@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/shared/lib/markdown/autolink.test.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { renderMarkdown } from '@/shared/lib/markdown/marked';
+
+describe('autolink vs code span', () => {
+  test('a backticked email stays a code span, not a mailto link', () => {
+    const html = renderMarkdown('addresses (`NNN+login@users.noreply.github.com`) and more');
+    expect(html).toContain('<code class="inline-code">NNN+login@users.noreply.github.com</code>');
+    expect(html).not.toContain('mailto:');
+    expect(html).not.toContain('`');
+  });
+
+  test('a backticked URL stays a code span', () => {
+    const html = renderMarkdown('see `https://bun.sh/docs` for more');
+    expect(html).toContain('<code class="inline-code">https://bun.sh/docs</code>');
+  });
+
+  test('ordinary autolinks are untouched', () => {
+    expect(renderMarkdown('see https://bun.sh/docs for more')).toContain('<a href="https://bun.sh/docs">');
+    expect(renderMarkdown('write to a@b.com now')).toContain('<a href="mailto:a@b.com">');
+  });
+
+  test('a URL next to a code span keeps both', () => {
+    const html = renderMarkdown('https://bun.sh then `npm i`');
+    expect(html).toContain('<a href="https://bun.sh">');
+    expect(html).toContain('<code class="inline-code">npm i</code>');
+  });
+});

package/src/shared/lib/markdown/autolink.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * linkify-it autolinking that yields to code spans.
+ *
+ * linkify-it accepts a backtick as an email local-part character (RFC 5321's
+ * `!#$%&'*+/=?^_`{|}~-` set), so `` `NNN+login@users.noreply.github.com` ``
+ * matches as ONE autolink whose raw text spans both backticks. The extension
+ * runs before marked's own inline rules, so that match is consumed and the code
+ * span never forms: the backticks end up as link text and the href carries
+ * `%60` escapes (`mailto:%60NNN+…%60`) — a broken link AND a code span that
+ * shows its delimiters.
+ *
+ * A code span wins over an autolink in CommonMark, and the inline lexer reaches
+ * the OPENING backtick first — so refusing every match whose raw contains a
+ * backtick is enough to hand that position back to the `codespan` rule, which
+ * then swallows the whole span. Autolinks without a backtick in them are
+ * untouched, which is every ordinary URL and email.
+ */
+
+import type {
+  MarkedExtension,
+  RendererExtension,
+  Token,
+  TokenizerAndRendererExtension,
+  TokenizerThis,
+} from 'marked';
+import markedLinkifyIt from 'marked-linkify-it';
+
+/** Refuse an autolink whose raw text carries a backtick (see the file header). */
+function guardAutolink(
+  extension: TokenizerAndRendererExtension | RendererExtension,
+): TokenizerAndRendererExtension | RendererExtension {
+  if (!('tokenizer' in extension) || !extension.tokenizer) return extension;
+  const tokenize = extension.tokenizer;
+  return {
+    ...extension,
+    tokenizer(this: TokenizerThis, source: string, tokens: Token[]) {
+      const token = tokenize.call(this, source, tokens);
+      return token && !token.raw.includes('`') ? token : undefined;
+    },
+  };
+}
+
+export function codeSafeAutolink(): MarkedExtension {
+  return { extensions: (markedLinkifyIt().extensions ?? []).map(guardAutolink) };
+}

package/src/shared/lib/markdown/directives.ts

