From 262bca335b81e40f84f79364591b913b18690d9f Mon Sep 17 00:00:00 2001
From: lxg
Date: Thu, 22 Oct 2026 11:14:02 +0800
Subject: [PATCH] fix: render LaTeX math in chat messages
- Render inline and display math with KaTeX
- Accept display delimiters that share lines with the formula
- Restore KaTeX layout after DOMPurify sanitization
- Bundle KaTeX assets and allow them in the webview CSP
---
package-lock.json | 43 +++++-
package.json | 2 +
src/extension/webview-html.test.ts | 11 ++
src/extension/webview-html.ts | 2 +-
.../components/MarkdownRenderer.test.ts | 74 +++++++++
src/webview/components/MarkdownRenderer.tsx | 145 +++++++++++++++++-
src/webview/index.css | 1 +
src/webview/index.tsx | 2 +
src/webview/styles/math.css | 15 ++
9 files changed, 287 insertions(+), 8 deletions(-)
create mode 100644 src/webview/styles/math.css
diff --git a/package-lock.json b/package-lock.json
index 9b1c21fa..21d7f8ab 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -17,7 +17,9 @@
"dompurify": "3.4.17",
"highlight.js": "11.12.0",
"jsonc-parser": "3.3.1",
+ "katex": "0.18.10",
"marked": "18.1.1",
+ "marked-katex-extension": "5.1.13",
"mermaid": "^12.2.0",
"solid-js": "^1.9.17"
},
@@ -5882,9 +5884,9 @@
}
},
"node_modules/katex": {
- "version": "0.19.0",
- "resolved": "https://registry.npmjs.org/katex/-/katex-0.19.0.tgz",
- "integrity": "sha512-v6Tznz3zJ7u3niRCoDTsumM2+HA2XXcCu+WAacCeHD2z3p9A9Ks987o5FzfTGBN0e8A0vjEgIDvLbICrXpdw/Q==",
+ "version": "0.18.10",
+ "resolved": "https://registry.npmjs.org/katex/-/katex-0.18.10.tgz",
+ "integrity": "sha512-/B6p9eY9DX7aHBfpkHdpirDTZ5QH9xTwL9y837PWuzuv41O5jFdqNQwVQEQsimY0/iVNkwBY4+4hMfhQ7d4Dbw==",
"funding": [
"https://opencollective.com/katex",
"https://github.com/sponsors/katex"
@@ -6280,6 +6282,16 @@
"node": ">= 20"
}
},
+ "node_modules/marked-katex-extension": {
+ "version": "5.1.13",
+ "resolved": "https://registry.npmjs.org/marked-katex-extension/-/marked-katex-extension-5.1.13.tgz",
+ "integrity": "sha512-+6gVygGg5at9g+YsuIQZk7XcAc6Pg1P0grEJKEWvF7DAwceZ7ZIvU0fhQe6auUqSbnPmSjJxZuICdSCdbGaFRw==",
+ "license": "MIT",
+ "peerDependencies": {
+ "katex": ">=0.16 <0.19",
+ "marked": ">=4 <19"
+ }
+ },
"node_modules/material-icon-theme": {
"version": "5.39.0",
"resolved": "https://registry.npmjs.org/material-icon-theme/-/material-icon-theme-5.39.0.tgz",
@@ -6363,6 +6375,31 @@
"node": ">=22.12.0"
}
},
+ "node_modules/mermaid/node_modules/commander": {
+ "version": "15.0.0",
+ "resolved": "https://registry.npmjs.org/commander/-/commander-15.0.0.tgz",
+ "integrity": "sha512-z67u4ZhzCL/Tydu1lJARtEZYWbWaN7oYLHbsuzocr6y4N6WZAagG3RQ4FW61V1/0+jImpj293XfrcYnd1qxtPg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=22.12.0"
+ }
+ },
+ "node_modules/mermaid/node_modules/katex": {
+ "version": "0.19.0",
+ "resolved": "https://registry.npmjs.org/katex/-/katex-0.19.0.tgz",
+ "integrity": "sha512-v6Tznz3zJ7u3niRCoDTsumM2+HA2XXcCu+WAacCeHD2z3p9A9Ks987o5FzfTGBN0e8A0vjEgIDvLbICrXpdw/Q==",
+ "funding": [
+ "https://opencollective.com/katex",
+ "https://github.com/sponsors/katex"
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "commander": "^15.0.0"
+ },
+ "bin": {
+ "katex": "cli.js"
+ }
+ },
"node_modules/mermaid/node_modules/marked": {
"version": "16.4.2",
"resolved": "https://registry.npmjs.org/marked/-/marked-16.4.2.tgz",
diff --git a/package.json b/package.json
index e7ebf88d..ff7a3bba 100644
--- a/package.json
+++ b/package.json
@@ -94,7 +94,9 @@
"dompurify": "3.4.17",
"highlight.js": "11.12.0",
"jsonc-parser": "3.3.1",
+ "katex": "0.18.10",
"marked": "18.1.1",
+ "marked-katex-extension": "5.1.13",
"mermaid": "^12.2.0",
"solid-js": "^1.9.17"
},
diff --git a/src/extension/webview-html.test.ts b/src/extension/webview-html.test.ts
index ab085b25..2274645f 100644
--- a/src/extension/webview-html.test.ts
+++ b/src/extension/webview-html.test.ts
@@ -220,6 +220,17 @@ describe('renderWebviewHtml', () => {
expect(imgSrc).toBe('vscode-webview-resource: data:');
});
+ it('allows bundled KaTeX fonts from the webview resource source', () => {
+ const html = renderWebviewHtml('vscode-webview-resource:', initialState, {
+ scriptUri: 'webview.js',
+ cssUri: 'webview.css',
+ version: 'fixed-cache-key',
+ });
+ const fontSrc = html.match(/font-src ([^;]+);/)?.[1];
+
+ expect(fontSrc).toBe('vscode-webview-resource: data:');
+ });
+
it('allows module chunks only from the webview resource source', () => {
const html = renderWebviewHtml('vscode-webview-resource:', initialState, {
scriptUri: 'webview.js',
diff --git a/src/extension/webview-html.ts b/src/extension/webview-html.ts
index 8565e761..b5023e75 100644
--- a/src/extension/webview-html.ts
+++ b/src/extension/webview-html.ts
@@ -146,7 +146,7 @@ export function renderWebviewHtml(
+ content="default-src 'none'; img-src ${cspSource} data:; script-src 'nonce-${nonce}' ${cspSource}; worker-src blob:; connect-src ${cspSource}; style-src 'unsafe-inline' ${cspSource}; font-src ${cspSource} data:;" />
Varro
${logoPreload}
${modulePreloads}
diff --git a/src/webview/components/MarkdownRenderer.test.ts b/src/webview/components/MarkdownRenderer.test.ts
index f2711b57..b495da17 100644
--- a/src/webview/components/MarkdownRenderer.test.ts
+++ b/src/webview/components/MarkdownRenderer.test.ts
@@ -481,6 +481,80 @@ describe('MarkdownRenderer', () => {
expect(mounted).not.toHaveBeenCalled();
});
+ it('renders inline and display LaTeX with KaTeX', () => {
+ const html = __parseMarkdownForTests(
+ [
+ 'Inline: $\\mathcal{N}(\\mu_t^{(p)},\\Sigma_t^{(p)})$',
+ '',
+ '$$',
+ '\\hat\\mu_t^{(p)}=A_t^{(p)}\\mu_t^{(p)}+b_t^{(p)},\\qquad',
+ '\\hat\\Sigma_t^{(p)}=A_t^{(p)}\\Sigma_t^{(p)}(A_t^{(p)})^\\top',
+ '$$',
+ ].join('\n'),
+ { cacheByContent: false }
+ );
+ const root = document.createElement('div');
+ root.innerHTML = html;
+
+ expect(root.querySelectorAll('.katex')).toHaveLength(2);
+ expect(root.querySelector('.katex-display')).not.toBeNull();
+ expect(root.querySelector('.katex-html [style]')).not.toBeNull();
+ expect(root.querySelector('.katex-error')).toBeNull();
+ });
+
+ it('renders display math when delimiters share lines with the formula', () => {
+ const html = __parseMarkdownForTests(
+ [
+ '然后按逆协方差加权融合:',
+ '',
+ '$$\\mu_t=\\Sigma_t\\sum_{p}',
+ '(\\hat\\Sigma_t^{(p)})^{-1}\\hat\\mu_t^{(p)},\\qquad',
+ '\\Sigma_t=\\Big(\\sum_{p}(\\hat\\Sigma_t^{(p)})^{-1}\\Big)^{-1}$$',
+ ].join('\n'),
+ { cacheByContent: false }
+ );
+ const root = document.createElement('div');
+ root.innerHTML = html;
+
+ expect(root.querySelector('.katex-display')).not.toBeNull();
+ expect(root.querySelector('.katex-html [style]')).not.toBeNull();
+ expect(root.querySelector('.katex-error')).toBeNull();
+ });
+
+ it('keeps LaTeX literal inside code spans and fenced code blocks', () => {
+ const html = __parseMarkdownForTests(
+ ['Inline code: `$x^2$`', '', '```text', '$y^2$', '```'].join('\n'),
+ { cacheByContent: false }
+ );
+ const root = document.createElement('div');
+ root.innerHTML = html;
+
+ expect(root.querySelector('.katex')).toBeNull();
+ expect(root.querySelector('code')?.textContent).toBe('$x^2$');
+ expect(root.querySelector('pre')?.textContent).toContain('$y^2$');
+ });
+
+ it('does not treat currency amounts as math', () => {
+ const html = __parseMarkdownForTests('It costs $5 and $10.', { cacheByContent: false });
+ const root = document.createElement('div');
+ root.innerHTML = html;
+
+ expect(root.querySelector('.katex')).toBeNull();
+ expect(root.textContent?.trim()).toBe('It costs $5 and $10.');
+ });
+
+ it('renders math followed by CJK punctuation', () => {
+ const html = __parseMarkdownForTests(
+ '查询出 $\\mathcal{N}(\\mu_t^{(p)},\\Sigma_t^{(p)})$,再变换回全局:',
+ { cacheByContent: false }
+ );
+ const root = document.createElement('div');
+ root.innerHTML = html;
+
+ expect(root.querySelector('.katex')).not.toBeNull();
+ expect(root.querySelector('.katex-error')).toBeNull();
+ });
+
it('renders indented text as prose while preserving fenced code blocks', () => {
const indentedHtml = __parseMarkdownForTests(
'Failure details\n\n Error: expected 37\n Received: 36.71875',
diff --git a/src/webview/components/MarkdownRenderer.tsx b/src/webview/components/MarkdownRenderer.tsx
index 6ab39801..a9f77e4e 100644
--- a/src/webview/components/MarkdownRenderer.tsx
+++ b/src/webview/components/MarkdownRenderer.tsx
@@ -2,7 +2,9 @@ import { Show, createSignal, createEffect, createMemo, onMount, onCleanup } from
import type { JSX } from 'solid-js';
import { Portal, render } from 'solid-js/web';
import DOMPurify from 'dompurify';
+import { renderToString as renderKatex } from 'katex';
import { marked, Tokenizer } from 'marked';
+import markedKatex from 'marked-katex-extension';
import type { Token, Tokens } from 'marked';
import type { Mermaid, MermaidConfig } from 'mermaid';
import { writeClipboard } from '../lib/write-clipboard';
@@ -188,6 +190,84 @@ const ALLOWED_HTML_ATTRIBUTES = [
'y1',
'y2',
];
+const KATEX_HTML_TAGS = [
+ 'annotation',
+ 'annotation-xml',
+ 'math',
+ 'menclose',
+ 'merror',
+ 'mfrac',
+ 'mi',
+ 'mmultiscripts',
+ 'mn',
+ 'mo',
+ 'mover',
+ 'mpadded',
+ 'mphantom',
+ 'mprescripts',
+ 'mrow',
+ 'mroot',
+ 'ms',
+ 'mspace',
+ 'msqrt',
+ 'mstyle',
+ 'msub',
+ 'msubsup',
+ 'msup',
+ 'mtable',
+ 'mtd',
+ 'mtext',
+ 'mtr',
+ 'munder',
+ 'munderover',
+ 'none',
+ 'semantics',
+];
+const KATEX_HTML_ATTRIBUTES = [
+ 'accent',
+ 'accentunder',
+ 'align',
+ 'bevelled',
+ 'columnlines',
+ 'columnalign',
+ 'columnspacing',
+ 'columnspan',
+ 'display',
+ 'displaystyle',
+ 'encoding',
+ 'equalcolumns',
+ 'equalrows',
+ 'frame',
+ 'framespacing',
+ 'linethickness',
+ 'lspace',
+ 'mathvariant',
+ 'maxsize',
+ 'minsize',
+ 'movablelimits',
+ 'notation',
+ 'preserveAspectRatio',
+ 'rowalign',
+ 'rowlines',
+ 'rowspacing',
+ 'rowspan',
+ 'rspace',
+ 'scriptlevel',
+ 'separator',
+ 'stretchy',
+ 'symmetric',
+ 'voffset',
+ 'xmlns',
+];
+const KATEX_RENDER_OPTIONS = {
+ throwOnError: false,
+ strict: 'ignore',
+ trust: false,
+ output: 'htmlAndMathml',
+} as const;
+// Models commonly emit display math as "$$first line\nlast line$$" instead of
+// placing the delimiters on their own lines. Match that form at block level.
+const DISPLAY_MATH_BLOCK_RE = /^\$\$[ \t]*\n?([\s\S]+?)\$\$(?=\n|$)/;
const MAX_COPY_TEXT_LENGTH = 20_000;
const MAX_MERMAID_SOURCE_LENGTH = 100_000;
const MERMAID_SVG_CACHE_LIMIT = 20;
@@ -572,6 +652,30 @@ marked.setOptions({
gfm: true,
breaks: false,
});
+marked.use(markedKatex(KATEX_RENDER_OPTIONS));
+marked.use({
+ extensions: [
+ {
+ name: 'displayKatexBlock',
+ level: 'block',
+ tokenizer(src) {
+ const match = DISPLAY_MATH_BLOCK_RE.exec(src);
+ if (!match) return undefined;
+ const text = match[1]?.trim();
+ if (!text) return undefined;
+ return {
+ type: 'displayKatexBlock',
+ raw: match[0],
+ text,
+ };
+ },
+ renderer(token) {
+ const text = getString(token.text);
+ return text ? `${renderKatex(text, { ...KATEX_RENDER_OPTIONS, displayMode: true })}\n` : '';
+ },
+ },
+ ],
+});
const PATH_SEPARATOR_SOURCE = String.raw`[\\/]`;
const PATH_SEGMENT_CHARS_SOURCE = String.raw`[\w.@+-]`;
@@ -746,7 +850,7 @@ function linkifySessionReferences(fragment: DocumentFragment) {
// SAFETY: The surrounding shape or discriminator check establishes the Text contract used below.
const node = walker.currentNode as Text;
const parent = node.parentElement;
- if (!parent || parent.closest('a, button, code, pre')) continue;
+ if (!parent || parent.closest('a, button, code, pre, .katex')) continue;
textNodes.push(node);
}
@@ -793,6 +897,33 @@ function linkifySessionReferences(fragment: DocumentFragment) {
}
}
+function rehydrateKatexMath(fragment: DocumentFragment) {
+ for (const element of Array.from(fragment.querySelectorAll('.katex'))) {
+ const annotation = element.querySelector('annotation[encoding="application/x-tex"]');
+ const tex = annotation?.textContent;
+ if (!tex) continue;
+
+ const displayMode =
+ element.closest('.katex-display') !== null ||
+ element.querySelector('math[display="block"]') !== null;
+ const rendered = renderKatex(tex, {
+ displayMode,
+ throwOnError: false,
+ strict: 'ignore',
+ trust: false,
+ output: 'htmlAndMathml',
+ });
+ const template = document.createElement('template');
+ template.innerHTML = rendered;
+ const wrapper = template.content.firstElementChild;
+ const replacement =
+ displayMode && wrapper?.classList.contains('katex-display')
+ ? wrapper.querySelector('.katex')
+ : wrapper;
+ if (replacement) element.replaceWith(replacement);
+ }
+}
+
function sanitizeHtml(
html: string,
disableCache: boolean,
@@ -810,13 +941,19 @@ function sanitizeHtml(
// second time, which is where mutation-XSS lives. Mutating the fragment
// DOMPurify vetted keeps a single parse/serialize round trip.
const fragment = DOMPurify.sanitize(html, {
- ALLOWED_TAGS: ALLOWED_HTML_TAGS,
- ALLOWED_ATTR: ALLOWED_HTML_ATTRIBUTES,
+ ALLOWED_TAGS: [...ALLOWED_HTML_TAGS, ...KATEX_HTML_TAGS],
+ ALLOWED_ATTR: [...ALLOWED_HTML_ATTRIBUTES, ...KATEX_HTML_ATTRIBUTES],
ALLOW_DATA_ATTR: false,
FORBID_ATTR: ['style'],
RETURN_DOM_FRAGMENT: true,
});
+ // DOMPurify removes the inline styles KaTeX needs for layout. Re-render each
+ // formula from its (sanitized) TeX annotation after sanitization so the
+ // trusted KaTeX markup keeps its positioning without allowing model-authored
+ // style attributes through the general Markdown sanitizer.
+ rehydrateKatexMath(fragment);
+
const privateSelector = PRIVATE_RENDERER_ATTRIBUTES.map((name) => `[${name}]`).join(',');
for (const element of Array.from(fragment.querySelectorAll(privateSelector))) {
if (element.hasAttribute(TRUSTED_RENDERER_ATTRIBUTE)) continue;
@@ -1518,7 +1655,7 @@ function linkifyPaths(fragment: DocumentFragment) {
if (
!parent ||
parent.closest(
- 'a, button, code, pre, svg, .interactive-result-code-block, .mermaid-diagram, .markdown-task-checkbox, .markdown-inline-slot'
+ 'a, button, code, pre, svg, .katex, .interactive-result-code-block, .mermaid-diagram, .markdown-task-checkbox, .markdown-inline-slot'
)
) {
continue;
diff --git a/src/webview/index.css b/src/webview/index.css
index 256c1a83..6f96ec09 100644
--- a/src/webview/index.css
+++ b/src/webview/index.css
@@ -7,6 +7,7 @@
@import './styles/base.css';
@import './styles/chat-shell.css' layer(components);
@import './styles/messages.css' layer(components);
+@import './styles/math.css' layer(components);
@import './styles/composer.css' layer(components);
@import './styles/tool-calls.css' layer(components);
@import './styles/menus.css' layer(components);
diff --git a/src/webview/index.tsx b/src/webview/index.tsx
index 6159d93a..d7fa3443 100644
--- a/src/webview/index.tsx
+++ b/src/webview/index.tsx
@@ -4,6 +4,8 @@ import { AppRoot } from './App';
import { cleanupBridge, initializeBridge, postMessage } from './lib/bridge';
// oxlint-disable-next-line no-unassigned-import
import './index.css';
+// oxlint-disable-next-line no-unassigned-import
+import 'katex/dist/katex.min.css';
import { applyChatFontConfig } from './lib/chat-font-config';
import { isFunction } from './lib/runtime-values';
import { readInitialWebviewState } from './lib/state-stored-values';
diff --git a/src/webview/styles/math.css b/src/webview/styles/math.css
new file mode 100644
index 00000000..7085a0ac
--- /dev/null
+++ b/src/webview/styles/math.css
@@ -0,0 +1,15 @@
+/* Display math can exceed the chat column on narrow views. Keep the formula
+ centered when it fits and scrollable instead of clipping it when it does not. */
+.katex-display {
+ max-width: 100%;
+ overflow-x: auto;
+ overflow-y: hidden;
+}
+
+.katex-display > .katex {
+ max-width: none;
+}
+
+.katex {
+ color: inherit;
+}