subagent-cli 0.3.0 → 0.3.1

package/src/ink/hooks/use-declared-cursor.ts

@@ -1,73 +0,0 @@
-import { useCallback, useContext, useLayoutEffect, useRef } from 'react'
-import CursorDeclarationContext from '../components/CursorDeclarationContext.js'
-import type { DOMElement } from '../dom.js'
-
-/**
- * Declares where the terminal cursor should be parked after each frame.
- *
- * Terminal emulators render IME preedit text at the physical cursor
- * position, and screen readers / screen magnifiers track the native
- * cursor — so parking it at the text input's caret makes CJK input
- * appear inline and lets accessibility tools follow the input.
- *
- * Returns a ref callback to attach to the Box that contains the input.
- * The declared (line, column) is interpreted relative to that Box's
- * nodeCache rect (populated by renderNodeToOutput).
- *
- * Timing: Both ref attach and useLayoutEffect fire in React's layout
- * phase — after resetAfterCommit calls scheduleRender. scheduleRender
- * defers onRender via queueMicrotask, so onRender runs AFTER layout
- * effects commit and reads the fresh declaration on the first frame
- * (no one-keystroke lag). Test env uses onImmediateRender (synchronous,
- * no microtask), so tests compensate by calling ink.onRender()
- * explicitly after render.
- */
-export function useDeclaredCursor({
-  line,
-  column,
-  active,
-}: {
-  line: number
-  column: number
-  active: boolean
-}): (element: DOMElement | null) => void {
-  const setCursorDeclaration = useContext(CursorDeclarationContext)
-  const nodeRef = useRef<DOMElement | null>(null)
-
-  const setNode = useCallback((node: DOMElement | null) => {
-    nodeRef.current = node
-  }, [])
-
-  // When active, set unconditionally. When inactive, clear conditionally
-  // (only if the currently-declared node is ours). The node-identity check
-  // handles two hazards:
-  //   1. A memo()ized active instance elsewhere (e.g. the search input in
-  //      a memo'd Footer) doesn't re-render this commit — an inactive
-  //      instance re-rendering here must not clobber it.
-  //   2. Sibling handoff (menu focus moving between list items) — when
-  //      focus moves opposite to sibling order, the newly-inactive item's
-  //      effect runs AFTER the newly-active item's set. Without the node
-  //      check it would clobber.
-  // No dep array: must re-declare every commit so the active instance
-  // re-claims the declaration after another instance's unmount-cleanup or
-  // sibling handoff nulls it.
-  useLayoutEffect(() => {
-    const node = nodeRef.current
-    if (active && node) {
-      setCursorDeclaration({ relativeX: column, relativeY: line, node })
-    } else {
-      setCursorDeclaration(null, node)
-    }
-  })
-
-  // Clear on unmount (conditionally — another instance may own by then).
-  // Separate effect with empty deps so cleanup only fires once — not on
-  // every line/column change, which would transiently null between commits.
-  useLayoutEffect(() => {
-    return () => {
-      setCursorDeclaration(null, nodeRef.current)
-    }
-  }, [setCursorDeclaration])
-
-  return setNode
-}

package/src/ink/hooks/use-input.ts

