@silvery/ui 0.3.0

package/src/image/kitty-graphics.ts

@@ -0,0 +1,161 @@
+/**
+ * Kitty Graphics Protocol
+ *
+ * Encodes and manages images using the Kitty terminal graphics protocol.
+ * Images are transmitted as base64-encoded PNG data via APC (Application
+ * Program Command) escape sequences.
+ *
+ * Protocol reference: https://sw.kovidgoyal.net/kitty/graphics-protocol/
+ *
+ * Key concepts:
+ * - `a=T` — transmit and display the image
+ * - `f=100` — format is PNG (raw PNG data, terminal decodes it)
+ * - `m=0|1` — 0 = last/only chunk, 1 = more chunks follow
+ * - Chunks should be <= 4096 bytes of base64 to avoid overwhelming the terminal
+ * - Images can be assigned an `i=<id>` for later deletion
+ */
+
+const APC_START = "\x1b_G"
+const ST = "\x1b\\"
+
+/** Maximum base64 bytes per chunk (Kitty recommendation) */
+const MAX_CHUNK_SIZE = 4096
+
+export interface KittyImageOptions {
+  /** Image width in terminal columns */
+  width?: number
+  /** Image height in terminal rows */
+  height?: number
+  /** Image ID for later reference/deletion (positive integer) */
+  id?: number
+}
+
+/**
+ * Encode a PNG image into Kitty graphics protocol escape sequences.
+ *
+ * The image data is base64-encoded and split into chunks of <= 4096 bytes.
+ * Each chunk is wrapped in an APC escape sequence. The first chunk carries
+ * the image metadata (action, format, dimensions, ID). Subsequent chunks
+ * only carry `m=1` or `m=0` to indicate continuation.
+ *
+ * @param pngData - Raw PNG image data
+ * @param opts - Optional dimensions and ID
+ * @returns A string containing the complete escape sequence(s)
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from "fs"
+ * import { encodeKittyImage } from "@silvery/react"
+ *
+ * const png = readFileSync("photo.png")
+ * const seq = encodeKittyImage(png, { width: 40, height: 20 })
+ * process.stdout.write(seq)
+ * ```
+ */
+export function encodeKittyImage(pngData: Buffer, opts?: KittyImageOptions): string {
+  const b64 = pngData.toString("base64")
+  const chunks = splitIntoChunks(b64, MAX_CHUNK_SIZE)
+
+  if (chunks.length === 0) {
+    // Empty image — send a single empty payload
+    return `${APC_START}${buildParams(opts, 0)};${ST}`
+  }
+
+  if (chunks.length === 1) {
+    // Single chunk — m=0 (last/only)
+    return `${APC_START}${buildParams(opts, 0)};${chunks[0]}${ST}`
+  }
+
+  // Multiple chunks
+  const parts: string[] = []
+
+  // First chunk carries full metadata, m=1 (more follows)
+  parts.push(`${APC_START}${buildParams(opts, 1)};${chunks[0]}${ST}`)
+
+  // Middle chunks — only m=1
+  for (let i = 1; i < chunks.length - 1; i++) {
+    parts.push(`${APC_START}m=1;${chunks[i]}${ST}`)
+  }
+
+  // Last chunk — m=0
+  parts.push(`${APC_START}m=0;${chunks[chunks.length - 1]}${ST}`)
+
+  return parts.join("")
+}
+
+/**
+ * Generate an escape sequence to delete a Kitty image by ID.
+ *
+ * Uses `a=d` (delete) with `d=i` (delete by image ID).
+ *
+ * @param id - The image ID to delete
+ * @returns The delete escape sequence
+ *
+ * @example
+ * ```ts
+ * process.stdout.write(deleteKittyImage(42))
+ * ```
+ */
+export function deleteKittyImage(id: number): string {
+  return `${APC_START}a=d,d=i,i=${id}${ST}`
+}
+
+/**
+ * Check if the current terminal likely supports the Kitty graphics protocol.
+ *
+ * This is a heuristic based on `TERM` and `TERM_PROGRAM` environment variables.
+ * For definitive detection, use a terminal query (send the graphics protocol
+ * query and check for a response), but that requires async I/O.
+ *
+ * Known supporting terminals: Kitty, WezTerm, Ghostty (partial), Konsole (partial).
+ *
+ * @returns `true` if the terminal likely supports Kitty graphics
+ */
+export function isKittyGraphicsSupported(): boolean {
+  const term = process.env.TERM ?? ""
+  const termProgram = process.env.TERM_PROGRAM ?? ""
+
+  // Kitty terminal
+  if (term === "xterm-kitty" || termProgram === "kitty") return true
+
+  // WezTerm supports Kitty graphics protocol
+  if (termProgram === "WezTerm") return true
+
+  // Ghostty supports Kitty graphics
+  if (termProgram === "ghostty") return true
+
+  // Konsole 22.04+ supports Kitty graphics
+  if (termProgram === "konsole") return true
+
+  return false
+}
+
+// ============================================================================
+// Internal helpers
+// ============================================================================
+
+/**
+ * Build the Kitty graphics protocol parameter string for the first chunk.
+ */
+function buildParams(opts: KittyImageOptions | undefined, more: 0 | 1): string {
+  const parts = [`a=T`, `f=100`, `m=${more}`]
+
+  if (opts?.width != null) parts.push(`s=${opts.width}`)
+  if (opts?.height != null) parts.push(`v=${opts.height}`)
+  if (opts?.id != null) parts.push(`i=${opts.id}`)
+
+  return parts.join(",")
+}
+
+/**
+ * Split a string into chunks of at most `size` characters.
+ */
+function splitIntoChunks(str: string, size: number): string[] {
+  if (str.length === 0) return []
+
+  const chunks: string[] = []
+  for (let i = 0; i < str.length; i += size) {
+    chunks.push(str.slice(i, i + size))
+  }
+  return chunks
+}

