Number align/gather/alignat rows per-row (amsmath semantics)

[mmcky]

Closes #73. Closes #80.

What this does

Under book-mode (and default) numbering, a multi-row align previously took a single block enumerator, so a LaTeX source that numbers N equations rendered as one number and every later equation drifted off the source's numbering. Each \\ row of a non-starred align / gather / alignat now advances the equation counter and takes its own number, rendered as an explicit KaTeX \tag at the row — with the shared & alignment axis preserved (the whole environment is still one KaTeX layout).

amsmath semantics implemented exactly as scoped in #73:

Source	Behavior
plain \\ row	advances the counter, shows its number
\nonumber / \notag row	renders without a number; counter does not advance
\tag{...} / \tag*{...} row	displays the tag; counter does not advance
per-row \label{...}	becomes that row's reference target — {eq} and \eqref resolve to the row's number
align* and friends	unnumbered
equation / single-row environments	unchanged block-level numbering (identical in amsmath)

Verified end to end on a probe book: two aligns (one with \nonumber + two row labels), an align*, a labeled $$ equation, and an align containing a nested \begin{cases} produce row numbers 1.1 1.2 1.3 (skip) 1.4, unnumbered starred rows, 1.5 continuing the counter, and 1.6 1.7 with the cases intact; {eq} references resolve to (1.3) / (1.4) and anchor to the block.

How it works

1. KaTeX bump ^0.15.2 → ^0.16.21 (first commit; closes Bump KaTeX ^0.15.2 → ^0.16 (per-row equation numbering machinery; prerequisite for #73) #80). KaTeX 0.16.0 added the per-row machinery this builds on: per-row \tag in aligned environments (0.15 hard-errors Multiple \tag), \nonumber suppression, and depth-aware row layout. The 0.16 line keeps the 0.15-era CSS class vocabulary, so markup stays compatible with the katex@0.15.2 stylesheet themes load today (the 0.18 class-rename line remains a coordinated later move — see Bump KaTeX ^0.15.2 → ^0.16 (per-row equation numbering machinery; prerequisite for #73) #80 / quantecon-theme.mystmd#118). Full test suite passes on 0.16.47 with zero snapshot churn. @types/katex is dropped in favor of the types bundled with katex since 0.16.
2. Scanner (myst-transforms/src/mathRows.ts, new): depth-aware row split of the environment body — \\ inside nested cases/matrix environments or brace groups is not a row boundary; \\* and \\[2em] separators are handled; per-row \label is stripped (mirroring existing behavior) and recorded with \nonumber/\tag flags on node.rows (typed in myst-spec ext). This is deliberately not built on transformSubEquations, per the findings on Number align/gather rows per-row (amsmath semantics) — honor per-row \label, \tag, \nonumber #73 — that path re-wraps rows in separate align*s (losing the axis), is lettered-subequation semantics, and splits with a depth-blind .split('\\\\').
3. Enumeration (enumerate.ts): math nodes with rows advance the equation counter once per numbered row (book prefixes and previousCounts chaining apply automatically); row labels register as individual reference targets carrying the row's enumerator and the block's html_id; a block-level directive label resolves to the first numbered row. The block takes no enumerator, so the theme's block chrome doesn't draw a duplicate number.
4. Rendering (math.ts): row-numbered nodes always render as the starred environment with explicit \tags injected for enumerated rows — no dependence on KaTeX's automatic CSS-counter numbers (which are page-global and can't express 1.15, and which the current 0.15.2 theme stylesheet couldn't draw anyway). Since enumeration runs after the initial render, a new renderRowNumberedMathTransform re-renders affected nodes in postProcessMdast once enumerators exist.
5. LaTeX export (myst-to-tex): per-row labels are re-emitted into the environment (resolving an existing TODO there), so PDF export numbers and anchors each row natively and agrees with the HTML output.

Notes / limitations

• flalign and eqnarray are excluded: KaTeX has no support for either (they fail to render today; eqnarray keeps its existing rewrite-to-align* path).
• Row numbers are rendered inside the KaTeX HTML, so unlike the block chrome they are not hash-links; row \eqrefs anchor to the block (rows of the same environment are adjacent on screen).
• align* becoming unnumbered is a behavior change for documents that relied on a starred environment taking a block number — it now matches amsmath, per the issue's requested behavior. Labeled starred environments keep MyST semantics (labeled = numbered as a block).
• Downstream payoff (Multi-row align/gather rows collapse to one equation number — HTML numbering drifts from the PDF (needs per-row numbering upstream) claude-latex-to-myst#186): the converter can now pass align through verbatim instead of rewriting to aligned, and the printed-PDF equation numbers match the site.

Testing

• 17 new tests in mathRows.spec.ts: scanner (nesting, separators, labels/tags/nonumber, alignat args, malformed input) and end-to-end enumeration + target resolution + rendered HTML.
• Full monorepo suite green (72 turbo tasks; 405 tests in myst-transforms alone) — the KaTeX bump produced zero existing-test churn.
• Probe book verified for both --site (AST enumerators, xref text, KaTeX tag HTML) and --tex (per-row labels re-emitted, no blank lines inside environments, nested cases intact).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR implements amsmath-style per-row equation numbering for multi-row align / gather / alignat display-math blocks, ensuring equation counters, \nonumber/\notag, \tag, and per-row \label behave like LaTeX while preserving the shared alignment axis in KaTeX output.

Changes:

• Add a depth-aware row scanner (scanMathRows) and serializer (buildRowTex) to model per-row semantics for aligned environments.
• Update enumeration and reference-target registration to advance counters per numbered row and register per-row labels as targets (while avoiding block-level duplicate numbering).
• Re-render affected math after enumeration by injecting explicit KaTeX \tag{...} per enumerated row; re-emit per-row labels during LaTeX export; bump KaTeX to ^0.16.21.

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/myst-transforms/src/mathRows.ts	New row scanner/builder for per-row numbering environments.
packages/myst-transforms/src/mathRows.spec.ts	New unit + end-to-end tests for scanning/enumeration/rendering behavior.
packages/myst-transforms/src/math.ts	Extract row structure, render row-numbered math via injected \tags, add post-enumeration re-render transform.
packages/myst-transforms/src/index.ts	Export new math row helpers and post-enumeration render transform.
packages/myst-transforms/src/enumerate.ts	Enumerate aligned envs per-row and register per-row label targets while avoiding block enumerators.
packages/myst-transforms/package.json	Bump katex to ^0.16.21 and drop @types/katex.
packages/myst-to-tex/src/math.ts	Re-inject stripped per-row \labels for LaTeX/PDF parity.
packages/myst-to-jats/package.json	Bump katex to ^0.16.21 and drop @types/katex.
packages/myst-spec/src/index.ts	Export new MathRow / MathRows types.
packages/myst-spec/src/ext.ts	Define MathRow / MathRows and add rows?: MathRows to Math nodes.
packages/myst-spec-ext/src/index.ts	Re-export MathRow / MathRows (deprecated aliases) for compatibility.
packages/myst-cli/src/process/mdast.ts	Run row-numbered math re-render after enumeration in postProcessMdast.
bun.lock	Lockfile updates for KaTeX bump and removed @types/katex.
.changeset/per-row-align-numbering.md	Changeset documenting new per-row numbering behavior and KaTeX bump.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.