@silvery/term 0.3.0

package/src/clipboard.ts

@@ -0,0 +1,74 @@
+/**
+ * OSC 52 Clipboard Support
+ *
+ * Provides clipboard access via the OSC 52 terminal protocol.
+ * This works across SSH sessions and in terminals that support it.
+ *
+ * Protocol: OSC 52
+ * - Copy:    ESC ] 52 ; c ; <base64> BEL
+ * - Query:   ESC ] 52 ; c ; ? BEL
+ * - Response: ESC ] 52 ; c ; <base64> BEL  (or ST terminator)
+ *
+ * Supported by: Ghostty, Kitty, WezTerm, iTerm2, xterm, foot, tmux
+ */
+
+const ESC = "\x1b"
+const BEL = "\x07"
+
+// ============================================================================
+// Clipboard Operations
+// ============================================================================
+
+/**
+ * Copy text to the system clipboard via OSC 52.
+ * Encodes the text as base64 and writes the OSC 52 sequence to stdout.
+ */
+export function copyToClipboard(stdout: NodeJS.WriteStream, text: string): void {
+  const base64 = Buffer.from(text).toString("base64")
+  stdout.write(`${ESC}]52;c;${base64}${BEL}`)
+}
+
+/**
+ * Request clipboard contents via OSC 52.
+ * Writes the OSC 52 query sequence. The terminal will respond with
+ * an OSC 52 response containing the clipboard contents as base64.
+ * Use parseClipboardResponse() to decode the response.
+ */
+export function requestClipboard(stdout: NodeJS.WriteStream): void {
+  stdout.write(`${ESC}]52;c;?${BEL}`)
+}
+
+// ============================================================================
+// Response Parsing
+// ============================================================================
+
+/** OSC 52 response prefix */
+const OSC52_PREFIX = `${ESC}]52;c;`
+
+/**
+ * Parse an OSC 52 clipboard response and decode the base64 content.
+ *
+ * Returns the decoded clipboard text, or null if the input is not
+ * an OSC 52 clipboard response.
+ *
+ * Handles both BEL (\x07) and ST (ESC \) terminators.
+ */
+export function parseClipboardResponse(input: string): string | null {
+  const prefixIdx = input.indexOf(OSC52_PREFIX)
+  if (prefixIdx === -1) return null
+
+  const contentStart = prefixIdx + OSC52_PREFIX.length
+
+  // Reject the query marker — it's not a response
+  if (input[contentStart] === "?") return null
+
+  // Find terminator: BEL (\x07) or ST (ESC \)
+  let contentEnd = input.indexOf(BEL, contentStart)
+  if (contentEnd === -1) {
+    contentEnd = input.indexOf(`${ESC}\\`, contentStart)
+  }
+  if (contentEnd === -1) return null
+
+  const base64 = input.slice(contentStart, contentEnd)
+  return Buffer.from(base64, "base64").toString("utf-8")
+}

package/src/cursor-query.ts

@@ -0,0 +1,85 @@
+/**
+ * CSI 6n Cursor Position Query
+ *
+ * Queries the terminal for the current cursor position using the standard
+ * Device Status Report (DSR) mechanism.
+ *
+ * Protocol:
+ * - Query:    CSI 6 n  (\x1b[6n)
+ * - Response: CSI {row} ; {col} R  (\x1b[{row};{col}R)
+ *
+ * Row and column are 1-indexed in the protocol response.
+ *
+ * Supported by: virtually all terminals (VT100+)
+ */
+
+/** Regex to match a CPR response: CSI row ; col R */
+const CPR_RESPONSE_RE = /\x1b\[(\d+);(\d+)R/
+
+/**
+ * Query the terminal cursor position.
+ *
+ * Sends CSI 6n and parses the CPR response.
+ * Returns 1-indexed row and column.
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin (resolves with data or null on timeout)
+ * @param timeoutMs How long to wait for response (default: 200ms)
+ */
+export async function queryCursorPosition(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  timeoutMs = 200,
+): Promise<{ row: number; col: number } | null> {
+  write("\x1b[6n")
+
+  const data = await read(timeoutMs)
+  if (data == null) return null
+
+  const match = CPR_RESPONSE_RE.exec(data)
+  if (!match) return null
+
+  return {
+    row: parseInt(match[1]!, 10),
+    col: parseInt(match[2]!, 10),
+  }
+}
+
+/**
+ * Query cursor position using real stdin/stdout.
+ * Convenience wrapper around queryCursorPosition.
+ */
+export async function queryCursorFromStdio(
+  stdout: { write: (s: string) => boolean | void },
+  stdin: NodeJS.ReadStream,
+  timeoutMs = 200,
+): Promise<{ row: number; col: number } | null> {
+  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 queryCursorPosition(write, read, timeoutMs)
+  } finally {
+    if (!wasRaw) stdin.setRawMode(false)
+  }
+}

