Skip to content

Commit d947a7a

Browse files
Hjalmar Karlsenclaude
andcommitted
feat(web): opt-in LaTeX math rendering in chat
Typeset $…$, $$…$$, \(…\) and \[…\] in chat and Markdown previews behind Settings → Appearance → Render math (off by default). Math is parsed by a micromark construct, so code, links, escapes and source offsets keep their CommonMark meaning; KaTeX loads lazily only when a formula renders. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 148e6de commit d947a7a

15 files changed

Lines changed: 834 additions & 6 deletions

‎apps/web/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,9 @@
4747
"jose": "catalog:",
4848
"jsonc-parser": "3.3.1",
4949
"jszip": "3.10.1",
50+
"katex": "^0.16.47",
5051
"lucide-react": "^0.564.0",
52+
"mdast-util-math": "^3.0.0",
5153
"react": "19.2.6",
5254
"react-dom": "19.2.6",
5355
"react-markdown": "^10.1.0",
@@ -76,6 +78,8 @@
7678
"babel-plugin-react-compiler": "1.0.0",
7779
"compression": "^1.8.1",
7880
"jsdom": "^30.0.1",
81+
"mdast-util-from-markdown": "^2.0.3",
82+
"micromark-util-types": "^2.0.2",
7983
"react-test-renderer": "19.2.6",
8084
"tailwindcss": "^4.0.0",
8185
"unified": "^11.0.5",

‎apps/web/src/components/ChatMarkdown.test.tsx‎

Lines changed: 73 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,16 @@ import { setMarkdownTaskChecked } from "./files/filePreviewMode";
1111

1212
vi.mock("@effect/atom-react", () => ({ useAtomValue: () => null }));
1313
vi.mock("../hooks/useTheme", () => ({ useTheme: () => ({ resolvedTheme: "dark" }) }));
14+
const settingsOverrides = vi.hoisted(() => ({ mathRenderingEnabled: false }));
1415
vi.mock("../hooks/useSettings", async (importOriginal) => {
1516
const actual = await importOriginal<typeof import("../hooks/useSettings")>();
1617
const settings = actual.getClientSettings();
1718
return {
1819
...actual,
19-
useClientSettings: (select?: (value: typeof settings) => unknown) =>
20-
select ? select(settings) : settings,
20+
useClientSettings: (select?: (value: typeof settings) => unknown) => {
21+
const value = { ...settings, ...settingsOverrides };
22+
return select ? select(value) : value;
23+
},
2124
};
2225
});
2326
vi.mock("./ui/tooltip", async () => {
@@ -447,6 +450,74 @@ describe("ChatMarkdown streaming", () => {
447450
});
448451
});
449452

