Disable single-$ inline math so plain-text dollar signs are not parsed as KaTeX

[marceloguedes]

Target area: packages/client/ui-primitives/src/markdown/ (settled markdown pipeline)

Summary

DSH's settled markdown arm enables micromark-extension-math with default options. The upstream default singleDollarTextMath: true makes any pair of single dollar signs an inline math delimiter. Prose that contains ordinary currency amounts (e.g. The price moved from $1.5B to $7B this year) is therefore parsed as inline TeX from the first $ to the last $ in the paragraph, and everything in between is handed to KaTeX. When the "formula" is not valid TeX, KaTeX throws, and the renderer's error arm replaces the span with an error placeholder — the original prose is lost to the reader.

The fix is a one-line option change: math({ singleDollarTextMath: false }). All explicit math delimiters ($$…$$, \(…\), \[…\]) keep working; bare $…$ becomes literal text again.

Problem and reproduction

Given a settled message body such as:

Net revenue was $38.5B, up 5.8%, and guidance is for $3.0B of FCF.

the markdown parser produces an inlineMath node whose content is 38.5B, up 5.8%, and guidance is for $3.0B of FCF — i.e. it pairs the first and last $ of the sentence. The KaTeX error arm then renders an error box in place of the sentence. Symptoms reported in the GUI:

• long spans rendered as math (wrong font, wrong size, wrong line height),
• overflow past the content margins (math spans are inline and unbounded),
• error placeholders where plain prose used to be.

The issue is deterministic and content-driven: it needs no user input beyond a normal message that mentions money twice.

Root cause

parseGfmWithMath in packages/client/ui-primitives/src/markdown/parse.ts builds the finalized-arm micromark pipeline as GFM + math:

use([gfmFootnote(), math(), ...])

micromark-extension-math (3.x) defaults to:

{ singleDollarTextMath: true, ... }

With that default, the mathText tokenizer treats $…$ as an inline math delimiter pair. The streaming arm (GFM only, no math extension) is unaffected — this is purely a settled-arm behavior.

Proposed change

packages/client/ui-primitives/src/markdown/parse.ts:

- use([gfmFootnote(), math(), ...])
+ use([gfmFootnote(), math({ singleDollarTextMath: false }), ...])

(Adapt to the actual pipeline call in the file — the change is the math() invocation, wherever the finalized pipeline is assembled.)

Behavior change matrix

Input	Before	After
cost $1.5B, target $7B	inlineMath (garbage TeX, likely error arm)	literal text
E = $$mc^2$$ inline	literal text ($$ not a single-$ pair)	inlineMath node
$$E = mc^2$$ on its own line	math (display) node	math (display) node
\( \frac{1}{2} \)	inlineMath node (mathCompatibility)	unchanged
\[ E = mc^2 \]	math (display) node (mathCompatibility)	unchanged
$$ left alone in prose (typo)	literal text	becomes a display-math delimiter toggle — see caveat below

Caveat (accepted consequence): with singleDollarTextMath: false, $$ is the only dollar-based delimiter, and a stray $$ in prose will open/close display math. This mirrors KaTeX's own default configuration (KTeX/MathJax both disable single-$ by default for exactly this reason) and is strictly less surprising for prose than the current behavior.

Tests and fixtures to update

Any spec or golden fixture that asserts single-$ inline math must be re-expressed with the surviving delimiters ($$…$$, \(…\)):

• packages/client/ui-primitives/tests/markdown.client.spec.tsx
• packages/client/ui-primitives/tests/markdown-incremental.client.spec.tsx
• packages/client/ui-primitives/tests/markdown-dom-parity.client.spec.tsx
• packages/client/ui-primitives/tests/fixtures/markdown-dom/math-*.streaming.txt (golden DOM; note the DOM-text convention in those files: backslashes are doubled in the file bytes, and \(…\) delimiters are consumed in the streaming arm so their content appears with plain parentheses)
• apps/web/tests/math-rendering.e2e.ts (+ its ui.expected.md snapshot if the DOM changes)

Audit command to find remaining single-$ math assertions across the repo:

rg -n '\$[\\a-zA-Z]' packages/client/ui-primitives/tests apps/web/tests

