@vsuryav/agent-sim 0.1.0

package/src/engine/ink/events/terminal-event.ts

@@ -0,0 +1,107 @@
+import { Event } from './event.js'
+
+type EventPhase = 'none' | 'capturing' | 'at_target' | 'bubbling'
+
+type TerminalEventInit = {
+  bubbles?: boolean
+  cancelable?: boolean
+}
+
+/**
+ * Base class for all terminal events with DOM-style propagation.
+ *
+ * Extends Event so existing event types (ClickEvent, InputEvent,
+ * TerminalFocusEvent) share a common ancestor and can migrate later.
+ *
+ * Mirrors the browser's Event API: target, currentTarget, eventPhase,
+ * stopPropagation(), preventDefault(), timeStamp.
+ */
+export class TerminalEvent extends Event {
+  readonly type: string
+  readonly timeStamp: number
+  readonly bubbles: boolean
+  readonly cancelable: boolean
+
+  private _target: EventTarget | null = null
+  private _currentTarget: EventTarget | null = null
+  private _eventPhase: EventPhase = 'none'
+  private _propagationStopped = false
+  private _defaultPrevented = false
+
+  constructor(type: string, init?: TerminalEventInit) {
+    super()
+    this.type = type
+    this.timeStamp = performance.now()
+    this.bubbles = init?.bubbles ?? true
+    this.cancelable = init?.cancelable ?? true
+  }
+
+  get target(): EventTarget | null {
+    return this._target
+  }
+
+  get currentTarget(): EventTarget | null {
+    return this._currentTarget
+  }
+
+  get eventPhase(): EventPhase {
+    return this._eventPhase
+  }
+
+  get defaultPrevented(): boolean {
+    return this._defaultPrevented
+  }
+
+  stopPropagation(): void {
+    this._propagationStopped = true
+  }
+
+  override stopImmediatePropagation(): void {
+    super.stopImmediatePropagation()
+    this._propagationStopped = true
+  }
+
+  preventDefault(): void {
+    if (this.cancelable) {
+      this._defaultPrevented = true
+    }
+  }
+
+  // -- Internal setters used by the Dispatcher
+
+  /** @internal */
+  _setTarget(target: EventTarget): void {
+    this._target = target
+  }
+
+  /** @internal */
+  _setCurrentTarget(target: EventTarget | null): void {
+    this._currentTarget = target
+  }
+
+  /** @internal */
+  _setEventPhase(phase: EventPhase): void {
+    this._eventPhase = phase
+  }
+
+  /** @internal */
+  _isPropagationStopped(): boolean {
+    return this._propagationStopped
+  }
+
+  /** @internal */
+  _isImmediatePropagationStopped(): boolean {
+    return this.didStopImmediatePropagation()
+  }
+
+  /**
+   * Hook for subclasses to do per-node setup before each handler fires.
+   * Default is a no-op.
+   */
+  _prepareForTarget(_target: EventTarget): void {}
+}
+
+export type EventTarget = {
+  parentNode: EventTarget | undefined
+  _eventHandlers?: Record<string, unknown>
+}

package/src/engine/ink/events/terminal-focus-event.ts

@@ -0,0 +1,19 @@
+import { Event } from './event.js'
+
+export type TerminalFocusEventType = 'terminalfocus' | 'terminalblur'
+
+/**
+ * Event fired when the terminal window gains or loses focus.
+ *
+ * Uses DECSET 1004 focus reporting - the terminal sends:
+ * - CSI I (\x1b[I) when the terminal gains focus
+ * - CSI O (\x1b[O) when the terminal loses focus
+ */
+export class TerminalFocusEvent extends Event {
+  readonly type: TerminalFocusEventType
+
+  constructor(type: TerminalFocusEventType) {
+    super()
+    this.type = type
+  }
+}

package/src/engine/ink/focus.ts

