# Inline math rendering — framing **Revision 2 — framing only; no implementation. Ground truth re-scouted against canonical `main` @ `ddaa80d`, protocol v20, 2026-07-24; every anchor re-checked at `f07b75b` (the vterm PTY-flake fix #153, test-only, which moved no anchor here).** Revision 1 was written against protocol v18, before LaTeX Stage 1 (#144), web grammars (#146), folding Stages 1–2 (#142/#149) and the GPU initial target (#148) landed. **Revision 2 changes no design decision.** It corrects the ground truth those merges invalidated, and records the staging decision the sibling substrate framing already took. A reader who knows revision 1 can read §0 alone. ## 0. What the landed-state re-scout corrected | # | Revision 1 said | Current state | | --- | --- | --- | | C1 | A MATH-table crate must be added; "neither is in the tree today" | **Both are already in `Cargo.lock`.** `ttf-parser` 0.25.1 reaches `pmacs-gpu` non-optionally via `fontdb` → `cosmic-text` → `glyphon`, and `pmacs-gpu` already calls `fontdb` directly in `build_font_system` (`pmacs-gpu/src/main.rs:217`). `read-fonts` 0.37.0, `skrifa`, `swash` and `font-types` are present too. The MATH module is feature-gated, so the declaration must name its features deliberately — see Tier 3 §A. | | C2 | Use "one of `ttf-parser` or `read-fonts`" | **Not interchangeable.** `ttf-parser` ships the MATH table (`tables/math.rs`: `Constants::axis_height`, `display_operator_min_height`, `script_percent_scale_down`, the `MathValue`/`MathValues` accessors Tier 3 names). `read-fonts` 0.37.0 exposes no MATH table. Only `ttf-parser` satisfies Tier 3. | | C3 | "Protocol is v18 … `SUPPORTED=[6..=18]`" (Q#IM1) | Protocol is **v20**, `SUPPORTED=[6..=20]`. v19 = the vterm terminal family; v20 = the GPU initial-target bootstrap. The Q#IM1 *decision* (query font size locally, no protocol change) is unaffected. | | C4 | `rebuild_code_slice()` at `pmacs-gpu/src/main.rs:4849` | Now `:6136`. The file grew through vterm Stage 3, tab-width parity and the initial-target work. | | C5 | Tier 1 must patch an upstream grammar or ship an overlay; "defers enumerating which grammars need this" | **Already available for `.tex`.** LaTeX Stage 1 (#144) bundles `codebook-tree-sitter-latex`, whose grammar exposes `math_delimiter` and `math_environment`, and the in-repo overlay `builtin/queries/latex/highlights.scm` already captures both. The overlay mechanism this tier proposed is proven, not speculative. Markdown still has no math capture. | | C6 | (silent on staging) | A sibling framing, `docs/latex-grammar-math-substrate-framing.md` (rev 3), names this note its parent and **decides Tier 2's staging in Q#LX5**: the parser lands *beside* its Tier 3 consumer, never ahead of it. Recorded in §Tier 2 below so it is not re-litigated. | | C7 | (silent on contention) | Tier 4's render path is contended. Folding Stage 2 (#149) landed fold projection in the paint path, and its **Stage 3 (GPU) is unframed**. The **bottom-panel arc** is implementing Stage 1 now; its Stage 2 claims both `pmacs-gpu/src/main.rs`'s render path and the next protocol version. Tier 4 must re-scout against whichever lands first. | Unchanged and re-verified: `InlineAdornment` (`pmacs-protocol/src/message.rs:1391`), `SquiggleRenderer` (`pmacs-gpu/src/main.rs:2825`), `TextView` (`src/text_view.rs:45`), and the three referenced framings (`multi-language-injections`, `pmacs-gpu-wavy-squiggles`, `semantic-frontend-protocol`) all exist as described. **Status: framing only; no implementation.** This note frames a feature that currently does not exist: rendering LaTeX math expressions as typed math (not raw source) in any buffer. It proposes a four-tier pipeline and identifies the substrate changes needed in the Rust core, the semantic protocol, and the GPU frontend. The TUI frontend is explicitly scoped out (terminal cells cannot express positioned math glyphs at interactive rates). If this is adopted, the TUI path would be "display the raw `$...$` source with a distinct face as a lossy fallback" and nothing more. The note assumes no dependency on KaTeX / MathJax / JavaScript runtimes. Everything from parsing through layout to rendering is native Rust. ## Design contract (inherits the existing semantic protocol boundary) From `docs/semantic-frontend-protocol.md`: **the instance never learns a pixel.** Inline math does not reopen this. The instance detects math ranges, parses LaTeX, and produces a position-independent math layout tree; the frontend positions glyphs at pixel coordinates using its own font metrics and viewport. The instance-to-frontend contract for math is a list of positioned-glyph or font-size-scalable records, not a pre-rasterized bitmap. ### Contract additions specific to math 1. **Math is text, not an image.** A math expression is selectable, copy-pastes as its LaTeX source, and re-renders on edit with no round-trip. Invariant: the raw `$...$` text in the rope is always the canonical source; the rendered glyphs are a projection. 2. **Cache invalidation is the frontend's job.** The instance does not track which expressions are visible or dirty. The GPU frontend maintains a math layout cache keyed by source-text hash; only the expression under the cursor invalidates on each keystroke. 3. **Display math is a block, not an inline layer.** `$$...$$` regions introduce vertical space and center the formula. They collapse to a single "block" cell in the base text layout and are rendered as a full-width overlay in a separate pass. ## Four-tier architecture ``` buffer text | [1. Detection] — regex / tree-sitter → byte ranges tagged Math | [2. Parsing] — recursive-descent → MathNode tree | [3. Layout] — MATH-font metrics → positioned glyph runs | [4. Rendering] — wgpu / glyphon pass at computed coordinates ``` ### Tier 1: Detection Every buffer, after every edit, scan for math delimiters. The default set: | Delimiter | Kind | Notes | |-----------|------|-------| | `$...$` | inline | Single-dollar, non-greedy | | `$$...$$` | display | Double-dollar, greedy across newlines | | `\(...\)` | inline | Alt inline (LaTeX convention) | | `\[...\]` | display | Alt display | The detection layer emits byte ranges with a tag: ```rust enum MathKind { Inline, Display } struct MathSpan { start: BytePos, end: BytePos, kind: MathKind } ``` **Where it runs:** - For buffers with a tree-sitter grammar: a math node in the grammar signals scanned injection ranges (reuses the existing `ParseTreeBundle` + `Layer` machinery from `docs/multi-language-injections-framing.md`). Each grammar that can contain LaTeX needs a math capture rule — either by patching the upstream grammar or shipping an in-repo query overlay. **This is no longer speculative for `.tex` (C5).** LaTeX Stage 1 (#144) bundles `codebook-tree-sitter-latex`, whose grammar already exposes `math_delimiter` and `math_environment`, and the in-repo overlay `builtin/queries/latex/highlights.scm` already captures both (`:57`, `:290`). The overlay pattern this tier proposed therefore exists and is proven; adding a `@math` capture beside the existing highlight captures is an edit to a file the repo already owns, not new machinery. The node names are the grammar's own — `math_environment` / `math_delimiter`, **not** the `(math_expression)` this framing originally guessed. Markdown remains unaddressed: its grammar comes from the crate query constants (the #146 web-grammars pattern, no in-repo overlay), so a markdown math capture needs the overlay treatment first. Enumerating further grammars stays deferred to adoption. - For buffers with no grammar: a fast byte-level scanner in Rust (two-pass: find `$` / `$$` / `\(` / `\[` boundaries, match pairs, handle escapes). Runs in the GPU frontend's `rebuild_code_slice()` (`pmacs-gpu/src/main.rs:6136`) as a post-shape hook, not the edit path, so keystroke latency is unaffected. (The TUI's `src/text_view.rs` is a separate line-index view that does not participate.) **Cost note:** the scan runs on every buffer after every edit, regardless of whether the buffer is likely to contain LaTeX. A log file with a bare `$` will be scanned, find no pair, and exit. This is a negligible cost per edit — the scan is O(length of changed region), not O(file) — but the framing notes it as a minor inefficiency. An extension-based gate (only scan buffers whose language is in a configured set) is a trivial v1 optimization. **Extensibility:** A Lua hook `pmacs.math.delimiters` registers additional patterns per mode. Example: ```lua pmacs.math.add_delimiter("markdown", "`$", "`$") -- `` $...$ `` in md ``` ### Tier 2: Parsing A recursive-descent parser converts the LaTeX math source into an AST. LaTeX math mode is a constrained grammar — far smaller than full LaTeX. The node set covers what appears in real mathematical writing: ```rust enum MathNode { /// Characters and identifiers Char(char), Identifier(SmolStr), // \sin, \alpha, x /// Subscript / superscript Sub(Box), // _{...} Super(Box), // ^{...} SubSuper(Box, Box), // _{...}^{...} /// Fractions Fraction(Box, Box), /// Radicals Sqrt(Box), SqrtN(Box, Box), // \sqrt[n]{...} /// Big operators (sum, prod, int — limits above/below) BigOp { op: MathOp, lower: Option>, upper: Option>, sub: Option>, // \sum_{i=1} vs \sum_{i=1}^\infty sup: Option>, }, /// Fences that may stretch Fenced { left: Delimiter, body: Box, right: Delimiter, }, /// Accents Accent { accent: AccentKind, base: Box }, /// Style overrides (e.g. \displaystyle) Styled(Box, MathStyle), /// \text{...} — literal text in math mode Text(String), /// Generic stretchy: \overline, \underbrace, etc. Stretch(StretchKind, Box), /// Sequences and groups Group(Vec), } ``` **~500 lines of Rust.** No lookup tables beyond symbol names → Unicode codepoints (the `\alpha` → `U+03B1` map is ~200 entries for Greek + Hebrew + arrows + operators). The parser does not handle macro definitions, preamble material, or LaTeX3 — only math-mode markup. **Staging: this tier lands beside Tier 3, never ahead of it (C6).** `docs/latex-grammar-math-substrate-framing.md` (rev 3) carved out the frontend-agnostic LaTeX substrate as its own lane and, in **Q#LX5**, deliberately excluded this parser from it. Reviewer and author concurred and recorded the decision "so it is not re-litigated". The rationale is that `MathNode`'s shape is only validated by a layout consumer, so building the parser first would fix an AST no one has exercised — the same no-build-ahead discipline folding applied to `BlockAdornments` and gpu-invocation applied to `FILE`. The practical consequence: **Tier 2 is not an independently shippable slice.** It is pure, dependency-free and conflict-free, which makes it tempting to land alone while other lanes hold the render path; that temptation is exactly what Q#LX5 refused. A PR that ships the parser must also ship enough of Tier 3 to exercise the AST. ### Tier 3: Layout This is the hard part and the place where pmacs would do something no interactive editor currently does natively: position math glyphs using an OpenType MATH table. The pipeline: **A. Font metrics.** Load a math font with an OpenType MATH table. The candidates, ranked: | Font | Table quality | License | Notes | |------|--------------|---------|-------| | **Latin Modern Math** | Full | **GUST Font License** (not OFL) | Reference, ships with TeX Live, most widely tested; ~717 KiB. Bundled by #158 as `pmacs-gpu/fonts/latinmodern-math.otf` | | **STIX Two Math** | Full | OFL | Broader Unicode coverage | | **Cambria Math** | Full | Proprietary | Ships with Office; unavailable on Linux | | **Libertinus Math** | Full | OFL | Derivative of Latin Modern, wider | Bundled default: Latin Modern Math. The existing font-loading path (`build_font_system()` → `fontdb::Database::load_font_source()` in `pmacs-gpu/src/main.rs:217`, via cosmic-text) already handles .ttf/.otf. **Reading the MATH table needs `ttf-parser`, and it is already in the build graph (C1, C2).** Revision 1 said a MATH crate must be added and that "neither is in the tree today"; both parts were wrong: - `ttf-parser` 0.25.1 already reaches `pmacs-gpu` through `fontdb` → `cosmic-text` → `glyphon` — the same `fontdb` the frontend already calls directly. It is not an optional or dev-only path. Adding it to `pmacs-gpu/Cargo.toml` declares a dependency the build already compiles, so it adds no new supply-chain surface. **Declare the feature set deliberately, or the "no rebuild" part stops being true.** The MATH module is gated: `ttf-parser` re-exports `math` under `#[cfg(feature = "opentype-layout")]`. It is compiled today only because `fontdb` asks for it — and `fontdb` asks with `default-features = false`, features `["opentype-layout", "apple-layout", "variable-fonts", "glyph-names", "no-std-float"]`, which is **not** `ttf-parser`'s own default set (that one adds `std` and drops `no-std-float`). A plain `ttf-parser = "0.25"` therefore unions `std` in and forces a one-time rebuild of `ttf-parser`, `fontdb`, `cosmic-text` and `glyphon`. The zero-rebuild spelling is `default-features = false, features = ["opentype-layout"]` — a subset of what `fontdb` already enables. - The choice is **not** "one of `ttf-parser` or `read-fonts`". Only `ttf-parser` exposes the MATH table (`tables/math.rs`), and it supplies exactly the constants this tier names below — `Constants::axis_height`, `display_operator_min_height`, `script_percent_scale_down`, and the `MathValue` / `MathValues` per-glyph accessors. `read-fonts` 0.37.0, though present in the tree, has no MATH table; selecting it would be a dead end. `skrifa`, `swash` and `font-types` are also present (via cosmic-text) but are not MATH-table providers either. The bundled font itself is still a real addition: ~200 KB for Latin Modern Math in `pmacs-gpu`. **B. Box model.** Each `MathNode` lays out into a `MathBox`: ```rust struct MathBox { width: f32, height: f32, ascent: f32, // above baseline descent: f32, // below baseline italic_correction: f32, glyphs: Vec, } struct PosGlyph { glyph_id: GlyphId, x: f32, y: f32, // relative to box baseline font_size: f32, color: Color, // usually inherited from theme } ``` Layout rules per node type (following Knuth's math layout algorithm, simplified to the common cases): - **Group**: lay out children left-to-right, accumulate width. Insert italic corrections between adjacent slanted glyphs (from the MATH table's `MathItalicsCorrection`). - **Fraction**: lay out numerator and denominator at 70% font size, centered horizontally; draw a rule between them at the math axis height (from MATH table `MathConstants::AxisHeight`); the box ascent = num.ascent + axis + rule_thickness/2, descent = den.descent + space + rule_thickness/2. - **Subscript / Superscript**: scale to ~70%, shift superscript up by `SuperscriptShiftUp` (from MATH table), shift subscript down by `SubscriptShiftDown`. If both present, adjust so they don't overlap. - **BigOp**: select the display-size glyph variant from the MATH table (`GlyphVariantRecord` chain). Place lower limit below, upper above, using `DisplayOperatorMinHeight` for minimum size. - **Fences** (`\left(...\right)`): measure the enclosed box height; select the smallest fully-enclosing glyph variant from the stretchy chain; if the height exceeds the largest single glyph, assemble from the `GlyphConstruction` parts (top, bottom, repeatable extender). - **Sqrt**: lay out the radicand; draw the radical sign extending from the top-left to cover the radicand height, using the `RadicalKern`, `RadicalExtraAscender`, and `RadicalRuleThickness` constants from the MATH table. **C. Caching.** The key performance insight: a laid-out `MathBox` is hashable (by the source LaTeX string). The cache is a `HashMap>` keyed by SipHash of the source bytes. The GPU frontend holds this cache across reshape calls. On edit, only the expression whose source range overlaps the edit range is evicted. Latency target: < 500 µs for the common case (a 20-node expression). Worst case (a full-page display equation with nested fractions and summations): < 5 ms. Cache hit: < 1 µs. **Bulk-doc note:** for a LaTeX document with hundreds of inline expressions on screen simultaneously (e.g., a dense math paper at high zoom-out), each visible expression is parsed and laid out independently. The 5 ms worst case *per expression* could add up: 50 visible expressions at 1 ms each = 50 ms. The hash cache absorbs re-parses across frames (an expression re-appears on re-scroll at hash cost only), so the expensive path is only the first render of each expression after an edit or a fresh scroll. For v0 this is acceptable; if it proves hot, v1 can add a frame budget — parse until deadline, render cached results for the rest. ### Tier 4: Rendering (GPU frontend) The GPU frontend (`pmacs-gpu/src/main.rs`) already renders text through cosmic-text + glyphon with per-span styling. Math expressions are a new layer inserted into the existing z-order. **This tier is contended and must re-scout before it is scheduled (C7).** Revision 1 described this render path as though math were its only claimant. Two other arcs now converge on it: - **Folding Stage 3 (GPU)** — Stages 1–2 landed (#142/#149); Stage 3 is the next ranked item and is **unframed**. It inherits a named obligation on this path: the `BufferSnapshot` fold-mirror clear. - **The bottom-panel arc** — Stage 1 (core + TUI) is implementing now; its **Stage 2 owns both** this render path (a projected panel cell grid painted as a band) **and the next protocol version**. Neither blocks the design below, and this framing reserves no protocol version (see §Protocol surface). But Tier 4's anchors are the ones most likely to move, so whichever of the three lands second re-scouts against the first — the same rule the bottom-panel and folding framings already apply to each other. ``` Backgrounds → Squiggles → Code Text → Math → Gutter → Caret → Minimap → Minibuffer → Completion → Context menu ``` **Inline math (`$...$`):** 1. `rebuild_code_slice()` detects `MathSpan`s in the visible range. 2. For each inline span, extract the source text, hash-lookup the math cache, parse+layout on miss. 3. Delete the raw `$...$` glyphs from the cosmic-text buffer. Insert a zero-width placeholder with explicit width = `MathBox.width`. 4. Collect all `PosGlyph` runs into a `Vec` list, offset by the line's baseline position. 5. In `render()`, after the code text draw call, iterate `MathDraw`s and issue glyphon `TextArea` calls for each glyph run at its computed absolute position. **Display math (`$$...$$`):** 1. The math source occupies full lines. Detect via the text layout that the `MathSpan` spans entire visual lines. 2. Replace the affected visual lines with a single spacer glyph. 3. Insert vertical space before and after (from `\abovedisplayskip` and `\belowdisplayskip` equivalents — hardcoded constants are fine for v0). 4. Render the math block centered horizontally at the spacer position. **Stretchy delimiters** (the hardest rendering case): the MATH table's `GlyphConstruction` entries describe how to assemble a vertically stretched glyph from top/middle/bottom/extender pieces. The render pass for a stretchy glyph draws 3–5 separate glyph IDs at computed positions, bottom-to-top. This is analogous to the existing squiggle shader (a custom WGSL path for diagnostic underlines); a stretchy-glyph shader or vertex-buffer assembly follows the same pattern. ## Protocol surface No new wire types for v0. The GPU frontend detects math locally from the text content it already receives via `BufferSnapshot`. The semantic protocol stays unchanged; math rendering is a pure frontend responsibility in v0. Note: this means frontend-local detection duplicates regex scanning for every reshape. In the common case (a handful of visible math spans) the cost is negligible; for a full-screen display of a LaTeX document with hundreds of inline expressions the scan cost accumulates linearly with visible byte count. The hash cache absorbs re-parse of unchanged expressions, but the delimiter scan itself is unavoidable. If this proves hot, v1 moves detection to the instance side. If this proves out, v1 would add an optional `MathSpans` variant to `InstanceMessage` so the instance's tree-sitter detection (tier 1) is authoritative and the frontend does not reimplement detection. This is deferred until there is a frontend consumer to validate the wire shape. As a secondary benefit, a single instance-side scan serves all connected frontends — the v0 approach pays the scan cost per frontend. ## Integration points | Component | Change | Risk | |-----------|--------|------| | `src/math_parse.rs` (new) | ~500-line recursive-descent parser | Low; pure fn, no deps. **Ships with Tier 3, not alone (Q#LX5).** | | `src/math_layout.rs` (new) | MATH-table loading + box layout | Medium; depends on `ttf-parser` | | `pmacs-gpu/Cargo.toml` | Declare `ttf-parser` as `default-features = false, features = ["opentype-layout"]` (already transitive via `fontdb`); bundle Latin Modern Math | Low; no new crate enters the graph, ~200 KB font. Spelling the features matters — bare `ttf-parser = "0.25"` unions `std` in and rebuilds the font chain | | `pmacs-gpu/src/main.rs` | Detect math spans in visible text, insert MathBox draw calls | **High, and contended** — see C7: folding Stage 3 (GPU) is unframed and the bottom-panel arc's Stage 2 claims this same render path | | `builtin/queries/latex/highlights.scm` | Add a `@math` capture beside the existing `math_environment` / `math_delimiter` captures | Low; the overlay already exists | | `semantic_render.rs` | No changes (v0) | None by design | The row that changed most is `pmacs-gpu/src/main.rs`. Revision 1 rated it "Medium; touches main render path" when that path was uncontested. It now has two other arcs converging on it, so Tier 4 cannot be scheduled without knowing which of them lands first. ## Open questions ### Q#IM1 — Font size and DPI scaling Math glyph positioning includes the font size as an explicit parameter. Inline math should match the base text font size; display math may use a slightly larger size. How does the math layout engine receive the current font size? Via the existing `FontFacts` protocol message (`protocol v17`), or queried from the `State` fields directly? **Proposed:** query `self.font_size` directly in the GPU frontend, same as code text does. No protocol change. (Protocol is **v20** at revision 2 — `SUPPORTED=[6..=20]`; v19 added the vterm terminal family and v20 the GPU initial-target bootstrap. The decision is version-independent: it holds precisely because it adds no wire surface. C3.) ### Q#IM2 — Color inheritance Math glyphs should render in the foreground face color of the surrounding text, including themed faces. At minimum: math inside a string literal should inherit the string face color; math in comments should inherit the comment color. This implies the detection layer must cross-reference style spans at the boundary byte ranges. **Proposed (v0):** render all math in the default foreground face. Color-by-context is deferred to v1. Caveat: in markdown buffers, math inside a fenced code block should render differently from math in prose. Since v0 defaults to foreground color everywhere, math inside a ` ```rust ` block will be indistinguishable from inline prose math. This is acceptable for v0 but should be the first upgrade in v1. ### Q#IM3 — Copy-paste fidelity If a user copies a visual region containing a rendered `\int_a^b`, what goes on the clipboard? **Proposed:** the raw LaTeX source from the rope. This matches the "math is text" invariant. A future refinement could copy the Unicode math representation (e.g., `∫ₐᵇ`) when that is available, but that is a specialization for the clipboard protocol, not the rendering path. ### Q#IM4 — Error fallback What does an unparseable expression (unbalanced braces, unknown command) look like? **Proposed:** render the raw LaTeX source with a red wavy underline (reuses the existing diagnostic squiggle shader from `docs/pmacs-gpu-wavy-squiggles-framing.md`). The expression is still editable and copy-pasteable; the squiggle signals the parse failure without losing the text. ### Q#IM5 — Delimiter pairing visibility `$` and `$$` are invisible delimiters in the rendered view. How does the user know where the math region begins and ends when the cursor is inside it? **Proposed:** when the cursor is inside a math span, draw a subtle background highlight over the entire range (reuses the `Decorations` mechanism — `MathFocus` decoration produced by the GPU frontend locally). The `$` characters themselves are never hidden from the underlying text buffer; they are merely suppressed in the glyph pipeline. When the cursor approaches the boundary, the raw `$` reappears. ### Q#IM6 — Cursor navigation inside a math expression The cursor moves through the raw LaTeX source at the byte level, not through the rendered glyphs. The user edits `\frac{a}{b}` and sees it render; the cursor steps through `\`, `f`, `r`, `a`, `c`, `{`, `a`, `}`, `{`, `b`, `}`. The visual cursor position is a best-effort projection: position the cursor at the x-offset of the *rendered* glyph that corresponds to the nearest byte offset in the source. **Proposed:** no structural cursor changes for v0. Cursor rendering uses the existing `CursorByte` mechanism, which operates on the raw text. The visual cursor may appear at a fractional screen position inside a rendered expression; this is equivalent to how it appears in an LSP inlay hint (already deployed — inline adornments hide their source text and the cursor skips over them). V1 could smooth this. ## Categorical bets - **No JavaScript runtime.** KaTeX is the best existing math renderer, but embedding a JS runtime (deno_core, quickjs, or a full V8) to run it would be the most expensive dependency pmacs has ever taken. Native Rust parsing + layout is ~2,000 lines vs ~30 MB of JS + WASM + runtime. The math layout algorithm is Knuth's 1978 design, well-documented and bounded in scope. Write it. - **No SVG or pre-rasterization.** Every expression renders fresh from the MATH table on every frame. This avoids a cache-invalidation explosion (what happens to a cached SVG when the user changes the font size? the theme? the DPI?) and keeps the rendering path uniform with code text (same glyphon pipeline, same GPU atlas). - **The TUI is out for v0.** Terminal cells cannot position glyphs at sub-cell resolution, cannot scale glyphs per-expression (except at great pain via Sixel / Kitty protocol), and cannot vary font size within a line. The TUI will render `$...$` as-is with a distinct face (e.g., italic + a highlight color). This is honest: the feature is GPU-only, like the squiggle shader. Note: the TUI still needs tier-1 detection (to know which `$...$` spans are math, so it can apply the distinct face). This makes detection a shared service — either the GPU frontend computes spans and the TUI queries them (impossible without a protocol message), or both frontends run their own detection. The v0 approach of frontend-local detection means the TUI must duplicate the delimiter scan. For v0 this is acceptable (the scan is cheap), but v1 should centralize detection in the instance and emit `MathSpans` on the wire. - **v0 is read-and-edit, not write-assist.** No `\begin{align}` completion, no auto-closing `}`, no preview of incomplete expressions. Those are UI conveniences layered on top once the pipeline exists. ## Non-goals (explicitly excluded from this framing) - Full LaTeX document rendering (titles, sections, bibliographies, cross-references). That is a separate mode (`latex-mode.lua`), not a frontend rendering concern. - MathML input. Detection parses `$...$` / `\(...\)` syntax only. MathML→rendered would be a separate pipeline. - Real-time preview of incomplete expressions. A partially typed `\frac{` will fail to parse and render as red-squiggled source; it does not show a partial fraction line. - Equation numbering and `\ref` / `\label`. That is LaTeX-mode substrate, not math rendering. ## Acceptance All acceptance is GPU-side (the TUI renders raw `$...$` and is not separately tested for math). Tests run against `pmacs-gpu` with a Vulkan device (`PMACS_REQUIRE_GPU=1`). Scratch buffers should clear `pmacs.lsp.config` to avoid spurious server starts unless the test exercises the LSP path. 1. **Inline math renders**: a buffer containing `The sum $\sum_{i=1}^n i$` opens; the `$...$` range is suppressed in the glyph stream; a glyph run for `∑`, baseline-shifted `i=1` and `n`, and the summation sign appears at the correct position between "The sum " and the following text. Visual assertion via GPU snapshot or caret/x-extent comparison. 2. **Display math centers**: a buffer containing `$$\int_a^b f(x)\,dx$$` opens; the math block occupies its own visual lines, centered horizontally, with vertical spacing above and below. 3. **Cache hit on re-scroll**: scroll an expression off-screen and back; the second render takes < 1 µs (cache fetch). Measured via the GPU frontend's per-frame timing (already emitted to stderr). 4. **Cache eviction on edit**: edit inside a `$...$` range; the expression re-parses (cache miss). Edit outside any math range; all cache entries survive. 5. **Error fallback renders as red-squiggled source**: a buffer containing `$\frac{a$` (unbalanced brace) opens; the raw source text `\frac{a$` is visible with a red wavy underline (reuses the `SquiggleRenderer` pipeline). 6. **No false positive on bare `$`**: a buffer containing `Price: $5.00` (single `$` with no pair) opens; no math spans are detected. The text renders as ordinary code text. 7. **Display math stores raw source for copy**: select a visual region containing a rendered `$$\sum_{i=1}^\infty a_i$$`; the clipboard receives the raw LaTeX source `$$\sum_{i=1}^\infty a_i$$`, not rendered glyphs. 8. **Cursor moves through raw source**: cursor-right through `$\alpha$` steps `$`, `\`, `a`, `l`, `p`, `h`, `a`, `$` (eight cursor positions) even though the visual rendering shows a single `α` glyph. 9. **Stretchy fences assemble from glyph parts**: a buffer containing `$\left(\frac{a}{b}\right)$` renders the parentheses at least as tall as the fraction. Visual assertion (the parens enclose the fraction without clipping). 10. **Math survives buffer switch**: open A (with math) and B (plain text), switch back; A's math cache is intact and no re-parse occurs. ## Adjacent prior art in pmacs - **Multi-language injections** (`docs/multi-language-injections-framing.md`): The `ParseTreeBundle` + `Layer` machinery already supports child parse trees at injected ranges. Math detection as a tree-sitter injection is a direct extension of this design, not a new mechanism. - **InlineAdornments** (M11.3, `docs/semantic-frontend-protocol.md`): LSP inlay hints demonstrate that the frontend can interleave virtual text at a byte offset without occupying document bytes. Math expressions need something strictly stronger — suppressing the raw `$...$` glyphs and replacing them with positioned math glyphs at potentially different widths. This suppression+replacement mechanism does not exist today (InlineAdornments are additive only — `ChunkSource::Source` and `ChunkSource::Adornment` are interleaved, not exclusive). The math pipeline would build it, roughly following the same anchor/offset pattern but with a `ByteRange` to suppress and a `MathBox` to render in its place. - **GPU squiggle shader** (`docs/pmacs-gpu-wavy-squiggles-framing.md`): Custom WGSL shader for diagnostic underlines demonstrates that pmacs-gpu already extends its rendering pipeline beyond basic glyph drawing. A stretchy-delimiter assembly pass or math-background pass follows the same architectural pattern (vertex buffer → dedicated shader → draw call in z-order). - **Theme-faces** (Themes Arc 4, `docs/theme-faces-framing.md`): The face resolution chain (`face-attribute → color → fallback`) would extend naturally to a `math-face` or `math-display-face` for themed math colors. ## Sibling lane (added in revision 2) `docs/latex-grammar-math-substrate-framing.md` (rev 3) names this note its parent and carves out the frontend-agnostic LaTeX substrate that can land without touching a contended file. Revision 1 did not reference it, which left the reader of this note unaware that part of its Tier 1 had already shipped (#144) and that its Tier 2 staging had already been decided. Read that lane before scheduling any tier here: - its **Q#LX5** governs Tier 2 (parser lands beside Tier 3, not ahead); - its landed portion supplies the `.tex` grammar and the query-overlay precedent Tier 1 depends on; - it explicitly defers Tier 3 layout, Tier 4 GPU render, and instance-side `(math_environment) @math` injection detection back to this arc.