@elabs-ai/components-ai 4.0.0 → 4.2.0

package/src/_lazy-math.ts

@@ -0,0 +1,90 @@
+"use client";
+
+/**
+ * Lazy-loaded replacement for `@streamdown/math`'s eager `math` export.
+ *
+ * Why this exists
+ * ----------------
+ * `@streamdown/math` bundles KaTeX (~600 KB unminified) plus `remark-math` and
+ * `rehype-katex`. `useStreamdownPlugins()` (`_streamdown-i18n.ts`) used to
+ * import it statically, so every consumer of `MessageResponse`/`MarkdownView`/
+ * `ReasoningContent` paid for KaTeX in their entry chunk whether or not a
+ * single conversation ever contains `$…$`.
+ *
+ * How it stays correct
+ * ---------------------
+ * Unlike Mermaid (`_lazy-mermaid.ts`), a remark/rehype `Pluggable` cannot be
+ * wrapped in a lazy accessor: `remark-math`'s micromark extension has to be
+ * registered on the unified processor BEFORE it parses, so there is no way to
+ * hand Streamdown a present-but-deferred math plugin the way `DiagramPlugin`
+ * defers its render. Instead:
+ *
+ *  1. `needsMathPlugin(text)` cheaply sniffs the RAW markdown source for `$…$`
+ *     / `\(…\)` / `\[…\]` delimiters — no parsing, just a regex.
+ *  2. `useLazyMathPlugin(text)` returns `undefined` until that sniff is true,
+ *     at which point it kicks off `import("@streamdown/math")` and returns the
+ *     loaded plugin once it resolves, triggering a re-render.
+ *
+ * The one user-visible cost: a message whose FIRST rendered chunk already
+ * contains math delimiters shows literal `$x^2$` for one paint before the
+ * import resolves (typically well under a frame from a warm cache, since the
+ * chunk is tiny next to KaTeX's own parse/layout work). Every subsequent
+ * message reuses the module-level cache and never re-pays it.
+ */
+import type { MathPlugin } from "@streamdown/math";
+import { useEffect, useState } from "react";
+
+/** Cheap, over-inclusive sniff — a false positive just means an unneeded fetch. */
+const MATH_DELIMITER_RE = /\$\$[\s\S]*?\$\$|\$[^\s$][^$\n]*\$|\\\(|\\\)|\\\[|\\\]/;
+
+/** Does `text` look like it contains LaTeX math delimiters? */
+export function needsMathPlugin(text: string): boolean {
+  return MATH_DELIMITER_RE.test(text);
+}
+
+/** Module-level singleton: the plugin (and its KaTeX bytes) load at most once. */
+let cachedPlugin: MathPlugin | undefined;
+let loadPromise: Promise<MathPlugin> | undefined;
+
+function loadMathPlugin(): Promise<MathPlugin> {
+  loadPromise ??= import("@streamdown/math").then((mod) => {
+    cachedPlugin = mod.math;
+    return cachedPlugin;
+  });
+  return loadPromise;
+}
+
+/**
+ * Start fetching the math plugin ahead of time (e.g. once a conversation is
+ * known to contain math, or on route entry). Optional; rendering math loads
+ * it either way.
+ */
+export const preloadMath = (): void => {
+  void loadMathPlugin();
+};
+
+/**
+ * Returns the loaded `MathPlugin` once `text` needs one, else `undefined`
+ * (Streamdown treats an absent `plugins.math` slot as "no math support" — the
+ * delimiters render as literal text until the plugin arrives).
+ */
+export function useLazyMathPlugin(text: string): MathPlugin | undefined {
+  const needed = needsMathPlugin(text);
+  const [plugin, setPlugin] = useState<MathPlugin | undefined>(cachedPlugin);
+
+  useEffect(() => {
+    if (!needed || cachedPlugin) return;
+    let cancelled = false;
+    loadMathPlugin().then((loaded) => {
+      if (!cancelled) setPlugin(loaded);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [needed]);
+
+  if (!needed) return undefined;
+  // `cachedPlugin` covers the case where another instance finished loading
+  // between this component's mount and this render (state update pending).
+  return plugin ?? cachedPlugin;
+}

package/src/_lazy-mermaid-absent.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it, vi } from "vitest";
+
+/**
+ * `mermaid` is genuinely absent from this file's module registry (deliberately
+ * mocked to the shape a bundler hands back for an uninstalled optional peer —
+ * see below), so this lives in its OWN file rather than a `describe` inside
+ * `_lazy-mermaid.test.ts`. `vi.mock` is hoisted to the top of the file and
+ * applies for the file's entire run; a second, conflicting registration for
+ * the same specifier inside one file (this shape, vs. `_lazy-mermaid.test.ts`'s
+ * `{ initialize, render }` shape) does not reliably scope to one `describe`
+ * block — it can leak into sibling tests in the same file that expect the
+ * OTHER shape, corrupting them instead of the isolated case this is meant to
+ * add. See `.claude/rules/component-api.md` "Regression locks with observable
+ * side effects must be verified co-resident" for the general version of this
+ * lesson; a global module-mock registration is exactly such a side effect.
+ *
+ * Vite's production build substitutes an EMPTY module for a genuinely-absent
+ * optional peer (`export default {}`) rather than rejecting the import — so
+ * `loadEngine()`'s own shape guard in `_lazy-mermaid.ts`, not a `.catch()`, is
+ * what has to catch this. `_lazy-mermaid.test.ts`'s own "engine call itself
+ * fails" test is circular for this exact case (it rejects with the very
+ * string it then asserts on); this one instead makes the RESOLVED module
+ * shape wrong, the way an empty stub actually is, and checks `loadEngine`'s
+ * guard converts that into the module-not-found-shaped message
+ * `isModuleNotFoundMessage` recognizes.
+ *
+ * **Explicit scope statement (issue #94):** this test proves the LOAD-TIME
+ * ERROR PATH — what happens when `import("mermaid")` resolves to an empty
+ * stub — and nothing more. It does NOT prove mermaid is absent from an
+ * installed consumer tree, and must never be read as though it did. For the
+ * other four lazy-loaded optional peers (Rive, xterm, `@xterm/addon-fit`,
+ * media-chrome), `fixtures/consumer-smoke` + `pnpm consumer:check` give an
+ * end-to-end proof of genuine absence from the installed tarball. That proof
+ * is currently UNWRITABLE for mermaid: two of `@elabs-ai/components-ai`'s own
+ * plain dependencies (`streamdown`, `@streamdown/mermaid`) each depend on
+ * mermaid directly, so mermaid is never actually absent from the installed
+ * tree for this fixture to observe (see `scripts/check-optional-peer-transitives.mjs`
+ * / `pnpm optional-peers:check`, which proves and tracks that residual
+ * instead). Do not "fix" this gap by trying to make this file assert
+ * absence — it can't, until upstream `streamdown` declares mermaid an
+ * optional peer of its own.
+ */
+vi.mock("mermaid", () => ({ default: {} }));
+
+describe("lazy mermaid plugin — genuinely absent optional peer (#33)", () => {
+  it("throws a module-not-found-shaped message when the resolved module has no initialize/render", async () => {
+    const { createLazyMermaidPlugin } = await import("./_lazy-mermaid");
+
+    await expect(
+      createLazyMermaidPlugin().getMermaid().render("d1", "graph TD; A-->B;"),
+    ).rejects.toThrow(/cannot find module 'mermaid'/i);
+  });
+});

package/src/_lazy-mermaid.test.ts

@@ -98,4 +98,19 @@ describe("lazy mermaid plugin", () => {
     expect(() => preloadMermaid()).not.toThrow();
     expect(render).not.toHaveBeenCalled();
   });
+
+  it("surfaces a module-not-found-shaped message when the engine call itself fails — the missing optional `mermaid` peer, #33", async () => {
+    // The engine module resolved fine (it is mocked at the top of this file);
+    // this simulates the shape a missing peer actually takes downstream — the
+    // dynamic `import("mermaid")` rejecting — by rejecting the mocked call the
+    // plugin awaits. Streamdown reduces whatever this rejects with to a plain
+    // string and hands it to `MermaidErrorPanel`
+    // (`_mermaid-error-panel.tsx`), which classifies a message in this exact
+    // shape as a capability gap, not a render failure.
+    render.mockRejectedValueOnce(new Error("Cannot find module 'mermaid'"));
+
+    await expect(
+      createLazyMermaidPlugin().getMermaid().render("d1", "graph TD; A-->B;"),
+    ).rejects.toThrow(/cannot find module/i);
+  });
 });

