nastech-tui 0.0.1

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

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

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