Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

14.2 KB
Raw Blame
/**
 * Math rendering across the shared Markdown pipeline (src/components/content/prose/
 * markdown-plugins.ts), via react-dom/server static markup — KaTeX renders synchronously, so the
 * finished formula is in the first pass with no DOM and no effects.
 *
 * What is pinned here is the set of decisions that are invisible once they work and silently wrong
 * when they break: which delimiters count, which look like delimiters but must not, what a
 * malformed formula does to the message around it, and what `Md` holds back while a reply
 * streams. That every renderer in the app shares the one plugin list is the Web App's own guard
 * (packages/web/test/markdown-math.test.ts).
 */
import { describe, expect, it } from "vitest";
import { createElement } from "react";
import { renderToStaticMarkup } from "react-dom/server";
import ReactMarkdown from "react-markdown";
import { REHYPE_PLUGINS, REMARK_PLUGINS } from "../src/components/content/prose/markdown-plugins";
import { Md } from "../src/components/content/prose/prose";

const render = (markdown: string) =>
  renderToStaticMarkup(
    createElement(
      ReactMarkdown,
      { remarkPlugins: REMARK_PLUGINS, rehypePlugins: REHYPE_PLUGINS },
      markdown,
    ),
  );

/** KaTeX rendered something here (as opposed to leaving the source as prose). */
const isMath = (html: string) => html.includes('class="katex');
/** KaTeX rendered it in display mode — its own block wrapper, not an inline run. */
const isDisplay = (html: string) => html.includes('class="katex-display"');
/**
 * The reader-visible text, tags stripped.
 *
 * KaTeX emits each formula twice: a visually hidden MathML tree (for screen readers, and carrying
 * the original TeX in an `<annotation>`) alongside the styled HTML. Dropping the `<math>` element
 * first is what makes this the text a reader actually sees rather than everything twice over.
 */
const text = (html: string) => html.replace(/<math\b[\s\S]*?<\/math>/g, "").replace(/<[^>]*>/g, "");

