Harden \stgroup and tighten the callout budget (review follow-up)

- Bracket ink is part of the fit: \st@facebody drops -inkw/-inke extreme
  coordinates and \stface/\ststack register them with the enclosing
  group/col/row fit, so a group outline can no longer be crossed by a
  member's bracket arms
- \stlink inside \stgroup or \stcol is now a package error: sub-flow
  members never terminate a pending connector, so the arrow was dropped
  silently while the label still rendered
- \stgroup requires role= (explicit role=neutral for mixed groups) and
  must bind at least two members or one \stcol partition; a lone stack
  or face inside a group is a dirty-build warning
- lint: default budget is one \stcallout per figure; the
  allow-multiple-callouts directive relaxes it to one per band
- build.sh: clean-build hint no longer names hue budget (lint owns it)
- tests/group-callout.tex reworked: multi-member group with a bracketed
  member as a regression probe, single callout; new negative fixtures
  group-link, group-norole, group-single, callout-budget
- api.md, checklist.md, style.md, layout.md, SKILL.md updated to match
This commit is contained in:
dela
2026-08-05 17:03:14 +08:00
parent 866173a831
commit de917a2fbd
13 changed files with 181 additions and 54 deletions
+24 -13
View File
@@ -10,8 +10,8 @@ does not need to be installed into your texmf tree.
The build first runs `scripts/lint.py`. It rejects ledger changes, untracked absolute
objects, repeated anonymous dimensions, raw TikZ rectangles, a formula placed before the
last row, an unclosed `\stgroup`, a callout anchored to anything other than a band or a
second callout on one band, and more than four active hue families per row. Intentional galleries/tests may
last row, an unclosed `\stgroup`, a callout anchored to anything other than a band, more
than one callout in the figure, and more than four active hue families per row. Intentional galleries/tests may
put `% supertensor-lint: allow-absolute, allow-missing-formula` near the top; do not add an
exemption to a deliverable merely to make it pass.
@@ -105,10 +105,12 @@ but wrap hand-placed nodes in `\sttrack` so the cursor knows about them.
role hue around whatever is placed between them, naming those objects as one composite:
```tex
\stgroup[role=q]{qg} % keys: role= (hue), pad= (default \stgrouppad)
\ststack[role=q]{qh}{}{T}{dh}{3} % "these three sheets are q"
\stgroup[role=q]{qg} % keys: role= (REQUIRED, hue), pad= (default \stgrouppad)
\stface[role=q]{q1}{}{T}{dh} % "these three heads are q"
\stface[role=q, gap=2mm]{q2}{}{T}{dh}
\stface[role=q, gap=2mm]{q3}{}{T}{dh}
\stgroupend
\stcaption{qg}{$\mathbf q$}{$B\times T\times h\times d_h$}
\stcaption{qg}{$\mathbf q$}{$T\times h\times d_h$}
```
The members go **inside** the block, and three properties follow from that:
@@ -117,12 +119,18 @@ The members go **inside** the block, and three properties follow from that:
swallow whatever sat between its members;
- the group, not its last member, terminates a pending `\stlink` and sources the next
one, so an arrow lands **on** the outline instead of ending inside it and crossing a
border that is not its endpoint;
- the padding is reserved on both sides, so the neighbour cannot land tangent to it.
border that is not its endpoint. For the same reason `\stlink` **inside** a group is a
package error: a member never terminates a connector, so the arrow would be dropped
silently;
- the padding is reserved on both sides, so the neighbour cannot land tangent to it. The
fit includes decoration ink too: a `bracket=true` member's arms stay inside the outline.
`\strowend` fits the group, so `\stcaption{qg}{...}` hangs from the caption lane below the
outline, not below the member. A group may contain a `\stcol`; it may not sit inside one,
and it may not nest. An unclosed group is a lint error.
A group must bind **at least two members, or one `\stcol` partition** — around a single
face or stack the outline is decoration, and the package warns. `role=` is required; a
genuinely mixed group passes `role=neutral` explicitly. `\strowend` fits the group, so
`\stcaption{qg}{...}` hangs from the caption lane below the outline, not below the member.
A group may contain a `\stcol`; it may not sit inside one, and it may not nest. An
unclosed group is a lint error.
## Callouts
@@ -135,9 +143,12 @@ of a **finished** band, top-aligned with it. Call it after `\strowend`:
\stcallout{n1}{5.2cm}{rowB}{下界化换来了什么}{Kimi Linear 的 $g$ 无下界……}
```
Arg 3 must be a `\strow` band name — one aside per band, and never anchored to a single
face. Both rules are lint errors, because a card beside one operand reads as a step in the
computation (`layout.md`). Inside an open band it is a package error.
Arg 3 must be a `\strow` band name, never a single face — a card beside one operand reads
as a step in the computation (`layout.md`). The budget is **one callout per figure**: a
card on every band is a dashboard, and the cards are unreadable at thumbnail size anyway.
Both rules are lint errors; `% supertensor-lint: allow-multiple-callouts` relaxes the
budget to one per band for a figure that genuinely needs it. Inside an open band a callout
is a package error.
A callout pushes the vertical cursor below its own bottom edge. A card taller than its band
therefore opens visible white space rather than colliding with the next stage — which is