package/src/image/sixel-encoder.ts

@@ -0,0 +1,194 @@
+/**
+ * Sixel Encoder (Minimal Implementation)
+ *
+ * Sixel is an older image protocol supported by terminals like xterm, mlterm,
+ * foot, and some others. Images are encoded as DCS (Device Control String)
+ * sequences where each character encodes 6 vertical pixels.
+ *
+ * DCS format: `ESC P <params> q <sixel-data> ESC \`
+ *
+ * This is a minimal implementation that produces valid Sixel output for
+ * simple images. For production use with complex images, consider using
+ * a dedicated Sixel library that handles color quantization and dithering.
+ *
+ * Protocol reference: https://en.wikipedia.org/wiki/Sixel
+ *
+ * TODO: Full Sixel encoding with proper color quantization, dithering,
+ * and compression. The current implementation handles basic RGBA image data
+ * with a simple nearest-color palette approach.
+ */
+
+const DCS_START = "\x1bP"
+const ST = "\x1b\\"
+
+/** Sixel introduces a color with `#<index>;2;<r>;<g>;<b>` (RGB percentages 0-100) */
+const SIXEL_NEWLINE = "-"
+
+export interface SixelImageData {
+  /** Image width in pixels */
+  width: number
+  /** Image height in pixels */
+  height: number
+  /** RGBA pixel data (4 bytes per pixel: R, G, B, A), row-major order */
+  data: Uint8Array
+}
+
+/**
+ * Encode RGBA image data as a Sixel escape sequence.
+ *
+ * This is a basic implementation that:
+ * 1. Quantizes colors to a small palette (up to 256 colors)
+ * 2. Encodes 6-row bands as Sixel characters
+ * 3. Wraps in a DCS escape sequence
+ *
+ * For transparent pixels (alpha < 128), the background shows through.
+ *
+ * @param imageData - Image dimensions and RGBA pixel data
+ * @returns A DCS escape sequence containing the Sixel-encoded image
+ *
+ * @example
+ * ```ts
+ * const img = { width: 10, height: 12, data: new Uint8Array(10 * 12 * 4) }
+ * const seq = encodeSixel(img)
+ * process.stdout.write(seq)
+ * ```
+ */
+export function encodeSixel(imageData: SixelImageData): string {
+  const { width, height, data } = imageData
+
+  if (width === 0 || height === 0 || data.length === 0) {
+    return `${DCS_START}q${ST}`
+  }
+
+  // Build a simple palette by collecting unique (quantized) colors
+  const palette = new Map<string, number>()
+  const pixelColors = new Uint16Array(width * height) // palette index per pixel (0 = transparent)
+  let nextColorIndex = 1 // 0 reserved for transparent/background
+
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const offset = (y * width + x) * 4
+      const r = data[offset]!
+      const g = data[offset + 1]!
+      const b = data[offset + 2]!
+      const a = data[offset + 3]!
+
+      if (a < 128) {
+        // Transparent — leave as 0
+        continue
+      }
+
+      // Quantize to 6-bit per channel (64 levels) to keep palette small
+      const qr = (r >> 2) & 0x3f
+      const qg = (g >> 2) & 0x3f
+      const qb = (b >> 2) & 0x3f
+      const key = `${qr},${qg},${qb}`
+
+      let idx = palette.get(key)
+      if (idx == null) {
+        if (nextColorIndex >= 256) {
+          // Palette full — find closest existing color (simple fallback)
+          idx = 1
+        } else {
+          idx = nextColorIndex++
+          palette.set(key, idx)
+        }
+      }
+
+      pixelColors[y * width + x] = idx
+    }
+  }
+
+  // Build Sixel data
+  const parts: string[] = []
+
+  // Raster attributes: Pan;Pad;Ph;Pv (aspect ratio 1:1, width, height)
+  parts.push(`"1;1;${width};${height}`)
+
+  // Define palette colors
+  for (const [key, idx] of palette) {
+    const [qr, qg, qb] = key.split(",").map(Number)
+    // Convert from 6-bit (0-63) to percentage (0-100)
+    const rPct = Math.round((qr! / 63) * 100)
+    const gPct = Math.round((qg! / 63) * 100)
+    const bPct = Math.round((qb! / 63) * 100)
+    parts.push(`#${idx};2;${rPct};${gPct};${bPct}`)
+  }
+
+  // Encode pixel data in 6-row bands
+  for (let bandY = 0; bandY < height; bandY += 6) {
+    if (bandY > 0) {
+      parts.push(SIXEL_NEWLINE) // Move to next sixel row
+    }
+
+    // For each color in the palette, emit the sixel row
+    // (Only emit colors that appear in this band)
+    const bandColors = new Set<number>()
+    for (let dy = 0; dy < 6 && bandY + dy < height; dy++) {
+      for (let x = 0; x < width; x++) {
+        const ci = pixelColors[(bandY + dy) * width + x]!
+        if (ci > 0) bandColors.add(ci)
+      }
+    }
+
+    let first = true
+    for (const colorIdx of bandColors) {
+      if (!first) {
+        parts.push("$") // Carriage return within sixel line (reposition to start)
+      }
+      first = false
+
+      parts.push(`#${colorIdx}`)
+
+      // Build the sixel characters for this color in this band
+      for (let x = 0; x < width; x++) {
+        let sixelBits = 0
+        for (let dy = 0; dy < 6; dy++) {
+          const y = bandY + dy
+          if (y < height && pixelColors[y * width + x] === colorIdx) {
+            sixelBits |= 1 << dy
+          }
+        }
+        // Sixel character = bits + 63 (0x3F)
+        parts.push(String.fromCharCode(sixelBits + 63))
+      }
+    }
+  }
+
+  return `${DCS_START}q${parts.join("")}${ST}`
+}
+
+/**
+ * Check if the current terminal likely supports the Sixel protocol.
+ *
+ * This is a heuristic based on environment variables. For definitive
+ * detection, send a DA1 (Device Attributes) query and check for "4"
+ * in the response, but that requires async I/O.
+ *
+ * Known supporting terminals: xterm (with +sixel), mlterm, foot, mintty,
+ * WezTerm, Contour, Sixel-enabled builds of various terminals.
+ *
+ * @returns `true` if the terminal likely supports Sixel
+ */
+export function isSixelSupported(): boolean {
+  const term = process.env.TERM ?? ""
+  const termProgram = process.env.TERM_PROGRAM ?? ""
+
+  // mlterm supports Sixel natively
+  if (termProgram === "mlterm" || term.startsWith("mlterm")) return true
+
+  // foot supports Sixel
+  if (termProgram === "foot" || term === "foot" || term === "foot-extra") return true
+
+  // WezTerm supports Sixel
+  if (termProgram === "WezTerm") return true
+
+  // mintty supports Sixel
+  if (termProgram === "mintty") return true
+
+  // xterm might support Sixel if compiled with +sixel
+  // We can't know for sure from env alone, so we don't claim support
+  // (the user can set protocol='sixel' explicitly)
+
+  return false
+}

