@xp266/dshtui 0.1.0

package/src/ui/hooks/use-mouse-selection.ts

@@ -0,0 +1,352 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { pointerHandlerEntries, type PointerSession } from '../pointer/registry.ts'
+import type { PointerHandlerContribution } from '../../contract/index.ts'
+import { createBuiltinPointerHandler, type BuiltinPointerHandler } from '../pointer/builtins.ts'
+import type { RefObject } from 'react'
+import type { ScreenCapture } from '../../terminal/screen.ts'
+import { createMouseController } from '../../terminal/mouse.ts'
+import { inputContentContains, hintSpan, scrollbarColumn } from '../layout-service.ts'
+import { clampFocusRow, toScreenSelection } from '../../model/selection.ts'
+import type { LineSelection } from '../../model/selection.ts'
+import type { ScrollSnapshot } from './use-scroll.ts'
+import { rowInfoAt, rowCount, scrollbarGeometry } from '../message/layout.ts'
+import { POINTER_BUILTIN_ORDER } from '../pointer/registry.ts'
+import type { InputBarHandle } from '../input/input-bar.tsx'
+import type { PanelPointerHandle } from '../panels/approval-panel.tsx'
+import type { CommandHintState } from '../input/commands.ts'
+import type { Message } from '../../model/message.ts'
+
+const DRAG_SCROLL_INTERVAL_MS = 15
+
+export interface HintRegion {
+  top: number
+  bottom: number
+}
+
+export function hintRegion(rows: number, hint: CommandHintState | null, dialogOpen: boolean, inputHeight: number): HintRegion | null {
+  return hintSpan(rows, inputHeight, hint?.commands.length ?? 0, dialogOpen)
+}
+
+export interface MouseSelectionOptions {
+  messages: Message[]
+  columns: number
+  rows: number
+  scrollTop: number
+  messageHeight: number
+  inputHeight: number
+  dialogOpen: boolean
+  hint: CommandHintState | null
+  screen?: ScreenCapture
+  inputHandle?: RefObject<InputBarHandle | null>
+  panelActive?: boolean
+  panelHandle?: RefObject<PanelPointerHandle | null>
+  getScroll(): ScrollSnapshot
+  onHintPress?(x: number, y: number): void
+  onHintDragStart?(x: number, y: number): void
+  onHintDragMove?(x: number, y: number): void
+  onHintRelease?(x: number, y: number, dragged: boolean): void
+  onDialogWheel?(y: number, dir: -1 | 1): boolean
+  onScroll(next: number): void
+  onToggleMessage(id: string): void
+  onDialogClick(y: number, x: number): void
+}
+
+export interface MouseSelectionState {
+  selection: LineSelection | null
+  messageAreaSelection: LineSelection | null
+  chromeSelection: LineSelection | null
+  setSelection(next: LineSelection | null | ((current: LineSelection | null) => LineSelection | null)): void
+  clearSelection(): void
+}
+
+export function useMouseSelection(options: MouseSelectionOptions): MouseSelectionState {
+  const { messages, columns, rows, scrollTop, messageHeight, inputHeight, dialogOpen, hint, screen, inputHandle, panelActive = false, panelHandle, getScroll, onHintPress, onHintDragStart, onHintDragMove, onHintRelease, onDialogWheel, onScroll, onToggleMessage, onDialogClick } = options
+  const [selection, setSelection] = useState<LineSelection | null>(null)
+  const messagesRef = useRef(messages)
+  const widthRef = useRef(columns)
+  const rowsRef = useRef(rows)
+  const scrollTopRef = useRef(scrollTop)
+  const messageHeightRef = useRef(messageHeight)
+  const inputHeightRef = useRef(inputHeight)
+  const dialogOpenRef = useRef(dialogOpen)
+  const hintStateRef = useRef<CommandHintState | null>(null)
+  const screenRef = useRef<ScreenCapture | undefined>(screen)
+  const inputHandleRef = useRef(inputHandle)
+  const panelActiveRef = useRef(panelActive)
+  const panelHandleRef = useRef(panelHandle)
+  const getScrollRef = useRef(getScroll)
+  const onHintPressRef = useRef(onHintPress)
+  const onHintDragStartRef = useRef(onHintDragStart)
+  const onHintDragMoveRef = useRef(onHintDragMove)
+  const onHintReleaseRef = useRef(onHintRelease)
+  const onDialogWheelRef = useRef(onDialogWheel)
+  const clickCandidateRef = useRef<{ messageId: string; y: number; x: number; moved: boolean } | null>(null)
+  const dialogClickCandidateRef = useRef<{ x: number; y: number } | null>(null)
+  const panelClickCandidateRef = useRef<{ x: number; y: number } | null>(null)
+  const inputClickCandidateRef = useRef<{ x: number; y: number } | null>(null)
+  const onScrollRef = useRef(onScroll)
+  const onToggleMessageRef = useRef(onToggleMessage)
+  const onDialogClickRef = useRef(onDialogClick)
+  const selectionRef = useRef<LineSelection | null>(null)
+  const autoScrollTimerRef = useRef<ReturnType<typeof setInterval> | null>(null)
+  const autoScrollDirRef = useRef<-1 | 1>(1)
+  const pointerSessionRef = useRef({ inMessageArea: false })
+  const scrollbarSessionRef = useRef<{ grabOffset: number } | null>(null)
+  messagesRef.current = messages
+  widthRef.current = columns
+  rowsRef.current = rows
+  scrollTopRef.current = scrollTop
+  messageHeightRef.current = messageHeight
+  inputHeightRef.current = inputHeight
+  dialogOpenRef.current = dialogOpen
+  hintStateRef.current = hint
+  screenRef.current = screen
+  inputHandleRef.current = inputHandle
+  panelActiveRef.current = panelActive
+  panelHandleRef.current = panelHandle
+  getScrollRef.current = getScroll
+  onHintPressRef.current = onHintPress
+  onHintDragStartRef.current = onHintDragStart
+  onHintDragMoveRef.current = onHintDragMove
+  onHintReleaseRef.current = onHintRelease
+  onDialogWheelRef.current = onDialogWheel
+  onScrollRef.current = onScroll
+  onToggleMessageRef.current = onToggleMessage
+  onDialogClickRef.current = onDialogClick
+  selectionRef.current = selection
+  useEffect(() => {
+    const stopDragScroll = (): void => {
+      if (autoScrollTimerRef.current !== null) {
+        clearInterval(autoScrollTimerRef.current)
+        autoScrollTimerRef.current = null
+      }
+    }
+    const extendSelectionTo = (row: number): void => {
+      setSelection(current => current === null || !current.inMessage
+        ? current
+        : { ...current, focusRow: Math.max(0, row) })
+    }
+    const startDragScroll = (dir: -1 | 1): void => {
+      if (autoScrollTimerRef.current !== null && autoScrollDirRef.current === dir) return
+      stopDragScroll()
+      autoScrollDirRef.current = dir
+      autoScrollTimerRef.current = setInterval(() => {
+        const scrollTop = scrollTopRef.current
+        const totalRows = rowCount(messagesRef.current, widthRef.current)
+        const maxScroll = Math.max(0, totalRows - messageHeightRef.current)
+        if ((dir === -1 && scrollTop <= 0) || (dir === 1 && scrollTop >= maxScroll)) {
+          stopDragScroll()
+          return
+        }
+        const next = scrollTop + dir
+        onScrollRef.current(next)
+        extendSelectionTo(dir === 1 ? next + messageHeightRef.current - 1 : next)
+      }, DRAG_SCROLL_INTERVAL_MS)
+    }
+    const updateDragScroll = (eventY: number): void => {
+      if (!pointerSessionRef.current.inMessageArea || dialogOpenRef.current) {
+        stopDragScroll()
+        return
+      }
+      let dir: -1 | 1 | 0 = 0
+      if (eventY <= 0) dir = -1
+      else if (eventY >= messageHeightRef.current - 1) dir = 1
+      if (dir === 0) stopDragScroll()
+      else startDragScroll(dir)
+    }
+    const inInputContent = (y: number): boolean =>
+      inputContentContains(y, rowsRef.current, inputHeightRef.current)
+    const scrollbarInfo = (): { geom: { top: number; height: number }; maxScroll: number; travel: number } | null => {
+      if (dialogOpenRef.current) return null
+      const mh = messageHeightRef.current
+      if (mh < 1) return null
+      const totalRows = rowCount(messagesRef.current, widthRef.current)
+      if (totalRows <= mh) return null
+      const geom = scrollbarGeometry(totalRows, mh, scrollTopRef.current)
+      if (geom === null) return null
+      return { geom, maxScroll: totalRows - mh, travel: Math.max(1, mh - geom.height) }
+    }
+    const onScrollbarDown = (x: number, y: number): boolean => {
+      if (x !== scrollbarColumn(widthRef.current) || y >= messageHeightRef.current) return false
+      const info = scrollbarInfo()
+      if (info === null) return false
+      stopDragScroll()
+      setSelection(null)
+      let grabOffset: number
+      if (y >= info.geom.top && y < info.geom.top + info.geom.height) {
+        grabOffset = y - info.geom.top
+      } else {
+        const centered = Math.max(0, Math.min(info.maxScroll,
+          Math.round(((y - info.geom.height / 2) / info.travel) * info.maxScroll)))
+        onScrollRef.current(centered)
+        grabOffset = y - Math.round((info.travel * centered) / info.maxScroll)
+      }
+      scrollbarSessionRef.current = { grabOffset }
+      pointerSessionRef.current = { inMessageArea: false }
+      return true
+    }
+    const onScrollbarDrag = (y: number): void => {
+      const session = scrollbarSessionRef.current
+      if (session === null) return
+      const info = scrollbarInfo()
+      if (info === null) {
+        scrollbarSessionRef.current = null
+        return
+      }
+      const thumbTop = Math.max(0, Math.min(info.travel, y - session.grabOffset))
+      const target = Math.max(0, Math.min(info.maxScroll, Math.round((thumbTop / info.travel) * info.maxScroll)))
+      onScrollRef.current(target)
+    }
+    const inMessageArea = (screenRow: number): boolean => {
+      if (screenRow >= messageHeightRef.current) return false
+      if (dialogOpenRef.current) return false
+      const region = hintRegion(rowsRef.current, hintStateRef.current, dialogOpenRef.current, inputHeightRef.current)
+      if (region !== null && screenRow >= region.top) return false
+      return true
+    }
+    const toContentRow = (screenRow: number) =>
+      inMessageArea(screenRow) ? screenRow + scrollTopRef.current : screenRow
+    const activeHintRegion = () => hintRegion(rowsRef.current, hintStateRef.current, dialogOpenRef.current, inputHeightRef.current)
+    const focusRowFor = (current: LineSelection, eventY: number): number => {
+      if (!current.inMessage) {
+        const region = activeHintRegion()
+        if (region !== null && current.anchorRow >= region.top && current.anchorRow <= region.bottom) {
+          return Math.max(region.top, Math.min(eventY, region.bottom))
+        }
+      }
+      return clampFocusRow(current.inMessage, eventY, scrollTopRef.current, messageHeightRef.current, rowsRef.current, dialogOpenRef.current)
+    }
+    const uiContext = () => ({
+      dialogOpen: dialogOpenRef.current,
+      panelActive: panelActiveRef.current,
+      hintRegion: activeHintRegion(),
+      rows: rowsRef.current,
+      columns: widthRef.current,
+      messageHeight: messageHeightRef.current,
+      inputHeight: inputHeightRef.current,
+      scrollTop: scrollTopRef.current,
+      getScroll: getScrollRef.current,
+    })
+    const session: PointerSession = {
+      getSelection: () => selectionRef.current,
+      setSelection: next => setSelection(next),
+      scroll: next => onScrollRef.current(next),
+      autoScroll: direction => {
+        if (direction === 0) stopDragScroll()
+        else startDragScroll(direction)
+      },
+    }
+    const builtinDeps = {
+      inInputContent,
+      inMessageArea,
+      toContentRow,
+      activeHintRegion,
+      focusRowFor,
+      clampMessageFocus: (anchorInMessage: boolean, eventY: number) =>
+        anchorInMessage
+          ? eventY + scrollTopRef.current
+          : clampFocusRow(false, eventY, scrollTopRef.current, messageHeightRef.current, rowsRef.current, dialogOpenRef.current),
+      setPointerArea: (value: boolean) => {
+        pointerSessionRef.current = { inMessageArea: value }
+      },
+      onScrollbarDown,
+      onScrollbarDrag,
+      stopDragScroll,
+      updateDragScroll,
+      setSelection,
+      getSelection: () => selectionRef.current,
+      rowHasText: (y: number) => screenRef.current?.rowHasText(y) ?? false,
+      rowInfoAt: (y: number) => {
+        const contentRow = toContentRow(y)
+        return rowInfoAt(messagesRef.current, widthRef.current, contentRow)
+      },
+      inputClickAt: (y: number, x: number) => inputHandleRef.current?.current?.clickAt(y, x),
+      panelClickAt: (y: number, x: number) => panelHandleRef.current?.current?.clickAt(y, x),
+      dialogWheel: (y: number, dir: -1 | 1) => onDialogWheelRef.current?.(y, dir) === true,
+      panelWheel: (dir: -1 | 1) => panelHandleRef.current?.current?.wheel(dir) === true,
+      hintWheel: (dir: -1 | 1) => inputHandleRef.current?.current?.hintWheel(dir),
+      inputWheel: (dir: -1 | 1) => inputHandleRef.current?.current?.wheel(dir),
+      hintPress: (x: number, y: number) => onHintPressRef.current?.(x, y),
+      hintDragStart: (x: number, y: number) => onHintDragStartRef.current?.(x, y),
+      hintDragMove: (x: number, y: number) => onHintDragMoveRef.current?.(x, y),
+      hintRelease: (x: number, y: number, dragged: boolean) => onHintReleaseRef.current?.(x, y, dragged),
+      onScroll: (next: number) => onScrollRef.current(next),
+      toggleMessage: (id: string) => onToggleMessageRef.current(id),
+      dialogClick: (y: number, x: number) => onDialogClickRef.current(y, x),
+    }
+    const builtinHandler: BuiltinPointerHandler = createBuiltinPointerHandler(builtinDeps)
+    let ownerId: string | null = null
+    const controller = createMouseController(rawEvent => {
+      const frame = { event: rawEvent, session, ui: uiContext() }
+      // The builtin composite participates in the same dispatch chain as
+      // plugin handlers, sorted by order (builtin at 100, plugin default 300).
+      const entries = [
+        { key: builtinHandler.id, order: POINTER_BUILTIN_ORDER, value: builtinHandler as PointerHandlerContribution },
+        ...pointerHandlerEntries(),
+      ].sort((a, b) => a.order - b.order)
+      const entryFor = (id: string | null) => entries.find(entry => entry.key === id)
+      switch (rawEvent.type) {
+        case 'down': {
+          if (rawEvent.button !== 0) return
+          builtinHandler.beginDown()
+          ownerId = null
+          for (const entry of entries) {
+            if (entry.value.onDown(frame) === true) {
+              ownerId = entry.key
+              return
+            }
+          }
+          // Dead click on unclaimed space (blank rows, padding): drop any
+          // lingering selection, matching native text-editor behavior.
+          setSelection(null)
+          return
+        }
+        case 'drag': {
+          entryFor(ownerId)?.value.onDrag?.(frame)
+          return
+        }
+        case 'up': {
+          stopDragScroll()
+          pointerSessionRef.current = { inMessageArea: false }
+          entryFor(ownerId)?.value.onUp?.(frame)
+          ownerId = null
+          return
+        }
+        case 'scroll': {
+          for (const entry of entries) {
+            if (entry.value.onWheel?.(frame) === true) return
+          }
+          return
+        }
+        default:
+          return
+      }
+    })
+    controller.enable()
+    return () => {
+      controller.disable()
+      stopDragScroll()
+    }
+  }, [])
+  const screenSelection = useMemo(
+    () => toScreenSelection(selection, scrollTop, messageHeight),
+    [selection, scrollTop, messageHeight],
+  )
+  const messageAreaSelection = useMemo(
+    () => (selection !== null && selection.inMessage ? screenSelection : null),
+    [selection, screenSelection],
+  )
+  const chromeSelection = useMemo(
+    () => (selection !== null && !selection.inMessage ? screenSelection : null),
+    [selection, screenSelection],
+  )
+  return {
+    selection,
+    messageAreaSelection,
+    chromeSelection,
+    setSelection,
+    clearSelection() {
+      setSelection(null)
+    },
+  }
+}

