@silvery/term 0.3.0

package/src/pipeline/types.ts

@@ -0,0 +1,161 @@
+/**
+ * Shared types for the Silvery render pipeline.
+ */
+
+import type { Cell } from "../buffer"
+import type { Measurer } from "../unicode"
+
+/**
+ * Context threaded through the render pipeline.
+ *
+ * Carries per-render resources that were previously accessed via module-level
+ * globals (e.g., `_scopedMeasurer` + `runWithMeasurer()`). Threading context
+ * explicitly eliminates save/restore patterns and makes the pipeline pure.
+ *
+ * Phase 1: measurer only.
+ * Phase 2: NodeRenderState for per-node params.
+ * Phase 3: instrumentation/diagnostics fields (optional — fall back to
+ *   module-level globals when absent for backward compat).
+ */
+export interface PipelineContext {
+  readonly measurer: Measurer
+  // Phase 3: instrumentation (all optional for backward compat)
+  readonly instrumentEnabled?: boolean
+  readonly stats?: ContentPhaseStats
+  readonly nodeTrace?: NodeTraceEntry[]
+  readonly nodeTraceEnabled?: boolean
+  readonly bgConflictMode?: BgConflictMode
+  readonly warnedBgConflicts?: Set<string>
+}
+
+/**
+ * Background conflict detection mode.
+ * Set via SILVERY_BG_CONFLICT env var: 'ignore' | 'warn' | 'throw'
+ */
+export type BgConflictMode = "ignore" | "warn" | "throw"
+
+/**
+ * Per-node trace entry for SILVERY_STRICT diagnosis.
+ */
+export interface NodeTraceEntry {
+  id: string
+  type: string
+  depth: number
+  rect: string
+  prevLayout: string
+  hasPrev: boolean
+  ancestorCleared: boolean
+  flags: string
+  decision: string
+  layoutChanged: boolean
+  contentAreaAffected?: boolean
+  parentRegionCleared?: boolean
+  parentRegionChanged?: boolean
+  childHasPrev?: boolean
+  childAncestorCleared?: boolean
+  skipBgFill?: boolean
+  bgColor?: string
+}
+
+/**
+ * Mutable stats counters for content phase instrumentation.
+ * Reset after each contentPhase call.
+ */
+export interface ContentPhaseStats {
+  nodesVisited: number
+  nodesRendered: number
+  nodesSkipped: number
+  textNodes: number
+  boxNodes: number
+  clearOps: number
+  // Per-flag breakdown: why nodes weren't skipped
+  noPrevBuffer: number
+  flagContentDirty: number
+  flagPaintDirty: number
+  flagLayoutChanged: number
+  flagSubtreeDirty: number
+  flagChildrenDirty: number
+  flagChildPositionChanged: number
+  flagAncestorLayoutChanged: number
+  // Scroll container diagnostics
+  scrollContainerCount: number
+  scrollViewportCleared: number
+  scrollClearReason: string
+  // Normal container diagnostics
+  normalChildrenRepaint: number
+  normalRepaintReason: string
+  // Cascade diagnostics
+  cascadeMinDepth: number
+  cascadeNodes: string
+  // Top-level prevBuffer diagnostics
+  _prevBufferNull: number
+  _prevBufferDimMismatch: number
+  _hasPrevBuffer: number
+  _layoutW: number
+  _layoutH: number
+  _prevW: number
+  _prevH: number
+  _callCount: number
+}
+
+/**
+ * Clip bounds for viewport clipping.
+ */
+export type ClipBounds = { top: number; bottom: number; left?: number; right?: number }
+
+/**
+ * Per-node render state that changes at each tree level.
+ *
+ * Groups the parameters that vary per-node during tree traversal:
+ * - scrollOffset: accumulated scroll offset from scroll containers
+ * - clipBounds: viewport clipping rectangle (from overflow containers)
+ * - hasPrevBuffer: whether the buffer was cloned from a previous frame
+ * - ancestorCleared: whether an ancestor already cleared this node's region
+ *
+ * Contrast with frame-scoped params (buffer, ctx) which stay the same
+ * for the entire render pass.
+ */
+export interface NodeRenderState {
+  scrollOffset: number
+  clipBounds?: ClipBounds
+  hasPrevBuffer: boolean
+  ancestorCleared: boolean
+  /** True when the buffer was cloned from prevBuffer (stale pixels exist).
+   * False when the buffer is a fresh TerminalBuffer (no stale pixels).
+   * Unlike hasPrevBuffer (which can be false per-node on a cloned buffer),
+   * this is constant for the entire render pass. Used to prevent clearExcessArea
+   * from writing inherited bg into a fresh buffer — no stale pixels to clear. */
+  bufferIsCloned: boolean
+  /** True when any ancestor had layoutChangedThisFrame = true.
+   * Propagated top-down to prevent descendants from being skipped when their
+   * own dirty flags are clean but their pixels are at wrong positions in the
+   * cloned buffer (because an ancestor moved/resized). Without this, the
+   * hasPrevBuffer cascade handles most cases, but this adds a direct safety
+   * net in the skip condition itself. */
+  ancestorLayoutChanged?: boolean
+}
+
+/**
+ * Cell change for diffing.
+ */
+export interface CellChange {
+  x: number
+  y: number
+  cell: Cell
+}
+
+/**
+ * Border character sets.
+ */
+export interface BorderChars {
+  topLeft: string
+  topRight: string
+  bottomLeft: string
+  bottomRight: string
+  horizontal: string
+  vertical: string
+  /** Bottom horizontal character. When absent, falls back to `horizontal`. */
+  bottomHorizontal?: string
+  /** Right vertical character. When absent, falls back to `vertical`. */
+  rightVertical?: string
+}

