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

package/bundled-realms/pretui/components/hover-card.md

@@ -0,0 +1,72 @@
+## What it is
+
+A rich preview that opens on hover or focus: a person behind a mention, the card behind a reference, the definition behind a term. It sits between two neighbours. **Tooltip** is a short string and is never interactive. **Popover** opens on click and can hold a form. HoverCard opens without a click, holds real content with its own links, and must itself be hoverable so the pointer can travel into it — which is what makes it the hardest of the three to get right.
+
+Use it for a preview the reader might want and can live without. If the content is something they must see, it is not a preview: put it on the page, or behind a **Popover** they open on purpose.
+
+## The contract
+
+```
+@open? @defaultOpen? @onOpenChange?        — the overlay contract
+@placement? (default 'bottom-start') @distance? (8)
+@openDelay? (seconds, default 0.5)
+@closeDelay? (seconds, default 0.3)
+@label? (default 'Preview')                — the card's accessible name
+@tapToOpen? (default true)                 — a tap opens it on a coarse pointer
+<:trigger>                                 — the link or control being previewed
+<:default as |close|>                      — the card
+```
+
+**Delays are in seconds.** Radix passes `700`; a bare number in a prop is a unit no caller can check, so here `@openDelay={{0.7}}` says what it means. The pair matters more than either value: the open delay stops the card firing as the pointer crosses the link, and the close delay is the bridge across the gap between trigger and card. Set the close delay to zero and the card becomes unreachable by pointer no matter how good the open delay is.
+
+**Focus ignores the open delay.** A reader who deliberately tabbed to the trigger has already expressed the intent, so the card opens at once. Focus leaving the whole surface — trigger and card together — closes it at once too.
+
+**The trigger block owns the control.** The focusable element inside it is given `aria-expanded`, plus an `aria-controls` pointing at the card while the card is open, both removed on teardown. Wrap a link, a button, or a **RecordPill**; the trigger's own activation is untouched, so a link stays a link.
+
+**Touch has a path.** On a coarse pointer a tap opens the card without swallowing the trigger; a tap outside closes it. `@tapToOpen={{false}}` turns that off, leaving the card reachable only by keyboard on touch devices — usually the wrong trade.
+
+**The default block yields `close`** for a card that wants its own dismiss. It closes and returns focus to the trigger, the same path Escape takes.
+
+## Prior art
+
+**shadcn HoverCard** is **Radix HoverCard**: `openDelay` / `closeDelay` in milliseconds, `side` / `align` for placement, `open` / `onOpenChange` / `defaultOpen`. **Mantine HoverCard** adds a `shadow` prop and a group-open. **Base UI PreviewCard** and **React Aria PreviewTrigger** are the same idea under the accessibility-conscious names. All share the two delays, because without them the card flickers.
+
+Where this is better, and the difference is the whole component: **the card is reachable by the people the pattern usually excludes.** Radix sets `tabindex='-1'` on every tabbable node inside the card. That prevents a keyboard trap, at the price of making the card's own links unreachable by exactly the users who most needed them reachable. Here the card renders in DOM order immediately after the trigger and keeps its tab stops, so Tab walks _into_ it, Tab out of the last one leaves and closes it, and Escape closes it and returns focus to the trigger. Radix also excludes touch outright, so on a phone the card does not exist; `@tapToOpen` gives it one. And the trigger carries `aria-expanded` and `aria-controls`, a relationship neither Radix nor shadcn establishes, so a screen-reader user is told the preview exists.
+
+Where it is thinner: no `side` / `align` pair — one logical `@placement` resolved through the kit's own `anchorTo`; no arrow; no portal arg, because the shared `Popup` decides that; and no Mantine-style group hover. The card has no built-in layout: it is a padded surface, and what goes in it is yours.
+
+## Accessibility
+
+Governing pattern: there is no APG pattern for a hover card, and that absence is the point — content that only appears on hover is content a keyboard user, a screen-reader user and every touch device cannot reach, so the component's job is to give each of them a path. WCAG **1.4.13** (content on hover or focus) is the requirement: dismissible, hoverable, persistent.
+
+What it does, and the tests assert:
+
+- **Focus opens it with no delay**, and the trigger's control gets `aria-expanded='true'` plus an `aria-controls` that points at the card's `id`.
+- **The card keeps its own tab stops.** A link inside it is reached by Tab from the trigger, and Tab past the last one leaves the surface and closes the card.
+- **Escape closes it and returns focus to the trigger**, taken in the capture phase on the document while open.
+- **Focus leaving the whole surface closes it**; focus moving between trigger and card does not.
+- **The card is `role='dialog'`** with `aria-label` from `@label`. The default `'Preview'` is generic; name the thing being previewed.
+- **Hoverable and persistent** by construction: the close delay bridges the gap, and pointer travel into the card cancels the close.
+
+The caller's part: put a real focusable control in the trigger block, or none of the keyboard path exists. Keep the card's content meaningful without the trigger's context, because a reader who tabs into it arrives with no pointer position. And do not put anything essential in it — 1.4.13 makes hover content dismissible, and a dismissed card is gone.
+
+## Theming
+
+Read directly: `--popover` and `--popover-foreground`, `--radius-surface`, `--space-4`, `--font-sans`, `--text-ui-md`, `--pretui-shadow-overlay`, and the enter motion pair `--pretui-dur-enter` / `--pretui-ease-enter`.
+
+One knob of its own: `--pretui-hovercard-width` (default 260px), capped at the viewport minus 16px. Entry motion is `@starting-style` (opacity plus a 4px rise and 0.98 scale, 180ms) with a `prefers-reduced-motion` opt-out. Position and flip come from the shared `Popup`, so a theme that retunes overlay placement retunes this with it.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| Agent types                                  | Give them                                              |
+| -------------------------------------------- | ------------------------------------------------------ |
+| Radix `openDelay={700}` / `closeDelay={300}` | `@openDelay={{0.7}}` / `@closeDelay={{0.3}}` — seconds |
+| `open` / `onOpenChange` / `defaultOpen`      | same                                                   |
+| `side` / `align`                             | one `@placement`                                       |
+| `HoverCardTrigger` / `HoverCardContent`      | `<:trigger>` / `<:default>`                            |
+| Mantine `shadow`                             | `--pretui-shadow-overlay`                              |
+| a preview that must be tappable on mobile    | `@tapToOpen` (on by default) — Radix has no equivalent |
+| a card with a form in it                     | **Popover**                                            |
+| a one-line label                             | **Tooltip**                                            |

