feat(markdown): add KaTeX math rendering via Streamdown plugin API (#156)

Signed-off-by: Logan Nguyen <lg.131.dev@gmail.com>

Author: quiet-node

bun.lock

@@ -42,8 +42,11 @@
     "@fontsource/source-serif-4": "^5.2.9",
     "@tauri-apps/api": "^2.11.0",
     "framer-motion": "^12.38.0",
+    "katex": "^0.16.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
+    "rehype-katex": "^7.0.1",
+    "remark-math": "^6.0.0",
     "streamdown": "^2.5.0"
   },
   "overrides": {

package.json

@@ -1,6 +1,7 @@
 @import 'tailwindcss';
 @source "../node_modules/streamdown/dist";
 @import 'streamdown/styles.css';
+@import 'katex/dist/katex.min.css';
 
 /* Source Serif 4 reading face for AI prose. Chrome stays Inter. */
 @import '@fontsource/source-serif-4/400.css';

src/App.css

@@ -1,5 +1,7 @@
 import React, { memo } from 'react';
-import { Streamdown } from 'streamdown';
+import { Streamdown, type MathPlugin } from 'streamdown';
+import remarkMath from 'remark-math';
+import rehypeKatex from 'rehype-katex';
 
 interface MarkdownRendererProps {
   content: string;
@@ -8,6 +10,13 @@ interface MarkdownRendererProps {
   isStreaming?: boolean;
 }
 
+const mathPlugin: MathPlugin = {
+  name: 'katex',
+  type: 'math',
+  remarkPlugin: remarkMath,
+  rehypePlugin: rehypeKatex,
+};
+
 /**
  * Renders markdown content using Streamdown, a streaming-aware markdown
  * renderer that handles incomplete syntax and memoizes completed blocks.
@@ -22,6 +31,10 @@ interface MarkdownRendererProps {
  * then sanitized, stripping script tags, event handlers, iframes, and
  * javascript: URLs. Link safety is disabled so links render as native
  * anchor elements with target="_blank" and rel="noopener noreferrer".
+ * KaTeX is appended after rehype-sanitize in Streamdown's pipeline and
+ * is therefore not covered by the allowlist. XSS safety for math content
+ * relies on KaTeX's own output escaping and the default trust:false setting,
+ * which blocks arbitrary-HTML LaTeX macros such as \href and \htmlClass.
  *
  * Memoized to skip re-renders when props are unchanged, which matters
  * during LLM token streaming where sibling bubbles would otherwise
@@ -47,6 +60,7 @@ export const MarkdownRenderer: React.FC<MarkdownRendererProps> = memo(
              In a Tauri app the webview opens external links in the system
              browser, making the modal unnecessary friction. */
           linkSafety={{ enabled: false }}
+          plugins={{ math: mathPlugin }}
         >
           {content}
         </Streamdown>

src/components/MarkdownRenderer.tsx

@@ -190,6 +190,68 @@ describe('MarkdownRenderer', () => {
     });
   });
 
+  describe('Math rendering', () => {
+    it('renders display math blocks via KaTeX', () => {
+      const { container } = render(
+        <MarkdownRenderer content={'$$x = \\frac{-b}{2a}$$'} />,
+      );
+      expect(container.querySelector('.katex')).not.toBeNull();
+      expect(container.textContent).not.toContain('$$');
+    });
+
+    it('renders inline math via KaTeX', () => {
+      const { container } = render(
+        <MarkdownRenderer content={'Energy is $E = mc^2$ at rest'} />,
+      );
+      expect(container.querySelector('.katex')).not.toBeNull();
+      expect(container.textContent).not.toContain('$E = mc^2$');
+    });
+
+    it('does not render raw LaTeX source as plain text', () => {
+      const { container } = render(
+        <MarkdownRenderer content={'$$\\sum_{i=0}^{n} i$$'} />,
+      );
+      expect(container.querySelector('.katex')).not.toBeNull();
+      // MathML <annotation> always contains the raw LaTeX source for
+      // accessibility; check only the visible katex-html portion.
+      const katexHtml = container.querySelector('.katex-html');
+      expect(katexHtml).not.toBeNull();
+      expect(katexHtml!.textContent).not.toContain('\\sum');
+    });
+
+    it('preserves XSS protection alongside math rendering', () => {
+      const { container } = render(
+        <MarkdownRenderer
+          content={'$E = mc^2$\n\n<script>alert("xss")</script>'}
+        />,
+      );
+      expect(container.querySelector('.katex')).not.toBeNull();
+      expect(container.querySelector('script')).toBeNull();
+      expect(container.innerHTML).not.toContain('<script');
+    });
+
+    it('blocks javascript: URLs in LaTeX \\href via trust:false', () => {
+      const { container } = render(
+        <MarkdownRenderer content={'$\\href{javascript:alert(1)}{click}$'} />,
+      );
+      // trust:false renders \href as a red error span, not a clickable link.
+      // MathML <annotation> contains raw source as non-executable text;
+      // check only the visible katex-html portion for any live href.
+      const katexHtml = container.querySelector('.katex-html');
+      expect(katexHtml).not.toBeNull();
+      expect(katexHtml!.innerHTML).not.toMatch(/javascript:/i);
+      expect(container.querySelector('a[href]')).toBeNull();
+    });
+
+    it('renders math in streaming mode without leaking raw LaTeX', () => {
+      const { container } = render(
+        <MarkdownRenderer content={'$$E = mc^2$$'} isStreaming={true} />,
+      );
+      expect(container.querySelector('.katex')).not.toBeNull();
+      expect(container.textContent).not.toContain('$$');
+    });
+  });
+
   describe('Edge cases', () => {
     it('handles empty string', () => {
       const { container } = render(<MarkdownRenderer content="" />);