package/src/device-attrs.ts

@@ -0,0 +1,228 @@
+/**
+ * Device Attributes (DA1/DA2/DA3) + XTVERSION Queries
+ *
+ * Provides functions to query terminal identity and capabilities using
+ * the standard VT device attribute escape sequences.
+ *
+ * Protocols:
+ *
+ * DA1 (Primary Device Attributes):
+ *   Query:    CSI c       (\x1b[c)
+ *   Response: CSI ? Ps ; Ps ; ... c
+ *
+ * DA2 (Secondary Device Attributes):
+ *   Query:    CSI > c     (\x1b[>c)
+ *   Response: CSI > Pt ; Pv ; Pc c
+ *   Where Pt=terminal type, Pv=firmware version, Pc=ROM cartridge id
+ *
+ * DA3 (Tertiary Device Attributes):
+ *   Query:    CSI = c     (\x1b[=c)
+ *   Response: DCS ! | hex-encoded-id ST  (\x1bP!|{hex}\x1b\\)
+ *
+ * XTVERSION (Terminal Name + Version):
+ *   Query:    CSI > 0 q   (\x1b[>0q)
+ *   Response: DCS > | name(version) ST  (\x1bP>|{text}\x1b\\)
+ *
+ * Supported by: xterm, Ghostty, Kitty, WezTerm, foot, VTE-based terminals
+ */
+
+/** Regex for DA1 response: CSI ? params c */
+const DA1_RESPONSE_RE = /\x1b\[\?([\d;]+)c/
+
+/** Regex for DA2 response: CSI > params c */
+const DA2_RESPONSE_RE = /\x1b\[>([\d;]+)c/
+
+/** Regex for DA3 response: DCS ! | hex ST */
+const DA3_RESPONSE_RE = /\x1bP!\|([0-9a-fA-F]*)\x1b\\/
+
+/** Regex for XTVERSION response: DCS > | text ST */
+const XTVERSION_RESPONSE_RE = /\x1bP>\|([^\x1b]*)\x1b\\/
+
+// ============================================================================
+// DA1 — Primary Device Attributes
+// ============================================================================
+
+/**
+ * Query primary device attributes (DA1).
+ *
+ * Returns the list of attribute parameters the terminal reports.
+ * Common params: 1=132-cols, 4=sixel, 6=selective-erase, 22=ANSI-color
+ *
+ * @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)
+ */
+export async function queryPrimaryDA(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  timeoutMs = 200,
+): Promise<{ params: number[] } | null> {
+  write("\x1b[c")
+
+  const data = await read(timeoutMs)
+  if (data == null) return null
+
+  const match = DA1_RESPONSE_RE.exec(data)
+  if (!match) return null
+
+  const params = match[1]!.split(";").map((s) => parseInt(s, 10))
+  return { params }
+}
+
+// ============================================================================
+// DA2 — Secondary Device Attributes
+// ============================================================================
+
+/**
+ * Query secondary device attributes (DA2).
+ *
+ * Returns terminal type, firmware version, and ROM cartridge id.
+ * Common type values: 0=VT100, 1=VT220, 41=xterm, 65=VT500
+ *
+ * @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)
+ */
+export async function querySecondaryDA(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  timeoutMs = 200,
+): Promise<{ type: number; version: number; id: number } | null> {
+  write("\x1b[>c")
+
+  const data = await read(timeoutMs)
+  if (data == null) return null
+
+  const match = DA2_RESPONSE_RE.exec(data)
+  if (!match) return null
+
+  const parts = match[1]!.split(";")
+  if (parts.length < 3) return null
+
+  return {
+    type: parseInt(parts[0]!, 10),
+    version: parseInt(parts[1]!, 10),
+    id: parseInt(parts[2]!, 10),
+  }
+}
+
+// ============================================================================
+// DA3 — Tertiary Device Attributes
+// ============================================================================
+
+/**
+ * Query tertiary device attributes (DA3).
+ *
+ * Returns a hex-encoded unit ID string. Decode with Buffer.from(hex, 'hex').
+ *
+ * @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)
+ */
+export async function queryTertiaryDA(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  timeoutMs = 200,
+): Promise<string | null> {
+  write("\x1b[=c")
+
+  const data = await read(timeoutMs)
+  if (data == null) return null
+
+  const match = DA3_RESPONSE_RE.exec(data)
+  if (!match) return null
+
+  return match[1]!
+}
+
+// ============================================================================
+// XTVERSION — Terminal Name + Version
+// ============================================================================
+
+/**
+ * Query the terminal name and version via XTVERSION.
+ *
+ * Returns the version string as reported by the terminal, e.g.:
+ * - "xterm(388)"
+ * - "tmux 3.4"
+ * - "WezTerm 20230712-072601-f4abf8fd"
+ *
+ * @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)
+ */
+export async function queryTerminalVersion(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  timeoutMs = 200,
+): Promise<string | null> {
+  write("\x1b[>0q")
+
+  const data = await read(timeoutMs)
+  if (data == null) return null
+
+  const match = XTVERSION_RESPONSE_RE.exec(data)
+  if (!match) return null
+
+  return match[1]!
+}
+
+// ============================================================================
+// Combined Query
+// ============================================================================
+
+/** Combined device attributes result. */
+export interface DeviceAttributes {
+  da1: { params: number[] } | null
+  da2: { type: number; version: number; id: number } | null
+  version: string | null
+}
+
+/**
+ * Query all device attributes: DA1, DA2, and XTVERSION.
+ *
+ * Convenience wrapper that queries all three sequentially.
+ * DA3 is omitted from the combined query as it's rarely needed.
+ *
+ * @param stdout Writable stream (e.g., process.stdout)
+ * @param stdin Readable stream (e.g., process.stdin)
+ * @param timeoutMs Per-query timeout (default: 200ms)
+ */
+export async function queryDeviceAttributes(
+  stdout: { write: (s: string) => boolean | void },
+  stdin: NodeJS.ReadStream,
+  timeoutMs = 200,
+): Promise<DeviceAttributes> {
+  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)
+      })
+
+    const da1 = await queryPrimaryDA(write, read, timeoutMs)
+    const da2 = await querySecondaryDA(write, read, timeoutMs)
+    const version = await queryTerminalVersion(write, read, timeoutMs)
+
+    return { da1, da2, version }
+  } finally {
+    if (!wasRaw) stdin.setRawMode(false)
+  }
+}