package/bundled-realms/pretui/components/hover-card.usage.gts

@@ -0,0 +1,174 @@
+// Pretui — HoverCard usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { HoverCard } from './hover-card';
+import type { PopupPlacement } from '../internal/overlay';
+
+const HC_PLACEMENTS = ['bottom-start', 'bottom', 'top', 'right-start', 'left-start'];
+
+// Glimmer accepts decimal number literals, but `{{0.5}}` reads like the
+// `{{foo.0}}` numeric-path form the transpiler rejects. Named constants keep
+// the template unambiguous.
+const DELAY_STEP = 0.1;
+const DELAY_MAX = 2;
+const DELAY_MIN = 0;
+const OPEN_DELAY_DEFAULT = 0.5;
+const CLOSE_DELAY_DEFAULT = 0.3;
+
+
+class HoverCardUsage extends GlimmerComponent {
+  @tracked placement = 'bottom-start';
+  @tracked openDelay = 0.5;
+  @tracked closeDelay = 0.3;
+
+  setPlacement = (value: string) => (this.placement = value);
+  setOpenDelay = (value: number | null) => (this.openDelay = value ?? 0.5);
+  setCloseDelay = (value: number | null) => (this.closeDelay = value ?? 0.3);
+
+  get placementValue() {
+    return this.placement as PopupPlacement;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='HoverCard'
+      @description='The rich link preview: a Popup with hover intent in front of it. Accessibility is the whole problem, because content that only appears on hover is content a keyboard user, a screen reader and every touch device cannot reach. Focus opens it with no delay, since a reader who deliberately tabbed to the trigger has already expressed the intent. The card keeps its own tab stops, so Tab walks into it and out again — Radix sets tabindex=-1 on everything inside, which prevents a trap by making the card useless to exactly the people it was made reachable for. And a tap opens it on a coarse pointer, where Radix simply excludes touch and the card does not exist at all.'
+    >
+      <:example>
+        <p class='oc-prose'>Lot 4417 was cupped by
+          <HoverCard
+            @placement={{this.placementValue}}
+            @openDelay={{this.openDelay}}
+            @closeDelay={{this.closeDelay}}
+            @label='Ama Boateng'
+          >
+            <:trigger>
+              <a class='oc-mention' href='#lot-4417'>Ama Boateng</a>
+            </:trigger>
+            <:default>
+              <div class='oc-card'>
+                <span class='oc-card-name'>Ama Boateng</span>
+                <span class='oc-card-role'>Q grader · Accra desk</span>
+                <p class='oc-card-note'>Scores East African naturals; keeps the
+                  arrivals board honest about moisture.</p>
+                <a class='oc-card-link' href='#profile'>Open profile</a>
+              </div>
+            </:default>
+          </HoverCard>
+          on the 14th, three days after arrival.</p>
+        <p class='oc-hint'>Tab to the link and the card opens at once. Tab again
+          and focus moves
+          <em>into</em>
+          the card, onto its own link. Tab past it and it closes. Escape closes
+          it and puts focus back on the mention.</p>
+      </:example>
+      <:api as |Args|>
+        <Args.Base
+          @name='open / onOpenChange / defaultOpen'
+          @description='The overlay contract. A controlled HoverCard is how a tour or a test drives it without a pointer.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='placement'
+          @description="Radix's side and align collapsed into one logical placement, resolved through the kit's own anchorTo."
+          @value={{this.placement}}
+          @options={{HC_PLACEMENTS}}
+          @defaultValue='bottom-start'
+          @onInput={{this.setPlacement}}
+        />
+        <Args.Number
+          @name='openDelay'
+          @description='Seconds of hover before it opens. Seconds, not the 700 Radix passes — a bare number in a prop is a unit no caller can check. Focus ignores this entirely.'
+          @value={{this.openDelay}}
+          @min={{DELAY_MIN}}
+          @max={{DELAY_MAX}}
+          @step={{DELAY_STEP}}
+          @defaultValue={{OPEN_DELAY_DEFAULT}}
+          @onInput={{this.setOpenDelay}}
+        />
+        <Args.Number
+          @name='closeDelay'
+          @description='Seconds after the pointer leaves before it closes. The pair matters more than either number: the close delay is the bridge across the gap between trigger and card, and setting it to zero makes the card unreachable by pointer no matter how good the open delay is.'
+          @value={{this.closeDelay}}
+          @min={{DELAY_MIN}}
+          @max={{DELAY_MAX}}
+          @step={{DELAY_STEP}}
+          @defaultValue={{CLOSE_DELAY_DEFAULT}}
+          @onInput={{this.setCloseDelay}}
+        />
+        <Args.Bool
+          @name='tapToOpen'
+          @description='On a coarse pointer a tap opens the card without swallowing the trigger, so a link stays a link and a preview is still available. This is the arg Radix does not have.'
+          @value={{true}}
+          @defaultValue={{true}}
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='trigger / default'
+          @description='The trigger block holds the link or control; whatever focusable it contains gets aria-expanded and aria-controls pointing at the card, a relationship neither Radix nor shadcn establishes. The default block receives a close function for a card that wants its own dismiss.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+
+    <style scoped>
+      .oc-prose {
+        margin: 0;
+        max-width: 54ch;
+        font-size: var(--text-body, 15px);
+        line-height: calc(var(--leading-body, 24px) / var(--text-body, 15px));
+      }
+      .oc-mention {
+        color: var(--pretui-primary-ink, var(--boxel-highlight-hover));
+        text-decoration: underline;
+        text-underline-offset: 2px;
+        text-decoration-style: dotted;
+      }
+      .oc-mention:focus-visible {
+        outline: 2px solid var(--ring);
+        outline-offset: 2px;
+        border-radius: 3px;
+      }
+      .oc-card {
+        display: grid;
+        gap: 3px;
+      }
+      .oc-card-name {
+        font-weight: 600;
+      }
+      .oc-card-role {
+        color: var(--muted-foreground);
+        font-size: var(--text-ui-sm, 11.5px);
+      }
+      .oc-card-note {
+        margin: var(--space-2, 6px) 0 0;
+        color: var(--muted-foreground);
+        font-size: var(--text-ui-sm, 11.5px);
+        line-height: 1.5;
+      }
+      .oc-card-link {
+        margin-top: var(--space-3, 8px);
+        color: var(--pretui-primary-ink, var(--boxel-highlight-hover));
+        font-size: var(--text-ui-sm, 11.5px);
+        font-weight: 600;
+      }
+      .oc-hint {
+        margin: var(--space-4, 11px) 0 0;
+        max-width: 62ch;
+        font-size: var(--text-ui-sm, 11.5px);
+        line-height: 1.6;
+        color: var(--muted-foreground);
+      }
+      .oc-hint em {
+        font-style: normal;
+        font-weight: 600;
+        color: var(--foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_HOVER_CARD: Record<string, unknown> = {
+  HoverCard: HoverCardUsage,
+};

package/bundled-realms/pretui/components/hover-video-player.gts

@@ -0,0 +1,315 @@
+// Pretui — HoverVideoPlayer: a poster that previews its video on hover or focus, never against reduced motion.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { modifier } from 'ember-modifier';
+import { cssDeclaration, cssStyleFrom } from '../pretui-css';
+
+// ── HoverVideoPlayer ─────────────────────────────────────────────────────
+// A thumbnail that becomes a moving preview when you show interest in it,
+// and stops when you stop. Four things the genre routinely gets wrong, and
+// what is done here instead:
+//
+//   1. **Touch.** Upstream binds `mouseenter`/`mouseleave` and is simply
+//      dead on a phone. Here there is always a real play/pause `<button>`;
+//      on fine pointers it fades in on hover or focus, on coarse pointers it
+//      is permanently visible at 44px.
+//   2. **Keyboard.** `focusin`/`focusout` drive the same path as the
+//      pointer, so tabbing to the card previews it.
+//   3. **Motion preference.** `prefers-reduced-motion: reduce` disables
+//      hover- and focus-autoplay outright — a moving image is exactly what
+//      that preference is about. The explicit button still works, because
+//      the preference is about ambient motion, not about consent.
+//   4. **Layout.** `@ratio` reserves the box before the poster loads, so a
+//      grid of these does not reflow as they arrive.
+//
+// Playback is driven by ONE tracked boolean through a modifier; there is no
+// timer, no rAF, and no listener that outlives the element.
+
+/** hover/focus intent on the card, with every listener removed on teardown */
+const previewIntent = modifier(
+  (
+    el: HTMLElement,
+    [onEnter, onLeave]: [() => void, () => void],
+  ) => {
+    let enter = () => onEnter();
+    let leave = () => onLeave();
+    el.addEventListener('pointerenter', enter);
+    el.addEventListener('pointerleave', leave);
+    el.addEventListener('focusin', enter);
+    el.addEventListener('focusout', leave);
+    return () => {
+      el.removeEventListener('pointerenter', enter);
+      el.removeEventListener('pointerleave', leave);
+      el.removeEventListener('focusin', enter);
+      el.removeEventListener('focusout', leave);
+    };
+  },
+);
+
+/**
+ * Playback follows one boolean. The modifier body re-runs whenever that
+ * boolean changes, which is the whole scheduling mechanism — no interval
+ * polls the element's state. `play()` can reject (a source that never
+ * loaded, an autoplay policy), so the rejection is routed back to the
+ * component instead of surfacing as an unhandled promise.
+ */
+const previewPlayback = modifier(
+  (
+    el: HTMLVideoElement,
+    [playing, rewind, onFail]: [boolean, boolean, () => void],
+  ) => {
+    if (playing) {
+      let started = el.play();
+      if (started && typeof started.catch === 'function') {
+        started.catch(() => onFail());
+      }
+      return;
+    }
+    el.pause();
+    if (rewind && el.readyState > 0) {
+      el.currentTime = 0;
+    }
+  },
+);
+
+export interface HoverVideoPlayerSignature {
+  Args: {
+    /** the preview clip */
+    src: string;
+    /** the still shown before and after playback */
+    poster?: string;
+    /**
+     * what the preview is OF. Required: it names the play control and the
+     * figure, and an unlabelled video is an unlabelled control.
+     */
+    label: string;
+    /** aspect ratio reserving the box, e.g. '16 / 9' (default '16 / 9') */
+    ratio?: string;
+    /** keep it silent (default true — an unmuted hover preview is hostile) */
+    muted?: boolean;
+    /** loop the preview (default true) */
+    loop?: boolean;
+    /** rewind to the first frame when the preview stops (default true) */
+    rewind?: boolean;
+    /** preview on hover and focus (default true) */
+    playOnIntent?: boolean;
+    /** caption rendered under the frame */
+    caption?: string;
+    /** fires whenever playback starts or stops */
+    onPlayingChange?: (playing: boolean) => void;
+  };
+  Blocks: {
+    /** content laid over the frame — a duration chip, a title */
+    overlay: [];
+  };
+  Element: HTMLElement;
+}
+
+export class HoverVideoPlayer extends Component<HoverVideoPlayerSignature> {
+  @tracked private playing = false;
+
+  get ratioStyle() {
+    return cssStyleFrom([
+      cssDeclaration('--pretui-hvp-ratio', this.args.ratio ?? '16 / 9'),
+    ]);
+  }
+  get muted(): boolean {
+    return this.args.muted ?? true;
+  }
+  get loop(): boolean {
+    return this.args.loop ?? true;
+  }
+  get rewind(): boolean {
+    return this.args.rewind ?? true;
+  }
+  get playOnIntent(): boolean {
+    return this.args.playOnIntent ?? true;
+  }
+  get toggleLabel(): string {
+    return (this.playing ? 'Pause preview of ' : 'Play preview of ') + this.args.label;
+  }
+
+  /** true when the reader has asked the platform for less movement */
+  private get reducedMotion(): boolean {
+    if (typeof window === 'undefined' || !window.matchMedia) {
+      return false;
+    }
+    return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  }
+
+  /** NOT named `set` — an arrow property called `set` on a Glimmer class
+   * trips ember/classic-decorator-no-classic-methods at realm lint, which
+   * reads it as the classic `this.set()` API. */
+  private setPlaying = (next: boolean) => {
+    if (this.playing === next) {
+      return;
+    }
+    this.playing = next;
+    this.args.onPlayingChange?.(next);
+  };
+
+  enter = () => {
+    if (!this.playOnIntent || this.reducedMotion) {
+      return;
+    }
+    this.setPlaying(true);
+  };
+
+  leave = () => {
+    if (!this.playOnIntent) {
+      return;
+    }
+    this.setPlaying(false);
+  };
+
+  toggle = () => this.setPlaying(!this.playing);
+
+  /** play() was refused; the control must not keep claiming it is playing */
+  failed = () => this.setPlaying(false);
+
+  <template>
+    <figure
+      class='pretui-hvp'
+      data-playing={{if this.playing 'true'}}
+      style={{this.ratioStyle}}
+      data-test-pretui-hover-video-player
+      {{previewIntent this.enter this.leave}}
+      ...attributes
+    >
+      <div class='pretui-hvp-frame'>
+        {{! The media element is decorative: it is named by the figcaption
+            and driven by the button beside it, so it is out of the tab order
+            and out of the accessibility tree rather than being a second,
+            unlabelled control. }}
+        <video
+          class='pretui-hvp-video'
+          src={{@src}}
+          poster={{@poster}}
+          muted={{if this.muted true}}
+          loop={{if this.loop true}}
+          playsinline={{true}}
+          preload='metadata'
+          tabindex='-1'
+          aria-hidden='true'
+          data-test-pretui-hover-video-player-video
+          {{previewPlayback this.playing this.rewind this.failed}}
+        ></video>
+        <span class='pretui-hvp-overlay'>{{yield to='overlay'}}</span>
+        <button
+          type='button'
+          class='pretui-hvp-toggle'
+          aria-label={{this.toggleLabel}}
+          aria-pressed={{if this.playing 'true' 'false'}}
+          data-test-pretui-hover-video-player-toggle
+          {{on 'click' this.toggle}}
+        >
+          {{#if this.playing}}
+            <svg viewBox='0 0 24 24' aria-hidden='true' focusable='false'>
+              <path d='M8 5h3v14H8zM13 5h3v14h-3z' fill='currentColor' />
+            </svg>
+          {{else}}
+            <svg viewBox='0 0 24 24' aria-hidden='true' focusable='false'>
+              <path d='M8 5l11 7-11 7z' fill='currentColor' />
+            </svg>
+          {{/if}}
+        </button>
+      </div>
+      <figcaption class='pretui-hvp-caption'>
+        {{#if @caption}}{{@caption}}{{else}}<span class='pretui-sr'
+          >{{@label}}</span>{{/if}}
+      </figcaption>
+    </figure>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-hvp {
+          margin: 0;
+          display: flex;
+          flex-direction: column;
+          gap: 6px;
+        }
+        .pretui-hvp-frame {
+          position: relative;
+          aspect-ratio: var(--pretui-hvp-ratio, 16 / 9);
+          border-radius: 10px;
+          overflow: hidden;
+          background: var(--inset, var(--boxel-100));
+          box-shadow: var(
+            --pretui-shadow-hairline,
+            0 0 0 1px var(--border)
+          );
+        }
+        .pretui-hvp-video {
+          display: block;
+          width: 100%;
+          height: 100%;
+          object-fit: cover;
+        }
+        .pretui-hvp-overlay {
+          position: absolute;
+          inset: auto 8px 8px auto;
+          display: flex;
+          gap: 5px;
+          pointer-events: none;
+        }
+        .pretui-hvp-toggle {
+          position: absolute;
+          inset: auto auto 8px 8px;
+          display: inline-grid;
+          place-items: center;
+          width: 32px;
+          height: 32px;
+          padding: 0;
+          border: 0;
+          border-radius: 50%;
+          background: color-mix(in oklch, var(--boxel-dark) 55%, transparent);
+          color: var(--boxel-light);
+          cursor: pointer;
+          opacity: 0;
+          transition: opacity 140ms linear;
+        }
+        .pretui-hvp-toggle svg {
+          width: 15px;
+          height: 15px;
+        }
+        /* hover is never the only affordance: focus-within reveals it too */
+        .pretui-hvp:hover .pretui-hvp-toggle,
+        .pretui-hvp:focus-within .pretui-hvp-toggle,
+        .pretui-hvp[data-playing] .pretui-hvp-toggle {
+          opacity: 1;
+        }
+        .pretui-hvp-toggle:focus-visible {
+          opacity: 1;
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+        .pretui-hvp-caption {
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+        }
+        .pretui-sr {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip-path: inset(50%);
+          white-space: nowrap;
+        }
+        /* a coarse pointer has no hover state to reveal anything with */
+        @media (any-pointer: coarse) {
+          .pretui-hvp-toggle {
+            opacity: 1;
+            width: 44px;
+            height: 44px;
+          }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-hvp-toggle {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/hover-video-player.md

@@ -0,0 +1,57 @@
+## What it is
+
+A video preview that plays on intent: hover it or focus it and the clip runs, leave and it stops. The pattern every media gallery uses to let a still stand in for a video without making you open it.
+
+Use it for a tile in a shelf or a grid. For a video someone is actually watching, that is **VideoPlayer**.
+
+## The contract
+
+```
+@src (required)   — the preview clip
+@label (required) — what the preview is OF; names the play control and the figure
+@poster?          — the still shown before and after playback
+@ratio?           — aspect ratio reserving the box. Default '16 / 9'
+@muted?           — keep it silent. Default true
+@loop?            — loop the preview. Default true
+@rewind?          — return to the first frame when the preview stops. Default true
+@playOnIntent?    — preview on hover and focus. Default true
+@caption?         — caption rendered under the frame
+@onPlayingChange? — fires whenever playback starts or stops
+
+<:overlay> — content laid over the frame: a duration chip, a title
+```
+
+**`@muted` defaults to true, and an unmuted hover preview is hostile.** Sound that starts because a pointer crossed a tile is the thing everyone hates about autoplaying video.
+
+**The box is reserved by `@ratio` before anything loads**, so a shelf of previews does not reflow as posters arrive.
+
+**Focus is an intent, not only hover.** A keyboard user tabbing to the tile gets the same preview a pointer user gets, which is the whole reason `@playOnIntent` covers both.
+
+**Reduced motion is checked**, so a reader who has asked for less movement is not ambushed by a clip that starts because their pointer passed over it.
+
+**The video is `preload='metadata'`**, so a shelf of previews costs metadata rather than bytes until something is hovered.
+
+## Prior art
+
+**cult-ui's `hover-video-player`** is the source.
+
+Where Pretui is better: **focus drives the preview too**, where upstream is pointer-only — which means on upstream a keyboard user simply cannot see the preview at all. **Reduced-motion readers get intentional playback rather than ambush video.** And the frame is a real `<figure>` with a real `<figcaption>`, so the caption is associated rather than merely adjacent.
+
+Where it is thinner: no hover-intent delay, so a pointer sweeping across a shelf starts and stops several previews in a row; no unmute affordance, since the preview is muted and stays that way; no scrubbing or seeking; and no thumbnail-strip preview on hover, which is the richer version of this pattern. The preview is also a separate clip from whatever the full video is — there is no contract tying the two together.
+
+## Accessibility
+
+- **The `<video>` is `aria-hidden` and `tabindex='-1'`.** It is a moving poster, not a control, and exposing it would put a second unlabelled media element in the accessibility tree beside the button that actually operates it.
+- **The toggle is a real button with `aria-pressed`** and an accessible name derived from `@label`, so the preview can be started and stopped by keyboard without relying on focus-to-play.
+- **`@label` is required by the type**, because it names both the figure and the control — an unlabelled video is an unlabelled control.
+- **The toggle's glyphs are `aria-hidden` with `focusable='false'`**, so the state comes from `aria-pressed` rather than from a symbol, and the SVG never takes a tab stop in older browsers.
+- **`<figure>`/`<figcaption>`** associates the caption with the preview.
+- **Motion starts without a click by design**, which is exactly why the reduced-motion check matters. `@playOnIntent={{false}}` turns the tile into a still with a play button, which is the right choice in a dense grid.
+
+## Theming
+
+`--pretui-hvp-ratio` (the reserved box, written from `@ratio` through the kit's CSS guard, so a nonsense ratio drops its declaration and the stylesheet's `16 / 9` stands).
+
+The rest — the toggle's surface, the overlay scrim, the caption's ink — comes from the kit's shared control and surface tokens rather than from a component-specific set, so a preview tile in a shelf matches the cards around it without per-theme work.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.