@effect-tui/react 0.1.0-alpha.1

package/src/motion/spring-math.ts

@@ -0,0 +1,114 @@
+/**
+ * Spring physics calculations using analytical solutions.
+ * Matches framer-motion's formulas.
+ */
+
+export interface SpringState {
+  value: number
+  velocity: number
+  done: boolean
+}
+
+export type SpringResolver = (t: number) => SpringState
+
+/**
+ * Create a spring resolver function using analytical solution.
+ * Returns a function that computes position/velocity at any time t.
+ */
+export function createSpringResolver(
+  from: number,
+  to: number,
+  initialVelocity: number,
+  stiffness: number,
+  damping: number,
+  mass: number,
+  restSpeed = 0.01,
+  restDelta = 0.01,
+): SpringResolver {
+  // Use same convention as framer-motion: initialDelta = from - to
+  const initialDelta = from - to
+  const dampingRatio = damping / (2 * Math.sqrt(stiffness * mass))
+  const angularFreq = Math.sqrt(stiffness / mass)
+  const gamma = dampingRatio * angularFreq
+
+  if (dampingRatio < 1) {
+    // Underdamped (oscillates)
+    const dampedFreq = angularFreq * Math.sqrt(1 - dampingRatio * dampingRatio)
+    // Coefficients matching framer-motion's formula
+    const A = initialDelta
+    const B = (initialVelocity + gamma * initialDelta) / dampedFreq
+
+    return (t: number): SpringState => {
+      const envelope = Math.exp(-gamma * t)
+      const cos = Math.cos(dampedFreq * t)
+      const sin = Math.sin(dampedFreq * t)
+
+      // Position: to + envelope * (A*cos + B*sin)
+      const value = to + envelope * (A * cos + B * sin)
+
+      // Velocity: derivative of position
+      const velocity = envelope * ((B * dampedFreq - gamma * A) * cos + (-A * dampedFreq - gamma * B) * sin)
+
+      const done = Math.abs(velocity) < restSpeed && Math.abs(to - value) < restDelta
+
+      return { value, velocity, done }
+    }
+  } else if (dampingRatio === 1) {
+    // Critically damped (fastest without oscillation)
+    const A = initialDelta
+    const B = initialVelocity + angularFreq * initialDelta
+
+    return (t: number): SpringState => {
+      const envelope = Math.exp(-angularFreq * t)
+      const value = to + envelope * (A + B * t)
+      const velocity = envelope * (B - angularFreq * A - angularFreq * B * t)
+
+      const done = Math.abs(velocity) < restSpeed && Math.abs(to - value) < restDelta
+
+      return { value, velocity, done }
+    }
+  } else {
+    // Overdamped (slow, no oscillation)
+    const s = Math.sqrt(dampingRatio * dampingRatio - 1)
+    const r1 = -angularFreq * (dampingRatio - s)
+    const r2 = -angularFreq * (dampingRatio + s)
+    // Solve: A + B = initialDelta, A*r1 + B*r2 = initialVelocity
+    const A = (initialVelocity - r2 * initialDelta) / (r1 - r2)
+    const B = initialDelta - A
+
+    return (t: number): SpringState => {
+      const e1 = Math.exp(r1 * t)
+      const e2 = Math.exp(r2 * t)
+      const value = to + A * e1 + B * e2
+      const velocity = A * r1 * e1 + B * r2 * e2
+
+      const done = Math.abs(velocity) < restSpeed && Math.abs(to - value) < restDelta
+
+      return { value, velocity, done }
+    }
+  }
+}
+
+/**
+ * Convert visualDuration/bounce to stiffness/damping.
+ * Uses Motion's formula from motion-dom.
+ */
+export function springFromVisualDuration(
+  visualDuration: number,
+  bounce: number,
+): { stiffness: number; damping: number } {
+  const root = (2 * Math.PI) / (visualDuration * 1.2)
+  const stiffness = root * root
+  // Clamp bounce to [0.05, 1], then invert: 0 bounce = damping ratio 1, 1 bounce = 0.05
+  const clampedBounce = Math.max(0.05, Math.min(1, 1 - bounce))
+  const damping = 2 * clampedBounce * Math.sqrt(stiffness)
+
+  return { stiffness, damping }
+}
+
+/**
+ * Check if a spring has settled.
+ */
+export function isSpringSettled(velocity: number, delta: number, restSpeed = 0.01, restDelta = 0.01): boolean {
+  return Math.abs(velocity) < restSpeed && Math.abs(delta) < restDelta
+}

