Add LaTeX math rendering to MarkdownPreview (#441)

apps/app/package.json

@@ -59,6 +59,7 @@
     "cronstrue": "^3.14.0",
     "jotai": "^2.19.0",
     "jotai-family": "^1.0.1",
+    "katex": "^0.16.22",
     "mermaid": "^11.15.0",
     "nanoid": "^5.1.6",
     "partysocket": "^1.1.16",
@@ -67,10 +68,12 @@
     "react-markdown": "^10.1.0",
     "react-resizable-panels": "^2.1.7",
     "react-router-dom": "^7.1.0",
+    "rehype-katex": "^7.0.1",
     "rehype-raw": "^7.0.0",
     "rehype-sanitize": "^6.0.0",
     "remark-breaks": "^4.0.0",
     "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
     "sonner": "^1.7.4",
     "sugar-high": "^1.2.1",
     "tailwind-merge": "^3.4.0",

apps/app/src/components/git-diff/PierreLineSelectionActions.tsx

@@ -95,7 +95,12 @@ function isGutterUtilityPointerEvent(
   return isGutterUtilityPath(event.nativeEvent.composedPath());
 }
 
-function isGutterUtilityPath(path: EventTarget[]): boolean {
+// `Event.composedPath()` is `EventTarget[]` under lib.dom but `[EventTarget?]`
+// once `@types/node`'s web-globals are in scope; accept both (each element is
+// re-narrowed with `instanceof Element` below).
+function isGutterUtilityPath(
+  path: readonly (EventTarget | undefined)[],
+): boolean {
   return path.some(
     (target) =>
       target instanceof Element &&

apps/app/src/components/ui/markdown-preview.stories.tsx

@@ -106,6 +106,19 @@ Long lines scroll horizontally until you toggle wrap (no language tag):
 $ pnpm exec turbo run typecheck --filter=@bb/app --filter=@bb/server --filter=@bb/host-daemon --filter=@bb/cli && echo "all packages clean"
 \`\`\``;
 
+const MATH_MARKDOWN = `Inline math sits in the prose, like the mass–energy
+relation $E = mc^2$ or the quadratic root $x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}$.
+
+Display math gets its own centered block:
+
+$$
+\\int_{-\\infty}^{\\infty} e^{-x^2} \\, dx = \\sqrt{\\pi}
+$$
+
+Escaped dollars stay literal text, so a budget line like \\$5 to \\$10 reads as
+written. Invalid TeX such as $\\frac{1}{$ surfaces a contained error instead of
+breaking the document.`;
+
 const MERMAID_MARKDOWN = `A Mermaid flowchart renders as a diagram:
 
 \`\`\`mermaid
@@ -209,6 +222,14 @@ export function Overview() {
           <MarkdownPreview content={CODE_MARKDOWN} />
         </PreviewStage>
       </StoryRow>
+      <StoryRow
+        label="math (LaTeX)"
+        hint="inline $…$ and display $$…$$ render with KaTeX; escaped \\$ stays literal; invalid TeX is contained"
+      >
+        <PreviewStage>
+          <MarkdownPreview content={MATH_MARKDOWN} />
+        </PreviewStage>
+      </StoryRow>
       <StoryRow
         label="mermaid"
         hint="fenced Mermaid blocks render as diagrams with open, zoom, pan, and source-copy controls"

apps/app/src/components/ui/markdown-preview.test.tsx

@@ -129,4 +129,53 @@ describe("MarkdownPreview", () => {
       `${window.location.protocol}//${window.location.hostname}:5173/demo`,
     );
   });
+
+  it("renders inline LaTeX math with KaTeX", () => {
+    const { container } = render(
+      <MarkdownPreview content={"Mass-energy is $E = mc^2$ exactly."} />,
+    );
+
+    expect(container.querySelector(".katex")).not.toBeNull();
+    expect(container.querySelector(".katex-display")).toBeNull();
+  });
+
+  it("renders display LaTeX math blocks with KaTeX", () => {
+    const { container } = render(
+      <MarkdownPreview content={"$$\n\\frac{1}{2} + \\frac{1}{2} = 1\n$$"} />,
+    );
+
+    expect(container.querySelector(".katex-display")).not.toBeNull();
+  });
+
+  it("leaves escaped dollar amounts as literal text", () => {
+    const { container } = render(
+      <MarkdownPreview content={"It went from \\$5 to \\$10 last week."} />,
+    );
+
+    expect(container.querySelector(".katex")).toBeNull();
+    expect(container.textContent).toContain("$5");
+    expect(container.textContent).toContain("$10");
+  });
+
+  it("renders math while still sanitizing untrusted HTML when allowHtml is set", () => {
+    const { container } = render(
+      <MarkdownPreview
+        allowHtml
+        content={"$a^2 + b^2 = c^2$\n\n<script>alert(1)</script>"}
+      />,
+    );
+
+    expect(container.querySelector(".katex")).not.toBeNull();
+    expect(container.querySelector("script")).toBeNull();
+    expect(container.textContent).not.toContain("alert(1)");
+  });
+
+  it("contains invalid TeX instead of throwing", () => {
+    const { container } = render(
+      <MarkdownPreview content={"Broken: $\\frac{1}{$ keeps rendering."} />,
+    );
+
+    expect(container.querySelector(".katex-error")).not.toBeNull();
+    expect(container.textContent).toContain("keeps rendering.");
+  });
 });

