@effect-tui/react 0.9.3 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effect-tui/react",
-	"version": "0.9.3",
+	"version": "0.10.0",
 	"description": "React bindings for @effect-tui/core",
 	"type": "module",
 	"files": [
@@ -83,7 +83,7 @@
 		"prepublishOnly": "bun run typecheck && bun run build"
 	},
 	"dependencies": {
-		"@effect-tui/core": "^0.9.3",
+		"@effect-tui/core": "^0.10.0",
 		"@effect/platform": "^0.94.0",
 		"@effect/platform-bun": "^0.87.0",
 		"@effect/rpc": "^0.73.0",

package/src/dev/Toast.tsx

@@ -84,38 +84,48 @@ export function ToastProvider({ children }: { children: ReactNode }) {
 // Screenshot Toast Animation
 // ─────────────────────────────────────────────────────────────
 
-// Bright flash color for initial state
-const FLASH_COLOR = { r: 255, g: 255, b: 220, a: 1 }
-// Final green success color
-const SUCCESS_COLOR = { r: 30, g: 70, b: 40, a: 1 }
+// Flash: bright background, dark text
+const FLASH_BG = { r: 220, g: 220, b: 220, a: 1 }
+const FLASH_FG = { r: 40, g: 40, b: 40, a: 1 }
 
-function ScreenshotToast({ message }: { message: string }) {
+// Settled: dark gray background, light text
+const SETTLED_BG = { r: 50, g: 50, b: 55, a: 1 }
+const SETTLED_FG = { r: 200, g: 200, b: 200, a: 1 }
+
+function ScreenshotToast({ message, toastId }: { message: string; toastId: number }) {
 	// Emoji sequence: 📷 → 📸 → 📷 (camera → flash → camera)
 	const emoji = useSequence({
 		keyframes: ["📷", "📸", "📷"],
 		times: [0, 0.08, 0.2], // Flash at 8%, back at 20%
 		duration: 2500,
+		playKey: toastId, // Replay when a new toast is created
 	})
 
-	// Background: bright flash → fade to green
-	const [bg, setBg] = useColorSpring(FLASH_COLOR, { visualDuration: 1.2, bounce: 0 })
+	// Background: bright flash → fade to dark gray
+	// Pass MotionValue directly to box - hosts auto-subscribe!
+	const [bgMv, setBg] = useColorSpring(FLASH_BG, { visualDuration: 0.8, bounce: 0 })
+	// Foreground: dark → light (spring animated)
+	const [fgMv, setFg] = useColorSpring(FLASH_FG, { visualDuration: 0.8, bounce: 0 })
 
-	// Trigger fade after flash phase
+	// Reset and trigger animation when toastId changes (new screenshot)
 	useEffect(() => {
+		// Jump back to flash colors immediately (no animation)
+		bgMv.jump(FLASH_BG)
+		fgMv.jump(FLASH_FG)
+
+		// Then spring-animate to settled after flash phase
 		const timer = setTimeout(() => {
-			setBg(SUCCESS_COLOR)
-		}, 200) // Start fade at 200ms
+			setBg(SETTLED_BG)
+			setFg(SETTLED_FG)
+		}, 200)
 		return () => clearTimeout(timer)
-	}, [setBg])
-
-	const bgValue = bg.get()
-	const isFlash = emoji === "📸"
+	}, [toastId, bgMv, fgMv, setBg, setFg])
 
 	return (
 		<hstack>
 			<spacer />
-			<box bg={Colors.rgb(bgValue.r, bgValue.g, bgValue.b)} padding={{ x: 1 }}>
-				<text fg={isFlash ? Colors.rgb(40, 40, 20) : Colors.rgb(140, 230, 140)}>
+			<box bg={bgMv} padding={{ x: 1 }}>
+				<text fg={fgMv}>
 					{` ${emoji} ${message} `}
 				</text>
 			</box>
@@ -137,7 +147,7 @@ export function ToastContainer() {
 
 	// Special animated toast for screenshots
 	if (toast.type === "screenshot") {
-		return <ScreenshotToast message={toast.message} />
+		return <ScreenshotToast message={toast.message} toastId={toast.id} />
 	}
 
 	const style = TOAST_STYLES[toast.type]

package/src/dev.tsx

@@ -49,8 +49,8 @@ import type { RendererOptions, TuiRenderer } from "./renderer-types.js"
  * }
  * ```
  */
-export function hmr<A>(key: string): (self: A) => A {
-	return (self: A): A => {
+export function hmr(key: string): <A,>(self: A) => A {
+	return <A,>(self: A): A => {
 		return globalValue(Symbol.for(`hmr/${key}`), () => {
 			// Apply keepAlive if it's an atom (just sets keepAlive: true)
 			if (typeof self === "object" && self !== null && "keepAlive" in self) {
@@ -169,7 +169,7 @@ export function autoHmr<A>(self: A): A {
 	if (!location) {
 		// Fallback: use a hash of the stack trace
 		const fallbackKey = `unknown:${stack.slice(0, 100)}`
-		return hmr<A>(fallbackKey)(self)
+		return hmr(fallbackKey)(self)
 	}
 
 	const cacheKey = `${location.file}:${location.line}:${location.col}`
@@ -189,7 +189,7 @@ export function autoHmr<A>(self: A): A {
 		keyCache.set(cacheKey, key)
 	}
 
-	return hmr<A>(key)(self)
+	return hmr(key)(self)
 }
 
 export interface DevRenderOptions extends RendererOptions {

package/src/hooks/index.ts

@@ -6,3 +6,5 @@ export { usePaste } from "./use-paste.js"
 export { useQuit } from "./use-quit.js"
 export type { ScrollState, UseScrollOptions, UseScrollReturn } from "./use-scroll.js"
 export { useScroll } from "./use-scroll.js"
+export type { TimerStatus, TimerType, UseTimerConfig, UseTimerReturn } from "./use-timer.js"
+export { useTimer } from "./use-timer.js"

package/src/hooks/use-scroll.ts

@@ -289,7 +289,6 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 	const handleViewportSize = useCallback(
 		(width: number, height: number) => {
 			const newSize = axis === "vertical" ? height : width
-			console.log("[useScroll] viewport size reported", { width, height, axis, newSize })
 			// Sync ref immediately so scrollToVisible uses correct size
 			viewportSizeRef.current = newSize
 			setViewportSize(newSize)
@@ -365,13 +364,6 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 			const effectiveContentSize = totalSize ?? contentSize
 			const isAbove = itemStart < currentOffset + padding
 			const isBelow = itemEnd > currentOffset + currentViewportSize - padding
-			console.log("[useScroll] scrollToVisible", {
-				currentViewportSize,
-				itemEnd,
-				currentOffset,
-				isAbove,
-				isBelow,
-			})
 
 			// If item is above viewport, scroll up to show it
 			if (isAbove) {

package/src/hooks/use-timer.ts

@@ -0,0 +1,155 @@
+// use-timer.ts — Hook for countdown/stopwatch timers
+
+import { useCallback, useEffect, useRef, useState } from "react"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type TimerStatus = "RUNNING" | "PAUSED" | "STOPPED"
+export type TimerType = "INCREMENTAL" | "DECREMENTAL"
+
+export interface UseTimerConfig {
+	/** Starting time value in seconds (required) */
+	initialTime: number
+	/** Timer direction: 'INCREMENTAL' (stopwatch) or 'DECREMENTAL' (countdown). Default: DECREMENTAL */
+	timerType?: TimerType
+	/** When to stop. Default: 0 for decremental, null (never) for incremental */
+	endTime?: number | null
+	/** Auto-start on mount. Default: false */
+	autostart?: boolean
+	/** Milliseconds between ticks. Default: 1000 */
+	interval?: number
+	/** Called when timer reaches endTime */
+	onTimeOver?: () => void
+	/** Called on each tick with current time */
+	onTimeUpdate?: (time: number) => void
+}
+
+export interface UseTimerReturn {
+	/** Current time value in seconds */
+	time: number
+	/** Start or resume the timer */
+	start: () => void
+	/** Pause the timer */
+	pause: () => void
+	/** Reset timer to initialTime and stop */
+	reset: () => void
+	/** Current timer status */
+	status: TimerStatus
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Hook for countdown or stopwatch timers.
+ *
+ * @example Countdown timer (rest between sets)
+ * ```tsx
+ * const { time, start, status } = useTimer({
+ *   initialTime: 90,
+ *   timerType: 'DECREMENTAL',
+ *   onTimeOver: () => playSound()
+ * })
+ *
+ * return <text>Rest: {time}s</text>
+ * ```
+ *
+ * @example Stopwatch (session duration)
+ * ```tsx
+ * const { time, start, pause } = useTimer({
+ *   initialTime: 0,
+ *   timerType: 'INCREMENTAL',
+ *   autostart: true
+ * })
+ *
+ * return <text>Duration: {Math.floor(time / 60)}:{(time % 60).toString().padStart(2, '0')}</text>
+ * ```
+ */
+export function useTimer(config: UseTimerConfig): UseTimerReturn {
+	const {
+		initialTime,
+		timerType = "DECREMENTAL",
+		endTime: endTimeConfig,
+		autostart = false,
+		interval = 1000,
+		onTimeOver,
+		onTimeUpdate,
+	} = config
+
+	// Determine endTime based on timer type if not explicitly set
+	const endTime = endTimeConfig ?? (timerType === "DECREMENTAL" ? 0 : null)
+
+	// State
+	const [time, setTime] = useState(initialTime)
+	const [status, setStatus] = useState<TimerStatus>(autostart ? "RUNNING" : "STOPPED")
+
+	// Refs for callbacks to avoid stale closures
+	const onTimeOverRef = useRef(onTimeOver)
+	const onTimeUpdateRef = useRef(onTimeUpdate)
+	onTimeOverRef.current = onTimeOver
+	onTimeUpdateRef.current = onTimeUpdate
+
+	// Control functions
+	const start = useCallback(() => {
+		setStatus("RUNNING")
+	}, [])
+
+	const pause = useCallback(() => {
+		setStatus((prev) => (prev === "RUNNING" ? "PAUSED" : prev))
+	}, [])
+
+	const reset = useCallback(() => {
+		setTime(initialTime)
+		setStatus("STOPPED")
+	}, [initialTime])
+
+	// Timer effect
+	useEffect(() => {
+		if (status !== "RUNNING") return
+
+		const tick = () => {
+			setTime((prevTime) => {
+				const step = timerType === "DECREMENTAL" ? -1 : 1
+				const nextTime = prevTime + step
+
+				// Check if we've reached the end
+				if (endTime !== null) {
+					const reachedEnd =
+						timerType === "DECREMENTAL" ? nextTime <= endTime : nextTime >= endTime
+
+					if (reachedEnd) {
+						// Schedule callback and status change for next tick to avoid state updates during render
+						setTimeout(() => {
+							setStatus("STOPPED")
+							onTimeOverRef.current?.()
+						}, 0)
+						return endTime
+					}
+				}
+
+				// Call onTimeUpdate
+				onTimeUpdateRef.current?.(nextTime)
+				return nextTime
+			})
+		}
+
+		const intervalId = setInterval(tick, interval)
+		return () => clearInterval(intervalId)
+	}, [status, timerType, endTime, interval])
+
+	// Reset time when initialTime changes (useful for restarting with different duration)
+	useEffect(() => {
+		setTime(initialTime)
+	}, [initialTime])
+
+	return {
+		time,
+		start,
+		pause,
+		reset,
+		status,
+	}
+}

package/src/hosts/base.ts

@@ -1,6 +1,42 @@
 import type { CellBuffer, Color, Palette } from "@effect-tui/core"
+import { COLOR_MOTION_VALUE_BRAND, MOTION_VALUE_BRAND } from "../motion/brands.js"
+import type { ColorMotionValue } from "../motion/color-motion-value.js"
+import type { MotionValue } from "../motion/motion-value.js"
 import type { CommonProps, HostContext, HostInstance, Rect, Size } from "../reconciler/types.js"
 
+/**
+ * Check if a value is a MotionValue.
+ * Uses brand Symbol for safety, with duck-typing fallback for compatibility.
+ */
+function isMotionValue(value: unknown): value is MotionValue<unknown> {
+	if (typeof value !== "object" || value === null) return false
+	// Prefer brand detection (safe, fast)
+	if (MOTION_VALUE_BRAND in value) return true
+	// Duck-typing fallback for compatibility
+	return (
+		"get" in value &&
+		typeof (value as MotionValue<unknown>).get === "function" &&
+		"on" in value &&
+		typeof (value as MotionValue<unknown>).on === "function"
+	)
+}
+
+/**
+ * Check if a value is a ColorMotionValue.
+ * Uses brand Symbol for safety, with duck-typing fallback for compatibility.
+ */
+function isColorMotionValue(value: unknown): value is ColorMotionValue {
+	if (typeof value !== "object" || value === null) return false
+	// Prefer brand detection (safe, fast)
+	if (COLOR_MOTION_VALUE_BRAND in value) return true
+	// Duck-typing fallback for compatibility
+	return (
+		isMotionValue(value) &&
+		"_subscribeChannels" in value &&
+		typeof (value as { _subscribeChannels: unknown })._subscribeChannels === "function"
+	)
+}
+
 /** Host that may have a background color (e.g., BoxHost) */
 export interface HostWithBg extends HostInstance {
 	bg?: Color
@@ -54,6 +90,13 @@ export abstract class BaseHost implements HostInstance {
 
 	protected ctx: HostContext
 
+	// ─────────────────────────────────────────────────────────────
+	// MotionValue subscriptions - for spring-animated props
+	// Lazy-initialized to avoid overhead for non-animated hosts
+	// Tracks both value identity and unsub function to avoid churn
+	// ─────────────────────────────────────────────────────────────
+	private _springSubscriptions?: Map<string, { value: unknown; unsub: () => void }>
+
 	constructor(type: string, _props: CommonProps, ctx: HostContext) {
 		this.id = `${type}-${idCounter++}`
 		this.type = type
@@ -63,6 +106,82 @@ export abstract class BaseHost implements HostInstance {
 		// which would overwrite any values set here.
 	}
 
+	/**
+	 * Resolve a prop that may be a MotionValue/ColorMotionValue.
+	 * If it's a spring, subscribes to changes and returns current value.
+	 * Automatically cleans up old subscriptions when prop changes.
+	 * Avoids subscription churn by tracking value identity.
+	 *
+	 * @param key - Unique key for this prop (used for subscription tracking)
+	 * @param value - The prop value (may be a MotionValue or regular value)
+	 * @param onUpdate - Called with new value when spring animates (update the host property!)
+	 * @returns The resolved value (current spring value or the value itself)
+	 */
+	protected resolveSpringProp<T>(
+		key: string,
+		value: T | MotionValue<T> | ColorMotionValue,
+		onUpdate?: (value: T) => void,
+	): T | undefined {
+		const existing = this._springSubscriptions?.get(key)
+
+		// Not a motion value - clean up any existing subscription and return as-is
+		if (!isMotionValue(value)) {
+			if (existing) {
+				existing.unsub()
+				this._springSubscriptions!.delete(key)
+			}
+			return value as T | undefined
+		}
+
+		// Same MotionValue as before - no need to resubscribe, just return current value
+		if (existing && existing.value === value) {
+			return (value as MotionValue<T>).get()
+		}
+
+		// Different MotionValue (or first time) - clean up old and subscribe to new
+		if (existing) {
+			existing.unsub()
+			this._springSubscriptions!.delete(key)
+		}
+
+		// Lazy-init the subscriptions map only when we actually have a spring
+		if (!this._springSubscriptions) {
+			this._springSubscriptions = new Map()
+		}
+
+		// ColorMotionValue - subscribe to all channels
+		if (isColorMotionValue(value)) {
+			const mv = value
+			const unsub = mv._subscribeChannels(() => {
+				onUpdate?.(mv.get() as T) // Update the host's property with new value!
+				this.ctx.requestRender()
+			})
+			this._springSubscriptions.set(key, { value: mv, unsub })
+			return mv.get() as T
+		}
+
+		// Regular MotionValue - subscribe to changes
+		const mv = value as MotionValue<T>
+		const unsub = mv.on("change", (newValue: T) => {
+			onUpdate?.(newValue) // Update the host's property with new value!
+			this.ctx.requestRender()
+		})
+		this._springSubscriptions.set(key, { value: mv, unsub })
+		return mv.get()
+	}
+
+	/**
+	 * Clean up all spring subscriptions.
+	 * Called automatically in destroy().
+	 */
+	protected clearSpringSubscriptions(): void {
+		if (!this._springSubscriptions) return
+		for (const { unsub } of this._springSubscriptions.values()) {
+			unsub()
+		}
+		this._springSubscriptions.clear()
+	}
+
 	abstract measure(maxW: number, maxH: number): Size
 	abstract render(buffer: CellBuffer, palette: Palette): void
 
@@ -187,6 +306,7 @@ export abstract class BaseHost implements HostInstance {
 	}
 
 	destroy(): void {
+		this.clearSpringSubscriptions()
 		// Override in subclasses if cleanup needed
 	}
 

package/src/hosts/box.ts

@@ -1,5 +1,6 @@
 import type { CellBuffer, Color, Palette } from "@effect-tui/core"
 import { Colors } from "@effect-tui/core"
+import type { ColorMotionValue } from "../motion/color-motion-value.js"
 import type { CommonProps, HostContext, Rect, Size } from "../reconciler/types.js"
 import {
 	type BorderKind,
@@ -15,15 +16,18 @@ import { SingleChildHost } from "./single-child.js"
 
 export type { BorderKind }
 
+/** Color prop that can be a static Color or a spring-animated ColorMotionValue */
+export type ColorProp = Color | ColorMotionValue
+
 export interface BoxProps extends CommonProps {
 	padding?: PaddingInput
 	border?: BorderKind
-	borderColor?: Color
-	bg?: Color
+	borderColor?: ColorProp
+	bg?: ColorProp
 	/** Title displayed on the top border */
 	title?: string
 	/** Title text color (defaults to borderColor) */
-	titleColor?: Color
+	titleColor?: ColorProp
 }
 
 export class BoxHost extends SingleChildHost {
@@ -137,9 +141,16 @@ export class BoxHost extends SingleChildHost {
 		super.updateProps(props)
 		this.padding = resolvePadding(props.padding as BoxProps["padding"])
 		this.border = (props.border as BorderKind | undefined) ?? "none"
-		this.borderColor = props.borderColor as Color | undefined
-		this.bg = props.bg as Color | undefined
+		// Color props support MotionValue/ColorMotionValue - auto-subscribe and animate
+		this.borderColor = this.resolveSpringProp("borderColor", props.borderColor, (v) => {
+			this.borderColor = v as Color
+		}) as Color | undefined
+		this.bg = this.resolveSpringProp("bg", props.bg, (v) => {
+			this.bg = v as Color
+		}) as Color | undefined
 		this.title = props.title as string | undefined
-		this.titleColor = props.titleColor as Color | undefined
+		this.titleColor = this.resolveSpringProp("titleColor", props.titleColor, (v) => {
+			this.titleColor = v as Color
+		}) as Color | undefined
 	}
 }

package/src/hosts/scroll.ts

@@ -52,8 +52,6 @@ export class ScrollHost extends SingleChildHost {
 	private contentWidth = 0
 	private contentHeight = 0
 	// Track last reported sizes to avoid redundant callbacks
-	private lastViewportW = 0
-	private lastViewportH = 0
 	private lastReportedContentW = 0
 	private lastReportedContentH = 0
 	private lastRectX = -1
@@ -103,7 +101,6 @@ export class ScrollHost extends SingleChildHost {
 
 	override layout(rect: Rect): void {
 		super.layout(rect)
-		console.log("[ScrollHost] layout rect", { x: rect.x, y: rect.y, w: rect.w, h: rect.h })
 
 		// Report content size if changed (deferred from measure() to keep it pure)
 		if (this.contentWidth !== this.lastReportedContentW || this.contentHeight !== this.lastReportedContentH) {
@@ -113,10 +110,9 @@ export class ScrollHost extends SingleChildHost {
 		}
 
 		// Report viewport size if changed (for useScroll hook)
-		if (rect.w !== this.lastViewportW || rect.h !== this.lastViewportH) {
-			this.lastViewportW = rect.w
-			this.lastViewportH = rect.h
-			this.onViewportSize?.(rect.w, rect.h)
+		// Always report on every layout - React may have recreated the hook with stale refs
+		if (this.onViewportSize) {
+			this.onViewportSize(rect.w, rect.h)
 		}
 
 		// Report rect if position changed (for hit testing)

package/src/hosts/text.ts

@@ -1,11 +1,15 @@
 import { type CellBuffer, type Color, displayWidth, type Palette } from "@effect-tui/core"
+import type { ColorMotionValue } from "../motion/color-motion-value.js"
 import type { CommonProps, HostContext, Rect, Size } from "../reconciler/types.js"
 import { resolveInheritedBgStyle, styleIdFromProps } from "../utils/index.js"
 import { BaseHost, getInheritedBg } from "./base.js"
 
+/** Color prop that can be a static Color or a spring-animated ColorMotionValue */
+export type ColorProp = Color | ColorMotionValue
+
 export interface TextProps extends CommonProps {
-	fg?: Color
-	bg?: Color
+	fg?: ColorProp
+	bg?: ColorProp
 	bold?: boolean
 	italic?: boolean
 	underline?: boolean
@@ -354,9 +358,13 @@ export class TextHost extends BaseHost {
 
 	override updateProps(props: Record<string, unknown>): void {
 		super.updateProps(props)
-		// Always assign; props may be undefined when attribute is removed
-		this.fg = props.fg as Color | undefined
-		this.bg = props.bg as Color | undefined
+		// Color props support MotionValue/ColorMotionValue - auto-subscribe and animate
+		this.fg = this.resolveSpringProp("fg", props.fg, (v) => {
+			this.fg = v as Color
+		}) as Color | undefined
+		this.bg = this.resolveSpringProp("bg", props.bg, (v) => {
+			this.bg = v as Color
+		}) as Color | undefined
 		this.bold = Boolean(props.bold)
 		this.italic = Boolean(props.italic)
 		this.underline = Boolean(props.underline)

package/src/motion/brands.ts

@@ -0,0 +1,10 @@
+/**
+ * Brand Symbols for MotionValue type detection.
+ * Separated to avoid circular dependency issues.
+ */
+
+/** Brand Symbol for safer MotionValue detection */
+export const MOTION_VALUE_BRAND = Symbol.for("effect-tui/MotionValue")
+
+/** Brand Symbol for safer ColorMotionValue detection */
+export const COLOR_MOTION_VALUE_BRAND = Symbol.for("effect-tui/ColorMotionValue")

package/src/motion/color-motion-value.ts

@@ -2,16 +2,22 @@
  * ColorMotionValue - animates RGBA colors using 4 internal numeric springs.
  */
 
+import { COLOR_MOTION_VALUE_BRAND } from "./brands.js"
 import { type ColorInput, parseColor, type RGBA } from "./color.js"
 import { EventEmitter } from "./event-emitter.js"
 import { MotionValue } from "./motion-value.js"
 import type { SpringOptions } from "./types.js"
 
+export { COLOR_MOTION_VALUE_BRAND } from "./brands.js"
+
 /**
  * ColorMotionValue animates RGBA colors using 4 internal numeric springs.
  * Each channel (r, g, b, a) is animated independently with the same spring config.
  */
 export class ColorMotionValue extends EventEmitter<RGBA> {
+	/** @internal Brand for safe type detection */
+	readonly [COLOR_MOTION_VALUE_BRAND] = true
+
 	private rMv: MotionValue<number>
 	private gMv: MotionValue<number>
 	private bMv: MotionValue<number>

package/src/motion/hooks.ts

@@ -2,7 +2,7 @@
  * React hooks for spring animations.
  */
 
-import { useCallback, useEffect, useRef } from "react"
+import { useCallback, useEffect, useRef, useState } from "react"
 import { useRenderer } from "../renderer.js"
 import type { ColorInput } from "./color.js"
 import { ColorMotionValue } from "./color-motion-value.js"
@@ -211,13 +211,18 @@ export function useColorMotionValue(initial: ColorInput): ColorMotionValue {
 /**
  * Create a spring-animated color. Accepts hex, rgb(), hsl(), or {r,g,b} object.
  *
+ * Returns a MotionValue - best for <canvas draw={...}> where you read in callbacks.
+ * For JSX props, use useColorSpringState instead.
+ *
  * @example
  * const [colorMv, setColor] = useColorSpring("#ff0000", { visualDuration: 0.5 })
  * setColor("#00ff00")  // Spring to green
- * setColor("hsl(240, 100%, 50%)")  // Spring to blue
  *
- * // In draw callback
- * const { r, g, b } = colorMv.get()
+ * // In canvas draw callback
+ * <canvas draw={(ctx) => {
+ *   const { r, g, b } = colorMv.get()
+ *   ctx.fill(0, 0, 10, 5, "█", { fg: Colors.rgb(r, g, b) })
+ * }} />
  */
 export function useColorSpring(
 	initial: ColorInput,
@@ -243,3 +248,44 @@ export function useColorSpring(
 
 	return [mv, set]
 }
+
+/**
+ * Like useColorSpring, but returns React state that updates during animation.
+ * Use this when you need spring values in JSX props.
+ *
+ * For <canvas draw={...}> callbacks, use useColorSpring instead (better perf).
+ *
+ * @example
+ * const [color, setColor] = useColorSpringState("#ff0000", { visualDuration: 0.5 })
+ * setColor("#00ff00")  // Spring to green
+ *
+ * // In JSX - React re-renders as the spring animates
+ * <box bg={Colors.rgb(color.r, color.g, color.b)}>
+ *   <text>Hello</text>
+ * </box>
+ */
+export function useColorSpringState(
+	initial: ColorInput,
+	options?: SpringOptions,
+): [{ r: number; g: number; b: number; a: number }, (color: ColorInput) => void] {
+	const mv = useColorMotionValue(initial)
+	const [value, setValue] = useState(() => mv.get())
+	const optionsRef = useRef(options)
+	optionsRef.current = options
+
+	// Subscribe to spring changes and update React state
+	useEffect(() => {
+		return mv._subscribeChannels(() => {
+			setValue(mv.get())
+		})
+	}, [mv])
+
+	const set = useCallback(
+		(color: ColorInput) => {
+			mv.set(color, optionsRef.current)
+		},
+		[mv],
+	)
+
+	return [value, set]
+}