package/src/motion/types.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared types for the motion system.
+ */
+
+export interface SpringOptions {
+  /** Stiffness of the spring. Higher = snappier. Default: 100 */
+  stiffness?: number
+  /** Damping of the spring. Higher = less oscillation. Default: 10 */
+  damping?: number
+  /** Mass of the spring. Higher = more inertia. Default: 1 */
+  mass?: number
+  /**
+   * Visual duration in seconds. This is the perceptual duration of the animation.
+   * The spring will feel like it completes in this time, though it may technically
+   * continue settling. Overrides stiffness/damping when provided.
+   */
+  visualDuration?: number
+  /** Bounce amount 0-1 when using visualDuration. 0 = no bounce, 1 = full bounce. Default: 0 */
+  bounce?: number
+  /** Velocity threshold to consider settled. Default: 0.01 */
+  restSpeed?: number
+  /** Position threshold to consider settled. Default: 0.01 */
+  restDelta?: number
+}
+
+export const DEFAULT_SPRING_OPTIONS: Required<SpringOptions> = {
+  stiffness: 100,
+  damping: 10,
+  mass: 1,
+  visualDuration: 0,
+  bounce: 0,
+  restSpeed: 0.01,
+  restDelta: 0.01,
+}

package/src/output.ts

@@ -0,0 +1,156 @@
+/**
+ * Output helpers for rendering CellBuffer to ANSI strings.
+ * Extracts common logic from renderer.ts rendering paths.
+ */
+
+import type { CellBuffer, Palette } from "@effect-tui/core"
+
+/**
+ * Emit a row of cells as an ANSI string with run-length SGR encoding.
+ * Handles wide characters (cellWidth=0 continuations) and style changes.
+ *
+ * @param buffer - The cell buffer to read from
+ * @param palette - Palette for SGR code generation
+ * @param y - Row index
+ * @param width - Terminal width
+ * @param startX - Start column (default 0)
+ * @param endX - End column exclusive (default width)
+ * @returns ANSI string for the row (no cursor positioning, no trailing reset)
+ */
+export function emitRow(
+	buffer: CellBuffer,
+	palette: Palette,
+	y: number,
+	width: number,
+	startX = 0,
+	endX = width,
+): { output: string; lastStyle: number } {
+	const row = y * width
+	let output = ""
+	let visualCol = startX
+	let currentStyle = -1
+
+	for (let x = startX; x < endX && visualCol < width; x++) {
+		const idx = row + x
+		const glyph = buffer.g[idx]
+		const styleId = buffer.s[idx]
+		const cellWidth = buffer.cw[idx] || 1
+
+		// Skip continuation cells (wide char second half)
+		if (cellWidth === 0) continue
+
+		// Stop if this char would overflow
+		if (visualCol + cellWidth > width) break
+
+		// Emit SGR only when style changes (run-length encoding)
+		if (styleId !== currentStyle) {
+			output += palette.sgr(styleId)
+			currentStyle = styleId
+		}
+
+		output += glyph === 32 ? " " : String.fromCodePoint(glyph)
+		visualCol += cellWidth
+	}
+
+	return { output, lastStyle: currentStyle }
+}
+
+/**
+ * Emit a row and reset style if needed.
+ */
+export function emitRowWithReset(
+	buffer: CellBuffer,
+	palette: Palette,
+	y: number,
+	width: number,
+	startX = 0,
+	endX = width,
+): string {
+	const { output, lastStyle } = emitRow(buffer, palette, y, width, startX, endX)
+	return lastStyle !== 0 ? output + palette.sgr(0) : output
+}
+
+/**
+ * Check if a row changed between two buffers.
+ */
+export function rowChanged(prev: CellBuffer, next: CellBuffer, y: number, width: number): boolean {
+	const row = y * width
+	for (let x = 0; x < width; x++) {
+		const idx = row + x
+		if (next.g[idx] !== prev.g[idx] || next.s[idx] !== prev.s[idx] || next.cw[idx] !== prev.cw[idx]) {
+			return true
+		}
+	}
+	return false
+}
+
+/**
+ * Find the rightmost column with content (non-space or styled).
+ * Returns 0 if row is empty.
+ */
+export function rowContentWidth(buffer: CellBuffer, y: number, width: number): number {
+	const row = y * width
+	for (let x = width - 1; x >= 0; x--) {
+		const idx = row + x
+		// Skip continuation cells
+		if (buffer.cw[idx] === 0) continue
+		// Found content if non-space or has style
+		if (buffer.g[idx] !== 32 || buffer.s[idx] !== 0) {
+			return x + 1
+		}
+	}
+	return 0
+}
+
+/**
+ * Find the change window between two buffers for a row.
+ * Returns the leftmost and rightmost changed columns, or null if no changes.
+ */
+export function findChangeWindow(
+	prev: CellBuffer,
+	next: CellBuffer,
+	y: number,
+	width: number,
+): { left: number; right: number } | null {
+	const row = y * width
+	let left = 0
+	let right = width - 1
+
+	// Find leftmost change
+	while (left <= right) {
+		const i = row + left
+		if (next.g[i] !== prev.g[i] || next.s[i] !== prev.s[i] || next.cw[i] !== prev.cw[i]) {
+			break
+		}
+		left++
+	}
+
+	// No changes found
+	if (left > right) return null
+
+	// Find rightmost change
+	while (right >= left) {
+		const i = row + right
+		if (next.g[i] !== prev.g[i] || next.s[i] !== prev.s[i] || next.cw[i] !== prev.cw[i]) {
+			break
+		}
+		right--
+	}
+
+	return { left, right }
+}
+
+/**
+ * Find the last row with content in a buffer.
+ */
+export function contentHeight(buffer: CellBuffer, width: number, height: number): number {
+	for (let y = height - 1; y >= 0; y--) {
+		const row = y * width
+		for (let x = 0; x < width; x++) {
+			const glyph = buffer.g[row + x]
+			const style = buffer.s[row + x]
+			if (glyph !== 32 || style !== 0) return y + 1
+		}
+	}
+	return 0
+}

