command-code 1.82.5 → 1.84.0

package/dist/bundled/mod-builder/reference/ui.md

@@ -2,19 +2,45 @@
 
 # UI surface
 
-Everything a mod can put on screen rides `cmd.ui`, `cmd.addRenderer`, and `cmd.showEntry`. All of it is line-based and host-agnostic: the TUI wires real rendering, headless runs degrade to deterministic defaults, and a crashing renderer becomes a warning - never a broken screen.
+Everything a mod can put on screen rides `cmd.ui`, `cmd.addRenderer`, and `cmd.showEntry`. All of it is data, never components: a mod returns strings or a small element tree, the TUI and the desktop app draw it, headless runs degrade to deterministic defaults, and a crashing render becomes a one-line warning - never a broken screen.
 
 ## Notifications and dialogs
 
 - `cmd.ui.notify(message, level?)` - a `notice` feed row, styled by `level`: `'info'` (default) is a dim bullet, `'warning'` an amber ⚠, `'error'` a red ⚠. Rendered during a turn (the per-turn feed projector); a notice raised at factory time flushes once the session binds.
+- `cmd.ui.toast(text, {level?, durationMs?})` - a short-lived line above the prompt that clears itself (default 4s). `level` is `info`, `success`, `warning`, or `error`. Where nothing draws toasts (headless), it falls back to a notice row so the message is never lost.
 - `cmd.ui.confirm({title, message?})` / `cmd.ui.select({title, options})` / `cmd.ui.input({title, placeholder?})` - the Interaction question modal in the TUI. Headless, each resolves its deterministic default: confirm → `false`, select/input → `undefined` - never auto-approved.
 - `cmd.ui.setTitle(text | null)` - the terminal tab title. The text replaces the session title on the tab (and survives the host's own title re-assertions) until `null` hands the tab back. Headless: no-op.
 
-## Footer status segments and editor widgets
+## Clipboard and sound
 
-> **Widgets are not wired into the TUI yet.** `cmd.ui.widget` and `cmd.ui.refreshWidgets` exist on the surface and are safe to call - they never throw and return the documented `Disposable` - but they currently render **nowhere**. The contract below is the intended design; wire-up is pending. `cmd.ui.setStatus` **is** wired and renders today.
+- `cmd.ui.copy(text)` - write `text` to the system clipboard through the same helper `/copy` uses. It never throws: `{isCopied: true}`, or `{isCopied: false, reason}` where `reason` is `headless` (no interactive host), `no-clipboard` (the machine's clipboard is unreachable, for example over SSH without X11), or `error`.
+- `cmd.audio.play({file, timeoutMs?})` - play a sound file with the platform player: `afplay` on macOS, `paplay` then `aplay` on Linux, PowerShell `Media.SoundPlayer` on Windows. A relative `file` resolves against the directory of the mod's own file, so ship the sound next to it; an absolute path works too. It runs through the runtime shell and is killed after `timeoutMs` (default 10s). It never throws: `{isPlayed: true}`, or `{isPlayed: false, reason}` where `reason` is `headless`, `not-found`, `no-player`, `timeout`, or `error`.
+- `cmd.audio.bell()` - ring the terminal bell. Returns `{isPlayed: true}`, or `{isPlayed: false, reason: 'headless'}`.
+- Where they work today. In the desktop app, copy, bell, and play all answer `headless` for now. Over SSH without a display, copy answers `no-clipboard`. On Windows, and on Linux with only ALSA (`aplay`, no PulseAudio or PipeWire), play handles WAV files only. Ship a `.wav` if the mod should sound everywhere.
+- Bad arguments never throw either. A `file` that is not a string answers `error`. A `timeoutMs` that is not a positive whole number falls back to the 10s default. A hot reload stops any sound the old code started.
 
-`cmd.ui.setStatus(text | null)` - a persistent per-mod segment in the TUI footer (under the input panel). One segment per mod: a new call replaces the text, `null` (or whitespace-only text) clears it, and the returned `Disposable` clears it too - but only while it still owns the segment, so a stale handle disposing late can't wipe a newer status. Segments from multiple mods render on one row in load order, and a call from async code repaints on its own. Text is printed verbatim (style it with ansi), collapsed to a single line: newlines and tabs become spaces. Headless: stored, rendered nowhere.
+Sound is a side effect, so do not `await` it in a hook unless the turn should wait for it:
+
+```ts
+cmd.hooks({
+	onStop: () => {
+		void cmd.audio.play({file: './done.wav'});
+		return undefined;
+	},
+});
+cmd.addCommand({
+	name: 'copy-branch',
+	handler: async ({exec, ui}) => {
+		const {stdout} = await exec({command: 'git', args: ['branch', '--show-current']});
+		const copied = await ui.copy(stdout.trim());
+		return {message: copied.isCopied ? 'Copied.' : `Not copied: ${copied.reason}`};
+	},
+});
+```
+
+## Footer status segments
+
+`cmd.ui.setStatus(text | null)` - a persistent per-mod segment on the TUI's status row (under the input). One segment per mod: a new call replaces the text, `null` (or whitespace-only text) clears it, and the returned `Disposable` clears it too - but only while it still owns the segment, so a stale handle disposing late can't wipe a newer status. Segments from multiple mods render after the row's built-in items in load order, and a call from async code repaints on its own. Style text with ansi colors (SGR) and OSC 8 links; every other escape - cursor moves, screen clears, OSC titles and clipboard writes - is stripped, and newlines and tabs become spaces. Mod segments share the user's one status line, after the built-ins and before the right-pinned phase model; the line is cut with `…` at the terminal edge, so trailing segments can be cut off. `/statusline off` hides the whole row (`cmd.ui.capabilities.status` stays true). Headless: stored, rendered nowhere. For a complete example built by asking Command Code, see [Add your own items with mods](https://commandcode.ai/docs/reference/slash-commands#add-your-own-items-with-mods).
 
 ```ts
 cmd.hooks({
@@ -23,20 +49,46 @@ cmd.hooks({
 });
 ```
 
-`cmd.ui.capabilities.status` - whether this host renders footer segments (true in the interactive TUI, false headless). Use it to pick a surface instead of shipping a permanent fallback:
+`cmd.ui.capabilities.status` / `cmd.ui.capabilities.surface` - whether this host renders footer segments, and widgets / panes / toasts (true in the interactive TUI and the desktop app, false headless). Use them to pick a surface instead of shipping a permanent fallback:
 
 ```ts
 if (cmd.ui.capabilities.status) cmd.ui.setStatus(text);
 else cmd.ui.notify(text);
 ```
 
-`cmd.ui.widget({placement: 'above-editor' | 'below-editor', render: () => lines})` - a line-based widget the TUI renders around the input panel. Same verbatim-lines contract as `addRenderer` (style with ansi); `render` re-runs on every repaint, and `cmd.ui.refreshWidgets()` requests a repaint after your data changes. A throwing render is skipped (reported as a `mod_error`) so siblings keep rendering. Headless: no-op.
+## Elements
+
+A widget's or pane's `render({width})` returns a list of nodes. A node is a plain string (one line) or one of:
+
+| Element | Shape | Draws |
+|---|---|---|
+| text | `{type: 'text', text, color?, bold?, dim?}` | styled text; `color` is `red` `green` `yellow` `blue` `magenta` `cyan` `white` `gray` |
+| row | `{type: 'row', children}` | children on one line, space-separated |
+| box | `{type: 'box', title?, children}` | an optional bold title, then each child on its own line |
+| button | `{type: 'button', label, hotkey?, key?, onPress}` | `[ r: Reset ]`; `hotkey` is one letter or digit, `key` is its identity (defaults to the label) |
+| progress | `{type: 'progress', value, width?, label?}` | `label ██████░░░░ 60%`, `value` 0..1 |
+| divider | `{type: 'divider'}` | a rule across `width` |
+| input | `{type: 'input', key, placeholder?, value?, onSubmit(text)}` | a one-line text field `[ value ]`; editable only while its pane has focus, Enter submits |
+| select | `{type: 'select', key, options: [{label, value}], value?, onSelect(value)}` | `○ Small  ◉ Medium  ○ Large` with `value` marked; while focused, ←/→ move the highlight and Enter picks |
+| markdown | `{type: 'markdown', text}` | markdown drawn the way the feed draws replies (headings, lists, code, tables); a host without a markdown renderer falls back to plain lines |
+
+`width` is the columns the surface draws into, so a mod can size its own layout. Mods still own their styling: a plain string is printed as written, ansi colors and styles included. Other escape sequences (cursor moves, screen clears) and control bytes other than newline and tab are dropped from all mod text, so a mod can never take over the terminal.
+
+`input` and `select` need a `key` (their identity for focus and handlers); a button's `key` defaults to its label. Their handlers run in the mod like a hook: a throw becomes `mod_error {hook: 'ui.submit'}` or `{hook: 'ui.select'}`, and the surface repaints after every submit or pick. Keep what they set in `cmd.state` and read it back as `value`, so the field shows it after a repaint or a hot reload. Images and raster graphics are not elements: terminal graphics protocols (kitty, iTerm2, sixel) differ per terminal and do not survive the TUI's line-based redraw.
+
+## Widgets: the band above the prompt
+
+`cmd.ui.widget({placement: 'above-editor' | 'below-editor', render})` - lines drawn around the input panel; `above-editor` is the band right above the prompt, `below-editor` sits under it with the status row. `render` re-runs on every repaint; call `cmd.ui.refreshWidgets()` after the data it reads changed (or keep that data in `cmd.state`, whose `set` repaints for you). A throwing render shows a one-line warning and reports a `mod_error` so siblings keep drawing. The returned `Disposable` removes the widget. Headless: stored, drawn nowhere.
 
 ```ts
 let failing = 0;
 cmd.ui.widget({
 	placement: 'above-editor',
-	render: () => [failing > 0 ? `✗ ${failing} tests failing` : '✓ tests green'],
+	render: () => [
+		failing > 0
+			? {type: 'text', text: `✗ ${failing} tests failing`, color: 'red'}
+			: {type: 'text', text: '✓ tests green', color: 'green'},
+	],
 });
 cmd.on('tool_completed', () => {
 	failing = readFailingCount();
@@ -44,24 +96,144 @@ cmd.on('tool_completed', () => {
 });
 ```
 
+## Panes
+
+`cmd.ui.pane({id, title, render})` - a titled, bordered panel above the prompt that the person opens and closes. Registering does not open it: `cmd.ui.openPane(id)` does (usually from a command), `cmd.ui.closePane(id)` closes it, and so do `/mods open <pane>` / `/mods close <pane>`. While a pane is open, **Alt+&lt;hotkey&gt;** presses its buttons (the pane's last line lists them) and **Alt+0** closes the newest one; typing still goes to the prompt. Hotkeys the prompt already owns (`p`, `v`, `w`, `u`, `m`) are drawn but never pressed by the chord. A pane's id is `<mod>/<id>`, so two mods can both have a `stats` pane; whether it is open survives a hot reload.
+
+**Docked on wide terminals.** From 140 columns up, open panes draw in a column to the right of the prompt (about 40% of the width, 40 to 72 columns) instead of stacking above it, and the prompt narrows to fit beside them. The feed above is scrollback, so panes dock beside the prompt, not beside the feed. Below 140 columns they stack above the prompt.
+
+### Focus
+
+The prompt keeps the keyboard until a pane takes it, so typing never reaches a pane by accident. **Alt+↑** moves focus into the newest open pane (its border lights up and the prompt steps aside, keeping what you typed), and `cmd.ui.openPane(id, {focus: true})` opens a pane with focus, like a dialog. While a pane has focus:
+
+| Key | Does |
+|---|---|
+| Tab / ↓ | next button, input, or select (wraps) |
+| Shift+Tab / ↑ | previous one |
+| Enter | press the button, submit the input, or pick the select's highlighted option |
+| ←/→ | move a select's highlight |
+| typing, Backspace | edit the focused input (it starts from its `value`) |
+| Esc | give the keyboard back to the prompt. The pane stays open, and what you typed in it is still there when it takes focus again. |
+| Alt+0 | close the newest pane (focus returns to the prompt) |
+
+Ctrl+C still reaches the prompt's interrupt and exit keys while a pane has focus. Closing the focused pane, or a dialog taking the screen, hands the keyboard back too.
+
+```ts
+cmd.ui.pane({
+	id: 'standup',
+	title: 'Standup',
+	render: () => [
+		{type: 'markdown', text: '**Today**: one line, then pick how it is going.'},
+		{
+			type: 'input',
+			key: 'note',
+			placeholder: 'what are you working on?',
+			value: cmd.state.get<string>('note') ?? '',
+			onSubmit: text => cmd.state.set('note', text),
+		},
+		{
+			type: 'select',
+			key: 'mood',
+			options: [
+				{label: 'Great', value: 'great'},
+				{label: 'Blocked', value: 'blocked'},
+			],
+			value: cmd.state.get<string>('mood'),
+			onSelect: value => cmd.state.set('mood', value),
+		},
+	],
+});
+cmd.addCommand({
+	name: 'standup',
+	handler: () => cmd.ui.openPane('standup', {focus: true}),
+});
+```
+
+```ts
+cmd.ui.pane({
+	id: 'calls',
+	title: 'Tool calls',
+	render: () => [
+		{type: 'progress', label: 'budget', value: calls() / 50},
+		{
+			type: 'button',
+			label: 'Reset',
+			hotkey: 'r',
+			onPress: () => cmd.state.set('calls', 0),
+		},
+	],
+});
+cmd.addCommand({name: 'calls', handler: () => cmd.ui.openPane('calls')});
+```
+
+A button's `onPress` runs in the mod like a hook: a throw becomes `mod_error {hook: 'ui.press'}`, and the surface repaints after every press.
+
 ## Custom feed rendering
 
 - `cmd.addRenderer(customType, data => lines)` - a renderer for a custom entry type; returns the lines to print (style them with ansi escapes - picocolors, `@commandcode/tui` helpers, or raw codes). First registration per type wins across mods.
 - `cmd.showEntry(customType, data)` - render a custom entry into the live feed through the renderer registered for that type (unrendered types pretty-print as JSON). The TUI wires the sink; headless runs drop entries. Pair with `cmd.session.appendCustomEntry` when the data should also persist.
 
-Rendering is deliberately **line-based, not component-based**: mods return styled text lines, never React components. That keeps renderers host-agnostic (the same mod renders in any future host) and a crashing renderer degrades to a warning notice, never a broken screen.
+## Restyle built-in rows
 
-## Headless behavior at a glance
+`cmd.ui.override(component, render)` - redraw a row Command Code draws itself, with the same [elements](#elements) widgets use. `render(props, next)` gets the row's data and returns nodes, or `undefined` to keep the built-in row. The returned `Disposable` removes the override, and a hot reload drops it with every other registration.
 
-| Surface | Interactive TUI | Headless (`-p`) |
+| Component | `props` | What the nodes do |
 |---|---|---|
-| `notify` | notice feed row | printed notice |
-| `confirm` | modal | resolves `false` |
-| `select` / `input` | modal | resolves `undefined` |
-| `setStatus` | footer segment under the input | stored, rendered nowhere |
-| `widget` | no-op (wire-up pending) | no-op |
-| `setTitle` | terminal tab title | no-op |
-| `showEntry` | rendered feed row | dropped |
-| `addShortcut` | dispatched after host bindings | never fires |
-| `sendUserMessage` | real user turn (queued while busy) | falls back to `queueMessage` |
-| `shutdown` | exits after the turn settles | no-op |
+| `spinner` | `{status, elapsedMs, tokens}` | appended after the working status line, on the same line |
+| `tool_row` | `{toolName, displayName, input, status, result?}` | drawn instead of the tool's row; `status` is `pending`, `success`, or `error`, `result` is set once it finished |
+| `user_message` | `{text}` | drawn instead of the person's message |
+| `command_output` | `{message, details?, isError}` | drawn instead of a slash command's result row |
+
+```ts
+// "tool calls: 3" beside the spinner.
+cmd.ui.override('spinner', (_props, next) => [
+	{type: 'text', text: `tool calls: ${calls()}`, color: 'cyan'},
+	...(next() ?? []),
+]);
+
+// Shell rows as one line; every other tool keeps its built-in row.
+cmd.ui.override('tool_row', ({toolName, input}) =>
+	toolName === 'shell_command' ? [`$ ${input}`] : undefined,
+);
+```
+
+How overrides compose and fail:
+
+- **Load order, first answer wins.** Several mods can override the same component. The first mod to return nodes wins; `undefined` passes to the next mod, and past the last one to the built-in row.
+- **`next()` is the rest of the chain.** It returns what the mods loaded after this one drew, or `undefined` when the built-in row would draw. Wrap it to add to another mod's drawing instead of replacing it (`[...mine, ...(next() ?? [])]`). It runs the later mods once, however often you call it.
+- **A broken override falls back.** An override that throws, returns something other than an array or `undefined` (a string, or the Promise of an `async` render), or draws a malformed tree is skipped as if it returned `undefined`. It reports one `mod_error {hook: 'ui.override:<component>'}` until the mod registers it again, so a broken spinner override does not report on every frame.
+- **Rows redraw with the row.** The spinner redraws about 12 times a second; a tool row redraws while it is live and is final once it scrolls into the transcript. An override applies to rows drawn after it registered.
+- **Tool and command rows are a trust surface.** A `tool_row` or `command_output` override changes what the transcript shows for a tool call or a command. Install only mods you trust to show those rows honestly.
+- **Never the permission prompt.** Only the four components above are overridable; any other name throws at registration.
+
+## In the desktop app
+
+The desktop app draws the same surface around the chat composer. Mod code still runs only in the app's main process: it renders each widget and pane there at a fixed 80 columns and sends the window plain lines and button ids, never code.
+
+- **Widgets**: `above-editor` sits right above the composer, `below-editor` right under it, with the status row below that.
+- **Panes**: an open pane is a card above the composer, titled, with a close button. Buttons are clickable where the mod drew them (`[ r: Reset ]`); Alt+hotkey chords are a TUI thing.
+- **Toasts**: the app's own toasts, titled with the mod's name.
+- **Styling**: ansi bold, dim, and the eight element colors map to the app theme; other escape codes (cursor moves, links, 256-color) are dropped.
+
+## Headless behavior at a glance
+
+| Surface | Interactive TUI | Desktop app | Headless (`-p`) |
+|---|---|---|---|
+| `notify` | notice feed row | notice feed row | printed notice |
+| `toast` | line above the prompt, clears itself | app toast, clears itself | notice row |
+| `confirm` | modal | question in the composer | resolves `false` |
+| `select` / `input` | modal | question in the composer | resolves `undefined` |
+| `setStatus` | footer segment under the input | status row under the composer | stored, rendered nowhere |
+| `widget` | band above / below the prompt | band above / below the composer | stored, drawn nowhere |
+| `pane` | bordered panel above the prompt (docked right from 140 columns), Alt+key buttons, Alt+↑ focus | card above the composer, clickable buttons | stored, drawn nowhere |
+| `override` | redraws the spinner / tool / message / command rows | not drawn | stored, drawn nowhere |
+| `setTitle` | terminal tab title | no-op | no-op |
+| `showEntry` | rendered feed row | dropped | dropped |
+| `addShortcut` | dispatched after host bindings | never fires | never fires |
+| `sendUserMessage` | real user turn (queued while busy) | falls back to `queueMessage` | falls back to `queueMessage` |
+| `prompt.submit` | starts a turn when idle, queues when busy | follow-up queue | follow-up queue |
+| `shutdown` | exits after the turn settles | no-op | no-op |
+| `ui.copy` | system clipboard | `{isCopied: false, reason: 'headless'}` | `{isCopied: false, reason: 'headless'}` |
+| `audio.play` / `audio.bell` | platform player / terminal bell | no sound, `reason: 'headless'` | no sound, `reason: 'headless'` |
+
+**TUI only for now.** `cmd.ui.override`, `cmd.ui.setTitle`, `cmd.ui.copy`, `cmd.audio`, `cmd.addShortcut`, `cmd.shutdown`, pane focus, and typing into `input` or picking in `select` elements are handled by the interactive TUI only. The desktop app draws an `input` or `select` element as plain text it cannot focus, and a `markdown` element as styled lines.

package/dist/bundled/mod-builder/reference/verify.md

@@ -27,7 +27,11 @@ Your mod must appear, with no load warnings. If it does not appear, the warning
 - **Hook** - trigger the behavior it guards (for a `beforeToolCall` blocker, ask for the blocked action and watch the block reason land as the tool result).
 - **Input interception** - type the pattern `transformInput` matches and confirm the rewrite/consume happened.
 - **Status** - `cmd.ui.setStatus('text')` must show up as a segment on the row under the input, replace itself on the next call, and disappear on `setStatus(null)`.
-- **Widget** - `cmd.ui.widget` / `cmd.ui.refreshWidgets` must return without throwing and hand back a `Disposable`. They render **nothing** today (TUI wire-up pending - see the [UI surface](./ui.md#ui-surface) note), so don't expect an editor widget to appear yet; only verify the calls are safe.
+- **Widget** - an `above-editor` widget draws right above the prompt, a `below-editor` one under it; `cmd.ui.refreshWidgets()` (or a `cmd.state.set`) repaints it.
+- **Pane** - open it (`/mods open <pane>`, or the mod's own command): it draws above the prompt with its buttons' Alt+keys on its last line; `Alt+<key>` presses one, `Alt+0` closes it. For inputs and selects, `Alt+↑` focuses it: Tab through the fields, type, press Enter, and check the pane redraws with the new `value`.
+- **Toast** - `cmd.ui.toast('text')` shows above the prompt and clears itself.
+- **Override** - send a prompt that runs a tool: a `spinner` override shows beside the working line, a `tool_row` override replaces that tool's row. If a row still looks built-in, the override returned `undefined` or threw (look for `mod_error` with `ui.override:` in its hook).
+- **Permission answers** - with an `onPermissionRequest` hook, trigger a call that would prompt: an answered prompt never appears. `cmd mods inspect` lists the hook so reviewers see it too.
 - **Renderer** - `cmd.showEntry` rows render styled; an unregistered type pretty-prints as JSON.
 
 ### Test: block-dangerous-commands guards rm -rf
@@ -42,9 +46,9 @@ Expected result:
 -  Declining blocks the tool - the model sees the block reason and adapts
 -  No `tool_running` fires for the blocked call
 
-## 4. Iterate with /reload
+## 4. Iterate: save, and it reloads
 
-Mods load once per process. After editing the file, run `/reload` - it restarts Command Code, resumes the session, and re-discovers and re-imports every mod (jiti caches nothing between loads).
+In the interactive TUI, saving a mod's file reloads it in place, with no restart: the feed says `[mods] ✓ reloaded <name>` (or why it did not). The old code gets `onSessionEnd` with `reason: 'reload'`, then every registration it made is disposed, except tools added with `addTool`. Those keep the old code until the next session. `cmd.state` survives, and `onSessionStart` fires again with `source: 'reload'`. A save that throws while loading leaves the old code running. `/mods reload [name]` reloads on demand. Two things need more than a reload: tools (the tool set is fixed per session, so start a new session or `/reload`) and new mod files (`/reload` re-discovers). `COMMANDCODE_MODS_HOT_RELOAD=0` turns the watcher off.
 
 ## 5. Headless check (CI)