@@ -0,0 +1,181 @@
+import type { DOMElement } from './dom.js'
+import { FocusEvent } from './events/focus-event.js'
+
+const MAX_FOCUS_STACK = 32
+
+/**
+ * DOM-like focus manager for the Ink terminal UI.
+ *
+ * Pure state — tracks activeElement and a focus stack. Has no reference
+ * to the tree; callers pass the root when tree walks are needed.
+ *
+ * Stored on the root DOMElement so any node can reach it by walking
+ * parentNode (like browser's `node.ownerDocument`).
+ */
+export class FocusManager {
+  activeElement: DOMElement | null = null
+  private dispatchFocusEvent: (target: DOMElement, event: FocusEvent) => boolean
+  private enabled = true
+  private focusStack: DOMElement[] = []
+
+  constructor(
+    dispatchFocusEvent: (target: DOMElement, event: FocusEvent) => boolean,
+  ) {
+    this.dispatchFocusEvent = dispatchFocusEvent
+  }
+
+  focus(node: DOMElement): void {
+    if (node === this.activeElement) return
+    if (!this.enabled) return
+
+    const previous = this.activeElement
+    if (previous) {
+      // Deduplicate before pushing to prevent unbounded growth from Tab cycling
+      const idx = this.focusStack.indexOf(previous)
+      if (idx !== -1) this.focusStack.splice(idx, 1)
+      this.focusStack.push(previous)
+      if (this.focusStack.length > MAX_FOCUS_STACK) this.focusStack.shift()
+      this.dispatchFocusEvent(previous, new FocusEvent('blur', node))
+    }
+    this.activeElement = node
+    this.dispatchFocusEvent(node, new FocusEvent('focus', previous))
+  }
+
+  blur(): void {
+    if (!this.activeElement) return
+
+    const previous = this.activeElement
+    this.activeElement = null
+    this.dispatchFocusEvent(previous, new FocusEvent('blur', null))
+  }
+
+  /**
+   * Called by the reconciler when a node is removed from the tree.
+   * Handles both the exact node and any focused descendant within
+   * the removed subtree. Dispatches blur and restores focus from stack.
+   */
+  handleNodeRemoved(node: DOMElement, root: DOMElement): void {
+    // Remove the node and any descendants from the stack
+    this.focusStack = this.focusStack.filter(
+      n => n !== node && isInTree(n, root),
+    )
+
+    // Check if activeElement is the removed node OR a descendant
+    if (!this.activeElement) return
+    if (this.activeElement !== node && isInTree(this.activeElement, root)) {
+      return
+    }
+
+    const removed = this.activeElement
+    this.activeElement = null
+    this.dispatchFocusEvent(removed, new FocusEvent('blur', null))
+
+    // Restore focus to the most recent still-mounted element
+    while (this.focusStack.length > 0) {
+      const candidate = this.focusStack.pop()!
+      if (isInTree(candidate, root)) {
+        this.activeElement = candidate
+        this.dispatchFocusEvent(candidate, new FocusEvent('focus', removed))
+        return
+      }
+    }
+  }
+
+  handleAutoFocus(node: DOMElement): void {
+    this.focus(node)
+  }
+
+  handleClickFocus(node: DOMElement): void {
+    const tabIndex = node.attributes['tabIndex']
+    if (typeof tabIndex !== 'number') return
+    this.focus(node)
+  }
+
+  enable(): void {
+    this.enabled = true
+  }
+
+  disable(): void {
+    this.enabled = false
+  }
+
+  focusNext(root: DOMElement): void {
+    this.moveFocus(1, root)
+  }
+
+  focusPrevious(root: DOMElement): void {
+    this.moveFocus(-1, root)
+  }
+
+  private moveFocus(direction: 1 | -1, root: DOMElement): void {
+    if (!this.enabled) return
+
+    const tabbable = collectTabbable(root)
+    if (tabbable.length === 0) return
+
+    const currentIndex = this.activeElement
+      ? tabbable.indexOf(this.activeElement)
+      : -1
+
+    const nextIndex =
+      currentIndex === -1
+        ? direction === 1
+          ? 0
+          : tabbable.length - 1
+        : (currentIndex + direction + tabbable.length) % tabbable.length
+
+    const next = tabbable[nextIndex]
+    if (next) {
+      this.focus(next)
+    }
+  }
+}
+
+function collectTabbable(root: DOMElement): DOMElement[] {
+  const result: DOMElement[] = []
+  walkTree(root, result)
+  return result
+}
+
+function walkTree(node: DOMElement, result: DOMElement[]): void {
+  const tabIndex = node.attributes['tabIndex']
+  if (typeof tabIndex === 'number' && tabIndex >= 0) {
+    result.push(node)
+  }
+
+  for (const child of node.childNodes) {
+    if (child.nodeName !== '#text') {
+      walkTree(child, result)
+    }
+  }
+}
+
+function isInTree(node: DOMElement, root: DOMElement): boolean {
+  let current: DOMElement | undefined = node
+  while (current) {
+    if (current === root) return true
+    current = current.parentNode
+  }
+  return false
+}
+
+/**
+ * Walk up to root and return it. The root is the node that holds
+ * the FocusManager — like browser's `node.getRootNode()`.
+ */
+export function getRootNode(node: DOMElement): DOMElement {
+  let current: DOMElement | undefined = node
+  while (current) {
+    if (current.focusManager) return current
+    current = current.parentNode
+  }
+  throw new Error('Node is not in a tree with a FocusManager')
+}
+
+/**
+ * Walk up to root and return its FocusManager.
+ * Like browser's `node.ownerDocument` — focus belongs to the root.
+ */
+export function getFocusManager(node: DOMElement): FocusManager {
+  return getRootNode(node).focusManager!
+}

