@silvery/term 0.3.0

package/src/inspector.ts

@@ -0,0 +1,155 @@
+/**
+ * silvery Inspector — Debug introspection for rendering pipeline.
+ *
+ * Activate with SILVERY_DEV=1 env var or by calling enableInspector().
+ * Outputs debug info to stderr or a log file (never to the TUI stdout).
+ *
+ * Features:
+ * - Component tree dump (with layout rects)
+ * - Focus path display
+ * - Render stats (frame time, dirty rows, cell changes)
+ * - Dirty region visualization
+ *
+ * This is DISTINCT from React DevTools (devtools.ts). This inspector provides
+ * silvery-specific introspection: render pipeline stats, focus tree, dirty regions,
+ * layout info.
+ */
+
+import type { createWriteStream as createWriteStreamType } from "node:fs"
+import type { RenderStats } from "./scheduler"
+import type { TeaNode } from "@silvery/tea/types"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface InspectorOptions {
+  /** Output stream (default: process.stderr) */
+  output?: NodeJS.WritableStream
+  /** Log file path (overrides output stream) */
+  logFile?: string
+  /** Include layout rects in tree dump */
+  showLayout?: boolean
+  /** Include style info in tree dump */
+  showStyles?: boolean
+}
+
+// =============================================================================
+// State
+// =============================================================================
+
+let inspectorEnabled = false
+let inspectorOutput: NodeJS.WritableStream = process.stderr
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+/** Enable the silvery inspector. */
+export function enableInspector(options?: InspectorOptions): void {
+  inspectorEnabled = true
+  if (options?.logFile) {
+    // Dynamic require to avoid pulling in fs for non-inspector users
+    const fs: { createWriteStream: typeof createWriteStreamType } = require("node:fs")
+    inspectorOutput = fs.createWriteStream(options.logFile, { flags: "a" })
+  } else if (options?.output) {
+    inspectorOutput = options.output
+  } else {
+    inspectorOutput = process.stderr
+  }
+}
+
+/** Disable the inspector. */
+export function disableInspector(): void {
+  inspectorEnabled = false
+}
+
+/** Check if inspector is active. */
+export function isInspectorEnabled(): boolean {
+  return inspectorEnabled
+}
+
+/**
+ * Log render stats after each frame.
+ *
+ * Called by the scheduler after executeRender completes. When the inspector
+ * is disabled this is a no-op (zero overhead).
+ */
+export function inspectFrame(stats: RenderStats): void {
+  if (!inspectorEnabled) return
+  const line =
+    `[silvery] frame #${stats.renderCount} ` +
+    `${stats.lastRenderTime.toFixed(1)}ms ` +
+    `avg=${stats.avgRenderTime.toFixed(1)}ms ` +
+    `skipped=${stats.skippedCount}\n`
+  inspectorOutput.write(line)
+}
+
+/**
+ * Dump the component tree structure as indented text.
+ *
+ * Walks the SilveryNode tree and formats each node with its type, testID,
+ * layout rect, and dirty flags.
+ */
+export function inspectTree(rootNode: TeaNode, options?: { depth?: number; showLayout?: boolean }): string {
+  const maxDepth = options?.depth ?? 10
+  const showLayout = options?.showLayout ?? true
+  const lines: string[] = []
+
+  function walk(node: TeaNode, indent: number): void {
+    if (indent > maxDepth) return
+
+    const prefix = "  ".repeat(indent)
+    const type = node.type
+    const testID = (node.props as Record<string, unknown>)?.testID
+    const idStr = testID ? ` #${testID}` : ""
+
+    // Layout rect from computed layout node or contentRect
+    let rectStr = ""
+    if (showLayout) {
+      if (node.contentRect) {
+        const r = node.contentRect
+        rectStr = ` [${r.x},${r.y} ${r.width}x${r.height}]`
+      } else if (node.layoutNode) {
+        const ln = node.layoutNode
+        rectStr = ` [${ln.getComputedLeft()},${ln.getComputedTop()} ${ln.getComputedWidth()}x${ln.getComputedHeight()}]`
+      }
+    }
+
+    // Dirty flags
+    const dirtyFlags: string[] = []
+    if (node.layoutDirty) dirtyFlags.push("layout")
+    if (node.contentDirty) dirtyFlags.push("content")
+    if (node.paintDirty) dirtyFlags.push("paint")
+    if (node.bgDirty) dirtyFlags.push("bg")
+    if (node.subtreeDirty) dirtyFlags.push("subtree")
+    if (node.childrenDirty) dirtyFlags.push("children")
+    const dirtyStr = dirtyFlags.length > 0 ? ` dirty=[${dirtyFlags.join(",")}]` : ""
+
+    // Text content (for text nodes)
+    const textStr = node.textContent
+      ? ` "${node.textContent.slice(0, 30)}${node.textContent.length > 30 ? "..." : ""}"`
+      : ""
+
+    lines.push(`${prefix}${type}${idStr}${rectStr}${dirtyStr}${textStr}`)
+
+    for (const child of node.children) {
+      walk(child, indent + 1)
+    }
+  }
+
+  walk(rootNode, 0)
+  return lines.join("\n")
+}
+
+/**
+ * Auto-enable if SILVERY_DEV=1 is set.
+ *
+ * Call this at startup to respect the environment variable convention.
+ */
+export function autoEnableInspector(): void {
+  if (process.env.SILVERY_DEV === "1" || process.env.SILVERY_DEV === "true") {
+    const logFile = process.env.SILVERY_DEV_LOG
+    enableInspector(logFile ? { logFile } : undefined)
+  }
+}

