@silvery/term 0.3.0

package/src/runtime/tick.ts

@@ -0,0 +1,219 @@
+/**
+ * Time/tick source for silvery-loop.
+ *
+ * Creates an AsyncIterable that yields at regular intervals.
+ * Used for animations, spinners, progress bars, etc.
+ */
+
+/**
+ * Create a tick source that yields at regular intervals.
+ *
+ * The tick source respects AbortSignal for cleanup and stops
+ * when the signal is aborted.
+ *
+ * @param intervalMs Interval between ticks in milliseconds
+ * @param signal Optional AbortSignal to stop the tick source
+ * @returns AsyncIterable that yields tick numbers (0, 1, 2, ...)
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController()
+ * const ticks = createTick(100, controller.signal)
+ *
+ * for await (const tick of ticks) {
+ *   console.log(`Tick ${tick}`)
+ *   if (tick >= 10) controller.abort()
+ * }
+ * ```
+ */
+export function createTick(intervalMs: number, signal?: AbortSignal): AsyncIterable<number> {
+  return {
+    [Symbol.asyncIterator]: () => createTickIterator(intervalMs, signal),
+  }
+}
+
+/**
+ * Create the actual tick iterator.
+ */
+function createTickIterator(intervalMs: number, signal?: AbortSignal): AsyncIterator<number> {
+  let count = 0
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let pendingResolve: ((result: IteratorResult<number>) => void) | undefined
+  let done = false
+
+  // Handle abort signal
+  const onAbort = () => {
+    done = true
+    if (timer) {
+      clearTimeout(timer)
+      timer = undefined
+    }
+    if (pendingResolve) {
+      pendingResolve({ done: true, value: undefined })
+      pendingResolve = undefined
+    }
+  }
+
+  if (signal) {
+    if (signal.aborted) {
+      done = true
+    } else {
+      signal.addEventListener("abort", onAbort, { once: true })
+    }
+  }
+
+  return {
+    async next(): Promise<IteratorResult<number>> {
+      if (done) {
+        return { done: true, value: undefined }
+      }
+
+      return new Promise<IteratorResult<number>>((resolve, _reject) => {
+        pendingResolve = resolve
+
+        timer = setTimeout(() => {
+          if (!done) {
+            const value = count++
+            pendingResolve = undefined
+            resolve({ done: false, value })
+          }
+        }, intervalMs)
+      })
+    },
+
+    async return(): Promise<IteratorResult<number>> {
+      done = true
+      if (timer) {
+        clearTimeout(timer)
+        timer = undefined
+      }
+      if (signal) {
+        signal.removeEventListener("abort", onAbort)
+      }
+      if (pendingResolve) {
+        pendingResolve({ done: true, value: undefined })
+        pendingResolve = undefined
+      }
+      return { done: true, value: undefined }
+    },
+  }
+}
+
+/**
+ * Create a tick source that yields at approximately 60fps (~16ms).
+ *
+ * @param signal Optional AbortSignal to stop the tick source
+ * @returns AsyncIterable that yields frame numbers
+ */
+export function createFrameTick(signal?: AbortSignal): AsyncIterable<number> {
+  return createTick(16, signal)
+}
+
+/**
+ * Create a tick source that yields once per second.
+ *
+ * @param signal Optional AbortSignal to stop the tick source
+ * @returns AsyncIterable that yields second counts
+ */
+export function createSecondTick(signal?: AbortSignal): AsyncIterable<number> {
+  return createTick(1000, signal)
+}
+
+/**
+ * Create a tick source with adaptive timing based on render performance.
+ *
+ * This is useful for maintaining a target frame rate while allowing
+ * for slower frames when needed.
+ *
+ * @param targetFps Target frames per second (default: 60)
+ * @param signal Optional AbortSignal to stop the tick source
+ * @returns AsyncIterable with timing information
+ */
+export function createAdaptiveTick(
+  targetFps = 60,
+  signal?: AbortSignal,
+): AsyncIterable<{ tick: number; elapsed: number; delta: number }> {
+  const targetMs = 1000 / targetFps
+  let lastTime = Date.now()
+  let tick = 0
+
+  return {
+    [Symbol.asyncIterator]: () => {
+      let done = false
+      let timer: ReturnType<typeof setTimeout> | undefined
+      let pendingResolve:
+        | ((
+            result: IteratorResult<{
+              tick: number
+              elapsed: number
+              delta: number
+            }>,
+          ) => void)
+        | undefined
+
+      const onAbort = () => {
+        done = true
+        if (timer) {
+          clearTimeout(timer)
+          timer = undefined
+        }
+        if (pendingResolve) {
+          pendingResolve({ done: true, value: undefined })
+          pendingResolve = undefined
+        }
+      }
+
+      if (signal) {
+        if (signal.aborted) {
+          done = true
+        } else {
+          signal.addEventListener("abort", onAbort, { once: true })
+        }
+      }
+
+      return {
+        async next(): Promise<IteratorResult<{ tick: number; elapsed: number; delta: number }>> {
+          if (done) {
+            return { done: true, value: undefined }
+          }
+
+          return new Promise((resolve) => {
+            pendingResolve = resolve
+            const now = Date.now()
+            const elapsed = now - lastTime
+            const delay = Math.max(0, targetMs - elapsed)
+
+            timer = setTimeout(() => {
+              if (!done) {
+                const currentTime = Date.now()
+                const delta = currentTime - lastTime
+                lastTime = currentTime
+                pendingResolve = undefined
+                resolve({
+                  done: false,
+                  value: { tick: tick++, elapsed: currentTime, delta },
+                })
+              }
+            }, delay)
+          })
+        },
+
+        async return(): Promise<IteratorResult<{ tick: number; elapsed: number; delta: number }>> {
+          done = true
+          if (timer) {
+            clearTimeout(timer)
+            timer = undefined
+          }
+          if (signal) {
+            signal.removeEventListener("abort", onAbort)
+          }
+          if (pendingResolve) {
+            pendingResolve({ done: true, value: undefined })
+            pendingResolve = undefined
+          }
+          return { done: true, value: undefined }
+        },
+      }
+    },
+  }
+}