package/src/ui/hooks/use-scroll.ts

@@ -0,0 +1,49 @@
+import { useCallback, useReducer, useRef } from 'react'
+
+export interface ScrollSnapshot {
+  top: number
+  maxScroll: number
+}
+
+export interface ScrollState {
+  scrollTop: number
+  getScroll(): ScrollSnapshot
+  applyScroll(next: number): void
+}
+
+/**
+ * The effective scroll offset is derived during render: when pinned to the
+ * bottom the offset is simply maxScroll, so incoming messages shift the view
+ * without a second render pass (the previous layout-effect bump rendered the
+ * whole App twice per streaming frame). Only explicit scroll commands commit
+ * and re-render.
+ */
+export function useScroll(total: number, messageHeight: number): ScrollState {
+  const maxScroll = Math.max(0, total - messageHeight)
+  const [, bump] = useReducer((count: number) => count + 1, 0)
+  const scrollTopRef = useRef(0)
+  const stickToBottomRef = useRef(true)
+  const maxScrollRef = useRef(maxScroll)
+  maxScrollRef.current = maxScroll
+  if (stickToBottomRef.current) {
+    scrollTopRef.current = maxScroll
+  } else if (scrollTopRef.current > maxScroll) {
+    scrollTopRef.current = maxScroll
+    stickToBottomRef.current = scrollTopRef.current >= maxScroll
+  }
+
+  const commit = useCallback((next: number, rerender: boolean): void => {
+    const clamped = Math.max(0, Math.min(maxScrollRef.current, next))
+    scrollTopRef.current = clamped
+    stickToBottomRef.current = clamped >= maxScrollRef.current
+    if (rerender) bump()
+  }, [bump])
+
+  const applyScroll = useCallback((next: number): void => {
+    commit(next === Infinity ? maxScrollRef.current : next, true)
+  }, [commit])
+
+  const getScroll = useCallback((): ScrollSnapshot => ({ top: scrollTopRef.current, maxScroll: maxScrollRef.current }), [])
+
+  return { scrollTop: scrollTopRef.current, getScroll, applyScroll }
+}

