@effect-tui/react 0.1.0-alpha.1

package/src/renderer.ts

@@ -0,0 +1,661 @@
+import React, { createContext, useContext, useState, useEffect, type ReactNode } from "react"
+import { performance } from "node:perf_hooks"
+import { CellBuffer, Palette, decodeKeys, type KeyMsg } from "@effect-tui/core"
+import { reconciler, type Container } from "./reconciler/host-config.js"
+import type { HostContext } from "./reconciler/types.js"
+import { ANSI, Terminal } from "./terminal.js"
+import * as Prof from "./profiler.js"
+import { DEFAULT_FPS } from "./constants.js"
+import {
+	emitRowWithReset,
+	rowChanged,
+	rowContentWidth,
+	findChangeWindow,
+	contentHeight,
+} from "./output.js"
+
+/** Minimal write stream interface for renderer output */
+export interface TuiWriteStream {
+  write(s: string): void
+  columns: number
+  rows: number
+  on(event: string, cb: () => void): void
+}
+
+/** Minimal read stream interface for renderer input */
+export interface TuiReadStream {
+  isTTY?: boolean
+  setRawMode?(mode: boolean): void
+  resume?(): void
+  on(event: string, cb: (data: Buffer) => void): void
+}
+
+export interface TuiRenderer {
+  /** Terminal width */
+  width: number
+  /** Terminal height */
+  height: number
+  /** Request a re-render */
+  requestRender(): void
+  /** Subscribe to per-frame stats (if enabled). */
+  onFrameStats?(handler: (stats: FrameStats) => void): () => void
+  /** Subscribe to keyboard events */
+  onKey(handler: (key: KeyMsg) => void): () => void
+  /** Subscribe to paste events (bracketed paste mode). */
+  onPaste?(handler: (text: string) => void): () => void
+  /** Subscribe to resize events */
+  onResize(handler: (width: number, height: number) => void): () => void
+  /** Stop the renderer */
+  stop(): void
+  /** Manually trigger one render frame (only in manualMode) */
+  flush(): void
+}
+
+/** Internal renderer type with container reference */
+interface TuiRendererInternal extends TuiRenderer {
+  _container: Container | null
+}
+
+// Context for accessing renderer in components
+export const RendererContext = createContext<TuiRenderer | null>(null)
+
+export function useRenderer(): TuiRenderer {
+  const renderer = useContext(RendererContext)
+  if (!renderer) {
+    throw new Error("useRenderer must be used within a TUI renderer")
+  }
+  return renderer
+}
+
+/** Hook that returns terminal size and re-renders on resize */
+export function useTerminalSize(): { width: number; height: number } {
+  const renderer = useRenderer()
+  const [size, setSize] = useState({ width: renderer.width, height: renderer.height })
+
+  useEffect(() => {
+    return renderer.onResize((width, height) => {
+      setSize({ width, height })
+    })
+  }, [renderer])
+
+  return size
+}
+
+export interface RendererOptions {
+  fps?: number
+  stdout?: NodeJS.WriteStream | TuiWriteStream
+  stdin?: NodeJS.ReadStream | TuiReadStream
+  /** Render mode: "fullscreen" uses alternate buffer, "inline" renders in-place */
+  mode?: "fullscreen" | "inline"
+  /** Exit the process on Ctrl+C unless preventDefault was called. Defaults to true. */
+  exitOnCtrlC?: boolean
+  /** Enable diffed rendering (per-line). Defaults to true in runtime, false in manualMode (tests). */
+  diff?: boolean
+  /** Enable diffed rendering for inline mode (off by default; eraseLines baseline). */
+  diffInline?: boolean
+  /** Skip automatic render loop. Call flush() manually to render frames. */
+  manualMode?: boolean
+  /** Skip fullscreen/raw mode setup (for testing) */
+  skipTerminalSetup?: boolean
+  /** Enable bracketed paste (default true). */
+  enablePaste?: boolean
+  /** Optional per-frame diagnostics hook. Called after each frame is written. */
+  debug?: {
+    onFrame?: (stats: FrameStats) => void
+  }
+}
+
+export interface FrameStats {
+  mode: "fullscreen" | "inline"
+  width: number
+  height: number
+  contentHeight: number
+  bytes: number
+  frameMs: number
+  phases: {
+    clear: number
+    layout: number
+    render: number
+    diffAnsi: number
+    write: number
+  }
+  timestamp: number
+}
+
+export function createRenderer(options?: RendererOptions): TuiRenderer {
+  const fps = options?.fps ?? DEFAULT_FPS
+  const stdout: TuiWriteStream = options?.stdout ?? process.stdout
+  const stdin: TuiReadStream = options?.stdin ?? process.stdin
+  const mode = options?.mode ?? "fullscreen"
+  const exitOnCtrlC = options?.exitOnCtrlC ?? true
+  const manualMode = options?.manualMode ?? false
+  const enableDiff = options?.diff ?? !manualMode
+  const enableDiffInline = options?.diffInline ?? false
+  const skipTerminalSetup = options?.skipTerminalSetup ?? false
+  const enablePaste = options?.enablePaste ?? true
+  const debugHook = options?.debug?.onFrame
+  const PASTE_START = "\x1b[200~"
+  const PASTE_END = "\x1b[201~"
+  const PASTE_ENABLE = "\x1b[?2004h"
+  const PASTE_DISABLE = "\x1b[?2004l"
+
+  let width = stdout.columns || 80
+  let height = stdout.rows || 24
+  let lastWidth = width // Track for shrink detection (like Ink)
+  let dirty = true
+  let running = true
+  let previousHeight = 0 // For inline mode: track how many lines were rendered
+  const printedWidths = new Map<number, number>() // track rightmost printed col per row for inline diff
+  const keyHandlers = new Set<(key: KeyMsg) => void>()
+  const pasteHandlers = new Set<(text: string) => void>()
+  const resizeHandlers = new Set<(width: number, height: number) => void>()
+  const frameHandlers = new Set<(stats: FrameStats) => void>()
+  let pasteActive = false
+  let pasteBuffer = ""
+
+  const palette = new Palette()
+  let prevBuffer: CellBuffer | null = null
+  let nextBuffer: CellBuffer | null = null
+  let loop: ReturnType<typeof setInterval> | null = null
+
+  const teardown = () => {
+    if (skipTerminalSetup) return
+    if (mode === "fullscreen") {
+      stdout.write(Terminal.exitFullscreen)
+    } else {
+      stdout.write("\r\n")
+    }
+    if (enablePaste) {
+      stdout.write(PASTE_DISABLE)
+    }
+    stdout.write(Terminal.showCursor)
+    if (stdin.isTTY && stdin.setRawMode) {
+      stdin.setRawMode(false)
+    }
+  }
+
+  // The actual render logic, extracted for manual flushing
+  const renderFrame = () => {
+    const frameStart = Prof.startFrame()
+    const frameStartMs = performance.now()
+    let clearMs = 0
+    let layoutMs = 0
+    let renderMs = 0
+    let diffAnsiMs = 0
+    let writeMs = 0
+    let contentH = height
+    const container = (renderer as TuiRendererInternal)._container
+    const root = container?.root ?? null
+    if (!dirty || !root) return
+    dirty = false
+
+    // Ensure buffers exist and are correct size
+    if (!prevBuffer || !nextBuffer || prevBuffer.w !== width || prevBuffer.h !== height) {
+      prevBuffer = new CellBuffer(width, height)
+      nextBuffer = new CellBuffer(width, height)
+      prevBuffer.clear(0)
+      nextBuffer.clear(0)
+    }
+
+    // Clear next buffer
+    let t = Prof.startPhase()
+    {
+      const t0 = performance.now()
+      nextBuffer.clear(0)
+      clearMs = performance.now() - t0
+    }
+    Prof.endPhase("clear", t)
+
+    // Layout
+    t = Prof.startPhase()
+    {
+      const t0 = performance.now()
+      root.measure(width, height)
+      root.layout({ x: 0, y: 0, w: width, h: height })
+      layoutMs = performance.now() - t0
+    }
+    Prof.endPhase("layout", t)
+
+    // Render
+    t = Prof.startPhase()
+    {
+      const t0 = performance.now()
+      root.render(nextBuffer, palette)
+      renderMs = performance.now() - t0
+    }
+    Prof.endPhase("render", t)
+
+    // Output based on mode
+    t = Prof.startPhase()
+    const diffStartMs = performance.now()
+    let output = ""
+
+    if (mode === "fullscreen") {
+      // Fullscreen: optionally diff per line for minimal writes
+      if (enableDiff && prevBuffer) {
+        for (let y = 0; y < height; y++) {
+          if (!rowChanged(prevBuffer, nextBuffer, y, width)) continue
+          output += ANSI.cursor.to(1, y + 1)
+          output += ANSI.line.clear
+          output += emitRowWithReset(nextBuffer, palette, y, width)
+        }
+      } else {
+        // Full redraw (tests/manual mode)
+        stdout.write(ANSI.cursor.to(1, 1))
+        for (let y = 0; y < height; y++) {
+          output += emitRowWithReset(nextBuffer, palette, y, width)
+          if (y < height - 1) output += "\r\n"
+        }
+      }
+    } else {
+      // ============================================================
+      // INLINE MODE RENDERING
+      // ============================================================
+      // Renders in-place without alternate buffer. Key insights from Ink:
+      // - Track previousHeight to know how many lines to erase
+      // - Trim trailing spaces to prevent wrap on terminal shrink
+      // - Safety valve: clear terminal if content >= terminal height
+      // ============================================================
+
+      const newHeight = contentHeight(nextBuffer, width, height)
+      contentH = newHeight
+
+      // Safety valve: if previous content would overflow, clear terminal first
+      if (previousHeight >= height) {
+        stdout.write(ANSI.screen.clear + ANSI.cursor.to(1, 1))
+        previousHeight = 0
+      }
+
+      // Move cursor up to start of previous output (eraseLines pattern)
+      if (previousHeight > 0) {
+        output += ANSI.cursor.up(previousHeight)
+        output += ANSI.cursor.startOfLine
+      }
+
+      if (enableDiffInline && prevBuffer) {
+        // Diff-based inline rendering: only update changed regions
+        const rowsToProcess = Math.max(newHeight, previousHeight)
+
+        for (let y = 0; y < rowsToProcess; y++) {
+          // Rows beyond newHeight: clear if previously printed
+          if (y >= newHeight) {
+            if ((printedWidths.get(y) ?? 0) > 0) {
+              output += ANSI.cursor.to(y + 1, 1) + palette.sgr(0) + ANSI.line.clear
+              printedWidths.set(y, 0)
+            }
+            continue
+          }
+
+          const change = findChangeWindow(prevBuffer, nextBuffer, y, width)
+          const newW = rowContentWidth(nextBuffer, y, width)
+          const prevW = printedWidths.get(y) ?? 0
+
+          if (!change) {
+            // No change; maybe need to clear tail if content shrunk
+            if (prevW > newW) {
+              output += ANSI.cursor.to(y + 1, newW + 1) + palette.sgr(0) + ANSI.line.clearToEnd
+              printedWidths.set(y, newW)
+            }
+            continue
+          }
+
+          // Emit changed region [left..right]
+          output += ANSI.cursor.to(y + 1, change.left + 1)
+          output += emitRowWithReset(nextBuffer, palette, y, width, change.left, change.right + 1)
+
+          // Clear tail if shrunk
+          const effectiveW = Math.max(newW, change.right + 1)
+          if (prevW > effectiveW) {
+            output += ANSI.cursor.to(y + 1, effectiveW + 1) + ANSI.line.clearToEnd
+          }
+          printedWidths.set(y, effectiveW)
+        }
+
+        previousHeight = newHeight
+      } else {
+        // Full redraw inline: clear and emit each line, trimming trailing spaces
+        for (let y = 0; y < newHeight; y++) {
+          output += palette.sgr(0) + ANSI.line.clear
+          const trimmedWidth = rowContentWidth(nextBuffer, y, width)
+          output += emitRowWithReset(nextBuffer, palette, y, width, 0, trimmedWidth)
+          output += "\r\n"
+        }
+
+        // Clear any extra lines if content shrank
+        for (let y = newHeight; y < previousHeight; y++) {
+          output += palette.sgr(0) + ANSI.line.clear + "\r\n"
+        }
+
+        // Move cursor back up to end of content
+        if (previousHeight > newHeight) {
+          output += ANSI.cursor.up(previousHeight - newHeight)
+        }
+
+        previousHeight = newHeight
+      }
+    }
+
+    output += palette.sgr(0) // Reset style
+    diffAnsiMs = performance.now() - diffStartMs
+    Prof.endPhase("diff+ansi", t)
+
+    t = Prof.startPhase()
+    {
+      const t0 = performance.now()
+      stdout.write(output)
+      writeMs = performance.now() - t0
+    }
+    Prof.endPhase("write", t)
+
+    Prof.endFrame(frameStart)
+    const frameMs = performance.now() - frameStartMs
+
+    // Swap buffers
+    const tmp = prevBuffer
+    prevBuffer = nextBuffer
+    nextBuffer = tmp
+
+    const stats: FrameStats = {
+      mode,
+      width,
+      height,
+      contentHeight: contentH,
+      bytes: Buffer.byteLength(output, "utf8"),
+      frameMs,
+      phases: {
+        clear: clearMs,
+        layout: layoutMs,
+        render: renderMs,
+        diffAnsi: diffAnsiMs,
+        write: writeMs,
+      },
+      timestamp: performance.now(),
+    }
+
+    if (debugHook) debugHook(stats)
+    if (frameHandlers.size > 0) {
+      for (const handler of frameHandlers) handler(stats)
+    }
+  }
+
+  const renderer: TuiRenderer = {
+    get width() {
+      return width
+    },
+    get height() {
+      return height
+    },
+    requestRender() {
+      dirty = true
+    },
+    onKey(handler: (key: KeyMsg) => void) {
+      keyHandlers.add(handler)
+      return () => keyHandlers.delete(handler)
+    },
+    onPaste(handler: (text: string) => void) {
+      pasteHandlers.add(handler)
+      return () => pasteHandlers.delete(handler)
+    },
+    onResize(handler: (width: number, height: number) => void) {
+      resizeHandlers.add(handler)
+      return () => resizeHandlers.delete(handler)
+    },
+    onFrameStats(handler: (stats: FrameStats) => void) {
+      frameHandlers.add(handler)
+      return () => frameHandlers.delete(handler)
+    },
+    stop() {
+      running = false
+      if (loop) {
+        clearInterval(loop)
+        loop = null
+      }
+      teardown()
+    },
+    flush() {
+      renderFrame()
+    },
+  }
+
+  // Terminal setup (skip for testing)
+  if (!skipTerminalSetup) {
+    if (mode === "fullscreen") {
+      stdout.write(Terminal.enterFullscreen)
+    }
+    // Hide cursor during rendering (both modes)
+    stdout.write(Terminal.hideCursor)
+    if (enablePaste) stdout.write(PASTE_ENABLE)
+
+    if (stdin.isTTY && stdin.setRawMode) {
+      stdin.setRawMode(true)
+      stdin.resume?.()
+    }
+  }
+
+  // Handle keyboard input (and bracketed paste)
+  stdin.on("data", (data: Buffer) => {
+    let chunk = data.toString("utf8")
+
+    const emitKeys = (str: string) => {
+      if (!str) return
+      const keys = decodeKeys(Buffer.from(str, "utf8"))
+      for (const key of keys) {
+        const wrapped: KeyMsg = {
+          ...key,
+          defaultPrevented: false,
+          preventDefault() {
+            wrapped.defaultPrevented = true
+          },
+        }
+        for (const handler of keyHandlers) {
+          if (wrapped.defaultPrevented) break
+          handler(wrapped)
+        }
+
+        // Default Ctrl+C handling - exit unless user called preventDefault()
+        if (exitOnCtrlC && !wrapped.defaultPrevented && key.ctrl && key.text === "c") {
+          process.exit(0)
+        }
+      }
+    }
+
+    while (chunk.length > 0) {
+      if (pasteActive) {
+        const endIdx = chunk.indexOf(PASTE_END)
+        if (endIdx >= 0) {
+          pasteBuffer += chunk.slice(0, endIdx)
+          pasteHandlers.forEach((h) => h(pasteBuffer))
+          pasteBuffer = ""
+          pasteActive = false
+          chunk = chunk.slice(endIdx + PASTE_END.length)
+          continue
+        } else {
+          pasteBuffer += chunk
+          chunk = ""
+          break
+        }
+      }
+
+      const startIdx = chunk.indexOf(PASTE_START)
+      if (startIdx >= 0) {
+        // Emit any keys before the paste start
+        emitKeys(chunk.slice(0, startIdx))
+        pasteActive = true
+        pasteBuffer = ""
+        chunk = chunk.slice(startIdx + PASTE_START.length)
+        continue
+      }
+
+      // No paste markers; treat as normal keys
+      emitKeys(chunk)
+      chunk = ""
+    }
+
+    dirty = true
+  })
+
+  // Handle resize - render synchronously like Ink does
+  stdout.on("resize", () => {
+    const newWidth = stdout.columns || 80
+    const newHeight = stdout.rows || 24
+
+    // Fullscreen: clear entire screen on resize to prevent artifacts from terminal reflow
+    // The terminal may leave stale content that our diff-based rendering doesn't see
+    if (mode === "fullscreen") {
+      stdout.write(ANSI.screen.clear + ANSI.cursor.to(1, 1))
+    } else if (mode === "inline" && newWidth < lastWidth && previousHeight > 0) {
+      // Inline: on width shrink, previous content may have wrapped to MORE lines
+      // than previousHeight. Clear from content start to END OF SCREEN to catch all.
+      stdout.write(ANSI.cursor.up(previousHeight) + ANSI.cursor.startOfLine)
+      stdout.write(ANSI.screen.clearToEnd)
+      previousHeight = 0
+    }
+
+    width = newWidth
+    height = newHeight
+    lastWidth = newWidth
+    prevBuffer = null
+    nextBuffer = null
+    dirty = true
+
+    // Notify resize handlers
+    for (const handler of resizeHandlers) {
+      handler(newWidth, newHeight)
+    }
+
+    // Render immediately on resize (like Ink) to prevent cursor corruption
+    renderFrame()
+  })
+
+  // Automatic render loop (skip in manual mode)
+  if (!manualMode) {
+    const frameMs = 1000 / fps
+    loop = setInterval(() => {
+      if (!running) {
+        if (loop) clearInterval(loop)
+        teardown()
+        return
+      }
+      renderFrame()
+    }, frameMs)
+  }
+  // Store container reference for direct root access
+  ;(renderer as TuiRendererInternal)._container = null
+
+  return renderer
+}
+
+export interface Root {
+  render(element: ReactNode, sync?: boolean): void
+  unmount(): void
+}
+
+export function createRoot(renderer: TuiRenderer): Root {
+  const hostContext: HostContext = {
+    requestRender: () => renderer.requestRender(),
+  }
+
+  const container: Container = {
+    root: null,
+    ctx: hostContext,
+  }
+
+  const fiberRoot = reconciler.createContainer(
+    container,
+    0, // LegacyRoot
+    null, // hydrationCallbacks
+    false, // isStrictMode
+    null, // concurrentUpdatesByDefaultOverride
+    "", // identifierPrefix
+    (err: Error) => console.error(err), // onUncaughtError
+    (err: Error) => console.error(err), // onCaughtError
+    (err: Error) => console.error(err), // onRecoverableError
+    () => {}, // onDefaultTransitionIndicator
+    null, // transitionCallbacks
+  )
+
+  // Give renderer direct access to container
+  ;(renderer as TuiRendererInternal)._container = container
+
+  const reconcilerAny: any = reconciler
+  const runSync = reconcilerAny.flushSync?.bind(reconcilerAny) ?? ((fn: () => void) => fn())
+
+  return {
+    render(element: ReactNode, sync = false) {
+      const wrapped = React.createElement(RendererContext.Provider, { value: renderer }, element)
+      if (sync) {
+        runSync(() => {
+          reconciler.updateContainer(wrapped, fiberRoot, null, null)
+        })
+        renderer.requestRender()
+      } else {
+        reconciler.updateContainer(wrapped, fiberRoot, null, () => {
+          renderer.requestRender()
+        })
+      }
+    },
+    unmount() {
+      reconciler.updateContainer(null, fiberRoot, null, () => {
+        renderer.stop()
+      })
+    },
+  }
+}
+
+// High-level convenience API (Ink-style)
+export interface RenderInstance {
+  renderer: TuiRenderer
+  root: Root
+  rerender(element: ReactNode): void
+  unmount(): void
+  waitUntilExit(): Promise<void>
+}
+
+/**
+ * Render a React tree to the terminal in one call.
+ * Returns helpers similar to Ink: rerender, unmount, waitUntilExit.
+ */
+export function render(element: ReactNode, options?: RendererOptions): RenderInstance {
+  const renderer = createRenderer(options)
+  const root = createRoot(renderer)
+
+  // Initial render (sync to avoid flicker before the loop runs)
+  root.render(element, true)
+
+  let resolved = false
+  let resolveExit: (() => void) | null = null
+  const exitPromise = new Promise<void>((resolve) => {
+    resolveExit = () => {
+      if (resolved) return
+      resolved = true
+      resolve()
+    }
+  })
+
+  const onExit = () => {
+    if (!resolved) {
+      renderer.stop()
+      resolveExit?.()
+    }
+  }
+  process.once("exit", onExit)
+
+  const unmount = () => {
+    process.off("exit", onExit)
+    renderer.stop()
+    resolveExit?.()
+  }
+
+  const rerender = (next: ReactNode) => {
+    if (resolved) return
+    root.render(next)
+  }
+
+  return {
+    renderer,
+    root,
+    rerender,
+    unmount,
+    waitUntilExit: () => exitPromise,
+  }
+}