@silvery/term 0.3.0

package/src/runtime/create-buffer.ts

@@ -0,0 +1,18 @@
+import { type TerminalBuffer, bufferToStyledText, bufferToText } from "../buffer"
+import type { TeaNode } from "@silvery/tea/types"
+import type { Buffer } from "./types"
+
+export function createBuffer(termBuffer: TerminalBuffer, nodes: TeaNode): Buffer {
+  let _text: string | undefined
+  let _ansi: string | undefined
+  return {
+    get text() {
+      return (_text ??= bufferToText(termBuffer))
+    },
+    get ansi() {
+      return (_ansi ??= bufferToStyledText(termBuffer))
+    },
+    nodes,
+    _buffer: termBuffer,
+  }
+}

package/src/runtime/create-runtime.ts

@@ -0,0 +1,325 @@
+/**
+ * Create the silvery-loop runtime kernel.
+ *
+ * The runtime owns the event loop, diffing, and output. Users interact via:
+ * - events() - AsyncIterable of all events (keys, resize, effects)
+ * - schedule() - Queue effects for async execution
+ * - render() - Output a buffer (diffing handled internally)
+ *
+ * NOTE: This runtime is designed for single-consumer use. Calling events()
+ * multiple times concurrently will cause events to be split between consumers.
+ * Each call returns a fresh AsyncIterable, but they share the underlying queue.
+ *
+ * @example
+ * ```typescript
+ * using runtime = createRuntime({ target: termTarget })
+ *
+ * for await (const event of runtime.events()) {
+ *   state = reducer(state, event)
+ *   runtime.render(layout(view(state), runtime.getDims()))
+ * }
+ * ```
+ */
+
+import { createOutputPhase } from "../pipeline/output-phase"
+import { takeUntil } from "@silvery/tea/streams"
+import { diff } from "./diff"
+import type { Buffer, Dims, Event, Runtime, RuntimeOptions } from "./types"
+
+// =============================================================================
+// Event Channel - unified async iterable for all internal events
+// =============================================================================
+
+interface EventChannel {
+  push(event: Event): void
+  events(): AsyncIterable<Event>
+  dispose(): void
+}
+
+/**
+ * Create an event channel that bridges callbacks to AsyncIterable.
+ *
+ * This is the single point where callbacks (resize, effect completion)
+ * are converted to the async iterable pattern. External sources like
+ * keyboard events are already AsyncIterable and merged at a higher level.
+ */
+function createEventChannel(signal: AbortSignal): EventChannel {
+  const queue: Event[] = []
+  let pendingResolve: ((event: Event | null) => void) | undefined
+  let disposed = false
+
+  // Resolve pending waiter on abort
+  const onAbort = () => {
+    if (pendingResolve) {
+      pendingResolve(null)
+      pendingResolve = undefined
+    }
+  }
+  signal.addEventListener("abort", onAbort, { once: true })
+
+  return {
+    push(event: Event): void {
+      if (disposed || signal.aborted) return
+
+      if (pendingResolve) {
+        const r = pendingResolve
+        pendingResolve = undefined
+        r(event)
+      } else {
+        queue.push(event)
+      }
+    },
+
+    events(): AsyncIterable<Event> {
+      return {
+        [Symbol.asyncIterator](): AsyncIterator<Event> {
+          return {
+            async next(): Promise<IteratorResult<Event>> {
+              if (disposed || signal.aborted) {
+                return { done: true, value: undefined }
+              }
+
+              // Return queued event if available
+              if (queue.length > 0) {
+                return { done: false, value: queue.shift()! }
+              }
+
+              // Wait for next event or abort
+              const event = await new Promise<Event | null>((resolve) => {
+                pendingResolve = resolve
+              })
+
+              if (event === null || disposed || signal.aborted) {
+                return { done: true, value: undefined }
+              }
+
+              return { done: false, value: event }
+            },
+          }
+        },
+      }
+    },
+
+    dispose(): void {
+      disposed = true
+      signal.removeEventListener("abort", onAbort)
+      if (pendingResolve) {
+        pendingResolve(null)
+        pendingResolve = undefined
+      }
+    },
+  }
+}
+
+// =============================================================================
+// Runtime Factory
+// =============================================================================
+
+/**
+ * Create a runtime kernel.
+ *
+ * @param options Runtime configuration
+ * @returns Runtime instance implementing Symbol.dispose
+ */
+export function createRuntime(options: RuntimeOptions): Runtime {
+  const { target, signal: externalSignal, mode = "fullscreen" } = options
+
+  // Inline mode needs persistent cursor tracking across frames.
+  // If no outputPhaseFn provided, create one so prevCursorRow/prevOutputLines
+  // persist between renders (bare diff() creates fresh state each call).
+  const fallbackOutputPhase = mode === "inline" ? createOutputPhase({}) : undefined
+  const outputPhaseFn = options.outputPhaseFn ?? fallbackOutputPhase
+
+  // Internal abort controller for cleanup
+  const controller = new AbortController()
+  const signal = controller.signal
+
+  // Wire external signal if provided - track for cleanup
+  let externalAbortHandler: (() => void) | undefined
+  if (externalSignal) {
+    if (externalSignal.aborted) {
+      controller.abort()
+    } else {
+      externalAbortHandler = () => controller.abort()
+      externalSignal.addEventListener("abort", externalAbortHandler, {
+        once: true,
+      })
+    }
+  }
+
+  // Track previous buffer for diffing
+  let prevBuffer: Buffer | null = null
+
+  // Scrollback offset tracking (inline mode only)
+  let scrollbackOffset = 0
+
+  // Track if disposed
+  let disposed = false
+
+  // Unified event channel for resize and effect events
+  const eventChannel = createEventChannel(signal)
+
+  // Subscribe to resize events if supported
+  let unsubscribeResize: (() => void) | undefined
+  if (target.onResize) {
+    unsubscribeResize = target.onResize((dims) => {
+      eventChannel.push({ type: "resize", cols: dims.cols, rows: dims.rows })
+    })
+  }
+
+  // Effect ID counter
+  let effectId = 0
+
+  return {
+    events(): AsyncIterable<Event> {
+      // Return channel events wrapped with takeUntil for cleanup
+      return takeUntil(eventChannel.events(), signal)
+    },
+
+    schedule<T>(effect: () => Promise<T>, opts?: { signal?: AbortSignal }): void {
+      if (disposed) return
+
+      const id = `effect-${effectId++}`
+      const effectSignal = opts?.signal
+
+      // Check if already aborted
+      if (effectSignal?.aborted) return
+
+      // Execute effect asynchronously
+      const execute = async () => {
+        // Track abort handler for cleanup
+        let abortHandler: (() => void) | undefined
+
+        try {
+          if (effectSignal) {
+            // Create abort race with cleanup
+            const aborted = new Promise<never>((_resolve, reject) => {
+              abortHandler = () => reject(new Error("Effect aborted"))
+              effectSignal.addEventListener("abort", abortHandler, {
+                once: true,
+              })
+            })
+
+            const result = await Promise.race([effect(), aborted])
+
+            // Clean up abort listener after success
+            if (abortHandler) {
+              effectSignal.removeEventListener("abort", abortHandler)
+            }
+
+            eventChannel.push({ type: "effect", id, result })
+          } else {
+            const result = await effect()
+            eventChannel.push({ type: "effect", id, result })
+          }
+        } catch (error) {
+          // Clean up abort listener on error too
+          if (abortHandler && effectSignal) {
+            effectSignal.removeEventListener("abort", abortHandler)
+          }
+
+          // Check for abort by name (handles DOMException, AbortError, etc.)
+          if (error instanceof Error && (error.message === "Effect aborted" || error.name === "AbortError")) {
+            // Silently ignore aborted effects
+            return
+          }
+          eventChannel.push({
+            type: "error",
+            error: error instanceof Error ? error : new Error(String(error)),
+          })
+        }
+      }
+
+      // Start immediately (microtask)
+      queueMicrotask(() => {
+        void execute()
+      })
+    },
+
+    render(buffer: Buffer): void {
+      if (disposed) return
+
+      // Compute diff internally — pass terminal rows to cap output.
+      // Inline mode: prevents scrollback corruption (cursor-up clamped at row 0).
+      // Fullscreen mode: prevents buffer overflow that scrolls the terminal and
+      // desynchronizes prevBuffer from actual terminal state (ghost pixel garble).
+      const offset = scrollbackOffset
+      scrollbackOffset = 0 // Consume the offset
+      const termRows = target.getDims().rows
+
+      // Use scoped output phase if provided (threads measurer/caps correctly),
+      // otherwise fall back to raw diff() for backwards compatibility
+      let patch: string
+      if (outputPhaseFn) {
+        const prevBuf = prevBuffer?._buffer ?? null
+        const nextBuf = buffer._buffer
+        patch = outputPhaseFn(prevBuf, nextBuf, mode, offset, termRows)
+      } else {
+        patch = diff(prevBuffer, buffer, mode, offset, termRows)
+      }
+      prevBuffer = buffer
+
+      // Debug: capture raw ANSI output that's actually written to the terminal
+      if (process.env.SILVERY_CAPTURE_RAW) {
+        try {
+          const fs = require("fs")
+          fs.appendFileSync("/tmp/silvery-runtime-raw.ansi", patch)
+        } catch {}
+      }
+
+      // Write to target
+      target.write(patch)
+    },
+
+    addScrollbackLines(lines: number): void {
+      if (mode !== "inline" || lines <= 0) return
+      scrollbackOffset += lines
+    },
+
+    invalidate(): void {
+      prevBuffer = null
+    },
+
+    resetInlineCursor(): void {
+      // Reset inline cursor tracking — delegates to the output phase (either
+      // the caller-provided one or the inline-mode fallback created above).
+      const fn = outputPhaseFn as { resetInlineState?: () => void } | undefined
+      fn?.resetInlineState?.()
+    },
+
+    getInlineCursorRow(): number {
+      const fn = outputPhaseFn as { getInlineCursorRow?: () => number } | undefined
+      return fn?.getInlineCursorRow?.() ?? -1
+    },
+
+    promoteScrollback(content: string, lines: number): void {
+      const fn = outputPhaseFn as { promoteScrollback?: (c: string, l: number) => void } | undefined
+      fn?.promoteScrollback?.(content, lines)
+    },
+
+    getDims(): Dims {
+      return target.getDims()
+    },
+
+    [Symbol.dispose](): void {
+      if (disposed) return
+      disposed = true
+
+      // Abort all pending operations
+      controller.abort()
+
+      // Remove external signal listener if still attached
+      if (externalAbortHandler && externalSignal) {
+        externalSignal.removeEventListener("abort", externalAbortHandler)
+      }
+
+      // Unsubscribe from resize
+      if (unsubscribeResize) {
+        unsubscribeResize()
+      }
+
+      // Dispose event channel
+      eventChannel.dispose()
+    },
+  }
+}

