@cmodjs/core 0.3.0 → 1.5.0

package/src/testing.ts

@@ -17,23 +17,39 @@ import type {
   UiPressArgument,
   UiSelectArgument,
 } from 'claude-code'
-import type { Reply } from './jobs/slash-command.js'
-import type { ModDefinition, ModEvent } from './mod.js'
+import type { CommandReply } from './jobs/slash-command.js'
+import type { Hook, ModDefinition } from './mod.js'
 import type { Options, OptionValues } from './options.js'
 import { readSteps, storeFolder, type Steps } from './records.js'
 import type { Claude } from './runtime/claude.js'
-import { answerCall, notInstalled } from './runtime/dependencies.js'
+import { answerCall, cmodPluginName, notInstalled } from './runtime/dependencies.js'
+import { foldAnswers, installBefore } from './runtime/before.js'
 import type { RoutedEvent } from './runtime/hooks.js'
+import { createRouter } from './runtime/router.js'
 import { toolInputOf } from './runtime/tool-calls.js'
 import { createLifecycle } from './runtime/lifecycle.js'
 import { MissingOptions } from './runtime/options.js'
-import { fakeClaude, type Fakes, type Shown, type TestCall } from './testing/fake-claude.js'
+import { conversationMethods } from './runtime/sessions.js'
+import type { ShownToast } from './runtime/toaster.js'
+import type { Message } from './session/context/turn/message/message.js'
+import { Note } from './session/context/turn/message/note.js'
+import { Prompt } from './session/context/turn/message/prompt.js'
+import { Mod, Person } from './session/context/turn/message/sender.js'
+import type { SessionChange } from './session/conversation.js'
+import type { BeforeEvent } from './session/session.js'
+import { calledAnswer, fakeClaude, type Fakes, type Shown as ShownByClaude, type TestCall } from './testing/fake-claude.js'
 import { elements, findElement, rowsOf } from './testing/fake-elements.js'
 import { fakeFiles } from './testing/fake-files.js'
-import { listed } from './utils/text.js'
-import type { Slot, SlotProps } from './ui/slots.js'
+import { fakeSessions, type FakeSession, type FakeSessions, type MessageDraft } from './testing/fake-sessions.js'
+import { listed, messageOf } from './utils/text.js'
+import { componentOf, type ComponentPlace, type PlaceProps } from './ui/places.js'
 
-export type { Fakes, Shown, TestCall } from './testing/fake-claude.js'
+export type { Fakes, TestCall } from './testing/fake-claude.js'
+export type { FakeSession, MessageDraft } from './testing/fake-sessions.js'
+export type { RoutedEvent } from './runtime/hooks.js'
+export type { ShownToast } from './runtime/toaster.js'
+
+export type Shown = ShownByClaude & { readonly toasts: readonly ShownToast[]; readonly sent: FakeSessions['sent'] }
 
 export type TestOptions<State extends object, Declared extends Options = Options> = {
   readonly state?: { readonly [Lifetime in keyof State]?: Partial<State[Lifetime]> }
@@ -45,23 +61,28 @@ export type TestOptions<State extends object, Declared extends Options = Options
   readonly dependencies?: { readonly [Name in keyof CmodDependencies]?: CmodDependencies[Name] }
   readonly files?: Readonly<Record<string, string>>
   readonly links?: Readonly<Record<string, string>>
+  readonly sessions?: readonly FakeSession[]
 }
 
 type FilledField = 'session_id' | 'transcript_path' | 'cwd' | 'hook_event_name' | 'tool_use_id'
 
-export type TestInput<E extends ModEvent> = Omit<ClassicHookInputs[E], FilledField> & Partial<Pick<ClassicHookInputs[E], FilledField & keyof ClassicHookInputs[E]>>
+export type TestInput<H extends Hook> = Omit<ClassicHookInputs[H], FilledField> & Partial<Pick<ClassicHookInputs[H], FilledField & keyof ClassicHookInputs[H]>>
 
 export type TestedMod<State extends object> = {
   start(): Promise<void>
-  fire<E extends ModEvent>(event: E, input: TestInput<E>, below?: EventResult<`classic.${E}`>): Promise<EventResult<`classic.${E}`>>
+  fire<H extends Hook>(hook: H, input: TestInput<H>, below?: EventResult<`classic.${H}`>): Promise<EventResult<`classic.${H}`>>
   fire<N extends RoutedEvent>(event: N, input: Args<N>, below?: EventResult<N>): Promise<EventResult<N>>
   settle(): Promise<void>
+  add(message: MessageDraft, options?: { readonly task?: string }): Promise<Message[]>
+  endTurn(): Promise<void>
+  compact(): Promise<void>
+  startTask(task: { readonly title: string; readonly agentType?: string; readonly model?: string; readonly openedBy?: string; readonly parent?: string }): Promise<string>
   lines(paneId: string): Promise<string[]>
-  lines<S extends Slot<object, object, { readonly component: RenderComponent }>>(slot: S, props: Omit<SlotProps<S>, 'Default'>, requestId?: string): Promise<string[]>
-  type(line: string): Promise<Reply>
+  lines<P extends ComponentPlace>(place: P, props: Omit<PlaceProps<P>, 'Default'>, requestId?: string): 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?: UiInputArgument['kind']): Promise<void>
+  input(paneId: string, key: string, text: string, type?: UiInputArgument['kind']): Promise<void>
   select(paneId: string, key: string, value: string): Promise<void>
   moveTo(projectRoot: string, cwd?: string): Promise<void>
   readonly state: Readonly<State>