describe("delimiters that are math", () => {
  it("renders the reported shape: a display formula in \\[…\\] with CJK in \\text{}", () => {
    const html = render(
      String.raw`\[\text{采集} \rightarrow \text{解码} \rightarrow \text{干预}\]`,
    );
    expect(isDisplay(html)).toBe(true);
    // The source is gone from view: no stray backslash commands left in the prose.
    expect(text(html)).not.toContain(String.raw`\rightarrow`);
    expect(text(html)).toBe("采集→解码→干预");
  });

  it("accepts all three delimiter pairs", () => {
    for (const source of [
      String.raw`\(E=mc^2\)`,
      String.raw`\[E=mc^2\]`,
      "$$E=mc^2$$",
      // Fenced $$ on its own lines, the block form remark-math documents.
      "$$\nE=mc^2\n$$",
    ]) {
      expect(isMath(render(source)), source).toBe(true);
    }
  });

  it("distinguishes display from inline", () => {
    expect(isDisplay(render(String.raw`\[x\]`))).toBe(true);
    expect(isDisplay(render("$$\nx\n$$"))).toBe(true);
    expect(isDisplay(render(String.raw`\(x\)`))).toBe(false);
    expect(isMath(render(String.raw`\(x\)`))).toBe(true);
  });

  it("makes a $$…$$ pair display wherever it is written, not only on its own lines", () => {
    // remark-math decides by run length, which leaves a one-line `$$…$$` inline: nowrap, typeset
    // cramped, and behaving unlike `\[…\]` for content nobody writes meaning inline. A `$$` pair
    // has been display since plain TeX, and single-dollar math is off, so nothing else fits.
    for (const source of ["$$E=mc^2$$", "text $$E=mc^2$$ text", "# heading $$x^2$$"]) {
      expect(isDisplay(render(source)), source).toBe(true);
    }
  });

  it("clamps a sizing command to a size the message body absorbs", () => {
    // KaTeX defaults maxSize to Infinity, so `\rule{9999em}{9999em}` is a black square many
    // viewports wide and no overflow rule can help: the element's own height is the problem.
    const html = render(String.raw`\[\rule{9999em}{9999em}\]`);
    const sizes = [...html.matchAll(/(?:width|height)[:="]+([\d.]+)em/g)].map((m) => Number(m[1]));
    expect(sizes.length).toBeGreaterThan(0);
    expect(Math.max(...sizes)).toBeLessThanOrEqual(5);
  });

  it("renders \\[…\\] mid-sentence without breaking the paragraph open", () => {
    // Display math is emitted as a <span>, so it nests legally inside the surrounding <p>.
    const html = render(String.raw`before \[x\] after`);
    expect(isDisplay(html)).toBe(true);
    expect(html).not.toMatch(/<p>[\s\S]*<(?:div|pre)\b/);
    expect(text(html)).toContain("before");
    expect(text(html)).toContain("after");
  });

  it("carries a multi-line formula that sits inside one paragraph", () => {
    const html = render(
      "start\n\\[\n\\begin{aligned}\na &= b \\\\\nc &= d\n\\end{aligned}\n\\]\nend",
    );
    expect(isDisplay(html)).toBe(true);
    expect(text(html)).toContain("start");
    expect(text(html)).toContain("end");
  });

  it("renders ordinary formulas: fractions, integrals, matrices, inline mass-energy", () => {
    for (const source of [
      String.raw`\[\frac{a}{b}\]`,
      String.raw`\[\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}\]`,
      String.raw`\[\begin{bmatrix} 1 & 2 \\ 3 & 4 \end{bmatrix}\]`,
      String.raw`\(E=mc^2\)`,
    ]) {
      const html = render(source);
      expect(isMath(html), source).toBe(true);
      expect(html, source).not.toContain("katex-error");
    }
  });

  it("gives CJK inside \\text{} the class the stylesheet hangs a font fallback on", () => {
    // KaTeX's own faces have no CJK glyphs; it tags the run `cjk_fallback` and defines nothing for
    // it, so prose.css points that class at the reading face. Without the class there is no hook.
    expect(render(String.raw`\[\text{采集}\]`)).toContain("cjk_fallback");
  });
});

describe("delimiters that are not math", () => {
  it("leaves shell variables and prices alone (single-dollar math is off)", () => {
    for (const prose of [
      "Set $PATH and $HOME before running.",
      "It costs $5 and $10 in total.",
      "The range is $5-$10 per seat.",
      "Use $HOME/.penguin/data or $PENGUIN_HOME.",
      "echo $PATH; echo $HOME",
      "Prices: $1,200 and $3,400.",
      "50% off: $20 to $10",
      "Balance: $0. Fee: $3.",
    ]) {
      const html = render(prose);
      expect(isMath(html), prose).toBe(false);
      // Every dollar sign survives, and so does the wording around it.
      expect(text(html), prose).toBe(prose);
    }
  });

  it("never renders math inside inline code", () => {
    for (const source of ["`$$x$$`", "`\\(x\\)`", "`\\[x\\]`", "`$PATH`"]) {
      const html = render(source);
      expect(isMath(html), source).toBe(false);
      expect(html, source).toContain("<code>");
    }
  });

  it("does not reach into a code span for a closer", () => {
    // The opener is safe by construction — the tokenizer is only entered where inline content is
    // read — but a closer inside a code span is just more raw characters to a scan already inside
    // a formula. Prose about the delimiters is the shape that breaks.
    for (const source of [
      "In LaTeX you open with \\( and close with `\\)`.",
      "Open with \\[ and close with `\\]`.",
      "Write \\( then `\\)` then more text.",
    ]) {
      const html = render(source);
      expect(isMath(html), source).toBe(false);
      expect(html, source).toContain("<code>");
      // The code span survives intact: no backtick spilled into the surrounding prose.
      expect(text(html), source).not.toContain("`");
    }
  });

  it("never renders math inside a fenced or indented code block", () => {
    for (const source of [
      "```\n\\[x\\]\n$$y$$\n\\(z\\)\n```",
      "```bash\necho $PATH\n\\[x\\]\n```",
      "~~~\n\\[x\\]\n~~~",
      "    \\[x\\]\n    $$y$$",
    ]) {
      expect(isMath(render(source)), source).toBe(false);
    }
  });

  it("leaves an escaped backslash-bracket as literal text", () => {
    const html = render(String.raw`escaped \\[not math\\] here`);
    expect(isMath(html)).toBe(false);
    expect(text(html)).toBe(String.raw`escaped \[not math\] here`);
  });

  it("does not disturb the other character escapes", () => {
    const html = render(String.raw`a \* b and \_c\_ and \# d`);
    expect(text(html)).toBe("a * b and _c_ and # d");
    expect(html).not.toContain("<em>");
  });
});

describe("collisions resolved on purpose", () => {
  it("reads CommonMark's escaped brackets as math", () => {
    // `\[` and `\]` are also the escapes for a literal bracket, so a footnote marker or a
    // placeholder written that way becomes a formula — and, `\[…\]` being display, a centred one
    // that splits the sentence. Two syntaxes over one character, and only one can win; it goes to
    // the one models actually emit. Pinned so the trade stays a decision rather than a surprise.
    for (const source of [
      String.raw`See \[1\] and \[2\] for details.`,
      String.raw`Write \[TODO\] in the file.`,
      String.raw`Use \(foo\) to capture a group.`,
    ]) {
      expect(isMath(render(source)), source).toBe(true);
    }
  });
});

describe("input that arrives broken or half-written", () => {
  it("renders a malformed expression as its own source instead of throwing", () => {
    const html = render(String.raw`\[\frac{1\]`);
    expect(html).toContain("katex-error");
    expect(text(html)).toContain(String.raw`\frac{1`);
  });

  it("keeps the rest of the message when one formula fails", () => {
    const html = render(String.raw`before \(\frac{1\) after \(E=mc^2\) end`);
    expect(text(html)).toContain("before");
    expect(text(html)).toContain("after");
    expect(text(html)).toContain("end");
    expect(html).toContain("katex-error"); // the broken one
    expect(html).toContain('class="katex"'); // the good one still rendered
  });

  it("renders the user's own mangled paste rather than blanking the reply", () => {
    // `\text(…)` — braces typed as parentheses. LaTeX-incompatible, still renderable.
    const html = render(String.raw`\[\text(采集) \rightarrow \text(解码)\]`);
    expect(text(html)).toContain("采集");
    expect(html).not.toBe("");
  });

  it("shows an unterminated delimiter as ordinary text, then settles when the closer lands", () => {
    // The three states a streaming reply passes through, delta by delta.
    const partial = String.raw`结论:\[\text{采集} \right`;
    expect(isMath(render(partial))).toBe(false);
    expect(text(render(partial))).toContain(String.raw`\text{采集}`);

    const stillPartial = String.raw`结论:\[\text{采集} \rightarrow \text{解码}`;
    expect(isMath(render(stillPartial))).toBe(false);

    const settled = String.raw`结论:\[\text{采集} \rightarrow \text{解码}\]`;
    expect(isDisplay(render(settled))).toBe(true);
    expect(text(render(settled))).toContain("结论:");
  });

  it("an unclosed opener costs one scan, not one per opener", () => {
    // Each opener with no closer used to scan the rest of the paragraph, so a paragraph full of
    // stray ones cost a full pass each — 1000 of them in an 18k-character paragraph measured ~235x
    // the same paragraph on its own, and chat bodies re-parse as they stream. Guards the give-up
    // memo in remark-math-brackets.ts. Compared as a ratio against a control render in the same
    // process rather than against a wall clock, so a loaded CI box moves both numbers together.
    const paragraph = "中文段落内容".repeat(3000);
    const hostile = "\\[".repeat(1000) + paragraph;
    const measure = (source: string) => {
      const started = performance.now();
      render(source);
      return performance.now() - started;
    };
    measure(hostile); // warm the pipeline, JIT included
    measure(paragraph);
    const control = Math.max(measure(paragraph), 1);
    expect(measure(hostile) / control).toBeLessThan(20);
  });
});

describe("Md, the renderer every Markdown surface shares", () => {
  const renderMd = (text: string, streaming = false) =>
    renderToStaticMarkup(createElement(Md, { text, streaming }));

  it("typesets a formula on settle and shows its source until then", () => {
    // rehype-katex is the expensive half of the pipeline — KaTeX's markup is re-parsed into hast
    // and rebuilt as several hundred React elements per formula — and a streaming body re-renders
    // on every delta. So the stage is held back to the settle render, the same one that
    // re-highlights code blocks. Losing this is invisible in a screenshot and quadratic in a chat.
    expect(isDisplay(renderMd(String.raw`\[\frac{a}{b}\]`))).toBe(true);
    expect(isMath(renderMd(String.raw`\(E=mc^2\)`))).toBe(true);

    for (const [source, formula] of [
      [String.raw`\[\frac{a}{b}\]`, String.raw`\frac{a}{b}`],
      [String.raw`\(E=mc^2\)`, "E=mc^2"],
      ["$$E=mc^2$$", "E=mc^2"],
    ] as const) {
      const html = renderMd(source, true);
      expect(isMath(html), source).toBe(false);
      // The source, delimiters aside, stays legible while it streams.
      expect(text(html), source).toBe(formula);
    }
  });

  it("keeps a streaming $$ block out of the CodeBlock chrome", () => {
    // remark-math models block math as a `language-math` fence, which is exactly what the `pre`
    // override turns into CodeBlock. Settled, rehype-katex replaces the pair before the override
    // is consulted; streaming, nothing does — so a formula would grow a language label and a copy
    // button for as long as the reply takes to arrive, then lose them.
    const html = renderMd("$$\n\\frac{a}{b}\n$$", true);
    expect(html).not.toContain("code-block");
    expect(html).toContain("<pre>");
    expect(text(html)).toContain(String.raw`\frac{a}{b}`);
  });

  it("a $$ block becomes a formula, not a code block", () => {
    // remark-math models block math as <pre><code class="language-math">, which is exactly what the
    // renderer's `pre` override turns into CodeBlock chrome. rehype-katex replaces the <pre>
    // outright before that override is ever consulted, so the two never collide.
    const html = renderMd("$$\n\\frac{a}{b}\n$$");
    expect(isDisplay(html)).toBe(true);
    expect(html).not.toContain("code-block");
  });

  it("still routes real fenced code through CodeBlock", () => {
    const html = renderMd("```js\nconst a = 1;\n```");
    expect(html).toContain("code-block");
    expect(isMath(html)).toBe(false);
  });
});