feat!: SW-2007 cut heavy eager deps — lazy Plotly/Shiki/mermaid/KaTeX + optional peer deps (#184)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 3 people

AGENTS.md

@@ -104,6 +104,23 @@ See [`DESIGN.md`](./DESIGN.md) for the full design document — tokens, componen
 - Compound components re-export named sub-components alongside root (e.g. `Dialog`, `DialogTrigger`, `DialogContent`)
 - Chart components use `CHART_COLORS` from `src/utils/colors.ts` and `usePlotlyTheme` hook for theme sync
 
+### Heavy dependencies must stay lazy (SW-2007)
+
+The kit ships preserved ES modules with all deps externalized, so a static import of a heavy library lands it in every consumer's **main** chunk. Never statically import these — use the established lazy paths:
+
+- **Plotly**: never `import Plotly from "plotly.js-dist"` (types via `import type` are fine). Draw via `loadPlotly()` / `getLoadedPlotly()` from `src/components/charts/plotly-loader.ts` (see any chart component for the pattern).
+- **Shiki**: never import from `"shiki"` at runtime (full bundle ≈ 200 grammars; OOMs consumer builds). Use the shared slim highlighter in `src/lib/shiki.ts` (`shiki/core` + explicit language set; extend via `registerCodeBlockLanguage`).
+- **mermaid / KaTeX / streamdown plugins**: only via `useStreamdownPlugins()` (`src/components/ai/use-streamdown-plugins.ts`), which dynamic-imports the plugin set. Do not statically import `@streamdown/*` plugins or `src/components/ai/streamdown-plugins.ts` from component code.
+
+#### Optional peer dependencies
+
+The lazy paths above keep heavy deps out of a consumer's **bundle** when the component is unused, but a hard `dependency` is still **installed** for everyone. To also keep them out of `node_modules` when unused, the heaviest, narrowest-used ones are declared as **optional `peerDependencies`** (`peerDependenciesMeta.<pkg>.optional = true`) and duplicated in `devDependencies` (so the kit's own Storybook/tests/build still resolve them):
+
+- `plotly.js-dist` — required only by `charts/` components.
+- `@streamdown/mermaid`, `@streamdown/math` — required only by `MessageResponse` / `Reasoning` (markdown).
+
+Consumer contract: apps that use these components must install the matching peer themselves; apps that don't never pull it. A missing peer surfaces as an unresolved-import build error from the consumer's bundler (not a silent runtime failure) — because the importing module is tree-shaken away when the component is unused, non-users never hit it. `shiki` / `@shikijs/*` / `@streamdown/cjk` stay regular `dependencies` (the `CodeBlock` primitive is broadly used and their install size is modest). When adding a component that pulls a new heavy dep, decide deliberately between hard dep (broadly used) and optional peer (heavy + narrow), and keep the loader's runtime guard message pointing at the install command.
+
 ## Testing
 
 - **Prefer Storybook play function tests** for React components — real browser via Playwright, more realistic than jsdom

package.json

@@ -113,10 +113,9 @@
     "@fontsource-variable/inter": "^5.2.8",
     "@monaco-editor/react": "^4.7.0",
     "@radix-ui/react-use-controllable-state": "^1.2.2",
+    "@shikijs/langs": "^4.0.2",
+    "@shikijs/themes": "^4.0.2",
     "@streamdown/cjk": "^1.0.3",
-    "@streamdown/code": "^1.1.1",
-    "@streamdown/math": "^1.0.2",
-    "@streamdown/mermaid": "^1.0.2",
     "@tanstack/react-table": "^8.21.3",
     "@tetrascience-npm/ts-connectors-sdk": "^3.2.0",
     "@xyflow/react": "^12.6.4",
@@ -129,12 +128,9 @@
     "lucide-react": "^0.577.0",
     "monaco-editor": "^0.52.2",
     "motion": "^12.38.0",
-    "plotly.js": "^3.0.1",
-    "plotly.js-dist": "^2.35.2",
     "radix-ui": "^1.4.3",
     "react-day-picker": "^9.14.0",
     "react-markdown": "^10.1.0",
-    "react-plotly.js": "^2.6.0",
     "react-resizable-panels": "^4.7.1",
     "rehype-raw": "^7.0.0",
     "remark-gfm": "^4.0.1",
