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

package/bundled-realms/pretui/components/qr-code.md

@@ -0,0 +1,58 @@
+## What it is
+
+A QR code generated from a value, with the encoded value also present as text or a link — never only as a symbol.
+
+## The contract
+
+```
+@value?           — the payload: a URL, an id, a vCard, anything under ~2 KB
+@label?           — accessible name for the symbol. Defaults to 'QR code'
+@errorCorrection? — ISO/IEC 18004 level. 'M' by default; forced to 'H' with @overlay
+@margin?          — quiet zone in modules, clamped to [4, 16]
+@size?            — rendered edge length in px, clamped to [64, 1024]. Default 180
+@foreground?, @background? — opaque hex only
+@valueDisplay?    — how the encoded value appears as text: 'auto' (default) renders
+                    an anchor for http(s) values and selectable code text otherwise;
+                    'link' and 'text' force one; 'none' keeps it visually hidden but
+                    still in the accessibility tree
+@caption?         — caption under the symbol; the <:caption> block wins
+@overlay?         — declares that an <:overlay> mark is being supplied
+@onRender?        — called with what was actually rendered
+
+<:caption> — replaces @caption
+<:overlay> — a mark centred over the symbol; requires @overlay={{true}}
+```
+
+**The encoded value is never removed outright.** `@valueDisplay='none'` hides it visually and keeps it in the accessibility tree, because a QR code alone is unusable to anyone who cannot point a camera at the screen they are already looking at.
+
+**`@overlay` is a flag _and_ a block, and the flag is what does the work.** Named blocks are not visible from component JavaScript, so the flag is what raises error correction to `'H'` and reserves the center. The block renders **only** when the flag is set — so forgetting it makes the overlay visibly vanish rather than silently producing an unscannable code.
+
+**The quiet zone lives in the `viewBox`, not in CSS padding**, so a caller cannot style away the margin the symbol needs in order to scan — the prior version accepted `margin: 0` and stretched the symbol to fill whatever box it was in besides.
+
+**The occluded area is capped at 20% of the symbol's edge** — about 4% of its area, well inside level H's ~30% budget.
+
+**Colours are opaque hex only.** A QR code with a translucent foreground is a QR code that does not scan.
+
+## Prior art
+
+**`wa-qr-code`.**
+
+Where Pretui is better: the value is always available as text, the overlay raises error correction automatically rather than leaving the caller to know that it must, and the failure mode of forgetting the flag is visible rather than silent.
+
+Where it is thinner: no logo sizing control beyond the cap, no module-shape styling (rounded dots and the like), and no export — the symbol is rendered, not downloadable.
+
+## Accessibility
+
+- **A QR code is not accessible content.** It is an image of a machine-readable string, and the only accessible version of it is the string. That is why `@valueDisplay` has no option that removes it.
+- **`@label` names the symbol, not the payload.** The value is exposed separately, so repeating it in the label is noise — which is why the default is the generic "QR code".
+- **`'auto'` renders an anchor for http(s) values**, which means the destination is reachable by keyboard on the same screen rather than requiring a second device.
+- **The quiet zone is clamped to the spec minimum and lives in the `viewBox`**, so a code cannot be rendered — or styled — in a way that fails to scan.
+- **`@onRender` reports what was actually produced**, which is how a caller detects that a payload was too large before a user finds out with a camera.
+
+## Theming
+
+`@foreground` and `@background` are args rather than tokens, and opaque hex rather than any CSS color — a deliberate departure from the kit's usual token channel, because contrast here is a functional requirement rather than an aesthetic one and a theme must not be able to break scanning.
+
+Everything around the symbol — the caption, the value text, the link — takes the normal kit tokens.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/qr-code.usage.gts

