nastech-tui 0.0.1

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

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

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

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

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

package/packages/nastech-ink/nastech-ink/src/ink/global.d.ts

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

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