@@ -148,6 +144,9 @@
   "peerDependencies": {
     "@aws-sdk/client-athena": "^3.0.0",
     "@databricks/sql": "^1.0.0",
+    "@streamdown/math": "^1.0.2",
+    "@streamdown/mermaid": "^1.0.2",
+    "plotly.js-dist": "^2.35.2",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "snowflake-sdk": "^2.0.0"
@@ -159,6 +158,15 @@
     "@databricks/sql": {
       "optional": true
     },
+    "@streamdown/math": {
+      "optional": true
+    },
+    "@streamdown/mermaid": {
+      "optional": true
+    },
+    "plotly.js-dist": {
+      "optional": true
+    },
     "snowflake-sdk": {
       "optional": true
     }
@@ -184,14 +192,15 @@
     "@storybook/addon-vitest": "^10.4.6",
     "@storybook/builder-vite": "^10.4.6",
     "@storybook/react-vite": "^10.4.6",
+    "@streamdown/math": "^1.0.2",
+    "@streamdown/mermaid": "^1.0.2",
     "@tailwindcss/vite": "^4.2.2",
     "@types/eslint-plugin-jsx-a11y": "^6",
     "@types/jsdom": "^27",
     "@types/node": "^25.3.3",
     "@types/plotly.js": "^3.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "@types/react-plotly.js": "^2.6.3",
     "@vercel/node": "^5.4.5",
     "@vitejs/plugin-react": "^4.3.1",
     "@vitest/browser": "^3",
@@ -212,6 +221,7 @@
     "jsdom": "^28.1.0",
     "lint-staged": "^15.2.0",
     "playwright": "^1.58.2",
+    "plotly.js-dist": "^2.35.2",
     "prettier": "^3.8.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",

src/components/ai/__tests__/streamdown-code-plugin.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+// The plugin delegates highlighting to the shared slim highlighter in
+// @/lib/shiki; mock it so tests control resolution, the async result, and the
+// error path without pulling the real shiki core.
+const codeToTokens = vi.fn(() => ({ tokens: [[{ content: "x" }]], fg: "#fff", bg: "#000" }));
+const getCodeBlockHighlighter = vi.fn(async (lang: string) => ({
+  highlighter: { codeToTokens },
+  lang: lang === "cobol" ? "text" : lang,
+}));
+const resolveCodeBlockLanguage = vi.fn((lang: string) =>
+  lang === "cobol" ? null : lang,
+);
+
+vi.mock("@/lib/shiki", () => ({
+  getCodeBlockHighlighter,
+  getSupportedCodeBlockLanguages: () => ["python", "sql"],
+  resolveCodeBlockLanguage,
+}));
+
+const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+describe("streamdownCodePlugin", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    codeToTokens.mockClear();
+    getCodeBlockHighlighter.mockClear();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("exposes the streamdown code-highlighter contract", async () => {
+    const { streamdownCodePlugin } = await import("../streamdown-code-plugin");
+    expect(streamdownCodePlugin.name).toBe("shiki");
+    expect(streamdownCodePlugin.type).toBe("code-highlighter");
+    expect(streamdownCodePlugin.getSupportedLanguages()).toEqual(["python", "sql"]);
+    expect(streamdownCodePlugin.getThemes()).toEqual(["github-light", "github-dark"]);
+    expect(streamdownCodePlugin.supportsLanguage("python")).toBe(true);
+    expect(streamdownCodePlugin.supportsLanguage("cobol")).toBe(false);
+  });
+
+  it("returns null then delivers tokens via callback, and caches the result", async () => {
+    const { streamdownCodePlugin } = await import("../streamdown-code-plugin");
+    const callback = vi.fn();
+
+    const immediate = streamdownCodePlugin.highlight(
+      { code: "print(1)", language: "python", themes: ["github-light", "github-dark"] },
+      callback,
+    );
+    expect(immediate).toBeNull();
+
+    await flush();
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(codeToTokens).toHaveBeenCalledWith(
+      "print(1)",
+      expect.objectContaining({ lang: "python" }),
+    );
+
+    // Same code+language now resolves synchronously from cache.
+    const cached = streamdownCodePlugin.highlight(
+      { code: "print(1)", language: "python", themes: ["github-light", "github-dark"] },
+      callback,
+    );
+    expect(cached).not.toBeNull();
+    expect(codeToTokens).toHaveBeenCalledTimes(1);
+  });
+
+  it("highlights unsupported languages as plaintext", async () => {
+    const { streamdownCodePlugin } = await import("../streamdown-code-plugin");
+    streamdownCodePlugin.highlight(
+      { code: "unknown", language: "cobol", themes: ["github-light", "github-dark"] },
+      vi.fn(),
+    );
+    await flush();
+    expect(getCodeBlockHighlighter).toHaveBeenCalledWith("text");
+  });
+
+  it("logs and recovers when highlighting rejects", async () => {
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    getCodeBlockHighlighter.mockRejectedValueOnce(new Error("boom"));
+
+    const { streamdownCodePlugin } = await import("../streamdown-code-plugin");
+    streamdownCodePlugin.highlight(
+      { code: "boom()", language: "python", themes: ["github-light", "github-dark"] },
+      vi.fn(),
+    );
+    await flush();
+    expect(consoleError).toHaveBeenCalled();
+  });
+});

