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

package/bundled-realms/pretui/components/descriptions.usage.gts

@@ -0,0 +1,123 @@
+// Pretui — Descriptions usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { Descriptions } from './descriptions';
+import type { DescriptionsItem } from './descriptions';
+import type { ListingSizeArg } from '../internal/reading-listing';
+import { LOTS, SIZES } from '../examples-listing';
+import type { Lot } from '../examples-listing';
+
+class DescriptionsUsage extends Component {
+  sizes = SIZES;
+  layouts = ['horizontal', 'vertical'];
+
+  @tracked columns = 3;
+  @tracked bordered = true;
+  @tracked layout: 'horizontal' | 'vertical' = 'horizontal';
+  @tracked size: ListingSizeArg = 'm';
+  @tracked colon = false;
+
+  setColumns = (v: number) => (this.columns = v);
+  setBordered = (v: boolean) => (this.bordered = v);
+  setLayout = (v: string) => (this.layout = v as 'horizontal' | 'vertical');
+  setSize = (v: string) => (this.size = v as ListingSizeArg);
+  setColon = (v: boolean) => (this.colon = v);
+
+  items: DescriptionsItem[] = [
+    { label: 'Lot', value: (LOTS[0] as Lot).id, mono: true },
+    { label: 'Tea', value: (LOTS[0] as Lot).tea },
+    { label: 'Supplier', value: (LOTS[0] as Lot).supplier },
+    { label: 'Origin', value: (LOTS[0] as Lot).place },
+    { label: 'Grade', value: (LOTS[0] as Lot).grade },
+    { label: 'Weight', value: String((LOTS[0] as Lot).kg) + ' kg', mono: true },
+    { label: 'Price', value: (LOTS[0] as Lot).price, mono: true },
+    { label: 'Chests', value: '2', mono: true },
+    { label: 'Cupping note', value: (LOTS[0] as Lot).note, span: 'fill' },
+  ];
+
+  <template>
+    <FreestyleUsage
+      @name='Descriptions'
+      @slug='descriptions'
+      @description='The read-only record display: label/value pairs in an N-column grid that folds to stacked. It is not RecordDetail (that is the editing machine) and not KeyValue (that is the plain two-column dl, which stays exactly what it is).'
+    >
+      <:example>
+        <Descriptions
+          @items={{this.items}}
+          @columns={{this.columns}}
+          @bordered={{this.bordered}}
+          @layout={{this.layout}}
+          @size={{this.size}}
+          @colon={{this.colon}}
+          @title='Lot record'
+        >
+          <:extra>
+            <Button @appearance='outlined' @size='s'>Edit</Button>
+          </:extra>
+        </Descriptions>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='items'
+          @value={{this.items}}
+          @description='The pairs, in reading order. Each carries label, an optional value string, an optional span (a number, or "fill" to take the rest of the row), an optional key, and mono for machine values.'
+        />
+        <Args.Number
+          @name='columns'
+          @value={{this.columns}}
+          @min={{1}}
+          @max={{4}}
+          @step={{1}}
+          @defaultValue={{3}}
+          @description='Pairs per row at full width, 1–4. column is accepted as Ant’s spelling. The container query only ever REDUCES this — narrow the artboard and watch it go 3 → 2 → 1 and then fold the label above the value. Ant resolves the same thing through matchMedia on the window, which is the wrong box inside a card.'
+          @onInput={{this.setColumns}}
+        />
+        <Args.Bool
+          @name='bordered'
+          @value={{this.bordered}}
+          @defaultValue={{false}}
+          @description='Rule the grid and tint the label cells. Unlike Ant, the semantics do not change with the flag: dt is the term and dd the description in both modes, because this is a dl and not a table dressed as one.'
+          @onInput={{this.setBordered}}
+        />
+        <Args.String
+          @name='layout'
+          @value={{this.layout}}
+          @options={{this.layouts}}
+          @defaultValue='horizontal'
+          @description="'horizontal' puts the label beside its value, 'vertical' above it. At the narrowest container width horizontal folds to vertical anyway — two columns of text in a 26rem pane is not a record, it is a wrap."
+          @onInput={{this.setLayout}}
+        />
+        <Args.String
+          @name='size'
+          @value={{this.size}}
+          @options={{this.sizes}}
+          @defaultValue='m'
+          @description='Density on the house scale.'
+          @onInput={{this.setSize}}
+        />
+        <Args.Bool
+          @name='colon'
+          @value={{this.colon}}
+          @defaultValue={{false}}
+          @description='Trailing colon after every label. Ant defaults this to true, which puts a colon on labels that already sit in their own tinted cell; here it is opt-in and the glyph is aria-hidden so it is never read aloud.'
+          @onInput={{this.setColon}}
+        />
+        <Args.String
+          @name='labelWidth'
+          @description='Width of the label column in horizontal layout (any CSS length; default max-content). It goes through the kit’s cssValue guard, so a caller string can never inject a second declaration.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @description='Named blocks: value (item, index) for markup in a description; title and extra for the header.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_DESCRIPTIONS: Record<string, unknown> = {
+  Descriptions: DescriptionsUsage,
+};

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

@@ -0,0 +1,153 @@
+// Pretui — Dialog: a modal on the native <dialog> top layer.
+import Component from '@glimmer/component';
+import { emit, resolveSize } from '../pretui-primitives';
+import type { PretuiSizeArg } from '../pretui-primitives';
+import { provide } from 'ember-provide-consume-context';
+import { POPUPS_IN_PLACE, resolveOpen, modalBehavior } from '../internal/overlay';
+import type { OpenArgs } from '../internal/overlay';
+
+/** The three width steps a Dialog paints, and every spelling of them. */
+type DialogSize = 's' | 'm' | 'l';
+const DIALOG_SIZES: Record<string, DialogSize> = {
+  xs: 's',
+  s: 's',
+  m: 'm',
+  l: 'l',
+  xl: 'l',
+};
+
+export interface DialogSignature {
+  Args: OpenArgs & {
+    /** Canonical close notify. Optional since 2026-08-13: a caller who only
+     * passes `@onOpenChange` (the Radix/shadcn contract, and what an agent
+     * will type) used to hit a hard `this.args.onClose is not a function`. */
+    onClose?: () => void;
+    /** alias — the Radix/shadcn layer notify, called with `false` on close.
+     * A layer needs a two-way knob: `@onClose` alone cannot reopen it. */
+    onOpenChange?: (open: boolean) => void;
+    label?: string;
+    /** the `s|m|l` width steps; `sm`/`md`/`lg`/`default` accepted */
+    size?: DialogSize | PretuiSizeArg;
+    dismissible?: boolean;
+  };
+  Blocks: { title: []; default: []; footer: [] };
+  Element: HTMLDialogElement;
+}
+
+export class Dialog extends Component<DialogSignature> {
+  @provide(POPUPS_IN_PLACE)
+  get popupsInPlace() {
+    return true;
+  }
+  get dismissible() {
+    return this.args.dismissible ?? true;
+  }
+  get open() {
+    return resolveOpen(this.args);
+  }
+  get size(): DialogSize {
+    return DIALOG_SIZES[resolveSize(this.args.size)] ?? 'm';
+  }
+  private requestClose() {
+    emit([this.args.onClose]);
+    emit([this.args.onOpenChange], false);
+  }
+  onCancel = (e: Event) => {
+    // Escape. Keep the element controlled: never let the platform close it
+    // out from under the @open arg.
+    e.preventDefault();
+    if (this.dismissible) {
+      this.requestClose();
+    }
+  };
+  onClick = (e: Event) => {
+    // The inner wrapper covers the whole dialog, so a click that targets the
+    // <dialog> itself landed on the ::backdrop.
+    if (this.dismissible && e.target === e.currentTarget) {
+      this.requestClose();
+    }
+  };
+  <template>
+    <dialog
+      class='pretui-dialog'
+      data-size={{this.size}}
+      aria-label={{@label}}
+      data-test-pretui-dialog
+      {{modalBehavior this.open this.onCancel this.onClick}}
+      ...attributes
+    >
+      <div class='pretui-dialog-inner'>
+        {{#if (has-block 'title')}}
+          <header class='pretui-dialog-title'>{{yield to='title'}}</header>
+        {{/if}}
+        <div class='pretui-dialog-body'>{{yield}}</div>
+        {{#if (has-block 'footer')}}
+          <footer class='pretui-dialog-footer'>{{yield to='footer'}}</footer>
+        {{/if}}
+      </div>
+    </dialog>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-dialog {
+          border: 0;
+          padding: 0;
+          background: var(--card);
+          color: var(--foreground);
+          border-radius: var(--radius-surface, 10px);
+          box-shadow: var(--pretui-shadow-overlay, 0 0 0 1px var(--border), 0 12px 40px rgb(16 24 40 / 0.18));
+          width: min(560px, calc(100vw - 32px));
+          max-height: calc(100dvh - 64px);
+          font-family: var(--font-sans);
+          font-size: var(--text-body, 15px);
+        }
+        .pretui-dialog[data-size='s'] {
+          width: min(400px, calc(100vw - 32px));
+        }
+        .pretui-dialog[data-size='l'] {
+          width: min(760px, calc(100vw - 32px));
+        }
+        .pretui-dialog::backdrop {
+          background: var(--pretui-overlay-scrim, rgb(16 24 40 / 0.4));
+        }
+        .pretui-dialog[open] {
+          opacity: 1;
+          transform: none;
+          transition: opacity 200ms cubic-bezier(0.23, 1, 0.32, 1),
+            transform 200ms cubic-bezier(0.23, 1, 0.32, 1);
+        }
+        @starting-style {
+          .pretui-dialog[open] {
+            opacity: 0;
+            transform: translateY(6px) scale(0.98);
+          }
+        }
+        .pretui-dialog-inner {
+          display: grid;
+          gap: var(--space-4, 11px);
+          padding: var(--space-6, 19px);
+        }
+        .pretui-dialog-title {
+          font-size: var(--text-heading, 19px);
+          font-weight: var(--weight-heading, 700);
+          letter-spacing: var(--track-heading, -0.02em);
+        }
+        .pretui-dialog-body {
+          color: var(--muted-foreground);
+          line-height: calc(var(--leading-body, 24px) / var(--text-body, 15px));
+        }
+        .pretui-dialog-footer {
+          display: flex;
+          justify-content: flex-end;
+          gap: var(--space-3, 8px);
+          border-top: 1px solid var(--border);
+          padding-top: var(--space-4, 11px);
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-dialog[open] {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,60 @@
+## What it is
+
+A modal window built on the native `<dialog>` element. Use it when a task must be finished or abandoned before the user returns to the page beneath — confirmations, destructive-action guards, short focused forms. Do not use it for anything the user should be able to work alongside; that is **Popover** (anchored, non-modal) or **Drawer** (edge-docked, still modal but sized for longer content). For transient, non-blocking notice use **Toast**; for inline blocking notice use **Alert**.
+
+## The contract
+
+```
+@open, @onClose (required), @label?, @size? ('s'|'m'|'l'), @dismissible? (default true)
+<:title> <:default> <:footer>
+```
+
+The one non-obvious decision: **the dialog is strictly controlled, and the platform is never allowed to close it.** The `cancel` event (Escape) is `preventDefault()`ed, and `@onClose` is called instead. So `@open` remains the single source of truth — the DOM cannot drift from your state. The consequence is that ignoring `@onClose` makes the dialog uncloseable; that is intended, and it is how `@dismissible={{false}}` is implemented (both Escape and backdrop click become no-ops).
+
+The second decision: `showModal()` is driven from a modifier rather than from a template `{{on}}` handler, because the kit's lint rule `no-invalid-interactive` rejects listeners on `<dialog>`. The modifier syncs `open`→`showModal()` / `!open`→`close()` on every re-render, and owns the `cancel` and `click` listeners with matching teardown.
+
+Backdrop detection is a nice trick worth understanding: the inner wrapper covers the whole dialog box, so any `click` whose `target === currentTarget` (the `<dialog>` itself) necessarily landed on the `::backdrop`. No hit-testing, no extra scrim element.
+
+## Prior art
+
+**Web Awesome `wa-dialog`** exposes `open`, `label`, `without-header`, `with-footer`, and `light-dismiss`. **Radix `Dialog`** composes `Root/Trigger/Portal/Overlay/Content/Title/Description/Close` with `open`/`onOpenChange`/`modal`, and implements its own focus trap, scroll lock and `aria-hidden` background over a plain `<div>`. **React Spectrum** wraps it in a `DialogTrigger` and adds `isDismissable`, `isKeyboardDismissDisabled`, and a `type` axis (`modal`/`popover`/`tray`) that swaps presentation by viewport.
+
+Pretui differs on two axes deliberately.
+
+_Default polarity._ Web Awesome makes light dismiss **opt-in** (`light-dismiss`); Pretui makes it **opt-out** (`@dismissible` defaults to `true`). Modals in this kit are overwhelmingly confirmations, and the safe-by-default reading is that a user can always get out; the rare "you must answer this" dialog pays the extra arg.
+
+_Native top layer instead of a JS overlay stack._ Radix and Spectrum re-implement focus trapping, stacking and inertness in JavaScript because they target a portalled `<div>`. Pretui rides `showModal()`, which gives focus trapping, Escape via `cancel`, `::backdrop`, correct stacking of nested dialogs, and `inert` background _from the browser_, with no dismissible-stack bookkeeping and nothing to leak on teardown. That is a smaller, more correct implementation — the platform maintains it.
+
+Entry/exit motion is pure CSS via `@starting-style`, so open state is encoded in the DOM rather than in an animation controller, and `prefers-reduced-motion: reduce` drops straight to the end state.
+
+## Accessibility
+
+Governing pattern: APG **Dialog (Modal)**. What the platform supplies via `showModal()`: `role="dialog"` + `aria-modal` semantics, focus trap, Escape, background inertness, top-layer stacking. What Pretui supplies: `aria-label` from `@label`.
+
+Honest gaps:
+
+- **`@label` is the only labelling route.** If you render a heading into `<:title>` there is no `aria-labelledby` wiring it to the dialog — you must _also_ pass `@label`, duplicating the string. Radix enforces a `Title` and warns when it is missing; Pretui does not warn.
+- **No description wiring** (`aria-describedby`) for the body.
+- **No initial-focus control.** The browser focuses the first focusable descendant. There is no `@initialFocus` equivalent to Spectrum's autofocus handling, so a destructive confirm dialog will focus whatever comes first in DOM order, not necessarily "Cancel".
+- **Focus return on close** is the browser's default (back to the invoker) and is generally correct, but it is not asserted by the component — if the trigger unmounts while the dialog is open, focus is lost to `<body>`.
+- Escape reaching `@onClose` depends on the caller actually flipping `@open`; a caller that ignores it silently creates a keyboard trap. Worth a lint rule.
+
+## Theming
+
+`--card`, `--foreground`, `--radius-surface`, `--pretui-shadow-overlay`, `--pretui-overlay-scrim` (the `::backdrop` fill), `--font-sans`, `--text-body`, `--text-heading`, `--weight-heading`, `--track-heading`, `--space-3/4/6`, `--border`, `--muted-foreground`, `--leading-body`. Widths are hard-capped at `min(400|560|760px, 100vw - 32px)` and height at `100dvh - 64px`; a theme cannot retune those without a variant. `--pretui-overlay-scrim` is the token most themes get wrong — it must read as a scrim in both light and dark, not simply invert.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+Ant/Mantine/MUI agents will type **Modal** (alias stub). Destructive
+confirms should be **AlertDialog**, not this.
+
+| React                               | Pretui                    |
+| ----------------------------------- | ------------------------- |
+| Dialog / Modal                      | this tile                 |
+| AlertDialog / Modal.confirm         | **AlertDialog**           |
+| Sheet (slide-over)                  | **Drawer**                |
+| `open` / `onOpenChange` / `onClose` | hybrid — accept `onClose` |
+| `title` / `footer`                  | blocks                    |
+| `fullScreen` / `size`               | @size                     |

package/bundled-realms/pretui/components/dialog.usage.gts

@@ -0,0 +1,86 @@
+// Pretui — Dialog usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { Dialog } from './dialog';
+
+const DIALOG_SIZES = ['s', 'm', 'l'];
+
+class DialogUsage extends GlimmerComponent {
+  @tracked open = false;
+  @tracked size = 's';
+  @tracked dismissible = true;
+  show = () => (this.open = true);
+  hide = () => (this.open = false);
+  setSize = (v: string) => (this.size = v);
+  setDismissible = (v: boolean) => (this.dismissible = v);
+  get sizeVal() {
+    return this.size as 's' | 'm' | 'l';
+  }
+  <template>
+    <FreestyleUsage
+      @name='Dialog'
+      @description='Modal dialog on the native top layer (showModal). Focus trap, Escape (as a cancelable controlled close), ::backdrop, and stacking come from the platform — no JS dismissible-stack. Supersedes boxel-ui Modal, which owns the viewport and ships no focus trap.'
+    >
+      <:example>
+        <Button @tone='neutral' @appearance='outlined' {{on 'click' this.show}}>
+          Open the dialog
+        </Button>
+        <Dialog
+          @open={{this.open}}
+          @onClose={{this.hide}}
+          @label='Demo'
+          @size={{this.sizeVal}}
+          @dismissible={{this.dismissible}}
+        >
+          <:title>Native top layer</:title>
+          <:default>Focus trap, Escape, backdrop click, and stacking come from
+            the platform dialog. Entry motion is pure CSS via
+            @starting-style.</:default>
+          <:footer>
+            <Button @tone='primary' {{on 'click' this.hide}}>Done</Button>
+          </:footer>
+        </Dialog>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='size'
+          @value={{this.size}}
+          @options={{DIALOG_SIZES}}
+          @defaultValue='m'
+          @description='Dialog width: s 400px, m 560px, l 760px (all clamped to the viewport).'
+          @onInput={{this.setSize}}
+        />
+        <Args.Bool
+          @name='dismissible'
+          @value={{this.dismissible}}
+          @defaultValue={{true}}
+          @description='Whether Escape and backdrop click close the dialog.'
+          @onInput={{this.setDismissible}}
+        />
+        <Args.Bool
+          @name='open'
+          @value={{this.open}}
+          @description='Controlled open state — the component never closes itself out from under it.'
+          @onInput={{this.setDismissible}}
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onClose'
+          @required={{true}}
+          @description='Called when the user dismisses (Escape, backdrop, or your own buttons).'
+        />
+        <Args.Yield
+          @name='title / default / footer'
+          @description='Named blocks: heading, body, and the right-aligned action row above a hairline.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_DIALOG: Record<string, unknown> = {
+  Dialog: DialogUsage,
+};

package/bundled-realms/pretui/components/diff-block.gts

@@ -0,0 +1,89 @@
+// Pretui — DiffBlock: a before/after change rendered as a line diff.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+
+export interface DiffLine {
+  op?: 'add' | 'del';
+  text: string;
+}
+
+export interface DiffBlockSignature {
+  Args: { lines: DiffLine[]; receipt?: string; maxLines?: number };
+  Element: HTMLDivElement;
+}
+
+// Staged change with an immutable receipt line; long diffs collapse.
+export class DiffBlock extends Component<DiffBlockSignature> {
+  @tracked collapsed = true;
+  get maxLines() {
+    return this.args.maxLines ?? 8;
+  }
+  get overflows() {
+    return this.args.lines.length > this.maxLines;
+  }
+  get shown() {
+    return this.collapsed && this.overflows
+      ? this.args.lines.slice(0, this.maxLines)
+      : this.args.lines;
+  }
+  get toggleLabel() {
+    return this.collapsed ? `… ${this.args.lines.length - this.maxLines} more lines` : 'collapse';
+  }
+  prefix = (line: DiffLine) => (line.op === 'add' ? '+ ' : line.op === 'del' ? '- ' : '  ');
+  toggle = () => {
+    this.collapsed = !this.collapsed;
+  };
+  <template>
+    <div class='pretui-diff' data-test-pretui-diff-block ...attributes>
+      {{#each this.shown as |line|}}
+        <div class='pretui-diff-line' data-op={{line.op}}>{{this.prefix line}}{{line.text}}</div>
+      {{/each}}
+      {{#if this.overflows}}
+        <button type='button' class='pretui-diff-line pretui-diff-toggle' {{on 'click' this.toggle}}>{{this.toggleLabel}}</button>
+      {{/if}}
+      {{#if @receipt}}<div class='pretui-diff-receipt'>{{@receipt}}</div>{{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-diff {
+          font-family: var(--font-mono);
+          font-size: var(--text-ui-sm, 11.5px);
+          line-height: 1.7;
+          background: var(--inset, var(--boxel-100));
+          border-radius: 8px;
+          box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
+          overflow: hidden;
+        }
+        .pretui-diff-line {
+          padding: 0 10px;
+          white-space: pre;
+        }
+        .pretui-diff-line[data-op='add'] {
+          background: color-mix(in oklch, var(--success, var(--boxel-success)) 12%, transparent);
+          color: color-mix(in oklch, var(--foreground) 30%, var(--success, var(--boxel-success)));
+        }
+        .pretui-diff-line[data-op='del'] {
+          background: color-mix(in oklch, var(--destructive) 10%, transparent);
+          color: color-mix(in oklch, var(--foreground) 30%, var(--destructive));
+        }
+        .pretui-diff-toggle {
+          display: block;
+          width: 100%;
+          text-align: left;
+          border: 0;
+          background: none;
+          font: inherit;
+          color: var(--pretui-primary-ink, var(--primary));
+          cursor: pointer;
+        }
+        .pretui-diff-receipt {
+          padding: 5px 10px;
+          font-size: 10.5px;
+          color: var(--ink-3, var(--boxel-400));
+          box-shadow: 0 -1px 0 var(--border);
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/diff-block.md

@@ -0,0 +1,51 @@
+## What it is
+
+A staged change rendered as a diff, with an immutable receipt line, collapsing when long. Use it wherever an agent shows what it altered — a file edit, a field patch, a config change — before or after **ApprovalFooter** gates it. If you are showing a _result_ rather than a change, **ResultCard**. If it is a code sample rather than a diff, that is `<pre>` inside **Prose**.
+
+## The contract
+
+```
+@lines: DiffLine[]   (required)
+@receipt?, @maxLines? (default 8)
+```
+
+**`@maxLines` defaults to 8 and long diffs collapse by default** (`@tracked collapsed = true`). That is the right default for a transcript: an agent that edits three files should not fill the viewport with 400 lines the user has not asked to read. Expansion is per-block, so the user opens the one they care about.
+
+**The receipt is immutable and separate from the diff.** It is the line that survives after the change is folded away — the thing a user scrolling a settled transcript sees in place of the full diff. That is the territory's fold law in miniature: settled work folds to receipts, and the receipt is the durable artefact, not the diff.
+
+`DiffLine` carries the per-line kind (added, removed, context) that drives the row dress.
+
+## Prior art
+
+No component kit ships a diff view. The references are `diff2html`, GitHub's blob diff, VS Code's inline diff, and Monaco's diff editor — all of them tools rather than components, and all much larger.
+
+The interesting comparison is what this deliberately does not do:
+
+- **No syntax highlighting.** GitHub and Monaco both highlight; this renders plain mono text. That keeps the component free of a language grammar dependency and keeps a diff in a transcript reading as _a change_, not as code — which is the right emphasis when the user is deciding whether to approve it.
+- **No side-by-side mode.** Unified only. In a transcript column that is the only mode that fits.
+- **No line numbers**, so a diff here cannot be referenced by line — a real limitation when discussing a change with the agent.
+- **No hunk headers or context expansion.** `@maxLines` truncates from the top of the block rather than showing collapsed context regions the way GitHub does.
+
+Where it is better than dropping a `diff2html` render into a transcript: the receipt line, the collapse default, and the fact that it wears the kit's mono voice rather than a diff library's own theme.
+
+## Accessibility
+
+No pattern governs it, and diffs are genuinely hard to make accessible. The relevant criteria are WCAG **1.4.1 Use of Colour**, **1.3.1** and **2.1.1**.
+
+Gaps, and the first is the classic diff failure:
+
+- **Added and removed lines are almost certainly distinguished by fill colour and a `+`/`-` prefix character.** If the prefix is present and part of the text, **WCAG 1.4.1** is satisfied — verify it, because if the `+`/`-` is a CSS `::before` or a background tint alone, colour is the only channel and the diff is unreadable for a colour-blind user. This is the single most important thing to check on this component.
+- **Diffs are hostile to linear reading.** A screen reader announcing forty lines of mono text with `+`/`-` prefixes conveys very little. The accessible affordance is a _summary_ — "3 lines added, 1 removed in config.json" — and the **receipt** is very nearly that already. Making the receipt the primary announced content, with the diff as expandable detail, would be a genuine improvement and the structure is already there.
+- **The collapse control's state is not described here.** Verify it is a real `<button>` with `aria-expanded` and a name that says what expands ("Show 40 more lines"), not a bare chevron.
+- **The truncation is silent.** A collapsed diff shows 8 of 40 lines; nothing announces that 32 are hidden, so a screen-reader user may believe they have read the whole change before approving it. Given that this component feeds an approval decision, that is a **WCAG 3.3.4** concern, not just an annoyance.
+- **No `<table>` or list semantics**, so line-to-line relationships are positional only.
+- **Long lines**: verify they wrap rather than scroll horizontally, or a keyboard user cannot reach the end of one (**WCAG 2.1.1**, and **1.4.10 Reflow**).
+- The receipt is text, which is right — it is the durable, readable form.
+
+## Theming
+
+Mono voice (`--font-mono`, `--text-ui-sm`), added and removed row tints derived from `--success` and `--destructive` mixed against `--card`, context rows in `--muted-foreground`, `--inset` for the block surface, `--border` for its edge, and the receipt in the quieter ink.
+
+The added/removed tints are the tokens to check per theme. They must be distinguishable from each other **and** legible as backgrounds behind mono text at 11.5px — a theme that tunes `--success` and `--destructive` for **Delta**'s foreground ink will usually find them far too strong as fills here. Because the tints are `color-mix` derivations rather than fixed hexes, adjusting the mix ratio is the lever; adjusting the hue is not.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/diff-block.usage.gts

@@ -0,0 +1,27 @@
+// Pretui — DiffBlock usage page.
+import Component from '@glimmer/component';
+import { FreestyleUsage } from './freestyle-usage';
+import { DiffBlock } from './diff-block';
+
+const DIFF_LINES = [
+  { text: 'lot: B-103' },
+  { op: 'del' as const, text: 'status: draft' },
+  { op: 'add' as const, text: 'status: approved' },
+  { op: 'add' as const, text: 'approvedBy: Mei-Lin Chua' },
+  { op: 'add' as const, text: 'approvedAt: 2026-08-13' },
+  { text: 'origin: Shizuoka' },
+];
+
+class DiffBlockUsage extends Component {
+  lines = DIFF_LINES;
+  <template>
+    <FreestyleUsage @name='DiffBlock' @description='A compact staged diff with textual prefixes, controlled expansion and an immutable receipt line.' @source='<DiffBlock @lines={{this.lines}} @receipt="3 fields changed" />' @viewportMode='wide'>
+      <:example><DiffBlock @lines={{this.lines}} @receipt='3 fields changed · run_8F3C' @maxLines={{3}} /></:example>
+      <:api as |Args|><Args.Object @name='lines' @value={{this.lines}} /><Args.String @name='receipt' @value='3 fields changed · run_8F3C' /><Args.Number @name='maxLines' @value={{3}} /></:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_DIFF_BLOCK: Record<string, unknown> = {
+  DiffBlock: DiffBlockUsage,
+};

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

@@ -0,0 +1,2 @@
+// Pretui — Disclosure: Collapsible under the name other kits use.
+export { Collapsible as Disclosure } from './collapsible';

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

@@ -0,0 +1,45 @@
+## What it is
+
+**Collapsible** under the name React Aria uses. The export is the same class — `import { Disclosure } from './disclosure';` and `import { Collapsible }` from the same module resolve to one component — so the tile exists for the reader who arrives with the Aria vocabulary: a port of an Aria `Disclosure`, or an agent whose first guess is that word. The contract, the behaviour and the depth are on **Collapsible**; this page says what the Aria names map to. **Accordion** is several of these behind boxel-ui's engine; **Fold** is the agentic receipt shape.
+
+## The contract
+
+```
+@open?           — controlled state (Aria isExpanded)
+@defaultOpen?    — uncontrolled initial state (Aria defaultExpanded)
+@onOpenChange?   — every toggle, with the next state (Aria onExpandedChange)
+@label?          — trigger text; sugar for <:trigger>
+@disabled?       — aria-disabled, still focusable (Aria isDisabled)
+@size?           — the kit size scale (xs · s · m · l · xl)
+@hideCaret?      — drop the rotating chevron
+<:trigger as |open|>   — the DisclosureButton content
+<:default>             — the DisclosurePanel
+```
+
+**The Aria spellings are not accepted.** `isExpanded`, `onExpandedChange` and `isDisabled` have to be renamed at the call site; the alias gives a port the component name, not the arg names.
+
+## Prior art
+
+**React Aria `Disclosure`** is a headless pair — `DisclosureButton` and `DisclosurePanel` — with `isExpanded` / `defaultExpanded` / `onExpandedChange` / `isDisabled`, `useDisclosure` for the ARIA wiring and no animation of its own; a consumer animates the panel or uses the `hidden="until-found"` mode for find-in-page. It also ships a `DisclosureGroup` (one open at a time), which here is **Accordion**'s job.
+
+What this has that Aria's does not: the height animation, with content that stays mounted and is taken out of the tab order through `visibility` when closed; a built-in rotating caret; a `@label` shortcut so the common case is one line. What Aria's has that this does not: `hidden="until-found"` (closed content here is never `hidden`, so browser find never expands it), the `DisclosureGroup` wrapper, and the `isExpanded` spellings.
+
+## Accessibility
+
+Collapsible's, exactly, and it is the APG **Disclosure** pattern Aria's component is named after: a native `<button>` with `aria-expanded` and `aria-controls`, a `role='region'` panel labelled by its trigger, Enter and Space from the native button, closed content removed from the tab order, and `@disabled` as `aria-disabled` so the trigger stays discoverable. The trigger carries no heading semantics; wrap it in the heading you mean.
+
+## Theming
+
+Collapsible's tokens: `--foreground`, `--muted-foreground`, `--hover`, `--ring`, `--radius-chip`, the `--pretui-size-*` and `--text-ui-*` scales, the component's own `--pretui-collapsible-h` and `--pretui-collapsible-px`, and the kit motion pairs `--pretui-dur-morph` / `--pretui-ease-morph` (fold) and `--pretui-dur-snap` / `--pretui-ease-snap` (caret). Nothing is themed under a Disclosure name.
+
+## React ecosystem
+
+| React Aria | Pretui |
+| --- | --- |
+| `isExpanded` / `defaultExpanded` | `@open` / `@defaultOpen` |
+| `onExpandedChange` | `@onOpenChange` |
+| `isDisabled` | `@disabled` |
+| `<DisclosureButton>` | `@label` or `<:trigger>` |
+| `<DisclosurePanel>` | `<:default>` |
+| `<DisclosureGroup>` | **Accordion** |
+| `hidden="until-found"` | not offered |