@silvery/term 0.3.0

package/src/layout.ts

@@ -0,0 +1,26 @@
+/**
+ * silvery/layout -- Layout feedback hooks.
+ *
+ * The key differentiator of silvery over Ink: components that know their
+ * own size during render, not after.
+ *
+ * ```tsx
+ * import { useContentRect, useScreenRect } from '@silvery/react/layout'
+ *
+ * function ResponsiveCard() {
+ *   const { width, height } = useContentRect()
+ *   const { x, y } = useScreenRect()
+ *   return <Text>{`${width}x${height} at (${x},${y})`}</Text>
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export {
+  useContentRect,
+  useContentRectCallback,
+  useScreenRect,
+  useScreenRectCallback,
+} from "@silvery/react/hooks/useLayout"
+export type { Rect } from "@silvery/tea/types"

package/src/measurer.ts

@@ -0,0 +1,74 @@
+/**
+ * Measurer composition layer.
+ *
+ * Creates term-scoped measurers and pipeline configs.
+ * Bridges ansi Term with silvery measurement capabilities.
+ */
+
+import type { Term, TerminalCaps } from "./ansi/index"
+import { createWidthMeasurer, type Measurer } from "./unicode"
+import { createOutputPhase } from "./pipeline/output-phase"
+import type { PipelineConfig } from "./pipeline"
+
+export type { Measurer } from "./unicode"
+
+/**
+ * Term extended with measurement capabilities.
+ */
+export interface MeasuredTerm extends Term, Measurer {}
+
+/**
+ * Extend a Term with measurement capabilities.
+ *
+ * Creates a width measurer from the term's caps and adds measurement
+ * methods (displayWidth, graphemeWidth, wrapText, etc.) to the term.
+ */
+export function withMeasurer(term: Term): MeasuredTerm {
+  const caps = term.caps
+  const measurer = createWidthMeasurer(
+    caps ? { textEmojiWide: caps.textEmojiWide, textSizingEnabled: caps.textSizingSupported } : {},
+  )
+
+  return Object.create(term, {
+    textEmojiWide: { get: () => measurer.textEmojiWide, enumerable: true },
+    textSizingEnabled: { get: () => measurer.textSizingEnabled, enumerable: true },
+    displayWidth: { value: measurer.displayWidth.bind(measurer), enumerable: true },
+    displayWidthAnsi: { value: measurer.displayWidthAnsi.bind(measurer), enumerable: true },
+    graphemeWidth: { value: measurer.graphemeWidth.bind(measurer), enumerable: true },
+    wrapText: { value: measurer.wrapText.bind(measurer), enumerable: true },
+    sliceByWidth: { value: measurer.sliceByWidth.bind(measurer), enumerable: true },
+    sliceByWidthFromEnd: { value: measurer.sliceByWidthFromEnd.bind(measurer), enumerable: true },
+  }) as MeasuredTerm
+}
+
+/**
+ * Create a pipeline configuration from caps and/or measurer.
+ *
+ * This is the single factory for PipelineConfig -- use it instead of
+ * manually constructing { measurer, outputPhaseFn }.
+ *
+ * @param options.caps - Terminal capabilities (for output phase SGR generation)
+ * @param options.measurer - Explicit measurer (if omitted, created from caps)
+ */
+export function createPipeline(
+  options: {
+    caps?: TerminalCaps
+    measurer?: Measurer
+  } = {},
+): PipelineConfig {
+  const { caps, measurer: explicitMeasurer } = options
+  const measurer =
+    explicitMeasurer ??
+    createWidthMeasurer(caps ? { textEmojiWide: caps.textEmojiWide, textSizingEnabled: caps.textSizingSupported } : {})
+  const outputPhaseFn = createOutputPhase(
+    caps
+      ? {
+          underlineStyles: caps.underlineStyles,
+          underlineColor: caps.underlineColor,
+          colorLevel: caps.colorLevel,
+        }
+      : {},
+    measurer,
+  )
+  return { measurer, outputPhaseFn }
+}

package/src/mode-query.ts