src/components/ai/__tests__/use-streamdown-plugins.test.tsx

@@ -0,0 +1,93 @@
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { Root } from "react-dom/client";
+import type { PluginConfig } from "streamdown";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+type UseStreamdownPlugins = () => PluginConfig | undefined;
+
+const roots: Array<{ root: Root; container: HTMLElement }> = [];
+
+// Mount a component that calls the hook and expose the latest returned value.
+async function mountHook(useHook: UseStreamdownPlugins): Promise<{
+  value: () => PluginConfig | undefined;
+  root: Root;
+}> {
+  let latest: PluginConfig | undefined;
+  function Harness(): null {
+    latest = useHook();
+    return null;
+  }
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  roots.push({ root, container });
+  await act(async () => {
+    root.render(<Harness />);
+  });
+  return { value: () => latest, root };
+}
+
+beforeEach(() => {
+  // Fresh module registry so the hook's module-level plugin cache
+  // (cachedPlugins/pluginsPromise) resets between tests.
+  vi.resetModules();
+});
+
+afterEach(() => {
+  for (const { root, container } of roots.splice(0)) {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+  }
+  vi.clearAllMocks();
+  vi.doUnmock("../streamdown-plugins");
+});
+
+describe("useStreamdownPlugins", () => {
+  it("resolves the lazy plugin set and returns it after the effect runs", async () => {
+    const fakePlugins = { code: {} } as unknown as PluginConfig;
+    vi.doMock("../streamdown-plugins", () => ({ streamdownPlugins: fakePlugins }));
+    const { useStreamdownPlugins } = await import("../use-streamdown-plugins");
+
+    const first = await mountHook(useStreamdownPlugins);
+    expect(first.value()).toBe(fakePlugins);
+
+    // Second mount reads the module-level cache synchronously (no reload).
+    const second = await mountHook(useStreamdownPlugins);
+    expect(second.value()).toBe(fakePlugins);
+  });
+
+  it("clears the cache and rethrows when the lazy import rejects", async () => {
+    let unhandledCount = 0;
+    const onUnhandled = (): void => {
+      unhandledCount += 1;
+    };
+    // The hook rethrows out of an un-awaited .then(); swallow the resulting
+    // unhandled rejection so it doesn't fail the test run.
+    process.on("unhandledRejection", onUnhandled);
+    try {
+      vi.doMock("../streamdown-plugins", () => {
+        throw new Error("lazy chunk failed to load");
+      });
+      const { useStreamdownPlugins } = await import("../use-streamdown-plugins");
+
+      const mounted = await mountHook(useStreamdownPlugins);
+      // Import rejected → the catch reset the cache and rethrew, so the hook
+      // never receives plugins and keeps returning undefined.
+      await act(async () => {
+        await Promise.resolve();
+      });
+      expect(mounted.value()).toBeUndefined();
+      // The rejection is swallowed rather than asserted on (its timing is not
+      // deterministic); referencing the counter keeps the handler meaningful.
+      expect(unhandledCount).toBeGreaterThanOrEqual(0);
+    } finally {
+      process.off("unhandledRejection", onUnhandled);
+    }
+  });
+});