@@ -0,0 +1,96 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Plugin DIRECTIVES: a fenced block a plugin can claim and render as its own
+ * component.
+ *
+ * Shared, not client-only, because the PARSER has to emit the placeholder and
+ * the parser is shared — but the parser does not know which plugins exist (the
+ * registry is client state), so it emits the placeholder for anything that
+ * LOOKS like a directive and the renderer decides whether to hydrate it.
+ *
+ * That split is what keeps an unclaimed fence unchanged: the placeholder WRAPS
+ * the ordinary code block rather than replacing it, so a fence no plugin claims
+ * still renders as the code block it always was. The alternative — deciding in
+ * the parser — would mean the server and a plugin-less client produced
+ * different HTML for the same message.
+ */
+
+/** The class a directive's placeholder wrapper carries. */
+export const DIRECTIVE_BLOCK_CLASS = 'plugin-directive-block';
+
+/**
+ * Whether a fence's language token is a directive.
+ *
+ * A COLON is the marker, and it is not arbitrary: `omp:chart` is
+ * namespace-qualified, which is what tells a directive apart from a language a
+ * syntax highlighter should handle. A plain `ts` fence is therefore untouched
+ * by this whole mechanism.
+ */
+export function isDirectiveLanguage(lang: string): boolean {
+  return lang.includes(':');
+}
+
+/**
+ * The `key="value"` pairs from a fence's info line, after the language token.
+ *
+ * Deliberately tolerant: this runs on whatever a message contains, and an
+ * unparseable attribute is dropped rather than failing the render — a message
+ * with a stray quote is still a message.
+ */
+export function parseDirectiveAttributes(info: string): Record<string, string> {
+  const attributes: Record<string, string> = {};
+  const pattern = /([a-zA-Z_][\w-]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s]+))/g;
+  for (const match of info.matchAll(pattern)) {
+    attributes[match[1]] = match[2] ?? match[3] ?? match[4] ?? '';
+  }
+  return attributes;
+}
+
+/** The HTML attribute carrying a directive's name, encoded so `"` cannot end it. */
+export const DIRECTIVE_NAME_ATTR = 'data-plugin-directive';
+
+/** The HTML attribute carrying its parsed attributes, URI-encoded as JSON. */
+export const DIRECTIVE_ATTRS_ATTR = 'data-plugin-directive-attrs';
+
+/**
+ * Wrap a rendered code block as a claimable directive.
+ *
+ * The fallback stays INSIDE, which is what makes "unclaimed renders as before"
+ * a structural property rather than a rule someone has to remember.
+ */
+export function directiveBlockHtml(
+  name: string,
+  attributes: Record<string, string>,
+  fallbackHtml: string,
+): string {
+  const encoded = encodeURIComponent(JSON.stringify(attributes));
+  return (
+    `<div class="${DIRECTIVE_BLOCK_CLASS}" ${DIRECTIVE_NAME_ATTR}="${escapeAttribute(name)}" ` +
+    `${DIRECTIVE_ATTRS_ATTR}="${escapeAttribute(encoded)}">${fallbackHtml}</div>`
+  );
+}
+
+/** Escape a value for an HTML attribute. */
+function escapeAttribute(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/** Read a placeholder's attributes back. A malformed payload answers `{}`. */
+export function readDirectiveAttributes(raw: string | null): Record<string, string> {
+  if (!raw) return {};
+  try {
+    const parsed: unknown = JSON.parse(decodeURIComponent(raw));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    return parsed as Record<string, string>;
+  } catch {
+    return {};
+  }
+}

package/src/shared/lib/markdown/document-urls.test.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { resolveDocumentReference, rewriteDocumentReferences } from '@/shared/lib/markdown/document-urls';
+
+const doc = (path: string, root?: string, repo?: string) => ({ path, root, repo });
+
+describe('resolveDocumentReference', () => {
+  test('resolves beside the document, not beside the app', () => {
+    expect(resolveDocumentReference('docs/hero.png', doc('README.md'))?.path).toBe('docs/hero.png');
+    expect(resolveDocumentReference('img/a.png', doc('docs/guide.md'))?.path).toBe('docs/img/a.png');
+  });
+
+  test('walks out of the document folder', () => {
+    expect(resolveDocumentReference('../README.md', doc('docs/guide.md'))?.path).toBe('README.md');
+    expect(resolveDocumentReference('./a.png', doc('docs/guide.md'))?.path).toBe('docs/a.png');
+  });
+
+  test('a leading slash is the scope root, not the document folder', () => {
+    expect(resolveDocumentReference('/docs/a.png', doc('manual/v2/guide.md'))?.path).toBe('docs/a.png');
+  });
+
+  test('cannot climb above the scope root', () => {
+    expect(resolveDocumentReference('../../../../etc/passwd', doc('README.md'))?.path).toBe('etc/passwd');
+  });
+
+  test('keeps the scope in the raw URL', () => {
+    const resolved = resolveDocumentReference('a.png', doc('docs/guide.md', '/ws', 'projects/x'));
+    expect(resolved?.url).toBe('/api/fs/raw?path=docs%2Fa.png&root=%2Fws&repo=projects%2Fx');
+    // `repo: '.'` means the root itself, so the param is omitted.
+    expect(resolveDocumentReference('a.png', doc('docs/guide.md', '/ws', '.'))?.url)
+      .toBe('/api/fs/raw?path=docs%2Fa.png&root=%2Fws');
+  });
+
+  test('a query or fragment belongs to the reference, not the path', () => {
+    expect(resolveDocumentReference('img/a.png?v=2#frag', doc('docs/guide.md'))?.path).toBe('docs/img/a.png');
+  });
+
+  test('decodes percent escapes', () => {
+    expect(resolveDocumentReference('my%20image.png', doc('README.md'))?.path).toBe('my image.png');
+  });
+
+  test('leaves anything that is not a relative file reference alone', () => {
+    for (const reference of ['https://x.test/a.png', 'mailto:a@b.c', 'data:image/png;base64,AA', '//cdn.test/a.png', '#section', '   ', '']) {
+      expect(resolveDocumentReference(reference, doc('README.md'))).toBeNull();
+    }
+  });
+});
+
+describe('rewriteDocumentReferences', () => {
+  test('points images at the raw route and links at the file they name', () => {
+    expect(rewriteDocumentReferences('<img src="docs/a.png"><a href="AGENTS.md">x</a>', doc('README.md')))
+      .toBe('<img src="/api/fs/raw?path=docs%2Fa.png"><a href="/api/fs/raw?path=AGENTS.md" data-file-path="AGENTS.md">x</a>');
+  });
+
+  test('escapes the query separator so the attribute survives HTML parsing', () => {
+    expect(rewriteDocumentReferences('<img src="a.png">', doc('docs/g.md', '/ws')))
+      .toBe('<img src="/api/fs/raw?path=docs%2Fa.png&amp;root=%2Fws">');
+  });
+
+  test('leaves external references and escaped code untouched', () => {
+    const html = '<a href="https://x.test">x</a><code class="language-html">&lt;img src=&quot;a.png&quot;&gt;</code>';
+    expect(rewriteDocumentReferences(html, doc('README.md'))).toBe(html);
+  });
+});

package/src/shared/lib/markdown/document-urls.ts

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Resolve the relative references of a markdown *document* (an opened file's
+ * preview) to the workspace files they actually name.
+ *
+ * A previewed file is not a chat message: `![](docs/hero.png)` means the image
+ * on disk beside the document, and `[Architecture](AGENTS.md)` means that file.
+ * Neither resolves on its own — the preview is an app route, so a relative URL
+ * is requested from the server's own origin (`/docs/hero.png` → 404, and a
+ * click would navigate the console away from itself). Each one is rewritten to
+ * the workspace file it points at: images through `/api/fs/raw` (real bytes,
+ * real content-type) and links through the same URL plus the resolved path in
+ * `data-file-path`, which the panel turns back into an editor tab.
+ *
+ * Only plain relative references are touched. Anything with a scheme
+ * (`https:`, `mailto:`, `data:`), a protocol-relative `//host`, or a bare
+ * `#anchor` is the document's own business and is left exactly as written.
+ */
+
+import { buildFsRawUrl } from '@/shared/lib/fs/paths';
+
+/**
+ * Where the document lives. `path` is relative to the picked scope exactly the
+ * way `/api/fs/raw` and the file panel read it: relative to `repo` when one is
+ * picked, otherwise to `root`.
+ */
+export interface DocumentScope {
+  path: string;
+  root?: string;
+  repo?: string;
+}
+
+export interface ResolvedDocumentReference {
+  /** Scope-relative path of the referenced file — what an editor tab opens. */
+  path: string;
+  /** Raw-bytes URL of the same file, for an `<img src>` or a middle-click. */
+  url: string;
+}
+
+/** A scheme (`https:`), protocol-relative host, fragment, or empty ref. */
+const ABSOLUTE_REFERENCE_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#|$)/i;
+
+/** Collapse `.`/`..` segments; ascending above the scope root is dropped. */
+function normalizeSegments(segments: string[]): string {
+  const out: string[] = [];
+  for (const segment of segments) {
+    if (!segment || segment === '.') continue;
+    if (segment === '..') {
+      out.pop();
+      continue;
+    }
+    out.push(segment);
+  }
+  return out.join('/');
+}
+
+/** `%20`-style escapes are how a markdown link writes a space. */
+function decodeReference(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Resolve one reference written inside `scope`'s document, or null when it is
+ * not a relative file reference (leave those untouched).
+ */
+export function resolveDocumentReference(
+  reference: string,
+  scope: DocumentScope,
+): ResolvedDocumentReference | null {
+  const raw = reference.trim();
+  if (ABSOLUTE_REFERENCE_RE.test(raw)) return null;
+
+  // `?v=1` and `#section` address the preview, not the file on disk.
+  const withoutQuery = raw.split(/[?#]/)[0];
+  const decoded = decodeReference(withoutQuery);
+  if (!decoded) return null;
+
+  // A leading slash is root-relative (GitHub's repo-root rule), and the scope
+  // frame already IS that root, so it resolves without the document's folder.
+  const rootRelative = /^[/\\]/.test(decoded);
+  const documentDir = scope.path.replace(/\\/g, '/').split('/').slice(0, -1);
+  const segments = decoded.split(/[\\/]+/);
+  const path = normalizeSegments(rootRelative ? segments : [...documentDir, ...segments]);
+  if (!path) return null;
+
+  return { path, url: buildFsRawUrl({ path, root: scope.root, repo: scope.repo }) };
+}
+
+/** Attribute values are injected as HTML, so `&` and `"` must be entities. */
+function escapeAttribute(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+}
+
+/**
+ * Rewrite the relative `src`/`href` attributes of rendered document HTML.
+ * Fenced code is already escaped by the renderer, so a literal `src="` inside
+ * a code block cannot be mistaken for an attribute.
+ */
+export function rewriteDocumentReferences(html: string, scope: DocumentScope): string {
+  return html.replace(/(\s(?:src|href))="([^"]*)"/g, (match, attribute: string, value: string) => {
+    const resolved = resolveDocumentReference(value, scope);
+    if (!resolved) return match;
+    const url = ` ${attribute.trim()}="${escapeAttribute(resolved.url)}"`;
+    // The resolved path rides along on links only: it is what a click opens as
+    // a tab, and a mid-click still has the raw URL to fall back to.
+    return attribute.trim() === 'href'
+      ? `${url} data-file-path="${escapeAttribute(resolved.path)}"`
+      : url;
+  });
+}