Each hit must be audited: keep it (now legitimately literal) or rewrite it to $$…$$ / \(...\) if it is meant to assert math.

Build and verification

# unit + golden DOM parity (fast)
CI=true pnpm vitest run packages/client/ui-primitives/tests/markdown

# web e2e (needs Playwright chromium: pnpm exec playwright install chromium from apps/)
CI=true pnpm vitest run --config vitest.web.config.ts math-rendering

# full rebuild of client artifacts + web shell (required for the running `dsh web` server to serve the change)
pnpm run build

Manual check: in a live GUI session, send/reply with a message containing two $ amounts in one paragraph; confirm both render as plain text and that a genuine $$E = mc^2$$ block still renders as display math.

[argszero]

Thanks for the very precise report, @marceloguedes. The bug is real and deterministic — I reproduced it against micromark-extension-math@3.1.0 (the pinned version) and your diagnosis is correct. But the proposed one-line option flip has a regression cost that I think is worth pausing on, and I'd suggest a more surgical fix.

Confirmed: the pairing is not flanking-aware

mathText in micromark-extension-math@3.1.0 recognizes an opening $ purely from its previous construct, which only rejects a \-escaped dollar:

function previous(code) {
  return code !== 36 || this.events[this.events.length - 1][1].type === "characterEscape"
}

There is no alphanumeric flanking check — no "reject $ when the preceding/following character is a letter or digit". So the data state machine simply pairs the next $:

Net revenue was $38.5B, up 5.8%, and guidance is for $3.0B of FCF.
  text("Net revenue was ") → inlineMath("38.5B, up 5.8%, and guidance is for ") → text("3.0B of FCF.")

That inlineMath content (38.5B, up 5.8%, and guidance is for) is not valid TeX, so KaTeX throws and the error arm swallows the whole span — exactly your symptom. Confirmed deterministic.

The regression: single-$ inline math is a tested feature

{ singleDollarTextMath: false } fixes the prose case but turns the intended math case back into literal text. And $E = mc^2$ — the canonical inline-math example — is asserted as a real feature in three test files:

• packages/client/ui-primitives/tests/markdown.client.spec.tsx:321 — 'Einstein wrote $E = mc^2$.' ⇒ .katex length 3 (inline + display + unsafe)
• packages/client/ui-primitives/tests/markdown-dom-parity.client.spec.tsx:221 — same, in the settled/streaming DOM-parity snapshot
• packages/client/ui-primitives/tests/markdown-incremental.client.spec.tsx:110 — same, in the incremental arm

Under { singleDollarTextMath: false }, that node becomes plain text("Einstein wrote $E = mc^2$.") and all three fail. So this isn't a free win — it's a behavior flip on a deliberately-kept feature, and the change matrix in the report already shows the $E = mc^2$ row regressing.

Suggested surgical fix: alphanumeric flanking guard

Rather than disabling single-$ entirely, reject it where it's not math — i.e. when the $ is immediately adjacent to an alphanumeric on the open OR close side. This is analogous to the CommonMark inline-code backtick flanking rule and it fixes both cases:

Input	Default	+ alnum flanking guard	singleDollarTextMath:false
cost $1.5B, target $7B	inlineMath (garbage)	literal text ✅	literal text ✅
$E = mc^2$	inlineMath ✅	inlineMath ✅	literal text ❌
$\theta$	inlineMath ✅	inlineMath ✅	literal text ❌

This is implementable in the existing seam. packages/client/ui-primitives/src/markdown/parse.ts:41 registers mathCompatibility() — a custom micromark extension (mathCompatibility.ts) that already exposes a previous construct and its own tokenizer. That's the right place to add the guard: extend the previous (and a symmetric close-side check) so a single $ adjacent to [A-Za-z0-9] is not treated as a delimiter, while $$…$$, \(…\), \[…\] and genuinely-padded $…$ all keep working.

The trade-off is narrower than the option flip: only the single-$ delimiter gets flanking rules, not the whole math feature. It keeps the three existing tests green and adds prose safety, instead of removing a tested capability.

If you'd like, I can put together the concrete mathCompatibility() guard patch and the two new regression fixtures ($1.5B / $7B literal, and re-affirm $E = mc^2$). Happy to iterate here before any PR.