package/src/pipeline.ts

@@ -0,0 +1,29 @@
+/**
+ * Silvery Render Pipeline
+ *
+ * Re-exports from the pipeline/ directory for backwards compatibility.
+ * See pipeline/index.ts for the main implementation.
+ */
+
+export {
+  // Types
+  type CellChange,
+  type BorderChars,
+  type ExecuteRenderOptions,
+  type PipelineConfig,
+  // Phase functions
+  measurePhase,
+  layoutPhase,
+  rectEqual,
+  scrollPhase,
+  screenRectPhase,
+  contentPhase,
+  outputPhase,
+  // Utilities
+  clearBgConflictWarnings,
+  setBgConflictMode,
+  // Orchestration
+  executeRender,
+  executeRenderAdapter,
+  type PipelineContext,
+} from "./pipeline/index"

package/src/pixel-size.ts

@@ -0,0 +1,119 @@
+/**
+ * CSI 14t/18t — Terminal Pixel and Text Area Size Queries
+ *
+ * Queries the terminal for window dimensions in pixels and characters.
+ *
+ * Protocols:
+ *
+ * Text Area Pixels (CSI 14t):
+ *   Query:    CSI 14 t
+ *   Response: CSI 4 ; height ; width t
+ *
+ * Text Area Size in Characters (CSI 18t):
+ *   Query:    CSI 18 t
+ *   Response: CSI 8 ; rows ; cols t
+ *
+ * Cell size can be derived by dividing pixel dimensions by character dimensions.
+ *
+ * Supported by: xterm, Ghostty, Kitty, WezTerm, foot, iTerm2
+ */
+
+/** Regex for CSI 4 ; height ; width t (pixel size response) */
+const PIXEL_RESPONSE_RE = /\x1b\[4;(\d+);(\d+)t/
+
+/** Regex for CSI 8 ; rows ; cols t (text area size response) */
+const TEXT_AREA_RESPONSE_RE = /\x1b\[8;(\d+);(\d+)t/
+
+// ============================================================================
+// Pixel Size Query
+// ============================================================================
+
+/**
+ * Query the terminal text area size in pixels.
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin
+ * @param timeoutMs How long to wait for response (default: 200ms)
+ * @returns Width and height in pixels, or null on timeout/unsupported
+ */
+export async function queryTextAreaPixels(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  timeoutMs = 200,
+): Promise<{ width: number; height: number } | null> {
+  write("\x1b[14t")
+
+  const data = await read(timeoutMs)
+  if (data == null) return null
+
+  const match = PIXEL_RESPONSE_RE.exec(data)
+  if (!match) return null
+
+  return {
+    height: parseInt(match[1]!, 10),
+    width: parseInt(match[2]!, 10),
+  }
+}
+
+// ============================================================================
+// Text Area Size Query (characters)
+// ============================================================================
+
+/**
+ * Query the terminal text area size in characters (rows x columns).
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin
+ * @param timeoutMs How long to wait for response (default: 200ms)
+ * @returns Rows and columns, or null on timeout/unsupported
+ */
+export async function queryTextAreaSize(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  timeoutMs = 200,
+): Promise<{ cols: number; rows: number } | null> {
+  write("\x1b[18t")
+
+  const data = await read(timeoutMs)
+  if (data == null) return null
+
+  const match = TEXT_AREA_RESPONSE_RE.exec(data)
+  if (!match) return null
+
+  return {
+    rows: parseInt(match[1]!, 10),
+    cols: parseInt(match[2]!, 10),
+  }
+}
+
+// ============================================================================
+// Cell Size (derived)
+// ============================================================================
+
+/**
+ * Query the terminal cell size in pixels by querying both pixel
+ * dimensions and character dimensions, then dividing.
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin
+ * @param timeoutMs Per-query timeout (default: 200ms)
+ * @returns Cell width and height in pixels, or null if either query fails
+ */
+export async function queryCellSize(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  timeoutMs = 200,
+): Promise<{ width: number; height: number } | null> {
+  const pixels = await queryTextAreaPixels(write, read, timeoutMs)
+  if (pixels == null) return null
+
+  const size = await queryTextAreaSize(write, read, timeoutMs)
+  if (size == null) return null
+
+  if (size.cols === 0 || size.rows === 0) return null
+
+  return {
+    width: pixels.width / size.cols,
+    height: pixels.height / size.rows,
+  }
+}

package/src/render-adapter.ts

@@ -0,0 +1,179 @@
+/**
+ * Render Adapter Abstraction
+ *
+ * This module defines the interfaces that allow silvery to render to different
+ * targets (terminal, canvas, etc.) while keeping the core layout and
+ * reconciliation logic portable.
+ */
+
+// ============================================================================
+// Text Measurement
+// ============================================================================
+
+export interface TextMeasureStyle {
+  bold?: boolean
+  italic?: boolean
+  fontSize?: number
+  fontFamily?: string
+}
+
+export interface TextMeasureResult {
+  width: number
+  height: number
+}
+
+export interface TextMeasurer {
+  /**
+   * Measure text dimensions.
+   * Returns width in adapter units (cells for terminal, pixels for canvas).
+   */
+  measureText(text: string, style?: TextMeasureStyle): TextMeasureResult
+
+  /**
+   * Get the line height for the given style.
+   */
+  getLineHeight(style?: TextMeasureStyle): number
+}
+
+// ============================================================================
+// Render Buffer
+// ============================================================================
+
+export interface RenderStyle {
+  fg?: string
+  bg?: string
+  attrs?: {
+    bold?: boolean
+    dim?: boolean
+    italic?: boolean
+    underline?: boolean
+    underlineStyle?: "single" | "double" | "curly" | "dotted" | "dashed"
+    underlineColor?: string
+    strikethrough?: boolean
+    inverse?: boolean
+  }
+}
+
+export interface RenderBuffer {
+  readonly width: number
+  readonly height: number
+
+  /**
+   * Fill a rectangle with a style.
+   */
+  fillRect(x: number, y: number, width: number, height: number, style: RenderStyle): void
+
+  /**
+   * Draw text at a position.
+   */
+  drawText(x: number, y: number, text: string, style: RenderStyle): void
+
+  /**
+   * Draw a single character at a position.
+   */
+  drawChar(x: number, y: number, char: string, style: RenderStyle): void
+
+  /**
+   * Check if coordinates are within bounds.
+   */
+  inBounds(x: number, y: number): boolean
+}
+
+// ============================================================================
+// Border Characters
+// ============================================================================
+
+export interface BorderChars {
+  topLeft: string
+  topRight: string
+  bottomLeft: string
+  bottomRight: string
+  horizontal: string
+  vertical: string
+}
+
+// ============================================================================
+// Render Adapter
+// ============================================================================
+
+export interface RenderAdapter {
+  /** Adapter name for debugging */
+  name: string
+
+  /** Text measurement for this adapter */
+  measurer: TextMeasurer
+
+  /**
+   * Create a buffer for rendering.
+   */
+  createBuffer(width: number, height: number): RenderBuffer
+
+  /**
+   * Flush the buffer to the output (terminal, canvas, etc.).
+   * For terminal: returns ANSI diff string.
+   * For canvas: draws directly, returns void.
+   */
+  flush(buffer: RenderBuffer, prevBuffer: RenderBuffer | null): string | void
+
+  /**
+   * Get border characters for the given style.
+   */
+  getBorderChars(style: string): BorderChars
+}
+
+// ============================================================================
+// Global Adapter Management
+// ============================================================================
+
+// NOTE: currentAdapter is intentionally a module-level singleton, not threaded
+// through PipelineContext. Unlike the width measurer (which varies per terminal
+// and needs per-render scoping), the render adapter defines the render *target*
+// (terminal vs canvas) and is set exactly once at startup. It never changes for
+// the lifetime of the process. Threading it through every pipeline function
+// would add significant plumbing for zero benefit -- there's no concurrency
+// or per-instance variation to protect against.
+let currentAdapter: RenderAdapter | null = null
+
+/**
+ * Set the current render adapter.
+ */
+export function setRenderAdapter(adapter: RenderAdapter): void {
+  currentAdapter = adapter
+}
+
+/**
+ * Get the current render adapter.
+ * Throws if no adapter is set.
+ */
+export function getRenderAdapter(): RenderAdapter {
+  if (!currentAdapter) {
+    throw new Error("No render adapter set. Call setRenderAdapter() first.")
+  }
+  return currentAdapter
+}
+
+/**
+ * Check if a render adapter has been set.
+ */
+export function hasRenderAdapter(): boolean {
+  return currentAdapter !== null
+}
+
+/**
+ * Get the text measurer from the current adapter.
+ */
+export function getTextMeasurer(): TextMeasurer {
+  return getRenderAdapter().measurer
+}
+
+/**
+ * Ensure a render adapter is initialized.
+ * If no adapter is set, lazily imports and sets the terminal adapter.
+ */
+export async function ensureRenderAdapterInitialized(): Promise<void> {
+  if (hasRenderAdapter()) return
+
+  // Lazy import to avoid circular dependencies
+  const { terminalAdapter } = await import("./adapters/terminal-adapter.js")
+  setRenderAdapter(terminalAdapter)
+}