@elabs-ai/components-ai 4.0.0

package/src/_flow-boundary.tsx

@@ -0,0 +1,237 @@
+"use client";
+
+/**
+ * The React Flow half of `@elabs-ai/components-ai`'s in-chat agent
+ * workspace graph — `Canvas`, `Controls`, `Edge`, `Node`, `Panel`, `Toolbar` —
+ * split out so the engine can be `lazy()`-loaded.
+ *
+ * `@xyflow/react` declares no `sideEffects`, so the six static imports it used to
+ * have (one per public module, plus `@xyflow/react/dist/style.css`) put the whole
+ * engine into the entry chunk of every consumer, canvas rendered or not. **The
+ * stylesheet import has to live here too**: a bare
+ * `import "@xyflow/react/dist/style.css"` in `canvas.tsx` keeps the edge alive on
+ * its own.
+ *
+ * This is ONE boundary for all six parts on purpose (see `_flow-lazy.ts`): six
+ * boundaries would be six chunks all pulling the same engine. The public modules
+ * keep their `import type { … } from "@xyflow/react"` lines (types erase) and
+ * their prop types, and render a `lazy()` wrapper over the implementations here.
+ * `connection.tsx` is type-only already and needs no boundary.
+ *
+ * See ADR 0019 and `pnpm heavy-deps:check`.
+ *
+ * @lazy-boundary This module must only ever be reached via `import()`. The gate
+ * fails if anything imports it statically, which would put React Flow back in
+ * the entry chunk and make the `lazy()` pointless.
+ */
+import { Card } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import type { EdgeProps, InternalNode, Node as FlowNode } from "@xyflow/react";
+import {
+  Background,
+  BaseEdge,
+  Controls as ControlsPrimitive,
+  getBezierPath,
+  getSimpleBezierPath,
+  Handle,
+  NodeToolbar,
+  Panel as PanelPrimitive,
+  Position,
+  ReactFlow,
+  useInternalNode,
+} from "@xyflow/react";
+
+import "@xyflow/react/dist/style.css";
+
+import type { CanvasProps } from "./canvas";
+import type { ControlsProps } from "./controls";
+import type { NodeProps } from "./node";
+import type { PanelProps } from "./panel";
+import type { ToolbarProps } from "./toolbar";
+
+const deleteKeyCode = ["Backspace", "Delete"];
+
+/**
+ * The React Flow attribution badge is hidden on both canvas surfaces (here and
+ * `@elabs-ai/components-flow`'s `CanvasShell`). `@xyflow/react` is
+ * MIT — the licence requires the notice in source copies, not a rendered badge —
+ * and xyflow asks that the badge only be hidden under a React Flow Pro
+ * subscription. Keeping it is therefore a product/commercial decision, and this
+ * repo's is to hide it. A consumer can restore it per-canvas with
+ * `proOptions={{ hideAttribution: false }}`, which still wins via `...props`.
+ */
+const proOptions = { hideAttribution: true };
+
+export const Canvas = ({ children, ...props }: CanvasProps) => (
+  <ReactFlow
+    deleteKeyCode={deleteKeyCode}
+    fitView
+    panOnDrag={false}
+    panOnScroll
+    proOptions={proOptions}
+    selectionOnDrag={true}
+    zoomOnDoubleClick={false}
+    {...props}
+  >
+    <Background bgColor="var(--sidebar)" />
+    {children}
+  </ReactFlow>
+);
+
+export const Controls = ({ className, ...props }: ControlsProps) => (
+  <ControlsPrimitive
+    className={cn(
+      "gap-px overflow-hidden rounded-md border bg-card p-1 shadow-none!",
+      "[&>button]:rounded-md [&>button]:border-none! [&>button]:bg-transparent! [&>button]:hover:bg-secondary!",
+      className,
+    )}
+    {...props}
+  />
+);
+
+export const EdgeTemporary = ({
+  id,
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  sourcePosition,
+  targetPosition,
+}: EdgeProps) => {
+  const [edgePath] = getSimpleBezierPath({
+    sourcePosition,
+    sourceX,
+    sourceY,
+    targetPosition,
+    targetX,
+    targetY,
+  });
+
+  return (
+    <BaseEdge
+      className="stroke-1 stroke-ring"
+      id={id}
+      path={edgePath}
+      style={{
+        strokeDasharray: "5, 5",
+      }}
+    />
+  );
+};
+
+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";
+
+  const handle = node.internals.handleBounds?.[handleType]?.find(
+    (h) => h.position === handlePosition,
+  );
+
+  if (!handle) {
+    return [0, 0] as const;
+  }
+
+  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}`);
+    }
+  }
+
+  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);
+
+  return {
+    sourcePos,
+    sx,
+    sy,
+    targetPos,
+    tx,
+    ty,
+  };
+};
+
+export const EdgeAnimated = ({ id, source, target, markerEnd, style }: EdgeProps) => {
+  const sourceNode = useInternalNode(source);
+  const targetNode = useInternalNode(target);
+
+  if (!(sourceNode && targetNode)) {
+    return null;
+  }
+
+  const { sx, sy, tx, ty, sourcePos, targetPos } = getEdgeParams(sourceNode, targetNode);
+
+  const [edgePath] = getBezierPath({
+    sourcePosition: sourcePos,
+    sourceX: sx,
+    sourceY: sy,
+    targetPosition: targetPos,
+    targetX: tx,
+    targetY: ty,
+  });
+
+  return (
+    <>
+      <BaseEdge id={id} markerEnd={markerEnd} path={edgePath} style={style} />
+      <circle fill="var(--primary)" r="4">
+        <animateMotion dur="2s" path={edgePath} repeatCount="indefinite" />
+      </circle>
+    </>
+  );
+};
+
+export const Node = ({ handles, className, ...props }: NodeProps) => (
+  <Card
+    className={cn("node-container relative size-full h-auto w-sm gap-0 rounded-md p-0", className)}
+    {...props}
+  >
+    {handles.target && <Handle position={Position.Left} type="target" />}
+    {handles.source && <Handle position={Position.Right} type="source" />}
+    {props.children}
+  </Card>
+);
+
+export const Panel = ({ className, ...props }: PanelProps) => (
+  <PanelPrimitive
+    className={cn("m-4 overflow-hidden rounded-md border bg-card p-1", className)}
+    {...props}
+  />
+);
+
+export const Toolbar = ({ className, ...props }: ToolbarProps) => (
+  <NodeToolbar
+    className={cn("flex items-center gap-1 rounded-sm border bg-background p-1.5", className)}
+    position={Position.Bottom}
+    {...props}
+  />
+);

package/src/_flow-lazy.ts

@@ -0,0 +1,34 @@
+/**
+ * The one dynamic-import seam every React-Flow-backed component in
+ * `@elabs-ai/components-ai` goes through.
+ *
+ * `@xyflow/react` declares no `sideEffects`, so a static import from any of the
+ * six public modules (`canvas`, `controls`, `edge`, `node`, `panel`, `toolbar`)
+ * put the whole engine into the entry chunk of every consumer. They all reach it
+ * through **one** boundary module — `_flow-boundary.tsx` — rather than six, so
+ * the engine lands in exactly one chunk: six boundaries would mean six chunks
+ * each pulling the same engine, and a `<Node>` rendered inside an already-loaded
+ * `<Canvas>` would fetch a second copy.
+ *
+ * Because every part resolves from the same specifier, the parts _inside_ a
+ * canvas resolve from the module cache the canvas already populated.
+ *
+ * This module is deliberately NOT itself a lazy boundary (it carries no such
+ * docblock tag, and `pnpm heavy-deps:check` would fail the six static imports
+ * below if it did): it holds no engine import of its own, only the `import()`
+ * call, so the public modules may import it statically. See ADR 0019.
+ */
+import { lazy } from "react";
+import type { ComponentType, LazyExoticComponent } from "react";
+
+type FlowBoundaryModule = typeof import("./_flow-boundary");
+
+/**
+ * Wrap one implementation from the React Flow boundary in a `lazy()` component.
+ *
+ * @param pick Selects the implementation from the boundary module.
+ */
+export const lazyFlowPart = <P>(
+  pick: (module: FlowBoundaryModule) => ComponentType<P>,
+): LazyExoticComponent<ComponentType<P>> =>
+  lazy(() => import("./_flow-boundary").then((m) => ({ default: pick(m) })));

package/src/_interactive-terminal-xterm.ts

@@ -0,0 +1,32 @@
+/**
+ * The xterm.js half of `InteractiveTerminal`, split out so it can be reached
+ * through a dynamic `import()`.
+ *
+ * `@xterm/xterm` declares no `sideEffects`, so a static import from
+ * `interactive-terminal.tsx` put the whole emulator — plus its stylesheet — into
+ * the entry chunk of every `@elabs-ai/components-ai` consumer, including
+ * the vast majority that never render a terminal. The **stylesheet import has to
+ * live here too**: a bare `import "@xterm/xterm/css/xterm.css"` in the public
+ * module keeps the edge alive on its own.
+ *
+ * Unlike `_persona-rive.tsx` (a `lazy()` component boundary), this one follows
+ * `_lazy-mermaid.ts`: the engine is reached through a **late-called interface**.
+ * `InteractiveTerminal` only ever constructs xterm inside its mount effect —
+ * never during render — so the public component keeps its `forwardRef`, its
+ * imperative handle and its container `<div>` unchanged, and awaits this module
+ * inside that effect. No `Suspense` seam, no skeleton swap, no change to the box
+ * the terminal paints into (the container is sized by the consumer either way).
+ *
+ * `ITheme` and the two constructor types stay `import type` in the public module
+ * (types erase), which is what keeps `buildInteractiveTerminalTheme` public.
+ *
+ * See ADR 0019 and `pnpm heavy-deps:check`.
+ *
+ * @lazy-boundary This module must only ever be reached via `import()`. The gate
+ * fails if anything imports it statically, which would put xterm back in the
+ * entry chunk and make the dynamic import pointless.
+ */
+import "@xterm/xterm/css/xterm.css";
+
+export { FitAddon } from "@xterm/addon-fit";
+export { Terminal as XTerm } from "@xterm/xterm";

package/src/_lazy-mermaid.test.ts

@@ -0,0 +1,101 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createLazyMermaidPlugin, lazyMermaid, preloadMermaid } from "./_lazy-mermaid";
+
+/**
+ * The Mermaid engine is mocked so we can observe how the plugin drives it.
+ *
+ * NOTE this file tests the plugin's *behaviour*. That the engine is genuinely
+ * lazy is a property of the BUILD, not of jsdom — `vi.mock` factories are
+ * hoisted and cached, so a counter here would prove nothing. The static proof is
+ * `pnpm heavy-deps:check`, which asserts no `packages/ai/src` module statically
+ * imports mermaid, plus the built `packages/ai/dist/index.js` carrying
+ * `import("mermaid")` and no `@streamdown/mermaid` edge.
+ */
+const initialize = vi.fn();
+const render = vi.fn(async (id: string) => ({ svg: `<svg id="${id}"/>` }));
+
+vi.mock("mermaid", () => ({ default: { initialize, render } }));
+
+describe("lazy mermaid plugin", () => {
+  beforeEach(() => {
+    initialize.mockClear();
+    render.mockClear();
+  });
+
+  it("exposes the DiagramPlugin contract Streamdown expects", () => {
+    expect(lazyMermaid).toMatchObject({
+      language: "mermaid",
+      name: "mermaid",
+      type: "diagram",
+    });
+    expect(typeof lazyMermaid.getMermaid).toBe("function");
+  });
+
+  it("touches the engine only on render, never on getMermaid", () => {
+    // Streamdown calls getMermaid() immediately before awaiting render(); the
+    // plugin object being present from the first frame is what avoids a
+    // "raw source flashes, then becomes a diagram" transition.
+    createLazyMermaidPlugin().getMermaid();
+    expect(initialize).not.toHaveBeenCalled();
+    expect(render).not.toHaveBeenCalled();
+  });
+
+  it("delegates render to the engine and returns its svg", async () => {
+    const result = await createLazyMermaidPlugin().getMermaid().render("d1", "graph TD; A-->B;");
+
+    expect(render).toHaveBeenCalledWith("d1", "graph TD; A-->B;");
+    expect(result.svg).toContain("d1");
+  });
+
+  it("initializes exactly once across repeated renders", async () => {
+    const instance = createLazyMermaidPlugin().getMermaid();
+
+    await instance.render("d1", "graph TD; A-->B;");
+    await instance.render("d2", "graph TD; C-->D;");
+
+    expect(initialize).toHaveBeenCalledTimes(1);
+    expect(render).toHaveBeenCalledTimes(2);
+  });
+
+  it("applies the upstream brand defaults, including securityLevel: strict", async () => {
+    await createLazyMermaidPlugin().getMermaid().render("d1", "graph TD; A-->B;");
+
+    expect(initialize).toHaveBeenCalledWith(
+      expect.objectContaining({
+        fontFamily: "monospace",
+        securityLevel: "strict",
+        startOnLoad: false,
+        suppressErrorRendering: true,
+        theme: "default",
+      }),
+    );
+  });
+
+  it("merges a per-plugin config over the defaults", async () => {
+    await createLazyMermaidPlugin({ config: { theme: "dark" } })
+      .getMermaid()
+      .render("d1", "graph TD; A-->B;");
+
+    expect(initialize).toHaveBeenCalledWith(
+      expect.objectContaining({ securityLevel: "strict", theme: "dark" }),
+    );
+  });
+
+  it("lets getMermaid(config) override, and re-initializes for it", async () => {
+    const plugin = createLazyMermaidPlugin();
+
+    await plugin.getMermaid().render("d1", "graph TD; A-->B;");
+    await plugin.getMermaid({ theme: "forest" }).render("d2", "graph TD; C-->D;");
+
+    expect(initialize).toHaveBeenCalledTimes(2);
+    expect(initialize).toHaveBeenLastCalledWith(
+      expect.objectContaining({ securityLevel: "strict", theme: "forest" }),
+    );
+  });
+
+  it("preloadMermaid resolves without rendering anything", async () => {
+    expect(() => preloadMermaid()).not.toThrow();
+    expect(render).not.toHaveBeenCalled();
+  });
+});

package/src/_lazy-mermaid.ts

@@ -0,0 +1,117 @@
+/**
+ * A drop-in replacement for `@streamdown/mermaid`'s `mermaid` plugin that loads
+ * the Mermaid engine **on first diagram render** instead of at import time.
+ *
+ * Why this exists
+ * ---------------
+ * `@streamdown/mermaid`'s dist opens with a static `import n from "mermaid"`, and
+ * neither it nor `mermaid`/`dompurify`/`d3` declares `sideEffects`, so a bundler
+ * must keep the whole edge. `@elabs-ai/components-ai` imported that plugin from three modules
+ * (`message`, `reasoning`, `markdown-view`), which put Mermaid + d3 + DOMPurify —
+ * several MB — in the **entry chunk** of every consumer, including the vast
+ * majority that never render a diagram.
+ *
+ * How it avoids a render flash
+ * ----------------------------
+ * `DiagramPlugin` is not the engine; it is a lazy accessor. Streamdown calls
+ * `getMermaid()` only from inside its async diagram-render path (immediately
+ * before `await instance.render(...)`), never at module or component init. So the
+ * plugin object can be present from the very first frame — Streamdown always
+ * treats a ```mermaid fence as a diagram — while the engine itself arrives with a
+ * dynamic import inside `render()`. No content-sniffing, no plugin swap, no
+ * suspense seam at the call sites, and no "raw source flashes then becomes a
+ * diagram" transition.
+ *
+ * The upstream plugin is ~10 lines; its defaults and initialize-once semantics
+ * are mirrored exactly below. The `DiagramPlugin` type is still imported (as a
+ * type, so it erases) from `@streamdown/mermaid`, which keeps this honest against
+ * the real contract at typecheck time.
+ */
+import type { DiagramPlugin, MermaidConfig, MermaidInstance } from "@streamdown/mermaid";
+
+/** Mirrors `@streamdown/mermaid`'s defaults — notably `securityLevel: "strict"`. */
+const DEFAULT_CONFIG: MermaidConfig = {
+  fontFamily: "monospace",
+  securityLevel: "strict",
+  startOnLoad: false,
+  suppressErrorRendering: true,
+  theme: "default",
+};
+
+type MermaidModule = {
+  initialize: (config: MermaidConfig) => void;
+  render: (id: string, source: string) => Promise<{ svg: string }>;
+};
+
+/**
+ * Module-level singleton: the engine is fetched at most once per app, however
+ * many diagrams or Streamdown instances render.
+ */
+let enginePromise: Promise<MermaidModule> | undefined;
+
+const loadEngine = (): Promise<MermaidModule> => {
+  enginePromise ??= import("mermaid").then((m) => m.default as unknown as MermaidModule);
+  return enginePromise;
+};
+
+/**
+ * Start fetching the Mermaid engine ahead of time.
+ *
+ * Optional. Call it when you already know the surface will render diagrams (on
+ * route entry, or when a conversation is known to contain them) so the first
+ * diagram doesn't pay the import latency. Safe to call repeatedly; safe to
+ * ignore — rendering a diagram loads the engine either way.
+ */
+export const preloadMermaid = (): void => {
+  void loadEngine();
+};
+
+/**
+ * Create a lazy Mermaid diagram plugin for Streamdown.
+ *
+ * @param options.config Mermaid config merged over the brand defaults.
+ */
+export const createLazyMermaidPlugin = (
+  options: { config?: MermaidConfig } = {},
+): DiagramPlugin => {
+  let initialized = false;
+  let config: MermaidConfig = { ...DEFAULT_CONFIG, ...options.config };
+
+  const instance: MermaidInstance = {
+    // Upstream calls `mermaid.initialize` synchronously here. We can't (the
+    // engine may not have loaded yet), so record the config and apply it inside
+    // `render`, which is the only place it can matter — Streamdown always calls
+    // `getMermaid()` immediately before awaiting `render()`.
+    initialize(next: MermaidConfig) {
+      config = { ...DEFAULT_CONFIG, ...options.config, ...next };
+      initialized = false;
+    },
+    async render(id: string, source: string) {
+      const engine = await loadEngine();
+      if (!initialized) {
+        engine.initialize(config);
+        initialized = true;
+      }
+      return engine.render(id, source);
+    },
+  };
+
+  return {
+    getMermaid(next?: MermaidConfig) {
+      if (next) {
+        instance.initialize(next);
+      }
+      return instance;
+    },
+    language: "mermaid",
+    name: "mermaid",
+    type: "diagram",
+  };
+};
+
+/**
+ * The shared lazy Mermaid plugin — the `@elabs-ai/components-ai` replacement for
+ * `@streamdown/mermaid`'s eager `mermaid` export. One instance for the whole
+ * app, so the engine and its initialize-once state are shared.
+ */
+export const lazyMermaid: DiagramPlugin = createLazyMermaidPlugin();