feat(web): render TeX math in chat markdown

[YishayPo]

Assistant responses full of LaTeX were unreadable: chat showed raw \(...\), $...$, and $$...$$ source instead of typeset math.

A Scient-owned module (apps/web/src/scient/math) renders TeX in chat markdown with a lazily loaded, locally bundled KaTeX 0.16.47 — no CDN request; the swap-variant stylesheet (katex-swap.min.css) and woff2 fonts ship in the async chunk, so math paints with fallback glyphs during cold font loads. Recognition happens at three altitudes, each where its inputs are unambiguous:

• normalizeScientMathDelimiters rewrites model-emitted \(...\)/\[...\] into $$ forms on the raw string, length-preserving (no character offset ever moves, so task-list toggling and other offset-based behavior stay correct on every surface). Fenced/indented/inline code, raw HTML <code>/<pre> regions, HTML tags (attribute text is never rewritten), and HTML comments are protected ranges.
• remarkScientSingleDollarMath recognizes single-dollar $...$ at a guarded micromark text construct — raw-source altitude, so spans arrive whole before emphasis runs, \$ escapes are handled structurally, and rejected candidates unwind without corrupting links, prices, or shell text. Flanking rules plus content plausibility keep $HOME/bin:$PATH, ${DIR}/${FILE}, $a\n$b, $el.fadeOut(200)$, reference links, footnotes, and autolinks byte-identical to a math-free renderer, while $x^2$, $sin(2x)$, $a*b*c$, $100\%$, and $[0,1)$ typeset. One residual glued-identifier shape is documented as the accepted floor in the internals doc.
• remarkScientMathRefinements runs on the parsed tree: unclosed or oversized math stays literal while streaming; authored \[...\] becomes display math wherever it appears, splitting its paragraph the way TeX does; \(...\) and single-dollar spans keep inline intent; own-line $$x$$ promotes to display. A per-message hook threads the pre-normalization text so the original delimiter at each node offset decides intent — possible precisely because normalization preserves offsets.

Rendering falls back to the literal source while the chunk loads, on KaTeX failure (no red error markup — throwOnError with literal fallback), and for oversized input; maxSize caps pathological dimensions. Rendered and fallback math carries data-markdown-copy with $$ forms, so highlight-and-copy round-trips TeX. Math cache reads/writes skip streaming renders, mirroring the Shiki highlight cache. Rendered markdown file previews inherit the same treatment; mobile is deliberately untouched (native markdown module keeps raw TeX legible).

The inherited-host seam is ChatMarkdown.tsx only: the math import block, three plugin entries per remark array, two hooks (useScientMathMarkdownText, useScientMathRemarkPlugins), and two component branches — guarded by the static seam-audit test. Maintenance contract: docs/internals/scient-math.md; shipped behavior: docs/user/math-in-chat.md.

Verification: 106 focused unit tests (delimiter normalization, tokenizer guards and plausibility rules, authored-intent matrix, streaming prefixes, seam audit, chat-shaped pipeline through the real plugin chain and sanitizer, RTL fixture); full apps/web unit project 2815/2815; three adversarial verification rounds structure-diffed against a no-plugin baseline with every discovered bypass encoded as a regression test; production Windows build packaged and manually exercised against live model output.

Implemented and reviewed by Claude Fable 5 running in Claude Code.

🤖 Generated with Claude Code

[yaacovcorcos]

Yishay, the overall architecture is strong and should remain:

• Math is owned under apps/web/src/scient/math.
• Integration with inherited T3 code is narrow and localized to ChatMarkdown.
• KaTeX is pinned, bundled locally, and lazily loaded.
• Rendering remains independent from the PDF reader and document-artifact architecture.
• Original TeX is preserved for copying.
• Literal fallback and bounded caching are the right design direction.

I am requesting changes because the current recognition and rendering behavior can corrupt ordinary Markdown and mishandle incomplete content.