package/src/kitty-detect.ts

@@ -0,0 +1,95 @@
+/**
+ * Kitty keyboard protocol detection.
+ *
+ * Sends CSI ? u and parses the response to determine whether the terminal
+ * supports the Kitty keyboard protocol and which flags it reports.
+ */
+
+import { queryKittyKeyboard } from "./output"
+
+export interface KittyDetectResult {
+  /** Whether the terminal responded to the Kitty protocol query */
+  supported: boolean
+  /** Bitfield of KittyFlags the terminal reported supporting (0 if unsupported) */
+  flags: number
+  /** Any non-response data that was read during detection (regular input that arrived) */
+  buffered?: string
+}
+
+/** Regex to match a Kitty keyboard query response: CSI ? <flags> u */
+const KITTY_RESPONSE_RE = /\x1b\[\?(\d+)u/
+
+/**
+ * Detect Kitty keyboard protocol support.
+ *
+ * Sends CSI ? u to the terminal and waits for a response.
+ * Supported terminals respond with CSI ? flags u.
+ * Unsupported terminals either ignore the query or echo it.
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin (should resolve with data or null on timeout)
+ * @param timeoutMs How long to wait for response (default: 200ms)
+ */
+export async function detectKittySupport(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  timeoutMs = 200,
+): Promise<KittyDetectResult> {
+  write(queryKittyKeyboard())
+
+  const data = await read(timeoutMs)
+  if (data == null) {
+    return { supported: false, flags: 0 }
+  }
+
+  const match = KITTY_RESPONSE_RE.exec(data)
+  if (!match) {
+    return { supported: false, flags: 0, buffered: data }
+  }
+
+  const flags = parseInt(match[1]!, 10)
+  // Anything outside the matched response is buffered input
+  const before = data.slice(0, match.index)
+  const after = data.slice(match.index + match[0].length)
+  const buffered = before + after
+  return { supported: true, flags, buffered: buffered || undefined }
+}
+
+/**
+ * Detect Kitty support using real stdin/stdout.
+ * Convenience wrapper around detectKittySupport.
+ */
+export async function detectKittyFromStdio(
+  stdout: { write: (s: string) => boolean | void },
+  stdin: NodeJS.ReadStream,
+  timeoutMs = 200,
+): Promise<KittyDetectResult> {
+  const wasRaw = stdin.isRaw
+  if (!wasRaw) stdin.setRawMode(true)
+
+  try {
+    const write = (s: string) => {
+      stdout.write(s)
+    }
+
+    const read = (ms: number): Promise<string | null> =>
+      new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          stdin.removeListener("data", onData)
+          resolve(null)
+        }, ms)
+
+        function onData(chunk: Buffer) {
+          clearTimeout(timer)
+          stdin.removeListener("data", onData)
+          resolve(chunk.toString())
+        }
+
+        stdin.on("data", onData)
+      })
+
+    return await detectKittySupport(write, read, timeoutMs)
+  } finally {
+    if (!wasRaw) stdin.setRawMode(false)
+  }
+}

