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

package/bundled-realms/pretui/components/action-bar.md

@@ -0,0 +1,48 @@
+## What it is
+
+The bulk-selection bar: "3 of 40 selected", the actions you can take against that selection, and a way to clear it.
+
+## The contract
+
+```
+@count (required) — how many things are selected. ZERO HIDES THE BAR ENTIRELY
+@total?    — the collection's size, for "3 of 40 selected"
+@noun?     — singular noun, pluralised by adding an s. Default 'item'
+@actions?  — the actions offered against the selection
+@maxVisible? — how many actions get their own button before the rest collapse
+             into an overflow Menu. Default 3
+@overflowLabel? — default 'More actions'
+@label?    — the bar's accessible name. Default 'Selection actions'
+@clearLabel?    — default 'Clear selection'
+@onClear?  — called by the clear button AND by Escape inside the bar
+```
+
+**Zero selection hides the bar.** The caller does not conditionally render it; it renders itself away, which is what keeps the show/hide logic in one place.
+
+**Escape inside the bar clears the selection**, not just closes something — which is the shortcut people reach for and almost no implementation wires up.
+
+**`@maxVisible` defaults to 3**, and everything past it folds into a Menu rather than wrapping or scrolling.
+
+## Prior art
+
+The bulk-action bar in table and list UIs.
+
+Where Pretui is better: Escape clearing, the self-hiding at zero, and the count sentence being built from `@count`/`@total`/`@noun` rather than assembled at each call site — which is how "1 items selected" ships.
+
+Where it is thinner: no undo affordance after a bulk action, no per-action confirmation, and no partial-selection state ("all on this page").
+
+## Accessibility
+
+- **The bar is a named region**, so it is findable when it appears.
+- **The count is a sentence**, not a number beside an icon — "3 of 40 items selected" is what gets announced.
+- **Escape clearing is a keyboard affordance for the most common intent**, and it is wired to the same handler as the button so the two can never diverge.
+- **The overflow trigger is named** rather than being an unlabelled ellipsis.
+- **A bar appearing is a change worth noticing.** Whether it is announced is the host's call — the component supplies a region, not a live region.
+
+## Theming
+
+The bar takes the kit's surface, elevation and control tokens.
+
+It usually floats over content, so it uses the shared raised elevation — the same one every other floating surface uses, which is what stops a selection bar looking like a different application's toolbar.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/action-bar.usage.gts

