@cmodjs/core 0.3.0 → 1.5.0

package/docs/testing.md

@@ -34,6 +34,7 @@ type TestOptions<State, Options> = {
   readonly dependencies?: { [Name in keyof CmodDependencies]?: CmodDependencies[Name] }
   readonly files?: Readonly<Record<string, string>>
   readonly links?: Readonly<Record<string, string>>
+  readonly sessions?: readonly FakeSession[]
 }
 ```
 
@@ -43,15 +44,16 @@ type TestOptions<State, Options> = {
 | `options` | The option values Claude Code passes, as a person set them ([options.md](options.md)) | none: each option gets its default |
 | `permissions` | Exactly the permissions the person granted, such as `['network:api.github.com', 'model']` ([permissions.md](permissions.md)) | every permission the mod's `package.json` declares |
 | `scope` | `'project'` makes the mod a project plugin, in `<projectRoot>/.claude/skills/<name>` | `'user'` |
-| `projectRoot` | `mod.projectRoot` | `/test/plugins/<name>`, or `/test/project` for a project plugin |
-| `cwd` | `mod.cwd` | `projectRoot` |
-| `dependencies` | The methods other mods answer with | none: every call fails with `<name> is not installed. Run cmod install <name>.` |
+| `projectRoot` | `sessions.current.project` | `/test/plugins/<name>`, or `/test/project` for a project plugin |
+| `cwd` | `sessions.current.cwd` | `projectRoot` |
+| `dependencies` | The methods other mods answer with | none: every call fails with `<name> is not installed. Add it with /plugin.` |
 | `files` | The fake file system, absolute path to text | no files |
 | `links` | Symbolic links in the fake file system, absolute link path to its target | no links |
+| `sessions` | The earlier conversations `sessions.list` and `sessions.search` read, each `{ id, messages?, goal?, … }` ([Build a conversation](#build-a-conversation)) | none: only the current session, `test-session` |
 
 A project plugin finds its repository through a `.git` entry at `projectRoot`, so a test of one puts it in `files`, such as `files: { '/test/project/.git': '' }`. Without it the project plugin has no repository, and its rules match calls in every folder, as a user mod's do.
 
-The fake session's id is `test-session`, its model is `test-model`, and its home is `/test/home`. So `mod.dataFolder` is `/test/home/.local/share/cmod/data/<name>`. The mod is installed and draws on a terminal 80 columns wide.
+The fake session's id is `test-session`, its model is `test-model`, and its home is `/test/home`. So `mod.dataFolder` is `/test/home/.local/share/cmod/data/<name>`, and `mod.folder` is `/test/plugins/<name>`. The mod is installed and draws on a terminal 80 columns wide.
 
 ## TestedMod
 
@@ -60,12 +62,16 @@ type TestedMod<State> = {
   start(): Promise<void>
   fire(event, input, below?): Promise<EventResult>
   settle(): Promise<void>
+  add(message: MessageDraft, options?: { task?: string }): Promise<Message[]>
+  endTurn(): Promise<void>
+  compact(): Promise<void>
+  startTask(task: { title: string; agentType?: string; model?: string; openedBy?: string; parent?: string }): Promise<string>
   lines(paneId: string): Promise<string[]>
-  lines(slot, props, requestId?): Promise<string[]>
-  type(line: string): Promise<Reply>
+  lines(place, props, requestId?): Promise<string[]>
+  type(line: string): Promise<CommandReply>
   callTool(name: string, input: Record<string, unknown>): Promise<EventResult<'tool.call'>>
   press(paneId: string, key: string, link?: string): Promise<void>
-  input(paneId: string, key: string, text: string, kind?: 'submit' | 'change'): Promise<void>
+  input(paneId: string, key: string, text: string, type?: 'submit' | 'change'): Promise<void>
   select(paneId: string, key: string, value: string): Promise<void>
   moveTo(projectRoot: string, cwd?: string): Promise<void>
   readonly state: Readonly<State>
@@ -82,13 +88,14 @@ Starts the mod: loads its state, runs `setup`, and adds its hooks, panes, and jo
 ### fire
 
 ```ts