@@ -76,7 +97,7 @@ const defaultRows = 24
 
 const presentation: CommandPresentation = { isFullscreen: false, columns: defaultColumns }
 
-const toolUseEvents: readonly string[] = ['PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'PermissionDenied'] satisfies readonly ModEvent[]
+const toolUseEvents: readonly string[] = ['PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'PermissionDenied'] satisfies readonly Hook[]
 
 export function testMod<State extends object, Declared extends Options = Options>(definition: ModDefinition<State, string, Declared>, options: TestOptions<State, Declared> = {}): TestedMod<State> {
   installJsx()
@@ -93,14 +114,38 @@ export function testMod<State extends object, Declared extends Options = Options
   fake.claude.session.id = async () => sessionId
   fake.claude.session.root = async () => projectRoot
   fake.claude.session.cwd = async () => cwd
-  fake.fakes.cmod.call = fakeDependencies(options.dependencies ?? {})
+  const conversations = fakeSessions({
+    callTool: (args: Parameters<Claude["tool"]["call"]>[0]) => fake.claude.tool.call(args),
+    project: () => projectRoot,
+    given: options.sessions ?? [],
+    push: (mod, session, change) => {
+      if (mod !== name) return
+      const pushed = { to: mod, method: conversationMethods.changed, input: { session, change }, caller: cmodPluginName } as unknown as Frozen<Args<'cmod.call'>>
+      void lifecycle.route('cmod.call', pushed, async () => ({ deny: notInstalled(mod) }))
+    },
+  })
+  conversations.start(sessionId)
+  fake.fakes.cmod.call = fakeDependencies(name, options.dependencies ?? {}, conversations)
+  const appendRow = fake.claude.session.append
+  fake.claude.session.append = async (args) => {
+    const added = await appendRow(args)
+    if (added.deny === undefined) conversations.add({ type: Note, text: args.message.content.map((block) => (typeof block['text'] === 'string' ? block['text'] : '')).join(''), from: { type: Mod, name } })
+    return added
+  }
+  const submitRow = fake.claude.prompt.submit
+  fake.claude.prompt.submit = async (args) => {
+    const submitted = await submitRow(args)
+    conversations.add({ type: Prompt, text: args.text, from: { type: Mod, name, ...(args.asUser === true ? { as: Person } : {}) } })
+    return submitted
+  }
   const firedAgents = new Map<string, string>()
   const listAgents = fake.claude.agent.list
   fake.claude.agent.list = async () => {
     if (fake.fakes.agent.list !== undefined || firedAgents.size === 0) return listAgents()
     return [...firedAgents].map(([id, type]) => ({ id, type, description: '', status: 'running' as const }))
   }
-  Object.assign(fake.fakes.fs, fakeFiles(options.files ?? {}, options.links))
+  const files = fakeFiles(options.files ?? {}, options.links)
+  Object.assign(fake.fakes.fs, files)
   const starting = options.state as Record<string, object> | undefined
   const declared = Object.entries(definition.state ?? {}) as [string, object][]
   const state = Object.fromEntries(declared.map(([lifetime, values]) => [lifetime, { ...values, ...starting?.[lifetime] }])) as State
@@ -122,6 +167,7 @@ export function testMod<State extends object, Declared extends Options = Options
       }
     })
     await started
+    await fake.settle()
     const { failure } = lifecycle
     if (failure instanceof MissingOptions) {
       const given = failure.keys.map((key) => `${key}: …`).join(', ')
@@ -130,9 +176,24 @@ export function testMod<State extends object, Declared extends Options = Options
     if (lifecycle.phase !== 'active') throw failure ?? new Error(`${name} did not start: the lifecycle is ${lifecycle.phase}.`)
   }
 