package/src/ui/hooks/use-terminal-size.ts

@@ -0,0 +1,20 @@
+import { useEffect, useState } from 'react'
+import { useStdout } from 'ink'
+
+export function useTerminalSize(): { columns: number; rows: number } {
+  const { stdout } = useStdout()
+  const [columns, setColumns] = useState(stdout?.columns ?? 80)
+  const [rows, setRows] = useState(stdout?.rows ?? 24)
+  useEffect(() => {
+    if (!stdout) return
+    const onResize = () => {
+      setColumns(stdout.columns)
+      setRows(stdout.rows)
+    }
+    stdout.on('resize', onResize)
+    return () => {
+      stdout.off('resize', onResize)
+    }
+  }, [stdout])
+  return { columns, rows }
+}

package/src/ui/input/commands.ts

@@ -0,0 +1,118 @@
+import { useSyncExternalStore } from 'react'
+import { keyedRegistry } from '../../kernel/registry.ts'
+import { matchHintEntries } from '../chrome/hint-service.ts'
+import type { CommandDef } from '../../contract/index.ts'
+
+export type { CommandDef } from '../../contract/index.ts'
+
+export type CommandId = string
+
+export interface CommandHintItem {
+  command: string
+  description: string
+  hint?: string
+}
+
+const registry = keyedRegistry<CommandDef>()
+
+export const COMMANDS: CommandDef[] = []
+
+let version = 0
+
+function refresh(): void {
+  version += 1
+  COMMANDS.length = 0
+  COMMANDS.push(...registry.values())
+}
+
+registry.register('new', { id: 'new', command: '/new', description: 'Start a new conversation in current directory' })
+registry.register('todo', { id: 'todo', command: '/todo', description: 'Show the current task list' })
+refresh()
+registry.subscribe(refresh)
+
+export function registerCommand(def: CommandDef): () => void {
+  return registry.register(def.id, def, { order: def.order })
+}
+
+export function subscribeCommands(listener: () => void): () => void {
+  return registry.subscribe(listener)
+}
+
+export function useCommandVersion(): number {
+  return useSyncExternalStore(subscribeCommands, () => version, () => version)
+}
+
+export function matchCommand(text: string): CommandDef | undefined {
+  return registry.values().find(command => command.command === text)
+}
+
+export type CommandAvailability = (command: CommandDef) => boolean
+
+export function matchAvailableCommand(text: string, isAvailable?: CommandAvailability, extra?: readonly CommandDef[]): CommandDef | undefined {
+  const token = text.split(/\s+/, 1)[0] ?? ''
+  const command = [...registry.values(), ...extra ?? []].find(entry => entry.command === token)
+  if (command === undefined) return undefined
+  if (isAvailable !== undefined && !isAvailable(command)) return undefined
+  return command
+}
+
+export function commandArgHints(name: string): readonly string[] | undefined {
+  const def = registry.values().find(candidate => candidate.command === `/${name}`)
+  return def?.args
+}
+
+export function mergeCommandEntries(
+  local: CommandDef[],
+  remote: readonly { name: string; description: string; hint?: string }[],
+): CommandHintItem[] {
+  const taken = new Set(local.map(command => command.command))
+  const entries: CommandHintItem[] = local.map(({ command, description, hint }) => ({
+    command,
+    description,
+    ...(hint === undefined ? {} : { hint }),
+  }))
+  for (const entry of remote) {
+    const command = `/${entry.name}`
+    if (taken.has(command)) continue
+    taken.add(command)
+    entries.push({
+      command,
+      description: entry.description,
+      ...(entry.hint === undefined ? {} : { hint: entry.hint }),
+    })
+  }
+  return entries
+}
+
+function isSubsequence(query: string, text: string): boolean {
+  let at = 0
+  for (let index = 0; index < text.length && at < query.length; index++) {
+    if (text[index] === query[at]) at += 1
+  }
+  return at === query.length
+}
+
+export function filterHintEntries(entries: readonly CommandHintItem[], value: string): CommandHintItem[] {
+  if (!value.startsWith('/') || /\s/.test(value)) return []
+  return matchHintEntries(entries, value)
+}
+
+/** Static literal arguments for registry commands whose hints mix literals with free-form prose. */
+export const KNOWN_COMMAND_ARGS: Record<string, readonly string[]> = {
+  plan: ['off'],
+}
+
+export function literalHintArgs(hint: string | undefined): string[] {
+  if (hint === undefined || hint === '') return []
+  const body = hint.replace(/^\[/, '').replace(/\]$/, '')
+  return body
+    .split('|')
+    .map(part => part.trim())
+    .filter(part => part !== '' && !part.includes('<'))
+}
+
+export interface CommandHintState {
+  commands: CommandHintItem[]
+  selectedIndex: number
+  startIndex?: number
+}