package/src/engine/ink/frame.ts

@@ -0,0 +1,124 @@
+import type { Cursor } from './cursor.js'
+import type { Size } from './layout/geometry.js'
+import type { ScrollHint } from './render-node-to-output.js'
+import {
+  type CharPool,
+  createScreen,
+  type HyperlinkPool,
+  type Screen,
+  type StylePool,
+} from './screen.js'
+
+export type Frame = {
+  readonly screen: Screen
+  readonly viewport: Size
+  readonly cursor: Cursor
+  /** DECSTBM scroll optimization hint (alt-screen only, null otherwise). */
+  readonly scrollHint?: ScrollHint | null
+  /** A ScrollBox has remaining pendingScrollDelta — schedule another frame. */
+  readonly scrollDrainPending?: boolean
+}
+
+export function emptyFrame(
+  rows: number,
+  columns: number,
+  stylePool: StylePool,
+  charPool: CharPool,
+  hyperlinkPool: HyperlinkPool,
+): Frame {
+  return {
+    screen: createScreen(0, 0, stylePool, charPool, hyperlinkPool),
+    viewport: { width: columns, height: rows },
+    cursor: { x: 0, y: 0, visible: true },
+  }
+}
+
+export type FlickerReason = 'resize' | 'offscreen' | 'clear'
+
+export type FrameEvent = {
+  durationMs: number
+  /** Phase breakdown in ms + patch count. Populated when the ink instance
+   *  has frame-timing instrumentation enabled (via onFrame wiring). */
+  phases?: {
+    /** createRenderer output: DOM → yoga layout → screen buffer */
+    renderer: number
+    /** LogUpdate.render(): screen diff → Patch[] (the hot path this PR optimizes) */
+    diff: number
+    /** optimize(): patch merge/dedupe */
+    optimize: number
+    /** writeDiffToTerminal(): serialize patches → ANSI → stdout */
+    write: number
+    /** Pre-optimize patch count (proxy for how much changed this frame) */
+    patches: number
+    /** yoga calculateLayout() time (runs in resetAfterCommit, before onRender) */
+    yoga: number
+    /** React reconcile time: scrollMutated → resetAfterCommit. 0 if no commit. */
+    commit: number
+    /** layoutNode() calls this frame (recursive, includes cache-hit returns) */
+    yogaVisited: number
+    /** measureFunc (text wrap/width) calls — the expensive part */
+    yogaMeasured: number
+    /** early returns via _hasL single-slot cache */
+    yogaCacheHits: number
+    /** total yoga Node instances alive (create - free). Growth = leak. */
+    yogaLive: number
+  }
+  flickers: Array<{
+    desiredHeight: number
+    availableHeight: number
+    reason: FlickerReason
+  }>
+}
+
+export type Patch =
+  | { type: 'stdout'; content: string }
+  | { type: 'clear'; count: number }
+  | {
+      type: 'clearTerminal'
+      reason: FlickerReason
+      // Populated by log-update when a scrollback diff triggers the reset.
+      // ink.tsx uses triggerY with findOwnerChainAtRow to attribute the
+      // flicker to its source React component.
+      debug?: { triggerY: number; prevLine: string; nextLine: string }
+    }
+  | { type: 'cursorHide' }
+  | { type: 'cursorShow' }
+  | { type: 'cursorMove'; x: number; y: number }
+  | { type: 'cursorTo'; col: number }
+  | { type: 'carriageReturn' }
+  | { type: 'hyperlink'; uri: string }
+  // Pre-serialized style transition string from StylePool.transition() —
+  // cached by (fromId, toId), zero allocations after warmup.
+  | { type: 'styleStr'; str: string }
+
+export type Diff = Patch[]
+
+/**
+ * Determines whether the screen should be cleared based on the current and previous frame.
+ * Returns the reason for clearing, or undefined if no clear is needed.
+ *
+ * Screen clearing is triggered when:
+ * 1. Terminal has been resized (viewport dimensions changed) → 'resize'
+ * 2. Current frame screen height exceeds available terminal rows → 'offscreen'
+ * 3. Previous frame screen height exceeded available terminal rows → 'offscreen'
+ */
+export function shouldClearScreen(
+  prevFrame: Frame,
+  frame: Frame,
+): FlickerReason | undefined {
+  const didResize =
+    frame.viewport.height !== prevFrame.viewport.height ||
+    frame.viewport.width !== prevFrame.viewport.width
+  if (didResize) {
+    return 'resize'
+  }
+
+  const currentFrameOverflows = frame.screen.height >= frame.viewport.height
+  const previousFrameOverflowed =
+    prevFrame.screen.height >= prevFrame.viewport.height
+  if (currentFrameOverflows || previousFrameOverflowed) {
+    return 'offscreen'
+  }
+
+  return undefined
+}

