@silvery/term 0.3.0

package/src/xterm/index.ts

@@ -0,0 +1,491 @@
+/**
+ * xterm.js Entry Point
+ *
+ * Provides a browser-friendly API for rendering silvery components to xterm.js terminals.
+ * This module sets up the terminal adapter and writes ANSI output to an xterm.js Terminal.
+ *
+ * The terminal adapter produces ANSI diff strings via `flush()`. xterm.js accepts ANSI
+ * via `term.write()`. This entry point bridges the two.
+ *
+ * `renderToXterm()` renders silvery components to xterm.js with full runtime support:
+ * useInput, focus management, and mouse events all work out of the box when
+ * `input: true` (or input callbacks) is provided.
+ *
+ * @example
+ * ```tsx
+ * import { Terminal } from "@xterm/xterm"
+ * import { renderToXterm, Box, Text, useContentRect } from '@silvery/term/xterm';
+ *
+ * function App() {
+ *   const { width, height } = useContentRect();
+ *   return (
+ *     <Box flexDirection="column">
+ *       <Text>Terminal size: {width} cols x {height} rows</Text>
+ *     </Box>
+ *   );
+ * }
+ *
+ * const term = new Terminal({ cols: 80, rows: 24 });
+ * term.open(document.getElementById('terminal')!);
+ * renderToXterm(<App />, term, { input: true });
+ * ```
+ */
+
+import React, { type ReactElement } from "react"
+import { createFlexilyZeroEngine } from "../adapters/flexily-zero-adapter"
+import { terminalAdapter } from "../adapters/terminal-adapter"
+import { setLayoutEngine } from "../layout-engine"
+import { executeRenderAdapter } from "../pipeline"
+import {
+  createContainer,
+  createFiberRoot,
+  getContainerRoot,
+  reconciler,
+  runWithDiscreteEvent,
+  setOnNodeRemoved,
+} from "@silvery/react/reconciler"
+import type { RenderBuffer } from "../render-adapter"
+import { setRenderAdapter } from "../render-adapter"
+import { RuntimeContext, FocusManagerContext, type RuntimeContextValue } from "@silvery/react/context"
+import { createFocusManager } from "@silvery/tea/focus-manager"
+import { parseKey, splitRawInput } from "@silvery/tea/keys"
+import { parseBracketedPaste } from "../bracketed-paste"
+import { createXtermProvider, type XtermProvider } from "./xterm-provider"
+
+// 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 { Divider, type DividerProps } from "@silvery/ui/components/Divider"
+export { TextInput, type TextInputProps, type TextInputHandle } from "@silvery/ui/components/TextInput"
+export { Spinner, type SpinnerProps } from "@silvery/ui/components/Spinner"
+export { useContentRect, useScreenRect } from "@silvery/react/hooks/useLayout"
+export { useApp } from "@silvery/react/hooks/useApp"
+export { useInput, type Key, type InputHandler, type UseInputOptions } from "@silvery/react/hooks/useInput"
+
+// Re-export adapter utilities
+export { terminalAdapter } from "../adapters/terminal-adapter"
+
+// Re-export provider for advanced usage
+export { createXtermProvider, type XtermProvider } from "./xterm-provider"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Duck-typed xterm.js Terminal interface — only the methods we need */
+export interface XtermTerminal {
+  write(data: string): void
+  readonly cols: number
+  readonly rows: number
+  /** Subscribe to terminal data (keyboard + mouse sequences). Required for input wiring. */
+  onData?: (callback: (data: string) => void) => { dispose(): void }
+  /** The hidden textarea xterm.js uses for focus. Required for focus tracking. */
+  textarea?: HTMLTextAreaElement | null
+}
+
+/** Mouse event info passed to onMouse callback */
+export interface XtermMouseInfo {
+  /** 0-indexed column */
+  x: number
+  /** 0-indexed row */
+  y: number
+  /** Mouse button (0=left, 1=middle, 2=right) */
+  button: number
+}
+
+/** Input handling options for renderToXterm */
+export interface XtermInputOptions {
+  /** Called on keyboard input (raw terminal data, after mouse sequences are filtered out) */
+  onKey?: (data: string) => void
+  /** Called on mouse press (SGR mode). Receives 0-indexed coordinates and button. */
+  onMouse?: (info: XtermMouseInfo) => void
+  /** Called when the terminal gains or loses focus */
+  onFocus?: (focused: boolean) => void
+}
+
+export interface XtermRenderOptions {
+  /** Width in columns (default: terminal.cols) */
+  cols?: number
+  /** Height in rows (default: terminal.rows) */
+  rows?: number
+  /** Called when the terminal is resized via fitAddon.fit() or resize() */
+  onResize?: (cols: number, rows: number) => void
+  /**
+   * Enable automatic input handling (keyboard, mouse, focus).
+   *
+   * When enabled, `useInput()` and focus management work inside rendered components.
+   *
+   * - `true` — enable mouse tracking and parse onData, but no callbacks
+   * - `{ onKey, onMouse, onFocus }` — enable with callbacks
+   * - `false` — disable (caller handles input manually)
+   *
+   * Default: `false` (backwards compatible)
+   */
+  input?: boolean | XtermInputOptions
+  /**
+   * Exit on Ctrl+C (default: true when input is enabled).
+   * When true, Ctrl+C will trigger the exit callback.
+   */
+  exitOnCtrlC?: boolean
+  /**
+   * Handle Tab/Shift+Tab/Escape focus cycling (default: true when input is enabled).
+   */
+  handleFocusCycling?: boolean
+}
+
+export interface XtermInstance {
+  /** 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
+  /** Force a re-render */
+  refresh: () => void
+  /** Resize the terminal and re-render. Overrides dynamic terminal.cols/rows. */
+  resize: (cols: number, rows: number) => void
+}
+
+// ============================================================================
+// ANSI Escape Sequences
+// ============================================================================
+
+const CURSOR_HIDE = "\x1b[?25l"
+const CURSOR_SHOW = "\x1b[?25h"
+const CURSOR_HOME = "\x1b[H"
+const CLEAR_SCREEN = "\x1b[2J"
+
+// ============================================================================
+// Initialization
+// ============================================================================
+
+let initialized = false
+
+function initXtermRenderer(): void {
+  if (initialized) return
+
+  setLayoutEngine(createFlexilyZeroEngine())
+  setRenderAdapter(terminalAdapter)
+
+  initialized = true
+}
+
+// ============================================================================
+// Input handler type for subscriber list
+// ============================================================================
+
+type InputEventHandler = (input: string, key: import("@silvery/tea/keys").Key) => void
+type PasteEventHandler = (text: string) => void
+
+// ============================================================================
+// Render Functions
+// ============================================================================
+
+/**
+ * Render a React element to an xterm.js terminal.
+ *
+ * Uses the terminal adapter to produce ANSI diff strings, then writes them
+ * to the terminal via `term.write()`.
+ *
+ * When `input` is enabled, provides full runtime support:
+ * - `useInput()` works for keyboard input handling
+ * - Focus management (Tab/Shift+Tab/Escape cycling)
+ * - Mouse events via SGR protocol
+ * - Paste detection via bracketed paste sequences
+ *
+ * @param element - React element to render
+ * @param terminal - xterm.js Terminal (or any object with write/cols/rows)
+ * @param options - Render options (cols, rows overrides, input handling)
+ * @returns XtermInstance for controlling the render
+ *
+ * @example
+ * ```tsx
+ * const term = new Terminal({ cols: 80, rows: 24 });
+ * term.open(container);
+ *
+ * // With useInput support
+ * const instance = renderToXterm(<App />, term, { input: true });
+ *
+ * // With callbacks
+ * const instance = renderToXterm(<App />, term, {
+ *   input: {
+ *     onKey: (data) => console.log('key:', data),
+ *     onMouse: ({ x, y }) => console.log('click:', x, y),
+ *   },
+ * });
+ *
+ * instance.unmount();
+ * ```
+ */
+export function renderToXterm(
+  element: ReactElement,
+  terminal: XtermTerminal,
+  options: XtermRenderOptions = {},
+): XtermInstance {
+  initXtermRenderer()
+
+  // If cols/rows were explicitly provided, use those (fixed size).
+  // Otherwise, read from terminal.cols/rows at render time (dynamic).
+  const fixedCols = options.cols ?? null
+  const fixedRows = options.rows ?? null
+  let overrideCols: number | null = null
+  let overrideRows: number | null = null
+
+  function getCols(): number {
+    return overrideCols ?? fixedCols ?? terminal.cols
+  }
+  function getRows(): number {
+    return overrideRows ?? fixedRows ?? terminal.rows
+  }
+
+  const container = createContainer(() => {
+    scheduleRender()
+  })
+
+  const root = getContainerRoot(container)
+  const fiberRoot = createFiberRoot(container)
+
+  let currentBuffer: RenderBuffer | null = null
+  let currentElement: ReactElement = element
+  let renderScheduled = false
+  let unmounted = false
+
+  // ---- Input / Runtime setup ----
+  const inputOpts = options.input
+  const inputEnabled = inputOpts === true || (typeof inputOpts === "object" && inputOpts !== null)
+  const inputCallbacks: XtermInputOptions = typeof inputOpts === "object" && inputOpts !== null ? inputOpts : {}
+  const exitOnCtrlC = options.exitOnCtrlC ?? inputEnabled
+  const handleFocusCycling = options.handleFocusCycling ?? inputEnabled
+
+  // Create xterm provider for input handling (only when input is enabled)
+  let provider: XtermProvider | null = null
+  let focusManager: ReturnType<typeof createFocusManager> | null = null
+  let runtimeContextValue: RuntimeContextValue | null = null
+
+  // Subscriber lists for RuntimeContext (no EventEmitter)
+  const inputHandlers = new Set<InputEventHandler>()
+  const pasteHandlers = new Set<PasteEventHandler>()
+
+  // Exit handler — uses doUnmount() indirection to avoid referencing
+  // the `unmount` const before it's declared.
+  let doUnmount: () => void = () => {}
+  const handleExit = (error?: Error) => {
+    doUnmount()
+  }
+
+  if (inputEnabled) {
+    provider = createXtermProvider(terminal)
+    focusManager = createFocusManager()
+
+    // Wire up focus cleanup on node removal
+    setOnNodeRemoved((removedNode) => focusManager!.handleSubtreeRemoved(removedNode))
+
+    // Wire provider input to RuntimeContext subscribers + user callbacks
+    provider.onInput((chunk: string) => {
+      if (unmounted) return
+
+      // Check for bracketed paste
+      const pasteResult = parseBracketedPaste(chunk)
+      if (pasteResult) {
+        for (const handler of pasteHandlers) {
+          handler(pasteResult.content)
+        }
+        return
+      }
+
+      // Split and process individual keys
+      for (const keypress of splitRawInput(chunk)) {
+        processKey(keypress)
+      }
+    })
+
+    // Wire mouse events to user callback
+    if (inputCallbacks.onMouse) {
+      const onMouse = inputCallbacks.onMouse
+      provider.onMouse((info) => {
+        if (info.type === "press" && info.button <= 2) {
+          onMouse({ x: info.x, y: info.y, button: info.button })
+        }
+      })
+    }
+
+    // Wire focus events to user callback
+    if (inputCallbacks.onFocus) {
+      provider.onFocus(inputCallbacks.onFocus)
+    }
+
+    // Enable SGR mouse tracking
+    provider.enableMouse()
+
+    // Process a single keypress — handles Ctrl+C, focus cycling, then dispatches
+    function processKey(rawKey: string): void {
+      // Handle Ctrl+C
+      if (rawKey === "\x03" && exitOnCtrlC) {
+        handleExit()
+        return
+      }
+
+      // Focus cycling (Tab/Shift+Tab/Escape)
+      if (handleFocusCycling && focusManager) {
+        const treeRoot = getContainerRoot(container)
+        if (treeRoot) {
+          const [, key] = parseKey(rawKey)
+          if (key.tab && !key.shift) {
+            focusManager.focusNext(treeRoot)
+            reconciler.flushSyncWork()
+            return
+          }
+          if (key.tab && key.shift) {
+            focusManager.focusPrev(treeRoot)
+            reconciler.flushSyncWork()
+            return
+          }
+          if (key.escape && focusManager.activeElement) {
+            focusManager.blur()
+            reconciler.flushSyncWork()
+            return
+          }
+        }
+      }
+
+      // Parse and dispatch to RuntimeContext subscribers
+      const [input, key] = parseKey(rawKey)
+      runWithDiscreteEvent(() => {
+        for (const handler of inputHandlers) {
+          handler(input, key)
+        }
+      })
+      reconciler.flushSyncWork()
+
+      // Also call user callback
+      inputCallbacks.onKey?.(rawKey)
+    }
+
+    // Build RuntimeContext value
+    runtimeContextValue = {
+      on(event, handler) {
+        if (event === "input") {
+          const typed = handler as InputEventHandler
+          inputHandlers.add(typed)
+          return () => {
+            inputHandlers.delete(typed)
+          }
+        }
+        if (event === "paste") {
+          const typed = handler as unknown as PasteEventHandler
+          pasteHandlers.add(typed)
+          return () => {
+            pasteHandlers.delete(typed)
+          }
+        }
+        return () => {} // Unknown event — no-op cleanup
+      },
+      emit() {
+        // renderToXterm doesn't support view → runtime events
+      },
+      exit: handleExit,
+    }
+  }
+
+  // Wrap element with context providers when input is enabled
+  function wrapElement(el: ReactElement): ReactElement {
+    if (!inputEnabled || !runtimeContextValue || !focusManager) return el
+    return React.createElement(
+      FocusManagerContext.Provider,
+      { value: focusManager },
+      React.createElement(RuntimeContext.Provider, { value: runtimeContextValue }, el),
+    )
+  }
+
+  function scheduleRender(): void {
+    if (renderScheduled || unmounted) return
+    renderScheduled = true
+
+    if (typeof requestAnimationFrame !== "undefined") {
+      requestAnimationFrame(() => {
+        renderScheduled = false
+        doRender()
+      })
+    } else {
+      setTimeout(() => {
+        renderScheduled = false
+        doRender()
+      }, 0)
+    }
+  }
+
+  function doRender(): void {
+    if (unmounted) return
+    reconciler.updateContainerSync(wrapElement(currentElement), fiberRoot, null, null)
+    reconciler.flushSyncWork()
+
+    const prevBuffer = currentBuffer
+    const result = executeRenderAdapter(root, getCols(), getRows(), prevBuffer)
+    currentBuffer = result.buffer
+
+    // The terminal adapter's flush() returns ANSI diff strings
+    if (typeof result.output === "string" && result.output.length > 0) {
+      terminal.write(result.output)
+    }
+  }
+
+  // Initial render: hide cursor, clear screen, move to home, then render
+  terminal.write(CURSOR_HIDE + CURSOR_HOME + CLEAR_SCREEN)
+  doRender()
+  // Second pass picks up layout feedback (useContentRect dimensions).
+  // Without this, the first frame shows zeros because forceUpdate() is
+  // deferred to requestAnimationFrame, which may not fire in iframes.
+  doRender()
+
+  const unmount = (): void => {
+    if (unmounted) return
+    unmounted = true
+
+    // Clean up provider (input wiring, mouse tracking)
+    if (provider) {
+      provider.disableMouse()
+      provider.dispose()
+    }
+    // Synchronous unmount ensures useEffect cleanups (e.g. clearInterval) run
+    // before returning, preventing stale renders to the same terminal.
+    reconciler.updateContainerSync(null, fiberRoot, null, null)
+    reconciler.flushSyncWork()
+    // Unregister node removal hook
+    setOnNodeRemoved(null)
+    // Clean up subscriber lists
+    inputHandlers.clear()
+    pasteHandlers.clear()
+    // Show cursor on unmount
+    terminal.write(CURSOR_SHOW)
+  }
+  doUnmount = unmount
+
+  return {
+    rerender(newElement: ReactElement): void {
+      currentElement = newElement
+      scheduleRender()
+    },
+
+    unmount,
+    [Symbol.dispose]: unmount,
+
+    refresh(): void {
+      scheduleRender()
+    },
+
+    resize(cols: number, rows: number): void {
+      overrideCols = cols
+      overrideRows = rows
+      // Clear the buffer so next render does a full repaint at the new size
+      currentBuffer = null
+      terminal.write(CURSOR_HOME + CLEAR_SCREEN)
+      options.onResize?.(cols, rows)
+      // Two passes: first pass calculates layout at new size and notifies
+      // useContentRect subscribers, second pass picks up the updated values.
+      // Without this, resize causes a flash of stale dimensions.
+      renderScheduled = false
+      doRender()
+      doRender()
+    },
+  }
+}