package/src/_lazy-mermaid.ts

@@ -50,7 +50,30 @@ type MermaidModule = {
 let enginePromise: Promise<MermaidModule> | undefined;
 
 const loadEngine = (): Promise<MermaidModule> => {
-  enginePromise ??= import("mermaid").then((m) => m.default as unknown as MermaidModule);
+  enginePromise ??= import("mermaid").then((m) => {
+    const engine = m.default as unknown as MermaidModule;
+    // `mermaid` is an optional peer (issue #33), but its bytes are always
+    // installed anyway: TWO of this package's own plain dependencies —
+    // `streamdown` and `@streamdown/mermaid` — each declare `mermaid` as
+    // their own plain, non-optional dependency (issue #94,
+    // `pnpm optional-peers:check` proves and tracks this). So a hoisting
+    // package manager (pnpm's default `node-linker=isolated` included, via
+    // phantom resolution through the virtual store) may still make the real
+    // bytes resolve even when a consumer never installed `mermaid`
+    // themselves — this guard does not cover that case, only a bundler
+    // whose optional-peer handling substitutes an EMPTY module (Vite's
+    // production stub is `export default {}`) once the peer is genuinely
+    // absent from the resolved tree. Without this guard that empty object
+    // resolves successfully and the crash lands one call later, on
+    // `engine.initialize is not a function` — a message
+    // `isModuleNotFoundMessage` does not recognize, so it reaches the user
+    // as "Diagram couldn't be drawn" with a Retry button that can never
+    // succeed, instead of the actionable capability-gap panel.
+    if (typeof engine?.initialize !== "function" || typeof engine?.render !== "function") {
+      throw new Error("Cannot find module 'mermaid'");
+    }
+    return engine;
+  });
   return enginePromise;
 };
 

package/src/_mermaid-error-panel.test.tsx

@@ -0,0 +1,50 @@
+/**
+ * Issue #33 — `mermaid` is an OPTIONAL peer of `@elabs-ai/components-ai`,
+ * reached only through the lazy plugin in `_lazy-mermaid.ts`. Streamdown hands
+ * a failed diagram render to `MermaidErrorPanel` as a plain STRING (never the
+ * original `Error`), so this test locks the message-based branch directly:
+ * a missing-peer-shaped message renders the neutral "capability gap" panel
+ * (`kind="empty"`, `role="status"`, no retry — re-installing a dependency does
+ * not happen by clicking a button); any other message keeps the destructive
+ * `kind="error"` panel wired to Streamdown's own `retry()`.
+ */
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { MermaidErrorPanel } from "./_mermaid-error-panel";
+
+afterEach(cleanup);
+
+describe("MermaidErrorPanel (#33)", () => {
+  it("renders the neutral capability-gap panel for a missing-peer-shaped message, naming mermaid", () => {
+    const retry = vi.fn();
+    render(
+      <MermaidErrorPanel
+        chart="graph TD; A-->B;"
+        error="Cannot find module 'mermaid'"
+        retry={retry}
+      />,
+    );
+
+    expect(screen.getByRole("status")).toBeInTheDocument();
+    expect(screen.getByText(/mermaid/)).toBeInTheDocument();
+    // Re-installing a dependency does not happen by clicking a button.
+    expect(screen.queryByRole("button")).not.toBeInTheDocument();
+  });
+
+  it("keeps the destructive, retryable panel for a genuine render failure", () => {
+    const retry = vi.fn();
+    render(
+      <MermaidErrorPanel
+        chart="graph TD; A--"
+        error="Parse error on line 1: Unexpected end of input"
+        retry={retry}
+      />,
+    );
+
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+    expect(screen.getByText(/Unexpected end of input/)).toBeInTheDocument();
+    const retryButton = screen.getByRole("button", { name: /try again/i });
+    retryButton.click();
+    expect(retry).toHaveBeenCalledTimes(1);
+  });
+});

package/src/_mermaid-error-panel.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+/**
+ * The `errorComponent` Streamdown renders in place of a Mermaid diagram that
+ * failed (issue #33). Streamdown hands back the render failure as a plain
+ * STRING (`MermaidErrorComponentProps.error`, already reduced from whatever
+ * was thrown), so this distinguishes two different failures by matching that
+ * string rather than the original error object:
+ *
+ * - **The optional `mermaid` peer is not installed.** This is a CAPABILITY
+ *   GAP, not something wrong with the diagram or the app — the same class as
+ *   `@elabs-ai/components-viewer`'s `parser-missing`
+ *   (@.claude/rules/viewer-components.md "A capability gap is not a
+ *   failure"). Renders the neutral `StatePanel kind="empty"`, naming the
+ *   package to install, announced `role="status"`, with no retry action
+ *   (re-installing a dependency does not happen by clicking a button in the
+ *   page).
+ * - **Anything else is a genuine render/syntax failure** — a real error, so
+ *   it gets `StatePanel kind="error"` (`role="alert"`, set internally by
+ *   `StatePanel`) wired to Streamdown's own `retry()`, which increments the
+ *   render attempt and re-runs the diagram.
+ */
+import { Button, StatePanel, isModuleNotFoundMessage, useLocale } from "@elabs-ai/components-ui";
+import { EyeOffIcon } from "lucide-react";
+
+export interface MermaidErrorPanelProps {
+  chart: string;
+  error: string;
+  retry: () => void;
+}
+
+export function MermaidErrorPanel({ error, retry }: MermaidErrorPanelProps) {
+  const { t } = useLocale();
+
+  if (isModuleNotFoundMessage(error)) {
+    const feature = t("ai.mermaid.feature");
+    return (
+      <div className="my-4" role="status" aria-live="polite">
+        <StatePanel
+          kind="empty"
+          // A dashed edge invites a drop; this panel accepts nothing. Solid —
+          // mirrors `@elabs-ai/components-viewer`'s `FileViewerError`.
+          className="border-solid"
+          icon={<EyeOffIcon aria-hidden="true" />}
+          title={t("ai.error.engineMissing", { feature })}
+          description={t("ai.error.engineMissingBody", { feature, packages: "mermaid" })}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div className="my-4">
+      <StatePanel
+        kind="error"
+        title={t("ai.mermaid.renderError")}
+        description={error}
+        actions={
+          <Button size="sm" variant="outline" onClick={retry}>
+            {t("ai.error.retry")}
+          </Button>
+        }
+      />
+    </div>
+  );
+}

package/src/_persona-rive.tsx

@@ -19,17 +19,45 @@
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { useReducedMotion } from "@elabs-ai/components-tokens";
 import type { RiveParameters } from "@rive-app/react-webgl2";
-import {
+// `import type` from an optional peer is safe HERE ONLY because this module is
+// reached exclusively through `lazy(() => import("./_persona-rive"))` — it is
+// never statically imported, so nothing in this file reaches the barrel's
+// `.d.ts` declaration graph. `persona.tsx`'s PUBLIC types must never do this
+// (issue #101) — see its module doc comment and `PersonaRiveEvent`/
+// `PersonaRiveEventCallback`, which this module imports below and proves
+// conformant against the real peer type at the bottom of this file.
+// A NAMED import (`import { useRive } from "@rive-app/react-webgl2"`) is a
+// static ESM binding a bundler must resolve at build time. Now that
+// `@rive-app/react-webgl2` is a genuinely optional peer (issue #33), a
+// consumer who has not installed it hits that resolution at the worst
+// possible time: Vite's own optional-peer-dependency handling swaps in a
+// build-time stub with no exports, and Rollup's static named-export check
+// then fails the WHOLE APP BUILD — not a runtime error `LazyEngineBoundary`
+// could ever see (confirmed against `fixtures/consumer-smoke`'s real Vite
+// build). A namespace import defers every one of these to a plain property
+// lookup, which Rollup does not statically validate, so the build always
+// succeeds; a genuinely missing peer instead resolves the destructured hooks
+// below to `undefined`, and the guard turns that into the render-phase throw
+// `LazyEngineBoundary` (see `persona.tsx`) already catches.
+import * as RiveModule from "@rive-app/react-webgl2";
+import type { ReactNode } from "react";
+import { memo, useEffect, useMemo, useRef, useState } from "react";
+
+import type { AssertAssignable } from "./_lazy-boundary-conformance";
+import type { PersonaRiveEventCallback } from "./persona";
+import type { PersonaSource, PersonaState } from "./persona-sources";
+
+const {
   useRive,
   useStateMachineInput,
   useViewModel,
   useViewModelInstance,
   useViewModelInstanceColor,
-} from "@rive-app/react-webgl2";
-import type { ReactNode } from "react";
-import { memo, useEffect, useMemo, useRef, useState } from "react";
+} = RiveModule;
 
-import type { PersonaSource, PersonaState } from "./persona-sources";
+if (!useRive) {
+  throw new Error("Cannot find module '@rive-app/react-webgl2'");
+}
 
 // Delays Rive initialization by one frame so that React Strict Mode's
 // immediate unmount cycle never creates a WebGL2 context. Only the
@@ -139,12 +167,12 @@ PersonaWithoutModel.displayName = "PersonaWithoutModel";
 
 export interface PersonaRiveProps {
   className?: string;
-  onLoad?: RiveParameters["onLoad"];
-  onLoadError?: RiveParameters["onLoadError"];
-  onPause?: RiveParameters["onPause"];
-  onPlay?: RiveParameters["onPlay"];
+  onLoad?: PersonaRiveEventCallback;
+  onLoadError?: PersonaRiveEventCallback;
+  onPause?: PersonaRiveEventCallback;
+  onPlay?: PersonaRiveEventCallback;
   onReady?: () => void;
-  onStop?: RiveParameters["onStop"];
+  onStop?: PersonaRiveEventCallback;
   source: PersonaSource;
   /** Resolved `.riv` URL — `Persona`'s `src` override, or the variant default. */
   src: string;
@@ -250,3 +278,27 @@ const PersonaRive = ({
 };
 
 export default PersonaRive;
+
+/**
+ * Conformance assertion (issue #101): compile-time proof that the owned
+ * `PersonaRiveEventCallback` (declared in `persona.tsx`, structurally free of
+ * `@rive-app/react-webgl2`/`@rive-app/webgl2`) is still assignable to the REAL
+ * `RiveParameters["onLoad"]` — and, since `onLoad`/`onLoadError`/`onPause`/
+ * `onPlay`/`onStop` all share Rive's one `EventCallback` type, this single
+ * check covers all five. `AssertAssignable`'s type parameter is constrained
+ * (`TOwned extends TReal`), so if a future Rive release changes `Event`'s
+ * shape in a way `PersonaRiveEvent` no longer satisfies, this line fails to
+ * typecheck — caught by `pnpm --filter @elabs-ai/components-ai typecheck`
+ * locally, never shipped as a silent mismatch to a consumer.
+ *
+ * `AssertAssignable` itself is shared with `_audio-player-media-chrome.tsx`
+ * via `_lazy-boundary-conformance.ts` — see that module's doc comment for
+ * what this check can and cannot prove (it is one-directional: it cannot
+ * catch the owned type being NARROWER than the real one, which is exactly
+ * what `PersonaRiveEvent["data"]` is — see the CHANGELOG's "Breaking (types)"
+ * entry).
+ */
+export type _PersonaRiveEventCallbackConformance = AssertAssignable<
+  PersonaRiveEventCallback,
+  NonNullable<RiveParameters["onLoad"]>
+>;

package/src/_streamdown-i18n.ts

@@ -29,13 +29,15 @@ import {
   useStreamdownTranslations,
   type StreamdownTranslationKey,
 } from "@elabs-ai/components-ui";
-import { cjk } from "@streamdown/cjk";
 import { createCodePlugin } from "@streamdown/code";
-import { math } from "@streamdown/math";
-import { useEffect, useMemo, useState } from "react";
+import { useMemo } from "react";
 import type { StreamdownTranslations } from "streamdown";
 import { buildCodeBlockTheme } from "./_code-block-theme";
+import { useLazyCjkPlugin } from "./_lazy-cjk";
+import { useLazyMathPlugin } from "./_lazy-math";
 import { lazyMermaid } from "./_lazy-mermaid";
+import { MermaidErrorPanel } from "./_mermaid-error-panel";
+import { useThemeScopeRevision } from "./_theme-scope-store";
 
 /**
  * Reactive replacement for `@streamdown/code`'s pre-configured `code` export
@@ -47,31 +49,32 @@ import { lazyMermaid } from "./_lazy-mermaid";
  *
  * Streamdown's dual-theme mechanism (`createCodePlugin({ themes: [light, dark] })`)
  * expects exactly TWO themes and picks between them purely via the `.dark` CSS
- * selector — but brand-ui ships THREE themes (light/dark),
+ * selector — but brand-ui ships EVERY theme, not just Shiki's light/dark,
  * and any dark-declaring theme matches `.dark` too (see `_code-block-theme.ts`). Passing a real
  * light/dark PAIR would still force such a theme into the dark slot. Instead
  * this pins BOTH slots to `buildCodeBlockTheme()` — the SAME brand-token-derived
  * theme the active `data-theme` resolves to — so whichever slot the `.dark`
  * selector picks, it's the CORRECT theme for whatever is actually active.
  *
- * Re-derives on every `data-theme` mutation (a `MutationObserver` on
- * `<html>`, mirroring `code-block.tsx`'s own) and returns a NEW plugin object
+ * Re-derives on every `data-theme` mutation and returns a NEW plugin object
  * each time, because Streamdown only re-reads `plugins.code.getThemes()` when
  * the `plugins.code` object's REFERENCE changes (see streamdown's internal
  * `shikiTheme` memo) — a mutated-in-place plugin would never be picked up.
+ *
+ * The mutation watch itself comes from the SHARED, ref-counted store in
+ * `./_theme-scope-store` (perf review §3.3) rather than a `MutationObserver`
+ * instantiated per hook call — every simultaneously-mounted
+ * `MessageResponse`/`MarkdownView` (and every `CodeBlock`) in a message-dense
+ * conversation now shares exactly one observer per distinct scope element,
+ * instead of one each. This hook has no element of its own to scope to (it
+ * runs before Streamdown renders anything), so it resolves to the document's
+ * theme scope (`getThemeScope(null)` → closest `[data-theme]` on `<html>`,
+ * same as its prior always-`<html>` behaviour) — a genuinely region-scoped
+ * derivation would need a ref to the rendered surface, which no current call
+ * site (`message.tsx`, `markdown-view.tsx`, `reasoning.tsx`) has available.
  */
 function useReactiveCodePlugin() {
-  const [revision, setRevision] = useState(0);
-
-  useEffect(() => {
-    if (typeof document === "undefined") return;
-    const observer = new MutationObserver(() => setRevision((r) => r + 1));
-    observer.observe(document.documentElement, {
-      attributes: true,
-      attributeFilter: ["data-theme"],
-    });
-    return () => observer.disconnect();
-  }, []);
+  const revision = useThemeScopeRevision(null);
 
   return useMemo(() => {
     const theme = buildCodeBlockTheme();
@@ -84,15 +87,84 @@ function useReactiveCodePlugin() {
  * The plugin set every `@elabs-ai/components-ai` markdown surface renders with.
  *
  * `mermaid` is the LAZY plugin (`./_lazy-mermaid`): the engine + d3 + DOMPurify
- * load on first diagram render, not in the entry chunk of every consumer. `code`
- * is the reactive, brand-token-derived plugin above (#315) — never the
+ * load on first diagram render, not in the entry chunk of every consumer.
+ * `math`/`cjk` are ALSO lazy (`./_lazy-math`, `./_lazy-cjk`, #perf-5): KaTeX
+ * (~600 KB) and the CJK remark plugins load only once `text` — the raw
+ * markdown source about to render — actually needs them, sniffed by a cheap
+ * regex rather than shipped unconditionally in every consumer's entry chunk.
+ * Both resolve to `undefined` (the slot is simply absent) until their content
+ * cue fires and the dynamic import resolves; see the two modules' docs for the
+ * one-paint tradeoff this makes and why it can't be avoided the way Mermaid's
+ * render-time laziness is.
+ *
+ * `code` is the reactive, brand-token-derived plugin above (#315) — never the
  * `@streamdown/code` package's static `github-light`/`github-dark` default.
  * Memoized so Streamdown sees a referentially stable `plugins` prop except when
- * the active theme actually changes.
+ * the active theme (or a lazy slot) actually changes.
+ *
+ * @param text The raw markdown source about to render — used only to decide
+ *   whether the math/CJK plugins are needed. Pass `""` to never load them
+ *   speculatively.
  */
-export function useStreamdownPlugins() {
+export function useStreamdownPlugins(text = "") {
   const code = useReactiveCodePlugin();
-  return useMemo(() => ({ cjk, code, math, mermaid: lazyMermaid }), [code]);
+  const math = useLazyMathPlugin(text);
+  const cjk = useLazyCjkPlugin(text);
+  return useMemo(() => ({ cjk, code, math, mermaid: lazyMermaid }), [cjk, code, math]);
+}
+
+/**
+ * A React `key` for the `<Streamdown>` element that renders with
+ * {@link useStreamdownPlugins}'s result — pass it as `key={getStreamdownPluginsKey(plugins)}`
+ * on the `<Streamdown>` JSX, never inside the `plugins` object itself.
+ *
+ * Why this exists (#perf-5 follow-up): Streamdown v2.5.0's `rehypePlugins`/
+ * `remarkPlugins` are `useMemo`'d with `plugins.math`/`plugins.cjk` in their
+ * dependency arrays, and its `Block`/`Streamdown` components' custom `memo`
+ * comparators do check plugin reference equality — on paper, a fresh
+ * `plugins.math` object arriving after the lazy `import()` resolves should be
+ * enough to make Streamdown rebuild its processing pipeline with the math
+ * plugin included. Empirically (verified directly against the real
+ * `streamdown` package, not a mock) it does not: once a block has rendered
+ * once without `plugins.math`/`plugins.cjk`, Streamdown's internal processor
+ * cache keeps serving the plugin-less result even after the reference
+ * changes, and the literal `$$…$$`/CJK-remark-less markdown source stays
+ * un-rendered indefinitely.
+ *
+ * Forcing React to unmount and remount the `<Streamdown>` element — by
+ * changing its `key` — sidesteps that internal cache entirely (a fresh
+ * instance has no stale cache to serve) and reliably picks up the lazily
+ * loaded plugin. The cost is a one-time full remount of that Streamdown
+ * instance the first time its lazy math/CJK slot resolves — at most once per
+ * mounted instance, since after that the key is stable again. Filed for
+ * upstream investigation; if a future `streamdown` release fixes the
+ * underlying cache, this key can be dropped without changing any call site's
+ * behavior (an unchanging key is a no-op).
+ */
+export function getStreamdownPluginsKey(plugins: {
+  readonly cjk?: unknown;
+  readonly math?: unknown;
+}): string {
+  return `${plugins.math ? "math" : "no-math"}:${plugins.cjk ? "cjk" : "no-cjk"}`;
+}
+
+/**
+ * The top-level Streamdown `mermaid` prop (distinct from `plugins.mermaid`,
+ * the LAZY `DiagramPlugin` `useStreamdownPlugins()` wires above) — this is
+ * where a FAILED render is caught (issue #33). Streamdown hands its
+ * `errorComponent` a plain STRING describing what went wrong;
+ * `MermaidErrorPanel` decides whether that string names a missing optional
+ * peer (`mermaid` not installed — a capability gap, `StatePanel kind="empty"`)
+ * or a genuine diagram render failure (`StatePanel kind="error"`, with retry).
+ *
+ * A stable module-level object, not a fresh one per render: Streamdown only
+ * re-reads `mermaid.errorComponent` when this reference changes, and
+ * `MermaidErrorPanel` never varies at runtime. Exported as a hook to match
+ * `useStreamdownPlugins()`'s call-site shape.
+ */
+const MERMAID_OPTIONS = { errorComponent: MermaidErrorPanel };
+export function useStreamdownMermaidOptions() {
+  return MERMAID_OPTIONS;
 }
 
 /*