@elabs-ai/components-ui 4.0.0

package/src/lib/file-source.test.ts

@@ -0,0 +1,217 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { type FileSource, normalizeFileSource } from "./file-source";
+
+const decode = (buffer: ArrayBuffer) => new TextDecoder().decode(buffer);
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe("normalizeFileSource — identity", () => {
+  it("reads name and MIME off a File", () => {
+    const source: FileSource = {
+      kind: "file",
+      file: new File(["x"], "Report.PDF", { type: "application/pdf" }),
+    };
+    expect(normalizeFileSource(source)).toMatchObject({
+      name: "Report.PDF",
+      mediaType: "application/pdf",
+      category: "document",
+      extension: "pdf",
+      size: 1,
+    });
+  });
+
+  it("infers a File's MIME from its name when the platform reports none", () => {
+    const file = new File(["a,b"], "rows.csv", { type: "" });
+    expect(normalizeFileSource({ kind: "file", file })).toMatchObject({
+      mediaType: "text/csv",
+      category: "data",
+    });
+  });
+
+  it("prefers an explicit mediaType over the Blob's own", () => {
+    const blob = new Blob(["x"], { type: "application/octet-stream" });
+    const resolved = normalizeFileSource({
+      kind: "blob",
+      blob,
+      name: "page.html",
+      mediaType: "text/html",
+    });
+    expect(resolved).toMatchObject({ mediaType: "text/html", category: "code" });
+  });
+
+  it("derives a name from the URL path when the caller gives none", () => {
+    expect(
+      normalizeFileSource({ kind: "url", url: "https://x.test/a/b/notes%20v2.md" }),
+    ).toMatchObject({
+      name: "notes v2.md",
+      category: "text",
+    });
+  });
+
+  it("ignores a URL query and hash when deriving the name", () => {
+    expect(
+      normalizeFileSource({ kind: "url", url: "https://x.test/chart.svg?v=2#top" }),
+    ).toMatchObject({
+      name: "chart.svg",
+      category: "image",
+    });
+  });
+
+  it("never produces an empty name", () => {
+    expect(normalizeFileSource({ kind: "url", url: "https://x.test/" }).name).toBe("file");
+  });
+
+  it("carries alt through", () => {
+    const file = new File([""], "a.png", { type: "image/png" });
+    expect(normalizeFileSource({ kind: "file", file, alt: "A bar chart" }).alt).toBe("A bar chart");
+  });
+
+  it("reports size only where the platform already knows it", () => {
+    const buffer = new TextEncoder().encode("hello").buffer as ArrayBuffer;
+    expect(
+      normalizeFileSource({
+        kind: "buffer",
+        buffer,
+        name: "a.bin",
+        mediaType: "application/octet-stream",
+      }).size,
+    ).toBe(5);
+    // A text source would need an encode pass and a url source a fetch — neither is free.
+    expect(
+      normalizeFileSource({ kind: "text", text: "hello", name: "a.txt" }).size,
+    ).toBeUndefined();
+    expect(normalizeFileSource({ kind: "url", url: "https://x.test/a.txt" }).size).toBeUndefined();
+  });
+
+  it("does not read anything until asked", async () => {
+    const fetchSpy = vi.fn();
+    vi.stubGlobal("fetch", fetchSpy);
+    normalizeFileSource({ kind: "url", url: "https://x.test/a.txt" });
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("normalizeFileSource — reading", () => {
+  it("reads every variant as bytes and as text", async () => {
+    const sources: FileSource[] = [
+      { kind: "file", file: new File(["hello"], "a.txt", { type: "text/plain" }) },
+      { kind: "blob", blob: new Blob(["hello"]), name: "a.txt" },
+      {
+        kind: "buffer",
+        buffer: new TextEncoder().encode("hello").buffer as ArrayBuffer,
+        name: "a.txt",
+        mediaType: "text/plain",
+      },
+      { kind: "text", text: "hello", name: "a.txt" },
+    ];
+    for (const source of sources) {
+      const resolved = normalizeFileSource(source);
+      expect(decode(await resolved.bytes()), source.kind).toBe("hello");
+      expect(await resolved.text(), source.kind).toBe("hello");
+    }
+  });
+
+  it("passes init through to fetch, so an authenticated file is reachable", async () => {
+    const fetchSpy = vi.fn().mockResolvedValue(new Response("secret", { status: 200 }));
+    vi.stubGlobal("fetch", fetchSpy);
+
+    const init: RequestInit = { headers: { Authorization: "Bearer t" }, credentials: "include" };
+    const resolved = normalizeFileSource({ kind: "url", url: "https://x.test/a.txt", init });
+    expect(await resolved.text()).toBe("secret");
+
+    expect(fetchSpy).toHaveBeenCalledWith(
+      "https://x.test/a.txt",
+      expect.objectContaining({ headers: { Authorization: "Bearer t" }, credentials: "include" }),
+    );
+  });
+
+  it("names the file in a failed fetch, so the error is actionable", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("", { status: 404 })));
+    const resolved = normalizeFileSource({ kind: "url", url: "https://x.test/missing.pdf" });
+    await expect(resolved.bytes()).rejects.toThrow(/missing\.pdf.*404/);
+  });
+
+  it("fetches once across repeated reads", async () => {
+    const fetchSpy = vi.fn().mockImplementation(() => Promise.resolve(new Response("hello")));
+    vi.stubGlobal("fetch", fetchSpy);
+
+    const resolved = normalizeFileSource({ kind: "url", url: "https://x.test/a.txt" });
+    await Promise.all([resolved.bytes(), resolved.bytes(), resolved.text()]);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not cache a failure, so a retry re-runs the read", async () => {
+    const fetchSpy = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("offline"))
+      .mockResolvedValueOnce(new Response("hello"));
+    vi.stubGlobal("fetch", fetchSpy);
+
+    const resolved = normalizeFileSource({ kind: "url", url: "https://x.test/a.txt" });
+    await expect(resolved.bytes()).rejects.toThrow("offline");
+    expect(decode(await resolved.bytes())).toBe("hello");
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it("rejects an already-aborted read without touching the network", async () => {
+    const fetchSpy = vi.fn();
+    vi.stubGlobal("fetch", fetchSpy);
+    const resolved = normalizeFileSource({ kind: "url", url: "https://x.test/a.txt" });
+    await expect(resolved.bytes(AbortSignal.abort())).rejects.toBeDefined();
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("normalizeFileSource — url()", () => {
+  it("returns a public remote URL unchanged, so the element streams it", async () => {
+    const fetchSpy = vi.fn();
+    vi.stubGlobal("fetch", fetchSpy);
+    const resolved = normalizeFileSource({ kind: "url", url: "https://x.test/a.png" });
+    expect(await resolved.url()).toBe("https://x.test/a.png");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("mints an object URL for a url source carrying init — the element cannot replay auth headers", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("bytes")));
+    const createObjectURL = vi.fn().mockReturnValue("blob:mock");
+    vi.stubGlobal("URL", Object.assign(URL, { createObjectURL, revokeObjectURL: vi.fn() }));
+
+    const resolved = normalizeFileSource({
+      kind: "url",
+      url: "https://x.test/a.png",
+      init: { headers: { Authorization: "Bearer t" } },
+    });
+    expect(await resolved.url()).toBe("blob:mock");
+    expect(createObjectURL).toHaveBeenCalledTimes(1);
+  });
+
+  it("mints one object URL per reader and revokes it exactly once", async () => {
+    const createObjectURL = vi.fn().mockReturnValue("blob:mock");
+    const revokeObjectURL = vi.fn();
+    vi.stubGlobal("URL", Object.assign(URL, { createObjectURL, revokeObjectURL }));
+
+    const file = new File(["x"], "a.png", { type: "image/png" });
+    const resolved = normalizeFileSource({ kind: "file", file });
+
+    expect(await resolved.url()).toBe("blob:mock");
+    expect(await resolved.url()).toBe("blob:mock");
+    expect(createObjectURL).toHaveBeenCalledTimes(1);
+
+    resolved.revoke();
+    resolved.revoke();
+    expect(revokeObjectURL).toHaveBeenCalledTimes(1);
+  });
+
+  it("revoke() is safe before any url() call", () => {
+    const revokeObjectURL = vi.fn();
+    vi.stubGlobal("URL", Object.assign(URL, { revokeObjectURL }));
+    expect(() =>
+      normalizeFileSource({ kind: "text", text: "x", name: "a.txt" }).revoke(),
+    ).not.toThrow();
+    expect(revokeObjectURL).not.toHaveBeenCalled();
+  });
+});

package/src/lib/file-source.ts

@@ -0,0 +1,269 @@
+/**
+ * One input model for "a file", whatever the app happens to be holding.
+ *
+ * The library previously had three: a `File` (upload), a `string` of content
+ * (chat assets), and a bare URL (attachments) — so every surface that wanted to
+ * render a file first had to guess which of the three it had. {@link FileSource}
+ * is the union all of them collapse into, and {@link normalizeFileSource} turns
+ * any member into one uniform reader.
+ *
+ * Two things this fixes beyond the merge:
+ *
+ * - **Authenticated remote files work.** The `url` variant carries
+ *   `init?: RequestInit`, so headers, credentials and an abort signal reach the
+ *   fetch. A viewer that can only take a naked URL cannot open anything behind
+ *   auth, which is most enterprise content.
+ * - **Alt text has a home.** Every binary variant takes `alt`, so an image or a
+ *   rendered page can be described without a parallel prop channel.
+ *
+ * Pure DOM/platform mechanics: no React, no other deps. SSR-safe to import;
+ * only {@link ResolvedFileSource.url} needs a browser, and it says so.
+ */
+
+import { type FileCategory, mediaTypeFromName, resolveFileKind } from "./file-kind";
+
+/** Any file the library can be handed. Discriminated on `kind`. */
+export type FileSource =
+  /** A user-picked file. Name and MIME come from the platform. */
+  | { kind: "file"; file: File; alt?: string }
+  /** In-memory bytes that already have a `Blob` wrapper (a generated export, a decoded attachment). */
+  | { kind: "blob"; blob: Blob; name: string; mediaType?: string; alt?: string }
+  /**
+   * A remote file. `init` is passed straight to `fetch` — this is how auth
+   * headers, `credentials` and an `AbortSignal` reach the request.
+   */
+  | {
+      kind: "url";
+      url: string;
+      name?: string;
+      mediaType?: string;
+      alt?: string;
+      init?: RequestInit;
+    }
+  /** Raw bytes with no wrapper (a worker result, a WASM output). */
+  | { kind: "buffer"; buffer: ArrayBuffer; name: string; mediaType: string; alt?: string }
+  /** Content the app already has as a string (an agent's markdown, a code snippet). */
+  | { kind: "text"; text: string; name: string; mediaType?: string };
+
+/**
+ * A {@link FileSource} with its identity resolved and its bytes reachable the
+ * same way regardless of where they came from.
+ *
+ * Reads are memoized on success, so `text()` after `bytes()` costs nothing and a
+ * remote file is fetched once. A failed read is NOT cached — a retry re-runs it.
+ */
+export interface ResolvedFileSource {
+  /** Display name, always non-empty. Derived from the URL path when the caller gave none. */
+  readonly name: string;
+  /** Best-known MIME, resolved from the declared type then the extension. */
+  readonly mediaType: string;
+  /** Coarse shape, for icons/labels/fallbacks. Not a renderer routing key. */
+  readonly category: FileCategory;
+  /** Lowercased extension without the dot, or `""`. */
+  readonly extension: string;
+  /** Author-supplied description, for images and rendered pages. */
+  readonly alt?: string;
+  /** Byte length when known up front. `undefined` for `text` and un-fetched `url` sources. */
+  readonly size?: number;
+
+  /** The full contents as bytes. */
+  bytes(signal?: AbortSignal): Promise<ArrayBuffer>;
+  /** The full contents decoded as UTF-8. */
+  text(signal?: AbortSignal): Promise<string>;
+  /**
+   * A URL usable as an `<img>`/`<video>`/`<iframe>` src.
+   *
+   * A public `url` source returns its own URL unchanged, so the browser streams
+   * it and no full read happens. Every other source (and any `url` source with
+   * an `init`, which the element could not replay) mints an object URL — release
+   * it with {@link revoke}. Browser only: rejects where `URL.createObjectURL`
+   * does not exist.
+   */
+  url(signal?: AbortSignal): Promise<string>;
+  /** Release any object URL this reader minted. Idempotent; safe to call unconditionally. */
+  revoke(): void;
+}
+
+/** Best-effort filename from a URL path. Never empty. */
+function nameFromUrl(url: string): string {
+  try {
+    // A relative URL still needs a base to parse; the base is never used.
+    const parsed = new URL(url, "http://localhost");
+    const last = parsed.pathname.split("/").filter(Boolean).pop();
+    return last ? decodeURIComponent(last) : "file";
+  } catch {
+    // Unparseable: strip the query/hash by hand rather than give up. Note this
+    // runs ONLY on a parse failure — running it as a fallback for an empty
+    // pathname would return the host ("x.test" for "https://x.test/").
+    const stripped = url.split(/[?#]/)[0] ?? "";
+    const last = stripped.split("/").filter(Boolean).pop();
+    return last && last.length > 0 ? last : "file";
+  }
+}
+
+/**
+ * `Blob`/`File` → bytes, feature-detecting `Blob.prototype.arrayBuffer`.
+ *
+ * jsdom does not implement it (nor `Blob.prototype.text`), and this module is
+ * reached from every downstream package's jsdom tests — so per the note in
+ * `packages/ui/vitest.setup.ts`, the detection lives HERE rather than in a stub
+ * that would only fix this package's own suite. `FileReader` is the fallback:
+ * jsdom implements it, and it is the pre-2020 browser path anyway.
+ */
+function blobToArrayBuffer(blob: Blob): Promise<ArrayBuffer> {
+  if (typeof blob.arrayBuffer === "function") return blob.arrayBuffer();
+
+  if (typeof FileReader !== "function") {
+    return Promise.reject(
+      new Error("Cannot read file bytes: no Blob.arrayBuffer and no FileReader."),
+    );
+  }
+  return new Promise<ArrayBuffer>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result as ArrayBuffer);
+    reader.onerror = () => reject(reader.error ?? new Error("Could not read the file."));
+    reader.readAsArrayBuffer(blob);
+  });
+}
+
+/** The declared name/MIME for a source, before extension inference. */
+function identify(source: FileSource): { name: string; declaredMediaType?: string } {
+  switch (source.kind) {
+    case "file":
+      return { name: source.file.name || "file", declaredMediaType: source.file.type };
+    case "blob":
+      return { name: source.name, declaredMediaType: source.mediaType ?? source.blob.type };
+    case "buffer":
+      return { name: source.name, declaredMediaType: source.mediaType };
+    case "text":
+      return {
+        name: source.name,
+        declaredMediaType: source.mediaType ?? mediaTypeFromName(source.name) ?? "text/plain",
+      };
+    case "url":
+      return { name: source.name ?? nameFromUrl(source.url), declaredMediaType: source.mediaType };
+  }
+}
+
+/** Byte length where the platform already knows it, without reading anything. */
+function knownSize(source: FileSource): number | undefined {
+  switch (source.kind) {
+    case "file":
+      return source.file.size;
+    case "blob":
+      return source.blob.size;
+    case "buffer":
+      return source.buffer.byteLength;
+    // `text` would need an encode pass, `url` a fetch — neither is free, so we
+    // report "unknown" rather than doing work a caller may not want.
+    default:
+      return undefined;
+  }
+}
+
+function assertNotAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new Error("Aborted");
+}
+
+/**
+ * Turn any {@link FileSource} into a uniform reader.
+ *
+ * Cheap and synchronous — it resolves identity only. Nothing is read, fetched or
+ * decoded until a `bytes()` / `text()` / `url()` call.
+ */
+export function normalizeFileSource(source: FileSource): ResolvedFileSource {
+  const { name, declaredMediaType } = identify(source);
+  const kind = resolveFileKind(name, declaredMediaType);
+  const alt = "alt" in source ? source.alt : undefined;
+
+  let bytesPromise: Promise<ArrayBuffer> | undefined;
+  let textPromise: Promise<string> | undefined;
+  let objectUrl: string | undefined;
+
+  async function readBytes(signal?: AbortSignal): Promise<ArrayBuffer> {
+    assertNotAborted(signal);
+    switch (source.kind) {
+      case "file":
+        return blobToArrayBuffer(source.file);
+      case "blob":
+        return blobToArrayBuffer(source.blob);
+      case "buffer":
+        return source.buffer;
+      case "text":
+        return new TextEncoder().encode(source.text).buffer as ArrayBuffer;
+      case "url": {
+        // The caller's own signal (via `init`) still applies; this one is layered
+        // on top so a per-read abort works even when `init` carries none.
+        const res = await fetch(source.url, {
+          ...source.init,
+          signal: signal ?? source.init?.signal,
+        });
+        if (!res.ok) {
+          throw new Error(`Could not read "${name}": the server responded ${res.status}.`);
+        }
+        return res.arrayBuffer();
+      }
+    }
+  }
+
+  async function blobOf(signal?: AbortSignal): Promise<Blob> {
+    if (source.kind === "file") return source.file;
+    if (source.kind === "blob") return source.blob;
+    const buffer = await bytes(signal);
+    return new Blob([buffer], { type: kind.mediaType });
+  }
+
+  function bytes(signal?: AbortSignal): Promise<ArrayBuffer> {
+    // Memoize the success only: a rejected read must be retryable.
+    bytesPromise ??= readBytes(signal).catch((error: unknown) => {
+      bytesPromise = undefined;
+      throw error;
+    });
+    return bytesPromise;
+  }
+
+  function text(signal?: AbortSignal): Promise<string> {
+    if (source.kind === "text") return Promise.resolve(source.text);
+    textPromise ??= bytes(signal)
+      .then((buffer) => new TextDecoder().decode(buffer))
+      .catch((error: unknown) => {
+        textPromise = undefined;
+        throw error;
+      });
+    return textPromise;
+  }
+
+  async function url(signal?: AbortSignal): Promise<string> {
+    // A public remote file is already a URL an element can stream. One carrying
+    // `init` is not: the element cannot replay those headers, so we fetch here.
+    if (source.kind === "url" && !source.init) return source.url;
+
+    if (objectUrl) return objectUrl;
+    if (typeof URL === "undefined" || typeof URL.createObjectURL !== "function") {
+      throw new Error(
+        `Could not create a URL for "${name}": no object-URL support in this environment.`,
+      );
+    }
+    objectUrl = URL.createObjectURL(await blobOf(signal));
+    return objectUrl;
+  }
+
+  function revoke(): void {
+    if (!objectUrl) return;
+    URL.revokeObjectURL(objectUrl);
+    objectUrl = undefined;
+  }
+
+  return {
+    name,
+    mediaType: kind.mediaType,
+    category: kind.category,
+    extension: kind.extension,
+    alt,
+    size: knownSize(source),
+    bytes,
+    text,
+    url,
+    revoke,
+  };
+}

package/src/lib/merge-refs.test.ts

@@ -0,0 +1,37 @@
+import { createRef, type ForwardedRef } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { mergeRefs } from "./merge-refs";
+
+describe("mergeRefs", () => {
+  it("writes the node to object refs and calls callback refs", () => {
+    const objectRef = createRef<HTMLDivElement>();
+    const callbackRef = vi.fn();
+    const node = document.createElement("div");
+
+    mergeRefs<HTMLDivElement>(objectRef, callbackRef)(node);
+
+    expect(objectRef.current).toBe(node);
+    expect(callbackRef).toHaveBeenCalledWith(node);
+  });
+
+  it("propagates unmount (null) to every ref", () => {
+    const objectRef = createRef<HTMLDivElement>();
+    const callbackRef = vi.fn();
+    const merged = mergeRefs<HTMLDivElement>(objectRef, callbackRef);
+
+    merged(document.createElement("div"));
+    merged(null);
+
+    expect(objectRef.current).toBeNull();
+    expect(callbackRef).toHaveBeenLastCalledWith(null);
+  });
+
+  it("skips null/undefined refs — the common `forwardRef` case where no ref was passed", () => {
+    const objectRef = createRef<HTMLDivElement>();
+    const node = document.createElement("div");
+    const forwarded: ForwardedRef<HTMLDivElement> = null;
+
+    expect(() => mergeRefs<HTMLDivElement>(forwarded, undefined, objectRef)(node)).not.toThrow();
+    expect(objectRef.current).toBe(node);
+  });
+});

package/src/lib/merge-refs.ts

@@ -0,0 +1,17 @@
+import type { ForwardedRef } from "react";
+
+/**
+ * Combine a `forwardRef`-forwarded ref with one or more locally-owned refs so
+ * both end up pointing at the same DOM node. Returns a stable callback ref
+ * wrapper — memoize the result (`useMemo`) keyed on the forwarded ref so it
+ * doesn't detach/reattach on every render.
+ */
+export function mergeRefs<T>(...refs: Array<ForwardedRef<T> | undefined>) {
+  return (node: T | null) => {
+    for (const ref of refs) {
+      if (!ref) continue;
+      if (typeof ref === "function") ref(node);
+      else ref.current = node;
+    }
+  };
+}

package/src/lib/streamdown-translations.ts

@@ -0,0 +1,99 @@
+"use client";
+
+/**
+ * Streamdown's own chrome microcopy, resolved through the brand locale seam.
+ *
+ * Why this lives in `@elabs-ai/components-ui` and not next to the
+ * renderer that uses it (#310, ADR 0017): Streamdown draws controls INSIDE the
+ * markdown it renders — a code-block copy button, table copy/download menus, a
+ * Mermaid toolbar, an external-link interstitial. Those labels live in the
+ * dependency, so `pnpm microcopy:check` structurally cannot see them and a
+ * `<LocaleProvider>` used to stop dead at the Streamdown boundary. TWO packages
+ * now render Streamdown — `@elabs-ai/components-ai` (chat answers,
+ * `MarkdownView`) and `@elabs-ai/components-viewer` (a markdown FILE
+ * someone opened) — and they may not import each other, so the shared half sits
+ * one layer down where both can reach it.
+ *
+ * Deliberately NO import of `streamdown`, not even a type: this keeps the
+ * base package free of a dependency it would otherwise carry for every consumer
+ * of every component. The COMPLETENESS of the key list is proved where the
+ * dependency actually is — see `packages/ai/src/_streamdown-i18n.ts`, whose
+ * compile-time assertion fails the build if a Streamdown upgrade adds a key.
+ * That is the right split: the base package owns the wiring, the package that
+ * pins the version owns the tripwire.
+ *
+ * The English defaults in `./components/locale-provider/messages.ts` are
+ * byte-identical to Streamdown's own, so this is a no-op for anyone who
+ * overrides nothing.
+ */
+
+import { useMemo } from "react";
+
+import { useLocale } from "../components/locale-provider";
+
+/**
+ * Every key of `StreamdownTranslations` as of streamdown@2.5.0.
+ *
+ * Kept explicit rather than derived from `defaultTranslations`, so the list is
+ * readable data here and checkable against the real type over in `ai`.
+ */
+export const STREAMDOWN_TRANSLATION_KEYS = [
+  "close",
+  "copied",
+  "copyCode",
+  "copyLink",
+  "copyTable",
+  "copyTableAsCsv",
+  "copyTableAsMarkdown",
+  "copyTableAsTsv",
+  "downloadDiagram",
+  "downloadDiagramAsMmd",
+  "downloadDiagramAsPng",
+  "downloadDiagramAsSvg",
+  "downloadFile",
+  "downloadImage",
+  "downloadTable",
+  "downloadTableAsCsv",
+  "downloadTableAsMarkdown",
+  "exitFullscreen",
+  "externalLinkWarning",
+  "imageNotAvailable",
+  "mermaidFormatMmd",
+  "mermaidFormatPng",
+  "mermaidFormatSvg",
+  "openExternalLink",
+  "openLink",
+  "tableFormatCsv",
+  "tableFormatMarkdown",
+  "tableFormatTsv",
+  "viewFullscreen",
+] as const;
+
+export type StreamdownTranslationKey = (typeof STREAMDOWN_TRANSLATION_KEYS)[number];
+
+/** What Streamdown's `translations` prop takes, expressed without importing it. */
+export type StreamdownTranslationMap = Record<StreamdownTranslationKey, string>;
+
+/**
+ * Resolve every Streamdown label through `t()`.
+ *
+ * Provider-optional, like `useLocale()` itself: with no `<LocaleProvider>` every
+ * key resolves to the shipped English default.
+ *
+ * Memoization matters — Streamdown puts `translations` into a React context, so
+ * a fresh object per render would re-render every code block and table in the
+ * document. The map is memoized on `t`, which is stable per locale.
+ */
+export function useStreamdownTranslations(): StreamdownTranslationMap {
+  const { t } = useLocale();
+  return useMemo(() => {
+    const resolved = {} as StreamdownTranslationMap;
+    for (const key of STREAMDOWN_TRANSLATION_KEYS) {
+      // The `ai.streamdown.*` namespace is kept as-is although this now serves
+      // two packages: the keys name STREAMDOWN's chrome, not any one package's,
+      // and renaming them would silently drop every consumer's overrides.
+      resolved[key] = t(`ai.streamdown.${key}`);
+    }
+    return resolved;
+  }, [t]);
+}