@elabs-ai/components-ai 4.0.0 → 4.2.0

package/src/markdown-view.stories.tsx

@@ -1,11 +1,47 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { ComponentProps } from "react";
+import {
+  InlineCitation,
+  InlineCitationCard,
+  InlineCitationCardBody,
+  InlineCitationCardTrigger,
+} from "./inline-citation";
 import { MarkdownView } from "./markdown-view";
 
 const meta = {
   title: "AI/MarkdownView",
   component: MarkdownView,
   tags: ["autodocs"],
-  parameters: { layout: "padded" },
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "A model-authored answer or a read-only markdown DOCUMENT, rendered as a " +
+          "document — never as Shiki source. " +
+          "Pick a markdown renderer by where the markdown is going to be READ: a " +
+          "read-only document in a chat or a side rail → `AI/MarkdownView`; the preview " +
+          "pane of the markdown editor → `Editor/MarkdownPreview`; a file the app did " +
+          "not write → the markdown adapter behind `Viewer/FileViewer`; streaming into " +
+          "a message as the model writes it → `MessageResponse` on `AI/Message`. See " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs)." +
+          " Its own seams: `baseHeadingLevel` constrains the heading rungs so a " +
+          "document `#` inside a 20rem rail lands on the `title` rung instead of " +
+          "becoming the biggest text on screen, and the sanitiser chain is LOCKED — " +
+          "`rehypePlugins` is omitted at the type level and stripped at runtime, so a " +
+          "caller cannot widen what a model is allowed to emit. It understands no brand " +
+          "directives; those belong to the editor preview.\n\n" +
+          "All three map their element tree onto the same `Prose*` primitives owned " +
+          "by `@elabs-ai/components-ui` (`@elabs-ai/components-editor` re-exports them " +
+          "under short names). The element MAPS stay per-surface on purpose — " +
+          "`@elabs-ai/components-ai`, `@elabs-ai/components-editor` and " +
+          "`@elabs-ai/components-viewer` are leaves that may not import one another, and " +
+          "`streamdown` deliberately never moves down into `@elabs-ai/components-ui`, or " +
+          "every consumer of every foundation component would carry it. One prose source, " +
+          "several renderers.",
+      },
+    },
+  },
 } satisfies Meta<typeof MarkdownView>;
 export default meta;
 type Story = StoryObj<typeof meta>;
@@ -55,3 +91,58 @@ export const ConstrainedHeadings: Story = {
     ),
   ],
 };
+
+const CITED_DOC = `## Q3 answer
+
+Revenue grew **12.4% QoQ**, led by EMEA[1](https://example.com/q3-report) with a smaller
+lift from APAC[2](https://example.com/apac-notes).
+
+Regular links are unaffected — see the [dashboard](https://example.com/dashboard) for the
+full breakdown.
+`;
+
+/** A markdown `a` renderer that swaps a `[1](url)`-style citation marker for an
+ * interactive `InlineCitation` chip; any other link renders exactly as before. */
+const citationLinkComponent: NonNullable<
+  ComponentProps<typeof MarkdownView>["components"]
+>["a"] = ({ href, children, node: _node, ...props }) => {
+  const label = typeof children === "string" ? children : "";
+  if (href && /^\d+$/.test(label)) {
+    return (
+      <InlineCitation>
+        <InlineCitationCard>
+          <InlineCitationCardTrigger sources={[href]} />
+          <InlineCitationCardBody>
+            <div className="p-3 text-meta text-muted-foreground">Source {label}</div>
+          </InlineCitationCardBody>
+        </InlineCitationCard>
+      </InlineCitation>
+    );
+  }
+  return (
+    <a href={href} rel="noopener noreferrer" target="_blank" {...props}>
+      {children}
+    </a>
+  );
+};
+
+/**
+ * The #10 motivating use case: a RAG answer's markdown emits `[1](url)`-style
+ * citation markers. Overriding `components.a` swaps those for `InlineCitation`
+ * chips — every other element (the `##` heading, the "dashboard" link) still
+ * renders through the internal Prose* map because `MarkdownView` MERGES the
+ * override in per key rather than replacing the whole map.
+ */
+export const InlineCitations: Story = {
+  args: {
+    children: CITED_DOC,
+    components: { a: citationLinkComponent },
+  },
+  decorators: [
+    (Story) => (
+      <div className="max-w-prose">
+        <Story />
+      </div>
+    ),
+  ],
+};

