Hermes-agent

ui-tui/packages/hermes-ink/ambient.d.ts

@@ -0,0 +1,83 @@
+/// <reference types="react" />
+
+declare module 'react/compiler-runtime' {
+  export function c(size: number): any[]
+}
+
+declare module 'bidi-js' {
+  const bidiFactory: () => Record<string, any>
+  export default bidiFactory
+}
+
+declare module 'stack-utils' {
+  class StackUtils {
+    static nodeInternals(): RegExp[]
+    constructor(opts?: { cwd?: string; internals?: RegExp[] })
+    clean(stack: string | undefined): string | undefined
+    parseLine(line: string): { file?: string; line?: number; column?: number; function?: string } | undefined
+  }
+  export default StackUtils
+}
+
+declare module 'react-reconciler' {
+  export type FiberRoot = unknown
+  const createReconciler: any
+  export default createReconciler
+}
+
+declare module 'react-reconciler/constants.js' {
+  export const ConcurrentRoot: number
+  export const LegacyRoot: number
+  export const DiscreteEventPriority: symbol | number
+  export const ContinuousEventPriority: symbol | number
+  export const DefaultEventPriority: symbol | number
+  export const NoEventPriority: symbol | number
+}
+
+declare module 'lodash-es/noop.js' {
+  const noop: (...args: unknown[]) => void
+  export default noop
+}
+
+declare module 'lodash-es/throttle.js' {
+  function throttle<T extends (...args: unknown[]) => unknown>(
+    fn: T,
+    wait?: number,
+    opts?: { leading?: boolean; trailing?: boolean }
+  ): T & { cancel(): void; flush(): void }
+  export default throttle
+}
+
+declare module 'semver' {
+  export function coerce(version: string | number | null | undefined): { version: string } | null
+  export function gt(a: string, b: string, opts?: { loose?: boolean }): boolean
+  export function gte(a: string, b: string, opts?: { loose?: boolean }): boolean
+  export function lt(a: string, b: string, opts?: { loose?: boolean }): boolean
+  export function lte(a: string, b: string, opts?: { loose?: boolean }): boolean
+  export function satisfies(version: string, range: string, opts?: { loose?: boolean }): boolean
+  export function compare(a: string, b: string, opts?: { loose?: boolean }): number
+}
+
+interface BunSemver {
+  order(a: string, b: string): -1 | 0 | 1
+  satisfies(version: string, range: string): boolean
+}
+
+interface BunRuntime {
+  stringWidth(s: string, opts?: { ambiguousIsNarrow?: boolean }): number
+  semver: BunSemver
+  wrapAnsi?(input: string, columns: number, options?: { hard?: boolean; wordWrap?: boolean; trim?: boolean }): string
+}
+
+declare var Bun: BunRuntime | undefined
+
+declare namespace React {
+  namespace JSX {
+    interface IntrinsicElements {
+      'ink-box': Record<string, unknown>
+      'ink-text': Record<string, unknown>
+      'ink-link': Record<string, unknown>
+      'ink-raw-ansi': Record<string, unknown>
+    }
+  }
+}

ui-tui/packages/hermes-ink/index.d.ts

@@ -0,0 +1,40 @@
+/// <reference path="./ambient.d.ts" />
+export { default as useStderr } from './src/hooks/use-stderr.ts'
+export type { StderrHandle } from './src/hooks/use-stderr.ts'
+export { default as useStdout } from './src/hooks/use-stdout.ts'
+export type { StdoutHandle } from './src/hooks/use-stdout.ts'
+export { Ansi } from './src/ink/Ansi.tsx'
+export { evictInkCaches } from './src/ink/cache-eviction.ts'
+export type { EvictLevel, InkCacheSizes } from './src/ink/cache-eviction.ts'
+export { AlternateScreen } from './src/ink/components/AlternateScreen.tsx'
+export type { MouseTrackingMode } from './src/ink/termio/dec.ts'
+export { default as Box } from './src/ink/components/Box.tsx'
+export type { Props as BoxProps } from './src/ink/components/Box.tsx'
+export { default as Link } from './src/ink/components/Link.tsx'
+export { default as Newline } from './src/ink/components/Newline.tsx'
+export { NoSelect } from './src/ink/components/NoSelect.tsx'
+export { RawAnsi } from './src/ink/components/RawAnsi.tsx'
+export { default as ScrollBox } from './src/ink/components/ScrollBox.tsx'
+export type { ScrollBoxHandle, ScrollBoxProps } from './src/ink/components/ScrollBox.tsx'
+export { default as Spacer } from './src/ink/components/Spacer.tsx'
+export type { Props as StdinProps } from './src/ink/components/StdinContext.ts'
+export { default as Text } from './src/ink/components/Text.tsx'
+export type { Props as TextProps } from './src/ink/components/Text.tsx'
+export type { Key } from './src/ink/events/input-event.ts'
+export { default as useApp } from './src/ink/hooks/use-app.ts'
+export { useCursorAdvance } from './src/ink/hooks/use-cursor-advance.ts'
+export { useDeclaredCursor } from './src/ink/hooks/use-declared-cursor.ts'
+export { default as useInput } from './src/ink/hooks/use-input.ts'
+export { useHasSelection, useSelection } from './src/ink/hooks/use-selection.ts'
+export { default as useStdin } from './src/ink/hooks/use-stdin.ts'
+export { useTabStatus } from './src/ink/hooks/use-tab-status.ts'
+export { useTerminalFocus } from './src/ink/hooks/use-terminal-focus.ts'
+export { useTerminalTitle } from './src/ink/hooks/use-terminal-title.ts'
+export { useTerminalViewport } from './src/ink/hooks/use-terminal-viewport.ts'
+export { default as measureElement } from './src/ink/measure-element.ts'
+export { createRoot, forceRedraw, default as render, renderSync } from './src/ink/root.ts'
+export type { Instance, RenderOptions, Root } from './src/ink/root.ts'
+export { stringWidth } from './src/ink/stringWidth.ts'
+export { wrapAnsi } from './src/ink/wrapAnsi.ts'
+export { default as TextInput, UncontrolledTextInput } from 'ink-text-input'
+export type { Props as TextInputProps } from 'ink-text-input'

ui-tui/packages/hermes-ink/index.js

@@ -0,0 +1 @@
+export * from './dist/entry-exports.js'

ui-tui/packages/hermes-ink/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@hermes/ink",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "esbuild src/entry-exports.ts --bundle --platform=node --format=esm --packages=external --outdir=dist"
+  },
+  "sideEffects": true,
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./text-input": {
+      "types": "./text-input.d.ts",
+      "import": "./text-input.js",
+      "default": "./text-input.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "ink-text-input": ">=6.0.0",
+    "react": ">=19.0.0"
+  },
+  "dependencies": {
+    "@alcalzone/ansi-tokenize": "^0.1.0",
+    "auto-bind": "^5.0.0",
+    "bidi-js": "^1.0.0",
+    "chalk": "^5.4.0",
+    "cli-boxes": "^3.0.0",
+    "code-excerpt": "^4.0.0",
+    "emoji-regex": "^10.4.0",
+    "get-east-asian-width": "^1.3.0",
+    "indent-string": "^5.0.0",
+    "lodash-es": "^4.17.0",
+    "react": ">=19.0.0",
+    "react-reconciler": "0.33.0",
+    "semver": "^7.6.0",
+    "signal-exit": "^4.1.0",
+    "stack-utils": "^2.0.0",
+    "strip-ansi": "^7.1.0",
+    "supports-hyperlinks": "^3.1.0",
+    "type-fest": "^4.30.0",
+    "usehooks-ts": "^3.1.0",
+    "wrap-ansi": "^9.0.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0"
+  }
+}

ui-tui/packages/hermes-ink/src/bootstrap/state.ts

@@ -0,0 +1,9 @@
+export function flushInteractionTime(): void {}
+
+export function updateLastInteractionTime(): void {}
+
+export function markScrollActivity(): void {}
+
+export function getIsInteractive(): boolean {
+  return !!process.stdin.isTTY && !!process.stdout.isTTY
+}

ui-tui/packages/hermes-ink/src/entry-exports.ts

@@ -0,0 +1,32 @@
+export { default as useStderr } from './hooks/use-stderr.js'
+export { default as useStdout } from './hooks/use-stdout.js'
+export { Ansi } from './ink/Ansi.js'
+export { evictInkCaches, type EvictLevel, type InkCacheSizes } from './ink/cache-eviction.js'
+export { AlternateScreen } from './ink/components/AlternateScreen.js'
+export { default as Box } from './ink/components/Box.js'
+export { default as Link } from './ink/components/Link.js'
+export { default as Newline } from './ink/components/Newline.js'
+export { NoSelect } from './ink/components/NoSelect.js'
+export { RawAnsi } from './ink/components/RawAnsi.js'
+export { default as ScrollBox } from './ink/components/ScrollBox.js'
+export { default as Spacer } from './ink/components/Spacer.js'
+export { default as Text } from './ink/components/Text.js'
+export { default as useApp } from './ink/hooks/use-app.js'
+export { useCursorAdvance } from './ink/hooks/use-cursor-advance.js'
+export { useDeclaredCursor } from './ink/hooks/use-declared-cursor.js'
+export { type RunExternalProcess, useExternalProcess, withInkSuspended } from './ink/hooks/use-external-process.js'
+export { default as useInput } from './ink/hooks/use-input.js'
+export { useHasSelection, useSelection } from './ink/hooks/use-selection.js'
+export { default as useStdin } from './ink/hooks/use-stdin.js'
+export { useTabStatus } from './ink/hooks/use-tab-status.js'
+export { useTerminalFocus } from './ink/hooks/use-terminal-focus.js'
+export { useTerminalTitle } from './ink/hooks/use-terminal-title.js'
+export { useTerminalViewport } from './ink/hooks/use-terminal-viewport.js'
+export { default as measureElement } from './ink/measure-element.js'
+export { scrollFastPathStats, type ScrollFastPathStats } from './ink/render-node-to-output.js'
+export { createRoot, forceRedraw, default as render, renderSync } from './ink/root.js'
+export { stringWidth } from './ink/stringWidth.js'
+export { wrapAnsi } from './ink/wrapAnsi.js'
+export { isXtermJs } from './ink/terminal.js'
+export type { MouseTrackingMode } from './ink/termio/dec.js'
+export { default as TextInput, UncontrolledTextInput } from 'ink-text-input'

ui-tui/packages/hermes-ink/src/hooks/use-stderr.ts

@@ -0,0 +1,15 @@
+import { useMemo } from 'react'
+export type StderrHandle = {
+  stderr: NodeJS.WriteStream
+  write: (data: string) => boolean
+}
+
+export default function useStderr(): StderrHandle {
+  return useMemo(
+    () => ({
+      stderr: process.stderr,
+      write: data => process.stderr.write(data)
+    }),
+    []
+  )
+}

ui-tui/packages/hermes-ink/src/hooks/use-stdout.ts

@@ -0,0 +1,15 @@
+import { useMemo } from 'react'
+export type StdoutHandle = {
+  stdout: NodeJS.WriteStream
+  write: (data: string) => boolean
+}
+
+export default function useStdout(): StdoutHandle {
+  return useMemo(
+    () => ({
+      stdout: process.stdout,
+      write: data => process.stdout.write(data)
+    }),
+    []
+  )
+}

ui-tui/packages/hermes-ink/src/ink/app-mouse.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { handleMouseEvent } from './components/App.js'
+import { createSelectionState, hasSelection, startSelection, updateSelection } from './selection.js'
+
+const makeApp = () => {
+  const selection = createSelectionState()
+
+  return {
+    clickCount: 1,
+    lastHoverCol: -1,
+    lastHoverRow: -1,
+    mouseCaptureTarget: undefined,
+    props: {
+      getSelectedText: vi.fn(() => 'selected text'),
+      onCopySelectionNoClear: vi.fn(async () => 'selected text'),
+      onHoverAt: vi.fn(),
+      onMouseDownAt: vi.fn(),
+      onMouseDragAt: vi.fn(),
+      onMouseUpAt: vi.fn(),
+      onSelectionChange: vi.fn(),
+      selection
+    }
+  } as any
+}
+
+describe('handleMouseEvent right-click selection behavior', () => {
+  it('copies an active selection instead of dispatching right-click paste handlers', async () => {
+    const app = makeApp()
+
+    startSelection(app.props.selection, 0, 0)
+    updateSelection(app.props.selection, 4, 0)
+
+    handleMouseEvent(app, { action: 'press', button: 2, col: 3, kind: 'mouse', row: 1 })
+    await Promise.resolve()
+
+    expect(app.props.onCopySelectionNoClear).toHaveBeenCalledOnce()
+    expect(app.props.onMouseDownAt).not.toHaveBeenCalled()
+    expect(app.clickCount).toBe(0)
+  })
+
+  it('clears the highlight after a successful right-click copy', async () => {
+    const app = makeApp()
+
+    startSelection(app.props.selection, 0, 0)
+    updateSelection(app.props.selection, 4, 0)
+    expect(hasSelection(app.props.selection)).toBe(true)
+
+    handleMouseEvent(app, { action: 'press', button: 2, col: 3, kind: 'mouse', row: 1, sequence: '' })
+    await Promise.resolve()
+    await Promise.resolve()
+
+    // Deliberate copy clears the selection (visual confirmation + a follow-up
+    // right-click on empty space pastes rather than re-copying a stale range).
+    expect(hasSelection(app.props.selection)).toBe(false)
+    expect(app.props.onSelectionChange).toHaveBeenCalled()
+  })
+
+  it('keeps the highlight when right-click copy fails (no clipboard path)', async () => {
+    const app = makeApp()
+    app.props.onCopySelectionNoClear.mockResolvedValue('')
+
+    startSelection(app.props.selection, 0, 0)
+    updateSelection(app.props.selection, 4, 0)
+
+    handleMouseEvent(app, { action: 'press', button: 2, col: 3, kind: 'mouse', row: 1, sequence: '' })
+    await Promise.resolve()
+    await Promise.resolve()
+
+    // Copy didn't land, so the highlight must survive (and we fall back to the
+    // right-click paste handler instead).
+    expect(hasSelection(app.props.selection)).toBe(true)
+  })
+
+  it('falls back to right-click handlers when selection copy has no clipboard path', async () => {
+    const app = makeApp()
+    app.props.onCopySelectionNoClear.mockResolvedValue('')
+
+    startSelection(app.props.selection, 0, 0)
+    updateSelection(app.props.selection, 4, 0)
+
+    handleMouseEvent(app, { action: 'press', button: 2, col: 3, kind: 'mouse', row: 1 })
+    await Promise.resolve()
+
+    expect(app.props.onCopySelectionNoClear).toHaveBeenCalledOnce()
+    expect(app.props.onMouseDownAt).toHaveBeenCalledWith(2, 0, 2)
+  })
+
+  it('does not paste when highlighted selection text is empty', async () => {
+    const app = makeApp()
+    app.props.getSelectedText.mockReturnValue('')
+
+    startSelection(app.props.selection, 0, 0)
+    updateSelection(app.props.selection, 4, 0)
+
+    handleMouseEvent(app, { action: 'press', button: 2, col: 3, kind: 'mouse', row: 1 })
+    await Promise.resolve()
+
+    expect(app.props.onCopySelectionNoClear).not.toHaveBeenCalled()
+    expect(app.props.onMouseDownAt).not.toHaveBeenCalled()
+  })
+
+  it('does not repeatedly copy or paste during right-button motion events over a selection', () => {
+    const app = makeApp()
+
+    startSelection(app.props.selection, 0, 0)
+    updateSelection(app.props.selection, 4, 0)
+
+    handleMouseEvent(app, { action: 'press', button: 0x20 | 2, col: 3, kind: 'mouse', row: 1 })
+
+    expect(app.props.onCopySelectionNoClear).not.toHaveBeenCalled()
+    expect(app.props.onMouseDownAt).not.toHaveBeenCalled()
+  })
+
+  it('still dispatches right-click handlers when no text is selected', () => {
+    const app = makeApp()
+
+    handleMouseEvent(app, { action: 'press', button: 2, col: 3, kind: 'mouse', row: 1 })
+
+    expect(app.props.onCopySelectionNoClear).not.toHaveBeenCalled()
+    expect(app.props.onMouseDownAt).toHaveBeenCalledWith(2, 0, 2)
+  })
+})

ui-tui/packages/hermes-ink/src/ink/app-rawmode-mouse.test.ts

@@ -0,0 +1,91 @@
+import { EventEmitter } from 'events'
+import React, { useContext, useEffect } from 'react'
+import { describe, expect, it } from 'vitest'
+
+import StdinContext from './components/StdinContext.js'
+import Text from './components/Text.js'
+import Ink from './ink.js'
+import { DISABLE_MOUSE_TRACKING } from './termio/dec.js'
+
+class FakeTty extends EventEmitter {
+  chunks: string[] = []
+  columns = 80
+  rows = 24
+  isTTY = true
+  isRaw = false
+
+  ref(): void {}
+  unref(): void {}
+  read(): null {
+    return null
+  }
+  setEncoding(): this {
+    return this
+  }
+  setRawMode(mode: boolean): this {
+    this.isRaw = mode
+    return this
+  }
+  write(chunk: string | Uint8Array, cb?: (err?: Error | null) => void): boolean {
+    this.chunks.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'))
+    cb?.()
+    return true
+  }
+}
+
+const tick = () => new Promise<void>(resolve => setImmediate(resolve))
+
+// A child that grabs the last useInput consumer's raw-mode toggle. Mounting
+// enables raw mode (count 0→1); unmounting disables it (count 1→0), which is
+// the teardown path that must DISABLE_MOUSE_TRACKING so DEC 1003 hover can't
+// leak as cooked-mode `35;col;row M` text over the prompt.
+function RawModeConsumer({ active }: { active: boolean }) {
+  const { setRawMode, isRawModeSupported } = useContext(StdinContext)
+
+  useEffect(() => {
+    if (!active || !isRawModeSupported) {
+      return
+    }
+
+    setRawMode(true)
+
+    return () => setRawMode(false)
+  }, [active, isRawModeSupported, setRawMode])
+
+  return React.createElement(Text, null, 'x')
+}
+
+describe('App raw-mode teardown', () => {
+  it('disables mouse tracking when the last raw-mode consumer detaches', async () => {
+    const stdout = new FakeTty()
+    const stdin = new FakeTty()
+    const stderr = new FakeTty()
+    const ink = new Ink({
+      exitOnCtrlC: false,
+      patchConsole: false,
+      stderr: stderr as unknown as NodeJS.WriteStream,
+      stdin: stdin as unknown as NodeJS.ReadStream,
+      stdout: stdout as unknown as NodeJS.WriteStream
+    })
+
+    // Mouse tracking is asserted on the alt screen; the teardown path lives in
+    // App, independent of who enabled tracking.
+    ink.setAltScreenActive(true, 'all')
+    ink.render(React.createElement(RawModeConsumer, { active: true }))
+    ink.onRender()
+    await tick()
+    expect(stdin.isRaw).toBe(true)
+
+    stdout.chunks = []
+
+    // Drop the consumer → raw-mode count hits 0 → teardown runs.
+    ink.render(React.createElement(RawModeConsumer, { active: false }))
+    ink.onRender()
+    await tick()
+
+    expect(stdin.isRaw).toBe(false)
+    expect(stdout.chunks.join('')).toContain(DISABLE_MOUSE_TRACKING)
+
+    ink.unmount()
+  })
+})

ui-tui/packages/hermes-ink/src/ink/bidi.ts

@@ -0,0 +1,145 @@
+/**
+ * Bidirectional text reordering for terminal rendering.
+ *
+ * Terminals on Windows do not implement the Unicode Bidi Algorithm,
+ * so RTL text (Hebrew, Arabic, etc.) appears reversed. This module
+ * applies the bidi algorithm to reorder ClusteredChar arrays from
+ * logical order to visual order before Ink's LTR cell placement loop.
+ *
+ * On macOS terminals (Terminal.app, iTerm2) bidi works natively.
+ * Windows Terminal (including WSL) does not implement bidi
+ * (https://github.com/microsoft/terminal/issues/538).
+ *
+ * Detection: Windows Terminal sets WT_SESSION; native Windows cmd/conhost
+ * also lacks bidi. We enable bidi reordering when running on Windows or
+ * inside Windows Terminal (covers WSL).
+ */
+import bidiFactory from 'bidi-js'
+
+type ClusteredChar = {
+  value: string
+  width: number
+  styleId: number
+  hyperlink: string | undefined
+}
+
+let bidiInstance: ReturnType<typeof bidiFactory> | undefined
+let needsSoftwareBidi: boolean | undefined
+
+function needsBidi(): boolean {
+  if (needsSoftwareBidi === undefined) {
+    needsSoftwareBidi =
+      process.platform === 'win32' ||
+      typeof process.env['WT_SESSION'] === 'string' || // WSL in Windows Terminal
+      process.env['TERM_PROGRAM'] === 'vscode' // VS Code integrated terminal (xterm.js)
+  }
+
+  return needsSoftwareBidi
+}
+
+function getBidi() {
+  if (!bidiInstance) {
+    bidiInstance = bidiFactory()
+  }
+
+  return bidiInstance
+}
+
+/**
+ * Reorder an array of ClusteredChars from logical order to visual order
+ * using the Unicode Bidi Algorithm. Active on terminals that lack native
+ * bidi support (Windows Terminal, conhost, WSL).
+ *
+ * Returns the same array on bidi-capable terminals (no-op).
+ */
+export function reorderBidi(characters: ClusteredChar[]): ClusteredChar[] {
+  if (!needsBidi() || characters.length === 0) {
+    return characters
+  }
+
+  // Build a plain string from the clustered chars to run through bidi
+  const plainText = characters.map(c => c.value).join('')
+
+  // Check if there are any RTL characters — skip bidi if pure LTR
+  if (!hasRTLCharacters(plainText)) {
+    return characters
+  }
+
+  const bidi = getBidi()
+  const { levels } = bidi.getEmbeddingLevels(plainText, 'auto')
+
+  // Map bidi levels back to ClusteredChar indices.
+  // Each ClusteredChar may be multiple code units in the joined string.
+  const charLevels: number[] = []
+  let offset = 0
+
+  for (let i = 0; i < characters.length; i++) {
+    charLevels.push(levels[offset]!)
+    offset += characters[i]!.value.length
+  }
+
+  // Get reorder segments from bidi-js, but we need to work at the
+  // ClusteredChar level, not the string level. We'll implement the
+  // standard bidi reordering: find the max level, then for each level
+  // from max down to 1, reverse all contiguous runs >= that level.
+  const reordered = [...characters]
+  const maxLevel = Math.max(...charLevels)
+
+  for (let level = maxLevel; level >= 1; level--) {
+    let i = 0
+
+    while (i < reordered.length) {
+      if (charLevels[i]! >= level) {
+        // Find the end of this run
+        let j = i + 1
+
+        while (j < reordered.length && charLevels[j]! >= level) {
+          j++
+        }
+
+        // Reverse the run in both arrays
+        reverseRange(reordered, i, j - 1)
+        reverseRangeNumbers(charLevels, i, j - 1)
+        i = j
+      } else {
+        i++
+      }
+    }
+  }
+
+  return reordered
+}
+
+function reverseRange<T>(arr: T[], start: number, end: number): void {
+  while (start < end) {
+    const temp = arr[start]!
+    arr[start] = arr[end]!
+    arr[end] = temp
+    start++
+    end--
+  }
+}
+
+function reverseRangeNumbers(arr: number[], start: number, end: number): void {
+  while (start < end) {
+    const temp = arr[start]!
+    arr[start] = arr[end]!
+    arr[end] = temp
+    start++
+    end--
+  }
+}
+
+/**
+ * Quick check for RTL characters (Hebrew, Arabic, and related scripts).
+ * Avoids running the full bidi algorithm on pure-LTR text.
+ */
+function hasRTLCharacters(text: string): boolean {
+  // Hebrew: U+0590-U+05FF, U+FB1D-U+FB4F
+  // Arabic: U+0600-U+06FF, U+0750-U+077F, U+08A0-U+08FF, U+FB50-U+FDFF, U+FE70-U+FEFF
+  // Thaana: U+0780-U+07BF
+  // Syriac: U+0700-U+074F
+  return /[\u0590-\u05FF\uFB1D-\uFB4F\u0600-\u06FF\u0750-\u077F\u08A0-\u08FF\uFB50-\uFDFF\uFE70-\uFEFF\u0780-\u07BF\u0700-\u074F]/u.test(
+    text
+  )
+}

ui-tui/packages/hermes-ink/src/ink/cache-eviction.ts

@@ -0,0 +1,45 @@
+// Unified cache eviction for the four hot Ink module-level caches:
+//   - widthCache       (stringWidth.ts)
+//   - wrapCache        (wrap-text.ts)
+//   - sliceCache       (sliceAnsi.ts)
+//   - lineWidthCache   (line-width-cache.ts)
+//
+// Used by the host (TUI) under memory pressure or on session swap to drop
+// content-keyed entries that won't recur. All caches are content-keyed
+// (not session-keyed), so cross-session sharing is normally beneficial —
+// only evict when memory tightens or when the user explicitly resets.
+
+import { evictSliceCache, sliceCacheSize } from '../utils/sliceAnsi.js'
+
+import { evictLineWidthCache, lineWidthCacheSize } from './line-width-cache.js'
+import { evictWidthCache, widthCacheSize } from './stringWidth.js'
+import { evictWrapCache, wrapCacheSize } from './wrap-text.js'
+
+export interface InkCacheSizes {
+  lineWidth: number
+  slice: number
+  width: number
+  wrap: number
+}
+
+function inkCacheSizes(): InkCacheSizes {
+  return {
+    lineWidth: lineWidthCacheSize(),
+    slice: sliceCacheSize(),
+    width: widthCacheSize(),
+    wrap: wrapCacheSize()
+  }
+}
+
+export type EvictLevel = 'all' | 'half'
+
+export function evictInkCaches(level: EvictLevel = 'half'): InkCacheSizes {
+  const keep = level === 'half' ? 0.5 : 0
+
+  evictWidthCache(keep)
+  evictWrapCache(keep)
+  evictSliceCache(keep)
+  evictLineWidthCache(keep)
+
+  return inkCacheSizes()
+}

ui-tui/packages/hermes-ink/src/ink/clearTerminal.ts

@@ -0,0 +1,68 @@
+/**
+ * Cross-platform terminal clearing with scrollback support.
+ * Detects modern terminals that support ESC[3J for clearing scrollback.
+ */
+
+import { csi, CURSOR_HOME, ERASE_SCREEN, ERASE_SCROLLBACK } from './termio/csi.js'
+
+// HVP (Horizontal Vertical Position) - legacy Windows cursor home
+const CURSOR_HOME_WINDOWS = csi(0, 'f')
+
+function isWindowsTerminal(): boolean {
+  return process.platform === 'win32' && !!process.env.WT_SESSION
+}
+
+function isMintty(): boolean {
+  // mintty 3.1.5+ sets TERM_PROGRAM to 'mintty'
+  if (process.env.TERM_PROGRAM === 'mintty') {
+    return true
+  }
+
+  // GitBash/MSYS2/MINGW use mintty and set MSYSTEM
+  if (process.platform === 'win32' && process.env.MSYSTEM) {
+    return true
+  }
+
+  return false
+}
+
+function isModernWindowsTerminal(): boolean {
+  // Windows Terminal sets WT_SESSION environment variable
+  if (isWindowsTerminal()) {
+    return true
+  }
+
+  // VS Code integrated terminal on Windows with ConPTY support
+  if (process.platform === 'win32' && process.env.TERM_PROGRAM === 'vscode' && process.env.TERM_PROGRAM_VERSION) {
+    return true
+  }
+
+  // mintty (GitBash/MSYS2/Cygwin) supports modern escape sequences
+  if (isMintty()) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Returns the ANSI escape sequence to clear the terminal including scrollback.
+ * Automatically detects terminal capabilities.
+ */
+export function getClearTerminalSequence(): string {
+  if (process.platform === 'win32') {
+    if (isModernWindowsTerminal()) {
+      return ERASE_SCREEN + ERASE_SCROLLBACK + CURSOR_HOME
+    } else {
+      // Legacy Windows console - can't clear scrollback
+      return ERASE_SCREEN + CURSOR_HOME_WINDOWS
+    }
+  }
+
+  return ERASE_SCREEN + ERASE_SCROLLBACK + CURSOR_HOME
+}
+
+/**
+ * Clears the terminal screen. On supported terminals, also clears scrollback.
+ */
+export const clearTerminal = getClearTerminalSequence()

ui-tui/packages/hermes-ink/src/ink/colorize.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  CHALK_USES_RICH_EIGHT_BIT_DOWNGRADE,
+  richEightBitColorNumber,
+  shouldUseRichEightBitDowngradeForLegacyAppleTerminal
+} from './colorize.js'
+
+describe('shouldUseRichEightBitDowngradeForLegacyAppleTerminal', () => {
+  it('memoizes the current process decision for render hot paths', () => {
+    expect(typeof CHALK_USES_RICH_EIGHT_BIT_DOWNGRADE).toBe('boolean')
+  })
+
+  it('uses Rich-compatible 256-color downgrade on legacy Apple Terminal', () => {
+    expect(
+      shouldUseRichEightBitDowngradeForLegacyAppleTerminal({ TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv, 2)
+    ).toBe(true)
+  })
+
+  it('normalizes Apple Terminal names before matching', () => {
+    expect(
+      shouldUseRichEightBitDowngradeForLegacyAppleTerminal({ TERM_PROGRAM: ' Apple_Terminal ' } as NodeJS.ProcessEnv, 2)
+    ).toBe(true)
+  })
+
+  it('does not rewrite when Apple Terminal advertises truecolor', () => {
+    expect(
+      shouldUseRichEightBitDowngradeForLegacyAppleTerminal(
+        { COLORTERM: 'truecolor', TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv,
+        3
+      )
+    ).toBe(false)
+  })
+
+  it('does not override explicit color environment choices', () => {
+    expect(
+      shouldUseRichEightBitDowngradeForLegacyAppleTerminal(
+        { FORCE_COLOR: '2', TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv,
+        2
+      )
+    ).toBe(false)
+    expect(
+      shouldUseRichEightBitDowngradeForLegacyAppleTerminal(
+        { HERMES_TUI_TRUECOLOR: '1', TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv,
+        3
+      )
+    ).toBe(false)
+  })
+})
+
+describe('richEightBitColorNumber', () => {
+  it('matches Rich downgrade output for default Hermes skin colors', () => {
+    expect(richEightBitColorNumber(0xff, 0xd7, 0x00)).toBe(220)
+    expect(richEightBitColorNumber(0xff, 0xbf, 0x00)).toBe(214)
+    expect(richEightBitColorNumber(0xcd, 0x7f, 0x32)).toBe(173)
+    expect(richEightBitColorNumber(0xb8, 0x86, 0x0b)).toBe(136)
+    expect(richEightBitColorNumber(0xff, 0xf8, 0xdc)).toBe(230)
+  })
+})
+

ui-tui/packages/hermes-ink/src/ink/colorize.ts

@@ -0,0 +1,277 @@
+import chalk from 'chalk'
+
+import type { Color, TextStyles } from './styles.js'
+
+/**
+ * xterm.js (VS Code, Cursor, code-server, Coder) has supported truecolor
+ * since 2017, but code-server/Coder containers often don't set
+ * COLORTERM=truecolor. chalk's supports-color doesn't recognize
+ * TERM_PROGRAM=vscode (it only knows iTerm.app/Apple_Terminal), so it falls
+ * through to the -256color regex → level 2. At level 2, chalk.rgb()
+ * downgrades to the nearest 6×6×6 cube color: rgb(215,119,87) → idx 174
+ * rgb(215,135,135) — washed-out salmon.
+ *
+ * Gated on level === 2 (not < 3) to respect NO_COLOR / FORCE_COLOR=0 —
+ * those yield level 0 and are an explicit "no colors" request. Desktop VS
+ * Code sets COLORTERM=truecolor itself, so this is a no-op there (already 3).
+ *
+ * Must run BEFORE the tmux clamp — if tmux is running inside a VS Code
+ * terminal, tmux's passthrough limitation wins and we want level 2.
+ */
+function boostChalkLevelForXtermJs(): boolean {
+  if (process.env.TERM_PROGRAM === 'vscode' && chalk.level === 2) {
+    chalk.level = 3
+
+    return true
+  }
+
+  return false
+}
+
+export function shouldUseRichEightBitDowngradeForLegacyAppleTerminal(
+  env: NodeJS.ProcessEnv = process.env,
+  level = chalk.level
+): boolean {
+  const termProgram = (env.TERM_PROGRAM ?? '').trim()
+  const truecolorOverride = /^(?:1|true|yes|on)$/i.test((env.HERMES_TUI_TRUECOLOR ?? '').trim())
+  const advertisesTruecolor = /^(?:truecolor|24bit)$/i.test((env.COLORTERM ?? '').trim())
+
+  return termProgram === 'Apple_Terminal' && !truecolorOverride && !advertisesTruecolor && !('FORCE_COLOR' in env) && level === 2
+}
+
+export function richEightBitColorNumber(red: number, green: number, blue: number): number {
+  const rn = red / 255
+  const gn = green / 255
+  const bn = blue / 255
+  const max = Math.max(rn, gn, bn)
+  const min = Math.min(rn, gn, bn)
+  const lightness = (max + min) / 2
+  const saturation = max === min ? 0 : lightness > 0.5 ? (max - min) / (2 - max - min) : (max - min) / (max + min)
+
+  if (saturation < 0.15) {
+    const gray = Math.round(lightness * 25)
+
+    return gray === 0 ? 16 : gray === 25 ? 231 : 231 + gray
+  }
+
+  const sixRed = red < 95 ? red / 95 : 1 + (red - 95) / 40
+  const sixGreen = green < 95 ? green / 95 : 1 + (green - 95) / 40
+  const sixBlue = blue < 95 ? blue / 95 : 1 + (blue - 95) / 40
+
+  return 16 + 36 * Math.round(sixRed) + 6 * Math.round(sixGreen) + Math.round(sixBlue)
+}
+
+/**
+ * tmux parses truecolor SGR (\e[48;2;r;g;bm) into its cell buffer correctly,
+ * but its client-side emitter only re-emits truecolor to the outer terminal if
+ * the outer terminal advertises Tc/RGB capability (via terminal-overrides).
+ * Default tmux config doesn't set this, so tmux emits the cell to iTerm2/etc
+ * WITHOUT the bg sequence — outer terminal's buffer has bg=default → black on
+ * dark profiles. Clamping to level 2 makes chalk emit 256-color (\e[48;5;Nm),
+ * which tmux passes through cleanly. grey93 (255) is visually identical to
+ * rgb(240,240,240).
+ *
+ * Users who HAVE set `terminal-overrides ,*:Tc` get a technically-unnecessary
+ * downgrade, but the visual difference is imperceptible. Querying
+ * `tmux show -gv terminal-overrides` to detect this would add a subprocess on
+ * startup — not worth it.
+ *
+ * $TMUX is a pty-lifecycle env var set by tmux itself; it never comes from
+ * globalSettings.env, so reading it here is correct. chalk is a singleton, so
+ * this clamps ALL truecolor output (fg+bg+hex) across the entire app.
+ */
+function clampChalkLevelForTmux(): boolean {
+  if (process.env.TMUX && chalk.level > 2) {
+    chalk.level = 2
+
+    return true
+  }
+
+  return false
+}
+
+// Computed once at module load — terminal/tmux environment doesn't change mid-session.
+// Order matters: boost first; then tmux can still clamp RGB to 256.
+// Exported for debugging — tree-shaken if unused.
+export const CHALK_BOOSTED_FOR_XTERMJS = boostChalkLevelForXtermJs()
+export const CHALK_CLAMPED_FOR_TMUX = clampChalkLevelForTmux()
+export const CHALK_USES_RICH_EIGHT_BIT_DOWNGRADE = shouldUseRichEightBitDowngradeForLegacyAppleTerminal()
+
+export type ColorType = 'foreground' | 'background'
+
+const RGB_REGEX = /^rgb\(\s?(\d+),\s?(\d+),\s?(\d+)\s?\)$/
+const ANSI_REGEX = /^ansi256\(\s?(\d+)\s?\)$/
+const HEX_REGEX = /^#[0-9a-fA-F]{6}$/
+
+export const colorize = (str: string, color: string | undefined, type: ColorType): string => {
+  if (!color) {
+    return str
+  }
+
+  if (color.startsWith('ansi:')) {
+    const value = color.substring('ansi:'.length)
+
+    switch (value) {
+      case 'black':
+        return type === 'foreground' ? chalk.black(str) : chalk.bgBlack(str)
+
+      case 'red':
+        return type === 'foreground' ? chalk.red(str) : chalk.bgRed(str)
+
+      case 'green':
+        return type === 'foreground' ? chalk.green(str) : chalk.bgGreen(str)
+
+      case 'yellow':
+        return type === 'foreground' ? chalk.yellow(str) : chalk.bgYellow(str)
+
+      case 'blue':
+        return type === 'foreground' ? chalk.blue(str) : chalk.bgBlue(str)
+
+      case 'magenta':
+        return type === 'foreground' ? chalk.magenta(str) : chalk.bgMagenta(str)
+
+      case 'cyan':
+        return type === 'foreground' ? chalk.cyan(str) : chalk.bgCyan(str)
+
+      case 'white':
+        return type === 'foreground' ? chalk.white(str) : chalk.bgWhite(str)
+
+      case 'blackBright':
+        return type === 'foreground' ? chalk.blackBright(str) : chalk.bgBlackBright(str)
+
+      case 'redBright':
+        return type === 'foreground' ? chalk.redBright(str) : chalk.bgRedBright(str)
+
+      case 'greenBright':
+        return type === 'foreground' ? chalk.greenBright(str) : chalk.bgGreenBright(str)
+
+      case 'yellowBright':
+        return type === 'foreground' ? chalk.yellowBright(str) : chalk.bgYellowBright(str)
+
+      case 'blueBright':
+        return type === 'foreground' ? chalk.blueBright(str) : chalk.bgBlueBright(str)
+
+      case 'magentaBright':
+        return type === 'foreground' ? chalk.magentaBright(str) : chalk.bgMagentaBright(str)
+
+      case 'cyanBright':
+        return type === 'foreground' ? chalk.cyanBright(str) : chalk.bgCyanBright(str)
+
+      case 'whiteBright':
+        return type === 'foreground' ? chalk.whiteBright(str) : chalk.bgWhiteBright(str)
+    }
+  }
+
+  if (color.startsWith('#')) {
+    if (HEX_REGEX.test(color) && CHALK_USES_RICH_EIGHT_BIT_DOWNGRADE) {
+      const value = Number.parseInt(color.slice(1), 16)
+      const red = (value >> 16) & 0xff
+      const green = (value >> 8) & 0xff
+      const blue = value & 0xff
+      const ansi = richEightBitColorNumber(red, green, blue)
+
+      return type === 'foreground' ? chalk.ansi256(ansi)(str) : chalk.bgAnsi256(ansi)(str)
+    }
+
+    return type === 'foreground' ? chalk.hex(color)(str) : chalk.bgHex(color)(str)
+  }
+
+  if (color.startsWith('ansi256')) {
+    const matches = ANSI_REGEX.exec(color)
+
+    if (!matches) {
+      return str
+    }
+
+    const value = Number(matches[1])
+
+    return type === 'foreground' ? chalk.ansi256(value)(str) : chalk.bgAnsi256(value)(str)
+  }
+
+  if (color.startsWith('rgb')) {
+    const matches = RGB_REGEX.exec(color)
+
+    if (!matches) {
+      return str
+    }
+
+    const firstValue = Number(matches[1])
+    const secondValue = Number(matches[2])
+    const thirdValue = Number(matches[3])
+
+    if (CHALK_USES_RICH_EIGHT_BIT_DOWNGRADE) {
+      const ansi = richEightBitColorNumber(firstValue, secondValue, thirdValue)
+
+      return type === 'foreground' ? chalk.ansi256(ansi)(str) : chalk.bgAnsi256(ansi)(str)
+    }
+
+    return type === 'foreground'
+      ? chalk.rgb(firstValue, secondValue, thirdValue)(str)
+      : chalk.bgRgb(firstValue, secondValue, thirdValue)(str)
+  }
+
+  return str
+}
+
+/**
+ * Apply TextStyles to a string using chalk.
+ * This is the inverse of parsing ANSI codes - we generate them from structured styles.
+ * Theme resolution happens at component layer, not here.
+ */
+export function applyTextStyles(text: string, styles: TextStyles): string {
+  let result = text
+
+  // Apply styles in reverse order of desired nesting.
+  // chalk wraps text so later calls become outer wrappers.
+  // Desired order (outermost to innermost):
+  //   background > foreground > text modifiers
+  // So we apply: text modifiers first, then foreground, then background last.
+
+  if (styles.inverse) {
+    result = chalk.inverse(result)
+  }
+
+  if (styles.strikethrough) {
+    result = chalk.strikethrough(result)
+  }
+
+  if (styles.underline) {
+    result = chalk.underline(result)
+  }
+
+  if (styles.italic) {
+    result = chalk.italic(result)
+  }
+
+  if (styles.bold) {
+    result = chalk.bold(result)
+  }
+
+  if (styles.dim) {
+    result = chalk.dim(result)
+  }
+
+  if (styles.color) {
+    // Color is now always a raw color value (theme resolution happens at component layer)
+    result = colorize(result, styles.color, 'foreground')
+  }
+
+  if (styles.backgroundColor) {
+    // backgroundColor is now always a raw color value
+    result = colorize(result, styles.backgroundColor, 'background')
+  }
+
+  return result
+}
+
+/**
+ * Apply a raw color value to text.
+ * Theme resolution should happen at component layer, not here.
+ */
+export function applyColor(text: string, color: Color | undefined): string {
+  if (!color) {
+    return text
+  }
+
+  return colorize(text, color, 'foreground')
+}

ui-tui/packages/hermes-ink/src/ink/components/AlternateScreen.tsx

@@ -0,0 +1,133 @@
+import React, { type PropsWithChildren, useContext, useInsertionEffect } from 'react'
+import { c as _c } from 'react/compiler-runtime'
+
+import instances from '../instances.js'
+import { CURSOR_HOME, ERASE_SCREEN, ERASE_SCROLLBACK } from '../termio/csi.js'
+import {
+  DISABLE_MOUSE_TRACKING,
+  enableMouseTrackingFor,
+  ENTER_ALT_SCREEN,
+  EXIT_ALT_SCREEN,
+  type MouseTrackingMode
+} from '../termio/dec.js'
+import { TerminalWriteContext } from '../useTerminalNotification.js'
+
+import Box from './Box.js'
+import { TerminalSizeContext } from './TerminalSizeContext.js'
+type Props = PropsWithChildren<{
+  /**
+   * Which SGR mouse-tracking preset to enable. Default `'all'` — wheel +
+   * click + drag + hover (1000 + 1002 + 1003 + 1006). Set to `'wheel'`
+   * (1000 + 1006) to silence the noisy hover events that tmux turns into
+   * "No image in clipboard" spam over the prompt row, while keeping
+   * scroll-wheel scrolling. `'off'` disables tracking entirely.
+   */
+  mouseTracking?: MouseTrackingMode
+}>
+
+/**
+ * Run children in the terminal's alternate screen buffer, constrained to
+ * the viewport height. While mounted:
+ *
+ * - Enters the alt screen (DEC 1049), clears it, homes the cursor
+ * - Constrains its own height to the terminal row count, so overflow must
+ *   be handled via `overflow: scroll` / flexbox (no native scrollback)
+ * - Optionally enables a subset of SGR mouse tracking (wheel-only,
+ *   wheel+drag, or wheel+drag+hover) — events surface as `ParsedKey`
+ *   (wheel) and update the Ink instance's selection state (click/drag).
+ *   See `MouseTrackingMode` for the available presets.
+ *
+ * On unmount, disables mouse tracking and exits the alt screen, restoring
+ * the main screen's content. Safe for use in ctrl-o transcript overlays
+ * and similar temporary fullscreen views — the main screen is preserved.
+ *
+ * Notifies the Ink instance via `setAltScreenActive()` so the renderer
+ * keeps the cursor inside the viewport (preventing the cursor-restore LF
+ * from scrolling content) and so signal-exit cleanup can exit the alt
+ * screen if the component's own unmount doesn't run.
+ */
+export function AlternateScreen(t0: Props) {
+  const $ = _c(7)
+
+  const { children, mouseTracking: t1 } = t0
+
+  const mouseTracking: MouseTrackingMode = t1 === undefined ? 'all' : t1
+  const size = useContext(TerminalSizeContext)
+  const writeRaw = useContext(TerminalWriteContext)
+  let t2
+  let t3
+
+  if ($[0] !== mouseTracking || $[1] !== writeRaw) {
+    t2 = () => {
+      const ink = instances.get(process.stdout)
+
+      if (!writeRaw) {
+        return
+      }
+
+      const enableMouse = enableMouseTrackingFor(mouseTracking)
+
+      // Always reset every mouse mode before enabling the requested preset
+      // so the terminal lands in an exact state. If a previous instance
+      // (crash, another app, lingering DECSET from a debugger) left DEC
+      // 1003 hover events asserted, picking 'wheel' or 'buttons' without
+      // an unconditional DISABLE would silently leave hover on and defeat
+      // the point of the preset.
+      writeRaw(
+        ENTER_ALT_SCREEN +
+          ERASE_SCROLLBACK +
+          ERASE_SCREEN +
+          CURSOR_HOME +
+          DISABLE_MOUSE_TRACKING +
+          enableMouse
+      )
+      ink?.setAltScreenActive(true, mouseTracking)
+      // setAltScreenActive(true, mouseTracking) above stores the mode for
+      // SIGCONT/resize/stdin-gap re-assertion. We don't also call
+      // setAltScreenMouseTracking(mouseTracking) here: it would early-return
+      // in the happy mode-change path (active flipped false→true with the
+      // new mode), and on any path where setAltScreenActive saw active was
+      // already true (so it didn't store mode), the writeRaw above has
+      // already DISABLE'd + enabled the new mode. A second
+      // setAltScreenMouseTracking would just duplicate the same DEC bytes.
+
+      return () => {
+        ink?.setAltScreenActive(false)
+        ink?.clearTextSelection()
+        // DISABLE_MOUSE_TRACKING is safe to send even when we never enabled
+        // tracking (it unconditionally resets all four modes). Sending it
+        // on every teardown means a crash mid-mount can't leak DEC modes
+        // back to the host shell.
+        writeRaw(DISABLE_MOUSE_TRACKING + EXIT_ALT_SCREEN)
+      }
+    }
+
+    t3 = [writeRaw, mouseTracking]
+    $[0] = mouseTracking
+    $[1] = writeRaw
+    $[2] = t2
+    $[3] = t3
+  } else {
+    t2 = $[2]
+    t3 = $[3]
+  }
+
+  useInsertionEffect(t2, t3)
+  const t4 = size?.rows ?? 24
+  let t5
+
+  if ($[4] !== children || $[5] !== t4) {
+    t5 = (
+      <Box flexDirection="column" flexShrink={0} height={t4} width="100%">
+        {children}
+      </Box>
+    )
+    $[4] = children
+    $[5] = t4
+    $[6] = t5
+  } else {
+    t5 = $[6]
+  }
+
+  return t5
+}

ui-tui/packages/hermes-ink/src/ink/components/AppContext.ts

@@ -0,0 +1,20 @@
+import { createContext } from 'react'
+
+export type Props = {
+  /**
+   * Exit (unmount) the whole Ink app.
+   */
+  readonly exit: (error?: Error) => void
+}
+
+/**
+ * `AppContext` is a React context, which exposes a method to manually exit the app (unmount).
+ */
+
+const AppContext = createContext<Props>({
+  exit() {}
+})
+
+AppContext.displayName = 'InternalAppContext'
+
+export default AppContext

ui-tui/packages/hermes-ink/src/ink/components/CursorAdvanceContext.ts

@@ -0,0 +1,35 @@
+import { createContext } from 'react'
+
+/**
+ * Notify Ink that the physical terminal cursor was advanced by an
+ * out-of-band stdout.write (e.g. the TextInput fast-echo path).
+ *
+ * This is a two-part notification — calling it updates both:
+ *
+ *   1. Ink's cached `displayCursor` (the basis log-update uses to
+ *      compute relative cursor moves for the next frame's preamble).
+ *      Without this, the next frame's preamble starts from a stale
+ *      parked position and the diff is rendered N cells offset.
+ *      This half is SKIPPED on alt-screen — every alt-screen frame
+ *      begins with CSI H which absolutely repositions the cursor, so
+ *      the relative-move basis is reset for free.
+ *
+ *   2. Ink's active `cursorDeclaration` (the target the cursor parks
+ *      at after every frame, set by `useDeclaredCursor`). Without
+ *      this, an unrelated component re-rendering before the deferred
+ *      React state catches up would publish a stale declaration and
+ *      visually undo the fast-echo's advance. This half applies to
+ *      BOTH main-screen and alt-screen — on alt-screen the cursor-
+ *      park branch in onRender emits an absolute CUP to
+ *      `rect.x + decl.relativeX`, so a stale declaration there is
+ *      still wrong even though displayCursor is skipped.
+ *
+ * `dx`/`dy` are deltas in terminal cells (positive = right/down,
+ * negative = left/up). The caller is responsible for ensuring the
+ * physical cursor really did move by that amount.
+ */
+export type CursorAdvanceNotifier = (dx: number, dy?: number) => void
+
+const CursorAdvanceContext = createContext<CursorAdvanceNotifier>(() => {})
+
+export default CursorAdvanceContext

ui-tui/packages/hermes-ink/src/ink/components/CursorDeclarationContext.ts

@@ -0,0 +1,28 @@
+import { createContext } from 'react'
+
+import type { DOMElement } from '../dom.js'
+
+export type CursorDeclaration = {
+  /** Display column (terminal cell width) within the declared node */
+  readonly relativeX: number
+  /** Line number within the declared node */
+  readonly relativeY: number
+  /** The ink-box DOMElement whose yoga layout provides the absolute origin */
+  readonly node: DOMElement
+}
+
+/**
+ * Setter for the declared cursor position.
+ *
+ * The optional second argument makes `null` a conditional clear: the
+ * declaration is only cleared if the currently-declared node matches
+ * `clearIfNode`. This makes the hook safe for sibling components
+ * (e.g. list items) that transfer focus among themselves — without the
+ * node check, a newly-unfocused item's clear could clobber a
+ * newly-focused sibling's set depending on layout-effect order.
+ */
+export type CursorDeclarationSetter = (declaration: CursorDeclaration | null, clearIfNode?: DOMElement | null) => void
+
+const CursorDeclarationContext = createContext<CursorDeclarationSetter>(() => {})
+
+export default CursorDeclarationContext

ui-tui/packages/hermes-ink/src/ink/components/Link.tsx

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react'
+import React from 'react'
+
+import Text from './Text.js'
+export type Props = {
+  readonly children?: ReactNode
+  readonly url: string
+  // Kept for backwards-compat: prior versions rendered `fallback` instead of
+  // the linked content on terminals where supportsHyperlinks() was false. We
+  // now always emit the hyperlink metadata so the in-process click/hover
+  // dispatcher can act on it regardless of the terminal's own OSC 8 support
+  // (see comment in the function body), so `fallback` is no longer wired up.
+  // Leaving the prop on the interface keeps existing call sites compiling.
+  readonly fallback?: ReactNode
+}
+
+export default function Link({ children, url }: Props): React.ReactNode {
+  // Always emit <ink-link>: the renderer stores `hyperlink` per cell in the
+  // screen buffer, which the click dispatcher (Ink.getHyperlinkAt →
+  // onHyperlinkClick) reads on mouseup to open URLs externally. Gating this
+  // on supportsHyperlinks() broke clicks in Apple Terminal / any terminal
+  // not on the OSC 8 allowlist — the cell's hyperlink field stayed empty,
+  // so the click pipeline had nothing to open.
+  //
+  // The OSC 8 escape itself is emitted unconditionally by the renderer
+  // (wrapWithOsc8Link in render-node-to-output.ts, oscLink in log-update.ts).
+  // Terminals that don't understand OSC 8 silently strip it — including
+  // Apple Terminal, which is why hover/click affordance has to come from
+  // the in-process overlay (applyHyperlinkHoverHighlight) and not from the
+  // terminal's own link rendering.
+  const content = children ?? url
+
+  return (
+    <Text>
+      <ink-link href={url}>{content}</ink-link>
+    </Text>
+  )
+}

ui-tui/packages/hermes-ink/src/ink/components/Newline.tsx

@@ -0,0 +1,43 @@
+import React from 'react'
+import { c as _c } from 'react/compiler-runtime'
+export type Props = {
+  /**
+   * Number of newlines to insert.
+   *
+   * @default 1
+   */
+  readonly count?: number
+}
+
+/**
+ * Adds one or more newline (\n) characters. Must be used within <Text> components.
+ */
+export default function Newline(t0: Props) {
+  const $ = _c(4)
+
+  const { count: t1 } = t0
+
+  const count = t1 === undefined ? 1 : t1
+  let t2
+
+  if ($[0] !== count) {
+    t2 = '\n'.repeat(count)
+    $[0] = count
+    $[1] = t2
+  } else {
+    t2 = $[1]
+  }
+
+  let t3
+
+  if ($[2] !== t2) {
+    t3 = <ink-text>{t2}</ink-text>
+    $[2] = t2
+    $[3] = t3
+  } else {
+    t3 = $[3]
+  }
+
+  return t3
+}
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6WyJSZWFjdCIsIlByb3BzIiwiY291bnQiLCJOZXdsaW5lIiwidDAiLCIkIiwiX2MiLCJ0MSIsInVuZGVmaW5lZCIsInQyIiwicmVwZWF0IiwidDMiXSwic291cmNlcyI6WyJOZXdsaW5lLnRzeCJdLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgUmVhY3QgZnJvbSAncmVhY3QnXG5cbmV4cG9ydCB0eXBlIFByb3BzID0ge1xuICAvKipcbiAgICogTnVtYmVyIG9mIG5ld2xpbmVzIHRvIGluc2VydC5cbiAgICpcbiAgICogQGRlZmF1bHQgMVxuICAgKi9cbiAgcmVhZG9ubHkgY291bnQ/OiBudW1iZXJcbn1cblxuLyoqXG4gKiBBZGRzIG9uZSBvciBtb3JlIG5ld2xpbmUgKFxcbikgY2hhcmFjdGVycy4gTXVzdCBiZSB1c2VkIHdpdGhpbiA8VGV4dD4gY29tcG9uZW50cy5cbiAqL1xuZXhwb3J0IGRlZmF1bHQgZnVuY3Rpb24gTmV3bGluZSh7IGNvdW50ID0gMSB9OiBQcm9wcykge1xuICByZXR1cm4gPGluay10ZXh0PnsnXFxuJy5yZXBlYXQoY291bnQpfTwvaW5rLXRleHQ+XG59XG4iXSwibWFwcGluZ3MiOiI7QUFBQSxPQUFPQSxLQUFLLE1BQU0sT0FBTztBQUV6QixPQUFPLEtBQUtDLEtBQUssR0FBRztFQUNsQjtBQUNGO0FBQ0E7QUFDQTtBQUNBO0VBQ0UsU0FBU0MsS0FBSyxDQUFDLEVBQUUsTUFBTTtBQUN6QixDQUFDOztBQUVEO0FBQ0E7QUFDQTtBQUNBLGVBQWUsU0FBQUMsUUFBQUMsRUFBQTtFQUFBLE1BQUFDLENBQUEsR0FBQUMsRUFBQTtFQUFpQjtJQUFBSixLQUFBLEVBQUFLO0VBQUEsSUFBQUgsRUFBb0I7RUFBbEIsTUFBQUYsS0FBQSxHQUFBSyxFQUFTLEtBQVRDLFNBQVMsR0FBVCxDQUFTLEdBQVRELEVBQVM7RUFBQSxJQUFBRSxFQUFBO0VBQUEsSUFBQUosQ0FBQSxRQUFBSCxLQUFBO0lBQ3ZCTyxFQUFBLE9BQUksQ0FBQUMsTUFBTyxDQUFDUixLQUFLLENBQUM7SUFBQUcsQ0FBQSxNQUFBSCxLQUFBO0lBQUFHLENBQUEsTUFBQUksRUFBQTtFQUFBO0lBQUFBLEVBQUEsR0FBQUosQ0FBQTtFQUFBO0VBQUEsSUFBQU0sRUFBQTtFQUFBLElBQUFOLENBQUEsUUFBQUksRUFBQTtJQUE3QkUsRUFBQSxZQUF5QyxDQUE5QixDQUFBRixFQUFpQixDQUFFLEVBQTlCLFFBQXlDO0lBQUFKLENBQUEsTUFBQUksRUFBQTtJQUFBSixDQUFBLE1BQUFNLEVBQUE7RUFBQTtJQUFBQSxFQUFBLEdBQUFOLENBQUE7RUFBQTtFQUFBLE9BQXpDTSxFQUF5QztBQUFBIiwiaWdub3JlTGlzdCI6W119

ui-tui/packages/hermes-ink/src/ink/components/NoSelect.tsx

@@ -0,0 +1,73 @@
+import React from 'react'
+import { c as _c } from 'react/compiler-runtime'
+
+import Box, { type Props as BoxProps } from './Box.js'
+type Props = Omit<BoxProps, 'noSelect'> & {
+  /**
+   * Extend the exclusion zone from column 0 to this box's right edge,
+   * for every row this box occupies. Use for gutters rendered inside a
+   * wider indented container (e.g. a diff inside a tool message row):
+   * without this, a multi-row drag picks up the container's leading
+   * indent on rows below the prefix.
+   *
+   * @default false
+   */
+  fromLeftEdge?: boolean
+}
+
+/**
+ * Marks its contents as non-selectable in fullscreen text selection.
+ * Cells inside this box are skipped by both the selection highlight and
+ * the copied text — the gutter stays visually unchanged while the user
+ * drags, making it clear what will be copied.
+ *
+ * Use to fence off gutters (line numbers, diff +/- sigils, list bullets)
+ * so click-drag over rendered code yields clean pasteable content:
+ *
+ *   <Box flexDirection="row">
+ *     <NoSelect fromLeftEdge><Text dimColor> 42 +</Text></NoSelect>
+ *     <Text>const x = 1</Text>
+ *   </Box>
+ *
+ * Only affects alt-screen text selection (<AlternateScreen> with mouse
+ * tracking). No-op in the main-screen scrollback render where the
+ * terminal's native selection is used instead.
+ */
+export function NoSelect(t0: Props) {
+  const $ = _c(8)
+  let boxProps
+  let children
+  let fromLeftEdge
+
+  if ($[0] !== t0) {
+    ;({ children, fromLeftEdge, ...boxProps } = t0)
+    $[0] = t0
+    $[1] = boxProps
+    $[2] = children
+    $[3] = fromLeftEdge
+  } else {
+    boxProps = $[1]
+    children = $[2]
+    fromLeftEdge = $[3]
+  }
+
+  const t1 = fromLeftEdge ? 'from-left-edge' : true
+  let t2
+
+  if ($[4] !== boxProps || $[5] !== children || $[6] !== t1) {
+    t2 = (
+      <Box {...boxProps} noSelect={t1}>
+        {children}
+      </Box>
+    )
+    $[4] = boxProps
+    $[5] = children
+    $[6] = t1
+    $[7] = t2
+  } else {
+    t2 = $[7]
+  }
+
+  return t2
+}
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6WyJSZWFjdCIsIlByb3BzV2l0aENoaWxkcmVuIiwiQm94IiwiUHJvcHMiLCJCb3hQcm9wcyIsIk9taXQiLCJmcm9tTGVmdEVkZ2UiLCJOb1NlbGVjdCIsInQwIiwiJCIsIl9jIiwiYm94UHJvcHMiLCJjaGlsZHJlbiIsInQxIiwidDIiXSwic291cmNlcyI6WyJOb1NlbGVjdC50c3giXSwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IFJlYWN0LCB7IHR5cGUgUHJvcHNXaXRoQ2hpbGRyZW4gfSBmcm9tICdyZWFjdCdcbmltcG9ydCBCb3gsIHsgdHlwZSBQcm9wcyBhcyBCb3hQcm9wcyB9IGZyb20gJy4vQm94LmpzJ1xuXG50eXBlIFByb3BzID0gT21pdDxCb3hQcm9wcywgJ25vU2VsZWN0Jz4gJiB7XG4gIC8qKlxuICAgKiBFeHRlbmQgdGhlIGV4Y2x1c2lvbiB6b25lIGZyb20gY29sdW1uIDAgdG8gdGhpcyBib3gncyByaWdodCBlZGdlLFxuICAgKiBmb3IgZXZlcnkgcm93IHRoaXMgYm94IG9jY3VwaWVzLiBVc2UgZm9yIGd1dHRlcnMgcmVuZGVyZWQgaW5zaWRlIGFcbiAgICogd2lkZXIgaW5kZW50ZWQgY29udGFpbmVyIChlLmcuIGEgZGlmZiBpbnNpZGUgYSB0b29sIG1lc3NhZ2Ugcm93KTpcbiAgICogd2l0aG91dCB0aGlzLCBhIG11bHRpLXJvdyBkcmFnIHBpY2tzIHVwIHRoZSBjb250YWluZXIncyBsZWFkaW5nXG4gICAqIGluZGVudCBvbiByb3dzIGJlbG93IHRoZSBwcmVmaXguXG4gICAqXG4gICAqIEBkZWZhdWx0IGZhbHNlXG4gICAqL1xuICBmcm9tTGVmdEVkZ2U/OiBib29sZWFuXG59XG5cbi8qKlxuICogTWFya3MgaXRzIGNvbnRlbnRzIGFzIG5vbi1zZWxlY3RhYmxlIGluIGZ1bGxzY3JlZW4gdGV4dCBzZWxlY3Rpb24uXG4gKiBDZWxscyBpbnNpZGUgdGhpcyBib3ggYXJlIHNraXBwZWQgYnkgYm90aCB0aGUgc2VsZWN0aW9uIGhpZ2hsaWdodCBhbmRcbiAqIHRoZSBjb3BpZWQgdGV4dCDigJQgdGhlIGd1dHRlciBzdGF5cyB2aXN1YWxseSB1bmNoYW5nZWQgd2hpbGUgdGhlIHVzZXJcbiAqIGRyYWdzLCBtYWtpbmcgaXQgY2xlYXIgd2hhdCB3aWxsIGJlIGNvcGllZC5cbiAqXG4gKiBVc2UgdG8gZmVuY2Ugb2ZmIGd1dHRlcnMgKGxpbmUgbnVtYmVycywgZGlmZiArLy0gc2lnaWxzLCBsaXN0IGJ1bGxldHMpXG4gKiBzbyBjbGljay1kcmFnIG92ZXIgcmVuZGVyZWQgY29kZSB5aWVsZHMgY2xlYW4gcGFzdGVhYmxlIGNvbnRlbnQ6XG4gKlxuICogICA8Qm94IGZsZXhEaXJlY3Rpb249XCJyb3dcIj5cbiAqICAgICA8Tm9TZWxlY3QgZnJvbUxlZnRFZGdlPjxUZXh0IGRpbUNvbG9yPiA0MiArPC9UZXh0PjwvTm9TZWxlY3Q+XG4gKiAgICAgPFRleHQ+Y29uc3QgeCA9IDE8L1RleHQ+XG4gKiAgIDwvQm94PlxuICpcbiAqIE9ubHkgYWZmZWN0cyBhbHQtc2NyZWVuIHRleHQgc2VsZWN0aW9uICg8QWx0ZXJuYXRlU2NyZWVuPiB3aXRoIG1vdXNlXG4gKiB0cmFja2luZykuIE5vLW9wIGluIHRoZSBtYWluLXNjcmVlbiBzY3JvbGxiYWNrIHJlbmRlciB3aGVyZSB0aGVcbiAqIHRlcm1pbmFsJ3MgbmF0aXZlIHNlbGVjdGlvbiBpcyB1c2VkIGluc3RlYWQuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBOb1NlbGVjdCh7XG4gIGNoaWxkcmVuLFxuICBmcm9tTGVmdEVkZ2UsXG4gIC4uLmJveFByb3BzXG59OiBQcm9wc1dpdGhDaGlsZHJlbjxQcm9wcz4pOiBSZWFjdC5SZWFjdE5vZGUge1xuICByZXR1cm4gKFxuICAgIDxCb3ggey4uLmJveFByb3BzfSBub1NlbGVjdD17ZnJvbUxlZnRFZGdlID8gJ2Zyb20tbGVmdC1lZGdlJyA6IHRydWV9PlxuICAgICAge2NoaWxkcmVufVxuICAgIDwvQm94PlxuICApXG59XG4iXSwibWFwcGluZ3MiOiI7QUFBQSxPQUFPQSxLQUFLLElBQUksS0FBS0MsaUJBQWlCLFFBQVEsT0FBTztBQUNyRCxPQUFPQyxHQUFHLElBQUksS0FBS0MsS0FBSyxJQUFJQyxRQUFRLFFBQVEsVUFBVTtBQUV0RCxLQUFLRCxLQUFLLEdBQUdFLElBQUksQ0FBQ0QsUUFBUSxFQUFFLFVBQVUsQ0FBQyxHQUFHO0VBQ3hDO0FBQ0Y7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtFQUNFRSxZQUFZLENBQUMsRUFBRSxPQUFPO0FBQ3hCLENBQUM7O0FBRUQ7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0EsT0FBTyxTQUFBQyxTQUFBQyxFQUFBO0VBQUEsTUFBQUMsQ0FBQSxHQUFBQyxFQUFBO0VBQUEsSUFBQUMsUUFBQTtFQUFBLElBQUFDLFFBQUE7RUFBQSxJQUFBTixZQUFBO0VBQUEsSUFBQUcsQ0FBQSxRQUFBRCxFQUFBO0lBQWtCO01BQUFJLFFBQUE7TUFBQU4sWUFBQTtNQUFBLEdBQUFLO0lBQUEsSUFBQUgsRUFJRTtJQUFBQyxDQUFBLE1BQUFELEVBQUE7SUFBQUMsQ0FBQSxNQUFBRSxRQUFBO0lBQUFGLENBQUEsTUFBQUcsUUFBQTtJQUFBSCxDQUFBLE1BQUFILFlBQUE7RUFBQTtJQUFBSyxRQUFBLEdBQUFGLENBQUE7SUFBQUcsUUFBQSxHQUFBSCxDQUFBO0lBQUFILFlBQUEsR0FBQUcsQ0FBQTtFQUFBO0VBRU0sTUFBQUksRUFBQSxHQUFBUCxZQUFZLEdBQVosZ0JBQXNDLEdBQXRDLElBQXNDO0VBQUEsSUFBQVEsRUFBQTtFQUFBLElBQUFMLENBQUEsUUFBQUUsUUFBQSxJQUFBRixDQUFBLFFBQUFHLFFBQUEsSUFBQUgsQ0FBQSxRQUFBSSxFQUFBO0lBQW5FQyxFQUFBLElBQUMsR0FBRyxLQUFLSCxRQUFRLEVBQVksUUFBc0MsQ0FBdEMsQ0FBQUUsRUFBcUMsQ0FBQyxDQUNoRUQsU0FBTyxDQUNWLEVBRkMsR0FBRyxDQUVFO0lBQUFILENBQUEsTUFBQUUsUUFBQTtJQUFBRixDQUFBLE1BQUFHLFFBQUE7SUFBQUgsQ0FBQSxNQUFBSSxFQUFBO0lBQUFKLENBQUEsTUFBQUssRUFBQTtFQUFBO0lBQUFBLEVBQUEsR0FBQUwsQ0FBQTtFQUFBO0VBQUEsT0FGTkssRUFFTTtBQUFBIiwiaWdub3JlTGlzdCI6W119

ui-tui/packages/hermes-ink/src/ink/components/RawAnsi.tsx

@@ -0,0 +1,61 @@
+import React from 'react'
+import { c as _c } from 'react/compiler-runtime'
+type Props = {
+  /**
+   * Pre-rendered ANSI lines. Each element must be exactly one terminal row
+   * (already wrapped to `width` by the producer) with ANSI escape codes inline.
+   */
+  lines: string[]
+  /** Column width the producer wrapped to. Sent to Yoga as the fixed leaf width. */
+  width: number
+}
+
+/**
+ * Bypass the <Ansi> → React tree → Yoga → squash → re-serialize roundtrip for
+ * content that is already terminal-ready.
+ *
+ * Use this when an external renderer (e.g. the ColorDiff NAPI module) has
+ * already produced ANSI-escaped, width-wrapped output. A normal <Ansi> mount
+ * reparses that output into one React <Text> per style span, lays out each
+ * span as a Yoga flex child, then walks the tree to re-emit the same escape
+ * codes it was given. For a long transcript full of syntax-highlighted diffs
+ * that roundtrip is the dominant cost of the render.
+ *
+ * This component emits a single Yoga leaf with a constant-time measure func
+ * (width × lines.length) and hands the joined string straight to output.write(),
+ * which already splits on '\n' and parses ANSI into the screen buffer.
+ */
+export function RawAnsi(t0: Props) {
+  const $ = _c(6)
+
+  const { lines, width } = t0
+
+  if (lines.length === 0) {
+    return null
+  }
+
+  let t1
+
+  if ($[0] !== lines) {
+    t1 = lines.join('\n')
+    $[0] = lines
+    $[1] = t1
+  } else {
+    t1 = $[1]
+  }
+
+  let t2
+
+  if ($[2] !== lines.length || $[3] !== t1 || $[4] !== width) {
+    t2 = <ink-raw-ansi rawHeight={lines.length} rawText={t1} rawWidth={width} />
+    $[2] = lines.length
+    $[3] = t1
+    $[4] = width
+    $[5] = t2
+  } else {
+    t2 = $[5]
+  }
+
+  return t2
+}
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6WyJSZWFjdCIsIlByb3BzIiwibGluZXMiLCJ3aWR0aCIsIlJhd0Fuc2kiLCJ0MCIsIiQiLCJfYyIsImxlbmd0aCIsInQxIiwiam9pbiIsInQyIl0sInNvdXJjZXMiOlsiUmF3QW5zaS50c3giXSwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IFJlYWN0IGZyb20gJ3JlYWN0J1xuXG50eXBlIFByb3BzID0ge1xuICAvKipcbiAgICogUHJlLXJlbmRlcmVkIEFOU0kgbGluZXMuIEVhY2ggZWxlbWVudCBtdXN0IGJlIGV4YWN0bHkgb25lIHRlcm1pbmFsIHJvd1xuICAgKiAoYWxyZWFkeSB3cmFwcGVkIHRvIGB3aWR0aGAgYnkgdGhlIHByb2R1Y2VyKSB3aXRoIEFOU0kgZXNjYXBlIGNvZGVzIGlubGluZS5cbiAgICovXG4gIGxpbmVzOiBzdHJpbmdbXVxuICAvKiogQ29sdW1uIHdpZHRoIHRoZSBwcm9kdWNlciB3cmFwcGVkIHRvLiBTZW50IHRvIFlvZ2EgYXMgdGhlIGZpeGVkIGxlYWYgd2lkdGguICovXG4gIHdpZHRoOiBudW1iZXJcbn1cblxuLyoqXG4gKiBCeXBhc3MgdGhlIDxBbnNpPiDihpIgUmVhY3QgdHJlZSDihpIgWW9nYSDihpIgc3F1YXNoIOKGkiByZS1zZXJpYWxpemUgcm91bmR0cmlwIGZvclxuICogY29udGVudCB0aGF0IGlzIGFscmVhZHkgdGVybWluYWwtcmVhZHkuXG4gKlxuICogVXNlIHRoaXMgd2hlbiBhbiBleHRlcm5hbCByZW5kZXJlciAoZS5nLiB0aGUgQ29sb3JEaWZmIE5BUEkgbW9kdWxlKSBoYXNcbiAqIGFscmVhZHkgcHJvZHVjZWQgQU5TSS1lc2NhcGVkLCB3aWR0aC13cmFwcGVkIG91dHB1dC4gQSBub3JtYWwgPEFuc2k+IG1vdW50XG4gKiByZXBhcnNlcyB0aGF0IG91dHB1dCBpbnRvIG9uZSBSZWFjdCA8VGV4dD4gcGVyIHN0eWxlIHNwYW4sIGxheXMgb3V0IGVhY2hcbiAqIHNwYW4gYXMgYSBZb2dhIGZsZXggY2hpbGQsIHRoZW4gd2Fsa3MgdGhlIHRyZWUgdG8gcmUtZW1pdCB0aGUgc2FtZSBlc2NhcGVcbiAqIGNvZGVzIGl0IHdhcyBnaXZlbi4gRm9yIGEgbG9uZyB0cmFuc2NyaXB0IGZ1bGwgb2Ygc3ludGF4LWhpZ2hsaWdodGVkIGRpZmZzXG4gKiB0aGF0IHJvdW5kdHJpcCBpcyB0aGUgZG9taW5hbnQgY29zdCBvZiB0aGUgcmVuZGVyLlxuICpcbiAqIFRoaXMgY29tcG9uZW50IGVtaXRzIGEgc2luZ2xlIFlvZ2EgbGVhZiB3aXRoIGEgY29uc3RhbnQtdGltZSBtZWFzdXJlIGZ1bmNcbiAqICh3aWR0aCDDlyBsaW5lcy5sZW5ndGgpIGFuZCBoYW5kcyB0aGUgam9pbmVkIHN0cmluZyBzdHJhaWdodCB0byBvdXRwdXQud3JpdGUoKSxcbiAqIHdoaWNoIGFscmVhZHkgc3BsaXRzIG9uICdcXG4nIGFuZCBwYXJzZXMgQU5TSSBpbnRvIHRoZSBzY3JlZW4gYnVmZmVyLlxuICovXG5leHBvcnQgZnVuY3Rpb24gUmF3QW5zaSh7IGxpbmVzLCB3aWR0aCB9OiBQcm9wcyk6IFJlYWN0LlJlYWN0Tm9kZSB7XG4gIGlmIChsaW5lcy5sZW5ndGggPT09IDApIHtcbiAgICByZXR1cm4gbnVsbFxuICB9XG4gIHJldHVybiAoXG4gICAgPGluay1yYXctYW5zaVxuICAgICAgcmF3VGV4dD17bGluZXMuam9pbignXFxuJyl9XG4gICAgICByYXdXaWR0aD17d2lkdGh9XG4gICAgICByYXdIZWlnaHQ9e2xpbmVzLmxlbmd0aH1cbiAgICAvPlxuICApXG59XG4iXSwibWFwcGluZ3MiOiI7QUFBQSxPQUFPQSxLQUFLLE1BQU0sT0FBTztBQUV6QixLQUFLQyxLQUFLLEdBQUc7RUFDWDtBQUNGO0FBQ0E7QUFDQTtFQUNFQyxLQUFLLEVBQUUsTUFBTSxFQUFFO0VBQ2Y7RUFDQUMsS0FBSyxFQUFFLE1BQU07QUFDZixDQUFDOztBQUVEO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBLE9BQU8sU0FBQUMsUUFBQUMsRUFBQTtFQUFBLE1BQUFDLENBQUEsR0FBQUMsRUFBQTtFQUFpQjtJQUFBTCxLQUFBO0lBQUFDO0VBQUEsSUFBQUUsRUFBdUI7RUFDN0MsSUFBSUgsS0FBSyxDQUFBTSxNQUFPLEtBQUssQ0FBQztJQUFBLE9BQ2IsSUFBSTtFQUFBO0VBQ1osSUFBQUMsRUFBQTtFQUFBLElBQUFILENBQUEsUUFBQUosS0FBQTtJQUdZTyxFQUFBLEdBQUFQLEtBQUssQ0FBQVEsSUFBSyxDQUFDLElBQUksQ0FBQztJQUFBSixDQUFBLE1BQUFKLEtBQUE7SUFBQUksQ0FBQSxNQUFBRyxFQUFBO0VBQUE7SUFBQUEsRUFBQSxHQUFBSCxDQUFBO0VBQUE7RUFBQSxJQUFBSyxFQUFBO0VBQUEsSUFBQUwsQ0FBQSxRQUFBSixLQUFBLENBQUFNLE1BQUEsSUFBQUYsQ0FBQSxRQUFBRyxFQUFBLElBQUFILENBQUEsUUFBQUgsS0FBQTtJQUQzQlEsRUFBQSxnQkFJRSxDQUhTLE9BQWdCLENBQWhCLENBQUFGLEVBQWUsQ0FBQyxDQUNmTixRQUFLLENBQUxBLE1BQUksQ0FBQyxDQUNKLFNBQVksQ0FBWixDQUFBRCxLQUFLLENBQUFNLE1BQU0sQ0FBQyxHQUN2QjtJQUFBRixDQUFBLE1BQUFKLEtBQUEsQ0FBQU0sTUFBQTtJQUFBRixDQUFBLE1BQUFHLEVBQUE7SUFBQUgsQ0FBQSxNQUFBSCxLQUFBO0lBQUFHLENBQUEsTUFBQUssRUFBQTtFQUFBO0lBQUFBLEVBQUEsR0FBQUwsQ0FBQTtFQUFBO0VBQUEsT0FKRkssRUFJRTtBQUFBIiwiaWdub3JlTGlzdCI6W119

ui-tui/packages/hermes-ink/src/ink/components/Spacer.tsx

@@ -0,0 +1,23 @@
+import React from 'react'
+import { c as _c } from 'react/compiler-runtime'
+
+import Box from './Box.js'
+
+/**
+ * A flexible space that expands along the major axis of its containing layout.
+ * It's useful as a shortcut for filling all the available spaces between elements.
+ */
+export default function Spacer() {
+  const $ = _c(1)
+  let t0
+
+  if ($[0] === Symbol.for('react.memo_cache_sentinel')) {
+    t0 = <Box flexGrow={1} />
+    $[0] = t0
+  } else {
+    t0 = $[0]
+  }
+
+  return t0
+}
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6WyJSZWFjdCIsIkJveCIsIlNwYWNlciIsIiQiLCJfYyIsInQwIiwiU3ltYm9sIiwiZm9yIl0sInNvdXJjZXMiOlsiU3BhY2VyLnRzeCJdLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgUmVhY3QgZnJvbSAncmVhY3QnXG5pbXBvcnQgQm94IGZyb20gJy4vQm94LmpzJ1xuXG4vKipcbiAqIEEgZmxleGlibGUgc3BhY2UgdGhhdCBleHBhbmRzIGFsb25nIHRoZSBtYWpvciBheGlzIG9mIGl0cyBjb250YWluaW5nIGxheW91dC5cbiAqIEl0J3MgdXNlZnVsIGFzIGEgc2hvcnRjdXQgZm9yIGZpbGxpbmcgYWxsIHRoZSBhdmFpbGFibGUgc3BhY2VzIGJldHdlZW4gZWxlbWVudHMuXG4gKi9cbmV4cG9ydCBkZWZhdWx0IGZ1bmN0aW9uIFNwYWNlcigpIHtcbiAgcmV0dXJuIDxCb3ggZmxleEdyb3c9ezF9IC8+XG59XG4iXSwibWFwcGluZ3MiOiI7QUFBQSxPQUFPQSxLQUFLLE1BQU0sT0FBTztBQUN6QixPQUFPQyxHQUFHLE1BQU0sVUFBVTs7QUFFMUI7QUFDQTtBQUNBO0FBQ0E7QUFDQSxlQUFlLFNBQUFDLE9BQUE7RUFBQSxNQUFBQyxDQUFBLEdBQUFDLEVBQUE7RUFBQSxJQUFBQyxFQUFBO0VBQUEsSUFBQUYsQ0FBQSxRQUFBRyxNQUFBLENBQUFDLEdBQUE7SUFDTkYsRUFBQSxJQUFDLEdBQUcsQ0FBVyxRQUFDLENBQUQsR0FBQyxHQUFJO0lBQUFGLENBQUEsTUFBQUUsRUFBQTtFQUFBO0lBQUFBLEVBQUEsR0FBQUYsQ0FBQTtFQUFBO0VBQUEsT0FBcEJFLEVBQW9CO0FBQUEiLCJpZ25vcmVMaXN0IjpbXX0=

ui-tui/packages/hermes-ink/src/ink/components/StdinContext.ts

@@ -0,0 +1,25 @@
+import { createContext } from 'react'
+
+import { EventEmitter } from '../events/emitter.js'
+import type { TerminalQuerier } from '../terminal-querier.js'
+
+export type Props = {
+  readonly stdin: NodeJS.ReadStream
+  readonly setRawMode: (value: boolean) => void
+  readonly isRawModeSupported: boolean
+  readonly exitOnCtrlC: boolean
+  readonly inputEmitter: EventEmitter
+  readonly querier: TerminalQuerier | null
+}
+
+const StdinContext = createContext<Props>({
+  stdin: process.stdin,
+  inputEmitter: new EventEmitter(),
+  setRawMode() {},
+  isRawModeSupported: false,
+  exitOnCtrlC: true,
+  querier: null
+})
+
+StdinContext.displayName = 'StdinContext'
+export default StdinContext

ui-tui/packages/hermes-ink/src/ink/components/TerminalFocusContext.tsx

@@ -0,0 +1,63 @@
+import React, { createContext, type ReactNode, useSyncExternalStore } from 'react'
+import { c as _c } from 'react/compiler-runtime'
+
+import {
+  getTerminalFocused,
+  getTerminalFocusState,
+  subscribeTerminalFocus,
+  type TerminalFocusState
+} from '../terminal-focus-state.js'
+export type { TerminalFocusState }
+export type TerminalFocusContextProps = {
+  readonly isTerminalFocused: boolean
+  readonly terminalFocusState: TerminalFocusState
+}
+
+const TerminalFocusContext = createContext<TerminalFocusContextProps>({
+  isTerminalFocused: true,
+  terminalFocusState: 'unknown'
+})
+
+TerminalFocusContext.displayName = 'TerminalFocusContext'
+
+// Separate component so App.tsx doesn't re-render on focus changes.
+// Children are a stable prop reference, so they don't re-render either —
+// only components that consume the context will re-render.
+export function TerminalFocusProvider(t0: { readonly children: ReactNode }) {
+  const $ = _c(6)
+
+  const { children } = t0
+
+  const isTerminalFocused = useSyncExternalStore(subscribeTerminalFocus, getTerminalFocused)
+  const terminalFocusState = useSyncExternalStore(subscribeTerminalFocus, getTerminalFocusState)
+  let t1
+
+  if ($[0] !== isTerminalFocused || $[1] !== terminalFocusState) {
+    t1 = {
+      isTerminalFocused,
+      terminalFocusState
+    }
+    $[0] = isTerminalFocused
+    $[1] = terminalFocusState
+    $[2] = t1
+  } else {
+    t1 = $[2]
+  }
+
+  const value = t1
+  let t2
+
+  if ($[3] !== children || $[4] !== value) {
+    t2 = <TerminalFocusContext.Provider value={value}>{children}</TerminalFocusContext.Provider>
+    $[3] = children
+    $[4] = value
+    $[5] = t2
+  } else {
+    t2 = $[5]
+  }
+
+  return t2
+}
+
+export default TerminalFocusContext
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6WyJSZWFjdCIsImNyZWF0ZUNvbnRleHQiLCJ1c2VNZW1vIiwidXNlU3luY0V4dGVybmFsU3RvcmUiLCJnZXRUZXJtaW5hbEZvY3VzZWQiLCJnZXRUZXJtaW5hbEZvY3VzU3RhdGUiLCJzdWJzY3JpYmVUZXJtaW5hbEZvY3VzIiwiVGVybWluYWxGb2N1c1N0YXRlIiwiVGVybWluYWxGb2N1c0NvbnRleHRQcm9wcyIsImlzVGVybWluYWxGb2N1c2VkIiwidGVybWluYWxGb2N1c1N0YXRlIiwiVGVybWluYWxGb2N1c0NvbnRleHQiLCJkaXNwbGF5TmFtZSIsIlRlcm1pbmFsRm9jdXNQcm92aWRlciIsInQwIiwiJCIsIl9jIiwiY2hpbGRyZW4iLCJ0MSIsInZhbHVlIiwidDIiXSwic291cmNlcyI6WyJUZXJtaW5hbEZvY3VzQ29udGV4dC50c3giXSwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IFJlYWN0LCB7IGNyZWF0ZUNvbnRleHQsIHVzZU1lbW8sIHVzZVN5bmNFeHRlcm5hbFN0b3JlIH0gZnJvbSAncmVhY3QnXG5pbXBvcnQge1xuICBnZXRUZXJtaW5hbEZvY3VzZWQsXG4gIGdldFRlcm1pbmFsRm9jdXNTdGF0ZSxcbiAgc3Vic2NyaWJlVGVybWluYWxGb2N1cyxcbiAgdHlwZSBUZXJtaW5hbEZvY3VzU3RhdGUsXG59IGZyb20gJy4uL3Rlcm1pbmFsLWZvY3VzLXN0YXRlLmpzJ1xuXG5leHBvcnQgdHlwZSB7IFRlcm1pbmFsRm9jdXNTdGF0ZSB9XG5cbmV4cG9ydCB0eXBlIFRlcm1pbmFsRm9jdXNDb250ZXh0UHJvcHMgPSB7XG4gIHJlYWRvbmx5IGlzVGVybWluYWxGb2N1c2VkOiBib29sZWFuXG4gIHJlYWRvbmx5IHRlcm1pbmFsRm9jdXNTdGF0ZTogVGVybWluYWxGb2N1c1N0YXRlXG59XG5cbmNvbnN0IFRlcm1pbmFsRm9jdXNDb250ZXh0ID0gY3JlYXRlQ29udGV4dDxUZXJtaW5hbEZvY3VzQ29udGV4dFByb3BzPih7XG4gIGlzVGVybWluYWxGb2N1c2VkOiB0cnVlLFxuICB0ZXJtaW5hbEZvY3VzU3RhdGU6ICd1bmtub3duJyxcbn0pXG5cbi8vIGVzbGludC1kaXNhYmxlLW5leHQtbGluZSBjdXN0b20tcnVsZXMvbm8tdG9wLWxldmVsLXNpZGUtZWZmZWN0c1xuVGVybWluYWxGb2N1c0NvbnRleHQuZGlzcGxheU5hbWUgPSAnVGVybWluYWxGb2N1c0NvbnRleHQnXG5cbi8vIFNlcGFyYXRlIGNvbXBvbmVudCBzbyBBcHAudHN4IGRvZXNuJ3QgcmUtcmVuZGVyIG9uIGZvY3VzIGNoYW5nZXMuXG4vLyBDaGlsZHJlbiBhcmUgYSBzdGFibGUgcHJvcCByZWZlcmVuY2UsIHNvIHRoZXkgZG9uJ3QgcmUtcmVuZGVyIGVpdGhlciDigJRcbi8vIG9ubHkgY29tcG9uZW50cyB0aGF0IGNvbnN1bWUgdGhlIGNvbnRleHQgd2lsbCByZS1yZW5kZXIuXG5leHBvcnQgZnVuY3Rpb24gVGVybWluYWxGb2N1c1Byb3ZpZGVyKHtcbiAgY2hpbGRyZW4sXG59OiB7XG4gIGNoaWxkcmVuOiBSZWFjdC5SZWFjdE5vZGVcbn0pOiBSZWFjdC5SZWFjdE5vZGUge1xuICBjb25zdCBpc1Rlcm1pbmFsRm9jdXNlZCA9IHVzZVN5bmNFeHRlcm5hbFN0b3JlKFxuICAgIHN1YnNjcmliZVRlcm1pbmFsRm9jdXMsXG4gICAgZ2V0VGVybWluYWxGb2N1c2VkLFxuICApXG4gIGNvbnN0IHRlcm1pbmFsRm9jdXNTdGF0ZSA9IHVzZVN5bmNFeHRlcm5hbFN0b3JlKFxuICAgIHN1YnNjcmliZVRlcm1pbmFsRm9jdXMsXG4gICAgZ2V0VGVybWluYWxGb2N1c1N0YXRlLFxuICApXG5cbiAgY29uc3QgdmFsdWUgPSB1c2VNZW1vKFxuICAgICgpID0+ICh7IGlzVGVybWluYWxGb2N1c2VkLCB0ZXJtaW5hbEZvY3VzU3RhdGUgfSksXG4gICAgW2lzVGVybWluYWxGb2N1c2VkLCB0ZXJtaW5hbEZvY3VzU3RhdGVdLFxuICApXG5cbiAgcmV0dXJuIChcbiAgICA8VGVybWluYWxGb2N1c0NvbnRleHQuUHJvdmlkZXIgdmFsdWU9e3ZhbHVlfT5cbiAgICAgIHtjaGlsZHJlbn1cbiAgICA8L1Rlcm1pbmFsRm9jdXNDb250ZXh0LlByb3ZpZGVyPlxuICApXG59XG5cbmV4cG9ydCBkZWZhdWx0IFRlcm1pbmFsRm9jdXNDb250ZXh0XG4iXSwibWFwcGluZ3MiOiI7QUFBQSxPQUFPQSxLQUFLLElBQUlDLGFBQWEsRUFBRUMsT0FBTyxFQUFFQyxvQkFBb0IsUUFBUSxPQUFPO0FBQzNFLFNBQ0VDLGtCQUFrQixFQUNsQkMscUJBQXFCLEVBQ3JCQyxzQkFBc0IsRUFDdEIsS0FBS0Msa0JBQWtCLFFBQ2xCLDRCQUE0QjtBQUVuQyxjQUFjQSxrQkFBa0I7QUFFaEMsT0FBTyxLQUFLQyx5QkFBeUIsR0FBRztFQUN0QyxTQUFTQyxpQkFBaUIsRUFBRSxPQUFPO0VBQ25DLFNBQVNDLGtCQUFrQixFQUFFSCxrQkFBa0I7QUFDakQsQ0FBQztBQUVELE1BQU1JLG9CQUFvQixHQUFHVixhQUFhLENBQUNPLHlCQUF5QixDQUFDLENBQUM7RUFDcEVDLGlCQUFpQixFQUFFLElBQUk7RUFDdkJDLGtCQUFrQixFQUFFO0FBQ3RCLENBQUMsQ0FBQzs7QUFFRjtBQUNBQyxvQkFBb0IsQ0FBQ0MsV0FBVyxHQUFHLHNCQUFzQjs7QUFFekQ7QUFDQTtBQUNBO0FBQ0EsT0FBTyxTQUFBQyxzQkFBQUMsRUFBQTtFQUFBLE1BQUFDLENBQUEsR0FBQUMsRUFBQTtFQUErQjtJQUFBQztFQUFBLElBQUFILEVBSXJDO0VBQ0MsTUFBQUwsaUJBQUEsR0FBMEJOLG9CQUFvQixDQUM1Q0csc0JBQXNCLEVBQ3RCRixrQkFDRixDQUFDO0VBQ0QsTUFBQU0sa0JBQUEsR0FBMkJQLG9CQUFvQixDQUM3Q0csc0JBQXNCLEVBQ3RCRCxxQkFDRixDQUFDO0VBQUEsSUFBQWEsRUFBQTtFQUFBLElBQUFILENBQUEsUUFBQU4saUJBQUEsSUFBQU0sQ0FBQSxRQUFBTCxrQkFBQTtJQUdRUSxFQUFBO01BQUFULGlCQUFBO01BQUFDO0lBQXdDLENBQUM7SUFBQUssQ0FBQSxNQUFBTixpQkFBQTtJQUFBTSxDQUFBLE1BQUFMLGtCQUFBO0lBQUFLLENBQUEsTUFBQUcsRUFBQTtFQUFBO0lBQUFBLEVBQUEsR0FBQUgsQ0FBQTtFQUFBO0VBRGxELE1BQUFJLEtBQUEsR0FDU0QsRUFBeUM7RUFFakQsSUFBQUUsRUFBQTtFQUFBLElBQUFMLENBQUEsUUFBQUUsUUFBQSxJQUFBRixDQUFBLFFBQUFJLEtBQUE7SUFHQ0MsRUFBQSxrQ0FBc0NELEtBQUssQ0FBTEEsTUFBSSxDQUFDLENBQ3hDRixTQUFPLENBQ1YsZ0NBQWdDO0lBQUFGLENBQUEsTUFBQUUsUUFBQTtJQUFBRixDQUFBLE1BQUFJLEtBQUE7SUFBQUosQ0FBQSxNQUFBSyxFQUFBO0VBQUE7SUFBQUEsRUFBQSxHQUFBTCxDQUFBO0VBQUE7RUFBQSxPQUZoQ0ssRUFFZ0M7QUFBQTtBQUlwQyxlQUFlVCxvQkFBb0IiLCJpZ25vcmVMaXN0IjpbXX0=

ui-tui/packages/hermes-ink/src/ink/components/TerminalSizeContext.tsx

@@ -0,0 +1,7 @@
+import { createContext } from 'react'
+export type TerminalSize = {
+  columns: number
+  rows: number
+}
+export const TerminalSizeContext = createContext<TerminalSize | null>(null)
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6WyJjcmVhdGVDb250ZXh0IiwiVGVybWluYWxTaXplIiwiY29sdW1ucyIsInJvd3MiLCJUZXJtaW5hbFNpemVDb250ZXh0Il0sInNvdXJjZXMiOlsiVGVybWluYWxTaXplQ29udGV4dC50c3giXSwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHsgY3JlYXRlQ29udGV4dCB9IGZyb20gJ3JlYWN0J1xuXG5leHBvcnQgdHlwZSBUZXJtaW5hbFNpemUgPSB7XG4gIGNvbHVtbnM6IG51bWJlclxuICByb3dzOiBudW1iZXJcbn1cblxuZXhwb3J0IGNvbnN0IFRlcm1pbmFsU2l6ZUNvbnRleHQgPSBjcmVhdGVDb250ZXh0PFRlcm1pbmFsU2l6ZSB8IG51bGw+KG51bGwpXG4iXSwibWFwcGluZ3MiOiJBQUFBLFNBQVNBLGFBQWEsUUFBUSxPQUFPO0FBRXJDLE9BQU8sS0FBS0MsWUFBWSxHQUFHO0VBQ3pCQyxPQUFPLEVBQUUsTUFBTTtFQUNmQyxJQUFJLEVBQUUsTUFBTTtBQUNkLENBQUM7QUFFRCxPQUFPLE1BQU1DLG1CQUFtQixHQUFHSixhQUFhLENBQUNDLFlBQVksR0FBRyxJQUFJLENBQUMsQ0FBQyxJQUFJLENBQUMiLCJpZ25vcmVMaXN0IjpbXX0=

ui-tui/packages/hermes-ink/src/ink/components/Text.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest'
+
+import { dimColorFallback, shouldUseAnsiDim } from './Text.js'
+
+describe('shouldUseAnsiDim', () => {
+  it('disables ANSI dim on VTE terminals by default', () => {
+    expect(shouldUseAnsiDim({ VTE_VERSION: '7603' } as NodeJS.ProcessEnv)).toBe(false)
+  })
+
+  it('disables ANSI dim on Apple Terminal by default', () => {
+    expect(shouldUseAnsiDim({ TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv)).toBe(false)
+  })
+
+  it('keeps ANSI dim enabled elsewhere by default', () => {
+    expect(shouldUseAnsiDim({ TERM: 'xterm-256color' } as NodeJS.ProcessEnv)).toBe(true)
+  })
+
+  it('honors explicit env override', () => {
+    expect(shouldUseAnsiDim({ HERMES_TUI_DIM: '1', VTE_VERSION: '7603' } as NodeJS.ProcessEnv)).toBe(true)
+    expect(shouldUseAnsiDim({ HERMES_TUI_DIM: '1', TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv)).toBe(true)
+    expect(shouldUseAnsiDim({ HERMES_TUI_DIM: '0' } as NodeJS.ProcessEnv)).toBe(false)
+  })
+})
+
+describe('dimColorFallback', () => {
+  it('renders Apple Terminal dim as muted gray by default', () => {
+    expect(dimColorFallback({ TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv)).toBe('#6B7280')
+  })
+
+  it('normalizes Apple Terminal names before matching', () => {
+    expect(dimColorFallback({ TERM_PROGRAM: ' Apple_Terminal ' } as NodeJS.ProcessEnv)).toBe('#6B7280')
+  })
+
+  it('does not apply when dim is explicitly configured', () => {
+    expect(dimColorFallback({ HERMES_TUI_DIM: '1', TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv)).toBeUndefined()
+    expect(dimColorFallback({ HERMES_TUI_DIM: '0', TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv)).toBeUndefined()
+  })
+})

ui-tui/packages/hermes-ink/src/ink/constants.ts

@@ -0,0 +1,6 @@
+// Shared frame interval for render throttling and animations (~60fps).
+export const FRAME_INTERVAL_MS = 16
+
+// Keep clock-driven animations at full speed when terminal focus changes.
+// We still pause entirely when there are no keepAlive subscribers.
+export const BLURRED_FRAME_INTERVAL_MS = FRAME_INTERVAL_MS

ui-tui/packages/hermes-ink/src/ink/cursor.ts

@@ -0,0 +1,5 @@
+export type Cursor = {
+  x: number
+  y: number
+  visible: boolean
+}

ui-tui/packages/hermes-ink/src/ink/devtools.ts

@@ -0,0 +1,2 @@
+/** Optional react-devtools hook; package may be absent. */
+export {}

ui-tui/packages/hermes-ink/src/ink/dom.ts

@@ -0,0 +1,495 @@
+import type { FocusManager } from './focus.js'
+import { createLayoutNode } from './layout/engine.js'
+import type { LayoutNode } from './layout/node.js'
+import { LayoutMeasureMode } from './layout/node.js'
+import measureText from './measure-text.js'
+import { addPendingClear, nodeCache } from './node-cache.js'
+import squashTextNodes from './squash-text-nodes.js'
+import type { Styles, TextStyles } from './styles.js'
+import { expandTabs } from './tabstops.js'
+import wrapText from './wrap-text.js'
+
+type InkNode = {
+  parentNode: DOMElement | undefined
+  yogaNode?: LayoutNode
+  style: Styles
+}
+
+export type TextName = '#text'
+export type ElementNames =
+  | 'ink-root'
+  | 'ink-box'
+  | 'ink-text'
+  | 'ink-virtual-text'
+  | 'ink-link'
+  | 'ink-progress'
+  | 'ink-raw-ansi'
+
+export type NodeNames = ElementNames | TextName
+
+export type DOMElement = {
+  nodeName: ElementNames
+  attributes: Record<string, DOMNodeAttribute>
+  childNodes: DOMNode[]
+  textStyles?: TextStyles
+
+  // Internal properties
+  onComputeLayout?: () => void
+  onRender?: () => void
+  onImmediateRender?: () => void
+  // Used to skip empty renders during React 19's effect double-invoke in test mode
+  hasRenderedContent?: boolean
+
+  // When true, this node needs re-rendering
+  dirty: boolean
+  // Set by the reconciler's hideInstance/unhideInstance; survives style updates.
+  isHidden?: boolean
+  // Event handlers set by the reconciler for the capture/bubble dispatcher.
+  // Stored separately from attributes so handler identity changes don't
+  // mark dirty and defeat the blit optimization.
+  _eventHandlers?: Record<string, unknown>
+
+  // Scroll state for overflow: 'scroll' boxes. scrollTop is the number of
+  // rows the content is scrolled down by. scrollHeight/scrollViewportHeight
+  // are computed at render time and stored for imperative access. stickyScroll
+  // auto-pins scrollTop to the bottom when content grows.
+  scrollTop?: number
+  // Accumulated scroll delta not yet applied to scrollTop. The renderer
+  // drains this at SCROLL_MAX_PER_FRAME rows/frame so fast flicks show
+  // intermediate frames instead of one big jump. Direction reversal
+  // naturally cancels (pure accumulator, no target tracking).
+  pendingScrollDelta?: number
+  // Render-time clamp bounds for virtual scroll. useVirtualScroll writes
+  // the currently-mounted children's coverage span; render-node-to-output
+  // clamps scrollTop to stay within it. Prevents blank screen when
+  // scrollTo's direct write races past React's async re-render — instead
+  // of painting spacer (blank), the renderer holds at the edge of mounted
+  // content until React catches up (next commit updates these bounds and
+  // the clamp releases). Undefined = no clamp (sticky-scroll, cold start).
+  scrollClampMin?: number
+  scrollClampMax?: number
+  scrollHeight?: number
+  scrollViewportHeight?: number
+  scrollViewportTop?: number
+  stickyScroll?: boolean
+  notifyScrollChange?: () => void
+  // Set by ScrollBox.scrollToElement; render-node-to-output reads
+  // el.yogaNode.getComputedTop() (FRESH — same Yoga pass as scrollHeight)
+  // and sets scrollTop = top + offset, then clears this. Unlike an
+  // imperative scrollTo(N) which bakes in a number that's stale by the
+  // time the throttled render fires, the element ref defers the position
+  // read to paint time. One-shot.
+  scrollAnchor?: { el: DOMElement; offset: number }
+  // Only set on ink-root. The document owns focus — any node can
+  // reach it by walking parentNode, like browser getRootNode().
+  focusManager?: FocusManager
+  // Measurement cache for ink-text nodes: avoids re-squashing and re-wrapping
+  // text when yoga calls measureFunc multiple times per frame with different
+  // widths during flex re-pass. Keyed by `${width}|${widthMode}`.
+  _textMeasureCache?: { gen: number; entries: Map<string, { _gen: number; result: { width: number; height: number } }> }
+} & InkNode
+
+export type TextNode = {
+  nodeName: TextName
+  nodeValue: string
+} & InkNode
+
+export type DOMNode<T = { nodeName: NodeNames }> = T extends {
+  nodeName: infer U
+}
+  ? U extends '#text'
+    ? TextNode
+    : DOMElement
+  : never
+
+export type DOMNodeAttribute = boolean | string | number
+
+export const createNode = (nodeName: ElementNames): DOMElement => {
+  const needsYogaNode = nodeName !== 'ink-virtual-text' && nodeName !== 'ink-link' && nodeName !== 'ink-progress'
+
+  const node: DOMElement = {
+    nodeName,
+    style: {},
+    attributes: {},
+    childNodes: [],
+    parentNode: undefined,
+    yogaNode: needsYogaNode ? createLayoutNode() : undefined,
+    dirty: false
+  }
+
+  if (nodeName === 'ink-text') {
+    node.yogaNode?.setMeasureFunc(measureTextNode.bind(null, node))
+  } else if (nodeName === 'ink-raw-ansi') {
+    node.yogaNode?.setMeasureFunc(measureRawAnsiNode.bind(null, node))
+  }
+
+  return node
+}
+
+export const appendChildNode = (node: DOMElement, childNode: DOMElement): void => {
+  if (childNode.parentNode) {
+    removeChildNode(childNode.parentNode, childNode)
+  }
+
+  childNode.parentNode = node
+  node.childNodes.push(childNode)
+
+  if (childNode.yogaNode) {
+    node.yogaNode?.insertChild(childNode.yogaNode, node.yogaNode.getChildCount())
+  }
+
+  markDirty(node)
+}
+
+export const insertBeforeNode = (node: DOMElement, newChildNode: DOMNode, beforeChildNode: DOMNode): void => {
+  if (newChildNode.parentNode) {
+    removeChildNode(newChildNode.parentNode, newChildNode)
+  }
+
+  newChildNode.parentNode = node
+
+  const index = node.childNodes.indexOf(beforeChildNode)
+
+  if (index >= 0) {
+    // Calculate yoga index BEFORE modifying childNodes.
+    // We can't use DOM index directly because some children (like ink-progress,
+    // ink-link, ink-virtual-text) don't have yogaNodes, so DOM indices don't
+    // match yoga indices.
+    let yogaIndex = 0
+
+    if (newChildNode.yogaNode && node.yogaNode) {
+      for (let i = 0; i < index; i++) {
+        if (node.childNodes[i]?.yogaNode) {
+          yogaIndex++
+        }
+      }
+    }
+
+    node.childNodes.splice(index, 0, newChildNode)
+
+    if (newChildNode.yogaNode && node.yogaNode) {
+      node.yogaNode.insertChild(newChildNode.yogaNode, yogaIndex)
+    }
+
+    markDirty(node)
+
+    return
+  }
+
+  node.childNodes.push(newChildNode)
+
+  if (newChildNode.yogaNode) {
+    node.yogaNode?.insertChild(newChildNode.yogaNode, node.yogaNode.getChildCount())
+  }
+
+  markDirty(node)
+}
+
+export const removeChildNode = (node: DOMElement, removeNode: DOMNode): void => {
+  if (removeNode.yogaNode) {
+    removeNode.parentNode?.yogaNode?.removeChild(removeNode.yogaNode)
+  }
+
+  // Collect cached rects from the removed subtree so they can be cleared
+  collectRemovedRects(node, removeNode)
+
+  removeNode.parentNode = undefined
+
+  const index = node.childNodes.indexOf(removeNode)
+
+  if (index >= 0) {
+    node.childNodes.splice(index, 1)
+  }
+
+  markDirty(node)
+}
+
+function collectRemovedRects(parent: DOMElement, removed: DOMNode, underAbsolute = false): void {
+  if (removed.nodeName === '#text') {
+    return
+  }
+
+  const elem = removed as DOMElement
+  // If this node or any ancestor in the removed subtree was absolute,
+  // its painted pixels may overlap non-siblings — flag for global blit
+  // disable. Normal-flow removals only affect direct siblings, which
+  // hasRemovedChild already handles.
+  const isAbsolute = underAbsolute || elem.style.position === 'absolute'
+  const cached = nodeCache.get(elem)
+
+  if (cached) {
+    addPendingClear(parent, cached, isAbsolute)
+    nodeCache.delete(elem)
+  }
+
+  for (const child of elem.childNodes) {
+    collectRemovedRects(parent, child, isAbsolute)
+  }
+}
+
+export const setAttribute = (node: DOMElement, key: string, value: DOMNodeAttribute): void => {
+  // Skip 'children' - React handles children via appendChild/removeChild,
+  // not attributes. React always passes a new children reference, so
+  // tracking it as an attribute would mark everything dirty every render.
+  if (key === 'children') {
+    return
+  }
+
+  // Skip if unchanged
+  if (node.attributes[key] === value) {
+    return
+  }
+
+  node.attributes[key] = value
+  markDirty(node)
+}
+
+export const setStyle = (node: DOMNode, style: Styles): void => {
+  // Compare style properties to avoid marking dirty unnecessarily.
+  // React creates new style objects on every render even when unchanged.
+  if (stylesEqual(node.style, style)) {
+    return
+  }
+
+  node.style = style
+  markDirty(node)
+}
+
+export const setTextStyles = (node: DOMElement, textStyles: TextStyles): void => {
+  // Same dirty-check guard as setStyle: React (and buildTextStyles in Text.tsx)
+  // allocate a new textStyles object on every render even when values are
+  // unchanged, so compare by value to avoid markDirty -> yoga re-measurement
+  // on every Text re-render.
+  if (shallowEqual(node.textStyles, textStyles)) {
+    return
+  }
+
+  node.textStyles = textStyles
+  markDirty(node)
+}
+
+function stylesEqual(a: Styles, b: Styles): boolean {
+  return shallowEqual(a, b)
+}
+
+function shallowEqual<T extends object>(a: T | undefined, b: T | undefined): boolean {
+  // Fast path: same object reference (or both undefined)
+  if (a === b) {
+    return true
+  }
+
+  if (a === undefined || b === undefined) {
+    return false
+  }
+
+  // Get all keys from both objects
+  const aKeys = Object.keys(a) as (keyof T)[]
+  const bKeys = Object.keys(b) as (keyof T)[]
+
+  // Different number of properties
+  if (aKeys.length !== bKeys.length) {
+    return false
+  }
+
+  // Compare each property
+  for (const key of aKeys) {
+    if (a[key] !== b[key]) {
+      return false
+    }
+  }
+
+  return true
+}
+
+export const createTextNode = (text: string): TextNode => {
+  const node: TextNode = {
+    nodeName: '#text',
+    nodeValue: text,
+    yogaNode: undefined,
+    parentNode: undefined,
+    style: {}
+  }
+
+  setTextNodeValue(node, text)
+
+  return node
+}
+
+const MEASURE_CACHE_CAP = 16
+
+const measureTextNode = function (
+  node: DOMNode,
+  width: number,
+  widthMode: LayoutMeasureMode
+): { width: number; height: number } {
+  const elem = node.nodeName !== '#text' ? (node as DOMElement) : node.parentNode
+
+  if (elem && elem.nodeName === 'ink-text') {
+    let cache = elem._textMeasureCache
+
+    if (!cache) {
+      cache = { gen: 0, entries: new Map() }
+      elem._textMeasureCache = cache
+    }
+
+    const key = `${width}|${widthMode}`
+    const hit = cache.entries.get(key)
+
+    if (hit && hit._gen === cache.gen) {
+      return hit.result
+    }
+
+    const result = computeTextMeasure(node, width, widthMode)
+
+    // Enforce cap with FIFO eviction to avoid unbounded growth during
+    // pathological frames where yoga probes many widths.
+    if (cache.entries.size >= MEASURE_CACHE_CAP) {
+      const firstKey = cache.entries.keys().next().value
+
+      if (firstKey !== undefined) {
+        cache.entries.delete(firstKey)
+      }
+    }
+
+    cache.entries.set(key, { _gen: cache.gen, result })
+
+    return result
+  }
+
+  return computeTextMeasure(node, width, widthMode)
+}
+
+const computeTextMeasure = function (
+  node: DOMNode,
+  width: number,
+  widthMode: LayoutMeasureMode
+): { width: number; height: number } {
+  const rawText = node.nodeName === '#text' ? node.nodeValue : squashTextNodes(node)
+
+  // Expand tabs for measurement (worst case: 8 spaces each).
+  // Actual tab expansion happens in output.ts based on screen position.
+  const text = expandTabs(rawText)
+
+  const dimensions = measureText(text, width)
+
+  // Text fits into container, no need to wrap
+  if (dimensions.width <= width) {
+    return dimensions
+  }
+
+  // This is happening when <Box> is shrinking child nodes and layout asks
+  // if we can fit this text node in a <1px space, so we just say "no"
+  if (dimensions.width >= 1 && width > 0 && width < 1) {
+    return dimensions
+  }
+
+  // For text with embedded newlines (pre-wrapped content), avoid re-wrapping
+  // at measurement width when layout is asking for intrinsic size (Undefined mode).
+  // This prevents height inflation during min/max size checks.
+  //
+  // However, when layout provides an actual constraint (Exactly or AtMost mode),
+  // we must respect it and measure at that width. Otherwise, if the actual
+  // rendering width is smaller than the natural width, the text will wrap to
+  // more lines than layout expects, causing content to be truncated.
+  if (text.includes('\n') && widthMode === LayoutMeasureMode.Undefined) {
+    const effectiveWidth = Math.max(width, dimensions.width)
+
+    return measureText(text, effectiveWidth)
+  }
+
+  const textWrap = node.style?.textWrap ?? 'wrap'
+  const wrappedText = wrapText(text, width, textWrap)
+
+  return measureText(wrappedText, width)
+}
+
+// ink-raw-ansi nodes hold pre-rendered ANSI strings with known dimensions.
+// No stringWidth, no wrapping, no tab expansion — the producer (e.g. ColorDiff)
+// already wrapped to the target width and each line is exactly one terminal row.
+const measureRawAnsiNode = function (node: DOMElement): {
+  width: number
+  height: number
+} {
+  return {
+    width: node.attributes['rawWidth'] as number,
+    height: node.attributes['rawHeight'] as number
+  }
+}
+
+/**
+ * Mark a node and all its ancestors as dirty for re-rendering.
+ * Also marks yoga dirty for text remeasurement if this is a text node.
+ */
+export const markDirty = (node?: DOMNode): void => {
+  let current: DOMNode | undefined = node
+  let markedYoga = false
+
+  while (current) {
+    if (current.nodeName !== '#text') {
+      const elem = current as DOMElement
+      elem.dirty = true
+
+      // Only mark yoga dirty on leaf nodes that have measure functions
+      if (!markedYoga && (elem.nodeName === 'ink-text' || elem.nodeName === 'ink-raw-ansi') && elem.yogaNode) {
+        elem.yogaNode.markDirty()
+        markedYoga = true
+      }
+
+      // Invalidate text measurement cache — child text or style changed.
+      if (elem._textMeasureCache) {
+        elem._textMeasureCache.gen++
+      }
+    }
+
+    current = current.parentNode
+  }
+}
+
+// Walk to root and call its onRender (the throttled scheduleRender). Use for
+// DOM-level mutations (scrollTop changes) that should trigger an Ink frame
+// without going through React's reconciler. Pair with markDirty() so the
+// renderer knows which subtree to re-evaluate.
+export const scheduleRenderFrom = (node?: DOMNode): void => {
+  let cur: DOMNode | undefined = node
+
+  while (cur?.parentNode) {
+    cur = cur.parentNode
+  }
+
+  if (cur && cur.nodeName !== '#text') {
+    ;(cur as DOMElement).onRender?.()
+  }
+}
+
+export const setTextNodeValue = (node: TextNode, text: string): void => {
+  if (typeof text !== 'string') {
+    text = String(text)
+  }
+
+  // Skip if unchanged
+  if (node.nodeValue === text) {
+    return
+  }
+
+  node.nodeValue = text
+  markDirty(node)
+}
+
+function isDOMElement(node: DOMElement | TextNode): node is DOMElement {
+  return node.nodeName !== '#text'
+}
+
+// Clear yogaNode references recursively before freeing.
+// freeRecursive() frees the node and ALL its children, so we must clear
+// all yogaNode references to prevent dangling pointers.
+export const clearYogaNodeReferences = (node: DOMElement | TextNode): void => {
+  if ('childNodes' in node) {
+    for (const child of node.childNodes) {
+      clearYogaNodeReferences(child)
+    }
+
+    node._textMeasureCache = undefined
+  }
+
+  node.yogaNode = undefined
+}

ui-tui/packages/hermes-ink/src/ink/events/click-event.ts

@@ -0,0 +1,38 @@
+import { Event } from './event.js'
+
+/**
+ * Mouse click event. Fired on left-button release without drag, only when
+ * mouse tracking is enabled (i.e. inside <AlternateScreen>).
+ *
+ * Bubbles from the deepest hit node up through parentNode. Call
+ * stopImmediatePropagation() to prevent ancestors' onClick from firing.
+ */
+export class ClickEvent extends Event {
+  /** 0-indexed screen column of the click */
+  readonly col: number
+  /** 0-indexed screen row of the click */
+  readonly row: number
+  /**
+   * Click column relative to the current handler's Box (col - box.x).
+   * Recomputed by dispatchClick before each handler fires, so an onClick
+   * on a container sees coords relative to that container, not to any
+   * child the click landed on.
+   */
+  localCol = 0
+  /** Click row relative to the current handler's Box (row - box.y). */
+  localRow = 0
+  /**
+   * True if the clicked cell has no visible content (unwritten in the
+   * screen buffer — both packed words are 0). Handlers can check this to
+   * ignore clicks on blank space to the right of text, so accidental
+   * clicks on empty terminal space don't toggle state.
+   */
+  readonly cellIsBlank: boolean
+
+  constructor(col: number, row: number, cellIsBlank: boolean) {
+    super()
+    this.col = col
+    this.row = row
+    this.cellIsBlank = cellIsBlank
+  }
+}

ui-tui/packages/hermes-ink/src/ink/events/cmd-shortcuts.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest'
+
+import { parseMultipleKeypresses } from '../parse-keypress.js'
+
+import { InputEvent } from './input-event.js'
+
+function parseOne(sequence: string) {
+  const [keys] = parseMultipleKeypresses({ incomplete: '', mode: 'NORMAL' }, sequence)
+  expect(keys).toHaveLength(1)
+
+  return keys[0]!
+}
+
+describe('enhanced keyboard modifier parsing', () => {
+  it('detects modified Enter sequences for multiline composer shortcuts', () => {
+    const shiftEnter = new InputEvent(parseOne('\u001b[13;2u'))
+    const ctrlEnter = new InputEvent(parseOne('\u001b[13;5u'))
+    const modifyOtherShiftEnter = new InputEvent(parseOne('\u001b[27;2;13~'))
+
+    expect(shiftEnter.key.return).toBe(true)
+    expect(shiftEnter.key.shift).toBe(true)
+    expect(shiftEnter.input).toBe('')
+
+    expect(ctrlEnter.key.return).toBe(true)
+    expect(ctrlEnter.key.ctrl).toBe(true)
+    expect(ctrlEnter.input).toBe('')
+
+    expect(modifyOtherShiftEnter.key.return).toBe(true)
+    expect(modifyOtherShiftEnter.key.shift).toBe(true)
+    expect(modifyOtherShiftEnter.input).toBe('')
+  })
+
+  it('preserves Cmd as super for kitty keyboard CSI-u sequences', () => {
+    const parsed = parseOne('\u001b[99;9u')
+    const event = new InputEvent(parsed)
+
+    expect(parsed.name).toBe('c')
+    expect(event.key.meta).toBe(false)
+    expect(event.key.super).toBe(true)
+  })
+
+  it('preserves forwarded VS Code/Cursor Cmd+C copy sequence as ctrl+super+c', () => {
+    const parsed = parseOne('\u001b[99;13u')
+    const event = new InputEvent(parsed)
+
+    expect(parsed.name).toBe('c')
+    expect(event.key.ctrl).toBe(true)
+    expect(event.key.super).toBe(true)
+  })
+
+  it('preserves Cmd on word-delete and word-navigation sequences', () => {
+    const backspace = new InputEvent(parseOne('\u001b[127;9u'))
+    const left = new InputEvent(parseOne('\u001b[1;9D'))
+    const right = new InputEvent(parseOne('\u001b[1;9C'))
+
+    expect(backspace.key.backspace).toBe(true)
+    expect(backspace.key.super).toBe(true)
+
+    expect(left.key.leftArrow).toBe(true)
+    expect(left.key.super).toBe(true)
+
+    expect(right.key.rightArrow).toBe(true)
+    expect(right.key.super).toBe(true)
+  })
+})

ui-tui/packages/hermes-ink/src/ink/events/dispatcher.ts

@@ -0,0 +1,242 @@
+import {
+  ContinuousEventPriority,
+  DefaultEventPriority,
+  DiscreteEventPriority,
+  NoEventPriority
+} from 'react-reconciler/constants.js'
+
+import { logError } from '../../utils/log.js'
+
+import { HANDLER_FOR_EVENT } from './event-handlers.js'
+import type { EventTarget, TerminalEvent } from './terminal-event.js'
+
+// --
+
+type DispatchListener = {
+  node: EventTarget
+  handler: (event: TerminalEvent) => void
+  phase: 'capturing' | 'at_target' | 'bubbling'
+}
+
+function getHandler(
+  node: EventTarget,
+  eventType: string,
+  capture: boolean
+): ((event: TerminalEvent) => void) | undefined {
+  const handlers = node._eventHandlers
+
+  if (!handlers) {
+    return undefined
+  }
+
+  const mapping = HANDLER_FOR_EVENT[eventType]
+
+  if (!mapping) {
+    return undefined
+  }
+
+  const propName = capture ? mapping.capture : mapping.bubble
+
+  if (!propName) {
+    return undefined
+  }
+
+  return handlers[propName] as ((event: TerminalEvent) => void) | undefined
+}
+
+/**
+ * Collect all listeners for an event in dispatch order.
+ *
+ * Uses react-dom's two-phase accumulation pattern:
+ * - Walk from target to root
+ * - Capture handlers are prepended (unshift) → root-first
+ * - Bubble handlers are appended (push) → target-first
+ *
+ * Result: [root-cap, ..., parent-cap, target-cap, target-bub, parent-bub, ..., root-bub]
+ */
+function collectListeners(target: EventTarget, event: TerminalEvent): DispatchListener[] {
+  const listeners: DispatchListener[] = []
+
+  let node: EventTarget | undefined = target
+
+  while (node) {
+    const isTarget = node === target
+
+    const captureHandler = getHandler(node, event.type, true)
+    const bubbleHandler = getHandler(node, event.type, false)
+
+    if (captureHandler) {
+      listeners.unshift({
+        node,
+        handler: captureHandler,
+        phase: isTarget ? 'at_target' : 'capturing'
+      })
+    }
+
+    if (bubbleHandler && (event.bubbles || isTarget)) {
+      listeners.push({
+        node,
+        handler: bubbleHandler,
+        phase: isTarget ? 'at_target' : 'bubbling'
+      })
+    }
+
+    node = node.parentNode
+  }
+
+  return listeners
+}
+
+/**
+ * Execute collected listeners with propagation control.
+ *
+ * Before each handler, calls event._prepareForTarget(node) so event
+ * subclasses can do per-node setup.
+ */
+function processDispatchQueue(listeners: DispatchListener[], event: TerminalEvent): void {
+  let previousNode: EventTarget | undefined
+
+  for (const { node, handler, phase } of listeners) {
+    if (event._isImmediatePropagationStopped()) {
+      break
+    }
+
+    if (event._isPropagationStopped() && node !== previousNode) {
+      break
+    }
+
+    event._setEventPhase(phase)
+    event._setCurrentTarget(node)
+    event._prepareForTarget(node)
+
+    try {
+      handler(event)
+    } catch (error) {
+      logError(error)
+    }
+
+    previousNode = node
+  }
+}
+
+// --
+
+/**
+ * Map terminal event types to React scheduling priorities.
+ * Mirrors react-dom's getEventPriority() switch.
+ */
+function getEventPriority(eventType: string): number {
+  switch (eventType) {
+    case 'keydown':
+
+    case 'keyup':
+
+    case 'click':
+
+    case 'focus':
+
+    case 'blur':
+
+    case 'paste':
+      return DiscreteEventPriority as number
+
+    case 'resize':
+
+    case 'scroll':
+
+    case 'mousemove':
+      return ContinuousEventPriority as number
+
+    default:
+      return DefaultEventPriority as number
+  }
+}
+
+// --
+
+type DiscreteUpdates = <A, B>(fn: (a: A, b: B) => boolean, a: A, b: B, c: undefined, d: undefined) => boolean
+
+/**
+ * Owns event dispatch state and the capture/bubble dispatch loop.
+ *
+ * The reconciler host config reads currentEvent and currentUpdatePriority
+ * to implement resolveUpdatePriority, resolveEventType, and
+ * resolveEventTimeStamp — mirroring how react-dom's host config reads
+ * ReactDOMSharedInternals and window.event.
+ *
+ * discreteUpdates is injected after construction (by InkReconciler)
+ * to break the import cycle.
+ */
+export class Dispatcher {
+  currentEvent: TerminalEvent | null = null
+  currentUpdatePriority: number = DefaultEventPriority as number
+  discreteUpdates: DiscreteUpdates | null = null
+
+  /**
+   * Infer event priority from the currently-dispatching event.
+   * Called by the reconciler host config's resolveUpdatePriority
+   * when no explicit priority has been set.
+   */
+  resolveEventPriority(): number {
+    if (this.currentUpdatePriority !== (NoEventPriority as number)) {
+      return this.currentUpdatePriority
+    }
+
+    if (this.currentEvent) {
+      return getEventPriority(this.currentEvent.type)
+    }
+
+    return DefaultEventPriority as number
+  }
+
+  /**
+   * Dispatch an event through capture and bubble phases.
+   * Returns true if preventDefault() was NOT called.
+   */
+  dispatch(target: EventTarget, event: TerminalEvent): boolean {
+    const previousEvent = this.currentEvent
+    this.currentEvent = event
+
+    try {
+      event._setTarget(target)
+
+      const listeners = collectListeners(target, event)
+      processDispatchQueue(listeners, event)
+
+      event._setEventPhase('none')
+      event._setCurrentTarget(null)
+
+      return !event.defaultPrevented
+    } finally {
+      this.currentEvent = previousEvent
+    }
+  }
+
+  /**
+   * Dispatch with discrete (sync) priority.
+   * For user-initiated events: keyboard, click, focus, paste.
+   */
+  dispatchDiscrete(target: EventTarget, event: TerminalEvent): boolean {
+    if (!this.discreteUpdates) {
+      return this.dispatch(target, event)
+    }
+
+    return this.discreteUpdates((t, e) => this.dispatch(t, e), target, event, undefined, undefined)
+  }
+
+  /**
+   * Dispatch with continuous priority.
+   * For high-frequency events: resize, scroll, mouse move.
+   */
+  dispatchContinuous(target: EventTarget, event: TerminalEvent): boolean {
+    const previousPriority = this.currentUpdatePriority
+
+    try {
+      this.currentUpdatePriority = ContinuousEventPriority as number
+
+      return this.dispatch(target, event)
+    } finally {
+      this.currentUpdatePriority = previousPriority
+    }
+  }
+}

ui-tui/packages/hermes-ink/src/ink/events/emitter.ts

@@ -0,0 +1,40 @@
+import { EventEmitter as NodeEventEmitter } from 'events'
+
+import { Event } from './event.js'
+
+// Similar to node's builtin EventEmitter, but is also aware of our `Event`
+// class, and so `emit` respects `stopImmediatePropagation()`.
+export class EventEmitter extends NodeEventEmitter {
+  constructor() {
+    super()
+    // Disable the default maxListeners warning. In React, many components
+    // can legitimately listen to the same event (e.g., useInput hooks).
+    // The default limit of 10 causes spurious warnings.
+    this.setMaxListeners(0)
+  }
+
+  override emit(type: string | symbol, ...args: unknown[]): boolean {
+    // Delegate to node for `error`, since it's not treated like a normal event
+    if (type === 'error') {
+      return super.emit(type, ...args)
+    }
+
+    const listeners = this.rawListeners(type)
+
+    if (listeners.length === 0) {
+      return false
+    }
+
+    const ccEvent = args[0] instanceof Event ? args[0] : null
+
+    for (const listener of listeners) {
+      listener.apply(this, args)
+
+      if (ccEvent?.didStopImmediatePropagation()) {
+        break
+      }
+    }
+
+    return true
+  }
+}

ui-tui/packages/hermes-ink/src/ink/events/event-handlers.ts

@@ -0,0 +1,84 @@
+import type { ClickEvent } from './click-event.js'
+import type { FocusEvent } from './focus-event.js'
+import type { KeyboardEvent } from './keyboard-event.js'
+import type { MouseEvent } from './mouse-event.js'
+import type { PasteEvent } from './paste-event.js'
+import type { ResizeEvent } from './resize-event.js'
+
+type KeyboardEventHandler = (event: KeyboardEvent) => void
+type FocusEventHandler = (event: FocusEvent) => void
+type PasteEventHandler = (event: PasteEvent) => void
+type ResizeEventHandler = (event: ResizeEvent) => void
+type ClickEventHandler = (event: ClickEvent) => void
+type MouseEventHandler = (event: MouseEvent) => void
+type HoverEventHandler = () => void
+
+/**
+ * Props for event handlers on Box and other host components.
+ *
+ * Follows the React/DOM naming convention:
+ * - onEventName: handler for bubble phase
+ * - onEventNameCapture: handler for capture phase
+ */
+export type EventHandlerProps = {
+  onKeyDown?: KeyboardEventHandler
+  onKeyDownCapture?: KeyboardEventHandler
+
+  onFocus?: FocusEventHandler
+  onFocusCapture?: FocusEventHandler
+  onBlur?: FocusEventHandler
+  onBlurCapture?: FocusEventHandler
+
+  onPaste?: PasteEventHandler
+  onPasteCapture?: PasteEventHandler
+
+  onResize?: ResizeEventHandler
+
+  onClick?: ClickEventHandler
+  onMouseDown?: MouseEventHandler
+  onMouseUp?: MouseEventHandler
+  onMouseDrag?: MouseEventHandler
+  onMouseEnter?: HoverEventHandler
+  onMouseLeave?: HoverEventHandler
+}
+
+/**
+ * Reverse lookup: event type string → handler prop names.
+ * Used by the dispatcher for O(1) handler lookup per node.
+ */
+export const HANDLER_FOR_EVENT: Record<
+  string,
+  { bubble?: keyof EventHandlerProps; capture?: keyof EventHandlerProps }
+> = {
+  keydown: { bubble: 'onKeyDown', capture: 'onKeyDownCapture' },
+  focus: { bubble: 'onFocus', capture: 'onFocusCapture' },
+  blur: { bubble: 'onBlur', capture: 'onBlurCapture' },
+  paste: { bubble: 'onPaste', capture: 'onPasteCapture' },
+  resize: { bubble: 'onResize' },
+  click: { bubble: 'onClick' },
+  mousedown: { bubble: 'onMouseDown' },
+  mouseup: { bubble: 'onMouseUp' },
+  mousedrag: { bubble: 'onMouseDrag' }
+}
+
+/**
+ * Set of all event handler prop names, for the reconciler to detect
+ * event props and store them in _eventHandlers instead of attributes.
+ */
+export const EVENT_HANDLER_PROPS = new Set<string>([
+  'onKeyDown',
+  'onKeyDownCapture',
+  'onFocus',
+  'onFocusCapture',
+  'onBlur',
+  'onBlurCapture',
+  'onPaste',
+  'onPasteCapture',
+  'onResize',
+  'onClick',
+  'onMouseDown',
+  'onMouseUp',
+  'onMouseDrag',
+  'onMouseEnter',
+  'onMouseLeave'
+])

ui-tui/packages/hermes-ink/src/ink/events/event.ts

@@ -0,0 +1,11 @@
+export class Event {
+  private _didStopImmediatePropagation = false
+
+  didStopImmediatePropagation(): boolean {
+    return this._didStopImmediatePropagation
+  }
+
+  stopImmediatePropagation(): void {
+    this._didStopImmediatePropagation = true
+  }
+}

ui-tui/packages/hermes-ink/src/ink/events/focus-event.ts

@@ -0,0 +1,18 @@
+import { type EventTarget, TerminalEvent } from './terminal-event.js'
+
+/**
+ * Focus event for component focus changes.
+ *
+ * Dispatched when focus moves between elements. 'focus' fires on the
+ * newly focused element, 'blur' fires on the previously focused one.
+ * Both bubble, matching react-dom's use of focusin/focusout semantics
+ * so parent components can observe descendant focus changes.
+ */
+export class FocusEvent extends TerminalEvent {
+  readonly relatedTarget: EventTarget | null
+
+  constructor(type: 'focus' | 'blur', relatedTarget: EventTarget | null = null) {
+    super(type, { bubbles: true, cancelable: false })
+    this.relatedTarget = relatedTarget
+  }
+}

ui-tui/packages/hermes-ink/src/ink/events/input-event.ts

@@ -0,0 +1,176 @@
+import { nonAlphanumericKeys, type ParsedKey } from '../parse-keypress.js'
+
+import { Event } from './event.js'
+
+const inputForSpecialSequence = (name: string): string =>
+  name === 'space' ? ' ' : name === 'return' || name === 'escape' ? '' : name
+
+export type Key = {
+  upArrow: boolean
+  downArrow: boolean
+  leftArrow: boolean
+  rightArrow: boolean
+  pageDown: boolean
+  pageUp: boolean
+  wheelUp: boolean
+  wheelDown: boolean
+  home: boolean
+  end: boolean
+  return: boolean
+  escape: boolean
+  ctrl: boolean
+  shift: boolean
+  fn: boolean
+  tab: boolean
+  backspace: boolean
+  delete: boolean
+  meta: boolean
+  super: boolean
+}
+
+function parseKey(keypress: ParsedKey): [Key, string] {
+  const key: Key = {
+    upArrow: keypress.name === 'up',
+    downArrow: keypress.name === 'down',
+    leftArrow: keypress.name === 'left',
+    rightArrow: keypress.name === 'right',
+    pageDown: keypress.name === 'pagedown',
+    pageUp: keypress.name === 'pageup',
+    wheelUp: keypress.name === 'wheelup',
+    wheelDown: keypress.name === 'wheeldown',
+    home: keypress.name === 'home',
+    end: keypress.name === 'end',
+    return: keypress.name === 'return',
+    escape: keypress.name === 'escape',
+    fn: keypress.fn,
+    ctrl: keypress.ctrl,
+    shift: keypress.shift,
+    tab: keypress.name === 'tab',
+    backspace: keypress.name === 'backspace',
+    delete: keypress.name === 'delete',
+    // `parseKeypress` parses \u001B\u001B[A (meta + up arrow) as meta = false
+    // but with option = true, so we need to take this into account here
+    // to avoid breaking changes in Ink.
+    // TODO(vadimdemedes): consider removing this in the next major version.
+    meta: keypress.meta || keypress.name === 'escape' || keypress.option,
+    // Super (Cmd on macOS / Win key) — only arrives via kitty keyboard
+    // protocol CSI u sequences. Distinct from meta (Alt/Option) so
+    // bindings like cmd+c can be expressed separately from opt+c.
+    super: keypress.super
+  }
+
+  let input = keypress.ctrl ? keypress.name : keypress.sequence
+
+  // Handle undefined input case
+  if (input === undefined) {
+    input = ''
+  }
+
+  // When ctrl is set, keypress.name for space is the literal word "space".
+  // Convert to actual space character for consistency with the CSI u branch
+  // (which maps 'space' → ' '). Without this, ctrl+space leaks the literal
+  // word "space" into text input.
+  if (keypress.ctrl && input === 'space') {
+    input = ' '
+  }
+
+  // Suppress unrecognized escape sequences that were parsed as function keys
+  // (matched by FN_KEY_RE) but have no name in the keyName map.
+  // Examples: ESC[25~ (F13/Right Alt on Windows), ESC[26~ (F14), etc.
+  // Without this, the ESC prefix is stripped below and the remainder (e.g.,
+  // "[25~") leaks into the input as literal text.
+  if (keypress.code && !keypress.name) {
+    input = ''
+  }
+
+  // (SGR mouse-report fragments used to be scrubbed here. They no longer reach
+  // this layer: the tokenizer keeps an incomplete CSI buffered across a
+  // watchdog flush and reassembles it on the next feed instead of force-
+  // emitting the partial as input. See termio/tokenize.ts.)
+
+  // Strip meta if it's still remaining after `parseKeypress`
+  // TODO(vadimdemedes): remove this in the next major version.
+  if (input.startsWith('\u001B')) {
+    input = input.slice(1)
+  }
+
+  // Track whether we've already processed this as a special sequence
+  // that converted input to the key name (CSI u or application keypad mode).
+  // For these, we don't want to clear input with nonAlphanumericKeys check.
+  let processedAsSpecialSequence = false
+
+  // Handle CSI u sequences (Kitty keyboard protocol): after stripping ESC,
+  // we're left with "[codepoint;modifieru" (e.g., "[98;3u" for Alt+b).
+  // Use the parsed key name instead for input handling. Require a digit
+  // after [ — real CSI u is always [<digits>…u, and a bare startsWith('[')
+  // false-matches X10 mouse at row 85 (Cy = 85+32 = 'u'), leaking the
+  // literal text "mouse" into the prompt via processedAsSpecialSequence.
+  if (/^\[\d/.test(input) && input.endsWith('u')) {
+    if (!keypress.name) {
+      // Unmapped Kitty functional key (Caps Lock 57358, F13–F35, KP nav,
+      // bare modifiers, etc.) — keycodeToName() returned undefined. Swallow
+      // so the raw "[57358u" doesn't leak into the prompt. See #38781.
+      input = ''
+    } else {
+      input = inputForSpecialSequence(keypress.name)
+    }
+
+    processedAsSpecialSequence = true
+  }
+
+  // Handle xterm modifyOtherKeys sequences: after stripping ESC, we're left
+  // with "[27;modifier;keycode~" (e.g., "[27;3;98~" for Alt+b). Same
+  // extraction as CSI u — without this, printable-char keycodes (single-letter
+  // names) skip the nonAlphanumericKeys clear and leak "[27;..." as input.
+  if (input.startsWith('[27;') && input.endsWith('~')) {
+    if (!keypress.name) {
+      // Unmapped modifyOtherKeys keycode — swallow for consistency with
+      // the CSI u handler above. Practically untriggerable today (xterm
+      // modifyOtherKeys only sends ASCII keycodes, all mapped), but
+      // guards against future terminal behavior.
+      input = ''
+    } else {
+      input = inputForSpecialSequence(keypress.name)
+    }
+
+    processedAsSpecialSequence = true
+  }
+
+  // Handle application keypad mode sequences: after stripping ESC,
+  // we're left with "O<letter>" (e.g., "Op" for numpad 0, "Oy" for numpad 9).
+  // Use the parsed key name (the digit character) for input handling.
+  if (input.startsWith('O') && input.length === 2 && keypress.name && keypress.name.length === 1) {
+    input = keypress.name
+    processedAsSpecialSequence = true
+  }
+
+  // Clear input for non-alphanumeric keys (arrows, function keys, etc.)
+  // Skip this for CSI u and application keypad mode sequences since
+  // those were already converted to their proper input characters.
+  if (!processedAsSpecialSequence && keypress.name && nonAlphanumericKeys.includes(keypress.name)) {
+    input = ''
+  }
+
+  // Set shift=true for uppercase letters (A-Z)
+  // Must check it's actually a letter, not just any char unchanged by toUpperCase
+  if (input.length === 1 && typeof input[0] === 'string' && input[0] >= 'A' && input[0] <= 'Z') {
+    key.shift = true
+  }
+
+  return [key, input]
+}
+
+export class InputEvent extends Event {
+  readonly keypress: ParsedKey
+  readonly key: Key
+  readonly input: string
+
+  constructor(keypress: ParsedKey) {
+    super()
+    const [key, input] = parseKey(keypress)
+
+    this.keypress = keypress
+    this.key = key
+    this.input = input
+  }
+}

ui-tui/packages/hermes-ink/src/ink/events/keyboard-event.ts

@@ -0,0 +1,57 @@
+import type { ParsedKey } from '../parse-keypress.js'
+
+import { TerminalEvent } from './terminal-event.js'
+
+/**
+ * Keyboard event dispatched through the DOM tree via capture/bubble.
+ *
+ * Follows browser KeyboardEvent semantics: `key` is the literal character
+ * for printable keys ('a', '3', ' ', '/') and a multi-char name for
+ * special keys ('down', 'return', 'escape', 'f1'). The idiomatic
+ * printable-char check is `e.key.length === 1`.
+ */
+export class KeyboardEvent extends TerminalEvent {
+  readonly key: string
+  readonly ctrl: boolean
+  readonly shift: boolean
+  readonly meta: boolean
+  readonly superKey: boolean
+  readonly fn: boolean
+
+  constructor(parsedKey: ParsedKey) {
+    super('keydown', { bubbles: true, cancelable: true })
+
+    this.key = keyFromParsed(parsedKey)
+    this.ctrl = parsedKey.ctrl
+    this.shift = parsedKey.shift
+    this.meta = parsedKey.meta || parsedKey.option
+    this.superKey = parsedKey.super
+    this.fn = parsedKey.fn
+  }
+}
+
+function keyFromParsed(parsed: ParsedKey): string {
+  const seq = parsed.sequence ?? ''
+  const name = parsed.name ?? ''
+
+  // Ctrl combos: sequence is a control byte (\x03 for ctrl+c), name is the
+  // letter. Browsers report e.key === 'c' with e.ctrlKey === true.
+  if (parsed.ctrl) {
+    return name
+  }
+
+  // Single printable char (space through ~, plus anything above ASCII):
+  // use the literal char. Browsers report e.key === '3', not 'Digit3'.
+  if (seq.length === 1) {
+    const code = seq.charCodeAt(0)
+
+    if (code >= 0x20 && code !== 0x7f) {
+      return seq
+    }
+  }
+
+  // Special keys (arrows, F-keys, return, tab, escape, etc.): sequence is
+  // either an escape sequence (\x1b[B) or a control byte (\r, \t), so use
+  // the parsed name. Browsers report e.key === 'ArrowDown'.
+  return name || seq
+}

ui-tui/packages/hermes-ink/src/ink/events/mouse-event.ts

@@ -0,0 +1,18 @@
+import { Event } from './event.js'
+
+export class MouseEvent extends Event {
+  readonly col: number
+  readonly row: number
+  localCol = 0
+  localRow = 0
+  readonly cellIsBlank: boolean
+  readonly button: number
+
+  constructor(col: number, row: number, cellIsBlank: boolean, button: number) {
+    super()
+    this.col = col
+    this.row = row
+    this.cellIsBlank = cellIsBlank
+    this.button = button
+  }
+}

ui-tui/packages/hermes-ink/src/ink/events/paste-event.ts

@@ -0,0 +1,10 @@
+import { TerminalEvent } from './terminal-event.js'
+
+export class PasteEvent extends TerminalEvent {
+  readonly text: string
+
+  constructor(text: string) {
+    super('paste', { bubbles: true, cancelable: true })
+    this.text = text
+  }
+}

ui-tui/packages/hermes-ink/src/ink/events/resize-event.ts

@@ -0,0 +1,12 @@
+import { TerminalEvent } from './terminal-event.js'
+
+export class ResizeEvent extends TerminalEvent {
+  readonly columns: number
+  readonly rows: number
+
+  constructor(columns: number, rows: number) {
+    super('resize', { bubbles: true, cancelable: true })
+    this.columns = columns
+    this.rows = rows
+  }
+}

ui-tui/packages/hermes-ink/src/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>
+}

ui-tui/packages/hermes-ink/src/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
+  }
+}

ui-tui/packages/hermes-ink/src/ink/focus.ts

@@ -0,0 +1,219 @@
+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!
+}

ui-tui/packages/hermes-ink/src/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
+  /** Absolute overlay moved/resized — schedule corrective frame without prevScreen. */
+  readonly absoluteOverlayMoved?: 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
+    /** Post-optimize patch count. */
+    optimizedPatches: number
+    /** Bytes written to stdout this frame. */
+    writeBytes: number
+    /** Whether stdout.write returned false. */
+    backpressure: boolean
+    /** Previous stdout.write callback latency; 0 if drained before next frame. */
+    prevFrameDrainMs: 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.
+      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
+}

ui-tui/packages/hermes-ink/src/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

ui-tui/packages/hermes-ink/src/ink/global.d.ts

@@ -0,0 +1 @@
+export {}

ui-tui/packages/hermes-ink/src/ink/hit-test.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest'
+
+import { appendChildNode, createNode } from './dom.js'
+import { dispatchClick, hitTest } from './hit-test.js'
+import { nodeCache } from './node-cache.js'
+
+const rect = (node: ReturnType<typeof createNode>, x: number, y: number, width: number, height: number) => {
+  nodeCache.set(node, { x, y, width, height })
+}
+
+describe('hit-test', () => {
+  it('hits absolutely positioned children that paint outside their parent rect', () => {
+    const root = createNode('ink-root')
+    const parent = createNode('ink-box')
+    const wrapper = createNode('ink-box')
+    const overlay = createNode('ink-box')
+    const row = createNode('ink-box')
+    const seen: string[] = []
+
+    appendChildNode(root, parent)
+    appendChildNode(parent, wrapper)
+    appendChildNode(wrapper, overlay)
+    appendChildNode(overlay, row)
+
+    overlay.style.position = 'absolute'
+    row._eventHandlers = { onClick: () => seen.push('row') }
+
+    rect(root, 0, 0, 120, 40)
+    rect(parent, 0, 30, 120, 1)
+    rect(wrapper, 0, 30, 120, 1)
+    rect(overlay, 0, 20, 96, 6)
+    rect(row, 1, 22, 80, 1)
+
+    expect(hitTest(root, 2, 22)).toBe(row)
+    expect(dispatchClick(root, 2, 22)).toBe(true)
+    expect(seen).toEqual(['row'])
+  })
+})

ui-tui/packages/hermes-ink/src/ink/hit-test.ts

@@ -0,0 +1,224 @@
+import type { DOMElement } from './dom.js'
+import { ClickEvent } from './events/click-event.js'
+import type { EventHandlerProps } from './events/event-handlers.js'
+import { MouseEvent } from './events/mouse-event.js'
+import { nodeCache } from './node-cache.js'
+
+function hitTestAbsoluteDescendants(node: DOMElement, col: number, row: number): DOMElement | null {
+  for (let i = node.childNodes.length - 1; i >= 0; i--) {
+    const child = node.childNodes[i]!
+
+    if (child.nodeName === '#text') {
+      continue
+    }
+
+    if (!nodeCache.get(child)) {
+      continue
+    }
+
+    if (child.style.position === 'absolute') {
+      const hit = hitTest(child, col, row)
+
+      if (hit) {
+        return hit
+      }
+    }
+
+    const nestedHit = hitTestAbsoluteDescendants(child, col, row)
+
+    if (nestedHit) {
+      return nestedHit
+    }
+  }
+
+  return null
+}
+
+/**
+ * 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
+  }
+
+  const inside = col >= rect.x && col < rect.x + rect.width && row >= rect.y && row < rect.y + rect.height
+
+  if (!inside) {
+    return hitTestAbsoluteDescendants(node, col, row)
+  }
+
+  // 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
+}
+
+type MouseHandler = 'onMouseDown' | 'onMouseUp' | 'onMouseDrag'
+
+export function dispatchMouse(
+  root: DOMElement,
+  col: number,
+  row: number,
+  handlerName: MouseHandler,
+  button: number,
+  cellIsBlank = false,
+  target?: DOMElement
+): DOMElement | undefined {
+  let node: DOMElement | undefined = target ?? hitTest(root, col, row) ?? undefined
+
+  if (!node) {
+    return undefined
+  }
+
+  const event = new MouseEvent(col, row, cellIsBlank, button)
+  let handled: DOMElement | undefined
+
+  while (node) {
+    const handler = node._eventHandlers?.[handlerName] as ((event: MouseEvent) => void) | undefined
+
+    if (handler) {
+      handled ??= node
+      const rect = nodeCache.get(node)
+
+      if (rect) {
+        event.localCol = col - rect.x
+        event.localRow = row - rect.y
+      }
+
+      handler(event)
+
+      if (event.didStopImmediatePropagation()) {
+        return handled
+      }
+    }
+
+    node = node.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?.()
+    }
+  }
+}

ui-tui/packages/hermes-ink/src/ink/hooks/use-animation-frame.ts

@@ -0,0 +1,62 @@
+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]
+}

ui-tui/packages/hermes-ink/src/ink/hooks/use-app.ts

@@ -0,0 +1,9 @@
+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

ui-tui/packages/hermes-ink/src/ink/hooks/use-cursor-advance.ts

@@ -0,0 +1,33 @@
+import { useContext } from 'react'
+
+import CursorAdvanceContext, { type CursorAdvanceNotifier } from '../components/CursorAdvanceContext.js'
+
+/**
+ * Returns a function that notifies Ink the physical terminal cursor was
+ * advanced out-of-band (e.g. by a direct stdout.write from the
+ * TextInput fast-echo bypass).
+ *
+ * Calling the returned function updates two pieces of Ink state:
+ *
+ *   - `displayCursor` — the cached parked-cursor position log-update
+ *     uses as the relative-move basis for the next frame. Skipped on
+ *     alt-screen, where every frame's CSI H resets the cursor anyway.
+ *
+ *   - The active `cursorDeclaration` — the target the cursor parks at
+ *     after every frame. Bumped on BOTH main- and alt-screen, because
+ *     onRender's alt-screen park branch emits an absolute CUP from
+ *     this value and a stale declaration there is still visibly wrong.
+ *     The next React commit that publishes a fresh declaration
+ *     supersedes the bump.
+ *
+ * The caller is responsible for the stdout write itself; this hook
+ * only reports the resulting cursor delta. Pass `dx` and optional
+ * `dy` in terminal cells (positive = moved right/down, negative =
+ * moved left/up).
+ *
+ * If the host isn't an Ink render root (test stubs, non-Ink renderer)
+ * the returned callback is a safe no-op.
+ */
+export function useCursorAdvance(): CursorAdvanceNotifier {
+  return useContext(CursorAdvanceContext)
+}

ui-tui/packages/hermes-ink/src/ink/hooks/use-declared-cursor.ts

@@ -0,0 +1,75 @@
+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
+}

ui-tui/packages/hermes-ink/src/ink/hooks/use-external-process.ts

@@ -0,0 +1,27 @@
+import { useCallback } from 'react'
+
+import instances from '../instances.js'
+
+export type RunExternalProcess = () => Promise<void>
+
+export async function withInkSuspended(run: RunExternalProcess): Promise<void> {
+  const ink = instances.get(process.stdout)
+
+  if (!ink) {
+    await run()
+
+    return
+  }
+
+  ink.enterAlternateScreen()
+
+  try {
+    await run()
+  } finally {
+    ink.exitAlternateScreen()
+  }
+}
+
+export function useExternalProcess(): (run: RunExternalProcess) => Promise<void> {
+  return useCallback((run: RunExternalProcess) => withInkSuspended(run), [])
+}

ui-tui/packages/hermes-ink/src/ink/hooks/use-input.ts

@@ -0,0 +1,95 @@
+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, exitOnCtrlC, inputEmitter } = 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) || !exitOnCtrlC) {
+      inputHandler(input, key, event)
+    }
+  })
+
+  useEffect(() => {
+    inputEmitter?.on('input', handleData)
+
+    return () => {
+      inputEmitter?.removeListener('input', handleData)
+    }
+  }, [inputEmitter, handleData])
+}
+
+export default useInput

ui-tui/packages/hermes-ink/src/ink/hooks/use-interval.ts

@@ -0,0 +1,71 @@
+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])
+}

ui-tui/packages/hermes-ink/src/ink/hooks/use-search-highlight.ts

@@ -0,0 +1,56 @@
+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])
+}

ui-tui/packages/hermes-ink/src/ink/hooks/use-selection.ts

@@ -0,0 +1,101 @@
+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: () => Promise<string>
+  /** Copy without clearing the highlight (for copy-on-select). */
+  copySelectionNoClear: () => Promise<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
+  /** Monotonic counter incremented on every selection mutation. */
+  version: () => number
+} {
+  // 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: async () => '',
+        copySelectionNoClear: async () => '',
+        clearSelection: () => {},
+        hasSelection: () => false,
+        getState: () => null,
+        subscribe: () => () => {},
+        shiftAnchor: () => {},
+        shiftSelection: () => {},
+        moveFocus: () => {},
+        captureScrolledRows: () => {},
+        setSelectionBgColor: () => {},
+        version: () => 0
+      }
+    }
+
+    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),
+      version: () => ink.getSelectionVersion()
+    }
+  }, [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
+  )
+}

ui-tui/packages/hermes-ink/src/ink/hooks/use-stdin.ts

@@ -0,0 +1,9 @@
+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

ui-tui/packages/hermes-ink/src/ink/hooks/use-tab-status.ts

@@ -0,0 +1,71 @@
+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])
+}

ui-tui/packages/hermes-ink/src/ink/hooks/use-terminal-focus.ts

@@ -0,0 +1,18 @@
+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
+}

ui-tui/packages/hermes-ink/src/ink/hooks/use-terminal-title.ts

@@ -0,0 +1,34 @@
+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])
+}

ui-tui/packages/hermes-ink/src/ink/hooks/use-terminal-viewport.ts

@@ -0,0 +1,100 @@
+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]
+}

ui-tui/packages/hermes-ink/src/ink/hyperlinkHover.ts

@@ -0,0 +1,52 @@
+import { cellAtIndex, CellWidth, type Screen, setCellStyleId, type StylePool } from './screen.js'
+
+/**
+ * Highlight every cell whose OSC 8 hyperlink matches `hoveredUrl` by inverting
+ * its style. This is the cursor-hover affordance for clickable links: terminal
+ * applications can't change the system mouse cursor, so we light up the link
+ * itself when the pointer is over it. Same overlay machinery as
+ * applySearchHighlight — post-layout, pure SGR, picked up by the diff.
+ *
+ * Returns true if any cell was highlighted. The caller decides whether to
+ * promote that into a full-frame damage request — for hover specifically,
+ * full damage is only useful on enter/leave/change transitions (so the
+ * previous frame's inverted cells get re-emitted), not on every steady-state
+ * frame the pointer sits on the link.
+ */
+export function applyHyperlinkHoverHighlight(
+  screen: Screen,
+  hoveredUrl: string | undefined,
+  stylePool: StylePool
+): boolean {
+  if (!hoveredUrl) {
+    return false
+  }
+
+  const w = screen.width
+  const height = screen.height
+  let applied = false
+
+  for (let row = 0; row < height; row++) {
+    const rowOff = row * w
+
+    for (let col = 0; col < w; col++) {
+      const cell = cellAtIndex(screen, rowOff + col)
+
+      // Skip SpacerTail — the head cell at col-1 owns the hyperlink, and
+      // setCellStyleId on the tail would split the styling of a wide-char
+      // glyph mid-cell. The head's restyle covers both halves.
+      if (cell.width === CellWidth.SpacerTail) {
+        continue
+      }
+
+      if (cell.hyperlink !== hoveredUrl) {
+        continue
+      }
+
+      applied = true
+      setCellStyleId(screen, col, row, stylePool.withInverse(cell.styleId))
+    }
+  }
+
+  return applied
+}

ui-tui/packages/hermes-ink/src/ink/ink-cursor-advance.test.ts

@@ -0,0 +1,234 @@
+import { EventEmitter } from 'events'
+
+import React from 'react'
+import { describe, expect, it } from 'vitest'
+
+import Text from './components/Text.js'
+import Ink from './ink.js'
+
+class FakeTty extends EventEmitter {
+  chunks: string[] = []
+  columns = 40
+  rows = 8
+  isTTY = true
+
+  write(chunk: string | Uint8Array, cb?: (err?: Error | null) => void): boolean {
+    this.chunks.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'))
+    cb?.()
+
+    return true
+  }
+}
+
+function makeInk() {
+  const stdout = new FakeTty()
+  const stdin = new FakeTty()
+  const stderr = new FakeTty()
+
+  const ink = new Ink({
+    exitOnCtrlC: false,
+    patchConsole: false,
+    stderr: stderr as unknown as NodeJS.WriteStream,
+    stdin: stdin as unknown as NodeJS.ReadStream,
+    stdout: stdout as unknown as NodeJS.WriteStream
+  })
+
+  return { ink, stdout, stdin, stderr }
+}
+
+// Cast helper instead of exposing __get*ForTest methods on production Ink —
+// these are internal frame/cursor caches we only inspect from tests.
+type InkPrivate = {
+  displayCursor: { x: number; y: number } | null
+  cursorDeclaration: { node: unknown; relativeX: number; relativeY: number } | null
+  frontFrame: { cursor: { x: number; y: number } }
+}
+const peek = (ink: Ink): InkPrivate => ink as unknown as InkPrivate
+
+// Closes the cursor-drift bug: when TextInput's fast-echo path writes a
+// printable character directly to stdout, the hardware cursor advances by
+// one cell BUT Ink's `displayCursor` cache (used as the basis for the
+// next frame's relative cursor preamble) wasn't being updated. On long
+// sessions an unrelated re-render (status bar timer, streaming
+// reasoning, etc.) would then park the hardware cursor N cells offset
+// from the actual caret — visible as "extra whitespace between my last
+// typed character and the cursor block".
+describe('Ink.noteExternalCursorAdvance', () => {
+  it('bumps an already-tracked displayCursor by the given delta', () => {
+    const { ink } = makeInk()
+
+    ink.render(React.createElement(Text, null, 'hi'))
+    ink.onRender()
+
+    // Seed a known parked position directly. In production this is set by
+    // the cursor-park branch in onRender when a useDeclaredCursor caller
+    // commits a declaration; this test bypasses React for hermeticity.
+    peek(ink).displayCursor = { x: 5, y: 0 }
+
+    ink.noteExternalCursorAdvance(3)
+    expect(peek(ink).displayCursor).toEqual({ x: 8, y: 0 })
+
+    ink.noteExternalCursorAdvance(-1)
+    expect(peek(ink).displayCursor).toEqual({ x: 7, y: 0 })
+
+    ink.noteExternalCursorAdvance(0, 2)
+    expect(peek(ink).displayCursor).toEqual({ x: 7, y: 2 })
+
+    ink.unmount()
+  })
+
+  it('seeds displayCursor from frontFrame.cursor when nothing was parked', () => {
+    const { ink } = makeInk()
+
+    ink.render(React.createElement(Text, null, 'hello'))
+    ink.onRender()
+
+    expect(peek(ink).displayCursor).toBeNull()
+    const base = { x: peek(ink).frontFrame.cursor.x, y: peek(ink).frontFrame.cursor.y }
+
+    ink.noteExternalCursorAdvance(4)
+    expect(peek(ink).displayCursor).toEqual({ x: base.x + 4, y: base.y })
+
+    ink.unmount()
+  })
+
+  it('is a no-op when the delta is zero', () => {
+    const { ink } = makeInk()
+
+    ink.render(React.createElement(Text, null, 'hi'))
+    ink.onRender()
+
+    ink.noteExternalCursorAdvance(0)
+    expect(peek(ink).displayCursor).toBeNull()
+
+    ink.noteExternalCursorAdvance(0, 0)
+    expect(peek(ink).displayCursor).toBeNull()
+
+    ink.unmount()
+  })
+
+  it('skips displayCursor on alt-screen — CSI H resets every frame', () => {
+    const { ink } = makeInk()
+
+    ink.setAltScreenActive(true)
+    ink.render(React.createElement(Text, null, 'hi'))
+    ink.onRender()
+    peek(ink).displayCursor = { x: 5, y: 0 }
+
+    ink.noteExternalCursorAdvance(3)
+
+    expect(peek(ink).displayCursor).toEqual({ x: 5, y: 0 })
+
+    ink.unmount()
+  })
+
+  // Closes Copilot follow-up on PR #26717: the default TUI wraps the
+  // composer in <AlternateScreen>, so alt-screen is the production
+  // path. CSI H only resets the log-update relative-move basis — the
+  // declared cursor target is still consulted by onRender's alt-screen
+  // park branch (`cursorPosition(row, col)` using rect + decl). So
+  // cursorDeclaration MUST advance on alt-screen too, even though
+  // displayCursor doesn't need to.
+  it('still advances cursorDeclaration on alt-screen', () => {
+    const { ink } = makeInk()
+
+    ink.setAltScreenActive(true)
+    ink.render(React.createElement(Text, null, 'hi'))
+    ink.onRender()
+
+    const fakeNode = {} as unknown as Record<string, unknown>
+
+    peek(ink).cursorDeclaration = { node: fakeNode, relativeX: 7, relativeY: 0 }
+    peek(ink).displayCursor = { x: 12, y: 0 }
+
+    ink.noteExternalCursorAdvance(3)
+
+    // displayCursor untouched on alt-screen
+    expect(peek(ink).displayCursor).toEqual({ x: 12, y: 0 })
+    // declaration still advanced — onRender's alt-screen park reads this
+    expect(peek(ink).cursorDeclaration).toEqual({ node: fakeNode, relativeX: 10, relativeY: 0 })
+
+    ink.unmount()
+  })
+
+  // Closes Copilot review feedback on PR #26717: even after the
+  // TextInput-level fix where layout reads `curRef.current` directly,
+  // there's still a window where a fast-echo wrote to stdout but the
+  // current cursor declaration on Ink (set by an earlier render's
+  // useDeclaredCursor commit) points at the PRE-keystroke caret
+  // column. If we advanced only `displayCursor`, an unrelated re-render
+  // in that window would re-run onRender's cursor-park branch with the
+  // stale declaration and visually undo the fast-echo's advance. We
+  // must bump BOTH so the cursor stays anchored to the physical caret
+  // until the next React commit publishes a fresh declaration
+  // (computed from `curRef.current` via the cursorLayout call in
+  // textInput.tsx) that supersedes the bump.
+  it('advances the active cursorDeclaration in lock-step with displayCursor', () => {
+    const { ink } = makeInk()
+
+    ink.render(React.createElement(Text, null, 'hi'))
+    ink.onRender()
+
+    const fakeNode = {} as unknown as Record<string, unknown>
+
+    peek(ink).cursorDeclaration = { node: fakeNode, relativeX: 7, relativeY: 0 }
+    peek(ink).displayCursor = { x: 12, y: 0 }
+
+    ink.noteExternalCursorAdvance(3)
+
+    expect(peek(ink).displayCursor).toEqual({ x: 15, y: 0 })
+    expect(peek(ink).cursorDeclaration).toEqual({ node: fakeNode, relativeX: 10, relativeY: 0 })
+
+    ink.noteExternalCursorAdvance(-1)
+    expect(peek(ink).displayCursor).toEqual({ x: 14, y: 0 })
+    expect(peek(ink).cursorDeclaration).toEqual({ node: fakeNode, relativeX: 9, relativeY: 0 })
+
+    ink.unmount()
+  })
+
+  // Closes Copilot follow-up on PR #26717: the dy half of the notifier
+  // contract was tested for `displayCursor` but not for
+  // `cursorDeclaration.relativeY`. Newlines in fast-echoed text never
+  // hit the bypass today (canFastAppendShape rejects '\n'), but `dy`
+  // is part of the public API and must propagate symmetrically with
+  // dx so future callers (e.g. multi-line paste shortcuts) don't get
+  // a half-implemented contract.
+  it('advances cursorDeclaration.relativeY when dy is non-zero', () => {
+    const { ink } = makeInk()
+
+    ink.render(React.createElement(Text, null, 'hi'))
+    ink.onRender()
+
+    const fakeNode = {} as unknown as Record<string, unknown>
+
+    peek(ink).cursorDeclaration = { node: fakeNode, relativeX: 2, relativeY: 1 }
+    peek(ink).displayCursor = { x: 4, y: 2 }
+
+    ink.noteExternalCursorAdvance(1, 3)
+
+    expect(peek(ink).displayCursor).toEqual({ x: 5, y: 5 })
+    expect(peek(ink).cursorDeclaration).toEqual({ node: fakeNode, relativeX: 3, relativeY: 4 })
+
+    // Negative dy too — cursor moving up across visual rows.
+    ink.noteExternalCursorAdvance(0, -2)
+    expect(peek(ink).displayCursor).toEqual({ x: 5, y: 3 })
+    expect(peek(ink).cursorDeclaration).toEqual({ node: fakeNode, relativeX: 3, relativeY: 2 })
+
+    ink.unmount()
+  })
+
+  it('leaves cursorDeclaration unchanged when no declaration is active', () => {
+    const { ink } = makeInk()
+
+    ink.render(React.createElement(Text, null, 'hi'))
+    ink.onRender()
+
+    expect(peek(ink).cursorDeclaration).toBeNull()
+
+    ink.noteExternalCursorAdvance(3)
+
+    expect(peek(ink).cursorDeclaration).toBeNull()
+
+    ink.unmount()
+  })
+})

ui-tui/packages/hermes-ink/src/ink/ink-resize.test.ts

@@ -0,0 +1,50 @@
+import { EventEmitter } from 'events'
+import React from 'react'
+import { describe, expect, it } from 'vitest'
+
+import Text from './components/Text.js'
+import Ink from './ink.js'
+import { CURSOR_HOME, ERASE_SCREEN } from './termio/csi.js'
+
+class FakeTty extends EventEmitter {
+  chunks: string[] = []
+  columns = 20
+  rows = 5
+  isTTY = true
+
+  write(chunk: string | Uint8Array, cb?: (err?: Error | null) => void): boolean {
+    this.chunks.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'))
+    cb?.()
+    return true
+  }
+}
+
+const tick = () => new Promise<void>(resolve => queueMicrotask(resolve))
+
+describe('Ink resize healing', () => {
+  it('heals same-dimension alt-screen resize events with an erase before repaint', async () => {
+    const stdout = new FakeTty()
+    const stdin = new FakeTty()
+    const stderr = new FakeTty()
+    const ink = new Ink({
+      exitOnCtrlC: false,
+      patchConsole: false,
+      stderr: stderr as unknown as NodeJS.WriteStream,
+      stdin: stdin as unknown as NodeJS.ReadStream,
+      stdout: stdout as unknown as NodeJS.WriteStream
+    })
+
+    ink.setAltScreenActive(true)
+    ink.render(React.createElement(Text, null, 'hello'))
+    ink.onRender()
+    stdout.chunks = []
+
+    stdout.emit('resize')
+    ink.onRender()
+    await tick()
+
+    expect(stdout.chunks.join('')).toContain(ERASE_SCREEN + CURSOR_HOME)
+
+    ink.unmount()
+  })
+})

ui-tui/packages/hermes-ink/src/ink/instances.ts

@@ -0,0 +1,10 @@
+// Store all instances of Ink (instance.js) to ensure that consecutive render() calls
+// use the same instance of Ink and don't create a new one
+//
+// This map has to be stored in a separate file, because render.js creates instances,
+// but instance.js should delete itself from the map on unmount
+
+import type Ink from './ink.js'
+
+const instances = new Map<NodeJS.WriteStream, Ink>()
+export default instances

ui-tui/packages/hermes-ink/src/ink/layout/engine.ts

@@ -0,0 +1,6 @@
+import type { LayoutNode } from './node.js'
+import { createYogaLayoutNode } from './yoga.js'
+
+export function createLayoutNode(): LayoutNode {
+  return createYogaLayoutNode()
+}

ui-tui/packages/hermes-ink/src/ink/layout/geometry.ts

@@ -0,0 +1,98 @@
+export type Point = {
+  x: number
+  y: number
+}
+
+export type Size = {
+  width: number
+  height: number
+}
+
+export type Rectangle = Point & Size
+
+/** Edge insets (padding, margin, border) */
+export type Edges = {
+  top: number
+  right: number
+  bottom: number
+  left: number
+}
+
+/** Create uniform edges */
+export function edges(all: number): Edges
+export function edges(vertical: number, horizontal: number): Edges
+export function edges(top: number, right: number, bottom: number, left: number): Edges
+
+export function edges(a: number, b?: number, c?: number, d?: number): Edges {
+  if (b === undefined) {
+    return { top: a, right: a, bottom: a, left: a }
+  }
+
+  if (c === undefined) {
+    return { top: a, right: b, bottom: a, left: b }
+  }
+
+  return { top: a, right: b, bottom: c, left: d! }
+}
+
+/** Add two edge values */
+export function addEdges(a: Edges, b: Edges): Edges {
+  return {
+    top: a.top + b.top,
+    right: a.right + b.right,
+    bottom: a.bottom + b.bottom,
+    left: a.left + b.left
+  }
+}
+
+/** Zero edges constant */
+export const ZERO_EDGES: Edges = { top: 0, right: 0, bottom: 0, left: 0 }
+
+/** Convert partial edges to full edges with defaults */
+export function resolveEdges(partial?: Partial<Edges>): Edges {
+  return {
+    top: partial?.top ?? 0,
+    right: partial?.right ?? 0,
+    bottom: partial?.bottom ?? 0,
+    left: partial?.left ?? 0
+  }
+}
+
+export function unionRect(a: Rectangle, b: Rectangle): Rectangle {
+  const minX = Math.min(a.x, b.x)
+  const minY = Math.min(a.y, b.y)
+  const maxX = Math.max(a.x + a.width, b.x + b.width)
+  const maxY = Math.max(a.y + a.height, b.y + b.height)
+
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY }
+}
+
+export function clampRect(rect: Rectangle, size: Size): Rectangle {
+  const minX = Math.max(0, rect.x)
+  const minY = Math.max(0, rect.y)
+  const maxX = Math.min(size.width - 1, rect.x + rect.width - 1)
+  const maxY = Math.min(size.height - 1, rect.y + rect.height - 1)
+
+  return {
+    x: minX,
+    y: minY,
+    width: Math.max(0, maxX - minX + 1),
+    height: Math.max(0, maxY - minY + 1)
+  }
+}
+
+export function withinBounds(size: Size, point: Point): boolean {
+  return point.x >= 0 && point.y >= 0 && point.x < size.width && point.y < size.height
+}
+
+export function clamp(value: number, min?: number, max?: number): number {
+  if (min !== undefined && value < min) {
+    return min
+  }
+
+  if (max !== undefined && value > max) {
+    return max
+  }
+
+  return value
+}

ui-tui/packages/hermes-ink/src/ink/layout/node.ts

@@ -0,0 +1,145 @@
+// --
+// Adapter interface for the layout engine (Yoga)
+
+export const LayoutEdge = {
+  All: 'all',
+  Horizontal: 'horizontal',
+  Vertical: 'vertical',
+  Left: 'left',
+  Right: 'right',
+  Top: 'top',
+  Bottom: 'bottom',
+  Start: 'start',
+  End: 'end'
+} as const
+export type LayoutEdge = (typeof LayoutEdge)[keyof typeof LayoutEdge]
+
+export const LayoutGutter = {
+  All: 'all',
+  Column: 'column',
+  Row: 'row'
+} as const
+export type LayoutGutter = (typeof LayoutGutter)[keyof typeof LayoutGutter]
+
+export const LayoutDisplay = {
+  Flex: 'flex',
+  None: 'none'
+} as const
+export type LayoutDisplay = (typeof LayoutDisplay)[keyof typeof LayoutDisplay]
+
+export const LayoutFlexDirection = {
+  Row: 'row',
+  RowReverse: 'row-reverse',
+  Column: 'column',
+  ColumnReverse: 'column-reverse'
+} as const
+export type LayoutFlexDirection = (typeof LayoutFlexDirection)[keyof typeof LayoutFlexDirection]
+
+export const LayoutAlign = {
+  Auto: 'auto',
+  Stretch: 'stretch',
+  FlexStart: 'flex-start',
+  Center: 'center',
+  FlexEnd: 'flex-end'
+} as const
+export type LayoutAlign = (typeof LayoutAlign)[keyof typeof LayoutAlign]
+
+export const LayoutJustify = {
+  FlexStart: 'flex-start',
+  Center: 'center',
+  FlexEnd: 'flex-end',
+  SpaceBetween: 'space-between',
+  SpaceAround: 'space-around',
+  SpaceEvenly: 'space-evenly'
+} as const
+export type LayoutJustify = (typeof LayoutJustify)[keyof typeof LayoutJustify]
+
+export const LayoutWrap = {
+  NoWrap: 'nowrap',
+  Wrap: 'wrap',
+  WrapReverse: 'wrap-reverse'
+} as const
+export type LayoutWrap = (typeof LayoutWrap)[keyof typeof LayoutWrap]
+
+export const LayoutPositionType = {
+  Relative: 'relative',
+  Absolute: 'absolute'
+} as const
+export type LayoutPositionType = (typeof LayoutPositionType)[keyof typeof LayoutPositionType]
+
+export const LayoutOverflow = {
+  Visible: 'visible',
+  Hidden: 'hidden',
+  Scroll: 'scroll'
+} as const
+export type LayoutOverflow = (typeof LayoutOverflow)[keyof typeof LayoutOverflow]
+
+export type LayoutMeasureFunc = (width: number, widthMode: LayoutMeasureMode) => { width: number; height: number }
+
+export const LayoutMeasureMode = {
+  Undefined: 'undefined',
+  Exactly: 'exactly',
+  AtMost: 'at-most'
+} as const
+export type LayoutMeasureMode = (typeof LayoutMeasureMode)[keyof typeof LayoutMeasureMode]
+
+export type LayoutNode = {
+  // Tree
+  insertChild(child: LayoutNode, index: number): void
+  removeChild(child: LayoutNode): void
+  getChildCount(): number
+  getParent(): LayoutNode | null
+
+  // Layout computation
+  calculateLayout(width?: number, height?: number): void
+  setMeasureFunc(fn: LayoutMeasureFunc): void
+  unsetMeasureFunc(): void
+  markDirty(): void
+
+  // Layout reading (post-layout)
+  getComputedLeft(): number
+  getComputedTop(): number
+  getComputedWidth(): number
+  getComputedHeight(): number
+  getComputedBorder(edge: LayoutEdge): number
+  getComputedPadding(edge: LayoutEdge): number
+
+  // Style setters
+  setWidth(value: number): void
+  setWidthPercent(value: number): void
+  setWidthAuto(): void
+  setHeight(value: number): void
+  setHeightPercent(value: number): void
+  setHeightAuto(): void
+  setMinWidth(value: number): void
+  setMinWidthPercent(value: number): void
+  setMinHeight(value: number): void
+  setMinHeightPercent(value: number): void
+  setMaxWidth(value: number): void
+  setMaxWidthPercent(value: number): void
+  setMaxHeight(value: number): void
+  setMaxHeightPercent(value: number): void
+  setFlexDirection(dir: LayoutFlexDirection): void
+  setFlexGrow(value: number): void
+  setFlexShrink(value: number): void
+  setFlexBasis(value: number): void
+  setFlexBasisPercent(value: number): void
+  setFlexWrap(wrap: LayoutWrap): void
+  setAlignItems(align: LayoutAlign): void
+  setAlignSelf(align: LayoutAlign): void
+  setJustifyContent(justify: LayoutJustify): void
+  setDisplay(display: LayoutDisplay): void
+  getDisplay(): LayoutDisplay
+  setPositionType(type: LayoutPositionType): void
+  setPosition(edge: LayoutEdge, value: number): void
+  setPositionPercent(edge: LayoutEdge, value: number): void
+  setOverflow(overflow: LayoutOverflow): void
+  setMargin(edge: LayoutEdge, value: number): void
+  setPadding(edge: LayoutEdge, value: number): void
+  setBorder(edge: LayoutEdge, value: number): void
+  setGap(gutter: LayoutGutter, value: number): void
+
+  // Lifecycle
+  free(): void
+  freeRecursive(): void
+}

ui-tui/packages/hermes-ink/src/ink/layout/yoga.ts

@@ -0,0 +1,313 @@
+import Yoga, {
+  Align,
+  Direction,
+  Display,
+  Edge,
+  FlexDirection,
+  Gutter,
+  Justify,
+  MeasureMode,
+  Overflow,
+  PositionType,
+  Wrap,
+  type Node as YogaNode
+} from '../../native-ts/yoga-layout/index.js'
+
+import {
+  type LayoutAlign,
+  LayoutDisplay,
+  type LayoutEdge,
+  type LayoutFlexDirection,
+  type LayoutGutter,
+  type LayoutJustify,
+  type LayoutMeasureFunc,
+  LayoutMeasureMode,
+  type LayoutNode,
+  type LayoutOverflow,
+  type LayoutPositionType,
+  type LayoutWrap
+} from './node.js'
+
+// --
+// Edge/Gutter mapping
+
+const EDGE_MAP: Record<LayoutEdge, Edge> = {
+  all: Edge.All,
+  horizontal: Edge.Horizontal,
+  vertical: Edge.Vertical,
+  left: Edge.Left,
+  right: Edge.Right,
+  top: Edge.Top,
+  bottom: Edge.Bottom,
+  start: Edge.Start,
+  end: Edge.End
+}
+
+const GUTTER_MAP: Record<LayoutGutter, Gutter> = {
+  all: Gutter.All,
+  column: Gutter.Column,
+  row: Gutter.Row
+}
+
+// --
+// Yoga adapter
+
+export class YogaLayoutNode implements LayoutNode {
+  readonly yoga: YogaNode
+
+  constructor(yoga: YogaNode) {
+    this.yoga = yoga
+  }
+
+  // Tree
+
+  insertChild(child: LayoutNode, index: number): void {
+    this.yoga.insertChild((child as YogaLayoutNode).yoga, index)
+  }
+
+  removeChild(child: LayoutNode): void {
+    this.yoga.removeChild((child as YogaLayoutNode).yoga)
+  }
+
+  getChildCount(): number {
+    return this.yoga.getChildCount()
+  }
+
+  getParent(): LayoutNode | null {
+    const p = this.yoga.getParent()
+
+    return p ? new YogaLayoutNode(p) : null
+  }
+
+  // Layout
+
+  calculateLayout(width?: number, _height?: number): void {
+    this.yoga.calculateLayout(width, undefined, Direction.LTR)
+  }
+
+  setMeasureFunc(fn: LayoutMeasureFunc): void {
+    this.yoga.setMeasureFunc((w, wMode) => {
+      const mode =
+        wMode === MeasureMode.Exactly
+          ? LayoutMeasureMode.Exactly
+          : wMode === MeasureMode.AtMost
+            ? LayoutMeasureMode.AtMost
+            : LayoutMeasureMode.Undefined
+
+      return fn(w, mode)
+    })
+  }
+
+  unsetMeasureFunc(): void {
+    this.yoga.unsetMeasureFunc()
+  }
+
+  markDirty(): void {
+    this.yoga.markDirty()
+  }
+
+  // Computed layout
+
+  getComputedLeft(): number {
+    return this.yoga.getComputedLeft()
+  }
+
+  getComputedTop(): number {
+    return this.yoga.getComputedTop()
+  }
+
+  getComputedWidth(): number {
+    return this.yoga.getComputedWidth()
+  }
+
+  getComputedHeight(): number {
+    return this.yoga.getComputedHeight()
+  }
+
+  getComputedBorder(edge: LayoutEdge): number {
+    return this.yoga.getComputedBorder(EDGE_MAP[edge]!)
+  }
+
+  getComputedPadding(edge: LayoutEdge): number {
+    return this.yoga.getComputedPadding(EDGE_MAP[edge]!)
+  }
+
+  // Style setters
+
+  setWidth(value: number): void {
+    this.yoga.setWidth(value)
+  }
+  setWidthPercent(value: number): void {
+    this.yoga.setWidthPercent(value)
+  }
+  setWidthAuto(): void {
+    this.yoga.setWidthAuto()
+  }
+  setHeight(value: number): void {
+    this.yoga.setHeight(value)
+  }
+  setHeightPercent(value: number): void {
+    this.yoga.setHeightPercent(value)
+  }
+  setHeightAuto(): void {
+    this.yoga.setHeightAuto()
+  }
+  setMinWidth(value: number): void {
+    this.yoga.setMinWidth(value)
+  }
+  setMinWidthPercent(value: number): void {
+    this.yoga.setMinWidthPercent(value)
+  }
+  setMinHeight(value: number): void {
+    this.yoga.setMinHeight(value)
+  }
+  setMinHeightPercent(value: number): void {
+    this.yoga.setMinHeightPercent(value)
+  }
+  setMaxWidth(value: number): void {
+    this.yoga.setMaxWidth(value)
+  }
+  setMaxWidthPercent(value: number): void {
+    this.yoga.setMaxWidthPercent(value)
+  }
+  setMaxHeight(value: number): void {
+    this.yoga.setMaxHeight(value)
+  }
+  setMaxHeightPercent(value: number): void {
+    this.yoga.setMaxHeightPercent(value)
+  }
+
+  setFlexDirection(dir: LayoutFlexDirection): void {
+    const map: Record<LayoutFlexDirection, FlexDirection> = {
+      row: FlexDirection.Row,
+      'row-reverse': FlexDirection.RowReverse,
+      column: FlexDirection.Column,
+      'column-reverse': FlexDirection.ColumnReverse
+    }
+
+    this.yoga.setFlexDirection(map[dir]!)
+  }
+
+  setFlexGrow(value: number): void {
+    this.yoga.setFlexGrow(value)
+  }
+  setFlexShrink(value: number): void {
+    this.yoga.setFlexShrink(value)
+  }
+  setFlexBasis(value: number): void {
+    this.yoga.setFlexBasis(value)
+  }
+  setFlexBasisPercent(value: number): void {
+    this.yoga.setFlexBasisPercent(value)
+  }
+
+  setFlexWrap(wrap: LayoutWrap): void {
+    const map: Record<LayoutWrap, Wrap> = {
+      nowrap: Wrap.NoWrap,
+      wrap: Wrap.Wrap,
+      'wrap-reverse': Wrap.WrapReverse
+    }
+
+    this.yoga.setFlexWrap(map[wrap]!)
+  }
+
+  setAlignItems(align: LayoutAlign): void {
+    const map: Record<LayoutAlign, Align> = {
+      auto: Align.Auto,
+      stretch: Align.Stretch,
+      'flex-start': Align.FlexStart,
+      center: Align.Center,
+      'flex-end': Align.FlexEnd
+    }
+
+    this.yoga.setAlignItems(map[align]!)
+  }
+
+  setAlignSelf(align: LayoutAlign): void {
+    const map: Record<LayoutAlign, Align> = {
+      auto: Align.Auto,
+      stretch: Align.Stretch,
+      'flex-start': Align.FlexStart,
+      center: Align.Center,
+      'flex-end': Align.FlexEnd
+    }
+
+    this.yoga.setAlignSelf(map[align]!)
+  }
+
+  setJustifyContent(justify: LayoutJustify): void {
+    const map: Record<LayoutJustify, Justify> = {
+      'flex-start': Justify.FlexStart,
+      center: Justify.Center,
+      'flex-end': Justify.FlexEnd,
+      'space-between': Justify.SpaceBetween,
+      'space-around': Justify.SpaceAround,
+      'space-evenly': Justify.SpaceEvenly
+    }
+
+    this.yoga.setJustifyContent(map[justify]!)
+  }
+
+  setDisplay(display: LayoutDisplay): void {
+    this.yoga.setDisplay(display === 'flex' ? Display.Flex : Display.None)
+  }
+
+  getDisplay(): LayoutDisplay {
+    return this.yoga.getDisplay() === Display.None ? LayoutDisplay.None : LayoutDisplay.Flex
+  }
+
+  setPositionType(type: LayoutPositionType): void {
+    this.yoga.setPositionType(type === 'absolute' ? PositionType.Absolute : PositionType.Relative)
+  }
+
+  setPosition(edge: LayoutEdge, value: number): void {
+    this.yoga.setPosition(EDGE_MAP[edge]!, value)
+  }
+
+  setPositionPercent(edge: LayoutEdge, value: number): void {
+    this.yoga.setPositionPercent(EDGE_MAP[edge]!, value)
+  }
+
+  setOverflow(overflow: LayoutOverflow): void {
+    const map: Record<LayoutOverflow, Overflow> = {
+      visible: Overflow.Visible,
+      hidden: Overflow.Hidden,
+      scroll: Overflow.Scroll
+    }
+
+    this.yoga.setOverflow(map[overflow]!)
+  }
+
+  setMargin(edge: LayoutEdge, value: number): void {
+    this.yoga.setMargin(EDGE_MAP[edge]!, value)
+  }
+  setPadding(edge: LayoutEdge, value: number): void {
+    this.yoga.setPadding(EDGE_MAP[edge]!, value)
+  }
+  setBorder(edge: LayoutEdge, value: number): void {
+    this.yoga.setBorder(EDGE_MAP[edge]!, value)
+  }
+  setGap(gutter: LayoutGutter, value: number): void {
+    this.yoga.setGap(GUTTER_MAP[gutter]!, value)
+  }
+
+  // Lifecycle
+
+  free(): void {
+    this.yoga.free()
+  }
+  freeRecursive(): void {
+    this.yoga.freeRecursive()
+  }
+}
+
+// --
+// Instance management
+//
+// The TS yoga-layout port is synchronous — no WASM loading, no linear memory
+// growth, so no preload/swap/reset machinery is needed. The Yoga instance is
+// just a plain JS object available at import time.
+
+export function createYogaLayoutNode(): LayoutNode {
+  return new YogaLayoutNode(Yoga.Node.create())
+}

ui-tui/packages/hermes-ink/src/ink/line-width-cache.ts

@@ -0,0 +1,38 @@
+import { lruEvict } from './lru.js'
+import { stringWidth } from './stringWidth.js'
+
+// During streaming, text grows but completed lines are immutable.
+// Caching stringWidth per-line avoids re-measuring hundreds of
+// unchanged lines on every token (~50x reduction in stringWidth calls).
+const cache = new Map<string, number>()
+
+const MAX_CACHE_SIZE = 4096
+
+export function lineWidth(line: string): number {
+  const cached = cache.get(line)
+
+  if (cached !== undefined) {
+    cache.delete(line)
+    cache.set(line, cached)
+
+    return cached
+  }
+
+  const width = stringWidth(line)
+
+  if (cache.size >= MAX_CACHE_SIZE) {
+    cache.delete(cache.keys().next().value!)
+  }
+
+  cache.set(line, width)
+
+  return width
+}
+
+export function lineWidthCacheSize(): number {
+  return cache.size
+}
+
+export function evictLineWidthCache(keepRatio = 0): void {
+  lruEvict(cache, keepRatio)
+}

ui-tui/packages/hermes-ink/src/ink/log-update.test.ts

@@ -0,0 +1,223 @@
+import { describe, expect, it } from 'vitest'
+
+import type { Frame } from './frame.js'
+import { LogUpdate } from './log-update.js'
+import { CellWidth, CharPool, createScreen, HyperlinkPool, type Screen, setCellAt, StylePool } from './screen.js'
+
+/**
+ * Contract tests for LogUpdate.render() — the diff-to-ANSI path that owns
+ * whether the terminal picks up each React commit correctly.
+ *
+ * These tests pin down a few load-bearing invariants so that any fix for
+ * the "scattered letters after rapid resize" artifact in xterm.js hosts
+ * can be grounded against them.
+ */
+
+const stylePool = new StylePool()
+const charPool = new CharPool()
+const hyperlinkPool = new HyperlinkPool()
+
+const mkScreen = (w: number, h: number) => createScreen(w, h, stylePool, charPool, hyperlinkPool)
+
+const paint = (screen: Screen, y: number, text: string) => {
+  for (let x = 0; x < text.length; x++) {
+    setCellAt(screen, x, y, {
+      char: text[x]!,
+      styleId: stylePool.none,
+      width: CellWidth.Narrow,
+      hyperlink: undefined
+    })
+  }
+}
+
+const mkFrame = (screen: Screen, viewportW: number, viewportH: number, cursorY = 0): Frame => ({
+  screen,
+  viewport: { width: viewportW, height: viewportH },
+  cursor: { x: 0, y: cursorY, visible: true }
+})
+
+const stdoutOnly = (diff: ReturnType<LogUpdate['render']>) =>
+  diff
+    .filter(p => p.type === 'stdout')
+    .map(p => (p as { type: 'stdout'; content: string }).content)
+    .join('')
+
+const ESC = '\u001b'
+const hasDecstbm = (text: string) => new RegExp(`${ESC}\\[\\d+;\\d+r`).test(text)
+
+describe('LogUpdate.render diff contract', () => {
+  it('emits only changed cells when most rows match', () => {
+    const w = 20
+    const h = 4
+    const prev = mkScreen(w, h)
+    paint(prev, 0, 'HELLO')
+    paint(prev, 1, 'WORLD')
+    paint(prev, 2, 'STAYSHERE')
+
+    const next = mkScreen(w, h)
+    paint(next, 0, 'HELLO')
+    paint(next, 1, 'CHANGE')
+    paint(next, 2, 'STAYSHERE')
+    next.damage = { x: 0, y: 0, width: w, height: h }
+
+    const log = new LogUpdate({ isTTY: true, stylePool })
+    const diff = log.render(mkFrame(prev, w, h), mkFrame(next, w, h), true, false)
+
+    const written = stdoutOnly(diff)
+    expect(written).toContain('CHANGE')
+    expect(written).not.toContain('HELLO')
+    expect(written).not.toContain('STAYSHERE')
+  })
+
+  it('width change emits a clearTerminal patch before repainting', () => {
+    const prevW = 20
+    const nextW = 15
+    const h = 3
+
+    const prev = mkScreen(prevW, h)
+    paint(prev, 0, 'thiswaswiderrow')
+
+    const next = mkScreen(nextW, h)
+    paint(next, 0, 'shorterrownow')
+    next.damage = { x: 0, y: 0, width: nextW, height: h }
+
+    const log = new LogUpdate({ isTTY: true, stylePool })
+    const diff = log.render(mkFrame(prev, prevW, h), mkFrame(next, nextW, h), true, false)
+
+    expect(diff.some(p => p.type === 'clearTerminal')).toBe(true)
+    expect(stdoutOnly(diff)).toContain('shorterrownow')
+  })
+
+  it('height growth emits a clearTerminal patch before repainting', () => {
+    const w = 20
+    const prevH = 3
+    const nextH = 6
+
+    const prev = mkScreen(w, prevH)
+    paint(prev, 0, 'old rows')
+
+    const next = mkScreen(w, nextH)
+    paint(next, 0, 'new rows')
+    next.damage = { x: 0, y: 0, width: w, height: nextH }
+
+    const log = new LogUpdate({ isTTY: true, stylePool })
+    const diff = log.render(mkFrame(prev, w, prevH), mkFrame(next, w, nextH), true, false)
+
+    expect(diff.some(p => p.type === 'clearTerminal')).toBe(true)
+    expect(stdoutOnly(diff)).toContain('newrows')
+  })
+
+  it('drift repro: identical prev/next emits no heal, even when the physical terminal is stale', () => {
+    // Load-bearing theory for the rapid-resize scattered-letter bug: if the
+    // physical terminal has stale cells that prev.screen doesn't know about
+    // (e.g. resize-induced reflow wrote past ink's tracked range), the
+    // renderer has no signal to heal them. LogUpdate.render only sees
+    // prev/next — no view of the physical terminal — so when prev==next,
+    // it emits nothing and any orphaned glyphs survive.
+    //
+    // The fix path is upstream of this diff: either (a) defensively
+    // full-repaint on xterm.js frames where prevFrameContaminated is set,
+    // or (b) close the drift window so prev.screen cannot diverge.
+    const w = 20
+    const h = 3
+
+    const prev = mkScreen(w, h)
+    paint(prev, 0, 'same')
+
+    const next = mkScreen(w, h)
+    paint(next, 0, 'same')
+    next.damage = { x: 0, y: 0, width: w, height: h }
+
+    const log = new LogUpdate({ isTTY: true, stylePool })
+    const diff = log.render(mkFrame(prev, w, h), mkFrame(next, w, h), true, false)
+
+    expect(stdoutOnly(diff)).toBe('')
+    expect(diff.some(p => p.type === 'clearTerminal')).toBe(false)
+  })
+
+  it('ignores main-screen scrollback-only changes instead of resetting repeatedly', () => {
+    const w = 20
+    const viewportH = 5
+    const h = 8
+
+    const prev = mkScreen(w, h)
+    paint(prev, 0, 'timer 1s')
+    paint(prev, 6, 'visible prompt')
+
+    const next = mkScreen(w, h)
+    paint(next, 0, 'timer 2s')
+    paint(next, 6, 'visible prompt')
+    next.damage = { x: 0, y: 0, width: w, height: h }
+
+    const log = new LogUpdate({ isTTY: true, stylePool })
+    const diff = log.render(mkFrame(prev, w, viewportH, h), mkFrame(next, w, viewportH, h), false, false)
+
+    expect(diff.some(p => p.type === 'clearTerminal')).toBe(false)
+    expect(stdoutOnly(diff)).not.toContain('timer2s')
+  })
+
+  it('keeps alt-screen full reset for unreachable scrollback row changes', () => {
+    const w = 20
+    const viewportH = 5
+    const h = 8
+
+    const prev = mkScreen(w, h)
+    paint(prev, 0, 'timer 1s')
+    paint(prev, 6, 'visible prompt')
+
+    const next = mkScreen(w, h)
+    paint(next, 0, 'timer 2s')
+    paint(next, 6, 'visible prompt')
+    next.damage = { x: 0, y: 0, width: w, height: h }
+
+    const log = new LogUpdate({ isTTY: true, stylePool })
+    const diff = log.render(mkFrame(prev, w, viewportH, h), mkFrame(next, w, viewportH, h), true, false)
+
+    expect(diff.some(p => p.type === 'clearTerminal')).toBe(true)
+    expect(stdoutOnly(diff)).toContain('timer2s')
+  })
+
+  it('keeps DECSTBM fast-path when scroll region stays above bottom row', () => {
+    const w = 12
+    const h = 6
+    const prev = mkScreen(w, h)
+    const next = mkScreen(w, h)
+
+    paint(prev, 1, 'row one')
+    paint(next, 1, 'row one')
+
+    const prevFrame = mkFrame(prev, w, h)
+
+    const nextFrame: Frame = {
+      ...mkFrame(next, w, h),
+      scrollHint: { top: 1, bottom: 4, delta: 1 }
+    }
+
+    const log = new LogUpdate({ isTTY: true, stylePool })
+    const diff = log.render(prevFrame, nextFrame, true, true)
+
+    expect(hasDecstbm(stdoutOnly(diff))).toBe(true)
+  })
+
+  it('skips DECSTBM when scroll region touches the bottom row', () => {
+    const w = 12
+    const h = 6
+    const prev = mkScreen(w, h)
+    const next = mkScreen(w, h)
+
+    paint(prev, 1, 'row one')
+    paint(next, 1, 'row one')
+
+    const prevFrame = mkFrame(prev, w, h)
+
+    const nextFrame: Frame = {
+      ...mkFrame(next, w, h),
+      scrollHint: { top: 1, bottom: 5, delta: 1 }
+    }
+
+    const log = new LogUpdate({ isTTY: true, stylePool })
+    const diff = log.render(prevFrame, nextFrame, true, true)
+
+    expect(hasDecstbm(stdoutOnly(diff))).toBe(false)
+  })
+})

ui-tui/packages/hermes-ink/src/ink/log-update.ts

@@ -0,0 +1,752 @@
+import { type AnsiCode, ansiCodesToString, diffAnsiCodes } from '@alcalzone/ansi-tokenize'
+
+import { logForDebugging } from '../utils/debug.js'
+
+import type { Diff, FlickerReason, Frame } from './frame.js'
+import type { Point } from './layout/geometry.js'
+import {
+  type Cell,
+  cellAt,
+  CellWidth,
+  charInCellAt,
+  diffEach,
+  type Hyperlink,
+  isEmptyCellAt,
+  type Screen,
+  shiftRows,
+  type StylePool,
+  visibleCellAtIndex
+} from './screen.js'
+import {
+  scrollDown as csiScrollDown,
+  scrollUp as csiScrollUp,
+  CURSOR_HOME,
+  RESET_SCROLL_REGION,
+  setScrollRegion
+} from './termio/csi.js'
+import { LINK_END, link as oscLink } from './termio/osc.js'
+
+type State = {
+  previousOutput: string
+}
+
+type Options = {
+  isTTY: boolean
+  stylePool: StylePool
+}
+
+const CARRIAGE_RETURN = { type: 'carriageReturn' } as const
+const NEWLINE = { type: 'stdout', content: '\n' } as const
+
+export class LogUpdate {
+  private state: State
+
+  constructor(private readonly options: Options) {
+    this.state = {
+      previousOutput: ''
+    }
+  }
+
+  renderPreviousOutput_DEPRECATED(prevFrame: Frame): Diff {
+    if (!this.options.isTTY) {
+      // Non-TTY output is no longer supported (string output was removed)
+      return [NEWLINE]
+    }
+
+    return this.getRenderOpsForDone(prevFrame)
+  }
+
+  // Called when process resumes from suspension (SIGCONT) to prevent clobbering terminal content
+  reset(): void {
+    this.state.previousOutput = ''
+  }
+
+  private renderFullFrame(frame: Frame): Diff {
+    const { screen } = frame
+    const lines: string[] = []
+    let currentStyles: AnsiCode[] = []
+    let currentHyperlink: Hyperlink = undefined
+
+    for (let y = 0; y < screen.height; y++) {
+      let line = ''
+
+      for (let x = 0; x < screen.width; x++) {
+        const cell = cellAt(screen, x, y)
+
+        if (cell && cell.width !== CellWidth.SpacerTail) {
+          // Handle hyperlink transitions
+          if (cell.hyperlink !== currentHyperlink) {
+            if (currentHyperlink !== undefined) {
+              line += LINK_END
+            }
+
+            if (cell.hyperlink !== undefined) {
+              line += oscLink(cell.hyperlink)
+            }
+
+            currentHyperlink = cell.hyperlink
+          }
+
+          const cellStyles = this.options.stylePool.get(cell.styleId)
+          const styleDiff = diffAnsiCodes(currentStyles, cellStyles)
+
+          if (styleDiff.length > 0) {
+            line += ansiCodesToString(styleDiff)
+            currentStyles = cellStyles
+          }
+
+          line += cell.char
+        }
+      }
+
+      // Close any open hyperlink before resetting styles
+      if (currentHyperlink !== undefined) {
+        line += LINK_END
+        currentHyperlink = undefined
+      }
+
+      // Reset styles at end of line so trimEnd doesn't leave dangling codes
+      const resetCodes = diffAnsiCodes(currentStyles, [])
+
+      if (resetCodes.length > 0) {
+        line += ansiCodesToString(resetCodes)
+        currentStyles = []
+      }
+
+      lines.push(line.trimEnd())
+    }
+
+    if (lines.length === 0) {
+      return []
+    }
+
+    return [{ type: 'stdout', content: lines.join('\n') }]
+  }
+
+  private getRenderOpsForDone(prev: Frame): Diff {
+    this.state.previousOutput = ''
+
+    if (!prev.cursor.visible) {
+      return [{ type: 'cursorShow' }]
+    }
+
+    return []
+  }
+
+  render(prev: Frame, next: Frame, altScreen = false, decstbmSafe = true): Diff {
+    if (!this.options.isTTY) {
+      return this.renderFullFrame(next)
+    }
+
+    const startTime = performance.now()
+    const stylePool = this.options.stylePool
+
+    // Terminal hosts can reflow/preserve old cells on any resize, including
+    // height-only growth. A partial diff can then leave stale transcript rows
+    // or cut off bordered content even when our virtual scrollTop is correct.
+    // Resizing is rare enough that a full repaint is the safer tradeoff.
+    if (
+      next.viewport.height !== prev.viewport.height ||
+      (prev.viewport.width !== 0 && next.viewport.width !== prev.viewport.width)
+    ) {
+      return fullResetSequence_CAUSES_FLICKER(next, 'resize', stylePool)
+    }
+
+    // DECSTBM scroll optimization: when a ScrollBox's scrollTop changed,
+    // shift content with a hardware scroll (CSI top;bot r + CSI n S/T)
+    // instead of rewriting the whole scroll region. The shiftRows on
+    // prev.screen simulates the shift so the diff loop below naturally
+    // finds only the rows that scrolled IN as diffs. prev.screen is
+    // about to become backFrame (reused next render) so mutation is safe.
+    // CURSOR_HOME after RESET_SCROLL_REGION is defensive — DECSTBM reset
+    // homes cursor per spec but terminal implementations vary.
+    //
+    // decstbmSafe: caller passes false when the DECSTBM→diff sequence
+    // can't be made atomic (no DEC 2026 / BSU/ESU). Without atomicity the
+    // outer terminal renders the intermediate state — region scrolled,
+    // edge rows not yet painted — a visible vertical jump on every frame
+    // where scrollTop moves. Falling through to the diff loop writes all
+    // shifted rows: more bytes, no intermediate state. next.screen from
+    // render-node-to-output's blit+shift is correct either way.
+    let scrollPatch: Diff = []
+
+    if (altScreen && next.scrollHint && decstbmSafe) {
+      const { top, bottom, delta } = next.scrollHint
+
+      // Keep DECSTBM away from the terminal's last visible row. In alt-screen
+      // layouts we reserve that lane for status/cursor parking, and scrolling
+      // it can leave transient ghosting/bleed artifacts until a later repaint.
+      if (top >= 0 && bottom < prev.screen.height - 1 && bottom < next.screen.height - 1) {
+        shiftRows(prev.screen, top, bottom, delta)
+        scrollPatch = [
+          {
+            type: 'stdout',
+            content:
+              setScrollRegion(top + 1, bottom + 1) +
+              (delta > 0 ? csiScrollUp(delta) : csiScrollDown(-delta)) +
+              RESET_SCROLL_REGION +
+              CURSOR_HOME
+          }
+        ]
+      }
+    }
+
+    // We have to use purely relative operations to manipulate the cursor since
+    // we don't know its starting point.
+    //
+    // When content height >= viewport height AND cursor is at the bottom,
+    // the cursor restore at the end of the previous frame caused terminal scroll.
+    // viewportY tells us how many rows are in scrollback from content overflow.
+    // Additionally, the cursor-restore scroll pushes 1 more row into scrollback.
+    // We need fullReset if any changes are to rows that are now in scrollback.
+    //
+    // This early full-reset check only applies in "steady state" (not growing).
+    // For growing, the viewportY calculation below (with cursorRestoreScroll)
+    // catches unreachable scrollback rows in the diff loop instead.
+    const cursorAtBottom = prev.cursor.y >= prev.screen.height
+    const isGrowing = next.screen.height > prev.screen.height
+
+    // When content fills the viewport exactly (height == viewport) and the
+    // cursor is at the bottom, the cursor-restore LF at the end of the
+    // previous frame scrolled 1 row into scrollback. Use >= to catch this.
+    const prevHadScrollback = cursorAtBottom && prev.screen.height >= prev.viewport.height
+
+    const isShrinking = next.screen.height < prev.screen.height
+    const nextFitsViewport = next.screen.height <= prev.viewport.height
+
+    // When shrinking from above-viewport to at-or-below-viewport, content that
+    // was in scrollback should now be visible. Terminal clear operations can't
+    // bring scrollback content into view, so we need a full reset.
+    // Use <= (not <) because even when next height equals viewport height, the
+    // scrollback depth from the previous render differs from a fresh render.
+    if (prevHadScrollback && nextFitsViewport && isShrinking) {
+      logForDebugging(
+        `Full reset (shrink->below): prevHeight=${prev.screen.height}, nextHeight=${next.screen.height}, viewport=${prev.viewport.height}`
+      )
+
+      return fullResetSequence_CAUSES_FLICKER(next, 'offscreen', stylePool)
+    }
+
+    if (
+      altScreen &&
+      prev.screen.height >= prev.viewport.height &&
+      prev.screen.height > 0 &&
+      cursorAtBottom &&
+      !isGrowing
+    ) {
+      // viewportY = rows in scrollback from content overflow
+      // +1 for the row pushed by cursor-restore scroll
+      const viewportY = prev.screen.height - prev.viewport.height
+      const scrollbackRows = viewportY + 1
+
+      let scrollbackChangeY = -1
+      diffEach(prev.screen, next.screen, (_x, y) => {
+        if (y < scrollbackRows) {
+          scrollbackChangeY = y
+
+          return true // early exit
+        }
+      })
+
+      if (scrollbackChangeY >= 0) {
+        const prevLine = readLine(prev.screen, scrollbackChangeY)
+        const nextLine = readLine(next.screen, scrollbackChangeY)
+
+        return fullResetSequence_CAUSES_FLICKER(next, 'offscreen', stylePool, {
+          triggerY: scrollbackChangeY,
+          prevLine,
+          nextLine
+        })
+      }
+    }
+
+    const screen = new VirtualScreen(prev.cursor, next.viewport.width)
+
+    // Treat empty screen as height 1 to avoid spurious adjustments on first render
+    const heightDelta = Math.max(next.screen.height, 1) - Math.max(prev.screen.height, 1)
+
+    const shrinking = heightDelta < 0
+    const growing = heightDelta > 0
+
+    // Handle shrinking: clear lines from the bottom
+    if (shrinking) {
+      const linesToClear = prev.screen.height - next.screen.height
+
+      // eraseLines only works within the viewport - it can't clear scrollback.
+      // If we need to clear more lines than fit in the viewport, some are in
+      // scrollback, so we need a full reset.
+      if (linesToClear > prev.viewport.height) {
+        return fullResetSequence_CAUSES_FLICKER(next, 'offscreen', this.options.stylePool)
+      }
+
+      // clear(N) moves cursor UP by N-1 lines and to column 0
+      // This puts us at line prev.screen.height - N = next.screen.height
+      // But we want to be at next.screen.height - 1 (bottom of new screen)
+      screen.txn(prev => [
+        [
+          { type: 'clear', count: linesToClear },
+          { type: 'cursorMove', x: 0, y: -1 }
+        ],
+        { dx: -prev.x, dy: -linesToClear }
+      ])
+    }
+
+    // viewportY = number of rows in scrollback (not visible on terminal).
+    // For shrinking: use max(prev, next) because terminal clears don't scroll.
+    // For growing: use prev state because new rows haven't scrolled old ones yet.
+    // When prevHadScrollback, add 1 for the cursor-restore LF that scrolled
+    // an additional row out of view at the end of the previous frame. Without
+    // this, the diff loop treats that row as reachable — but the cursor clamps
+    // at viewport top, causing writes to land 1 row off and garbling the output.
+    const cursorRestoreScroll = prevHadScrollback ? 1 : 0
+
+    const viewportY = growing
+      ? Math.max(0, prev.screen.height - prev.viewport.height + cursorRestoreScroll)
+      : Math.max(prev.screen.height, next.screen.height) - next.viewport.height + cursorRestoreScroll
+
+    let currentStyleId = stylePool.none
+    let currentHyperlink: Hyperlink = undefined
+
+    // First pass: render changes to existing rows (rows < prev.screen.height)
+    let needsFullReset = false
+    let resetTriggerY = -1
+    diffEach(prev.screen, next.screen, (x, y, removed, added) => {
+      // Skip new rows - we'll render them directly after
+      if (growing && y >= prev.screen.height) {
+        return
+      }
+
+      // Skip spacers during rendering because the terminal will automatically
+      // advance 2 columns when we write the wide character itself.
+      // SpacerTail: Second cell of a wide character
+      // SpacerHead: Marks line-end position where wide char wraps to next line
+      if (added && (added.width === CellWidth.SpacerTail || added.width === CellWidth.SpacerHead)) {
+        return
+      }
+
+      if (removed && (removed.width === CellWidth.SpacerTail || removed.width === CellWidth.SpacerHead) && !added) {
+        return
+      }
+
+      // Skip empty cells that don't need to overwrite existing content.
+      // This prevents writing trailing spaces that would cause unnecessary
+      // line wrapping at the edge of the screen.
+      // Uses isEmptyCellAt to check if both packed words are zero (empty cell).
+      if (added && isEmptyCellAt(next.screen, x, y) && !removed) {
+        return
+      }
+
+      // If the cell outside the viewport range has changed, we need to reset
+      // because we can't move the cursor there to draw. In main-screen mode,
+      // those rows are already in terminal scrollback and invisible; resetting
+      // on every scrollback-only update can loop when a resize changes the
+      // physical buffer. Shrink-to-visible cases are handled above.
+      if (y < viewportY) {
+        if (!altScreen) {
+          return
+        }
+
+        needsFullReset = true
+        resetTriggerY = y
+
+        return true // early exit
+      }
+
+      moveCursorTo(screen, x, y)
+
+      if (added) {
+        const targetHyperlink = added.hyperlink
+        currentHyperlink = transitionHyperlink(screen.diff, currentHyperlink, targetHyperlink)
+        const styleStr = stylePool.transition(currentStyleId, added.styleId)
+
+        if (writeCellWithStyleStr(screen, added, styleStr)) {
+          currentStyleId = added.styleId
+        }
+      } else if (removed) {
+        // Cell was removed - clear it with a space
+        // (This handles shrinking content)
+        // Reset any active styles/hyperlinks first to avoid leaking into cleared cells
+        const styleIdToReset = currentStyleId
+        const hyperlinkToReset = currentHyperlink
+        currentStyleId = stylePool.none
+        currentHyperlink = undefined
+
+        screen.txn(() => {
+          const patches: Diff = []
+          transitionStyle(patches, stylePool, styleIdToReset, stylePool.none)
+          transitionHyperlink(patches, hyperlinkToReset, undefined)
+          patches.push({ type: 'stdout', content: ' ' })
+
+          return [patches, { dx: 1, dy: 0 }]
+        })
+      }
+    })
+
+    if (needsFullReset) {
+      return fullResetSequence_CAUSES_FLICKER(next, 'offscreen', stylePool, {
+        triggerY: resetTriggerY,
+        prevLine: readLine(prev.screen, resetTriggerY),
+        nextLine: readLine(next.screen, resetTriggerY)
+      })
+    }
+
+    // Reset styles before rendering new rows (they'll set their own styles)
+    currentStyleId = transitionStyle(screen.diff, stylePool, currentStyleId, stylePool.none)
+    currentHyperlink = transitionHyperlink(screen.diff, currentHyperlink, undefined)
+
+    // Handle growth: render new rows directly (they naturally scroll the terminal)
+    if (growing) {
+      renderFrameSlice(screen, next, prev.screen.height, next.screen.height, stylePool)
+    }
+
+    // Restore cursor. Skipped in alt-screen: the cursor is hidden, its
+    // position only matters as the starting point for the NEXT frame's
+    // relative moves, and in alt-screen the next frame always begins with
+    // CSI H (see ink.tsx onRender) which resets to (0,0) regardless. This
+    // saves a CR + cursorMove round-trip (~6-10 bytes) every frame.
+    //
+    // Main screen: if cursor needs to be past the last line of content
+    // (typical: cursor.y = screen.height), emit \n to create that line
+    // since cursor movement can't create new lines.
+    if (altScreen) {
+      // no-op; next frame's CSI H anchors cursor
+    } else if (next.cursor.y >= next.screen.height) {
+      // Move to column 0 of current line, then emit newlines to reach target row
+      screen.txn(prev => {
+        const rowsToCreate = next.cursor.y - prev.y
+
+        if (rowsToCreate > 0) {
+          // Use CR to resolve pending wrap (if any) without advancing
+          // to the next line, then LF to create each new row.
+          const patches: Diff = new Array<Diff[number]>(1 + rowsToCreate)
+          patches[0] = CARRIAGE_RETURN
+
+          for (let i = 0; i < rowsToCreate; i++) {
+            patches[1 + i] = NEWLINE
+          }
+
+          return [patches, { dx: -prev.x, dy: rowsToCreate }]
+        }
+
+        // At or past target row - need to move cursor to correct position
+        const dy = next.cursor.y - prev.y
+
+        if (dy !== 0 || prev.x !== next.cursor.x) {
+          // Use CR to clear pending wrap (if any), then cursor move
+          const patches: Diff = [CARRIAGE_RETURN]
+          patches.push({ type: 'cursorMove', x: next.cursor.x, y: dy })
+
+          return [patches, { dx: next.cursor.x - prev.x, dy }]
+        }
+
+        return [[], { dx: 0, dy: 0 }]
+      })
+    } else {
+      moveCursorTo(screen, next.cursor.x, next.cursor.y)
+    }
+
+    const elapsed = performance.now() - startTime
+
+    if (elapsed > 50) {
+      const damage = next.screen.damage
+
+      const damageInfo = damage ? `${damage.width}x${damage.height} at (${damage.x},${damage.y})` : 'none'
+
+      logForDebugging(
+        `Slow render: ${elapsed.toFixed(1)}ms, screen: ${next.screen.height}x${next.screen.width}, damage: ${damageInfo}, changes: ${screen.diff.length}`
+      )
+    }
+
+    return scrollPatch.length > 0 ? [...scrollPatch, ...screen.diff] : screen.diff
+  }
+}
+
+function transitionHyperlink(diff: Diff, current: Hyperlink, target: Hyperlink): Hyperlink {
+  if (current !== target) {
+    diff.push({ type: 'hyperlink', uri: target ?? '' })
+
+    return target
+  }
+
+  return current
+}
+
+function transitionStyle(diff: Diff, stylePool: StylePool, currentId: number, targetId: number): number {
+  const str = stylePool.transition(currentId, targetId)
+
+  if (str.length > 0) {
+    diff.push({ type: 'styleStr', str })
+  }
+
+  return targetId
+}
+
+function readLine(screen: Screen, y: number): string {
+  let line = ''
+
+  for (let x = 0; x < screen.width; x++) {
+    line += charInCellAt(screen, x, y) ?? ' '
+  }
+
+  return line.trimEnd()
+}
+
+function fullResetSequence_CAUSES_FLICKER(
+  frame: Frame,
+  reason: FlickerReason,
+  stylePool: StylePool,
+  debug?: { triggerY: number; prevLine: string; nextLine: string }
+): Diff {
+  // After clearTerminal, cursor is at (0, 0)
+  const screen = new VirtualScreen({ x: 0, y: 0 }, frame.viewport.width)
+  renderFrame(screen, frame, stylePool)
+
+  return [{ type: 'clearTerminal', reason, debug }, ...screen.diff]
+}
+
+function renderFrame(screen: VirtualScreen, frame: Frame, stylePool: StylePool): void {
+  renderFrameSlice(screen, frame, 0, frame.screen.height, stylePool)
+}
+
+/**
+ * Render a slice of rows from the frame's screen.
+ * Each row is rendered followed by a newline. Cursor ends at (0, endY).
+ */
+function renderFrameSlice(
+  screen: VirtualScreen,
+  frame: Frame,
+  startY: number,
+  endY: number,
+  stylePool: StylePool
+): VirtualScreen {
+  let currentStyleId = stylePool.none
+  let currentHyperlink: Hyperlink = undefined
+  // Track the styleId of the last rendered cell on this line (-1 if none).
+  // Passed to visibleCellAtIndex to enable fg-only space optimization.
+  let lastRenderedStyleId = -1
+
+  const { width: screenWidth, cells, charPool, hyperlinkPool } = frame.screen
+
+  let index = startY * screenWidth
+
+  for (let y = startY; y < endY; y += 1) {
+    // Advance cursor to this row using LF (not CSI CUD / cursor-down).
+    // CSI CUD stops at the viewport bottom margin and cannot scroll,
+    // but LF scrolls the viewport to create new lines. Without this,
+    // when the cursor is at the viewport bottom, moveCursorTo's
+    // cursor-down silently fails, creating a permanent off-by-one
+    // between the virtual cursor and the real terminal cursor.
+    if (screen.cursor.y < y) {
+      const rowsToAdvance = y - screen.cursor.y
+      screen.txn(prev => {
+        const patches: Diff = new Array<Diff[number]>(1 + rowsToAdvance)
+        patches[0] = CARRIAGE_RETURN
+
+        for (let i = 0; i < rowsToAdvance; i++) {
+          patches[1 + i] = NEWLINE
+        }
+
+        return [patches, { dx: -prev.x, dy: rowsToAdvance }]
+      })
+    }
+
+    // Reset at start of each line — no cell rendered yet
+    lastRenderedStyleId = -1
+
+    for (let x = 0; x < screenWidth; x += 1, index += 1) {
+      // Skip spacers, unstyled empty cells, and fg-only styled spaces that
+      // match the last rendered style (since cursor-forward produces identical
+      // visual result). visibleCellAtIndex handles the optimization internally
+      // to avoid allocating Cell objects for skipped cells.
+      const cell = visibleCellAtIndex(cells, charPool, hyperlinkPool, index, lastRenderedStyleId)
+
+      if (!cell) {
+        continue
+      }
+
+      moveCursorTo(screen, x, y)
+
+      // Handle hyperlink
+      const targetHyperlink = cell.hyperlink
+      currentHyperlink = transitionHyperlink(screen.diff, currentHyperlink, targetHyperlink)
+
+      // Style transition — cached string, zero allocations after warmup
+      const styleStr = stylePool.transition(currentStyleId, cell.styleId)
+
+      if (writeCellWithStyleStr(screen, cell, styleStr)) {
+        currentStyleId = cell.styleId
+        lastRenderedStyleId = cell.styleId
+      }
+    }
+
+    // Reset styles/hyperlinks before newline so background color doesn't
+    // bleed into the next line when the terminal scrolls. The old code
+    // reset implicitly by writing trailing unstyled spaces; now that we
+    // skip empty cells, we must reset explicitly.
+    currentStyleId = transitionStyle(screen.diff, stylePool, currentStyleId, stylePool.none)
+    currentHyperlink = transitionHyperlink(screen.diff, currentHyperlink, undefined)
+    // CR+LF at end of row — \r resets to column 0, \n moves to next line.
+    // Without \r, the terminal cursor stays at whatever column content ended
+    // (since we skip trailing spaces, this can be mid-row).
+    screen.txn(prev => [[CARRIAGE_RETURN, NEWLINE], { dx: -prev.x, dy: 1 }])
+  }
+
+  // Reset any open style/hyperlink at end of slice
+  transitionStyle(screen.diff, stylePool, currentStyleId, stylePool.none)
+  transitionHyperlink(screen.diff, currentHyperlink, undefined)
+
+  return screen
+}
+
+type Delta = { dx: number; dy: number }
+
+/**
+ * Write a cell with a pre-serialized style transition string (from
+ * StylePool.transition). Inlines the txn logic to avoid closure/tuple/delta
+ * allocations on every cell.
+ *
+ * Returns true if the cell was written, false if skipped (wide char at
+ * viewport edge). Callers MUST gate currentStyleId updates on this — when
+ * skipped, styleStr is never pushed and the terminal's style state is
+ * unchanged. Updating the virtual tracker anyway desyncs it from the
+ * terminal, and the next transition is computed from phantom state.
+ */
+function writeCellWithStyleStr(screen: VirtualScreen, cell: Cell, styleStr: string): boolean {
+  const cellWidth = cell.width === CellWidth.Wide ? 2 : 1
+  const px = screen.cursor.x
+  const vw = screen.viewportWidth
+
+  // Don't write wide chars that would cross the viewport edge.
+  // Single-codepoint chars (CJK) at vw-2 are safe; multi-codepoint
+  // graphemes (flags, ZWJ emoji) need stricter threshold.
+  if (cellWidth === 2 && px < vw) {
+    const threshold = cell.char.length > 2 ? vw : vw + 1
+
+    if (px + 2 >= threshold) {
+      return false
+    }
+  }
+
+  const diff = screen.diff
+
+  if (styleStr.length > 0) {
+    diff.push({ type: 'styleStr', str: styleStr })
+  }
+
+  const needsCompensation = cellWidth === 2 && needsWidthCompensation(cell.char)
+
+  // On terminals with old wcwidth tables, a compensated emoji only advances
+  // the cursor 1 column, so the CHA below skips column x+1 without painting
+  // it. Write a styled space there first — on correct terminals the emoji
+  // glyph (width 2) overwrites it harmlessly; on old terminals it fills the
+  // gap with the emoji's background. Also clears any stale content at x+1.
+  // CHA is 1-based, so column px+1 (0-based) is CHA target px+2.
+  if (needsCompensation && px + 1 < vw) {
+    diff.push({ type: 'cursorTo', col: px + 2 })
+    diff.push({ type: 'stdout', content: ' ' })
+    diff.push({ type: 'cursorTo', col: px + 1 })
+  }
+
+  diff.push({ type: 'stdout', content: cell.char })
+
+  // Force terminal cursor to correct column after the emoji.
+  if (needsCompensation) {
+    diff.push({ type: 'cursorTo', col: px + cellWidth + 1 })
+  }
+
+  // Update cursor — mutate in place to avoid Point allocation
+  if (px >= vw) {
+    screen.cursor.x = cellWidth
+    screen.cursor.y++
+  } else {
+    screen.cursor.x = px + cellWidth
+  }
+
+  return true
+}
+
+function moveCursorTo(screen: VirtualScreen, targetX: number, targetY: number) {
+  screen.txn(prev => {
+    const dx = targetX - prev.x
+    const dy = targetY - prev.y
+    const inPendingWrap = prev.x >= screen.viewportWidth
+
+    // If we're in pending wrap state (cursor.x >= width), use CR
+    // to reset to column 0 on the current line without advancing
+    // to the next line, then issue the cursor movement.
+    if (inPendingWrap) {
+      return [[CARRIAGE_RETURN, { type: 'cursorMove', x: targetX, y: dy }], { dx, dy }]
+    }
+
+    // When moving to a different line, use carriage return (\r) to reset to
+    // column 0 first, then cursor move.
+    if (dy !== 0) {
+      return [[CARRIAGE_RETURN, { type: 'cursorMove', x: targetX, y: dy }], { dx, dy }]
+    }
+
+    // Standard same-line cursor move
+    return [[{ type: 'cursorMove', x: dx, y: dy }], { dx, dy }]
+  })
+}
+
+/**
+ * Identify emoji where the terminal's wcwidth may disagree with Unicode.
+ * On terminals with correct tables, the CHA we emit is a harmless no-op.
+ *
+ * Two categories:
+ * 1. Newer emoji (Unicode 12.0+) missing from terminal wcwidth tables.
+ * 2. Text-by-default emoji + VS16 (U+FE0F): the base codepoint is width 1
+ *    in wcwidth, but VS16 triggers emoji presentation making it width 2.
+ *    Examples: ⚔️ (U+2694), ☠️ (U+2620), ❤️ (U+2764).
+ */
+function needsWidthCompensation(char: string): boolean {
+  const cp = char.codePointAt(0)
+
+  if (cp === undefined) {
+    return false
+  }
+
+  // U+1FA70-U+1FAFF: Symbols and Pictographs Extended-A (Unicode 12.0-15.0)
+  // U+1FB00-U+1FBFF: Symbols for Legacy Computing (Unicode 13.0)
+  if ((cp >= 0x1fa70 && cp <= 0x1faff) || (cp >= 0x1fb00 && cp <= 0x1fbff)) {
+    return true
+  }
+
+  // Text-by-default emoji with VS16: scan for U+FE0F in multi-codepoint
+  // graphemes. Single BMP chars (length 1) and surrogate pairs without VS16
+  // skip this check. VS16 (0xFE0F) can't collide with surrogates (0xD800-0xDFFF).
+  if (char.length >= 2) {
+    for (let i = 0; i < char.length; i++) {
+      if (char.charCodeAt(i) === 0xfe0f) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
+class VirtualScreen {
+  // Public for direct mutation by writeCellWithStyleStr (avoids txn overhead).
+  // File-private class — not exposed outside log-update.ts.
+  cursor: Point
+  diff: Diff = []
+
+  constructor(
+    origin: Point,
+    readonly viewportWidth: number
+  ) {
+    this.cursor = { ...origin }
+  }
+
+  txn(fn: (prev: Point) => [patches: Diff, next: Delta]): void {
+    const [patches, next] = fn(this.cursor)
+
+    for (const patch of patches) {
+      this.diff.push(patch)
+    }
+
+    this.cursor.x += next.dx
+    this.cursor.y += next.dy
+  }
+}

ui-tui/packages/hermes-ink/src/ink/lru.ts

@@ -0,0 +1,14 @@
+// Shared eviction for the hot Ink LRU caches (widthCache, wrapCache,
+// sliceCache, lineWidthCache). Hot-path touch-on-read stays inlined per
+// cache — only the bulk eviction is factored here.
+export function lruEvict<K, V>(cache: Map<K, V>, keepRatio: number): void {
+  if (keepRatio <= 0) {
+    return cache.clear()
+  }
+
+  const target = Math.floor(cache.size * keepRatio)
+
+  while (cache.size > target) {
+    cache.delete(cache.keys().next().value!)
+  }
+}

ui-tui/packages/hermes-ink/src/ink/measure-element.ts

@@ -0,0 +1,23 @@
+import type { DOMElement } from './dom.js'
+
+type Output = {
+  /**
+   * Element width.
+   */
+  width: number
+
+  /**
+   * Element height.
+   */
+  height: number
+}
+
+/**
+ * Measure the dimensions of a particular `<Box>` element.
+ */
+const measureElement = (node: DOMElement): Output => ({
+  width: node.yogaNode?.getComputedWidth() ?? 0,
+  height: node.yogaNode?.getComputedHeight() ?? 0
+})
+
+export default measureElement

ui-tui/packages/hermes-ink/src/ink/measure-text.ts

@@ -0,0 +1,50 @@
+import { lineWidth } from './line-width-cache.js'
+
+type Output = {
+  width: number
+  height: number
+}
+
+// Single-pass measurement: computes both width and height in one
+// iteration instead of two (widestLine + countVisualLines).
+// Uses indexOf to avoid array allocation from split('\n').
+function measureText(text: string, maxWidth: number): Output {
+  if (text.length === 0) {
+    return {
+      width: 0,
+      height: 0
+    }
+  }
+
+  // Infinite or non-positive width means no wrapping — each line is one visual line.
+  // Must check before the loop since Math.ceil(w / Infinity) = 0.
+  const noWrap = maxWidth <= 0 || !Number.isFinite(maxWidth)
+
+  let height = 0
+  let width = 0
+  let start = 0
+
+  while (start <= text.length) {
+    const end = text.indexOf('\n', start)
+    const line = end === -1 ? text.substring(start) : text.substring(start, end)
+
+    const w = lineWidth(line)
+    width = Math.max(width, w)
+
+    if (noWrap) {
+      height++
+    } else {
+      height += w === 0 ? 1 : Math.ceil(w / maxWidth)
+    }
+
+    if (end === -1) {
+      break
+    }
+
+    start = end + 1
+  }
+
+  return { width, height }
+}
+
+export default measureText

ui-tui/packages/hermes-ink/src/ink/node-cache.ts

@@ -0,0 +1,53 @@
+import type { DOMElement } from './dom.js'
+import type { Rectangle } from './layout/geometry.js'
+
+/**
+ * Cached layout bounds for each rendered node (used for blit + clearing).
+ * `top` is the yoga-local getComputedTop() — stored so ScrollBox viewport
+ * culling can skip yoga reads for clean children whose position hasn't
+ * shifted (O(dirty) instead of O(mounted) first-pass).
+ */
+export type CachedLayout = {
+  x: number
+  y: number
+  width: number
+  height: number
+  top?: number
+}
+
+export const nodeCache = new WeakMap<DOMElement, CachedLayout>()
+
+/** Rects of removed children that need clearing on next render */
+export const pendingClears = new WeakMap<DOMElement, Rectangle[]>()
+
+/**
+ * Set when a pendingClear is added for an absolute-positioned node.
+ * Signals renderer to disable blit for the next frame: the removed node
+ * may have painted over non-siblings (e.g. an overlay over a ScrollBox
+ * earlier in tree order), so their blits from prevScreen would restore
+ * the overlay's pixels. Normal-flow removals are already handled by
+ * hasRemovedChild at the parent level; only absolute positioning paints
+ * cross-subtree. Reset at the start of each render.
+ */
+let absoluteNodeRemoved = false
+
+export function addPendingClear(parent: DOMElement, rect: Rectangle, isAbsolute: boolean): void {
+  const existing = pendingClears.get(parent)
+
+  if (existing) {
+    existing.push(rect)
+  } else {
+    pendingClears.set(parent, [rect])
+  }
+
+  if (isAbsolute) {
+    absoluteNodeRemoved = true
+  }
+}
+
+export function consumeAbsoluteRemovedFlag(): boolean {
+  const had = absoluteNodeRemoved
+  absoluteNodeRemoved = false
+
+  return had
+}

ui-tui/packages/hermes-ink/src/ink/optimizer.ts

@@ -0,0 +1,99 @@
+import type { Diff } from './frame.js'
+
+/**
+ * Optimize a diff by applying all optimization rules in a single pass.
+ * This reduces the number of patches that need to be written to the terminal.
+ *
+ * Rules applied:
+ * - Remove empty stdout patches
+ * - Merge consecutive cursorMove patches
+ * - Remove no-op cursorMove (0,0) patches
+ * - Concat adjacent style patches (transition diffs — can't drop either)
+ * - Dedupe consecutive hyperlinks with same URI
+ * - Cancel cursor hide/show pairs
+ * - Remove clear patches with count 0
+ */
+export function optimize(diff: Diff): Diff {
+  if (diff.length <= 1) {
+    return diff
+  }
+
+  const result: Diff = []
+  let len = 0
+
+  for (const patch of diff) {
+    const type = patch.type
+
+    // Skip no-ops
+    if (type === 'stdout') {
+      if (patch.content === '') {
+        continue
+      }
+    } else if (type === 'cursorMove') {
+      if (patch.x === 0 && patch.y === 0) {
+        continue
+      }
+    } else if (type === 'clear') {
+      if (patch.count === 0) {
+        continue
+      }
+    }
+
+    // Try to merge with previous patch
+    if (len > 0) {
+      const lastIdx = len - 1
+      const last = result[lastIdx]!
+      const lastType = last.type
+
+      // Merge consecutive cursorMove
+      if (type === 'cursorMove' && lastType === 'cursorMove') {
+        result[lastIdx] = {
+          type: 'cursorMove',
+          x: last.x + patch.x,
+          y: last.y + patch.y
+        }
+
+        continue
+      }
+
+      // Collapse consecutive cursorTo (only the last one matters)
+      if (type === 'cursorTo' && lastType === 'cursorTo') {
+        result[lastIdx] = patch
+
+        continue
+      }
+
+      // Concat adjacent style patches. styleStr is a transition diff
+      // (computed by diffAnsiCodes(from, to)), not a setter — dropping
+      // the first is only sound if its undo-codes are a subset of the
+      // second's, which is NOT guaranteed. e.g. [\e[49m, \e[2m]: dropping
+      // the bg reset leaks it into the next \e[2J/\e[2K via BCE.
+      if (type === 'styleStr' && lastType === 'styleStr') {
+        result[lastIdx] = { type: 'styleStr', str: last.str + patch.str }
+
+        continue
+      }
+
+      // Dedupe hyperlinks
+      if (type === 'hyperlink' && lastType === 'hyperlink' && patch.uri === last.uri) {
+        continue
+      }
+
+      // Cancel cursor hide/show pairs
+      if (
+        (type === 'cursorShow' && lastType === 'cursorHide') ||
+        (type === 'cursorHide' && lastType === 'cursorShow')
+      ) {
+        result.pop()
+        len--
+
+        continue
+      }
+    }
+
+    result.push(patch)
+    len++
+  }
+
+  return result
+}

ui-tui/packages/hermes-ink/src/ink/output.ts

@@ -0,0 +1,845 @@
+import { type AnsiCode, type StyledChar, styledCharsFromTokens, tokenize } from '@alcalzone/ansi-tokenize'
+
+import { logForDebugging } from '../utils/debug.js'
+import { getGraphemeSegmenter } from '../utils/intl.js'
+import sliceAnsi from '../utils/sliceAnsi.js'
+
+import { reorderBidi } from './bidi.js'
+import { type Rectangle, unionRect } from './layout/geometry.js'
+import {
+  blitRegion,
+  CellWidth,
+  extractHyperlinkFromStyles,
+  filterOutHyperlinkStyles,
+  markNoSelectRegion,
+  OSC8_PREFIX,
+  resetScreen,
+  type Screen,
+  setCellAt,
+  shiftRows,
+  type StylePool
+} from './screen.js'
+import { stringWidth } from './stringWidth.js'
+import { widestLine } from './widest-line.js'
+
+/**
+ * A grapheme cluster with precomputed terminal width, styleId, and hyperlink.
+ * Built once per unique line (cached via charCache), so the per-char hot loop
+ * is just property reads + setCellAt — no stringWidth, no style interning,
+ * no hyperlink extraction per frame.
+ *
+ * styleId is safe to cache: StylePool is session-lived (never reset).
+ * hyperlink is stored as a string (not interned ID) since hyperlinkPool
+ * resets every 5 min; setCellAt interns it per-frame (cheap Map.get).
+ */
+type ClusteredChar = {
+  value: string
+  width: number
+  styleId: number
+  hyperlink: string | undefined
+}
+
+/**
+ * Collects write/blit/clear/clip operations from the render tree, then
+ * applies them to a Screen buffer in `get()`. The Screen is what gets
+ * diffed against the previous frame to produce terminal updates.
+ */
+
+type Options = {
+  width: number
+  height: number
+  stylePool: StylePool
+  /**
+   * Screen to render into. Will be reset before use.
+   * For double-buffering, pass a reusable screen. Otherwise create a new one.
+   */
+  screen: Screen
+}
+
+export type Operation =
+  | WriteOperation
+  | ClipOperation
+  | UnclipOperation
+  | BlitOperation
+  | ClearOperation
+  | NoSelectOperation
+  | ShiftOperation
+
+type WriteOperation = {
+  type: 'write'
+  x: number
+  y: number
+  text: string
+  /**
+   * Per-line soft-wrap flags, parallel to text.split('\n'). softWrap[i]=true
+   * means line i is a continuation of line i-1 (the `\n` before it was
+   * inserted by word-wrap, not in the source). Index 0 is always false.
+   * Undefined means the producer didn't track wrapping (e.g. fills,
+   * raw-ansi) — the screen's per-row bitmap is left untouched.
+   */
+  softWrap?: boolean[]
+}
+
+type ClipOperation = {
+  type: 'clip'
+  clip: Clip
+}
+
+export type Clip = {
+  x1: number | undefined
+  x2: number | undefined
+  y1: number | undefined
+  y2: number | undefined
+}
+
+/**
+ * Intersect two clips. `undefined` on an axis means unbounded; the other
+ * clip's bound wins. If both are bounded, take the tighter constraint
+ * (max of mins, min of maxes). If the resulting region is empty
+ * (x1 >= x2 or y1 >= y2), writes clipped by it will be dropped.
+ */
+function intersectClip(parent: Clip | undefined, child: Clip): Clip {
+  if (!parent) {
+    return child
+  }
+
+  return {
+    x1: maxDefined(parent.x1, child.x1),
+    x2: minDefined(parent.x2, child.x2),
+    y1: maxDefined(parent.y1, child.y1),
+    y2: minDefined(parent.y2, child.y2)
+  }
+}
+
+function maxDefined(a: number | undefined, b: number | undefined): number | undefined {
+  if (a === undefined) {
+    return b
+  }
+
+  if (b === undefined) {
+    return a
+  }
+
+  return Math.max(a, b)
+}
+
+function minDefined(a: number | undefined, b: number | undefined): number | undefined {
+  if (a === undefined) {
+    return b
+  }
+
+  if (b === undefined) {
+    return a
+  }
+
+  return Math.min(a, b)
+}
+
+type UnclipOperation = {
+  type: 'unclip'
+}
+
+type BlitOperation = {
+  type: 'blit'
+  src: Screen
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+type ShiftOperation = {
+  type: 'shift'
+  top: number
+  bottom: number
+  n: number
+}
+
+type ClearOperation = {
+  type: 'clear'
+  region: Rectangle
+  /**
+   * Set when the clear is for an absolute-positioned node's old bounds.
+   * Absolute nodes overlay normal-flow siblings, so their stale paint is
+   * what an earlier sibling's clean-subtree blit wrongly restores from
+   * prevScreen. Normal-flow siblings' clears don't have this problem —
+   * their old position can't have been painted on top of a sibling.
+   */
+  fromAbsolute?: boolean
+}
+
+type NoSelectOperation = {
+  type: 'noSelect'
+  region: Rectangle
+}
+
+export default class Output {
+  width: number
+  height: number
+  private readonly stylePool: StylePool
+  private screen: Screen
+
+  private readonly operations: Operation[] = []
+
+  private charCache: Map<string, ClusteredChar[]> = new Map()
+
+  constructor(options: Options) {
+    const { width, height, stylePool, screen } = options
+
+    this.width = width
+    this.height = height
+    this.stylePool = stylePool
+    this.screen = screen
+
+    resetScreen(screen, width, height)
+  }
+
+  /**
+   * Reuse this Output for a new frame. Zeroes the screen buffer, clears
+   * the operation list (backing storage is retained), and caps charCache
+   * growth. Preserving charCache across frames is the main win — most
+   * lines don't change between renders, so tokenize + grapheme clustering
+   * becomes a cache hit.
+   */
+  reset(width: number, height: number, screen: Screen): void {
+    this.width = width
+    this.height = height
+    this.screen = screen
+    this.operations.length = 0
+    resetScreen(screen, width, height)
+
+    if (this.charCache.size > 16384) {
+      this.charCache.clear()
+    }
+  }
+
+  /**
+   * Copy cells from a source screen region (blit = block image transfer).
+   */
+  blit(src: Screen, x: number, y: number, width: number, height: number): void {
+    this.operations.push({ type: 'blit', src, x, y, width, height })
+  }
+
+  /**
+   * Shift full-width rows within [top, bottom] by n. n > 0 = up. Mirrors
+   * what DECSTBM + SU/SD does to the terminal. Paired with blit() to reuse
+   * prevScreen content during pure scroll, avoiding full child re-render.
+   */
+  shift(top: number, bottom: number, n: number): void {
+    this.operations.push({ type: 'shift', top, bottom, n })
+  }
+
+  /**
+   * Clear a region by writing empty cells. Used when a node shrinks to
+   * ensure stale content from the previous frame is removed.
+   */
+  clear(region: Rectangle, fromAbsolute?: boolean): void {
+    this.operations.push({ type: 'clear', region, fromAbsolute })
+  }
+
+  /**
+   * Mark a region as non-selectable (excluded from fullscreen text
+   * selection copy + highlight). Used by <NoSelect> to fence off
+   * gutters (line numbers, diff sigils). Applied AFTER blit/write so
+   * the mark wins regardless of what's blitted into the region.
+   */
+  noSelect(region: Rectangle): void {
+    this.operations.push({ type: 'noSelect', region })
+  }
+
+  write(x: number, y: number, text: string, softWrap?: boolean[]): void {
+    if (!text) {
+      return
+    }
+
+    this.operations.push({
+      type: 'write',
+      x,
+      y,
+      text,
+      softWrap
+    })
+  }
+
+  clip(clip: Clip) {
+    this.operations.push({
+      type: 'clip',
+      clip
+    })
+  }
+
+  unclip() {
+    this.operations.push({
+      type: 'unclip'
+    })
+  }
+
+  get(): Screen {
+    const screen = this.screen
+    const screenWidth = this.width
+    const screenHeight = this.height
+
+    // Track blit vs write cell counts for debugging
+    let blitCells = 0
+    let writeCells = 0
+
+    // Pass 1: expand damage to cover clear regions. The buffer is freshly
+    // zeroed by resetScreen, so this pass only marks damage so diff()
+    // checks these regions against the previous frame.
+    //
+    // Also collect clears from absolute-positioned nodes. An absolute
+    // node overlays normal-flow siblings; when it shrinks, its clear is
+    // pushed AFTER those siblings' clean-subtree blits (DOM order). The
+    // blit copies the absolute node's own stale paint from prevScreen,
+    // and since clear is damage-only, the ghost survives diff. Normal-
+    // flow clears don't need this — a normal-flow node's old position
+    // can't have been painted on top of a sibling's current position.
+    const absoluteClears: Rectangle[] = []
+
+    for (const operation of this.operations) {
+      if (operation.type !== 'clear') {
+        continue
+      }
+
+      const { x, y, width, height } = operation.region
+      const startX = Math.max(0, x)
+      const startY = Math.max(0, y)
+      const maxX = Math.min(x + width, screenWidth)
+      const maxY = Math.min(y + height, screenHeight)
+
+      if (startX >= maxX || startY >= maxY) {
+        continue
+      }
+
+      const rect = {
+        x: startX,
+        y: startY,
+        width: maxX - startX,
+        height: maxY - startY
+      }
+
+      screen.damage = screen.damage ? unionRect(screen.damage, rect) : rect
+
+      if (operation.fromAbsolute) {
+        absoluteClears.push(rect)
+      }
+    }
+
+    const clips: Clip[] = []
+
+    for (const operation of this.operations) {
+      switch (operation.type) {
+        case 'clear':
+          // handled in pass 1
+          continue
+
+        case 'clip':
+          // Intersect with the parent clip (if any) so nested
+          // overflow:hidden boxes can't write outside their ancestor's
+          // clip region. Without this, a message with overflow:hidden at
+          // the bottom of a scrollbox pushes its OWN clip (based on its
+          // layout bounds, already translated by -scrollTop) which can
+          // extend below the scrollbox viewport — writes escape into
+          // the sibling bottom section's rows.
+          clips.push(intersectClip(clips.at(-1), operation.clip))
+
+          continue
+
+        case 'unclip':
+          clips.pop()
+
+          continue
+        case 'blit': {
+          // Bulk-copy cells from source screen region using TypedArray.set().
+          // Tracking damage ensures diff() checks blitted cells for stale content
+          // when a parent blits an area that previously contained child content.
+          const { src, x: regionX, y: regionY, width: regionWidth, height: regionHeight } = operation
+
+          // Intersect with active clip — a child's clean-blit passes its full
+          // cached rect, but the parent ScrollBox may have shrunk (pill mount).
+          // Without this, the blit writes past the ScrollBox's new bottom edge
+          // into the pill's row.
+          const clip = clips.at(-1)
+          const startX = Math.max(regionX, clip?.x1 ?? 0)
+          const startY = Math.max(regionY, clip?.y1 ?? 0)
+
+          const maxY = Math.min(regionY + regionHeight, screenHeight, src.height, clip?.y2 ?? Infinity)
+
+          const maxX = Math.min(regionX + regionWidth, screenWidth, src.width, clip?.x2 ?? Infinity)
+
+          if (startX >= maxX || startY >= maxY) {
+            continue
+          }
+
+          // Exclude cells covered by an absolute-positioned node's clear.
+          // Absolute nodes overlay normal-flow siblings, so prevScreen in
+          // that region holds stale overlay paint. If we blit those cells
+          // back, removed/moved overlays ghost as a duplicate.
+          if (absoluteClears.length === 0) {
+            blitRegion(screen, src, startX, startY, maxX, maxY)
+            blitCells += (maxY - startY) * (maxX - startX)
+
+            continue
+          }
+
+          for (let row = startY; row < maxY; row++) {
+            let spans: [number, number][] = [[startX, maxX]]
+
+            for (const r of absoluteClears) {
+              if (row < r.y || row >= r.y + r.height || !spans.length) {
+                break
+              }
+
+              const cs = Math.max(startX, r.x)
+              const ce = Math.min(maxX, r.x + r.width)
+
+              if (cs >= ce) {
+                continue
+              }
+
+              const next: [number, number][] = []
+
+              for (const [sx, ex] of spans) {
+                if (ce <= sx || cs >= ex) {
+                  next.push([sx, ex])
+
+                  continue
+                }
+
+                if (sx < cs) {
+                  next.push([sx, cs])
+                }
+
+                if (ce < ex) {
+                  next.push([ce, ex])
+                }
+              }
+
+              spans = next
+            }
+
+            for (const [sx, ex] of spans) {
+              blitRegion(screen, src, sx, row, ex, row + 1)
+              blitCells += ex - sx
+            }
+          }
+
+          continue
+        }
+
+        case 'shift': {
+          shiftRows(screen, operation.top, operation.bottom, operation.n)
+
+          continue
+        }
+
+        case 'write': {
+          const { text, softWrap } = operation
+          let { x, y } = operation
+          let lines = text.split('\n')
+          let swFrom = 0
+          let prevContentEnd = 0
+
+          const clip = clips.at(-1)
+
+          if (clip) {
+            const clipHorizontally = typeof clip?.x1 === 'number' && typeof clip?.x2 === 'number'
+
+            const clipVertically = typeof clip?.y1 === 'number' && typeof clip?.y2 === 'number'
+
+            // If text is positioned outside of clipping area altogether,
+            // skip to the next operation to avoid unnecessary calculations
+            if (clipHorizontally) {
+              const width = widestLine(text)
+
+              if (x + width <= clip.x1! || x >= clip.x2!) {
+                continue
+              }
+            }
+
+            if (clipVertically) {
+              const height = lines.length
+
+              if (y + height <= clip.y1! || y >= clip.y2!) {
+                continue
+              }
+            }
+
+            if (clipHorizontally) {
+              lines = lines.map(line => {
+                const width = stringWidth(line)
+                const startsBefore = x < clip.x1!
+                const endsAfter = x + width > clip.x2!
+
+                // Fast path: line fits entirely within the clip box — skip
+                // tokenize/slice. Common case for transcript text where
+                // containers are wider than rendered content. CPU profile
+                // (Apr 2026): sliceAnsi at 18% total during scroll, mostly
+                // no-op (line, 0, width) slices.
+                if (!startsBefore && !endsAfter) {
+                  return line
+                }
+
+                const from = startsBefore ? clip.x1! - x : 0
+                const to = endsAfter ? clip.x2! - x : width
+                let sliced = sliceAnsi(line, from, to)
+
+                // Wide chars (CJK, emoji) occupy 2 cells. When `to` lands
+                // on the first cell of a wide char, sliceAnsi includes the
+                // entire glyph and the result overflows clip.x2 by one cell,
+                // writing a SpacerTail into the adjacent sibling. Re-slice
+                // one cell earlier; wide chars are exactly 2 cells, so a
+                // single retry always fits.
+                if (stringWidth(sliced) > to - from) {
+                  sliced = sliceAnsi(line, from, to - 1)
+                }
+
+                return sliced
+              })
+
+              if (x < clip.x1!) {
+                x = clip.x1!
+              }
+            }
+
+            if (clipVertically) {
+              const from = y < clip.y1! ? clip.y1! - y : 0
+              const height = lines.length
+              const to = y + height > clip.y2! ? clip.y2! - y : height
+
+              // If the first visible line is a soft-wrap continuation, we
+              // need the clipped previous line's content end so
+              // screen.softWrap[lineY] correctly records the join point
+              // even though that line's cells were never written.
+              if (softWrap && from > 0 && softWrap[from] === true) {
+                prevContentEnd = x + stringWidth(lines[from - 1]!)
+              }
+
+              lines = lines.slice(from, to)
+              swFrom = from
+
+              if (y < clip.y1!) {
+                y = clip.y1!
+              }
+            }
+          }
+
+          const swBits = screen.softWrap
+          let offsetY = 0
+
+          for (const line of lines) {
+            const lineY = y + offsetY
+
+            // Line can be outside screen if `text` is taller than screen height
+            if (lineY >= screenHeight) {
+              break
+            }
+
+            const contentEnd = writeLineToScreen(screen, line, x, lineY, screenWidth, this.stylePool, this.charCache)
+
+            writeCells += contentEnd - x
+
+            // See Screen.softWrap docstring for the encoding. contentEnd
+            // from writeLineToScreen is tab-expansion-aware, unlike
+            // x+stringWidth(line) which treats tabs as width 0.
+            if (softWrap) {
+              const isSW = softWrap[swFrom + offsetY] === true
+              swBits[lineY] = isSW ? prevContentEnd : 0
+              prevContentEnd = contentEnd
+            }
+
+            offsetY++
+          }
+
+          continue
+        }
+      }
+    }
+
+    // noSelect ops go LAST so they win over blits (which copy noSelect
+    // from prevScreen) and writes (which don't touch noSelect). This way
+    // a <NoSelect> box correctly fences its region even when the parent
+    // blits, and moving a <NoSelect> between frames correctly clears the
+    // old region (resetScreen already zeroed the bitmap).
+    for (const operation of this.operations) {
+      if (operation.type === 'noSelect') {
+        const { x, y, width, height } = operation.region
+        markNoSelectRegion(screen, x, y, width, height)
+      }
+    }
+
+    // Log blit/write ratio for debugging - high write count suggests blitting isn't working
+    const totalCells = blitCells + writeCells
+
+    if (totalCells > 1000 && writeCells > blitCells) {
+      logForDebugging(
+        `High write ratio: blit=${blitCells}, write=${writeCells} (${((writeCells / totalCells) * 100).toFixed(1)}% writes), screen=${screenHeight}x${screenWidth}`
+      )
+    }
+
+    return screen
+  }
+}
+
+function stylesEqual(a: AnsiCode[], b: AnsiCode[]): boolean {
+  if (a === b) {
+    return true
+  } // Reference equality fast path
+
+  const len = a.length
+
+  if (len !== b.length) {
+    return false
+  }
+
+  if (len === 0) {
+    return true
+  } // Both empty
+
+  for (let i = 0; i < len; i++) {
+    if (a[i]!.code !== b[i]!.code) {
+      return false
+    }
+  }
+
+  return true
+}
+
+/**
+ * Convert a string with ANSI codes into styled characters with proper grapheme
+ * clustering. Fixes ansi-tokenize splitting grapheme clusters (like family
+ * emojis) into individual code points.
+ *
+ * Also precomputes styleId + hyperlink per style run (not per char) — an
+ * 80-char line with 3 style runs does 3 intern calls instead of 80.
+ */
+function styledCharsWithGraphemeClustering(chars: StyledChar[], stylePool: StylePool): ClusteredChar[] {
+  const charCount = chars.length
+
+  if (charCount === 0) {
+    return []
+  }
+
+  const result: ClusteredChar[] = []
+  const bufferChars: string[] = []
+  let bufferStyles: AnsiCode[] = chars[0]!.styles
+
+  for (let i = 0; i < charCount; i++) {
+    const char = chars[i]!
+    const styles = char.styles
+
+    // Different styles means we need to flush and start new buffer
+    if (bufferChars.length > 0 && !stylesEqual(styles, bufferStyles)) {
+      flushBuffer(bufferChars.join(''), bufferStyles, stylePool, result)
+      bufferChars.length = 0
+    }
+
+    bufferChars.push(char.value)
+    bufferStyles = styles
+  }
+
+  // Final flush
+  if (bufferChars.length > 0) {
+    flushBuffer(bufferChars.join(''), bufferStyles, stylePool, result)
+  }
+
+  return result
+}
+
+function flushBuffer(buffer: string, styles: AnsiCode[], stylePool: StylePool, out: ClusteredChar[]): void {
+  // Compute styleId + hyperlink ONCE for the whole style run.
+  // Every grapheme in this buffer shares the same styles.
+  //
+  // Extract and track hyperlinks separately, filter from styles.
+  // Always check for OSC 8 codes to filter, not just when a URL is
+  // extracted. The tokenizer treats OSC 8 close codes (empty URL) as
+  // active styles, so they must be filtered even when no hyperlink
+  // URL is present.
+  const hyperlink = extractHyperlinkFromStyles(styles) ?? undefined
+
+  const hasOsc8Styles =
+    hyperlink !== undefined || styles.some(s => s.code.length >= OSC8_PREFIX.length && s.code.startsWith(OSC8_PREFIX))
+
+  const filteredStyles = hasOsc8Styles ? filterOutHyperlinkStyles(styles) : styles
+
+  const styleId = stylePool.intern(filteredStyles)
+
+  for (const { segment: grapheme } of getGraphemeSegmenter().segment(buffer)) {
+    out.push({
+      value: grapheme,
+      width: stringWidth(grapheme),
+      styleId,
+      hyperlink
+    })
+  }
+}
+
+/**
+ * Write a single line's characters into the screen buffer.
+ * Extracted from Output.get() so JSC can optimize this tight,
+ * monomorphic loop independently — better register allocation,
+ * setCellAt inlining, and type feedback than when buried inside
+ * a 300-line dispatch function.
+ *
+ * Returns the end column (x + visual width, including tab expansion) so
+ * the caller can record it in screen.softWrap without re-walking the
+ * line via stringWidth(). Caller computes the debug cell-count as end-x.
+ */
+function writeLineToScreen(
+  screen: Screen,
+  line: string,
+  x: number,
+  y: number,
+  screenWidth: number,
+  stylePool: StylePool,
+  charCache: Map<string, ClusteredChar[]>
+): number {
+  let characters = charCache.get(line)
+
+  if (!characters) {
+    characters = reorderBidi(styledCharsWithGraphemeClustering(styledCharsFromTokens(tokenize(line)), stylePool))
+    charCache.set(line, characters)
+  }
+
+  let offsetX = x
+
+  for (let charIdx = 0; charIdx < characters.length; charIdx++) {
+    const character = characters[charIdx]!
+    const codePoint = character.value.codePointAt(0)
+
+    // Handle C0 control characters (0x00-0x1F) that cause cursor movement
+    // mismatches. stringWidth treats these as width 0, but terminals may
+    // move the cursor differently.
+    if (codePoint !== undefined && codePoint <= 0x1f) {
+      // Tab (0x09): expand to spaces to reach next tab stop
+      if (codePoint === 0x09) {
+        const tabWidth = 8
+        const spacesToNextStop = tabWidth - (offsetX % tabWidth)
+
+        for (let i = 0; i < spacesToNextStop && offsetX < screenWidth; i++) {
+          setCellAt(screen, offsetX, y, {
+            char: ' ',
+            styleId: stylePool.none,
+            width: CellWidth.Narrow,
+            hyperlink: undefined
+          })
+          offsetX++
+        }
+      }
+      // ESC (0x1B): skip incomplete escape sequences that ansi-tokenize
+      // didn't recognize. ansi-tokenize only parses SGR sequences (ESC[...m)
+      // and OSC 8 hyperlinks (ESC]8;;url BEL). Other sequences like cursor
+      // movement, screen clearing, or terminal title become individual char
+      // tokens that we need to skip here.
+      else if (codePoint === 0x1b) {
+        const nextChar = characters[charIdx + 1]?.value
+        const nextCode = nextChar?.codePointAt(0)
+
+        if (nextChar === '(' || nextChar === ')' || nextChar === '*' || nextChar === '+') {
+          // Charset selection: ESC ( X, ESC ) X, etc.
+          // Skip the intermediate char and the charset designator
+          charIdx += 2
+        } else if (nextChar === '[') {
+          // CSI sequence: ESC [ ... final-byte
+          // Final byte is in range 0x40-0x7E (@, A-Z, [\]^_`, a-z, {|}~)
+          // Examples: ESC[2J (clear), ESC[?25l (cursor hide), ESC[H (home)
+          charIdx++ // skip the [
+
+          while (charIdx < characters.length - 1) {
+            charIdx++
+            const c = characters[charIdx]?.value.codePointAt(0)
+
+            // Final byte terminates the sequence
+            if (c !== undefined && c >= 0x40 && c <= 0x7e) {
+              break
+            }
+          }
+        } else if (nextChar === ']' || nextChar === 'P' || nextChar === '_' || nextChar === '^' || nextChar === 'X') {
+          // String-based sequences terminated by BEL (0x07) or ST (ESC \):
+          // - OSC: ESC ] ... (Operating System Command)
+          // - DCS: ESC P ... (Device Control String)
+          // - APC: ESC _ ... (Application Program Command)
+          // - PM:  ESC ^ ... (Privacy Message)
+          // - SOS: ESC X ... (Start of String)
+          charIdx++ // skip the introducer char
+
+          while (charIdx < characters.length - 1) {
+            charIdx++
+            const c = characters[charIdx]?.value
+
+            // BEL (0x07) terminates the sequence
+            if (c === '\x07') {
+              break
+            }
+
+            // ST (String Terminator) is ESC \
+            // When we see ESC, check if next char is backslash
+            if (c === '\x1b') {
+              const nextC = characters[charIdx + 1]?.value
+
+              if (nextC === '\\') {
+                charIdx++ // skip the backslash too
+
+                break
+              }
+            }
+          }
+        } else if (nextCode !== undefined && nextCode >= 0x30 && nextCode <= 0x7e) {
+          // Single-character escape sequences: ESC followed by 0x30-0x7E
+          // (excluding the multi-char introducers already handled above)
+          // - Fp range (0x30-0x3F): ESC 7 (save cursor), ESC 8 (restore)
+          // - Fe range (0x40-0x5F): ESC D (index), ESC M (reverse index)
+          // - Fs range (0x60-0x7E): ESC c (reset)
+          charIdx++ // skip the command char
+        }
+      }
+
+      // Carriage return (0x0D): would move cursor to column 0, skip it
+      // Backspace (0x08): would move cursor left, skip it
+      // Bell (0x07), vertical tab (0x0B), form feed (0x0C): skip
+      // All other control chars (0x00-0x06, 0x0E-0x1F): skip
+      // Note: newline (0x0A) is already handled by line splitting
+      continue
+    }
+
+    // Zero-width characters (combining marks, ZWNJ, ZWS, etc.)
+    // don't occupy terminal cells — storing them as Narrow cells
+    // desyncs the virtual cursor from the real terminal cursor.
+    // Width was computed once during clustering (cached via charCache).
+    const charWidth = character.width
+
+    if (charWidth === 0) {
+      continue
+    }
+
+    const isWideCharacter = charWidth >= 2
+
+    // Wide char at last column can't fit — terminal would wrap it to
+    // the next line, desyncing our cursor model. Place a SpacerHead
+    // to mark the blank column, matching terminal behavior.
+    if (isWideCharacter && offsetX + 2 > screenWidth) {
+      setCellAt(screen, offsetX, y, {
+        char: ' ',
+        styleId: stylePool.none,
+        width: CellWidth.SpacerHead,
+        hyperlink: undefined
+      })
+      offsetX++
+
+      continue
+    }
+
+    // styleId + hyperlink were precomputed during clustering (once per
+    // style run, cached via charCache). Hot loop is now just property
+    // reads — no intern, no extract, no filter per frame.
+    setCellAt(screen, offsetX, y, {
+      char: character.value,
+      styleId: character.styleId,
+      width: isWideCharacter ? CellWidth.Wide : CellWidth.Narrow,
+      hyperlink: character.hyperlink
+    })
+    offsetX += isWideCharacter ? 2 : 1
+  }
+
+  return offsetX
+}

ui-tui/packages/hermes-ink/src/ink/parse-keypress.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest'
+
+import { INITIAL_STATE, parseMultipleKeypresses } from './parse-keypress.js'
+import { PASTE_END, PASTE_START } from './termio/csi.js'
+
+describe('parseMultipleKeypresses bracketed paste recovery', () => {
+  it('emits empty bracketed pastes when the terminal sends both markers', () => {
+    const [keys, state] = parseMultipleKeypresses(INITIAL_STATE, PASTE_START + PASTE_END)
+
+    expect(keys).toHaveLength(1)
+    expect(keys[0]).toMatchObject({ isPasted: true, raw: '' })
+    expect(state.mode).toBe('NORMAL')
+  })
+
+  it('flushes unterminated paste content back to normal input mode', () => {
+    const [pendingKeys, pendingState] = parseMultipleKeypresses(INITIAL_STATE, PASTE_START + 'hello')
+
+    expect(pendingKeys).toEqual([])
+    expect(pendingState.mode).toBe('IN_PASTE')
+
+    const [keys, state] = parseMultipleKeypresses(pendingState, null)
+
+    expect(keys).toHaveLength(1)
+    expect(keys[0]).toMatchObject({ isPasted: true, raw: 'hello' })
+    expect(state.mode).toBe('NORMAL')
+    expect(state.pasteBuffer).toBe('')
+  })
+
+  it('resets an empty unterminated paste start instead of staying stuck', () => {
+    const [pendingKeys, pendingState] = parseMultipleKeypresses(INITIAL_STATE, PASTE_START)
+
+    expect(pendingKeys).toEqual([])
+    expect(pendingState.mode).toBe('IN_PASTE')
+
+    const [keys, state] = parseMultipleKeypresses(pendingState, null)
+
+    expect(keys).toEqual([])
+    expect(state.mode).toBe('NORMAL')
+    expect(state.pasteBuffer).toBe('')
+  })
+})
+
+describe('mouse wheel modifier decoding', () => {
+  // SGR mouse format: ESC [ < button ; col ; row M
+  // Wheel up = 64 (0x40), wheel down = 65 (0x41).
+  // Modifier bits: shift = 0x04, meta = 0x08, ctrl = 0x10.
+  const sgrWheel = (button: number) => `\x1b[<${button};10;10M`
+
+  it('plain wheel up has no modifiers', () => {
+    const [[key]] = parseMultipleKeypresses(INITIAL_STATE, sgrWheel(0x40))
+
+    expect(key).toMatchObject({ name: 'wheelup', ctrl: false, meta: false, shift: false })
+  })
+
+  it('plain wheel down has no modifiers', () => {
+    const [[key]] = parseMultipleKeypresses(INITIAL_STATE, sgrWheel(0x41))
+
+    expect(key).toMatchObject({ name: 'wheeldown', ctrl: false, meta: false, shift: false })
+  })
+
+  it('decodes meta (Alt/Option) on wheel up', () => {
+    const [[key]] = parseMultipleKeypresses(INITIAL_STATE, sgrWheel(0x40 | 0x08))
+
+    expect(key).toMatchObject({ name: 'wheelup', ctrl: false, meta: true, shift: false })
+  })
+
+  it('decodes meta (Alt/Option) on wheel down', () => {
+    const [[key]] = parseMultipleKeypresses(INITIAL_STATE, sgrWheel(0x41 | 0x08))
+
+    expect(key).toMatchObject({ name: 'wheeldown', ctrl: false, meta: true, shift: false })
+  })
+
+  it('decodes ctrl on wheel events', () => {
+    const [[key]] = parseMultipleKeypresses(INITIAL_STATE, sgrWheel(0x40 | 0x10))
+
+    expect(key).toMatchObject({ name: 'wheelup', ctrl: true, meta: false, shift: false })
+  })
+
+  it('decodes shift on wheel events', () => {
+    const [[key]] = parseMultipleKeypresses(INITIAL_STATE, sgrWheel(0x41 | 0x04))
+
+    expect(key).toMatchObject({ name: 'wheeldown', ctrl: false, meta: false, shift: true })
+  })
+
+  it('decodes combined modifiers', () => {
+    const [[key]] = parseMultipleKeypresses(INITIAL_STATE, sgrWheel(0x40 | 0x08 | 0x10))
+
+    expect(key).toMatchObject({ name: 'wheelup', ctrl: true, meta: true, shift: false })
+  })
+
+  it('decodes meta on legacy X10 wheel encoding', () => {
+    // X10: ESC [ M Cb Cx Cy where each byte is value+32.
+    const x10 = `\x1b[M${String.fromCharCode(0x40 + 0x08 + 32)}${String.fromCharCode(10 + 32)}${String.fromCharCode(10 + 32)}`
+    const [[key]] = parseMultipleKeypresses(INITIAL_STATE, x10)
+
+    expect(key).toMatchObject({ name: 'wheelup', meta: true })
+  })
+})
+
+describe('flush-boundary SGR mouse reassembly', () => {
+  it('reassembles a report split by a mid-sequence watchdog flush into one mouse event', () => {
+    // chunk 1: heavy render stalls the loop, only the prefix is read
+    let [keys, state] = parseMultipleKeypresses(INITIAL_STATE, '\x1b[<0;35;')
+    expect(keys).toEqual([])
+
+    // App's 50ms watchdog flushes (input=null) — must NOT emit the partial
+    ;[keys, state] = parseMultipleKeypresses(state, null)
+    expect(keys).toEqual([])
+
+    // continuation arrives; the whole report reassembles, nothing leaks
+    ;[keys, state] = parseMultipleKeypresses(state, '46M')
+    expect(keys).toEqual([expect.objectContaining({ kind: 'mouse', button: 0, col: 35, row: 46, action: 'press' })])
+  })
+
+  it('drops a truncated mouse prefix after a second flush instead of leaking it', () => {
+    let [keys, state] = parseMultipleKeypresses(INITIAL_STATE, '\x1b[<0;35;')
+
+    ;[keys, state] = parseMultipleKeypresses(state, null) // first flush keeps it
+    ;[keys, state] = parseMultipleKeypresses(state, null) // second flush drops it
+
+    expect(keys).toEqual([])
+    expect(state.incomplete).toBe('')
+  })
+
+  it('re-synthesizes an orphaned X10 wheel tail (legacy mouse) into a scroll key', () => {
+    // X10 wheel-up = ESC[M + (0x40+32) + col + row. If the ESC was flushed as a
+    // lone Escape and the `[M…` payload arrives as text, resynthesize it.
+    const tail = '[M' + String.fromCharCode(0x60) + '!!'
+    const [[key]] = parseMultipleKeypresses(INITIAL_STATE, tail)
+
+    expect(key).toMatchObject({ name: 'wheelup' })
+  })
+})

ui-tui/packages/hermes-ink/src/ink/parse-keypress.ts

@@ -0,0 +1,848 @@
+/**
+ * Keyboard input parser - converts terminal input to key events
+ *
+ * Uses the termio tokenizer for escape sequence boundary detection,
+ * then interprets sequences as keypresses.
+ */
+import { Buffer } from 'buffer'
+
+import { PASTE_END, PASTE_START } from './termio/csi.js'
+import { createTokenizer, type Tokenizer } from './termio/tokenize.js'
+
+// eslint-disable-next-line no-control-regex
+const META_KEY_CODE_RE = /^(?:\x1b)([a-zA-Z0-9])$/
+
+const FN_KEY_RE =
+  // eslint-disable-next-line no-control-regex
+  /^(?:\x1b+)(O|N|\[|\[\[)(?:(\d+)(?:;(\d+))?([~^$])|(?:1;)?(\d+)?([a-zA-Z]))/
+
+// CSI u (kitty keyboard protocol): ESC [ codepoint [; modifier] u
+// Example: ESC[13;2u = Shift+Enter, ESC[27u = Escape (no modifiers)
+// Modifier is optional - when absent, defaults to 1 (no modifiers)
+// eslint-disable-next-line no-control-regex
+const CSI_U_RE = /^\x1b\[(\d+)(?:;(\d+))?u/
+
+// xterm modifyOtherKeys: ESC [ 27 ; modifier ; keycode ~
+// Example: ESC[27;2;13~ = Shift+Enter. Emitted by Ghostty/tmux/xterm when
+// modifyOtherKeys=2 is active or via user keybinds, typically over SSH where
+// TERM sniffing misses Ghostty and we never push Kitty keyboard mode.
+// Note param order is reversed vs CSI u (modifier first, keycode second).
+// eslint-disable-next-line no-control-regex
+const MODIFY_OTHER_KEYS_RE = /^\x1b\[27;(\d+);(\d+)~/
+
+// -- Terminal response patterns (inbound sequences from the terminal itself) --
+// DECRPM: CSI ? Ps ; Pm $ y  — response to DECRQM (request mode)
+// eslint-disable-next-line no-control-regex
+const DECRPM_RE = /^\x1b\[\?(\d+);(\d+)\$y$/
+// DA1: CSI ? Ps ; ... c  — primary device attributes response
+// eslint-disable-next-line no-control-regex
+const DA1_RE = /^\x1b\[\?([\d;]*)c$/
+// DA2: CSI > Ps ; ... c  — secondary device attributes response
+// eslint-disable-next-line no-control-regex
+const DA2_RE = /^\x1b\[>([\d;]*)c$/
+// Kitty keyboard flags: CSI ? flags u  — response to CSI ? u query
+// (private ? marker distinguishes from CSI u key events)
+// eslint-disable-next-line no-control-regex
+const KITTY_FLAGS_RE = /^\x1b\[\?(\d+)u$/
+// DECXCPR cursor position: CSI ? row ; col R
+// The ? marker disambiguates from modified F3 keys (Shift+F3 = CSI 1;2 R,
+// Ctrl+F3 = CSI 1;5 R, etc.) — plain CSI row;col R is genuinely ambiguous.
+// eslint-disable-next-line no-control-regex
+const CURSOR_POSITION_RE = /^\x1b\[\?(\d+);(\d+)R$/
+// OSC response: OSC code ; data (BEL|ST)
+// eslint-disable-next-line no-control-regex
+const OSC_RESPONSE_RE = /^\x1b\](\d+);(.*?)(?:\x07|\x1b\\)$/s
+// XTVERSION: DCS > | name ST  — terminal name/version string (answer to CSI > 0 q).
+// xterm.js replies "xterm.js(X.Y.Z)"; Ghostty, kitty, iTerm2, etc. reply with
+// their own name. Unlike TERM_PROGRAM, this survives SSH since the query/reply
+// goes through the pty, not the environment.
+// eslint-disable-next-line no-control-regex
+const XTVERSION_RE = /^\x1bP>\|(.*?)(?:\x07|\x1b\\)$/s
+// SGR mouse event: CSI < button ; col ; row M (press) or m (release)
+// Button codes: 64=wheel-up, 65=wheel-down (0x40 | wheel-bit).
+// Button 32=left-drag (0x20 | motion-bit). Plain 0/1/2 = left/mid/right click.
+// eslint-disable-next-line no-control-regex
+const SGR_MOUSE_RE = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/
+
+function createPasteKey(content: string): ParsedKey {
+  return {
+    kind: 'key',
+    name: '',
+    fn: false,
+    ctrl: false,
+    meta: false,
+    shift: false,
+    option: false,
+    super: false,
+    sequence: content,
+    raw: content,
+    isPasted: true
+  }
+}
+
+/** DECRPM status values (response to DECRQM) */
+export const DECRPM_STATUS = {
+  NOT_RECOGNIZED: 0,
+  SET: 1,
+  RESET: 2,
+  PERMANENTLY_SET: 3,
+  PERMANENTLY_RESET: 4
+} as const
+
+/**
+ * A response sequence received from the terminal (not a keypress).
+ * Emitted in answer to queries like DECRQM, DA1, OSC 11, etc.
+ */
+export type TerminalResponse =
+  /** DECRPM: answer to DECRQM (request DEC private mode status) */
+  | { type: 'decrpm'; mode: number; status: number }
+  /** DA1: primary device attributes (used as a universal sentinel) */
+  | { type: 'da1'; params: number[] }
+  /** DA2: secondary device attributes (terminal version info) */
+  | { type: 'da2'; params: number[] }
+  /** Kitty keyboard protocol: current flags (answer to CSI ? u) */
+  | { type: 'kittyKeyboard'; flags: number }
+  /** DSR: cursor position report (answer to CSI 6 n) */
+  | { type: 'cursorPosition'; row: number; col: number }
+  /** OSC response: generic operating-system-command reply (e.g. OSC 11 bg color) */
+  | { type: 'osc'; code: number; data: string }
+  /** XTVERSION: terminal name/version string (answer to CSI > 0 q).
+   *  Example values: "xterm.js(5.5.0)", "ghostty 1.2.0", "iTerm2 3.6". */
+  | { type: 'xtversion'; name: string }
+
+/**
+ * Try to recognize a sequence token as a terminal response.
+ * Returns null if the sequence is not a known response pattern
+ * (i.e. it should be treated as a keypress).
+ *
+ * These patterns are syntactically distinguishable from keyboard input —
+ * no physical key produces CSI ? ... c or CSI ? ... $ y, so they can be
+ * safely parsed out of the input stream at any time.
+ */
+function parseTerminalResponse(s: string): TerminalResponse | null {
+  // CSI-prefixed responses
+  if (s.startsWith('\x1b[')) {
+    let m: RegExpExecArray | null
+
+    if ((m = DECRPM_RE.exec(s))) {
+      return {
+        type: 'decrpm',
+        mode: parseInt(m[1]!, 10),
+        status: parseInt(m[2]!, 10)
+      }
+    }
+
+    if ((m = DA1_RE.exec(s))) {
+      return { type: 'da1', params: splitNumericParams(m[1]!) }
+    }
+
+    if ((m = DA2_RE.exec(s))) {
+      return { type: 'da2', params: splitNumericParams(m[1]!) }
+    }
+
+    if ((m = KITTY_FLAGS_RE.exec(s))) {
+      return { type: 'kittyKeyboard', flags: parseInt(m[1]!, 10) }
+    }
+
+    if ((m = CURSOR_POSITION_RE.exec(s))) {
+      return {
+        type: 'cursorPosition',
+        row: parseInt(m[1]!, 10),
+        col: parseInt(m[2]!, 10)
+      }
+    }
+
+    return null
+  }
+
+  // OSC responses (e.g. OSC 11 ; rgb:... for bg color query)
+  if (s.startsWith('\x1b]')) {
+    const m = OSC_RESPONSE_RE.exec(s)
+
+    if (m) {
+      return { type: 'osc', code: parseInt(m[1]!, 10), data: m[2]! }
+    }
+  }
+
+  // DCS responses (e.g. XTVERSION: DCS > | name ST)
+  if (s.startsWith('\x1bP')) {
+    const m = XTVERSION_RE.exec(s)
+
+    if (m) {
+      return { type: 'xtversion', name: m[1]! }
+    }
+  }
+
+  return null
+}
+
+function splitNumericParams(params: string): number[] {
+  if (!params) {
+    return []
+  }
+
+  return params.split(';').map(p => parseInt(p, 10))
+}
+
+export type KeyParseState = {
+  mode: 'NORMAL' | 'IN_PASTE'
+  incomplete: string
+  pasteBuffer: string
+  // Internal tokenizer instance
+  _tokenizer?: Tokenizer
+}
+
+export const INITIAL_STATE: KeyParseState = {
+  mode: 'NORMAL',
+  incomplete: '',
+  pasteBuffer: ''
+}
+
+function inputToString(input: Buffer | string): string {
+  if (Buffer.isBuffer(input)) {
+    if (input[0]! > 127 && input[1] === undefined) {
+      ;(input[0] as unknown as number) -= 128
+
+      return '\x1b' + String(input)
+    } else {
+      return String(input)
+    }
+  } else if (input !== undefined && typeof input !== 'string') {
+    return String(input)
+  } else if (!input) {
+    return ''
+  } else {
+    return input
+  }
+}
+
+export function parseMultipleKeypresses(
+  prevState: KeyParseState,
+  input: Buffer | string | null = ''
+): [ParsedInput[], KeyParseState] {
+  const isFlush = input === null
+  const inputString = isFlush ? '' : inputToString(input)
+
+  // Get or create tokenizer
+  const tokenizer = prevState._tokenizer ?? createTokenizer({ x10Mouse: true })
+
+  // Tokenize the input
+  const tokens = isFlush ? tokenizer.flush() : tokenizer.feed(inputString)
+
+  // Convert tokens to parsed keys, handling paste mode
+  const keys: ParsedInput[] = []
+  let inPaste = prevState.mode === 'IN_PASTE'
+  let pasteBuffer = prevState.pasteBuffer
+
+  for (const token of tokens) {
+    if (token.type === 'sequence') {
+      if (token.value === PASTE_START) {
+        inPaste = true
+        pasteBuffer = ''
+      } else if (token.value === PASTE_END) {
+        // Always emit a paste key, even for empty pastes. This allows
+        // downstream handlers to detect empty pastes (e.g., for clipboard
+        // image handling on macOS). The paste content may be empty string.
+        keys.push(createPasteKey(pasteBuffer))
+        inPaste = false
+        pasteBuffer = ''
+      } else if (inPaste) {
+        // Sequences inside paste are treated as literal text
+        pasteBuffer += token.value
+      } else {
+        const response = parseTerminalResponse(token.value)
+
+        if (response) {
+          keys.push({ kind: 'response', sequence: token.value, response })
+        } else {
+          const mouse = parseMouseEvent(token.value)
+
+          if (mouse) {
+            keys.push(mouse)
+          } else {
+            keys.push(parseKeypress(token.value))
+          }
+        }
+      }
+    } else if (token.type === 'text') {
+      if (inPaste) {
+        pasteBuffer += token.value
+      } else if (/^\[M[\x60-\x7f][\x20-\uffff]{2}$/.test(token.value)) {
+        // Orphaned X10 wheel tail (legacy 1000/1002 terminals, fullscreen
+        // only). If the buffered ESC was flushed as a lone Escape and the X10
+        // payload (`[M` + 3 bytes) arrived as the next text token, re-synthesize
+        // with ESC so the scroll event still fires instead of leaking. SGR mouse
+        // reports no longer reach this branch — the tokenizer keeps an
+        // incomplete CSI buffered across a flush and reassembles it (see
+        // termio/tokenize.ts), so the old fragment/burst recovery is gone.
+        const resynthesized = '\x1b' + token.value
+        keys.push(parseKeypress(resynthesized))
+      } else {
+        keys.push(parseKeypress(token.value))
+      }
+    }
+  }
+
+  // If a terminal drops the paste-end marker, the App watchdog flushes the
+  // partial paste and returns to normal input instead of swallowing all future
+  // keystrokes as paste content.
+  if (isFlush && inPaste) {
+    if (pasteBuffer) {
+      keys.push(createPasteKey(pasteBuffer))
+    }
+
+    inPaste = false
+    pasteBuffer = ''
+  }
+
+  // Build new state
+  const newState: KeyParseState = {
+    mode: inPaste ? 'IN_PASTE' : 'NORMAL',
+    incomplete: tokenizer.buffer(),
+    pasteBuffer,
+    _tokenizer: tokenizer
+  }
+
+  return [keys, newState]
+}
+
+const keyName: Record<string, string> = {
+  /* xterm/gnome ESC O letter */
+  OP: 'f1',
+  OQ: 'f2',
+  OR: 'f3',
+  OS: 'f4',
+  /* Application keypad mode (numpad digits 0-9) */
+  Op: '0',
+  Oq: '1',
+  Or: '2',
+  Os: '3',
+  Ot: '4',
+  Ou: '5',
+  Ov: '6',
+  Ow: '7',
+  Ox: '8',
+  Oy: '9',
+  /* Application keypad mode (numpad operators) */
+  Oj: '*',
+  Ok: '+',
+  Ol: ',',
+  Om: '-',
+  On: '.',
+  Oo: '/',
+  OM: 'return',
+  /* xterm/rxvt ESC [ number ~ */
+  '[11~': 'f1',
+  '[12~': 'f2',
+  '[13~': 'f3',
+  '[14~': 'f4',
+  /* from Cygwin and used in libuv */
+  '[[A': 'f1',
+  '[[B': 'f2',
+  '[[C': 'f3',
+  '[[D': 'f4',
+  '[[E': 'f5',
+  /* common */
+  '[15~': 'f5',
+  '[17~': 'f6',
+  '[18~': 'f7',
+  '[19~': 'f8',
+  '[20~': 'f9',
+  '[21~': 'f10',
+  '[23~': 'f11',
+  '[24~': 'f12',
+  /* xterm ESC [ letter */
+  '[A': 'up',
+  '[B': 'down',
+  '[C': 'right',
+  '[D': 'left',
+  '[E': 'clear',
+  '[F': 'end',
+  '[H': 'home',
+  /* xterm/gnome ESC O letter */
+  OA: 'up',
+  OB: 'down',
+  OC: 'right',
+  OD: 'left',
+  OE: 'clear',
+  OF: 'end',
+  OH: 'home',
+  /* xterm/rxvt ESC [ number ~ */
+  '[1~': 'home',
+  '[2~': 'insert',
+  '[3~': 'delete',
+  '[4~': 'end',
+  '[5~': 'pageup',
+  '[6~': 'pagedown',
+  /* putty */
+  '[[5~': 'pageup',
+  '[[6~': 'pagedown',
+  /* rxvt */
+  '[7~': 'home',
+  '[8~': 'end',
+  /* rxvt keys with modifiers */
+  '[a': 'up',
+  '[b': 'down',
+  '[c': 'right',
+  '[d': 'left',
+  '[e': 'clear',
+
+  '[2$': 'insert',
+  '[3$': 'delete',
+  '[5$': 'pageup',
+  '[6$': 'pagedown',
+  '[7$': 'home',
+  '[8$': 'end',
+
+  Oa: 'up',
+  Ob: 'down',
+  Oc: 'right',
+  Od: 'left',
+  Oe: 'clear',
+
+  '[2^': 'insert',
+  '[3^': 'delete',
+  '[5^': 'pageup',
+  '[6^': 'pagedown',
+  '[7^': 'home',
+  '[8^': 'end',
+  /* misc. */
+  '[Z': 'tab'
+}
+
+export const nonAlphanumericKeys = [
+  // Filter out single-character values (digits, operators from numpad) since
+  // those are printable characters that should produce input
+  ...Object.values(keyName).filter(v => v.length > 1),
+  // escape and backspace are assigned directly in parseKeypress (not via the
+  // keyName map), so the spread above misses them. Without these, ctrl+escape
+  // via Kitty/modifyOtherKeys leaks the literal word "escape" as input text
+  // (input-event.ts:58 assigns keypress.name when ctrl is set).
+  'escape',
+  'backspace',
+  'wheelup',
+  'wheeldown',
+  'mouse'
+]
+
+const isShiftKey = (code: string): boolean => {
+  return ['[a', '[b', '[c', '[d', '[e', '[2$', '[3$', '[5$', '[6$', '[7$', '[8$', '[Z'].includes(code)
+}
+
+const isCtrlKey = (code: string): boolean => {
+  return ['Oa', 'Ob', 'Oc', 'Od', 'Oe', '[2^', '[3^', '[5^', '[6^', '[7^', '[8^'].includes(code)
+}
+
+/**
+ * Decode XTerm-style modifier value to individual flags.
+ * Modifier encoding: 1 + (shift ? 1 : 0) + (alt ? 2 : 0) + (ctrl ? 4 : 0) + (super ? 8 : 0)
+ *
+ * Note: `meta` here means Alt/Option (bit 2). `super` is a distinct
+ * modifier (bit 8, i.e. Cmd on macOS / Win key). Most legacy terminal
+ * sequences can't express super — it only arrives via kitty keyboard
+ * protocol (CSI u) or xterm modifyOtherKeys.
+ */
+function decodeModifier(modifier: number): {
+  shift: boolean
+  meta: boolean
+  ctrl: boolean
+  super: boolean
+} {
+  const m = modifier - 1
+
+  return {
+    shift: !!(m & 1),
+    meta: !!(m & 2),
+    ctrl: !!(m & 4),
+    super: !!(m & 8)
+  }
+}
+
+/**
+ * Map keycode to key name for modifyOtherKeys/CSI u sequences.
+ * Handles both ASCII keycodes and Kitty keyboard protocol functional keys.
+ *
+ * Numpad codepoints are from Unicode Private Use Area, defined at:
+ * https://sw.kovidgoyal.net/kitty/keyboard-protocol/#functional-key-definitions
+ */
+function keycodeToName(keycode: number): string | undefined {
+  switch (keycode) {
+    case 9:
+      return 'tab'
+
+    case 13:
+      return 'return'
+
+    case 27:
+      return 'escape'
+
+    case 32:
+      return 'space'
+
+    case 127:
+      return 'backspace'
+
+    // Kitty keyboard protocol numpad keys (KP_0 through KP_9)
+    case 57399:
+      return '0'
+
+    case 57400:
+      return '1'
+
+    case 57401:
+      return '2'
+
+    case 57402:
+      return '3'
+
+    case 57403:
+      return '4'
+
+    case 57404:
+      return '5'
+
+    case 57405:
+      return '6'
+
+    case 57406:
+      return '7'
+
+    case 57407:
+      return '8'
+
+    case 57408:
+      return '9'
+
+    case 57409: // KP_DECIMAL
+      return '.'
+
+    case 57410: // KP_DIVIDE
+      return '/'
+
+    case 57411: // KP_MULTIPLY
+      return '*'
+
+    case 57412: // KP_SUBTRACT
+      return '-'
+
+    case 57413: // KP_ADD
+      return '+'
+
+    case 57414: // KP_ENTER
+      return 'return'
+
+    case 57415: // KP_EQUAL
+      return '='
+
+    default:
+      // Printable ASCII characters
+      if (keycode >= 32 && keycode <= 126) {
+        return String.fromCharCode(keycode).toLowerCase()
+      }
+
+      return undefined
+  }
+}
+
+export type ParsedKey = {
+  kind: 'key'
+  fn: boolean
+  name: string | undefined
+  ctrl: boolean
+  meta: boolean
+  shift: boolean
+  option: boolean
+  super: boolean
+  sequence: string | undefined
+  raw: string | undefined
+  code?: string
+  isPasted: boolean
+}
+
+/** A terminal response sequence (DECRPM, DA1, OSC reply, etc.) parsed
+ *  out of the input stream. Not user input — consumers should dispatch
+ *  to a response handler. */
+export type ParsedResponse = {
+  kind: 'response'
+  /** Raw escape sequence bytes, for debugging/logging */
+  sequence: string
+  response: TerminalResponse
+}
+
+/** SGR mouse event with coordinates. Emitted for clicks, drags, and
+ *  releases (wheel events remain ParsedKey). col/row are 1-indexed
+ *  from the terminal sequence (CSI < btn;col;row M/m). */
+export type ParsedMouse = {
+  kind: 'mouse'
+  /** Raw SGR button code. Low 2 bits = button (0=left,1=mid,2=right),
+   *  bit 5 (0x20) = drag/motion, bit 6 (0x40) = wheel. */
+  button: number
+  /** 'press' for M terminator, 'release' for m terminator */
+  action: 'press' | 'release'
+  /** 1-indexed column (from terminal) */
+  col: number
+  /** 1-indexed row (from terminal) */
+  row: number
+  sequence: string
+}
+
+/** Everything that can come out of the input parser: a user keypress/paste,
+ *  a mouse click/drag event, or a terminal response to a query we sent. */
+export type ParsedInput = ParsedKey | ParsedMouse | ParsedResponse
+
+/**
+ * Parse an SGR mouse event sequence into a ParsedMouse, or null if not a
+ * mouse event or if it's a wheel event (wheel stays as ParsedKey for the
+ * keybinding system). Button bit 0x40 = wheel, bit 0x20 = drag/motion.
+ */
+function parseMouseEvent(s: string): ParsedMouse | null {
+  const match = SGR_MOUSE_RE.exec(s)
+
+  if (!match) {
+    return null
+  }
+
+  const button = parseInt(match[1]!, 10)
+
+  // Wheel events (bit 6 set, low bits 0/1 for up/down) stay as ParsedKey
+  // so the keybinding system can route them to scroll handlers.
+  if ((button & 0x40) !== 0) {
+    return null
+  }
+
+  return {
+    kind: 'mouse',
+    button,
+    action: match[4] === 'M' ? 'press' : 'release',
+    col: parseInt(match[2]!, 10),
+    row: parseInt(match[3]!, 10),
+    sequence: s
+  }
+}
+
+function parseKeypress(s: string = ''): ParsedKey {
+  let parts
+
+  const key: ParsedKey = {
+    kind: 'key',
+    name: '',
+    fn: false,
+    ctrl: false,
+    meta: false,
+    shift: false,
+    option: false,
+    super: false,
+    sequence: s,
+    raw: s,
+    isPasted: false
+  }
+
+  key.sequence = key.sequence || s || key.name
+
+  // Handle CSI u (kitty keyboard protocol): ESC [ codepoint [; modifier] u
+  // Example: ESC[13;2u = Shift+Enter, ESC[27u = Escape (no modifiers)
+  let match: RegExpExecArray | null
+
+  if ((match = CSI_U_RE.exec(s))) {
+    const codepoint = parseInt(match[1]!, 10)
+    // Modifier defaults to 1 (no modifiers) when not present
+    const modifier = match[2] ? parseInt(match[2], 10) : 1
+    const mods = decodeModifier(modifier)
+    const name = keycodeToName(codepoint)
+
+    return {
+      kind: 'key',
+      name,
+      fn: false,
+      ctrl: mods.ctrl,
+      meta: mods.meta,
+      shift: mods.shift,
+      option: false,
+      super: mods.super,
+      sequence: s,
+      raw: s,
+      isPasted: false
+    }
+  }
+
+  // Handle xterm modifyOtherKeys: ESC [ 27 ; modifier ; keycode ~
+  // Must run before FN_KEY_RE — FN_KEY_RE only allows 2 params before ~ and
+  // would leave the tail as garbage if it partially matched.
+  if ((match = MODIFY_OTHER_KEYS_RE.exec(s))) {
+    const mods = decodeModifier(parseInt(match[1]!, 10))
+    const name = keycodeToName(parseInt(match[2]!, 10))
+
+    return {
+      kind: 'key',
+      name,
+      fn: false,
+      ctrl: mods.ctrl,
+      meta: mods.meta,
+      shift: mods.shift,
+      option: false,
+      super: mods.super,
+      sequence: s,
+      raw: s,
+      isPasted: false
+    }
+  }
+
+  // SGR mouse wheel events. Click/drag/release events are handled
+  // earlier by parseMouseEvent and emitted as ParsedMouse, so they
+  // never reach here. Mask with 0x43 (bits 6+1+0) to check wheel-flag
+  // + direction while ignoring modifier bits (Shift=0x04, Meta=0x08,
+  // Ctrl=0x10) — modified wheel events (e.g. Ctrl+scroll, button=80)
+  // should still be recognized as wheelup/wheeldown. Preserve those
+  // modifier bits for callers that bind modified wheel gestures.
+  if ((match = SGR_MOUSE_RE.exec(s))) {
+    const button = parseInt(match[1]!, 10)
+
+    if ((button & 0x43) === 0x40) {
+      return createWheelKey(s, 'wheelup', button)
+    }
+
+    if ((button & 0x43) === 0x41) {
+      return createWheelKey(s, 'wheeldown', button)
+    }
+
+    // Shouldn't reach here (parseMouseEvent catches non-wheel) but be safe
+    return createNavKey(s, 'mouse', false)
+  }
+
+  // X10 mouse: CSI M + 3 raw bytes (Cb+32, Cx+32, Cy+32). Terminals that
+  // ignore DECSET 1006 (SGR) but honor 1000/1002 emit this legacy encoding.
+  // Button bits match SGR: 0x40 = wheel, low bit = direction. Non-wheel
+  // X10 events (clicks/drags) are swallowed here — we only enable mouse
+  // tracking in alt-screen and only need wheel for ScrollBox.
+  if (s.length === 6 && s.startsWith('\x1b[M')) {
+    const button = s.charCodeAt(3) - 32
+
+    if ((button & 0x43) === 0x40) {
+      return createWheelKey(s, 'wheelup', button)
+    }
+
+    if ((button & 0x43) === 0x41) {
+      return createWheelKey(s, 'wheeldown', button)
+    }
+
+    return createNavKey(s, 'mouse', false)
+  }
+
+  if (s === '\r' || s === '\n') {
+    key.raw = undefined
+    key.name = 'return'
+  } else if (s === '\t') {
+    key.name = 'tab'
+  } else if (s === '\b' || s === '\x1b\b') {
+    key.name = 'backspace'
+    key.meta = s.charAt(0) === '\x1b'
+  } else if (s === '\x7f' || s === '\x1b\x7f') {
+    key.name = 'backspace'
+    key.meta = s.charAt(0) === '\x1b'
+  } else if (s === '\x1b' || s === '\x1b\x1b') {
+    key.name = 'escape'
+    key.meta = s.length === 2
+  } else if (s === ' ' || s === '\x1b ') {
+    key.name = 'space'
+    key.meta = s.length === 2
+  } else if (s === '\x1f') {
+    key.name = '_'
+    key.ctrl = true
+  } else if (s <= '\x1a' && s.length === 1) {
+    key.name = String.fromCharCode(s.charCodeAt(0) + 'a'.charCodeAt(0) - 1)
+    key.ctrl = true
+  } else if (s.length === 1 && s >= '0' && s <= '9') {
+    key.name = 'number'
+  } else if (s.length === 1 && s >= 'a' && s <= 'z') {
+    key.name = s
+  } else if (s.length === 1 && s >= 'A' && s <= 'Z') {
+    key.name = s.toLowerCase()
+    key.shift = true
+  } else if ((parts = META_KEY_CODE_RE.exec(s))) {
+    key.meta = true
+    key.shift = /^[A-Z]$/.test(parts[1]!)
+  } else if ((parts = FN_KEY_RE.exec(s))) {
+    const segs = [...s]
+
+    if (segs[0] === '\u001b' && segs[1] === '\u001b') {
+      key.option = true
+    }
+
+    const code = [parts[1], parts[2], parts[4], parts[6]].filter(Boolean).join('')
+
+    const modifier = ((parts[3] || parts[5] || 1) as number) - 1
+
+    key.ctrl = !!(modifier & 4)
+    key.meta = !!(modifier & 2)
+    key.super = !!(modifier & 8)
+    key.shift = !!(modifier & 1)
+    key.code = code
+
+    key.name = keyName[code]
+    key.shift = isShiftKey(code) || key.shift
+    key.ctrl = isCtrlKey(code) || key.ctrl
+  }
+
+  // iTerm in natural text editing mode
+  if (key.raw === '\x1Bb') {
+    key.meta = true
+    key.name = 'left'
+  } else if (key.raw === '\x1Bf') {
+    key.meta = true
+    key.name = 'right'
+  }
+
+  switch (s) {
+    case '\u001b[1~':
+      return createNavKey(s, 'home', false)
+
+    case '\u001b[4~':
+      return createNavKey(s, 'end', false)
+
+    case '\u001b[5~':
+      return createNavKey(s, 'pageup', false)
+
+    case '\u001b[6~':
+      return createNavKey(s, 'pagedown', false)
+
+    case '\u001b[1;5D':
+      return createNavKey(s, 'left', true)
+
+    case '\u001b[1;5C':
+      return createNavKey(s, 'right', true)
+  }
+
+  return key
+}
+
+function createNavKey(s: string, name: string, ctrl: boolean): ParsedKey {
+  return {
+    kind: 'key',
+    name,
+    ctrl,
+    meta: false,
+    shift: false,
+    option: false,
+    super: false,
+    fn: false,
+    sequence: s,
+    raw: s,
+    isPasted: false
+  }
+}
+
+function createWheelKey(s: string, name: 'wheelup' | 'wheeldown', button: number): ParsedKey {
+  return {
+    kind: 'key',
+    name,
+    ctrl: !!(button & 0x10),
+    meta: !!(button & 0x08),
+    shift: !!(button & 0x04),
+    option: false,
+    super: false,
+    fn: false,
+    sequence: s,
+    raw: s,
+    isPasted: false
+  }
+}

ui-tui/packages/hermes-ink/src/ink/reconciler.ts

@@ -0,0 +1,382 @@
+import createReconciler from 'react-reconciler'
+
+import {
+  appendChildNode,
+  clearYogaNodeReferences,
+  createNode,
+  createTextNode,
+  type DOMElement,
+  type DOMNodeAttribute,
+  type ElementNames,
+  insertBeforeNode,
+  markDirty,
+  removeChildNode,
+  setAttribute,
+  setStyle,
+  setTextNodeValue,
+  setTextStyles,
+  type TextNode
+} from './dom.js'
+import { Dispatcher } from './events/dispatcher.js'
+import { EVENT_HANDLER_PROPS } from './events/event-handlers.js'
+import { getFocusManager, getRootNode } from './focus.js'
+import { LayoutDisplay } from './layout/node.js'
+import applyStyles, { type Styles, type TextStyles } from './styles.js'
+
+// We need to conditionally perform devtools connection to avoid
+// accidentally breaking other third-party code.
+// See https://github.com/vadimdemedes/ink/issues/384
+if (process.env.NODE_ENV === 'development') {
+  try {
+    void import('./devtools.js')
+  } catch (error: any) {
+    if (error.code === 'ERR_MODULE_NOT_FOUND') {
+      // biome-ignore lint/suspicious/noConsole: intentional warning
+      console.warn(
+        `
+The environment variable DEV is set to true, so Ink tried to import \`react-devtools-core\`,
+but this failed as it was not installed. Debugging with React Devtools requires it.
+
+To install use this command:
+
+$ npm install --save-dev react-devtools-core
+				`.trim() + '\n'
+      )
+    } else {
+      throw error
+    }
+  }
+}
+
+// --
+
+type AnyObject = Record<string, unknown>
+
+const diff = (before: AnyObject, after: AnyObject): AnyObject | undefined => {
+  if (before === after) {
+    return
+  }
+
+  if (!before) {
+    return after
+  }
+
+  const changed: AnyObject = {}
+  let isChanged = false
+
+  for (const key of Object.keys(before)) {
+    const isDeleted = after ? !Object.hasOwn(after, key) : true
+
+    if (isDeleted) {
+      changed[key] = undefined
+      isChanged = true
+    }
+  }
+
+  if (after) {
+    for (const key of Object.keys(after)) {
+      if (after[key] !== before[key]) {
+        changed[key] = after[key]
+        isChanged = true
+      }
+    }
+  }
+
+  return isChanged ? changed : undefined
+}
+
+const cleanupYogaNode = (node: DOMElement | TextNode): void => {
+  const yogaNode = node.yogaNode
+
+  if (yogaNode) {
+    yogaNode.unsetMeasureFunc()
+    // Clear all references BEFORE freeing to prevent other code from
+    // accessing freed WASM memory during concurrent operations
+    clearYogaNodeReferences(node)
+    yogaNode.freeRecursive()
+  }
+}
+
+// --
+
+type Props = Record<string, unknown>
+
+type HostContext = {
+  isInsideText: boolean
+}
+
+function setEventHandler(node: DOMElement, key: string, value: unknown): void {
+  if (!node._eventHandlers) {
+    node._eventHandlers = {}
+  }
+
+  node._eventHandlers[key] = value
+}
+
+function applyProp(node: DOMElement, key: string, value: unknown): void {
+  if (key === 'children') {
+    return
+  }
+
+  if (key === 'style') {
+    setStyle(node, value as Styles)
+
+    if (node.yogaNode) {
+      applyStyles(node.yogaNode, value as Styles)
+    }
+
+    return
+  }
+
+  if (key === 'textStyles') {
+    node.textStyles = value as TextStyles
+
+    return
+  }
+
+  if (EVENT_HANDLER_PROPS.has(key)) {
+    setEventHandler(node, key, value)
+
+    return
+  }
+
+  setAttribute(node, key, value as DOMNodeAttribute)
+}
+
+// --
+
+export const dispatcher = new Dispatcher()
+
+// --- SCROLL PROFILING (bench/scroll-e2e.sh reads via getLastYogaMs) ---
+// Set by onComputeLayout wrapper in ink.tsx; read by onRender for phases.
+let _lastYogaMs = 0
+let _lastCommitMs = 0
+let _commitStart = 0
+
+export function recordYogaMs(ms: number): void {
+  _lastYogaMs = ms
+}
+
+export function getLastYogaMs(): number {
+  return _lastYogaMs
+}
+
+export function markCommitStart(): void {
+  _commitStart = performance.now()
+}
+
+export function getLastCommitMs(): number {
+  return _lastCommitMs
+}
+
+export function resetProfileCounters(): void {
+  _lastYogaMs = 0
+  _lastCommitMs = 0
+  _commitStart = 0
+}
+// --- END ---
+
+const reconciler = createReconciler({
+  getRootHostContext: () => ({ isInsideText: false }),
+  prepareForCommit: () => null,
+  preparePortalMount: () => null,
+  clearContainer: () => false,
+  resetAfterCommit(rootNode: DOMElement) {
+    _lastCommitMs = _commitStart > 0 ? performance.now() - _commitStart : 0
+    _commitStart = 0
+
+    if (typeof rootNode.onComputeLayout === 'function') {
+      rootNode.onComputeLayout()
+    }
+
+    if (process.env.NODE_ENV === 'test') {
+      if (rootNode.childNodes.length === 0 && rootNode.hasRenderedContent) {
+        return
+      }
+
+      if (rootNode.childNodes.length > 0) {
+        rootNode.hasRenderedContent = true
+      }
+
+      rootNode.onImmediateRender?.()
+
+      return
+    }
+
+    rootNode.onRender?.()
+  },
+  getChildHostContext(parentHostContext: HostContext, type: ElementNames): HostContext {
+    const previousIsInsideText = parentHostContext.isInsideText
+
+    const isInsideText = type === 'ink-text' || type === 'ink-virtual-text' || type === 'ink-link'
+
+    if (previousIsInsideText === isInsideText) {
+      return parentHostContext
+    }
+
+    return { isInsideText }
+  },
+  shouldSetTextContent: () => false,
+  createInstance(
+    originalType: ElementNames,
+    newProps: Props,
+    _root: DOMElement,
+    hostContext: HostContext,
+    _internalHandle?: unknown
+  ): DOMElement {
+    if (hostContext.isInsideText && originalType === 'ink-box') {
+      throw new Error(`<Box> can't be nested inside <Text> component`)
+    }
+
+    const type = originalType === 'ink-text' && hostContext.isInsideText ? 'ink-virtual-text' : originalType
+
+    const node = createNode(type)
+
+    for (const [key, value] of Object.entries(newProps)) {
+      applyProp(node, key, value)
+    }
+
+    return node
+  },
+  createTextInstance(text: string, _root: DOMElement, hostContext: HostContext): TextNode {
+    if (!hostContext.isInsideText) {
+      throw new Error(`Text string "${text}" must be rendered inside <Text> component`)
+    }
+
+    return createTextNode(text)
+  },
+  resetTextContent() {},
+  hideTextInstance(node: TextNode) {
+    setTextNodeValue(node, '')
+  },
+  unhideTextInstance(node: TextNode, text: string) {
+    setTextNodeValue(node, text)
+  },
+  getPublicInstance: (instance: DOMElement): DOMElement => instance,
+  hideInstance(node: DOMElement) {
+    node.isHidden = true
+    node.yogaNode?.setDisplay(LayoutDisplay.None)
+    markDirty(node)
+  },
+  unhideInstance(node: DOMElement) {
+    node.isHidden = false
+    node.yogaNode?.setDisplay(LayoutDisplay.Flex)
+    markDirty(node)
+  },
+  appendInitialChild: appendChildNode,
+  appendChild: appendChildNode,
+  insertBefore: insertBeforeNode,
+  finalizeInitialChildren(_node: DOMElement, _type: ElementNames, props: Props): boolean {
+    return props['autoFocus'] === true
+  },
+  commitMount(node: DOMElement): void {
+    getFocusManager(node).handleAutoFocus(node)
+  },
+  isPrimaryRenderer: true,
+  supportsMutation: true,
+  supportsPersistence: false,
+  supportsHydration: false,
+  scheduleTimeout: setTimeout,
+  cancelTimeout: clearTimeout,
+  noTimeout: -1,
+  getCurrentUpdatePriority: () => dispatcher.currentUpdatePriority,
+  beforeActiveInstanceBlur() {},
+  afterActiveInstanceBlur() {},
+  detachDeletedInstance() {},
+  getInstanceFromNode: () => null,
+  prepareScopeUpdate() {},
+  getInstanceFromScope: () => null,
+  appendChildToContainer: appendChildNode,
+  insertInContainerBefore: insertBeforeNode,
+  removeChildFromContainer(node: DOMElement, removeNode: DOMElement): void {
+    removeChildNode(node, removeNode)
+    cleanupYogaNode(removeNode)
+    getFocusManager(node).handleNodeRemoved(removeNode, node)
+  },
+  // React 19 commitUpdate receives old and new props directly instead of an updatePayload
+  commitUpdate(node: DOMElement, _type: ElementNames, oldProps: Props, newProps: Props): void {
+    const props = diff(oldProps, newProps)
+    const style = diff(oldProps['style'] as Styles, newProps['style'] as Styles)
+
+    if (props) {
+      for (const [key, value] of Object.entries(props)) {
+        if (key === 'style') {
+          setStyle(node, value as Styles)
+
+          continue
+        }
+
+        if (key === 'textStyles') {
+          setTextStyles(node, value as TextStyles)
+
+          continue
+        }
+
+        if (EVENT_HANDLER_PROPS.has(key)) {
+          setEventHandler(node, key, value)
+
+          continue
+        }
+
+        setAttribute(node, key, value as DOMNodeAttribute)
+      }
+    }
+
+    if (style && node.yogaNode) {
+      applyStyles(node.yogaNode, style, newProps['style'] as Styles)
+    }
+  },
+  commitTextUpdate(node: TextNode, _oldText: string, newText: string): void {
+    setTextNodeValue(node, newText)
+  },
+  removeChild(node: DOMElement, removeNode: DOMElement | TextNode) {
+    removeChildNode(node, removeNode)
+    cleanupYogaNode(removeNode)
+
+    if (removeNode.nodeName !== '#text') {
+      const root = getRootNode(node)
+      root.focusManager!.handleNodeRemoved(removeNode, root)
+    }
+  },
+  // React 19 required methods
+  maySuspendCommit(): boolean {
+    return false
+  },
+  preloadInstance(): boolean {
+    return true
+  },
+  startSuspendingCommit(): void {},
+  suspendInstance(): void {},
+  waitForCommitToBeReady(): null {
+    return null
+  },
+  NotPendingTransition: null,
+  HostTransitionContext: {
+    $$typeof: Symbol.for('react.context'),
+    _currentValue: null
+  } as never,
+  setCurrentUpdatePriority(newPriority: number): void {
+    dispatcher.currentUpdatePriority = newPriority
+  },
+  resolveUpdatePriority(): number {
+    return dispatcher.resolveEventPriority()
+  },
+  resetFormInstance(): void {},
+  requestPostPaintCallback(): void {},
+  shouldAttemptEagerTransition(): boolean {
+    return false
+  },
+  trackSchedulerEvent(): void {},
+  resolveEventType(): string | null {
+    return dispatcher.currentEvent?.type ?? null
+  },
+  resolveEventTimeStamp(): number {
+    return dispatcher.currentEvent?.timeStamp ?? -1.1
+  }
+})
+
+// Wire the reconciler's discreteUpdates into the dispatcher.
+// This breaks the import cycle: dispatcher.ts doesn't import reconciler.ts.
+dispatcher.discreteUpdates = reconciler.discreteUpdates.bind(reconciler)
+
+export default reconciler

ui-tui/packages/hermes-ink/src/ink/render-border.ts

@@ -0,0 +1,206 @@
+import chalk from 'chalk'
+import cliBoxes, { type Boxes, type BoxStyle } from 'cli-boxes'
+
+import { applyColor } from './colorize.js'
+import type { DOMNode } from './dom.js'
+import type Output from './output.js'
+import { stringWidth } from './stringWidth.js'
+import type { Color } from './styles.js'
+
+export type BorderTextOptions = {
+  content: string // Pre-rendered string with ANSI color codes
+  position: 'top' | 'bottom'
+  align: 'start' | 'end' | 'center'
+  offset?: number // Only used with 'start' or 'end' alignment. Number of characters from the edge.
+}
+
+export const CUSTOM_BORDER_STYLES = {
+  dashed: {
+    top: '╌',
+    left: '╎',
+    right: '╎',
+    bottom: '╌',
+    // there aren't any line-drawing characters for dashes unfortunately
+    topLeft: ' ',
+    topRight: ' ',
+    bottomLeft: ' ',
+    bottomRight: ' '
+  }
+} as const
+
+export type BorderStyle = keyof Boxes | keyof typeof CUSTOM_BORDER_STYLES | BoxStyle
+
+function embedTextInBorder(
+  borderLine: string,
+  text: string,
+  align: 'start' | 'end' | 'center',
+  offset: number = 0,
+  borderChar: string
+): [before: string, text: string, after: string] {
+  const textLength = stringWidth(text)
+  const borderLength = borderLine.length
+
+  if (textLength >= borderLength - 2) {
+    return ['', text.substring(0, borderLength), '']
+  }
+
+  let position: number
+
+  if (align === 'center') {
+    position = Math.floor((borderLength - textLength) / 2)
+  } else if (align === 'start') {
+    position = offset + 1 // +1 to account for corner character
+  } else {
+    // align === 'end'
+    position = borderLength - textLength - offset - 1 // -1 for corner character
+  }
+
+  // Ensure position is valid
+  position = Math.max(1, Math.min(position, borderLength - textLength - 1))
+
+  const before = borderLine.substring(0, 1) + borderChar.repeat(position - 1)
+
+  const after = borderChar.repeat(borderLength - position - textLength - 1) + borderLine.substring(borderLength - 1)
+
+  return [before, text, after]
+}
+
+function styleBorderLine(line: string, color: Color | undefined, dim: boolean | undefined): string {
+  let styled = applyColor(line, color)
+
+  if (dim) {
+    styled = chalk.dim(styled)
+  }
+
+  return styled
+}
+
+const renderBorder = (x: number, y: number, node: DOMNode, output: Output): void => {
+  if (node.style.borderStyle) {
+    const width = Math.floor(node.yogaNode!.getComputedWidth())
+    const height = Math.floor(node.yogaNode!.getComputedHeight())
+
+    const box =
+      typeof node.style.borderStyle === 'string'
+        ? (CUSTOM_BORDER_STYLES[node.style.borderStyle as keyof typeof CUSTOM_BORDER_STYLES] ??
+          cliBoxes[node.style.borderStyle as keyof Boxes])
+        : node.style.borderStyle
+
+    const topBorderColor = node.style.borderTopColor ?? node.style.borderColor
+
+    const bottomBorderColor = node.style.borderBottomColor ?? node.style.borderColor
+
+    const leftBorderColor = node.style.borderLeftColor ?? node.style.borderColor
+
+    const rightBorderColor = node.style.borderRightColor ?? node.style.borderColor
+
+    const dimTopBorderColor = node.style.borderTopDimColor ?? node.style.borderDimColor
+
+    const dimBottomBorderColor = node.style.borderBottomDimColor ?? node.style.borderDimColor
+
+    const dimLeftBorderColor = node.style.borderLeftDimColor ?? node.style.borderDimColor
+
+    const dimRightBorderColor = node.style.borderRightDimColor ?? node.style.borderDimColor
+
+    const showTopBorder = node.style.borderTop !== false
+    const showBottomBorder = node.style.borderBottom !== false
+    const showLeftBorder = node.style.borderLeft !== false
+    const showRightBorder = node.style.borderRight !== false
+
+    const contentWidth = Math.max(0, width - (showLeftBorder ? 1 : 0) - (showRightBorder ? 1 : 0))
+
+    const topBorderLine = showTopBorder
+      ? (showLeftBorder ? box.topLeft : '') + box.top.repeat(contentWidth) + (showRightBorder ? box.topRight : '')
+      : ''
+
+    // Handle text in top border
+    let topBorder: string | undefined
+
+    if (showTopBorder && node.style.borderText?.position === 'top') {
+      const [before, text, after] = embedTextInBorder(
+        topBorderLine,
+        node.style.borderText.content,
+        node.style.borderText.align,
+        node.style.borderText.offset,
+        box.top
+      )
+
+      topBorder =
+        styleBorderLine(before, topBorderColor, dimTopBorderColor) +
+        text +
+        styleBorderLine(after, topBorderColor, dimTopBorderColor)
+    } else if (showTopBorder) {
+      topBorder = styleBorderLine(topBorderLine, topBorderColor, dimTopBorderColor)
+    }
+
+    let verticalBorderHeight = height
+
+    if (showTopBorder) {
+      verticalBorderHeight -= 1
+    }
+
+    if (showBottomBorder) {
+      verticalBorderHeight -= 1
+    }
+
+    verticalBorderHeight = Math.max(0, verticalBorderHeight)
+
+    let leftBorder = (applyColor(box.left, leftBorderColor) + '\n').repeat(verticalBorderHeight)
+
+    if (dimLeftBorderColor) {
+      leftBorder = chalk.dim(leftBorder)
+    }
+
+    let rightBorder = (applyColor(box.right, rightBorderColor) + '\n').repeat(verticalBorderHeight)
+
+    if (dimRightBorderColor) {
+      rightBorder = chalk.dim(rightBorder)
+    }
+
+    const bottomBorderLine = showBottomBorder
+      ? (showLeftBorder ? box.bottomLeft : '') +
+        box.bottom.repeat(contentWidth) +
+        (showRightBorder ? box.bottomRight : '')
+      : ''
+
+    // Handle text in bottom border
+    let bottomBorder: string | undefined
+
+    if (showBottomBorder && node.style.borderText?.position === 'bottom') {
+      const [before, text, after] = embedTextInBorder(
+        bottomBorderLine,
+        node.style.borderText.content,
+        node.style.borderText.align,
+        node.style.borderText.offset,
+        box.bottom
+      )
+
+      bottomBorder =
+        styleBorderLine(before, bottomBorderColor, dimBottomBorderColor) +
+        text +
+        styleBorderLine(after, bottomBorderColor, dimBottomBorderColor)
+    } else if (showBottomBorder) {
+      bottomBorder = styleBorderLine(bottomBorderLine, bottomBorderColor, dimBottomBorderColor)
+    }
+
+    const offsetY = showTopBorder ? 1 : 0
+
+    if (topBorder) {
+      output.write(x, y, topBorder)
+    }
+
+    if (showLeftBorder) {
+      output.write(x, y + offsetY, leftBorder)
+    }
+
+    if (showRightBorder) {
+      output.write(x + width - 1, y + offsetY, rightBorder)
+    }
+
+    if (bottomBorder) {
+      output.write(x, y + height - 1, bottomBorder)
+    }
+  }
+}
+
+export default renderBorder

ui-tui/packages/hermes-ink/src/ink/render-to-screen.ts

@@ -0,0 +1,236 @@
+import noop from 'lodash-es/noop.js'
+import type { ReactElement } from 'react'
+import { LegacyRoot } from 'react-reconciler/constants.js'
+
+import { logForDebugging } from '../utils/debug.js'
+
+import { createNode, type DOMElement } from './dom.js'
+import { FocusManager } from './focus.js'
+import Output from './output.js'
+import reconciler from './reconciler.js'
+import renderNodeToOutput, { resetLayoutShifted } from './render-node-to-output.js'
+import {
+  cellAtIndex,
+  CellWidth,
+  CharPool,
+  createScreen,
+  HyperlinkPool,
+  type Screen,
+  setCellStyleId,
+  StylePool
+} from './screen.js'
+
+/** Position of a match within a rendered message, relative to the message's
+ *  own bounding box (row 0 = message top). Stable across scroll — to
+ *  highlight on the real screen, add the message's screen-row offset. */
+export type MatchPosition = {
+  row: number
+  col: number
+  /** Number of CELLS the match spans (= query.length for ASCII, more
+   *  for wide chars in the query). */
+  len: number
+}
+
+// Shared across calls. Pools accumulate style/char interns — reusing them
+// means later calls hit cache more. Root/container reuse saves the
+// createContainer cost (~1ms). LegacyRoot: all work sync, no scheduling —
+// ConcurrentRoot's scheduler backlog leaks across roots via flushSyncWork.
+let root: DOMElement | undefined
+let container: ReturnType<typeof reconciler.createContainer> | undefined
+let stylePool: StylePool | undefined
+let charPool: CharPool | undefined
+let hyperlinkPool: HyperlinkPool | undefined
+let output: Output | undefined
+
+const timing = { reconcile: 0, yoga: 0, paint: 0, scan: 0, calls: 0 }
+const LOG_EVERY = 20
+
+/** Render a React element (wrapped in all contexts the component needs —
+ *  caller's job) to an isolated Screen buffer at the given width. Returns
+ *  the Screen + natural height (from yoga). Used for search: render ONE
+ *  message, scan its Screen for the query, get exact (row, col) positions.
+ *
+ *  ~1-3ms per call (yoga alloc + calculateLayout + paint). The
+ *  flushSyncWork cross-root leak measured ~0.0003ms/call growth — fine
+ *  for on-demand single-message rendering, pathological for render-all-
+ *  8k-upfront. Cache per (msg, query, width) upstream.
+ *
+ *  Unmounts between calls. Root/container/pools persist for reuse. */
+export function renderToScreen(el: ReactElement, width: number): { screen: Screen; height: number } {
+  if (!root) {
+    root = createNode('ink-root')
+    root.focusManager = new FocusManager(() => false)
+    stylePool = new StylePool()
+    charPool = new CharPool()
+    hyperlinkPool = new HyperlinkPool()
+    container = reconciler.createContainer(root, LegacyRoot, null, false, null, 'search-render', noop, noop, noop, noop)
+  }
+
+  const t0 = performance.now()
+  reconciler.updateContainerSync(el, container, null, noop)
+  reconciler.flushSyncWork()
+  const t1 = performance.now()
+
+  // Yoga layout. Root might not have a yogaNode if the tree is empty.
+  root.yogaNode?.setWidth(width)
+  root.yogaNode?.calculateLayout(width)
+  const height = Math.ceil(root.yogaNode?.getComputedHeight() ?? 0)
+  const t2 = performance.now()
+
+  // Paint to a fresh Screen. Width = given, height = yoga's natural.
+  // No alt-screen, no prevScreen (every call is fresh).
+  const screen = createScreen(
+    width,
+    Math.max(1, height), // avoid 0-height Screen (createScreen may choke)
+    stylePool!,
+    charPool!,
+    hyperlinkPool!
+  )
+
+  if (!output) {
+    output = new Output({ width, height, stylePool: stylePool!, screen })
+  } else {
+    output.reset(width, height, screen)
+  }
+
+  resetLayoutShifted()
+  renderNodeToOutput(root, output, { prevScreen: undefined })
+  // renderNodeToOutput queues writes into Output; .get() flushes the
+  // queue into the Screen's cell arrays. Without this the screen is
+  // blank (constructor-zero).
+  const rendered = output.get()
+  const t3 = performance.now()
+
+  // Unmount so next call gets a fresh tree. Leaves root/container/pools.
+  reconciler.updateContainerSync(null, container, null, noop)
+  reconciler.flushSyncWork()
+
+  timing.reconcile += t1 - t0
+  timing.yoga += t2 - t1
+  timing.paint += t3 - t2
+
+  if (++timing.calls % LOG_EVERY === 0) {
+    const total = timing.reconcile + timing.yoga + timing.paint + timing.scan
+    logForDebugging(
+      `renderToScreen: ${timing.calls} calls · ` +
+        `reconcile=${timing.reconcile.toFixed(1)}ms yoga=${timing.yoga.toFixed(1)}ms ` +
+        `paint=${timing.paint.toFixed(1)}ms scan=${timing.scan.toFixed(1)}ms · ` +
+        `total=${total.toFixed(1)}ms · avg ${(total / timing.calls).toFixed(2)}ms/call`
+    )
+  }
+
+  return { screen: rendered, height }
+}
+
+/** Scan a Screen buffer for all occurrences of query. Returns positions
+ *  relative to the buffer (row 0 = buffer top). Same cell-skip logic as
+ *  applySearchHighlight (SpacerTail/SpacerHead/noSelect) so positions
+ *  match what the overlay highlight would find. Case-insensitive.
+ *
+ *  For the side-render use: this Screen is the FULL message (natural
+ *  height, not viewport-clipped). Positions are stable — to highlight
+ *  on the real screen, add the message's screen offset (lo). */
+export function scanPositions(screen: Screen, query: string): MatchPosition[] {
+  const lq = query.toLowerCase()
+
+  if (!lq) {
+    return []
+  }
+
+  const qlen = lq.length
+  const w = screen.width
+  const h = screen.height
+  const noSelect = screen.noSelect
+  const positions: MatchPosition[] = []
+
+  const t0 = performance.now()
+
+  for (let row = 0; row < h; row++) {
+    const rowOff = row * w
+    // Same text-build as applySearchHighlight. Keep in sync — or extract
+    // to a shared helper (TODO once both are stable). codeUnitToCell
+    // maps indexOf positions (code units in the LOWERCASED text) to cell
+    // indices in colOf — surrogate pairs (emoji) and multi-unit lowercase
+    // (Turkish İ → i + U+0307) make text.length > colOf.length.
+    let text = ''
+    const colOf: number[] = []
+    const codeUnitToCell: number[] = []
+
+    for (let col = 0; col < w; col++) {
+      const idx = rowOff + col
+      const cell = cellAtIndex(screen, idx)
+
+      if (cell.width === CellWidth.SpacerTail || cell.width === CellWidth.SpacerHead || noSelect[idx] === 1) {
+        continue
+      }
+
+      const lc = cell.char.toLowerCase()
+      const cellIdx = colOf.length
+
+      for (let i = 0; i < lc.length; i++) {
+        codeUnitToCell.push(cellIdx)
+      }
+
+      text += lc
+      colOf.push(col)
+    }
+
+    // Non-overlapping — same advance as applySearchHighlight.
+    let pos = text.indexOf(lq)
+
+    while (pos >= 0) {
+      const startCi = codeUnitToCell[pos]!
+      const endCi = codeUnitToCell[pos + qlen - 1]!
+      const col = colOf[startCi]!
+      const endCol = colOf[endCi]! + 1
+      positions.push({ row, col, len: endCol - col })
+      pos = text.indexOf(lq, pos + qlen)
+    }
+  }
+
+  timing.scan += performance.now() - t0
+
+  return positions
+}
+
+/** Write CURRENT (yellow+bold+underline) at positions[currentIdx] +
+ *  rowOffset. OTHER positions are NOT styled here — the scan-highlight
+ *  (applySearchHighlight with null hint) does inverse for all visible
+ *  matches, including these. Two-layer: scan = 'you could go here',
+ *  position = 'you ARE here'. Writing inverse again here would be a
+ *  no-op (withInverse idempotent) but wasted work.
+ *
+ *  Positions are message-relative (row 0 = message top). rowOffset =
+ *  message's current screen-top (lo). Clips outside [0, height). */
+export function applyPositionedHighlight(
+  screen: Screen,
+  stylePool: StylePool,
+  positions: MatchPosition[],
+  rowOffset: number,
+  currentIdx: number
+): boolean {
+  if (currentIdx < 0 || currentIdx >= positions.length) {
+    return false
+  }
+
+  const p = positions[currentIdx]!
+  const row = p.row + rowOffset
+
+  if (row < 0 || row >= screen.height) {
+    return false
+  }
+
+  const transform = (id: number) => stylePool.withCurrentMatch(id)
+  const rowOff = row * screen.width
+
+  for (let col = p.col; col < p.col + p.len; col++) {
+    if (col < 0 || col >= screen.width) {
+      continue
+    }
+
+    const cell = cellAtIndex(screen, rowOff + col)
+    setCellStyleId(screen, col, row, transform(cell.styleId))
+  }
+
+  return true
+}

ui-tui/packages/hermes-ink/src/ink/renderer.ts

@@ -0,0 +1,169 @@
+import { logForDebugging } from '../utils/debug.js'
+
+import { type DOMElement, markDirty } from './dom.js'
+import type { Frame } from './frame.js'
+import { consumeAbsoluteRemovedFlag } from './node-cache.js'
+import Output from './output.js'
+import renderNodeToOutput, {
+  didAbsoluteOverlayMove,
+  getScrollDrainNode,
+  getScrollHint,
+  resetLayoutShifted,
+  resetScrollDrainNode,
+  resetScrollHint
+} from './render-node-to-output.js'
+import { createScreen, type StylePool } from './screen.js'
+
+export type RenderOptions = {
+  frontFrame: Frame
+  backFrame: Frame
+  isTTY: boolean
+  terminalWidth: number
+  terminalRows: number
+  altScreen: boolean
+  // True when the previous frame's screen buffer was mutated post-render
+  // (selection overlay), reset to blank (alt-screen enter/resize/SIGCONT),
+  // or reset to 0×0 (forceRedraw). Blitting from such a prevScreen would
+  // copy stale inverted cells, blanks, or nothing. When false, blit is safe.
+  prevFrameContaminated: boolean
+}
+
+export type Renderer = (options: RenderOptions) => Frame
+
+export default function createRenderer(node: DOMElement, stylePool: StylePool): Renderer {
+  // Reuse Output across frames so charCache (tokenize + grapheme clustering)
+  // persists — most lines don't change between renders.
+  let output: Output | undefined
+
+  return options => {
+    const { frontFrame, backFrame, isTTY, terminalWidth, terminalRows } = options
+
+    const prevScreen = frontFrame.screen
+    const backScreen = backFrame.screen
+    // Read pools from the back buffer's screen — pools may be replaced
+    // between frames (generational reset), so we can't capture them in the closure
+    const charPool = backScreen.charPool
+    const hyperlinkPool = backScreen.hyperlinkPool
+
+    // Return empty frame if yoga node doesn't exist or layout hasn't been computed yet.
+    // getComputedHeight() returns NaN before calculateLayout() is called.
+    // Also check for invalid dimensions (negative, Infinity) that would cause RangeError
+    // when creating arrays.
+    const computedHeight = node.yogaNode?.getComputedHeight()
+    const computedWidth = node.yogaNode?.getComputedWidth()
+
+    const hasInvalidHeight = computedHeight === undefined || !Number.isFinite(computedHeight) || computedHeight < 0
+
+    const hasInvalidWidth = computedWidth === undefined || !Number.isFinite(computedWidth) || computedWidth < 0
+
+    if (!node.yogaNode || hasInvalidHeight || hasInvalidWidth) {
+      // Log to help diagnose root cause (visible with --debug flag)
+      if (node.yogaNode && (hasInvalidHeight || hasInvalidWidth)) {
+        logForDebugging(
+          `Invalid yoga dimensions: width=${computedWidth}, height=${computedHeight}, ` +
+            `childNodes=${node.childNodes.length}, terminalWidth=${terminalWidth}, terminalRows=${terminalRows}`
+        )
+      }
+
+      return {
+        screen: createScreen(terminalWidth, 0, stylePool, charPool, hyperlinkPool),
+        viewport: { width: terminalWidth, height: terminalRows },
+        cursor: { x: 0, y: 0, visible: true }
+      }
+    }
+
+    const width = Math.floor(node.yogaNode.getComputedWidth())
+    const yogaHeight = Math.floor(node.yogaNode.getComputedHeight())
+    // Alt-screen: the screen buffer IS the alt buffer — always exactly
+    // terminalRows tall. <AlternateScreen> wraps children in <Box
+    // height={rows} flexShrink={0}>, so yogaHeight should equal
+    // terminalRows. But if something renders as a SIBLING of that Box
+    // (bug: MessageSelector was outside <FullscreenLayout>), yogaHeight
+    // exceeds rows and every assumption below (viewport +1 hack, cursor.y
+    // clamp, log-update's heightDelta===0 fast path) breaks, desyncing
+    // virtual/physical cursors. Clamping here enforces the invariant:
+    // overflow writes land at y >= screen.height and setCellAt drops
+    // them. The sibling is invisible (obvious, easy to find) instead of
+    // corrupting the whole terminal.
+    const height = options.altScreen ? terminalRows : yogaHeight
+
+    if (options.altScreen && yogaHeight > terminalRows) {
+      logForDebugging(
+        `alt-screen: yoga height ${yogaHeight} > terminalRows ${terminalRows} — ` +
+          `something is rendering outside <AlternateScreen>. Overflow clipped.`,
+        { level: 'warn' }
+      )
+    }
+
+    const screen = backScreen ?? createScreen(width, height, stylePool, charPool, hyperlinkPool)
+
+    if (output) {
+      output.reset(width, height, screen)
+    } else {
+      output = new Output({ width, height, stylePool, screen })
+    }
+
+    resetLayoutShifted()
+    resetScrollHint()
+    resetScrollDrainNode()
+
+    // prevFrameContaminated: selection overlay mutated the returned screen
+    // buffer post-render (in ink.tsx), resetFramesForAltScreen() replaced it
+    // with blanks, or forceRedraw() reset it to 0×0. Blit on the NEXT frame
+    // would copy stale inverted cells / blanks / nothing. When clean, blit
+    // restores the O(unchanged) fast path for steady-state frames (spinner
+    // tick, text stream).
+    // Removing an absolute-positioned node poisons prevScreen: it may
+    // have painted over non-siblings (e.g. an overlay over a ScrollBox
+    // earlier in tree order), so their blits would restore the removed
+    // node's pixels. hasRemovedChild only shields direct siblings.
+    // Normal-flow removals don't paint cross-subtree and are fine.
+    const absoluteRemoved = consumeAbsoluteRemovedFlag()
+    renderNodeToOutput(node, output, {
+      prevScreen: absoluteRemoved || options.prevFrameContaminated ? undefined : prevScreen
+    })
+
+    const renderedScreen = output.get()
+
+    // Drain continuation: render cleared scrollbox.dirty, so next frame's
+    // root blit would skip the subtree. markDirty walks ancestors so the
+    // next frame descends. Done AFTER render so the clear-dirty at the end
+    // of renderNodeToOutput doesn't overwrite this.
+    const drainNode = getScrollDrainNode()
+
+    if (drainNode) {
+      markDirty(drainNode)
+    }
+
+    return {
+      absoluteOverlayMoved: didAbsoluteOverlayMove(),
+      scrollHint: options.altScreen ? getScrollHint() : null,
+      scrollDrainPending: drainNode !== null,
+      screen: renderedScreen,
+      viewport: {
+        width: terminalWidth,
+        // Alt screen: fake viewport.height = rows + 1 so that
+        // shouldClearScreen()'s `screen.height >= viewport.height` check
+        // (which treats exactly-filling content as "overflows" for
+        // scrollback purposes) never fires. Alt-screen content is always
+        // exactly `rows` tall (via <Box height={rows}>) but never
+        // scrolls — the cursor.y clamp below keeps the cursor-restore
+        // from emitting an LF. With the standard diff path, every frame
+        // is incremental; no fullResetSequence_CAUSES_FLICKER.
+        height: options.altScreen ? terminalRows + 1 : terminalRows
+      },
+      cursor: {
+        x: 0,
+        // In the alt screen, keep the cursor inside the viewport. When
+        // screen.height === terminalRows exactly (content fills the alt
+        // screen), cursor.y = screen.height would trigger log-update's
+        // cursor-restore LF at the last row, scrolling one row off the top
+        // of the alt buffer and desyncing the diff's cursor model. The
+        // cursor is hidden so its position only matters for diff coords.
+        y: options.altScreen ? Math.max(0, Math.min(screen.height, terminalRows) - 1) : screen.height,
+        // Hide cursor when there's dynamic output to render (only in TTY mode)
+        visible: !isTTY || screen.height === 0
+      }
+    }
+  }
+}

ui-tui/packages/hermes-ink/src/ink/root.ts

@@ -0,0 +1,204 @@
+import { Stream } from 'stream'
+
+import type { ReactNode } from 'react'
+
+import { logForDebugging } from '../utils/debug.js'
+
+import type { FrameEvent } from './frame.js'
+import Ink, { type Options as InkOptions } from './ink.js'
+import instances from './instances.js'
+
+export type RenderOptions = {
+  /**
+   * Output stream where app will be rendered.
+   *
+   * @default process.stdout
+   */
+  stdout?: NodeJS.WriteStream
+  /**
+   * Input stream where app will listen for input.
+   *
+   * @default process.stdin
+   */
+  stdin?: NodeJS.ReadStream
+  /**
+   * Error stream.
+   * @default process.stderr
+   */
+  stderr?: NodeJS.WriteStream
+  /**
+   * Configure whether Ink should listen to Ctrl+C keyboard input and exit the app. This is needed in case `process.stdin` is in raw mode, because then Ctrl+C is ignored by default and process is expected to handle it manually.
+   *
+   * @default true
+   */
+  exitOnCtrlC?: boolean
+
+  /**
+   * Patch console methods to ensure console output doesn't mix with Ink output.
+   *
+   * @default true
+   */
+  patchConsole?: boolean
+
+  /**
+   * Called after each frame render with timing and flicker information.
+   */
+  onFrame?: (event: FrameEvent) => void
+
+  /**
+   * Called when a click lands on a cell with an OSC 8 hyperlink (or a
+   * plain-text URL the renderer detects on the same row). The host owns
+   * the actual open — `child_process.spawn` with an argv array (NOT
+   * shell-mode) to the platform's native opener: `open` on macOS,
+   * `xdg-open` on Linux/BSD, `explorer.exe` on Windows. Avoid
+   * `cmd.exe /c start` — `start` is a cmd builtin that reparses the URL
+   * through cmd's tokenizer (`&` / `|` / `^` / `<` / `>` get split or
+   * reinterpreted as command syntax), which both breaks plain URLs with
+   * `&` in query strings and undermines any protocol allowlist on the
+   * caller side. Hermes wires this in `entry.tsx`; library users who
+   * don't pass it will see clickable underline styling but no action on
+   * click in any terminal where mouse tracking is on.
+   */
+  onHyperlinkClick?: (url: string) => void
+}
+
+export type Instance = {
+  /**
+   * Replace previous root node with a new one or update props of the current root node.
+   */
+  rerender: Ink['render']
+  /**
+   * Manually unmount the whole Ink app.
+   */
+  unmount: Ink['unmount']
+  /**
+   * Returns a promise, which resolves when app is unmounted.
+   */
+  waitUntilExit: Ink['waitUntilExit']
+  cleanup: () => void
+}
+
+/**
+ * A managed Ink root, similar to react-dom's createRoot API.
+ * Separates instance creation from rendering so the same root
+ * can be reused for multiple sequential screens.
+ */
+export type Root = {
+  render: (node: ReactNode) => void
+  unmount: () => void
+  waitUntilExit: () => Promise<void>
+}
+
+export const forceRedraw = (stdout: NodeJS.WriteStream = process.stdout): boolean => {
+  const instance = instances.get(stdout)
+
+  if (!instance) {
+    return false
+  }
+
+  instance.forceRedraw()
+
+  return true
+}
+
+/**
+ * Mount a component and render the output.
+ */
+export const renderSync = (node: ReactNode, options?: NodeJS.WriteStream | RenderOptions): Instance => {
+  const opts = getOptions(options)
+
+  const inkOptions: InkOptions = {
+    stdout: process.stdout,
+    stdin: process.stdin,
+    stderr: process.stderr,
+    exitOnCtrlC: true,
+    patchConsole: true,
+    ...opts
+  }
+
+  const instance: Ink = getInstance(inkOptions.stdout, () => new Ink(inkOptions))
+
+  instance.render(node)
+
+  return {
+    rerender: instance.render,
+    unmount() {
+      instance.unmount()
+    },
+    waitUntilExit: instance.waitUntilExit,
+    cleanup: () => instances.delete(inkOptions.stdout)
+  }
+}
+
+const wrappedRender = async (node: ReactNode, options?: NodeJS.WriteStream | RenderOptions): Promise<Instance> => {
+  // Preserve the microtask boundary that `await loadYoga()` used to provide.
+  // Without it, the first render fires synchronously before async startup work
+  // (e.g. useReplBridge notification state) settles, and the subsequent Static
+  // write overwrites scrollback instead of appending below the logo.
+  await Promise.resolve()
+  const instance = renderSync(node, options)
+  logForDebugging(`[render] first ink render: ${Math.round(process.uptime() * 1000)}ms since process start`)
+
+  return instance
+}
+
+export default wrappedRender
+
+/**
+ * Create an Ink root without rendering anything yet.
+ * Like react-dom's createRoot — call root.render() to mount a tree.
+ */
+export async function createRoot({
+  stdout = process.stdout,
+  stdin = process.stdin,
+  stderr = process.stderr,
+  exitOnCtrlC = true,
+  patchConsole = true,
+  onFrame,
+  onHyperlinkClick
+}: RenderOptions = {}): Promise<Root> {
+  // See wrappedRender — preserve microtask boundary from the old WASM await.
+  await Promise.resolve()
+
+  const instance = new Ink({
+    stdout,
+    stdin,
+    stderr,
+    exitOnCtrlC,
+    patchConsole,
+    onFrame,
+    onHyperlinkClick
+  })
+
+  // Register in the instances map so that code that looks up the Ink
+  // instance by stdout (e.g. external editor pause/resume) can find it.
+  instances.set(stdout, instance)
+
+  return {
+    render: node => instance.render(node),
+    unmount: () => instance.unmount(),
+    waitUntilExit: () => instance.waitUntilExit()
+  }
+}
+
+const getOptions = (stdout: NodeJS.WriteStream | RenderOptions | undefined = {}): RenderOptions => {
+  if (stdout instanceof Stream) {
+    return {
+      stdout,
+      stdin: process.stdin
+    }
+  }
+
+  return stdout
+}
+
+const getInstance = (stdout: NodeJS.WriteStream, createInstance: () => Ink): Ink => {
+  let instance = instances.get(stdout)
+
+  if (!instance) {
+    instance = createInstance()
+    instances.set(stdout, instance)
+  }
+
+  return instance
+}