@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/media-player.md

@@ -0,0 +1,74 @@
+## What it is
+
+The transport: play, seek, volume, captions, playback rate, picture-in-picture, fullscreen, keyboard — over a real `<video>` or `<audio>` element. Audio and video come from the one contract, with `@kind` deciding whether the chrome lays out over a picture or in normal flow.
+
+You rarely reach for it directly. **VideoPlayer** and **AudioPlayer** are skins over it, and **MediaViewer** routes to those by asset kind. Use this when you want the transport without either skin's framing — or with `@chrome='none'`, when you want to build the control bar yourself.
+
+## The contract
+
+```
+@src?            — passed through untouched; the player never builds or revokes an object URL
+@kind?           — 'video' (default) | 'audio'
+@label?          — accessible name for the player region
+@poster?         — poster image for video
+@placeholder?    — tiny inline image painted under the poster while the poster loads
+@aspectRatio?    — CSS aspect-ratio for the stage. Default '16 / 9'
+@tracks?         — MediaTrackSpec[]: captions, subtitles, descriptions, chapters
+@thumbnails?     — WebVTT thumbnails track; present ⇒ the scrubber previews while seeking
+@transcript?     — TranscriptCue[], seekable
+@transcriptOpen? — open the transcript on first paint. Default false
+@captionsDefault?— turn on the first subtitles track unasked. Default false
+@chrome?         — 'full' (default) | 'none', which renders an empty bar for <:controls>
+@seekOffset?     — seconds for the skip buttons and ←/→. Default 10
+@autoHide?       — let controls fade during playback. Default false
+@loop?, @muted?  — both default false
+@preload?        — 'none' | 'metadata' (default) | 'auto'
+@crossOrigin?    — 'anonymous' | 'use-credentials'
+@quietStatus?    — hide the status line. Default false
+@onSnapshot?     — fires on every media event with the current snapshot
+
+<:overlay>  floats over the picture, top-left
+<:controls> appended inside the control bar, before fullscreen
+<:footer>   under the transport, above the transcript
+```
+
+**`@src` is passed through untouched.** The player never builds or revokes an object URL, so a blob URL stays the caller's to revoke — the component cannot know when the caller is done with it.
+
+**The stage reserves its aspect ratio from the first paint**, which is what stops the poster's arrival from reflowing the page around it. `@placeholder` exists for the gap before the poster itself resolves.
+
+**There is no autoplay.** `@muted` is a starting state, not a licence to start.
+
+**`@autoHide` defaults to false, inverting Media Chrome's own default.** Controls that vanish during playback are a discoverability cost the kit is not willing to pay by default. Focus always brings them back regardless.
+
+**`@crossOrigin` is load-bearing for captions.** A cross-origin `<track>` file needs `'anonymous'` here or the browser drops it silently — no error, no captions button, nothing to debug.
+
+**The transcript disclosure is uncontrolled with an override.** Internal state starts as "unset", which means `@transcriptOpen` still applies; once the reader touches the toggle, their choice wins and a caller flipping the arg no longer moves it.
+
+**`timeupdate` is only subscribed when something on screen moves with the playhead** — that is, when there is a transcript. It costs a re-render four times a second, and paying it for a player with nothing to highlight would be waste.
+
+## Prior art
+
+Built on **Media Chrome** (MIT, web components): `<media-controller>` and its control-bar elements are doing the transport work, not a re-implementation. **Vidstack** is the reference for the video skin above it.
+
+Where Pretui adds: the **seekable transcript** — neither upstream ships one, and it is the single most useful accessibility affordance a player can have, for readers who cannot use audio _and_ for anyone who wants to find a moment without scrubbing. The **status line** is a text channel for buffering and error state rather than a spinner alone. `@autoHide` is inverted. And the reserved aspect ratio is enforced from first paint rather than being the caller's problem.
+
+Where it is thinner: there is no playlist or queue model, no quality or track selector beyond captions, no chapters UI (chapters ride along for the browser and the scrubber but get no menu of their own), and no analytics or heartbeat hooks beyond `@onSnapshot`. Anything resembling adaptive streaming is entirely the browser's business here.
+
+## Accessibility
+
+This is the component where most of the accessibility budget went, and three decisions are worth knowing.
+
+- **The live region says one thing, and says it rarely: a failure.** It is always present and empty until a load fails. Play, pause and seek are already announced by the transport buttons' own labels, and repeating them would be the "announces on every keystroke" failure — a region that narrates every interaction is a region users turn off.
+- **The transcript is an APG disclosure rather than `<details>`/`<summary>`, and that is not a preference.** Realm lint's `no-nested-interactive` counts `<details>` as interactive and rejects any `<button>` inside it, cue buttons included. The platform element would have been the better answer — platform behaviour before a JS re-implementation — so since it is unavailable, the replacement carries the full contract instead: a real button, `aria-expanded`, `aria-controls`, and a region that stays in the DOM and hides with `hidden`, so the id `aria-controls` names always resolves.
+- **The cue containing the playhead carries `aria-current`**, so a screen-reader user moving through the transcript can tell where playback is.
+- **`@label` is strongly recommended and not enforced.** An unnamed player region is a dead end for someone moving by landmark, and nothing here will tell you that you forgot it.
+- **The status glyph is `aria-hidden`**; the status text beside it carries the meaning, so buffering and error state are never conveyed by a symbol alone.
+- **The disclosure id comes from a module counter**, not a random value or a timestamp — both are forbidden in this codebase, and neither is needed: the id has to be unique in a document, not unguessable.
+
+## Theming
+
+`--pretui-media-aspect` (the reserved stage ratio, written from `@aspectRatio`), `--pretui-media-radius`, `--pretui-media-ink` (the chrome's foreground), `--pretui-media-scrim` (the wash under the controls that keeps them legible over any frame), `--pretui-destructive-ink` (the error state), `--pretui-shadow-card`, `--pretui-shadow-hairline`.
+
+The scrim is the token to watch across themes: it is what guarantees the control bar stays readable over an arbitrary video frame, and a theme that lightens it for aesthetics on a dark test clip will fail on a bright one. The kit's shared shadow tokens mean a player sits at the same elevation as the cards around it without a per-component value.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/media-player.usage.gts

@@ -0,0 +1,265 @@
+// Pretui — MediaPlayer usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { MediaPlayer } from './media-player';
+import type { MediaChrome, MediaSnapshot } from './media-player';
+import {
+  SAMPLE_VIDEO_POSTER,
+  SAMPLE_VIDEO_SRC,
+  SOURCING_TRACKS,
+  SOURCING_TRANSCRIPT,
+  TONE_WAV,
+} from '../media-examples';
+import { Token } from './token';
+import { CHROMES } from '../demo-media';
+
+// ── MediaPlayer ──────────────────────────────────────────────────────────
+const KINDS: string[] = ['audio', 'video'];
+
+class MediaPlayerUsage extends Component {
+  chromes = CHROMES;
+  kinds = KINDS;
+  tracks = SOURCING_TRACKS;
+  transcript = SOURCING_TRANSCRIPT;
+
+  @tracked kind = 'audio';
+  @tracked chrome = 'full';
+  @tracked autoHide = false;
+  @tracked transcriptOpen = true;
+  @tracked quietStatus = false;
+  @tracked captionsDefault = false;
+  @tracked seekOffset = 10;
+  @tracked lastPhase = 'idle';
+
+  setKind = (v: string) => (this.kind = v);
+  setChrome = (v: string) => (this.chrome = v);
+  setAutoHide = (v: boolean) => (this.autoHide = v);
+  setTranscriptOpen = (v: boolean) => (this.transcriptOpen = v);
+  setQuietStatus = (v: boolean) => (this.quietStatus = v);
+  setCaptionsDefault = (v: boolean) => (this.captionsDefault = v);
+  setSeekOffset = (v: number | null) => (this.seekOffset = v ?? 10);
+  noteSnapshot = (snapshot: MediaSnapshot) => (this.lastPhase = snapshot.phase);
+
+  get kindValue(): 'audio' | 'video' {
+    return this.kind === 'video' ? 'video' : 'audio';
+  }
+  get chromeValue(): MediaChrome {
+    return this.chrome as MediaChrome;
+  }
+  get src(): string {
+    return this.kindValue === 'video' ? SAMPLE_VIDEO_SRC : TONE_WAV;
+  }
+  get poster(): string | undefined {
+    return this.kindValue === 'video' ? SAMPLE_VIDEO_POSTER : undefined;
+  }
+  get label(): string {
+    return this.kindValue === 'video'
+      ? 'Estate reel — second flush'
+      : 'Lot B-1180 — desk note';
+  }
+  get usage(): string {
+    return [
+      '<MediaPlayer',
+      `  @kind='${this.kindValue}'`,
+      "  @src={{this.src}}",
+      `  @label='${this.label}'`,
+      `  @chrome='${this.chrome}'`,
+      '  @tracks={{this.tracks}}',
+      '  @transcript={{this.transcript}}',
+      '/>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='MediaPlayer'
+      @description="One transport contract for audio and video, built on Media Chrome (MIT, vendored at ./media-chrome). Everything here plays offline: the audio is six seconds of PCM synthesised as a speech-shaped desk note, and its captions are a WebVTT data URL compiled from the very cue list the transcript below renders — so the browser's caption channel and ours cannot drift apart. Try the keyboard before anything else: click the picture, then Space, ←, →, ↑, ↓, m, c, f, and Shift+/ for the shortcut sheet. Then set autoHide on, Tab into the controls, and watch them come back — Media Chrome's own default leaves them focusable and invisible, which is the one behaviour on this page that had to be inverted rather than themed."
+      @source={{this.usage}}
+    >
+      <:example>
+        <MediaPlayer
+          @kind={{this.kindValue}}
+          @src={{this.src}}
+          @label={{this.label}}
+          @poster={{this.poster}}
+          @chrome={{this.chromeValue}}
+          @autoHide={{this.autoHide}}
+          @tracks={{this.tracks}}
+          @transcript={{this.transcript}}
+          @transcriptOpen={{this.transcriptOpen}}
+          @captionsDefault={{this.captionsDefault}}
+          @quietStatus={{this.quietStatus}}
+          @seekOffset={{this.seekOffset}}
+          @onSnapshot={{this.noteSnapshot}}
+        />
+        <p class='mp-readout'>
+          <span class='mp-readoutLabel'>@onSnapshot phase</span>
+          <Token @value={{this.lastPhase}} />
+        </p>
+      </:example>
+
+      <:api as |Args|>
+        <Args.String
+          @name='kind'
+          @value={{this.kind}}
+          @options={{this.kinds}}
+          @defaultValue='video'
+          @description="'video' (default) or 'audio'. Audio mode lays the transport out in normal flow instead of over a picture, drops the fullscreen and picture-in-picture controls, and re-points the ink token at the page foreground — one custom-property flip, not a second theme. NOTE: switching to video here loads a public test clip over the network; offline it lands on the error channel, which is itself worth seeing."
+          @onInput={{this.setKind}}
+        />
+        <Args.String
+          @name='src'
+          @value={{this.src}}
+          @description='URL of the media. Passed through untouched — this component never creates or revokes an object URL, so a blob URL stays yours to revoke.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='label'
+          @value={{this.label}}
+          @description='Accessible name for the player region. An unnamed media region is a dead end for anyone moving by landmark.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='chrome'
+          @value={{this.chrome}}
+          @options={{this.chromes}}
+          @defaultValue='full'
+          @description="How much transport to wear: 'full', 'compact' (no skip buttons, no rate), 'minimal' (play + scrubber), 'none' (an empty bar for the <:controls> block to fill). Four named steps rather than nine booleans — anything finer is @chrome='none' plus the block."
+          @onInput={{this.setChrome}}
+        />
+        <Args.Bool
+          @name='autoHide'
+          @value={{this.autoHide}}
+          @defaultValue={{false}}
+          @description="Let the controls fade during playback. Media Chrome's own default is ON; Pretui inverts it, because a focusable invisible control is worse than no control. When you do opt in, focus brings the bar straight back — an outer-tree rule beats the shadow root's ::slotted() rules on a slotted child, so no !important and no :deep() is involved."
+          @onInput={{this.setAutoHide}}
+        />
+        <Args.Object
+          @name='tracks'
+          @value={{this.tracks}}
+          @description='Text tracks: { src, label, srclang, kind?, isDefault? }[]. `isDefault` rather than `default` because the boolean must bind as a property, not a string. Captions and subtitles get a captions button; descriptions and chapters ride along for the browser. No tracks ⇒ no captions button at all, rather than a dead one.'
+        />
+        <Args.Object
+          @name='transcript'
+          @value={{this.transcript}}
+          @description='{ start, end, text, speaker? }[] — a real, seekable transcript, rendered in a native <details>. Click any line to seek. The cue holding the playhead carries aria-current plus a weight change and an inline-start rule, so it survives greyscale. Supplying a transcript is also what subscribes the player to `timeupdate`; with no transcript there is nothing on screen that moves with the playhead, so nothing subscribes.'
+        />
+        <Args.Bool
+          @name='transcriptOpen'
+          @value={{this.transcriptOpen}}
+          @defaultValue={{false}}
+          @description='Open the transcript disclosure on first paint.'
+          @onInput={{this.setTranscriptOpen}}
+        />
+        <Args.Bool
+          @name='captionsDefault'
+          @value={{this.captionsDefault}}
+          @defaultValue={{false}}
+          @description='Turn on the first subtitles track without the reader asking. Off by default: captions are a reader preference, and Media Chrome already remembers the last choice.'
+          @onInput={{this.setCaptionsDefault}}
+        />
+        <Args.Number
+          @name='seekOffset'
+          @value={{this.seekOffset}}
+          @defaultValue={{10}}
+          @min={{1}}
+          @max={{60}}
+          @description='Seconds for the skip buttons and the ←/→ hotkeys. Seek by PAGE needs no argument: focus the scrubber and PageUp/PageDown move by a large step, because it is a native <input type=range> underneath.'
+          @onInput={{this.setSeekOffset}}
+        />
+        <Args.Bool
+          @name='quietStatus'
+          @value={{this.quietStatus}}
+          @defaultValue={{false}}
+          @description='Hide the status line under the transport. That line is the TEXT channel for buffering, ended and error — state is never colour alone here — so silence it only when the host shows the same thing elsewhere. The polite live region is separate and always present; it speaks only on failure.'
+          @onInput={{this.setQuietStatus}}
+        />
+        <Args.String
+          @name='poster'
+          @description='Poster image for video. Together with @aspectRatio it is what makes the reserved space useful rather than merely blank.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='aspectRatio'
+          @defaultValue='16 / 9'
+          @description='CSS aspect-ratio for the stage, reserved from the first paint so nothing reflows when the poster resolves. Filtered to digits, dot, slash and space before it reaches the custom property.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='thumbnails'
+          @description='URL of a WebVTT thumbnails track (video only). Present ⇒ the scrubber shows a preview image while seeking.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='crossOrigin'
+          @description="'anonymous' | 'use-credentials'. Cross-origin <track> files need this or the browser drops them silently."
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='preload'
+          @defaultValue='metadata'
+          @description="'none' | 'metadata' | 'auto'. There is no @autoplay arg, and there will not be one."
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onSnapshot'
+          @description='(snapshot) => void on every media event: { phase, currentTime, duration, errorMessage }. Event-driven, never polled — no rAF loop and no timer anywhere in this component. The readout under the player is this callback.'
+        />
+        <Args.Yield
+          @name='overlay'
+          @description='Floats over the picture, top-left — a live pill, a rights badge. Pointer-transparent by default so it never steals a click; set pointer-events: auto on your own control.'
+        />
+        <Args.Yield
+          @name='controls'
+          @description="Appended INSIDE the control bar, just before fullscreen. Combine with @chrome='none' to own the bar completely."
+        />
+        <Args.Yield
+          @name='footer'
+          @description='Under the transport, above the transcript.'
+        />
+      </:api>
+
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-media-aspect'
+          @type='ratio'
+          @description='The reserved stage ratio. Set through @aspectRatio; restyle here when a wrapper wants to override.'
+        />
+        <Css.Basic
+          @name='pretui-media-ink'
+          @type='color'
+          @description='The transport ink. Defaults to --card over a picture and --foreground in audio mode, which is the whole of the light/dark story — there is no dark branch in this component.'
+        />
+        <Css.Basic
+          @name='pretui-media-scrim'
+          @type='color'
+          @description='The gradient under the video transport, so the controls stay legible over a bright frame.'
+        />
+        <Css.Basic
+          @name='pretui-media-radius'
+          @type='length'
+          @description='Corner radius of the stage.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+
+    <style scoped>
+      .mp-readout {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        margin: 10px 0 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .mp-readoutLabel {
+        font-family: var(--font-mono);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_MEDIA_PLAYER: Record<string, unknown> = {
+  MediaPlayer: MediaPlayerUsage,
+};

package/bundled-realms/pretui/components/media-viewer.gts

@@ -0,0 +1,136 @@
+// Pretui — MediaViewer: one entry point for any asset, routed to the adapter that claims its kind.
+//
+//   <MediaViewer @asset={{asset}} />
+//     ├─ video → VideoPlayer
+//     ├─ audio → AudioPlayer
+//     ├─ image → ImageFrame
+//     └─ anything else → an honest, named fallback
+//
+// The point of this file is NOT the two players it happens to route to. It
+// is that kind detection and adapter selection live HERE, once, so that the
+// next kind — model, PDF, SVG, font, CAD — is a registration rather than a
+// rewrite, and no caller ever has to know what it is holding.
+//
+// Three decisions worth stating, because they are what make it an adapter
+// shell rather than a switch statement:
+//
+//   1. **Kind detection is data, in one place.** An explicit `kind` wins;
+//      then the MIME type (including the one inside a `data:` URL); then the
+//      extension, through a table. A caller never sniffs.
+//   2. **The registry is open and last-write-wins.** `registerMediaAdapter`
+//      unshifts, so a consumer that registers `image` after this module
+//      loads overrides the built-in without patching it. Adapters are
+//      matched by predicate, not by kind, so an adapter can claim a subset
+//      ("images under 2 MP", "audio with a transcript").
+//   3. **The fallback names the gap.** An unrouted asset does not render a
+//      blank box; it renders what kind it is, what would handle it, and a
+//      link to open the file when that link is safe. A kind with no adapter
+//      registered says so out loud rather than failing silently.
+//
+// BETTER THAN THE INSPIRATION: every DAM viewer surveyed picks its viewer
+// with an if-chain inside the gallery component, which is why adding a kind
+// means editing the gallery. Here the gallery knows nothing.
+import Component from '@glimmer/component';
+import { EmptyState } from './empty-state';
+import { adapterFor, resolveAsset, safeHref } from '../internal/media-viewer';
+import type { MediaAdapter, MediaAssetSpec, ResolvedMediaAsset } from '../internal/media-viewer';
+
+// What the fallback says it is waiting for. Naming the intended component
+// is Law 7's "unfinished edges are named in the docs rather than hidden",
+// moved from the docs into the UI where it is actually read.
+const PLANNED: Readonly<Record<string, string>> = {
+  model: 'ModelViewer, on @google/model-viewer — not vendored yet.',
+  unknown: 'No adapter claims this kind.',
+};
+
+// ── MediaViewer ──────────────────────────────────────────────────────────
+
+export interface MediaViewerSignature {
+  Args: {
+    /** The asset to show. Kind detection happens here. */
+    asset: MediaAssetSpec;
+  };
+  Blocks: {
+    /** Replaces the built-in fallback for an unrouted asset. */
+    unsupported: [];
+  };
+  Element: HTMLDivElement;
+}
+
+export class MediaViewer extends Component<MediaViewerSignature> {
+  get asset(): ResolvedMediaAsset {
+    return resolveAsset(this.args.asset);
+  }
+  get adapter(): MediaAdapter | undefined {
+    return adapterFor(this.asset);
+  }
+  get adapterId(): string {
+    return this.adapter?.id ?? 'unsupported';
+  }
+  get fallbackTitle(): string {
+    return `Nothing here opens ${this.asset.kind === 'unknown' ? 'this file' : `${this.asset.kind} assets`} yet`;
+  }
+  get openHref(): string | undefined {
+    return safeHref(this.asset.src);
+  }
+  get fallbackMessage(): string {
+    return (
+      PLANNED[this.asset.kind] ??
+      'No adapter claims this kind. Register one with registerMediaAdapter.'
+    );
+  }
+
+  <template>
+    <div
+      class='pretui-mviewer'
+      data-adapter={{this.adapterId}}
+      data-kind={{this.asset.kind}}
+      data-test-pretui-media-viewer
+      ...attributes
+    >
+      {{#if this.adapter}}
+        {{#let this.adapter.component as |Adapter|}}
+          <Adapter @asset={{this.asset}} />
+        {{/let}}
+      {{else if (has-block 'unsupported')}}
+        {{yield to='unsupported'}}
+      {{else}}
+        <EmptyState @title={{this.fallbackTitle}} @texture={{false}}>
+          <:default>
+            {{this.fallbackMessage}}
+          </:default>
+          <:action>
+            {{#if this.openHref}}
+              <a
+                class='pretui-mviewer-link'
+                href={{this.openHref}}
+                target='_blank'
+                rel='noopener noreferrer'
+              >Open {{this.asset.label}} in a new tab</a>
+            {{/if}}
+          </:action>
+        </EmptyState>
+      {{/if}}
+    </div>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-mviewer {
+          display: block;
+          min-width: 0;
+        }
+        .pretui-mviewer-link {
+          font-size: var(--text-ui-sm, 11.5px);
+          font-weight: 600;
+          color: var(--pretui-primary-ink, var(--boxel-highlight-hover));
+          text-underline-offset: 3px;
+        }
+        .pretui-mviewer-link:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 3px;
+          border-radius: 3px;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/media-viewer.md

@@ -0,0 +1,47 @@
+## What it is
+
+One shell that picks a viewer for an asset. You hand it a `MediaAssetSpec` — a `src` plus whatever else you know — and it decides the kind, finds the adapter that claims it, and renders that. Four kinds are modelled: image, video, audio, model.
+
+Use it whenever the kind is a property of the data rather than a decision you are making. When you already know it is a video, **VideoPlayer** is more direct. **AssetGrid** and **Gallery** compose this rather than routing themselves.
+
+## The contract
+
+```
+@asset (required) — a MediaAssetSpec: src, plus optional kind, mimeType,
+                    name, alt, width, height, meta
+<:unsupported>    — replaces the built-in fallback for an unrouted asset
+```
+
+**Kind detection is data, in one place, and never a sniff.** An explicit `kind` wins; then the MIME type, including the one inside a `data:` URL; then the file extension through a table. No `HEAD` request — that would be a lie in a realm anyway, where every asset sits behind header auth — and no byte sniffing. The result is deterministic and works offline, which matters because half this kit's media examples are data URLs.
+
+**The registry is open and last-write-wins.** `registerMediaAdapter` unshifts, so a consumer that registers an `image` adapter after this module loads overrides the built-in without patching or forking it. Adapters are matched by **predicate, not by kind**, so one can claim a subset — "images under 2 MP", "audio with a transcript" — rather than a whole category.
+
+**Resolution fills the gaps before an adapter sees the asset.** `resolveAsset` derives the kind, a `label` (the caller's `name`, else the basename of the URL, else "Untitled asset" for a data URL), and an `aspectRatio` string when both dimensions are known. Adapters therefore take a `ResolvedMediaAsset` and never repeat that work.
+
+**The fallback names the gap rather than rendering a blank box.** An unrouted asset gets an empty state saying what kind it is, what would handle it, and a link to open the file in a new tab with `rel='noopener noreferrer'`.
+
+## Prior art
+
+A kit addition, and the comparison is against how digital-asset managers actually do this: an if-chain inside the gallery component picking a viewer. That is why adding a kind means editing the gallery in every one of them.
+
+Where Pretui is better: **the gallery knows nothing.** Routing lives in one registry, a new kind is a registration rather than an edit, and an adapter can be overridden from outside the module. The fallback being informative rather than blank is the other half — an unsupported asset is a normal condition in a real library, not an error case.
+
+Where it is thinner, and one of these is a live inconsistency: **`ModelViewer` ships but is not routed here by default.** It registers through an explicit `installModelAdapter()` call, deliberately — the engine costs 292 KB gzipped and importing a component must not silently change how every other viewer in the process behaves — but the fallback message for a model asset still reads "not vendored yet", which is now stale copy rather than a true statement. A host that wants 3D has to call the installer and will not learn that from the message it sees.
+
+Beyond that: there is no loading or error state at the shell level (each adapter owns its own), no size or fit contract shared across adapters, and no way to ask the shell which adapter _would_ run without rendering it, other than the exported `adapterFor`.
+
+## Accessibility
+
+- **The shell itself is a plain `<div>` with no role and no name**, which is correct: it is a router, and the adapter it renders owns the semantics. An `ImageFrame` carries the alt text, a `MediaPlayer` carries the region and its label.
+- **The fallback is the one part with its own semantics**, and it is text plus a real link rather than a grey box — so an unrouted asset is still reachable, still named, and still openable by keyboard.
+- **The fallback link opens a new tab** with `rel='noopener noreferrer'`. It is announced as a link to the asset by its resolved label, so "Open quarterly-review.glb in a new tab" rather than "click here".
+- **`<:unsupported>` replaces that fallback entirely**, which means a caller who overrides it inherits the responsibility for naming the asset and offering a way to reach it.
+- **Nothing about kind is conveyed by colour** at this level; the `data-kind` and `data-adapter` attributes are for styling and tests, not for meaning.
+
+## Theming
+
+The shell has almost no surface of its own: `--text-ui-sm` and `--pretui-primary-ink` for the fallback link, and `--pretui-shadow-hairline` shared with the adapters in this module.
+
+That is deliberate. Everything visible comes from the adapter that ran, so a theme retunes **MediaPlayer**, **ImageFrame** and the rest, and the shell inherits whatever they became. A viewer that themed independently of its adapters would be a viewer that looks different depending on what you put in it.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/media-viewer.usage.gts

@@ -0,0 +1,70 @@
+// Pretui — MediaViewer usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { MediaViewer } from './media-viewer';
+import type { MediaAssetSpec } from '../internal/media-viewer';
+import { SAMPLE_ASSETS } from '../media-examples';
+
+// ── MediaViewer ──────────────────────────────────────────────────────────
+class MediaViewerUsage extends Component {
+  assets = SAMPLE_ASSETS;
+  names: string[] = SAMPLE_ASSETS.map((asset) => asset.name ?? asset.src);
+
+  @tracked choice = SAMPLE_ASSETS[0].name ?? '';
+
+  setChoice = (v: string) => (this.choice = v);
+
+  get asset(): MediaAssetSpec {
+    return (
+      SAMPLE_ASSETS.find((candidate) => candidate.name === this.choice) ??
+      SAMPLE_ASSETS[0]
+    );
+  }
+  get usage(): string {
+    return '<MediaViewer @asset={{this.asset}} />';
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='MediaViewer'
+      @description="The adapter shell: one signature, N adapters, selected by asset kind. Pick a different asset and a different viewer runs — image, audio, video — without the caller knowing what it is holding. Then pick the .glb and read the fallback: it names the kind, names the component that would open it, and offers the file. That is the point of the shell. Kind detection is data in one place (explicit kind, then MIME type — including the one inside a data: URL — then an extension table), and the registry is open and last-write-wins, so a consumer overrides a built-in by registering after this module loads. Adding PDF, SVG, font or CAD later is a registration, not a rewrite."
+      @source={{this.usage}}
+    >
+      <:example>
+        <MediaViewer @asset={{this.asset}} />
+      </:example>
+
+      <:api as |Args|>
+        <Args.String
+          @name='asset (demo knob)'
+          @value={{this.choice}}
+          @options={{this.names}}
+          @description='The asset handed to the shell. Eight assets across four kinds, one of which (model/gltf-binary) deliberately has no adapter yet.'
+          @onInput={{this.setChoice}}
+        />
+        <Args.Object
+          @name='asset'
+          @value={{this.asset}}
+          @description='{ src, name?, kind?, mimeType?, poster?, thumbnail?, alt?, tracks?, transcript?, width?, height?, duration?, bytes?, meta? }. Only src is required. The shell resolves it once — kind, display label and aspect ratio — and hands the RESOLVED asset to the adapter, so no adapter re-derives any of it.'
+        />
+        <Args.Yield
+          @name='unsupported'
+          @description='Replaces the built-in fallback for an unrouted asset. The built-in is deliberately loud: silence here is how a gallery ends up showing a blank box for a file type nobody noticed was missing.'
+        />
+        <Args.Base
+          @name='registerMediaAdapter(adapter)'
+          @description='{ id, label, handles(asset), component }. Unshifts, so the most recently registered adapter that claims an asset wins. Matching is by predicate rather than by kind, so an adapter can claim a subset — "images over 20 MP", "audio that has a transcript". mediaAdapters() lists them; adapterFor(asset) resolves one.'
+        />
+        <Args.Base
+          @name='kindForAsset(asset)'
+          @description="Exported. 'image' | 'video' | 'audio' | 'model' | 'unknown'. Deterministic and offline — no HEAD request, which would be a lie in a realm where every asset sits behind header auth."
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_MEDIA_VIEWER: Record<string, unknown> = {
+  MediaViewer: MediaViewerUsage,
+};