package/src/markdown-view.test.tsx

@@ -1,5 +1,7 @@
-import { cleanup, render, screen } from "@testing-library/react";
-import { afterEach, describe, expect, it } from "vitest";
+import { math } from "@streamdown/math";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import type { ComponentProps } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { MarkdownView } from "./markdown-view";
 
 afterEach(cleanup);
@@ -34,3 +36,236 @@ describe("MarkdownView (#193, research 04 §5 — document, not Shiki source)",
     expect(screen.getByRole("heading", { level: 2, name: "Board note" })).toBeInTheDocument();
   });
 });
+
+describe("MarkdownView components/plugins overrides (#10 — inline citations)", () => {
+  const CITATION_DOC = `# Board note
+
+Revenue grew[1](https://example.com/report) this quarter.
+
+A paragraph with [a link](https://example.com) and \`inline\` code.
+
+- first
+- second
+`;
+
+  it("uses a consumer-supplied `components` entry for one element type", () => {
+    render(
+      <MarkdownView
+        components={{
+          a: ({ href, children }) => (
+            <span data-testid="citation-chip" data-href={href}>
+              [{children}]
+            </span>
+          ),
+        }}
+      >
+        {CITATION_DOC}
+      </MarkdownView>,
+    );
+
+    // The overridden `a` renders through the consumer's component…
+    const chips = screen.getAllByTestId("citation-chip");
+    expect(chips).toHaveLength(2);
+    expect(chips[0]).toHaveAttribute("data-href", "https://example.com/report");
+    // …and NOT through the internal ProseLink (no anchor role at all now).
+    expect(screen.queryByRole("link")).not.toBeInTheDocument();
+  });
+
+  it("keeps the internal prose styling for element types the consumer did NOT override", () => {
+    // `baseHeadingLevel` is what makes this discriminating: a plain object
+    // merge/replace of `components` still satisfies role=heading (Streamdown's
+    // OWN default `h1` is still a real <h1>), but ONLY buildProseComponents()
+    // knows about baseHeadingLevel's h1→h2 remap. If MarkdownView's merge drops
+    // the internal map for keys the consumer didn't set, this regresses to h1.
+    render(
+      <MarkdownView
+        baseHeadingLevel={2}
+        components={{
+          a: ({ children }) => <span data-testid="citation-chip">{children}</span>,
+        }}
+      >
+        {CITATION_DOC}
+      </MarkdownView>,
+    );
+
+    expect(screen.queryByRole("heading", { level: 1 })).not.toBeInTheDocument();
+    expect(screen.getByRole("heading", { level: 2, name: "Board note" })).toBeInTheDocument();
+    expect(screen.getAllByRole("listitem")).toHaveLength(2);
+  });
+
+  it("merges a real `plugins.cjk` override in (append), keeps sanitisation on, and keeps the untouched `plugins.math` default alive (#10)", async () => {
+    // A real, discriminating lock — NOT `plugins={{}}` (that exercises zero
+    // slots and passes identically under merge, replace, or a no-op; #10
+    // review I3). This test supplies a genuine `cjk` plugin (one of the two
+    // slots MarkdownView actually reaches — `code`/`mermaid`/`renderers` are
+    // consulted only inside Streamdown's OWN default `code` renderer, which
+    // `buildProseComponents()` always shadows) and proves BOTH halves of the
+    // merge property:
+    //   1. Streamdown's default rehypePlugins (raw → sanitize → harden)
+    //      still hold — a <script> is stripped.
+    //   2. The supplied `cjk` plugin APPENDS (its remark transformer runs)
+    //      *and* the internal `math` default the consumer did NOT set
+    //      SURVIVES alongside it (`$$x^2$$` renders as real KaTeX, not
+    //      literal text). A REPLACE implementation
+    //      (`plugins = pluginOverrides`) would drop `math` — along with
+    //      `code`/`mermaid` — the moment a consumer sets `cjk`, and this
+    //      assertion would fail.
+    const cjkRemarkSpy = vi.fn(() => (tree: unknown) => tree);
+    const customCjkPlugin: NonNullable<
+      NonNullable<ComponentProps<typeof MarkdownView>["plugins"]>["cjk"]
+    > = {
+      name: "cjk",
+      remarkPlugins: [],
+      remarkPluginsAfter: [cjkRemarkSpy],
+      remarkPluginsBefore: [],
+      type: "cjk",
+    };
+    const UNSAFE_DOC = `# Note
+
+<script>window.__pwned = true;</script>
+
+$$x^2$$
+`;
+    render(<MarkdownView plugins={{ cjk: customCjkPlugin }}>{UNSAFE_DOC}</MarkdownView>);
+
+    // (1) sanitisation still holds.
+    expect(document.querySelector("script")).not.toBeInTheDocument();
+    expect(document.body.textContent).not.toMatch(/pwned/);
+    // (2a) the supplied `cjk` plugin appended (its transformer ran)…
+    expect(cjkRemarkSpy).toHaveBeenCalled();
+    // (2b) …and the internal `math` default the consumer did not set is
+    // still active — real KaTeX markup, not the literal `$$x^2$$` text.
+    // `math` is now lazy-loaded off the source text (#perf-5) — it starts
+    // `undefined` and arrives after a dynamic import, hence `waitFor`.
+    await waitFor(() => {
+      expect(document.querySelector(".katex")).toBeInTheDocument();
+    });
+  });
+});
+
+describe("MarkdownView sanitiser is not overridable (#36)", () => {
+  it("ignores a caller-supplied rehypePlugins array (the sanitiser is not overridable)", () => {
+    // A rehype plugin that appends a <script> AFTER the pipeline. Under the bug the
+    // consumer array REPLACES [rehypeRaw, rehypeSanitize, harden], so nothing strips it.
+    const injectScript = () => (tree: { children: unknown[] }) => {
+      tree.children.push({
+        type: "element",
+        tagName: "script",
+        properties: {},
+        children: [{ type: "text", value: "globalThis.__pwned = true" }],
+      });
+    };
+    const { container } = render(
+      // `as any`: a JS consumer, an `any`, or a wider spread object still reaches
+      // this path even after the type-level `Omit`, so the assertion must exercise
+      // the RUNTIME strip, not the type. (`as never` doesn't typecheck as a JSX
+      // spread — TS2698, "Spread types may only be created from object types" —
+      // `any` is the cast the issue itself names as the bypass vector.)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- deliberate: proves the runtime strip, not the type
+      <MarkdownView {...({ rehypePlugins: [injectScript] } as any)}>{"# hi"}</MarkdownView>,
+    );
+    expect(container.querySelector("script")).toBeNull();
+  });
+
+  it("SUPPORTS a caller-supplied remarkPlugins array, and still sanitises what it injects", () => {
+    // PR #74 review, round 1: `remarkPlugins` is NOT a sanitiser override. It runs
+    // upstream of [rehypeRaw, rehypeSanitize, harden], which Streamdown derives
+    // without reading it — so the prop stays supported (no `as any` below: the TYPE
+    // must accept it) while its output is still sanitised. Both halves are asserted,
+    // so re-adding it to the runtime strip fails, and dropping the rehype chain fails.
+    const ran = vi.fn();
+    const injectHostile = () => (tree: { children: unknown[] }) => {
+      ran();
+      tree.children.push({
+        type: "html",
+        value: '<script>globalThis.__pwned = true</script><img src="x" onerror="void 0">',
+      });
+      tree.children.push({
+        type: "paragraph",
+        data: { hName: "script", hChildren: [{ type: "text", value: "globalThis.__x = 1" }] },
+        children: [],
+      });
+    };
+    const { container } = render(
+      <MarkdownView remarkPlugins={[injectHostile]}>{"# hi"}</MarkdownView>,
+    );
+
+    expect(ran).toHaveBeenCalled(); // the prop really reached Streamdown
+    expect(container.querySelector("script")).toBeNull();
+    expect(container.querySelector("[onerror]")).toBeNull();
+    expect(document.body.textContent).not.toMatch(/pwned/);
+  });
+});
+
+describe("MarkdownView trusted plugin slots run after the sanitiser (#76)", () => {
+  // `plugins.math.rehypePlugin` is appended to the END of Streamdown's rehype
+  // pipeline, i.e. AFTER `rehype-raw` → `rehype-sanitize` → `rehype-harden`, so
+  // whatever it emits is never re-sanitised. That is a deliberate, documented
+  // trusted-code seam (a consumer who can supply an executable `Pluggable` can
+  // already run code in their own bundle) — but until #76 it had no runtime
+  // half at all, unlike `rehypePlugins`. These three tests are the runtime half:
+  // it WARNS (1), it does not become noise (2), and it stays OPEN (3).
+  const injectScript = () => (tree: { children: unknown[] }) => {
+    tree.children.push({
+      type: "element",
+      tagName: "script",
+      properties: {},
+      children: [{ type: "text", value: "globalThis.__pwned76 = true" }],
+    });
+  };
+  const evilMath = { ...math, rehypePlugin: injectScript };
+
+  it("warns when a consumer replaces plugins.math.rehypePlugin", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      render(<MarkdownView plugins={{ math: evilMath }}>{"# hi"}</MarkdownView>);
+      const messages = warn.mock.calls.flat().join("\n");
+      expect(messages).toMatch(/math\.rehypePlugin/);
+      expect(messages).toMatch(/after/i);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("does not warn for the default plugin set or a safe slot override", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      render(<MarkdownView>{"# hi"}</MarkdownView>);
+      cleanup();
+      // A `cjk` override is remark-stage only — its output is re-sanitised
+      // downstream, so it is NOT a trust boundary and must stay silent. This is
+      // the arm that stops the warning degrading into noise consumers learn to
+      // ignore.
+      const customCjkPlugin: NonNullable<
+        NonNullable<ComponentProps<typeof MarkdownView>["plugins"]>["cjk"]
+      > = {
+        name: "cjk",
+        remarkPlugins: [],
+        remarkPluginsAfter: [],
+        remarkPluginsBefore: [],
+        type: "cjk",
+      };
+      render(<MarkdownView plugins={{ cjk: customCjkPlugin }}>{"# hi"}</MarkdownView>);
+      expect(warn).not.toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("documents the boundary rather than closing it (the slot stays open)", () => {
+    // Counter-intuitive but load-bearing: this pins the deliberate trusted-code
+    // escape hatch OPEN. A future "hardening" that strips the slot would break a
+    // legitimate consumer (a real KaTeX/math plugin) silently — this fails loudly
+    // instead. The defence is the warning above plus the documented boundary,
+    // NOT removing the capability.
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const { container } = render(
+        <MarkdownView plugins={{ math: evilMath }}>{"# hi"}</MarkdownView>,
+      );
+      expect(container.querySelector("script")).not.toBeNull();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});

package/src/markdown-view.tsx

@@ -7,8 +7,28 @@
  * was the ASSET-2 defect: `CodeBlock code={…} language="markdown"`). Built on
  * the EXISTING `streamdown` dependency (no new heavy dep), but unlike the
  * streaming `MessageResponse` it maps the element tree onto the promoted
- * `Prose*` primitives from `@elabs-ai/components-ui` via a `components` map — one
- * source-owned prose set for chat answers, the editor preview and this view.
+ * `Prose*` primitives from `@elabs-ai/components-ui` via a `components` map.
+ *
+ * What is SHARED is the `Prose*` set — plus the Streamdown locale bridge in
+ * `_streamdown-i18n` and `ui`'s `streamdown-translations` — NOT the renderer and
+ * NOT the element map. The wording this docblock used to carry ("one source-owned
+ * prose set for chat answers, the editor preview and this view") kept being read
+ * as "one renderer", and it never meant that. Three branded document renderers
+ * ship, and their element MAPS stay per-surface on purpose:
+ *   - this view — `baseHeadingLevel` for a constrained rung, and a sanitiser
+ *     chain locked at the type level AND at runtime;
+ *   - `@elabs-ai/components-editor`'s `MarkdownPreview` — the brand `:::card` /
+ *     `:::callout` / `::metric` / `:::timeline` dialect, and every standard
+ *     element wrapped to attach `data-sourcepos`, the ghost-diff wash and the
+ *     search wash, with slug ids and a heading-action slot on headings;
+ *   - `@elabs-ai/components-viewer`'s markdown adapter — a file the app did not
+ *     write, so no plugins and no streaming.
+ * `ai`, `editor` and `viewer` are layer-2 leaves that may not import one
+ * another, so the half that COULD move down already has; and `streamdown` must
+ * never follow it into `ui` — see the rule stated in
+ * `packages/ui/src/lib/streamdown-translations.ts` — or every consumer of every
+ * foundation component would carry it. Re-litigated and re-ratified 2026-09-03:
+ * the three maps are the decision, not an unpaid debt.
  *
  * `baseHeadingLevel` is the constrained-rung seam (research 04 §5 / 09 §G.2):
  * inside a narrow rail pass `baseHeadingLevel={2}` so a document `#` renders
@@ -26,12 +46,19 @@ import {
   type ProseHeadingLevel,
 } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
-import { useStreamdownPlugins, useStreamdownTranslations } from "./_streamdown-i18n";
+import { stripSanitizerOverrides, warnOnTrustedPluginSlots } from "./_streamdown-safety";
+import {
+  getStreamdownPluginsKey,
+  useStreamdownMermaidOptions,
+  useStreamdownPlugins,
+  useStreamdownTranslations,
+} from "./_streamdown-i18n";
 import type { ComponentProps } from "react";
 import { useMemo } from "react";
 import { Streamdown } from "streamdown";
 
 type StreamdownComponents = NonNullable<ComponentProps<typeof Streamdown>["components"]>;
+type StreamdownPlugins = ComponentProps<typeof Streamdown>["plugins"];
 
 const MAX_HEADING_LEVEL = 6;
 
@@ -75,7 +102,7 @@ function buildProseComponents(baseHeadingLevel: ProseHeadingLevel): StreamdownCo
 
 export interface MarkdownViewProps extends Omit<
   ComponentProps<typeof Streamdown>,
-  "components" | "plugins"
+  "components" | "plugins" | "rehypePlugins"
 > {
   /**
    * The prose level a markdown `#` maps to; deeper headings shift with it
@@ -83,28 +110,152 @@ export interface MarkdownViewProps extends Omit<
    * embeds (a context rail) so headings stay on the constrained rung.
    */
   baseHeadingLevel?: ProseHeadingLevel;
+  /**
+   * Per-element renderer overrides, MERGED over the internal Prose* map
+   * (#10) — a consumer entry wins for its key; every key the consumer does
+   * NOT set keeps rendering through `buildProseComponents()`. This is the
+   * seam for rendering inline citations: override `a` (or a custom node
+   * type) to swap a `[1](url)`-style marker for an `InlineCitation` chip
+   * while headings/lists/etc. keep the branded prose styling.
+   *
+   * Deliberately a MERGE, not a replace: sanitisation is unaffected either
+   * way (see `plugins` below), but a wholesale replace would silently drop
+   * the branded styling from every element the consumer didn't think to
+   * re-declare — a citation override should not have to also re-implement
+   * headings/lists/code to keep them on-brand.
+   *
+   * **Known constraint: a `components` change alone does not force a
+   * re-render of already-rendered markdown (#10).** Streamdown memoizes on
+   * `children`/`plugins`/theme/etc but NOT on `components`
+   * (`streamdown@2.5.0`'s top-level `memo` comparator omits it), so if the
+   * SAME markdown string is still current when an override's closed-over
+   * data changes — e.g. an inline-citation chip that resolves its title
+   * asynchronously — the new render function is captured but nothing
+   * schedules Streamdown to call it again. Don't rely on a `components`
+   * closure to reflect state that arrives after the initial render; instead
+   * have the overriding component read that state itself (a shared context,
+   * a store keyed by citation id, or an internal `useState`/subscription
+   * inside the override) so IT re-renders independently of `MarkdownView`'s
+   * own render pass — the pattern `InlineCitation`/`InlineCitationCard`
+   * already use.
+   */
+  components?: StreamdownComponents;
+  /**
+   * Streamdown plugin-slot overrides (`cjk`/`code`/`math`/`mermaid`/
+   * `renderers`), MERGED per key over the internal defaults (the reactive,
+   * brand-token-derived `code` plugin and i18n-aware `cjk`/`math`/`mermaid`
+   * set — see `_streamdown-i18n.ts`).
+   *
+   * **This narrow `plugins` prop can only APPEND — it can never displace
+   * Streamdown's default `rehypePlugins` chain** (`rehype-raw` →
+   * `rehype-sanitize` → `rehype-harden`). `MarkdownView` never sets
+   * `rehypePlugins` itself, and nothing in `PluginConfig` removes or replaces
+   * a member of that pipeline, so the sanitiser cannot be turned off through
+   * this prop. But two of the five slots are **not** upstream of it and must
+   * be treated as trusted code:
+   * - **`math.rehypePlugin` runs AFTER `rehype-sanitize`/`rehype-harden`**
+   *   (appended to the end of the rehype pipeline, verified against
+   *   `streamdown@2.5.0`'s `dist/chunk-BO2N2NFS.js`) — its output is never
+   *   re-sanitised.
+   * - **`mermaid` never enters the rehype/remark pipeline at all.** Its
+   *   `getMermaid().render()` result is written via
+   *   `dangerouslySetInnerHTML` (streamdown's only such sink). brand-ui's own
+   *   `useStreamdownPlugins()` default pins `securityLevel: "strict"`
+   *   (`_lazy-mermaid.ts`); a replacement `mermaid` plugin must sanitise its
+   *   own SVG output the same way.
+   * - `cjk` (remark-stage only — its output is re-sanitised downstream by
+   *   the rehype pipeline like any other remark result), `code` (feeds only
+   *   `shikiTheme`, no HTML injection) and `renderers` (ordinary React
+   *   components rendered with the fenced block's raw `code` string as a
+   *   `string` prop, the same trusted-component boundary as a `components`
+   *   override) do not bypass sanitisation.
+   *
+   * **`rehypePlugins` is NOT exposed on this component (#36, fixed).** Unlike
+   * `plugins`, a caller-supplied `rehypePlugins` array would REPLACE
+   * Streamdown's default rehype pipeline wholesale rather than extending it,
+   * silently dropping `rehype-raw`/`rehype-sanitize`/`rehype-harden` and
+   * letting a plain markdown string execute script in the host page — so
+   * `MarkdownViewProps` `Omit`s it at the type level AND
+   * `stripSanitizerOverrides()` deletes it at runtime before the `{...props}`
+   * spread below, even if a JS consumer or a cast reaches this component with
+   * it set. If you need to widen sanitisation, use
+   * `allowedTags`/`literalTagContent`, which MERGE into the sanitize schema
+   * instead of replacing the pipeline. See
+   * `packages/ai/src/_streamdown-safety.ts`.
+   *
+   * **`remarkPlugins` IS supported** (PR #74 review, round 1 — the original
+   * #36 fix over-reached and removed it too). The remark stage runs strictly
+   * upstream of the rehype chain, and Streamdown builds its rehype list
+   * without reading `remarkPlugins`, so everything a remark plugin emits is
+   * still sanitised downstream — measured across raw-`html` mdast nodes,
+   * `data.hName`/`hChildren` hast elements, `hProperties` event handlers,
+   * `javascript:` link URLs and smuggled `raw` hast children. Note the
+   * ordinary (non-security) footgun: your array REPLACES Streamdown's own
+   * remark defaults (`remark-gfm`, `codeMeta`), so spread
+   * `Object.values(defaultRemarkPlugins)` from `streamdown` back in if you
+   * want to keep GFM tables/strikethrough.
+   */
+  plugins?: StreamdownPlugins;
 }
 
 export const MarkdownView = ({
   baseHeadingLevel = 1,
   className,
   children,
+  components: componentOverrides,
+  plugins: pluginOverrides,
   ...props
 }: MarkdownViewProps) => {
-  const components = useMemo(() => buildProseComponents(baseHeadingLevel), [baseHeadingLevel]);
+  // Streamdown installs [rehypeRaw, rehypeSanitize, harden] as the DEFAULT VALUE of
+  // `rehypePlugins`; a supplied array REPLACES it. This component renders untrusted
+  // model output, so the chain is not overridable. Widen with `allowedTags` /
+  // `literalTagContent`, which merge into the sanitize schema. See issue #36.
+  // `remarkPlugins` is deliberately left alone — it runs upstream of the rehype
+  // chain and cannot bypass it (PR #74 review; see `_streamdown-safety.ts`).
+  stripSanitizerOverrides(props);
+  const internalComponents = useMemo(
+    () => buildProseComponents(baseHeadingLevel),
+    [baseHeadingLevel],
+  );
+  // Consumer entries win per key; every other key falls through to the
+  // internal Prose* map — see the `components` prop doc above.
+  const components = useMemo(
+    () => ({ ...internalComponents, ...componentOverrides }),
+    [internalComponents, componentOverrides],
+  );
   // Streamdown's own chrome (code copy, table menus) reads the locale seam (#310).
   // Spread AFTER so an explicit `translations` prop still wins (ADR 0017).
   const translations = useStreamdownTranslations();
   // Brand-token-derived `code` plugin, not the package's static github-*
   // default (#315 follow-up) — re-derives when the active theme changes.
-  const plugins = useStreamdownPlugins();
+  // `math`/`cjk` are lazy-loaded off the raw markdown source (#perf-5, see
+  // `_streamdown-i18n.ts`) — pass `children` so they load only when this
+  // view actually needs them.
+  const internalPlugins = useStreamdownPlugins(typeof children === "string" ? children : "");
+  // Same per-key merge as `components` — see the `plugins` prop doc above.
+  // `math.rehypePlugin`/`mermaid` are the two slots that land in the DOM after
+  // (or outside) the sanitiser chain, so replacing one is a TRUSTED-CODE
+  // decision. The runtime half of that documented boundary is a dev warning —
+  // the plugin still runs; stripping it would break the legitimate use (#76).
+  const plugins = useMemo(() => {
+    warnOnTrustedPluginSlots(pluginOverrides, internalPlugins);
+    return { ...internalPlugins, ...pluginOverrides };
+  }, [internalPlugins, pluginOverrides]);
+  // The TOP-LEVEL Streamdown `mermaid` prop (distinct from `plugins.mermaid`
+  // above) — catches a failed diagram render, including a missing `mermaid`
+  // optional peer (issue #33). See `_streamdown-i18n.ts`.
+  const mermaidOptions = useStreamdownMermaidOptions();
   return (
     <Streamdown
+      // Forces a remount the first time the lazy math/cjk slot resolves —
+      // see `getStreamdownPluginsKey`'s doc in `_streamdown-i18n.ts` for why.
+      key={getStreamdownPluginsKey(internalPlugins)}
       data-slot="markdown-view"
       className={cn("space-y-3 [&>*:first-child]:mt-0 [&>*:last-child]:mb-0", className)}
       components={components}
       plugins={plugins}
       translations={translations}
+      mermaid={mermaidOptions}
       {...props}
     >
       {children}