From 1a8ac63aa3ec2365a77b06a15d65d955ec93bd76 Mon Sep 17 00:00:00 2001
From: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com>
Date: Thu, 10 Sep 2026 21:44:15 -0700
Subject: [PATCH 1/3] perf(web): reuse completed Markdown prefixes while
 streaming

---
 apps/web/package.json                      |   2 +
 apps/web/src/components/ChatMarkdown.tsx   |   8 +-
 apps/web/src/markdown-incremental.test.tsx | 112 +++++++++++++++++++++
 apps/web/src/markdown-incremental.ts       |  98 ++++++++++++++++++
 pnpm-lock.yaml                             |   6 ++
 5 files changed, 225 insertions(+), 1 deletion(-)
 create mode 100644 apps/web/src/markdown-incremental.test.tsx
 create mode 100644 apps/web/src/markdown-incremental.ts

diff --git a/apps/web/package.json b/apps/web/package.json
index c2ce73b42b11..069a222ca122 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -59,6 +59,7 @@
     "@types/babel__core": "^7.20.5",
     "@types/compression": "^1.8.1",
     "@types/culori": "^4.0.1",
+    "@types/mdast": "^4.0.4",
     "@types/react": "~19.2.14",
     "@types/react-dom": "~19.2.3",
     "@types/react-test-renderer": "19.1.0",
@@ -68,6 +69,7 @@
     "compression": "^1.8.1",
     "react-test-renderer": "19.2.6",
     "tailwindcss": "^4.0.0",
+    "unified": "^11.0.5",
     "vite": "catalog:",
     "vite-plus": "catalog:"
   }
diff --git a/apps/web/src/components/ChatMarkdown.tsx b/apps/web/src/components/ChatMarkdown.tsx
index 192abaf385f7..88d34b8d58bc 100644
--- a/apps/web/src/components/ChatMarkdown.tsx
+++ b/apps/web/src/components/ChatMarkdown.tsx
@@ -69,6 +69,7 @@ import React, {
 } from "react";
 import type { Components, Options as ReactMarkdownOptions } from "react-markdown";
 import ReactMarkdown from "react-markdown";
+import { createIncrementalMarkdownPlugin } from "../markdown-incremental";
 import { defaultUrlTransform } from "react-markdown";
 import rehypeRaw from "rehype-raw";
 import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
