feat: add superfig paper-figure toolkit

Standalone LaTeX/TikZ skill for non-tensor paper figures: node/edge macros, lint-on-warning build, golden examples, and negative fixtures.
2026-08-17 09:40:12 +08:00
commit db5598fbf7
39 changed files with 1732 additions and 0 deletions
@@ -0,0 +1,86 @@
+# superfig
+
+A paper-figure toolkit for non-tensor diagrams: a LaTeX/TikZ macro package, a
+build pipeline that fails on silent corruption, worked examples, and an agent
+skill that ties them together.
+
+It is the generic-node sibling of `supertensor`. Same house style, same
+role/cursor/warning discipline. The primitives are nodes, edges and groups,
+not tensor faces. Use `supertensor` when axis lengths and shape identities
+are the claim.
+
+This repository is a **child** of SuperPaper, the family parent that
+routes paper notes to the right figure toolkit. Clone SuperPaper with
+`--recurse-submodules` for the whole family; use this directory alone
+when you only need node/edge figures.
+
+```
+SKILL.md              the skill entry point (lean; loads references on demand)
+references/           grammar, layout, style, api, checklist, antipatterns
+assets/superfig.sty   the macro package
+scripts/preflight.sh  is the TikZ + CJK path available?
+scripts/lint.py       reject source-level invariant escapes
+scripts/build.sh      lint, compile, audit the log, export pdf/svg/png/thumb
+scripts/test.sh       positive examples plus negative package/lint fixtures
+examples/             four golden examples + an anti-pattern gallery
+```
+
+## Quick start
+
+```bash
+./scripts/preflight.sh                          # 0 = full path, 1 = degraded, 2 = no LaTeX
+./scripts/build.sh examples/pipeline.tex        # -> examples/build/pipeline.{pdf,svg,png}
+./scripts/test.sh
+```
+
+A minimal figure:
+
+```tex
+\documentclass[border=10pt]{standalone}
+\usepackage[cjk]{superfig}
+
+\sfsetrole{input}{sfTeal}
+\sfsetrole{model}{sfOrange}
+
+\begin{document}\begin{tikzpicture}
+  \sfstage{S}{one band, placed by cursor}
+  \sfrow{R1}{14mm}
+    \sfnode[role=input]{x}{输入 $x$}{16mm}{12mm}
+    \sfconn{e1}{预处理}
+    \sfnode[role=model]{f}{模型 $f_\theta$}{18mm}{12mm}
+  \sfrowend
+  \sflane{R1}
+  \sfcaption{x}{$x$}{原始输入}
+  \sfcaption{f}{$f_\theta$}{可学习参数}
+\end{tikzpicture}\end{document}
+```
+
+See `references/api.md` for the full macro list.
+
+## Examples
+
+| file | shows |
+|---|---|
+| `pipeline.tex` | cursor flow; loss as a side object, not a station on the forward path |
+| `branch-architecture.tex` | residual skip; a group captioned on the shared lane |
+| `state-flow.tex` | time/state step; one `\sfcallout` on a finished band |
+| `dependency-graph.tex` | dual-encoder join, fusion placed from existing anchors |
+| `antipatterns.tex` | four figures that compile cleanly and still teach something false |
+
+## Using it as an agent skill
+
+`SKILL.md` is the entry point; the `references/` files are loaded on demand.
+Point your agent runtime at this directory. The skill assumes `scripts/` and
+`assets/` sit beside it.
+
+## Why the build script fails on warnings
+
+`Missing character` drops a CJK glyph silently. `Overfull \hbox` lets a label
+escape its lane. `Package superfig Warning` is an undeclared role, a
+single-member group, a band overflow, a second callout, or a callout hanging
+off a node. `build.sh` greps for all of them and exits non-zero.
+
+A clean build also proves the source avoided raw TikZ drawing, a formula
+placed before the last row, and more than four active hues. It still cannot
+prove that the relationships are right; that is what `references/checklist.md`
+is for.