@elabs-ai/components-ai 4.0.0 → 4.2.0

package/src/__contract__/prompt-input-mode.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for PromptInputMode (`packages/ai/src/prompt-input-mode.tsx`), derived from its
+ * `Default` story (packages/ai/src/prompt-input-mode.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../prompt-input-mode.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `ai-composer-promptinputmode--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("PromptInputMode contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="prompt-input-mode" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="prompt-input-mode"]')).not.toBeNull();
+  });
+});

package/src/_audio-player-media-chrome.tsx

@@ -10,8 +10,11 @@
  * never render an `AudioPlayer`. Keeping every media-chrome *value* import in
  * this module, reached only through
  * `lazy(() => import("./_audio-player-media-chrome"))`, confines it to its own
- * chunk. `audio-player.tsx` still owns the public prop types and imports the
- * media-chrome element types with `import type` (types erase).
+ * chunk. `audio-player.tsx` owns the public prop types, and — since issue #101
+ * — owns them as OWNED types (`AudioPlayerPartProps` and its ten aliases) that
+ * never reference `media-chrome/react`'s own types; this module still imports
+ * the REAL media-chrome values (below) and, at the bottom of the file, proves
+ * every owned type stays assignable to its real counterpart.
  *
  * See ADR 0019 and `pnpm heavy-deps:check`.
  *
@@ -21,20 +24,23 @@
  */
 import { Button, ButtonGroup, ButtonGroupText } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
-import {
-  MediaControlBar,
-  MediaController,
-  MediaDurationDisplay,
-  MediaMuteButton,
-  MediaPlayButton,
-  MediaSeekBackwardButton,
-  MediaSeekForwardButton,
-  MediaTimeDisplay,
-  MediaTimeRange,
-  MediaVolumeRange,
-} from "media-chrome/react";
-import type { CSSProperties } from "react";
+// A NAMED import (`import { MediaController } from "media-chrome/react"`) is a
+// static ESM binding a bundler must resolve at build time. Now that
+// `media-chrome` 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 any `.catch()`/error boundary 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 names below to `undefined`,
+// and the guard turns that into a render-phase throw `LazyEngineBoundary`
+// already catches (see `persona.tsx`'s identical pattern).
+import * as MediaChromeReactModule from "media-chrome/react";
+import type { ComponentProps, CSSProperties } from "react";
 
+import type { AssertAssignable } from "./_lazy-boundary-conformance";
 import type {
   AudioPlayerControlBarProps,
   AudioPlayerDurationDisplayProps,
@@ -48,6 +54,28 @@ import type {
   AudioPlayerVolumeRangeProps,
 } from "./audio-player";
 
+const {
+  MediaControlBar,
+  MediaController,
+  MediaDurationDisplay,
+  MediaMuteButton,
+  MediaPlayButton,
+  MediaSeekBackwardButton,
+  MediaSeekForwardButton,
+  MediaTimeDisplay,
+  MediaTimeRange,
+  MediaVolumeRange,
+} = MediaChromeReactModule;
+
+// The peer is genuinely absent (Vite's build-time stub, or any other bundler
+// that resolves an optional peer to an empty module) — surface a message
+// `isModuleNotFoundMessage` recognizes, so the caller's `renderMissing` still
+// gets the actionable "install media-chrome" copy rather than a raw
+// "MediaController is not a valid JSX element" crash.
+if (!MediaController) {
+  throw new Error("Cannot find module 'media-chrome'");
+}
+
 export const AudioPlayer = ({ children, style, ...props }: AudioPlayerProps) => (
   <MediaController
     audio
@@ -144,3 +172,62 @@ export const AudioPlayerVolumeRange = ({ className, ...props }: AudioPlayerVolum
     <MediaVolumeRange className={cn("", className)} {...props} />
   </ButtonGroupText>
 );
+
+/**
+ * Conformance assertions (issue #101): compile-time proof that every OWNED
+ * type declared in `audio-player.tsx` stays assignable to its REAL
+ * `media-chrome/react` counterpart — this module still has the real values
+ * (and therefore the real types) in scope, since it is the one place they are
+ * allowed to be (see the module doc comment above). `AssertAssignable`'s type
+ * parameter is constrained (`TOwned extends TReal`), so if a future
+ * media-chrome release narrows an element's props in a way the owned type no
+ * longer satisfies, ONE of these ten lines fails to typecheck — caught by
+ * `pnpm --filter @elabs-ai/components-ai typecheck` locally, never shipped as
+ * a silent mismatch to a consumer using the real component underneath.
+ *
+ * `AssertAssignable` itself is shared with `_persona-rive.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 these
+ * owned types are — see the CHANGELOG's "Breaking (types)" entry).
+ */
+export type _AudioPlayerPropsConformance = AssertAssignable<
+  AudioPlayerProps,
+  Omit<ComponentProps<typeof MediaController>, "audio">
+>;
+export type _AudioPlayerControlBarPropsConformance = AssertAssignable<
+  AudioPlayerControlBarProps,
+  ComponentProps<typeof MediaControlBar>
+>;
+export type _AudioPlayerPlayButtonPropsConformance = AssertAssignable<
+  AudioPlayerPlayButtonProps,
+  ComponentProps<typeof MediaPlayButton>
+>;
+export type _AudioPlayerSeekBackwardButtonPropsConformance = AssertAssignable<
+  AudioPlayerSeekBackwardButtonProps,
+  ComponentProps<typeof MediaSeekBackwardButton>
+>;
+export type _AudioPlayerSeekForwardButtonPropsConformance = AssertAssignable<
+  AudioPlayerSeekForwardButtonProps,
+  ComponentProps<typeof MediaSeekForwardButton>
+>;
+export type _AudioPlayerTimeDisplayPropsConformance = AssertAssignable<
+  AudioPlayerTimeDisplayProps,
+  ComponentProps<typeof MediaTimeDisplay>
+>;
+export type _AudioPlayerTimeRangePropsConformance = AssertAssignable<
+  AudioPlayerTimeRangeProps,
+  ComponentProps<typeof MediaTimeRange>
+>;
+export type _AudioPlayerDurationDisplayPropsConformance = AssertAssignable<
+  AudioPlayerDurationDisplayProps,
+  ComponentProps<typeof MediaDurationDisplay>
+>;
+export type _AudioPlayerMuteButtonPropsConformance = AssertAssignable<
+  AudioPlayerMuteButtonProps,
+  ComponentProps<typeof MediaMuteButton>
+>;
+export type _AudioPlayerVolumeRangePropsConformance = AssertAssignable<
+  AudioPlayerVolumeRangeProps,
+  ComponentProps<typeof MediaVolumeRange>
+>;

package/src/_chat-shell-rail.tsx

@@ -4,8 +4,8 @@ import { FileText, Sparkles } from "lucide-react";
 export function ContextPanelRail() {
   return (
     <div className="flex h-full flex-col bg-surface">
-      <div className="flex h-12 items-center border-b px-4 text-sm font-semibold">Context</div>
-      <div className="space-y-2 p-3 text-sm">
+      <div className="flex h-12 items-center border-b px-4 text-body font-semibold">Context</div>
+      <div className="space-y-2 p-3 text-body">
         <div className="flex items-center gap-2 rounded-md border bg-card p-2">
           <FileText className="size-4 text-muted-foreground" /> Deploy log — wk 23
         </div>

package/src/_flow-boundary.tsx

@@ -119,65 +119,84 @@ export const EdgeTemporary = ({
   );
 };
 
-const getHandleCoordsByPosition = (node: InternalNode<FlowNode>, handlePosition: Position) => {
-  // Choose the handle type based on position - Left is for target, Right is for source
-  const handleType = handlePosition === Position.Left ? "target" : "source";
+/**
+ * The point on `node` where an edge of `handleType` should attach, plus the side
+ * it leaves from.
+ *
+ * Read from React Flow's **measured** `handleBounds` — the DOM box of the
+ * painted dot — and taken at the box's OUTER edge, which is React Flow's own
+ * convention (the anchor lands on the dot's rim, which keeps a `markerEnd`
+ * visible).
+ *
+ * The two fallbacks matter as much as the happy path. `preferred` is only a
+ * preference: `nodeTypes` is an open prop, so a consumer node may legitimately
+ * put its handles on the top and bottom, and the shipped `Node`'s left/right
+ * pair is a convenience rather than a constraint. And `handleBounds` is empty
+ * until React Flow's first measurement pass, which on this canvas is a real
+ * window because the engine arrives in a lazy chunk (ADR 0019). Both used to
+ * resolve to `[0, 0]` — the CANVAS ORIGIN — so the edge was drawn hundreds of
+ * pixels from either node (measured at 498.8px in the `VerticalHandles` story).
+ * Falling back to any handle of the right type, and then to the node's own
+ * border, keeps the line on the node in every case.
+ */
+const getHandleAnchor = (
+  node: InternalNode<FlowNode>,
+  handleType: "source" | "target",
+  preferred: Position,
+) => {
+  const bounds = node.internals.handleBounds?.[handleType] ?? [];
+  const handle = bounds.find((h) => h.position === preferred) ?? bounds[0];
+  const origin = node.internals.positionAbsolute;
 
-  const handle = node.internals.handleBounds?.[handleType]?.find(
-    (h) => h.position === handlePosition,
-  );
+  if (handle) {
+    // Offset to the handle box's outer edge on its own side; the other axis is
+    // centred.
+    const offsetX =
+      handle.position === Position.Left
+        ? 0
+        : handle.position === Position.Right
+          ? handle.width
+          : handle.width / 2;
+    const offsetY =
+      handle.position === Position.Top
+        ? 0
+        : handle.position === Position.Bottom
+          ? handle.height
+          : handle.height / 2;
 
-  if (!handle) {
-    return [0, 0] as const;
+    return {
+      position: handle.position,
+      x: origin.x + handle.x + offsetX,
+      y: origin.y + handle.y + offsetY,
+    };
   }
 
-  let offsetX = handle.width / 2;
-  let offsetY = handle.height / 2;
-
-  // this is a tiny detail to make the markerEnd of an edge visible.
-  // The handle position that gets calculated has the origin top-left, so depending which side we are using, we add a little offset
-  // when the handlePosition is Position.Right for example, we need to add an offset as big as the handle itself in order to get the correct position
-  switch (handlePosition) {
-    case Position.Left: {
-      offsetX = 0;
-      break;
-    }
-    case Position.Right: {
-      offsetX = handle.width;
-      break;
-    }
-    case Position.Top: {
-      offsetY = 0;
-      break;
-    }
-    case Position.Bottom: {
-      offsetY = handle.height;
-      break;
-    }
-    default: {
-      throw new Error(`Invalid handle position: ${handlePosition}`);
-    }
+  // No measured handle at all — anchor on the node's own border midpoint.
+  const width = node.measured.width ?? 0;
+  const height = node.measured.height ?? 0;
+  switch (preferred) {
+    case Position.Left:
+      return { position: preferred, x: origin.x, y: origin.y + height / 2 };
+    case Position.Right:
+      return { position: preferred, x: origin.x + width, y: origin.y + height / 2 };
+    case Position.Top:
+      return { position: preferred, x: origin.x + width / 2, y: origin.y };
+    default:
+      return { position: preferred, x: origin.x + width / 2, y: origin.y + height };
   }
-
-  const x = node.internals.positionAbsolute.x + handle.x + offsetX;
-  const y = node.internals.positionAbsolute.y + handle.y + offsetY;
-
-  return [x, y] as const;
 };
 
 const getEdgeParams = (source: InternalNode<FlowNode>, target: InternalNode<FlowNode>) => {
-  const sourcePos = Position.Right;
-  const [sx, sy] = getHandleCoordsByPosition(source, sourcePos);
-  const targetPos = Position.Left;
-  const [tx, ty] = getHandleCoordsByPosition(target, targetPos);
+  const from = getHandleAnchor(source, "source", Position.Right);
+  const to = getHandleAnchor(target, "target", Position.Left);
 
   return {
-    sourcePos,
-    sx,
-    sy,
-    targetPos,
-    tx,
-    ty,
+    sourcePos: from.position,
+    sx: from.x,
+    sy: from.y,
+    targetPos: to.position,
+    tx: to.x,
+    ty: to.y,
   };
 };
 

package/src/_lazy-boundary-conformance.ts

@@ -0,0 +1,38 @@
+/**
+ * `AssertAssignable` — the shared compile-time conformance-check helper for
+ * issue #101's "own the type locally" pattern (see `persona.tsx`,
+ * `audio-player.tsx`, and the ADR 0019 amendment). Every `@lazy-boundary`
+ * sibling module that owns a structurally-compatible mirror of an optional
+ * peer's type (`_persona-rive.tsx`, `_audio-player-media-chrome.tsx`) uses
+ * THIS declaration rather than redeclaring it locally — previously the same
+ * three-line type was declared verbatim in both files (round-1 validator
+ * finding F5), which is exactly the kind of drift this repo's "a convention
+ * ships with its teeth" rule (@.claude/rules/quality-gates.md) exists to
+ * avoid: a future edit to one copy (e.g. relaxing the constraint) could
+ * silently diverge from the other with no gate to catch it.
+ *
+ * Purely a type-level helper — no runtime value, no import of anything heavy
+ * or peer-owned — so it is safe for a `@lazy-boundary` module to import it
+ * statically without pulling the peer back into the entry chunk, and safe for
+ * anything else in the package to import it too.
+ *
+ * ## What this assertion can, and cannot, prove (round-1 validator finding F4)
+ *
+ * `AssertAssignable<TOwned extends TReal, TReal>` only typechecks when
+ * `TOwned` is assignable TO `TReal` — i.e. it proves the owned mirror is a
+ * SUPERTYPE-OR-EQUAL of the real peer type (every value the real type can
+ * produce is accepted by the owned type), never the reverse. That is
+ * sufficient to prove the mirror is SAFE to use in place of the real type
+ * wherever the real type is only ever produced (an event object Rive hands
+ * back, a prop object media-chrome reads) — but it is a ONE-DIRECTIONAL
+ * check, so it cannot detect the owned type merely being NARROWER than the
+ * real one. `PersonaRiveEvent["data"]` (`unknown`) and the `AudioPlayer*`
+ * part-prop types (ordinary HTML attributes only, no per-element instance
+ * members, no `ref`) are both real, deliberate narrowings versus their real
+ * peer counterparts — see the CHANGELOG's "Breaking (types)" entry — and this
+ * assertion passes for both, exactly as designed: a narrower type is still a
+ * valid supertype-direction match. Don't read a green
+ * `_*Conformance` type as "identical shape to the peer"; read it as "safe to
+ * substitute here", which is the property issue #101 actually needed.
+ */
+export type AssertAssignable<_TOwned extends TReal, TReal> = true;

package/src/_lazy-cjk.test.ts

@@ -0,0 +1,43 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { needsCjkPlugin, preloadCjk, useLazyCjkPlugin } from "./_lazy-cjk";
+
+const fakeCjkPlugin = {
+  name: "cjk",
+  remarkPlugins: [],
+  remarkPluginsAfter: [],
+  remarkPluginsBefore: [],
+  type: "cjk",
+};
+
+vi.mock("@streamdown/cjk", () => ({ cjk: fakeCjkPlugin }));
+
+describe("needsCjkPlugin", () => {
+  it("returns false for plain ASCII text", () => {
+    expect(needsCjkPlugin("plain text")).toBe(false);
+  });
+
+  it("matches CJK Unified Ideographs, Hiragana, Katakana and Hangul", () => {
+    expect(needsCjkPlugin("你好")).toBe(true);
+    expect(needsCjkPlugin("こんにちは")).toBe(true);
+    expect(needsCjkPlugin("コンニチハ")).toBe(true);
+    expect(needsCjkPlugin("안녕하세요")).toBe(true);
+  });
+});
+
+describe("useLazyCjkPlugin", () => {
+  it("returns undefined when the text has no CJK codepoints", () => {
+    const { result } = renderHook(() => useLazyCjkPlugin("plain text"));
+    expect(result.current).toBeUndefined();
+  });
+
+  it("loads and returns the plugin once the text needs CJK handling", async () => {
+    const { result } = renderHook(() => useLazyCjkPlugin("你好，世界"));
+    await waitFor(() => expect(result.current).toBe(fakeCjkPlugin));
+  });
+
+  it("preloadCjk resolves without throwing", () => {
+    expect(() => preloadCjk()).not.toThrow();
+  });
+});

package/src/_lazy-cjk.ts

@@ -0,0 +1,73 @@
+"use client";
+
+/**
+ * Lazy-loaded replacement for `@streamdown/cjk`'s eager `cjk` export.
+ *
+ * Same rationale and mechanism as `_lazy-math.ts` — `remark-cjk-friendly` +
+ * `remark-cjk-friendly-gfm-strikethrough` load only once `needsCjkPlugin(text)`
+ * sees a CJK codepoint, instead of shipping in every consumer's entry chunk.
+ * See `_lazy-math.ts` for why a remark `Pluggable` cannot be deferred the way
+ * `DiagramPlugin` defers Mermaid's render, and for the one-paint literal-text
+ * cost this trades for it.
+ */
+import type { CjkPlugin } from "@streamdown/cjk";
+import { useEffect, useState } from "react";
+
+/**
+ * Hiragana, Katakana, CJK Unified Ideographs (+ Extension A), Hangul Syllables,
+ * CJK punctuation and halfwidth Katakana — the ranges `remark-cjk-friendly`
+ * exists to handle (emphasis/strikethrough boundary rules around CJK text).
+ */
+// The range's first codepoint is the ideographic full-width space, not
+// accidental whitespace — a deliberate boundary character, not noise.
+// eslint-disable-next-line no-irregular-whitespace -- see comment above
+const CJK_RANGE_RE = /[　-〿぀-ヿ㐀-䶿一-鿿가-힣･-ﾟ]/u;
+
+/** Does `text` contain a CJK codepoint? */
+export function needsCjkPlugin(text: string): boolean {
+  return CJK_RANGE_RE.test(text);
+}
+
+/** Module-level singleton: the plugin loads at most once. */
+let cachedPlugin: CjkPlugin | undefined;
+let loadPromise: Promise<CjkPlugin> | undefined;
+
+function loadCjkPlugin(): Promise<CjkPlugin> {
+  loadPromise ??= import("@streamdown/cjk").then((mod) => {
+    cachedPlugin = mod.cjk;
+    return cachedPlugin;
+  });
+  return loadPromise;
+}
+
+/**
+ * Start fetching the CJK plugin ahead of time (e.g. once a conversation's
+ * locale is known to be CJK). Optional; rendering CJK text loads it either way.
+ */
+export const preloadCjk = (): void => {
+  void loadCjkPlugin();
+};
+
+/**
+ * Returns the loaded `CjkPlugin` once `text` needs one, else `undefined`
+ * (Streamdown treats an absent `plugins.cjk` slot as "no CJK handling" — plain
+ * remark-gfm boundary rules apply until the plugin arrives).
+ */
+export function useLazyCjkPlugin(text: string): CjkPlugin | undefined {
+  const needed = needsCjkPlugin(text);
+  const [plugin, setPlugin] = useState<CjkPlugin | undefined>(cachedPlugin);
+
+  useEffect(() => {
+    if (!needed || cachedPlugin) return;
+    let cancelled = false;
+    loadCjkPlugin().then((loaded) => {
+      if (!cancelled) setPlugin(loaded);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [needed]);
+
+  if (!needed) return undefined;
+  return plugin ?? cachedPlugin;
+}

package/src/_lazy-engine-boundary.tsx

@@ -0,0 +1,61 @@
+"use client";
+
+import { Component, type ErrorInfo, type ReactNode } from "react";
+
+export interface LazyEngineBoundaryProps {
+  children: ReactNode;
+  /**
+   * Called once a wrapped `lazy()` import rejects (an optional peer that is
+   * not installed, or any other load-time failure). Return what to render in
+   * its place — the boundary owns no default visual, since the right
+   * stand-in differs by surface (an orb placeholder for `Persona`, `null`
+   * for an `AudioPlayer` sub-control).
+   */
+  renderMissing: (error: unknown) => ReactNode;
+}
+
+interface LazyEngineBoundaryState {
+  // Wrapped in an object so `{ value: undefined }` (a boundary that caught
+  // an error whose value happens to be `undefined`) is distinguishable from
+  // "nothing caught yet" (`error: null`).
+  error: { value: unknown } | null;
+}
+
+/**
+ * Catches a `React.lazy()` load failure — an optional peer dependency that is
+ * not installed (issue #33), or any other dynamic-import rejection — and
+ * renders a caller-supplied fallback instead of unmounting the tree.
+ *
+ * `Suspense` alone does not do this: it only covers the PENDING state. A
+ * REJECTED lazy import throws during render, and with no boundary above it
+ * that throw propagates to the nearest ancestor boundary React DOES find —
+ * by default, the whole app. This is the one place in `@elabs-ai/components-ai`
+ * that needs a real render-phase error boundary; Mermaid and the interactive
+ * terminal fail via an awaited promise instead (Streamdown's `errorComponent`
+ * and a `.catch()` on the mount effect, respectively), which don't need one.
+ */
+export class LazyEngineBoundary extends Component<
+  LazyEngineBoundaryProps,
+  LazyEngineBoundaryState
+> {
+  override state: LazyEngineBoundaryState = { error: null };
+
+  static getDerivedStateFromError(error: unknown): LazyEngineBoundaryState {
+    return { error: { value: error } };
+  }
+
+  override componentDidCatch(error: unknown, info: ErrorInfo): void {
+    console.error(
+      "[@elabs-ai/components-ai] a lazy engine failed to load:",
+      error,
+      info.componentStack,
+    );
+  }
+
+  override render(): ReactNode {
+    if (this.state.error) {
+      return this.props.renderMissing(this.state.error.value);
+    }
+    return this.props.children;
+  }
+}

package/src/_lazy-math.test.ts

@@ -0,0 +1,63 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { needsMathPlugin, preloadMath, useLazyMathPlugin } from "./_lazy-math";
+
+/**
+ * The KaTeX-carrying `@streamdown/math` module is mocked so this file tests
+ * the lazy wrapper's *behaviour*. That the real dependency is genuinely
+ * absent from the entry chunk is a property of the BUILD, not of jsdom — see
+ * `pnpm check --rule eager-heavy-deps`, which
+ * asserts no `packages/ai/src` module statically imports `@streamdown/math`
+ * or `katex`.
+ */
+const fakeMathPlugin = {
+  name: "katex",
+  rehypePlugin: vi.fn(),
+  remarkPlugin: vi.fn(),
+  type: "math",
+};
+
+vi.mock("@streamdown/math", () => ({ math: fakeMathPlugin }));
+
+describe("needsMathPlugin", () => {
+  it("matches $$block$$ and $inline$ delimiters", () => {
+    expect(needsMathPlugin("plain text")).toBe(false);
+    expect(needsMathPlugin("$$x^2$$")).toBe(true);
+    expect(needsMathPlugin("the answer is $x + 1$ today")).toBe(true);
+  });
+
+  it("matches \\( \\) and \\[ \\] delimiters", () => {
+    expect(needsMathPlugin("\\(x^2\\)")).toBe(true);
+    expect(needsMathPlugin("\\[x^2\\]")).toBe(true);
+  });
+
+  it("does not false-positive on a bare dollar amount", () => {
+    // A single, unpaired `$` (no closing delimiter on the same line) is not math.
+    expect(needsMathPlugin("that costs $5")).toBe(false);
+  });
+});
+
+describe("useLazyMathPlugin", () => {
+  it("returns undefined when the text has no math delimiters", () => {
+    const { result } = renderHook(() => useLazyMathPlugin("plain text"));
+    expect(result.current).toBeUndefined();
+  });
+
+  it("loads and returns the plugin once the text needs math", async () => {
+    const { result } = renderHook(() => useLazyMathPlugin("$$x^2$$"));
+    await waitFor(() => expect(result.current).toBe(fakeMathPlugin));
+  });
+
+  it("preloadMath resolves without throwing", () => {
+    expect(() => preloadMath()).not.toThrow();
+  });
+
+  it("serves a second, simultaneous consumer off the same cached load", async () => {
+    const first = renderHook(() => useLazyMathPlugin("$$x^2$$"));
+    const second = renderHook(() => useLazyMathPlugin("$y^2$"));
+
+    await waitFor(() => expect(first.result.current).toBe(fakeMathPlugin));
+    await waitFor(() => expect(second.result.current).toBe(fakeMathPlugin));
+  });
+});