package/src/devtools.ts

@@ -0,0 +1,123 @@
+/**
+ * React DevTools integration for silvery.
+ *
+ * Provides optional connection to React DevTools standalone app for
+ * debugging TUI component trees. Requires `react-devtools-core` to be
+ * installed (optional peer dependency).
+ *
+ * Usage:
+ *   1. Install: `bun add -d react-devtools-core`
+ *   2. Run devtools: `npx react-devtools`
+ *   3. Launch app with: `DEBUG_DEVTOOLS=1 bun run app.ts`
+ *
+ * Or call `connectDevTools()` manually from your app code.
+ *
+ * @module
+ */
+
+import { reconciler } from "@silvery/react/reconciler"
+
+let connected = false
+
+/**
+ * Connect to React DevTools standalone app.
+ *
+ * This lazy-loads `react-devtools-core` so it has zero impact on
+ * production bundles. The connection is established via WebSocket
+ * to the devtools electron app (default: ws://localhost:8097).
+ *
+ * Safe to call multiple times -- subsequent calls are no-ops.
+ *
+ * @example
+ * ```ts
+ * import { connectDevTools } from '@silvery/react';
+ * await connectDevTools();
+ * // Now open React DevTools standalone to inspect the component tree
+ * ```
+ */
+export async function connectDevTools(): Promise<boolean> {
+  if (connected) return true
+
+  try {
+    // Polyfill WebSocket for Node.js environments (required by react-devtools-core)
+    if (typeof globalThis.WebSocket === "undefined") {
+      try {
+        // @ts-expect-error -- ws is an optional peer dependency
+        const ws = await import("ws")
+        globalThis.WebSocket = ws.default ?? ws
+      } catch {
+        // ws not available -- devtools won't be able to connect
+        console.warn(
+          "silvery devtools: WebSocket polyfill (ws) not available. " +
+            "Install ws for DevTools support: bun add -d ws",
+        )
+        return false
+      }
+    }
+
+    // Ensure window/self exist for react-devtools-core internals
+    if (typeof globalThis.window === "undefined") {
+      // @ts-expect-error -- polyfill for devtools
+      globalThis.window = globalThis
+    }
+
+    // Configure component filters to hide silvery internals from the DevTools tree.
+    // Filter types from react-devtools-shared/src/types.js:
+    //   1 = ComponentFilterElementType, value 7 = HostComponent
+    //   2 = ComponentFilterDisplayName (regex on displayName)
+    if (!globalThis.__REACT_DEVTOOLS_COMPONENT_FILTERS__) {
+      globalThis.__REACT_DEVTOOLS_COMPONENT_FILTERS__ = [
+        { type: 1, value: 7, isEnabled: true },
+        { type: 2, value: "SilveryApp", isEnabled: true, isValid: true },
+      ]
+    }
+
+    // @ts-expect-error -- react-devtools-core has no type declarations
+    const devtools = await import("react-devtools-core")
+    devtools.initialize()
+    devtools.connectToDevTools()
+
+    // Inject renderer info so DevTools can identify silvery.
+    // rendererPackageName and rendererVersion are read from the host config
+    // passed to Reconciler() -- see reconciler/host-config.ts.
+    reconciler.injectIntoDevTools()
+
+    connected = true
+    return true
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    console.warn(
+      `silvery devtools: Failed to connect to React DevTools. ` +
+        `Install react-devtools-core: bun add -d react-devtools-core\n` +
+        `  Error: ${message}`,
+    )
+    return false
+  }
+}
+
+/**
+ * Check if DevTools are currently connected.
+ */
+export function isDevToolsConnected(): boolean {
+  return connected
+}
+
+/**
+ * Auto-connect to DevTools if DEBUG_DEVTOOLS=1 environment variable is set.
+ * Called internally during render initialization.
+ */
+export async function autoConnectDevTools(): Promise<void> {
+  if (process.env.DEBUG_DEVTOOLS === "1" || process.env.DEBUG_DEVTOOLS === "true") {
+    await connectDevTools()
+  }
+}
+
+// Global type augmentation for devtools polyfills
+declare global {
+  var __REACT_DEVTOOLS_COMPONENT_FILTERS__: Array<{
+    type: number
+    value: number | string
+    isEnabled: boolean
+    isValid?: boolean
+  }>
+}