453+
describe("ChatMarkdown math", () => {
454+
it("typesets only when enabled, keeping prices and task offsets intact", async () => {
455+
vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
456+
const text = "Area $\\pi r^2$ costs $5 and $10.\n\n\\[\nE = mc^2\n\\]\n\n- [ ] check \\(x\\)";
457+
const renderers: ReactTestRenderer[] = [];
458+
const render = async (parseRawHtml: boolean) => {
459+
await act(async () => {
460+
renderers.push(
461+
create(<ChatMarkdown cwd="/tmp/project" text={text} parseRawHtml={parseRawHtml} />),
462+
);
463+
});
464+
const renderer = renderers.at(-1)!;
465+
return {
466+
formulas: renderer.root
467+
.findAll((node) => node.type === "span" && node.props["data-markdown-math"] === "")
468+
.map((formula) => formula.props["data-markdown-copy"]),
469+
markerOffset: Number(renderer.root.findByType("li").props["data-task-marker-offset"]),
470+
};
471+
};
472+
473+
try {
474+
expect((await render(true)).formulas).toEqual([]);
475+
// Raw HTML carrying the math classes stays code while the setting is off.
476+
await act(async () => {
477+
renderers.push(
478+
create(
479+
<ChatMarkdown
480+
cwd="/tmp/project"
481+
text={'<code class="language-math math-inline">x</code>'}
482+
/>,
483+
),
484+
);
485+
});
486+
expect(
487+
renderers.at(-1)!.root.findAll((node) => node.props["data-markdown-math"] === ""),
488+
).toEqual([]);
489+
settingsOverrides.mathRenderingEnabled = true;
490+
// Both the sanitized raw-HTML pipeline and the literal one keep the math classes.
491+
for (const parseRawHtml of [true, false]) {
492+
const { formulas, markerOffset } = await render(parseRawHtml);
493+
expect(formulas).toEqual(["$\\pi r^2$", "$$\nE = mc^2\n$$\n\n", "$x$"]);
494+
expect(setMarkdownTaskChecked(text, markerOffset, true)).toBe(
495+
text.replace("- [ ]", "- [x]"),
496+
);
497+
}
498+
// List indentation recovery parses blocks again; they still typeset.
499+
const recovered = await act(async () =>
500+
create(
501+
<ChatMarkdown
502+
cwd="/tmp/project"
503+
text={"- intro\n\n $$\n x^2\n $$"}
504+
/>,
505+
),
506+
);
507+
renderers.push(recovered);
508+
expect(
509+
recovered.root
510+
.findAll((node) => node.type === "span" && node.props["data-markdown-math"] === "")
511+
.map((formula) => formula.props["data-markdown-copy"]),
512+
).toEqual(["$$\nx^2\n$$\n\n"]);
513+
} finally {
514+
settingsOverrides.mathRenderingEnabled = false;
515+
await act(async () => renderers.forEach((renderer) => renderer.unmount()));
516+
vi.unstubAllGlobals();
517+
}
518+
});
519+
});
520+
450521
describe("canUseMarkdownFileShellActions", () => {
451522
const environmentId = EnvironmentId.make("environment-1");
452523

‎apps/web/src/components/ChatMarkdown.tsx‎

Lines changed: 42 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -90,13 +90,15 @@ import { parseComposerContextHref } from "@t3tools/shared/composerContextReferen
9090
import { AssistantCitationChip } from "./chat/AssistantCitationChip";
9191
import remarkGfm from "remark-gfm";
9292
import { remarkGithubAlerts } from "../markdown-github-alerts";
93+
import { mathKind, mayContainMath, remarkChatMath } from "../markdown-math";
9394
import {
9495
artifactTemplateFromHastProperties,
9596
CODEX_ARTIFACT_TEMPLATE_HAST_PROPERTIES,
9697
remarkCodexDirectives,
9798
renderCodexFileCitationsAsMarkdown,
9899
} from "@t3tools/client-runtime/codex-markdown-directives";
99100
import { renderSkillInlineMarkdownChildren } from "./chat/SkillInlineText";
101+
import { MarkdownMath } from "./chat/MarkdownMath";
100102
import {
101103
resolveMarkdownMediaPreview,
102104
type ExpandedImagePreview,
@@ -470,7 +472,12 @@ const CHAT_MARKDOWN_SANITIZE_SCHEMA = {
470472
attributes: {
471473
...defaultSchema.attributes,
472474
"*": (defaultSchema.attributes?.["*"] ?? []).filter((attribute) => attribute !== "title"),
473-
code: [...(defaultSchema.attributes?.code ?? []), "dataCodeMeta", "dataInlineCode"],
475+
// Fence languages plus the two math classes `remarkChatMath` emits.
476+
code: [
477+
["className", /^language-./, "math-inline", "math-display"],
478+
"dataCodeMeta",
479+
"dataInlineCode",
480+
],
474481
blockquote: [...(defaultSchema.attributes?.blockquote ?? []), "dataAlert"],
475482
div: [...(defaultSchema.attributes?.div ?? []), ...CODEX_ARTIFACT_TEMPLATE_HAST_PROPERTIES],
476483
a: [...(defaultSchema.attributes?.a ?? []), "dataPullRequestAutolink"],
@@ -507,6 +514,22 @@ const CHAT_MARKDOWN_REMARK_PLUGINS_WITH_BREAKS = [
507514
remarkNormalizeLinksAndTagInlineCode,
508515
] satisfies NonNullable<ReactMarkdownOptions["remarkPlugins"]>;
509516

517+
const CHAT_MARKDOWN_MATH_REMARK_PLUGINS = [remarkChatMath, ...CHAT_MARKDOWN_REMARK_PLUGINS];
518+
519+
const CHAT_MARKDOWN_MATH_REMARK_PLUGINS_WITH_BREAKS = [
520+
remarkChatMath,
521+
...CHAT_MARKDOWN_REMARK_PLUGINS_WITH_BREAKS,
522+
];
523+
524+
function chatMarkdownRemarkPlugins(lineBreaks: boolean, math: boolean) {
525+
if (math) {
526+
return lineBreaks
527+
? CHAT_MARKDOWN_MATH_REMARK_PLUGINS_WITH_BREAKS
528+
: CHAT_MARKDOWN_MATH_REMARK_PLUGINS;
529+
}
530+
return lineBreaks ? CHAT_MARKDOWN_REMARK_PLUGINS_WITH_BREAKS : CHAT_MARKDOWN_REMARK_PLUGINS;
531+
}
532+
510533
const CHAT_MARKDOWN_REHYPE_PLUGINS = [
511534
rehypeRaw,
512535
rehypePreserveImageSourceMeta,
@@ -3315,6 +3338,19 @@ const CHAT_MARKDOWN_COMPONENTS = {
33153338
},
33163339
} satisfies Components;
33173340

3341+
const MarkdownCodeOrMath: NonNullable<Components["code"]> = (props) => {
3342+
const math = mathKind(props.className);
3343+
if (!math) return CHAT_MARKDOWN_COMPONENTS.code(props);
3344+
return <MarkdownMath tex={nodeToPlainText(props.children)} display={math === "display"} />;
3345+
};
3346+
3347+
// Only messages parsed with math enabled can typeset, so raw HTML carrying the
3348+
// math classes stays an ordinary code element while the setting is off.
3349+
const CHAT_MARKDOWN_MATH_COMPONENTS = {
3350+
...CHAT_MARKDOWN_COMPONENTS,
3351+
code: MarkdownCodeOrMath,
3352+
} satisfies Components;
3353+
33183354
function ChatMarkdown({
33193355
text,
33203356
className,
@@ -3335,13 +3371,15 @@ function ChatMarkdown({
33353371
props.isStreaming === true &&
33363372
extraRemarkPlugins.length === 0 &&
33373373
/(?:^|\n) {0,3}(?:`{3}|~{3})/.test(text);
3374+
const math =
3375+
useClientSettings((settings) => settings.mathRenderingEnabled) && mayContainMath(text);
33383376
const remarkPlugins = useMemo(
33393377
() => [
3340-
...(lineBreaks ? CHAT_MARKDOWN_REMARK_PLUGINS_WITH_BREAKS : CHAT_MARKDOWN_REMARK_PLUGINS),
3378+
...chatMarkdownRemarkPlugins(lineBreaks, math),
33413379
...extraRemarkPlugins,
33423380
...(incrementalParsing ? [createIncrementalMarkdownPlugin()] : []),
33433381
],
3344-
[extraRemarkPlugins, incrementalParsing, lineBreaks],
3382+
[extraRemarkPlugins, incrementalParsing, lineBreaks, math],
33453383
);
33463384

33473385
// react-markdown converts unparsed HTML nodes to text when skipHtml is false.
@@ -3363,7 +3401,7 @@ function ChatMarkdown({
33633401
remarkPlugins={remarkPlugins}
33643402
rehypePlugins={parseRawHtml ? CHAT_MARKDOWN_REHYPE_PLUGINS : undefined}
33653403
skipHtml={false}
3366-
components={CHAT_MARKDOWN_COMPONENTS}
3404+
components={math ? CHAT_MARKDOWN_MATH_COMPONENTS : CHAT_MARKDOWN_COMPONENTS}
33673405
urlTransform={markdownUrlTransform}
33683406
>
33693407
{text}
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
import { lazy, memo, Suspense } from "react";
2+
3+
import { RenderErrorBoundary } from "../RenderErrorBoundary";
4+
5+
const MathTypeset = lazy(() => import("./MathTypeset"));
6+
7+
/**
8+
* One formula from `remarkChatMath`. Shows its TeX until KaTeX loads, and
9+
* keeps showing it when KaTeX cannot parse it, such as mid-stream. Copying
10+
* any part of a formula copies its whole TeX source.
11+
*/
12+
export const MarkdownMath = memo(function MarkdownMath(props: { tex: string; display: boolean }) {
13+
const tex = props.tex.trim();
14+
const source = props.display ? `$$\n${tex}\n$$` : `$${tex}$`;
15+
const fallback = <span className="chat-markdown-math-source">{source}</span>;
16+
return (
17+
<span
18+
className={props.display ? "chat-markdown-math-display" : undefined}
19+
data-markdown-math=""
20+
data-markdown-copy={props.display ? `${source}\n\n` : source}
21+
>
22+
<RenderErrorBoundary resetKeys={[tex]} fallback={fallback}>
23+
<Suspense fallback={fallback}>
24+
<MathTypeset tex={tex} display={props.display} fallback={fallback} />
25+
</Suspense>
26+
</RenderErrorBoundary>
27+
</span>
28+
);
29+
});
Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
import katex from "katex";
2+
import "katex/dist/katex.min.css";
3+
import type { ReactNode } from "react";
4+
5+
import { LRUCache } from "../../lib/lruCache";
6+
7+
// Virtualized threads remount messages while scrolling; cached markup keeps
8+
// that from typesetting the same formulas again. "" records a parse error.
9+
const typesetCache = new LRUCache<string>(1000, 4 * 1024 * 1024);
10+
11+
function typeset(tex: string, display: boolean): string {
12+
const key = `${display ? "display" : "inline"}:${tex}`;
13+
const cached = typesetCache.get(key);
14+
if (cached !== null) return cached;
15+
let html = "";
16+
try {
17+
html = katex.renderToString(tex, {
18+
displayMode: display,
19+
output: "htmlAndMathml",
20+
throwOnError: true,
21+
// No \href, \url, \htmlClass, or other commands that emit active HTML.
22+
trust: false,
23+
strict: "ignore",
24+
maxSize: 20,
25+
maxExpand: 1000,
26+
});
27+
} catch {
28+
// Unfinished or unsupported TeX stays readable as its source.
29+
}
30+
typesetCache.set(key, html, (key.length + html.length) * 2);
31+
return html;
32+
}
33+
34+
/** KaTeX lives in this lazily loaded chunk, so it is only fetched once a formula renders. */
35+
export default function MathTypeset(props: { tex: string; display: boolean; fallback: ReactNode }) {
36+
const html = typeset(props.tex, props.display);
37+
if (!html) return props.fallback;
38+
// KaTeX escapes the TeX it renders, and `trust: false` keeps it from emitting links or attributes.
39+
return <span dangerouslySetInnerHTML={{ __html: html }} />;
40+
}

‎apps/web/src/components/settings/SettingsPanels.tsx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -540,6 +540,9 @@ export function useSettingsRestore(onRestored?: () => void) {
540540
? ["Diff colors"]
541541
: []),
542542
...(settings.chatWidth !== DEFAULT_UNIFIED_SETTINGS.chatWidth ? ["Chat width"] : []),
543+
...(settings.mathRenderingEnabled !== DEFAULT_UNIFIED_SETTINGS.mathRenderingEnabled
544+
? ["Render math"]
545+
: []),
543546
...(settings.panelAnimationDurationMs !== DEFAULT_UNIFIED_SETTINGS.panelAnimationDurationMs
544547
? ["Panel animations"]
545548
: []),
@@ -650,6 +653,7 @@ export function useSettingsRestore(onRestored?: () => void) {
650653
settings.appearanceContrast,
651654
settings.diffColorScheme,
652655
settings.chatWidth,
656+
settings.mathRenderingEnabled,
653657
settings.enableAgentBrowserAccess,
654658
settings.confirmQuit,
655659
settings.confirmThreadArchive,
@@ -762,6 +766,7 @@ export function useSettingsRestore(onRestored?: () => void) {
762766
appearanceContrast: DEFAULT_UNIFIED_SETTINGS.appearanceContrast,
763767
diffColorScheme: DEFAULT_UNIFIED_SETTINGS.diffColorScheme,
764768
chatWidth: DEFAULT_UNIFIED_SETTINGS.chatWidth,
769+
mathRenderingEnabled: DEFAULT_UNIFIED_SETTINGS.mathRenderingEnabled,
765770
timestampFormat: DEFAULT_UNIFIED_SETTINGS.timestampFormat,
766771
notificationMode: DEFAULT_UNIFIED_SETTINGS.notificationMode,
767772
inAppNotificationsEnabled: DEFAULT_UNIFIED_SETTINGS.inAppNotificationsEnabled,
@@ -1425,6 +1430,31 @@ export function AppearanceSettingsPanel() {
14251430
</div>
14261431
}
14271432
/>
1433+
<SettingsRow
1434+
{...searchableSetting("math-rendering")}
1435+
description="Typeset LaTeX math, such as $x^2$ or \[x^2\], in messages and Markdown previews. Web and desktop only."
1436+
resetAction={
1437+
settings.mathRenderingEnabled !== DEFAULT_UNIFIED_SETTINGS.mathRenderingEnabled ? (
1438+
<SettingResetButton
1439+
label="math rendering"
1440+
onClick={() =>
1441+
updateSettings({
1442+
mathRenderingEnabled: DEFAULT_UNIFIED_SETTINGS.mathRenderingEnabled,
1443+
})
1444+
}
1445+
/>
1446+
) : null
1447+
}
1448+
control={
1449+
<Switch
1450+
checked={settings.mathRenderingEnabled}
1451+
onCheckedChange={(checked) =>
1452+
updateSettings({ mathRenderingEnabled: Boolean(checked) })
1453+
}
1454+
aria-label="Render math"
1455+
/>
1456+
}
1457+
/>
14281458
</SettingsSection>
14291459

14301460
<SettingsSection id="motion" title="Motion">

‎apps/web/src/components/settings/settingsSearch.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -217,6 +217,12 @@ export const SETTINGS_SEARCH_ITEMS = [
217217
to: "/settings/appearance",
218218
searchTerms: ["wide full width column layout messages composer monitor"],
219219
},
220+
{
221+
id: "math-rendering",
222+
title: "Render math",
223+
to: "/settings/appearance",
224+
searchTerms: ["latex tex katex equations formulas markdown"],
225+
},
220226
{
221227
id: "panel-animations",
222228
title: "Panel animations",

‎apps/web/src/index.css‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1725,6 +1725,22 @@ code {
17251725
margin: 0.65rem 0;
17261726
}
17271727

1728+
/* Wide display equations scroll instead of clipping or widening the message. */
1729+
.chat-markdown .chat-markdown-math-display {
1730+
display: block;
1731+
margin: 0.65rem 0;
1732+
overflow-x: auto;
1733+
overflow-y: hidden;
1734+
}
1735+
1736+
.chat-markdown .chat-markdown-math-display .katex-display {
1737+
margin: 0;
1738+
}
1739+
1740+
.chat-markdown .chat-markdown-math-source {
1741+
white-space: pre-wrap;
1742+
}
1743+
17281744
.chat-markdown h1,
17291745
.chat-markdown h2,
17301746
.chat-markdown h3,

0 commit comments

Comments
 (0)