# supertensor.sty API

```tex
\documentclass[border=10pt]{standalone}
\usepackage[cjk]{supertensor}     % cjk: ctex + fandol (XeLaTeX). en: English rail labels.
```

Build with `./scripts/build.sh fig.tex` — it puts `assets/` on `TEXINPUTS`, so the package
does not need to be installed into your texmf tree.

## Ledgers

```tex
\stsetrole{q}{stTeal}      % role -> color. Macros take a ROLE, never a color.
\stdim{T}{6}               % symbolic axis -> physical edge length in cells
\stsetauthor{...}          % default 五道口纳什
\stsetlabels{A}{O}{M}      % override the three meaning-box rail labels
\stsetrail{3.2em}          % width of the bold label rail
```

Colors: `stTeal stOrange stCoral stViolet stGray stInk`. An unknown role falls back to gray
**and emits a package warning**, which `build.sh` turns into a failed build.

Lengths: `\stunit` (one cell, 4.6 mm) and `\sttilegap` (white gutter, 0.5 mm).

## Faces

```tex
\stface[keys]{name}{(coord)}{rows}{cols}
\ststack[keys]{name}{(coord)}{rows}{cols}{sheets}
\stindexface[keys]{name}{(coord)}{rows}{cols}{entries}
```

`rows`/`cols` accept a declared axis name or a raw integer. `(coord)` must include its own
parentheses — `{(0,0)}`, `{($(A.east)+(1.5,0)$)}`. `name` becomes a TikZ node you can
anchor against; `\ststack` also defines `name-front`.

Keys:

| key | default | meaning |
|---|---|---|
| `role=` | `neutral` | hue, via `\stsetrole` |
| `pattern=` | `dense` | `solid dense diag band lower upper causal empty data` |
| `data=` | — | with `pattern=data`: comma-separated rows, one digit per cell, `0`–`3` = level |
| `level=` | `2` | level for `pattern=solid` and the flat level of a mask |
| `bracket=` | `false` | thin neutral matrix brackets |
| `border=` | `true` | outer `black!60` border |
| `tiles=` | `true` | `false` = one flat filled rectangle |

`\stindexface` entries are row-major, `rows*cols` of them; `.` leaves a cell blank.
It deliberately has no lightness ramp — see `semantics.md`.

```tex
\stface[role=w, pattern=data, level=3,
        data={3300,0330,0033,3003,3030,0303}]{D}{(0,0)}{T}{E}
\stindexface[role=idx]{I}{(b)}{T}{k}{0,1, 1,2, 2,3, 3,0, 0,2, 1,3}
```

## Captions

```tex
\node[inner sep=0pt, fit=(A)(B)(C)] (rowA) {};
\stlane{rowA}
\stcaption{A}{$\mathbf A$}{$T\times d$}     % symbol lane, shape lane
\stnolane
\stcaptiontop{A}{\stshapefont{token}}       % occasional label above a face
```

`\stcaption` defines `name-sym` and `name-shape` nodes; anchor the next stage heading
against `name-shape.south`.

## Operators, connectors, nodes

```tex
\node[st op, right=6mm of A] (m) {$\times$};
\node[st comm, right=9mm of P] (ar) {All-Reduce};
\starrow{P.east}{ar.west}
\starrowlabel{M.east}{A.west}{softmax}
```

Styles: `st sym st shape st stage st op st note st arrow st comm st brace`.
Text helpers: `\stformula \ststagelabel \stoperator \stsymfont \stshapefont \stprose`.
Connectors route on the background layer automatically.

## Bottom

```tex
\node[inner sep=0pt, fit=(F)(rowA)(rowB)(Y-shape)] (all) {};
\stmeaningbox{mb}{16.6cm}{all}{axes text}{objects text}{mechanism text}
\stsignature{因果多头注意力（掩码 + 拼接投影）}{mb}
```

Arg 2 is the total box width; arg 3 is the node it hangs below — include every caption and
top label in that `fit` or the box will overlap them. An empty `{}` row is dropped.

## Gotchas

- `\ststack` never re-enters `\stface`; if you extend the package, do not pass
  `role=\st@role` back through pgfkeys — it defines the macro in terms of itself and hangs.
- A coordinate expression inside `fit=` needs braces: `fit={(a) ($(b)+(1,0)$)}`.
- `\foreach {\macro,...,1}` cannot infer its direction from an unexpanded macro.
- `\strole` is expandable on purpose (it is used inside `\edef`); the warning lives in
  `\stcheckrole`.