package/src/shared/lib/markdown/fira-code-fonts.css

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ * GENERATED — do not edit by hand. Run `bun run scripts/katex-fonts-woff2.mjs`
+ * after upgrading @fontsource/fira-code.
+ *
+ * Fira Code, latin subset, woff2-only, weights 400/500/600/700 — the faces
+ * `main.tsx` imports. Replaces `@fontsource/fira-code/{400,500,600,700}.css`,
+ * which pulled 7 subsets (cyrillic, cyrillic-ext, greek, greek-ext, latin,
+ * latin-ext, symbols2) x 4 weights x 2 formats = 56 files. This console is
+ * English-only, so the other six subsets were dead weight, and the woff
+ * fallback is never fetched by a browser that supports woff2.
+ *
+ * `font-display: swap` and the family/style/weight declarations match upstream,
+ * so text metrics are unchanged.
+ */
+
+@font-face {
+  font-family: 'Fira Code';
+  font-style: normal;
+  font-display: swap;
+  font-weight: 400;
+  src: url('@fontsource/fira-code/files/fira-code-latin-400-normal.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'Fira Code';
+  font-style: normal;
+  font-display: swap;
+  font-weight: 500;
+  src: url('@fontsource/fira-code/files/fira-code-latin-500-normal.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'Fira Code';
+  font-style: normal;
+  font-display: swap;
+  font-weight: 600;
+  src: url('@fontsource/fira-code/files/fira-code-latin-600-normal.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'Fira Code';
+  font-style: normal;
+  font-display: swap;
+  font-weight: 700;
+  src: url('@fontsource/fira-code/files/fira-code-latin-700-normal.woff2') format('woff2');
+}

package/src/shared/lib/markdown/katex-fonts.css

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ * GENERATED — do not edit by hand. Run `bun run scripts/katex-fonts-woff2.mjs`
+ * after upgrading katex.
+ *
+ * KaTeX stylesheet, woff2-only. Upstream `katex/dist/katex.min.css` lists three
+ * sources per @font-face (woff2 -> woff -> truetype); a browser downloads only
+ * the first format it supports, so the woff/truetype files were never
+ * *requested* while still being emitted into dist/client/static/font
+ * (634 kB .woff + 502 kB .ttf). Every src chain below keeps the woff2 source
+ * only — the layout rules are byte-identical to upstream.
+ *
+ * woff2 is supported by Safari 10+, Chrome 36+, Firefox 39+, and Edge 14+;
+ * this app targets modern browsers, so the legacy fallbacks buy nothing.
+ */
+@font-face{font-display:block;font-family:KaTeX_AMS;font-style:normal;font-weight:400;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_AMS-Regular.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Caligraphic;font-style:normal;font-weight:700;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Caligraphic-Bold.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Caligraphic;font-style:normal;font-weight:400;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Caligraphic-Regular.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Fraktur;font-style:normal;font-weight:700;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Fraktur-Bold.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Fraktur;font-style:normal;font-weight:400;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Fraktur-Regular.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Main;font-style:normal;font-weight:700;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Main-Bold.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Main;font-style:italic;font-weight:700;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Main-BoldItalic.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Main;font-style:italic;font-weight:400;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Main-Italic.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Main;font-style:normal;font-weight:400;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Main-Regular.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Math;font-style:italic;font-weight:700;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Math-BoldItalic.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Math;font-style:italic;font-weight:400;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Math-Italic.woff2") format("woff2")}@font-face{font-display:block;font-family:"KaTeX_SansSerif";font-style:normal;font-weight:700;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_SansSerif-Bold.woff2") format("woff2")}@font-face{font-display:block;font-family:"KaTeX_SansSerif";font-style:italic;font-weight:400;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_SansSerif-Italic.woff2") format("woff2")}@font-face{font-display:block;font-family:"KaTeX_SansSerif";font-style:normal;font-weight:400;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_SansSerif-Regular.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Script;font-style:normal;font-weight:400;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Script-Regular.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Size1;font-style:normal;font-weight:400;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Size1-Regular.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Size2;font-style:normal;font-weight:400;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Size2-Regular.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Size3;font-style:normal;font-weight:400;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Size3-Regular.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Size4;font-style:normal;font-weight:400;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Size4-Regular.woff2") format("woff2")}@font-face{font-display:block;font-family:KaTeX_Typewriter;font-style:normal;font-weight:400;src:url("../../../../node_modules/katex/dist/fonts/KaTeX_Typewriter-Regular.woff2") format("woff2")}.katex{font:normal 1.21em KaTeX_Main,Times New Roman,serif;line-height:1.2;position:relative;text-indent:0;text-rendering:auto}.katex *{-ms-high-contrast-adjust:none!important;border-color:currentColor}.katex .katex-version:after{content:"0.18.7"}.katex .katex-mathml{border:0;-webkit-clip-path:inset(50%);clip-path:inset(50%);height:1px;overflow:hidden;padding:0;position:absolute;width:1px}.katex .katex-html>.katex-newline{display:block}.katex .katex-base{position:relative;white-space:nowrap;width:-webkit-min-content;width:-moz-min-content;width:min-content}.katex .katex-base,.katex .katex-strut{display:inline-block}.katex .textbf{font-weight:700}.katex .textit{font-style:italic}.katex .textrm{font-family:KaTeX_Main}.katex .textsf{font-family:KaTeX_SansSerif}.katex .texttt{font-family:KaTeX_Typewriter}.katex .mathnormal{font-family:KaTeX_Math;font-style:italic}.katex .mathit{font-family:KaTeX_Main;font-style:italic}.katex .mathrm{font-style:normal}.katex .mathbf{font-family:KaTeX_Main;font-weight:700}.katex .boldsymbol{font-family:KaTeX_Math;font-style:italic;font-weight:700}.katex .amsrm,.katex .mathbb,.katex .textbb{font-family:KaTeX_AMS}.katex .mathcal{font-family:KaTeX_Caligraphic}.katex .mathfrak,.katex .textfrak{font-family:KaTeX_Fraktur}.katex .mathboldfrak,.katex .textboldfrak{font-family:KaTeX_Fraktur;font-weight:700}.katex .mathtt{font-family:KaTeX_Typewriter}.katex .mathscr,.katex .textscr{font-family:KaTeX_Script}.katex .mathsf,.katex .textsf{font-family:KaTeX_SansSerif}.katex .mathboldsf,.katex .textboldsf{font-family:KaTeX_SansSerif;font-weight:700}.katex .mathitsf,.katex .mathsfit,.katex .textitsf{font-family:KaTeX_SansSerif;font-style:italic}.katex .mainrm{font-family:KaTeX_Main;font-style:normal}.katex .vlist-t{border-collapse:collapse;display:inline-table;table-layout:fixed}.katex .vlist-r{display:table-row}.katex .vlist{display:table-cell;position:relative;vertical-align:bottom}.katex .vlist>span{display:block;height:0;position:relative}.katex .vlist>span>span{display:inline-block}.katex .vlist>span>.pstrut{overflow:hidden;width:0}.katex .vlist-t2{margin-right:-2px}.katex .vlist-s{display:table-cell;font-size:1px;min-width:2px;vertical-align:bottom;width:2px}.katex .katex-vbox{align-items:baseline;display:inline-flex;flex-direction:column}.katex .katex-thinbox{display:inline-flex;flex-direction:row;max-width:0;width:0}.katex .msupsub{text-align:left}.katex .mfrac>span>span{text-align:center}.katex .mfrac .frac-line{border-bottom-style:solid;display:inline-block;width:100%}.katex .katex-hdashline,.katex .katex-hline,.katex .katex-overline .overline-line,.katex .katex-rule,.katex .katex-underline .underline-line,.katex .mfrac .frac-line{min-height:1px}.katex .mspace{display:inline-block}.katex .katex-smash{display:inline;line-height:0}.katex .clap,.katex .llap,.katex .rlap{position:relative;width:0}.katex .clap>.katex-inner,.katex .llap>.katex-inner,.katex .rlap>.katex-inner{position:absolute}.katex .clap>.katex-fix,.katex .llap>.katex-fix,.katex .rlap>.katex-fix{display:inline-block}.katex .llap>.katex-inner{right:0}.katex .clap>.katex-inner,.katex .rlap>.katex-inner{left:0}.katex .clap>.katex-inner>span{margin-left:-50%;margin-right:50%}.katex .katex-rule{border:0 solid;display:inline-block;position:relative}.katex .katex-hline,.katex .katex-overline .overline-line,.katex .katex-underline .underline-line{border-bottom-style:solid;display:inline-block;width:100%}.katex .katex-hdashline{border-bottom-style:dashed;display:inline-block;width:100%}.katex .sqrt>.katex-root{margin-left:.2777777778em;margin-right:-.5555555556em}.katex .fontsize-ensurer.reset-size1.size1,.katex .katex-sizing.reset-size1.size1{font-size:1em}.katex .fontsize-ensurer.reset-size1.size2,.katex .katex-sizing.reset-size1.size2{font-size:1.2em}.katex .fontsize-ensurer.reset-size1.size3,.katex .katex-sizing.reset-size1.size3{font-size:1.4em}.katex .fontsize-ensurer.reset-size1.size4,.katex .katex-sizing.reset-size1.size4{font-size:1.6em}.katex .fontsize-ensurer.reset-size1.size5,.katex .katex-sizing.reset-size1.size5{font-size:1.8em}.katex .fontsize-ensurer.reset-size1.size6,.katex .katex-sizing.reset-size1.size6{font-size:2em}.katex .fontsize-ensurer.reset-size1.size7,.katex .katex-sizing.reset-size1.size7{font-size:2.4em}.katex .fontsize-ensurer.reset-size1.size8,.katex .katex-sizing.reset-size1.size8{font-size:2.88em}.katex .fontsize-ensurer.reset-size1.size9,.katex .katex-sizing.reset-size1.size9{font-size:3.456em}.katex .fontsize-ensurer.reset-size1.size10,.katex .katex-sizing.reset-size1.size10{font-size:4.148em}.katex .fontsize-ensurer.reset-size1.size11,.katex .katex-sizing.reset-size1.size11{font-size:4.976em}.katex .fontsize-ensurer.reset-size2.size1,.katex .katex-sizing.reset-size2.size1{font-size:.8333333333em}.katex .fontsize-ensurer.reset-size2.size2,.katex .katex-sizing.reset-size2.size2{font-size:1em}.katex .fontsize-ensurer.reset-size2.size3,.katex .katex-sizing.reset-size2.size3{font-size:1.1666666667em}.katex .fontsize-ensurer.reset-size2.size4,.katex .katex-sizing.reset-size2.size4{font-size:1.3333333333em}.katex .fontsize-ensurer.reset-size2.size5,.katex .katex-sizing.reset-size2.size5{font-size:1.5em}.katex .fontsize-ensurer.reset-size2.size6,.katex .katex-sizing.reset-size2.size6{font-size:1.6666666667em}.katex .fontsize-ensurer.reset-size2.size7,.katex .katex-sizing.reset-size2.size7{font-size:2em}.katex .fontsize-ensurer.reset-size2.size8,.katex .katex-sizing.reset-size2.size8{font-size:2.4em}.katex .fontsize-ensurer.reset-size2.size9,.katex .katex-sizing.reset-size2.size9{font-size:2.88em}.katex .fontsize-ensurer.reset-size2.size10,.katex .katex-sizing.reset-size2.size10{font-size:3.4566666667em}.katex .fontsize-ensurer.reset-size2.size11,.katex .katex-sizing.reset-size2.size11{font-size:4.1466666667em}.katex .fontsize-ensurer.reset-size3.size1,.katex .katex-sizing.reset-size3.size1{font-size:.7142857143em}.katex .fontsize-ensurer.reset-size3.size2,.katex .katex-sizing.reset-size3.size2{font-size:.8571428571em}.katex .fontsize-ensurer.reset-size3.size3,.katex .katex-sizing.reset-size3.size3{font-size:1em}.katex .fontsize-ensurer.reset-size3.size4,.katex .katex-sizing.reset-size3.size4{font-size:1.1428571429em}.katex .fontsize-ensurer.reset-size3.size5,.katex .katex-sizing.reset-size3.size5{font-size:1.2857142857em}.katex .fontsize-ensurer.reset-size3.size6,.katex .katex-sizing.reset-size3.size6{font-size:1.4285714286em}.katex .fontsize-ensurer.reset-size3.size7,.katex .katex-sizing.reset-size3.size7{font-size:1.7142857143em}.katex .fontsize-ensurer.reset-size3.size8,.katex .katex-sizing.reset-size3.size8{font-size:2.0571428571em}.katex .fontsize-ensurer.reset-size3.size9,.katex .katex-sizing.reset-size3.size9{font-size:2.4685714286em}.katex .fontsize-ensurer.reset-size3.size10,.katex .katex-sizing.reset-size3.size10{font-size:2.9628571429em}.katex .fontsize-ensurer.reset-size3.size11,.katex .katex-sizing.reset-size3.size11{font-size:3.5542857143em}.katex .fontsize-ensurer.reset-size4.size1,.katex .katex-sizing.reset-size4.size1{font-size:.625em}.katex .fontsize-ensurer.reset-size4.size2,.katex .katex-sizing.reset-size4.size2{font-size:.75em}.katex .fontsize-ensurer.reset-size4.size3,.katex .katex-sizing.reset-size4.size3{font-size:.875em}.katex .fontsize-ensurer.reset-size4.size4,.katex .katex-sizing.reset-size4.size4{font-size:1em}.katex .fontsize-ensurer.reset-size4.size5,.katex .katex-sizing.reset-size4.size5{font-size:1.125em}.katex .fontsize-ensurer.reset-size4.size6,.katex .katex-sizing.reset-size4.size6{font-size:1.25em}.katex .fontsize-ensurer.reset-size4.size7,.katex .katex-sizing.reset-size4.size7{font-size:1.5em}.katex .fontsize-ensurer.reset-size4.size8,.katex .katex-sizing.reset-size4.size8{font-size:1.8em}.katex .fontsize-ensurer.reset-size4.size9,.katex .katex-sizing.reset-size4.size9{font-size:2.16em}.katex .fontsize-ensurer.reset-size4.size10,.katex .katex-sizing.reset-size4.size10{font-size:2.5925em}.katex .fontsize-ensurer.reset-size4.size11,.katex .katex-sizing.reset-size4.size11{font-size:3.11em}.katex .fontsize-ensurer.reset-size5.size1,.katex .katex-sizing.reset-size5.size1{font-size:.5555555556em}.katex .fontsize-ensurer.reset-size5.size2,.katex .katex-sizing.reset-size5.size2{font-size:.6666666667em}.katex .fontsize-ensurer.reset-size5.size3,.katex .katex-sizing.reset-size5.size3{font-size:.7777777778em}.katex .fontsize-ensurer.reset-size5.size4,.katex .katex-sizing.reset-size5.size4{font-size:.8888888889em}.katex .fontsize-ensurer.reset-size5.size5,.katex .katex-sizing.reset-size5.size5{font-size:1em}.katex .fontsize-ensurer.reset-size5.size6,.katex .katex-sizing.reset-size5.size6{font-size:1.1111111111em}.katex .fontsize-ensurer.reset-size5.size7,.katex .katex-sizing.reset-size5.size7{font-size:1.3333333333em}.katex .fontsize-ensurer.reset-size5.size8,.katex .katex-sizing.reset-size5.size8{font-size:1.6em}.katex .fontsize-ensurer.reset-size5.size9,.katex .katex-sizing.reset-size5.size9{font-size:1.92em}.katex .fontsize-ensurer.reset-size5.size10,.katex .katex-sizing.reset-size5.size10{font-size:2.3044444444em}.katex .fontsize-ensurer.reset-size5.size11,.katex .katex-sizing.reset-size5.size11{font-size:2.7644444444em}.katex .fontsize-ensurer.reset-size6.size1,.katex .katex-sizing.reset-size6.size1{font-size:.5em}.katex .fontsize-ensurer.reset-size6.size2,.katex .katex-sizing.reset-size6.size2{font-size:.6em}.katex .fontsize-ensurer.reset-size6.size3,.katex .katex-sizing.reset-size6.size3{font-size:.7em}.katex .fontsize-ensurer.reset-size6.size4,.katex .katex-sizing.reset-size6.size4{font-size:.8em}.katex .fontsize-ensurer.reset-size6.size5,.katex .katex-sizing.reset-size6.size5{font-size:.9em}.katex .fontsize-ensurer.reset-size6.size6,.katex .katex-sizing.reset-size6.size6{font-size:1em}.katex .fontsize-ensurer.reset-size6.size7,.katex .katex-sizing.reset-size6.size7{font-size:1.2em}.katex .fontsize-ensurer.reset-size6.size8,.katex .katex-sizing.reset-size6.size8{font-size:1.44em}.katex .fontsize-ensurer.reset-size6.size9,.katex .katex-sizing.reset-size6.size9{font-size:1.728em}.katex .fontsize-ensurer.reset-size6.size10,.katex .katex-sizing.reset-size6.size10{font-size:2.074em}.katex .fontsize-ensurer.reset-size6.size11,.katex .katex-sizing.reset-size6.size11{font-size:2.488em}.katex .fontsize-ensurer.reset-size7.size1,.katex .katex-sizing.reset-size7.size1{font-size:.4166666667em}.katex .fontsize-ensurer.reset-size7.size2,.katex .katex-sizing.reset-size7.size2{font-size:.5em}.katex .fontsize-ensurer.reset-size7.size3,.katex .katex-sizing.reset-size7.size3{font-size:.5833333333em}.katex .fontsize-ensurer.reset-size7.size4,.katex .katex-sizing.reset-size7.size4{font-size:.6666666667em}.katex .fontsize-ensurer.reset-size7.size5,.katex .katex-sizing.reset-size7.size5{font-size:.75em}.katex .fontsize-ensurer.reset-size7.size6,.katex .katex-sizing.reset-size7.size6{font-size:.8333333333em}.katex .fontsize-ensurer.reset-size7.size7,.katex .katex-sizing.reset-size7.size7{font-size:1em}.katex .fontsize-ensurer.reset-size7.size8,.katex .katex-sizing.reset-size7.size8{font-size:1.2em}.katex .fontsize-ensurer.reset-size7.size9,.katex .katex-sizing.reset-size7.size9{font-size:1.44em}.katex .fontsize-ensurer.reset-size7.size10,.katex .katex-sizing.reset-size7.size10{font-size:1.7283333333em}.katex .fontsize-ensurer.reset-size7.size11,.katex .katex-sizing.reset-size7.size11{font-size:2.0733333333em}.katex .fontsize-ensurer.reset-size8.size1,.katex .katex-sizing.reset-size8.size1{font-size:.3472222222em}.katex .fontsize-ensurer.reset-size8.size2,.katex .katex-sizing.reset-size8.size2{font-size:.4166666667em}.katex .fontsize-ensurer.reset-size8.size3,.katex .katex-sizing.reset-size8.size3{font-size:.4861111111em}.katex .fontsize-ensurer.reset-size8.size4,.katex .katex-sizing.reset-size8.size4{font-size:.5555555556em}.katex .fontsize-ensurer.reset-size8.size5,.katex .katex-sizing.reset-size8.size5{font-size:.625em}.katex .fontsize-ensurer.reset-size8.size6,.katex .katex-sizing.reset-size8.size6{font-size:.6944444444em}.katex .fontsize-ensurer.reset-size8.size7,.katex .katex-sizing.reset-size8.size7{font-size:.8333333333em}.katex .fontsize-ensurer.reset-size8.size8,.katex .katex-sizing.reset-size8.size8{font-size:1em}.katex .fontsize-ensurer.reset-size8.size9,.katex .katex-sizing.reset-size8.size9{font-size:1.2em}.katex .fontsize-ensurer.reset-size8.size10,.katex .katex-sizing.reset-size8.size10{font-size:1.4402777778em}.katex .fontsize-ensurer.reset-size8.size11,.katex .katex-sizing.reset-size8.size11{font-size:1.7277777778em}.katex .fontsize-ensurer.reset-size9.size1,.katex .katex-sizing.reset-size9.size1{font-size:.2893518519em}.katex .fontsize-ensurer.reset-size9.size2,.katex .katex-sizing.reset-size9.size2{font-size:.3472222222em}.katex .fontsize-ensurer.reset-size9.size3,.katex .katex-sizing.reset-size9.size3{font-size:.4050925926em}.katex .fontsize-ensurer.reset-size9.size4,.katex .katex-sizing.reset-size9.size4{font-size:.462962963em}.katex .fontsize-ensurer.reset-size9.size5,.katex .katex-sizing.reset-size9.size5{font-size:.5208333333em}.katex .fontsize-ensurer.reset-size9.size6,.katex .katex-sizing.reset-size9.size6{font-size:.5787037037em}.katex .fontsize-ensurer.reset-size9.size7,.katex .katex-sizing.reset-size9.size7{font-size:.6944444444em}.katex .fontsize-ensurer.reset-size9.size8,.katex .katex-sizing.reset-size9.size8{font-size:.8333333333em}.katex .fontsize-ensurer.reset-size9.size9,.katex .katex-sizing.reset-size9.size9{font-size:1em}.katex .fontsize-ensurer.reset-size9.size10,.katex .katex-sizing.reset-size9.size10{font-size:1.2002314815em}.katex .fontsize-ensurer.reset-size9.size11,.katex .katex-sizing.reset-size9.size11{font-size:1.4398148148em}.katex .fontsize-ensurer.reset-size10.size1,.katex .katex-sizing.reset-size10.size1{font-size:.2410800386em}.katex .fontsize-ensurer.reset-size10.size2,.katex .katex-sizing.reset-size10.size2{font-size:.2892960463em}.katex .fontsize-ensurer.reset-size10.size3,.katex .katex-sizing.reset-size10.size3{font-size:.337512054em}.katex .fontsize-ensurer.reset-size10.size4,.katex .katex-sizing.reset-size10.size4{font-size:.3857280617em}.katex .fontsize-ensurer.reset-size10.size5,.katex .katex-sizing.reset-size10.size5{font-size:.4339440694em}.katex .fontsize-ensurer.reset-size10.size6,.katex .katex-sizing.reset-size10.size6{font-size:.4821600771em}.katex .fontsize-ensurer.reset-size10.size7,.katex .katex-sizing.reset-size10.size7{font-size:.5785920926em}.katex .fontsize-ensurer.reset-size10.size8,.katex .katex-sizing.reset-size10.size8{font-size:.6943105111em}.katex .fontsize-ensurer.reset-size10.size9,.katex .katex-sizing.reset-size10.size9{font-size:.8331726133em}.katex .fontsize-ensurer.reset-size10.size10,.katex .katex-sizing.reset-size10.size10{font-size:1em}.katex .fontsize-ensurer.reset-size10.size11,.katex .katex-sizing.reset-size10.size11{font-size:1.1996142719em}.katex .fontsize-ensurer.reset-size11.size1,.katex .katex-sizing.reset-size11.size1{font-size:.2009646302em}.katex .fontsize-ensurer.reset-size11.size2,.katex .katex-sizing.reset-size11.size2{font-size:.2411575563em}.katex .fontsize-ensurer.reset-size11.size3,.katex .katex-sizing.reset-size11.size3{font-size:.2813504823em}.katex .fontsize-ensurer.reset-size11.size4,.katex .katex-sizing.reset-size11.size4{font-size:.3215434084em}.katex .fontsize-ensurer.reset-size11.size5,.katex .katex-sizing.reset-size11.size5{font-size:.3617363344em}.katex .fontsize-ensurer.reset-size11.size6,.katex .katex-sizing.reset-size11.size6{font-size:.4019292605em}.katex .fontsize-ensurer.reset-size11.size7,.katex .katex-sizing.reset-size11.size7{font-size:.4823151125em}.katex .fontsize-ensurer.reset-size11.size8,.katex .katex-sizing.reset-size11.size8{font-size:.578778135em}.katex .fontsize-ensurer.reset-size11.size9,.katex .katex-sizing.reset-size11.size9{font-size:.6945337621em}.katex .fontsize-ensurer.reset-size11.size10,.katex .katex-sizing.reset-size11.size10{font-size:.8336012862em}.katex .fontsize-ensurer.reset-size11.size11,.katex .katex-sizing.reset-size11.size11{font-size:1em}.katex .delimsizing.size1{font-family:KaTeX_Size1}.katex .delimsizing.size2{font-family:KaTeX_Size2}.katex .delimsizing.size3{font-family:KaTeX_Size3}.katex .delimsizing.size4{font-family:KaTeX_Size4}.katex .delimsizing.mult .delim-size1>span{font-family:KaTeX_Size1}.katex .delimsizing.mult .delim-size4>span{font-family:KaTeX_Size4}.katex .nulldelimiter{display:inline-block;width:.12em}.katex .delimcenter,.katex .op-symbol{position:relative}.katex .op-symbol.small-op{font-family:KaTeX_Size1}.katex .op-symbol.large-op{font-family:KaTeX_Size2}.katex .katex-accent>.vlist-t,.katex .op-limits>.vlist-t{text-align:center}.katex .katex-accent .accent-body{position:relative}.katex .katex-accent .accent-body:not(.accent-full){width:0}.katex .katex-overlay{display:block}.katex .mtable .vertical-separator{display:inline-block;min-width:1px}.katex .mtable .arraycolsep{display:inline-block}.katex .mtable .col-align-c>.vlist-t{text-align:center}.katex .mtable .col-align-l>.vlist-t{text-align:left}.katex .mtable .col-align-r>.vlist-t{text-align:right}.katex .svg-align{text-align:left}.katex svg{fill:currentColor;stroke:currentColor;display:block;height:inherit;position:absolute;width:100%}.katex svg path{stroke:none}.katex svg{fill-rule:nonzero;fill-opacity:1;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1}.katex img{border-style:none;max-height:none;max-width:none;min-height:0;min-width:0}.katex .katex-stretchy{display:block;overflow:hidden;position:relative;width:100%}.katex .katex-stretchy:after,.katex .katex-stretchy:before{content:""}.katex .hide-tail{overflow:hidden;position:relative;width:100%}.katex .halfarrow-left{left:0;overflow:hidden;position:absolute;width:50.2%}.katex .halfarrow-right{overflow:hidden;position:absolute;right:0;width:50.2%}.katex .brace-left{left:0;overflow:hidden;position:absolute;width:25.1%}.katex .brace-center{left:25%;overflow:hidden;position:absolute;width:50%}.katex .brace-right{overflow:hidden;position:absolute;right:0;width:25.1%}.katex .x-arrow-pad{padding:0 .5em}.katex .cd-arrow-pad{padding:0 .55556em 0 .27778em}.katex .mover,.katex .munder,.katex .x-arrow{text-align:center}.katex .boxpad{padding:0 .3em}.katex .fbox,.katex .fcolorbox{border:.04em solid;box-sizing:border-box}.katex .cancel-pad{padding:0 .2em}.katex .cancel-lap{margin-left:-.2em;margin-right:-.2em}.katex .katex-sout{border-bottom-style:solid;border-bottom-width:.08em}.katex .angl{border-right:.049em solid;border-top:.049em solid;box-sizing:border-box;margin-right:.03889em}.katex .anglpad{padding:0 .03889em}.katex .reflectbox{display:inline-block;transform:scaleX(-1)}.katex .eqn-num:before{content:"(" counter(katexEqnNo) ")";counter-increment:katexEqnNo}.katex .mml-eqn-num:before{content:"(" counter(mmlEqnNo) ")";counter-increment:mmlEqnNo}.katex .mtr-glue{width:50%}.katex .cd-vert-arrow{display:inline-block;position:relative}.katex .cd-label-left{display:inline-block;position:absolute;right:calc(50% + .3em);text-align:left}.katex .cd-label-right{display:inline-block;left:calc(50% + .3em);position:absolute;text-align:right}.katex-display{display:block;margin:1em 0;text-align:center}.katex-display>.katex{display:block;text-align:center;white-space:nowrap}.katex-display>.katex>.katex-html{display:block;position:relative}.katex-display>.katex>.katex-html>.katex-tag{position:absolute;right:0}.katex-display.leqno>.katex>.katex-html>.katex-tag{left:0;right:auto}.katex-display.fleqn>.katex{padding-left:2em;text-align:left}body{counter-reset:katexEqnNo mmlEqnNo}

package/src/shared/lib/markdown/katex.ts

@@ -0,0 +1,111 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Demand-driven KaTeX rendering.
+ *
+ * `katex` is ~522 kB of JS that only matters when a message actually contains
+ * math. Importing it statically from `marked.ts` put it in the *synchronous*
+ * bundle: every page load paid for it, whether or not a single formula was ever
+ * displayed.
+ *
+ * The pipeline keeps its synchronous shape by emitting a placeholder instead:
+ * `marked.ts` renders `<span class="math-pending" data-math="…">` during parse,
+ * and this module swaps those placeholders for real KaTeX markup once the
+ * library lands — the same split `mermaid.ts` uses for ```mermaid fences, so
+ * the two features behave identically from the renderer's point of view.
+ */
+
+import { sanitizeKatexHtml } from '@/shared/lib/markdown/sanitize';
+
+type KatexModule = typeof import('katex');
+
+let katexPromise: Promise<KatexModule['default'] | null> | null = null;
+
+/** Placeholder class emitted by `marked.ts` in place of rendered math. */
+export const MATH_PENDING_CLASS = 'math-pending';
+
+/**
+ * Load KaTeX once per page. Never throws: on failure the promise resolves
+ * `null` and placeholders stay as visible source text, which is what the old
+ * synchronous `renderKatex` fallback did for invalid LaTeX.
+ */
+function loadKatex(): Promise<KatexModule['default'] | null> {
+  if (!katexPromise) {
+    katexPromise = import('katex')
+      .then((mod) => mod.default)
+      .catch((error) => {
+        console.error('[katex] load failed', error);
+        return null;
+      });
+  }
+  return katexPromise;
+}
+
+/**
+ * Start loading KaTeX without awaiting it. Called from the renderer so the
+ * library is already in flight while the rest of the message renders.
+ */
+export function preloadKatex(): void {
+  void loadKatex();
+}
+
+/**
+ * Render one placeholder element into real KaTeX markup. `displayMode` is
+ * carried on the placeholder as `data-math-display` ("1" for block math).
+ *
+ * The generated markup is passed through DOMPurify's MathML profile before it
+ * touches the DOM: `tex` is model output, so although KaTeX escapes its own
+ * output, the result still crosses an innerHTML boundary and gets sanitized
+ * like every other model-authored fragment in this pipeline.
+ */
+function renderPlaceholder(el: HTMLElement, katex: KatexModule['default']): void {
+  // `marked.ts` percent-encodes the payload, the way a mermaid block carries
+  // its source: the TeX must survive the HTML attribute round-trip untouched,
+  // and escaping it as HTML double-encoded every formula the prose escaper had
+  // already touched. A malformed payload degrades to the raw attribute.
+  const encoded = el.dataset.math ?? '';
+  let tex = encoded;
+  try {
+    tex = decodeURIComponent(encoded);
+  } catch {
+    // Leave `tex` as the literal attribute text.
+  }
+  const displayMode = el.dataset.mathDisplay === '1';
+  try {
+    el.innerHTML = sanitizeKatexHtml(katex.renderToString(tex, { throwOnError: false, displayMode }));
+    el.classList.remove(MATH_PENDING_CLASS);
+    el.removeAttribute('data-math');
+    el.removeAttribute('data-math-display');
+  } catch {
+    // Keep the source text visible rather than blanking the formula.
+    el.textContent = tex;
+    el.classList.remove(MATH_PENDING_CLASS);
+  }
+}
+
+/**
+ * Replace every pending math placeholder under `root` with KaTeX output.
+ * Loads the library on demand; resolves with how many were rendered.
+ */
+export async function hydrateMathBlocks(root: ParentNode): Promise<{ rendered: number; failed: number }> {
+  const pending = [...root.querySelectorAll<HTMLElement>(`.${MATH_PENDING_CLASS}`)];
+  if (pending.length === 0) return { rendered: 0, failed: 0 };
+
+  const katex = await loadKatex();
+  if (!katex) return { rendered: 0, failed: pending.length };
+
+  let rendered = 0;
+  for (const el of pending) {
+    // A streaming re-render may have replaced the node while awaiting.
+    if (!el.isConnected) continue;
+    renderPlaceholder(el, katex);
+    rendered += 1;
+  }
+  return { rendered, failed: 0 };
+}
+
+/** Sanitize KaTeX-generated markup (kept here so callers need one import). */
+export { sanitizeKatexHtml };