1. Dollar parsing corrupts ordinary Markdown

With singleDollarTextMath: true, remark-math changes Markdown structure before ScientMath can apply its currency heuristic.

I reproduced these failures:

[_chat.$threadId.tsx](/tmp/_chat.$threadId.tsx:12)
$PATH$
$USD$
$HOME and $PATH.

The file link is destroyed, and shell/environment identifiers are interpreted as math. The same parser-level problem affects some currency expressions. The component-level currency fallback cannot reconstruct Markdown that was already parsed incorrectly.

Please make dollar recognition token-aware and ensure ordinary dollars remain completely unchanged in:

• link labels and destinations;
• file paths and route parameters;
• shell/environment identifiers;
• currency;
• escaped dollars;
• unmatched delimiters.

If $...$ cannot be distinguished safely, it should not be globally enabled until it can be.

2. Backslash-delimiter normalization mutates literal code

The current raw-string transformation for \(...\) and \[...\] only protects simple backtick cases. I reproduced rewriting inside:

• tilde code fences;
• indented code blocks;
• raw <code> regions.

Math normalization must only affect eligible Markdown text, never code or literal regions. The solution must preserve source positions so task-list editing and other offset-based behavior remain correct.

The current onTaskListChange === undefined gate also causes identical Markdown to support different delimiters depending on the rendering surface. Please remove that surface-dependent behavior as part of correcting the normalization boundary.

3. Incomplete streaming math renders prematurely

An unclosed display block such as:

$$
x + y

is already interpreted and rendered as display math. Unclosed math fences behave similarly.

While streaming, incomplete math must stay literal until its closing delimiter arrives. Rendering should then begin normally. Please also bound the maximum TeX input size so malformed or extremely large model output cannot repeatedly trigger expensive KaTeX work.

4. Test the real ChatMarkdown integration

The current seam test primarily inspects source strings and a default react-markdown pipeline. It does not prove that the actual ChatMarkdown component map routes inline and display nodes correctly.

Please add integration-level regressions covering:

• inline math;
• display math;
• fenced math;
• unfinished streaming delimiters;
• links and paths containing $;
• $PATH$, $USD$, currency, and escaped dollars;
• inline, fenced, tilde-fenced, indented, and raw HTML code;
• task-list Markdown;
• malformed or unsupported TeX;
• copying the original TeX;
• both backslash and dollar delimiters.

The test should prove that inline math avoids <pre>, while display and fenced math use the display wrapper.

5. Prevent inherited chat wrapping from breaking equations

.chat-markdown applies overflow-wrap: anywhere and word-break: break-word. The KaTeX subtree currently does not reset those inherited rules.

Please prevent internal equation fragments from wrapping arbitrarily. Wide display equations should scroll within their math container rather than widening or breaking the conversation.

6. Make malformed-math fallback consistent

The documentation says unrenderable equations fall back to their original notation. However, throwOnError: false currently produces KaTeX's hard-coded red error markup for unsupported commands.

Please make the behavior consistent: malformed or unsupported TeX should display the original literal notation cleanly, without an unthemed red KaTeX error.

7. Finish dependency and asset hygiene

Before merge:

• Add KaTeX, its distributed fonts, and remark-math to apps/web/THIRD_PARTY_NOTICES.md.
• Use the KaTeX swap stylesheet or another explicit strategy that avoids blank math during cold font loading.
• Correct the documentation claiming only WOFF2 assets are emitted; the current stylesheet references WOFF2, WOFF, and TTF.
• Remove the incidental unist-util-visit lockfile change if it is not required by the resolved dependency graph.

Final verification

After the fixes:

• Rebase onto current main.
• Run focused math and real ChatMarkdown tests, web typecheck, production build, formatting, lint, and git diff --check.
• Attach visual evidence for light/dark and narrow/wide chat, including one RTL conversation and a long display equation.

