@effect-tui/core 0.1.0-alpha.1

package/src/render/surface.ts

@@ -0,0 +1,238 @@
+import { CellBuffer, type Wcwidth, defaultWcwidth } from "./buffer.js"
+import { Palette, ScopedPalette, type ColorValue, type StyleSpec, mergeStyle } from "./palette.js"
+
+// Re-export palette types for other modules
+export type { ColorValue, StyleSpec }
+export { Palette, mergeStyle }
+
+/** Color inputs accepted by helpers: numeric, rgb object, or string (hex/name/grayN). */
+export type ColorLike = ColorValue | string
+
+export const BASE_NAMES = {
+  black: 0,
+  red: 1,
+  green: 2,
+  yellow: 3,
+  blue: 4,
+  magenta: 5,
+  cyan: 6,
+  white: 7,
+  brightBlack: 8,
+  brightRed: 9,
+  brightGreen: 10,
+  brightYellow: 11,
+  brightBlue: 12,
+  brightMagenta: 13,
+  brightCyan: 14,
+  brightWhite: 15,
+} as const
+
+/**
+ * Parse flexible color inputs into a ColorValue.
+ * Supports: number (0..255), {r,g,b}, "#rrggbb", base names, and gray0..gray23.
+ */
+export function parseColor(c: ColorLike): ColorValue {
+  if (typeof c === "number") return c
+  if (typeof c === "object") return { r: c.r | 0, g: c.g | 0, b: c.b | 0 }
+  const s = String(c).trim()
+
+  if (s.startsWith("#")) {
+    const hex = s.slice(1)
+    if (hex.length === 6) {
+      const r = parseInt(hex.slice(0, 2), 16)
+      const g = parseInt(hex.slice(2, 4), 16)
+      const b = parseInt(hex.slice(4, 6), 16)
+      return { r, g, b }
+    }
+  }
+
+  if (s in BASE_NAMES) return BASE_NAMES[s as keyof typeof BASE_NAMES]
+
+  const m = /^(?:gray|grey)(\d{1,2})$/.exec(s)
+  if (m?.[1]) {
+    const n = Math.max(0, Math.min(23, parseInt(m[1], 10)))
+    return 232 + n
+  }
+
+  return 7 // default to white if unrecognized
+}
+
+type ColorsApi = typeof BASE_NAMES & {
+  rgb(r: number, g: number, b: number): ColorValue
+  hex(hex: string): ColorValue
+  gray(level: number): number
+}
+
+export const Colors: ColorsApi = Object.assign(
+  {
+    rgb(r: number, g: number, b: number): ColorValue {
+      return { r, g, b }
+    },
+    hex(hex: string): ColorValue {
+      return parseColor(hex)
+    },
+    gray(level: number): number {
+      const n = Math.max(0, Math.min(23, level | 0))
+      return 232 + n
+    },
+  },
+  BASE_NAMES,
+) as ColorsApi
+
+export function derivePalette(p: Palette, base?: StyleSpec): Palette {
+  return new ScopedPalette(p, base)
+}
+
+export class Surface {
+  readonly w: number
+  readonly h: number
+  private B: CellBuffer
+  private palette: Palette
+
+  constructor(width: number, height: number, opts?: { palette?: Palette; wcwidth?: Wcwidth }) {
+    this.w = Math.max(1, width | 0)
+    this.h = Math.max(1, height | 0)
+
+    const wc = opts?.wcwidth ?? defaultWcwidth
+    this.B = new CellBuffer(this.w, this.h, wc)
+    this.palette = opts?.palette ?? new Palette()
+
+    this.B.clear(0)
+  }
+
+  /** Clear the back buffer (B) to spaces in the given style. */
+  clear(styleId = 0): void {
+    this.B.clear(styleId)
+  }
+
+  /** Draw a single code point at (x,y). If width=2, marks the following cell as continuation (w=0). */
+  drawCP(x: number, y: number, cp: number, styleId = 0): void {
+    this.B.drawCP(x, y, cp, styleId)
+  }
+
+  /** Draw plain text (no wrapping) clipped to width. Uses Intl.Segmenter if available. */
+  drawText(x: number, y: number, text: string, styleId = 0, maxWidth?: number): void {
+    this.B.drawText(x, y, text, styleId, maxWidth)
+  }
+
+  /** Fill a rectangle with a code point + style. */
+  fillRect(x: number, y: number, w: number, h: number, cp = 32, styleId = 0): void {
+    this.B.fillRect(x, y, w, h, cp, styleId)
+  }
+
+  // --- Clipping helpers (forwarded to back buffer) ---
+
+  pushClip(x: number, y: number, w: number, h: number): void {
+    this.B.pushClip(x, y, w, h)
+  }
+
+  popClip(): void {
+    this.B.popClip()
+  }
+
+  withClip(x: number, y: number, w: number, h: number, fn: () => void): void {
+    this.B.withClip(x, y, w, h, fn)
+  }
+
+  // --- Offset helpers (forwarded to back buffer) ---
+
+  pushOffset(dx: number, dy: number): void {
+    this.B.pushOffset(dx, dy)
+  }
+
+  popOffset(): void {
+    this.B.popOffset()
+  }
+
+  withOffset(dx: number, dy: number, fn: () => void): void {
+    this.B.withOffset(dx, dy, fn)
+  }
+
+  /** Convert surface to plain text (for testing). */
+  toString(): string {
+    const lines: string[] = []
+    for (let y = 0; y < this.h; y++) {
+      const row = y * this.w
+      let line = ""
+      for (let x = 0; x < this.w; x++) {
+        const i = row + x
+        const cp = this.B.g[i]
+        const w = this.B.cw[i]
+        if (w !== 0) line += cp === 32 ? " " : String.fromCodePoint(cp)
+      }
+      // trim right spaces
+      line = line.replace(/\s+$/, "")
+      lines.push(line)
+    }
+    return lines.join("\n")
+  }
+
+  /** Compute tight bounding box of content in back buffer: any non-space glyph or non-default style. */
+  contentBounds(): { x: number; y: number; w: number; h: number } {
+    const W = this.w
+    const H = this.h
+    const g = this.B.g
+    const s = this.B.s
+    const cw = this.B.cw
+    let minX = W,
+      minY = H,
+      maxX = -1,
+      maxY = -1
+    for (let y = 0; y < H; y++) {
+      const row = y * W
+      for (let x = 0; x < W; x++) {
+        const i = row + x
+        if (cw[i] === 0) continue
+        if (g[i] !== 32 || s[i] !== 0) {
+          if (x < minX) minX = x
+          if (y < minY) minY = y
+          if (x > maxX) maxX = x
+          if (y > maxY) maxY = y
+        }
+      }
+    }
+    if (maxX < minX || maxY < minY) return { x: 0, y: 0, w: 0, h: 0 }
+    return { x: minX, y: minY, w: maxX - minX + 1, h: maxY - minY + 1 }
+  }
+
+  /** Build styled text lines for a given bounds region of the back buffer (without trailing newlines). */
+  buildStyledLines(bounds: { x: number; y: number; w: number; h: number }, palette: Palette = this.palette): string[] {
+    const W = this.w
+    const g = this.B.g
+    const s = this.B.s
+    const cw = this.B.cw
+    const lines: string[] = []
+    const { x: bx, y: by, w: bw, h: bh } = bounds
+    const endY = Math.min(by + bh, this.h)
+    const endX = Math.min(bx + bw, W)
+
+    for (let y = Math.max(0, by); y < endY; y++) {
+      const row = y * W
+      let line = ""
+      let currentStyle = -1
+
+      for (let x = Math.max(0, bx); x < endX; x++) {
+        const i = row + x
+        if (cw[i] === 0) continue // skip continuation cells
+
+        const styleId = s[i]
+        if (styleId !== currentStyle) {
+          line += palette.sgr(styleId)
+          currentStyle = styleId
+        }
+
+        const cp = g[i]
+        line += cp === 32 ? " " : String.fromCodePoint(cp)
+      }
+
+      // reset style at end of line
+      if (currentStyle !== 0) {
+        line += palette.sgr(0)
+      }
+
+      lines.push(line)
+    }
+
+    return lines
+  }
+}

