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

package/bundled-realms/pretui/components/asset-well.md

@@ -0,0 +1,72 @@
+## What it is
+
+One asset, one slot: the drop zone and preview for a single file. Five states — empty, drag-over, in-flight, filled, failed — over a real `<input type='file'>`, so the pointer gesture and the keyboard path are the same control rather than two.
+
+Use it for a card's image, an avatar, an attachment. For many assets, that is **AssetGrid**; for a curated set with a hero, **Gallery**.
+
+## The contract
+
+```
+@asset?, @defaultAsset?, @onAssetChange? — controlled / uncontrolled slot;
+                        null means "deliberately empty"
+@onSelect?     — THE event: fires with the accepted File, before any preview exists
+@onReject?     — fires with everything that failed screening, one reason each
+@onRemove?     — fires when the reader clears the slot
+@onRetry?      — fires from the failure state's retry button
+@onCancel?     — fires from the in-flight state's cancel button
+@uploading?, @uploadFraction?, @errorMessage? — the state levers
+@accept?       — an <input accept> list, enforced on BOTH the picker and the drop
+@maxSize?      — largest acceptable file, in bytes
+@label?, @hint? — the empty invitation's two lines
+@ratio?        — reserved preview ratio; defaults to the asset's own, then 4 / 3
+@icon?         — icon-registry name for the empty glyph. Default 'ImagePlaceholder'
+@disabled?     — dimmed and inert; drops are ignored
+@viewOnly?     — preview only, nothing that mutates
+@altLabel?     — offer an alt-text line under the preview
+
+<:preview> replaces the preview; receives the resolved asset
+<:empty>   replaces the invitation's copy — but NOT the browse button
+<:actions> extra controls beside Remove
+```
+
+**Upload is yours; the well never does it.** `@onSelect` fires with the accepted `File` before any preview exists, which is the moment to start uploading. The well then reflects what you tell it through `@uploading`, `@uploadFraction` and `@errorMessage`.
+
+**Four states resolve from three arguments in a fixed precedence**: failure beats in-flight, in-flight beats filled, filled beats empty. That ordering is the contract — a well that is both uploading and holding an old asset shows the upload.
+
+**Omit `@uploadFraction` while uploading and you get an indeterminate spinner.** A fake percentage is a lie with a progress bar around it.
+
+**Retry and cancel exist only when they can work.** No `@onRetry`, no retry button — an affordance that does nothing is worse than none.
+
+**`@accept` and `@maxSize` are enforced on both paths.** A rule applied to the picker but not to the drop is a rule that will be discovered by a user rather than by a developer.
+
+**A real file input sits behind the zone in every state**, and the browse button is a real `<button>` whose wording follows the state. That is why `<:empty>` replaces the copy but not the button: the button is the keyboard path and cannot be designed away.
+
+**The preview routes through MediaViewer** rather than assuming an `<img>`, so a well holding a video or an audio file previews correctly.
+
+## Prior art
+
+**boxel-catalog's image-source-editor** is the source, with **React Aria's FileTrigger** as the reference for the input-behind-the-zone pattern.
+
+Where Pretui is better, and the first one is a bug fix rather than a feature: **the catalog source hardcoded `alt=''`, which made every image it produced permanently undescribable.** `@altLabel` is the fix, and it is opt-in rather than always-on only because some slots really are decorative. Beyond that: five states rather than two, rejection reported with a reason per file rather than a silent refusal, and screening applied to the drop as well as the picker.
+
+Where it is thinner: no crop or focal-point step after a pick (**ImageCropper** is a separate component and the two do not compose today), no multi-file mode — by design, but it means a caller wanting two slots renders two wells and coordinates them — no paste-from-clipboard, and no resumable or chunked upload contract beyond cancel and retry.
+
+## Accessibility
+
+- **The file input is real and present in every state**, so the control is reachable and operable by keyboard without any custom key handling.
+- **The browse button is a real button whose label follows the state**, so a screen-reader user is told whether they are adding or replacing.
+- **The failure carries a word and a role, not a colour.** The reason is text on the screen rather than a red border, which is the difference between a recoverable error and a mysterious one.
+- **Remove announces itself**, reports `null` through `@onAssetChange`, and calls `@onRemove` — the state change is perceivable rather than silent.
+- **`@viewOnly` keeps the preview and drops every mutation**, so a read-only slot has no focusable controls that lead nowhere.
+- **`@altLabel` is the accessibility affordance that matters most here**, because it is what stops the asset from being undescribable downstream. Offer it whenever the image carries meaning.
+- **The empty state's glyph is `aria-hidden`**; the invitation's text carries the meaning.
+
+## Theming
+
+`--pretui-well-aspect` (the reserved preview ratio), `--pretui-well-glyph-size`, `--pretui-well-transition`, plus the `--pretui-well-*` family for the state surfaces, `--pretui-on-neutral` and `--pretui-shadow-hairline`.
+
+Reserving the ratio before the bytes arrive is why a card holding a well never reflows when its image loads — the same rule **ImageFrame** and **MediaPlayer** follow, and the reason all three take a ratio rather than inferring one late.
+
+A theme retunes the five state surfaces through the `--pretui-well-*` tokens together, which keeps the empty, hover, in-flight, filled and failed states reading as one control changing rather than five different components.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/asset-well.usage.gts

