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

package/bundled-realms/pretui/components/command-palette.md

@@ -0,0 +1,47 @@
+## What it is
+
+The ⌘K palette: a search field over the same command tree **Menu** renders, opened by a global shortcut.
+
+One definition, two surfaces — the commands in a menubar and the commands in a palette are the same tree, not two lists that drift apart.
+
+## The contract
+
+```
+@items (required) — the same tree Menu renders
+@open?, @onClose (required) — the palette's visibility
+@onOpen?       — opens the palette; supply it to enable @hotkey
+@hotkey?       — global shortcut that opens the palette. Default 'Mod+K'; needs @onOpen
+@placeholder?, @label?, @emptyMessage?
+@onSelect?     — fires after any command runs
+@platform?     — force the shortcut platform
+```
+
+**`@hotkey` does nothing without `@onOpen`.** The palette cannot open itself into a caller's state, so the global shortcut is only wired when there is something to call — the same conditional-affordance rule the kit applies everywhere.
+
+**Shortcuts render through Kbd**, so a command's accelerator shows the platform-correct face without the command tree knowing which platform it is on.
+
+**`@emptyMessage` means no matches says something** rather than showing an empty list.
+
+## Prior art
+
+The command palette in editors and the `cmdk` family.
+
+Where Pretui is better: sharing the menu tree. Most palettes take their own flat command list, which means a product maintains two definitions of what its commands are and they disagree within a release.
+
+Where it is thinner: no fuzzy-match scoring controls, no command groups or scoping beyond the tree's own structure, no recent commands, and no nested palette modes ("type > to run a command").
+
+## Accessibility
+
+- **The field is a real search input** and the list a real listbox, so the arrow/Enter model is the platform's.
+- **The palette is named**, which matters because it is a dialog appearing over whatever the reader was doing.
+- **A global hotkey is a strong commitment**: `Mod+K` is taken from the page, and a reader who uses that chord for something else loses it. It is opt-in through `@onOpen` rather than always on.
+- **Shortcut faces come from Kbd**, which means each one carries the platform-neutral spelling as its announced form rather than a run of glyphs.
+- **`@emptyMessage` is announced**, so a search with no results is a stated outcome.
+
+## Theming
+
+The palette takes the kit's overlay, input and menu tokens; the shortcut faces take **Kbd**'s.
+
+Sharing the menu tokens is what makes a command look the same in the palette as it does in the menubar — which is the visible half of the shared-tree design.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/command-palette.usage.gts