package/src/xterm/xterm-provider.ts

@@ -0,0 +1,204 @@
+/**
+ * xterm.js Provider — browser-friendly input/output adapter.
+ *
+ * Bridges an xterm.js Terminal into a provider interface that silvery's
+ * RuntimeContext can consume. No Node.js dependencies.
+ *
+ * Handles:
+ * - Keyboard input (via terminal.onData)
+ * - Mouse input (SGR mode parsing)
+ * - Focus tracking (via textarea focus/blur)
+ * - Terminal dimensions
+ * - ANSI output
+ *
+ * @example
+ * ```typescript
+ * import { createXtermProvider } from "@silvery/term/xterm/xterm-provider"
+ *
+ * const provider = createXtermProvider(terminal)
+ * const cleanup = provider.onInput((chunk) => {
+ *   // raw terminal data, ready for parseKey/splitRawInput
+ * })
+ * provider.write(ansiOutput)
+ * provider.dispose()
+ * ```
+ */
+
+import type { XtermTerminal } from "./index"
+
+// SGR mouse sequence regex: \x1b[<btn;x;yM (press) or \x1b[<btn;x;ym (release)
+const SGR_MOUSE_RE = /\x1b\[<(\d+);(\d+);(\d+)([Mm])/g
+
+// Mouse tracking: Normal mode + SGR extended mode
+const MOUSE_ENABLE = "\x1b[?1000h\x1b[?1006h"
+const MOUSE_DISABLE = "\x1b[?1000l\x1b[?1006l"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface XtermProvider {
+  /**
+   * Subscribe to raw input chunks (keyboard data with mouse sequences stripped).
+   * The chunks are raw terminal escape sequences suitable for splitRawInput/parseKey.
+   * Returns cleanup function.
+   */
+  onInput(handler: (chunk: string) => void): () => void
+
+  /**
+   * Subscribe to mouse events (SGR mode, parsed).
+   * Returns cleanup function.
+   */
+  onMouse(handler: (info: { x: number; y: number; button: number; type: "press" | "release" }) => void): () => void
+
+  /**
+   * Subscribe to focus changes.
+   * Returns cleanup function.
+   */
+  onFocus(handler: (focused: boolean) => void): () => void
+
+  /** Get current dimensions */
+  dims(): { cols: number; rows: number }
+
+  /** Write ANSI output to terminal */
+  write(data: string): void
+
+  /** Enable SGR mouse tracking */
+  enableMouse(): void
+
+  /** Disable SGR mouse tracking */
+  disableMouse(): void
+
+  /** Clean up all listeners */
+  dispose(): void
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Create a provider that bridges an xterm.js Terminal to silvery's input system.
+ *
+ * The provider separates mouse sequences from keyboard input, so consumers
+ * get clean keyboard data via `onInput` and parsed mouse events via `onMouse`.
+ */
+export function createXtermProvider(terminal: XtermTerminal): XtermProvider {
+  const inputHandlers = new Set<(chunk: string) => void>()
+  const mouseHandlers = new Set<(info: { x: number; y: number; button: number; type: "press" | "release" }) => void>()
+  const focusHandlers = new Set<(focused: boolean) => void>()
+  const disposables: Array<{ dispose(): void }> = []
+  let disposed = false
+
+  // Wire terminal.onData — split mouse sequences from keyboard input
+  if (terminal.onData) {
+    const dataDisposable = terminal.onData((data: string) => {
+      if (disposed) return
+
+      // Extract all mouse sequences, forward keyboard remainder
+      let lastIndex = 0
+      let keyboardData = ""
+
+      SGR_MOUSE_RE.lastIndex = 0
+      let match: RegExpExecArray | null
+      while ((match = SGR_MOUSE_RE.exec(data)) !== null) {
+        // Collect keyboard data before this mouse sequence
+        if (match.index > lastIndex) {
+          keyboardData += data.slice(lastIndex, match.index)
+        }
+        lastIndex = match.index + match[0].length
+
+        // Parse and dispatch mouse event
+        const btn = parseInt(match[1]!, 10)
+        const x = parseInt(match[2]!, 10) - 1 // 1-indexed → 0-indexed
+        const y = parseInt(match[3]!, 10) - 1
+        const type = match[4] === "M" ? ("press" as const) : ("release" as const)
+
+        for (const handler of mouseHandlers) {
+          handler({ x, y, button: btn, type })
+        }
+      }
+
+      // Remaining keyboard data after last mouse sequence
+      if (lastIndex < data.length) {
+        keyboardData += data.slice(lastIndex)
+      }
+
+      // Dispatch keyboard input if any
+      if (keyboardData.length > 0) {
+        for (const handler of inputHandlers) {
+          handler(keyboardData)
+        }
+      }
+    })
+    disposables.push(dataDisposable)
+  }
+
+  // Wire focus/blur tracking via xterm.js textarea
+  if (terminal.textarea) {
+    const textarea = terminal.textarea
+    const onFocusIn = () => {
+      for (const handler of focusHandlers) handler(true)
+    }
+    const onFocusOut = () => {
+      for (const handler of focusHandlers) handler(false)
+    }
+    textarea.addEventListener("focus", onFocusIn)
+    textarea.addEventListener("blur", onFocusOut)
+    disposables.push({
+      dispose() {
+        textarea.removeEventListener("focus", onFocusIn)
+        textarea.removeEventListener("blur", onFocusOut)
+      },
+    })
+  }
+
+  return {
+    onInput(handler) {
+      inputHandlers.add(handler)
+      return () => {
+        inputHandlers.delete(handler)
+      }
+    },
+
+    onMouse(handler) {
+      mouseHandlers.add(handler)
+      return () => {
+        mouseHandlers.delete(handler)
+      }
+    },
+
+    onFocus(handler) {
+      focusHandlers.add(handler)
+      return () => {
+        focusHandlers.delete(handler)
+      }
+    },
+
+    dims() {
+      return { cols: terminal.cols, rows: terminal.rows }
+    },
+
+    write(data: string) {
+      terminal.write(data)
+    },
+
+    enableMouse() {
+      terminal.write(MOUSE_ENABLE)
+    },
+
+    disableMouse() {
+      terminal.write(MOUSE_DISABLE)
+    },
+
+    dispose() {
+      if (disposed) return
+      disposed = true
+      for (const d of disposables) d.dispose()
+      disposables.length = 0
+      inputHandlers.clear()
+      mouseHandlers.clear()
+      focusHandlers.clear()
+    },
+  }
+}