package/src/engine/ink/get-max-width.ts

@@ -0,0 +1,27 @@
+import { LayoutEdge, type LayoutNode } from './layout/node.js'
+
+/**
+ * Returns the yoga node's content width (computed width minus padding and
+ * border).
+ *
+ * Warning: can return a value WIDER than the parent container. In a
+ * column-direction flex parent, width is the cross axis — align-items:
+ * stretch never shrinks children below their intrinsic size, so the text
+ * node overflows (standard CSS behavior). Yoga measures leaf nodes in two
+ * passes: the AtMost pass determines width, the Exactly pass determines
+ * height. getComputedWidth() reflects the wider AtMost result while
+ * getComputedHeight() reflects the narrower Exactly result. Callers that
+ * use this for wrapping should clamp to actual available screen space so
+ * the rendered line count stays consistent with the layout height.
+ */
+const getMaxWidth = (yogaNode: LayoutNode): number => {
+  return (
+    yogaNode.getComputedWidth() -
+    yogaNode.getComputedPadding(LayoutEdge.Left) -
+    yogaNode.getComputedPadding(LayoutEdge.Right) -
+    yogaNode.getComputedBorder(LayoutEdge.Left) -
+    yogaNode.getComputedBorder(LayoutEdge.Right)
+  )
+}
+
+export default getMaxWidth