@@ -1,92 +0,0 @@
-import { useEffect, useLayoutEffect } from 'react'
-import { useEventCallback } from 'usehooks-ts'
-import type { InputEvent, Key } from '../events/input-event.js'
-import useStdin from './use-stdin.js'
-
-type Handler = (input: string, key: Key, event: InputEvent) => void
-
-type Options = {
-  /**
-   * Enable or disable capturing of user input.
-   * Useful when there are multiple useInput hooks used at once to avoid handling the same input several times.
-   *
-   * @default true
-   */
-  isActive?: boolean
-}
-
-/**
- * This hook is used for handling user input.
- * It's a more convenient alternative to using `StdinContext` and listening to `data` events.
- * The callback you pass to `useInput` is called for each character when user enters any input.
- * However, if user pastes text and it's more than one character, the callback will be called only once and the whole string will be passed as `input`.
- *
- * ```
- * import {useInput} from 'ink';
- *
- * const UserInput = () => {
- *   useInput((input, key) => {
- *     if (input === 'q') {
- *       // Exit program
- *     }
- *
- *     if (key.leftArrow) {
- *       // Left arrow key pressed
- *     }
- *   });
- *
- *   return …
- * };
- * ```
- */
-const useInput = (inputHandler: Handler, options: Options = {}) => {
-  const { setRawMode, internal_exitOnCtrlC, internal_eventEmitter } = useStdin()
-
-  // useLayoutEffect (not useEffect) so that raw mode is enabled synchronously
-  // during React's commit phase, before render() returns. With useEffect, raw
-  // mode setup is deferred to the next event loop tick via React's scheduler,
-  // leaving the terminal in cooked mode — keystrokes echo and the cursor is
-  // visible until the effect fires.
-  useLayoutEffect(() => {
-    if (options.isActive === false) {
-      return
-    }
-
-    setRawMode(true)
-
-    return () => {
-      setRawMode(false)
-    }
-  }, [options.isActive, setRawMode])
-
-  // Register the listener once on mount so its slot in the EventEmitter's
-  // listener array is stable. If isActive were in the effect's deps, the
-  // listener would re-append on false→true, moving it behind listeners
-  // that registered while it was inactive — breaking
-  // stopImmediatePropagation() ordering. useEventCallback keeps the
-  // reference stable while reading latest isActive/inputHandler from
-  // closure (it syncs via useLayoutEffect, so it's compiler-safe).
-  const handleData = useEventCallback((event: InputEvent) => {
-    if (options.isActive === false) {
-      return
-    }
-    const { input, key } = event
-
-    // If app is not supposed to exit on Ctrl+C, then let input listener handle it
-    // Note: discreteUpdates is called at the App level when emitting events,
-    // so all listeners are already within a high-priority update context.
-    if (!(input === 'c' && key.ctrl) || !internal_exitOnCtrlC) {
-      inputHandler(input, key, event)
-    }
-  })
-
-  useEffect(() => {
-    internal_eventEmitter?.on('input', handleData)
-
-    return () => {
-      internal_eventEmitter?.removeListener('input', handleData)
-    }
-  }, [internal_eventEmitter, handleData])
-}
-
-export default useInput

package/src/ink/hooks/use-interval.ts

@@ -1,67 +0,0 @@
-import { useContext, useEffect, useRef, useState } from 'react'
-import { ClockContext } from '../components/ClockContext.js'
-
-/**
- * Returns the clock time, updating at the given interval.
- * Subscribes as non-keepAlive — won't keep the clock alive on its own,
- * but updates whenever a keepAlive subscriber (e.g. the spinner)
- * is driving the clock.
- *
- * Use this to drive pure time-based computations (shimmer position,
- * frame index) from the shared clock.
- */
-export function useAnimationTimer(intervalMs: number): number {
-  const clock = useContext(ClockContext)
-  const [time, setTime] = useState(() => clock?.now() ?? 0)
-
-  useEffect(() => {
-    if (!clock) return
-
-    let lastUpdate = clock.now()
-
-    const onChange = (): void => {
-      const now = clock.now()
-      if (now - lastUpdate >= intervalMs) {
-        lastUpdate = now
-        setTime(now)
-      }
-    }
-
-    return clock.subscribe(onChange, false)
-  }, [clock, intervalMs])
-
-  return time
-}
-
-/**
- * Interval hook backed by the shared Clock.
- *
- * Unlike `useInterval` from `usehooks-ts` (which creates its own setInterval),
- * this piggybacks on the single shared clock so all timers consolidate into
- * one wake-up. Pass `null` for intervalMs to pause.
- */
-export function useInterval(
-  callback: () => void,
-  intervalMs: number | null,
-): void {
-  const callbackRef = useRef(callback)
-  callbackRef.current = callback
-
-  const clock = useContext(ClockContext)
-
-  useEffect(() => {
-    if (!clock || intervalMs === null) return
-
-    let lastUpdate = clock.now()
-
-    const onChange = (): void => {
-      const now = clock.now()
-      if (now - lastUpdate >= intervalMs) {
-        lastUpdate = now
-        callbackRef.current()
-      }
-    }
-
-    return clock.subscribe(onChange, false)
-  }, [clock, intervalMs])
-}