-fire<E extends ModEvent>(event: E, input: TestInput<E>, below?): Promise<EventResult<`classic.${E}`>>
+fire<H extends Hook>(hook: H, input: TestInput<H>, below?): Promise<EventResult<`classic.${H}`>>
 fire<N extends RoutedEvent>(event: N, input: Args<N>, below?): Promise<EventResult<N>>
 ```
 
-- `fire('UserPromptSubmit', { prompt: 'hello' })` runs the mod's hooks on a `ModEvent`. `TestInput<E>` is the event's input without the fields `fire` fills: `session_id`, `transcript_path`, `cwd`, `hook_event_name`, and a new `tool_use_id` for each tool event.
+- `fire(UserPromptSubmit, { prompt: 'hello' })` runs the mod's listeners on a hook. `TestInput<H>` is the hook's input without the fields `fire` fills: `session_id`, `transcript_path`, `cwd`, `hook_event_name`, and a new `tool_use_id` for each tool event.
+- A `SessionStart` that names no `transcript_path` also writes its transcript as an empty file in the test's files, so the session's `session` values last as they do in Claude Code ([state.md](state.md)).
 - For a tool event, `files` is worked out from the call and the test's `files`, as in Claude Code.
-- `fire('PreToolUse', …)` runs the call's `tool.call`, and its `tool.check` inside it, as Claude Code does. `testMod` runs a mod as if `register.ts` calls `registerPermissionCheck`, so it returns `allow: true` or `ask` with the reason when the mod's hooks or `permissions` job decided the permission. A `PreToolUse` with `agent_id` and `agent_type`, such as `fire('PreToolUse', { tool_name: 'Read', tool_input: { file_path: 'a.ts' }, agent_id: 'agent-7', agent_type: 'explorer' })`, runs as that subagent's call. It returns `updatedInput` when the hooks rewrote the input, `additionalContext` as a list, and `deny` when a hook or Claude Code refused the call. Its `below` is `{ deny }` to test a call Claude Code refuses, and Claude Code runs the call otherwise.
+- `fire(PreToolUse, …)` runs the call's `tool.call`, and its `tool.check` inside it, as Claude Code does. `testMod` runs a mod as if `register.ts` calls `registerPermissionCheck`, so it returns `allow: true` or `ask` with the reason when the mod's hooks or `permissions` job decided the permission. A `PreToolUse` with `agent_id` and `agent_type`, such as `fire(PreToolUse, { tool_name: 'Read', tool_input: { file_path: 'a.ts' }, agent_id: 'agent-7', agent_type: 'explorer' })`, runs as that subagent's call. It returns `updatedInput` when the hooks rewrote the input, `additionalContext` as a list, and `deny` when a hook or Claude Code refused the call. Its `below` is `{ deny }` to test a call Claude Code refuses, and Claude Code runs the call otherwise.
 - On every other event, `below` is what the hooks beneath the mod answered. Pass it to test how the mod's answer combines with another. When nothing in the mod answers, `fire` returns `below` as it is.
 - Left out, `below` is `{}`, except on `prompt.submit`, where it is what Claude Code answers: the prompt that entered, `{ text, context, origin }`, with the `context` the mod's hooks added.
 - It returns the combined answer in Claude Code's own field names: `additionalContext` is a list, and `decision: 'block'` is `block`.
@@ -115,7 +122,7 @@ test('a force push is denied with the reason', async () => {
 
 ### Test a prompt with when
 
-A `prompt` with `when` runs on the hook-module event `prompt.submit`, not on `UserPromptSubmit`, so `fire('UserPromptSubmit', …)` never reaches it. `fire('prompt.submit', …)` returns the prompt that entered, with the text the prompt added in its `context`:
+A `prompt` with `when` runs on the hook-module event `prompt.submit`, not on `UserPromptSubmit`, so `fire(UserPromptSubmit, …)` never reaches it. `fire('prompt.submit', …)` returns the prompt that entered, with the text the prompt added in its `context`:
 
 - The `prompt.submit` input is `{ text, wait, origin }`. A prompt the person typed has `wait: false` and `origin: { kind: 'composer' }`.
 - `context` is a list of strings, each `# <name>\n<text>`. The answer has no `context` when no prompt added anything.