The PDF/document-artifact boundaries are already correct and do not need to change in this PR. The required work is to make the current math layer safe, deterministic, and proven through its real integration surface.

[yaacovcorcos]

Alignment with existing Scient work

Before finalizing this PR, please review:

• the “Mathematics Everywhere It Belongs” direction in the Scientific Document Platform Roadmap;
• the controlled-renderer requirements in docs/internals/scient-pdf-export-rendering-plan.md;
• the existing conversational bidi implementation from PR #15 and PR #17; and
• the Markdown task-list and truncated-preview safety established by PR #64. PR #30 is also useful context for the existing Markdown-preview behavior this PR inherits.

These references do not expand this PR into PDF export, LaTeX compilation, or broader document-platform work. They establish the boundaries this foundation should preserve:

• keep one reusable Scient-owned Markdown math renderer rather than creating surface-specific math stacks later;
• preserve original TeX and a clean literal fallback;
• cooperate with the existing bidi pipeline and never rewrite mathematical content as RTL prose;
• preserve Markdown source positions and task-list write safety; and
• keep the inherited ChatMarkdown integration narrow so future T3 updates remain manageable.

Please also update docs/internals/scient-math.md and docs/user/math-in-chat.md so they accurately describe the final corrected behavior.

The Scientific Document Platform Roadmap is proposed product direction, while the desktop PDF export plan is the repository implementation plan for its lane. Neither should be treated as permission to broaden this PR beyond the chat/Markdown math foundation.

[yaacovcorcos]

Three targeted additions to the requested changes

1. Please explicitly preserve numeric inline math. Properly delimited expressions such as $1/2$, $1+1$, $12-15$, and $42$ must render as math; the currency safeguard must not classify every numeric-only span as money. Add currency counterexamples alongside these regressions.
2. Alongside the maximum TeX input length, configure a finite KaTeX maxSize and test a pathological size command such as \rule{500em}{500em}. Oversized input must not create pathological chat layout and should use the clean literal fallback when rejected.
3. Add one focused RTL non-regression. Mathematics can appear inside an otherwise ordinary Hebrew or RTL conversation, so the surrounding prose must retain its existing direction while the equation remains correctly isolated and ordered. This is compatibility proof for the shared renderer, not a request for broader RTL work.

For equation wrapping, verify behavior with long inline and display fixtures: prevent arbitrary inherited word-breaking, retain KaTeX’s intentional inline break opportunities, and keep wide display math contained and horizontally scrollable.

A regenerated lockfile may legitimately retain the unist-util-visit change through the resolved dependency graph; do not remove it manually if regeneration preserves it. Please rebase on the latest main before final verification.

[YishayPo]

Thank you for the review — the recognition redesign it forced was the right call. All seven areas plus the follow-up additions are addressed in fix(web): make chat math recognition token-aware and streaming-safe (with the earlier hardening commit rebased beneath it). Point by point:

1. Dollar parsing. singleDollarTextMath is now off — I confirmed your diagnosis that structure the parser destroys cannot be repaired downstream. Single-dollar spans are recognized by a new Scient remark plugin (remarkScientMathRefinements) on the parsed tree, where link labels/destinations, code, images, and raw HTML are structurally excluded, under token rules: opener/closer flanking, no digit after the closer (protects $5-$10), all-caps identifiers stay text, spaced content needs an operator or control sequence, and a text run containing an escaped \$ opts out entirely. Your repro cases are regression tests: the $threadId file link survives intact, $PATH$/$USD$/$HOME and $PATH. stay text, and per your follow-up, $42$, $1/2$, $1+1$, and $12-15$ all render as math (currency counterexamples alongside).

2. Normalization boundary. The rewrite is now length-preserving — each of \(, \), \[, \] becomes exactly $$ — so no source offset ever moves and the onTaskListChange gate is deleted; identical markdown now behaves identically on every surface. Tilde fences, indented code, unclosed fences, inline code (including multi-backtick), and raw <code>/<pre> regions are protected, each with a test. Because remark-math treats single-line $$x$$ as inline, a refinement step promotes a paragraph holding exactly one $$ span to display math, which is how own-line \[...\] keeps block semantics.