apps/app/src/components/ui/markdown-preview.tsx

@@ -16,10 +16,13 @@ import type {
   Options as ReactMarkdownOptions,
   UrlTransform,
 } from "react-markdown";
+import rehypeKatex from "rehype-katex";
 import rehypeRaw from "rehype-raw";
 import rehypeSanitize from "rehype-sanitize";
 import remarkBreaks from "remark-breaks";
 import remarkGfm from "remark-gfm";
+import remarkMath from "remark-math";
+import "katex/dist/katex.min.css";
 import { ImageLightbox } from "./image-lightbox.js";
 import { CopyButton } from "./copy-button.js";
 import { Icon } from "./icon.js";
@@ -219,13 +222,26 @@ const MARKDOWN_TABLE_BREAKOUT_WIDTH = "max(100%, min(1100px, 100cqw - 2rem))";
 const MARKDOWN_CONTENT_WIDTH_VARIABLE = "--md-content-w";
 const MARKDOWN_SOURCE_COLOR_SCHEME_MEDIA_PATTERN =
   /^\(\s*prefers-color-scheme\s*:\s*(dark|light)\s*\)$/iu;
-// Security-critical order: raw HTML must become nodes before sanitization can
-// strip unsafe elements, attributes, and URLs.
+// `remark-math` emits math as `<code class="language-math">` (inline) and
+// `<pre><code class="language-math">` (display) holding the raw TeX, and
+// `rehype-katex` renders any element carrying that class. The default sanitize
+// schema already keeps `language-*` classes on `<code>`, so the wrappers survive
+// sanitization untouched — and `rehype-katex` runs LAST, after sanitize, so KaTeX
+// (which uses `trust: false` and self-escapes its TeX input) emits its rendered
+// output without it being re-sanitized.
+//
+// Security-critical order: raw HTML must become nodes (rehypeRaw) before
+// sanitization can strip unsafe elements, attributes, and URLs.
 const MARKDOWN_HTML_REHYPE_PLUGINS: MarkdownRehypePlugins = [
   rehypeRaw,
   rehypeSanitize,
+  rehypeKatex,
 ];
 
+// No raw HTML means nothing untrusted to sanitize, so KaTeX renders straight
+// from the `remark-math` wrappers.
+const MARKDOWN_MATH_REHYPE_PLUGINS: MarkdownRehypePlugins = [rehypeKatex];
+
 function areMarkdownAbsoluteLocalFileLinkRoutingsEqual({
   next,
   previous,
@@ -1176,6 +1192,11 @@ function MarkdownPreviewComponent({
   const remarkPlugins = useMemo(
     () => [
       remarkGfm,
+      // `remark-math` with single-dollar math left ON (the default), matching
+      // GitHub: `$x$` is inline and `$$x$$` is block. The known trade-off is that
+      // a line with two unescaped `$` (e.g. "$5 to $10", "$HOME and $PATH") parses
+      // the span between them as math; authors escape a literal dollar with `\$`.
+      remarkMath,
       ...(threadMentions !== undefined || promptMentions !== undefined
         ? [remarkBreaks]
         : []),
@@ -1208,7 +1229,11 @@ function MarkdownPreviewComponent({
           <MarkdownFrontmatter source={frontmatter} />
         ) : null}
         <ReactMarkdown
-          rehypePlugins={allowHtml ? MARKDOWN_HTML_REHYPE_PLUGINS : undefined}
+          rehypePlugins={
+            allowHtml
+              ? MARKDOWN_HTML_REHYPE_PLUGINS
+              : MARKDOWN_MATH_REHYPE_PLUGINS
+          }
           remarkPlugins={remarkPlugins}
           components={markdownComponents}
           urlTransform={resolvedUrlTransform}