package/src/dom/index.ts

@@ -0,0 +1,194 @@
+/**
+ * DOM Entry Point
+ *
+ * Provides a browser-friendly API for rendering silvery components to DOM elements.
+ * This module sets up the DOM adapter and provides render functions.
+ *
+ * Advantages over Canvas:
+ * - Native text selection and copying
+ * - Screen reader accessibility
+ * - Browser font rendering
+ * - CSS integration
+ *
+ * @example
+ * ```tsx
+ * import { renderToDOM, Box, Text, useContentRect } from '@silvery/term/dom';
+ *
+ * function App() {
+ *   const { width, height } = useContentRect();
+ *   return (
+ *     <Box flexDirection="column">
+ *       <Text>Container size: {width}px × {height}px</Text>
+ *     </Box>
+ *   );
+ * }
+ *
+ * const container = document.getElementById('app');
+ * renderToDOM(<App />, container);
+ * ```
+ */
+
+import type { ReactElement } from "react"
+import { type DOMAdapterConfig, DOMRenderBuffer, createDOMAdapter, injectDOMStyles } from "../adapters/dom-adapter"
+import { createBrowserRenderer, initBrowserRenderer, renderOnce } from "../browser-renderer"
+import type { RenderBuffer } from "../render-adapter"
+
+// Re-export components and hooks for convenience
+export { Box, type BoxProps } from "@silvery/react/components/Box"
+export { Text, type TextProps } from "@silvery/react/components/Text"
+export { useContentRect, useScreenRect } from "@silvery/react/hooks/useLayout"
+export { useApp } from "@silvery/react/hooks/useApp"
+
+// Re-export adapter utilities
+export { createDOMAdapter, DOMRenderBuffer, injectDOMStyles, type DOMAdapterConfig } from "../adapters/dom-adapter"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface DOMRenderOptions extends DOMAdapterConfig {
+  /** Width of the container (default: container.clientWidth or 800) */
+  width?: number
+  /** Height of the container (default: container.clientHeight or 600) */
+  height?: number
+  /** Inject global CSS styles (default: true) */
+  injectStyles?: boolean
+}
+
+export interface DOMInstance {
+  /** Re-render with a new element */
+  rerender: (element: ReactElement) => void
+  /** Unmount and clean up */
+  unmount: () => void
+  /** Dispose (alias for unmount) — enables `using` */
+  [Symbol.dispose](): void
+  /** Get the current buffer */
+  getBuffer: () => RenderBuffer | null
+  /** Force a re-render */
+  refresh: () => void
+  /** Get the container element */
+  getContainer: () => HTMLElement
+}
+
+// ============================================================================
+// Initialization
+// ============================================================================
+
+const domAdapterFactory = { createAdapter: (config: DOMAdapterConfig) => createDOMAdapter(config) }
+
+/**
+ * Initialize the DOM rendering system.
+ * Called automatically by renderToDOM, but can be called manually.
+ */
+export function initDOMRenderer(config: DOMAdapterConfig = {}): void {
+  initBrowserRenderer(domAdapterFactory, config)
+}
+
+// ============================================================================
+// Render Functions
+// ============================================================================
+
+/**
+ * Render a React element to a DOM container.
+ *
+ * @param element - React element to render
+ * @param container - Target DOM element
+ * @param options - Render options (font size, colors, etc.)
+ * @returns DOMInstance for controlling the render
+ *
+ * @example
+ * ```tsx
+ * const container = document.getElementById('app');
+ * const instance = renderToDOM(<App />, container, { fontSize: 16 });
+ *
+ * // Later: update the component
+ * instance.rerender(<App newProps />);
+ *
+ * // Clean up
+ * instance.unmount();
+ * ```
+ */
+export function renderToDOM(
+  element: ReactElement,
+  container: HTMLElement,
+  options: DOMRenderOptions = {},
+): DOMInstance {
+  const { injectStyles = true, ...adapterConfig } = options
+
+  if (injectStyles) {
+    injectDOMStyles(adapterConfig.classPrefix)
+  }
+
+  initDOMRenderer(adapterConfig)
+
+  const pixelWidth = options.width ?? (container.clientWidth || 800)
+  const pixelHeight = options.height ?? (container.clientHeight || 600)
+
+  // Convert pixel dimensions to cell dimensions for the layout engine.
+  // The layout engine operates in cell units (columns x rows), not pixels.
+  // We estimate cell size from font metrics: charWidth ~ fontSize * 0.6, lineHeight ~ fontSize * lineHeight.
+  const fontSize = adapterConfig.fontSize ?? 14
+  const lineHeightMultiplier = adapterConfig.lineHeight ?? 1.2
+  const charWidth = fontSize * 0.6
+  const lineHeight = fontSize * lineHeightMultiplier
+  const cols = Math.floor(pixelWidth / charWidth)
+  const rows = Math.floor(pixelHeight / lineHeight)
+
+  const base = createBrowserRenderer<DOMRenderBuffer>(
+    element,
+    cols,
+    rows,
+    (buffer) => {
+      buffer.setContainer(container)
+      buffer.render()
+    },
+    () => {
+      container.innerHTML = ""
+    },
+  )
+
+  return {
+    ...base,
+    getContainer(): HTMLElement {
+      return container
+    },
+  }
+}
+
+/**
+ * Render a React element to DOM once and return the HTML string.
+ * Useful for server-side rendering or static generation.
+ *
+ * @param element - React element to render
+ * @param width - Container width in pixels
+ * @param height - Container height in pixels
+ * @param options - Render options
+ * @returns HTML string representation
+ */
+export function renderDOMOnce(
+  element: ReactElement,
+  width: number,
+  height: number,
+  options: DOMAdapterConfig = {},
+): string {
+  initDOMRenderer(options)
+
+  // Convert pixel dimensions to cell dimensions for the layout engine
+  const fontSize = options.fontSize ?? 14
+  const lineHeightMultiplier = options.lineHeight ?? 1.2
+  const charWidth = fontSize * 0.6
+  const lineHeight = fontSize * lineHeightMultiplier
+  const cols = Math.floor(width / charWidth)
+  const rows = Math.floor(height / lineHeight)
+
+  const buffer = renderOnce<DOMRenderBuffer>(element, cols, rows)
+
+  if (typeof document !== "undefined") {
+    const tempContainer = document.createElement("div")
+    buffer.setContainer(tempContainer)
+    buffer.render()
+    return tempContainer.innerHTML
+  }
+
+  return "<!-- DOM rendering requires browser environment -->"
+}