flux-md 0.3.1

package/src/html-to-react.ts

@@ -0,0 +1,282 @@
+import { createElement, type ReactNode } from "react";
+import type { Components } from "./types";
+
+// HTML void elements: no closing tag, never have children.
+const VOID = new Set([
+  "area", "base", "br", "col", "embed", "hr", "img", "input",
+  "link", "meta", "param", "source", "track", "wbr",
+]);
+
+// Attribute name → React prop name, for the handful that differ. Anything not
+// listed passes through verbatim (React forwards data-*/aria-* and lowercase
+// attributes unchanged).
+const ATTR_MAP: Record<string, string> = {
+  class: "className",
+  for: "htmlFor",
+  colspan: "colSpan",
+  rowspan: "rowSpan",
+  tabindex: "tabIndex",
+  maxlength: "maxLength",
+  minlength: "minLength",
+  readonly: "readOnly",
+  autocomplete: "autoComplete",
+  autofocus: "autoFocus",
+  spellcheck: "spellCheck",
+  contenteditable: "contentEditable",
+  crossorigin: "crossOrigin",
+  enterkeyhint: "enterKeyHint",
+  inputmode: "inputMode",
+};
+
+// URL-bearing attributes whose value must be scheme-checked. `htmlToReact` is
+// exported and may be handed untrusted HTML directly; React happily renders a
+// `javascript:` href (it only warns), so we neutralize it here as
+// defense-in-depth — the core's own output is already sanitized.
+const URL_ATTRS = new Set(["href", "src", "xlink:href", "formaction", "action", "poster", "data"]);
+
+/** Replace a dangerous-scheme URL with "#". Mirrors the Rust `is_dangerous_scheme`:
+ *  strip control chars (C0, DEL, C1 — matching Rust char::is_control),
+ *  lowercase, then match. The strip affects only the probe, never output. */
+function safeUrl(value: string): string {
+  // eslint-disable-next-line no-control-regex
+  const probe = value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").replace(/^\s+/, "").toLowerCase();
+  if (
+    probe.startsWith("javascript:") ||
+    probe.startsWith("vbscript:") ||
+    probe.startsWith("data:text/html") ||
+    probe.startsWith("data:text/javascript")
+  ) {
+    return "#";
+  }
+  return value;
+}
+
+type HNode =
+  | { kind: "text"; text: string }
+  | { kind: "el"; tag: string; attrs: Record<string, string | true>; children: HNode[] };
+
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ",
+  copy: "©", reg: "®", hellip: "…", mdash: "—", ndash: "–",
+};
+
+/** Decode the (small, known) set of entities the core emits, plus numeric refs. */
+export function decodeEntities(s: string): string {
+  if (s.indexOf("&") === -1) return s;
+  return s.replace(/&(#x[0-9a-fA-F]+|#\d+|[a-zA-Z][a-zA-Z0-9]*);/g, (m, body: string) => {
+    if (body[0] === "#") {
+      const code = body[1] === "x" || body[1] === "X"
+        ? parseInt(body.slice(2), 16)
+        : parseInt(body.slice(1), 10);
+      if (Number.isNaN(code) || code < 0 || code > 0x10ffff) return m;
+      try {
+        return String.fromCodePoint(code);
+      } catch {
+        return m;
+      }
+    }
+    const named = NAMED_ENTITIES[body];
+    return named === undefined ? m : named;
+  });
+}
+
+/**
+ * Parse an inline CSS string (`"text-align:left;color:red"`) into the object
+ * React's `style` prop requires, camelCasing property names. Custom properties
+ * (`--x`) keep their literal name.
+ */
+export function parseStyle(css: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const decl of css.split(";")) {
+    const c = decl.indexOf(":");
+    if (c === -1) continue;
+    const rawName = decl.slice(0, c).trim();
+    const value = decl.slice(c + 1).trim();
+    if (!rawName || !value) continue;
+    const name = rawName.startsWith("--")
+      ? rawName
+      : rawName.toLowerCase().replace(/-([a-z])/g, (_, ch: string) => ch.toUpperCase());
+    out[name] = value;
+  }
+  return out;
+}
+
+/** Parse one opening tag starting at `start` (the `<`). */
+function parseOpenTag(html: string, start: number) {
+  let i = start + 1;
+  let j = i;
+  while (j < html.length && /[a-zA-Z0-9-]/.test(html[j])) j++;
+  const tag = html.slice(i, j).toLowerCase();
+  i = j;
+  const attrs: Record<string, string | true> = {};
+  while (i < html.length) {
+    const loopStart = i;
+    while (i < html.length && /\s/.test(html[i])) i++;
+    if (html[i] === ">") return { tag, attrs, selfClose: false, next: i + 1 };
+    if (html[i] === "/" && html[i + 1] === ">") return { tag, attrs, selfClose: true, next: i + 2 };
+    if (i >= html.length) break;
+    let k = i;
+    while (k < html.length && !/[\s=>/]/.test(html[k])) k++;
+    const name = html.slice(i, k);
+    i = k;
+    while (i < html.length && /\s/.test(html[i])) i++;
+    if (html[i] === "=") {
+      i++;
+      while (i < html.length && /\s/.test(html[i])) i++;
+      let value = "";
+      const q = html[i];
+      if (q === '"' || q === "'") {
+        i++;
+        const e = html.indexOf(q, i);
+        value = html.slice(i, e === -1 ? html.length : e);
+        i = e === -1 ? html.length : e + 1;
+      } else {
+        let v = i;
+        while (v < html.length && !/[\s>]/.test(html[v])) v++;
+        value = html.slice(i, v);
+        i = v;
+      }
+      if (name) attrs[name] = decodeEntities(value);
+    } else if (name) {
+      attrs[name] = true; // boolean attribute (e.g. checked, disabled)
+    }
+    // Guarantee forward progress on malformed input (e.g. a stray '/').
+    if (i <= loopStart) i = loopStart + 1;
+  }
+  return { tag, attrs, selfClose: false, next: i };
+}
+
+/**
+ * Tokenize **trusted** HTML (the kind flux-md's core emits: well-formed,
+ * entity-escaped, allowlisted) into a small node tree. This is deliberately not
+ * a defensive HTML5 parser — the threat model is "our own serializer output",
+ * not hostile markup. Unrecognized constructs (comments, doctype) are skipped.
+ */
+// Instrumentation: how many times the tokenizer has run. Used by tests to
+// prove open blocks and the no-override fast path never reach the parser, and
+// that memoized closed blocks parse exactly once. Negligible cost in prod.
+let parseCount = 0;
+export function getParseCount(): number {
+  return parseCount;
+}
+export function resetParseCount(): void {
+  parseCount = 0;
+}
+
+export function parseTrustedHtml(html: string): HNode[] {
+  parseCount++;
+  const root: HNode[] = [];
+  const stack: Array<Extract<HNode, { kind: "el" }>> = [];
+  let i = 0;
+  const push = (n: HNode) => {
+    if (stack.length) stack[stack.length - 1].children.push(n);
+    else root.push(n);
+  };
+  while (i < html.length) {
+    const lt = html.indexOf("<", i);
+    if (lt === -1) {
+      const t = html.slice(i);
+      if (t) push({ kind: "text", text: decodeEntities(t) });
+      break;
+    }
+    if (lt > i) push({ kind: "text", text: decodeEntities(html.slice(i, lt)) });
+
+    if (html.startsWith("<!--", lt)) {
+      const end = html.indexOf("-->", lt + 4);
+      i = end === -1 ? html.length : end + 3;
+      continue;
+    }
+    if (html[lt + 1] === "!") {
+      const end = html.indexOf(">", lt);
+      i = end === -1 ? html.length : end + 1;
+      continue;
+    }
+    if (html[lt + 1] === "/") {
+      const end = html.indexOf(">", lt);
+      const tag = html.slice(lt + 2, end === -1 ? html.length : end).trim().toLowerCase();
+      for (let s = stack.length - 1; s >= 0; s--) {
+        if (stack[s].tag === tag) {
+          stack.length = s;
+          break;
+        }
+      }
+      i = end === -1 ? html.length : end + 1;
+      continue;
+    }
+    // An opening tag must start with an ASCII letter. Anything else (a stray
+    // '<', as in "3 < 4") is literal text. (Real core output escapes '<' to
+    // &lt;, so this only matters for hand-fed input — but it must not hang.)
+    const c1 = html[lt + 1];
+    const isName = (c1 >= "a" && c1 <= "z") || (c1 >= "A" && c1 <= "Z");
+    if (!isName) {
+      push({ kind: "text", text: "<" });
+      i = lt + 1;
+      continue;
+    }
+    const { tag, attrs, selfClose, next } = parseOpenTag(html, lt);
+    const el: Extract<HNode, { kind: "el" }> = { kind: "el", tag, attrs, children: [] };
+    push(el);
+    if (!selfClose && !VOID.has(tag)) stack.push(el);
+    i = next;
+  }
+  return root;
+}
+
+function attrsToProps(tag: string, attrs: Record<string, string | true>, key: string): Record<string, unknown> {
+  const props: Record<string, unknown> = { key };
+  for (const name in attrs) {
+    const value = attrs[name];
+    const lower = name.toLowerCase();
+    // Defense-in-depth: never forward inline event handlers, even though
+    // React drops most lowercase `on*` attrs — this also covers casings and
+    // future React behavior.
+    if (lower.startsWith("on")) continue;
+    if (lower === "style" && typeof value === "string") {
+      props.style = parseStyle(value);
+      continue;
+    }
+    // Neutralize dangerous-scheme URLs (javascript:, vbscript:, data:text/html).
+    if (URL_ATTRS.has(lower) && typeof value === "string") {
+      props[ATTR_MAP[lower] ?? name] = safeUrl(value);
+      continue;
+    }
+    // A static checkbox carries `checked` with no handler; render it
+    // uncontrolled so React doesn't warn about a missing onChange.
+    if (tag === "input" && lower === "checked") {
+      props.defaultChecked = value === true ? true : value;
+      continue;
+    }
+    props[ATTR_MAP[lower] ?? name] = value;
+  }
+  return props;
+}
+
+function nodesToReact(nodes: HNode[], components: Components, keyPrefix: string): ReactNode {
+  const out: ReactNode[] = [];
+  for (let idx = 0; idx < nodes.length; idx++) {
+    const n = nodes[idx];
+    if (n.kind === "text") {
+      out.push(n.text);
+      continue;
+    }
+    const key = keyPrefix + idx;
+    const type = components[n.tag] ?? n.tag;
+    const props = attrsToProps(n.tag, n.attrs, key);
+    if (VOID.has(n.tag)) {
+      out.push(createElement(type, props));
+    } else {
+      out.push(createElement(type, props, nodesToReact(n.children, components, key + ".")));
+    }
+  }
+  return out.length === 1 ? out[0] : out;
+}
+
+/**
+ * Convert a block's trusted HTML string into a React node tree, replacing any
+ * element whose tag name appears in `components`. Call this only for **closed**
+ * blocks (open/streaming blocks have partial HTML); memoize on `(html,
+ * components)` at the call site.
+ */
+export function htmlToReact(html: string, components: Components): ReactNode {
+  return nodesToReact(parseTrustedHtml(html), components, "");
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * flux-md: zero-dep streaming markdown for the browser.
+ *
+ * Public surface:
+ *   - FluxClient: owns one Web Worker + Rust parser per stream
+ *   - FluxMarkdown: React component that subscribes to a FluxClient
+ *   - Block / Patch / BlockKind types
+ *   - highlight: optional in-house syntax highlighter
+ *
+ * Typical use (React + a Vite-like bundler):
+ *
+ *     import { FluxClient, FluxMarkdown } from "flux-md";
+ *     const client = new FluxClient();
+ *     // ... in your component: <FluxMarkdown client={client} />
+ *     // ... wherever your tokens land: client.append(deltaText);
+ *     client.finalize();
+ */
+export { FluxClient, FluxPool, getDefaultPool } from "./client";
+export { FluxMarkdown } from "./react";
+export { highlight, supportedLangs } from "./hi";
+export { htmlToReact, parseTrustedHtml } from "./html-to-react";
+export type {
+  Block,
+  BlockKind,
+  BlockKindTag,
+  BlockComponentProps,
+  Components,
+  Patch,
+  FromWorker,
+  ToWorker,
+  WorkerLike,
+  ParserConfig,
+} from "./types";

package/src/react.tsx

@@ -0,0 +1,223 @@
+import { createElement, memo, useMemo, useSyncExternalStore, type CSSProperties } from "react";
+import type { Block, BlockComponentProps, Components } from "./types";
+import type { FluxClient } from "./client";
+import { CodeBlock } from "./renderers/CodeBlock";
+import { MathBlock } from "./renderers/Math";
+import { Mermaid } from "./renderers/Mermaid";
+import { htmlToReact } from "./html-to-react";
+
+/**
+ * Render a streaming markdown document from a FluxClient. Each block is its
+ * own memoized React node keyed by its stable parser-assigned ID, so React
+ * only reconciles the blocks whose HTML actually changed since the last
+ * patch. Heavy renderers (Shiki, KaTeX, Mermaid) defer work until a block
+ * is closed.
+ *
+ * ## Custom components
+ *
+ * Pass `components` to override rendering (see {@link Components}):
+ *
+ * ```tsx
+ * <FluxMarkdown
+ *   client={client}
+ *   components={{
+ *     table: (p) => <table className="my-table" {...p} />, // tag-level
+ *     a: (p) => <a target="_blank" rel="noreferrer" {...p} />,
+ *     CodeBlock: (p) => <MyCodeBlock {...p} />,             // block-kind
+ *   }}
+ * />
+ * ```
+ *
+ * Rules:
+ *   - **Tag-level** keys (`table`, `a`, `code`, `h1`…) replace that element
+ *     wherever it appears inside a block. Applied by converting the block's
+ *     trusted HTML to a React tree.
+ *   - **Block-kind** keys ({@link BlockKindTag}: `CodeBlock`, `Mermaid`,
+ *     `Table`…) replace the whole block; the component gets
+ *     {@link BlockComponentProps}.
+ *   - **Open / speculative** blocks always render via `innerHTML` (their HTML
+ *     is partial); a tag-level override takes effect once the block commits.
+ *   - With no `components` prop the renderer takes the original fast
+ *     `innerHTML` path — output is byte-identical to before.
+ *   - **Memoize `components`** (or hoist it) if you define it inside a
+ *     component — a fresh object identity each render busts the block memo and
+ *     forces every block to re-parse on every patch.
+ *   - For code blocks the built-in highlighter is the default; it is bypassed
+ *     (so your override wins) when you provide `components.CodeBlock`,
+ *     `components.pre`, or `components.code`.
+ */
+
+interface FluxMarkdownProps {
+  client: FluxClient;
+  components?: Components;
+  /**
+   * Skip layout/paint for off-screen blocks via CSS `content-visibility: auto`
+   * — for very long documents (hundreds+ of blocks). Off by default. Applies
+   * only to *closed* blocks (the streaming tail always renders fully). Keeps
+   * nodes in the DOM; it cuts rendering cost, not node count.
+   */
+  virtualize?: boolean;
+  /**
+   * Render a bottom snap target so the view follows the streaming tail. This is
+   * CSS-only: it emits a sentinel with `scroll-snap-align: end`; **you** add
+   * `scroll-snap-type: y proximity` to your scroll container. The view then
+   * follows the bottom as content streams in and releases when the user scrolls
+   * up (and re-locks when they scroll back near the bottom). Off by default.
+   */
+  stickToBottom?: boolean;
+}
+
+function FluxMarkdownImpl({ client, components, virtualize, stickToBottom }: FluxMarkdownProps) {
+  const blocks = useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
+  // Normalize "no overrides" to a stable `undefined` so memo comparisons and
+  // the fast path don't churn on an empty object identity.
+  const comps = components && Object.keys(components).length > 0 ? components : undefined;
+  return (
+    <div className="flux-md">
+      {blocks.map((b) => (
+        <BlockView key={b.id} block={b} components={comps} virtualize={virtualize} />
+      ))}
+      {stickToBottom && <div aria-hidden="true" style={{ scrollSnapAlign: "end" }} className="flux-bottom-anchor" />}
+    </div>
+  );
+}
+
+export const FluxMarkdown = memo(FluxMarkdownImpl);
+
+function decodeEntities(s: string): string {
+  return s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
+function decodeCodeText(html: string): string {
+  const m = html.match(/<pre><code[^>]*>([\s\S]*?)<\/code><\/pre>/);
+  return m ? decodeEntities(m[1]) : "";
+}
+
+/**
+ * The LaTeX source for a MathBlock. Display math (`$$…$$` / `\[…\]`) renders as
+ * `<div class="math math-display">…</div>`; a fenced ```math block renders as
+ * `<pre><code>…</code></pre>`. Either way the body is the HTML-escaped LaTeX —
+ * decode it back so a `components.MathBlock` override gets the raw source.
+ */
+function decodeMathText(html: string): string {
+  const d = html.match(/<div class="math math-display">([\s\S]*?)<\/div>/);
+  if (d) return decodeEntities(d[1]);
+  return decodeCodeText(html);
+}
+
+function blockKindProps(block: Block): BlockComponentProps {
+  const props: BlockComponentProps = {
+    block,
+    html: block.html,
+    open: block.open,
+    speculative: block.speculative,
+  };
+  const data = block.kind.data as { lang?: string | null } | undefined;
+  if (block.kind.type === "CodeBlock") {
+    props.text = decodeCodeText(block.html);
+    props.language = data?.lang ?? "";
+  } else if (block.kind.type === "MathBlock") {
+    props.text = decodeMathText(block.html);
+  }
+  return props;
+}
+
+/** Convert a closed block's HTML to a React tree, memoized on html+components. */
+function SafeHtml({ html, components }: { html: string; components: Components }) {
+  return useMemo(() => htmlToReact(html, components), [html, components]) as JSX.Element;
+}
+
+// Per-kind off-screen size estimate for `contain-intrinsic-size` — keeps the
+// scrollbar stable while a block is layout-skipped. Wrong by 2× is fine; the
+// `auto` keyword makes the browser remember the real size once rendered.
+const INTRINSIC_PX: Record<string, number> = {
+  Paragraph: 80, Heading: 44, CodeBlock: 300, MathBlock: 140, Mermaid: 220,
+  List: 120, Blockquote: 100, Alert: 120, Table: 200, Rule: 24, Html: 80,
+};
+
+function BlockViewImpl(props: { block: Block; components?: Components; virtualize?: boolean }) {
+  const { block, virtualize } = props;
+  const content = renderBlockContent(props);
+  // Virtualize only *closed* blocks: the streaming tail (open/speculative) is
+  // where the user looks and where heights change fastest — deferring it there
+  // causes flicker. A uniform wrapper covers every kind, including dedicated
+  // renderers and block-kind overrides.
+  if (virtualize && !block.open && !block.speculative) {
+    const px = INTRINSIC_PX[block.kind.type] ?? 120;
+    return (
+      <div style={{ contentVisibility: "auto", containIntrinsicSize: `auto ${px}px` } as CSSProperties}>
+        {content}
+      </div>
+    );
+  }
+  return content;
+}
+
+function renderBlockContent({ block, components }: { block: Block; components?: Components }) {
+  const kind = block.kind.type;
+
+  // Block-kind override replaces the entire renderer for this block.
+  if (components) {
+    const blockOverride = components[kind];
+    if (blockOverride) {
+      return createElement(blockOverride, blockKindProps(block));
+    }
+  }
+
+  // Dedicated renderers for code / math / mermaid. Code blocks fall through to
+  // the generic (override-aware) path if the user supplied a pre/code override.
+  switch (kind) {
+    case "CodeBlock": {
+      const wantsCodeOverride = !!components && (!!components.pre || !!components.code);
+      if (!wantsCodeOverride) return <CodeBlock html={block.html} open={block.open} />;
+      break; // fall through to generic override-aware rendering
+    }
+    case "MathBlock":
+      return <MathBlock html={block.html} open={block.open} />;
+    case "Mermaid":
+      return <Mermaid html={block.html} open={block.open} />;
+  }
+
+  const className =
+    "flux-block flux-block-" +
+    kind.toLowerCase() +
+    (block.open ? " flux-open" : "") +
+    (block.speculative ? " flux-speculative" : "");
+
+  // Tag-level overrides only apply to a settled block (open/speculative blocks
+  // have partial HTML we must not feed to the parser).
+  if (components && !block.open && !block.speculative) {
+    return (
+      <div className={className}>
+        <SafeHtml html={block.html} components={components} />
+      </div>
+    );
+  }
+
+  return <div className={className} dangerouslySetInnerHTML={{ __html: block.html }} />;
+}
+
+// A block is the same render when its identity, HTML, open-state, and the
+// active components map are all unchanged. Exported for tests: this predicate
+// is what stops a committed block from re-rendering (and thus re-parsing) on
+// every streaming patch.
+export function blocksEqual(
+  prev: { block: Block; components?: Components; virtualize?: boolean },
+  next: { block: Block; components?: Components; virtualize?: boolean },
+): boolean {
+  return (
+    prev.block.id === next.block.id &&
+    prev.block.html === next.block.html &&
+    prev.block.open === next.block.open &&
+    prev.block.speculative === next.block.speculative &&
+    prev.components === next.components &&
+    prev.virtualize === next.virtualize
+  );
+}
+
+const BlockView = memo(BlockViewImpl, blocksEqual);

package/src/renderers/CodeBlock.tsx

@@ -0,0 +1,62 @@
+import { memo, useMemo } from "react";
+import { highlight } from "../hi";
+
+/**
+ * Deferred-highlighting code block. Open (streaming) blocks render plain;
+ * the moment the parser commits the block (open=false), we run our in-house
+ * tokenizer on the source and swap in highlighted HTML. Highlighting is
+ * memoized on html identity so closed blocks never re-tokenize.
+ */
+
+function decodeText(html: string): string {
+  const m = html.match(/<pre><code[^>]*>([\s\S]*?)<\/code><\/pre>/);
+  if (!m) return "";
+  return m[1]
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
+function extractLang(html: string): string {
+  const m = html.match(/data-lang="([^"]+)"/);
+  return m ? m[1] : "";
+}
+
+interface Props {
+  html: string;
+  open: boolean;
+}
+
+function CodeBlockImpl({ html, open }: Props) {
+  const lang = extractLang(html) || "text";
+  const highlighted = useMemo(() => {
+    if (open) return null;
+    const text = decodeText(html);
+    if (!text) return null;
+    return highlight(text, lang);
+  }, [html, open, lang]);
+
+  return (
+    <div className={"flux-code-block" + (open ? " flux-streaming" : "")}>
+      <div className="flux-code-header">
+        <span className="flux-code-lang">{lang}</span>
+        {open && <span className="flux-code-streaming-pill">streaming</span>}
+      </div>
+      <div className="flux-code-body">
+        {highlighted ? (
+          // tabIndex=0 + role/label so keyboard users can scroll long code and
+          // screen readers announce the region with its language.
+          <pre tabIndex={0} role="region" aria-label={`${lang} code`}>
+            <code dangerouslySetInnerHTML={{ __html: highlighted }} />
+          </pre>
+        ) : (
+          <div tabIndex={0} role="region" aria-label={`${lang} code`} dangerouslySetInnerHTML={{ __html: html }} />
+        )}
+      </div>
+    </div>
+  );
+}
+
+export const CodeBlock = memo(CodeBlockImpl);

package/src/renderers/Math.tsx

@@ -0,0 +1,26 @@
+import { memo } from "react";
+
+/**
+ * Math block — preformatted-text only. flux-md is zero-dep, so we don't
+ * ship KaTeX/MathJax. If you want rendered math, drop in a renderer via
+ * the (future) plugin slot and override this component.
+ */
+
+interface Props {
+  html: string;
+  open: boolean;
+}
+
+function MathImpl({ html, open }: Props) {
+  return (
+    <div className={"flux-math-block" + (open ? " flux-streaming" : "")}>
+      <div className="flux-math-header">
+        <span className="flux-math-lang">math</span>
+        {open && <span className="flux-code-streaming-pill">streaming</span>}
+      </div>
+      <div className="flux-math-body" dangerouslySetInnerHTML={{ __html: html }} />
+    </div>
+  );
+}
+
+export const MathBlock = memo(MathImpl);

package/src/renderers/Mermaid.tsx

@@ -0,0 +1,26 @@
+import { memo } from "react";
+
+/**
+ * Mermaid block — preformatted-text only. flux-md is zero-dep, so we don't
+ * ship the Mermaid runtime. The diagram source is shown in a code block;
+ * plug in your own renderer at this slot if you want SVG output.
+ */
+
+interface Props {
+  html: string;
+  open: boolean;
+}
+
+function MermaidImpl({ html, open }: Props) {
+  return (
+    <div className={"flux-mermaid-block" + (open ? " flux-streaming" : "")}>
+      <div className="flux-mermaid-header">
+        <span className="flux-mermaid-lang">mermaid</span>
+        {open && <span className="flux-code-streaming-pill">streaming</span>}
+      </div>
+      <div className="flux-mermaid-body" dangerouslySetInnerHTML={{ __html: html }} />
+    </div>
+  );
+}
+
+export const Mermaid = memo(MermaidImpl);