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

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

@@ -0,0 +1,107 @@
+// Pretui — VideoPlayer usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { VideoPlayer } from './video-player';
+import {
+  SAMPLE_VIDEO_POSTER,
+  SAMPLE_VIDEO_SRC,
+  SOURCING_TRACKS,
+  SOURCING_TRANSCRIPT,
+} from '../media-examples';
+import { Chip } from './chip';
+import { CHROMES } from '../demo-media';
+
+// ── VideoPlayer ──────────────────────────────────────────────────────────
+const RATIOS: string[] = ['16 / 9', '4 / 3', '1 / 1', '21 / 9'];
+
+class VideoPlayerUsage extends Component {
+  ratios = RATIOS;
+  chromes = CHROMES;
+  tracks = SOURCING_TRACKS;
+  transcript = SOURCING_TRANSCRIPT;
+  src = SAMPLE_VIDEO_SRC;
+  poster = SAMPLE_VIDEO_POSTER;
+
+  @tracked aspectRatio = '16 / 9';
+  @tracked autoHide = true;
+  @tracked caption =
+    'Second flush arriving at the Kandy shed. Public test clip, used here as a stand-in.';
+
+  setAspectRatio = (v: string) => (this.aspectRatio = v);
+  setAutoHide = (v: boolean) => (this.autoHide = v);
+  setCaption = (v: string) => (this.caption = v);
+
+  get usage(): string {
+    return [
+      '<VideoPlayer',
+      '  @src={{this.src}}',
+      '  @poster={{this.poster}}',
+      `  @aspectRatio='${this.aspectRatio}'`,
+      `  @autoHide={{${this.autoHide}}}`,
+      '  @tracks={{this.tracks}}',
+      '/>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='VideoPlayer'
+      @description="The other skin: @kind='video' curried, a reserved aspect ratio, a poster, and a <figcaption> so the picture and its caption are one figure to assistive technology. This is the one page on the site that needs a network — there is no way to synthesise an mp4 — so the src points at the public test clip Media Chrome's own documentation uses, and it is a knob. Offline you get the poster, the reserved box and the error text, which is exactly what the error channel is for. Note autoHide is ON here, against the kit default: press Tab and the bar returns."
+      @source={{this.usage}}
+    >
+      <:example>
+        <VideoPlayer
+          @src={{this.src}}
+          @label='Estate reel — second flush'
+          @poster={{this.poster}}
+          @aspectRatio={{this.aspectRatio}}
+          @autoHide={{this.autoHide}}
+          @caption={{this.caption}}
+          @tracks={{this.tracks}}
+          @transcript={{this.transcript}}
+        >
+          <:overlay>
+            <Chip>Rights: internal</Chip>
+          </:overlay>
+        </VideoPlayer>
+      </:example>
+
+      <:api as |Args|>
+        <Args.String
+          @name='aspectRatio'
+          @value={{this.aspectRatio}}
+          @options={{this.ratios}}
+          @defaultValue='16 / 9'
+          @description='Reserved before the poster resolves, so nothing reflows. Switch it and watch the box change without a flash of collapsed layout — the defect the catalog sweep found three separate times.'
+          @onInput={{this.setAspectRatio}}
+        />
+        <Args.Bool
+          @name='autoHide'
+          @value={{this.autoHide}}
+          @defaultValue={{false}}
+          @description='Cinema behaviour. Focus always brings the transport back.'
+          @onInput={{this.setAutoHide}}
+        />
+        <Args.String
+          @name='caption'
+          @value={{this.caption}}
+          @description='Rendered as a <figcaption> inside a <figure>, which is the semantic pairing — not a paragraph that happens to sit underneath.'
+          @onInput={{this.setCaption}}
+        />
+        <Args.Yield
+          @name='overlay'
+          @description='Over the picture, top-left. The rights chip above is this block.'
+        />
+        <Args.Base
+          @name='everything else'
+          @description='Every MediaPlayer arg except @kind is forwarded verbatim, including @thumbnails — supply a WebVTT thumbnails track and the scrubber shows preview frames while seeking.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_VIDEO_PLAYER: Record<string, unknown> = {
+  VideoPlayer: VideoPlayerUsage,
+};

package/bundled-realms/pretui/components/viewport.gts

@@ -0,0 +1,520 @@
+// Pretui — Viewport: the artboard every usage example renders in.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { htmlSafe } from '@ember/template';
+import { modifier } from 'ember-modifier';
+import { SegmentedControl } from './segmented-control';
+import { Select } from './select';
+import { Slider } from './slider';
+import { Switch } from './switch';
+
+function htmlWidth(w: string) {
+  return htmlSafe(`width: ${w}`);
+}
+function isInline(mode: string) {
+  return mode === 'inline';
+}
+function isBp(mode: string) {
+  return mode === 'bp';
+}
+
+// ── Viewport — the artboard ──────────────────────────────────────────────
+// Built against the artboard contract: true widths that pan
+// rather than clamp, a neutral stage with explicit surface/gutter settings,
+// named breakpoints + a 3-up mode, honest live captions, a drag handle
+// (pointer capture, no document listeners), and reflected data-* state.
+const VIEWPORT_MODES = [
+  { value: 'fill', label: 'Fill' },
+  { value: 'phone', label: 'Phone' },
+  { value: 'tablet', label: 'Tablet' },
+  { value: 'desktop', label: 'Desktop' },
+  { value: 'bp', label: '3-up' },
+  { value: 'inline', label: 'Inline' },
+  { value: 'grid', label: 'Grid' },
+];
+const PRESET_WIDTHS: Record<string, number> = {
+  phone: 320,
+  tablet: 600,
+  desktop: 1120,
+};
+const BREAKPOINTS = Object.entries(PRESET_WIDTHS).map(([bp, px]) => ({
+  bp,
+  width: `${px}px`,
+  caption: `${VIEWPORT_MODES.find((m) => m.value === bp)?.label} · ${px}px`,
+}));
+const SURFACES = [
+  { value: 'background', label: 'Background' },
+  { value: 'card', label: 'Card' },
+  { value: 'inset', label: 'Inset' },
+  { value: 'sidebar', label: 'Sidebar' },
+];
+// pre-artboard mode names still referenced by older pages
+const LEGACY_MODES: Record<string, string> = {
+  narrow: 'phone',
+  wide: 'desktop',
+};
+const GRID_CELLS = [1, 2, 3, 4, 5, 6];
+
+export interface ViewportSignature {
+  Args: {
+    defaultMode?:
+      | 'fill'
+      | 'phone'
+      | 'tablet'
+      | 'desktop'
+      | 'bp'
+      | 'inline'
+      | 'grid'
+      | 'narrow'
+      | 'wide';
+  };
+  Blocks: { default: [] };
+  Element: HTMLDivElement;
+}
+
+export class Viewport extends Component<ViewportSignature> {
+  @tracked mode: string =
+    LEGACY_MODES[this.args.defaultMode ?? ''] ?? this.args.defaultMode ?? 'fill';
+  @tracked customWidth = 0;
+  @tracked surface = 'background';
+  @tracked gutter = true;
+  cells = GRID_CELLS;
+  breakpoints = BREAKPOINTS;
+  surfaces = SURFACES;
+  setMode = (v: string) => {
+    this.mode = v;
+    this.customWidth = 0;
+  };
+  // A free width belongs to Fill, so every preset click afterwards is a real
+  // change that resets it; snapped to the slider's 5px step so the slider
+  // can land on a dragged width.
+  setWidth = (v: number) => {
+    this.customWidth = Math.round(Math.min(1600, Math.max(240, v)) / 5) * 5;
+    this.mode = 'fill';
+  };
+  formatWidth = (v: number) => `${v} pixels`;
+  setSurface = (v: string) => (this.surface = v);
+  setGutter = (v: boolean) => (this.gutter = v);
+  get isFramed() {
+    return this.mode === 'fill' || this.mode in PRESET_WIDTHS;
+  }
+  get artboardWidth(): number {
+    return this.customWidth || PRESET_WIDTHS[this.mode] || 0;
+  }
+  get widthLabel() {
+    return this.artboardWidth ? `${this.artboardWidth}px` : '100%';
+  }
+  // named by the selected mode, like the 3-up captions; a dragged width is
+  // Fill, so it reads "Fill · 412px"
+  get frameCaption() {
+    let mode = VIEWPORT_MODES.find((m) => m.value === this.mode)?.label;
+    return `${mode} · ${this.widthLabel}`;
+  }
+  // Drag-to-resize on the artboard edge. Pointer capture keeps every event
+  // on the handle — no document listeners (backdrop-close discipline).
+  resizeHandle = modifier((handle: HTMLElement) => {
+    let artboard = handle.closest('.pretui-artboard') as HTMLElement | null;
+    // The flag lives on the viewport root, not documentElement: scoped CSS
+    // can only match elements this component renders, and the root is the
+    // ancestor of everything a drag could otherwise select.
+    let root = handle.closest('.pretui-viewport') as HTMLElement | null;
+    let startX = 0;
+    let startW = 0;
+    let active = false;
+    // Pointer capture keeps the events coming to the handle, but it does NOT
+    // stop the browser from extending a text selection across the page while
+    // the button is held. preventDefault on pointerdown suppresses the
+    // selection gesture at its source, and the data-resizing flag pins
+    // user-select: none for the duration in case a selection was already
+    // under way when the drag started.
+    let down = (e: PointerEvent) => {
+      if (e.button !== 0) return;
+      active = true;
+      startX = e.clientX;
+      startW = artboard?.getBoundingClientRect().width ?? 0;
+      handle.setPointerCapture(e.pointerId);
+      e.preventDefault();
+      root?.setAttribute('data-resizing', 'true');
+    };
+    let move = (e: PointerEvent) => {
+      if (active) {
+        this.setWidth(startW + (e.clientX - startX));
+      }
+    };
+    let up = () => {
+      active = false;
+      root?.removeAttribute('data-resizing');
+    };
+    handle.addEventListener('pointerdown', down);
+    handle.addEventListener('pointermove', move);
+    handle.addEventListener('pointerup', up);
+    handle.addEventListener('pointercancel', up);
+    return () => {
+      handle.removeEventListener('pointerdown', down);
+      handle.removeEventListener('pointermove', move);
+      handle.removeEventListener('pointerup', up);
+      handle.removeEventListener('pointercancel', up);
+      // Never leave the page unselectable if the handle unmounts mid-drag.
+      root?.removeAttribute('data-resizing');
+    };
+  });
+  <template>
+    <div class='pretui-viewport' data-test-pretui-viewport ...attributes>
+      <div class='pretui-viewport-bar'>
+        <SegmentedControl
+          class='pretui-viewport-modes'
+          @label='Viewport mode'
+          @options={{VIEWPORT_MODES}}
+          @value={{this.mode}}
+          @onValueChange={{this.setMode}}
+        />
+        <div class='pretui-viewport-settings'>
+          <div class='pretui-viewport-surface'>
+            <Select
+              @label='Stage surface'
+              @options={{this.surfaces}}
+              @value={{this.surface}}
+              @onValueChange={{this.setSurface}}
+              @disabled={{isInline this.mode}}
+            />
+          </div>
+          <label class='pretui-viewport-gutter'>
+            <Switch
+              @checked={{this.gutter}}
+              @onCheckedChange={{this.setGutter}}
+              @disabled={{isInline this.mode}}
+              data-test-pretui-viewport-gutter
+            />
+            <span>Padding</span>
+          </label>
+        </div>
+        <div class='pretui-viewport-width'>
+          <Slider
+            @value={{this.artboardWidth}}
+            @min={{240}}
+            @max={{1600}}
+            @step={{5}}
+            @label='Artboard width'
+            @formatValue={{this.formatWidth}}
+            @onValueChange={{this.setWidth}}
+          />
+          <span class='pretui-viewport-readout'>{{this.widthLabel}}</span>
+        </div>
+      </div>
+      {{! wide artboards pan inside the canvas, so it takes a tab stop and a
+          name for keyboard users }}
+      <div
+        class='pretui-viewport-canvas'
+        tabindex='0'
+        role='region'
+        aria-label='Artboard canvas'
+        data-mode={{this.mode}}
+        data-width={{this.widthLabel}}
+      >
+        {{#if this.isFramed}}
+          <div
+            class='pretui-artboard'
+            data-label={{this.frameCaption}}
+            data-width={{this.widthLabel}}
+            style={{htmlWidth this.widthLabel}}
+            data-test-pretui-artboard
+          >
+            <div
+              class='pretui-artboard-body'
+              data-surface={{this.surface}}
+              data-gutter={{if this.gutter 'true' 'false'}}
+              data-test-pretui-artboard-body
+              data-test-pretui-viewport-specimen
+            >
+              {{yield}}
+            </div>
+            <span
+              class='pretui-artboard-handle'
+              aria-hidden='true'
+              title='Drag to resize — or use the width slider'
+              {{this.resizeHandle}}
+            ></span>
+          </div>
+        {{else if (isBp this.mode)}}
+          <div class='pretui-bp-row'>
+            {{#each this.breakpoints as |b|}}
+              <div
+                class='pretui-artboard'
+                data-bp={{b.bp}}
+                data-label={{b.caption}}
+                style={{htmlWidth b.width}}
+                data-test-pretui-artboard
+              >
+                <div
+                  class='pretui-artboard-body'
+                  data-surface={{this.surface}}
+                  data-gutter={{if this.gutter 'true' 'false'}}
+                  data-test-pretui-artboard-body
+                  data-test-pretui-viewport-specimen
+                >
+                  {{yield}}
+                </div>
+              </div>
+            {{/each}}
+          </div>
+        {{else if (isInline this.mode)}}
+          {{! a div, not a p: the specimen may be block-level markup }}
+          <div class='pretui-viewport-prose'>The order ledger closes at noon,
+            and
+            <div
+              class='pretui-viewport-inline'
+              data-test-pretui-viewport-specimen
+            >{{yield}}</div>
+            sits inline with the running text — cap-line trim and optical
+            spacing judged mid-paragraph, exactly where machine values live.</div>
+        {{else}}
+          <div class='pretui-viewport-grid'>
+            {{#each this.cells}}
+              <div
+                class='pretui-viewport-cell'
+                data-surface={{this.surface}}
+                data-gutter={{if this.gutter 'true' 'false'}}
+                data-test-pretui-viewport-specimen
+              >{{yield}}</div>
+            {{/each}}
+          </div>
+        {{/if}}
+      </div>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-viewport {
+          --pretui-viewport-bar-min-h: 2.25rem;
+          --pretui-viewport-width-min-w: 10rem;
+          --pretui-viewport-width-max-w: 18.75rem;
+          --pretui-viewport-readout-min-w: 3rem;
+          --pretui-viewport-surface-w: 8.125rem;
+          --pretui-viewport-canvas-min-h: 13.75rem;
+          --pretui-viewport-canvas-max-h: 34rem;
+          --pretui-viewport-dot-gap: 1.25rem;
+          /* a translucent --background follows the theme in light and dark,
+             which the fixed --boxel-light-* overlays don't */
+          --pretui-viewport-veil: color-mix(
+            in oklch,
+            var(--background) 70%,
+            transparent
+          );
+          --pretui-artboard-min-h: 4.5rem;
+          --pretui-artboard-handle-w: 1rem;
+          --pretui-artboard-grip-w: 0.25rem;
+          --pretui-artboard-grip-h: 1.875rem;
+          --pretui-viewport-tile-min-w: 12.5rem;
+          --pretui-viewport-cell-min-h: 4rem;
+
+          /* one column that may shrink below its content, so a wide artboard
+             pans inside the canvas instead of widening the whole viewport */
+          display: grid;
+          grid-template-columns: minmax(0, 1fr);
+          min-width: 0;
+        }
+        /* While the width handle is being dragged, nothing in the viewport is
+           selectable — otherwise the drag paints a text selection across the
+           artboard and its captions. Set by the resizeHandle modifier and
+           cleared on pointerup, pointercancel, and teardown. */
+        .pretui-viewport[data-resizing='true'] {
+          user-select: none;
+          -webkit-user-select: none;
+          cursor: ew-resize;
+        }
+        .pretui-viewport-bar {
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+          gap: var(--boxel-sp-sm);
+          flex-wrap: wrap;
+          min-width: 0;
+          min-height: var(--pretui-viewport-bar-min-h);
+          padding: var(--boxel-sp-2xs) var(--boxel-sp-sm);
+          box-shadow: inset 0 -1px 0 var(--border);
+        }
+        /* seven segments outgrow a phone-width panel; the control scrolls on
+           its own rather than pushing the page sideways */
+        .pretui-viewport-modes {
+          max-width: 100%;
+          overflow-x: auto;
+          scrollbar-width: none;
+        }
+        .pretui-viewport-width {
+          display: flex;
+          align-items: center;
+          gap: var(--boxel-sp-xs);
+          flex: 1;
+          min-width: min(var(--pretui-viewport-width-min-w), 100%);
+          max-width: var(--pretui-viewport-width-max-w);
+        }
+        .pretui-viewport-width > :first-child {
+          flex: 1;
+        }
+        .pretui-viewport-readout {
+          font-family: var(--font-mono);
+          font-size: var(--boxel-font-size-xs);
+          color: var(--muted-foreground);
+          min-width: var(--pretui-viewport-readout-min-w);
+          text-align: right;
+          font-variant-numeric: tabular-nums;
+        }
+        .pretui-viewport-settings {
+          display: flex;
+          flex-wrap: wrap;
+          align-items: center;
+          gap: var(--boxel-sp-sm);
+          min-width: 0;
+        }
+        .pretui-viewport-surface {
+          width: var(--pretui-viewport-surface-w);
+        }
+        .pretui-viewport-gutter {
+          display: inline-flex;
+          align-items: center;
+          gap: var(--boxel-sp-2xs);
+          font-size: var(--boxel-ui-label-font-size);
+          font-weight: var(--boxel-ui-label-font-weight);
+          line-height: var(--boxel-ui-label-line-height);
+          letter-spacing: var(--boxel-ui-label-letter-spacing);
+          color: var(--muted-foreground);
+          white-space: nowrap;
+          cursor: pointer;
+        }
+        .pretui-viewport-canvas {
+          /* the canvas floor: dot grid on the inset surface (Figma idiom).
+             R1: true widths — wide artboards pan, they are never clamped */
+          background-color: var(--inset);
+          color: var(--foreground);
+          background-image: radial-gradient(
+            circle,
+            var(--border) 1px,
+            transparent 1px
+          );
+          background-size: var(--pretui-viewport-dot-gap)
+            var(--pretui-viewport-dot-gap);
+          min-height: var(--pretui-viewport-canvas-min-h);
+          max-height: var(--pretui-viewport-canvas-max-h);
+          padding: var(--boxel-sp-2xl) var(--boxel-sp-lg) var(--boxel-sp-lg);
+          overflow: auto;
+          min-width: 0;
+        }
+        .pretui-artboard {
+          /* exact width from its inline style; centered while it fits, panned
+             once it doesn't. The preset widths stay in px: they stand in for
+             device widths in CSS pixels. */
+          position: relative;
+          margin-inline: auto;
+          min-height: var(--pretui-artboard-min-h);
+        }
+        .pretui-artboard[data-label]::before {
+          content: attr(data-label);
+          position: absolute;
+          top: calc(-1 * var(--boxel-sp-lg));
+          inset-inline-start: 0;
+          font-family: var(--font-mono);
+          font-size: var(--boxel-font-size-2xs);
+          letter-spacing: var(--boxel-lsp-sm);
+          color: var(--primary-ink);
+          white-space: nowrap;
+        }
+        /* a neutral stage, normal block flow with no centering opinion; grid
+           cells share its surfaces */
+        .pretui-artboard-body,
+        .pretui-viewport-cell {
+          min-height: var(--pretui-artboard-min-h);
+          border-radius: var(--boxel-border-radius-sm);
+          box-shadow: 0 0 0 1px var(--border);
+        }
+        .pretui-artboard-body[data-gutter='true'] {
+          padding: var(--boxel-sp);
+        }
+        .pretui-artboard-body[data-surface='background'],
+        .pretui-viewport-cell[data-surface='background'] {
+          /* a veil of the page color over the dot floor, so the stage reads as
+             an area while the specimen still sits on the page background */
+          background-color: var(--pretui-viewport-veil);
+        }
+        .pretui-artboard-body[data-surface='card'],
+        .pretui-viewport-cell[data-surface='card'] {
+          background-color: var(--card);
+          color: var(--card-foreground);
+          box-shadow:
+            0 0 0 1px var(--border),
+            var(--shadow-sm);
+        }
+        .pretui-artboard-body[data-surface='sidebar'],
+        .pretui-viewport-cell[data-surface='sidebar'] {
+          background-color: var(--sidebar);
+          color: var(--sidebar-foreground);
+          box-shadow: 0 0 0 1px var(--sidebar-border);
+        }
+        .pretui-artboard-body[data-surface='inset'],
+        .pretui-viewport-cell[data-surface='inset'] {
+          background-color: var(--inset);
+          box-shadow: inset 0 0 0 1px var(--border);
+        }
+        .pretui-artboard-handle {
+          position: absolute;
+          top: 0;
+          bottom: 0;
+          right: calc(-1 * var(--pretui-artboard-handle-w) - var(--boxel-sp-6xs));
+          width: var(--pretui-artboard-handle-w);
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          cursor: ew-resize;
+          touch-action: none;
+        }
+        .pretui-artboard-handle::after {
+          content: '';
+          width: var(--pretui-artboard-grip-w);
+          height: var(--pretui-artboard-grip-h);
+          border-radius: var(--boxel-border-radius-xs);
+          background-color: var(--border-strong);
+        }
+        .pretui-artboard-handle:hover::after {
+          background-color: var(--primary-ink);
+        }
+        .pretui-bp-row {
+          /* R3: the same specimen at every breakpoint, side by side */
+          display: flex;
+          gap: var(--boxel-sp-2xl);
+          align-items: flex-start;
+          width: max-content;
+          margin-inline: auto;
+        }
+        .pretui-viewport-prose {
+          max-width: 62ch;
+          font-size: var(--boxel-body-font-size);
+          line-height: var(--boxel-body-line-height);
+        }
+        /* a block specimen (a toast, a segmented control) still sits on the
+           line instead of breaking the paragraph */
+        .pretui-viewport-inline {
+          display: inline-block;
+          max-width: 100%;
+          vertical-align: middle;
+        }
+        .pretui-viewport-grid {
+          display: grid;
+          grid-template-columns: repeat(
+            auto-fill,
+            minmax(var(--pretui-viewport-tile-min-w), 1fr)
+          );
+          gap: var(--boxel-sp-sm);
+        }
+        .pretui-viewport-cell {
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          gap: var(--boxel-sp-xs);
+          flex-wrap: wrap;
+          min-height: var(--pretui-viewport-cell-min-h);
+        }
+        .pretui-viewport-cell[data-gutter='true'] {
+          padding: var(--boxel-sp-sm);
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/viewport.md

@@ -0,0 +1,55 @@
+## What it is
+
+The artboard: a framed stage that renders its content at a chosen device width, with a caption stating its width. Use it around any example that needs to be seen at a size other than the page's — every **FreestyleUsage** example sits in one. If you just need a bounded box, plain CSS is enough; Viewport is for _comparing_ a component across widths.
+
+## The contract
+
+```
+@defaultMode? 'fill' | 'phone' | 'tablet' | 'desktop' | 'bp' | 'inline' | 'grid'
+              ('narrow' and 'wide' are kept as aliases for 'phone' and 'desktop')
+<:default>
+```
+
+**True widths that pan rather than clamp.** A `phone` artboard is genuinely 320px wide and the stage scrolls horizontally to show it, rather than scaling the content down or clamping to the available space. That is the difference between an artboard and a resized div: a clamped preview lies about what the component does at that width, and a scaled one lies about its type size.
+
+**`bp` is a 3-up mode** — three breakpoints side by side, which is how you actually check a responsive component. **`inline`** sets the specimen inside a line of running text, to judge it mid-paragraph. **`grid`** repeats it in six cells, for density.
+
+**The stage** takes one of four surfaces (Background, a translucent veil of the page color; Card; Sidebar; Inset) and an optional Padding. Both apply to the framed modes and the grid cells; Inline sits in prose, so the two controls are disabled there.
+
+**The caption is live**: `"Phone · 320px"` for a preset, `"Fill · 100%"` for the full width, and `"Fill · 412px"` once you drag or use the width slider, updating as it moves. A dragged width belongs to Fill, so clicking a preset afterwards always resets it. An artboard whose label does not track its real width is worse than no label, because it invites you to trust it.
+
+**The drag handle uses pointer capture, not document listeners.** Same discipline as **Popover**'s backdrop and **SplitPanes**' handle: the listeners live on the handle, so teardown only unbinds them and clears the resize flag. Only the primary button starts a drag.
+
+State is reflected as `data-*`, so a theme or a test can read the current mode.
+
+## Prior art
+
+Built against the kit's artboard contract. The comparison set is design tooling rather than component libraries: **Storybook's viewport addon** (a dropdown of device presets that resizes the preview iframe), **Figma's frames**, and **Chrome DevTools' device toolbar**.
+
+Where this differs from Storybook's viewport addon, which is the closest analogue:
+
+- **Storybook scales the iframe** to fit the panel by default; this pans. Scaling makes 12px type look like 9px type and hides exactly the legibility problems you opened the phone preset to find.
+- **The caption is honest and live.** Storybook shows the preset name, not the measured width.
+- **A drag handle for arbitrary widths**, not only presets — which is how you find the width where a layout actually breaks, as opposed to confirming it works at three widths someone chose.
+- **A 3-up mode** with no analogue in Storybook.
+
+Where it is thinner: no device chrome, no orientation toggle, no zoom, and no device-pixel-ratio simulation.
+
+## Accessibility
+
+No pattern governs it; it is a tool, and the criteria are WCAG **2.1.1 Keyboard**, **2.5.7 Dragging Movements** and **1.4.10 Reflow**.
+
+- **The width slider is the keyboard path.** The drag handle is a redundant pointer target, hidden from assistive tech and not focusable; the **Slider** beside it sets the same width with the arrow keys (5px steps), Page Up/Down and Home/End, and announces it as "N pixels". The presets and a click on the slider track are the single-pointer alternatives 2.5.7 asks for.
+- **The canvas is a named region with a tab stop** ("Artboard canvas"), so a keyboard user can pan a `desktop` or 3-up artboard that is wider than the page.
+- **The mode picker is a SegmentedControl** (a radiogroup named "Viewport mode"). In a panel narrower than its seven segments it scrolls on its own instead of widening the page.
+- **In Fill, 3-up, Inline and Grid the slider reads its 240px minimum**, since those modes have no single fixed width to report.
+- **The live caption is not a live region**, so dragging gives a screen-reader user no width feedback; the slider's announced value is the channel.
+- **The framed content is arbitrary**, so anything inside keeps its own tab order: tabbing through a 3-up view traverses three copies of the component, and Grid six. That is expected for a tool and worth knowing.
+
+## Theming
+
+Stage surfaces (`--background`, `--card`, `--inset`, and `--sidebar` / `--sidebar-foreground` / `--sidebar-border`), `--border` for frames and the canvas dots, `--shadow-sm` on the card surface, `--border-strong` for the resize grip, `--primary-ink` for the artboard caption and the hovered grip, `--muted-foreground` for the width readout and the Padding label, a translucent `--background` veil over the dot floor on the Background surface, and and the tokens of the **SegmentedControl**, **Select**, **Switch** and **Slider** in the toolbar.
+
+**The stage is deliberately neutral** with explicit surface and padding settings, because an artboard that shares the page's background makes the framed component's own surface invisible. A theme must keep the stage distinguishable from `--card` — otherwise every example appears to float in nothing, which is exactly the illusion an artboard exists to prevent.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.