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

package/bundled-realms/pretui/components/app-shell.md

@@ -0,0 +1,43 @@
+## What it is
+
+**AppShell** is **PageScaffold** under the name Mantine uses (Ant calls it `Layout`). The export is the same component. Import it when a port already says AppShell; the **PageScaffold** writeup carries the depth. The five named regions Mantine AppShell and Ant Layout lay out, header, navbar, main, aside and footer, are the regions PageScaffold already has, with the same landmarks.
+
+A thin wrapper with Mantine's argument shape was considered and deliberately not shipped. Glimmer cannot conditionally forward a named block, so a wrapper would make PageScaffold emit empty `<nav>`, `<aside>` and `<footer>` landmarks for regions the caller never supplied, which is worse than no wrapper. The full reasoning is at the top of `components/app-shell.gts`.
+
+## The contract
+
+```
+@preset?, @label?, @navLabel?, @asideLabel?
+@navWidth?, @asideWidth?, @maxWidth?
+@stickyMasthead?, @divided?, @skipLink?
+<:masthead> <:subhead> <:navigation> <:default> <:aside> <:footer>
+Element: HTMLDivElement
+```
+
+Identical to PageScaffold. Each region renders only when its block is supplied.
+
+## Prior art
+
+**Mantine `AppShell`** takes `header`, `navbar`, `aside` and `footer` config objects (`height`, `width`, `breakpoint`, `collapsed`) with `AppShell.Header`, `.Navbar`, `.Main`, `.Aside`, `.Footer` and `.Section` children. It injects its layout config as a stylesheet on every render. **Ant `Layout`** has `Header`, `Sider`, `Content` and `Footer`.
+
+The mapping: Mantine's `AppShell.Header` is the `<:masthead>` block, `.Navbar` is `<:navigation>` (with **Sidebar** inside it for a collapsible rail), `.Main` is the default block, `.Aside` is `<:aside>` and `.Footer` is `<:footer>`. `AppShell.Section grow` is a **Stack** cell with `flex: 1`. Collapse belongs to **Sidebar**, not to the frame.
+
+## Accessibility
+
+Identical to PageScaffold. Each region is its landmark, `<header>`, `<nav>`, `<main>`, `<aside>` or `<footer>`, named by `@label`, `@navLabel` and `@asideLabel`, and rendered only when supplied, so there are no empty landmarks. `@skipLink` adds a **SkipLink** to the main region, and `<main>` takes `tabindex="-1"` so the skip moves focus, which neither Mantine nor Ant does.
+
+## Theming
+
+Identical to PageScaffold: `--pretui-page-nav-width`, `--pretui-page-aside-width`, `--pretui-page-gap`, `--pretui-page-column-gap`, `--pretui-page-bg`, `--pretui-page-radius`, `--pretui-page-shadow` and `--pretui-page-sticky-top`, with the boxel `--boxel-layout-*` values as fallbacks.
+
+## React ecosystem
+
+| Mantine / Ant                      | Pretui                                   |
+| ---------------------------------- | ---------------------------------------- |
+| `<AppShell.Header>` / Ant `Header` | `<:masthead>`                            |
+| `<AppShell.Navbar>` / Ant `Sider`  | `<:navigation>`, with **Sidebar** inside |
+| `<AppShell.Main>` / Ant `Content`  | the default block                        |
+| `<AppShell.Aside>`                 | `<:aside>`                               |
+| `<AppShell.Footer>` / Ant `Footer` | `<:footer>`                              |
+| `navbar={{ collapsed }}`           | **Sidebar**'s `@open` / `@collapsible`   |
+| `AppShell.Section grow`            | a **Stack** cell with `flex: 1`          |

package/bundled-realms/pretui/components/app-shell.usage.gts