package/src/engine/ink/global.d.ts

@@ -0,0 +1,18 @@
+// Global type augmentations for the ink engine
+import type { DOMElement } from './dom.js';
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      'ink-box': any;
+      'ink-text': any;
+      'ink-root': any;
+      'ink-virtual-text': any;
+      'ink-raw-ansi': {
+        rawText: string;
+        rawWidth: number;
+        rawHeight: number;
+      };
+    }
+  }
+}

package/src/engine/ink/hit-test.ts

@@ -0,0 +1,130 @@
+import type { DOMElement } from './dom.js'
+import { ClickEvent } from './events/click-event.js'
+import type { EventHandlerProps } from './events/event-handlers.js'
+import { nodeCache } from './node-cache.js'
+
+/**
+ * Find the deepest DOM element whose rendered rect contains (col, row).
+ *
+ * Uses the nodeCache populated by renderNodeToOutput — rects are in screen
+ * coordinates with all offsets (including scrollTop translation) already
+ * applied. Children are traversed in reverse so later siblings (painted on
+ * top) win. Nodes not in nodeCache (not rendered this frame, or lacking a
+ * yogaNode) are skipped along with their subtrees.
+ *
+ * Returns the hit node even if it has no onClick — dispatchClick walks up
+ * via parentNode to find handlers.
+ */
+export function hitTest(
+  node: DOMElement,
+  col: number,
+  row: number,
+): DOMElement | null {
+  const rect = nodeCache.get(node)
+  if (!rect) return null
+  if (
+    col < rect.x ||
+    col >= rect.x + rect.width ||
+    row < rect.y ||
+    row >= rect.y + rect.height
+  ) {
+    return null
+  }
+  // Later siblings paint on top; reversed traversal returns topmost hit.
+  for (let i = node.childNodes.length - 1; i >= 0; i--) {
+    const child = node.childNodes[i]!
+    if (child.nodeName === '#text') continue
+    const hit = hitTest(child, col, row)
+    if (hit) return hit
+  }
+  return node
+}
+
+/**
+ * Hit-test the root at (col, row) and bubble a ClickEvent from the deepest
+ * containing node up through parentNode. Only nodes with an onClick handler
+ * fire. Stops when a handler calls stopImmediatePropagation(). Returns
+ * true if at least one onClick handler fired.
+ */
+export function dispatchClick(
+  root: DOMElement,
+  col: number,
+  row: number,
+  cellIsBlank = false,
+): boolean {
+  let target: DOMElement | undefined = hitTest(root, col, row) ?? undefined
+  if (!target) return false
+
+  // Click-to-focus: find the closest focusable ancestor and focus it.
+  // root is always ink-root, which owns the FocusManager.
+  if (root.focusManager) {
+    let focusTarget: DOMElement | undefined = target
+    while (focusTarget) {
+      if (typeof focusTarget.attributes['tabIndex'] === 'number') {
+        root.focusManager.handleClickFocus(focusTarget)
+        break
+      }
+      focusTarget = focusTarget.parentNode
+    }
+  }
+  const event = new ClickEvent(col, row, cellIsBlank)
+  let handled = false
+  while (target) {
+    const handler = target._eventHandlers?.onClick as
+      | ((event: ClickEvent) => void)
+      | undefined
+    if (handler) {
+      handled = true
+      const rect = nodeCache.get(target)
+      if (rect) {
+        event.localCol = col - rect.x
+        event.localRow = row - rect.y
+      }
+      handler(event)
+      if (event.didStopImmediatePropagation()) return true
+    }
+    target = target.parentNode
+  }
+  return handled
+}
+
+/**
+ * Fire onMouseEnter/onMouseLeave as the pointer moves. Like DOM
+ * mouseenter/mouseleave: does NOT bubble — moving between children does
+ * not re-fire on the parent. Walks up from the hit node collecting every
+ * ancestor with a hover handler; diffs against the previous hovered set;
+ * fires leave on the nodes exited, enter on the nodes entered.
+ *
+ * Mutates `hovered` in place so the caller (App instance) can hold it
+ * across calls. Clears the set when the hit is null (cursor moved into a
+ * non-rendered gap or off the root rect).
+ */
+export function dispatchHover(
+  root: DOMElement,
+  col: number,
+  row: number,
+  hovered: Set<DOMElement>,
+): void {
+  const next = new Set<DOMElement>()
+  let node: DOMElement | undefined = hitTest(root, col, row) ?? undefined
+  while (node) {
+    const h = node._eventHandlers as EventHandlerProps | undefined
+    if (h?.onMouseEnter || h?.onMouseLeave) next.add(node)
+    node = node.parentNode
+  }
+  for (const old of hovered) {
+    if (!next.has(old)) {
+      hovered.delete(old)
+      // Skip handlers on detached nodes (removed between mouse events)
+      if (old.parentNode) {
+        ;(old._eventHandlers as EventHandlerProps | undefined)?.onMouseLeave?.()
+      }
+    }
+  }
+  for (const n of next) {
+    if (!hovered.has(n)) {
+      hovered.add(n)
+      ;(n._eventHandlers as EventHandlerProps | undefined)?.onMouseEnter?.()
+    }
+  }
+}