@@ -0,0 +1,213 @@
+// Pretui — ActionBar usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { ActionBar } from './action-bar';
+import type { ActionBarAction } from './action-bar';
+import { TEAS } from '../examples-kit';
+
+// ── ActionBar ───────────────────────────────────────────────────────────
+const ROSTER = TEAS.slice(0, 7);
+
+class ActionBarUsage extends Component {
+  @tracked picked: string[] = [ROSTER[0] as string, ROSTER[2] as string];
+  @tracked maxVisible = 2;
+  @tracked noun = 'lot';
+  @tracked showTotal = true;
+  @tracked lastFired = 'Nothing fired yet.';
+
+  setMaxVisible = (v: number | null) => (this.maxVisible = v ?? 2);
+  setNoun = (v: string) => (this.noun = v);
+  setShowTotal = (v: boolean) => (this.showTotal = v);
+
+  get total(): number | undefined {
+    return this.showTotal ? ROSTER.length : undefined;
+  }
+  get roster(): { name: string; on: boolean }[] {
+    return ROSTER.map((name) => ({
+      name,
+      on: this.picked.indexOf(name) !== -1,
+    }));
+  }
+
+  toggle = (event: Event) => {
+    let name = (event.currentTarget as HTMLElement).getAttribute('data-name');
+    if (!name) {
+      return;
+    }
+    this.picked =
+      this.picked.indexOf(name) === -1
+        ? [...this.picked, name]
+        : this.picked.filter((n) => n !== name);
+  };
+  clear = () => (this.picked = []);
+  fire = (id: string) => {
+    this.lastFired =
+      id + ' fired on ' + this.picked.length + ' selected lots.';
+  };
+
+  get actions(): ActionBarAction[] {
+    return [
+      { id: 'cup', label: 'Schedule cupping', onAction: this.fire },
+      { id: 'price', label: 'Re-price', onAction: this.fire },
+      { id: 'export', label: 'Export', icon: 'file', onAction: this.fire },
+      { id: 'archive', label: 'Archive', icon: 'folder', onAction: this.fire },
+      {
+        id: 'withdraw',
+        label: 'Withdraw from sale',
+        icon: 'circle-minus',
+        destructive: true,
+        onAction: this.fire,
+      },
+    ];
+  }
+
+  get usage(): string {
+    return (
+      '<ActionBar @count={{this.picked.length}} @total={{this.total}}' +
+      " @noun='" + this.noun + "'" +
+      ' @actions={{this.actions}} @maxVisible={{' + this.maxVisible + '}}' +
+      ' @onClear={{this.clear}} />'
+    );
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='ActionBar'
+      @description='The bar that appears when a selection exists. Every control in it is an existing kit component — Button, IconButton and Menu for the overflow — so what the bar adds is the count as a sentence, an overflow threshold, and the APG toolbar keyboard contract: one tab stop, arrows within, Home and End to the ends, Escape to clear. Select a row or two below to bring it in.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pretui-ab-demo'>
+          <ul class='pretui-ab-demo-list'>
+            {{#each this.roster key='name' as |row|}}
+              <li>
+                <button
+                  type='button'
+                  class='pretui-ab-demo-row'
+                  data-name={{row.name}}
+                  data-on={{if row.on 'true'}}
+                  aria-pressed={{if row.on 'true' 'false'}}
+                  {{on 'click' this.toggle}}
+                >{{row.name}}</button>
+              </li>
+            {{/each}}
+          </ul>
+          <ActionBar
+            @count={{this.picked.length}}
+            @total={{this.total}}
+            @noun={{this.noun}}
+            @actions={{this.actions}}
+            @maxVisible={{this.maxVisible}}
+            @onClear={{this.clear}}
+            @position='inline'
+          />
+          <p class='pretui-ab-demo-note'>{{this.lastFired}}</p>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='count'
+          @required={{true}}
+          @description='How many things are selected. Zero hides the bar entirely.'
+        />
+        <Args.Bool
+          @name='total'
+          @value={{this.showTotal}}
+          @description='Demo switch for the total argument: with it set the bar reads 3 lots selected of 7.'
+          @onInput={{this.setShowTotal}}
+        />
+        <Args.String
+          @name='noun'
+          @value={{this.noun}}
+          @defaultValue='item'
+          @description='Singular noun, pluralised by adding an s.'
+          @onInput={{this.setNoun}}
+        />
+        <Args.Number
+          @name='maxVisible'
+          @value={{this.maxVisible}}
+          @min={{0}}
+          @max={{5}}
+          @step={{1}}
+          @description='How many actions get their own button before the rest collapse into an overflow Menu. Exactly one action over the limit is promoted instead — a menu holding one item is worse than one more button.'
+          @onInput={{this.setMaxVisible}}
+        />
+        <Args.Array
+          @name='actions'
+          @description='Each has an id, a label, and optionally an icon, tone, disabled or destructive flag and an onAction callback.'
+        />
+        <Args.Action
+          @name='onClear'
+          @description='Called by the clear button and by Escape inside the bar. Omit it and no clear button is drawn.'
+        />
+        <Args.Yield
+          @name='default'
+          @description='Extra controls appended after the actions. Give anything focusable a data-actionbar-item attribute so it joins the arrow-key rotation.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-actionbar-enter'
+          @type='duration'
+          @description='How long the bar takes to arrive. Reduced motion lands on the end state.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-ab-demo {
+        display: grid;
+        gap: var(--space-3, 8px);
+        max-width: 520px;
+      }
+      .pretui-ab-demo-list {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--space-2, 6px);
+      }
+      .pretui-ab-demo-row {
+        padding: 4px 10px;
+        border: 0;
+        border-radius: var(--radius-control, 8px);
+        background: var(--card);
+        box-shadow: var(
+          --pretui-shadow-hairline,
+          0 0 0 1px var(--border)
+        );
+        font: inherit;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--foreground);
+        cursor: pointer;
+      }
+      .pretui-ab-demo-row[data-on='true'] {
+        background: color-mix(
+          in oklch,
+          var(--primary) 12%,
+          var(--card)
+        );
+        color: color-mix(
+          in oklch,
+          var(--foreground) 16%,
+          var(--primary)
+        );
+      }
+      .pretui-ab-demo-row:focus-visible {
+        outline: 2px solid var(--ring);
+        outline-offset: 1px;
+      }
+      .pretui-ab-demo-note {
+        margin: 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_ACTION_BAR: Record<string, unknown> = {
+  ActionBar: ActionBarUsage,
+};

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

@@ -0,0 +1,116 @@
+// Pretui — Affix: pin a child to the top (or bottom) of its scroll container once it scrolls past a threshold.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+// type-only gap: 'ember-modifier' resolves at realm runtime; glint cannot see
+// it here (accepted parse baseline, same as toaster.gts / focus.gts)
+import { modifier } from 'ember-modifier';
+import { scrollParent } from '../internal/structure-scroll';
+import { cssDeclaration, cssStyleFrom } from '../pretui-css';
+
+export interface AffixSignature {
+  Args: {
+    /** Pin to the 'top' (default) or 'bottom' edge of the scroll container. */
+    position?: 'top' | 'bottom';
+    /** Distance from that edge while pinned, any kit-valid CSS length (default 0). */
+    offset?: string;
+    /** Fires with true when the child becomes pinned and false when it is released. */
+    onChange?: (pinned: boolean) => void;
+  };
+  Blocks: { default: [pinned: boolean] };
+  Element: HTMLDivElement;
+}
+
+/**
+ * Ant and Mantine Affix, done with CSS: the wrapper is `position: sticky`, so
+ * the browser pins it inside its nearest scroll container — the pane, not the
+ * window — with no scroll listener and no portal. What CSS cannot say is
+ * *whether* it is pinned, so a zero-height sentinel just before (or after)
+ * the child is watched with an IntersectionObserver rooted at the scroll
+ * container: when the sentinel leaves, the child is stuck. That state is
+ * yielded, set as `data-pinned` for styling, and reported by `@onChange`.
+ *
+ * Pinning is visual, so nothing is announced. Sticky needs the scroll
+ * container to be the nearest ancestor with overflow; a parent with
+ * `overflow: hidden` in between stops it, which is the one case a portal-
+ * based affix handles and this does not.
+ */
+export class Affix extends Component<AffixSignature> {
+  @tracked pinned = false;
+
+  get position(): 'top' | 'bottom' {
+    return this.args.position === 'bottom' ? 'bottom' : 'top';
+  }
+  get isTop(): boolean {
+    return this.position === 'top';
+  }
+  get style() {
+    return cssStyleFrom([cssDeclaration('--pretui-affix-offset', this.args.offset)]);
+  }
+
+  watch = modifier((sentinel: HTMLElement, [position, offset]: [string, string | undefined]) => {
+    void offset;
+    let root = scrollParent(sentinel);
+    // The wrapper sticks at its used inset (rem, calc, whatever @offset was),
+    // so the observer's edge moves in by the same amount; otherwise the
+    // pinned state lags the pinning by the offset.
+    let wrapper = (position === 'top' ? sentinel.nextElementSibling : sentinel.previousElementSibling) as HTMLElement | null;
+    let inset = wrapper ? parseFloat(getComputedStyle(wrapper)[position === 'top' ? 'top' : 'bottom']) || 0 : 0;
+    let rootMargin = position === 'top' ? `${-inset}px 0px 0px 0px` : `0px 0px ${-inset}px 0px`;
+    let observer = new IntersectionObserver(
+      (entries) => {
+        let entry = entries[entries.length - 1];
+        if (!entry) {
+          return;
+        }
+        // Stuck when the sentinel has left through the pinned edge.
+        let box = entry.rootBounds;
+        let rect = entry.boundingClientRect;
+        let gone = !entry.isIntersecting;
+        let pinned = gone && (box ? (position === 'top' ? rect.top < box.top : rect.bottom > box.bottom) : true);
+        if (pinned !== this.pinned) {
+          this.pinned = pinned;
+          this.args.onChange?.(pinned);
+        }
+      },
+      { root, rootMargin, threshold: 0 },
+    );
+    observer.observe(sentinel);
+    return () => observer.disconnect();
+  });
+
+  <template>
+    {{#if this.isTop}}<div class='pretui-affix-sentinel' aria-hidden='true' {{this.watch this.position @offset}}></div>{{/if}}
+    <div
+      class='pretui-affix'
+      data-position={{this.position}}
+      data-pinned={{if this.pinned 'true' 'false'}}
+      style={{this.style}}
+      data-test-pretui-affix
+      ...attributes
+    >{{yield this.pinned}}</div>
+    {{#unless this.isTop}}<div class='pretui-affix-sentinel' aria-hidden='true' {{this.watch this.position @offset}}></div>{{/unless}}
+    <style scoped>
+      @layer PretComponent {
+        .pretui-affix {
+          position: sticky;
+          z-index: var(--pretui-z-sticky, 10);
+        }
+        .pretui-affix[data-position='top'] {
+          inset-block-start: var(--pretui-affix-offset, 0);
+        }
+        .pretui-affix[data-position='bottom'] {
+          inset-block-end: var(--pretui-affix-offset, 0);
+        }
+        .pretui-affix[data-pinned='true'] {
+          box-shadow: var(--pretui-affix-shadow, none);
+        }
+        .pretui-affix-sentinel {
+          block-size: 0;
+          pointer-events: none;
+        }
+      }
+    </style>
+  </template>
+
+}
+

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

@@ -0,0 +1,54 @@
+## What it is
+
+**Pin a child to the edge of its scroll container once it scrolls past.** A toolbar that stays at the top of a long form, or a Save bar that stays at the bottom of a long list. The child is usually a **Toolbar**, an **ActionBar** or a **FloatButton**.
+
+Reach for a neighbour when pinning is not the point:
+
+- **PageScaffold**'s `@stickyMasthead` pins the page header.
+- **FloatButton** anchors to a corner and does not follow scroll.
+
+## The contract
+
+```
+@position? ('top' | 'bottom'; default 'top')
+@offset?   — distance from that edge while pinned (default 0)
+@onChange? — true when pinned, false when released
+<:default as |pinned|>
+Element: HTMLDivElement
+```
+
+**CSS does the pinning.** The wrapper is `position: sticky` against `@position`, so the browser pins it inside its nearest scroll container, the pane, not the window. There is no scroll listener and no portal.
+
+**An observer tells you whether it is pinned.** CSS can't say whether a sticky element is stuck. So a zero-height sentinel sits just before the child (or just after it, for bottom). An IntersectionObserver rooted at the scroll container watches it, with its edge moved in by the wrapper's actual inset, so the pinned state turns on exactly when an `@offset` wrapper sticks. That state is yielded to the block, set as `data-pinned` on the wrapper for styling, and reported by `@onChange`.
+
+## Prior art
+
+**Ant `Affix`** takes `offsetTop`, `offsetBottom`, `target` (the scroll container) and `onChange`. It measures on scroll and switches the child to `position: fixed`, with a placeholder to hold its space. **Mantine `Affix`** is a fixed-position portal, a different idea. **MUI `useScrollTrigger`** is a hook that reports a threshold crossing.
+
+Where Pretui is better: **sticky, not fixed.** The child keeps its place in the layout, needs no placeholder, and never jumps a frame behind the scroll. **The pinned state comes from an observer**, not a scroll listener.
+
+Where it is thinner: **sticky needs the scroll container to be the nearest ancestor with overflow.** A parent with `overflow: hidden` in between stops it, which is the one case Ant's fixed-plus-placeholder approach handles. There is **no `target` arg**: the scroll container is found by walking up.
+
+## Accessibility
+
+No APG pattern.
+
+- **Pinning is visual, so nothing is announced.** The child keeps its place in the reading and tab order, because sticky doesn't move it in the DOM.
+- **The sentinel is `aria-hidden`**, with zero height, so it has no presence.
+- **A pinned bar covers content.** A pinned toolbar sits over the top of the scrolled content, so give focusable content `scroll-margin-top` at least the bar's height, or a focused field can hide behind it.
+
+## Theming
+
+`--pretui-affix-offset` (set from `@offset`, default 0), `--pretui-affix-shadow` (applied while pinned, default none) and `--pretui-z-sticky` (the kit's sticky tier, 10).
+
+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                                   |
+| ------------------------------ | ------------------------------------------- |
+| Ant `<Affix offsetTop={0}>`    | `<Affix>`                                   |
+| Ant `offsetBottom`             | `@position='bottom'` + `@offset`            |
+| Ant `onChange(affixed)`        | `@onChange`, or the yielded `pinned`        |
+| Ant `target={() => container}` | the nearest scroll container, found for you |
+| MUI `useScrollTrigger()`       | the yielded `pinned` state                  |

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

@@ -0,0 +1,73 @@
+// Pretui — Affix usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Affix } from './affix';
+import { Toolbar } from './toolbar';
+import { Button } from './button';
+
+const PARAS = Array.from({ length: 12 }, (_, i) => `Roast note ${i + 1}: first crack at 9:40, dropped at 11:05, development 17%.`);
+
+export class AffixUsage extends Component {
+  paras = PARAS;
+  @tracked pinned = false;
+  setPinned = (v: boolean) => (this.pinned = v);
+  get usage() {
+    return "<Affix @onChange={{this.setPinned}} as |pinned|>\n  <Toolbar>…</Toolbar>\n</Affix>";
+  }
+  <template>
+    <FreestyleUsage
+      @name='Affix'
+      @description='Pins a child, usually a Toolbar, to the top or bottom of its scroll container once it scrolls past. It is CSS sticky against the pane, not the window, with an IntersectionObserver that reports whether it is pinned. Scroll the demo pane.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='af-demo'>
+          <p class='af-demo-p'>Lot 7 · Huila, washed</p>
+          <Affix @onChange={{this.setPinned}} as |pinned|>
+            <div class='af-demo-bar' data-pinned={{if pinned 'true' 'false'}}>
+              <Toolbar><Button @size='s'>Save</Button><Button @size='s' @appearance='outlined'>Share</Button></Toolbar>
+            </div>
+          </Affix>
+          {{#each this.paras as |note|}}<p class='af-demo-p'>{{note}}</p>{{/each}}
+        </div>
+        <p class='af-demo-state'>Pinned: {{if this.pinned 'yes' 'no'}}</p>
+      </:example>
+      <:api as |Args|>
+        <Args.String @name='position' @defaultValue='top' @description='top or bottom.' />
+        <Args.String @name='offset' @defaultValue='0' @description='Distance from that edge while pinned.' />
+        <Args.Action @name='onChange' @description='true when pinned, false when released.' />
+        <Args.Yield @name='default' @description='The child, yielded whether it is pinned.' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .af-demo {
+        block-size: 14rem;
+        overflow-y: auto;
+        padding-inline: var(--space-4, 0.6875rem);
+        border-radius: var(--radius-surface, 10px);
+        box-shadow: 0 0 0 1px var(--border);
+        background: var(--card);
+      }
+      .af-demo-p {
+        font-size: var(--text-ui-md, 0.78rem);
+      }
+      .af-demo-bar {
+        padding-block: var(--space-2, 0.375rem);
+        background: var(--card);
+      }
+      .af-demo-bar[data-pinned='true'] {
+        box-shadow: 0 1px 0 var(--border);
+      }
+      .af-demo-state {
+        margin: var(--space-2, 0.375rem) 0 0;
+        font-size: var(--text-ui-sm, 0.72rem);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_AFFIX: Record<string, unknown> = {
+  Affix: AffixUsage,
+};

package/bundled-realms/pretui/components/agent-question.gts

@@ -0,0 +1,116 @@
+// Pretui — AgentQuestion: a question the agent is waiting on, answered in place.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { fn } from '@ember/helper';
+
+export interface AgentQuestionSignature {
+  Args: {
+    question: string;
+    options?: string[];
+    answered?: string;
+    onAnswer?: (answer: string) => void;
+  };
+  Element: HTMLDivElement;
+}
+
+// ASK verb: option pills + free answer; settles to a quiet answered line.
+export class AgentQuestion extends Component<AgentQuestionSignature> {
+  @tracked picked?: string = this.args.answered;
+  settle = (value: string) => {
+    this.picked = value;
+    this.args.onAnswer?.(value);
+  };
+  onKey = (e: Event) => {
+    let ev = e as KeyboardEvent;
+    let input = ev.target as HTMLInputElement;
+    if (ev.key === 'Enter' && input.value) {
+      this.settle(input.value);
+    }
+  };
+  <template>
+    {{#if this.picked}}
+      <div class='pretui-answered' data-test-pretui-agent-question ...attributes>
+        <span class='pretui-answered-check'>✓</span>
+        {{@question}}
+        <b>{{this.picked}}</b>
+      </div>
+    {{else}}
+      <div class='pretui-question' data-test-pretui-agent-question ...attributes>
+        <div class='pretui-question-text'>{{@question}}</div>
+        <div class='pretui-question-opts'>
+          {{#each @options as |option|}}
+            <button type='button' class='pretui-qpill' {{on 'click' (fn this.settle option)}}>{{option}}</button>
+          {{/each}}
+        </div>
+        <input class='pretui-qinput' aria-label='Answer' placeholder='Or type an answer…' {{on 'keydown' this.onKey}} />
+      </div>
+    {{/if}}
+    <style scoped>
+      @layer PretComponent {
+        .pretui-question {
+          display: grid;
+          gap: 8px;
+        }
+        .pretui-question-text {
+          font-weight: 500;
+        }
+        .pretui-question-opts {
+          display: flex;
+          flex-wrap: wrap;
+          gap: 6px;
+        }
+        .pretui-qpill {
+          display: inline-flex;
+          align-items: center;
+          height: 26px;
+          padding: 0 calc(6px * var(--pretui-capsule-base, 1.35) + 13px * var(--pretui-radius-encroach, 0.35));
+          border-radius: 13px;
+          border: 0;
+          background: var(--card);
+          box-shadow: var(--pretui-shadow-control, 0 0 0 1px var(--border));
+          font: inherit;
+          font-size: var(--text-ui, 12px);
+          font-weight: 500;
+          cursor: pointer;
+          color: var(--foreground);
+        }
+        .pretui-qpill:hover {
+          background: var(--hover, var(--boxel-100));
+        }
+        .pretui-qinput {
+          display: flex;
+          align-items: center;
+          height: var(--control-h, 28px);
+          padding: 0 9px;
+          border: 0;
+          border-radius: var(--radius);
+          font: inherit;
+          font-size: var(--text-ui-md, 12.5px);
+          color: var(--foreground);
+          background: var(--field, var(--boxel-light));
+          box-shadow: 0 0 0 1px var(--input);
+          width: 100%;
+        }
+        .pretui-qinput:focus {
+          outline: none;
+          box-shadow: 0 0 0 2px var(--primary), var(--pretui-shadow-inset, inset 0 1px 2px rgb(0 0 0 / 0.16));
+        }
+        .pretui-answered {
+          display: flex;
+          align-items: center;
+          gap: 8px;
+          font-size: var(--text-ui-md, 12.5px);
+          color: var(--muted-foreground);
+        }
+        .pretui-answered-check {
+          color: var(--success, var(--boxel-success));
+        }
+        .pretui-answered b {
+          color: var(--foreground);
+          font-weight: 500;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/agent-question.md

@@ -0,0 +1,50 @@
+## What it is
+
+The ASK verb: a question from the agent, option pills to answer it, a free-text fallback, and a quiet settled line once answered. Use it when an agent needs a decision to continue. If it needs _approval_ of work already staged, **ApprovalFooter**. If it is reporting rather than asking, **WorkItem** or **ResultCard**. If the question is a form, it is a form — use **Form**.
+
+## The contract
+
+```
+@question: string   (required)
+@options?: string[]
+@answered?, @onAnswer?(answer: string)
+```
+
+**Options and free text coexist.** The pills are shortcuts, not a closed set — the input accepts anything and commits on Enter. That is the right model for an agent conversation, where the agent's guesses at likely answers should not constrain the human.
+
+**It settles.** Once answered, the component collapses to a quiet answered line rather than staying open. `@answered` seeds that state, so a transcript re-rendered from history shows settled questions settled. This is the territory's general shape — attention states are loud, resolved states recede — and it is what keeps a long transcript readable.
+
+`@onAnswer` fires for both paths; the caller cannot tell a pill from typed text, which is deliberate (the answer is the answer).
+
+## Prior art
+
+No component kit has this. The references are chat products: Slack's interactive message buttons, ChatGPT's suggested replies, and the general "quick reply" pattern from messaging platforms.
+
+The decisions worth comparing:
+
+- **Quick-reply chips in messaging platforms are usually a closed set** — you tap one or you type something the bot cannot parse. Here the pills and the free-text field are the same commitment, and both settle the question.
+- **Most chat UIs leave answered prompts fully rendered**, so scrolling back through a conversation means scrolling past dozens of dead button rows. Settling to a quiet line is a better long-transcript behaviour and is the same instinct **Fold** and **CollapsedTurn** apply elsewhere in this territory.
+
+Where it is thin: no multi-select answers, no typed answer validation, no "I don't know" / decline path, and no timeout or default. An agent blocked on a question that never gets answered has no expressed fallback.
+
+## Accessibility
+
+No APG pattern; the pieces are a group of buttons plus a text field.
+
+Gaps, and they are the same shape as the rest of the territory — the semantics are fine, the _announcement_ is missing:
+
+- **The question's arrival is not announced.** An agent asking a question mid-run is precisely a status message that must reach the user (**WCAG 4.1.3**), and there is no live region. A screen-reader user reading a transcript will not know the agent has stopped and is waiting. This is the same gap **ApprovalFooter** has and it is the territory's central accessibility problem.
+- **The question is not programmatically the label of the answer controls.** The pills and the input are siblings of the question text, so a screen-reader user tabbing to the input hears an unlabelled text field. `aria-labelledby` from the input to the question, and `role="group"` with the same, would fix both.
+- **The option pills are plain buttons with no group semantics.** For a single-choice answer the accurate model is `role="radiogroup"` — the same correction **FilterChips** and **SegmentedControl** need — though the free-text escape complicates it; a labelled `role="group"` is the minimum.
+- **Commit-on-Enter is undiscoverable.** There is no visible submit button and no hint that Enter commits. For keyboard and screen-reader users that is a **WCAG 3.3.2 Labels or Instructions** gap; a visually-hidden instruction or a real submit button would close it.
+- **The settled transition is silent**, and the answered line's relationship to the original question is visual.
+- **No `aria-live` on the settled state** means a user who answers by pill gets no confirmation that their answer registered.
+- Pill target sizes should be checked against WCAG **2.5.8**'s 24×24 minimum.
+
+## Theming
+
+Attention tone for the unanswered state (the territory's reserved "a human must act now" hue), receding to `--muted-foreground` once settled. Pills carry **Chip**- or **Button**-family dress; the input carries the kit's control tokens (`--field`, `--input`, `--primary`, `--control-h`, `--radius`).
+
+The unanswered-to-settled contrast is the thing a theme must get right: the question must be visibly _pending_ in a scroll-back of forty transcript rows, and visibly _done_ afterwards. If a theme flattens that difference, a long transcript stops showing where the agent is blocked — which is the one thing the territory exists to make obvious.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.