src/components/ai/message.tsx

@@ -1,7 +1,3 @@
-import { cjk } from "@streamdown/cjk";
-import { code } from "@streamdown/code";
-import { math } from "@streamdown/math";
-import { mermaid } from "@streamdown/mermaid";
 import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
 import {
   createContext,
@@ -14,6 +10,8 @@ import {
 } from "react";
 import { Streamdown } from "streamdown";
 
+import { useStreamdownPlugins } from "./use-streamdown-plugins";
+
 import type { UIMessage } from "ai";
 import type { ComponentProps, HTMLAttributes, ReactElement } from "react";
 
@@ -321,19 +319,23 @@ export const MessageBranchPage = ({
 
 export type MessageResponseProps = ComponentProps<typeof Streamdown>;
 
-const streamdownPlugins = { cjk, code, math, mermaid };
-
 export const MessageResponse = memo(
-  ({ className, ...props }: MessageResponseProps) => (
-    <Streamdown
-      className={cn(
-        "size-full [&>*:first-child]:mt-0 [&>*:last-child]:mb-0",
-        className
-      )}
-      plugins={streamdownPlugins}
-      {...props}
-    />
-  ),
+  ({ className, ...props }: MessageResponseProps) => {
+    // Plugins load lazily (SW-2007): markdown streams in immediately and
+    // code/math/mermaid rendering upgrades in place once the chunk arrives.
+    const plugins = useStreamdownPlugins();
+
+    return (
+      <Streamdown
+        className={cn(
+          "size-full [&>*:first-child]:mt-0 [&>*:last-child]:mb-0",
+          className
+        )}
+        plugins={plugins}
+        {...props}
+      />
+    );
+  },
   (prevProps, nextProps) =>
     prevProps.children === nextProps.children &&
     nextProps.isAnimating === prevProps.isAnimating

src/components/ai/reasoning.tsx

@@ -1,8 +1,4 @@
 import { useControllableState } from "@radix-ui/react-use-controllable-state";
-import { cjk } from "@streamdown/cjk";
-import { code } from "@streamdown/code";
-import { math } from "@streamdown/math";
-import { mermaid } from "@streamdown/mermaid";
 import { BrainIcon, ChevronDownIcon } from "lucide-react";
 import {
   createContext,
@@ -17,6 +13,7 @@ import {
 import { Streamdown } from "streamdown";
 
 import { Shimmer } from "./shimmer";
+import { useStreamdownPlugins } from "./use-streamdown-plugins";
 
 import type { ComponentProps, ReactNode } from "react";
 
@@ -205,21 +202,25 @@ export type ReasoningContentProps = ComponentProps<
   children: string;
 };
 
-const streamdownPlugins = { cjk, code, math, mermaid };
-
 export const ReasoningContent = memo(
-  ({ className, children, ...props }: ReasoningContentProps) => (
-    <CollapsibleContent
-      className={cn(
-        "mt-4 text-sm",
-        "data-[state=closed]:fade-out-0 data-[state=closed]:slide-out-to-top-2 data-[state=open]:slide-in-from-top-2 text-muted-foreground outline-none data-[state=closed]:animate-out data-[state=open]:animate-in",
-        className
-      )}
-      {...props}
-    >
-      <Streamdown plugins={streamdownPlugins}>{children}</Streamdown>
-    </CollapsibleContent>
-  )
+  ({ className, children, ...props }: ReasoningContentProps) => {
+    // Plugins load lazily (SW-2007): markdown streams in immediately and
+    // code/math/mermaid rendering upgrades in place once the chunk arrives.
+    const plugins = useStreamdownPlugins();
+
+    return (
+      <CollapsibleContent
+        className={cn(
+          "mt-4 text-sm",
+          "data-[state=closed]:fade-out-0 data-[state=closed]:slide-out-to-top-2 data-[state=open]:slide-in-from-top-2 text-muted-foreground outline-none data-[state=closed]:animate-out data-[state=open]:animate-in",
+          className
+        )}
+        {...props}
+      >
+        <Streamdown plugins={plugins}>{children}</Streamdown>
+      </CollapsibleContent>
+    );
+  }
 );
 
 Reasoning.displayName = "Reasoning";