@@ -153,26 +160,59 @@ test('a prompt about a release gets the release steps, and another prompt gets n
 
 Waits until the work a hook started without awaiting it has run, such as a `void` call in a `Stop` hook. It returns while a fake the test holds open has not answered.
 
+### Build a conversation
+
+The current session, `test-session`, starts empty. A test builds the conversation the mod reads through `sessions` ([session.md](session.md)), the way Claude Code would write it:
+
+- `add(message, { task? })` adds a message and returns it, placed in its context and turn. A `Prompt` opens a new turn. With `task`, the message is that task's.
+- `endTurn()` ends the open turn, as Claude stopping does.
+- `compact()` records a compaction boundary, which ends the context and starts the next, as a compaction does.
+- `startTask({ title, agentType?, model?, openedBy?, parent? })` starts a task and returns its id, under the task `parent` names when it has one. Its owner runs `agentType` on `model`, and a `Prompt` added with its `task` opens the owner's own turn.
+
+Each one runs the mod's session listeners, as a new message does in Claude Code. A `MessageDraft` is a message without its place: `{ type: Prompt, text, from? }`, `{ type: Note, text, from? }`, `{ type: Reply, text }`, `{ type: ToolCall, name, input?, callId? }`, `{ type: ToolResult, callId, text, isError? }`, `{ type: Skill, name, text }`, `{ type: Document, path, text }`, or `{ type: Notice, text }`.
+
+The `sessions` option gives the earlier conversations, each a `FakeSession`: an `id`, its `messages` as drafts, its `goal`, and any `Session` field, such as `title`, `project`, or `isRunning`. A session that names no `project` is in the test's project.
+
+```ts
+import { expect, test } from 'bun:test'
+import { Prompt, Reply } from '../node_modules/@cmodjs/core/mod.js'
+import { testMod } from '../node_modules/@cmodjs/core/testing.js'
+import { recall } from '../src/mod.js'
+
+test('/recall finds the earlier session about the deploy', async () => {
+  const tested = testMod(recall, { sessions: [{ id: 'older', title: 'Fix the deploy', messages: [{ type: Prompt, text: 'Why did the deploy fail?' }] }] })
+  await tested.add({ type: Prompt, text: 'Recall the deploy' })
+  await tested.add({ type: Reply, text: 'Looking.' })
+  await tested.endTurn()
+
+  expect(await tested.type('/recall deploy')).toEqual({ text: 'Fix the deploy: Why did the deploy fail?' })
+})
+```
+
+`shown.sent` lists what the mod sent to other sessions and to tasks' owners, each with its `session`, and its `task` for an owner. `fakes.agent.spawn` answers the current session's `startTask`, such as `async () => ({ agentId: 'agent-7', model: 'test-model' })`, and `fakes.tool.call` its `callTool`. Another session's `startTask` starts a task in that fake session.
+
+A `before` listener on the current session answers the event `fire` raises, such as `tested.fire('prompt.submit', { text: 'Deploy to prod', origin: { kind: 'composer' }, wait: false })` or `tested.fire('tool.call', { tool: 'Bash', tool_use_id: 'toolu_1', command: 'rm -rf build' })`.
+
 ### lines
 
 - `lines(paneId)` draws an open pane and returns its rows of text. It rejects a pane that is not open: open it first with `tested.type('/<command>')` or `pane.open()` in the mod. The render gets the props `title`, `isFocused`, true once an `open` or `toggle` with `{ focus: true }` opened it, `bodyColumns`, `placement: 'dock'`, `scroll: { offset: 0, bodyRows: 24 }`, and `view: {}`, the main conversation's view.
 - A `Button` draws as Claude Code draws it: `[ Save ]`, or `1: Save` when it is `plain` with a `hotkey`, or `Save` when it is `plain` alone. Borders and colors are not drawn.
-- `lines(slot, props, requestId?)` draws a slot render with `props` and returns its rows. `Default` draws a plain listing of the props it gets, so a test sees what the render changed. Draw `slots.AssistantMessage` with a reply's `text` to test a markdown slot render. Draws that pass one `requestId` grow one streamed reply.
+- `lines(place, props, requestId?)` draws a place render with `props` and returns its rows. `Default` draws a plain listing of the props it gets, so a test sees what the render changed. Draw `Reply` with a reply's `text` to test a markdown place render. Draws that pass one `requestId` grow one streamed reply. `AbovePrompt` ends with the toasts shown now, under the mod's own rows.
 
 ```ts
 import { expect, test } from 'bun:test'
 import type { RenderPropsOf } from 'claude-code'
+import { AbovePrompt, UserPromptSubmit } from '../node_modules/@cmodjs/core/mod.js'
 import { testMod } from '../node_modules/@cmodjs/core/testing.js'
-import { slots } from '../node_modules/@cmodjs/core/ui/slots.js'
 import { hints } from '../src/mod.js'
 
 const band: RenderPropsOf['AbovePrompt'] = { hasSurvey: false, isWorking: false, maxRows: 12, bodyColumns: 75, scroll: { offset: 0, bodyRows: 12 }, view: {} }
 
-test('the band shows the prompt count on its last line', async () => {
+test('the band shows the prompt count', async () => {
   const tested = testMod(hints)
-  await tested.fire('UserPromptSubmit', { prompt: 'hello' })
+  await tested.fire(UserPromptSubmit, { prompt: 'hello' })
 
-  expect((await tested.lines(slots.AbovePrompt, band)).at(-1)).toBe('Prompts: 1')
+  expect(await tested.lines(AbovePrompt, band)).toContain('Prompts: 1')
 })
 ```
 
@@ -190,7 +230,7 @@ test('the band shows the prompt count on its last line', async () => {
 
 - `press(paneId, key)` presses the `Button` whose `key` or `label` is `key`, and runs its `onPress`.
 - `press(paneId, key, link)` presses the link `link` in the `Markdown` whose `key` is `key`, and runs its `onLinkPress`.
-- `input(paneId, key, text)` types `text` into the `Input` whose `key` is `key` and presses Enter, which runs its `onSubmit`. With `kind` `'change'` it runs `onInput` instead, as one edit does.
+- `input(paneId, key, text)` types `text` into the `Input` whose `key` is `key` and presses Enter, which runs its `onSubmit`. With `type` `'change'` it runs `onInput` instead, as one edit does.
 - `select(paneId, key, value)` picks the option `value` of the `Select` whose `key` is `key`, and runs its `onSelect`. It rejects an option the `Select` does not have.
 
 ```ts
@@ -201,7 +241,7 @@ expect(await tested.lines('history')).toContain('deploy by explorer')
 
 ### moveTo
 
-`moveTo(projectRoot, cwd?)` moves the session. A new `projectRoot` runs a `/cd` there, so the mod loads that project's state. A `cwd` then runs a Bash `cd` there. The mod's `CwdChanged` hooks run for each move.
+`moveTo(projectRoot, cwd?)` moves the session. A new `projectRoot` runs a `/cd` there, so the mod loads that project's state. A `cwd` then runs a Bash `cd` there. The mod's `CwdChanged` listeners run for each move, and `sessions.current` follows it.
 
 ### state
 
@@ -235,20 +275,22 @@ Set a fake to answer a call:
 
 - A call with no fake throws `<call>(<args>) has no fake answer. Set fakes.<call> on the tested mod.` So set `fakes.process.run` before a test runs a program, and `fakes.ui.ask` before the mod asks a question.
 - A `program` job is the exception: it catches the `process.spawn` error and retries after 1, 2, 4, 8 and 16 seconds on real timers, so its `ready()` waits past `bun test`'s 5-second timeout. Set `fakes.process.spawn` before a test starts a `program` job.
-- `files` already fills the `fs` fakes: a write is read back, and `list` lists the given files. The fake file system resolves a relative path against `/`, not against `mod.cwd`, so a mod under test reads `${mod.projectRoot}/<file>` rather than a relative path. `fs.list()` with no path rejects.
+- `files` already fills the `fs` fakes: a write is read back, and `list` lists the given files. The fake file system resolves a relative path against `/`, not against the session's working folder, so a mod under test reads `${sessions.current.project}/<file>` rather than a relative path. `fs.list()` with no path rejects.
 - `ui.open` places every pane by default. A fake that answers `{ isPlaced: false }` holds a pane back.
 - `ui.scroll` answers `{}` by default, as when the window moved. A fake that answers `{ deny }` refuses the scroll.
 - `clock.after(ms, fn)` and `clock.every(ms, fn)` each return `{ cancel() }`, and so must a fake of either. `clock.after` runs a real timer by default. `clock.every` never fires unless a fake keeps `fn` for the test to call, so a test of `mod.every` keeps it and calls it once per tick.
 - `session.append` and `prompt.submit` take every note and prompt by default, into `shown.notes` and `shown.prompts`. A fake that answers `{ deny }` or `{ drop }` refuses one.
 - `model.complete` has no default: set it to the answer the model gives, such as `async () => ({ isAnswered: true, text: 'no', usage })`.
+- `settings.read` answers `{}` by default, as Claude Code does with no `settings.json` files.
 - `config.list` answers no `/config` rows by default. A `config.list` fake that answers a row with `isLocked: true` locks that option as managed settings do.
 - `tool.call` answers `CronCreate`, `CronDelete`, and `CronList` by default, keeping the crons a `schedule` makes in `shown.schedules`. A call to any other tool needs a fake.
-- `files` takes symbolic links too: `testMod(mod, { files, links: { '/work/skills': '/shared/skills' } })` makes `/work/skills` a link to `/shared/skills`, so a test of `mod.fs.find` or `mod.metadata.update` follows it as a real file system does.
+- `files` takes symbolic links too: `testMod(mod, { files, links: { '/work/skills': '/shared/skills' } })` makes `/work/skills` a link to `/shared/skills`, so a test of `fs.find` or `metadata.update` follows it as a real file system does.
 - `testMod` runs no installer pane: an option with no default and no value fails `start()` with its fix, and the `installer` steps are not shown. Test a step's `render` and `isDone` by calling them with the started `mod`.
 - The `committer` below runs `git`, so its `package.json` declares `"permissions": { "run": ["git"] }`. A gated call the mod does not declare fails before it reaches a fake ([permissions.md](permissions.md)).
 
 ```ts
 import { expect, test } from 'bun:test'
+import { Stop } from '../node_modules/@cmodjs/core/mod.js'
 import { testMod } from '../node_modules/@cmodjs/core/testing.js'
 import { committer } from '../src/mod.js'
 
@@ -257,7 +299,7 @@ test('a Commit answer commits', async () => {
   tested.fakes.ui.ask = async () => 'Commit'
   tested.fakes.process.run = async () => ({ exitCode: 0, stdout: '', stderr: '', isStdoutTruncated: false, isStderrTruncated: false })
 
-  await tested.fire('Stop', { stop_hook_active: false })
+  await tested.fire(Stop, { stop_hook_active: false })
 
   expect(tested.calls.filter(({ call }) => call === 'process.run').map(({ args }) => args[0])).toEqual([['git', 'commit', '-am', 'wip']])
 })
@@ -267,7 +309,7 @@ test('a Commit answer commits', async () => {
 
 ```ts
 type Shown = {
-  readonly toasts: string[]
+  readonly toasts: ShownToast[]
   readonly notes: string[]
   readonly prompts: string[]
   readonly logs: string[]
@@ -277,10 +319,13 @@ type Shown = {
   readonly commands: string[]
   readonly tools: string[]
   readonly schedules: { readonly id: string; readonly cron: string; readonly prompt: string }[]
+  readonly sent: { readonly session: string; readonly type: string; readonly text: string; readonly as?: string }[]
 }
+
+type ShownToast = { readonly type: ToastType; readonly message: string; readonly description?: string }
 ```
 
-What the person and Claude would see: the toasts, the notes the mod added for Claude with `mod.session.append` or a `prompt` that follows the state, the prompts it sent with `mod.session.submit`, the log lines, the debug log lines, each status line text, the open panes, the slash commands and tools the mod added, and the crons its `schedule` keeps now.
+What the person and Claude would see: the toasts shown now, with a text description, the notes the mod added for Claude with `sessions.current.send` or a `prompt` that follows the state, the prompts it sent to the current session, the messages it sent to other sessions in `sent`, the log lines, the debug log lines, each status line text, the open panes, the slash commands and tools the mod added, and the crons its `schedule` keeps now.
 
 ```ts
 test('the Mode prompt follows the mode', async () => {

package/docs/ui.md

@@ -1,14 +1,15 @@
 # UI
 
-A mod draws in four places: its own panes, the rows Claude Code draws (slots), the blocks of Claude's replies (markdown slots), and short messages: toasts, progress lines, and questions. All of it lives on `mod.ui`.
+A mod draws in four ways: its own panes, the rows Claude Code draws (places), the blocks of Claude's replies (markdown places), and short messages: toasts, questions, and notices. All of it lives on `mod.ui`.
 
 ```ts
 mod.ui.pane(pane: Pane<State>): PaneHandle
-mod.ui.render<S extends Slot>(slot: S, Component: (props: SlotProps<S>) => RenderElement): void
-mod.ui.toast(text: string, options?: { timeoutMs?: number }): void
-mod.ui.progress<T>(title: string, task: (report: (step: ProgressStep) => void) => Promise<T>): Promise<T>
+mod.ui.render<P extends Place>(place: P, Component: (props: PlaceProps<P>) => RenderElement): Disposable
+mod.ui.toast: Toast
+mod.ui.copy(text: string): Promise<void>
 mod.ui.ask(question: string, options?: readonly string[] | AskOptions): Promise<string>
 mod.ui.scroll(args: UiScrollArgs): Promise<UiScrollResult>
+mod.ui.notice(callId: string, text: string | undefined): void
 ```
 
 Claude Mod Manager (cmod) draws the mod again whenever a value in `mod.state` changes. A render reads `mod.state` and returns what to show. It never draws by hand.
@@ -45,13 +46,13 @@ export function Count({ label, count }: { readonly label: string; readonly count
 }
 ```
 
-An element called outside a render throws `<Element> was called outside a render. Use it inside a pane's render or a slot's component.` So build elements inside a pane's `render` or a slot's component, never at module load or in a hook.
+An element built outside a render, at module load or in a hook, holds its props until a render draws it. So a hook can build a toast's `description` and the band draws it later.
 
 `drawWith(table, draw, markdown?)` is the function cmod draws a render with. A mod never calls it.
 
 ## Components
 
-`ui/components.js` exports controls built from the elements and Claude Code's theme colors, so they follow the person's theme and look the same in every mod. Each is a component like the ones a mod writes: a function of props, used in a pane's `render` or a slot's component.
+`ui/components.js` exports controls built from the elements and Claude Code's theme colors, so they follow the person's theme and look the same in every mod. Each is a component like the ones a mod writes: a function of props, used in a pane's `render` or a place's component.
 
 ```ts
 Tabs(props: { tabs: readonly { key: string; label: string }[]; selected: string; onSelect(key: string): void; children? })
@@ -62,7 +63,7 @@ Tooltip(props: { text: string; children? })
 Help(props: { text: string; isOpen: boolean; onOpenChange(isOpen: boolean): void })
 Dialog(props: { title: string; children?; actions })
 Pagination(props: { page: number; pages: number; onPage(page: number): void })
-ProgressBar(props: { done: number; total: number; width?: number })
+Progress(props: { value: number; width?: number })
 ```
 
 - `Tabs` draws a row of tabs over `children`. The selected tab's number is in the accent color and its label bold and underlined. Each other tab is a `Button` whose hotkey is its number, so a pane that holds the keyboard switches tabs by number, Tab, or a click. A hotkey is one digit, so only the first nine tabs have a number.
@@ -72,7 +73,7 @@ ProgressBar(props: { done: number; total: number; width?: number })
 - `Help` draws a `?` that shows `text` the same way. A press of `?` keeps the card open until the next press, so the keyboard reaches it too. Keep `isOpen` in `mod.state`.
 - `Dialog` lays out a dialog's title, body, and `actions`, the buttons in a row. Put the safe action first, as the `primary` Button with `autoFocus`.
 - `Pagination` draws `p: Previous  2 of 5  n: Next`. `p` and `n` are its hotkeys, and an end it cannot pass is dim text.
-- `ProgressBar` fills `width` columns, 24 unless given, in proportion to `done` of `total`, and shows the count. The progress lines `mod.ui.progress` draws use it too.
+- `Progress` fills `value` percent of `width` columns, 24 unless given. Put the count or a label beside it in a `Text`, or pass it as a loading toast's `description`.
 - `Tabs`, `Toggle`, `Help`, and `Pagination` hold no state of their own. Keep their value in `mod.state` and set it in the callback, as in React's controlled components.
 
 A pane opened with `focus`, `closeOnEscape`, and `holdToasts` is a dialog. Claude Code shows it as a tab of the dock, beside the mod's other panes, and Escape closes it:
@@ -114,7 +115,7 @@ Open it with `mod.ui.pane(confirmPane).open({ focus: true })`. It draws as:
  [ Keep it ]  [ Delete ]
 ```
 
-A pane with `Tabs`, a `Tooltip`, a `ProgressBar`, `Pagination`, and a `Toggle` with `Help` draws as:
+A pane with `Tabs`, a `Tooltip`, a `Progress` beside its count, `Pagination`, and a `Toggle` with `Help` draws as:
 
 ```text
  1: Controls   2: Split   3: Files
@@ -217,9 +218,13 @@ type PaneHandle = {
   close(): Promise<void>
   toggle(options?: { readonly focus?: true }): Promise<void>
   readonly isOpen: boolean
+  readonly isShown: boolean
+  readonly isFocused: boolean
 }
 ```
 
+- `isShown` is true while the pane is the one Claude Code shows. Claude Code shows one pane at a time and the rest wait as tabs behind it.
+- `isFocused` is true while the person has given the pane the keyboard.
 - `open` asks Claude Code to show the pane. `isOpen` turns true once Claude Code places it. Claude Code may hold a pane back, and then `isOpen` stays false.
 - `{ focus: true }` asks Claude Code to give the pane the keyboard as it opens. Claude Code gives it only while the prompt is empty and holds the keyboard, so typed text, a dialog, or another pane the person is using keeps it. cmod sends `focus` only on that one open, never when it resizes the pane.
 - `mod.ui.pane` only adds the pane. cmod opens it only when the mod calls `open` or `toggle`, and Claude Code shows a pane only once the plugin has opened it. So give the person a way in, such as a slash command whose `reply` calls `pane.toggle()`.
@@ -248,141 +253,170 @@ export const notes = defineMod({
 })
 ```
 
-## Slots: change a row Claude Code draws
+## Places: change a row Claude Code draws
 
-`mod.ui.render(slot, Component)` draws in place of one of Claude Code's own rows. `ui/slots.js` exports `slots`:
+`mod.ui.render(place, Component)` draws in place of one of Claude Code's own rows. `mod.js` exports each place as a constant. A message type is a place too, so `Reply` is where Claude Code draws a reply:
 
-| Slot | What Claude Code draws there |
+| Place | What Claude Code draws there |
 | --- | --- |
-| `slots.AssistantMessage` | One text block of Claude's reply |
-| `slots.UserMessage` | A user row: the prompt, a task notification, or another agent's message |
-| `slots.ToolUse` | A tool call's row |
-| `slots.ToolResult` | A tool call's result |
-| `slots.ToolGroup` | The condensed row of a group of tool calls |
-| `slots.ToolProgress` | A tool's progress line |
-| `slots.CommandOutput` | A slash command's output |
-| `slots.AskUserQuestion` | The dialog the AskUserQuestion tool opens |
-| `slots.InfoNotice` | A dim status line under the logo |
-| `slots.Spinner` | The spinner line while Claude works |
-| `slots.TurnDuration` | The line that closes a turn |
-| `slots.SessionMode` | The session's modes |
-| `slots.PromptHint` | The prompt's hint line, such as `? for shortcuts` |
-| `slots.AbovePrompt` | The band above the prompt, where surveys draw |
-
-`Component` gets `SlotProps<S>`: the props Claude Code types as `RenderPropsOf['<Slot>']`, plus `Default`.
+| `Reply` | One text block of Claude's reply |
+| `Prompt` | A prompt row: the person's prompt, a task notification, or another session's message |
+| `ToolCall` | A tool call's row |
+| `ToolResult` | A tool call's result |
+| `Notice` | A dim status line under the logo |
+| `ToolGroup` | The condensed row of a group of tool calls |
+| `ToolProgress` | A tool's progress line |
+| `CommandOutput` | A slash command's output |
+| `AskUserQuestion` | The dialog the AskUserQuestion tool opens |
+| `Spinner` | The spinner line while Claude works |
+| `TurnDuration` | The line that closes a turn |
+| `SessionMode` | The session's modes |
+| `PromptHint` | The prompt's hint line, such as `? for shortcuts` |
+| `AbovePrompt` | The band above the prompt, where surveys draw |
+
+`Component` gets `PlaceProps<P>`: the props Claude Code draws that row with, plus `Default`.
 
 - `Default` draws what Claude Code, and the renders of other mods, would draw. Pass it props to change what it draws, such as `<Default hint="…" />`. Return `<Default />` to change nothing.
 - A render adds to what it wraps. In `AbovePrompt`, drawing `<Default />` and a line under it keeps the lines of Claude Code and other mods.
 - A render must draw the same for the same props. One that calls `Default` a different number of times on a second draw falls back to Claude Code's drawing.
-- A render that throws falls back to Claude Code's drawing. cmod logs `<mod>: the <Slot> render threw, so Claude Code draws its own: <error>` once.
-- A mod renders each slot once. A second `mod.ui.render` of one slot throws `<mod>: a render of <Slot> is already added. Render each slot once.` For a markdown slot the error names it as `a render of markdown <Kind>`, such as `a render of markdown CodeBlock`.
-- `slots.ToolUse` changes a call's own row. A group of calls shows the `slots.ToolGroup` row, which Claude Code builds from the stored message, so a mod that hides a tool's input also sets `isExpanded` on `slots.ToolGroup` to unfold the group into `ToolUse` rows.
-- No slot covers the permission dialog.
+- A render that throws, or draws differently on a second pass, falls back to Claude Code's drawing, and cmod shows the error toast `The <Place> render failed` once, with the reason under it.
+- A mod renders each place once. A second `mod.ui.render` of one place throws `<mod>: a render of <Place> is already added. Render each place once.`
+- `render` returns a `Disposable`. `dispose()` takes the render back, and Claude Code draws the row as before ([mod.md](mod.md#disposable)).
+- `ToolCall` changes a call's own row. A group of calls shows the `ToolGroup` row, which Claude Code builds from the stored message, so a mod that hides a tool's input also sets `isExpanded` on `ToolGroup` to unfold the group into `ToolCall` rows.
+- No place covers the permission dialog. `mod.ui.notice` adds a line under it instead ([Notices](#notices)).
 
 ```tsx
-import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+import { AbovePrompt, defineMod, PromptHint, UserPromptSubmit } from '../node_modules/@cmodjs/core/mod.js'
 import { Box, Text } from '../node_modules/@cmodjs/core/ui/elements.js'
-import { slots } from '../node_modules/@cmodjs/core/ui/slots.js'
 
 export const hints = defineMod({
   name: 'hints',
   state: { session: { prompts: 0 } },
   setup(mod) {
-    mod.ui.render(slots.PromptHint, ({ hint, Default }) => <Default hint={hint.toUpperCase()} />)
-    mod.ui.render(slots.AbovePrompt, ({ hasSurvey, Default }) =>
+    mod.ui.render(PromptHint, ({ hint, Default }) => <Default hint={hint.toUpperCase()} />)
+    mod.ui.render(AbovePrompt, ({ hasSurvey, Default }) =>
       hasSurvey ? <Default /> : (
         <Box flexDirection="column">
           <Default />
           <Text dimColor>{`Prompts: ${mod.state.session.prompts}`}</Text>
         </Box>
       ))
-    mod.on('UserPromptSubmit', () => {
+    mod.on(UserPromptSubmit, () => {
       mod.state.session.prompts += 1
     })
   },
 })
 ```
 
-`Slot` and `SlotProps` are the types behind `slots`. Type a component's props as `SlotProps<typeof slots.PromptHint>`.
+`Place` is the type of every place, and `PlaceProps` the props of one. Type a component's props as `PlaceProps<typeof PromptHint>`.
 
-## Markdown slots: change the blocks of a reply
+## Markdown places: change the blocks of a reply
 
-`ui/markdown.js` exports `markdownSlots`, one per markdown block:
+Each markdown block of a reply is a place of its own. `ui/markdown.js` exports these places, apart from the rest, because it brings the markdown reader, about 230 KB that takes some 18 ms to load. A mod that imports none of them starts without it.
 
-| Slot | Block | Props beyond `text` and `source` |
+| Place | Block | Props beyond `text` and `source` |
 | --- | --- | --- |
-| `markdownSlots.Heading` | A heading | `depth`, 1 to 6 |
-| `markdownSlots.Paragraph` | A paragraph | none |
-| `markdownSlots.CodeBlock` | A code block | `lang`, `meta`, `value` |
-| `markdownSlots.BlockQuote` | A block quote | none |
-| `markdownSlots.List` | A list | `ordered`, `start`, `spread` |
-| `markdownSlots.Table` | A table | `align` |
-| `markdownSlots.ThematicBreak` | A `---` line | none |
-| `markdownSlots.HtmlBlock` | An HTML block | `value` |
+| `Heading` | A heading | `depth`, 1 to 6 |
+| `Paragraph` | A paragraph | none |
+| `CodeBlock` | A code block | `lang`, `meta`, `value` |
+| `BlockQuote` | A block quote | none |
+| `List` | A list | `ordered`, `start`, `spread` |
+| `Table` | A table | `align` |
+| `ThematicBreak` | A `---` line | none |
+| `HtmlBlock` | An HTML block | `value` |
 
 - `text` is the block's plain text, one line per list item, table row, or quoted line. `source` is the block's markdown.
 - `Default` draws the block as Claude Code would. `<Default source="…" />` draws other markdown in its place.
-- A markdown slot render draws in Claude's replies and in every `Markdown` element of the mod's panes.
+- A markdown render draws in Claude's replies and in every `Markdown` element of the mod's panes.
 - While a reply streams in, Claude Code draws a block that is not finished yet. The mod draws it once it is.
-- A render that throws falls back to Claude Code's drawing of the block and logs once.
+- A render that throws falls back to Claude Code's drawing of the block, and shows the error toast once.
 
 ```tsx
 import type { RenderElement } from 'claude-code'
-import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+import { defineMod, type PlaceProps } from '../node_modules/@cmodjs/core/mod.js'
+import { CodeBlock } from '../node_modules/@cmodjs/core/ui/markdown.js'
 import { Text } from '../node_modules/@cmodjs/core/ui/elements.js'
-import { markdownSlots } from '../node_modules/@cmodjs/core/ui/markdown.js'
-import type { SlotProps } from '../node_modules/@cmodjs/core/ui/slots.js'
 
-function MermaidBlock({ lang, value, Default }: SlotProps<typeof markdownSlots.CodeBlock>): RenderElement {
+function MermaidBlock({ lang, value, Default }: PlaceProps<typeof CodeBlock>): RenderElement {
   return lang === 'mermaid' ? <Text>{`diagram: ${value}`}</Text> : <Default />
 }
 
 export const diagrams = defineMod({
   name: 'diagrams',
   setup(mod) {
-    mod.ui.render(markdownSlots.CodeBlock, MermaidBlock)
+    mod.ui.render(CodeBlock, MermaidBlock)
   },
 })
 ```
 
 ```ts
-markdownBlocks<S>(text: string, slot: S): Omit<SlotProps<S>, 'Default'>[]
+markdownBlocks<P extends MarkdownPlace>(text: string, place: P): Omit<PlaceProps<P>, 'Default'>[]
 ```
 
-`markdownBlocks` returns the props of every block of one kind in a markdown text. A test uses it to call a component with real props.
-
-`MarkdownKind`, `MarkdownReader`, and `MarkdownPiece` are the types behind `markdownSlots`. A mod never builds them.
+`markdownBlocks`, exported from `ui/markdown.js`, returns the props of every block at one markdown place in a markdown text, such as every code block of a reply. A mod reads the blocks of a reply it got in a hook with it, and a test calls a component with real props.
 
-## Toasts
+```ts
+import { CodeBlock, markdownBlocks } from '../node_modules/@cmodjs/core/ui/markdown.js'
 
-`mod.ui.toast(text, options?)` shows the person a short message on Claude Code's stack of plugin toasts, over the transcript's top right corner and under the mod's name. It stays 4 seconds, or `timeoutMs`. A click takes it off, and the pointer resting on it holds it. While a pane opened with `holdToasts` is shown, it waits.
+const diagrams = markdownBlocks(reply, CodeBlock).filter((block) => block.lang === 'mermaid')
+```
 
-## Progress lines
+## Notices
 
 ```ts
-mod.ui.progress<T>(title: string, task: (report: (step: ProgressStep) => void) => Promise<T>): Promise<T>
+mod.ui.notice(callId: string, text: string | undefined): void
+```
+
+`notice` shows `text` as one line under the permission dialog that is open for the tool call `callId`, the call's `tool_use_id`, such as `checked by safe-delete`. `undefined` removes the line, and Claude Code removes it on its own once the call is decided. A call with no open dialog takes no line.
+
+## Toasts
+
+`mod.ui.toast` shows the person a short message in the band above the prompt, one row per toast, under the mod's name. Its shape follows [Sonner](https://sonner.emilkowal.ski/toast):
 
-type ProgressStep = { readonly done: number; readonly total: number; readonly label?: string }
+```ts
+mod.ui.toast(message: string, options?: ToastOptions): ToastId
+mod.ui.toast.success(message, options?) / .info / .warning / .error / .loading
+mod.ui.toast.promise<T>(task: Promise<T> | (() => Promise<T>), messages: { loading: string; success: string | ((value: T) => string); error: string | ((error: unknown) => string) }): { unwrap(): Promise<T> }
+mod.ui.toast.dismiss(id?: ToastId): void
+
+type ToastOptions = {
+  id?: ToastId
+  description?: string | RenderElement
+  action?: { label: string; onClick(): unknown }
+  duration?: number
+}
 ```
 
-`progress` draws a line in the band above the prompt while `task` runs, and removes it when `task` settles. The line shows a spinner and the title. After the first `report` it also shows a bar, `done/total`, and the label. `progress` resolves or rejects as `task` does.
+- Each type draws its icon: `✓` success, `ℹ` info, `⚠` warning, `✗` error, and a spinner for loading.
+- A toast stays 4 seconds once the band draws it, or `duration` ms. `Infinity` keeps it until the person closes it, and a loading toast stays until it changes. The time waits while Claude Code shows a survey over the band.
+- A toast with the `id` of a shown toast replaces it in place, so a loading toast turns into its success or error.
+- A text `description` shows its first line dim under the message. A press on the message unfolds the whole text and stops the time, and a second press folds it. An element `description`, such as a `Progress`, draws as it is.
+- `action` draws a button after the message. A press that throws shows an error toast with the cause.
+- `✕` closes the toast. The band shows the newest 3, and `+N more` shows every toast.
+- `promise` shows `loading` while `task` runs, then `success` or `error` in the same row. `unwrap()` resolves or rejects as `task` does.
 
 ```ts
-import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+import { defineMod, fs, SessionStart, sessions } from '../node_modules/@cmodjs/core/mod.js'
 
 export const indexer = defineMod({
   name: 'indexer',
   setup(mod) {
-    mod.on('SessionStart', async () => {
-      const entries = await mod.fs.list(mod.projectRoot)
-      await mod.ui.progress('Indexing', async (report) => {
-        for (const [index, entry] of entries.entries()) report({ done: index + 1, total: entries.length, label: entry.name })
-      })
+    mod.on(SessionStart, async () => {
+      const indexed = fs.list(sessions.current.project).then((entries) => entries.length)
+      mod.ui.toast.promise(indexed, { loading: 'Indexing files', success: (count) => `Indexed ${count} files`, error: 'Indexing failed' })
     })
   },
 })
 ```
 
+An error cmod catches for a mod, such as a hook that throws, shows as an error toast that stays, with its buttons on a line under the message:
+
+- `Retry` runs the failed step again, where running it again can work: an install, the mod's setup, or a program that stopped.
+- `Report` replaces the toast's buttons with the ways to tell the mod's author, with the keys on the first, and `Back` returns to the buttons. The same failure happening again keeps them open. `Ask Claude to report it` sends this session a prompt to file the report with the person's own tools, and Claude Code asks before each step. `Report it on GitHub (opens your browser)` opens a filled-in issue on the mod's `supportUrl` or `repository` in its `plugin.json`, or `Email the author (opens your mail app)` writes to its `author.email`. `Copy the error` copies the mod's name and version, the `@cmodjs/core` version, the message, the whole cause, and the stack.
+- `Hide` closes the toast and keeps the same failure hidden in later sessions. A new version of the mod, or a different failure, shows again.
+
+`mod.ui.copy(text)` puts `text` on the person's clipboard. It rejects with Claude Code's reason when the terminal cannot take it.
+
 ## Questions
 
 ```ts
@@ -394,14 +428,14 @@ type AskOptions = { options?: readonly string[]; header?: string; multiSelect?:
 `ask` shows a question with 2 to 4 options and resolves the answer. Fewer than two options are padded with Yes and No, and the person may type an answer of their own. `header` is a short chip beside the question, 12 characters at most. `multiSelect` lets the person pick several, and the answer comes back joined by commas.
 
 ```ts
-import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+import { defineMod, process, sessions, Stop } from '../node_modules/@cmodjs/core/mod.js'
 
 export const committer = defineMod({
   name: 'committer',
   setup(mod) {
-    mod.on('Stop', async () => {
+    mod.on(Stop, async () => {
       const answer = await mod.ui.ask('Commit the changes?', { options: ['Commit', 'Wait'], header: 'Commit' })
-      if (answer === 'Commit') await mod.process.run(['git', 'commit', '-am', 'wip'], { cwd: mod.projectRoot })
+      if (answer === 'Commit') await process.run(['git', 'commit', '-am', 'wip'], { cwd: sessions.current.project })
     })
   },
 })
@@ -419,6 +453,12 @@ mod.ui.scroll(args: { to: 'start' | 'end' | { key: string } | { requestId: strin
 <Button label="Latest" onPress={() => mod.ui.scroll({ to: 'end', in: 'log' })} />
 ```
 
+A [message](session.md#message)'s `id` names the row Claude Code draws it under, so a history pane brings the conversation to the message a person presses. When one row holds several messages, such as a reply with its tool calls, each `id` ends in `:<n>`, and the row is the `id` before it:
+
+```tsx
+<Button label={message.text} onPress={() => mod.ui.scroll({ to: { requestId: message.id.split(':')[0] } })} />
+```
+
 ## Test the UI
 
-`tested.lines(paneId)` reads an open pane as rows of text. `tested.lines(slot, props)` draws a slot render. `tested.press(paneId, key)` presses a button. `tested.shown.toasts` lists the toasts. [testing.md](testing.md) covers each.
+`tested.lines(paneId)` reads an open pane as rows of text. `tested.lines(place, props)` draws a place render. `tested.press(paneId, key)` presses a button. `tested.shown.toasts` lists the toasts shown now, each as `{ type, message, description? }`. [testing.md](testing.md) covers each.

package/jobs/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/jobs/check.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAOpC,OAAO,EAAyB,KAAK,MAAM,EAAE,MAAM,+BAA+B,CAAA;AAIlF,wBAAgB,KAAK,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CA4BjM"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/jobs/check.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAQpC,OAAO,EAAyB,KAAK,MAAM,EAAE,MAAM,+BAA+B,CAAA;AAIlF,wBAAgB,KAAK,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CA8BjM"}

package/jobs/check.js

@@ -2,7 +2,8 @@ import { longestMs } from '../runtime/deadline.js';
 import { callEffects } from '../utils/call-effects.js';
 import { dirname } from '../vendor.js';
 import { listed, messageOf } from '../utils/text.js';
-import { afterCall, modOf, targetWords } from './context.js';
+import { engineOf } from '../runtime/engine.js';
+import { afterCall, targetWords, withinDeadline } from './context.js';
 import { matchTarget, targetOf } from './permissions/match-target.js';
 const defaultMs = 60_000;
 export function check(options) {
@@ -25,7 +26,9 @@ export function check(options) {
                 return [];
             try {
                 const { command, folder } = triggered;
-                const { exitCode, stdout, stderr } = await modOf(job, { folder }, workspace, deadline).process.run(command);
+                const workTree = await workspace.scope?.workTreeOf(folder);
+                const { claude } = engineOf(job.mod);
+                const { exitCode, stdout, stderr } = await withinDeadline(job.mod, deadline, command.join(' '), () => claude.process.run(command, { ...(workTree === undefined ? {} : { cwd: workTree }), timeoutMs }));
                 return exitCode === 0 ? [] : [`${command.join(' ')} exited with ${exitCode}:\n${`${stdout}${stderr}`.trim()}`];
             }
             catch (error) {