package/src/profiler.ts

@@ -0,0 +1,88 @@
+// Simple render profiler - accumulates timing stats per phase
+// Enable with: PROFILE_TUI=1
+// Output goes to ./tui-profile.txt
+
+import { writeFileSync } from "node:fs"
+
+const ENABLED = process.env.PROFILE_TUI === "1"
+const OUTPUT_FILE = "tui-profile.txt"
+
+interface PhaseStats {
+  total: number
+  count: number
+  min: number
+  max: number
+}
+
+const phases = new Map<string, PhaseStats>()
+let frameCount = 0
+let frameTotal = 0
+
+export function startFrame(): number {
+  if (!ENABLED) return 0
+  return performance.now()
+}
+
+export function endFrame(start: number): void {
+  if (!ENABLED) return
+  const elapsed = performance.now() - start
+  frameCount++
+  frameTotal += elapsed
+}
+
+export function startPhase(): number {
+  if (!ENABLED) return 0
+  return performance.now()
+}
+
+export function endPhase(name: string, start: number): void {
+  if (!ENABLED) return
+  const elapsed = performance.now() - start
+  let stats = phases.get(name)
+  if (!stats) {
+    stats = { total: 0, count: 0, min: Infinity, max: 0 }
+    phases.set(name, stats)
+  }
+  stats.total += elapsed
+  stats.count++
+  stats.min = Math.min(stats.min, elapsed)
+  stats.max = Math.max(stats.max, elapsed)
+}
+
+export function dumpStats(): void {
+  if (!ENABLED || frameCount === 0) return
+
+  const lines: string[] = []
+  const avgFrame = frameTotal / frameCount
+  lines.push(`=== TUI Profile (${frameCount} frames, avg ${avgFrame.toFixed(2)}ms) ===`)
+
+  // Sort by total time descending
+  const sorted = [...phases.entries()].sort((a, b) => b[1].total - a[1].total)
+
+  for (const [name, stats] of sorted) {
+    const avg = stats.total / stats.count
+    const pct = ((stats.total / frameTotal) * 100).toFixed(1)
+    lines.push(
+      `  ${name.padEnd(12)} ${avg.toFixed(3)}ms avg  ${stats.min.toFixed(3)}-${stats.max.toFixed(3)}ms  ${pct}%`,
+    )
+  }
+  lines.push("")
+
+  try {
+    writeFileSync(OUTPUT_FILE, lines.join("\n"))
+    // Also print path after alt buffer exit
+    setTimeout(() => console.log(`Profile written to ${OUTPUT_FILE}`), 50)
+  } catch {
+    // Fallback to stderr if file write fails
+    console.error(lines.join("\n"))
+  }
+}
+
+// Auto-dump on exit
+if (ENABLED) {
+  process.on("exit", dumpStats)
+  process.on("SIGINT", () => {
+    dumpStats()
+    process.exit(0)
+  })
+}