@@ -0,0 +1,106 @@
+/**
+ * DECRQM — DEC Private Mode Query
+ *
+ * Queries the terminal for the state of DEC private modes.
+ *
+ * Protocol:
+ * - Query:    CSI ? {mode} $ p
+ * - Response: CSI ? {mode} ; {Ps} $ y
+ *
+ * Where Ps is:
+ *   1 = set (mode is enabled)
+ *   2 = reset (mode is disabled)
+ *   0 = not recognized (unknown mode)
+ *   3 = permanently set
+ *   4 = permanently reset
+ *
+ * We normalize 3→"set" and 4→"reset" for simplicity.
+ *
+ * Supported by: xterm, Ghostty, Kitty, WezTerm, foot, VTE-based terminals
+ */
+
+/** Regex for DECRPM response: CSI ? mode ; Ps $ y */
+const DECRPM_RESPONSE_RE = /\x1b\[\?(\d+);(\d+)\$y/
+
+/** Well-known DEC private mode constants. */
+export const DecMode = {
+  /** DEC cursor visible (DECTCEM) */
+  CURSOR_VISIBLE: 25,
+  /** Alternate screen buffer (DECSET 1049) */
+  ALT_SCREEN: 1049,
+  /** Normal mouse tracking (X10) */
+  MOUSE_TRACKING: 1000,
+  /** Bracketed paste mode */
+  BRACKETED_PASTE: 2004,
+  /** Synchronized output */
+  SYNC_OUTPUT: 2026,
+  /** Focus reporting */
+  FOCUS_REPORTING: 1004,
+} as const
+
+type ModeState = "set" | "reset" | "unknown"
+
+/**
+ * Query the state of a single DEC private mode.
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin
+ * @param mode DEC private mode number (e.g., DecMode.ALT_SCREEN)
+ * @param timeoutMs How long to wait for response (default: 200ms)
+ * @returns "set", "reset", or "unknown"
+ */
+export async function queryMode(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  mode: number,
+  timeoutMs = 200,
+): Promise<ModeState> {
+  write(`\x1b[?${mode}$p`)
+
+  const data = await read(timeoutMs)
+  if (data == null) return "unknown"
+
+  const match = DECRPM_RESPONSE_RE.exec(data)
+  if (!match) return "unknown"
+
+  const reportedMode = parseInt(match[1]!, 10)
+  if (reportedMode !== mode) return "unknown"
+
+  const ps = parseInt(match[2]!, 10)
+  switch (ps) {
+    case 1:
+    case 3:
+      return "set"
+    case 2:
+    case 4:
+      return "reset"
+    default:
+      return "unknown"
+  }
+}
+
+/**
+ * Query the state of multiple DEC private modes.
+ *
+ * Queries each mode sequentially and returns a Map of results.
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin
+ * @param modes Array of DEC private mode numbers
+ * @param timeoutMs Per-query timeout (default: 200ms)
+ */
+export async function queryModes(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  modes: number[],
+  timeoutMs = 200,
+): Promise<Map<number, ModeState>> {
+  const results = new Map<number, ModeState>()
+
+  for (const mode of modes) {
+    const state = await queryMode(write, read, mode, timeoutMs)
+    results.set(mode, state)
+  }
+
+  return results
+}

package/src/mouse-events.ts

@@ -0,0 +1,419 @@
+/**
+ * DOM-level Mouse Events for silvery
+ *
+ * Provides React DOM-compatible mouse event infrastructure:
+ * - SilveryMouseEvent / SilveryWheelEvent synthetic event objects
+ * - Tree-based hit testing using screenRect (replaces manual HitRegistry)
+ * - Event dispatch with bubbling (target → root, stopPropagation support)
+ * - Double-click detection (300ms / 2-cell threshold)
+ * - mouseenter/mouseleave tracking (no bubble, like DOM spec)
+ */
+
+import type { FocusManager } from "@silvery/tea/focus-manager"
+import { findFocusableAncestor } from "@silvery/tea/focus-queries"
+import type { ParsedMouse } from "./mouse"
+import { getAncestorPath, pointInRect } from "@silvery/tea/tree-utils"
+import type { TeaNode } from "@silvery/tea/types"
+
+// ============================================================================
+// Event Types
+// ============================================================================
+
+/**
+ * Synthetic mouse event, mirroring React.MouseEvent / DOM MouseEvent.
+ */
+export interface SilveryMouseEvent {
+  /** Terminal column (0-indexed) */
+  clientX: number
+  /** Terminal row (0-indexed) */
+  clientY: number
+  /** Mouse button: 0=left, 1=middle, 2=right */
+  button: number
+  /** Modifier keys */
+  altKey: boolean
+  ctrlKey: boolean
+  metaKey: boolean
+  shiftKey: boolean
+  /** Deepest node under cursor */
+  target: TeaNode
+  /** Node whose handler is currently firing (changes during bubble) */
+  currentTarget: TeaNode
+  /** Event type */
+  type: "click" | "dblclick" | "mousedown" | "mouseup" | "mousemove" | "mouseenter" | "mouseleave" | "wheel"
+  /** Stop event from bubbling to parent nodes */
+  stopPropagation(): void
+  /** Prevent default behavior */
+  preventDefault(): void
+  /** Whether stopPropagation() was called */
+  readonly propagationStopped: boolean
+  /** Whether preventDefault() was called */
+  readonly defaultPrevented: boolean
+  /** Raw parsed mouse data from SGR protocol */
+  nativeEvent: ParsedMouse
+}
+
+/**
+ * Synthetic wheel event, extending SilveryMouseEvent with scroll deltas.
+ */
+export interface SilveryWheelEvent extends SilveryMouseEvent {
+  /** Vertical scroll: -1 (up) or +1 (down) */
+  deltaY: number
+  /** Horizontal scroll: always 0 for terminals */
+  deltaX: number
+}
+
+// ============================================================================
+// Mouse Event Handler Props (added to BoxProps/TextProps)
+// ============================================================================
+
+export interface MouseEventProps {
+  onClick?: (event: SilveryMouseEvent) => void
+  onDoubleClick?: (event: SilveryMouseEvent) => void
+  onMouseDown?: (event: SilveryMouseEvent) => void
+  onMouseUp?: (event: SilveryMouseEvent) => void
+  onMouseMove?: (event: SilveryMouseEvent) => void
+  onMouseEnter?: (event: SilveryMouseEvent) => void
+  onMouseLeave?: (event: SilveryMouseEvent) => void
+  onWheel?: (event: SilveryWheelEvent) => void
+}
+
+// ============================================================================
+// Event Factory
+// ============================================================================
+
+/**
+ * Create a synthetic mouse event.
+ */
+export function createMouseEvent(
+  type: SilveryMouseEvent["type"],
+  x: number,
+  y: number,
+  target: TeaNode,
+  parsed: ParsedMouse,
+): SilveryMouseEvent {
+  let propagationStopped = false
+  let defaultPrevented = false
+
+  return {
+    type,
+    clientX: x,
+    clientY: y,
+    button: parsed.button,
+    altKey: parsed.meta,
+    ctrlKey: parsed.ctrl,
+    metaKey: false,
+    shiftKey: parsed.shift,
+    target,
+    currentTarget: target,
+    nativeEvent: parsed,
+    get propagationStopped() {
+      return propagationStopped
+    },
+    get defaultPrevented() {
+      return defaultPrevented
+    },
+    stopPropagation() {
+      propagationStopped = true
+    },
+    preventDefault() {
+      defaultPrevented = true
+    },
+  }
+}
+
+/**
+ * Create a synthetic wheel event.
+ */
+export function createWheelEvent(x: number, y: number, target: TeaNode, parsed: ParsedMouse): SilveryWheelEvent {
+  const base = createMouseEvent("wheel", x, y, target, parsed) as SilveryWheelEvent
+  base.deltaY = parsed.delta ?? 0
+  base.deltaX = 0
+  return base
+}
+
+// ============================================================================
+// Hit Testing
+// ============================================================================
+
+/**
+ * Tree-based hit test: find the deepest node whose screenRect contains (x, y).
+ * Uses reverse child order (last sibling wins = highest z-order, like DOM).
+ * Respects overflow:hidden clipping.
+ */
+export function hitTest(node: TeaNode, x: number, y: number): TeaNode | null {
+  const rect = node.screenRect
+  if (!rect) return null
+
+  // Check if point is within this node's bounds
+  if (!pointInRect(x, y, rect)) return null
+
+  // pointerEvents="none" makes this node and its subtree invisible to hit testing
+  const props = node.props as { overflow?: string; pointerEvents?: string }
+  if (props.pointerEvents === "none") return null
+
+  // Check overflow clipping — if overflow is "hidden" or "scroll",
+  // children outside this node's rect are not hittable
+  const clips = props.overflow === "hidden" || props.overflow === "scroll"
+
+  // DFS: check children in reverse order (last child = top z-order, like DOM)
+  for (let i = node.children.length - 1; i >= 0; i--) {
+    const child = node.children[i]!
+    // If parent clips, skip children whose screenRect doesn't overlap parent
+    if (clips) {
+      const childRect = child.screenRect
+      if (childRect && !pointInRect(x, y, rect)) {
+        continue
+      }
+    }
+    const hit = hitTest(child, x, y)
+    if (hit) return hit
+  }
+
+  // No child matched — this node is the target (if it has a screenRect)
+  return node
+}
+
+// ============================================================================
+// Event Dispatch
+// ============================================================================
+
+/** Map event type to the handler prop name */
+const EVENT_HANDLER_MAP: Record<string, keyof MouseEventProps> = {
+  click: "onClick",
+  dblclick: "onDoubleClick",
+  mousedown: "onMouseDown",
+  mouseup: "onMouseUp",
+  mousemove: "onMouseMove",
+  mouseenter: "onMouseEnter",
+  mouseleave: "onMouseLeave",
+  wheel: "onWheel",
+}
+
+/**
+ * Dispatch a mouse event through the render tree with DOM-style bubbling.
+ *
+ * Bubbles from target → root, calling the appropriate handler on each node.
+ * stopPropagation() halts bubbling. mouseenter/mouseleave do NOT bubble (DOM spec).
+ */
+export function dispatchMouseEvent(event: SilveryMouseEvent): void {
+  const handlerProp = EVENT_HANDLER_MAP[event.type]
+  if (!handlerProp) return
+
+  // mouseenter/mouseleave don't bubble (DOM spec)
+  const noBubble = event.type === "mouseenter" || event.type === "mouseleave"
+
+  if (noBubble) {
+    // Only fire on the target itself
+    const handler = (event.target.props as Record<string, unknown>)[handlerProp] as
+      | ((e: SilveryMouseEvent) => void)
+      | undefined
+    if (handler) {
+      const mutableEvent = event as { currentTarget: TeaNode }
+      mutableEvent.currentTarget = event.target
+      handler(event)
+    }
+    return
+  }
+
+  // Bubble phase: fire from target up to root
+  const path = getAncestorPath(event.target)
+  for (const node of path) {
+    if (event.propagationStopped) break
+
+    const handler = (node.props as Record<string, unknown>)[handlerProp] as ((e: SilveryMouseEvent) => void) | undefined
+    if (handler) {
+      const mutableEvent = event as { currentTarget: TeaNode }
+      mutableEvent.currentTarget = node
+      handler(event)
+    }
+  }
+}
+
+// ============================================================================
+// Double-Click Detection
+// ============================================================================
+
+export interface DoubleClickState {
+  lastClickTime: number
+  lastClickX: number
+  lastClickY: number
+  lastClickButton: number
+}
+
+export function createDoubleClickState(): DoubleClickState {
+  return {
+    lastClickTime: 0,
+    lastClickX: -999,
+    lastClickY: -999,
+    lastClickButton: -1,
+  }
+}
+
+const DOUBLE_CLICK_TIME_MS = 300
+const DOUBLE_CLICK_DISTANCE = 2
+
+/**
+ * Check if a click qualifies as a double-click, given the previous click state.
+ * Updates the state for the next check.
+ * Returns true if this is a double-click.
+ */
+export function checkDoubleClick(
+  state: DoubleClickState,
+  x: number,
+  y: number,
+  button: number,
+  now: number = Date.now(),
+): boolean {
+  const timeDelta = now - state.lastClickTime
+  const dx = Math.abs(x - state.lastClickX)
+  const dy = Math.abs(y - state.lastClickY)
+  const sameButton = button === state.lastClickButton
+
+  const isDouble =
+    sameButton && timeDelta <= DOUBLE_CLICK_TIME_MS && dx <= DOUBLE_CLICK_DISTANCE && dy <= DOUBLE_CLICK_DISTANCE
+
+  // Update state
+  state.lastClickTime = now
+  state.lastClickX = x
+  state.lastClickY = y
+  state.lastClickButton = button
+
+  // If double-click, reset so triple-click doesn't register as another double
+  if (isDouble) {
+    state.lastClickTime = 0
+  }
+
+  return isDouble
+}
+
+// ============================================================================
+// Mouse Enter/Leave Tracking
+// ============================================================================
+
+/**
+ * Compute mouseenter/mouseleave transitions between two ancestor paths.
+ *
+ * Returns { entered, left } — arrays of nodes that were entered or left.
+ * Mirrors the DOM spec: fire mouseleave on nodes in prevPath not in nextPath,
+ * and mouseenter on nodes in nextPath not in prevPath.
+ */
+export function computeEnterLeave(prevPath: TeaNode[], nextPath: TeaNode[]): { entered: TeaNode[]; left: TeaNode[] } {
+  const prevSet = new Set(prevPath)
+  const nextSet = new Set(nextPath)
+
+  const entered = nextPath.filter((n) => !prevSet.has(n))
+  const left = prevPath.filter((n) => !nextSet.has(n))
+
+  return { entered, left }
+}
+
+// ============================================================================
+// High-Level Mouse Event Processor
+// ============================================================================
+
+/**
+ * Options for creating a mouse event processor.
+ */
+export interface MouseEventProcessorOptions {
+  /** Optional focus manager — enables click-to-focus behavior.
+   *  On mousedown, the deepest focusable ancestor of the hit target is focused. */
+  focusManager?: FocusManager
+}
+
+/**
+ * State for the mouse event processor.
+ */
+export interface MouseEventProcessorState {
+  doubleClick: DoubleClickState
+  /** Previous hover path (for enter/leave tracking) */
+  hoverPath: TeaNode[]
+  /** Whether the left button is currently down (for click detection) */
+  mouseDownTarget: TeaNode | null
+  /** Optional focus manager for click-to-focus */
+  focusManager?: FocusManager
+}
+
+export function createMouseEventProcessor(options?: MouseEventProcessorOptions): MouseEventProcessorState {
+  return {
+    doubleClick: createDoubleClickState(),
+    hoverPath: [],
+    mouseDownTarget: null,
+    focusManager: options?.focusManager,
+  }
+}
+
+/**
+ * Process a raw ParsedMouse event and dispatch DOM-level events on the render tree.
+ *
+ * Call this for every SGR mouse event received. It handles:
+ * - mousedown / mouseup
+ * - click (on mouseup if same target as mousedown)
+ * - dblclick (based on timing)
+ * - mousemove + mouseenter/mouseleave
+ * - wheel
+ */
+export function processMouseEvent(state: MouseEventProcessorState, parsed: ParsedMouse, root: TeaNode): void {
+  const { x, y, action } = parsed
+  const target = hitTest(root, x, y)
+  if (!target) return
+
+  if (action === "down") {
+    state.mouseDownTarget = target
+
+    // Click-to-focus: find nearest focusable ancestor and focus it
+    if (state.focusManager) {
+      const focusable = findFocusableAncestor(target)
+      if (focusable) {
+        state.focusManager.focus(focusable, "mouse")
+      }
+    }
+
+    const event = createMouseEvent("mousedown", x, y, target, parsed)
+    dispatchMouseEvent(event)
+  } else if (action === "up") {
+    const event = createMouseEvent("mouseup", x, y, target, parsed)
+    dispatchMouseEvent(event)
+
+    // Click = mouseup on the same node (or ancestor) where mousedown happened
+    // DOM actually fires click even if up is on a different element, but the target
+    // is the nearest common ancestor. For simplicity, we fire click on the up target
+    // if mousedown was on the same target or a descendant.
+    if (state.mouseDownTarget) {
+      const clickEvent = createMouseEvent("click", x, y, target, parsed)
+      dispatchMouseEvent(clickEvent)
+
+      // Check for double-click
+      const isDouble = checkDoubleClick(state.doubleClick, x, y, parsed.button)
+      if (isDouble) {
+        const dblEvent = createMouseEvent("dblclick", x, y, target, parsed)
+        dispatchMouseEvent(dblEvent)
+      }
+    }
+
+    state.mouseDownTarget = null
+  } else if (action === "move") {
+    const event = createMouseEvent("mousemove", x, y, target, parsed)
+    dispatchMouseEvent(event)
+
+    // Compute enter/leave transitions
+    const newPath = getAncestorPath(target)
+    const { entered, left } = computeEnterLeave(state.hoverPath, newPath)
+
+    // Fire mouseleave on nodes that were left (reverse order = deepest first)
+    for (const node of left) {
+      const leaveEvent = createMouseEvent("mouseleave", x, y, node, parsed)
+      dispatchMouseEvent(leaveEvent)
+    }
+
+    // Fire mouseenter on newly entered nodes (forward order = shallowest first)
+    for (const node of entered.reverse()) {
+      const enterEvent = createMouseEvent("mouseenter", x, y, node, parsed)
+      dispatchMouseEvent(enterEvent)
+    }
+
+    state.hoverPath = newPath
+  } else if (action === "wheel") {
+    const event = createWheelEvent(x, y, target, parsed)
+    dispatchMouseEvent(event)
+  }
+}

package/src/mouse.ts

@@ -0,0 +1,83 @@
+/**
+ * SGR mouse event parsing (mode 1006).
+ *
+ * SGR format: CSI < button;x;y M (press) or CSI < button;x;y m (release)
+ *
+ * Button encoding:
+ * - Bits 0-1: 0=left, 1=middle, 2=right, 3=release (X10 only, not SGR)
+ * - Bit 2 (+4): Shift held
+ * - Bit 3 (+8): Meta/Alt held
+ * - Bit 4 (+16): Ctrl held
+ * - Bit 5 (+32): Motion event (mouse moved while button held)
+ * - Bits 6-7: 64=wheel-up, 65=wheel-down, 66=wheel-left, 67=wheel-right
+ */
+
+/**
+ * Parsed mouse event from SGR mouse protocol (mode 1006).
+ */
+export interface ParsedMouse {
+  /** Mouse button: 0=left, 1=middle, 2=right */
+  button: number
+  /** Column (0-indexed) */
+  x: number
+  /** Row (0-indexed) */
+  y: number
+  /** Event action */
+  action: "down" | "up" | "move" | "wheel"
+  /** Wheel delta: -1 for up, +1 for down */
+  delta?: number
+  /** Shift was held */
+  shift: boolean
+  /** Alt/Meta was held */
+  meta: boolean
+  /** Ctrl was held */
+  ctrl: boolean
+}
+
+const SGR_MOUSE_RE = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/
+
+/**
+ * Parse an SGR mouse sequence.
+ *
+ * @returns ParsedMouse or null if not a valid mouse sequence
+ */
+export function parseMouseSequence(input: string): ParsedMouse | null {
+  const m = SGR_MOUSE_RE.exec(input)
+  if (!m) return null
+
+  const raw = parseInt(m[1]!)
+  const x = parseInt(m[2]!) - 1 // 1-indexed → 0-indexed
+  const y = parseInt(m[3]!) - 1
+  const terminator = m[4]!
+
+  const shift = !!(raw & 4)
+  const meta = !!(raw & 8)
+  const ctrl = !!(raw & 16)
+  const motion = !!(raw & 32)
+  const isWheel = !!(raw & 64)
+
+  if (isWheel) {
+    const wheelButton = raw & 3 // 0=up, 1=down, 2=left, 3=right
+    return {
+      button: 0,
+      x,
+      y,
+      action: "wheel",
+      delta: wheelButton === 0 ? -1 : 1,
+      shift,
+      meta,
+      ctrl,
+    }
+  }
+
+  const button = raw & 3
+  const action = motion ? "move" : terminator === "M" ? "down" : "up"
+  return { button, x, y, action, shift, meta, ctrl }
+}
+
+const SGR_MOUSE_TEST_RE = /^\x1b\[<\d+;\d+;\d+[Mm]$/
+
+/** Check if a raw input string is a mouse sequence */
+export function isMouseSequence(input: string): boolean {
+  return SGR_MOUSE_TEST_RE.test(input)
+}