# superderive.sty API

```tex
\documentclass[border=10pt]{standalone}
\usepackage[cjk]{superderive}     % cjk: ctex + fandol (XeLaTeX). en: English meaning-box and sdcol 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.

The build first runs `scripts/lint.py`. It rejects raw TikZ drawing, a formula placed
before the last row, more than one `\sdcol` contrast pair, and more than four active hue
families in the figure. Intentional galleries/tests may put
`% superderive-lint: allow-raw-tikz` near the top; do not add an exemption to a
deliverable merely to make it pass.

## Ledgers

```tex
\sdsetrole{keep}{sdTeal}        % role -> color. Macros take a ROLE, never a color.
\sdsetlabels{Idea}{Rewrite}{Caveat}  % override the three meaning-box rail labels
```

Colors: `sdTeal sdOrange sdCoral sdViolet sdGray sdInk`. An unknown role falls back to
gray **and emits a package warning**, which `build.sh` turns into a failed build.
Redeclaring a role with the same value is harmless; changing its value emits a warning
and keeps the original mapping.

## Flow layout

**This is the default.** `\sdrow` opens a band, every object inside is placed at the
cursor, `\sdrowend` closes it. Hand-written offsets are the main source of layout bugs.

```tex
\sdstage{D1}{stage heading}       % on the left rail, below the previous band
\sdrow[16mm]{R1}                  % open a band; height default is 16mm
  \sdbox[role=keep]{x}{$u$}      % existing term, kept as-is
  \sdsubst[role=live]{s1}{$u$}{$x^2$}     % from->to with a strike on the from
  \sdstep[role=rewrite]{s2}{QK^\top}{QK^\top/\sqrt{d_k}}  % lhs -> rhs
  \sdreason{s1}{§3.2.1}          % justification note, anchored to s1
\sdrowend                         % fit the band
```

| macro | does |
|---|---|
| `\sdstage{name}{text}` | stage heading on the left rail, below all ink so far |
| `\sdrow[height]{name}` | open a band; optional height defaults to 16mm |
| `\sdrowend` | `fit` the band, warn if empty, close it |
| `\sdstep[keys]{name}{lhs}{rhs}` | one rewrite step: two term boxes with an arrow |
| `\sdcancel[keys]{name}{math}` | one term, struck through |
| `\sdsubst[keys]{name}{from}{to}` | from-term struck through, to-term in role hue |
| `\sdbox[keys]{name}{math}` | plain term, no arrow, no strike |
| `\sdreason{step-name}{text}` | justification note anchored to a named step |
| `\sdcol{name}{illegal}{legal}` | one contrast pair per figure — second is a warning |
| `\sdbbox{all}` | everything drawn so far, as one node, for `\sdmeaningbox` |
| `\sdtopformula{F}{math}` | the claim line, centered on what was actually drawn |
| `\sdtrack{node}` | fold a hand-placed node into the bbox and the vertical cursor |
| `\sdvgap{4mm}` / `\sdgap{4mm}` | one-off extra space, vertical / horizontal |
| `\sdleftrail{x}` / `\sdlayoutreset` | move the rail / start over |

### Keys for step/cancel/subst/box

| key | default | meaning |
|---|---|---|
| `role=` | `rewrite` for step/subst, `cancel` for cancel, `keep` for box | hue, via `\sdsetrole` |
| `level=` | `2` | lightness level 0–3 for the fill |
| `gap=` | `\sdgutter` | space *before* this object; `gap=0pt` = exactly adjacent |

Authors can declare their own roles: `\sdsetrole{live}{sdTeal}`.

## Contrast column

`\sdcol{name}{illegal}{legal}` draws two boxes side by side: the left in `sdCoral!30`
struck, labelled **illegal** (or **非法** in `[cjk]` mode — never both); the right in
`sdTeal!30`, labelled **legal** (or **合法**). The budget is **one per figure**; a second
`\sdcol` triggers a package warning → build failure.

## Bottom

```tex
\sdbbox{all}
\sdtopformula{F}{$\mathrm{Attention}(Q,K,V)=\mathrm{softmax}(QK^\top/\sqrt{d_k})V$}
\sdmeaningbox{mb}{120mm}{all}{Idea text}{Rewrite text}{Caveat text}
\sdsignature{scaled-dot-product attention}{mb}   % optional
```

Arg 2 of `\sdmeaningbox` is the total box width; arg 3 is the node it hangs below.
Arg 4/5/6 are the three rail rows; an empty `{}` row is dropped.

`\sdsignature` renders only its subject; it has no author or handle mechanism. Its node
is named `(#2-sig)` from the anchor.

## Gotchas

- `\sdrow`, `\sdrowend`, `\sdstage` must appear outside any other flow object.
- A band that overflows its declared height triggers `Package superderive Warning` →
  build failure.
- `\sdcheckrole` never redefines an existing role. Use `\sdsetrole{name}{newColor}`
  to change the mapping for subsequent figures in the same document.
- `\sdcol` labels are **not** customizable via `\sdsetlabels` — they depend only on the
  package option `[en]`/`[cjk]`.