@@ -0,0 +1,224 @@
+// Pretui — QrCode usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { QrCode } from './qr-code';
+import type { QrRenderInfo } from './qr-code';
+import { Token } from './token';
+
+// ── QrCode ───────────────────────────────────────────────────────────────
+const ECLS: string[] = ['L', 'M', 'Q', 'H'];
+
+const VALUE_DISPLAYS: string[] = ['auto', 'link', 'text', 'none'];
+
+const SAMPLE_VALUES: string[] = [
+  'https://boxel.ai/tickets/TESSAR-2026-0041',
+  'TESSAR-2026-0041',
+  'BEGIN:VCARD\nVERSION:3.0\nN:Lovelace;Ada\nEND:VCARD',
+];
+
+class QrCodeUsage extends Component {
+  ecls = ECLS;
+  displays = VALUE_DISPLAYS;
+  samples = SAMPLE_VALUES;
+
+  @tracked value = SAMPLE_VALUES[0]!;
+  @tracked label = 'Check-in code';
+  @tracked errorCorrection = 'M';
+  @tracked margin = 4;
+  @tracked size = 200;
+  @tracked foreground = '#000000';
+  @tracked background = '#ffffff';
+  @tracked valueDisplay = 'auto';
+  @tracked caption = '';
+  @tracked overlay = false;
+  @tracked info: QrRenderInfo | undefined;
+
+  setValue = (v: string) => (this.value = v);
+  setLabel = (v: string) => (this.label = v);
+  setEcl = (v: string) => (this.errorCorrection = v);
+  setMargin = (v: number | null) => (this.margin = v ?? 4);
+  setSize = (v: number | null) => (this.size = v ?? 200);
+  setForeground = (v: string) => (this.foreground = v);
+  setBackground = (v: string) => (this.background = v);
+  setValueDisplay = (v: string) => (this.valueDisplay = v);
+  setCaption = (v: string) => (this.caption = v);
+  setOverlay = (v: boolean) => (this.overlay = v);
+  noteRender = (info: QrRenderInfo) => (this.info = info);
+
+  get eclValue(): 'L' | 'M' | 'Q' | 'H' {
+    return this.errorCorrection as 'L' | 'M' | 'Q' | 'H';
+  }
+  get displayValue(): 'auto' | 'link' | 'text' | 'none' {
+    return this.valueDisplay as 'auto' | 'link' | 'text' | 'none';
+  }
+  get versionText(): string {
+    return this.info?.version ? 'v' + this.info.version : '—';
+  }
+  get modulesText(): string {
+    return this.info?.moduleCount ? this.info.moduleCount + '²' : '—';
+  }
+  get contrastText(): string {
+    return this.info?.contrastRejected ? 'rejected' : 'accepted';
+  }
+  get usage(): string {
+    return [
+      '<QrCode',
+      "  @value='" + this.value.split('\n')[0] + "'",
+      "  @label='" + this.label + "'",
+      "  @errorCorrection='" + this.errorCorrection + "'",
+      '  @margin={{' + this.margin + '}}',
+      '  @size={{' + this.size + '}}',
+      "  @valueDisplay='" + this.valueDisplay + "'",
+      '/>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='QrCode'
+      @description="Encodes a value to a QR symbol as one <svg> with one <path>, from a vendored copy of the qrcode encoder core — the two implementations this replaces imported it from a public CDN at runtime, which broke offline and handed a third party a seat inside the realm. Two things here are deliberately NOT theme-obedient, and it is worth pushing the knobs until you see why. Drag the quiet zone down to zero: it clamps at 4, because the margin lives in the viewBox where CSS cannot reach it and a symbol without it does not scan. Then set a foreground and background that are close in luminance, or invert them, or type a var() token: the pair is refused, the symbol falls back to black-on-white, and the refusal is stated in the caption rather than shipped as an unscannable code. Everything AROUND the symbol is fully tokenized and re-tints with the theme. And whatever you encode is always reachable as selectable text or a real link — a QR code that only exists as an image is unusable to anyone not holding a second device."
+      @source={{this.usage}}
+    >
+      <:example>
+        <QrCode
+          @value={{this.value}}
+          @label={{this.label}}
+          @errorCorrection={{this.eclValue}}
+          @margin={{this.margin}}
+          @size={{this.size}}
+          @foreground={{this.foreground}}
+          @background={{this.background}}
+          @valueDisplay={{this.displayValue}}
+          @caption={{this.caption}}
+          @overlay={{this.overlay}}
+          @onRender={{this.noteRender}}
+        >
+          <:overlay><span class='qr-mark'>B</span></:overlay>
+        </QrCode>
+        <p class='cap-readout'>
+          <span class='cap-readoutLabel'>@onRender</span>
+          <Token @value={{this.versionText}} />
+          <Token @value={{this.modulesText}} />
+          <Token @value={{this.contrastText}} />
+        </p>
+      </:example>
+
+      <:api as |Args|>
+        <Args.String
+          @name='value'
+          @value={{this.value}}
+          @options={{this.samples}}
+          @description='The payload. A URL becomes a real link under the symbol; anything else becomes selectable monospace text.'
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='label'
+          @value={{this.label}}
+          @defaultValue='QR code'
+          @description='Accessible name for the symbol itself. The encoded value is exposed separately, so repeating it here is usually noise.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.String
+          @name='errorCorrection'
+          @value={{this.errorCorrection}}
+          @options={{this.ecls}}
+          @defaultValue='M'
+          @description='ISO/IEC 18004 level: L/M/Q/H recover roughly 7/15/25/30 percent. Higher costs capacity — watch the version token climb. Forced to H whenever overlay is set.'
+          @onInput={{this.setEcl}}
+        />
+        <Args.Number
+          @name='margin'
+          @value={{this.margin}}
+          @min={{0}}
+          @max={{20}}
+          @defaultValue={{4}}
+          @description='Quiet zone in modules. Clamped to [4, 16]: this widens the margin, it can never remove it.'
+          @onInput={{this.setMargin}}
+        />
+        <Args.Number
+          @name='size'
+          @value={{this.size}}
+          @min={{40}}
+          @max={{1200}}
+          @defaultValue={{180}}
+          @description='Rendered edge length in px, clamped to [64, 1024]. The only inline style the component writes, and it is a clamped integer.'
+          @onInput={{this.setSize}}
+        />
+        <Args.String
+          @name='foreground'
+          @value={{this.foreground}}
+          @defaultValue='#000000'
+          @description='Dark modules. Opaque hex only — try var(--foreground), rgb(0 0 0), or a light value, and watch it get refused.'
+          @onInput={{this.setForeground}}
+        />
+        <Args.String
+          @name='background'
+          @value={{this.background}}
+          @defaultValue='#ffffff'
+          @description='Light modules. The pair must be dark-on-light at 3:1 or better or both are discarded.'
+          @onInput={{this.setBackground}}
+        />
+        <Args.String
+          @name='valueDisplay'
+          @value={{this.valueDisplay}}
+          @options={{this.displays}}
+          @defaultValue='auto'
+          @description="How the encoded value appears as text. 'none' hides it visually but keeps it in the accessibility tree — it is never removed outright."
+          @onInput={{this.setValueDisplay}}
+        />
+        <Args.String
+          @name='caption'
+          @value={{this.caption}}
+          @description='Caption text under the symbol. The caption block wins over it.'
+          @onInput={{this.setCaption}}
+        />
+        <Args.Bool
+          @name='overlay'
+          @value={{this.overlay}}
+          @defaultValue={{false}}
+          @description='Declares that an overlay block is supplied. Named blocks are invisible to component JS, so this flag is what raises error correction to H and reserves the centre — and the block renders only when it is set, so forgetting it makes the mark visibly vanish instead of silently producing an unscannable code.'
+          @onInput={{this.setOverlay}}
+        />
+        <Args.Object
+          @name='onRender'
+          @value={{this.info}}
+          @description='Reports version, module count, quiet zone, level, the colours actually used, and whether a caller pair was refused. Fires once per meaningful change, from a modifier taking only primitives.'
+        />
+        <Args.Yield
+          @name='caption'
+          @description='Replaces @caption.'
+        />
+        <Args.Yield
+          @name='overlay'
+          @description='A mark centred over the symbol, capped at 20 percent of its edge. Requires @overlay.'
+        />
+      </:api>
+    </FreestyleUsage>
+
+    <style scoped>
+      .qr-mark {
+        font-family: var(--font-sans);
+        font-weight: 700;
+        font-size: 12px;
+        line-height: 1;
+        color: var(--boxel-dark);
+      }
+      .cap-readout {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        margin: 10px 0 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .cap-readoutLabel {
+        font-family: var(--font-mono);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_QR_CODE: Record<string, unknown> = {
+  QrCode: QrCodeUsage,
+};

package/bundled-realms/pretui/components/queued-message.gts

@@ -0,0 +1,83 @@
+// Pretui — QueuedMessage: a message waiting to be sent while the agent is busy.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { Button } from './button';
+
+export interface QueuedMessageSignature {
+  Args: {
+    text: string;
+    mode?: 'steer' | 'now';
+    onSendNow?: () => void;
+    onEdit?: () => void;
+  };
+  Element: HTMLDivElement;
+}
+
+// Per-message delivery semantics, stated in the UI: Send now interrupts;
+// Steer is delivered at the next checkpoint.
+export class QueuedMessage extends Component<QueuedMessageSignature> {
+  get mode() {
+    return this.args.mode ?? 'steer';
+  }
+  get modeLabel() {
+    return this.mode === 'now' ? 'send now' : 'steer';
+  }
+  get semantics() {
+    return this.mode === 'now' ? 'interrupts the run' : 'delivered at next checkpoint';
+  }
+  get canSendNow() {
+    return this.mode !== 'now' && this.args.onSendNow;
+  }
+  edit = () => this.args.onEdit?.();
+  sendNow = () => this.args.onSendNow?.();
+  <template>
+    <div class='pretui-queued' data-test-pretui-queued-message ...attributes>
+      <span class='pretui-queued-mode'>{{this.modeLabel}}</span>
+      <span class='pretui-queued-text'>{{@text}}</span>
+      <span class='pretui-queued-note'>{{this.semantics}}</span>
+      {{#if @onEdit}}<Button @variant='ghost' class='pretui-queued-btn' {{on 'click' this.edit}}>Edit</Button>{{/if}}
+      {{#if this.canSendNow}}<Button @variant='ghost' class='pretui-queued-btn' {{on 'click' this.sendNow}}>Send now</Button>{{/if}}
+    </div>
+    <style scoped>
+      /* above Button's layer, so these win by layer order, not file order */
+      @layer PretComponent, PretComposite;
+      @layer PretComposite {
+        .pretui-queued {
+          display: flex;
+          align-items: center;
+          gap: 8px;
+          padding: 7px 10px;
+          border-radius: 8px;
+          background: var(--field, var(--boxel-light));
+          box-shadow: 0 0 0 1px var(--border);
+          font-size: var(--text-ui-md, 12.5px);
+        }
+        .pretui-queued-mode {
+          font-family: var(--font-mono);
+          font-size: 9.5px;
+          font-weight: 600;
+          letter-spacing: 0.06em;
+          text-transform: uppercase;
+          color: var(--pretui-primary-ink, var(--primary));
+          flex: none;
+        }
+        .pretui-queued-text {
+          flex: 1;
+          min-width: 0;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+        .pretui-queued-note {
+          font-size: var(--text-ui-xs, 11px);
+          color: var(--ink-3, var(--boxel-400));
+          flex: none;
+        }
+        :deep(.pretui-queued-btn) {
+          height: 22px;
+          padding: 0 7px;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/queued-message.md

@@ -0,0 +1,53 @@
+## What it is
+
+A message the user has typed while the agent is busy, shown with its **delivery semantics stated in the UI**: `steer` is delivered at the next checkpoint, `now` interrupts. Use it in the composer area of an agent surface for anything queued behind a running turn. If the message has already been delivered, it is a transcript row, not this. If the agent is asking _you_ something, **AgentQuestion**.
+
+## The contract
+
+```
+@text: string   (required)
+@mode? 'steer' | 'now'   (default 'steer')
+@onSendNow?, @onEdit?
+```
+
+**The mode's meaning is rendered, not implied.** The component carries a `semantics` line explaining what each mode does — "Send now interrupts; Steer is delivered at the next checkpoint" — because the two modes have materially different consequences and a badge reading `steer` teaches nobody. That is the territory's colour-never-carries-state-alone law applied to a delivery guarantee.
+
+**`steer` is the default**, and that is the safe default: interrupting a running agent discards partial work, and a user who has not thought about it should get the non-destructive behaviour.
+
+`@onEdit` exists because a queued message is still editable — it has not been sent — and a queue with no edit is a queue you have to delete from.
+
+## Prior art
+
+This has essentially no precedent in component libraries, and only a thin one in products. The recognisable analogues are **email's "undo send" window**, **Slack's scheduled-send**, and the general messaging-queue pattern of a message in a pending state.
+
+What is genuinely novel is the **two delivery semantics as a first-class distinction**. Most agent composers have one behaviour — either your message interrupts, or it queues — and the user learns which by experiment. Naming both, defaulting to the safe one, and stating the difference in the UI is the right design for an interaction where getting it wrong costs the agent's current work.
+
+Where it is thin:
+
+- **No queue.** This is one message; the ordering, count and "3 messages queued" summary are the caller's.
+- **No delivery confirmation.** The component shows a message as queued and has no state for "delivered".
+- **No cancel.** `@onEdit` implies editing; there is no `@onDiscard`.
+- **No checkpoint indication.** `steer` promises delivery "at the next checkpoint" and nothing shows when that will be, so the promise is unfalsifiable from the UI.
+
+## Accessibility
+
+No pattern governs it. The relevant criteria are WCAG **4.1.3 Status Messages**, **3.3.2 Labels or Instructions** and **3.3.4 Error Prevention**.
+
+What is right: **the semantics line is text.** The consequence of each mode is available to everyone, not encoded in a badge colour — which satisfies **3.3.2** for an interaction whose consequences are not obvious.
+
+Gaps:
+
+- **The message's queued state is not announced.** A user types, presses Enter, and the message moves into a pending state — a status change (**4.1.3**) with no live region. For a screen-reader user the message simply is not sent, with no explanation, which is the worst possible reading of the interaction. A `role="status"` region saying "Queued — will be delivered at the next checkpoint" is close to mandatory here.
+- **Delivery is not announced either.** When the checkpoint arrives and the message goes, nothing says so.
+- **"Send now" is a consequential action with no confirmation.** It interrupts a running agent and discards partial work; **WCAG 3.3.4** asks for confirmation or reversibility for actions with significant consequences. Nothing here confirms, and the button sits directly beside "Edit".
+- **The mode is not a control.** `@mode` is an arg the caller sets, so a user cannot switch a queued message from steer to now except through `@onSendNow`, which is a different action. That is a coherent design, but it means the displayed mode reads like a toggle and is not one — verify it is not marked up as one.
+- **`@text` may be long** and there is no expressed truncation or expansion behaviour; a queued paragraph should not be silently clipped.
+- **Button labels are generic.** "Send now" and "Edit" outside their context do not name the message; `aria-describedby` pointing at the text would help on a screen with several queued messages.
+
+## Theming
+
+`--inset` or `--card` (the pending surface — a queued message should read as _not yet_ part of the transcript), `--border`, `--muted-foreground` (the semantics line), `--foreground` (the message text), plus **Button** tokens for the two actions and the mode's own dress.
+
+The visual distinction that matters is **pending versus sent**. A queued message must not look like a transcript row, or the user will believe it has gone. A theme should give it a distinct surface, a dashed edge, or reduced weight — and should check that the distinction survives in dark mode, where the usual "slightly lighter gray" solution collapses.
+
+The styles sit in `@layer PretComposite`, above Button's `PretComponent` layer, so what this component sets on Button wins by layer order. A caller's unlayered CSS overrides both without a more specific selector.

package/bundled-realms/pretui/components/queued-message.usage.gts

@@ -0,0 +1,21 @@
+// Pretui — QueuedMessage usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { QueuedMessage } from './queued-message';
+import { DemoReceipt, DemoStack } from '../demo-foundations-more';
+
+class QueuedMessageUsage extends Component {
+  @tracked receipt = 'Waiting for the next checkpoint';
+  send = () => (this.receipt = 'Interrupt requested');
+  <template>
+    <FreestyleUsage @name='QueuedMessage' @description='A queued instruction that names its delivery semantics instead of hiding them in an icon or colour.' @source='<QueuedMessage @text="Also check the reserve price" @mode="steer" … />' @viewportMode='wide'>
+      <:example><DemoStack><QueuedMessage @text='Also check the reserve price' @mode='steer' @onSendNow={{this.send}} /><DemoReceipt>{{this.receipt}}</DemoReceipt></DemoStack></:example>
+      <:api as |Args|><Args.String @name='text' @value='Also check the reserve price' /><Args.String @name='mode' @value='steer' /><Args.Action @name='onSendNow' /><Args.Action @name='onEdit' /></:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_QUEUED_MESSAGE: Record<string, unknown> = {
+  QueuedMessage: QueuedMessageUsage,
+};

package/bundled-realms/pretui/components/radio-card.gts

@@ -0,0 +1,88 @@
+// Pretui — RadioCard: a one-of-N choice where each option is a card.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { fn } from '@ember/helper';
+import { guidFor } from '@ember/object/internals';
+import { emit, firstDefined } from '../pretui-primitives';
+import { ChoiceGrid, OptionCard } from '../internal/choice-cards';
+import type { ChoiceCardOption, ChoiceCardOrientation, ChoiceCardsSharedArgs } from '../internal/choice-cards';
+
+export interface RadioCardSignature {
+  Args: ChoiceCardsSharedArgs & {
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    /** alias */
+    onChange?: (value: string) => void;
+  };
+  Blocks: {
+    /** replaces the generated title and description of every card */
+    default: [option: ChoiceCardOption, selected: boolean];
+    /** an icon or thumbnail on the card's start edge */
+    media: [option: ChoiceCardOption];
+  };
+  Element: HTMLDivElement;
+}
+
+export class RadioCard extends Component<RadioCardSignature> {
+  @tracked internal = this.args.defaultValue;
+  generatedName = `${guidFor(this)}-rc`;
+  get name() {
+    return this.args.name ?? this.generatedName;
+  }
+  get options(): ChoiceCardOption[] {
+    return firstDefined(this.args.options, this.args.items) ?? [];
+  }
+  get value() {
+    return this.args.value ?? this.internal;
+  }
+  get groupDisabled() {
+    return firstDefined(this.args.disabled, this.args.isDisabled) ?? false;
+  }
+  get orientation(): ChoiceCardOrientation {
+    return this.args.orientation ?? 'vertical';
+  }
+  pick = (option: ChoiceCardOption, ev: Event) => {
+    if (this.args.value === undefined) {
+      this.internal = option.value;
+    }
+    emit([this.args.onValueChange, this.args.onChange], option.value);
+    if (this.args.value !== undefined) {
+      // controlled: the platform already moved the radios; put them back until
+      // the owner moves @value, so the checked input matches the painted card
+      let group = (ev.target as HTMLElement).closest('.pretui-choicecards');
+      group
+        ?.querySelectorAll<HTMLInputElement>('input[type="radio"]')
+        .forEach((input) => (input.checked = input.value === this.value));
+    }
+  };
+  isOn = (option: ChoiceCardOption) => this.value === option.value;
+  isDisabled = (option: ChoiceCardOption) =>
+    this.groupDisabled || Boolean(option.disabled);
+  <template>
+    <ChoiceGrid
+      role='radiogroup'
+      aria-label={{@label}}
+      data-orientation={{this.orientation}}
+      data-columns={{@columns}}
+      data-test-pretui-radio-card
+      ...attributes
+    >
+      {{#each this.options as |option|}}
+        <OptionCard
+          @kind='radio'
+          @name={{this.name}}
+          @option={{option}}
+          @selected={{this.isOn option}}
+          @disabled={{this.isDisabled option}}
+          @onChange={{fn this.pick option}}
+          @custom={{has-block}}
+          @hasMedia={{has-block 'media'}}
+        >
+          <:default as |o selected|>{{yield o selected}}</:default>
+          <:media as |o|>{{yield o to='media'}}</:media>
+        </OptionCard>
+      {{/each}}
+    </ChoiceGrid>
+  </template>
+}

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

@@ -0,0 +1,72 @@
+## What it is
+
+One-of-N where every option is a card. The card is the label and the whole hit target; a real radio sits inside it, visually hidden, and a small mark in the card's corner shows the state. Use it when each option needs a title, a line of description and a figure — a billing plan, a shipping speed, a region — and the choice deserves the room. If the options are short words, **RadioGroup** is the same contract at a fraction of the size. If the options are peers that switch a view rather than set a value, **SegmentedControl**. If more than one option can be chosen, **CheckboxCard** is this component with an array value. If the card is content rather than a choice, **Card**.
+
+## The contract
+
+```
+@options?          — ChoiceCardOption[]: { value, title, description?, meta?, disabled? }
+@items?            — alias of @options
+@value?            — controlled selection; omit for the uncontrolled half
+@defaultValue?     — uncontrolled seed
+@onValueChange?    — fires with the chosen value; @onChange is the alias
+@disabled?         — every card; @isDisabled is the alias
+@label?            — the radiogroup's accessible name when no label element points at it
+@name?             — the form field the radios submit under; a generated name groups them otherwise
+@orientation?      — 'vertical' (default) | 'horizontal'
+@columns?          — 2 | 3 | 4, a fixed count for 'horizontal'
+<:default as |option selected|>   — replaces the generated title and description
+<:media as |option|>              — an icon or thumbnail on the card's start edge
+```
+
+**Hybrid state.** With `@value` undefined the group keeps its own selection, seeded by `@defaultValue`. With `@value` set the group never moves itself: it reports the request through `@onValueChange`, puts the native radios back to the controlled value, and waits for the parent to change the arg. So the checked input always matches the painted card, and a withheld card can be requested again. The callback fires in both modes.
+
+**`@name` makes it a form field.** A `<form>` around the group submits the chosen value under `@name`. Without it the radios share a generated name, which groups them for the keyboard but submits under a meaningless key.
+
+**One option is disabled through `disabled` on the option; the group through `@disabled`.** Either disables the real radio, so the platform skips it, and stamps `data-disabled` on the card.
+
+**Selection is a hairline, not a border.** The chosen card wears a 1px ring in `--primary` and a soft 4px halo of the same hue at 12%; the rest of the card does not change. The corner mark is the same 15px disc **RadioGroup** draws, so a card group and a plain group read as one family.
+
+**State attributes are strings both ways.** `data-selected='true' | 'false'` and `data-disabled='true' | 'false'` on every card; `data-orientation` and `data-columns` on the root.
+
+## Prior art
+
+**Chakra `RadioCard`** is a root with `RadioCard.Item`, `ItemText`, `ItemDescription`, `ItemIndicator` and an `ItemHiddenInput`, with `variant` (`surface` / `subtle` / `outline` / `solid`) and `orientation`; the addon slot is a separate `ItemAddon` band. **Tremor `RadioCardGroup`** is the same idea over Radix `RadioGroup`, a plain card per item and a `RadioCardIndicator` you place yourself. The **origin-ui** recipes hand-roll the pattern from shadcn `RadioGroup` plus a `Label` styled with `has-[[data-state=checked]]`.
+
+Where this is better: **it is a single component, not an assembly.** An option is a value, a title, a description and a figure, and the card is generated from that; the hidden input, the indicator and the selected ring do not have to be composed by hand each time, which is where the recipes go wrong (an indicator outside the label, a card that is not the hit target). The keyboard model is the platform's because the inputs are real radios sharing a name, not a Radix roving-tabindex reimplementation.
+
+Where it is thinner: **one visual recipe.** There is no `variant` axis — no filled or solid card — and no per-card tone. The **media** slot is a start-edge slot only; there is no addon band under the body. The card's title and description are strings unless you take over the whole body with the default block. There is no `size` axis.
+
+## Accessibility
+
+Governing pattern: a native radio group. The root is `role="radiogroup"` and takes `@label` as `aria-label`; each card is a `<label>` wrapping a real `<input type="radio">`, and every radio in the group shares one generated `name`.
+
+What that buys, without any script: **the platform keyboard model.** Tab lands on the checked radio (or the first, when none is checked), arrow keys move the selection between cards and check as they go, and the roving tabindex is the browser's. Clicking anywhere on the card is a click on its label, which checks the radio.
+
+- **Focus stays visible.** The input is positioned off the card at 1px with zero opacity — it is in the tab order and in the accessibility tree — and the card paints the focus ring itself through `:has(.pretui-optioncard-input:focus-visible)`.
+- **The accessible name of each radio is the card's text**: title, description and meta, in that order, because all of it is inside the label. A long description makes a long announcement; that is the caller's to keep short.
+- **The mark is `aria-hidden`.** It repeats the checked state visually and contributes nothing to the tree.
+- **`data-selected` is a stamp, not a role.** Assistive tech reads the radio's own checked state.
+- **A media block's content is inside the label**, so an icon with a text alternative becomes part of the radio's name. Pass `aria-hidden` on decorative icons.
+
+The tests assert the radiogroup role, the shared name, one radio per label, the click-to-check path, disabled propagation and the data stamps. Arrow-key movement is the platform's and is not re-asserted.
+
+## Theming
+
+From the host theme: `--card` and `--card-foreground` (the card surface and its ink), `--border` (the resting hairline), `--hover` (the hover fill), `--primary` (the selected ring, halo and mark fill), `--primary-foreground` (unused on a radio mark; the checkbox check), `--field` and `--input` (the resting mark), `--ring` (the focus outline), `--muted-foreground` (description and meta).
+
+Kit tokens, each named once on the card: `--space-4` (padding), `--space-3` (gap), `--text-ui-md` and `--text-ui-sm` (title and description), `--weight-strong` (title weight), `--radius-surface` (card radius), `--pretui-dur-snap` and `--pretui-ease-snap` (the ring and fill transitions), `--pretui-shadow-control` (the resting shadow), `--pretui-edge-highlight` (the inset highlight on a selected mark). The grid reads `--space-3` for its gap.
+
+A theme retunes the selected treatment entirely through `--primary`; the 12% halo mix, the 15px mark and the 11rem minimum card width in `horizontal` are fixed.
+
+## React ecosystem
+
+| React                   | Pretui                                                  |
+| ----------------------- | ------------------------------------------------------- |
+| value / onChange        | `@value` / `@onValueChange` (`@onChange` accepted)      |
+| defaultValue            | `@defaultValue`                                         |
+| items                   | `@items` (alias of `@options`)                          |
+| orientation             | `@orientation`                                          |
+| disabled / isDisabled   | `@disabled` / `@isDisabled`                             |
+| RadioCard.Item children | the default block, yielded the option                   |
+| ItemAddon / indicator   | not separate — `meta` on the option and the corner mark |