package/src/reconciler/host-config.ts

@@ -0,0 +1,277 @@
+import Reconciler from "react-reconciler"
+import { createContext } from "react"
+import type { HostInstance, HostContext } from "./types.js"
+import { createHostInstance, createTextInstance, type RawTextHost, type BaseHost } from "../hosts/index.js"
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+/** Container is the root of our host tree */
+export interface Container {
+	root: HostInstance | null
+	ctx: HostContext
+}
+
+/** Props passed to host instances */
+type Props = Record<string, unknown>
+
+/** Element type (e.g., "text", "vstack", "box") */
+type Type = string
+
+/** Our host instance type */
+type Instance = BaseHost
+
+/** Text instance type */
+type TextInstance = RawTextHost
+
+/** Host context passed during tree traversal */
+interface ReconcilerHostContext {
+	isInsideText: boolean
+}
+
+// ============================================================================
+// Priority Management
+// ============================================================================
+
+const NoEventPriority = 0
+const DefaultEventPriority = 16
+let currentUpdatePriority = NoEventPriority
+
+// ============================================================================
+// Host Config
+// ============================================================================
+// Note: We define methods with proper types but cast the final config to any
+// because react-reconciler's HostConfig type has ~80 required methods and
+// changes frequently between versions. This gives us type safety within
+// each method while avoiding type compatibility issues with the reconciler.
+
+const hostConfig = {
+  supportsMutation: true,
+  supportsPersistence: false,
+  supportsHydration: false,
+
+  createInstance(type: Type, props: Props, rootContainer: Container) {
+    return createHostInstance(type, props, rootContainer.ctx)
+  },
+
+  appendChild(parent: Instance, child: Instance) {
+    parent.appendChild(child)
+  },
+
+  removeChild(parent: Instance, child: Instance) {
+    parent.removeChild(child)
+    child.destroy()
+  },
+
+  insertBefore(parent: Instance, child: Instance, beforeChild: Instance) {
+    parent.insertBefore(child, beforeChild)
+  },
+
+  insertInContainerBefore(container: Container, child: Instance, beforeChild: Instance) {
+    if (container.root) {
+      container.root.insertBefore(child, beforeChild)
+    }
+  },
+
+  removeChildFromContainer(container: Container, child: Instance) {
+    if (container.root) {
+      container.root.removeChild(child)
+      child.destroy()
+    }
+  },
+
+  prepareForCommit() {
+    return null
+  },
+
+  resetAfterCommit(container: Container) {
+    container.ctx.requestRender()
+  },
+
+  getRootHostContext(): ReconcilerHostContext {
+    return { isInsideText: false }
+  },
+
+  getChildHostContext(parentHostContext: ReconcilerHostContext, type: Type): ReconcilerHostContext {
+    const isInsideText = type === "text" || parentHostContext.isInsideText
+    return { ...parentHostContext, isInsideText }
+  },
+
+  shouldSetTextContent() {
+    return false
+  },
+
+  createTextInstance(text: string, rootContainer: Container, hostContext: ReconcilerHostContext): TextInstance {
+    // Raw text nodes are only valid inside <text> elements
+    if (!hostContext.isInsideText) {
+      console.warn("Text nodes should be inside <text> elements")
+    }
+    return createTextInstance(text, rootContainer.ctx)
+  },
+
+  scheduleTimeout: setTimeout,
+  cancelTimeout: clearTimeout,
+  noTimeout: -1,
+
+  shouldAttemptEagerTransition() {
+    return false
+  },
+
+  finalizeInitialChildren(instance: Instance, _type: Type, props: Props) {
+    instance.updateProps(props)
+    return false
+  },
+
+  commitMount() {
+    // Could handle focus here
+  },
+
+  commitUpdate(
+		instance: Instance,
+		_updatePayload: unknown,
+		_type: Type,
+		_oldProps: Props,
+		newProps: Props | { pendingProps?: Props; memoizedProps?: Props },
+	) {
+		// Handle case where newProps might be a Fiber node (react-reconciler API varies)
+		const props =
+			(newProps as { pendingProps?: Props }).pendingProps ??
+			(newProps as { memoizedProps?: Props }).memoizedProps ??
+			(newProps as Props)
+		instance.updateProps(props)
+	},
+
+  commitTextUpdate(textInstance: TextInstance, _oldText: string, newText: string) {
+    textInstance.updateText(newText)
+  },
+
+  appendChildToContainer(container: Container, child: Instance) {
+    // The first child becomes the root
+    container.root = child
+    child.parent = null
+  },
+
+  appendInitialChild(parent: Instance, child: Instance) {
+    parent.appendChild(child)
+  },
+
+  hideInstance() {
+    // Could implement visibility
+  },
+
+  unhideInstance() {
+    // Could implement visibility
+  },
+
+  hideTextInstance() {},
+
+  unhideTextInstance() {},
+
+  clearContainer(container: Container) {
+    container.root = null
+  },
+
+  setCurrentUpdatePriority(newPriority: number) {
+    currentUpdatePriority = newPriority
+  },
+
+  getCurrentUpdatePriority: () => currentUpdatePriority,
+
+  resolveUpdatePriority() {
+    if (currentUpdatePriority !== NoEventPriority) {
+      return currentUpdatePriority
+    }
+    return DefaultEventPriority
+  },
+
+  maySuspendCommit() {
+    return false
+  },
+
+  NotPendingTransition: null,
+
+  HostTransitionContext: createContext(null),
+
+  resetFormInstance() {},
+
+  requestPostPaintCallback() {},
+
+  trackSchedulerEvent() {},
+
+  resolveEventType() {
+    return null
+  },
+
+  resolveEventTimeStamp() {
+    return -1.1
+  },
+
+  preloadInstance() {
+    return true
+  },
+
+  startSuspendingCommit() {},
+
+  suspendInstance() {},
+
+  waitForCommitToBeReady() {
+    return null
+  },
+
+  detachDeletedInstance(instance: Instance) {
+    if (!instance.parent) {
+      instance.destroy()
+    }
+  },
+
+  getPublicInstance(instance: Instance) {
+    return instance
+  },
+
+  preparePortalMount() {},
+
+  isPrimaryRenderer: true,
+
+  getInstanceFromNode() {
+    return null
+  },
+
+  beforeActiveInstanceBlur() {},
+
+  afterActiveInstanceBlur() {},
+
+  prepareScopeUpdate() {},
+
+  getInstanceFromScope() {
+    return null
+  },
+
+  prepareUpdate() {
+    return true
+  },
+}
+
+// Cast to any at the boundary - the config is internally typed but
+// react-reconciler's generic constraints are too strict for real-world usage
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const reconciler = Reconciler(hostConfig as any)
+
+// ============================================================================
+// Reconciler Helpers
+// ============================================================================
+// These helpers guard against API changes between react-reconciler versions
+
+type ReconcilerWithOptionalMethods = typeof reconciler & {
+	flushPassiveEffects?: () => void
+	flushSync?: <T>(fn?: () => T) => T
+	batchedUpdates?: <T>(fn: () => T) => T
+	discreteUpdates?: <T>(fn: () => T) => T
+}
+
+const r = reconciler as ReconcilerWithOptionalMethods
+
+export const flushPassiveEffects = r.flushPassiveEffects?.bind(r) ?? (() => {})
+export const flushSync = r.flushSync?.bind(r) ?? (<T>(fn?: () => T) => fn?.())
+export const batchedUpdates = r.batchedUpdates?.bind(r) ?? (<T>(fn: () => T) => fn())
+export const discreteUpdates = r.discreteUpdates?.bind(r) ?? (<T>(fn: () => T) => fn())