@@ -0,0 +1,52 @@
+// Pretui — AppShell usage page.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { FreestyleUsage } from './freestyle-usage';
+import { AppShell } from './app-shell';
+
+const SOURCE = `<AppShell @label='Roastery' @navLabel='Sections'>
+  <:masthead>…</:masthead>
+  <:navigation>…</:navigation>
+  <:default>…</:default>
+</AppShell>`;
+
+const AppShellUsage: TemplateOnlyComponent = <template>
+  <FreestyleUsage
+    @name='AppShell'
+    @description='PageScaffold under the Mantine name (Ant calls it Layout): the named regions masthead, navigation, main, aside and footer, each its landmark and rendered only when supplied. Import it when a port already says AppShell; the component and its writeup are PageScaffold. A collapsible rail is Sidebar inside the navigation block.'
+    @source={{SOURCE}}
+  >
+    <:example>
+      <div class='as-demo'>
+        <AppShell @label='Roastery' @navLabel='Sections'>
+          <:masthead><strong>Northwind Roasters</strong></:masthead>
+          <:navigation><ul class='as-demo-nav'><li>Lots</li><li>Roasts</li><li>Orders</li></ul></:navigation>
+          <:default><p>Lot 7 · Huila, washed · roasting Thursday</p></:default>
+        </AppShell>
+      </div>
+    </:example>
+    <:api as |Args|>
+      <Args.String @name='label' @description='Names the main region.' />
+      <Args.String @name='navLabel' />
+      <Args.String @name='asideLabel' />
+      <Args.Bool @name='skipLink' @description='Adds a SkipLink to the main region.' />
+      <Args.Yield @name='masthead' />
+      <Args.Yield @name='navigation' />
+      <Args.Yield @name='default' />
+      <Args.Yield @name='aside' />
+      <Args.Yield @name='footer' />
+    </:api>
+  </FreestyleUsage>
+  <style scoped>
+    .as-demo {
+      block-size: 14rem;
+    }
+    .as-demo-nav {
+      margin: 0;
+      padding-inline-start: 1rem;
+    }
+  </style>
+</template>;
+
+export const DEMOS_APP_SHELL: Record<string, unknown> = {
+  AppShell: AppShellUsage,
+};

package/bundled-realms/pretui/components/approval-footer.gts