3. Streaming. The refinement plugin checks the raw source for each math node: an unclosed $$ block or ```math fence renders as its literal source until the closing delimiter arrives, then renders normally — your exact repro is a test. TeX is bounded at 1000 characters; oversized input downgrades to literal in every form.

4. Integration tests. The seam test now runs the review matrix through the real plugin chain and sanitize schema shape: inline/display/fenced math, unfinished streaming delimiters, links and paths with $, identifiers, currency, escaped dollars, all four code-region kinds, task-list markdown, malformed TeX, copy round-trip, and both delimiter families — proving inline math arrives as a bare code and display/fenced math under pre. One honest limitation: a full ChatMarkdown mount needs more environment stubbing than the node test runner reasonably supports, so the component-map routing itself is covered by the static seam audit plus component-level fallback renders. The RTL non-regression runs the pipeline with rehypeScientBidi: Hebrew prose keeps its direction while the equation stays an isolated LTR math node.

5. Wrapping. overflow-wrap/word-break are reset to normal inside the KaTeX subtree, keeping KaTeX's own break opportunities; wide display math scrolls inside .scient-math-display.

6. Malformed-math fallback. renderScientTexToHtml now uses throwOnError: true in a try/catch and returns null; components render the literal dollar-form source — the same fallback as loading and error-boundary states. No red KaTeX markup. maxSize: 50 caps pathological sizes; the \rule{500em}{500em} fixture asserts capped rendered styles.

7. Hygiene. KaTeX (with its WOFF2/WOFF/TTF fonts) and remark-math are in THIRD_PARTY_NOTICES.md; the docs' woff2-only claim is corrected. Font loading uses font-display: swap, injected by a small build plugin (scientKatexFontDisplay.ts, same pattern as scientPdfAssets) — verified in the production build: all 20 @font-face rules patched, 59 font files emitted locally, KaTeX in its own lazy chunk. The unist-util-visit lockfile entry is retained by regeneration through remark-math's dependency graph. Both docs are updated to the corrected behavior, and the branch is rebased onto current main (48d63d4).

Verification: 65 focused tests, targeted typecheck clean for every changed file, apps/web production build passing, format and git diff --check clean. Visual evidence for light/dark, narrow/wide, RTL, and a long display equation is being captured from a dev instance and will be attached here.

Implemented and reviewed by Claude Fable 5 running in Claude Code, on Yishay's behalf.

Superseded by the consolidated review of current head 4822241. Addressed items are no longer requested; the remaining current findings are recorded in the new review.

[yaacovcorcos]

Yishay, the redesign is a substantial improvement. Moving away from
singleDollarTextMath: true, keeping the implementation Scient-owned behind a
narrow ChatMarkdown seam, preserving literal fallback and copyable TeX, and
bounding streaming work are the right architectural decisions.

I rechecked the current head through the real plugin prefix. Three issues
remain in behavior this PR already implements:

1. Single-dollar recognition is still unsafe and inconsistent.
   echo $HOME/bin:$PATH turns HOME/bin: into a math node; $a*b*c$ and
   $a~~b~~c$ are fragmented; and literal \$5 then valid $x+1$ suppresses
   the later valid expression. Please either move $...$ recognition to a
   parser/tokenizer boundary that retains source context or leave single-dollar
   recognition disabled for this first release.
2. Backslash-delimiter normalization loses meaning and touches protected
   text. \(x\) and \[x\] both become $$x$$, and raw HTML attributes can
   be rewritten. Please preserve inline/display intent and structurally exclude
   raw HTML, attributes, code, escapes, and other protected Markdown contexts.
3. The KaTeX font-display patch is ineffective. The emitted face contains
   swap followed by the original block, so block wins. Please replace the
   original declaration or otherwise make the final emitted CSS unambiguous.

Please add the exact reproducers above to the focused real-plugin-chain tests.
The repository-wide cancelled Test job should be rerun through the repository
CI lane; it is not evidence of a math-specific flake.

I am not asking this PR to add PDF export, complete-document LaTeX, a broader
scientific renderer, or a new product-wide geometry policy.

[YishayPo]

All three points are addressed on the rebased head (fa2191b, on top of 5c1a63f), each verified by a running reproducer before and after the fix.

1. Single-dollar recognition. All three failures reproduced exactly as you described — and your diagnosis pointed at the fix. I implemented your first option: recognition moved to a guarded micromark text construct (apps/web/src/scient/math/scientSingleDollarMath.ts), which emits the upstream mathText tokens so mdast-util-math needs no extra wiring. At the tokenizer, the problems that killed the tree-level approach dissolve: the construct sees raw source before emphasis runs, so $a*b*c$ arrives whole; markdown's escape construct consumes \$ before the construct is attempted, so escapes work structurally instead of by text-run opt-out; and a rejected candidate unwinds without touching surrounding structure, so links and prices cannot be corrupted. Recognition is bounded by flanking rules (no word character before the opener, no whitespace at either edge, no digit/dollar/brace after the closer, single-line, 300-char cap — streaming half-formulas stay literal) and content plausibility (shell identifiers and identifier paths, interpolation shapes, string escapes like $a\n$b, code calls, markdown link/footnote boundaries, HTML-tag shapes, and domains all stay text). Your reproducers are regression tests, and three adversarial verification rounds — structure-diffing ~70 probe documents against a no-plugin baseline, guard-bypass batteries over shell/interpolation/currency corpora, and per-character streaming prefixes — drove every discovered bypass into the rules; the reproducers live in the co-located tests. One residual shape is documented as the accepted floor in docs/internals/scient-math.md (echo $a$b — content byte-identical to authored math). Rationale for implementing rather than disabling for v1: model answers are the dominant source of chat math, and several model families emit $...$ constantly — with it off, the feature misses its main use case.

2. Delimiter normalization. The rewrite stays length-preserving, and that property now recovers intent instead of erasing it: a per-message hook threads the pre-normalization text to the refinement plugin (the shared static plugin arrays are untouched when a message has no backslash delimiters), which reads the original delimiter at each math node's offset. \[...\] becomes display math wherever it appears — splitting its paragraph into prose–equation–prose the way TeX does — and \(...\) is never promoted to display. The onTaskListChange-style surface dependence stays gone. Raw HTML tags and comments are now protected ranges, so attribute text (href, title) is never rewritten; prose between inline tags stays eligible, matching CommonMark semantics.

3. Font-display. Confirmed precisely: katex.min.css ships font-display: block and the prepended swap lost by source order — the patch achieved nothing. It is deleted; the runtime now imports katex/dist/katex-swap.min.css, the variant KaTeX itself ships with swap in every face. Verified in the emitted production CSS chunk: 20 occurrences of font-display:swap, zero of block, fonts and the lazy KaTeX chunk unchanged.

Verification: 106 focused math tests through the real plugin chain and sanitize schema shape; full apps/web unit project 2815/2815; full-repo lint with zero findings in touched files; git diff --check clean; production Windows build packaged and manually exercised against live model output. Both docs are updated to the corrected behavior. The repository Test lane re-runs on this push.

Implemented and reviewed by Claude Fable 5 running in Claude Code, on Yishay's behalf.

[yaacovcorcos]

Re-reviewed at 5b94d72. The requested tokenizer, delimiter-normalization, and KaTeX font-loading corrections are implemented, the focused behavior is covered, all current hosted checks pass, and no review threads remain unresolved. Agent capability awareness is intentionally tracked as a separate follow-up rather than expanding this renderer PR.