@elabs-ai/components-viewer 4.0.0

package/src/adapters/markdown/markdown-adapter.tsx

@@ -0,0 +1,353 @@
+"use client";
+
+/**
+ * Markdown adapter — a `.md` file read as a DOCUMENT, not as source.
+ *
+ * Renders through `streamdown`, the same markdown engine
+ * `@elabs-ai/components-ai`'s `MarkdownView` and
+ * `@elabs-ai/components-editor`'s preview use, mapped onto the same
+ * `Prose*` primitives from `@elabs-ai/components-ui`. That is the
+ * point: a README must not look like three different documents depending on
+ * which pane it opened in. The element map below is deliberately a near-copy of
+ * `MarkdownView`'s — the packages are siblings and may not import each other,
+ * and the shared half that could move down (the `Prose*` set, the Streamdown
+ * locale bridge) already has.
+ *
+ * What this does NOT do, on purpose:
+ *
+ * - **No plugins.** `@streamdown/code`, `/math`, `/cjk` and `/mermaid` are four
+ *   more packages a consumer would have to install to open one file. Fenced code
+ *   is rendered as an unhighlighted block by the element map below (Streamdown
+ *   emits a bare `<code>` without the code plugin, so the `<pre>` is ours); a
+ *   source file opened directly still gets Shiki from the `code` adapter, and a
+ *   diagram fence reads as its own text rather than as a picture.
+ * - **No streaming.** A file arrives settled or not at all, so `mode="static"`
+ *   and `parseIncompleteMarkdown={false}` — the incomplete-token repair that
+ *   makes Streamdown good at chat is only overhead for a file on disk.
+ */
+
+import {
+  ProseBlockquote,
+  ProseHeading,
+  ProseInlineCode,
+  ProseLink,
+  ProseList,
+  ProseListItem,
+  ProseText,
+  StatePanel,
+  cn,
+  useLocale,
+  useStreamdownTranslations,
+} from "@elabs-ai/components-ui";
+import type { ProseHeadingLevel, ResolvedFileSource } from "@elabs-ai/components-ui";
+import type { ComponentProps, ReactNode } from "react";
+import { createContext, use, useMemo, useRef } from "react";
+import type * as StreamdownExports from "streamdown";
+
+import { toViewerError } from "../../core/errors";
+import { toMarkRanges, type MarkRanges } from "../../core/highlight-marks";
+import { useScrollActiveHighlightIntoView } from "../../core/use-highlight-scroll";
+import type {
+  AdapterDocument,
+  AdapterLoadContext,
+  AdapterModule,
+  AdapterRendererProps,
+  FileAdapter,
+} from "../../core/types";
+import { blockMark, blockMarkAttributes, type PositionedNode } from "./markdown-marks";
+import { markdownManifest } from "./markdown-manifest";
+
+/**
+ * Characters kept before truncation. Markdown is parsed into an element tree,
+ * which costs more than a `<pre>` — this sits between the code and plain-text
+ * limits for that reason.
+ */
+export const MARKDOWN_CHARACTER_LIMIT = 1_000_000;
+
+export interface MarkdownDocument extends AdapterDocument {
+  kind: "markdown";
+  text: string;
+  /** Total characters in the file, when more than what is shown. */
+  totalCharacters?: number;
+}
+
+// Type-only, so it erases: the runtime edge is the dynamic import below.
+type StreamdownModule = typeof StreamdownExports;
+type StreamdownComponents = NonNullable<
+  ComponentProps<StreamdownModule["Streamdown"]>["components"]
+>;
+
+/**
+ * The engine, resolved once per page.
+ *
+ * Loaded in `load()` rather than imported at the top of this module for the
+ * reason every other adapter does it: `streamdown` is an OPTIONAL peer, and a
+ * static edge would make this module unresolvable — not merely heavier — for a
+ * consumer who never installs it. The renderer reads the same cached module,
+ * which is guaranteed to be populated because a document only exists once
+ * `load()` has resolved.
+ */
+let streamdown: StreamdownModule | undefined;
+
+async function loadStreamdown(): Promise<StreamdownModule> {
+  // Dynamic: the ONLY edge to the optional peer (heavy-deps:check).
+  streamdown ??= await import("streamdown");
+  return streamdown;
+}
+
+class MarkdownAdapter implements FileAdapter {
+  async load(source: ResolvedFileSource, context: AdapterLoadContext): Promise<MarkdownDocument> {
+    let raw: string;
+    try {
+      raw = await source.text(context.signal);
+    } catch (error) {
+      throw toViewerError(error, "read-failed", { fileName: source.name });
+    }
+
+    // Before returning: a document this adapter's Renderer cannot draw is a
+    // failed load, not a blank pane. A missing peer surfaces from here as
+    // `parser-missing` (see `parserMissingError`).
+    await loadStreamdown();
+
+    const truncated = raw.length > MARKDOWN_CHARACTER_LIMIT;
+    return {
+      kind: "markdown",
+      text: truncated ? raw.slice(0, MARKDOWN_CHARACTER_LIMIT) : raw,
+      totalCharacters: truncated ? raw.length : undefined,
+    };
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* Renderer                                                                    */
+/* -------------------------------------------------------------------------- */
+
+/** Never past `h6`, whatever the offset — an `h7` is not an element. */
+const clampHeadingLevel = (level: number): ProseHeadingLevel =>
+  Math.min(6, Math.max(1, level)) as ProseHeadingLevel;
+
+/* -------------------------------------------------------------------------- */
+/* Highlight plates                                                            */
+/* -------------------------------------------------------------------------- */
+
+const EMPTY_MARKS: MarkRanges = { ranges: [], activeIndex: -1 };
+
+/**
+ * The marks, read by the block components.
+ *
+ * A context rather than a closure over `buildProseComponents`, so the element
+ * map stays memoized on the heading offset alone: rebuilding it per keystroke
+ * of a find-as-you-type would hand Streamdown a new `components` object every
+ * time, which it treats as a reason to re-render every block in the file.
+ */
+const MarkContext = createContext<MarkRanges>(EMPTY_MARKS);
+
+/** Set once a block has plated, so a nested one does not plate on top of it. */
+const PlatedContext = createContext(false);
+
+/**
+ * The plate for one block, and a wrapper that stops its children plating again.
+ *
+ * A loose list item renders as `li > p`, and both nodes' source spans contain
+ * the same mark — without the suppression the reader sees two stacked fills for
+ * one citation.
+ */
+function usePlate(node: PositionedNode | undefined, className?: string) {
+  const marks = use(MarkContext);
+  const plated = use(PlatedContext);
+  const mark = plated ? { marked: false, active: false } : blockMark(marks, node);
+  return {
+    props: blockMarkAttributes(mark, className),
+    wrap: (children: ReactNode) =>
+      mark.marked ? <PlatedContext value={true}>{children}</PlatedContext> : children,
+  };
+}
+
+/*
+ * The plating blocks are named components rather than inline arrows in the map
+ * below: they call a hook, and a lowercase `p:` key is not a component name as
+ * far as the rules-of-hooks lint can tell.
+ */
+
+const MarkdownParagraph: NonNullable<StreamdownComponents["p"]> = ({
+  node,
+  className,
+  children,
+  ...props
+}) => {
+  const plate = usePlate(node, className);
+  return (
+    <ProseText {...plate.props} {...props}>
+      {plate.wrap(children)}
+    </ProseText>
+  );
+};
+
+const MarkdownListItem: NonNullable<StreamdownComponents["li"]> = ({
+  node,
+  className,
+  children,
+  ...props
+}) => {
+  const plate = usePlate(node, className);
+  return (
+    <ProseListItem {...plate.props} {...props}>
+      {plate.wrap(children)}
+    </ProseListItem>
+  );
+};
+
+const MarkdownCode: NonNullable<StreamdownComponents["code"]> = ({
+  node,
+  className,
+  children,
+  ...props
+}) => {
+  const fence = /\blanguage-/.test(className ?? "");
+  // The plate goes on the `<pre>` — the whole fence is what a citation points
+  // at. Its own `bg-surface-muted` wins over the plate's fill (see
+  // `blockMarkAttributes`), so the code keeps its ground and the rail is what
+  // says it is cited.
+  const plate = usePlate(
+    fence ? node : undefined,
+    "bg-surface-muted text-code overflow-x-auto rounded-md p-3 font-mono whitespace-pre",
+  );
+  // A fence needs its own `<pre>`. With no `@streamdown/code` plugin installed
+  // Streamdown emits a BARE `<code data-block>` — no block wrapper — which the
+  // surrounding prose's `whitespace-normal` then collapses into one run-on
+  // line. The fence is unhighlighted here by design (see the module docblock);
+  // it still has to read as a block of code.
+  return fence ? (
+    <pre {...plate.props}>
+      <code className={className} {...props}>
+        {plate.wrap(children)}
+      </code>
+    </pre>
+  ) : (
+    <ProseInlineCode className={className} {...props}>
+      {children}
+    </ProseInlineCode>
+  );
+};
+
+/** Everything that does not depend on the heading offset. */
+const SHARED_COMPONENTS: StreamdownComponents = {
+  p: MarkdownParagraph,
+  a: ({ node: _node, ...props }) => <ProseLink {...props} />,
+  // `ref` is stripped: ProseList's intersection ref type (ul & ol) is narrower
+  // than the per-element ref react-markdown passes.
+  ul: ({ node: _node, ref: _ref, ...props }) => <ProseList {...props} />,
+  ol: ({ node: _node, ref: _ref, ...props }) => <ProseList ordered {...props} />,
+  li: MarkdownListItem,
+  blockquote: ({ node: _node, ...props }) => <ProseBlockquote {...props} />,
+  code: MarkdownCode,
+};
+
+/**
+ * Map the markdown element tree onto the Prose primitives.
+ *
+ * Built per `baseHeadingLevel` (memoized by the renderer, not rebuilt each
+ * render): the map is otherwise pure and Streamdown puts it into a context, so
+ * a fresh object per render would re-render every block.
+ *
+ * The heading offset is the reason this takes an argument at all. A viewed file
+ * carries its own heading tree, correct only relative to the page hosting it —
+ * a README's `#` inside an app that already has an `<h1>` would otherwise put
+ * two `h1`s in a screen reader's flat heading list. Same seam, same arithmetic
+ * as `@elabs-ai/components-ai`'s `MarkdownView`.
+ */
+function buildProseComponents(baseHeadingLevel: ProseHeadingLevel): StreamdownComponents {
+  const heading =
+    (markdownLevel: number): StreamdownComponents["h1"] =>
+    ({ node, className, children, ...props }) => {
+      const plate = usePlate(node, className);
+      return (
+        <ProseHeading
+          level={clampHeadingLevel(markdownLevel + baseHeadingLevel - 1)}
+          {...plate.props}
+          {...props}
+        >
+          {plate.wrap(children)}
+        </ProseHeading>
+      );
+    };
+  return {
+    h1: heading(1),
+    h2: heading(2),
+    h3: heading(3),
+    h4: heading(4),
+    h5: heading(5),
+    h6: heading(6),
+    ...SHARED_COMPONENTS,
+  };
+}
+
+function MarkdownRenderer({
+  document: doc,
+  className,
+  baseHeadingLevel = 2,
+  highlights,
+  activeHighlightId,
+}: AdapterRendererProps) {
+  const markdown = doc as MarkdownDocument;
+  const { t, formatNumber } = useLocale();
+  const translations = useStreamdownTranslations();
+  const components = useMemo(() => buildProseComponents(baseHeadingLevel), [baseHeadingLevel]);
+  const container = useRef<HTMLDivElement>(null);
+  const marks = useMemo(
+    () => toMarkRanges(highlights, markdown.text.length),
+    [highlights, markdown.text],
+  );
+
+  useScrollActiveHighlightIntoView(container, activeHighlightId);
+
+  if (markdown.text.trim().length === 0) {
+    return <StatePanel kind="empty" title={t("viewer.file.empty")} className={className} />;
+  }
+
+  const Streamdown = streamdown?.Streamdown;
+  if (!Streamdown) return null;
+
+  return (
+    // No `overflow-auto` here: `FileViewerContent` is the scroll boundary, and
+    // nesting a second one clips the last block above the outer pane's padding.
+    <div ref={container} className={cn("flex flex-col gap-2", className)}>
+      {markdown.totalCharacters !== undefined && (
+        // Not an error — the file is fine, we are showing part of it.
+        <p role="status" className="text-meta text-muted-foreground">
+          {t("viewer.text.truncated", {
+            shown: formatNumber(markdown.text.length),
+            total: formatNumber(markdown.totalCharacters),
+          })}
+        </p>
+      )}
+      {/* `max-w-prose` because this is genuine long-form reading, not a label:
+          a README run edge-to-edge across a wide pane loses the line. The pane's
+          own padding is the page margin — the article adds none. */}
+      <article className="mx-auto max-w-prose space-y-3">
+        {/* `mode="static"` is what makes the plates addressable: it hands the
+            whole file to ONE parse, so every node's `position.start.offset` is
+            an offset into `document.text`. Splitting into blocks (streaming
+            mode) would restart them per block. */}
+        <MarkContext value={marks}>
+          <Streamdown
+            mode="static"
+            parseIncompleteMarkdown={false}
+            components={components}
+            translations={translations}
+          >
+            {markdown.text}
+          </Streamdown>
+        </MarkContext>
+      </article>
+    </div>
+  );
+}
+
+const adapterModule: AdapterModule = {
+  manifest: markdownManifest,
+  create: () => new MarkdownAdapter(),
+  Renderer: MarkdownRenderer,
+};
+
+export default adapterModule;

package/src/adapters/markdown/markdown-manifest.ts

@@ -0,0 +1,21 @@
+import type { AdapterManifest } from "../../core/types";
+import { PROTOCOL_VERSION } from "../../core/types";
+
+/**
+ * Eager, data-only (see `image-manifest.ts`).
+ *
+ * `.mdx` is deliberately NOT claimed: it is JavaScript wearing markdown, and
+ * rendering it would mean evaluating a foreign file's code — the one thing a
+ * viewer must never do. An `.mdx` falls through to the plain-text adapter.
+ */
+export const markdownManifest: AdapterManifest = {
+  id: "markdown",
+  protocol: PROTOCOL_VERSION,
+  extensions: ["md", "markdown", "mdown", "mkd"],
+  mediaTypes: ["text/markdown"],
+  // Both kinds address the SOURCE, which is what `text` is here — and both are
+  // painted as a whole-block plate rather than as characters, because a source
+  // offset can land inside markup the reader never sees. See `markdown-marks.ts`.
+  capabilities: { text: true, search: true, highlight: ["quote", "range"] },
+  requires: ["streamdown"],
+};

package/src/adapters/markdown/markdown-marks.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+
+import type { MarkRanges } from "../../core/highlight-marks";
+import { blockMark, blockMarkAttributes } from "./markdown-marks";
+
+const at = (start: number, end: number) => ({
+  position: { start: { offset: start }, end: { offset: end } },
+});
+const marks = (ranges: [number, number][], activeIndex = -1): MarkRanges => ({
+  ranges,
+  activeIndex,
+});
+
+describe("blockMark", () => {
+  it("marks a block a range falls inside", () => {
+    expect(blockMark(marks([[12, 20]]), at(10, 30))).toEqual({ marked: true, active: false });
+  });
+
+  it("marks a block a range only overlaps", () => {
+    // A citation running across a block break belongs to BOTH blocks — that is
+    // what keeps one passage reading as one passage.
+    expect(blockMark(marks([[5, 15]]), at(10, 30)).marked).toBe(true);
+    expect(blockMark(marks([[25, 40]]), at(10, 30)).marked).toBe(true);
+  });
+
+  it("leaves the neighbours alone when a range abuts a boundary", () => {
+    expect(blockMark(marks([[0, 10]]), at(10, 30)).marked).toBe(false);
+    expect(blockMark(marks([[30, 40]]), at(10, 30)).marked).toBe(false);
+  });
+
+  it("reports the active range separately from the rest", () => {
+    const two = marks(
+      [
+        [12, 14],
+        [50, 55],
+      ],
+      1,
+    );
+    expect(blockMark(two, at(10, 30))).toEqual({ marked: true, active: false });
+    expect(blockMark(two, at(45, 60))).toEqual({ marked: true, active: true });
+  });
+
+  it("marks nothing for a node with no source position", () => {
+    // rehype-raw and generated nodes have none; a plate guessed from a missing
+    // position would land on an arbitrary block.
+    expect(blockMark(marks([[0, 100]]), {})).toEqual({ marked: false, active: false });
+    expect(blockMark(marks([[0, 100]]), undefined)).toEqual({ marked: false, active: false });
+    expect(blockMark(marks([[0, 100]]), at(10, 10))).toEqual({ marked: false, active: false });
+  });
+});
+
+describe("blockMarkAttributes", () => {
+  it("adds nothing to an unmarked block but its own class", () => {
+    expect(blockMarkAttributes({ marked: false, active: false })).toEqual({});
+    expect(blockMarkAttributes({ marked: false, active: false }, "prose")).toEqual({
+      className: "prose",
+    });
+  });
+
+  it("gives a marked block the shared slot, and the active one a name for AT", () => {
+    const marked = blockMarkAttributes({ marked: true, active: false });
+    expect(marked["data-slot"]).toBe("highlight-block");
+    expect(marked["data-active"]).toBeUndefined();
+    expect(marked["aria-current"]).toBeUndefined();
+
+    const active = blockMarkAttributes({ marked: true, active: true });
+    // Presence form, not `"true"`: one selector finds the current highlight
+    // whichever painter drew it.
+    expect(active["data-active"]).toBe("");
+    expect(active["aria-current"]).toBe("true");
+  });
+
+  it("distinguishes the current plate by more than its colour", () => {
+    // WCAG 1.4.1: the rail doubles in width as well as changing hue, so the
+    // current passage survives greyscale.
+    expect(blockMarkAttributes({ marked: true, active: false }).className).toContain("border-s-2");
+    expect(blockMarkAttributes({ marked: true, active: true }).className).toContain("border-s-4");
+  });
+
+  it("keeps the block's own classes alongside the plate's", () => {
+    expect(blockMarkAttributes({ marked: true, active: false }, "font-mono").className).toContain(
+      "font-mono",
+    );
+  });
+});

package/src/adapters/markdown/markdown-marks.ts

@@ -0,0 +1,119 @@
+/**
+ * Markdown highlights are BLOCK-shaped, and that is a deliberate downgrade.
+ *
+ * Every other text adapter marks characters, because its `document.text` is the
+ * thing on screen. Markdown's is not: `text` is the SOURCE, so offset 12 might
+ * land in the middle of `**bold**` — two of whose characters are never drawn at
+ * all — or inside a link's URL, which the reader only sees as a word. There is
+ * no honest character-level mapping from source offsets to rendered text
+ * without re-implementing the parser's own position bookkeeping for inline
+ * nodes, and getting that subtly wrong would put marks on the wrong words while
+ * looking exactly as confident as a correct one.
+ *
+ * So a markdown mark says "this passage is in HERE" — the paragraph, heading,
+ * list item or fence whose source span the mark touches is plated whole. That
+ * is enough for the case the feature exists for (a citation pointing a reader at
+ * the passage an answer came from) and it cannot be subtly wrong: a block either
+ * contains the source range or it does not.
+ *
+ * The offsets are trustworthy because the renderer runs Streamdown in
+ * `mode="static"`, which hands the WHOLE file to one parse — no per-block
+ * splitting, no incomplete-token repair — so every hast node's
+ * `position.start.offset` is an offset into `document.text` itself.
+ */
+
+import { cn } from "@elabs-ai/components-ui";
+
+import type { MarkRanges } from "../../core/highlight-marks";
+
+/** The subset of a unist `Position` this needs. Structural, so no unist import. */
+export interface SourcePosition {
+  start?: { offset?: number };
+  end?: { offset?: number };
+}
+
+/** A hast node as the component overrides receive it. */
+export interface PositionedNode {
+  position?: SourcePosition;
+}
+
+/** Whether a block carries any mark, and whether it carries the current one. */
+export interface BlockMark {
+  marked: boolean;
+  active: boolean;
+}
+
+const UNMARKED: BlockMark = { marked: false, active: false };
+
+/**
+ * Which marks land inside one block's source span.
+ *
+ * Half-open on both sides and strict, so a mark ending exactly where a block
+ * begins belongs to the block before it — otherwise the paragraph after a
+ * marked heading would light up too, on every citation.
+ */
+export function blockMark(marks: MarkRanges, node: PositionedNode | undefined): BlockMark {
+  const start = node?.position?.start?.offset;
+  const end = node?.position?.end?.offset;
+  if (start === undefined || end === undefined || end <= start) return UNMARKED;
+
+  let marked = false;
+  let active = false;
+  marks.ranges.forEach(([from, to], index) => {
+    if (from >= end || to <= start) return;
+    marked = true;
+    if (index === marks.activeIndex) active = true;
+  });
+  return marked ? { marked, active } : UNMARKED;
+}
+
+/**
+ * The attributes a plated block carries.
+ *
+ * `data-slot`/`data-active` are the same seam the character marks use, so one
+ * selector finds "the current highlight" whatever adapter drew it — that is what
+ * `useScrollActiveHighlightIntoView` scrolls to. `aria-current` is the part that
+ * is not decoration: the active block is announced as the current one rather
+ * than being distinguishable only by a warmer plate (WCAG 1.4.1).
+ */
+export interface BlockMarkAttributes {
+  "data-slot"?: "highlight-block";
+  /**
+   * Present-or-absent, never `"false"` — the same shape `MatchHighlight`'s marks
+   * and the PDF's boxes emit, so one selector (`[data-active]`) finds the current
+   * highlight whichever painter drew it.
+   */
+  "data-active"?: "";
+  "aria-current"?: "true";
+  className?: string;
+}
+
+/**
+ * Plate classes.
+ *
+ * A marked block gets a fill AND a rail; the current one doubles the rail's
+ * width on top of warming the fill, so "which one am I on" survives greyscale
+ * and a colour-vision difference. The negative margins let the plate bleed into
+ * the prose column's own gutter instead of shifting the text when it appears.
+ */
+const MARKED_CLASS = "bg-highlight/40 border-s-2 border-highlight rounded-e-sm ps-2 -ms-2";
+const ACTIVE_CLASS =
+  "bg-highlight-active/40 border-s-4 border-highlight-active rounded-e-sm ps-2 -ms-2";
+
+/**
+ * Spreadable attributes for a block, given how the marks fell on it.
+ *
+ * The block's OWN classes are merged last and therefore win, which is the
+ * deliberate answer for a fenced code block: `bg-surface-muted` beats the
+ * plate's fill, so the code keeps its own ground and the rail alone says it is
+ * cited. Leaving the order to CSS source order instead would make that outcome
+ * accidental.
+ */
+export function blockMarkAttributes(mark: BlockMark, className?: string): BlockMarkAttributes {
+  if (!mark.marked) return className === undefined ? {} : { className };
+  return {
+    "data-slot": "highlight-block",
+    ...(mark.active ? { "data-active": "" as const, "aria-current": "true" as const } : {}),
+    className: cn(mark.active ? ACTIVE_CLASS : MARKED_CLASS, className),
+  };
+}

package/src/adapters/media/media-adapter.test.tsx

@@ -0,0 +1,79 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import type { AdapterRendererProps } from "../../core/types";
+import adapterModule, { type MediaDocument } from "./media-adapter";
+
+function source(overrides: Partial<Record<string, unknown>> = {}) {
+  return {
+    name: "briefing.mp4",
+    mediaType: "video/mp4",
+    category: "video",
+    extension: "mp4",
+    bytes: () => Promise.resolve(new ArrayBuffer(0)),
+    text: () => Promise.resolve(""),
+    url: () => Promise.resolve("blob:media"),
+    revoke: vi.fn(),
+    ...overrides,
+  } as unknown as AdapterRendererProps["source"];
+}
+
+function renderMedia(media: "video" | "audio", name: string) {
+  const { Renderer } = adapterModule;
+  const document: MediaDocument = { kind: "media", url: "blob:media", media };
+  return render(<Renderer document={document} source={source({ name, category: media })} />);
+}
+
+describe("media adapter — load", () => {
+  it("streams from a URL instead of buffering the whole file", async () => {
+    const bytes = vi.fn();
+    const adapter = adapterModule.create();
+    const document = await adapter.load(source({ bytes }), {});
+
+    expect(document).toMatchObject({ kind: "media", media: "video", url: "blob:media" });
+    // A 2 GB video read into memory to feed a <video> element is the wrong shape
+    // at every size — the element streams and seeks from the URL itself.
+    expect(bytes).not.toHaveBeenCalled();
+  });
+
+  it("picks the audio element from the source's own category", async () => {
+    const adapter = adapterModule.create();
+    const document = await adapter.load(source({ category: "audio", name: "call.mp3" }), {});
+    expect(document).toMatchObject({ media: "audio" });
+  });
+
+  it("revokes the object URL it minted", async () => {
+    const revoke = vi.fn();
+    const adapter = adapterModule.create();
+    await adapter.load(source({ revoke }), {});
+    adapter.dispose?.();
+    expect(revoke).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("media adapter — rendering", () => {
+  it("renders a native, controllable video with an accessible name", () => {
+    const { container } = renderMedia("video", "briefing.mp4");
+    const video = container.querySelector("video");
+    expect(video).toHaveAttribute("controls");
+    expect(video).toHaveAttribute("aria-label", "briefing.mp4 player");
+    // Sound that starts on its own is the reason browsers block autoplay.
+    expect(video).not.toHaveAttribute("autoplay");
+  });
+
+  it("renders an audio element for audio", () => {
+    const { container } = renderMedia("audio", "call.mp3");
+    expect(container.querySelector("audio")).toBeInTheDocument();
+    expect(container.querySelector("video")).toBeNull();
+  });
+
+  it("states an undecodable codec as a settled failure, with no retry", () => {
+    const { container } = renderMedia("video", "briefing.mp4");
+    fireEvent.error(container.querySelector("video") as HTMLVideoElement);
+
+    const alert = screen.getByRole("alert");
+    expect(alert).toHaveTextContent("This browser can't play briefing.mp4.");
+    // Retrying cannot install a codec.
+    expect(screen.queryByRole("button")).not.toBeInTheDocument();
+  });
+});