# Layout invariants

Everything on the canvas is a bounding box: tensors, full offset stacks, brackets,
operators, arrow labels, annotations, symbols, shape labels, stage headings, the meaning
box, the signature. **Tangency counts as collision.**

## Gutters

Define one base gutter `g ≥ 1 em`. Unrelated boxes stay at least `g` apart; stage bands at
least `1.5g`. In practice: `right=5mm–9mm` between an operator and its operands, `7mm–9mm`
between the last caption of one row and the next stage heading.

Overlap is allowed only inside one declared composite:

- tiles inside their own face,
- shards tiling a parent,
- outline sheets in one `\ststack`,
- a bracket around its own tensor,
- a connector endpoint touching its source/target border.

Every other intersection or occlusion is forbidden.

## Lanes

Reserve separate vertical lanes and never put anything else in them:

```
stage heading
(connector annotations)
tensor / operator row
symbols          <- \stcaption arg 2
shapes           <- \stcaption arg 3
```

Faces of different heights would otherwise hang their captions at different depths. Fix it
with a shared baseline:

```tex
\node[inner sep=0pt, fit=(Q)(KT)(S)] (rowA) {};
\stlane{rowA}
\stcaption{Q}{$\mathbf Q^{(i)}$}{$h\times T\times d_h$}
...
\stnolane
```

Every `\stcaption` between `\stlane` and `\stnolane` hangs from the bottom of `rowA`, so
symbols and shapes form two flat lanes.

Stage headings share one left rail. Anchor each heading below the previous row but at the
previous *heading's* x, not at the previous row's content:

```tex
\coordinate (cy) at ($(I-shape.south)+(0,-9mm)$);
\node[st stage, anchor=north west] (SC) at (SB.west |- cy) {...};
```

Explanatory prose belongs in the stage subtitle, the bottom box, or above its own
connector. Never drop a floating commentary card between two operands unless it is a real
operation node (`st comm`).

## Layers

The package declares three: `stbg` (connectors), `main` (tensors, operators), `stfg`
(text). `\starrow` and `\starrowlabel` route on `stbg` automatically, so a connector can
never cover a face. Two consequences you still own:

- A connector may not cross a box that is not one of its endpoints. Move the row, don't
  route over.
- A label's white underlay may cover only its own connector — never a tensor, never
  another label. If the label is wider than the arrow, shorten the label or widen the gap.
  This is the single most common failure after a first draft.

## Stacks

`\ststack` includes its offset sheets in the bounding box, so neighbours can be spaced
against the real extent. Back sheets are outline-only and must carry no semantic content
of their own. If individual slices need to be read, use separate panels instead of overlap.

## When it does not fit

In this order:

1. shorten or remove secondary annotation,
2. widen the natural crop,
3. increase row spacing,
4. move the whole stage to another row.

Never solve crowding by shrinking below the type hierarchy, closing the gutter, or covering
another object.