@@ -0,0 +1,95 @@
+// Pretui — CommandPalette usage page.
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { CommandPalette } from './command-palette';
+import { Kbd } from './kbd';
+import { MenuState } from '../demo-menu';
+
+// ── CommandPalette ───────────────────────────────────────────────────────
+class CommandPaletteUsage extends MenuState {
+  <template>
+    <FreestyleUsage
+      @name='CommandPalette'
+      @description='The same MenuNode tree Menu renders in place, seen flattened and filtered. Typing searches every command beneath the current scope — including the ones nested inside submenus, with their path shown — and the matched characters are highlighted by a dependency-free fuzzy matcher that prefers word-boundary initials, so "cs" finds Copy lot link before it finds an "s" in the middle of a word. Descending into a submenu pushes a breadcrumb scope (kbar’s model) so nesting survives the flattening; Backspace or ← on an empty query pops back out, and Esc leaves one scope at a time before closing. Checkmark state travels with the node, so a toggle is a toggle in both surfaces. It is a combobox, not a menu: the input keeps focus and aria-activedescendant points at the active row, which is the pattern assistive tech actually handles for a filtered list.'
+    >
+      <:example>
+        <div class='pal-row'>
+          <Button
+            @tone='neutral'
+            @appearance='outlined'
+            {{on 'click' this.openPalette}}
+          >Open palette
+            <Kbd @value='Mod+K' @platform={{this.platformValue}} /></Button>
+          <span class='menu-log'>last action:
+            <strong>{{this.log}}</strong></span>
+        </div>
+        <CommandPalette
+          @items={{this.items}}
+          @open={{this.paletteOpen}}
+          @onOpen={{this.openPalette}}
+          @onClose={{this.closePalette}}
+          @platform={{this.platformValue}}
+          @label='Sourcing desk commands'
+          @placeholder='Search lot commands…'
+        />
+        <p class='menu-hint'>Try
+          <em>“export”</em>
+          — it is two submenus deep and still one keystroke away. Then open
+          <em>Share</em>
+          to see the breadcrumb, and press Backspace on an empty query to come
+          back.</p>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='items'
+          @description='The same MenuNode tree Menu takes — nothing is redefined for the palette. Sections flatten into group headers; submenus become enterable scopes AND searchable branches; description and keywords widen what a node matches on without widening what it highlights.'
+          @value={{this.items}}
+        />
+        <Args.Base
+          @name='open / onClose / onOpen'
+          @description='Controlled visibility over a native <dialog>, so the top layer, the focus trap, the backdrop and Escape come from the platform rather than a z-index and a scroll lock.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='hotkey'
+          @description='Global shortcut that opens the palette (default Mod+K); needs @onOpen. The listener is owned by an ember-modifier and removed on teardown.'
+          @value='Mod+K'
+          @defaultValue='Mod+K'
+        />
+        <Args.Base
+          @name='placeholder / label / emptyMessage / platform'
+          @description='Copy knobs. Everything visual is a token; --pretui-palette-hit re-tints the match highlight on its own.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pal-row {
+        display: flex;
+        align-items: center;
+        gap: var(--space-4, 11px);
+        flex-wrap: wrap;
+      }
+      .menu-log {
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .menu-log strong {
+        color: var(--foreground);
+        font-weight: 600;
+      }
+      .menu-hint {
+        margin: var(--space-4, 11px) 0 0;
+        max-width: 62ch;
+        font-size: var(--text-ui-sm, 11.5px);
+        line-height: 1.6;
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_COMMAND_PALETTE: Record<string, unknown> = {
+  CommandPalette: CommandPaletteUsage,
+};

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

@@ -0,0 +1,2 @@
+// Pretui — Command: The shadcn / cmdk name for CommandPalette.
+export { CommandPalette as Command } from './command-palette';

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

@@ -0,0 +1,45 @@
+## What it is
+
+**CommandPalette** under the name shadcn and cmdk use. The export is the same class — `import { Command } from './command';` resolves to CommandPalette — so the tile exists for a port of a shadcn `Command` block or an agent whose first guess is that word. The contract and the depth are on **CommandPalette**; this page maps cmdk's parts onto it. **Menu** renders the same tree in place; **ContextMenu** and **Menubar** are the other surfaces over it.
+
+## The contract
+
+```
+@items           — required; the MenuNode tree Menu renders
+@open?, @onClose — required onClose; controlled visibility over a native <dialog>
+@onOpen?         — opens the palette; supply it to enable @hotkey
+@hotkey?         — global shortcut (default 'Mod+K'); does nothing without @onOpen
+@placeholder?, @label?, @emptyMessage?
+@onSelect?       — after any command runs
+@platform?       — force the shortcut platform
+```
+
+**There are no parts to assemble.** cmdk is a set of components a consumer nests; here the nesting is data — sections become group headers, submenus become enterable scopes that are also searchable, and the input, list and empty state are rendered for you.
+
+## Prior art
+
+**shadcn `Command`** wraps **cmdk**: `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandGroup`, `CommandItem` (with `onSelect`, `keywords`, `disabled`), `CommandEmpty`, `CommandShortcut`, `CommandSeparator`, and `shouldFilter` / `filter` / `loop` on the root. **Mantine Spotlight** is a store-driven modal with `actions`, `nothingFound` and `shortcut`.
+
+Where this is better: one command tree shared with Menu, so the menubar and the palette cannot disagree about what the commands are; nested submenus flatten into search with their path shown, and descend into breadcrumb scopes (kbar's model), where cmdk has flat groups; the fuzzy matcher prefers word-boundary initials; the dialog is a native `<dialog>`, so top layer, focus trap and Escape are the platform's.
+
+Where it is thinner: no `filter` function or `shouldFilter` escape hatch, no `loop`, no per-item render slot — an item is a MenuNode, not JSX — and no recent-commands or mode prefix.
+
+## Accessibility
+
+CommandPalette's: a combobox, not a menu. The input keeps focus and `aria-activedescendant` points at the active row, which is the pattern assistive tech handles for a filtered list; the palette is a named dialog; shortcut faces render through **Kbd** so they are announced as text rather than glyphs; `@emptyMessage` makes a fruitless search a stated outcome. The global hotkey takes `Mod+K` from the page and is opt-in through `@onOpen`.
+
+## Theming
+
+CommandPalette's: the kit's overlay, input and menu tokens, so a command looks the same in the palette as in the menubar, plus `--pretui-palette-hit` for the match highlight. Nothing is themed under a Command name.
+
+## React ecosystem
+
+| shadcn / cmdk                              | Pretui                                              |
+| ------------------------------------------ | --------------------------------------------------- |
+| `<Command>` + `<CommandDialog>`            | `<Command @open @onClose>` — the dialog is built in |
+| `<CommandInput placeholder>`               | `@placeholder`                                      |
+| `<CommandList>` / `<CommandGroup heading>` | sections in `@items`                                |
+| `<CommandItem onSelect keywords>`          | a MenuNode `action` with `keywords`                 |
+| `<CommandEmpty>`                           | `@emptyMessage`                                     |
+| `<CommandShortcut>`                        | the node's `kbd`, rendered by Kbd                   |
+| `shouldFilter` / `filter` / `loop`         | not offered                                         |

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

@@ -0,0 +1,58 @@
+// Pretui — Command usage page.
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { Command } from './command';
+import { Kbd } from './kbd';
+import { MenuState } from '../demo-menu';
+
+class CommandUsage extends MenuState {
+  <template>
+    <FreestyleUsage
+      @name='Command'
+      @description='CommandPalette under the shadcn / cmdk name: a search field over the same MenuNode tree Menu renders, opened by a global shortcut. Reach for this import when a port or an agent already speaks that vocabulary; the component, its contract and its writeup are CommandPalette’s.'
+      @source="<Command @items={{this.items}} @open={{this.paletteOpen}} @onOpen={{this.openPalette}} @onClose={{this.closePalette}} />"
+    >
+      <:example>
+        <Button
+          @tone='neutral'
+          @appearance='outlined'
+          {{on 'click' this.openPalette}}
+        >Open palette
+          <Kbd @value='Mod+K' @platform={{this.platformValue}} /></Button>
+        <Command
+          @items={{this.items}}
+          @open={{this.paletteOpen}}
+          @onOpen={{this.openPalette}}
+          @onClose={{this.closePalette}}
+          @platform={{this.platformValue}}
+          @label='Sourcing desk commands'
+          @placeholder='Search lot commands…'
+        />
+        <p class='pretui-demo-readout'>last action: <strong>{{this.log}}</strong></p>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='items'
+          @description='The MenuNode tree — cmdk’s CommandGroup / CommandItem nesting as data.'
+          @value={{this.items}}
+        />
+        <Args.Base
+          @name='open / onOpen / onClose'
+          @description='Controlled visibility over a native <dialog>; cmdk’s CommandDialog.'
+          @hideControls={{true}}
+        />
+        <Args.String @name='hotkey' @defaultValue='Mod+K' @description='Global shortcut; needs @onOpen.' />
+        <Args.Base
+          @name='placeholder / label / emptyMessage / platform'
+          @description='Copy knobs — CommandInput placeholder, dialog name, CommandEmpty text.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_COMMAND: Record<string, unknown> = {
+  Command: CommandUsage,
+};

package/bundled-realms/pretui/components/compaction-chip.gts

@@ -0,0 +1,273 @@
+// Pretui — CompactionChip: a marker that earlier context was compacted, expandable to what was kept.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { guidFor } from '@ember/object/internals';
+import { Spinner } from './spinner';
+import { Collapse } from '../internal/agentic-chat';
+
+// ── CompactionChip ───────────────────────────────────────────────────────
+// Compaction is the moment a session quietly loses its history. The law the
+// spec states is that it must be *rendered* — a transcript that silently
+// forgets is a transcript the reader cannot reason about. So: a marker in
+// the stream while it runs, and a receipt afterwards that expands to the
+// written summary of what was condensed.
+//
+// The counts are caller data and are rendered as text beside the label, not
+// only as a tooltip, so the receipt survives the screenshot test.
+
+export interface CompactionChipSignature {
+  Args: {
+    /** 'running' while compacting, 'done' once the summary exists */
+    state?: 'running' | 'done';
+    /** label while running (default 'Compacting long history') */
+    runningLabel?: string;
+    /** label once settled (default 'History compacted') */
+    doneLabel?: string;
+    /** how many messages were condensed */
+    messageCount?: number;
+    /** how many tool calls were condensed */
+    toolCallCount?: number;
+    /** the written summary; without one, the chip does not offer to expand */
+    summary?: string;
+    /** starting disclosure state when uncontrolled */
+    defaultExpanded?: boolean;
+    /** controlled disclosure state */
+    expanded?: boolean;
+    /** fires with the requested disclosure state */
+    onExpandedChange?: (expanded: boolean) => void;
+  };
+  Blocks: {
+    /** rich summary content, replacing the `@summary` string */
+    summary: [];
+  };
+  Element: HTMLDivElement;
+}
+
+export class CompactionChip extends Component<CompactionChipSignature> {
+  @tracked private innerExpanded?: boolean;
+
+  private panelId = guidFor(this) + '-summary';
+
+  get state(): 'running' | 'done' {
+    return this.args.state ?? 'done';
+  }
+  get running(): boolean {
+    return this.state === 'running';
+  }
+  get label(): string {
+    return this.running
+      ? (this.args.runningLabel ?? 'Compacting long history')
+      : (this.args.doneLabel ?? 'History compacted');
+  }
+  /** the condensed-counts line, assembled as text so it reads in greyscale */
+  get counts(): string | undefined {
+    let parts: string[] = [];
+    let messages = this.args.messageCount;
+    let calls = this.args.toolCallCount;
+    if (messages !== undefined) {
+      parts.push(messages + (messages === 1 ? ' message' : ' messages'));
+    }
+    if (calls !== undefined) {
+      parts.push(calls + (calls === 1 ? ' tool call' : ' tool calls'));
+    }
+    return parts.length ? parts.join(' · ') + ' condensed' : undefined;
+  }
+  get expandable(): boolean {
+    return !this.running;
+  }
+  get expanded(): boolean {
+    return (
+      this.args.expanded ?? this.innerExpanded ?? this.args.defaultExpanded ?? false
+    );
+  }
+
+  toggle = () => {
+    let next = !this.expanded;
+    if (this.args.expanded === undefined) {
+      this.innerExpanded = next;
+    }
+    this.args.onExpandedChange?.(next);
+  };
+
+  <template>
+    <div
+      class='pretui-compaction'
+      data-state={{this.state}}
+      data-test-pretui-compaction-chip
+      ...attributes
+    >
+      <div class='pretui-compaction-marker'>
+        <span class='pretui-compaction-rule' aria-hidden='true'></span>
+        {{#if this.expandable}}
+          <button
+            type='button'
+            class='pretui-compaction-chip'
+            aria-expanded={{if this.expanded 'true' 'false'}}
+            aria-controls={{this.panelId}}
+            data-test-pretui-compaction-toggle
+            {{on 'click' this.toggle}}
+          >
+            <svg viewBox='0 0 24 24' aria-hidden='true' focusable='false'>
+              <path
+                d='M4 8h16M7 12h10M10 16h4'
+                fill='none'
+                stroke='currentColor'
+                stroke-width='2'
+                stroke-linecap='round'
+              />
+            </svg>
+            <span class='pretui-compaction-label'>{{this.label}}</span>
+            {{#if this.counts}}
+              <span class='pretui-compaction-counts'>{{this.counts}}</span>
+            {{/if}}
+            <svg
+              class='pretui-compaction-chev'
+              viewBox='0 0 24 24'
+              aria-hidden='true'
+              focusable='false'
+            >
+              <path
+                d='M6 9l6 6 6-6'
+                fill='none'
+                stroke='currentColor'
+                stroke-width='2.2'
+                stroke-linecap='round'
+                stroke-linejoin='round'
+              />
+            </svg>
+          </button>
+        {{else}}
+          <span class='pretui-compaction-chip' role='status'>
+            <Spinner @size={{11}} />
+            <span class='pretui-compaction-label'>{{this.label}}</span>
+          </span>
+        {{/if}}
+        <span class='pretui-compaction-rule' aria-hidden='true'></span>
+      </div>
+
+      {{#if this.expandable}}
+        <Collapse @open={{this.expanded}} id={{this.panelId}}>
+          <div class='pretui-compaction-summary'>
+            {{#if (has-block 'summary')}}
+              {{yield to='summary'}}
+            {{else if @summary}}
+              <p>{{@summary}}</p>
+            {{else}}
+              <p class='pretui-compaction-none'>No written summary was kept for
+                this compaction.</p>
+            {{/if}}
+          </div>
+        </Collapse>
+      {{/if}}
+    </div>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-compaction {
+          display: flex;
+          flex-direction: column;
+          gap: 4px;
+          font-size: var(--text-ui-sm, 11.5px);
+        }
+        .pretui-compaction-marker {
+          display: flex;
+          align-items: center;
+          gap: 10px;
+        }
+        .pretui-compaction-rule {
+          flex: 1;
+          height: 1px;
+          min-width: 12px;
+          background: var(--border);
+        }
+        .pretui-compaction-chip {
+          display: inline-flex;
+          align-items: center;
+          gap: 7px;
+          min-height: 26px;
+          padding: 0 10px;
+          border: 0;
+          border-radius: 999px;
+          background: var(--inset, var(--boxel-100));
+          box-shadow: var(
+            --pretui-shadow-hairline,
+            0 0 0 1px var(--border)
+          );
+          font: inherit;
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+          flex: none;
+          max-width: 100%;
+        }
+        button.pretui-compaction-chip {
+          cursor: pointer;
+        }
+        button.pretui-compaction-chip:hover {
+          background: var(--hover, var(--boxel-100));
+          color: var(--foreground);
+        }
+        button.pretui-compaction-chip:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+        .pretui-compaction-chip > svg {
+          width: 13px;
+          height: 13px;
+          flex: none;
+          color: var(--ink-3, var(--boxel-400));
+        }
+        .pretui-compaction-label {
+          font-weight: 500;
+          min-width: 0;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+        .pretui-compaction-counts {
+          flex: none;
+          color: var(--ink-3, var(--boxel-400));
+          font-variant-numeric: tabular-nums;
+        }
+        .pretui-compaction-chev {
+          transition: transform 300ms
+            var(--pretui-ease-enter, cubic-bezier(0.22, 0.61, 0.25, 1));
+        }
+        .pretui-compaction-chip[aria-expanded='true'] .pretui-compaction-chev {
+          transform: rotate(180deg);
+        }
+        .pretui-compaction-summary {
+          margin: 4px auto 0;
+          max-width: 62ch;
+          padding: 9px 12px;
+          border-radius: 10px;
+          background: var(--inset, var(--boxel-100));
+          box-shadow: var(
+            --pretui-shadow-hairline,
+            0 0 0 1px var(--border)
+          );
+          color: var(--muted-foreground);
+          line-height: 1.6;
+        }
+        .pretui-compaction-summary p {
+          margin: 0;
+        }
+        .pretui-compaction-none {
+          color: var(--ink-3, var(--boxel-400));
+          font-style: italic;
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-compaction-chev {
+            transition: none;
+          }
+        }
+        @media (any-pointer: coarse) {
+          button.pretui-compaction-chip {
+            min-height: 44px;
+            padding: 0 16px;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/compaction-chip.md

@@ -0,0 +1,45 @@
+## What it is
+
+The marker in a transcript where history was condensed: what was compacted, how much of it, and — once written — the summary that replaced it.
+
+## The contract
+
+```
+@state?         — 'running' while compacting, 'done' once the summary exists
+@runningLabel?  — label while running. Default 'Compacting long history'
+@doneLabel?     — label once settled. Default 'History compacted'
+@messageCount?  — how many messages were condensed
+@toolCallCount? — how many tool calls were condensed
+@summary?       — the written summary; WITHOUT one, the chip does not offer to expand
+@defaultExpanded?, @expanded?, @onExpandedChange? — the disclosure
+```
+
+**Without `@summary` the chip does not offer to expand.** A disclosure that opens onto nothing is worse than no disclosure — the same rule as **TaskRow**'s details and **AssetWell**'s retry button.
+
+**The two counts are separate because they are different things.** Twenty messages and two tool calls is a different compaction from two messages and twenty tool calls, and a single "22 items" hides which.
+
+**`@state` is the caller's**, because compaction is something the host is doing, not something this chip performs.
+
+## Prior art
+
+The compaction marker in long-running agent sessions.
+
+Where Pretui is better: the summary being the gate on the disclosure, and the counts being separated by kind. Most implementations render a line of text and nothing openable, which makes a compaction an irreversible gap in the transcript from the reader's point of view.
+
+Where it is thinner: no way to reach the original messages — the summary is what remains — no partial or per-range compaction display, and no indication of *why* compaction happened.
+
+## Accessibility
+
+- **It is a disclosure with the full contract** — a real button, `aria-expanded`, `aria-controls` — and the collapsed content is inert rather than merely hidden.
+- **The running and settled labels are both text**, so the state is announced rather than carried by an animation.
+- **The counts are in the label**, so what was condensed is available without opening anything.
+- **Expanding is offered only when there is something to read**, which means a reader is never sent into an empty panel.
+- **A compaction is a gap in the record.** Making it a visible, named, expandable marker rather than a silent removal is the accessibility property that matters most here — the transcript says what it no longer holds.
+
+## Theming
+
+The chip takes the agentic set's shared tier tokens and the kit's disclosure treatment; the running state uses **TextShimmer**, the same as **Thinking**'s working label.
+
+Sharing the shimmer is deliberate — "the agent is doing something" should look the same everywhere in a transcript, whether it is thinking or compacting.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.