@liberation-data/desk 0.1.0

package/llms.txt

@@ -0,0 +1,410 @@
+# @liberation-data/desk
+
+A desktop for the web, in React: windows that fill the desk, layered, and arrange when asked, with a dock, a menu bar,
+commands routed to whoever is responsible, and the controls to fill the windows. Apache-2.0.
+
+This file is the whole public surface in one place, for a coding agent. Prose for people:
+`docs/guide.md`. How it should look and behave: `HIG.md`.
+
+## Install and entry points
+
+```
+npm install @liberation-data/desk        # peer: react ^19
+```
+
+```ts
+import { createDesk }                    from '@liberation-data/desk'        // no DOM, no React
+import { Desktop, DeskProvider }         from '@liberation-data/desk/react'  // components and hooks
+import '@liberation-data/desk/desk.css'                                      // tokens and styles
+```
+
+## The shape of an app
+
+```tsx
+const desk = createDesk()
+
+<DeskShell desk={desk}>         {/* desk + bus + toasts; or DeskProvider on its own */}
+      <MenuBar menus={…} status={…} />
+      <div className="screen">  {/* position: relative; the stage fills it */}
+        <Desktop title={id => TITLES[id]} renderWindow={id => SURFACES[id]} empty={…} />
+        <InputBar onSubmit={…} />
+        <Dock entries={…} />
+        <SearchPalette open={…} onOpenChange={…} search={…} />
+      </div>
+</DeskShell>
+```
+
+Rules that are easy to get wrong:
+- `.desk-stage` fills its parent: give the parent a height, and `position: relative` if the dock or input
+  bar overlays it. Set `--desk-inset-bottom` to the height of anything overlaying the bottom.
+- A window is an id; `renderWindow(id)` says what it looks like. Every open window renders, including ones
+  offstage in the touch layout — that is what preserves their state.
+- Opening a window that is already open focuses it. For a second window onto the same thing use
+  `openInstance`, and render by `windowType(id)`.
+
+## Core: `@liberation-data/desk`
+
+```ts
+createDesk(options?: DeskOptions): Desk
+interface DeskOptions { cascade?: Partial<CascadeOptions>; stage?: () => Size; initial?: DeskState }
+
+interface Desk {
+  getState(): DeskState
+  subscribe(listener: (state: DeskState) => void): () => void
+  open(id: string, options?: { mode?: 'filled' | 'floating'; frame?: Frame }): void   // default fills; a frame floats
+  openInstance(type: string, options?): string    // 'query', then 'query#2' — returns the id it opened
+  close(id: string): void
+  closeAll(): void
+  focus(id: string): void
+  float(id: string, frame?: Frame): void          // no frame: last place it sat, else the next cascade step
+  fill(id: string): void                          // fill the desk; remembers the frame for float()
+  toggleMode(id: string): void                    // zoom: fill ⇄ free
+  placeAll(frames: Record<string, Frame>): void   // free windows at these frames; Arrange uses it
+  restore(state: DeskState): void                 // e.g. from a URL; normalised, not trusted
+  setStage(stage: () => Size): void
+}
+
+interface DeskState {
+  windows: readonly DeskWindow[]   // the order they were opened = the order Arrange lays out
+  stack: readonly string[]         // back to front; the last one is key
+}
+type DeskWindow = { id: string; mode: 'filled' } | { id: string; mode: 'floating'; frame: Frame }
+interface Frame { x: number; y: number; width: number; height: number }
+
+focusedId(state): string | null
+windowType(id): string                            // 'query#2' → 'query'; what to render
+instancesOf(state, type): DeskWindow[]            // every window of a kind
+isOpen(state, id): boolean
+normalise(state): DeskState
+cascadeFrame(slot, stage, options?): Frame
+cascadeSlot(frame, stage, options?): number
+nextCascadeFrame(windows, stage, options?): Frame
+EMPTY: DeskState
+```
+
+Every window opens filled, layered over the others; a filled window follows the stage's size. Arrange
+lays windows out once as free windows (`placeAll`); moving or resizing one changes only that one. Dragging a
+filled window frees it where it sits. Edge drops take a half; double-click or the green control zooms. State is immutable; every mutator returns void and notifies
+subscribers only when something actually changed.
+
+### URL and history
+
+```ts
+syncWithLocation(desk, stage: () => Size, options?: LocationOptions, env?: LocationEnv): () => void
+serialize(state, options?): URLSearchParams        // #w=rides,map~&f=map   (`~` = free; the rest fill)
+parse(params, stage, options?): DeskState
+interface LocationOptions { key?: 'w'; focusKey?: 'f'; isKnown?: (id: string) => boolean }
+```
+
+Opening or closing pushes history (Back closes); focus and mode changes replace it. Frames are never in the
+URL. Other hash parameters are left alone. A URL naming no windows adopts whatever the app opened.
+
+### Commands (the responder chain)
+
+```ts
+perform(desk, command: string, args?, options?: ChainOptions): boolean      // true if something handled it
+canPerform(desk, command: string, options?: ChainOptions): boolean          // what a menu asks
+addCommandHandler(element: EventTarget, command, handler, { enabled? }): () => void
+addDeskCommands(stage: EventTarget, desk): () => void
+chainStart(desk, options?): EventTarget
+windowElement(doc, id): Element | null
+DeskCommands = { closeWindow, zoomWindow, arrange, nextWindow, previousWindow }
+// arrange is answered by a mounted Desktop: 1 fills, 2 split, 3 one tall + two stacked, 4+ a grid of usable cells;
+// the focused window takes the first place. Put it in the Window menu as "Arrange", shortcut 'mod+alt+a'.
+WINDOW_ATTRIBUTE = 'data-desk-window'; STAGE_ATTRIBUTE = 'data-desk-stage'
+```
+
+The chain is the DOM: focused element → its window → stage → document. The first responder that implements
+a command decides; if it is disabled the command stops there (AppKit's rule). Events are `desk:perform` and
+`desk:can-perform`, bubbling and composed.
+
+### Shortcuts
+
+```ts
+bindShortcuts(desk, keymap: Record<string, string>, { target?, apple? }): () => void
+parseShortcut('mod+shift+z'): Shortcut
+matchesShortcut(event, shortcut, apple?): boolean
+formatShortcut('mod+comma', apple?): string        // '⌘,' or 'Ctrl+,'
+isApplePlatform(): boolean
+isInstalledApp(): boolean                          // gate ⌘W / ⌘` on this; never take ⌘T or ⌘N
+titleCase('ride card'): string                    // 'Ride Card' — app and window names; a document keeps its own name
+isTitleCase(name): boolean                         // for a test over the names an app defines
+```
+
+`mod` is ⌘ on Apple, Ctrl elsewhere. Matching also falls back to the physical key, so ⌥] works on a Mac. A
+shortcut nothing handles leaves the browser's default alone. Bare keys are ignored while typing in a field.
+
+### Dragging between windows
+
+```tsx
+useDragSource<T>({ type, disabled? }): { dragProps(payload, preview?), dragging }   // lists
+useDraggable<T>({ type, payload, preview?, disabled? }): { dragProps, dragging }    // one thing
+useDropTarget<T>({ accepts, onDrop, disabled? }): { dropProps, over, ready }
+useDragging(): Drag | null
+interface Drag<T> { type: string; payload: T; from: string | null }
+type Accepts = string | string[] | ((type: string) => boolean)
+```
+
+Pointer Events, so touch and pen work; Escape calls a drag off; the drop brings the receiving window
+forward. `dropProps` carries `data-ready` and `data-over`, which the stylesheet already draws. A
+`DeskProvider` supplies the drag state, as it does the bus.
+
+### Events between windows
+
+```ts
+createBus(): Bus
+interface Bus {
+  publish<T>(topic: string, payload: T, options?: { from?: string | null }): DeskEvent<T>
+  subscribe<T>(topic: string, handler: (e: DeskEvent<T>) => void, options?: { replay?: boolean }): () => void
+  last<T>(topic: string): DeskEvent<T> | undefined
+}
+interface DeskEvent<T> { topic: string; payload: T; from: string | null; at: number }
+topicMatches(pattern, topic): boolean              // 'ride.*' and '*' are the only wildcards
+InputCommands = { submit: 'desk.input.submit', describe: 'desk.input.describe' }
+```
+
+## React: `@liberation-data/desk/react`
+
+### Shell
+
+```tsx
+<DeskShell desk?={Desk} options?={DeskOptions} bus?={Bus} toasts?={true}>
+<DeskProvider desk={desk}>                          // or options={…} to make one
+useDesk(): Desk
+useDeskState(): DeskState
+useWindowId(): string | null                        // inside a window's content
+
+<Desktop
+  renderWindow={(id) => ReactNode}                  // memoised: chrome re-renders, content does not
+  title={(id) => ReactNode}
+  actions?={(id) => ReactNode}                      // window-wide controls in the title bar
+  loading?={(id) => ReactNode}                      // inside a window while its code loads
+  failed?={(id, error, reload) => ReactNode}        // inside a window that could not open
+  empty?={ReactNode}
+  layout?={'auto' | 'desktop' | 'fullscreen'}       // auto: touch screens get one window at a time
+  className?={string}
+/>
+```
+
+### Loading and failing, per window
+
+```tsx
+const RoutePlanner = lazyWindow(() => import('./apps/RoutePlanner'))   // use in renderWindow
+```
+
+Every window has its own Suspense and error boundary: one window loading or throwing never blanks another,
+the menu bar or the dock. A failure is logged with `console.error` and shows Reload, which remounts the
+window; `lazyWindow` retries its import on reload, unlike `React.lazy`, which caches a failed import.
+
+### Dock
+
+```tsx
+<Dock entries={DockEntry[]} label?="Dock" placement?={'overlay' | 'inline'} />
+dockItem({ id, label, icon, window?, description?, badge?, onSelect?, disabled? })
+dockStack({ id, label, items: DockItem[], icon? })
+dockSeparator(id)
+```
+
+An item opens `window ?? id` and shows a dot while that window is open, accent when it is key. A stack fans
+out above the dock. One tab stop; arrow keys along it; Escape folds a stack away.
+
+### Menu bar
+
+```tsx
+<MenuBar menus={Menu[]} status?={Menu[]} leading?={ReactNode} trailing?={ReactNode} shortcuts?={true} />
+interface Menu { id: string; label: string; title?: ReactNode; emphasis?: boolean; items: MenuItem[] | (() => MenuItem[]) }
+// emphasis: the app's own menu, its name in bold, conventionally first
+menuCommand(label, command, { shortcut?, checked?, detail?, args? })
+menuAction(label, onSelect, { disabled?, shortcut?, checked?, detail? })
+menuSeparator(); menuHeader(label)
+windowMenuItems(state, focus, title): MenuItem[]
+```
+
+Command items are enabled via `canPerform` as the menu opens, and menus bind their own shortcuts. Opening a
+menu does not take focus from the key window, so a chosen command reaches the same responder a shortcut
+would. `items` as a function is re-read on every open.
+
+### Commands and input
+
+```tsx
+useCommand<Args>(command, handler, { enabled?: boolean | (() => boolean), at?: 'window' | 'app' | RefObject })
+usePerform(): (command, args?) => boolean
+useCanPerform(): (command) => boolean
+useShortcuts(keymap, { target?, apple? })
+
+useWindowInput(handler: (text: string) => void, { placeholder?, target?, disabled? })
+<InputBar onSubmit={(text) => void} fallbackPlaceholder? fallbackTarget? label?
+          mode?={'summoned' | 'inline'} shortcut?={'mod+j' | null} />   // summoned: centred, Escape closes
+InputCommands.open = 'desk.input.open'                                   // a menu item can summon it
+```
+
+`useCommand` defaults to the window it is rendered in, and to the app outside one.
+
+### Dragging between windows
+
+```tsx
+useDragSource<T>({ type, disabled? }): { dragProps(payload, preview?), dragging }   // lists
+useDraggable<T>({ type, payload, preview?, disabled? }): { dragProps, dragging }    // one thing
+useDropTarget<T>({ accepts, onDrop, disabled? }): { dropProps, over, ready }
+useDragging(): Drag | null
+interface Drag<T> { type: string; payload: T; from: string | null }
+type Accepts = string | string[] | ((type: string) => boolean)
+```
+
+Pointer Events, so touch and pen work; Escape calls a drag off; the drop brings the receiving window
+forward. `dropProps` carries `data-ready` and `data-over`, which the stylesheet already draws. A
+`DeskProvider` supplies the drag state, as it does the bus.
+
+### Events
+
+```tsx
+<BusProvider bus?={Bus}>                              // optional: a desk already carries a bus
+useBus(): Bus
+usePublish(): <T>(topic, payload) => DeskEvent<T>     // stamped with the window it came from
+useDeskEvent<T>(topic, handler, { replay? })          // replay: deliver the last event immediately
+```
+
+### Generated apps
+
+```tsx
+<AppFrame title src?|srcDoc? listens?={string[]} says?={string[]} accepts?={Accepts} opens?={string[]}
+          sandbox?="allow-scripts allow-forms" />
+withAppBridge(html): string          // puts the app-side script in the page's <head>
+APP_BRIDGE_SCRIPT                    // the same script, to include some other way
+```
+
+Inside the page: `desk.on(topic, message => …)`, `desk.onDrop(message => …)`, `desk.publish(topic, payload)`,
+`desk.open(window)`, and `desk.window` once connected. Messages carry `desk: 1`. The host ignores anything not
+from its own frame, drops publishes outside `says` and opens outside `opens`, never echoes an app its own
+events, and sets the frame's `pointer-events: none` while a drag is in the air so drops reach it.
+
+### Search
+
+```tsx
+<SearchPalette open onOpenChange search={(q) => SearchResult[] | Promise<SearchResult[]>}
+               placeholder? label? hint? empty?={(q) => ReactNode} shortcut?={'mod+k' | null} />
+interface SearchResult { id; title; subtitle?; group?; icon?; kind?; onSelect(): void }
+windowResults(desk, title, group?): SearchResult[]
+SearchCommand = 'desk.search'                          // a menu item can open it
+```
+
+### Controls
+
+```tsx
+<Button intent?={'normal'|'default'|'quiet'|'destructive'} size?={'regular'|'small'} icon? … />
+<SegmentedControl options={{value,label,icon?,disabled?}[]} value onChange label size? disabled? />
+<Toggle checked onChange label? description? disabled? aria-label? />        // applies at once
+<Checkbox checked indeterminate? onChange label? description? disabled? />   // waits for Save
+<Slider value onChange label min? max? step? disabled? format?={(v) => string} />
+<TextField label labelHidden? help? error? … />                             // error marks it invalid
+<RadioGroup options={{value,label,description?,disabled?}[]} value onChange label labelHidden? />
+<ChoiceGroup options={{value,label,description?,icon?,tag?,disabled?}[]} value onChange label labelHidden? />
+                                                  // cards for a setup step; native radios, arrow keys move the choice
+<PopUpButton value={T|null} onChange options={{value,label,description?,icon?,disabled?}[]}
+             label labelHidden? placeholder? disabled? size? />
+```
+
+### Lists
+
+```tsx
+<Table rows columns rowId={(row) => string} label rowProps?={(row) => object}
+       selected?={string | string[] | null} selection?={'single' | 'multiple'}
+       onSelect? onSelectionChange? onActivate? sort? onSortChange? empty? />
+interface Column<Row> { key; header; render?; align?; numeric?; sortable?; width? }
+interface Sort { key: string; direction: 'ascending' | 'descending' }
+
+<Sidebar sections={{ id, label?, items: { id, label, icon?, badge?, disabled? }[] }[]}
+         value onChange label footer? />
+```
+
+Table: one tab stop, arrow keys move the selection, Enter or double click activates, `aria-sort` on
+sortable headings. It renders what it is given — no paging, no fetching.
+
+### Overlays
+
+```tsx
+<Popover open onOpenChange label trigger={(props) => <Button {...props} />} placement? align? />
+<Sheet open onDismiss title description? actions? />        // renders inside its own window
+<Alert open title message? confirmLabel onConfirm onCancel cancelLabel? destructive? />
+<ToastProvider>; useToast(): { show(toast): string; dismiss(id): void }
+toast.show({ message, tone?: 'neutral'|'ok'|'bad', action?: { label, onSelect }, duration?: 6000 })
+```
+
+All share one layer stack: Escape dismisses the topmost. Popover, Sheet and Alert trap focus and return it.
+A toast pauses while the pointer or focus is on it.
+
+### Conversation
+
+```tsx
+<Thread messages={Message[]} me?="me" typing? onRetry? empty? label? />
+interface Message { id; from; authorName?; body: ReactNode; at?: Date | string; state?: 'sending'|'sent'|'failed' }
+<Composer value onChange onSubmit placeholder? label? disabled? busy? onStop? accessory? maxRows? />
+```
+
+No transport of its own. The thread follows new messages only while the reader is at the end. The composer
+sends on Enter, keeps Shift+Enter for a new line, and never sends mid-composition in an input method.
+
+### Teaching and first run
+
+```tsx
+<TourBar tour={{ id, name, description?, steps }} onFinish? onStop? offer? />
+interface TourStep { window?: string; point?: string; caption: ReactNode; yourTurn?: boolean;
+                   until?: string | { topic: string; when: (event: DeskEvent) => boolean } }
+
+const tasks = useTasks(Task[]): { items: TaskProgress[]; running; done; failed; start(); restart() }
+interface Task { id; name: ReactNode; detail?: ReactNode; run: (report: (detail: ReactNode) => void) => unknown }
+<Checklist items={TaskProgress[]} onRetry? progress?={true} label? />   // a failed row shows its error and Try again
+
+const setup = useSetupProgress({ key, initial: Answers, store?: SetupStore })
+  // { loaded, index, setIndex, answers, answer(patch), finished, finish(), reset() }
+interface SetupStore<A> { load(): SetupRecord<A> | undefined | Promise<…>; save(record): void | Promise<void>; clear() }
+localSetupStore(key)   // the default: localStorage under `desk.setup.<key>`; never put secrets in answers
+
+<Wizard steps={WizardStep[]} index onIndexChange onFinish label? />
+interface WizardStep { id; name; title; description?; body?; glyph?; complete?; continueLabel?;
+                       skip?: { label, onSkip }; working?; onEnter?;
+                       onContinue?: () => unknown | Promise<unknown>; busyLabel? }
+```
+
+A tour step opens its window and points at `point` (a `data-tour` name or a selector). A step with `until` moves on
+when that event is published (no Done button). `offer` shows the tour's name and description with Show me / Not now
+(Not now calls onStop) and opens nothing until accepted — use it right after setup. A wizard step offers
+Continue only when `complete`, and `working` steps offer no Back. `onContinue` runs before moving on: Continue
+shows `busyLabel` (default "Working…") and is disabled; a thrown Error's message is shown in the step and the
+step stays; returning `false` stays silently. Pressing again while it runs does nothing. Tasks run in order and
+stop at the first that throws; `start()` runs whatever is not done (the retry), `restart()` runs them all again.
+For a waiting step: `working: !tasks.failed, complete: tasks.done, onEnter: tasks.restart`.
+
+## Styling
+
+Every value reads a `--desk-*` token; redefine tokens, never override selectors. Colour roles: `--desk-ground`,
+`--desk-surface`, `--desk-titlebar`, `--desk-ink`, `--desk-muted`, `--desk-rule`, `--desk-accent`,
+`--desk-ok|warn|bad`, `--desk-on-accent`. Spacing `--desk-space-1..7` = 4, 8, 12, 16, 24, 32, 48 px. Also
+`--desk-radius`, `--desk-control-height`, `--desk-control-radius`, `--desk-font`, `--desk-font-mono`,
+`--desk-ease`, `--desk-dock-size`, `--desk-dock-glass`, `--desk-inset-bottom`.
+
+Light and dark follow `prefers-color-scheme`; `data-theme="light" | "dark"` on the root wins.
+
+## Testing
+
+```ts
+const desk = createDesk({ stage: () => ({ width: 1000, height: 700 }) })   // jsdom measures nothing
+render(<DeskProvider desk={desk}>…</DeskProvider>)
+```
+
+Query a window by `[data-desk-window="id"]`: on a touch layout an offstage window is `inert`, so it is not
+in the accessibility tree.
+
+## Facts an agent should not guess
+
+- React 19 is a peer dependency; the core entry point imports no React and touches no DOM except through
+  the command helpers.
+- Focus follows the key window when it changes, but never on first render.
+- First run (HIG §8): check on Continue with `onContinue`, not on the next step; show waiting work with
+  `useTasks` + `Checklist`; open the chosen window last so it is in front; offer the tour (`offer`) once on
+  arrival; remember progress with `useSetupProgress`, and never put passwords or keys in its answers.
+- A `DeskProvider` already carries an event bus; `BusProvider` is only for supplying or sharing one.
+- `renderWindow` must be stable (module scope or `useCallback`) for the memoisation to hold.
+- `parse`/`syncWithLocation` warn once when no `isKnown` is given: unknown ids from a URL are then trusted.
+- `npm run size` enforces a gzipped budget: core 10 KiB, react 46 KiB, css 10 KiB.
+- The package is ESM only, with `"sideEffects": ["**/*.css"]`.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@liberation-data/desk",
+  "version": "0.1.0",
+  "description": "A desktop for the web, for React: windows, a dock, menus and commands, controls, tours and setup assistants.",
+  "license": "Apache-2.0",
+  "author": "Jasper Blues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liberation-data/desk.git"
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "src",
+    "llms.txt",
+    "NOTICE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./desk.css": "./dist/desk.css"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/desk.css dist/desk.css",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "example": "vite examples/garage",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "size": "node scripts/size.mjs",
+    "check": "npm run typecheck && npm test && npm run build && npm run size",
+    "check:browser": "node scripts/browser-check.mjs"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.7",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "jsdom": "^30.0.1",
+    "puppeteer-core": "^25.11.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.0"
+  }
+}

package/src/core/commands.ts

@@ -0,0 +1,142 @@
+import { focusedId } from './desk.js'
+import type { Desk } from './desk.js'
+
+/*
+ * The responder chain, built from the DOM rather than beside it.
+ *
+ * A command that names no target — Copy, Close, text typed into the desk's input
+ * bar — is dispatched as an event from the start of the chain and bubbles up
+ * through ancestors: focused element → its window → the stage → the document.
+ * The first element with a handler for that command decides. Menus ask the same
+ * chain whether a command can be performed before they draw an item enabled.
+ *
+ * Deciding is AppKit's rule: the first responder that implements a command is
+ * its target, and its answer stands. A disabled handler stops the command rather
+ * than letting it fall through to something further up the chain.
+ */
+
+export type CommandId = string
+
+/** Marks a window's element, so the chain can start at the key window. */
+export const WINDOW_ATTRIBUTE = 'data-desk-window'
+/** Marks the stage, the desk-level responder. */
+export const STAGE_ATTRIBUTE = 'data-desk-stage'
+
+const PERFORM = 'desk:perform'
+const QUERY = 'desk:can-perform'
+
+interface PerformDetail {
+  readonly command: CommandId
+  readonly args: unknown
+  handled: boolean
+}
+
+interface QueryDetail {
+  readonly command: CommandId
+  enabled: boolean | undefined
+}
+
+export type CommandHandler<Args = unknown> = (args: Args) => void
+
+export interface CommandOptions {
+  /** Whether the handler can act right now. Asked before performing and when a menu opens. Default: always. */
+  readonly enabled?: () => boolean
+}
+
+/**
+ * Makes `element` a responder for `command`. Returns a function that removes it.
+ * Attach to `document` for an app-level responder.
+ */
+export function addCommandHandler<Args = unknown>(
+  element: EventTarget,
+  command: CommandId,
+  handler: CommandHandler<Args>,
+  options: CommandOptions = {},
+): () => void {
+  const enabled = options.enabled ?? (() => true)
+
+  const onPerform = (event: Event) => {
+    const detail = (event as CustomEvent<PerformDetail>).detail
+    if (detail.command !== command) return
+    event.stopPropagation()
+    if (!enabled()) return
+    detail.handled = true
+    handler(detail.args as Args)
+  }
+
+  const onQuery = (event: Event) => {
+    const detail = (event as CustomEvent<QueryDetail>).detail
+    if (detail.command !== command) return
+    event.stopPropagation()
+    detail.enabled = enabled()
+  }
+
+  element.addEventListener(PERFORM, onPerform)
+  element.addEventListener(QUERY, onQuery)
+  return () => {
+    element.removeEventListener(PERFORM, onPerform)
+    element.removeEventListener(QUERY, onQuery)
+  }
+}
+
+export interface ChainOptions {
+  /** Start here instead of at the focused element. */
+  readonly from?: Element | null
+  readonly document?: Document
+}
+
+/** Where a command starts: focus inside the key window, else the key window, else the stage, else the document. */
+export function chainStart(desk: Desk | null, options: ChainOptions = {}): EventTarget {
+  if (options.from) return options.from
+  const doc = options.document ?? globalThis.document
+  const key = desk ? focusedId(desk.getState()) : null
+  const window = key ? windowElement(doc, key) : null
+  const active = doc.activeElement
+  if (window && active && window.contains(active)) return active
+  return window ?? doc.querySelector(`[${STAGE_ATTRIBUTE}]`) ?? doc
+}
+
+export const windowElement = (doc: ParentNode, id: string): Element | null =>
+  [...doc.querySelectorAll(`[${WINDOW_ATTRIBUTE}]`)].find(el => el.getAttribute(WINDOW_ATTRIBUTE) === id) ?? null
+
+/** Sends a command along the chain. Returns whether anything handled it. */
+export function perform<Args = unknown>(desk: Desk | null, command: CommandId, args?: Args, options: ChainOptions = {}): boolean {
+  const detail: PerformDetail = { command, args, handled: false }
+  chainStart(desk, options).dispatchEvent(new CustomEvent(PERFORM, { detail, bubbles: true, composed: true }))
+  return detail.handled
+}
+
+/** Asks the chain whether a command would be handled right now. */
+export function canPerform(desk: Desk | null, command: CommandId, options: ChainOptions = {}): boolean {
+  const detail: QueryDetail = { command, enabled: undefined }
+  chainStart(desk, options).dispatchEvent(new CustomEvent(QUERY, { detail, bubbles: true, composed: true }))
+  return detail.enabled ?? false
+}
+
+/** The commands the desk itself answers, at the stage. */
+export const DeskCommands = {
+  closeWindow: 'desk.window.close',
+  /** Fills the key window, or frees it: the green control. */
+  zoomWindow: 'desk.window.zoom',
+  /** Answered by a mounted Desktop, which knows the space windows are laid out in. */
+  arrange: 'desk.window.arrange',
+  nextWindow: 'desk.window.next',
+  previousWindow: 'desk.window.previous',
+} as const
+
+export function addDeskCommands(stage: EventTarget, desk: Desk): () => void {
+  const key = () => focusedId(desk.getState())
+  const cycle = (step: 1 | -1) => {
+    const { windows } = desk.getState()
+    const current = windows.findIndex(w => w.id === key())
+    const next = windows[(current + step + windows.length) % windows.length]
+    if (next) desk.focus(next.id)
+  }
+  const removers = [
+    addCommandHandler(stage, DeskCommands.closeWindow, () => { const id = key(); if (id) desk.close(id) }, { enabled: () => key() !== null }),
+    addCommandHandler(stage, DeskCommands.zoomWindow, () => { const id = key(); if (id) desk.toggleMode(id) }, { enabled: () => key() !== null }),
+    addCommandHandler(stage, DeskCommands.nextWindow, () => cycle(1), { enabled: () => desk.getState().windows.length > 1 }),
+    addCommandHandler(stage, DeskCommands.previousWindow, () => cycle(-1), { enabled: () => desk.getState().windows.length > 1 }),
+  ]
+  return () => removers.forEach(remove => remove())
+}