+  const cmodPlugin = createRouter()
+  const askMod = async (event: BeforeEvent, change: SessionChange) => {
+    const asked = { to: name, method: conversationMethods.before, input: { session: sessionId, event, change }, caller: cmodPluginName } as unknown as Frozen<Args<'cmod.call'>>
+    return calledAnswer(cmodPluginName, await lifecycle.route('cmod.call', asked, async () => ({ deny: notInstalled(name) })))
+  }
+  installBefore({
+    claude: fake.claude,
+    router: cmodPlugin,
+    hooks: {
+      place: async () => conversations.place(),
+      wants: async (event) => conversations.wants(name, event),
+      decide: (event, change) => foldAnswers(event, change, [(latest) => askMod(event, latest)], (error) => fake.claude.ui.log(`cmod: passed the ${event} on without ${name}'s answer: ${messageOf(error)}`, { to: 'debug' })),
+    },
+  })
+
   const route = async <N extends RoutedEvent>(event: N, input: unknown, below: unknown): Promise<EventResult<N>> => {
     await start()
-    return lifecycle.route(event, input as Frozen<Args<N>>, async (e) => (below ?? claudeCodeAnswer(event, e)) as EventResult<N>)
+    return cmodPlugin.dispatch(event, input as Frozen<Args<N>>, (passed) => lifecycle.route(event, passed, async (e) => (below ?? claudeCodeAnswer(event, e)) as EventResult<N>))
   }
 
   const drawPane = async (paneId: string) => {
@@ -166,14 +227,19 @@ export function testMod<State extends object, Declared extends Options = Options
 
   const fire = ((event: string, input: object, below?: unknown) => {
     if (event.includes('.')) return route(event as RoutedEvent, input, below)
-    if (event === 'SessionStart') sessionId = (input as { session_id?: string }).session_id ?? sessionId
+    if (event === 'SessionStart') {
+      sessionId = (input as { session_id?: string }).session_id ?? sessionId
+      conversations.start(sessionId)
+    }
     if (event === 'UserPromptSubmit') {
       cwd = cwdAfterPrompt ?? cwd
       cwdAfterPrompt = undefined
     }
     const toolUse = toolUseEvents.includes(event) ? { tool_use_id: `toolu_${(toolUses += 1)}` } : {}
-    const filled = { session_id: sessionId, transcript_path: '/test/transcript.jsonl', cwd, hook_event_name: event, ...toolUse, ...input }
-    if (event !== 'PreToolUse') return route(`classic.${event as Exclude<ModEvent, 'PreToolUse'>}`, filled, below)
+    const transcript = `/test/transcripts/${sessionId}.jsonl`
+    const filled = { session_id: sessionId, transcript_path: transcript, cwd, hook_event_name: event, ...toolUse, ...input }
+    if (event === 'SessionStart' && !('transcript_path' in input)) return files.write(transcript, '').then(() => route('classic.SessionStart', filled, below))
+    if (event !== 'PreToolUse') return route(`classic.${event as Exclude<Hook, 'PreToolUse'>}`, filled, below)
     return firePreToolUse(filled as ClassicHookInputs['PreToolUse'], below as { deny?: string } | undefined)
   }) as TestedMod<State>['fire']
 
@@ -187,7 +253,7 @@ export function testMod<State extends object, Declared extends Options = Options
     const answer = await lifecycle.route('tool.call', envelope, async (e) => {
       reached = e
       check = await lifecycle.route('tool.check', { tool: e.tool, input: toolInputOf(e), tool_use_id: e.tool_use_id, ...(e.agentId === undefined ? {} : { agentId: e.agentId }) }, async () => asks)
-      return (check.decision === 'deny' ? { deny: check.reason ?? '' } : { result: '' }) as EventResult<'tool.call'>
+      return check.decision === 'deny' ? { deny: check.reason ?? '' } : { result: '' }
     })
     const updatedInput = toolInputOf(reached)
     const decided = check === asks ? {} : check.decision === 'allow' ? { allow: true } : check.decision === 'ask' ? { ask: check.reason ?? '' } : {}
@@ -198,14 +264,37 @@ export function testMod<State extends object, Declared extends Options = Options
     } as EventResult<'classic.PreToolUse'>
   }
 
