@cmodjs/core 3.1.0 → 4.0.0

package/docs/session.md

@@ -34,7 +34,7 @@ type Sessions = {
   readonly current: CurrentSession
   list(options?: { running?: boolean; since?: string; everyProject?: boolean }): Promise<Session[]>
   search(text: string, matcher?: Matcher<Message>, options?: { running?: boolean; since?: string; everyProject?: boolean; before?: Message }): AsyncIterable<Message>
-  onMessage(matcher?, listener, options?): Disposable   // and every on method below
+  onMessage(matcher?, listener, options?): Subscription   // and every on method below
 }
 ```
 
@@ -76,8 +76,8 @@ type Session = {
   turns(options?: { last?: number }): Promise<Turn[]>
   messages(options?: { after?: string; last?: number }): Promise<Message[]>
   search(text: string, matcher?: Matcher<Message>): AsyncIterable<Message>
-  onMessage(matcher?, listener, options?): Disposable      // and every on method below
-  beforePrompt(matcher?, listener, options?): Disposable   // and every before method below
+  onMessage(matcher?, listener, options?): Subscription      // and every on method below
+  beforePrompt(matcher?, listener, options?): Subscription   // and every before method below
   send(message: { type: Prompt | Note; text: string; as?: Person | Session }): Promise<void>
   startTask(task: { prompt: string; title: string; agentType?: string; model?: string; name?: string; cwd?: string }): Promise<Task>
   callTool(call: { name: string; input: Record<string, unknown> }): Promise<ToolResult>
@@ -109,11 +109,13 @@ const explorers = (await sessions.current.goal.tasks()).filter((task) => task.ow
 
 A session that has ended keeps its record, so every read works on it.
 
+`sessions.current` adds two members for the rows Claude Code draws, `scrollTo(message, options?)` and `caption(toolCall, text)` ([ui.md](ui.md#the-conversations-rows)).
+
 ### Listen to a record
 
 ```ts
-part.on<Event>(listener: (payload, time: { deadline: number; signal: AbortSignal }) => unknown, options?: { timeoutMs?: number }): Disposable
-part.on<Event>(matcher: Matcher<payload>, listener, options?): Disposable
+part.on<Event>(listener: (payload, time: { deadline: number; signal: AbortSignal }) => unknown, options?: { timeoutMs?: number }): Subscription
+part.on<Event>(matcher: Matcher<payload>, listener, options?): Subscription
 ```
 
 Each event has its own method, such as `onReply` or `onTaskStart`, which runs `listener` for each new message, turn, context, task, goal change, or usage change, as it happens. `sessions`, a session, its goal, a task, a context, and a turn each have every `on` method, and each hears what happens inside it: an event reaches the part it happens in and every part above it.
@@ -153,7 +155,7 @@ sessions.current.onToolCall({ name: /^(Edit|Write)$/ }, (call) => void (mod.stat
 sessions.current.onTaskStart({ owner: { agentType: 'Explore' } }, (task) => mod.log(`Exploring: ${task.title}`))
 ```
 
-A listener that throws shows the error toast `The <method> listener failed`, such as `The onReply listener failed`. `dispose()` on the `Disposable` stops the listener.
+A listener that throws shows the error toast `The <method> listener failed`, such as `The onReply listener failed`. `remove()` on the `Subscription` stops the listener.
 
 ### Give a listener time
 
@@ -170,8 +172,8 @@ An `on` listener that passes its time stops quietly. A `before` listener that pa
 ### Change what happens
 
 ```ts
-part.before<Event>(listener: (payload, time) => Answer | void, options?: { timeoutMs?: number; onFailure?: 'pass' | 'refuse' }): Disposable
-part.before<Event>(matcher: Matcher<payload>, listener, options?): Disposable
+part.before<Event>(listener: (payload, time) => Answer | void, options?: { timeoutMs?: number; onFailure?: 'pass' | 'refuse' }): Subscription
+part.before<Event>(matcher: Matcher<payload>, listener, options?): Subscription
 ```
 
 Each `before` method, such as `beforeToolCall`, runs `listener` just before something happens, and its answer changes or refuses it. Returning nothing lets it happen as it was. Each part except `sessions` has every `before` method, and hears what is about to happen inside it, the way `on` methods do.
