@elabs-ai/components-ai 4.0.0 → 4.1.0

package/src/message.test.tsx

@@ -1,4 +1,6 @@
+import { math } from "@streamdown/math";
 import { useState } from "react";
+import type { ComponentProps } from "react";
 import { describe, expect, it, vi } from "vitest";
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
@@ -183,6 +185,107 @@ describe("MessageResponse loading (#269, loading-states.md)", () => {
   });
 });
 
+describe("MessageResponse plugins/components overrides (#10 — merge-not-replace semantics)", () => {
+  it("merges a real `plugins.cjk` override in (append), keeps sanitisation on, and keeps the untouched `plugins.math` default alive (#10)", () => {
+    // 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 MessageResponse actually reaches — `code`/`mermaid`/`renderers` are
+    // consulted only inside Streamdown's OWN default `code` renderer, which
+    // `MessageResponse` 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 MessageResponse>["plugins"]>["cjk"]
+    > = {
+      name: "cjk",
+      remarkPlugins: [],
+      remarkPluginsAfter: [cjkRemarkSpy],
+      remarkPluginsBefore: [],
+      type: "cjk",
+    };
+    const UNSAFE_DOC = `# Note
+
+<script>window.__pwned = true;</script>
+
+$$x^2$$
+`;
+    render(<MessageResponse plugins={{ cjk: customCjkPlugin }}>{UNSAFE_DOC}</MessageResponse>);
+
+    // (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.
+    expect(document.querySelector(".katex")).toBeInTheDocument();
+  });
+});
+
+describe("MessageResponse 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
+      <MessageResponse {...({ rehypePlugins: [injectScript] } as any)}>{"# hi"}</MessageResponse>,
+    );
+    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(
+      <MessageResponse remarkPlugins={[injectHostile]}>{"# hi"}</MessageResponse>,
+    );
+
+    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("Message data-slot / data-role contract", () => {
   it("marks the root and its parts with kebab-case data-slots", () => {
     const { container } = render(
@@ -506,3 +609,76 @@ describe("MessageActions hover-reveal pill", () => {
     expect(screen.getByRole("button", { name: "Unpin" })).toHaveAttribute("aria-pressed", "true");
   });
 });
+
+describe("MessageResponse 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(<MessageResponse plugins={{ math: evilMath }}>{"# hi"}</MessageResponse>);
+      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 {
+      const { unmount } = render(<MessageResponse>{"# hi"}</MessageResponse>);
+      unmount();
+      // 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 MessageResponse>["plugins"]>["cjk"]
+      > = {
+        name: "cjk",
+        remarkPlugins: [],
+        remarkPluginsAfter: [],
+        remarkPluginsBefore: [],
+        type: "cjk",
+      };
+      render(<MessageResponse plugins={{ cjk: customCjkPlugin }}>{"# hi"}</MessageResponse>);
+      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(
+        <MessageResponse plugins={{ math: evilMath }}>{"# hi"}</MessageResponse>,
+      );
+      expect(container.querySelector("script")).not.toBeNull();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});

package/src/message.tsx

@@ -6,7 +6,12 @@ import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@elabs
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { useLocale } from "@elabs-ai/components-ui";
 import { cva, type VariantProps } from "class-variance-authority";
-import { useStreamdownPlugins, useStreamdownTranslations } from "./_streamdown-i18n";
+import { stripSanitizerOverrides, warnOnTrustedPluginSlots } from "./_streamdown-safety";
+import {
+  useStreamdownMermaidOptions,
+  useStreamdownPlugins,
+  useStreamdownTranslations,
+} from "./_streamdown-i18n";
 import type { UIMessage } from "ai";
 import { BotIcon, ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
 import type { ComponentProps, HTMLAttributes, ReactElement } from "react";
@@ -540,7 +545,19 @@ export const MessageBranchPage = ({ className, ...props }: MessageBranchPageProp
   );
 };
 
-export type MessageResponseProps = ComponentProps<typeof Streamdown> & {
+/**
+ * `rehypePlugins` is NOT exposed on `MessageResponse` (#36, fixed). This
+ * renders untrusted, streamed model output — the type-level `Omit` below plus
+ * a runtime `stripSanitizerOverrides()` call before the `{...props}` spread
+ * onto `<Streamdown>` keep Streamdown's default sanitiser chain (rehype-raw →
+ * rehype-sanitize → rehype-harden) non-overridable, even through a JS consumer
+ * or a force-cast.
+ *
+ * `remarkPlugins` IS supported: the remark stage runs upstream of that chain
+ * and cannot bypass it (PR #74 review, round 1). See `MarkdownView`'s TSDoc and
+ * `packages/ai/src/_streamdown-safety.ts` for the full security model.
+ */
+export type MessageResponseProps = Omit<ComponentProps<typeof Streamdown>, "rehypePlugins"> & {
   /**
    * No content has arrived yet (loading-states.md `loading`) — renders
    * skeleton lines at the body line-height instead of `<Streamdown>`, so the
@@ -548,10 +565,58 @@ export type MessageResponseProps = ComponentProps<typeof Streamdown> & {
    * @default false
    */
   loading?: boolean;
+  /**
+   * Custom renderers for markdown elements. **Semantics differ from
+   * `MarkdownView`:** `components` here REPLACES (not merges) per key against
+   * Streamdown's own defaults, since `MessageResponse` has no internal
+   * component map to merge with. See `MarkdownView` for merge-over-defaults
+   * semantics and `#10` for details.
+   */
+  components?: ComponentProps<typeof Streamdown>["components"];
+  /**
+   * Streamdown plugin-slot overrides (`cjk`/`code`/`math`/`mermaid`/
+   * `renderers`), **merged** per key over the internal defaults, so a
+   * consumer's entry wins for its key; every key the consumer does not set
+   * keeps the reactive, i18n-aware internal default. Same semantics as
+   * `MarkdownView` (#10 fix round).
+   *
+   * **This narrow `plugins` prop can only APPEND — it can never displace
+   * Streamdown's default `rehypePlugins` chain** (`rehype-raw` →
+   * `rehype-sanitize` → `rehype-harden`). `MessageResponse` never sets
+   * `rehypePlugins` itself, and nothing in `PluginConfig` removes a member of
+   * that pipeline. But two of the five slots are **not** upstream of it and
+   * must be treated as TRUSTED CODE (#76):
+   * - **`math.rehypePlugin` runs AFTER `rehype-sanitize`/`rehype-harden`** —
+   *   it is appended to the end of the rehype pipeline (verified against
+   *   `streamdown@2.5.0`'s `dist/chunk-BO2N2NFS.js`), so its output is never
+   *   re-sanitised. Replacing it emits a dev-only `console.warn`; the plugin
+   *   still runs (the seam is deliberate, not a hole to close). The sharp
+   *   edge in practice is KaTeX's `trust` option — it disables KaTeX's own
+   *   sanitisation, so leave it off for model-authored content.
+   * - **`mermaid` never enters the rehype/remark pipeline at all.** Its
+   *   render output is written via `dangerouslySetInnerHTML` (streamdown's
+   *   only such sink); brand-ui's default pins mermaid's strict security
+   *   level, and a replacement must sanitise its own SVG. Also dev-warned.
+   * - `cjk` (remark-stage, re-sanitised downstream), `code` (feeds
+   *   `shikiTheme` only) and `renderers` (ordinary React components) do not
+   *   bypass sanitisation and are never warned about.
+   *
+   * See `docs/CSP-AND-NETWORK.md` §1 and
+   * `packages/ai/src/_streamdown-safety.ts`; `MarkdownView`'s TSDoc carries
+   * the same model for the sibling surface.
+   */
+  plugins?: ComponentProps<typeof Streamdown>["plugins"];
 };
 
 export const MessageResponse = memo(
-  ({ className, loading = false, ...props }: MessageResponseProps) => {
+  ({ className, loading = false, plugins: pluginOverrides, ...props }: MessageResponseProps) => {
+    // Streamdown installs [rehypeRaw, rehypeSanitize, harden] as the DEFAULT VALUE of
+    // `rehypePlugins`; a supplied array REPLACES it. This component renders untrusted,
+    // streamed 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);
     // Streamdown renders its own chrome (code copy, table menus, Mermaid
     // toolbar); route its labels through the locale seam (#310). Spread AFTER
     // so an explicit `translations` prop still wins (ADR 0017 override chain).
@@ -559,7 +624,27 @@ export const MessageResponse = memo(
     const { t } = useLocale();
     // 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();
+    const internalPlugins = useStreamdownPlugins();
+    // MERGED per key over the internal defaults — the same semantics as
+    // `MarkdownView`'s `plugins` prop (#10 fix round, M4): a consumer entry
+    // wins for its key; every key the consumer does not set keeps the
+    // reactive, i18n-aware internal default. Previously this component
+    // REPLACED `plugins` wholesale (`{...props}` spread after `plugins=`),
+    // the opposite of `MarkdownView` for the same prop on a sibling
+    // Streamdown surface — aligned so both components mean the same thing by
+    // "override a plugin slot".
+    // `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 — catches a failed diagram
+    // render, including a missing `mermaid` optional peer (issue #33).
+    const mermaidOptions = useStreamdownMermaidOptions();
 
     if (loading) {
       return (
@@ -594,6 +679,7 @@ export const MessageResponse = memo(
         data-slot="message-response"
         plugins={plugins}
         translations={translations}
+        mermaid={mermaidOptions}
         {...props}
       />
     );

package/src/microcopy.test.tsx

@@ -2,9 +2,11 @@ import { describe, expect, it } from "vitest";
 import { render, screen } from "@testing-library/react";
 import { LocaleProvider } from "@elabs-ai/components-ui";
 
+import { Artifact, ArtifactClose } from "./artifact";
 import { Composer } from "./composer";
 import { InlineCitationCard, InlineCitationCarouselNext } from "./inline-citation";
 import { Message, MessageBranch, MessageBranchNext } from "./message";
+import { Plan, PlanTrigger } from "./plan";
 import { PromptInput, PromptInputBody, PromptInputTextarea } from "./prompt-input";
 
 /**
@@ -19,7 +21,9 @@ const de = {
   "ai.message.nextBranch": "Nächster Zweig",
   "ai.promptInput.placeholder": "Was möchtest du wissen?",
   "ai.promptInput.uploadFiles": "Dateien hochladen",
+  "ai.plan.togglePlan": "Plan umschalten",
   next: "Weiter",
+  close: "Schließen",
 };
 
 describe("microcopy — English defaults are unchanged", () => {
@@ -48,6 +52,20 @@ describe("microcopy — English defaults are unchanged", () => {
     );
     expect(screen.getByRole("button", { name: "Next branch" })).toBeInTheDocument();
   });
+
+  it("ArtifactClose keeps its sr-only 'Close' name (#18 — reuses the generic `close` key)", () => {
+    render(<ArtifactClose />);
+    expect(screen.getByRole("button", { name: "Close" })).toBeInTheDocument();
+  });
+
+  it("PlanTrigger keeps its sr-only 'Toggle plan' name (#18)", () => {
+    render(
+      <Plan>
+        <PlanTrigger />
+      </Plan>,
+    );
+    expect(screen.getByRole("button", { name: "Toggle plan" })).toBeInTheDocument();
+  });
 });
 
 describe("microcopy — a LocaleProvider overrides it", () => {
@@ -106,6 +124,28 @@ describe("microcopy — a LocaleProvider overrides it", () => {
     );
     expect(screen.getByPlaceholderText("Explicit wins")).toBeInTheDocument();
   });
+
+  it("translates ArtifactClose's sr-only name via the reused generic `close` key (#18)", () => {
+    render(
+      <LocaleProvider locale="de-DE" messages={de}>
+        <Artifact>
+          <ArtifactClose />
+        </Artifact>
+      </LocaleProvider>,
+    );
+    expect(screen.getByRole("button", { name: "Schließen" })).toBeInTheDocument();
+  });
+
+  it("translates PlanTrigger's sr-only name via the new `ai.plan.togglePlan` key (#18)", () => {
+    render(
+      <LocaleProvider locale="de-DE" messages={de}>
+        <Plan>
+          <PlanTrigger />
+        </Plan>
+      </LocaleProvider>,
+    );
+    expect(screen.getByRole("button", { name: "Plan umschalten" })).toBeInTheDocument();
+  });
 });
 
 describe("microcopy — no provider is required", () => {

package/src/{model-selector.stories.tsx → model-provider-logo.stories.tsx}

@@ -1,30 +1,39 @@
 /**
- * ModelSelector — a command-palette model picker.
+ * ModelProviderLogo — the mark of an AI model provider, sized for a list row.
  *
- * `ModelSelectorLogo` fetches provider marks from a **remote origin**
+ * It fetches provider marks from a **remote origin**
  * (`models.dev`) by default, so a restrictive `img-src` blocks them. Pass `src`
  * to self-host, or `fallback` to control what a blocked load renders — it is
  * never a broken-image glyph. See `docs/CSP-AND-NETWORK.md`.
  */
 import type { Meta, StoryObj } from "@storybook/react-vite";
 
-import { ModelSelectorLogo } from "./model-selector";
+import { ModelProviderLogo } from "./model-provider-logo";
 
 const meta = {
-  title: "AI/ModelSelectorLogo",
-  component: ModelSelectorLogo,
+  title: "AI/ModelProviderLogo",
+  component: ModelProviderLogo,
   parameters: {
     layout: "centered",
     docs: {
       description: {
         component:
-          "Provider logo for the model selector. Defaults to fetching from models.dev; pass `src` for a self-hosted asset and `fallback` for the blocked/offline case. A failed load renders a neutral glyph, never a broken image.",
+          "The mark of an AI model provider, sized for a row in a model list. Defaults to " +
+          "fetching from models.dev; pass `src` for a self-hosted asset and `fallback` for the " +
+          "blocked/offline case. A failed load renders a neutral glyph, never a broken image.\n\n" +
+          "**`ModelProviderLogo` vs `ServiceLogo` (`@elabs-ai/components-icons`).** An AI " +
+          "provider mark with a zero-config remote default → this component. Any other " +
+          "third-party service mark, resolved from a registry the app supplies and never " +
+          "fetched → `ServiceLogo`.\n\n" +
+          "For the list this logo sits in: an inline pill in a composer footer → `ModelPicker` " +
+          "(`@elabs-ai/components-ui`); a full ⌘K palette → compose `CommandDialog` + " +
+          "`Command*` from `@elabs-ai/components-ui` directly.",
       },
     },
   },
   args: { provider: "anthropic" },
   tags: ["autodocs"],
-} satisfies Meta<typeof ModelSelectorLogo>;
+} satisfies Meta<typeof ModelProviderLogo>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
@@ -64,7 +73,7 @@ export const LiveRemoteLogos: Story = {
     <div className="flex items-center gap-4">
       {(["anthropic", "openai", "google", "mistral"] as const).map((provider) => (
         <figure className="flex flex-col items-center gap-2" key={provider}>
-          <ModelSelectorLogo provider={provider} />
+          <ModelProviderLogo provider={provider} />
           <figcaption className="text-meta text-muted-foreground">{provider}</figcaption>
         </figure>
       ))}

package/src/{model-selector.test.tsx → model-provider-logo.test.tsx}

@@ -1,21 +1,21 @@
 import { describe, expect, it, vi } from "vitest";
 import { fireEvent, render, screen } from "@testing-library/react";
 
-import { MODEL_SELECTOR_LOGO_BASE_URL, ModelSelectorLogo } from "./model-selector";
+import { MODEL_PROVIDER_LOGO_BASE_URL, ModelProviderLogo } from "./model-provider-logo";
 
-describe("ModelSelectorLogo — remote origin escape hatches", () => {
+describe("ModelProviderLogo — remote origin escape hatches", () => {
   it("defaults to the models.dev logo for the provider", () => {
-    render(<ModelSelectorLogo provider="anthropic" />);
+    render(<ModelProviderLogo provider="anthropic" />);
     expect(screen.getByRole("img", { name: "anthropic logo" })).toHaveAttribute(
       "src",
-      `${MODEL_SELECTOR_LOGO_BASE_URL}/anthropic.svg`,
+      `${MODEL_PROVIDER_LOGO_BASE_URL}/anthropic.svg`,
     );
   });
 
   it("lets a caller override src for a self-hosted asset", () => {
     // The old props type did `Omit<…, "src">` AND spread props before `src=`, so
     // a self-hosting consumer had no way to win. Both are fixed.
-    render(<ModelSelectorLogo provider="anthropic" src="/local/anthropic.svg" />);
+    render(<ModelProviderLogo provider="anthropic" src="/local/anthropic.svg" />);
     expect(screen.getByRole("img", { name: "anthropic logo" })).toHaveAttribute(
       "src",
       "/local/anthropic.svg",
@@ -23,7 +23,7 @@ describe("ModelSelectorLogo — remote origin escape hatches", () => {
   });
 
   it("renders a neutral glyph instead of a broken image when the load fails", () => {
-    render(<ModelSelectorLogo provider="anthropic" />);
+    render(<ModelProviderLogo provider="anthropic" />);
     fireEvent.error(screen.getByRole("img", { name: "anthropic logo" }));
 
     const fallback = screen.getByRole("img", { name: "anthropic logo" });
@@ -32,24 +32,24 @@ describe("ModelSelectorLogo — remote origin escape hatches", () => {
   });
 
   it("renders a caller-supplied fallback when provided", () => {
-    render(<ModelSelectorLogo provider="anthropic" fallback={<span data-testid="fb">AI</span>} />);
+    render(<ModelProviderLogo provider="anthropic" fallback={<span data-testid="fb">AI</span>} />);
     fireEvent.error(screen.getByRole("img", { name: "anthropic logo" }));
     expect(screen.getByTestId("fb")).toBeInTheDocument();
   });
 
   it("still calls a caller's onError", () => {
     const onError = vi.fn();
-    render(<ModelSelectorLogo provider="anthropic" onError={onError} />);
+    render(<ModelProviderLogo provider="anthropic" onError={onError} />);
     fireEvent.error(screen.getByRole("img", { name: "anthropic logo" }));
     expect(onError).toHaveBeenCalledTimes(1);
   });
 
   it("keeps an accessible name in both states", () => {
-    const { rerender } = render(<ModelSelectorLogo provider="openai" />);
+    const { rerender } = render(<ModelProviderLogo provider="openai" />);
     expect(screen.getByRole("img", { name: "openai logo" })).toBeInTheDocument();
 
     fireEvent.error(screen.getByRole("img", { name: "openai logo" }));
-    rerender(<ModelSelectorLogo provider="openai" />);
+    rerender(<ModelProviderLogo provider="openai" />);
     expect(screen.getByRole("img", { name: "openai logo" })).toBeInTheDocument();
   });
 });

package/src/model-provider-logo.tsx

@@ -0,0 +1,149 @@
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { BotIcon } from "lucide-react";
+import type { ComponentProps, ReactNode } from "react";
+import { useState } from "react";
+
+/**
+ * Where provider logos are fetched from by default.
+ *
+ * This is a REMOTE origin: a deployment with a restrictive `img-src` blocks it.
+ * Self-host the SVGs and pass `src` (or set a `fallback`) — see
+ * `docs/CSP-AND-NETWORK.md`.
+ */
+export const MODEL_PROVIDER_LOGO_BASE_URL = "https://models.dev/logos";
+
+export type ModelProviderLogoProps = Omit<ComponentProps<"img">, "alt"> & {
+  /**
+   * Override the logo URL — point at a self-hosted or bundled asset when a CSP
+   * blocks `models.dev`. Defaults to `${MODEL_PROVIDER_LOGO_BASE_URL}/<provider>.svg`.
+   */
+  src?: string;
+  /**
+   * Rendered when the logo fails to load (blocked, offline, or unknown
+   * provider). Defaults to a neutral Lucide glyph, so the row never collapses
+   * to a broken image.
+   */
+  fallback?: ReactNode;
+  provider:
+    | "moonshotai-cn"
+    | "lucidquery"
+    | "moonshotai"
+    | "zai-coding-plan"
+    | "alibaba"
+    | "xai"
+    | "vultr"
+    | "nvidia"
+    | "upstage"
+    | "groq"
+    | "github-copilot"
+    | "mistral"
+    | "vercel"
+    | "nebius"
+    | "deepseek"
+    | "alibaba-cn"
+    | "google-vertex-anthropic"
+    | "venice"
+    | "chutes"
+    | "cortecs"
+    | "github-models"
+    | "togetherai"
+    | "azure"
+    | "baseten"
+    | "huggingface"
+    | "opencode"
+    | "fastrouter"
+    | "google"
+    | "google-vertex"
+    | "cloudflare-workers-ai"
+    | "inception"
+    | "wandb"
+    | "openai"
+    | "zhipuai-coding-plan"
+    | "perplexity"
+    | "openrouter"
+    | "zenmux"
+    | "v0"
+    | "iflowcn"
+    | "synthetic"
+    | "deepinfra"
+    | "zhipuai"
+    | "submodel"
+    | "zai"
+    | "inference"
+    | "requesty"
+    | "morph"
+    | "lmstudio"
+    | "anthropic"
+    | "aihubmix"
+    | "fireworks-ai"
+    | "modelscope"
+    | "llama"
+    | "scaleway"
+    | "amazon-bedrock"
+    | "cerebras"
+    // oxlint-disable-next-line typescript-eslint(ban-types) -- intentional pattern for autocomplete-friendly string union
+    | (string & {});
+};
+
+/**
+ * The mark of an AI model provider (`anthropic`, `openai`, `google`, …), sized
+ * for a row in a model list.
+ *
+ * **`ModelProviderLogo` vs `ServiceLogo` (`@elabs-ai/components-icons`).** An AI
+ * provider mark with a zero-config remote default — name the provider and a logo
+ * appears, no registration step — is this component. Any other third-party
+ * service mark, resolved from a registry the app supplies and never fetched, is
+ * `ServiceLogo`. The two are not interchangeable: `ServiceLogo` has no
+ * per-instance `src` and no `onError`, and this one reaches a remote origin by
+ * default (see `docs/CSP-AND-NETWORK.md`).
+ */
+export const ModelProviderLogo = ({
+  provider,
+  className,
+  src,
+  fallback,
+  onError,
+  ...props
+}: ModelProviderLogoProps) => {
+  const [failed, setFailed] = useState(false);
+
+  // A blocked/missing logo must not leave a broken-image glyph in the row.
+  if (failed) {
+    return (
+      <>
+        {fallback ?? (
+          <BotIcon aria-label={`${provider} logo`} className={cn("size-3", className)} role="img" />
+        )}
+      </>
+    );
+  }
+
+  return (
+    <img
+      {...props}
+      alt={`${provider} logo`}
+      className={cn("size-3 dark:invert", className)}
+      height={12}
+      onError={(event) => {
+        setFailed(true);
+        onError?.(event);
+      }}
+      // AFTER the spread, so the caller's `src` wins via the destructured
+      // default rather than being silently overwritten.
+      src={src ?? `${MODEL_PROVIDER_LOGO_BASE_URL}/${provider}.svg`}
+      width={12}
+    />
+  );
+};
+
+export type ModelProviderLogoGroupProps = ComponentProps<"div">;
+
+export const ModelProviderLogoGroup = ({ className, ...props }: ModelProviderLogoGroupProps) => (
+  <div
+    className={cn(
+      "flex shrink-0 items-center -space-x-1 [&>img]:rounded-full [&>img]:bg-background [&>img]:p-px [&>img]:ring-1 dark:[&>img]:bg-foreground",
+      className,
+    )}
+    {...props}
+  />
+);