@elabs-ai/components-ai 4.0.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elabs-ai/components-ai",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,18 +25,12 @@
   },
   "dependencies": {
     "@radix-ui/react-use-controllable-state": "^1.2.2",
-    "@rive-app/react-webgl2": "^4.26.1",
     "@streamdown/cjk": "^1.0.2",
     "@streamdown/code": "^1.1.0",
     "@streamdown/math": "^1.0.2",
     "@streamdown/mermaid": "^1.0.2",
-    "mermaid": "^11.12.2",
-    "@xterm/addon-fit": "^0.11.0",
-    "@xterm/xterm": "^6.0.0",
-    "ansi-to-react": "^6.2.6",
     "class-variance-authority": "^0.7.1",
     "lucide-react": "^0.577.0",
-    "media-chrome": "^4.17.2",
     "motion": "^12.26.2",
     "nanoid": "^5.1.6",
     "react-jsx-parser": "^2.2.0",
@@ -47,14 +41,33 @@
     "zod": "^3.24.1"
   },
   "peerDependencies": {
+    "@rive-app/react-webgl2": "^4.26.1",
     "@xyflow/react": "^12.11.1",
-    "ai": "^6.0.0",
+    "ai": "^6.0.0 || ^7.0.0",
+    "media-chrome": "^4.17.2",
+    "mermaid": "^11.12.2",
     "react": "^18.2.0 || ^19.0.0",
     "react-dom": "^18.2.0 || ^19.0.0",
-    "@elabs-ai/components-tokens": "4.0.0",
-    "@elabs-ai/components-ui": "4.0.0"
+    "@elabs-ai/components-icons": "4.1.0",
+    "@elabs-ai/components-ui": "4.1.0",
+    "@elabs-ai/components-tokens": "4.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@rive-app/react-webgl2": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "media-chrome": {
+      "optional": true
+    },
+    "mermaid": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@rive-app/react-webgl2": "^4.26.1",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",
@@ -62,20 +75,22 @@
     "@types/react-dom": "^19.0.2",
     "@vitejs/plugin-react": "^4.3.4",
     "@xyflow/react": "^12.11.1",
-    "ai": "^6.0.0",
+    "ai": "^7.0.0",
     "eslint": "^9.17.0",
     "jsdom": "^25.0.1",
+    "media-chrome": "^4.17.2",
+    "mermaid": "^11.12.2",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tsup": "^8.3.5",
     "typescript": "^5.7.3",
     "vitest": "^3.0.2",
-    "@elabs-ai/components-charts": "4.0.0",
+    "@elabs-ai/components-charts": "4.1.0",
     "@elabs-ai/components-eslint-config": "0.1.0",
-    "@elabs-ai/components-icons": "4.0.0",
-    "@elabs-ai/components-typescript-config": "0.1.0",
-    "@elabs-ai/components-tokens": "4.0.0",
-    "@elabs-ai/components-ui": "4.0.0"
+    "@elabs-ai/components-icons": "4.1.0",
+    "@elabs-ai/components-tokens": "4.1.0",
+    "@elabs-ai/components-ui": "4.1.0",
+    "@elabs-ai/components-typescript-config": "0.1.0"
   },
   "scripts": {
     "build": "tsup",

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/_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-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-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);
+  });
+});