package/src/kitty-manager.ts

@@ -0,0 +1,160 @@
+/**
+ * Kitty keyboard protocol manager.
+ *
+ * Handles lifecycle (enable/disable/auto-detect) for the Kitty keyboard
+ * protocol. Used by both test and interactive rendering paths.
+ *
+ * @see https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+ */
+
+import { enableKittyKeyboard, disableKittyKeyboard, queryKittyKeyboard } from "./output"
+
+/** Regex to match a Kitty keyboard query response: CSI ? <digits> u */
+const KITTY_RESPONSE_RE = /\x1b\[\?(\d+)u/
+
+/** Regex to match a partial Kitty keyboard query response: ESC [ ? <digits> (at least one digit, no trailing 'u') */
+const KITTY_PARTIAL_RE = /\x1b\[\?\d+$/
+
+/** Kitty protocol manager handle. */
+export interface KittyManager {
+  /** Whether the kitty keyboard protocol is currently enabled. */
+  enabled: boolean
+  /** Disable the protocol and clean up any pending detection. */
+  cleanup(): void
+}
+
+/** Options for configuring the kitty keyboard protocol manager. */
+export interface KittyManagerOptions {
+  /** Detection mode: "enabled" activates immediately, "auto" probes the terminal, "disabled" does nothing. */
+  mode?: "auto" | "enabled" | "disabled"
+  /** Bitmask of KittyFlags to enable. Defaults to KittyFlags.DISAMBIGUATE (1). */
+  flags?: number
+}
+
+/**
+ * Create a kitty protocol manager that handles setup and teardown.
+ *
+ * Supports three modes:
+ * - "enabled": enable immediately if stdin/stdout are TTYs
+ * - "auto": probe the terminal for support, enable if detected
+ * - "disabled" / undefined: do nothing
+ */
+export function createKittyManager(
+  stdin: NodeJS.ReadStream,
+  stdout: NodeJS.WriteStream,
+  opts: KittyManagerOptions | undefined,
+): KittyManager {
+  let enabled = false
+  let cancelDetection: (() => void) | undefined
+
+  function enable(flagBitmask: number): void {
+    stdout.write(enableKittyKeyboard(flagBitmask))
+    enabled = true
+  }
+
+  if (opts) {
+    const mode = opts.mode ?? "auto"
+    const flagBitmask = opts.flags ?? 1 // Default: DISAMBIGUATE
+    const isTTY = (stdin as any)?.isTTY && (stdout as any)?.isTTY
+
+    if (isTTY) {
+      if (mode === "enabled") {
+        enable(flagBitmask)
+      } else if (mode === "auto") {
+        cancelDetection = initKittyAutoDetection(stdin, stdout, flagBitmask, enable)
+      }
+    }
+  }
+
+  return {
+    get enabled() {
+      return enabled
+    },
+    cleanup() {
+      if (cancelDetection) {
+        cancelDetection()
+        cancelDetection = undefined
+      }
+      if (enabled) {
+        stdout.write(disableKittyKeyboard())
+        enabled = false
+      }
+    },
+  }
+}
+
+/**
+ * Initialize kitty keyboard auto-detection.
+ *
+ * Queries the terminal for support, listens for the response, and enables
+ * the protocol if supported. Returns a cleanup function to cancel detection.
+ *
+ * Uses a synchronous event-based approach (not async) because render() must
+ * return synchronously. Delegates to @silvery/term for escape sequences.
+ */
+function initKittyAutoDetection(
+  stdin: NodeJS.ReadStream,
+  stdout: NodeJS.WriteStream,
+  flagBitmask: number,
+  onEnable: (flags: number) => void,
+): () => void {
+  // Buffer incoming data as raw bytes to preserve binary integrity (e.g., split UTF-8 sequences).
+  // We always work with the concatenated raw bytes and only decode to string for regex matching.
+  const rawChunks: Buffer[] = []
+  let cleaned = false
+  let unmounted = false
+
+  /** Decode the full concatenated buffer to string for regex matching. */
+  function getBufferAsString(): string {
+    return Buffer.concat(rawChunks).toString()
+  }
+
+  const cleanup = (): void => {
+    if (cleaned) return
+    cleaned = true
+    clearTimeout(timer)
+    stdin.removeListener("data", onData)
+
+    // Re-emit any buffered data that wasn't the protocol response.
+    // Strip both complete protocol responses and partial protocol prefixes
+    // (e.g., "\x1b[?1" without the trailing "u") — these are protocol artifacts, not user data.
+    const allBytes = Buffer.concat(rawChunks)
+    rawChunks.length = 0
+    const fullString = allBytes.toString()
+    let remaining = fullString.replace(KITTY_RESPONSE_RE, "")
+    remaining = remaining.replace(KITTY_PARTIAL_RE, "")
+
+    if (remaining.length > 0) {
+      // Find where the remaining content starts in the original byte stream
+      // by computing the byte offset of the protocol prefix that was stripped.
+      const protocolPrefix = fullString.slice(0, fullString.indexOf(remaining))
+      const prefixByteLen = Buffer.byteLength(protocolPrefix)
+      stdin.unshift(allBytes.subarray(prefixByteLen))
+    }
+  }
+
+  const onData = (data: Uint8Array | string): void => {
+    // Buffer raw bytes. For strings, convert to Buffer to preserve byte-level integrity.
+    rawChunks.push(typeof data === "string" ? Buffer.from(data) : Buffer.from(data))
+
+    // Decode the full accumulated buffer to check for the protocol response.
+    // This ensures correct handling of multi-byte sequences split across chunks.
+    if (KITTY_RESPONSE_RE.test(getBufferAsString())) {
+      cleanup()
+      if (!unmounted) {
+        onEnable(flagBitmask)
+      }
+    }
+  }
+
+  // Attach listener before writing the query so synchronous responses are not missed
+  stdin.on("data", onData)
+  const timer = setTimeout(cleanup, 200)
+
+  stdout.write(queryKittyKeyboard())
+
+  return () => {
+    unmounted = true
+    cleanup()
+  }
+}

package/src/layout-engine.ts

@@ -0,0 +1,296 @@
+/**
+ * Layout Engine Abstraction
+ *
+ * Provides a pluggable interface for layout engines (Yoga, Flexily, etc.)
+ * This allows silvery to use different layout backends without code changes.
+ */
+
+// ============================================================================
+// Measure Function Types
+// ============================================================================
+
+/**
+ * Measure mode determines how the width/height constraint should be interpreted.
+ */
+export type MeasureMode = "undefined" | "exactly" | "at-most"
+
+/**
+ * Measure function callback for intrinsic sizing.
+ * Called when a node needs to determine its size based on content.
+ */
+export type MeasureFunc = (
+  width: number,
+  widthMode: MeasureMode,
+  height: number,
+  heightMode: MeasureMode,
+) => { width: number; height: number }
+
+// ============================================================================
+// Layout Node Interface
+// ============================================================================
+
+/**
+ * Abstract layout node interface.
+ * Represents a single node in the layout tree.
+ */
+export interface LayoutNode {
+  // Tree operations
+  insertChild(child: LayoutNode, index: number): void
+  removeChild(child: LayoutNode): void
+  free(): void
+
+  // Measure function
+  setMeasureFunc(measureFunc: MeasureFunc): void
+
+  // Dirty tracking
+  markDirty(): void
+
+  // Dimension setters
+  setWidth(value: number): void
+  setWidthPercent(value: number): void
+  setWidthAuto(): void
+  setHeight(value: number): void
+  setHeightPercent(value: number): void
+  setHeightAuto(): void
+  setMinWidth(value: number): void
+  setMinWidthPercent(value: number): void
+  setMinHeight(value: number): void
+  setMinHeightPercent(value: number): void
+  setMaxWidth(value: number): void
+  setMaxWidthPercent(value: number): void
+  setMaxHeight(value: number): void
+  setMaxHeightPercent(value: number): void
+
+  // Flex properties
+  setFlexGrow(value: number): void
+  setFlexShrink(value: number): void
+  setFlexBasis(value: number): void
+  setFlexBasisPercent(value: number): void
+  setFlexBasisAuto(): void
+  setFlexDirection(direction: number): void
+  setFlexWrap(wrap: number): void
+
+  // Alignment
+  setAlignItems(align: number): void
+  setAlignSelf(align: number): void
+  setAlignContent(align: number): void
+  setJustifyContent(justify: number): void
+
+  // Spacing
+  setPadding(edge: number, value: number): void
+  setMargin(edge: number, value: number): void
+  setBorder(edge: number, value: number): void
+  setGap(gutter: number, value: number): void
+
+  // Display & Position
+  setDisplay(display: number): void
+  setPositionType(positionType: number): void
+  setPosition(edge: number, value: number): void
+  setPositionPercent(edge: number, value: number): void
+  setOverflow(overflow: number): void
+
+  // Aspect Ratio
+  setAspectRatio(value: number): void
+
+  // Layout calculation
+  calculateLayout(width: number, height: number, direction?: number): void
+
+  // Layout results
+  getComputedLeft(): number
+  getComputedTop(): number
+  getComputedWidth(): number
+  getComputedHeight(): number
+}
+
+// ============================================================================
+// Branded Types for Type Safety
+// ============================================================================
+
+/**
+ * Branded types prevent accidentally mixing up layout constant categories.
+ * E.g., you can't pass an AlignValue where a FlexDirectionValue is expected.
+ */
+export type FlexDirectionValue = number & { readonly __brand: "FlexDirection" }
+export type WrapValue = number & { readonly __brand: "Wrap" }
+export type AlignValue = number & { readonly __brand: "Align" }
+export type JustifyValue = number & { readonly __brand: "Justify" }
+export type EdgeValue = number & { readonly __brand: "Edge" }
+export type GutterValue = number & { readonly __brand: "Gutter" }
+export type DisplayValue = number & { readonly __brand: "Display" }
+export type PositionTypeValue = number & { readonly __brand: "PositionType" }
+export type OverflowValue = number & { readonly __brand: "Overflow" }
+export type DirectionValue = number & { readonly __brand: "Direction" }
+export type MeasureModeValue = number & { readonly __brand: "MeasureMode" }
+
+// ============================================================================
+// Layout Constants Interface
+// ============================================================================
+
+/**
+ * Constants for layout configuration.
+ * These are the same across Yoga and Flexily.
+ * Uses branded types for compile-time safety.
+ */
+export interface LayoutConstants {
+  // Flex Direction
+  FLEX_DIRECTION_COLUMN: FlexDirectionValue
+  FLEX_DIRECTION_COLUMN_REVERSE: FlexDirectionValue
+  FLEX_DIRECTION_ROW: FlexDirectionValue
+  FLEX_DIRECTION_ROW_REVERSE: FlexDirectionValue
+
+  // Wrap
+  WRAP_NO_WRAP: WrapValue
+  WRAP_WRAP: WrapValue
+  WRAP_WRAP_REVERSE: WrapValue
+
+  // Align
+  ALIGN_AUTO: AlignValue
+  ALIGN_FLEX_START: AlignValue
+  ALIGN_CENTER: AlignValue
+  ALIGN_FLEX_END: AlignValue
+  ALIGN_STRETCH: AlignValue
+  ALIGN_BASELINE: AlignValue
+  ALIGN_SPACE_BETWEEN: AlignValue
+  ALIGN_SPACE_AROUND: AlignValue
+  ALIGN_SPACE_EVENLY: AlignValue
+
+  // Justify
+  JUSTIFY_FLEX_START: JustifyValue
+  JUSTIFY_CENTER: JustifyValue
+  JUSTIFY_FLEX_END: JustifyValue
+  JUSTIFY_SPACE_BETWEEN: JustifyValue
+  JUSTIFY_SPACE_AROUND: JustifyValue
+  JUSTIFY_SPACE_EVENLY: JustifyValue
+
+  // Edge
+  EDGE_LEFT: EdgeValue
+  EDGE_TOP: EdgeValue
+  EDGE_RIGHT: EdgeValue
+  EDGE_BOTTOM: EdgeValue
+  EDGE_HORIZONTAL: EdgeValue
+  EDGE_VERTICAL: EdgeValue
+  EDGE_ALL: EdgeValue
+
+  // Gutter
+  GUTTER_COLUMN: GutterValue
+  GUTTER_ROW: GutterValue
+  GUTTER_ALL: GutterValue
+
+  // Display
+  DISPLAY_FLEX: DisplayValue
+  DISPLAY_NONE: DisplayValue
+
+  // Position Type
+  POSITION_TYPE_STATIC: PositionTypeValue
+  POSITION_TYPE_RELATIVE: PositionTypeValue
+  POSITION_TYPE_ABSOLUTE: PositionTypeValue
+
+  // Overflow
+  OVERFLOW_VISIBLE: OverflowValue
+  OVERFLOW_HIDDEN: OverflowValue
+  OVERFLOW_SCROLL: OverflowValue
+
+  // Direction
+  DIRECTION_LTR: DirectionValue
+
+  // Measure Mode
+  MEASURE_MODE_UNDEFINED: MeasureModeValue
+  MEASURE_MODE_EXACTLY: MeasureModeValue
+  MEASURE_MODE_AT_MOST: MeasureModeValue
+}
+
+// ============================================================================
+// Layout Engine Interface
+// ============================================================================
+
+/**
+ * Abstract layout engine interface.
+ * Implementations can wrap Yoga, Flexily, or other layout engines.
+ */
+export interface LayoutEngine {
+  /** Create a new layout node */
+  createNode(): LayoutNode
+
+  /** Layout constants for this engine */
+  readonly constants: LayoutConstants
+
+  /** Engine name for debugging */
+  readonly name: string
+}
+
+// ============================================================================
+// Global Layout Engine Management
+// ============================================================================
+
+let layoutEngine: LayoutEngine | null = null
+
+/**
+ * Set the global layout engine instance.
+ * Must be called before rendering.
+ */
+export function setLayoutEngine(engine: LayoutEngine): void {
+  layoutEngine = engine
+}
+
+/**
+ * Get the global layout engine instance.
+ * Throws if not initialized.
+ */
+export function getLayoutEngine(): LayoutEngine {
+  if (!layoutEngine) {
+    throw new Error("Layout engine not initialized. Call setLayoutEngine() or initYoga()/initFlexily() first.")
+  }
+  return layoutEngine
+}
+
+/**
+ * Check if a layout engine is initialized.
+ */
+export function isLayoutEngineInitialized(): boolean {
+  return layoutEngine !== null
+}
+
+/**
+ * Get the layout constants from the current engine.
+ * Convenience function for accessing constants.
+ */
+export function getConstants(): LayoutConstants {
+  return getLayoutEngine().constants
+}
+
+// ============================================================================
+// Default Engine Initialization
+// ============================================================================
+
+/**
+ * Layout engine type for configuration.
+ *
+ * - 'flexily': Zero-allocation Flexily (default, optimized for high-frequency layout)
+ * - 'flexily-classic': Classic Flexily algorithm (for debugging/compatibility)
+ * - 'yoga': Facebook's WASM-based flexbox (most mature)
+ */
+export type LayoutEngineType = "flexily" | "yoga"
+
+/**
+ * Initialize the layout engine if not already set.
+ *
+ * @param engineType - 'flexily', 'flexily-classic', or 'yoga'. If not provided, checks
+ *                     SILVERY_ENGINE env var, then defaults to 'flexily'.
+ */
+export async function ensureDefaultLayoutEngine(engineType?: LayoutEngineType): Promise<void> {
+  if (isLayoutEngineInitialized()) {
+    return
+  }
+
+  // Resolve engine type: option → env → 'flexily'
+  const resolved = engineType ?? (process.env.SILVERY_ENGINE?.toLowerCase() as LayoutEngineType) ?? "flexily"
+
+  if (resolved === "yoga") {
+    const { initYogaEngine } = await import("./adapters/yoga-adapter.js")
+    setLayoutEngine(await initYogaEngine())
+  } else {
+    // 'flexily' (default) uses zero-allocation engine
+    const { createFlexilyZeroEngine } = await import("./adapters/flexily-zero-adapter.js")
+    setLayoutEngine(createFlexilyZeroEngine())
+  }
+}