package/src/ui/input/composer-bus.ts

@@ -0,0 +1,14 @@
+import type { ComposerInsertSpec } from '../../contract/index.ts'
+
+type ComposerInserter = (spec: ComposerInsertSpec) => boolean
+
+let inserter: ComposerInserter | undefined
+
+export function setComposerInserter(next: ComposerInserter | undefined): void {
+  inserter = next
+}
+
+export function insertIntoComposer(spec: ComposerInsertSpec): boolean {
+  if (inserter === undefined) return false
+  return inserter(spec)
+}

package/src/ui/input/composer-fields.ts

@@ -0,0 +1,111 @@
+import {
+  allocateField,
+  charactersChipLabel,
+  fieldExpandOf,
+  imageChipLabel,
+  isFieldChar,
+  linesChipLabel,
+  releaseUnreferenced,
+} from '../../core/fields.ts'
+import { classifyPaste, summarizePaste } from '../../core/paste.ts'
+import type { PendingImage } from '../../core/paste.ts'
+import type { ClipboardImage } from '../../terminal/clipboard.ts'
+
+export interface ComposerField {
+  kind: string
+  label: string
+  images?: PendingImage[]
+  text?: string
+  data?: unknown
+}
+
+export type ComposerFieldMap = Map<string, ComposerField>
+
+export function buildPasteFields(normalized: string, fields: ComposerFieldMap): string {
+  const segments = classifyPaste(normalized)
+  let value = ''
+  for (const segment of segments) {
+    if (segment.type === 'images') {
+      value += insertImageField(segment.paths.map(path => ({ kind: 'path' as const, path })), fields)
+      continue
+    }
+    const summary = summarizePaste(segment.text)
+    if (summary === null) {
+      value += segment.text
+      continue
+    }
+    const label = summary.lines > 1 ? linesChipLabel(summary.lines) : charactersChipLabel(summary.characters)
+    const char = allocateField('paste', label, 'composer')
+    if (char === null) {
+      value += segment.text
+      continue
+    }
+    fields.set(char, { kind: 'paste', label, text: segment.text })
+    value += char
+  }
+  return value
+}
+
+export function insertImageField(images: PendingImage[], fields: ComposerFieldMap): string {
+  if (images.length === 0) return ''
+  const label = imageChipLabel(images.length)
+  const char = allocateField('image', label, 'composer')
+  if (char === null) return images.length === 1 && images[0]!.kind === 'path' ? images[0]!.path : label
+  fields.set(char, { kind: 'image', label, images })
+  return char
+}
+
+export function insertClipboardImage(image: ClipboardImage, fields: ComposerFieldMap): string {
+  return insertImageField([{
+    kind: 'data',
+    data: image.data,
+    mediaType: image.mediaType,
+    name: 'clipboard',
+  }], fields)
+}
+
+export function insertFieldSpec(
+  spec: { kind: string; label: string; data?: unknown },
+  fields: ComposerFieldMap,
+): string {
+  const char = allocateField(spec.kind, spec.label, 'composer')
+  if (char === null) return spec.label
+  let field: ComposerField
+  if (spec.kind === 'paste') {
+    field = { kind: 'paste', label: spec.label, text: typeof spec.data === 'string' ? spec.data : spec.label }
+  } else if (spec.kind === 'image' && Array.isArray(spec.data)) {
+    field = { kind: 'image', label: spec.label, images: spec.data as PendingImage[] }
+  } else {
+    field = { kind: spec.kind, label: spec.label, data: spec.data }
+  }
+  fields.set(char, field)
+  return char
+}
+
+export function reconcileComposerFields(value: string, fields: ComposerFieldMap): void {
+  for (const char of fields.keys()) {
+    if (!value.includes(char)) fields.delete(char)
+  }
+  releaseUnreferenced('composer', value)
+}
+
+export interface ComposerSubmission {
+  text: string
+  images: PendingImage[][]
+}
+
+export function expandComposerValue(value: string, fields: ComposerFieldMap): ComposerSubmission {
+  let text = ''
+  const images: PendingImage[][] = []
+  for (const char of value) {
+    const field = isFieldChar(char) ? fields.get(char) : undefined
+    if (field === undefined) {
+      text += char
+      continue
+    }
+    if (field.kind === 'paste') text += field.text ?? ''
+    else if (field.kind === 'image' && (field.images ?? []).length > 0) images.push(field.images!)
+    else text += fieldExpandOf(field.kind)?.(field.data) ?? field.label
+  }
+  return { text: text.trim(), images }
+}

package/src/ui/input/composer-keys.ts

@@ -0,0 +1,21 @@
+import { keyedRegistry } from '../../kernel/registry.ts'
+import type { TuiKey } from '../../contract/index.ts'
+
+export interface ComposerKeyBinding {
+  id: string
+  order?: number
+  handle(input: string, key: TuiKey): boolean
+}
+
+const bindings = keyedRegistry<ComposerKeyBinding>()
+
+export function registerComposerKeyBinding(binding: ComposerKeyBinding): () => void {
+  return bindings.register(binding.id, binding, { order: binding.order })
+}
+
+export function handleComposerKeyBindings(input: string, key: TuiKey): boolean {
+  for (const binding of bindings.values()) {
+    if (binding.handle(input, key) === true) return true
+  }
+  return false
+}