Skip to content

Your lightweight open-source personal agent.

fix(webui): preserve TeX formula boundaries in streaming Markdown

chengyongru810802e016cd
diff --git a/webui/bun.lock b/webui/bun.lock
index ea15f64f2..b74767da7 100644
--- a/webui/bun.lock
+++ b/webui/bun.lock
@@ -28,9 +28,11 @@
"remark-breaks": "^4.0.0",
"remark-gfm": "^4.0.0",
"remark-math": "^6.0.0",
+ "remark-parse": "^11.0.0",
"remend": "1.3.0",
"streamdown": "2.5.0",
"tailwind-merge": "^2.6.0",
+ "unified": "^11.0.5",
},
"devDependencies": {
"@eslint/js": "^10.0.1",
diff --git a/webui/package-lock.json b/webui/package-lock.json
index ed1db3679..5c06ef2c7 100644
--- a/webui/package-lock.json
+++ b/webui/package-lock.json
@@ -30,8 +30,11 @@
"remark-breaks": "^4.0.0",
"remark-gfm": "^4.0.0",
"remark-math": "^6.0.0",
+ "remark-parse": "^11.0.0",
+ "remend": "1.3.0",
"streamdown": "2.5.0",
- "tailwind-merge": "^2.6.0"
+ "tailwind-merge": "^2.6.0",
+ "unified": "^11.0.5"
},
"devDependencies": {
"@eslint/js": "^10.0.1",
diff --git a/webui/package.json b/webui/package.json
index 8760f7492..af8ed1a1e 100644
--- a/webui/package.json
+++ b/webui/package.json
@@ -36,9 +36,11 @@
"remark-breaks": "^4.0.0",
"remark-gfm": "^4.0.0",
"remark-math": "^6.0.0",
+ "remark-parse": "^11.0.0",
"remend": "1.3.0",
"streamdown": "2.5.0",
- "tailwind-merge": "^2.6.0"
+ "tailwind-merge": "^2.6.0",
+ "unified": "^11.0.5"
},
"devDependencies": {
"@eslint/js": "^10.0.1",
diff --git a/webui/src/components/MarkdownTextRenderer.tsx b/webui/src/components/MarkdownTextRenderer.tsx
index 23fbfff82..b609bed63 100644
--- a/webui/src/components/MarkdownTextRenderer.tsx
+++ b/webui/src/components/MarkdownTextRenderer.tsx
@@ -14,6 +14,8 @@ import remarkMath from "remark-math";
import { Streamdown, type Components, type StreamdownProps } from "streamdown";
import remend from "remend";
+import { parseMathAwareMarkdownBlocks } from "@/lib/markdown-streaming-blocks";
+
import { AttachmentTile } from "@/components/AttachmentTile";
import { CodeBlock } from "@/components/CodeBlock";
import { WebLink } from "@/components/WebLink";
@@ -831,6 +833,7 @@ export default function MarkdownTextRenderer({
key={needsMath && mathPlugin ? "math" : "text"}
mode={streaming || preserveStreamingLayout ? "streaming" : "static"}
parseIncompleteMarkdown={false}
+ parseMarkdownIntoBlocksFn={parseMathAwareMarkdownBlocks}
isAnimating={false}
animated={false}
linkSafety={DIRECT_LINKS}
diff --git a/webui/src/lib/markdown-streaming-blocks.ts b/webui/src/lib/markdown-streaming-blocks.ts
new file mode 100644
index 000000000..fdcadbec6
--- /dev/null
+++ b/webui/src/lib/markdown-streaming-blocks.ts
@@ -0,0 +1,56 @@
+import type { Nodes } from "mdast";
+import remarkGfm from "remark-gfm";
+import remarkMath from "remark-math";
+import remarkParse from "remark-parse";
+import { parseMarkdownIntoBlocks } from "streamdown";
+import { unified } from "unified";
+
+import { remarkTexMath } from "@/lib/remark-tex-math";
+
+const boundaryParser = unified()
+ .use(remarkParse)
+ .use(remarkGfm)
+ .use(remarkMath, { singleDollarTextMath: false })
+ .use(remarkTexMath, { allowUnclosedFlow: true })
+ .freeze();
+
+function containsMath(node: Nodes): boolean {
+ return node.type === "math" || node.type === "inlineMath"
+ || ("children" in node && node.children.some(containsMath));
+}
+
+/** Keep formula boundaries intact without replacing Streamdown's ordinary block grouping. */
+export function parseMathAwareMarkdownBlocks(source: string): string[] {
+ const blocks = parseMarkdownIntoBlocks(source);
+ if (blocks.length < 2 || !/\$\$|\\\[/.test(source)) return blocks;
+
+ // Marked normalizes line endings. Do not compare its offsets against different source bytes.
+ if (blocks.join("") !== source) return [source];
+
+ const ranges: Array<{ start: number; end: number }> = [];
+ for (const node of boundaryParser.parse(source).children) {
+ if (!containsMath(node)) continue;
+ const start = node.position?.start.offset;
+ const end = node.position?.end.offset;
+ if (start === undefined || end === undefined) return [source];
+ // Protect the enclosing list/quote too: isolated continuation lines lose their container.
+ ranges.push({ start, end });
+ }
+ if (ranges.length === 0) return blocks;
+
+ const merged: string[] = [];
+ let pending = "";
+ let offset = 0;
+ let rangeIndex = 0;
+ for (const block of blocks) {
+ pending += block;
+ offset += block.length;
+ while (rangeIndex < ranges.length && offset >= ranges[rangeIndex].end) rangeIndex++;
+ const range = ranges[rangeIndex];
+ if (range && range.start < offset && offset < range.end) continue;
+ merged.push(pending);
+ pending = "";
+ }
+ if (pending) merged.push(pending);
+ return merged;
+}
diff --git a/webui/src/lib/remark-tex-math.ts b/webui/src/lib/remark-tex-math.ts
index 523aea205..231c2e19a 100644
--- a/webui/src/lib/remark-tex-math.ts
+++ b/webui/src/lib/remark-tex-math.ts
@@ -25,37 +25,50 @@ type ProcessorData = {
micromarkExtensions?: Extension[];
};
-const texMathSyntax: Extension = {
- flow: {
- [BACKSLASH]: {
- tokenize: tokenizeTexMathFlow,
- concrete: true,
- name: "texMathFlow",
+function texMathSyntax(allowUnclosedFlow: boolean): Extension {
+ return {
+ flow: {
+ [BACKSLASH]: {
+ tokenize(effects, ok, nok) {
+ return tokenizeTexMathFlow(effects, ok, nok, allowUnclosedFlow);
+ },
+ concrete: true,
+ name: "texMathFlow",
+ },
+ [DOLLAR]: {
+ tokenize(effects, ok, nok) {
+ return tokenizeDollarMathFlow(effects, ok, nok, allowUnclosedFlow);
+ },
+ concrete: true,
+ name: "dollarMathFlow",
+ },
},
- [DOLLAR]: {
- tokenize: tokenizeDollarMathFlow,
- concrete: true,
- name: "dollarMathFlow",
+ text: {
+ [BACKSLASH]: {
+ tokenize: tokenizeTexMathText,
+ name: "texMathText",
+ },
+ [DOLLAR]: {
+ tokenize: tokenizeGuardedDollarMathText,
+ name: "guardedDollarMathText",
+ },
},
- },
- text: {
- [BACKSLASH]: {
- tokenize: tokenizeTexMathText,
- name: "texMathText",
- },
- [DOLLAR]: {
- tokenize: tokenizeGuardedDollarMathText,
- name: "guardedDollarMathText",
- },
- },
-};
+ };
+}
+
+interface TexMathOptions {
+ /** Keep an unfinished display formula together when locating streaming block boundaries. */
+ allowUnclosedFlow?: boolean;
+}
-export const remarkTexMath: Plugin<[], Root> = function remarkTexMath() {
+export const remarkTexMath: Plugin<[TexMathOptions?], Root> = function remarkTexMath(
+ { allowUnclosedFlow = false } = {},
+) {
const data = this.data() as ProcessorData;
const micromarkExtensions =
data.micromarkExtensions || (data.micromarkExtensions = []);
- micromarkExtensions.push(texMathSyntax);
+ micromarkExtensions.push(texMathSyntax(allowUnclosedFlow));
};
function isLineEnding(code: Code): boolean {
@@ -93,6 +106,19 @@ const dollarMathFlowClose: Construct = {
partial: true,
};
+const nonLazyContinuation: Construct = {
+ partial: true,
+ tokenize(effects, ok, nok) {
+ const lineStart: State = (code) => this.parser.lazy[this.now().line] ? nok(code) : ok(code);
+ return (code) => {
+ effects.enter("lineEnding");
+ effects.consume(code);
+ effects.exit("lineEnding");
+ return lineStart;
+ };
+ },
+};
+
// Model output commonly uses `$...$`; numeric-only spans are usually prices, not formulas.
function tokenizeGuardedDollarMathText(effects: Effects, ok: State, nok: State): State {
let hasMathSignal = false;
@@ -212,18 +238,26 @@ function tokenizeTexMathText(effects: Effects, ok: State, nok: State): State {
}
}
-function tokenizeTexMathFlow(effects: Effects, ok: State, nok: State): State {
- return tokenizeMathFlow(effects, ok, nok, LEFT_BRACKET, BACKSLASH, texMathFlowClose);
+function tokenizeTexMathFlow(
+ effects: Effects, ok: State, nok: State, allowUnclosedFlow: boolean,
+): State {
+ return tokenizeMathFlow(
+ effects, ok, nok, LEFT_BRACKET, BACKSLASH, texMathFlowClose, allowUnclosedFlow,
+ );
}
// Treat text after an opening $$ as formula content, not Markdown fence metadata.
-function tokenizeDollarMathFlow(effects: Effects, ok: State, nok: State): State {
- return tokenizeMathFlow(effects, ok, nok, DOLLAR, DOLLAR, dollarMathFlowClose);
+function tokenizeDollarMathFlow(
+ effects: Effects, ok: State, nok: State, allowUnclosedFlow: boolean,
+): State {
+ return tokenizeMathFlow(
+ effects, ok, nok, DOLLAR, DOLLAR, dollarMathFlowClose, allowUnclosedFlow,
+ );
}
function tokenizeMathFlow(
effects: Effects, ok: State, nok: State,
- openingTail: number, closingStart: number, closing: Construct,
+ openingTail: number, closingStart: number, closing: Construct, allowUnclosedFlow = false,
): State {
return start;
@@ -251,14 +285,9 @@ function tokenizeMathFlow(
}
function contentStart(code: Code): State | undefined {
- if (code === null) return nok(code);
+ if (code === null) return allowUnclosedFlow ? done(code) : nok(code);
- if (isLineEnding(code)) {
- effects.enter("lineEnding");
- effects.consume(code);
- effects.exit("lineEnding");
- return contentStart;
- }
+ if (isLineEnding(code)) return beforeLineEnding(code);
if (code === closingStart) {
return effects.attempt(closing, done, contentStartAfterDelimiter)(code);
@@ -271,15 +300,12 @@ function tokenizeMathFlow(
function content(code: Code): State | undefined {
if (code === null) {
effects.exit("mathFlowValue");
- return nok(code);
+ return allowUnclosedFlow ? done(code) : nok(code);
}
if (isLineEnding(code)) {
effects.exit("mathFlowValue");
- effects.enter("lineEnding");
- effects.consume(code);
- effects.exit("lineEnding");
- return contentStart;
+ return beforeLineEnding(code);
}
if (code === closingStart) {
@@ -291,6 +317,20 @@ function tokenizeMathFlow(
return openingTail === DOLLAR && code === BACKSLASH ? escaped : content;
}
+ function beforeLineEnding(code: Code): State | undefined {
+ // A pending formula must end with its list/quote, not absorb following root blocks.
+ return allowUnclosedFlow
+ ? effects.check(nonLazyContinuation, consumeLineEnding, done)(code)
+ : consumeLineEnding(code);
+ }
+
+ function consumeLineEnding(code: Code): State | undefined {
+ effects.enter("lineEnding");
+ effects.consume(code);
+ effects.exit("lineEnding");
+ return contentStart;
+ }
+
function escaped(code: Code): State | undefined {
if (code === null || isLineEnding(code)) return content(code);
effects.consume(code);
@@ -305,12 +345,12 @@ function tokenizeMathFlow(
function done(code: Code): State | undefined {
effects.exit("mathFlow");
- if (openingTail === DOLLAR) return factorySpace(effects, afterClose, "whitespace")(code);
- return ok(code);
+ // Flow constructs must finish at EOL/EOF, including Remend's synthetic link suffixes.
+ return factorySpace(effects, afterClose, "whitespace")(code);
}
function afterClose(code: Code): State | undefined {
- // Inline formulas followed by prose belong to remark-math's text tokenizer.
+ // Reject suffixes that would leave the flow tokenizer in the middle of a line.
return code === null || isLineEnding(code) ? ok(code) : nok(code);
}
}
diff --git a/webui/src/tests/markdown-streaming-blocks.test.ts b/webui/src/tests/markdown-streaming-blocks.test.ts
new file mode 100644
index 000000000..18ea39616
--- /dev/null
+++ b/webui/src/tests/markdown-streaming-blocks.test.ts
@@ -0,0 +1,102 @@
+import remarkMath from "remark-math";
+import remarkParse from "remark-parse";
+import { parseMarkdownIntoBlocks } from "streamdown";
+import { unified } from "unified";
+import { describe, expect, it } from "vitest";
+
+import { parseMathAwareMarkdownBlocks } from "@/lib/markdown-streaming-blocks";
+import { remarkTexMath } from "@/lib/remark-tex-math";
+
+const formula = String.raw`\[
+\tan\left(\frac{\mathrm{HFOV}}{2}\right)
+=
+\frac{X}{Z}
+
+\]`;
+
+function expectIntact(source: string, protectedSource: string) {
+ const blocks = parseMathAwareMarkdownBlocks(source);
+ expect(blocks.join("")).toBe(source);
+ expect(blocks.some((block) => block.includes(protectedSource))).toBe(true);
+ return blocks;
+}
+
+describe("math-aware streaming blocks", () => {
+ it("merges a TeX formula split at a Setext equals line and blank lines", () => {
+ const source = "Before\n\n" + formula + "\n\nAfter";
+ expect(parseMarkdownIntoBlocks(source).some((block) => block.includes(formula))).toBe(false);
+ const blocks = expectIntact(source, formula);
+ expect(blocks[0]).toBe("Before");
+ expect(blocks.at(-1)).toBe("After");
+ });
+
+ it("keeps every unfinished display-math prefix together without carrying state", () => {
+ for (let end = 2; end <= formula.length; end++) {
+ const partial = formula.slice(0, end);
+ expectIntact("Before\n\n" + partial, partial);
+ }
+ expect(parseMathAwareMarkdownBlocks("Replacement\n\nPlain text")).toEqual(
+ parseMarkdownIntoBlocks("Replacement\n\nPlain text"),
+ );
+ });
+
+ it.each([
+ String.raw`\[a
+=
+b\]`,
+ "Before\n" + formula,
+ String.raw`\(a + b\)`,
+ "$$a\n=\nb\n\n$$",
+ "$$$\na\n=\nb\n\n$$$",
+ ])("keeps math intact with surrounding text and supported fences: %s", (math) => {
+ expectIntact(math + "\n\nAfter", math);
+ });
+
+ it.each([
+ formula.split("\n").map((line) => "> " + line).join("\n"),
+ "- Item\n\n" + formula.split("\n").map((line) => " " + line).join("\n"),
+ ])("protects the enclosing container: %s", (container) => {
+ expectIntact(container + "\n\nAfter", container);
+ });
+
+ it("does not consume text outside an unfinished blockquote formula", () => {
+ const quoted = "> \\[\n> a\n> =\n> b";
+ const blocks = expectIntact(quoted + "\n\nOutside\n\nNext", quoted);
+ expect(blocks.at(-1)).toBe("Next");
+ expect(blocks.some((block) => block.includes(quoted) && block.includes("Outside"))).toBe(false);
+ });
+
+ it.each([
+ "", "First\n\n## Heading\n\nLast", "Prices: $20 and $30.\n\nNext",
+ "```latex\n" + formula + "\n```\n\nAfter",
+ formula.split("\n").map((line) => " " + line).join("\n") + "\n\nAfter",
+ "`" + formula + "`\n\nAfter",
+ String.raw`\\[a
+=
+b\\]
+
+After`,
+ "$$a$$ trailing prose\n\nAfter",
+ "[link][target]\n\nNext\n\n[target]: https://example.com",
+ "<div>\n\nOrdinary HTML\n\n</div>\n\nAfter",
+ ])("preserves default grouping when no math boundary needs repair: %s", (source) => {
+ expect(parseMathAwareMarkdownBlocks(source)).toEqual(parseMarkdownIntoBlocks(source));
+ });
+
+ it("preserves CRLF source bytes rather than comparing normalized offsets", () => {
+ const source = "Before\r\n\r\n" + formula.replaceAll("\n", "\r\n") + "\r\n\r\nAfter";
+ expect(parseMathAwareMarkdownBlocks(source)).toEqual([source]);
+ });
+
+ it("does not enable unfinished formulas in the rendering grammar", () => {
+ const source = String.raw`\[
+a
+=
+b`;
+ const strict = unified().use(remarkParse).use(remarkMath).use(remarkTexMath);
+ const boundaries = unified().use(remarkParse).use(remarkMath)
+ .use(remarkTexMath, { allowUnclosedFlow: true });
+ expect(strict.parse(source).children.some((node) => node.type === "math")).toBe(false);
+ expect(boundaries.parse(source).children.map((node) => node.type)).toEqual(["math"]);
+ });
+});
diff --git a/webui/src/tests/markdown-text-math.test.tsx b/webui/src/tests/markdown-text-math.test.tsx
new file mode 100644
index 000000000..7a24d8823
--- /dev/null
+++ b/webui/src/tests/markdown-text-math.test.tsx
@@ -0,0 +1,33 @@
+import { render, waitFor } from "@testing-library/react";
+import { expect, it } from "vitest";
+
+import { MarkdownText } from "@/components/MarkdownText";
+
+it("retains a rendered TeX formula when an assistant response completes in streaming layout", async () => {
+ const source = String.raw`Before
+
+\[
+\tan\left(\frac{\mathrm{HFOV}}{2}\right)
+=
+\frac{W}{2f_x}
+
+\]
+
+After`;
+ const { container, rerender } = render(
+ <MarkdownText streaming preserveStreamingLayout>{source}</MarkdownText>,
+ );
+ await waitFor(() => expect(container.querySelector(".katex-display")).toBeInTheDocument(), {
+ timeout: 10_000,
+ });
+ const formula = container.querySelector(".katex-display");
+ const tex = container.querySelector("annotation")?.textContent;
+
+ rerender(<MarkdownText preserveStreamingLayout>{source}</MarkdownText>);
+ await waitFor(() => expect(container.querySelector(".katex-display")).toBe(formula));
+ expect(container.querySelector("annotation")?.textContent).toBe(tex);
+ expect(container.querySelector(".katex-error")).toBeNull();
+ expect(container.querySelector("h1, h2")).toBeNull();
+ expect(container).toHaveTextContent("Before");
+ expect(container).toHaveTextContent("After");
+});
diff --git a/webui/src/tests/markdown-text-renderer.test.tsx b/webui/src/tests/markdown-text-renderer.test.tsx
index 40e2d81e8..b4b135a42 100644
--- a/webui/src/tests/markdown-text-renderer.test.tsx
+++ b/webui/src/tests/markdown-text-renderer.test.tsx
@@ -842,6 +842,48 @@ describe("MarkdownTextRenderer", () => {
expect(container.querySelector("annotation")).toHaveTextContent("C = \\sum_i c_i");
});
+ it.each([false, true])("keeps TeX equations out of Markdown headings (streaming=%s)", (streaming) => {
+ const formula = String.raw`\tan\left(\frac{\mathrm{HFOV}}{2}\right)
+=
+\frac{X}{Z}`;
+ const source = "Before\n\n\\[\n" + formula + "\n\n\\]\n\nAfter";
+ const { container } = render(
+ <MarkdownTextRenderer streaming={streaming}>{source}</MarkdownTextRenderer>,
+ );
+ expect(container.querySelector(".katex-display annotation")?.textContent?.trim()).toBe(formula);
+ expect(container.querySelector(".katex-error")).toBeNull();
+ expect(container.querySelector("h1, h2")).toBeNull();
+ expect(container).toHaveTextContent("Before");
+ expect(container).toHaveTextContent("After");
+ });
+
+ it("keeps an unfinished TeX command renderable when Remend adds a link suffix", () => {
+ const { container } = render(
+ <MarkdownTextRenderer streaming>{"\\[\n\\"}</MarkdownTextRenderer>,
+ );
+ expect(container.textContent).not.toBe("");
+ });
+
+ it("recovers a complete TeX equation after every streaming prefix", () => {
+ const source = String.raw`\[
+\boxed{
+\mathrm{HFOV}
+=
+
+2\arctan\left(\frac{W}{2f_x}\right)
+}
+\]`;
+ const { container, rerender } = render(<MarkdownTextRenderer streaming>{""}</MarkdownTextRenderer>);
+ for (let end = 1; end <= source.length; end++) {
+ rerender(<MarkdownTextRenderer streaming>{source.slice(0, end)}</MarkdownTextRenderer>);
+ }
+ rerender(<MarkdownTextRenderer streaming>{source + "\n\nFollowing paragraph"}</MarkdownTextRenderer>);
+ expect(container.querySelectorAll(".katex-display")).toHaveLength(1);
+ expect(container.querySelector(".katex-error")).toBeNull();
+ expect(container.querySelector("h1, h2")).toBeNull();
+ expect(container).toHaveTextContent("Following paragraph");
+ });
+
it("still renders explicit math blocks", () => {
const { container } = render(
<MarkdownTextRenderer>{"$$x^2 + y^2 = z^2$$"}</MarkdownTextRenderer>,