package/src/runtime/diff.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure diff function for silvery-loop.
+ *
+ * Takes prev and next buffers, returns minimal ANSI patch.
+ * This is an internal function used by the runtime.
+ */
+
+import { outputPhase } from "../pipeline"
+import type { Buffer } from "./types"
+
+/**
+ * Diff mode for ANSI output.
+ */
+export type DiffMode = "fullscreen" | "inline"
+
+/**
+ * Compute the minimal ANSI diff between two buffers.
+ *
+ * @param prev Previous buffer (null on first render)
+ * @param next Current buffer
+ * @param mode Render mode (fullscreen or inline)
+ * @returns ANSI escape sequence string to transform prev into next
+ *
+ * @example
+ * ```typescript
+ * import { diff, layout } from '@silvery/term/runtime'
+ *
+ * const prev = layout(<Text>Hello</Text>, dims)
+ * const next = layout(<Text>World</Text>, dims)
+ * const patch = diff(prev, next)
+ * process.stdout.write(patch)
+ * ```
+ */
+export function diff(
+  prev: Buffer | null,
+  next: Buffer,
+  mode: DiffMode = "fullscreen",
+  scrollbackOffset = 0,
+  termRows?: number,
+): string {
+  const prevBuffer = prev?._buffer ?? null
+  const nextBuffer = next._buffer
+
+  return outputPhase(prevBuffer, nextBuffer, mode, scrollbackOffset, termRows)
+}
+
+/**
+ * Render a buffer to ANSI string (no diff, full render).
+ *
+ * @param buffer Buffer to render
+ * @param mode Render mode (fullscreen or inline)
+ * @returns Full ANSI output
+ */
+export function render(buffer: Buffer, mode: DiffMode = "fullscreen"): string {
+  return outputPhase(null, buffer._buffer, mode)
+}