@@ -3104,12 +3105,17 @@ function ChatMarkdown({
     localMediaPreview,
     setLocalMediaPreview,
   } = useChatMarkdownState({ text, ...props });
+  const incrementalParsing =
+    props.isStreaming === true &&
+    extraRemarkPlugins.length === 0 &&
+    /(?:^|\n) {0,3}(?:`{3}|~{3})/.test(text);
   const remarkPlugins = useMemo(
     () => [
       ...(lineBreaks ? CHAT_MARKDOWN_REMARK_PLUGINS_WITH_BREAKS : CHAT_MARKDOWN_REMARK_PLUGINS),
       ...extraRemarkPlugins,
+      ...(incrementalParsing ? [createIncrementalMarkdownPlugin()] : []),
     ],
-    [extraRemarkPlugins, lineBreaks],
+    [extraRemarkPlugins, incrementalParsing, lineBreaks],
   );
 
   // react-markdown converts unparsed HTML nodes to text when skipHtml is false.
diff --git a/apps/web/src/markdown-incremental.test.tsx b/apps/web/src/markdown-incremental.test.tsx
new file mode 100644
index 000000000000..9611e60cbb17
--- /dev/null
+++ b/apps/web/src/markdown-incremental.test.tsx
@@ -0,0 +1,112 @@
+import type { Root } from "mdast";
+import { renderToStaticMarkup } from "react-dom/server";
+import ReactMarkdown from "react-markdown";
+import rehypeRaw from "rehype-raw";
+import rehypeSanitize from "rehype-sanitize";
+import remarkGfm from "remark-gfm";
+import type { Plugin } from "unified";
+import { describe, expect, it } from "vite-plus/test";
+
+import { remarkCodexDirectives } from "@t3tools/client-runtime/codex-markdown-directives";
+import { remarkGithubAlerts } from "./markdown-github-alerts";
+import { createIncrementalMarkdownPlugin } from "./markdown-incremental";
+import { remarkNormalizeListItemIndentation } from "./markdown-list-indentation";
+
+function render(source: string, incremental?: Plugin<[], Root>) {
+  let tree: Root | undefined;
+  const capture: Plugin<[], Root> = () => (root) => {
+    tree = structuredClone(root);
+  };
+  const html = renderToStaticMarkup(
+    <ReactMarkdown
+      remarkPlugins={[
+        capture,
+        remarkGfm,
+        remarkGithubAlerts,
+        remarkNormalizeListItemIndentation,
+        remarkCodexDirectives,
+        ...(incremental ? [incremental] : []),
+      ]}
+      rehypePlugins={[rehypeRaw, rehypeSanitize]}
+    >
+      {source}
+    </ReactMarkdown>,
+  );
+  return { html, tree };
+}
+
+const prefix = "# Before\n\n```ts\nconst values = [1, 2];\n```\n\n";
+
+describe("incremental Markdown parsing", () => {
+  it.each([
+    "a\n===\n\nb\n---\n",
+    "- first\n\n  continued\n\n- next\n",
+    "> quoted\n>\n> ```js\n> abc\n> ```\n\nend",
+    "<div>\nhello\n\n</div>\n\nend",
+    "[ref]\n\n[ref]: /later",
+    "a[^x]\n\n[^x]: note",
+    "a | b\n--|--\na | b\n",
+    "```\na\n```\n\nnext\n\n~~~\nb\n~~~\n\nmore",
+    "\n\n\tcode\n\nmore",
+    "text <https://example.com> *bold*",
+    "> [!NOTE]\n> alert\n\n- [ ] task",
+    "\uFEFFtext after a byte-order mark",
+  ])("preserves the parse tree, positions, and HTML while streaming %j", (tail) => {
+    const source = prefix + tail;
+    const incremental = createIncrementalMarkdownPlugin();
+    for (let end = 0; end <= source.length; end++) {
+      const text = source.slice(0, end);
+      expect(render(text, incremental), `prefix ${end}`).toEqual(render(text));
+    }
+  });
+
+  it.each(["\r\n", "\r"])("preserves partial %j line endings", (newline) => {
+    const source = (prefix + "next\n\n```\nlast\n```\n\nend").replaceAll("\n", newline);
+    const incremental = createIncrementalMarkdownPlugin();
+    for (let end = 0; end <= source.length; end++) {
+      const text = source.slice(0, end);
+      expect(render(text, incremental)).toEqual(render(text));
+    }
+  });
+
+  it("updates earlier references when definitions arrive after the cached prefix", () => {
+    const before = "[later] and footnote[^note]\n\n" + prefix;
+    const incremental = createIncrementalMarkdownPlugin();
+    for (const tail of ["text", "[later]: /target", "[later]: /target\n\n[^note]: a note"]) {
+      expect(render(before + tail, incremental)).toEqual(render(before + tail));
+    }
+  });
+
+  it("handles edits, replacements, and repeated renders without leaking transformed nodes", () => {
+    const incremental = createIncrementalMarkdownPlugin();
+    const documents = [
+      prefix + "- first\n - second",
+      prefix + "> [!NOTE]\n> transformed alert",
+      prefix + "plain text",
+      "replacement without fences",
+      prefix.replace("Before", "Edited") + "edited prefix",
+      prefix + "plain text",
+      prefix + "plain text",
+    ];
+    for (const document of documents) {
+      expect(render(document, incremental)).toEqual(render(document));
+    }
+  });
+
+  it("does not freeze unclosed, nested, indented, or mismatched fences", () => {
+    const prefixes = [
+      "```\nopen\n\n",
+      "````\n```\n\n",
+      "> ```\n> code\n> ```\n\n",
+      "- ```\n  code\n  ```\n\n",
+      "    ```\n    code\n    ```\n\n",
+      "<script>\n```\ncode\n```\n\n",
+    ];
+    for (const start of prefixes) {
+      const incremental = createIncrementalMarkdownPlugin();
+      for (const tail of ["", "text", "\n```\n", "\n```\n\nnext"]) {
+        expect(render(start + tail, incremental)).toEqual(render(start + tail));
+      }
+    }
+  });
+});
diff --git a/apps/web/src/markdown-incremental.ts b/apps/web/src/markdown-incremental.ts
new file mode 100644
index 000000000000..df6395a372e9
--- /dev/null
+++ b/apps/web/src/markdown-incremental.ts
@@ -0,0 +1,98 @@
+import type { Root, RootContent } from "mdast";
+import type { Parser as UnifiedParser, Plugin } from "unified";
+
+type Parser = UnifiedParser<Root>;
+
+interface ParsedPrefix {
+  source: string;
+  offset: number;
+  line: number;
+  children: RootContent[];
+}
+
+function hasDefinitions(node: Root | RootContent): boolean {
+  return (
+    node.type === "definition" ||
+    node.type === "footnoteDefinition" ||
+    ("children" in node && node.children.some((child) => hasDefinitions(child)))
+  );
+}
+
+function shiftPositions(node: Root | RootContent, offset: number, lines: number): void {
+  if (node.position) {
+    for (const point of [node.position.start, node.position.end]) {
+      if (point.offset !== undefined) point.offset += offset;
+      point.line += lines;
+    }
+  }
+  if ("children" in node) {
+    for (const child of node.children) shiftPositions(child, offset, lines);
+  }
+}
+
+/** Keep the full document pipeline while avoiding parsing a completed code-heavy
+ * prefix on every token. A closed top-level fence followed by a blank line is a
+ * parsing boundary. Definitions are document-wide, so they require a full parse.
+ */
+export function createIncrementalMarkdownParser(parse: Parser): Parser {
+  let cached: ParsedPrefix | undefined;
+
+  return (source, file) => {
+    // A streaming CR can become half of a CRLF. A BOM at the suffix boundary
+    // would be stripped by a new parser although it is inside the full document.
+    if (source.includes("\r") || source.includes("\uFEFF")) return parse(source, file);
+
+    const prefix = cached && source.startsWith(cached.source) ? cached : undefined;
+    let root: Root;
+    if (prefix) {
+      root = parse(source.slice(prefix.offset), file);
+      if (hasDefinitions(root)) return parse(source, file);
+      shiftPositions(root, prefix.offset, prefix.line - 1);
+      if (root.position) root.position.start = { line: 1, column: 1, offset: 0 };
+      // Remark transforms mutate their input. The cache owns pristine nodes and
+      // each render receives its own copy, including source positions.
+      root.children.unshift(...structuredClone(prefix.children));
+    } else {
+      root = parse(source, file);
+      if (hasDefinitions(root)) return root;
+    }
+
+    for (let index = root.children.length - 1; index >= 0; index--) {
+      const node = root.children[index];
+      if (node?.type !== "code") continue;
+      const start = node.position?.start.offset;
+      const end = node.position?.end.offset;
+      if (start === undefined || end === undefined) continue;
+      if (prefix && end < prefix.offset) break;
+      const value = source.slice(start, end);
+      const opening = /^ {0,3}(`{3,}|~{3,})[^\n]*\n/.exec(value)?.[1];
+      if (!opening) continue;
+      const lastLine = value.slice(value.lastIndexOf("\n") + 1);
+      const closing = new RegExp(`^ {0,3}${opening[0]}{${opening.length},}[ \\t]*$`);
+      const separator = /^\n[ \t]*\n/.exec(source.slice(end))?.[0];
+      if (!closing.test(lastLine) || !separator) continue;
+      const offset = end + separator.length;
+      cached = {
+        source: source.slice(0, offset),
+        offset,
+        line: node.position!.end.line + 2,
+        children: structuredClone(root.children.slice(0, index + 1)),
+      };
+      break;
+    }
+    return root;
+  };
+}
+
+/** One cache per streaming renderer. Extra syntax plugins must use the normal
+ * parser because their document-wide dependencies are not known here.
+ */
+export function createIncrementalMarkdownPlugin(): Plugin<[], Root> {
+  let parser: Parser | undefined;
+  return function () {
+    const original = this.parser;
+    if (!original) return;
+    parser ??= createIncrementalMarkdownParser((source, file) => original(source, file) as Root);
+    this.parser = parser;
+  };
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2cba4e1a8771..704437983bac 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -707,6 +707,9 @@ importers:
       '@types/culori':
         specifier: ^4.0.1
         version: 4.0.1
+      '@types/mdast':
+        specifier: ^4.0.4
+        version: 4.0.4
       '@types/react':
         specifier: ~19.2.14
         version: 19.2.16
@@ -734,6 +737,9 @@ importers:
       tailwindcss:
         specifier: 4.3.3
         version: 4.3.3
+      unified:
+        specifier: ^11.0.5
+        version: 11.0.5
       vite:
         specifier: npm:@voidzero-dev/vite-plus-core@0.3.0
         version: '@voidzero-dev/vite-plus-core@0.3.0(@types/node@24.12.4)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.48.0)(typescript@7.0.2)(unrun@0.2.39)(yaml@2.9.0)'

From acacd586bdc66e97ebe977aa9fe38f1bcd415389 Mon Sep 17 00:00:00 2001
From: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com>
Date: Thu, 10 Sep 2026 21:57:48 -0700
Subject: [PATCH 2/3] fix(web): keep Markdown recovery parses out of the stream
 cache

---
 apps/web/src/markdown-incremental.test.tsx | 26 +++++++++++++++++++++-
 apps/web/src/markdown-incremental.ts       | 11 ++++++++-
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/apps/web/src/markdown-incremental.test.tsx b/apps/web/src/markdown-incremental.test.tsx
index 9611e60cbb17..cf06355f3b49 100644
--- a/apps/web/src/markdown-incremental.test.tsx
+++ b/apps/web/src/markdown-incremental.test.tsx
@@ -12,14 +12,24 @@ import { remarkGithubAlerts } from "./markdown-github-alerts";
 import { createIncrementalMarkdownPlugin } from "./markdown-incremental";
 import { remarkNormalizeListItemIndentation } from "./markdown-list-indentation";
 
-function render(source: string, incremental?: Plugin<[], Root>) {
+function render(source: string, incremental?: Plugin<[], Root>, parsedSources?: string[]) {
   let tree: Root | undefined;
+  const observeParsing: Plugin<[], Root> = function () {
+    const original = this.parser;
+    if (original) {
+      this.parser = (text, file) => {
+        parsedSources?.push(text);
+        return original(text, file);
+      };
+    }
+  };
   const capture: Plugin<[], Root> = () => (root) => {
     tree = structuredClone(root);
   };
   const html = renderToStaticMarkup(
     <ReactMarkdown
       remarkPlugins={[
+        observeParsing,
         capture,
         remarkGfm,
         remarkGithubAlerts,
@@ -38,6 +48,20 @@ function render(source: string, incremental?: Plugin<[], Root>) {
 const prefix = "# Before\n\n```ts\nconst values = [1, 2];\n```\n\n";
 
 describe("incremental Markdown parsing", () => {
+  it("keeps the document prefix cached when list recovery parses contain fences", () => {
+    const source =
+      prefix +
+      "-       first block\n\n        ```ts\n        const nested = 1;\n        ```\n\n        tail";
+    const incremental = createIncrementalMarkdownPlugin();
+    const parsedSources: string[] = [];
+    expect(render(source, incremental, parsedSources)).toEqual(render(source));
+    parsedSources.length = 0;
+    const next = source + " more";
+    expect(render(next, incremental, parsedSources)).toEqual(render(next));
+    expect(parsedSources).not.toContain(next);
+    expect(parsedSources.some((text) => text.startsWith("t3-markdown-inline-prefix:"))).toBe(true);
+  });
+
   it.each([
     "a\n===\n\nb\n---\n",
     "- first\n\n  continued\n\n- next\n",
diff --git a/apps/web/src/markdown-incremental.ts b/apps/web/src/markdown-incremental.ts
index df6395a372e9..e1e8c06213c1 100644
--- a/apps/web/src/markdown-incremental.ts
+++ b/apps/web/src/markdown-incremental.ts
@@ -93,6 +93,15 @@ export function createIncrementalMarkdownPlugin(): Plugin<[], Root> {
     const original = this.parser;
     if (!original) return;
     parser ??= createIncrementalMarkdownParser((source, file) => original(source, file) as Root);
-    this.parser = parser;
+    const parseDocument = parser;
+    // ReactMarkdown creates a processor per render. Its first parse is the
+    // document; transforms can then parse synthetic recovery text on that same
+    // processor. Those parses must not read or replace the document's cache.
+    let documentParsed = false;
+    this.parser = (source, file) => {
+      if (documentParsed) return original(source, file);
+      documentParsed = true;
+      return parseDocument(source, file);
+    };
   };
 }

From a660ad9413e5dedba3937696a88c9ea17cbcc37a Mon Sep 17 00:00:00 2001
From: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com>
Date: Thu, 10 Sep 2026 22:08:12 -0700
Subject: [PATCH 3/3] chore(web): keep the Markdown parser cache helper private

---
 apps/web/src/markdown-incremental.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/src/markdown-incremental.ts b/apps/web/src/markdown-incremental.ts
index e1e8c06213c1..3fffa35d3adb 100644
--- a/apps/web/src/markdown-incremental.ts
+++ b/apps/web/src/markdown-incremental.ts
@@ -34,7 +34,7 @@ function shiftPositions(node: Root | RootContent, offset: number, lines: number)
  * prefix on every token. A closed top-level fence followed by a blank line is a
  * parsing boundary. Definitions are document-wide, so they require a full parse.
  */
-export function createIncrementalMarkdownParser(parse: Parser): Parser {
+function createIncrementalMarkdownParser(parse: Parser): Parser {
   let cached: ParsedPrefix | undefined;
 
   return (source, file) => {