package/src/images.ts

@@ -0,0 +1,22 @@
+/**
+ * silvery/images -- Image rendering via Kitty graphics and Sixel protocol.
+ *
+ * ```tsx
+ * import { Image } from '@silvery/ui/images'
+ *
+ * <Image src={pngBuffer} width={40} height={15} fallback="[image]" />
+ * ```
+ *
+ * Auto-detects the best available protocol (Kitty > Sixel > text fallback).
+ *
+ * @packageDocumentation
+ */
+
+export { Image } from "./image/Image"
+export type { ImageProps } from "./image/Image"
+
+export { encodeKittyImage, deleteKittyImage, isKittyGraphicsSupported } from "./image/kitty-graphics"
+export type { KittyImageOptions } from "./image/kitty-graphics"
+
+export { encodeSixel, isSixelSupported } from "./image/sixel-encoder"
+export type { SixelImageData } from "./image/sixel-encoder"

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * silvery-ui - UI components for Ink/silvery TUI apps
+ *
+ * Progress indicators, spinners, and task wrappers for CLI applications.
+ *
+ * @example
+ * ```ts
+ * // Fluent task API (recommended)
+ * import { task, tasks } from "@silvery/ui/progress";
+ *
+ * const data = await task("Loading").wrap(fetchData());
+ *
+ * const results = await tasks()
+ *   .add("Loading", () => fetchData())
+ *   .add("Processing", () => process())
+ *   .run({ clear: true });
+ *
+ * // Low-level CLI components
+ * import { Spinner, ProgressBar } from "@silvery/ui/cli";
+ *
+ * // React/TUI components
+ * import { Spinner, ProgressBar } from "@silvery/ui/react";
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Re-export everything for convenience
+export * from "./types.js"
+export * from "./cli/index.js"
+export * from "./wrappers/index.js"
+
+// Note: React components should be imported from "@silvery/ui/react"
+// to avoid requiring React as a dependency for CLI-only usage

package/src/input/Select.tsx

@@ -0,0 +1,155 @@
+/**
+ * React Select component for silvery/Ink TUI apps
+ *
+ * Single-choice selection list with keyboard navigation.
+ */
+
+import React, { useState, useEffect, useCallback } from "react"
+import type { SelectProps, SelectOption } from "../types.js"
+
+/**
+ * Scrollable single-choice selection list
+ *
+ * @example
+ * ```tsx
+ * import { Select } from "@silvery/ui/input";
+ *
+ * function SettingsView() {
+ *   const [theme, setTheme] = useState("light");
+ *
+ *   return (
+ *     <Select
+ *       options={[
+ *         { label: "Light", value: "light" },
+ *         { label: "Dark", value: "dark" },
+ *         { label: "System", value: "system" },
+ *       ]}
+ *       value={theme}
+ *       onChange={setTheme}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function Select<T>({
+  options,
+  value,
+  onChange,
+  maxVisible = 10,
+  highlightIndex: controlledHighlightIndex,
+  onHighlightChange,
+}: SelectProps<T>): React.ReactElement {
+  // Find the index of the currently selected value
+  const selectedIndex = options.findIndex((opt) => opt.value === value)
+
+  // Internal highlight state (for uncontrolled mode)
+  const [internalHighlightIndex, setInternalHighlightIndex] = useState(selectedIndex >= 0 ? selectedIndex : 0)
+
+  // Use controlled or internal highlight index
+  const highlightIndex = controlledHighlightIndex ?? internalHighlightIndex
+
+  // Calculate scroll window
+  const scrollOffset = Math.max(0, Math.min(highlightIndex - Math.floor(maxVisible / 2), options.length - maxVisible))
+  const visibleOptions = options.slice(scrollOffset, scrollOffset + maxVisible)
+  const hasMoreAbove = scrollOffset > 0
+  const hasMoreBelow = scrollOffset + maxVisible < options.length
+
+  // Sync internal highlight when value changes externally
+  useEffect(() => {
+    if (controlledHighlightIndex === undefined && selectedIndex >= 0) {
+      setInternalHighlightIndex(selectedIndex)
+    }
+  }, [selectedIndex, controlledHighlightIndex])
+
+  return (
+    <div data-silvery-select>
+      {hasMoreAbove && <div data-silvery-select-scroll-indicator="up">...</div>}
+      {visibleOptions.map((option, visibleIdx) => {
+        const actualIndex = scrollOffset + visibleIdx
+        const isSelected = option.value === value
+        const isHighlighted = actualIndex === highlightIndex
+
+        return (
+          <div key={actualIndex} data-silvery-select-option data-selected={isSelected} data-highlighted={isHighlighted}>
+            <span data-silvery-select-indicator>{isSelected ? ">" : " "}</span>
+            <span data-silvery-select-label>{option.label}</span>
+          </div>
+        )
+      })}
+      {hasMoreBelow && <div data-silvery-select-scroll-indicator="down">...</div>}
+    </div>
+  )
+}
+
+/**
+ * Hook for managing select state with keyboard navigation
+ *
+ * @example
+ * ```tsx
+ * function MySelect() {
+ *   const options = [
+ *     { label: "Option A", value: "a" },
+ *     { label: "Option B", value: "b" },
+ *   ];
+ *
+ *   const { highlightIndex, moveUp, moveDown, select, value } = useSelect({
+ *     options,
+ *     initialValue: "a",
+ *   });
+ *
+ *   useInput((input, key) => {
+ *     if (key.upArrow) moveUp();
+ *     if (key.downArrow) moveDown();
+ *     if (key.return) select();
+ *   });
+ *
+ *   return <Select options={options} value={value} highlightIndex={highlightIndex} />;
+ * }
+ * ```
+ */
+export function useSelect<T>({
+  options,
+  initialValue,
+  onChange,
+}: {
+  options: SelectOption<T>[]
+  initialValue?: T
+  onChange?: (value: T) => void
+}): {
+  value: T | undefined
+  highlightIndex: number
+  moveUp: () => void
+  moveDown: () => void
+  select: () => void
+  setHighlightIndex: (index: number) => void
+} {
+  const initialIndex = initialValue !== undefined ? options.findIndex((opt) => opt.value === initialValue) : 0
+
+  const [highlightIndex, setHighlightIndex] = useState(Math.max(0, initialIndex))
+  const [value, setValue] = useState<T | undefined>(initialValue)
+
+  const moveUp = useCallback(() => {
+    setHighlightIndex((i) => Math.max(0, i - 1))
+  }, [])
+
+  const moveDown = useCallback(() => {
+    setHighlightIndex((i) => Math.min(options.length - 1, i + 1))
+  }, [options.length])
+
+  const select = useCallback(() => {
+    const option = options[highlightIndex]
+    if (option) {
+      setValue(option.value)
+      onChange?.(option.value)
+    }
+  }, [highlightIndex, options, onChange])
+
+  return {
+    value,
+    highlightIndex,
+    moveUp,
+    moveDown,
+    select,
+    setHighlightIndex,
+  }
+}