@silvery/term 0.3.0

package/src/runtime/index.ts

@@ -0,0 +1,119 @@
+/**
+ * silvery-loop Runtime Module
+ *
+ * Provides the core primitives for the silvery-loop architecture:
+ *
+ * Layer 0: Pure render functions
+ * - layout() - React element → Buffer
+ * - diff() - Buffer diff → ANSI patch
+ *
+ * Layer 1: Runtime kernel (createRuntime)
+ * - events() - AsyncIterable event stream
+ * - schedule() - Effect scheduling
+ * - render() - Output to target
+ *
+ * Stream helpers
+ * - merge, map, filter, takeUntil, etc.
+ */
+
+// Types
+export type {
+  Buffer,
+  Dims,
+  Event,
+  RenderTarget,
+  Runtime,
+  RuntimeOptions,
+  // Provider types
+  Provider,
+  ProviderEvent,
+  NamespacedEvent,
+  ProviderEventKey,
+  EventData,
+} from "./types"
+
+// Terminal provider
+export {
+  createTermProvider,
+  type TermProvider,
+  type TermState,
+  type TermEvents,
+  type TermProviderOptions,
+} from "./term-provider"
+
+// Layer 0: Pure render functions
+export { layout, layoutSync, ensureLayoutEngine, type LayoutOptions } from "./layout"
+export { diff, render, type DiffMode } from "./diff"
+
+// Buffer helper
+export { createBuffer } from "./create-buffer"
+
+// Layer 1: Runtime kernel
+export { createRuntime } from "./create-runtime"
+
+// Layer 2: React integration
+export {
+  run,
+  useInput,
+  useExit,
+  usePaste,
+  type RunOptions,
+  type RunHandle,
+  type InputHandler,
+  type PasteHandler,
+  type Key,
+} from "./run"
+
+// Key parsing utilities
+export { parseKey, emptyKey } from "./keys"
+
+// Terminal lifecycle (suspend/resume, interrupt)
+export {
+  captureTerminalState,
+  restoreTerminalState,
+  resumeTerminalState,
+  performSuspend,
+  CTRL_C,
+  CTRL_Z,
+  type TerminalLifecycleOptions,
+  type TerminalState,
+} from "./terminal-lifecycle"
+
+// Layer 1.5: TEA store (re-exported for discoverability)
+export { createStore, silveryUpdate, defaultInit, withFocusManagement } from "@silvery/tea/store"
+export type { StoreConfig, StoreApi } from "@silvery/tea/store"
+
+// Layer 3: Store integration
+export {
+  createApp,
+  useApp,
+  useAppShallow,
+  StoreContext,
+  type AppDefinition,
+  type AppHandle,
+  type AppRunOptions,
+  type AppRunner,
+  type EventHandler,
+  type EventHandlers,
+  type EventHandlerContext,
+} from "./create-app"
+
+// Time/tick sources
+export { createTick, createFrameTick, createSecondTick, createAdaptiveTick } from "./tick"
+
+// Stream helpers (re-export from streams module)
+export {
+  merge,
+  map,
+  filter,
+  filterMap,
+  takeUntil,
+  take,
+  throttle,
+  debounce,
+  batch,
+  concat,
+  zip,
+  fromArray,
+  fromArrayWithDelay,
+} from "@silvery/tea/streams"

package/src/runtime/keys.ts

@@ -0,0 +1,8 @@
+/**
+ * Key parsing for silvery-loop runtime.
+ *
+ * Re-exports from canonical source in ../keys.ts.
+ */
+
+export type { Key, InputHandler, ParsedKeypress } from "@silvery/tea/keys"
+export { parseKey, emptyKey, parseKeypress, splitRawInput } from "@silvery/tea/keys"

package/src/runtime/layout.ts