package/src/ink/hooks/use-search-highlight.ts

@@ -1,53 +0,0 @@
-import { useContext, useMemo } from 'react'
-import StdinContext from '../components/StdinContext.js'
-import type { DOMElement } from '../dom.js'
-import instances from '../instances.js'
-import type { MatchPosition } from '../render-to-screen.js'
-
-/**
- * Set the search highlight query on the Ink instance. Non-empty → all
- * visible occurrences are inverted on the next frame (SGR 7, screen-buffer
- * overlay, same damage machinery as selection). Empty → clears.
- *
- * This is a screen-space highlight — it matches the RENDERED text, not the
- * source message text. Works for anything visible (bash output, file paths,
- * error messages) regardless of where it came from in the message tree. A
- * query that matched in source but got truncated/ellipsized in rendering
- * won't highlight; that's acceptable — we highlight what you see.
- */
-export function useSearchHighlight(): {
-  setQuery: (query: string) => void
-  /** Paint an existing DOM subtree (from the MAIN tree) to a fresh
-   *  Screen at its natural height, scan. Element-relative positions
-   *  (row 0 = element top). Zero context duplication — the element
-   *  IS the one built with all real providers. */
-  scanElement: (el: DOMElement) => MatchPosition[]
-  /** Position-based CURRENT highlight. Every frame writes yellow at
-   *  positions[currentIdx] + rowOffset. The scan-highlight (inverse on
-   *  all matches) still runs — this overlays on top. rowOffset tracks
-   *  scroll; positions stay stable (message-relative). null clears. */
-  setPositions: (
-    state: {
-      positions: MatchPosition[]
-      rowOffset: number
-      currentIdx: number
-    } | null,
-  ) => void
-} {
-  useContext(StdinContext) // anchor to App subtree for hook rules
-  const ink = instances.get(process.stdout)
-  return useMemo(() => {
-    if (!ink) {
-      return {
-        setQuery: () => {},
-        scanElement: () => [],
-        setPositions: () => {},
-      }
-    }
-    return {
-      setQuery: (query: string) => ink.setSearchHighlight(query),
-      scanElement: (el: DOMElement) => ink.scanElementSubtree(el),
-      setPositions: state => ink.setSearchPositions(state),
-    }
-  }, [ink])
-}

package/src/ink/hooks/use-selection.ts