package/src/runtime/backend_node.ts

@@ -0,0 +1,80 @@
+import { ANSI, Terminal } from "../ansi.js"
+
+export interface TerminalBackend {
+  size(): { cols: number; rows: number }
+  write(s: string): void
+  enterFullscreen(): void
+  exitFullscreen(): void
+  hideCursor(): void
+  showCursor(): void
+  enableMouse(): void
+  disableMouse(): void
+  /** Query terminal for current cursor position (1-based). */
+  getCursorPosition(): Promise<{ row: number; col: number }>
+}
+
+export class TerminalBackendLive implements TerminalBackend {
+  size() {
+    return { cols: process.stdout.columns || 80, rows: process.stdout.rows || 24 }
+  }
+  write(s: string) {
+    try {
+      if (!process.stdout.write(s)) {
+        // queue a microtask to flush on 'drain' without blocking
+        const onDrain = () => process.stdout.off("drain", onDrain)
+        process.stdout.on("drain", onDrain)
+      }
+    } catch {}
+  }
+  enterFullscreen() {
+    this.write(Terminal.enterFullscreen)
+    this.write(Terminal.bracketedPasteOn)
+    this.enableMouse()
+  }
+  exitFullscreen() {
+    this.disableMouse()
+    this.write(Terminal.bracketedPasteOff)
+    this.write(Terminal.exitFullscreen)
+  }
+  hideCursor() {
+    this.write(ANSI.cursor.hide)
+  }
+  showCursor() {
+    this.write(ANSI.cursor.show)
+  }
+  enableMouse() {
+    this.write(Terminal.mouseOn)
+  }
+  disableMouse() {
+    this.write(Terminal.mouseOff)
+  }
+
+  getCursorPosition(): Promise<{ row: number; col: number }> {
+    return new Promise((resolve) => {
+      const inp = process.stdin
+      let buf = ""
+      const onData = (b: Buffer) => {
+        buf += b.toString("utf8")
+        // Look for ESC [ row ; col R
+        const m = /\x1b\[(\d+);(\d+)R/.exec(buf)
+        if (m) {
+          cleanup()
+          resolve({ row: parseInt(m[1], 10) || 1, col: parseInt(m[2], 10) || 1 })
+        }
+      }
+      const cleanup = () => {
+        clearTimeout(timer)
+        inp.off("data", onData)
+      }
+      const timer = setTimeout(() => {
+        cleanup()
+        // Fallback: best effort guess (bottom-left)
+        resolve({ row: process.stdout.rows || 24, col: 1 })
+      }, 120)
+
+      inp.on("data", onData)
+      // Device Status Report: “Report Cursor Position”
+      this.write(Terminal.reportCursorPosition)
+    })
+  }
+}

package/src/spring-physics.ts

@@ -0,0 +1,151 @@
+// spring-physics.ts - Core spring physics primitives
+
+export type SpringState = {
+	// current normalized position (e.g., 0..1)
+	x: number
+	// current velocity in units per second
+	v: number
+	// target normalized position
+	target: number
+}
+
+export type SpringConfig = {
+	// natural frequency in Hz (cycles per second). e.g., 3 = fairly snappy
+	frequency?: number
+	// damping ratio (1 = critical damping, < 1 underdamped, > 1 overdamped)
+	dampingRatio?: number
+	// when |x-target| and |v| fall below epsilon, consider settled
+	epsilon?: number
+	// Optional UX-style controls akin to Motion libraries:
+	// approximate settle time in seconds (to ~2% band)
+	duration?: number
+	// bounce amount (0..1), maps to overshoot ratio; default 0 = no overshoot
+	bounce?: number
+}
+
+export const DEFAULTS: Required<Omit<SpringConfig, "duration">> & { duration?: number } = {
+	frequency: 3,
+	dampingRatio: 1,
+	epsilon: 0.0005,
+	duration: undefined,
+	bounce: 0,
+}
+
+export function fromDurationBounce(durationSec: number, bounce = 0): { frequency: number; dampingRatio: number } {
+	const d = Math.max(0.05, durationSec)
+	let zeta: number
+	const b = Math.max(0, Math.min(0.999, bounce))
+	if (b <= 0) {
+		zeta = 1 // critically damped, no overshoot
+	} else {
+		// Map overshoot ratio M_p=b to damping ratio via standard 2nd-order step response
+		const lnMp = Math.log(Math.max(1e-6, b))
+		zeta = Math.sqrt((lnMp * lnMp) / (Math.PI * Math.PI + lnMp * lnMp))
+		zeta = Math.max(0.02, Math.min(0.999, zeta))
+	}
+	// Use ~2% settling time approximation Ts ≈ 4/(ζ ω_n)
+	const omega = 4 / (Math.max(0.02, zeta) * d)
+	const freq = omega / (2 * Math.PI)
+	return { frequency: freq, dampingRatio: zeta }
+}
+
+/**
+ * Advance a 1D damped spring towards its target using a semi-implicit Euler step.
+ * - Stable enough for small dt (<= ~1/30s) typical of frame ticks.
+ * - Uses frequency/dampingRatio to feel similar across frame rates.
+ */
+export function advanceSpring(
+	state: SpringState,
+	dtSeconds: number,
+	config?: SpringConfig,
+): SpringState & { settled: boolean } {
+	let { frequency, dampingRatio, epsilon } = { ...DEFAULTS, ...(config ?? {}) }
+	const bounce = config?.bounce ?? DEFAULTS.bounce
+	// If duration is provided, derive frequency/dampingRatio from it and bounce
+	if (config?.duration != null) {
+		const derived = fromDurationBounce(config.duration, config.bounce ?? DEFAULTS.bounce)
+		frequency = derived.frequency
+		dampingRatio = derived.dampingRatio
+	}
+	const omega = Math.PI * 2 * Math.max(0.001, frequency)
+	const k = omega * omega // stiffness
+	const c = 2 * dampingRatio * omega // damping
+
+	let { x, v, target } = state
+	const prevX = x
+	if (dtSeconds <= 0)
+		return {
+			x,
+			v,
+			target,
+			settled: Math.abs(x - target) < epsilon && Math.abs(v) < epsilon,
+		}
+
+	// semi-implicit Euler integration
+	const a = k * (target - x) - c * v
+	v += a * dtSeconds
+	x += v * dtSeconds
+
+	// With bounce=0 users expect a monotonic approach; clamp if we cross the target.
+	if (bounce <= 0) {
+		const crossed = (prevX - target) * (x - target) <= 0
+		if (crossed) {
+			x = target
+			v = 0
+		}
+	}
+
+	// snap to target when sufficiently close to avoid long tails
+	const settled = Math.abs(x - target) < epsilon && Math.abs(v) < epsilon
+	if (settled) {
+		x = target
+		v = 0
+	}
+	return { x, v, target, settled }
+}
+
+/**
+ * Internal exact spring step for 1D channel (frame-rate independent).
+ * Uses closed-form analytical solution for underdamped/critically-damped/overdamped cases.
+ */
+export function stepSpring1D(
+	x: number,
+	v: number,
+	target: number,
+	dt: number,
+	freq: number,
+	zeta: number,
+): { x: number; v: number } {
+	const omega = Math.max(0.001, freq) * 2 * Math.PI
+	const A0 = x - target
+	const exp = Math.exp(-zeta * omega * dt)
+	if (zeta < 1) {
+		// Underdamped
+		const wd = omega * Math.sqrt(1 - zeta * zeta)
+		const cos = Math.cos(wd * dt)
+		const sin = Math.sin(wd * dt)
+		const B0 = v + zeta * omega * A0
+		const A = exp * (A0 * cos + (B0 / wd) * sin)
+		const dA = exp * (-zeta * omega * (A0 * cos + (B0 / wd) * sin) + (-A0 * wd * sin + B0 * cos))
+		return { x: target + A, v: dA }
+	} else if (zeta === 1) {
+		// Critically damped
+		const t = dt
+		const C2 = v + omega * A0
+		const A = exp * (A0 + C2 * t)
+		const dA = exp * (C2 - omega * (A0 + C2 * t))
+		return { x: target + A, v: dA }
+	} else {
+		// Overdamped
+		const s = Math.sqrt(zeta * zeta - 1)
+		const r1 = -omega * (zeta - s)
+		const r2 = -omega * (zeta + s)
+		const C1 = (v - r2 * A0) / (r1 - r2)
+		const C2 = A0 - C1
+		const e1 = Math.exp(r1 * dt)
+		const e2 = Math.exp(r2 * dt)
+		const A = C1 * e1 + C2 * e2
+		const dA = C1 * r1 * e1 + C2 * r2 * e2
+		return { x: target + A, v: dA }
+	}
+}

package/src/spring.ts

@@ -0,0 +1,234 @@
+// spring.ts - Higher-level spring API for number and color values
+
+import type { ColorLike, ColorValue } from "./render/surface.js"
+import { parseColor } from "./render/surface.js"
+import { idxToRGB } from "./render/color-utils.js"
+import { advanceSpring, DEFAULTS, type SpringConfig, type SpringState } from "./spring-physics.js"
+
+// ---- Types ----
+
+export type SpringValue = SpringState & {
+	/** last timestamp in ms used for dt; hidden from callers */
+	_last?: number
+	/** default config for ticks (optional) */
+	_config?: SpringConfig
+}
+
+export type SpringColorValue = {
+	x: { r: number; g: number; b: number }
+	v: { r: number; g: number; b: number }
+	target: { r: number; g: number; b: number }
+	_last?: number
+	_config?: SpringConfig
+}
+
+export type AnySpringValue = SpringValue | SpringColorValue
+
+export type SpringAutoOptions = SpringConfig & {
+	as?: "auto" | "number" | "color"
+}
+
+// ---- Helpers ----
+
+export function colorLikeToRGB(c: ColorLike): { r: number; g: number; b: number } {
+	const v = parseColor(c)
+	if (typeof v === "number") return idxToRGB(v)
+	return { r: v.r | 0, g: v.g | 0, b: v.b | 0 }
+}
+
+function isColorSpring(s: AnySpringValue): s is SpringColorValue {
+	return typeof (s as any).x === "object"
+}
+
+// ---- Number spring primitives ----
+
+function initNumber(initial: number, cfg?: SpringConfig): SpringValue {
+	return {
+		x: initial,
+		v: 0,
+		target: initial,
+		...(cfg && { _config: cfg }),
+	}
+}
+
+function tickNumber(s: SpringValue, nowMs: number, cfg?: SpringConfig): SpringValue {
+	const last = s._last ?? nowMs
+	const dt = Math.max(0, Math.min(0.1, (nowMs - last) / 1000))
+	const stepped = advanceSpring(s, dt, cfg ?? s._config)
+	return {
+		...s,
+		x: stepped.x,
+		v: stepped.v,
+		target: stepped.target,
+		_last: nowMs,
+		...(cfg || s._config ? { _config: cfg ?? s._config } : {}),
+	}
+}
+
+function toNumber(s: SpringValue, target: number): SpringValue {
+	return { ...s, target }
+}
+
+function valueNumber(s: SpringValue): number {
+	return s.x
+}
+
+function settledNumber(s: SpringValue, eps = DEFAULTS.epsilon): boolean {
+	return Math.abs(s.x - s.target) < eps && Math.abs(s.v) < eps
+}
+
+// ---- Color spring primitives ----
+
+const SpringColor = {
+	init(initial: ColorLike, cfg?: SpringConfig): SpringColorValue {
+		const rgb = colorLikeToRGB(initial)
+		return {
+			x: { ...rgb },
+			v: { r: 0, g: 0, b: 0 },
+			target: { ...rgb },
+			...(cfg && { _config: cfg }),
+		}
+	},
+	to(s: SpringColorValue, target: ColorLike): SpringColorValue {
+		const rgb = colorLikeToRGB(target)
+		return { ...s, target: { ...rgb } }
+	},
+	tick(s: SpringColorValue, nowMs: number, cfg?: SpringConfig): SpringColorValue {
+		const last = s._last ?? nowMs
+		const dt = Math.max(0, Math.min(0.1, (nowMs - last) / 1000))
+		const rx = advanceSpring({ x: s.x.r, v: s.v.r, target: s.target.r }, dt, cfg ?? s._config)
+		const gx = advanceSpring({ x: s.x.g, v: s.v.g, target: s.target.g }, dt, cfg ?? s._config)
+		const bx = advanceSpring({ x: s.x.b, v: s.v.b, target: s.target.b }, dt, cfg ?? s._config)
+		return {
+			x: { r: rx.x, g: gx.x, b: bx.x },
+			v: { r: rx.v, g: gx.v, b: bx.v },
+			target: { r: s.target.r, g: s.target.g, b: s.target.b },
+			_last: nowMs,
+			...(cfg || s._config ? { _config: cfg ?? s._config } : {}),
+		}
+	},
+	value(s: SpringColorValue): ColorValue {
+		const clamp = (n: number) => (n < 0 ? 0 : n > 255 ? 255 : n | 0)
+		return { r: clamp(s.x.r), g: clamp(s.x.g), b: clamp(s.x.b) }
+	},
+	settled(s: SpringColorValue, eps = DEFAULTS.epsilon): boolean {
+		const dx = Math.abs(s.x.r - s.target.r) + Math.abs(s.x.g - s.target.g) + Math.abs(s.x.b - s.target.b)
+		const dv = Math.abs(s.v.r) + Math.abs(s.v.g) + Math.abs(s.v.b)
+		return dx < eps * 3 && dv < eps * 3
+	},
+}
+
+// ---- Unified, type-agnostic helpers ----
+
+// Overloads for the ergonomic, single-API surface
+function create(initial: number, cfg?: SpringAutoOptions): SpringValue
+function create(initial: ColorLike, cfg?: SpringAutoOptions): SpringColorValue
+function create(initial: number | ColorLike, cfg?: SpringAutoOptions): AnySpringValue {
+	const as = cfg?.as ?? (typeof initial === "number" ? "number" : "color")
+	return as === "number" ? initNumber(initial as number, cfg) : SpringColor.init(initial as ColorLike, cfg)
+}
+
+function to(s: SpringValue, target: number): SpringValue
+function to(s: SpringColorValue, target: ColorLike): SpringColorValue
+function to(s: AnySpringValue, target: number | ColorLike): AnySpringValue {
+	return isColorSpring(s) ? SpringColor.to(s, target as ColorLike) : toNumber(s as SpringValue, target as number)
+}
+
+function tick(s: SpringValue, nowMs: number, cfg?: SpringConfig): SpringValue
+function tick(s: SpringColorValue, nowMs: number, cfg?: SpringConfig): SpringColorValue
+function tick(s: AnySpringValue, nowMs: number, cfg?: SpringConfig): AnySpringValue {
+	return isColorSpring(s) ? SpringColor.tick(s, nowMs, cfg) : tickNumber(s as SpringValue, nowMs, cfg)
+}
+
+function read(s: SpringValue): number
+function read(s: SpringColorValue): ColorValue
+function read(s: AnySpringValue): number | ColorValue {
+	return isColorSpring(s) ? SpringColor.value(s) : valueNumber(s as SpringValue)
+}
+
+function isSettled(s: SpringValue, eps?: number): boolean
+function isSettled(s: SpringColorValue, eps?: number): boolean
+function isSettled(s: AnySpringValue, eps = DEFAULTS.epsilon): boolean {
+	return isColorSpring(s) ? SpringColor.settled(s, eps) : settledNumber(s as SpringValue, eps)
+}
+
+// ---- Public Spring API ----
+
+export type SpringAPI = {
+	// number
+	init(initial: number, cfg?: SpringConfig): SpringValue
+	to(s: SpringValue, target: number): SpringValue
+	tick(s: SpringValue, nowMs: number, cfg?: SpringConfig): SpringValue
+	value(s: SpringValue): number
+	settled(s: SpringValue, eps?: number): boolean
+
+	// color (legacy explicit path kept for convenience)
+	color: {
+		init(initial: ColorLike, cfg?: SpringConfig): SpringColorValue
+		to(s: SpringColorValue, target: ColorLike): SpringColorValue
+		tick(s: SpringColorValue, nowMs: number, cfg?: SpringConfig): SpringColorValue
+		value(s: SpringColorValue): ColorValue
+		settled(s: SpringColorValue, eps?: number): boolean
+	}
+
+	// unified ergonomic API (overloads)
+	create(initial: number, cfg?: SpringAutoOptions): SpringValue
+	create(initial: ColorLike, cfg?: SpringAutoOptions): SpringColorValue
+	to(s: SpringColorValue, target: ColorLike): SpringColorValue // overload of number variant
+	tick(s: SpringColorValue, nowMs: number, cfg?: SpringConfig): SpringColorValue // overload of number variant
+	advance(s: SpringValue, nowMs: number, cfg?: SpringConfig): SpringValue
+	advance(s: SpringColorValue, nowMs: number, cfg?: SpringConfig): SpringColorValue
+	read(s: SpringValue): number
+	read(s: SpringColorValue): ColorValue
+	isSettled(s: SpringValue, eps?: number): boolean
+	isSettled(s: SpringColorValue, eps?: number): boolean
+}
+
+export const Spring: SpringAPI = {
+	// number
+	init: initNumber,
+	to,
+	tick,
+	value: valueNumber,
+	settled: settledNumber,
+
+	// color (explicit path)
+	color: SpringColor,
+
+	// unified ergonomic API
+	create,
+	advance: tick,
+	read,
+	isSettled,
+}
+
+// ---- Stepper (frame-based discrete animation) ----
+
+export type Stepper = {
+	index: number
+	length: number
+	intervalMs: number
+	_accumMs: number
+	_last?: number
+}
+
+export const Step = {
+	init(length: number, intervalMs: number, startIndex = 0): Stepper {
+		return {
+			index: ((startIndex % length) + length) % length,
+			length: Math.max(1, length | 0),
+			intervalMs: Math.max(1, intervalMs | 0),
+			_accumMs: 0,
+		}
+	},
+	tick(s: Stepper, nowMs: number): Stepper {
+		const last = s._last ?? nowMs
+		let accum = s._accumMs + Math.max(0, nowMs - last)
+		let idx = s.index
+		while (accum >= s.intervalMs) {
+			accum -= s.intervalMs
+			idx = (idx + 1) % s.length
+		}
+		return { ...s, index: idx, _accumMs: accum, _last: nowMs }
+	},
+}