@@ -0,0 +1,164 @@
+/**
+ * Pure layout function for silvery-loop.
+ *
+ * Takes a React element and dimensions, returns an immutable Buffer.
+ * This is Layer 0 - no runtime, no events, just pure rendering.
+ */
+
+import { createTerm } from "../ansi/index"
+import React, { type ReactElement } from "react"
+import { bufferToStyledText, bufferToText } from "../buffer"
+import { StdoutContext, StderrContext, TermContext } from "@silvery/react/context"
+import { ensureDefaultLayoutEngine, isLayoutEngineInitialized } from "../layout-engine"
+import { executeRender } from "../pipeline"
+import { createContainer, createFiberRoot, getContainerRoot, reconciler } from "@silvery/react/reconciler"
+import type { Buffer, Dims } from "./types"
+
+/**
+ * Options for the layout function.
+ */
+export interface LayoutOptions {
+  /** Skip layout notifications (for static renders). Default: true */
+  skipLayoutNotifications?: boolean
+  /** Strip ANSI codes for plain text output. Default: false */
+  plain?: boolean
+}
+
+/**
+ * Ensure layout engine is initialized.
+ * Must be called before layout() in async contexts.
+ */
+export async function ensureLayoutEngine(): Promise<void> {
+  if (!isLayoutEngineInitialized()) {
+    await ensureDefaultLayoutEngine()
+  }
+}
+
+/**
+ * Pure layout function - renders a React element to a Buffer.
+ *
+ * IMPORTANT: Call ensureLayoutEngine() first in async contexts.
+ * The layout engine must be initialized before calling this.
+ *
+ * @param element React element to render
+ * @param dims Terminal dimensions
+ * @param options Layout options
+ * @returns Immutable Buffer with text, ansi, and nodes
+ *
+ * @example
+ * ```typescript
+ * import { layout, ensureLayoutEngine } from '@silvery/term/runtime'
+ *
+ * await ensureLayoutEngine()
+ * const buffer = layout(<Text>Hello</Text>, { cols: 80, rows: 24 })
+ * console.log(buffer.text) // "Hello"
+ * ```
+ */
+export function layout(element: ReactElement, dims: Dims, options: LayoutOptions = {}): Buffer {
+  if (!isLayoutEngineInitialized()) {
+    throw new Error("Layout engine not initialized. Call ensureLayoutEngine() first.")
+  }
+
+  const { skipLayoutNotifications = true, plain = false } = options
+  const { cols: width, rows: height } = dims
+
+  // Create container for React reconciliation
+  const container = createContainer(() => {})
+
+  // Create fiber root
+  const fiberRoot = createFiberRoot(container)
+
+  // Create minimal mock stdout for components that use useStdout
+  const mockStdout = {
+    columns: width,
+    rows: height,
+    write: () => true,
+    isTTY: false,
+    on: () => mockStdout,
+    off: () => mockStdout,
+    once: () => mockStdout,
+    removeListener: () => mockStdout,
+    addListener: () => mockStdout,
+  } as unknown as NodeJS.WriteStream
+
+  // Create mock term for components that use useTerm()
+  const mockTerm = createTerm({ color: plain ? null : "truecolor" })
+
+  // Wrap with minimal contexts (no input handling needed)
+  const wrapped = React.createElement(
+    TermContext.Provider,
+    { value: mockTerm },
+    React.createElement(
+      StdoutContext.Provider,
+      {
+        value: {
+          stdout: mockStdout,
+          write: () => {},
+        },
+      },
+      React.createElement(
+        StderrContext.Provider,
+        {
+          value: {
+            stderr: process.stderr,
+            write: (data: string) => {
+              process.stderr.write(data)
+            },
+          },
+        },
+        element,
+      ),
+    ),
+  )
+
+  // Mount, render, and unmount - all without act warnings
+  withoutActWarnings(() => {
+    reconciler.updateContainerSync(wrapped, fiberRoot, null, null)
+    reconciler.flushSyncWork()
+  })
+
+  // Execute render pipeline (skip layout notifications for static renders)
+  const root = getContainerRoot(container)
+  const { buffer: termBuffer } = executeRender(root, width, height, null, {
+    skipLayoutNotifications,
+  })
+
+  // Get text representations
+  const text = bufferToText(termBuffer)
+  const ansi = bufferToStyledText(termBuffer)
+
+  // Unmount (cleanup)
+  withoutActWarnings(() => {
+    reconciler.updateContainerSync(null, fiberRoot, null, null)
+    reconciler.flushSyncWork()
+  })
+
+  return {
+    text,
+    ansi,
+    nodes: root,
+    _buffer: termBuffer,
+  }
+}
+
+/**
+ * Synchronous layout - assumes engine is already initialized.
+ * Throws if engine not ready.
+ */
+export function layoutSync(element: ReactElement, dims: Dims, options: LayoutOptions = {}): Buffer {
+  return layout(element, dims, options)
+}
+
+/**
+ * Run a function with React act warnings disabled.
+ * Used for static renders where we don't use act() and don't need layout feedback.
+ */
+function withoutActWarnings(fn: () => void): void {
+  const prev = (globalThis as any).IS_REACT_ACT_ENVIRONMENT
+  ;(globalThis as any).IS_REACT_ACT_ENVIRONMENT = false
+  try {
+    fn()
+  } finally {
+    ;(globalThis as any).IS_REACT_ACT_ENVIRONMENT = prev
+  }
+}