@@ -1,104 +0,0 @@
-import { useContext, useMemo, useSyncExternalStore } from 'react'
-import StdinContext from '../components/StdinContext.js'
-import instances from '../instances.js'
-import {
-  type FocusMove,
-  type SelectionState,
-  shiftAnchor,
-} from '../selection.js'
-
-/**
- * Access to text selection operations on the Ink instance (fullscreen only).
- * Returns no-op functions when fullscreen mode is disabled.
- */
-export function useSelection(): {
-  copySelection: () => string
-  /** Copy without clearing the highlight (for copy-on-select). */
-  copySelectionNoClear: () => string
-  clearSelection: () => void
-  hasSelection: () => boolean
-  /** Read the raw mutable selection state (for drag-to-scroll). */
-  getState: () => SelectionState | null
-  /** Subscribe to selection mutations (start/update/finish/clear). */
-  subscribe: (cb: () => void) => () => void
-  /** Shift the anchor row by dRow, clamped to [minRow, maxRow]. */
-  shiftAnchor: (dRow: number, minRow: number, maxRow: number) => void
-  /** Shift anchor AND focus by dRow (keyboard scroll: whole selection
-   *  tracks content). Clamped points get col reset to the full-width edge
-   *  since their content was captured by captureScrolledRows. Reads
-   *  screen.width from the ink instance for the col-reset boundary. */
-  shiftSelection: (dRow: number, minRow: number, maxRow: number) => void
-  /** Keyboard selection extension (shift+arrow): move focus, anchor fixed.
-   *  Left/right wrap across rows; up/down clamp at viewport edges. */
-  moveFocus: (move: FocusMove) => void
-  /** Capture text from rows about to scroll out of the viewport (call
-   *  BEFORE scrollBy so the screen buffer still has the outgoing rows). */
-  captureScrolledRows: (
-    firstRow: number,
-    lastRow: number,
-    side: 'above' | 'below',
-  ) => void
-  /** Set the selection highlight bg color (theme-piping; solid bg
-   *  replaces the old SGR-7 inverse so syntax highlighting stays readable
-   *  under selection). Call once on mount + whenever theme changes. */
-  setSelectionBgColor: (color: string) => void
-} {
-  // Look up the Ink instance via stdout — same pattern as instances map.
-  // StdinContext is available (it's always provided), and the Ink instance
-  // is keyed by stdout which we can get from process.stdout since there's
-  // only one Ink instance per process in practice.
-  useContext(StdinContext) // anchor to App subtree for hook rules
-  const ink = instances.get(process.stdout)
-  // Memoize so callers can safely use the return value in dependency arrays.
-  // ink is a singleton per stdout — stable across renders.
-  return useMemo(() => {
-    if (!ink) {
-      return {
-        copySelection: () => '',
-        copySelectionNoClear: () => '',
-        clearSelection: () => {},
-        hasSelection: () => false,
-        getState: () => null,
-        subscribe: () => () => {},
-        shiftAnchor: () => {},
-        shiftSelection: () => {},
-        moveFocus: () => {},
-        captureScrolledRows: () => {},
-        setSelectionBgColor: () => {},
-      }
-    }
-    return {
-      copySelection: () => ink.copySelection(),
-      copySelectionNoClear: () => ink.copySelectionNoClear(),
-      clearSelection: () => ink.clearTextSelection(),
-      hasSelection: () => ink.hasTextSelection(),
-      getState: () => ink.selection,
-      subscribe: (cb: () => void) => ink.subscribeToSelectionChange(cb),
-      shiftAnchor: (dRow: number, minRow: number, maxRow: number) =>
-        shiftAnchor(ink.selection, dRow, minRow, maxRow),
-      shiftSelection: (dRow, minRow, maxRow) =>
-        ink.shiftSelectionForScroll(dRow, minRow, maxRow),
-      moveFocus: (move: FocusMove) => ink.moveSelectionFocus(move),
-      captureScrolledRows: (firstRow, lastRow, side) =>
-        ink.captureScrolledRows(firstRow, lastRow, side),
-      setSelectionBgColor: (color: string) => ink.setSelectionBgColor(color),
-    }
-  }, [ink])
-}
-
-const NO_SUBSCRIBE = () => () => {}
-const ALWAYS_FALSE = () => false
-
-/**
- * Reactive selection-exists state. Re-renders the caller when a text
- * selection is created or cleared. Always returns false outside
- * fullscreen mode (selection is only available in alt-screen).
- */
-export function useHasSelection(): boolean {
-  useContext(StdinContext)
-  const ink = instances.get(process.stdout)
-  return useSyncExternalStore(
-    ink ? ink.subscribeToSelectionChange : NO_SUBSCRIBE,
-    ink ? ink.hasTextSelection : ALWAYS_FALSE,
-  )
-}

package/src/ink/hooks/use-stdin.ts

@@ -1,8 +0,0 @@
-import { useContext } from 'react'
-import StdinContext from '../components/StdinContext.js'
-
-/**
- * `useStdin` is a React hook, which exposes stdin stream.
- */
-const useStdin = () => useContext(StdinContext)
-export default useStdin

package/src/ink/hooks/use-tab-status.ts

