Repository navigation
fix(dashboard): render LaTeX-native math delimiters via KaTeX - #7806
Conversation
02225e0 to
3c7ee2a
Compare
UX Review (Fable 5, fork) — ✅ PASSUX-level review of UX-Verdict: PASS Verify the PR's stated residual with real connector content: Jira/ADF-escaped [UX-REVIEWED] fe8ae99 |
Design Review (Fable 5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the timing-guard tests' wall-clock on CI — six 900 KB renders under one 5-minute timeout is a permanent cost every frontend run now pays. Suggestions
[DESIGN-REVIEWED] fe8ae99 |
First Principles Review (Fable 5, fork) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS
Not justified as shipped
What this change shipsInventory (9 items) — 7 justifiedIntent: make LaTeX-native
[FIRST-PRINCIPLES-REVIEWED] fe8ae99 |
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Opus 4.8 Review (fork) — ✅ no blocking findingsReviewed Review detailsThe PR branch isn't checked out locally, so I'm validating against the pre-fetched diff, which contains the full new-file contents. I've traced both candidates through that code. Candidate 1 ( Candidate 2 ( No new groundable defects surfaced during falsification. No blocking issues; one advisory false-negative in entity alignment. FINDING — website/src/utils/remarkLatexDelimiters.ts:269 — [OPUS-REVIEWED] fe8ae99 |
3c7ee2a to
5f51fca
Compare
Review round 1 — GPT blockings addressed in
|
5f51fca to
b290b4d
Compare
Review round 2 — both lanes' blockings addressed in
|
Review disposition (head
|
1bcd277 to
d52066b
Compare
|
Round on F1 — inline math strips the surrounding soft breaks (UPHELD → fixed). Exactly as described: F2 — quoted 155/155 in the renderer suite, 1060 across the 62 renderer-related files, |
d52066b to
4191a1f
Compare
|
Round on F1 — unclosed verbatim openers make pairing quadratic (UPHELD-FENCED → fixed, in both consumers). Correct, and measurable: 6000 unclosed Fix in the shared module: Test: the 6000-opener input under a 3 s bound — fails the previous head at 8.0 s, passes now at ~0.3 s (9x headroom, so it will not flake on a slow runner), and asserts the semantics (one KaTeX span for the trailing math, the lone openers shown as source). 156/156 renderer suite, 1061 across the 62 renderer-related files, tsc/lint clean. |
|
Round on F1 — text-node boundaries misclassify mid-sentence brackets as display math (UPHELD-FENCED → fixed). Correct: I did not take the suggested absolute-offset check: it would reject Tests: |
|
Round on GPT F1 — cached tag indices go stale after a text-node splice (UPHELD-FENCED → fixed). Real, and mine from last round: the pairing map was built lazily on the sibling list and then consulted after First Principles BLOCK — committed screenshots (fixed). You are right and I should have read Subtractions taken: 160/160 renderer suite, 1065 across the 62 renderer-related files, tsc/lint clean. |
|
Round on Opus F1 — per-closer slicing makes a Measured on 161/161 renderer suite, 1066 across the 62 renderer-related files, tsc/lint clean. |
|
Fix: both timing guards now assert a ratio, not a wall-clock bound, so they read the same on any runner:
Neither test's semantics changed (one KaTeX span / no conversion assertions kept). 161/161 x3 locally, tsc/lint clean. If the shard-1 red turns out to be something else once the log is readable, I'll address it next round rather than guess further here. |
|
|
|
|
|
|
|
Reviewed on the current head for approval.
|
|
|
Models emit \[ ... \] (display) and \( ... \) (inline) — LaTeX's own delimiters — but remark-math only tokenizes dollar math, and the renderer deliberately runs singleDollarTextMath: false (the currency guard), so valid math displayed as raw source text (kirodotdev#7803). normalizeMathDelimiters rewrites both forms to $$ before remark-math, skipping fenced code blocks and inline code spans, leaving unmatched openers alone, and preserving string length exactly (2 chars -> 2 chars) so sourcePos coordinates stay valid. Fixes kirodotdev#7803
bolichen97
left a comment
There was a problem hiding this comment.
Reviewed the full diff on head fe8ae99 as part of the 2026-09-17 readiness audit (evidence: pr-ready-audit-20260917-0835). Verified before approving: readiness: passed in place, required status PR Readiness success on this head, no CHANGES_REQUESTED, no unresolved human hold, main-drift checked against files this PR touches, last push by jeeshofone. Merge follows through the normal protected path (no bypass).
Problem / Motivation
Assistant responses containing valid LaTeX display math (
\[ ... \]) or inline math (\( ... \)) render as raw source text in the dashboard chat instead of formatted equations (#7803).Why it matters
These are the delimiters LaTeX itself uses, and exactly what models tend to emit. Any technical or mathematical conversation degrades to unreadable markup, even though the dashboard already ships a full KaTeX pipeline.
What changed (motivation → approach → change)
Symptom: valid math shows as raw text. Root cause: the markdown pipeline runs
remark-mathwithsingleDollarTextMath: false— a deliberate guard so currency strings ($9.99 … $19.95) don't get parsed as one giant math span — which leaves$$…$$as the only recognized math form. remark-math never tokenizes\[…\]/\(…\), so they fall through as text. KaTeX itself (rehype-katex+ stylesheet) is fully wired; the gap is purely delimiter recognition.Change: a remark transform,
remarkLatexDelimiters(website/src/utils/remarkLatexDelimiters.ts), registered inREMARK_PLUGINSright afterremark-math. It emits remark-math's own mdast nodes (inlineMath/math, identicaldata.hName/hProperties/hChildren) from eligible text nodes only, so rehype-katex renders them exactly like$$math. Because remark has already consumed CommonMark escapes when it builds a text node, the transform reads the node's RAW source slice through its position (so\[is still visible) and re-applies escape + character-reference decoding to the prose it hands back. Display math found inside a paragraph splits the paragraph so themathblock is valid flow content.What is protected, and why it is structural rather than enumerated:
code,inlineCode,html,link,linkReference,image,imageReference,definition, footnotes and frontmatter are other node types and are never visited. So fenced code (including inside blockquotes), indented code, inline code spans, link destinations, reference-link definitions and raw HTML attributes are untouched by construction — not by a scanner that has to recognise each one in source. Eligibility rules, each with a regression test:\\(is an escaped backslash followed by a plain paren;\\\(is an escaped backslash then a real opener).\( … \)needs its closer in the same text node. Accepted residual: inline has no line-shape guard, so a producer that escapes parens in prose (the ADF/Jira class the display rule is hardened against) now renders\(x\)as KaTeX where it used to show(x); the display rule's line-shape test has no inline analogue because inline math legitimately sits mid-sentence, and the escape-parity rule still keeps\\(x\\)literal.\[ … \]needs whitespace-shaped delimiters that own their line ends within the node (\[ x \],\[\n…\n\]); a hugging escaped bracket (\[a\],\[REDACTED: …\],see \[ x \] here— the Jira/ADF converter's shapes) stays a literal escape.(is link/image syntax and never converts.](junk input stays linear. The timing guards assert ratios of medians over three interleaved samples per shape (amedianRatiohelper in the test file), never a singleperformance.now()pair, so a GC pause or a shared runner's noise cannot fail them; the 900 KB flood test's timeout is raised to cover six renders.This is the shape arbitrated in round 6: review rounds 1–6 each surfaced one more non-prose context a source scanner had to enumerate (ADF brackets, link destinations, definitions, escape parity, indented code, and finally raw HTML attributes), a list that can never be shown complete by inspection. The plugin costs no extra parse — it runs inside the parse the renderer already performs — and follows the file's existing "read it off remark's own parse" pattern (
AUTOLINK_PARSER,remarkAutolinkRules).Also in this change, because the plugin exposed it: the renderer's verbatim-unknown-tags pass and the plugin's verbatim context now share one tag grammar (
website/src/utils/htmlTagGrammar.ts— the quote-aware single-tag regex,singleTagName,isOpeningTag, and a single-passpairedCloseIndices), replacing two private copies that had already diverged on a quoted>inside an attribute. The shared pairing is one linear pass with a stack per tag name; the per-opener suffix scan it replaces was quadratic on unclosed openers in both consumers (measured 8.0 s for 6000 unclosed<customblock>before one math delimiter; ~0.3 s now, guarded by a timing test). The plugin'sverbatimTagpredicate is required — the renderer supplies the same predicate its own pass uses, so there is no second list of verbatim tags.Alternatives considered: enabling
singleDollarTextMath(reintroduces the currency-crash class the guard exists for); a standalone pre-parse mask (measured: the parse itself is super-linear on this PR's own](junk input, ~6.9s at 100kB — acceptable inside the render parse that already pays it, not as an additional pass).Tests
Twenty render-level cases in
MarkdownRenderer.test.tsx(144/144 in the file; 547/547 across the 35 renderer test files): display and inline math render through KaTeX (.katex-display/.katex); literal\[survives inside fenced code, blockquoted fenced code, indented code and inline code; unmatched openers are left alone; ADF/Jira hugging and mid-sentence escaped brackets stay literal; whitespace-padded display converts; link destinations and reference-link definitions keep their escaped parens; escape parity (\\(literal,\\\(converts); the two linear-time guards against pathological unmatched-opener and](junk input; a raw HTMLhrefwith escaped parens survives intact while prose math beside it converts (the round-7 finding — fails on the scanner head); a paragraph is split around display math with no<pre>under a<p>; character references in prose next to converted math decode correctly.Note: the new describe block is appended at the end of the test file — inserting it mid-file surfaced a pre-existing order-sensitivity in a neighboring test (reproducible at base with only test insertion, no source change); left for a separate report rather than folded into this fix.
Manual verification
N/A — unit coverage exercises the full render path (ReactMarkdown → remark-math → rehype-katex) through the real component in jsdom, including the exact payload from the issue.
Screenshots / video
Same markdown through the renderer on
mainand on this branch (Storybook story rendering the realMarkdownRenderer; the escaped-literal cases -- Jira key in a code span,**bold** \[ x \]mid-sentence,\[escape\]in code -- render identically in both, which is the point).Before (main): raw
\[ \sum_{i=1}^{n} ... \]and\(e^{i\pi} + 1 = 0\)shown as source text.After (this PR): inline and display KaTeX; the display block owns its line; blockquote math renders.
Related Issues
Fixes #7803
Pattern harvest
Rule candidate: review-prompt
Pattern: "renderer feature enabled for only one delimiter dialect — check what producers actually emit (LLMs emit LaTeX-native
\[ \]/\( \), not$$) before concluding a rendering feature works"Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement