@silvery/term 0.3.0

package/src/screenshot.ts

@@ -0,0 +1,57 @@
+import { writeFile } from "node:fs/promises"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface Screenshotter {
+  /** Render HTML to PNG. First call starts Playwright (~3-5s), subsequent calls ~200ms */
+  capture(html: string, outputPath?: string): Promise<Buffer>
+  /** Close browser */
+  close(): Promise<void>
+  [Symbol.asyncDispose](): Promise<void>
+}
+
+// ============================================================================
+// Factory
+// ============================================================================
+
+export function createScreenshotter(): Screenshotter {
+  let browser: import("playwright").Browser | null = null
+  let page: import("playwright").Page | null = null
+
+  async function ensureBrowser() {
+    if (browser && page) return page
+
+    const { chromium } = await import("playwright")
+    browser = await chromium.launch()
+    const context = await browser.newContext()
+    page = await context.newPage()
+    return page
+  }
+
+  async function capture(html: string, outputPath?: string): Promise<Buffer> {
+    const p = await ensureBrowser()
+    await p.setContent(html, { waitUntil: "load" })
+    await p.waitForTimeout(50)
+    const buffer = (await p.screenshot({ fullPage: true })) as Buffer
+    if (outputPath) {
+      await writeFile(outputPath, buffer)
+    }
+    return buffer
+  }
+
+  async function close() {
+    if (browser) {
+      await browser.close()
+      browser = null
+      page = null
+    }
+  }
+
+  return {
+    capture,
+    close,
+    [Symbol.asyncDispose]: close,
+  }
+}

package/src/scroll-region.ts

@@ -0,0 +1,69 @@
+/**
+ * Terminal scroll region (DECSTBM) utilities.
+ *
+ * Scroll regions tell the terminal to natively scroll content within
+ * a defined row range, which is faster than re-rendering all cells.
+ *
+ * DECSTBM (DEC Set Top and Bottom Margins) is supported by most modern
+ * terminal emulators: xterm, iTerm2, Kitty, Ghostty, WezTerm, etc.
+ */
+
+const ESC = "\x1b"
+
+/** Set terminal scroll region (1-indexed top and bottom rows). */
+export function setScrollRegion(stdout: NodeJS.WriteStream, top: number, bottom: number): void {
+  stdout.write(`${ESC}[${top};${bottom}r`)
+}
+
+/** Reset scroll region to full terminal. */
+export function resetScrollRegion(stdout: NodeJS.WriteStream): void {
+  stdout.write(`${ESC}[r`)
+}
+
+/** Scroll content up by N lines within the current scroll region. */
+export function scrollUp(stdout: NodeJS.WriteStream, lines: number = 1): void {
+  stdout.write(`${ESC}[${lines}S`)
+}
+
+/** Scroll content down by N lines within the current scroll region. */
+export function scrollDown(stdout: NodeJS.WriteStream, lines: number = 1): void {
+  stdout.write(`${ESC}[${lines}T`)
+}
+
+/** Move cursor to a specific position (1-indexed row and column). */
+export function moveCursor(stdout: NodeJS.WriteStream, row: number, col: number): void {
+  stdout.write(`${ESC}[${row};${col}H`)
+}
+
+export interface ScrollRegionConfig {
+  /** Top row of the scrollable area (0-indexed). */
+  top: number
+  /** Bottom row of the scrollable area (0-indexed). */
+  bottom: number
+  /** Whether scroll region optimization is enabled. */
+  enabled: boolean
+}
+
+/**
+ * Detect if the terminal likely supports DECSTBM scroll regions.
+ *
+ * Most modern terminals do (xterm, iTerm2, Kitty, Ghostty, WezTerm, etc.)
+ * but some (e.g., Linux console) may not handle them correctly.
+ */
+export function supportsScrollRegions(): boolean {
+  const term = process.env.TERM ?? ""
+  const termProgram = process.env.TERM_PROGRAM ?? ""
+
+  // Known-good terminal programs
+  if (termProgram === "iTerm.app" || termProgram === "WezTerm" || termProgram === "ghostty" || termProgram === "vscode")
+    return true
+
+  // Known-good TERM values
+  if (term.includes("xterm") || term.includes("screen") || term.includes("tmux") || term.includes("kitty")) return true
+
+  // Linux console doesn't support DECSTBM
+  if (term === "linux") return false
+
+  // Default: assume support for any term that's not empty
+  return term !== ""
+}

package/src/scroll-utils.ts

@@ -0,0 +1,97 @@
+/**
+ * Scroll Utilities
+ *
+ * Shared functions for edge-based scrolling behavior across VirtualList,
+ * HorizontalVirtualList, and other scroll-aware components.
+ */
+
+/**
+ * Calculate edge-based scroll offset.
+ *
+ * Only scrolls when cursor approaches the edge of the visible area.
+ * This provides smoother scrolling by starting to scroll before hitting
+ * the absolute edge, maintaining context around the selected item.
+ *
+ * ## Algorithm
+ *
+ * The viewport is divided into zones:
+ * ```
+ * |<padding>|<------ safe zone ------>|<padding>|
+ * |  scroll |    no scroll needed     | scroll  |
+ * |  if <   |                         | if >    |
+ * ```
+ *
+ * When the selected item enters a padding zone, the viewport scrolls
+ * to keep the item visible with margin.
+ *
+ * ## Asymmetry Note
+ *
+ * The +1 in the "scroll down/right" case is intentional:
+ * - Offset points to the TOP/LEFT of the viewport
+ * - We want the selected item to be `padding` items from the BOTTOM/RIGHT
+ * - Formula: `selectedIndex - visibleCount + padding + 1`
+ *
+ * Example: visibleCount=10, padding=2, selectedIndex=15
+ *   offset = 15 - 10 + 2 + 1 = 8
+ *   viewport shows items 8-17, selected item 15 is at position 7 (2 from bottom)
+ *
+ * @param selectedIndex - Currently selected item index
+ * @param currentOffset - Current scroll offset (topmost/leftmost visible item)
+ * @param visibleCount - Number of items visible in viewport
+ * @param totalCount - Total number of items
+ * @param padding - Items to keep visible before/after cursor (default: 1)
+ * @returns New scroll offset
+ */
+export function calcEdgeBasedScrollOffset(
+  selectedIndex: number,
+  currentOffset: number,
+  visibleCount: number,
+  totalCount: number,
+  padding = 1,
+): number {
+  // If everything fits, no scrolling needed
+  if (totalCount <= visibleCount) return 0
+
+  // Reduce padding when viewport is too small to have a non-empty safe zone.
+  // With padding=1 and visibleCount=2, paddedStart > paddedEnd (inverted zone),
+  // causing every re-render to trigger a scroll in one direction.
+  const effectivePadding = padding * 2 >= visibleCount ? 0 : padding
+
+  // Calculate visible range
+  const visibleStart = currentOffset
+  const visibleEnd = currentOffset + visibleCount - 1
+
+  // Define the "safe zone" where cursor doesn't trigger scroll
+  const paddedStart = visibleStart + effectivePadding
+  const paddedEnd = visibleEnd - effectivePadding
+
+  let newOffset = currentOffset
+
+  if (selectedIndex < paddedStart) {
+    // Scrolling UP/LEFT: place item `effectivePadding` rows from top
+    newOffset = Math.max(0, selectedIndex - effectivePadding)
+  } else if (
+    effectivePadding === 0 &&
+    selectedIndex === paddedStart &&
+    currentOffset > 0 &&
+    // Only scroll back if the viewport is large enough to show both the
+    // context item and the selected item. When visibleCount <= padding,
+    // scrolling back pushes the selected item out of view, which triggers
+    // a forward scroll on the next render → infinite oscillation.
+    visibleCount > padding
+  ) {
+    // Small viewport (effectivePadding forced to 0): cursor at the very first visible
+    // position should still scroll back to provide context. Without this, scrolling
+    // right works (cursor past last visible triggers scroll) but scrolling left doesn't
+    // (cursor at first visible doesn't trigger), creating asymmetric behavior.
+    // Use original padding for the offset formula to show context before the cursor.
+    newOffset = Math.max(0, selectedIndex - padding)
+  } else if (selectedIndex > paddedEnd) {
+    // Scrolling DOWN/RIGHT: place item `effectivePadding` rows from bottom
+    // The +1 converts from 0-indexed offset to correct position
+    newOffset = Math.min(totalCount - visibleCount, selectedIndex - visibleCount + effectivePadding + 1)
+  }
+
+  // Clamp to valid range
+  return Math.max(0, Math.min(newOffset, totalCount - visibleCount))
+}

package/src/term-def.ts

@@ -0,0 +1,267 @@
+/**
+ * TermDef Resolution
+ *
+ * Converts TermDef (minimal render config) into resolved values for rendering.
+ * Handles auto-detection of events from stdin, dimension defaults, etc.
+ */
+
+import type { ColorLevel, Term } from "./ansi/index"
+import type { Event, TermDef } from "@silvery/tea/types"
+
+// ============================================================================
+// Resolved TermDef
+// ============================================================================
+
+/**
+ * Resolved values from a TermDef, ready for use by the render system.
+ */
+export interface ResolvedTermDef {
+  /** Output stream (may be mock for static rendering) */
+  stdout: NodeJS.WriteStream | null
+
+  /** Width in columns */
+  width: number
+
+  /** Height in rows */
+  height: number
+
+  /** Color level (null = no colors) */
+  colors: ColorLevel | null
+
+  /** Event source (null = static mode) */
+  events: AsyncIterable<Event> | null
+
+  /** Whether this is static mode (no events = render until stable) */
+  isStatic: boolean
+}
+
+// ============================================================================
+// Resolution Logic
+// ============================================================================
+
+/**
+ * Default dimensions when not detectable.
+ */
+const DEFAULT_WIDTH = 80
+const DEFAULT_HEIGHT = 24
+
+/**
+ * Check if a value is a Term instance (duck typing).
+ */
+export function isTerm(value: unknown): value is Term {
+  // Term can be a callable Proxy (typeof === 'function') or object
+  if (!value || (typeof value !== "object" && typeof value !== "function")) {
+    return false
+  }
+  const obj = value as Record<string, unknown>
+  return (
+    typeof obj.hasCursor === "function" &&
+    typeof obj.hasInput === "function" &&
+    typeof obj.hasColor === "function" &&
+    typeof obj.write === "function"
+  )
+}
+
+/**
+ * Check if a value is a TermDef (not a Term).
+ */
+export function isTermDef(value: unknown): value is TermDef {
+  if (!value || typeof value !== "object") return false
+  // TermDef doesn't have hasCursor method
+  const obj = value as Record<string, unknown>
+  return typeof obj.hasCursor !== "function"
+}
+
+/**
+ * Resolve a TermDef into concrete values.
+ *
+ * @param def - TermDef to resolve
+ * @returns Resolved values ready for rendering
+ */
+export function resolveTermDef(def: TermDef): ResolvedTermDef {
+  // Resolve dimensions
+  const width = def.width ?? def.stdout?.columns ?? DEFAULT_WIDTH
+  const height = def.height ?? def.stdout?.rows ?? DEFAULT_HEIGHT
+
+  // Resolve colors
+  let colors: ColorLevel | null = null
+  if (def.colors === true) {
+    // Auto-detect from stdout
+    colors = detectColorLevel(def.stdout)
+  } else if (def.colors === false || def.colors === null) {
+    colors = null
+  } else if (def.colors) {
+    colors = def.colors
+  } else {
+    // Default: auto-detect
+    colors = detectColorLevel(def.stdout)
+  }
+
+  // Resolve events
+  let events: AsyncIterable<Event> | null = null
+  if (def.events) {
+    // Explicit events provided
+    events = def.events
+  } else if (def.stdin) {
+    // Auto-create events from stdin
+    events = createInputEvents(def.stdin)
+  }
+
+  return {
+    stdout: def.stdout ?? null,
+    width,
+    height,
+    colors,
+    events,
+    isStatic: events === null,
+  }
+}
+
+/**
+ * Resolve a Term instance into ResolvedTermDef.
+ *
+ * @param term - Term instance
+ * @returns Resolved values
+ */
+export function resolveFromTerm(term: Term): ResolvedTermDef {
+  return {
+    stdout: term.stdout,
+    width: term.cols ?? DEFAULT_WIDTH,
+    height: term.rows ?? DEFAULT_HEIGHT,
+    colors: term.hasColor(),
+    // Term instances always have interactive capabilities
+    events: createInputEvents(term.stdin),
+    isStatic: false,
+  }
+}
+
+// ============================================================================
+// Color Detection
+// ============================================================================
+
+/**
+ * Detect color level from stdout stream.
+ */
+function detectColorLevel(stdout?: NodeJS.WriteStream): ColorLevel | null {
+  // Check environment variables
+  if (process.env.NO_COLOR !== undefined) {
+    return null
+  }
+
+  if (process.env.FORCE_COLOR !== undefined) {
+    const level = Number.parseInt(process.env.FORCE_COLOR, 10)
+    if (level === 0) return null
+    if (level === 1) return "basic"
+    if (level === 2) return "256"
+    if (level >= 3) return "truecolor"
+    return "basic"
+  }
+
+  // Check COLORTERM for truecolor
+  if (process.env.COLORTERM === "truecolor" || process.env.COLORTERM === "24bit") {
+    return "truecolor"
+  }
+
+  // Check if TTY
+  if (!stdout?.isTTY) {
+    return null
+  }
+
+  // Check TERM for 256 color support
+  const term = process.env.TERM ?? ""
+  if (term.includes("256color") || term.includes("256")) {
+    return "256"
+  }
+
+  // Default to basic if TTY
+  return "basic"
+}
+
+// ============================================================================
+// Input Events
+// ============================================================================
+
+/**
+ * Create an async iterable of input events from a stdin stream.
+ *
+ * This enables interactive mode by providing a source of keyboard events.
+ */
+export function createInputEvents(stdin: NodeJS.ReadStream): AsyncIterable<Event> {
+  return {
+    [Symbol.asyncIterator](): AsyncIterator<Event> {
+      const buffer: Event[] = []
+      let resolveNext: ((value: IteratorResult<Event>) => void) | null = null
+      let done = false
+
+      // Set up stdin reading
+      const handleData = (chunk: Buffer | string) => {
+        const data = typeof chunk === "string" ? chunk : chunk.toString("utf8")
+
+        // Convert raw input to key events
+        // This is simplified - real implementation would parse ANSI sequences
+        for (const char of data) {
+          const event: Event = {
+            type: "key",
+            key: char,
+            ctrl: char.charCodeAt(0) < 32 && char !== "\r" && char !== "\n" && char !== "\t",
+          }
+
+          if (resolveNext) {
+            resolveNext({ value: event, done: false })
+            resolveNext = null
+          } else {
+            buffer.push(event)
+          }
+        }
+      }
+
+      const handleEnd = () => {
+        done = true
+        if (resolveNext) {
+          resolveNext({ value: undefined as unknown as Event, done: true })
+          resolveNext = null
+        }
+      }
+
+      // Only set up if stdin supports raw mode
+      if (stdin.isTTY && typeof stdin.setRawMode === "function") {
+        stdin.setEncoding("utf8")
+        stdin.on("data", handleData)
+        stdin.on("end", handleEnd)
+      }
+
+      return {
+        next(): Promise<IteratorResult<Event>> {
+          // Return buffered event if available
+          const buffered = buffer.shift()
+          if (buffered) {
+            return Promise.resolve({ value: buffered, done: false })
+          }
+
+          // If done, return done
+          if (done) {
+            return Promise.resolve({
+              value: undefined as unknown as Event,
+              done: true,
+            })
+          }
+
+          // Wait for next event
+          return new Promise((resolve) => {
+            resolveNext = resolve
+          })
+        },
+
+        return(): Promise<IteratorResult<Event>> {
+          done = true
+          stdin.off("data", handleData)
+          stdin.off("end", handleEnd)
+          return Promise.resolve({
+            value: undefined as unknown as Event,
+            done: true,
+          })
+        },
+      }
+    },
+  }
+}

package/src/terminal-caps.ts

@@ -0,0 +1,5 @@
+/**
+ * Terminal capability detection -- re-exported from the ansi submodule.
+ */
+
+export { detectTerminalCaps, defaultCaps, type TerminalCaps } from "./ansi/detection"