@@ -1,72 +0,0 @@
-import { useContext, useEffect, useRef } from 'react'
-import {
-  CLEAR_TAB_STATUS,
-  supportsTabStatus,
-  tabStatus,
-  wrapForMultiplexer,
-} from '../termio/osc.js'
-import type { Color } from '../termio/types.js'
-import { TerminalWriteContext } from '../useTerminalNotification.js'
-
-export type TabStatusKind = 'idle' | 'busy' | 'waiting'
-
-const rgb = (r: number, g: number, b: number): Color => ({
-  type: 'rgb',
-  r,
-  g,
-  b,
-})
-
-// Per the OSC 21337 usage guide's suggested mapping.
-const TAB_STATUS_PRESETS: Record<
-  TabStatusKind,
-  { indicator: Color; status: string; statusColor: Color }
-> = {
-  idle: {
-    indicator: rgb(0, 215, 95),
-    status: 'Idle',
-    statusColor: rgb(136, 136, 136),
-  },
-  busy: {
-    indicator: rgb(255, 149, 0),
-    status: 'Working…',
-    statusColor: rgb(255, 149, 0),
-  },
-  waiting: {
-    indicator: rgb(95, 135, 255),
-    status: 'Waiting',
-    statusColor: rgb(95, 135, 255),
-  },
-}
-
-/**
- * Declaratively set the tab-status indicator (OSC 21337).
- *
- * Emits a colored dot + short status text to the tab sidebar. Terminals
- * that don't support OSC 21337 discard the sequence silently, so this is
- * safe to call unconditionally. Wrapped for tmux/screen passthrough.
- *
- * Pass `null` to opt out. If a status was previously set, transitioning to
- * `null` emits CLEAR_TAB_STATUS so toggling off mid-session doesn't leave
- * a stale dot. Process-exit cleanup is handled by ink.tsx's unmount path.
- */
-export function useTabStatus(kind: TabStatusKind | null): void {
-  const writeRaw = useContext(TerminalWriteContext)
-  const prevKindRef = useRef<TabStatusKind | null>(null)
-
-  useEffect(() => {
-    // When kind transitions from non-null to null (e.g. user toggles off
-    // showStatusInTerminalTab mid-session), clear the stale dot.
-    if (kind === null) {
-      if (prevKindRef.current !== null && writeRaw && supportsTabStatus()) {
-        writeRaw(wrapForMultiplexer(CLEAR_TAB_STATUS))
-      }
-      prevKindRef.current = null
-      return
-    }
-
-    prevKindRef.current = kind
-    if (!writeRaw || !supportsTabStatus()) return
-    writeRaw(wrapForMultiplexer(tabStatus(TAB_STATUS_PRESETS[kind])))
-  }, [kind, writeRaw])
-}

package/src/ink/hooks/use-terminal-focus.ts

@@ -1,16 +0,0 @@
-import { useContext } from 'react'
-import TerminalFocusContext from '../components/TerminalFocusContext.js'
-
-/**
- * Hook to check if the terminal has focus.
- *
- * Uses DECSET 1004 focus reporting - the terminal sends escape sequences
- * when it gains or loses focus. These are handled automatically
- * by Ink and filtered from useInput.
- *
- * @returns true if the terminal is focused (or focus state is unknown)
- */
-export function useTerminalFocus(): boolean {
-  const { isTerminalFocused } = useContext(TerminalFocusContext)
-  return isTerminalFocused
-}

package/src/ink/hooks/use-terminal-title.ts

@@ -1,31 +0,0 @@
-import { useContext, useEffect } from 'react'
-import stripAnsi from 'strip-ansi'
-import { OSC, osc } from '../termio/osc.js'
-import { TerminalWriteContext } from '../useTerminalNotification.js'
-
-/**
- * Declaratively set the terminal tab/window title.
- *
- * Pass a string to set the title. ANSI escape sequences are stripped
- * automatically so callers don't need to know about terminal encoding.
- * Pass `null` to opt out — the hook becomes a no-op and leaves the
- * terminal title untouched.
- *
- * On Windows, uses `process.title` (classic conhost doesn't support OSC).
- * Elsewhere, writes OSC 0 (set title+icon) via Ink's stdout.
- */
-export function useTerminalTitle(title: string | null): void {
-  const writeRaw = useContext(TerminalWriteContext)
-
-  useEffect(() => {
-    if (title === null || !writeRaw) return
-
-    const clean = stripAnsi(title)
-
-    if (process.platform === 'win32') {
-      process.title = clean
-    } else {
-      writeRaw(osc(OSC.SET_TITLE_AND_ICON, clean))
-    }
-  }, [title, writeRaw])
-}