@@ -0,0 +1,264 @@
+// Pretui — AssetWell usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { AssetWell } from './asset-well';
+import type { MediaAssetSpec } from '../internal/media-viewer';
+import type { FileRejection } from '../internal/file-intake';
+import { platePoster } from '../media-examples';
+import { Token } from './token';
+
+// ── AssetWell ────────────────────────────────────────────────────────────
+const WELL_ASSET: MediaAssetSpec = {
+  src: platePoster('Chest 118, front', '1600 / 1067'),
+  name: 'chest-118-front.svg',
+  kind: 'image',
+  mimeType: 'image/svg+xml',
+  alt: 'Chest 118 photographed square-on before grading',
+  width: 1600,
+  height: 1067,
+  bytes: 184_320,
+};
+
+class AssetWellUsage extends Component {
+  @tracked filled = true;
+  @tracked uploading = false;
+  @tracked fraction = 0.42;
+  @tracked determinate = true;
+  @tracked failure = '';
+  @tracked viewOnly = false;
+  @tracked ratio = '3 / 2';
+  @tracked lastEvent = '—';
+
+  get asset(): MediaAssetSpec | null {
+    return this.filled ? WELL_ASSET : null;
+  }
+  get uploadFraction(): number | undefined {
+    return this.determinate ? this.fraction : undefined;
+  }
+
+  setFilled = (v: boolean) => (this.filled = v);
+  setUploading = (v: boolean) => (this.uploading = v);
+  setDeterminate = (v: boolean) => (this.determinate = v);
+  setFraction = (v: number | null) => (this.fraction = v ?? 0);
+  setFailure = (v: string) => (this.failure = v);
+  setViewOnly = (v: boolean) => (this.viewOnly = v);
+  setRatio = (v: string) => (this.ratio = v);
+
+  noteSelect = (file: File) => {
+    this.lastEvent = `onSelect: ${file.name} (${file.size} bytes)`;
+  };
+  noteReject = (rejections: FileRejection[]) => {
+    this.lastEvent = `onReject: ${rejections.length} file(s) turned away`;
+  };
+  noteRemove = () => {
+    this.filled = false;
+    this.lastEvent = 'onRemove';
+  };
+  noteRetry = () => {
+    this.failure = '';
+    this.lastEvent = 'onRetry — failure cleared';
+  };
+  noteCancel = () => {
+    this.uploading = false;
+    this.lastEvent = 'onCancel — upload stopped';
+  };
+
+  get usage(): string {
+    return [
+      '<AssetWell',
+      '  @asset={{this.asset}}',
+      "  @accept='image/*'",
+      '  @maxSize={{5242880}}',
+      "  @ratio='3 / 2'",
+      "  @label='Drop the plate photograph here'",
+      '  @uploading={{this.uploading}}',
+      '  @uploadFraction={{this.fraction}}',
+      '  @errorMessage={{this.failure}}',
+      '  @onSelect={{this.upload}}',
+      '  @onRemove={{this.clear}}',
+      '  @onRetry={{this.upload}}',
+      '/>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='AssetWell'
+      @description="One asset, one slot, five states — empty, drag-over, in-flight, filled, failed — over a Dropzone that is the root in every one of them. That single composition decision is what makes the keyboard path structural rather than optional: Dropzone renders a FileTrigger, FileTrigger encapsulates a real file input, and neither can be designed away by a caller replacing the body. It also means dragging a file onto a FILLED well replaces it, which the catalog source could not do, and that accept lists and size limits are enforced identically on the drop path and the picker path because it is literally the same screening code. Drive the four states from the rail; nothing reflows between them because the preview's aspect ratio is reserved before any bytes arrive."
+      @source={{this.usage}}
+    >
+      <:example>
+        <AssetWell
+          @asset={{this.asset}}
+          @accept='image/*'
+          @maxSize={{5242880}}
+          @ratio={{this.ratio}}
+          @label='Drop the plate photograph here'
+          @hint='PNG, JPEG or SVG, up to 5 MB'
+          @altLabel='Alt text'
+          @uploading={{this.uploading}}
+          @uploadFraction={{this.uploadFraction}}
+          @errorMessage={{this.failure}}
+          @viewOnly={{this.viewOnly}}
+          @onSelect={{this.noteSelect}}
+          @onReject={{this.noteReject}}
+          @onRemove={{this.noteRemove}}
+          @onRetry={{this.noteRetry}}
+          @onCancel={{this.noteCancel}}
+        />
+        <p class='dml-readout'>
+          <span class='dml-readoutLabel'>last event</span>
+          <Token @value={{this.lastEvent}} />
+        </p>
+      </:example>
+
+      <:api as |Args|>
+        <Args.Object
+          @name='asset'
+          @description='Controlled asset (a MediaAssetSpec). Omit the arg entirely for the uncontrolled case, where a dropped file becomes a local preview through an object URL the component owns and revokes — on replace, and again in willDestroy. A controlled well never invents an asset, because inventing a blob URL the caller cannot see is a resource it can never free.'
+          @value={{this.asset}}
+        />
+        <Args.Bool
+          @name='(demo) filled'
+          @value={{this.filled}}
+          @defaultValue={{true}}
+          @description='Not an argument — the demo toggling whether the asset arg is a spec or null.'
+          @onInput={{this.setFilled}}
+        />
+        <Args.Bool
+          @name='uploading'
+          @value={{this.uploading}}
+          @defaultValue={{false}}
+          @description='Puts the well in its in-flight state. The zone goes inert while it is set: a second drop mid-upload is a race nobody asked for.'
+          @onInput={{this.setUploading}}
+        />
+        <Args.Bool
+          @name='(demo) determinate'
+          @value={{this.determinate}}
+          @defaultValue={{true}}
+          @description='Not an argument — whether the demo passes uploadFraction at all. Off means the fraction is undefined and the well shows an indeterminate spinner, which is the honest answer when the transport reports no progress. A fake percentage is a lie with a progress bar around it.'
+          @onInput={{this.setDeterminate}}
+        />
+        <Args.Number
+          @name='uploadFraction'
+          @value={{this.fraction}}
+          @min={{0}}
+          @max={{1}}
+          @step={{0.01}}
+          @description='Completed fraction, 0–1. Omit while uploading for the indeterminate spinner.'
+          @onInput={{this.setFraction}}
+        />
+        <Args.String
+          @name='errorMessage'
+          @value={{this.failure}}
+          @description='Non-empty puts the well in its failure state and is the text shown. The failure channel is a glyph AND a word AND a role — never a colour, which is the one thing the source had no answer for.'
+          @onInput={{this.setFailure}}
+        />
+        <Args.String
+          @name='ratio'
+          @value={{this.ratio}}
+          @description="Aspect ratio reserved for the preview — '16 / 9', '1 / 1'. Defaults to the asset's own, then 4 / 3. Reserving it before the bytes land is why nothing on the card reflows. The value goes through the shared cssValue guard, so a caller string can never inject declarations into a style attribute."
+          @onInput={{this.setRatio}}
+        />
+        <Args.Bool
+          @name='viewOnly'
+          @value={{this.viewOnly}}
+          @defaultValue={{false}}
+          @description='Show the preview and nothing that mutates — no replace, no remove.'
+          @onInput={{this.setViewOnly}}
+        />
+        <Args.String
+          @name='accept'
+          @value='image/*'
+          @description='An input accept list. Enforced on BOTH the picker and the drop, by the same code, with the same wording in the same live region.'
+          @hideControls={{true}}
+        />
+        <Args.Number
+          @name='maxSize'
+          @value={{5242880}}
+          @description='Largest acceptable file, in bytes. Anything over it lands on onReject with a reason.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='altLabel'
+          @description="Offer an alt-text line under the preview. Opt-in because some slots really are decorative — but the source hardcoded alt='' with no alt field anywhere on its model, which made every image it ever held permanently undescribable."
+          @value='Alt text'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onSelect'
+          @description='(file) — THE event. Fires with the accepted file from a drop or a pick, before any preview exists. Upload from here.'
+        />
+        <Args.Action
+          @name='onAssetChange'
+          @description="(asset | null) whenever the well's own asset changes: on adopt in the uncontrolled case, on remove in both."
+        />
+        <Args.Action
+          @name='onReject'
+          @description='(rejections) — everything that failed screening, one reason each.'
+        />
+        <Args.Action
+          @name='onRemove'
+          @description='() when the reader clears the slot.'
+        />
+        <Args.Action
+          @name='onRetry'
+          @description='() from the failure state. Omit it and no retry button is offered at all — an affordance that does nothing is worse than none.'
+        />
+        <Args.Action
+          @name='onCancel'
+          @description='() from the in-flight state, on the same terms.'
+        />
+        <Args.Yield
+          @name='preview'
+          @description='Replaces the preview entirely; receives the resolved asset.'
+        />
+        <Args.Yield
+          @name='empty'
+          @description="Replaces the invitation's copy. The browse button is NOT part of this block — it is the keyboard path."
+        />
+        <Args.Yield
+          @name='actions'
+          @description='Extra controls beside Remove in the filled state.'
+        />
+      </:api>
+
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-well-aspect'
+          @type='ratio'
+          @description='Reserved preview ratio. Set through @ratio; exposed so a theme can floor it.'
+        />
+        <Css.Basic
+          @name='pretui-well-glyph-size'
+          @type='dimension'
+          @description="Size of the empty state's icon."
+        />
+        <Css.Basic
+          @name='pretui-well-transition'
+          @type='duration'
+          @description='Fade of the preview tools. Zeroed under prefers-reduced-motion.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+
+    <style scoped>
+      .dml-readout {
+        display: flex;
+        align-items: center;
+        gap: var(--space-2, 6px);
+        margin: var(--space-3, 8px) 0 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .dml-readoutLabel {
+        font-weight: var(--weight-medium, 500);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_ASSET_WELL: Record<string, unknown> = {
+  AssetWell: AssetWellUsage,
+};

package/bundled-realms/pretui/components/audio-player.gts

@@ -0,0 +1,152 @@
+// Pretui — AudioPlayer: MediaPlayer skinned for audio, with cover art, title and artist.
+import Component from '@glimmer/component';
+import { MediaPlayer } from './media-player';
+import type { MediaPlayerSignature } from './media-player';
+
+// ── AudioPlayer ──────────────────────────────────────────────────────────
+//
+// A skin, in the Tag-wraps-Pill idiom: it curries `@kind='audio'` and adds
+// the one thing an audio track needs that a video does not — a face. Cover
+// art, title and artist are args with slot escape hatches, per Law 7.
+
+export interface AudioPlayerSignature {
+  Args: Omit<
+    MediaPlayerSignature['Args'],
+    'kind' | 'poster' | 'placeholder' | 'thumbnails' | 'aspectRatio'
+  > & {
+    /** Cover art URL. */
+    cover?: string;
+    /** Alt text for the cover. Empty (the default) marks it decorative,
+     * which is right when the title beside it says the same thing. */
+    coverAlt?: string;
+    /** Track title. */
+    title?: string;
+    /** Artist, show, or byline. */
+    artist?: string;
+  };
+  Blocks: {
+    /** Replaces the cover art entirely. */
+    art: [];
+    /** Replaces the title/artist stack. */
+    meta: [];
+    /** Forwarded to MediaPlayer's control-bar slot. */
+    controls: [];
+    /** Forwarded to MediaPlayer's footer. */
+    footer: [];
+  };
+  Element: HTMLDivElement;
+}
+
+export class AudioPlayer extends Component<AudioPlayerSignature> {
+  get label(): string {
+    return this.args.label ?? this.args.title ?? 'Audio';
+  }
+  get coverAlt(): string {
+    return this.args.coverAlt ?? '';
+  }
+
+  <template>
+    <div class='pretui-audio' data-test-pretui-audio-player ...attributes>
+      <div class='pretui-audio-head'>
+        <div class='pretui-audio-art'>
+          {{#if @cover}}
+            <img src={{@cover}} alt={{this.coverAlt}} loading='lazy' />
+          {{/if}}{{yield to='art'}}
+        </div>
+        <div class='pretui-audio-meta'>
+          {{#if @title}}
+            <span class='pretui-audio-title'>{{@title}}</span>
+          {{/if}}
+          {{#if @artist}}
+            <span class='pretui-audio-artist'>{{@artist}}</span>
+          {{/if}}{{yield to='meta'}}
+        </div>
+      </div>
+      <MediaPlayer
+        @kind='audio'
+        @src={{@src}}
+        @label={{this.label}}
+        @tracks={{@tracks}}
+        @transcript={{@transcript}}
+        @transcriptOpen={{@transcriptOpen}}
+        @captionsDefault={{@captionsDefault}}
+        @chrome={{@chrome}}
+        @seekOffset={{@seekOffset}}
+        @autoHide={{@autoHide}}
+        @loop={{@loop}}
+        @muted={{@muted}}
+        @preload={{@preload}}
+        @crossOrigin={{@crossOrigin}}
+        @quietStatus={{@quietStatus}}
+        @onSnapshot={{@onSnapshot}}
+      >
+        <:controls>{{yield to='controls'}}</:controls>
+        <:footer>{{yield to='footer'}}</:footer>
+      </MediaPlayer>
+    </div>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-audio {
+          display: flex;
+          flex-direction: column;
+          gap: 10px;
+          min-width: 0;
+        }
+        .pretui-audio-head {
+          display: flex;
+          align-items: center;
+          gap: 12px;
+          min-width: 0;
+        }
+        .pretui-audio-art {
+          flex: 0 0 auto;
+          width: 52px;
+          aspect-ratio: 1;
+          border-radius: var(--radius-sm, 6px);
+          overflow: hidden;
+          background: color-mix(
+            in oklch,
+            var(--foreground) 8%,
+            var(--card)
+          );
+          box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
+        }
+        .pretui-audio-art:empty {
+          display: none;
+        }
+        .pretui-audio-art img {
+          width: 100%;
+          height: 100%;
+          object-fit: cover;
+          display: block;
+        }
+        .pretui-audio-meta {
+          display: flex;
+          flex-direction: column;
+          gap: 1px;
+          min-width: 0;
+        }
+        .pretui-audio-meta:empty {
+          display: none;
+        }
+        .pretui-audio-title {
+          font-size: var(--text-body, 14px);
+          font-weight: 600;
+          letter-spacing: -0.01em;
+          color: var(--foreground);
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+        .pretui-audio-artist {
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,51 @@
+## What it is
+
+The audio skin over **MediaPlayer**: cover art, title and artist beside a compact transport laid out in normal flow rather than over a picture.
+
+Like **VideoPlayer** it is a skin, not a rewrite — the transport, the transcript, the status line and the keyboard contract are all the base component's. Use it for a single track. There is no playlist here; a queue is the caller's to build around it.
+
+## The contract
+
+```
+every MediaPlayer arg except kind, poster, placeholder, thumbnails and aspectRatio
+@cover?    — cover art URL
+@coverAlt? — alt text for the cover; empty by default, which marks it decorative
+@title?    — track title
+@artist?   — artist, show, or byline
+
+<:art>      replaces the cover art entirely
+<:meta>     replaces the title/artist stack
+<:controls> forwarded to MediaPlayer's control bar
+<:footer>   forwarded to MediaPlayer's footer
+```
+
+**Five of the base's args are omitted rather than ignored**: the kind is fixed to `'audio'`, and the poster, placeholder, thumbnails and aspect-ratio args have nothing to apply to when there is no picture. The type says so, so passing one is a compile error rather than a silent no-op.
+
+**`@title` is the fallback accessible name.** The label resolves as `@label`, then `@title`, then the literal `'Audio'` — so a player with a title is never nameless, and a player with neither is named honestly rather than not at all.
+
+**`@coverAlt` defaults to empty, marking the cover decorative.** That is right when the title beside it says the same thing, which is the common case; supply alt text only when the artwork carries meaning the text does not.
+
+**The cover is lazy-loaded.**
+
+## Prior art
+
+The upstream here is **MediaPlayer** itself — this is a skin rather than a port. Media Chrome underneath ships an audio layout; what it does not ship is the metadata block, and the cover/title/artist arrangement is the thing every product rebuilds.
+
+Where Pretui is better: the metadata stack is part of the component and replaceable through `<:art>` and `<:meta>`, so a caller who needs a different arrangement overrides a block instead of abandoning the component. And the transcript — genuinely more valuable for audio than for video, since there is no picture to read — comes from the base for free.
+
+Where it is thinner: no playlist, no queue, no chapter list, no waveform. **Waveform** is a separate component and the two do not compose today, which is the most obvious missing pairing in this category.
+
+## Accessibility
+
+- **The player is named even when the caller forgets**, through the `@label` → `@title` → `'Audio'` chain. That is weaker than a real label and better than an unnamed region.
+- **The cover is decorative by default.** An `alt` of empty string is a deliberate signal, not a missing attribute — it tells a screen reader to skip an image whose meaning is already in the title beside it. Overriding it matters when the artwork is the content.
+- **Audio has no picture, so the transcript carries more weight here.** Everything that would be conveyed visually in a video is conveyed by the transcript in audio, and it is the one thing worth supplying if you supply nothing else.
+- **The live region, the status line and the disclosure contract are MediaPlayer's**, unchanged.
+
+## Theming
+
+`--pretui-media-ink`, `--pretui-media-radius`, `--pretui-media-scrim`, `--pretui-destructive-ink`, `--pretui-shadow-card`, `--pretui-shadow-hairline` — all from **MediaPlayer**, which is the point: an audio player and a video player in the same theme are visibly the same family.
+
+The audio layout adds no tokens of its own. The cover size and the metadata stack's spacing are fixed, so a row of audio players aligns without per-instance tuning.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,118 @@
+// Pretui — AudioPlayer usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { AudioPlayer } from './audio-player';
+import type { MediaChrome } from './media-player';
+import {
+  SOURCING_TRACKS,
+  SOURCING_TRANSCRIPT,
+  TONE_ASSET,
+  TONE_WAV,
+} from '../media-examples';
+import { CHROMES } from '../demo-media';
+
+// ── AudioPlayer ──────────────────────────────────────────────────────────
+class AudioPlayerUsage extends Component {
+  chromes = CHROMES;
+  tracks = SOURCING_TRACKS;
+  transcript = SOURCING_TRANSCRIPT;
+  src = TONE_WAV;
+  cover = TONE_ASSET.thumbnail;
+
+  @tracked title = 'Lot B-1180 — desk note';
+  @tracked artist = 'Sourcing desk · Kandy line';
+  @tracked chrome = 'compact';
+
+  setTitle = (v: string) => (this.title = v);
+  setArtist = (v: string) => (this.artist = v);
+  setChrome = (v: string) => (this.chrome = v);
+
+  get chromeValue(): MediaChrome {
+    return this.chrome as MediaChrome;
+  }
+  get usage(): string {
+    return [
+      '<AudioPlayer',
+      '  @src={{this.src}}',
+      `  @title='${this.title}'`,
+      `  @artist='${this.artist}'`,
+      '  @cover={{this.cover}}',
+      '  @transcript={{this.transcript}}',
+      '/>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='AudioPlayer'
+      @description="A skin over MediaPlayer, in the wrap-and-curry idiom Law 10 names — it curries @kind='audio' and adds the one thing a track needs that a video does not: a face. Cover art, title and artist are args, each with a slot escape hatch, and everything else is forwarded untouched. That is the whole component; there is no second transport, no second theme and no second keyboard map to keep in sync."
+      @source={{this.usage}}
+    >
+      <:example>
+        <AudioPlayer
+          @src={{this.src}}
+          @title={{this.title}}
+          @artist={{this.artist}}
+          @cover={{this.cover}}
+          @chrome={{this.chromeValue}}
+          @tracks={{this.tracks}}
+          @transcript={{this.transcript}}
+        />
+      </:example>
+
+      <:api as |Args|>
+        <Args.String
+          @name='title'
+          @value={{this.title}}
+          @description='Track title. Also the default accessible name when @label is absent.'
+          @onInput={{this.setTitle}}
+        />
+        <Args.String
+          @name='artist'
+          @value={{this.artist}}
+          @description='Artist, show, or byline.'
+          @onInput={{this.setArtist}}
+        />
+        <Args.String
+          @name='cover'
+          @value={{this.cover}}
+          @description='Cover art URL. The plate on this page is a generated SVG, so the demo needs no network.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='coverAlt'
+          @defaultValue=''
+          @description='Alt text for the cover. Empty (the default) marks it decorative, which is right when the title beside it says the same thing — the alternative is a screen reader reading the album name twice.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='chrome'
+          @value={{this.chrome}}
+          @options={{this.chromes}}
+          @defaultValue='full'
+          @description='Forwarded to MediaPlayer.'
+          @onInput={{this.setChrome}}
+        />
+        <Args.Yield
+          @name='art'
+          @description='Replaces the cover art entirely — a canvas, a waveform, an avatar stack.'
+        />
+        <Args.Yield
+          @name='meta'
+          @description='Replaces the title/artist stack.'
+        />
+        <Args.Yield @name='controls' @description='Forwarded to the bar.' />
+        <Args.Yield @name='footer' @description='Forwarded to the footer.' />
+        <Args.Base
+          @name='everything else'
+          @description='src, label, tracks, transcript, transcriptOpen, captionsDefault, seekOffset, loop, muted, preload, crossOrigin, quietStatus and onSnapshot are all forwarded to MediaPlayer verbatim. The kind, poster and aspectRatio args are removed from the signature rather than ignored, because a skin that accepts an arg it cannot honour is a lie.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_AUDIO_PLAYER: Record<string, unknown> = {
+  AudioPlayer: AudioPlayerUsage,
+};