@@ -0,0 +1,69 @@
+// Pretui — ApprovalFooter: the approve / reject bar for a change that needs a human decision.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { Button } from './button';
+
+export interface ApprovalFooterSignature {
+  Args: {
+    count?: number;
+    message?: string;
+    destructive?: boolean;
+    onKeep?: () => void;
+    onRevert?: () => void;
+    onAcceptAll?: () => void;
+  };
+  Element: HTMLDivElement;
+}
+
+// Destructive operations always ask, regardless of autonomy level.
+export class ApprovalFooter extends Component<ApprovalFooterSignature> {
+  get message() {
+    if (this.args.message) {
+      return this.args.message;
+    }
+    let n = this.args.count ?? 1;
+    return `${n} change${n === 1 ? '' : 's'} await${n === 1 ? 's' : ''} your approval`;
+  }
+  get keepLabel() {
+    return this.args.destructive ? 'Keep anyway' : 'Keep';
+  }
+  get keepVariant(): 'destructive' | 'primary' {
+    return this.args.destructive ? 'destructive' : 'primary';
+  }
+  keep = () => this.args.onKeep?.();
+  revert = () => this.args.onRevert?.();
+  acceptAll = () => this.args.onAcceptAll?.();
+  <template>
+    <div class='pretui-approval' data-test-pretui-approval-footer ...attributes>
+      <span class='pretui-approval-msg'>{{this.message}}</span>
+      <span class='pretui-approval-actions'>
+        {{#if @onAcceptAll}}<Button @variant='ghost' {{on 'click' this.acceptAll}}>Accept all</Button>{{/if}}
+        <Button @variant='secondary' {{on 'click' this.revert}}>Revert</Button>
+        <Button @variant={{this.keepVariant}} {{on 'click' this.keep}}>{{this.keepLabel}}</Button>
+      </span>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-approval {
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+          gap: 10px;
+          padding: 8px 11px;
+          border-radius: 0 0 10px 10px;
+          box-shadow: 0 -1px 0 var(--border);
+          background: color-mix(in oklch, var(--pretui-attention, var(--boxel-fuschia)) 7%, var(--card));
+        }
+        .pretui-approval-msg {
+          font-size: var(--text-ui, 12px);
+          color: var(--foreground);
+          font-weight: 500;
+        }
+        .pretui-approval-actions {
+          display: flex;
+          gap: 7px;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/approval-footer.md

@@ -0,0 +1,49 @@
+## What it is
+
+The gate: a bar stating how many changes await approval, with Keep / Revert / Accept-all actions. Use it at the end of a run of **WorkItem**s an agent has staged but not committed. If the agent needs an _answer_ rather than an approval, **AgentQuestion**. If it is reporting something it already did, **ResultCard**. If the whole surface is blocking, that is a **Dialog** and probably too heavy for a transcript.
+
+## The contract
+
+```
+@count?, @message?, @destructive?
+@onKeep?, @onRevert?, @onAcceptAll?
+```
+
+**The default message is generated with correct grammar**: `1 change awaits your approval` / `3 changes await your approval` — the noun _and_ the verb both inflect. That is a small thing that most generated strings get wrong ("1 changes await"), and it matters here because this sentence is the last thing a user reads before committing an agent's work.
+
+**`@destructive` is the territory's hard rule, stated in the source: destructive operations always ask, regardless of autonomy level.** An agent configured to act freely still surfaces this footer when the change cannot be undone. That is a policy encoded in a component rather than left to a config flag, which is the right place for it.
+
+`@onAcceptAll` is separate from `@onKeep` deliberately — "keep this" and "accept everything" are different commitments and should not be the same button.
+
+## Prior art
+
+No component library ships an approval gate. The references are product surfaces: Claude Code's diff-approval prompt, Cursor's accept/reject bar, GitHub's "Files changed" review controls, and the general pattern of a **staged-changes gate** from version control.
+
+The design decisions worth comparing against those:
+
+- **Git's model is the right ancestor**, and the vocabulary follows it: changes are _staged_, then kept or reverted, and the receipt survives. Compare the common agent-UI pattern of an undo toast, which puts a time limit on the decision.
+- **Three actions, not two.** Most accept/reject bars offer a binary; separating "keep" from "accept all" acknowledges that a user reviewing a long run wants to commit incrementally and then bulk-commit the rest.
+- **The count is in the sentence, not in a badge.** "3 changes await your approval" is a claim the user can check; a badge reading "3" beside two buttons is not.
+
+Where it is thin: **no per-change navigation** (you cannot step through what you are approving from here — that is **DiffBlock**'s job and there is no link between them), no "review each", no keyboard shortcut affordance, and no busy state while the commit is in flight.
+
+## Accessibility
+
+No APG pattern. The relevant criteria are WCAG **3.3.4 Error Prevention** (this _is_ the error-prevention mechanism for agent actions), **4.1.3 Status Messages** and **2.4.3 Focus Order**.
+
+Gaps, and the first two are serious given what this component gates:
+
+- **The footer's appearance is not announced.** This is the moment the agent stops and needs a human, and it arrives silently — a screen-reader user reading a transcript has no signal that work has paused pending their decision. A live region announcing "3 changes await your approval" is not optional for this component; it is the point of it. `role="alert"` (assertive) is defensible here in a way it is not for most components, since the user genuinely cannot proceed. **This is the highest-value fix in the territory.**
+- **`@destructive` is a visual state with no announced counterpart.** The destructive dress presumably tints the bar; nothing tells a screen-reader user that the pending changes cannot be undone. Given that "destructive operations always ask" is the stated law, the _reason_ they are being asked must reach everyone — put it in the message text, not in the color.
+- **Focus is not moved to the footer.** When an agent stops and asks, the user's focus is wherever it was. **Form**'s `focusInvalid()` solves the equivalent problem for refused submits, and the same treatment applies here.
+- **Accept-all has no confirmation.** A single button commits every staged change; combined with the lack of announcement, a screen-reader user can commit an agent's entire run without ever hearing what it contained. **WCAG 3.3.4** asks for reversibility, checking or confirmation for actions with significant consequences.
+- **The button labels are generic.** "Keep" and "Revert" outside their sentence do not say what is being kept — `aria-describedby` pointing at the message would fix it.
+- **No busy state.** Nothing prevents a double-commit while the first is in flight; **Button** has `@busy` and it is not wired here.
+
+## Theming
+
+`--card` or `--inset` (the bar), `--border` and `--pretui-shadow-hairline` (its edge), `--foreground` and `--muted-foreground` (the message), plus **Button**'s full token set for the three actions. The destructive dress reads `--destructive`.
+
+The three buttons use the kit's **Button**, so tone and appearance travel with the theme — Keep is the affirmative, Revert the quiet outlined one, and the destructive variant re-tones them. A theme must keep the destructive dress clearly distinct from the normal one at a glance; this is the one bar in the product where mistaking the state is expensive.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/approval-footer.usage.gts

@@ -0,0 +1,22 @@
+// Pretui — ApprovalFooter usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { ApprovalFooter } from './approval-footer';
+import { DemoReceipt, DemoStack } from '../demo-foundations-more';
+
+class ApprovalFooterUsage extends Component {
+  @tracked receipt = 'Awaiting a decision';
+  keep = () => (this.receipt = 'Kept 3 changes');
+  revert = () => (this.receipt = 'Reverted 3 changes');
+  <template>
+    <FreestyleUsage @name='ApprovalFooter' @description='A decision boundary for staged changes. It states the count and keeps destructive intent explicit in button text.' @source='<ApprovalFooter @count={{3}} @onKeep={{this.keep}} … />'>
+      <:example><DemoStack><ApprovalFooter @count={{3}} @onKeep={{this.keep}} @onRevert={{this.revert}} /><DemoReceipt>{{this.receipt}}</DemoReceipt></DemoStack></:example>
+      <:api as |Args|><Args.Number @name='count' @value={{3}} /><Args.Bool @name='destructive' @defaultValue={{false}} /><Args.Action @name='onKeep' /><Args.Action @name='onRevert' /><Args.Action @name='onAcceptAll' /></:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_APPROVAL_FOOTER: Record<string, unknown> = {
+  ApprovalFooter: ApprovalFooterUsage,
+};

package/bundled-realms/pretui/components/aspect-ratio.gts

@@ -0,0 +1,328 @@
+// Pretui — AspectRatio: a frame that reserves a ratio and fits its media (AspectBox is the same component).
+import Component from '@glimmer/component';
+import { cssDeclaration, cssStyleFrom } from '../pretui-css';
+
+// ── AspectRatio ──────────────────────────────────────────────────────────
+//
+// Sources read: radix-primitives/packages/react/aspect-ratio, shadcn
+// aspect-ratio.tsx, mantine AspectRatio.
+//
+// Law 8 in one component — a value that arrives late reserves its space —
+// and deliberately built to be the shared frame another agent asked for under
+// the name `AspectBox`: Gallery, AssetWell, MediaPlayer, CopyFit and
+// Skeleton all want the same box. It is exported under BOTH names at the
+// bottom of this file so neither search misses.
+//
+// What is fixed relative to the sources:
+//
+//   1. **Radix and Chakra still ship the padding-bottom hack.** Radix wraps
+//      the content in an opaque outer div with
+//      `paddingBottom: 100 / ratio + '%'` and pins the inner element to
+//      `top/right/bottom/left: 0` — physical, and written AFTER the
+//      consumer's own `style` is spread, so position and offsets cannot be
+//      changed at all. The wrapper accepts no className, no style, no ref, so
+//      the box that actually has the size is unstyleable from outside except
+//      through an undocumented data attribute. Chakra moves the same hack to
+//      a `::before`. Both predate the `aspect-ratio` property; both cost an
+//      element, break `object-fit` composition, and make height-driven
+//      sizing ("fill this row, derive the width") impossible. This uses the
+//      property: one element, composable with everything.
+//      `100 / ratio` also yields `Infinity%` for `ratio = 0` in all of them,
+//      unvalidated — a rejected ratio here just leaves the box at its
+//      stylesheet default.
+//   2. **`ratio` is a bare number upstream**, so `16/9` has to be evaluated
+//      in JS and shows up in DevTools as `1.7777777777777777` with the
+//      authoring intent gone. Here `@ratio` accepts either a number or the
+//      CSS spelling (`'16 / 9'`), because that is what an agent will type,
+//      and it reaches CSS through the kit's caller-value guard rather than
+//      string interpolation.
+//      Mantine does use the property, but sets `--ar-ratio` on the parent and
+//      consumes it in `> :where(*:not(style))` — so one AspectRatio ratios
+//      EVERY child, and at zero specificity. The frame here is the sized box
+//      itself, so there is nothing to leak onto.
+//   3. **No image handling at all upstream.** Radix frames whatever you put
+//      in it, which means every consumer re-decides `<img>` vs
+//      `background-image`, alt text and lazy loading — and most of them get
+//      the accessible name wrong. The `@fit` split makes it one decision:
+//      • `actual` renders a REAL `<img>` with the intrinsic `width`/`height`
+//        attributes, `loading='lazy'`, `decoding='async'` and real `alt`.
+//        This is the accessible default and the only mode that gives the
+//        browser an aspect ratio before the bytes land.
+//      • `contain` / `cover` paint a `background-image` on a `role='img'`
+//        div — the right choice for art direction, where the image is a
+//        surface rather than content.
+//      **An empty alt drops `role='img'` entirely.** A `role='img'` with no
+//      accessible name is a nameless landmark every screen reader announces
+//      as "image" and nothing else; a decorative background is better off as
+//      a plain div.
+//   4. **`url()` is built here, never interpolated.** `cssValue` deliberately
+//      rejects `url`, `:` and quotes, so this file owns a narrow URL guard
+//      (`cssUrl` below) that parses the value with the platform's own `URL`
+//      and emits a quoted `url("…")` only for a protocol on the allowlist.
+//   5. **`object-fit` is hardcoded to `cover` by Mantine and Chakra** with no
+//      escape short of overriding their rule; Radix does nothing at all, so
+//      an image simply overflows unless the consumer remembers. Here it is
+//      the `--pretui-aspect-object-fit` knob, defaulting to `cover`. And
+//      Chakra's `Children.only` throws outright on `{loading ? null : …}` —
+//      a conditional child is a hard runtime error. A block here can be
+//      empty, one node, or many.
+
+/**
+ * Protocols an image may be fetched over. `javascript:` and `vbscript:` are
+ * the obvious exclusions; `file:` is excluded because a realm card can never
+ * legitimately reach one.
+ */
+const IMAGE_PROTOCOLS = new Set(['http:', 'https:', 'data:', 'blob:']);
+
+/** Characters that would break out of a quoted `url("…")` token, plus the
+ * whitespace CSS would treat as a token boundary. A real URL encodes all of
+ * these, so rejecting them costs nothing. */
+const URL_FORBIDDEN = /["'\\()<>\s]/;
+
+/** Longer than any legitimate src, including a modest inline data URI. */
+const MAX_URL_LENGTH = 8192;
+
+/**
+ * Validate a caller-supplied image URL and return a quoted `url("…")` token,
+ * or `undefined`. Allowlist, never a sanitiser — a value is passed through
+ * whole or dropped whole, exactly like `cssValue` in `pretui-css.gts`.
+ *
+ * This lives here rather than in the shared guard because the shared guard is
+ * deliberately hostile to `url()`: admitting it kit-wide would let every
+ * `@hue`-shaped arg in the kit fetch a remote resource. Only a component that
+ * is ABOUT an image should be able to write one.
+ */
+export function cssUrl(raw: unknown): string | undefined {
+  if (typeof raw !== 'string') {
+    return undefined;
+  }
+  let value = raw.trim();
+  if (value.length === 0 || value.length > MAX_URL_LENGTH) {
+    return undefined;
+  }
+  if (URL_FORBIDDEN.test(value)) {
+    return undefined;
+  }
+  let parsed: URL;
+  try {
+    // A base is supplied so a relative path (`/photos/a.jpg`) resolves and can
+    // be protocol-checked; the base itself is never emitted.
+    parsed = new URL(value, 'https://pretui.invalid/');
+  } catch {
+    return undefined;
+  }
+  if (!IMAGE_PROTOCOLS.has(parsed.protocol)) {
+    return undefined;
+  }
+  // A data: URI may only carry an image, so a `data:text/html` payload cannot
+  // ride in through a `background-image` that some browser decides to honour.
+  if (parsed.protocol === 'data:' && !value.startsWith('data:image/')) {
+    return undefined;
+  }
+  return 'url("' + value + '")';
+}
+
+export type AspectFit = 'actual' | 'contain' | 'cover';
+
+export interface AspectRatioSignature {
+  Args: {
+    /**
+     * The ratio to reserve. A number (`1.7778`) or the CSS spelling
+     * (`'16 / 9'`). Default `1`. Validated by the kit guard; a rejected value
+     * leaves the box at `auto` rather than breaking the stylesheet.
+     */
+    ratio?: number | string;
+    /**
+     * `actual` (default) renders a real `<img>`; `contain` and `cover` paint a
+     * `background-image` on a `role='img'` box. Ignored when there is no
+     * `@src` and a `<:default>` block is supplied instead.
+     */
+    fit?: AspectFit;
+    /** Image source. Omit to frame `<:default>` content instead. */
+    src?: string;
+    /**
+     * The image's accessible name. An EMPTY or omitted alt means decorative:
+     * `actual` keeps `alt=''` (the correct decorative `<img>`), and
+     * `contain`/`cover` drop `role='img'` entirely rather than leave an
+     * unnamed image role in the tree.
+     */
+    alt?: string;
+    /** Intrinsic pixel width, for `actual`. Lets the browser reserve space. */
+    width?: number;
+    /** Intrinsic pixel height, for `actual`. */
+    height?: number;
+    /** `lazy` (default) or `eager`. */
+    loading?: 'lazy' | 'eager';
+    /** Ground colour behind a `contain` letterbox. Any kit-valid CSS colour. */
+    background?: string;
+    /** Corner radius. Any kit-valid CSS length. */
+    radius?: string;
+    /** Draw the kit hairline around the frame. */
+    bordered?: boolean;
+  };
+  Blocks: {
+    /** Arbitrary framed content — an iframe, a canvas, a chart, a map. */
+    default: [];
+  };
+  Element: HTMLDivElement;
+}
+
+/**
+ * A box that reserves its shape before its content arrives.
+ *
+ * ```hbs
+ * <AspectRatio @ratio='16 / 9' @src={{this.photo}} @alt='Estate at dawn' />
+ * <AspectRatio @ratio={{1}} @fit='cover' @src={{this.avatar}} @alt='' />
+ * <AspectRatio @ratio='4 / 3'><MapView /></AspectRatio>
+ * ```
+ */
+export class AspectRatio extends Component<AspectRatioSignature> {
+  get fit(): AspectFit {
+    return this.args.fit ?? 'actual';
+  }
+  /** `undefined` when the caller supplied nothing usable, so the stylesheet's
+   * own `1` survives rather than the box collapsing. */
+  private get ratioValue(): string | undefined {
+    let raw = this.args.ratio;
+    if (raw === undefined) {
+      return undefined;
+    }
+    return typeof raw === 'number' ? String(raw) : raw;
+  }
+  get style() {
+    return cssStyleFrom([
+      cssDeclaration('--pretui-aspect-ratio', this.ratioValue),
+      cssDeclaration('--pretui-aspect-bg', this.args.background),
+      cssDeclaration('--pretui-aspect-radius', this.args.radius),
+    ]);
+  }
+  /** The painted mode's own declaration — built here, from a guarded URL. */
+  get paintedStyle() {
+    let url = cssUrl(this.args.src);
+    return cssStyleFrom([
+      cssDeclaration('--pretui-aspect-ratio', this.ratioValue),
+      cssDeclaration('--pretui-aspect-bg', this.args.background),
+      cssDeclaration('--pretui-aspect-radius', this.args.radius),
+      url === undefined ? undefined : 'background-image: ' + url,
+    ]);
+  }
+  get alt(): string {
+    return (this.args.alt ?? '').trim();
+  }
+  /**
+   * An unnamed `role='img'` announces as a bare "image" and tells the reader
+   * nothing, so a decorative painted frame drops the role and becomes an
+   * ordinary div. This is the one line most ports of Radix get wrong.
+   */
+  get paintedRole(): string | undefined {
+    return this.alt.length > 0 ? 'img' : undefined;
+  }
+  get loading(): 'lazy' | 'eager' {
+    return this.args.loading ?? 'lazy';
+  }
+  get painted(): boolean {
+    return this.fit !== 'actual';
+  }
+
+  <template>
+    {{#if @src}}
+      {{#if this.painted}}
+        <div
+          class='pretui-aspect'
+          style={{this.paintedStyle}}
+          data-fit={{this.fit}}
+          data-bordered={{if @bordered 'true' 'false'}}
+          role={{this.paintedRole}}
+          aria-label={{if this.paintedRole this.alt}}
+          data-test-pretui-aspect-ratio
+          ...attributes
+        ></div>
+      {{else}}
+        <div
+          class='pretui-aspect'
+          style={{this.style}}
+          data-fit='actual'
+          data-bordered={{if @bordered 'true' 'false'}}
+          data-test-pretui-aspect-ratio
+          ...attributes
+        >
+          <img
+            class='pretui-aspect-img'
+            src={{@src}}
+            alt={{this.alt}}
+            width={{@width}}
+            height={{@height}}
+            loading={{this.loading}}
+            decoding='async'
+          />
+        </div>
+      {{/if}}
+    {{else}}
+      <div
+        class='pretui-aspect'
+        style={{this.style}}
+        data-fit='slot'
+        data-bordered={{if @bordered 'true' 'false'}}
+        data-test-pretui-aspect-ratio
+        ...attributes
+      >
+        {{yield}}
+      </div>
+    {{/if}}
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-aspect {
+          /* The property, not the padding-bottom hack: one element, composable
+             with object-fit, and `min-block-size` still works on it. */
+          aspect-ratio: var(--pretui-aspect-ratio, 1);
+          inline-size: 100%;
+          min-inline-size: 0;
+          overflow: hidden;
+          border-radius: var(--pretui-aspect-radius, var(--radius));
+          background-color: var(
+            --pretui-aspect-bg,
+            color-mix(in oklch, var(--foreground) 6%, var(--card))
+          );
+          background-position: center;
+          background-repeat: no-repeat;
+          box-sizing: border-box;
+        }
+        /* A slot frame is a single-cell grid, so a yielded child stretches to
+           the box without this component styling the caller's element — which
+           the scoped-CSS transpiler would not let it do anyway. */
+        .pretui-aspect[data-fit='slot'] {
+          display: grid;
+          grid-template-columns: minmax(0, 1fr);
+          grid-template-rows: minmax(0, 1fr);
+        }
+        .pretui-aspect[data-fit='contain'] {
+          background-size: contain;
+        }
+        .pretui-aspect[data-fit='cover'] {
+          background-size: cover;
+        }
+        .pretui-aspect[data-bordered='true'] {
+          box-shadow: var(
+            --pretui-shadow-hairline,
+            0 0 0 1px var(--border)
+          );
+        }
+        .pretui-aspect-img {
+          display: block;
+          inline-size: 100%;
+          block-size: 100%;
+          object-fit: var(--pretui-aspect-object-fit, cover);
+        }
+      }
+    </style>
+  </template>
+}
+
+/**
+ * `AspectBox` is the same component under the name the foundation review asked
+ * for. One implementation, two entry points: an agent trained on Radix types
+ * `AspectRatio`, an agent reading the Pretui foundation notes types
+ * `AspectBox`, and neither gets a second frame.
+ */
+export const AspectBox = AspectRatio;

package/bundled-realms/pretui/components/aspect-ratio.md

@@ -0,0 +1,72 @@
+## What it is
+
+A box that **reserves its shape before its content arrives**. It is Law 8 as a component: a value that arrives late never shifts the layout around it. Give it a ratio and either an image (`@src`) or arbitrary content (an iframe, a map, a chart, a canvas) in its block. **AspectBox** is the same component under a second name, not a second frame.
+
+Reach for a neighbour instead when one fits better:
+
+- **ImageFrame** is the kit's opinionated photo treatment.
+- **Image** adds a load fallback and a preview to a framed image.
+- **Skeleton** is the placeholder while there is nothing to frame yet.
+- **MediaPlayer** owns video and audio chrome.
+
+AspectRatio is the plain frame all of them can sit in.
+
+## The contract
+
+```
+@ratio? (number or CSS spelling like '16 / 9'; default 1)
+@src?, @alt?, @fit? ('actual' | 'contain' | 'cover'; default 'actual')
+@width?, @height?, @loading? ('lazy' | 'eager'; default 'lazy')
+@background?, @radius?, @bordered?
+<:default>   — framed content, used when @src is absent
+Element: HTMLDivElement
+```
+
+**One element, sized by the `aspect-ratio` property.** There is no padding-bottom hack and no inner absolutely-positioned wrapper. The frame is the sized box, so `...attributes`, `min-block-size` and height-driven sizing all work on it. The block form is a single-cell grid, so a yielded child stretches to fill the frame without the component styling the caller's element.
+
+**The ratio keeps its spelling.** `@ratio='16 / 9'` reaches CSS as `16 / 9`, not a pre-divided float, and a number is accepted too. Both pass through the kit's caller-value guard. A rejected value leaves the stylesheet default of `1` rather than breaking the box.
+
+**`@fit` is the image decision, made once.**
+
+- `actual` renders a real `<img>` with `alt`, the intrinsic `@width` / `@height` attributes, `loading` and `decoding='async'`. It is the accessible default, and the only mode that lets the browser know the ratio before the bytes land.
+- `contain` and `cover` paint a `background-image` instead. That suits art direction, where the image is a surface rather than content.
+
+**`@src` is guarded, never interpolated.** The painted modes build `url("…")` through `cssUrl`. It parses the value with the platform `URL`, admits only `http:`, `https:`, `blob:` and `data:image/`, and rejects quotes, brackets and whitespace. A value either passes through whole or is dropped whole. It is exported for any other component that is about an image.
+
+`@background` sets the letterbox ground behind `contain`, `@radius` the corner radius, and `@bordered` draws the kit hairline.
+
+## Prior art
+
+**Radix / shadcn AspectRatio** and **Chakra** still use the padding-bottom hack. Radix wraps the content in an unstyleable outer div and pins the inner one with physical offsets written after the caller's style, so position cannot be changed at all. A `ratio` of `0` yields `Infinity%`. **Mantine** uses the property, but sets it on the parent and applies it to every child at zero specificity, so one AspectRatio ratios all of its children. All of them take `ratio` as a bare number, so `16/9` shows up in DevTools as `1.7777777777777777`.
+
+Where Pretui is better: **one element and a real property**; **the ratio keeps its authoring spelling**; **image handling is built in**, with the `<img>` vs painted choice, accessible naming and lazy loading decided in one place instead of by every consumer; and **`object-fit` is a knob** (`--pretui-aspect-object-fit`, default `cover`) instead of hardcoded as in Mantine and Chakra. A block can be empty, one node or many, where Chakra's `Children.only` throws on a conditional child.
+
+Where it is thinner: **no `asChild`**. The frame is always a `div`, so framing a link means putting the link inside. There is **no `srcset` / `sizes`** for the `actual` image, and **no load or error state**. A broken `@src` shows the ground colour. **Image** covers fallback and preview.
+
+## Accessibility
+
+No APG pattern. A frame is layout, and it carries no role unless it is itself the image.
+
+- **`actual` is a real `<img>` with real `alt`.** The frame around it carries no role, so the image is announced once. The tests assert both.
+- **A named painted frame is `role="img"` with `aria-label` from `@alt`**, and it has no `<img>` inside. The tests assert the role, the name and the absence of an `img`.
+- **An empty or whitespace-only `@alt` means decorative.** `actual` keeps `alt=""`, which is the correct decorative `<img>`. The painted modes drop `role="img"` entirely instead of leaving an unnamed image role that announces as a bare "image". The tests assert both the empty and the whitespace case.
+- **What `alt` says is the caller's job.** Describe the image's purpose in context. Leave it empty only when the image adds nothing that the surrounding text lacks.
+- **Framed content keeps its own semantics.** An iframe in the block still needs its own `title`.
+
+## Theming
+
+`--pretui-aspect-ratio` (set from `@ratio`, default `1`), `--pretui-aspect-bg` (set from `@background`; the default is `--foreground` mixed 6% into `--card`), `--pretui-aspect-radius` (set from `@radius`, default `--radius`), `--pretui-aspect-object-fit` (the `actual` image's fit, default `cover`) and `--pretui-shadow-hairline` for `@bordered`, falling back to a 1px `--border` ring.
+
+A theme changes the empty-frame ground and the corner through `--card`, `--foreground` and `--radius`. Everything else is geometry, and that is fixed: full inline size, `min-inline-size: 0`, and clipped overflow.
+
+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                                  |
+| ------------------------------------ | ------------------------------------------ |
+| `<AspectRatio ratio={16 / 9}>`       | `@ratio='16 / 9'` (or the number)          |
+| `asChild`                            | `...attributes` on the frame; no `asChild` |
+| `<AspectRatio><img/></AspectRatio>`  | `@src` + `@alt` (`@fit='actual'`)          |
+| `<img style={{objectFit: 'cover'}}>` | `@fit='cover'` or the object-fit token     |
+| AspectBox (foundation name)          | the same component                         |