@@ -277,7 +279,7 @@ mod.use(slashCommand({
     const task = await sessions.current.startTask({ prompt: 'Summarize README.md in one line.', title: 'Summarize the README', agentType: 'Explore' })
     task.onTaskEnd(async (ended) => {
       const [answer] = await ended.owner.messages({ last: 1 })
-      if (answer?.type === Reply) mod.ui.toast(answer.text)
+      if (answer?.type === Reply) mod.toast(answer.text)
     })
     return 'Summarizing the README.'
   },
@@ -300,14 +302,14 @@ type MessageOf<Type> = {
 }
 ```
 
-- `id` names the transcript row the message is in. When one row holds several messages, such as a reply with its tool calls, each `id` ends in `:<n>`. `mod.ui.scroll({ to: { requestId: message.id.split(':')[0] } })` scrolls to the message's row ([ui.md](ui.md#scrolling)).
+- `id` names the transcript row the message is in. When one row holds several messages, such as a reply with its tool calls, each `id` ends in `:<n>`. `sessions.current.scrollTo(message)` scrolls to the message's row ([ui.md](ui.md#the-conversations-rows)).
 - `at` is its ISO time. `session` is the session's id, and `context` the number of the context it is in, from 1.
 - `turn` is the `id` of the prompt that opened its turn. A task's message names its owner's turn. A message before the first prompt has none.
 - `task` is the id of the task whose message it is. A message of the session itself has none.
 
 | Type | Constant | Its own fields |
 | --- | --- | --- |
-| `'prompt'` | `Prompt` | `text`, `from`: the prompt that opens a turn. A command Claude Code sends as a prompt reads as typed, such as `/review 12`. |
+| `'prompt'` | `Prompt` | `text`, `from`: the prompt that opens a turn. A command Claude Code sends as a prompt reads as typed, such as `/review 12`. A command a mod runs, such as cmod's `/reload-plugins`, is no prompt, and `commands.onRun` hears it. |
 | `'note'` | `Note` | `text`, `from`: text Claude reads that is not a prompt, such as a mod's note or a task's notification. |
 | `'reply'` | `Reply` | `text`: what Claude said. |
 | `'toolCall'` | `ToolCall` | `callId`, `name`, `input`, `cwd`, `files`: a tool Claude called, the folder it called it in, and the files it reads and changes. |
@@ -396,7 +398,7 @@ type Task = {
 
 ```ts
 sessions.current.onTurnEnd((turn) => {
-  if (turn.failure !== undefined) mod.ui.toast.error(`Claude stopped: ${turn.failure.text}`)
+  if (turn.failure !== undefined) mod.toast.error(`Claude stopped: ${turn.failure.text}`)
 })
 ```
 - `abort()` stops a turn while it runs, a task's turn included, and needs the `prompt` permission. It throws on a turn that has ended. Claude Code shows no marker, so a mod that aborts tells the person with a toast.

package/docs/testing.md

@@ -19,7 +19,7 @@ test('/todo adds the item to the project list', async () => {
 })
 ```
 
-Assert what a person or Claude sees: `tested.lines(...)`, `tested.shown`, `tested.state`, and what `tested.raise...`, `tested.type(...)`, and `tested.callTool(...)` return.
+Assert what a person or Claude sees: `tested.shown.page.lines()`, `tested.lines(...)`, `tested.shown`, `tested.state`, and what `tested.raise...`, `tested.type(...)`, and `tested.callTool(...)` return.
 
 ## TestOptions
 
@@ -46,7 +46,7 @@ type TestOptions<State, Options> = {
 | `scope` | `'project'` makes the mod a project plugin, in `<projectRoot>/.claude/skills/<name>` | `'user'` |
 | `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.` |
+| `dependencies` | The methods other mods answer with | none: every call fails with `<name> is not installed. Install it in Plugins.` |
 | `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` |
@@ -68,14 +68,14 @@ type TestedMod<State> = {
   compact(): Promise<void>
   startSession(start: { source: 'startup' | 'resume' | 'clear' | 'fork'; id?: string }): Promise<void>
   startTask(task: { title: string; agentType?: string; model?: string; openedBy?: string; parent?: string }): Promise<string>
-  lines(paneId: string): Promise<string[]>
-  lines(place, props, requestId?): Promise<string[]>
+  lines(area: Area, props?: { columns?: number }): Promise<string[]>
+  lines(kind: Row, props, requestId?): Promise<string[]>
   type(line: string): Promise<CommandReply>
+  hotkey(name: string): Promise<void>
   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, type?: 'submit' | 'change'): Promise<void>
-  select(paneId: string, key: string, value: string): Promise<void>
+  press(area: Area, key: string): Promise<void>
   moveTo(projectRoot: string, cwd?: string): Promise<void>
+  readonly api: { [method: string]: (input?: unknown) => Promise<unknown> }
   readonly state: Readonly<State>
   readonly calls: readonly TestCall[]
   readonly fakes: Fakes
@@ -85,7 +85,7 @@ type TestedMod<State> = {
 
 ### start
 
-Starts the mod: loads its state, runs `setup`, and adds its listeners, panes, and jobs. `raise`, `fire`, `lines`, `type`, `callTool`, `press`, `input`, `select`, and `moveTo` start the mod first, so a test calls `start` only before it reads `state` or `shown` with nothing else to run. It rejects with the reason when the mod does not start.
+Starts the mod: loads its state, runs `setup`, and adds its listeners, pages, panes, widgets, and jobs. `raise`, `fire`, `lines`, `type`, `hotkey`, `callTool`, `press`, `moveTo`, and `api` start the mod first, so a test calls `start` only before it reads `state` or `shown` with nothing else to run. It rejects with the reason when the mod does not start.
 
 ### raise
 
@@ -121,8 +121,8 @@ fire(event: 'tool.check' | 'prompt.context' | 'cmod.call' | 'ui.render' | 'ui.sc
 
 - `fire('tool.check', { tool: 'Edit', input: { … }, tool_use_id: 'toolu_1' }, { decision: 'allow' })` asks the mod's `permissions` job and `beforePermissionCheck` listeners about any call. `below` is Claude Code's own verdict.
 - `fire('prompt.context', { blocks: [] }, { blocks: [] })` starts the conversation's context, which gives each `prompt` job its first block.
-- `fire('cmod.call', { to, method, input })` calls a method of the mod's `api`, as another mod's `mod.dependencies` does, and returns `{ value }` with what the method returned, or `{ deny }` with the reason it failed.
-- `ui.render`, `ui.scroll`, and `ui.close` are what `lines` and a pane's own events raise. `lines` is the way to draw.
+- `fire('cmod.call', { to, method, input })` calls a method `setup` returned, as another mod's `mod.dependencies` does, and returns `{ value }` with what the method returned, or `{ deny }` with the reason it failed. `tested.api.<method>(input)` does the same and resolves the value, or rejects with the reason.
+- `ui.render`, `ui.scroll`, and `ui.close` are what `lines` and a pane's own events raise. `shown.pane.lines()` and `lines` are the way to draw.
 
 ```ts
 expect(await tested.fire('cmod.call', { to: 'safe-delete', method: 'restore', input: { path: 'a.ts' } })).toEqual({ value: { restored: true } })
@@ -210,30 +210,41 @@ A `before` listener on the current session answers what `raise` asks, such as `t
 
 ### 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.
+- `shown.page.lines()` draws the page the mod shows in the Sidebar now, and `shown.pane.lines()` the pane it shows now, and each returns its rows of text. Each rejects when the mod shows none, such as `No pane of notes shows. Open one with pane.open(), from a slash command, a hotkey, or setup.` A page gets `params`, `isFocused`, and `columns`, 80 unless `lines({ columns })` gives another. A pane gets `params`, `title`, `isFocused`, true once an `open` or `toggle` with `{ focus: true }` opened it, `bodyColumns`, `placement: 'dock'`, `scroll: { offset: 0, bodyRows: 24 }`, and `view: {}`. `shown.page.id` and `shown.pane.id` name what shows, and `params` holds its params.
 - 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(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.
+- `lines(area)` draws the mod's widgets in that area, in the rows the person would see, and returns them. A new widget is in the first row of its first area. A layout given in `files` as `/test/home/.local/share/cmod/widgets.json` places the widgets another way. `{ columns }` sets the row's width, 80 by default. `lines(TurnEnd)` draws under the last turn that ended, and rejects when none has: end one with `tested.endTurn()` first.
+- `lines(kind, props, requestId?)` draws the mod's style of that kind with `props` and returns its rows. `Default` draws a plain listing of the props it gets, so a test sees what the style changed. Draw `Reply` with a reply's `text` to test a markdown style. Draws that pass one `requestId` grow one streamed reply.
 
 ```ts
 import { expect, test } from 'bun:test'
-import type { RenderPropsOf } from 'claude-code'
-import { AbovePrompt, Prompt } from '../node_modules/@cmodjs/core/mod.js'
+import { BelowPrompt, Prompt } from '../node_modules/@cmodjs/core/mod.js'
 import { testMod } from '../node_modules/@cmodjs/core/testing.js'
-import { hints } from '../src/mod.js'
+import { prompts } 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', async () => {
-  const tested = testMod(hints)
+test('the prompt count shows below the prompt', async () => {
+  const tested = testMod(prompts)
   await tested.add({ type: Prompt, text: 'hello' })
 
-  expect(await tested.lines(AbovePrompt, band)).toContain('Prompts: 1')
+  expect(await tested.lines(BelowPrompt)).toEqual(['Prompts: 1'])
 })
 ```
 
 ### type
 
-`type('/<command> <arguments>')` runs a slash command as the person types it and returns its reply, `{ text?, note? }`. The mod's `commands.beforeRun` listeners hear it first, so `type('/compact')` tests a listener that refuses a built-in. It rejects a line that does not start with `/`, and a command nothing in the mod answers.
+`type('/<command> <arguments>')` runs a slash command as the person types it and returns its reply, `{ text?, note? }`. The mod's `commands.beforeRun` listeners hear it first, so `type('/compact')` tests a listener that refuses a built-in. It rejects a line that does not start with `/`, a command nothing in the mod answers, and a command of the mod that calls `next(e)` on to Claude Code's own run of it, which shows the person `<mod> registered /<command> but no command.run hook answered it`. `hotkey` rejects the same way.
+
+### hotkey
+
+`hotkey(name)` presses the hotkey `defineMod` declared under `name`, as the person pressing its combo does, and awaits its listeners. A page it opens shows as `shown.page`. It rejects a name the mod does not declare.
+
+```ts
+test('the hotkey shows the prompt count in the Sidebar', async () => {
+  const tested = testMod(myMod)
+  await tested.add({ type: Prompt, text: 'hello' })
+  await tested.hotkey('toggle')
+  expect(await tested.shown.page.lines()).toEqual(['Prompts this session: 1'])
+})
+```
 
 ### callTool
 
@@ -241,17 +252,18 @@ test('the band shows the prompt count', async () => {
 
 ### press, input, and select
 
-`press`, `input`, and `select` act on an element of an open pane as the person does, and await its handler. Each passes the handler the event Claude Code passes, with `component: 'Pane'`, `requestId` the pane's id, and `surface: 'terminal'`. Each rejects when the pane does not draw the element: `The pane "<pane>" of <mod> draws no <Element> with the key "<key>".`
+`shown.page` and `shown.pane` act on an element of what shows as the person does, and await its handler. Each rejects when it does not draw the element: `The pane "<pane>" of <mod> draws no <Element> with the key "<key>".`, or the same for a page.
 
-- `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 `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.
+- `press(key)` presses the `Button` whose `key` or `label` is `key`, and runs its `onPress`.
+- `press(key, link)` presses the link `link` in the `Markdown` whose `key` is `key`, and runs its `onLinkPress`.
+- `input(key, text)` types `text` into the `Input` whose `key` is `key` and presses Enter, which runs its `onSubmit`. With a third argument `'change'` it runs `onInput` instead, as one edit does.
+- `select(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.
+- `tested.press(area, key)` presses a `Button` one of the mod's widgets draws in that area, the way the person presses it in a row.
 
 ```ts
-await tested.input('history', 'search', 'deploy')
-await tested.select('history', 'agent', 'explorer')
-expect(await tested.lines('history')).toContain('deploy by explorer')
+await tested.shown.page.input('search', 'deploy')
+await tested.shown.page.select('agent', 'explorer')
+expect(await tested.shown.page.lines()).toContain('deploy by explorer')
 ```
 
 ### moveTo
@@ -276,7 +288,7 @@ type Fakes = {
   settings: { read? }
   config: { list? }
   command: { list?, run? }
-  ui: { ask?, open?, scroll? }
+  ui: { ask?, open?, scroll?, copy?, focus? }
   session: { messages?, append? }
   prompt: { submit? }
   model: { complete? }
@@ -294,6 +306,7 @@ Set a fake to answer a call:
 - `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.
+- `clipboard.write(text)` reaches `ui.copy({ text })`, so a test keeps each copied text with a fake that answers `{ isCopied: true }`.
 - `clock.now()` answers the real time unless a fake gives its own, so a test of a deadline can move time. `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 })`.
@@ -333,18 +346,28 @@ type Shown = {
   readonly prompts: string[]
   readonly logs: string[]
   readonly debug: string[]
-  readonly statuses: (string | undefined)[]
   readonly openPanes: Set<string>
   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 }[]
+  readonly page: ShownPart
+  readonly pane: ShownPart
+}
+
+type ShownPart = {
+  readonly id: string
+  readonly params: unknown
+  lines(options?: { columns?: number }): Promise<string[]>
+  press(key: string, link?: string): Promise<void>
+  input(key: string, text: string, type?: 'submit' | 'change'): Promise<void>
+  select(key: string, value: string): Promise<void>
 }
 
 type ShownToast = { readonly type: ToastType; readonly message: string; readonly description?: string }
 ```
 
-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.
+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, 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 () => {