package/src/runtime/run.tsx

@@ -0,0 +1,318 @@
+/**
+ * run() - Layer 2 entry point for silvery-loop
+ *
+ * Thin wrapper over createApp() for simple React apps with keyboard input.
+ * Use this when you want React component state (useState, useEffect)
+ * with simple keyboard input via useInput().
+ *
+ * For stores and providers, use createApp() (Layer 3) directly.
+ *
+ * @example
+ * ```tsx
+ * import { run, useInput } from '@silvery/term/runtime'
+ *
+ * function Counter() {
+ *   const [count, setCount] = useState(0)
+ *
+ *   useInput((input, key) => {
+ *     if (input === 'j') setCount(c => c + 1)
+ *     if (key.upArrow) setCount(c => c + 1)
+ *     if (input === 'q') return 'exit'
+ *   })
+ *
+ *   return <Text>Count: {count}</Text>
+ * }
+ *
+ * await run(<Counter />)
+ * ```
+ */
+
+import React, { useContext, useEffect, useRef, type ReactElement } from "react"
+
+import { RuntimeContext } from "@silvery/react/context"
+import { createApp } from "./create-app"
+import type { Key, InputHandler } from "./keys"
+import type { Term } from "../ansi/term"
+import { detectTerminalCaps } from "../terminal-caps"
+import { detectTheme } from "@silvery/theme/detect"
+import { ThemeProvider } from "@silvery/theme/ThemeContext"
+
+// Re-export types from keys.ts
+export type { Key, InputHandler } from "./keys"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Options for run().
+ *
+ * run() auto-detects terminal capabilities and enables features by default.
+ * Pass explicit values to override. For the full list of capabilities detected,
+ * see {@link detectTerminalCaps} in terminal-caps.ts.
+ *
+ * **Mouse tracking note:** When `mouse` is enabled (the default), the terminal
+ * captures mouse events and native text selection (copy/paste) requires holding
+ * Shift (or Option on macOS in some terminals). Set `mouse: false` to restore
+ * native copy/paste behavior.
+ */
+export interface RunOptions {
+  /** Terminal dimensions (default: from process.stdout) */
+  cols?: number
+  rows?: number
+  /** Standard output (default: process.stdout) */
+  stdout?: NodeJS.WriteStream
+  /** Standard input (default: process.stdin) */
+  stdin?: NodeJS.ReadStream
+  /**
+   * Plain writable sink for ANSI output. Headless mode with active output.
+   * Requires cols and rows. Input via handle.press().
+   */
+  writable?: { write(data: string): void }
+  /** Abort signal for external cleanup */
+  signal?: AbortSignal
+  /**
+   * Enable Kitty keyboard protocol for unambiguous key identification
+   * (Cmd ⌘, Hyper ✦ modifiers, key release events).
+   * - `true`: enable with DISAMBIGUATE flag (1)
+   * - number: enable with specific KittyFlags bitfield
+   * - `false`: don't enable
+   * - Default: auto-detected from terminal (enabled for Ghostty, Kitty, WezTerm, foot)
+   */
+  kitty?: boolean | number
+  /**
+   * Enable SGR mouse tracking (mode 1006) for click, scroll, and drag events.
+   * When enabled, native text selection requires holding Shift (or Option on macOS)
+   * and native terminal scrolling is disabled.
+   * Default: `true` in fullscreen mode, `false` in inline mode (where content
+   * lives in terminal scrollback and natural scrolling is expected).
+   */
+  mouse?: boolean
+  /**
+   * Render mode: fullscreen (alt screen, default) or inline (scrollback-compatible).
+   */
+  mode?: "fullscreen" | "inline"
+  /**
+   * Enable Kitty text sizing protocol (OSC 66) for PUA characters.
+   * Ensures nerdfont/powerline icons are measured and rendered at the correct width.
+   * - `true`: force enable
+   * - `"auto"`: enable if terminal supports it (Kitty 0.40+, Ghostty)
+   * - `false`: disabled
+   * - Default: "auto"
+   */
+  textSizing?: boolean | "auto"
+  /**
+   * Enable terminal focus reporting (CSI ?1004h).
+   * Dispatches 'term:focus' events with `{ focused: boolean }`.
+   * Default: true
+   */
+  focusReporting?: boolean
+  /**
+   * Terminal capabilities for width measurement and output suppression.
+   * Default: auto-detected via detectTerminalCaps()
+   */
+  caps?: import("../terminal-caps.js").TerminalCaps
+  /**
+   * Handle Ctrl+Z by suspending the process. Default: true
+   */
+  suspendOnCtrlZ?: boolean
+  /**
+   * Handle Ctrl+C by restoring terminal and exiting. Default: true
+   */
+  exitOnCtrlC?: boolean
+  /** Called before suspend. Return false to prevent. */
+  onSuspend?: () => boolean | void
+  /** Called after resume from suspend. */
+  onResume?: () => void
+  /** Called on Ctrl+C. Return false to prevent exit. */
+  onInterrupt?: () => boolean | void
+}
+
+/**
+ * Handle returned by run() for controlling the app.
+ */
+export interface RunHandle {
+  /** Current rendered text (no ANSI) */
+  readonly text: string
+  /** Wait until the app exits */
+  waitUntilExit(): Promise<void>
+  /** Unmount and cleanup */
+  unmount(): void
+  /** Dispose (alias for unmount) — enables `using` */
+  [Symbol.dispose](): void
+  /** Send a key press */
+  press(key: string): Promise<void>
+}
+
+/** Paste handler callback type */
+export type PasteHandler = (text: string) => void
+
+// ============================================================================
+// Hooks (Layer 2 — uses RuntimeContext, works in both run() and createApp())
+// ============================================================================
+
+/**
+ * Hook for handling keyboard input.
+ *
+ * Layer 2 variant: supports returning 'exit' from the handler to exit the app.
+ * For the standard hook (isActive, onPaste options), import from 'silvery'.
+ *
+ * @example
+ * ```tsx
+ * useInput((input, key) => {
+ *   if (input === 'q') return 'exit'
+ *   if (key.upArrow) moveCursor(-1)
+ *   if (key.downArrow) moveCursor(1)
+ * })
+ * ```
+ */
+export function useInput(handler: InputHandler): void {
+  const rt = useContext(RuntimeContext)
+
+  // Stable ref for the handler — avoids tearing down/recreating the
+  // subscription on every render. Without this, rapid keystrokes between
+  // effect cleanup and setup are lost (e.g., Ctrl+D twice, Escape).
+  const handlerRef = useRef(handler)
+  handlerRef.current = handler
+
+  useEffect(() => {
+    if (!rt) return
+    return rt.on("input", (input: string, key: Key) => {
+      const result = handlerRef.current(input, key)
+      if (result === "exit") rt.exit()
+    })
+  }, [rt])
+}
+
+/**
+ * Hook for programmatic exit.
+ */
+export function useExit(): () => void {
+  const rt = useContext(RuntimeContext)
+  if (!rt) throw new Error("useExit must be used within run() or createApp()")
+  return rt.exit
+}
+
+/**
+ * Hook for handling bracketed paste events.
+ */
+export function usePaste(handler: PasteHandler): void {
+  const rt = useContext(RuntimeContext)
+
+  // Stable ref — same pattern as useInput to avoid lost paste events.
+  const handlerRef = useRef(handler)
+  handlerRef.current = handler
+
+  useEffect(() => {
+    if (!rt) return
+    return rt.on("paste", (text: string) => {
+      handlerRef.current(text)
+    })
+  }, [rt])
+}
+
+// ============================================================================
+// run() — thin wrapper over createApp()
+// ============================================================================
+
+/**
+ * Run a React component with the silvery-loop runtime.
+ *
+ * Accepts either a Term instance or RunOptions:
+ * - `run(<App />, term)` — Term handles streams, createApp handles rendering
+ * - `run(<App />, { cols, rows, ... })` — classic options API
+ *
+ * Internally delegates to createApp() with an empty store.
+ * For stores and providers, use createApp() directly.
+ */
+export async function run(element: ReactElement, term: Term): Promise<RunHandle>
+export async function run(element: ReactElement, options?: RunOptions): Promise<RunHandle>
+export async function run(element: ReactElement, optionsOrTerm: RunOptions | Term = {}): Promise<RunHandle> {
+  // Term path: pass Term as provider + its streams, auto-enable from Term caps
+  if (isTerm(optionsOrTerm)) {
+    const term = optionsOrTerm as Term
+    const emulator = (term as Record<string, unknown>)._emulator as { feed(data: string): void } | undefined
+
+    // Emulator-backed term: headless mode with writable routing to emulator
+    if (emulator) {
+      const app = createApp(() => () => ({}))
+      const handle = await app.run(element, {
+        writable: { write: (s: string) => emulator.feed(s) },
+        cols: term.cols ?? 80,
+        rows: term.rows ?? 24,
+        // Wire resize: term.subscribe() fires when term.resize() is called
+        onResize: (handler) => term.subscribe((state) => handler(state)),
+      })
+      return wrapHandle(handle)
+    }
+
+    // Real terminal: full setup
+    const caps = term.caps ?? detectTerminalCaps()
+    // Detect terminal colors via OSC — must happen before alt screen
+    const theme = await detectTheme()
+    const themed = <ThemeProvider theme={theme}>{element}</ThemeProvider>
+    const app = createApp(() => () => ({}))
+    const handle = await app.run(themed, {
+      term,
+      stdout: term.stdout,
+      stdin: term.stdin,
+      cols: term.cols ?? undefined,
+      rows: term.rows ?? undefined,
+      caps,
+      alternateScreen: true,
+      kitty: caps.kittyKeyboard,
+      mouse: true,
+      focusReporting: true,
+      textSizing: "auto",
+    })
+    return wrapHandle(handle)
+  }
+
+  // Options path: auto-detect caps and derive defaults
+  const { mode, ...rest } = optionsOrTerm as RunOptions
+  const caps = rest.caps ?? detectTerminalCaps()
+  const headless = rest.writable != null || (rest.cols != null && rest.rows != null && !rest.stdout)
+  // Detect terminal colors via OSC — must happen before alt screen (skipped for headless)
+  const themed = headless
+    ? element
+    : await detectTheme().then((theme) => <ThemeProvider theme={theme}>{element}</ThemeProvider>)
+  const app = createApp(() => () => ({}))
+  const handle = await app.run(themed, {
+    ...rest,
+    caps,
+    alternateScreen: mode !== "inline",
+    kitty: rest.kitty ?? caps.kittyKeyboard,
+    mouse: rest.mouse ?? mode !== "inline",
+    focusReporting: rest.focusReporting ?? mode !== "inline",
+    textSizing: rest.textSizing ?? "auto",
+  })
+  return wrapHandle(handle)
+}
+
+/** Duck-type check: Term has getState and events as functions.
+ *  Note: Term is a Proxy wrapping chalk, so typeof is "function" not "object". */
+function isTerm(obj: unknown): obj is Term {
+  if (obj == null) return false
+  if (typeof obj !== "object" && typeof obj !== "function") return false
+  const o = obj as Record<string, unknown>
+  return typeof o.getState === "function" && typeof o.events === "function"
+}
+
+/** Wrap AppHandle as RunHandle (subset of the full handle). */
+function wrapHandle(handle: {
+  readonly text: string
+  waitUntilExit(): Promise<void>
+  unmount(): void
+  [Symbol.dispose](): void
+  press(key: string): Promise<void>
+}): RunHandle {
+  return {
+    get text() {
+      return handle.text
+    },
+    waitUntilExit: () => handle.waitUntilExit(),
+    unmount: () => handle.unmount(),
+    [Symbol.dispose]: () => handle[Symbol.dispose](),
+    press: (key: string) => handle.press(key),
+  }
+}