nastech-tui 0.0.1

package/packages/nastech-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
+  )
+}

package/packages/nastech-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

package/packages/nastech-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])
+}

package/packages/nastech-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
+}

package/packages/nastech-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])
+}

package/packages/nastech-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]
+}

package/packages/nastech-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
+}

package/packages/nastech-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()
+  })
+})

package/packages/nastech-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()
+  })
+})