package/src/ink/hooks/use-terminal-viewport.ts

@@ -1,96 +0,0 @@
-import { useCallback, useContext, useLayoutEffect, useRef } from 'react'
-import { TerminalSizeContext } from '../components/TerminalSizeContext.js'
-import type { DOMElement } from '../dom.js'
-
-type ViewportEntry = {
-  /**
-   * Whether the element is currently within the terminal viewport
-   */
-  isVisible: boolean
-}
-
-/**
- * Hook to detect if a component is within the terminal viewport.
- *
- * Returns a callback ref and a viewport entry object.
- * Attach the ref to the component you want to track.
- *
- * The entry is updated during the layout phase (useLayoutEffect) so callers
- * always read fresh values during render. Visibility changes do NOT trigger
- * re-renders on their own — callers that re-render for other reasons (e.g.
- * animation ticks, state changes) will pick up the latest value naturally.
- * This avoids infinite update loops when combined with other layout effects
- * that also call setState.
- *
- * @example
- * const [ref, entry] = useTerminalViewport()
- * return <Box ref={ref}><Animation enabled={entry.isVisible}>...</Animation></Box>
- */
-export function useTerminalViewport(): [
-  ref: (element: DOMElement | null) => void,
-  entry: ViewportEntry,
-] {
-  const terminalSize = useContext(TerminalSizeContext)
-  const elementRef = useRef<DOMElement | null>(null)
-  const entryRef = useRef<ViewportEntry>({ isVisible: true })
-
-  const setElement = useCallback((el: DOMElement | null) => {
-    elementRef.current = el
-  }, [])
-
-  // Runs on every render because yoga layout values can change
-  // without React being aware. Only updates the ref — no setState
-  // to avoid cascading re-renders during the commit phase.
-  // Walks the DOM ancestor chain fresh each time to avoid holding stale
-  // references after yoga tree rebuilds.
-  useLayoutEffect(() => {
-    const element = elementRef.current
-    if (!element?.yogaNode || !terminalSize) {
-      return
-    }
-
-    const height = element.yogaNode.getComputedHeight()
-    const rows = terminalSize.rows
-
-    // Walk the DOM parent chain (not yoga.getParent()) so we can detect
-    // scroll containers and subtract their scrollTop. Yoga computes layout
-    // positions without scroll offset — scrollTop is applied at render time.
-    // Without this, an element inside a ScrollBox whose yoga position exceeds
-    // terminalRows would be considered offscreen even when scrolled into view
-    // (e.g., the spinner in fullscreen mode after enough messages accumulate).
-    let absoluteTop = element.yogaNode.getComputedTop()
-    let parent: DOMElement | undefined = element.parentNode
-    let root = element.yogaNode
-    while (parent) {
-      if (parent.yogaNode) {
-        absoluteTop += parent.yogaNode.getComputedTop()
-        root = parent.yogaNode
-      }
-      // scrollTop is only ever set on scroll containers (by ScrollBox + renderer).
-      // Non-scroll nodes have undefined scrollTop → falsy fast-path.
-      if (parent.scrollTop) absoluteTop -= parent.scrollTop
-      parent = parent.parentNode
-    }
-
-    // Only the root's height matters
-    const screenHeight = root.getComputedHeight()
-
-    const bottom = absoluteTop + height
-    // When content overflows the viewport (screenHeight > rows), the
-    // cursor-restore at frame end scrolls one extra row into scrollback.
-    // log-update.ts accounts for this with scrollbackRows = viewportY + 1.
-    // We must match, otherwise an element at the boundary is considered
-    // "visible" here (animation keeps ticking) but its row is treated as
-    // scrollback by log-update (content change → full reset → flicker).
-    const cursorRestoreScroll = screenHeight > rows ? 1 : 0
-    const viewportY = Math.max(0, screenHeight - rows) + cursorRestoreScroll
-    const viewportBottom = viewportY + rows
-    const visible = bottom > viewportY && absoluteTop < viewportBottom
-
-    if (visible !== entryRef.current.isVisible) {
-      entryRef.current = { isVisible: visible }
-    }
-  })
-
-  return [setElement, entryRef.current]
-}