package/src/engine/ink/hooks/use-animation-frame.ts

@@ -0,0 +1,57 @@
+import { useContext, useEffect, useState } from 'react'
+import { ClockContext } from '../components/ClockContext.js'
+import type { DOMElement } from '../dom.js'
+import { useTerminalViewport } from './use-terminal-viewport.js'
+
+/**
+ * Hook for synchronized animations that pause when offscreen.
+ *
+ * Returns a ref to attach to the animated element and the current animation time.
+ * All instances share the same clock, so animations stay in sync.
+ * The clock only runs when at least one keepAlive subscriber exists.
+ *
+ * Pass `null` to pause — unsubscribes from the clock so no ticks fire.
+ * Time freezes at the last value and resumes from the current clock time
+ * when a number is passed again.
+ *
+ * @param intervalMs - How often to update, or null to pause
+ * @returns [ref, time] - Ref to attach to element, elapsed time in ms
+ *
+ * @example
+ * function Spinner() {
+ *   const [ref, time] = useAnimationFrame(120)
+ *   const frame = Math.floor(time / 120) % FRAMES.length
+ *   return <Box ref={ref}>{FRAMES[frame]}</Box>
+ * }
+ *
+ * The clock automatically slows when the terminal is blurred,
+ * so consumers don't need to handle focus state.
+ */
+export function useAnimationFrame(
+  intervalMs: number | null = 16,
+): [ref: (element: DOMElement | null) => void, time: number] {
+  const clock = useContext(ClockContext)
+  const [viewportRef, { isVisible }] = useTerminalViewport()
+  const [time, setTime] = useState(() => clock?.now() ?? 0)
+
+  const active = isVisible && intervalMs !== null
+
+  useEffect(() => {
+    if (!clock || !active) return
+
+    let lastUpdate = clock.now()
+
+    const onChange = (): void => {
+      const now = clock.now()
+      if (now - lastUpdate >= intervalMs!) {
+        lastUpdate = now
+        setTime(now)
+      }
+    }
+
+    // keepAlive: true — visible animations drive the clock
+    return clock.subscribe(onChange, true)
+  }, [clock, intervalMs, active])
+
+  return [viewportRef, time]
+}

package/src/engine/ink/hooks/use-app.ts

@@ -0,0 +1,8 @@
+import { useContext } from 'react'
+import AppContext from '../components/AppContext.js'
+
+/**
+ * `useApp` is a React hook, which exposes a method to manually exit the app (unmount).
+ */
+const useApp = () => useContext(AppContext)
+export default useApp