package/src/runtime/types.ts

@@ -0,0 +1,210 @@
+/**
+ * Core types for the silvery-loop runtime.
+ */
+
+import type { TerminalBuffer } from "../buffer"
+import type { TeaNode } from "@silvery/tea/types"
+
+/**
+ * Dimensions for rendering.
+ */
+export interface Dims {
+  cols: number
+  rows: number
+}
+
+/**
+ * Immutable render output buffer.
+ *
+ * Contains:
+ * - text: Plain text without ANSI codes (for assertions)
+ * - ansi: Styled output with ANSI escape codes
+ * - nodes: Internal node tree for locator queries
+ */
+export interface Buffer {
+  /** Plain text without ANSI codes */
+  readonly text: string
+  /** Styled output with ANSI escape codes */
+  readonly ansi: string
+  /** Internal node tree for locator queries */
+  readonly nodes: TeaNode
+  /** Raw terminal buffer for diffing */
+  readonly _buffer: TerminalBuffer
+}
+
+/**
+ * Event types from the runtime.
+ */
+export type Event =
+  | {
+      type: "key"
+      key: string
+      ctrl?: boolean
+      meta?: boolean
+      shift?: boolean
+    }
+  | {
+      type: "mouse"
+      button: number
+      x: number
+      y: number
+      action: "down" | "up" | "move" | "wheel"
+      delta?: number
+      shift: boolean
+      meta: boolean
+      ctrl: boolean
+    }
+  | { type: "paste"; content: string }
+  | { type: "resize"; cols: number; rows: number }
+  | { type: "tick"; time: number }
+  | { type: "effect"; id: string; result: unknown }
+  | { type: "error"; error: Error }
+
+/**
+ * Render target interface - abstracts terminal output.
+ */
+export interface RenderTarget {
+  /** Write rendered frame to output */
+  write(frame: string): void
+  /** Get current dimensions */
+  getDims(): Dims
+  /** Subscribe to resize events */
+  onResize?(handler: (dims: Dims) => void): () => void
+}
+
+/**
+ * Runtime options for createRuntime().
+ */
+export interface RuntimeOptions {
+  /** Render target (terminal, test mock, etc.) */
+  target: RenderTarget
+  /** Abort signal for cleanup */
+  signal?: AbortSignal
+  /** Render mode: fullscreen (alt screen) or inline (scrollback-compatible) */
+  mode?: "fullscreen" | "inline"
+  /** Scoped output phase function (from createOutputPhase/createPipeline). When provided,
+   *  runtime.render() uses this instead of the raw outputPhase — ensures measurer/caps are threaded. */
+  outputPhaseFn?: (
+    prev: import("../buffer.js").TerminalBuffer | null,
+    next: import("../buffer.js").TerminalBuffer,
+    mode?: "fullscreen" | "inline",
+    scrollbackOffset?: number,
+    termRows?: number,
+  ) => string
+}
+
+/**
+ * The runtime kernel interface.
+ */
+export interface Runtime {
+  /** Event stream - yields until disposed */
+  events(): AsyncIterable<Event>
+
+  /** Schedule an effect with optional cancellation */
+  schedule<T>(effect: () => Promise<T>, opts?: { signal?: AbortSignal }): void
+
+  /** Render a buffer to the target */
+  render(buffer: Buffer): void
+
+  /** Report lines written to stdout between renders (inline mode only) */
+  addScrollbackLines(lines: number): void
+
+  /** Reset diff state so next render outputs a full frame */
+  invalidate(): void
+
+  /** Reset inline cursor tracking state (inline mode only).
+   *  Called by useScrollback before re-emitting frozen items on resize. */
+  resetInlineCursor(): void
+
+  /** Get inline cursor row relative to render region start. -1 if unknown. */
+  getInlineCursorRow(): number
+
+  /** Promote frozen content to scrollback via the output phase.
+   *  Content is written in a single frame with the live render — no flicker. */
+  promoteScrollback(content: string, lines: number): void
+
+  /** Get current dimensions */
+  getDims(): Dims
+
+  /** Dispose and cleanup - idempotent */
+  [Symbol.dispose](): void
+}
+
+// ============================================================================
+// Provider Types
+// ============================================================================
+
+/**
+ * Event emitted by a provider, tagged with event type.
+ */
+export type ProviderEvent<Events extends Record<string, unknown>> = {
+  [K in keyof Events]: { type: K; data: Events[K] }
+}[keyof Events]
+
+/**
+ * Provider interface - unified store + event source.
+ *
+ * Providers are the building blocks of silvery-loop applications.
+ * They encapsulate:
+ * - State (Zustand-compatible: getState/subscribe)
+ * - Events (AsyncIterable of typed events)
+ * - Cleanup (Symbol.dispose)
+ *
+ * @example
+ * ```typescript
+ * type TermProvider = Provider<
+ *   { cols: number; rows: number },
+ *   { key: { input: string; key: Key }; resize: Dims }
+ * >;
+ * ```
+ */
+export interface Provider<State = unknown, Events extends Record<string, unknown> = Record<string, never>> {
+  /** Get current state (Zustand-compatible) */
+  getState(): State
+
+  /** Subscribe to state changes (Zustand-compatible) */
+  subscribe(listener: (state: State) => void): () => void
+
+  /** Event stream - yields typed events until disposed */
+  events(): AsyncIterable<ProviderEvent<Events>>
+
+  /** Cleanup resources */
+  [Symbol.dispose](): void
+}
+
+/**
+ * Extract the namespaced event type from a providers map.
+ *
+ * Given { term: TermProvider, sync: SyncProvider }, produces:
+ * | { type: 'term:key'; data: { input: string; key: Key } }
+ * | { type: 'term:resize'; data: Dims }
+ * | { type: 'sync:data'; data: Item[] }
+ * | ...
+ */
+export type NamespacedEvent<Providers extends Record<string, Provider<unknown, Record<string, unknown>>>> = {
+  [P in keyof Providers]: Providers[P] extends Provider<unknown, infer E>
+    ? {
+        [K in keyof E & string]: {
+          type: `${P & string}:${K}`
+          data: E[K]
+        }
+      }[keyof E & string]
+    : never
+}[keyof Providers]
+
+/**
+ * Extract all event keys from a providers map.
+ *
+ * Given { term: TermProvider, sync: SyncProvider }, produces:
+ * 'term:key' | 'term:resize' | 'sync:data' | ...
+ */
+export type ProviderEventKey<Providers extends Record<string, Provider<unknown, Record<string, unknown>>>> =
+  NamespacedEvent<Providers>["type"]
+
+/**
+ * Get the data type for a specific event key.
+ */
+export type EventData<
+  Providers extends Record<string, Provider<unknown, Record<string, unknown>>>,
+  K extends ProviderEventKey<Providers>,
+> = Extract<NamespacedEvent<Providers>, { type: K }>["data"]