package/src/runtime/event-handlers.ts

@@ -0,0 +1,254 @@
+/**
+ * Event handler composition for createApp runtime.
+ *
+ * Extracted from create-app.tsx to reduce nesting depth.
+ * Contains: handler context creation, focus navigation dispatch,
+ * mouse event dispatch, and key handler dispatch.
+ *
+ * All functions are pure or near-pure — they don't access the event loop's
+ * mutable state (pendingRerender, isRendering, etc.), which stays in create-app.tsx.
+ */
+
+import type { StoreApi } from "zustand"
+
+import { createKeyEvent, dispatchKeyEvent } from "@silvery/tea/focus-events"
+import type { FocusManager } from "@silvery/tea/focus-manager"
+import { findByTestID } from "@silvery/tea/focus-queries"
+import { type MouseEventProcessorState, processMouseEvent, hitTest } from "../mouse-events"
+import type { Container } from "@silvery/react/reconciler"
+import { getContainerRoot } from "@silvery/react/reconciler"
+import type { TeaNode } from "@silvery/tea/types"
+import type { Key } from "./keys"
+import type { EventHandler, EventHandlerContext, EventHandlers } from "./create-app"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Namespaced event from a provider.
+ */
+export interface NamespacedEvent {
+  type: string
+  provider: string
+  event: string
+  data: unknown
+}
+
+// ============================================================================
+// Handler Context
+// ============================================================================
+
+/**
+ * Build the EventHandlerContext passed to user-defined event handlers.
+ * Shared by runEventHandler() and press().
+ *
+ * When the store was created with `tea()` middleware, `dispatch` is
+ * automatically wired from the store state.
+ */
+export function createHandlerContext<S>(
+  store: StoreApi<S>,
+  focusManager: FocusManager,
+  container: Container,
+): EventHandlerContext<S> {
+  // Detect tea() middleware: store state has a dispatch function
+  const state = store.getState() as Record<string, unknown>
+  const teaDispatch = typeof state.dispatch === "function" ? state.dispatch : undefined
+
+  return {
+    set: store.setState,
+    get: store.getState,
+    focusManager,
+    focus(testID: string) {
+      const root = getContainerRoot(container)
+      focusManager.focusById(testID, root, "programmatic")
+    },
+    activateScope(scopeId: string) {
+      const root = getContainerRoot(container)
+      focusManager.activateScope(scopeId, root)
+    },
+    getFocusPath() {
+      const root = getContainerRoot(container)
+      return focusManager.getFocusPath(root)
+    },
+    dispatch: teaDispatch as EventHandlerContext<S>["dispatch"],
+    hitTest(x: number, y: number) {
+      const root = getContainerRoot(container)
+      return hitTest(root, x, y)
+    },
+  }
+}
+
+// ============================================================================
+// Focus Navigation
+// ============================================================================
+
+/**
+ * Dispatch a key event through the focus system and handle default
+ * focus navigation (Tab, Shift+Tab, Enter scope, Escape scope).
+ *
+ * Returns "consumed" if the focus system handled the event (caller should
+ * render and return), or "continue" if the event should proceed to app handlers.
+ */
+export function handleFocusNavigation(
+  input: string,
+  parsedKey: Key,
+  focusManager: FocusManager,
+  container: Container,
+): "consumed" | "continue" {
+  // Dispatch key event to focused node (capture + bubble phases)
+  if (focusManager.activeElement) {
+    const keyEvent = createKeyEvent(input, parsedKey, focusManager.activeElement)
+    dispatchKeyEvent(keyEvent)
+
+    // If focus system consumed the event, skip app handlers
+    if (keyEvent.propagationStopped || keyEvent.defaultPrevented) {
+      return "consumed"
+    }
+  }
+
+  const root = getContainerRoot(container)
+
+  // Tab: focus next (works even when nothing is focused — starts from first)
+  if (parsedKey.tab && !parsedKey.shift) {
+    focusManager.focusNext(root)
+    return "consumed"
+  }
+
+  // Shift+Tab: focus previous (works even when nothing is focused — starts from last)
+  if (parsedKey.tab && parsedKey.shift) {
+    focusManager.focusPrev(root)
+    return "consumed"
+  }
+
+  // Enter: if focused element has focusScope, enter that scope
+  if (parsedKey.return && focusManager.activeElement) {
+    const activeEl = focusManager.activeElement
+    const props = activeEl.props as Record<string, unknown>
+    const testID = typeof props.testID === "string" ? props.testID : null
+    if (props.focusScope && testID) {
+      focusManager.enterScope(testID)
+      focusManager.focusNext(root, activeEl)
+      return "consumed"
+    }
+  }
+
+  // Escape: blur current focus or exit the current focus scope
+  if (parsedKey.escape) {
+    if (focusManager.scopeStack.length > 0) {
+      const scopeId = focusManager.scopeStack[focusManager.scopeStack.length - 1]!
+      focusManager.exitScope()
+      const scopeNode = findByTestID(root, scopeId)
+      if (scopeNode) {
+        focusManager.focus(scopeNode, "keyboard")
+      }
+      return "consumed"
+    }
+    if (focusManager.activeElement) {
+      focusManager.blur()
+      return "consumed"
+    }
+  }
+
+  return "continue"
+}
+
+// ============================================================================
+// Mouse Event Dispatch
+// ============================================================================
+
+/**
+ * Dispatch a DOM-level mouse event to the node tree.
+ * Called from runEventHandler for mouse events.
+ */
+export function dispatchMouseEventToTree(
+  event: NamespacedEvent,
+  mouseEventState: MouseEventProcessorState,
+  root: TeaNode,
+): void {
+  if (event.event !== "mouse" || !event.data) return
+
+  const mouseData = event.data as {
+    button: number
+    x: number
+    y: number
+    action: string
+    delta?: number
+    shift: boolean
+    meta: boolean
+    ctrl: boolean
+  }
+
+  processMouseEvent(
+    mouseEventState,
+    {
+      button: mouseData.button,
+      x: mouseData.x,
+      y: mouseData.y,
+      action: mouseData.action as "down" | "up" | "move" | "wheel",
+      delta: mouseData.delta,
+      shift: mouseData.shift,
+      meta: mouseData.meta,
+      ctrl: mouseData.ctrl,
+    },
+    root,
+  )
+}
+
+// ============================================================================
+// Event Handler Dispatch
+// ============================================================================
+
+/**
+ * Invoke the namespaced handler for a single event (state mutation only, no render).
+ * Returns true to continue, false to exit, or "flush" for a render barrier.
+ *
+ * Also dispatches DOM-level mouse events when applicable.
+ */
+export function invokeEventHandler<S>(
+  event: NamespacedEvent,
+  handlers: EventHandlers<S> | undefined,
+  ctx: EventHandlerContext<S>,
+  mouseEventState: MouseEventProcessorState,
+  container: Container,
+): boolean | "flush" {
+  const namespacedHandler = handlers?.[event.type as keyof typeof handlers]
+
+  if (namespacedHandler && typeof namespacedHandler === "function") {
+    const result = (namespacedHandler as EventHandler<unknown, S>)(event.data, ctx)
+    if (result === "exit") return false
+    if (result === "flush") return "flush"
+  }
+
+  // DOM-level mouse event dispatch
+  const root = getContainerRoot(container)
+  dispatchMouseEventToTree(event, mouseEventState, root)
+
+  return true
+}
+
+/**
+ * Dispatch a term:key event to app handlers (namespaced + legacy).
+ * Returns "exit" if the handler signaled exit, undefined otherwise.
+ */
+export function dispatchKeyToHandlers<S>(
+  input: string,
+  parsedKey: Key,
+  handlers: EventHandlers<S> | undefined,
+  ctx: EventHandlerContext<S>,
+): "exit" | undefined {
+  // Namespaced handler
+  const namespacedHandler = handlers?.["term:key" as keyof typeof handlers]
+  if (namespacedHandler && typeof namespacedHandler === "function") {
+    const result = (namespacedHandler as EventHandler<unknown, S>)({ input, key: parsedKey }, ctx)
+    if (result === "exit") return "exit"
+  }
+
+  // Legacy handler
+  if ((handlers as any)?.key) {
+    const result = (handlers as any).key(input, parsedKey, ctx)
+    if (result === "exit") return "exit"
+  }
+
+  return undefined
+}