@vsuryav/agent-sim 0.1.0

package/src/engine/ink/render-to-screen.ts

@@ -0,0 +1,231 @@
+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 {
+  CellWidth,
+  CharPool,
+  cellAtIndex,
+  createScreen,
+  HyperlinkPool,
+  type Screen,
+  StylePool,
+  setCellStyleId,
+} 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()
+    // @ts-expect-error react-reconciler 0.33 takes 10 args; @types says 11
+    container = reconciler.createContainer(
+      root,
+      LegacyRoot,
+      null,
+      false,
+      null,
+      'search-render',
+      noop,
+      noop,
+      noop,
+      noop,
+    )
+  }
+
+  const t0 = performance.now()
+  // @ts-expect-error updateContainerSync exists but not in @types
+  reconciler.updateContainerSync(el, container, null, noop)
+  // @ts-expect-error flushSyncWork exists but not in @types
+  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.
+  // @ts-expect-error updateContainerSync exists but not in @types
+  reconciler.updateContainerSync(null, container, null, noop)
+  // @ts-expect-error flushSyncWork exists but not in @types
+  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/src/engine/ink/renderer.ts

@@ -0,0 +1,178 @@
+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, {
+  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 {
+      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/src/engine/ink/root.ts

@@ -0,0 +1,184 @@
+import type { ReactNode } from 'react'
+import { logForDebugging } from '../utils/debug.js'
+import { Stream } from 'stream'
+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
+}
+
+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>
+}
+
+/**
+ * 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,
+}: 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,
+  })
+
+  // 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
+}