+  const settled = async <Value>(value: Value) => {
+    await fake.settle()
+    return value
+  }
+
   return {
     start,
     fire,
     settle: fake.settle,
-    lines: (async (target: string | { readonly component: RenderComponent }, props: object = {}, requestId?: string) => {
-      const { drawing, columns } = typeof target === 'string' ? await drawPane(target) : await drawSlot(target.component, props, requestId)
+    add: async (message, added) => {
+      await start()
+      return settled(conversations.add(message, added?.task))
+    },
+    endTurn: async () => {
+      await start()
+      await settled(conversations.endTurn())
+    },
+    compact: async () => {
+      await start()
+      await settled(conversations.compact())
+    },
+    startTask: async (task) => {
+      await start()
+      return settled(conversations.startTask(task))
+    },
+    lines: async (target: string, props?: object, requestId?: string) => {
+      const component = componentOf(target as ComponentPlace)
+      if (props !== undefined && component === undefined) throw new Error(`lines takes a pane id, or a place render draws and its props, and ${target} is neither a place such as ToolCall nor called without props.`)
+      const { drawing, columns } = props === undefined || component === undefined ? await drawPane(target) : await drawSlot(component, props, requestId)
       return rowsOf(drawing, columns).map((row) => row.trimEnd())
-    }) as TestedMod<State>['lines'],
+    },
     async type(line) {
       const typed = /^\/(\S+)\s*(.*)$/s.exec(line)
       if (typed === null) throw new Error(`type takes a slash command the way the user types it, such as tested.type('/help'), and "${line}" does not start with /.`)
@@ -230,16 +319,16 @@ export function testMod<State extends object, Declared extends Options = Options
       const props = await drawnElement(paneId, link === undefined ? 'Button' : 'Markdown', key)
       if (link !== undefined && props['onLinkPress'] === undefined) throw new Error(`The Markdown "${key}" in the pane "${paneId}" of ${name} has no onLinkPress, so Claude Code opens its links itself.`)
       const pressed: UiPressArgument = { ...eventIn(paneId, String(props['key'])), ...(link === undefined ? {} : { link: { href: link } }) }
-      await lifecycle.route('ui.press', pressed as Frozen<Args<'ui.press'>>, async (e) => {
+      await lifecycle.route('ui.press', pressed, async (e) => {
         if (e.link === undefined) await (props['onPress'] as (e: UiPressArgument) => unknown)(e)
         else await (props['onLinkPress'] as (link: PressedLink, e: UiPressArgument) => unknown)(e.link, e)
         return { element: e.element }
       })
     },
-    async input(paneId, key, text, kind = 'submit') {
+    async input(paneId, key, text, type = 'submit') {
       const props = await drawnElement(paneId, 'Input', key)
-      const typed: UiInputArgument = { ...eventIn(paneId, key), kind, value: text }
-      await (props[kind === 'submit' ? 'onSubmit' : 'onInput'] as ((value: string, e: UiInputArgument) => unknown) | undefined)?.(text, typed)
+      const typed: UiInputArgument = { ...eventIn(paneId, key), kind: type, value: text }
+      await (props[type === 'submit' ? 'onSubmit' : 'onInput'] as ((value: string, e: UiInputArgument) => unknown) | undefined)?.(text, typed)
     },
     async select(paneId, key, value) {
       const props = await drawnElement(paneId, 'Select', key)
@@ -269,21 +358,32 @@ export function testMod<State extends object, Declared extends Options = Options
     },
     calls: fake.calls,
     fakes: fake.fakes,
-    shown: fake.shown,
+    shown: {
+      ...fake.shown,
+      get toasts() {
+        return lifecycle.toasts
+      },
+      sent: conversations.sent,
+    },
   }
 }
 
-function fakeDependencies(dependencies: NonNullable<TestOptions<object>['dependencies']>): Claude['cmod']['call'] {
-  const apis = dependencies as Readonly<Record<string, Parameters<typeof answerCall>[1] | undefined>>
+function fakeDependencies(caller: string, dependencies: NonNullable<TestOptions<object>['dependencies']>, conversations: FakeSessions): Claude['cmod']['call'] {
+  const cmod = { forkParent: () => null, updateSettings: () => null }
+  const apis = { [cmodPluginName]: cmod, ...dependencies } as Readonly<Record<string, Parameters<typeof answerCall>[1] | undefined>>
   return async (call) => {
+    const served = call.to === cmodPluginName ? conversations.answer(caller, call.method, call.input) : undefined
+    if (served !== undefined) return calledAnswer(caller, served as EventResult<'cmod.call'>)
     const api = apis[call.to]
-    const answer = api === undefined ? { deny: notInstalled(call.to) } : await answerCall(call.to, api, call)
-    if (answer.deny !== undefined) throw new Error(answer.deny)
-    return answer.value
+    return calledAnswer(caller, api === undefined ? { deny: notInstalled(call.to) } : await answerCall(call.to, api, call))
   }
 }
 
 function claudeCodeAnswer(event: RoutedEvent, e: unknown): unknown {
+  if (event === 'agent.spawn') {
+    const { model, parentModel } = e as Args<'agent.spawn'>
+    return { agentId: 'agent-1', model: model ?? parentModel }
+  }
   if (event !== 'prompt.submit') return {}
   const { text, context, origin } = e as Args<'prompt.submit'>
   return { text, ...(context === undefined ? {} : { context }), origin }
@@ -294,7 +394,7 @@ function plainOutput({ component, props }: Args<'ui.render'>): RenderElement {
   return elements.Box({ flexDirection: 'column', children: [elements.Text({ children: component }), elements.Box({ flexDirection: 'column', paddingLeft: 2, children: rows })] })
 }
 
-function replyOf({ text, context }: CommandRunResult): Reply {
+function replyOf({ text, context }: CommandRunResult): CommandReply {
   return { ...(text === undefined ? {} : { text }), ...(context === undefined ? {} : { context: context.join('\n') }) }
 }
 
@@ -302,7 +402,10 @@ async function modSteps(): Promise<Steps> {
   const manifest = '../../../package.json'
   const loaded: unknown = await import(manifest, { with: { type: 'json' } }).then(
     (module: { default: unknown }) => module.default,
-    () => undefined,
+    (error: { readonly code?: unknown }) => {
+      if (error.code === 'ERR_MODULE_NOT_FOUND') return undefined
+      throw error
+    },
   )
   return readSteps(loaded) ?? {}
 }

package/src/ui/components.ts

@@ -49,9 +49,9 @@ export function Pagination({ page, pages, onPage }: { readonly page: number; rea
   })
 }
 
-export function ProgressBar({ done, total, width = 24 }: { readonly done: number; readonly total: number; readonly width?: number }): RenderElement {
-  const filled = total > 0 ? Math.round(Math.min(done / total, 1) * width) : 0
-  return Text({ children: [Text({ color: 'claude', children: '█'.repeat(filled) }), Text({ color: 'subtle', children: '░'.repeat(width - filled) }), '  ', Text({ dimColor: true, children: `${done}/${total}` })] })
+export function Progress({ value, width = 24 }: { readonly value: number; readonly width?: number }): RenderElement {
+  const filled = Math.round((Math.min(Math.max(value, 0), 100) / 100) * width)
+  return Text({ children: [Text({ color: 'claude', children: '█'.repeat(filled) }), Text({ color: 'subtle', children: '░'.repeat(width - filled) })] })
 }
 
 const cardColumns = 36

package/src/ui/elements.ts

@@ -6,25 +6,39 @@ type CompletedTable = Record<ElementName, (props: object) => RenderElement>
 
 type Drawing = { readonly table: CompletedTable; readonly markdown: ((props: MarkdownProps) => RenderElement) | undefined }
 
+const unbuilt = Symbol('an element built outside a render')
+
+type Unbuilt = { readonly [unbuilt]: { readonly name: ElementName; readonly props: object } }
+
 let drawing: Drawing | undefined
 
 export function drawWith<Drawn>(table: ElementTable, draw: () => Drawn, markdown?: (props: MarkdownProps) => RenderElement): Drawn {
   const outer = drawing
-  drawing = { table: table as CompletedTable, markdown }
+  const current = { table: table as CompletedTable, markdown }
+  drawing = current
   try {
-    return draw()
+    return built(current, draw()) as Drawn
   } finally {
     drawing = outer
   }
 }
 
 function element<Name extends keyof Terminal & ElementName>(name: Name): Terminal[Name] {
-  const construct = (props: object) => {
-    if (drawing === undefined) throw new Error(`${name} was called outside a render. Use it inside a pane's render or a slot's component.`)
-    if (name === 'Markdown' && drawing.markdown !== undefined) return drawing.markdown(props as MarkdownProps)
-    return drawing.table[name](props)
-  }
-  return construct as Terminal[Name]
+  const construct = (props: object) => (drawing === undefined ? ({ [unbuilt]: { name, props } } satisfies Unbuilt as unknown as RenderElement) : build(drawing, name, props))
+  return construct
+}
+
+function build(current: Drawing, name: ElementName, props: object): RenderElement {
+  const ready = 'children' in props ? { ...props, children: built(current, props.children) } : props
+  if (name === 'Markdown' && current.markdown !== undefined) return current.markdown(ready as MarkdownProps)
+  return current.table[name](ready)
+}
+
+function built(current: Drawing, value: unknown): unknown {
+  if (Array.isArray(value)) return value.map((child: unknown) => built(current, child))
+  if (typeof value !== 'object' || value === null || !(unbuilt in value)) return value
+  const { name, props } = (value as Unbuilt)[unbuilt]
+  return build(current, name, props)
 }
 
 export const Box = element('Box')

package/src/ui/markdown.ts

@@ -1,11 +1,9 @@
 import type { Nodes, RootContent } from 'mdast'
 import { fromMarkdown, gfm, gfmFromMarkdown, toString } from '../vendor-markdown.js'
-import type { Slot, SlotProps } from './slots.js'
+import type { PlaceProps } from './places.js'
 
 type Block = { readonly text: string; readonly source: string }
 
-type MarkdownSlot<Props extends object = object> = Slot<Props, { readonly source?: string }, { readonly markdown: MarkdownKind }>
-
 type BlockFields = {
   heading: { readonly depth: 1 | 2 | 3 | 4 | 5 | 6 }
   code: { readonly lang: string | undefined; readonly meta: string | undefined; readonly value: string }
@@ -14,18 +12,31 @@ type BlockFields = {
   html: { readonly value: string }
 }
 
-type BlockProps<Type extends string> = Type extends keyof BlockFields ? Block & BlockFields[Type] : Block
+export type BlockProps<Type extends string> = Type extends keyof BlockFields ? Block & BlockFields[Type] : Block
 
 export type MarkdownPiece<Render> = { readonly text: string } | { readonly render: Render; readonly props: Block }
 
 export type MarkdownReader = <Render>(text: string, renderOf: (type: string) => Render | undefined, replyId?: string) => readonly MarkdownPiece<Render>[]
 
-export type MarkdownKind = {
+export type MarkdownPlace<Type extends string = string> = {
   readonly name: string
-  readonly type: string
-  readonly createReader: () => MarkdownReader
+  readonly markdown: Type
+  createReader(): MarkdownReader
 }
 
+function markdownPlace<const Type extends string>(name: string, markdown: Type): MarkdownPlace<Type> {
+  return { name, markdown, createReader }
+}
+
+export const Heading = markdownPlace('Heading', 'heading')
+export const Paragraph = markdownPlace('Paragraph', 'paragraph')
+export const CodeBlock = markdownPlace('CodeBlock', 'code')
+export const BlockQuote = markdownPlace('BlockQuote', 'blockquote')
+export const List = markdownPlace('List', 'list')
+export const Table = markdownPlace('Table', 'table')
+export const ThematicBreak = markdownPlace('ThematicBreak', 'thematicBreak')
+export const HtmlBlock = markdownPlace('HtmlBlock', 'html')
+
 type Parsed = {
   readonly type: string
   readonly start: number
@@ -52,7 +63,7 @@ const blankLine = /\n[^\S\n]*\n/
 
 const fence = /^ {0,3}(`{3}|~{3})/
 
-function createReader(): MarkdownReader {
+export function createReader(): MarkdownReader {
   const replies: Reply[] = []
 
   const remember = (reply: Reply) => {
@@ -152,22 +163,7 @@ function plainText(node: Nodes): string {
   return node.children.map(plainText).join(node.type === 'tableRow' ? '\t' : '\n')
 }
 
-function markdownSlot<Type extends RootContent['type']>(name: string, type: Type): MarkdownSlot<BlockProps<Type>> {
-  return { markdown: { name, type, createReader } } as MarkdownSlot<BlockProps<Type>>
-}
-
-export const markdownSlots = {
-  Heading: markdownSlot('Heading', 'heading'),
-  Paragraph: markdownSlot('Paragraph', 'paragraph'),
-  CodeBlock: markdownSlot('CodeBlock', 'code'),
-  BlockQuote: markdownSlot('BlockQuote', 'blockquote'),
-  List: markdownSlot('List', 'list'),
-  Table: markdownSlot('Table', 'table'),
-  ThematicBreak: markdownSlot('ThematicBreak', 'thematicBreak'),
-  HtmlBlock: markdownSlot('HtmlBlock', 'html'),
-}
-
-export function markdownBlocks<S extends MarkdownSlot>(text: string, slot: S): Omit<SlotProps<S>, 'Default'>[] {
-  const blocks = parsed(text, 0).filter((block) => block.type === slot.markdown.type)
-  return blocks.map((block) => block.props) as unknown as Omit<SlotProps<S>, 'Default'>[]
+export function markdownBlocks<P extends MarkdownPlace>(text: string, place: P): Omit<PlaceProps<P>, 'Default'>[] {
+  const blocks = parsed(text, 0).filter((block) => block.type === place.markdown)
+  return blocks.map((block) => block.props) as unknown as Omit<PlaceProps<P>, 'Default'>[]
 }

package/src/ui/places.ts

@@ -0,0 +1,49 @@
+import type { Frozen, RenderComponent, RenderElement, RenderPropsOf } from 'claude-code'
+import type { BlockProps, MarkdownPlace } from './markdown.js'
+
+export const ToolGroup = 'toolGroup'
+export const ToolProgress = 'toolProgress'
+export const CommandOutput = 'commandOutput'
+export const AskUserQuestion = 'askUserQuestion'
+export const Spinner = 'spinner'
+export const TurnDuration = 'turnDuration'
+export const SessionMode = 'sessionMode'
+export const PromptHint = 'promptHint'
+export const AbovePrompt = 'abovePrompt'
+
+const components = {
+  prompt: 'UserMessage',
+  reply: 'AssistantMessage',
+  toolCall: 'ToolUse',
+  toolResult: 'ToolResult',
+  notice: 'InfoNotice',
+  [ToolGroup]: 'ToolGroup',
+  [ToolProgress]: 'ToolProgress',
+  [CommandOutput]: 'CommandOutput',
+  [AskUserQuestion]: 'AskUserQuestion',
+  [Spinner]: 'Spinner',
+  [TurnDuration]: 'TurnDuration',
+  [SessionMode]: 'SessionMode',
+  [PromptHint]: 'PromptHint',
+  [AbovePrompt]: 'AbovePrompt',
+} as const satisfies Readonly<Record<string, Exclude<RenderComponent, 'Pane'>>>
+
+export type ComponentPlace = keyof typeof components
+
+export type Place = ComponentPlace | MarkdownPlace
+
+type ComponentProps = { readonly [P in ComponentPlace]: RenderPropsOf[(typeof components)[P]] }
+
+type PropsOf<P extends Place> = P extends ComponentPlace ? ComponentProps[P] : P extends MarkdownPlace<infer Type> ? BlockProps<Type> : never
+
+type DefaultOf<P extends Place> = P extends ComponentPlace ? Partial<Omit<ComponentProps[P], 'onScreen'>> : { readonly source?: string }
+
+export type PlaceProps<P extends Place> = Frozen<PropsOf<P>> & { readonly Default: (props: Frozen<DefaultOf<P>>) => RenderElement }
+
+export function componentOf(place: Place): Exclude<RenderComponent, 'Pane'> | undefined {
+  return typeof place === 'string' && Object.hasOwn(components, place) ? components[place] : undefined
+}
+
+export function nameOf(place: Place): string {
+  return typeof place === 'string' ? `${place.charAt(0).toUpperCase()}${place.slice(1)}` : place.name
+}

package/src/utils/call-effects.ts

@@ -1,12 +1,12 @@
 import { parseShell, type ShellCommand } from './parse-shell.js'
-import { expandHome, type FileSystem } from './paths.js'
+import { expandHome, ifMissing, type FileSystem } from './paths.js'
 import { resolve } from '../vendor.js'
 
 export type CallBase = { tool: string; input: Readonly<Record<string, unknown>>; agentId?: string; agentType?: string }
 export type CommandCall = CallBase & { commands: [string, ...string[]][]; isFullyParsed: boolean }
 export type FileCall = CallBase & { path: string; content?: string; previousContent?: string }
 export type FetchCall = CallBase & { url: string }
-export type ToolCall = CommandCall | FileCall | FetchCall | CallBase
+export type Call = CommandCall | FileCall | FetchCall | CallBase
 
 export type Contents = { content?: string; previousContent?: string }
 export type FileAccess = { path: string; contents: (() => Promise<Contents>) | undefined }
@@ -18,9 +18,9 @@ export type CallEffects = {
   subagent: string | undefined
 }
 
-export function callEffects(use: CallBase, workspace: { cwd: string; home: string; fs: FileSystem }): CallEffects {
+export function callEffects(use: CallBase, workspace: { cwd: string; home: string; configRoot?: string; fs: FileSystem }): CallEffects {
   const { fs } = workspace
-  const absolute = (path: string, folder = workspace.cwd) => resolve(folder, expandHome(path, workspace.home))
+  const absolute = (path: string, folder = workspace.cwd) => resolve(folder, expandHome(path, workspace.home, workspace.configRoot))
   const access = (path: string): FileAccess => ({ path: absolute(path), contents: undefined })
   const effects: CallEffects = { shell: undefined, reads: [], writes: [], urls: [], subagent: undefined }
   if (use.tool === 'Bash') {
@@ -79,7 +79,7 @@ async function editedContents(use: CallBase, path: string, fs: FileSystem): Prom
 }
 
 async function previousContentOf(path: string, fs: FileSystem): Promise<string | undefined> {
-  const stat = await fs.stat(path).catch(() => undefined)
+  const stat = await fs.stat(path).catch(ifMissing(undefined))
   return stat?.kind === 'file' ? fs.read(path) : undefined
 }
 

package/src/utils/changelog.ts

@@ -0,0 +1,32 @@
+export type ChangelogSection = { readonly version: string; readonly date?: string; readonly text: string }
+
+export const unreleased = 'Unreleased'
+
+const heading = /^##\s+\[?([^\]\s]+)\]?(?:\s+-\s+(\S+))?\s*$/
+
+const linkReference = /^\[[^\]]+\]:\s/
+
+export function changelogSections(markdown: string): ChangelogSection[] {
+  const sections: { readonly version: string; readonly date: string | undefined; readonly lines: string[] }[] = []
+  for (const line of markdown.split('\n')) {
+    const match = heading.exec(line)
+    if (match !== null) sections.push({ version: match[1] as string, date: match[2], lines: [] })
+    else if (!linkReference.test(line)) sections.at(-1)?.lines.push(line)
+  }
+  return sections.map(({ version, date, lines }) => ({ version, ...(date === undefined ? {} : { date }), text: lines.join('\n').trim() }))
+}
+
+export function changeLines(text: string): string[] {
+  let group: string | undefined
+  return text.split('\n').flatMap((line) => {
+    const trimmed = line.trim()
+    const subheading = /^###\s+(.+)$/.exec(trimmed)?.[1]
+    if (subheading !== undefined) {
+      group = subheading
+      return []
+    }
+    const item = /^[-*]\s+(.+)$/.exec(trimmed)?.[1] ?? trimmed
+    if (item === '') return []
+    return [group === undefined ? item : `${group}: ${item}`]
+  })
+}

package/src/utils/disposable.ts

@@ -0,0 +1,3 @@
+export type Disposable = {
+  dispose(): void
+}

package/src/utils/matcher.ts

@@ -0,0 +1,37 @@
+export type Matcher<Value> = Value extends string
+  ? string | RegExp
+  : Value extends number | boolean | null | undefined
+    ? Value
+    : Value extends readonly (infer Item)[]
+      ? Matcher<Item>
+      : Value extends (...args: never[]) => unknown
+        ? never
+        : Value extends object
+          ? { readonly [Key in keyof Value]?: Matcher<Value[Key]> }
+          : Value
+
+export type SentMatcher = string | number | boolean | null | { readonly regexp: string; readonly flags: string } | { readonly [key: string]: SentMatcher } | readonly SentMatcher[]
+
+export function matches(value: unknown, matcher: unknown): boolean {
+  if (matcher instanceof RegExp) return value !== undefined && value !== null && matcher.test(String(value))
+  if (Array.isArray(matcher)) return matcher.some((each) => matches(value, each))
+  if (typeof matcher !== 'object' || matcher === null) return value === matcher
+  if (Array.isArray(value)) return value.some((each) => matches(each, matcher))
+  if (typeof value !== 'object' || value === null) return false
+  return Object.entries(matcher).every(([key, wanted]) => wanted === undefined || matches((value as Record<string, unknown>)[key], wanted))
+}
+
+export function sentMatcher(matcher: unknown): SentMatcher {
+  if (matcher instanceof RegExp) return { regexp: matcher.source, flags: matcher.flags }
+  if (Array.isArray(matcher)) return matcher.map(sentMatcher)
+  if (typeof matcher !== 'object' || matcher === null) return matcher as SentMatcher
+  return Object.fromEntries(Object.entries(matcher).filter(([, value]) => value !== undefined).map(([key, value]) => [key, sentMatcher(value)]))
+}
+
+export function receivedMatcher(sent: SentMatcher): unknown {
+  if (Array.isArray(sent)) return sent.map(receivedMatcher)
+  if (typeof sent !== 'object' || sent === null) return sent
+  const fields = sent as Readonly<Record<string, unknown>>
+  if (typeof fields['regexp'] === 'string' && typeof fields['flags'] === 'string' && Object.keys(fields).length === 2) return new RegExp(fields['regexp'], fields['flags'])
+  return Object.fromEntries(Object.entries(fields).map(([key, value]) => [key, receivedMatcher(value as SentMatcher)]))
+}