@cmodjs/core 3.0.0 → 4.0.0

package/src/jobs/prompt.ts

@@ -3,6 +3,7 @@ import type { Deadline } from '../runtime/deadline.js'
 import { engineOf } from '../runtime/engine.js'
 import { onStateChange } from '../runtime/state.js'
 import { modNote } from '../session/context/turn/message/note.js'
+import type { Subscription } from '../utils/subscription.js'
 import { listed, messageOf } from '../utils/text.js'
 import { callEffects, type Call } from '../utils/call-effects.js'
 import { matchTarget, targetOf, type Target } from './permissions/match-target.js'
@@ -18,13 +19,13 @@ type PromptOptions<State extends object> = {
 
 const deadline: Deadline = { ms: 5000, job: 'prompt' }
 
-export function prompt<State extends object = Record<never, never>>({ name, prompt: text, after }: PromptOptions<State>): Job<void, State> {
+export function prompt<State extends object = Record<never, never>>({ name, prompt: text, after }: PromptOptions<State>): Job<Subscription, State> {
   if (name.trim() === '') throw new Error('prompt: give the block a name. Claude reads the text under it.')
   const targets = after === undefined ? [] : Array.isArray(after) ? after : [after]
   for (const target of targets) targetOf(target)
 
   return (job) => {
-    job.reserveName('prompt', name, `prompt: ${job.mod.name} adds the name "${name}" two times. Give each prompt its own name.`)
+    const reserved = job.reserveName('prompt', name, `prompt: ${job.mod.name} adds the name "${name}" two times. Give each prompt its own name.`)
 
     const log = (reason: string) => job.mod.log(`prompt "${name}" added nothing: ${reason}`)
     const textFor = async (input: PromptInput) => {
@@ -42,29 +43,30 @@ export function prompt<State extends object = Record<never, never>>({ name, prom
       return value === undefined ? undefined : `# ${name}\n${value}`
     }
 
-    if (targets.length > 0) {
-      addAfterCalls(job, targets, headedText, log)
-      job.announce(`the ${name} prompt after ${listed(targets.map(targetWords))}`)
-    } else {
-      addKeptCurrent(job, name, () => textFor({}), log)
-      job.announce(`the ${name} prompt`)
+    job.announce(targets.length > 0 ? `the ${name} prompt after ${listed(targets.map(targetWords))}` : `the ${name} prompt`)
+    const added = targets.length > 0 ? addAfterCalls(job, targets, headedText, log) : addKeptCurrent(job, name, () => textFor({}), log)
+    return {
+      remove() {
+        added.remove()
+        reserved.remove()
+      },
     }
   }
 }
 
-function addKeptCurrent<State extends object>(job: JobContext<State>, name: string, textFor: () => Promise<string | undefined>, log: (reason: string) => void): void {
+function addKeptCurrent<State extends object>(job: JobContext<State>, name: string, textFor: () => Promise<string | undefined>, log: (reason: string) => void): Subscription {
   const { claude, router } = engineOf(job.mod)
   let given: string | undefined
   let hasStarted = false
   let isQueued = false
   let updates = Promise.resolve()
 
-  router.add('classic.SessionStart', (e, next) => {
+  const starting = router.add('classic.SessionStart', (e, next) => {
     hasStarted = e.source === 'resume' || e.source === 'compact'
     if (!hasStarted) given = undefined
     return next(e)
   })
-  router.add('prompt.context', async (e, next) => {
+  const adding = router.add('prompt.context', async (e, next) => {
     const below = await next(e)
     hasStarted = true
     if (below.blocks.some((block) => block.name === name)) {
@@ -85,15 +87,22 @@ function addKeptCurrent<State extends object>(job: JobContext<State>, name: stri
       if (added.deny !== undefined) log(`Claude Code refused the new text: ${added.deny}`)
     })
   }
-  onStateChange(job.mod.state, () => {
+  const following = onStateChange(job.mod.state, () => {
     if (isQueued) return
     isQueued = true
     updates = updates.then(update).catch((error: unknown) => log(messageOf(error)))
   })
+  return {
+    remove() {
+      starting.remove()
+      adding.remove()
+      following.remove()
+    },
+  }
 }
 
-function addAfterCalls<State extends object>(job: JobContext<State>, targets: Target[], textFor: (input: PromptInput) => Promise<string | undefined>, log: (reason: string) => void): void {
-  afterCall(
+function addAfterCalls<State extends object>(job: JobContext<State>, targets: Target[], textFor: (input: PromptInput) => Promise<string | undefined>, log: (reason: string) => void): Subscription {
+  return afterCall(
     job,
     async (use, workspace) => {
       const effects = callEffects(use, workspace)

package/src/jobs/schedule.ts

@@ -1,12 +1,13 @@
 import type { Job } from '../mod.js'
 import { onStateChange } from '../runtime/state.js'
 import { engineOf } from '../runtime/engine.js'
+import type { Subscription } from '../utils/subscription.js'
 
 export type ScheduledPrompt = { readonly cron: string; readonly prompt: string }
 
 const scheduleCounts = new WeakMap<object, number>()
 
-export function schedule<State extends object = Record<never, never>>(entry: ScheduledPrompt | ((state: State) => ScheduledPrompt | undefined)): Job<void, State> {
+export function schedule<State extends object = Record<never, never>>(entry: ScheduledPrompt | ((state: State) => ScheduledPrompt | undefined)): Job<Subscription, State> {
   if (typeof entry !== 'function') checked(entry)
 
   return (job) => {
@@ -51,12 +52,25 @@ export function schedule<State extends object = Record<never, never>>(entry: Sch
       .then((left) => (typeof left === 'string' ? remove(left) : undefined))
       .then(update)
       .catch((error: unknown) => report('failed', error))
-    onStateChange(mod.state, () => {
+    const following = onStateChange(mod.state, () => {
       if (isQueued) return
       isQueued = true
       updates = updates.then(update).catch((error: unknown) => report('failed', error))
     })
     job.announce(typeof entry === 'function' ? 'a schedule from its state' : `a schedule at ${entry.cron}`)
+    return {
+      remove() {
+        following.remove()
+        updates = updates
+          .then(async () => {
+            if (current === undefined) return
+            const { id } = current
+            current = undefined
+            await remove(id)
+          })
+          .catch((error: unknown) => report('failed', error))
+      },
+    }
   }
 }
 

package/src/jobs/slash-command.ts

@@ -1,5 +1,5 @@
 import type { CommandRunResult } from 'claude-code'
-import type { Disposable, Job, Mod } from '../mod.js'
+import type { Job, Mod } from '../mod.js'
 import { parse } from '../vendor.js'
 import type { Deadline } from '../runtime/deadline.js'
 import { engineOf } from '../runtime/engine.js'
@@ -9,6 +9,8 @@ import { withinDeadline } from './context.js'
 
 export type CommandReply = string | { text?: string; note?: string } | undefined
 
+export type SlashCommand = { readonly name: string; remove(): void }
+
 const deadline: Deadline = { ms: 30000, job: 'slashCommand' }
 
 const commandName = /^[A-Za-z0-9_-]{1,64}$/
@@ -19,11 +21,11 @@ export function slashCommand<State extends object = Record<never, never>>(option
   readonly argumentHint?: string
   readonly immediate?: true
   readonly reply: (input: { args: string; positionals: string[] }, mod: Mod<State>) => CommandReply | void | Promise<CommandReply | void>
-}): Job<Disposable, State> {
+}): Job<SlashCommand, State> {
   const { name, description, argumentHint, immediate, reply } = options
   return (job) => {
     const { mod, announce, reserveName } = job
-    const { claude, router, report } = engineOf(mod)
+    const { claude, router, report, answerInput } = engineOf(mod)
     if (!commandName.test(name)) throw new Error(`${mod.name}: "${name}" is not a slash command name. Use 1 to 64 letters, digits, "_", or "-", without the slash.`)
     const reserved = reserveName('slashCommand', name, `${mod.name}: the slash command /${name} is already added. Give each slashCommand its own name.`)
 
@@ -41,15 +43,16 @@ export function slashCommand<State extends object = Record<never, never>>(option
     const answering = router.add('command.run', async (e, next) => {
       if (e.command !== registered) return next(e)
       try {
-        return answerOf(mod.name, await withinDeadline(mod, deadline, `/${name}`, () => reply({ args: e.args, positionals: splitWords(e.args) }, mod)))
+        return await answerInput(async () => answerOf(mod.name, await withinDeadline(mod, deadline, `/${name}`, () => reply({ args: e.args, positionals: splitWords(e.args) }, mod))), () => next(e))
       } catch (error) {
         return { text: `/${name} failed: ${oneLine(error)}` }
       }
     })
     return {
-      dispose() {
-        answering.dispose()
-        reserved.dispose()
+      name,
+      remove() {
+        answering.remove()
+        reserved.remove()
       },
     }
   }

package/src/jobs/tool.ts

@@ -1,5 +1,5 @@
 import type { FromSchema, JSONSchema } from 'json-schema-to-ts'
-import type { Disposable, Job, Mod } from '../mod.js'
+import type { Job, Mod } from '../mod.js'
 import { Validator } from '../vendor.js'
 import { toolDeadline } from '../runtime/deadline.js'
 import { engineOf } from '../runtime/engine.js'
@@ -9,12 +9,14 @@ import { withinDeadline } from './context.js'
 
 const toolName = /^[A-Za-z0-9_-]{1,64}$/
 
+export type Tool = { readonly name: string; remove(): void }
+
 export function tool<const Schema extends object = { type: 'object' }, State extends object = Record<never, never>>(options: {
   readonly name: string
   readonly description: string
   readonly inputSchema?: Schema
   readonly execute: (input: Schema extends JSONSchema ? FromSchema<Schema> : never, mod: Mod<State>) => unknown
-}): Job<Disposable & { readonly name: string }, State> {
+}): Job<Tool, State> {
   const { name, description, inputSchema, execute } = options
   return (job) => {
     const { mod, announce, reserveName } = job
@@ -50,9 +52,9 @@ export function tool<const Schema extends object = { type: 'object' }, State ext
     })
     return {
       name: `mcp__${claude.plugin.name}__${name}`,
-      dispose() {
-        answering.dispose()
-        named.dispose()
+      remove() {
+        answering.remove()
+        named.remove()
       },
     }
   }

package/src/mod.ts

@@ -9,7 +9,6 @@ import type {
   ModelCompleteOptions,
   ModelCompleteRequest,
   ModelCompleteResult,
-  PaneOpenArgs,
   ProcessRunInit,
   ProcessRunResult,
   ProcessSpawnChunk,
@@ -17,20 +16,24 @@ import type {
   ProcessSpawnResult,
   RenderElement,
   Settings,
-  UiScrollArgs,
-  UiScrollResult,
 } from 'claude-code'
-import type { Step } from './installer.js'
+import { checkHotkeys, type Hotkey, type HotkeyInit, type Hotkeys } from './hotkeys.js'
+import { checkSteps, type Step } from './installer.js'
 import { checkOptions, type Option, type Options, type OptionValues } from './options.js'
 import { bound } from './runtime/bound.js'
 import { Mod as modSender } from './session/context/turn/message/sender.js'
 import { sessionEvents, type BeforeMethod, type CommandRun, type CommandRunAnswer, type OnMethod, type OnMethods, type Sessions } from './session/session.js'
-import type { Pane } from './ui/define-pane.js'
-import type { Place, PlaceProps } from './ui/places.js'
-import type { Disposable } from './utils/disposable.js'
+import type { Widget, WidgetInit } from './ui/areas.js'
+import type { Page, PageInit, Pane, PaneInit } from './ui/panes.js'
+import type { Kind, Style, StyleInit } from './ui/styles.js'
 import type { Matcher } from './utils/matcher.js'
+import type { Subscription } from './utils/subscription.js'
 
-export type { Disposable }
+export type { Subscription }
+
+export type Timer = { readonly isRunning: boolean; stop(): void }
+
+export type Reservation = { remove(): void }
 
 export type ToastId = string | number
 
@@ -56,15 +59,6 @@ export type Toast = {
   dismiss(id?: ToastId): void
 }
 
-export type PaneHandle = {
-  open(options?: Readonly<Pick<PaneOpenArgs, 'focus'>>): Promise<void>
-  close(): Promise<void>
-  toggle(options?: Readonly<Pick<PaneOpenArgs, 'focus'>>): Promise<void>
-  readonly isOpen: boolean
-  readonly isShown: boolean
-  readonly isFocused: boolean
-}
-
 export type Metadata = Readonly<Record<string, string>>
 
 export type FileMatch = {
@@ -138,8 +132,8 @@ export type Imports = {
     readonly user: SettingsFile
     readonly project: SettingsFile
     readonly local: SettingsFile
-    beforeFileChange(listener: SettingsFileChangeListener): Disposable
-    beforeFileChange(matcher: Matcher<SettingsFileChange>, listener: SettingsFileChangeListener): Disposable
+    beforeFileChange(listener: SettingsFileChangeListener): Subscription
+    beforeFileChange(matcher: Matcher<SettingsFileChange>, listener: SettingsFileChangeListener): Subscription
   }
   readonly model: { complete(request: ModelCompleteRequest, options?: ModelCompleteOptions): Promise<ModelCompleteResult> }
   readonly fs: {
@@ -149,7 +143,7 @@ export type Imports = {
     find(glob: string | readonly string[]): Promise<readonly FileMatch[]>
     list(path?: string): Promise<Entry[]>
     stat(path: string, options?: FsStatOptions): Promise<Stat>
-    onChange(matcher: { readonly path: string | readonly string[] }, listener: (change: FileChange) => unknown): Disposable
+    onChange(matcher: { readonly path: string | readonly string[] }, listener: (change: FileChange) => unknown): Subscription
   }
   readonly metadata: {
     read(path: string): Promise<Metadata>
@@ -160,6 +154,7 @@ export type Imports = {
     spawn(argv: readonly string[], init?: Omit<ProcessSpawnRequest, 'argv'>): HookStream<ProcessSpawnChunk, ProcessSpawnResult>
   }
   readonly http: { fetch(url: string, init?: HttpInit): Promise<HttpResponse> }
+  readonly clipboard: { write(text: string): Promise<void> }
 }
 
 export const sessions: Imports['sessions'] = {
@@ -168,7 +163,7 @@ export const sessions: Imports['sessions'] = {
   },
   list: (options) => bound().sessions.list(options),
   search: (text, matcher, options) => bound().sessions.search(text, matcher, options),
-  ...(Object.fromEntries(Object.keys(sessionEvents).map((named) => [`on${named}`, (...args: unknown[]) => (bound().sessions[`on${named}` as keyof OnMethods] as (...each: unknown[]) => Disposable)(...args)])) as OnMethods),
+  ...(Object.fromEntries(Object.keys(sessionEvents).map((named) => [`on${named}`, (...args: unknown[]) => (bound().sessions[`on${named}` as keyof OnMethods] as (...each: unknown[]) => Subscription)(...args)])) as OnMethods),
 }
 
 export const settings: Imports['settings'] = {
@@ -181,8 +176,8 @@ export const settings: Imports['settings'] = {
 export const commands: Imports['commands'] = {
   list: () => bound().commands.list(),
   run: (name, args) => bound().commands.run(name, args),
-  beforeRun: ((...args: never[]) => (bound().commands.beforeRun as (...each: never[]) => Disposable)(...args)) as Imports['commands']['beforeRun'],
-  onRun: ((...args: never[]) => (bound().commands.onRun as (...each: never[]) => Disposable)(...args)) as Imports['commands']['onRun'],
+  beforeRun: ((...args: never[]) => (bound().commands.beforeRun as (...each: never[]) => Subscription)(...args)) as Imports['commands']['beforeRun'],
+  onRun: ((...args: never[]) => (bound().commands.onRun as (...each: never[]) => Subscription)(...args)) as Imports['commands']['onRun'],
 }
 
 export const config: Imports['config'] = {
@@ -217,30 +212,32 @@ export const http: Imports['http'] = {
   fetch: (url, init) => bound().http.fetch(url, init),
 }
 
-export type Mod<State extends object = Record<never, never>, Declared extends Options = Options> = {
+export const clipboard: Imports['clipboard'] = {
+  write: (text) => bound().clipboard.write(text),
+}
+
+export type Mod<State extends object = Record<never, never>, Declared extends Options = Options, Keys extends Hotkeys = Hotkeys> = {
   readonly name: string
   readonly folder: string
   readonly dataFolder: string
   readonly state: Readonly<State>
   readonly options: OptionValues<Declared>
   readonly permissions: Permissions
-  every(ms: number, listener: () => unknown): Disposable
-  after(ms: number, listener: () => unknown): Disposable
+  readonly hotkeys: { readonly [Key in keyof Keys]: Hotkey }
+  every(ms: number, listener: () => unknown): Timer
+  after(ms: number, listener: () => unknown): Timer
   use<Handle>(job: Job<Handle, State>): Handle
   log(text: string, options?: { readonly to?: 'debug' | 'transcript' }): void
-  readonly ui: {
-    pane(pane: Pane<State>): PaneHandle
-    render<P extends Place>(place: P, Component: (props: PlaceProps<P>) => RenderElement): Disposable
-    readonly toast: Toast
-    ask(question: string, options?: readonly string[] | AskOptions): Promise<string>
-    copy(text: string): Promise<void>
-    scroll(args: UiScrollArgs): Promise<UiScrollResult>
-    notice(callId: string, text: string | undefined): void
-  }
+  readonly panes: { add<Params = undefined>(pane: PaneInit<State, Params>): Pane<Params> }
+  readonly sidebar: { add<Params = undefined>(page: PageInit<State, Params>): Page<Params> }
   readonly settings: {
-    page(page: Pane<State>): void
-    open(pageId?: string): Promise<void>
+    add<Params = undefined>(page: PageInit<State, Params>): Page<Params>
+    open(): Promise<void>
   }
+  readonly widgets: { add(widget: WidgetInit<State>): Widget }
+  readonly styles: { add<K extends Kind>(style: StyleInit<K, State>): Style }
+  readonly toast: Toast
+  ask(question: string, options?: readonly string[] | AskOptions): Promise<string>
   readonly dependencies: CmodDependencies
 }
 
@@ -253,36 +250,51 @@ type StateGroups = {
   readonly global?: object
 }
 
-type Api<Contract, State extends object> = {
-  readonly [Method in keyof Contract]: Contract[Method] extends (input: infer Input) => infer Result ? (input: Input, mod: Mod<State>) => Result | Awaited<Result> : never
-}
+type AnyApi = { readonly [method: string]: (input: never) => unknown } | void
+
+type Api<Name extends string> = 0 extends 1 & CmodDependencies
+  ? AnyApi
+  : Name extends keyof CmodDependencies
+    ? { readonly [Method in keyof CmodDependencies[Name]]: CmodDependencies[Name][Method] extends (input: infer Input) => infer Result ? (input: Input) => Result | Awaited<Result> : never }
+    : AnyApi
 
-export type ModDefinition<State extends StateGroups = Record<never, never>, Name extends string = string, Declared extends Options = Record<never, Option>> = {
+export type ModDefinition<State extends StateGroups = Record<never, never>, Name extends string = string, Declared extends Options = Record<never, Option>, Keys extends Hotkeys = Record<never, HotkeyInit>> = {
   readonly name: Name
   readonly state?: State
   readonly options?: Declared
-  readonly api?: Name extends keyof CmodDependencies ? Api<CmodDependencies[Name], State> : { readonly [method: string]: (input: never, mod: Mod<State>) => unknown }
+  readonly hotkeys?: Keys
   readonly installer?: readonly Step<State>[]
-  setup(mod: Mod<State, Declared>): unknown
+  setup(mod: Mod<State, Declared, Keys>): Api<Name> | Promise<Api<Name>>
 }
 
 export type JobContext<State extends object = Record<never, never>> = {
   readonly mod: Mod<State>
   announce(feature: string): void
-  reserveName(type: string, name: string, taken: string): Disposable
+  reserveName(type: string, name: string, taken: string): Reservation
 }
 
 export type Job<Handle, State extends object = Record<never, never>> = (context: JobContext<State>) => Handle
 
-export function defineMod<State extends StateGroups = Record<never, never>, Name extends string = string, const Declared extends Options = Record<never, Option>>(definition: ModDefinition<State, Name, Declared>): ModDefinition<State, Name, Declared> {
+export function defineMod<State extends StateGroups = Record<never, never>, Name extends string = string, const Declared extends Options = Record<never, Option>, const Keys extends Hotkeys = Record<never, HotkeyInit>>(
+  definition: ModDefinition<State, Name, Declared, Keys>,
+): ModDefinition<State, Name, Declared, Keys> {
   if (definition.name.trim() === '') throw new Error('defineMod: the mod needs a name, such as the name in .claude-plugin/plugin.json.')
   if (definition.options !== undefined) checkOptions(definition.name, definition.options)
+  if (definition.hotkeys !== undefined) checkHotkeys(definition.name, definition.hotkeys)
+  if (definition.installer !== undefined) checkSteps(definition.name, definition.installer)
   return definition
 }
 
 export type { Matcher } from './utils/matcher.js'
-export type { Place, PlaceProps } from './ui/places.js'
-export { AbovePrompt, AskUserQuestion, CommandOutput, PromptHint, SessionMode, Spinner, ToolGroup, ToolProgress, TurnDuration } from './ui/places.js'
+export type { Combo, Hotkey, HotkeyInit, Key } from './hotkeys.js'
+export type { OpenOptions, Page, PageInit, PageProps, Pane, PaneInit, PaneProps, ScrollOptions, ScrollTarget } from './ui/panes.js'
+export type { Kind, Row, Style, StyleInit, StyleProps } from './ui/styles.js'
+export type { Block } from './ui/markdown.js'
+export { AskUserQuestion, CommandOutput, ToolGroup, ToolProgress } from './ui/styles.js'
+export { AbovePrompt, BelowPrompt, Dashboard, TurnEnd, Working, type Area, type Widget, type WidgetContext, type WidgetInit } from './ui/areas.js'
+export type { Step } from './installer.js'
+export type { SlashCommand } from './jobs/slash-command.js'
+export type { Tool } from './jobs/tool.js'
 export { Session, type AnswerOptions, type BeforeMethods, type Surface, type Listener, type ListenerTime, type OnMethods, type ReadOptions, type RecordPart, type Refusal, type SearchOptions, type SessionScope, type SessionSend, type Sessions, type CurrentSession, type Placement, type ProjectSetup, type SessionStartAsked, type SessionStarted, type SessionEnded, type ModelChange, type CwdChange, type DirectoryAdd, type Worktree, type Notification, type Elicitation, type ElicitationResponse, type McpServer, type PermissionUpdate, type PermissionCheck, type PermissionRequest, type PermissionDenial, type BatchedCall, type ToolBatch, type Todo, type ReplyDisplay, type TaskOwner, type TaskStartArgs, type ToolCallArgs, type Usage, type CommandRun, type CommandRunAnswer } from './session/session.js'
 export type { Context } from './session/context/context.js'
 export type { Turn } from './session/context/turn/turn.js'

package/src/records.ts

@@ -1,3 +1,4 @@
+import { checkHotkeys, type HotkeyInit, type Hotkeys } from './hotkeys.js'
 import { listed, messageOf } from './utils/text.js'
 
 export type InstallRecord = {
@@ -15,7 +16,7 @@ export type Steps = {
   install?: string
   uninstall?: string
   program?: string
-  keys?: Readonly<Record<string, string>>
+  hotkeys?: Hotkeys
   permissions?: readonly string[]
 }
 
@@ -39,7 +40,7 @@ export type ReadFile = (path: string) => Promise<string | undefined>
 export type RunnerEvent =
   | { type: 'progress'; done: number; total: number; label: string }
   | { type: 'log'; text: string }
-  | { type: 'needs-consent'; sha256: string; install: string; uninstall: string; keys: string; permissions: readonly string[] }
+  | { type: 'needs-consent'; sha256: string; install: string; uninstall: string; hotkeys: string; permissions: readonly string[] }
   | { type: 'done'; name: string; version?: string }
   | { type: 'missing'; name: string }
   | { type: 'retries'; when: 'changed' | 'later' }
@@ -139,7 +140,7 @@ export function readSteps(pkg: unknown): Steps | undefined {
     ...readCommand(steps, 'install'),
     ...readCommand(steps, 'uninstall'),
     ...(program === undefined ? {} : { program }),
-    ...readKeys(steps['keys']),
+    ...readHotkeys(steps['hotkeys']),
     ...(permissions.length === 0 ? {} : { permissions }),
   }
 }
@@ -173,6 +174,12 @@ function readPermissions(steps: Record<string, unknown>): string[] {
   return items
 }
 
+export const grantFix = 'Turn it on in Settings.'
+
+export const installFix = 'Install it in Plugins.'
+
+export const secretFix = 'Set it in /config, where Claude Code keeps it in your keychain.'
+
 export function permissionWords(item: string): string {
   const split = item.indexOf(':')
   const target = item.slice(split + 1)
@@ -211,12 +218,6 @@ export function isSettingCovered(granted: Iterable<string>, path: string): boole
   return [...granted].some((each) => item === each || item.startsWith(`${each}.`))
 }
 
-export const settingsPagesMethod = 'cmod:settingsPages'
-
-export const changelogPage = 'changelog'
-
-export const openPageMethod = 'cmod:openPage'
-
 export const pendingStepsMethod = 'cmod:pendingSteps'
 
 export const finishStepsMethod = 'cmod:finishSteps'
@@ -239,6 +240,14 @@ export function consentPath(store: string): string {
   return `${store}/consent.json`
 }
 
+export function pluginsChangedPath(store: string): string {
+  return `${store}/plugins-changed`
+}
+
+export function widgetsPath(store: string): string {
+  return `${store}/widgets.json`
+}
+
 export function parseConsent(value: unknown, path: string): Record<string, string[]> {
   if (value === undefined) return Object.create(null)
   if (!isObject(value) || Object.values(value).some((items) => !Array.isArray(items) || items.some((item) => typeof item !== 'string'))) {
@@ -247,29 +256,35 @@ export function parseConsent(value: unknown, path: string): Record<string, strin
   return Object.assign(Object.create(null), value) as Record<string, string[]>
 }
 
-function readKeys(keys: unknown): Steps {
-  if (keys === undefined) return {}
-  if (!isObject(keys) || Object.keys(keys).length === 0) throw new Error('package.json "cmod.keys" must bind each key to a command, such as "keys": { "shift+tab": "/mode" }.')
-  const commands: Record<string, string> = {}
-  for (const [key, value] of Object.entries(keys)) {
-    const command = typeof value === 'string' ? /^\/([A-Za-z0-9][A-Za-z0-9._:-]*)$/.exec(value)?.[1] : undefined
-    if (key.trim() === '' || command === undefined) throw new Error(`package.json "cmod.keys" binds "${key}" to ${JSON.stringify(value)}. Bind each key to one of the mod's commands, such as "shift+tab": "/mode".`)
-    commands[key] = command
-  }
-  return { keys: commands }
+function readHotkeys(hotkeys: unknown): Steps {
+  if (hotkeys === undefined) return {}
+  const fix = 'cmod check writes it from the hotkeys defineMod declares, so run cmod check.'
+  if (!isObject(hotkeys) || !Object.values(hotkeys).every((each) => isObject(each) && typeof each['title'] === 'string' && typeof each['default'] === 'string')) throw new Error(`package.json "cmod.hotkeys" is not a map of hotkeys to their title and default combo. ${fix}`)
+  return { hotkeys: checkHotkeys('package.json "cmod"', hotkeys as Record<string, HotkeyInit>) }
 }
 
-export const coreVersion = '3.0.0'
+export const coreVersion = '4.0.0'
 
-export function oldestCmodFor(steps: Steps): string {
-  if (steps.permissions?.some((item) => item.startsWith('config:')) === true) return '1.6.0'
-  if (steps.permissions?.includes('tasks') === true) return '1.0.0'
-  if (steps.permissions !== undefined) return '0.2.0'
-  return Object.keys(steps.keys ?? {}).length > 0 ? '0.1.12' : '0.0.0'
+export function hotkeyCommand(mod: string, hotkey: string): string {
+  return `${mod}--${hotkey}`
 }
 
-export function keyWords(keys: Readonly<Record<string, string>> | undefined): string {
-  return listed(Object.entries(keys ?? {}).map(([key, command]) => `${key} to /${command}`))
+export function hotkeyBindings(mod: string, hotkeys: Hotkeys | undefined): Record<string, string> {
+  return Object.fromEntries(Object.entries(hotkeys ?? {}).map(([name, { default: combo }]) => [combo, hotkeyCommand(mod, name)]))
+}
+
+export function boundCombos(keybindings: unknown): Map<string, string> {
+  const blocks = isObject(keybindings) && Array.isArray(keybindings['bindings']) ? keybindings['bindings'] : []
+  const combos = new Map<string, string>()
+  for (const block of blocks) {
+    if (!isObject(block) || block['context'] !== 'Chat' || !isObject(block['bindings'])) continue
+    for (const [combo, action] of Object.entries(block['bindings'])) if (typeof action === 'string' && action.startsWith('command:')) combos.set(action.slice('command:'.length), combo)
+  }
+  return combos
+}
+
+export function hotkeyWords(hotkeys: Hotkeys | undefined): string {
+  return listed(Object.values(hotkeys ?? {}).map(({ title, default: combo }) => `${combo} to ${title}`))
 }
 
 function readCommand(steps: Record<string, unknown>, key: 'install' | 'uninstall'): Steps {
@@ -282,6 +297,10 @@ function readCommand(steps: Record<string, unknown>, key: 'install' | 'uninstall
   return { [key]: command }
 }
 
+export function bundleDefines(permissions: readonly string[]): Record<string, string> {
+  return permissions.includes('approve') ? {} : { 'globalThis.cmodWithoutApprove': 'true' }
+}
+
 export function scriptPaths(command: string): string[] {
   const words = command
     .split(/[\s;&|()<>]+/)
@@ -310,7 +329,7 @@ export async function scriptsSha256(steps: Steps, files: { read: ReadFile; list:
     steps.install ?? '',
     steps.uninstall ?? '',
     steps.program ?? '',
-    ...(steps.keys === undefined ? [] : [JSON.stringify(Object.entries(steps.keys).sort())]),
+    ...(steps.hotkeys === undefined ? [] : [JSON.stringify(Object.entries(steps.hotkeys).sort())]),
     ...(steps.permissions === undefined ? [] : [JSON.stringify([...steps.permissions].sort())]),
   ].join('\0')
   for (const folder of [...folders].sort()) {
@@ -332,7 +351,7 @@ export function formatEvent(event: RunnerEvent): string {
     case 'log':
       return `log ${event.text}`
     case 'needs-consent':
-      return `needs-consent ${[event.sha256, event.install, event.uninstall, event.keys, ...event.permissions].join('\t')}`
+      return `needs-consent ${[event.sha256, event.install, event.uninstall, event.hotkeys, ...event.permissions].join('\t')}`
     case 'done':
       return event.version === undefined ? `done ${event.name}` : `done ${event.name} ${event.version}`
     case 'missing':
@@ -349,8 +368,8 @@ export function parseEvent(line: string): RunnerEvent {
   if (progress !== null) return { type: 'progress', done: Number(progress[1]), total: Number(progress[2]), label: progress[3] ?? '' }
   const consent = /^needs-consent (\S+)\t([^\t]*)\t([^\t]*)(?:\t(.*))?$/.exec(line)
   if (consent !== null) {
-    const [keys = '', ...permissions] = (consent[4] ?? '').split('\t')
-    return { type: 'needs-consent', sha256: consent[1] as string, install: consent[2] as string, uninstall: consent[3] as string, keys, permissions: permissions.filter((item) => item !== '') }
+    const [hotkeys = '', ...permissions] = (consent[4] ?? '').split('\t')
+    return { type: 'needs-consent', sha256: consent[1] as string, install: consent[2] as string, uninstall: consent[3] as string, hotkeys, permissions: permissions.filter((item) => item !== '') }
   }
   const done = /^done (\S+)(?: (\S+))?$/.exec(line)
   if (done !== null) return { type: 'done', name: done[1] as string, ...(done[2] === undefined ? {} : { version: done[2] }) }

package/src/register.ts

@@ -21,7 +21,6 @@ async function startMod($: EngineInterface, eventInput: Frozen<Args<'session.sta
   const claude: Claude = {
     plugin: { name: $.plugin.name, root: $.plugin.root },
     ui: {
-      status: (text) => $.ui.status(text),
       log: (text, options) => $.ui.log(text, options),
       notice: (toolUseId, text) => $.ui.notice(toolUseId, text),
       invalidate: (event) => $.ui.invalidate(event),
@@ -112,7 +111,7 @@ function routeCallFailure(_$: EngineInterface, eventInput: Frozen<Args<'cmod.cal
 
 export function registerMod<State extends object, Declared extends Options>(addHook: On, definition: ModDefinition<State, string, Declared>, options: PluginOptions): void {
   permissionCheck = undefined
-  registered = definition as ModDefinition<object>
+  registered = definition
   lifecycle = createLifecycle(definition, () => permissionCheck, options)
   addHook('session.start', startMod)
   addHook('classic.Setup', routeToMod).catch(routeFailure)
@@ -142,13 +141,13 @@ export function registerMod<State extends object, Declared extends Options>(addH
   addHook('classic.PostCompact', routeToMod).catch(routeFailure)
   addHook('classic.Stop', routeToMod).catch(routeFailure)
   addHook('classic.StopFailure', routeToMod).catch(routeFailure)
-  addHook('classic.FileChanged', routeToMod).catch(routeFailure)
   addHook('classic.WorktreeCreate', routeToMod).catch(routeFailure)
   addHook('classic.WorktreeRemove', routeToMod).catch(routeFailure)
   addHook('tool.call', routeToMod).catch(routeFailure)
   addHook('prompt.submit', routeToMod).catch(routeFailure)
   addHook('prompt.context', routeToMod).catch(routeFailure)
   addHook('command.run', routeToMod).catch(routeFailure)
+  addHook('command.describe', routeToMod).catch(routeFailure)
   addHook('session.measure', routeToMod).catch(routeFailure)
   addHook('skill.prompt', routeToMod).catch(routeFailure)
   addHook('ui.render', routeToMod).catch(routeFailure)