@number10/jsx-core 5.0.0

package/dist/animation/spring-physics.js

@@ -0,0 +1,94 @@
+const DEFAULT_SPRING_CONFIG = {
+  tension: 170,
+  friction: 26,
+  mass: 1,
+  restVelocity: 0.01,
+  restDelta: 0.01,
+  clamp: false
+};
+const SPRING_PRESETS = {
+  /** Gentle, but still responsive animation */
+  gentle: { tension: 350, friction: 24, restVelocity: 0.5, restDelta: 0.1 },
+  /** Moderate, balanced animation (default) */
+  default: { tension: 600, friction: 40, restVelocity: 0.5, restDelta: 0.1 },
+  /** Bouncy, playful animation tuned for quick UI feedback */
+  wobbly: { tension: 900, friction: 35, restVelocity: 0.5, restDelta: 0.1 },
+  /** Very fast, snappy response for press/pulse-style interactions */
+  stiff: { tension: 1800, friction: 60, restVelocity: 0.5, restDelta: 0.1 },
+  /** Slow, deliberate animation */
+  slow: { tension: 350, friction: 48, restVelocity: 0.5, restDelta: 0.1 },
+  /** Nearly instant transition */
+  instant: { tension: 2500, friction: 90, restVelocity: 1, restDelta: 0.02, clamp: true }
+};
+class SpringPhysics {
+  config;
+  /**
+   * Creates a new spring physics engine
+   * @param config - Spring configuration
+   */
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_SPRING_CONFIG, ...config };
+  }
+  /**
+   * Updates spring configuration
+   * @param config - Partial config to merge with current
+   */
+  updateConfig(config) {
+    this.config = { ...this.config, ...config };
+  }
+  /**
+   * Performs one physics step
+   * Uses semi-implicit Euler integration for stability
+   * @param state - Current spring state
+   * @param target - Target value
+   * @param deltaTime - Time delta in seconds
+   * @returns New spring state
+   */
+  step(state, target, deltaTime) {
+    const { tension, friction, mass, clamp } = this.config;
+    const springForce = -tension * (state.value - target);
+    const dampingForce = -friction * state.velocity;
+    const acceleration = (springForce + dampingForce) / mass;
+    const newVelocity = state.velocity + acceleration * deltaTime;
+    let newValue = state.value + newVelocity * deltaTime;
+    if (clamp) {
+      const min = Math.min(state.value, target);
+      const max = Math.max(state.value, target);
+      newValue = Math.max(min, Math.min(max, newValue));
+    }
+    return {
+      value: newValue,
+      velocity: newVelocity
+    };
+  }
+  /**
+   * Checks if spring has reached rest state
+   * @param state - Current spring state
+   * @param target - Target value
+   * @returns True if spring is at rest
+   */
+  isAtRest(state, target) {
+    const { restVelocity, restDelta } = this.config;
+    const isVelocitySmall = Math.abs(state.velocity) <= restVelocity;
+    const isDisplacementSmall = Math.abs(state.value - target) <= restDelta;
+    return isVelocitySmall && isDisplacementSmall;
+  }
+  /**
+   * Snaps spring to target if at rest
+   * @param state - Current spring state
+   * @param target - Target value
+   * @returns Adjusted state (snapped if at rest)
+   */
+  snapIfAtRest(state, target) {
+    if (this.isAtRest(state, target)) {
+      return { value: target, velocity: 0 };
+    }
+    return state;
+  }
+}
+export {
+  DEFAULT_SPRING_CONFIG,
+  SPRING_PRESETS,
+  SpringPhysics
+};
+//# sourceMappingURL=spring-physics.js.map

package/dist/animation/spring-physics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spring-physics.js","sources":["../../src/animation/spring-physics.ts"],"sourcesContent":["/**\n * Spring physics engine for smooth, natural animations\n * Based on spring-damper system with configurable tension, friction, and mass\n *\n * @migration(audit:surface-access) Phase 7 — moved to @number10/jsx-core ✅\n */\n\n/**\n * Configuration for spring physics behavior\n */\nexport interface SpringConfig {\n  /** Spring stiffness (higher = faster, snappier). Default: 170 */\n  tension?: number\n  /** Damping force (higher = less oscillation). Default: 26 */\n  friction?: number\n  /** Mass of the animated object (higher = slower). Default: 1 */\n  mass?: number\n  /** Velocity threshold below which animation stops. Default: 0.01 */\n  restVelocity?: number\n  /** Distance threshold below which animation stops. Default: 0.01 */\n  restDelta?: number\n  /** Clamp values to prevent overshoot. Default: false */\n  clamp?: boolean\n  /**\n   * Called once when the spring starts moving from rest.\n   * Fires BEFORE the first physics step.\n   */\n  onStart?: (() => void) | undefined\n  /**\n   * Called on every frame with the current spring value.\n   * Useful for syncing non-signal state.\n   */\n  onUpdate?: ((value: number) => void) | undefined\n}\n\n/**\n * Spring physics state\n */\nexport interface SpringState {\n  /** Current value */\n  value: number\n  /** Current velocity */\n  velocity: number\n}\n\n/**\n * Default spring configuration (similar to react-spring)\n */\nexport const DEFAULT_SPRING_CONFIG: Required<Omit<SpringConfig, 'onStart' | 'onUpdate'>> = {\n  tension: 170,\n  friction: 26,\n  mass: 1,\n  restVelocity: 0.01,\n  restDelta: 0.01,\n  clamp: false,\n}\n\n/**\n * Preset spring configurations for common use cases\n * Note: clamp prevents overshoot but can make animations feel less natural\n * For UI animations, consider enabling clamp to prevent visual artifacts\n */\nexport const SPRING_PRESETS = {\n  /** Gentle, but still responsive animation */\n  gentle: { tension: 350, friction: 24, restVelocity: 0.5, restDelta: 0.1 },\n  /** Moderate, balanced animation (default) */\n  default: { tension: 600, friction: 40, restVelocity: 0.5, restDelta: 0.1 },\n  /** Bouncy, playful animation tuned for quick UI feedback */\n  wobbly: { tension: 900, friction: 35, restVelocity: 0.5, restDelta: 0.1 },\n  /** Very fast, snappy response for press/pulse-style interactions */\n  stiff: { tension: 1800, friction: 60, restVelocity: 0.5, restDelta: 0.1 },\n  /** Slow, deliberate animation */\n  slow: { tension: 350, friction: 48, restVelocity: 0.5, restDelta: 0.1 },\n  /** Nearly instant transition */\n  instant: { tension: 2500, friction: 90, restVelocity: 1, restDelta: 0.02, clamp: true },\n} as const\n\n/**\n * Type for animation preset keys\n */\nexport type AnimationPreset = keyof typeof SPRING_PRESETS\n/**\n * Type for animation configuration (preset name or custom config)\n */\nexport type AnimationConfig = AnimationPreset | SpringConfig\n\n/**\n * Spring physics engine\n * Implements spring-damper physics for smooth, natural animations\n */\nexport class SpringPhysics {\n  private config: Required<Omit<SpringConfig, 'onStart' | 'onUpdate'>> &\n    Pick<SpringConfig, 'onStart' | 'onUpdate'>\n\n  /**\n   * Creates a new spring physics engine\n   * @param config - Spring configuration\n   */\n  constructor(config: SpringConfig = {}) {\n    this.config = { ...DEFAULT_SPRING_CONFIG, ...config } as typeof this.config\n  }\n\n  /**\n   * Updates spring configuration\n   * @param config - Partial config to merge with current\n   */\n  updateConfig(config: Partial<SpringConfig>): void {\n    this.config = { ...this.config, ...config } as typeof this.config\n  }\n\n  /**\n   * Performs one physics step\n   * Uses semi-implicit Euler integration for stability\n   * @param state - Current spring state\n   * @param target - Target value\n   * @param deltaTime - Time delta in seconds\n   * @returns New spring state\n   */\n  step(state: SpringState, target: number, deltaTime: number): SpringState {\n    const { tension, friction, mass, clamp } = this.config\n\n    // Calculate spring force (Hooke's law)\n    const springForce = -tension * (state.value - target)\n\n    // Calculate damping force\n    const dampingForce = -friction * state.velocity\n\n    // Calculate acceleration (F = ma → a = F/m)\n    const acceleration = (springForce + dampingForce) / mass\n\n    // Update velocity (semi-implicit Euler)\n    const newVelocity = state.velocity + acceleration * deltaTime\n\n    // Update position\n    let newValue = state.value + newVelocity * deltaTime\n\n    // Clamp if enabled\n    if (clamp) {\n      const min = Math.min(state.value, target)\n      const max = Math.max(state.value, target)\n      newValue = Math.max(min, Math.min(max, newValue))\n    }\n\n    return {\n      value: newValue,\n      velocity: newVelocity,\n    }\n  }\n\n  /**\n   * Checks if spring has reached rest state\n   * @param state - Current spring state\n   * @param target - Target value\n   * @returns True if spring is at rest\n   */\n  isAtRest(state: SpringState, target: number): boolean {\n    const { restVelocity, restDelta } = this.config\n    const isVelocitySmall = Math.abs(state.velocity) <= restVelocity\n    const isDisplacementSmall = Math.abs(state.value - target) <= restDelta\n    return isVelocitySmall && isDisplacementSmall\n  }\n\n  /**\n   * Snaps spring to target if at rest\n   * @param state - Current spring state\n   * @param target - Target value\n   * @returns Adjusted state (snapped if at rest)\n   */\n  snapIfAtRest(state: SpringState, target: number): SpringState {\n    if (this.isAtRest(state, target)) {\n      return { value: target, velocity: 0 }\n    }\n    return state\n  }\n}\n"],"names":[],"mappings":"AAgDO,MAAM,wBAA8E;AAAA,EACzF,SAAS;AAAA,EACT,UAAU;AAAA,EACV,MAAM;AAAA,EACN,cAAc;AAAA,EACd,WAAW;AAAA,EACX,OAAO;AACT;AAOO,MAAM,iBAAiB;AAAA;AAAA,EAE5B,QAAQ,EAAE,SAAS,KAAK,UAAU,IAAI,cAAc,KAAK,WAAW,IAAA;AAAA;AAAA,EAEpE,SAAS,EAAE,SAAS,KAAK,UAAU,IAAI,cAAc,KAAK,WAAW,IAAA;AAAA;AAAA,EAErE,QAAQ,EAAE,SAAS,KAAK,UAAU,IAAI,cAAc,KAAK,WAAW,IAAA;AAAA;AAAA,EAEpE,OAAO,EAAE,SAAS,MAAM,UAAU,IAAI,cAAc,KAAK,WAAW,IAAA;AAAA;AAAA,EAEpE,MAAM,EAAE,SAAS,KAAK,UAAU,IAAI,cAAc,KAAK,WAAW,IAAA;AAAA;AAAA,EAElE,SAAS,EAAE,SAAS,MAAM,UAAU,IAAI,cAAc,GAAG,WAAW,MAAM,OAAO,KAAA;AACnF;AAeO,MAAM,cAAc;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA;AAAA,EAOR,YAAY,SAAuB,IAAI;AACrC,SAAK,SAAS,EAAE,GAAG,uBAAuB,GAAG,OAAA;AAAA,EAC/C;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,aAAa,QAAqC;AAChD,SAAK,SAAS,EAAE,GAAG,KAAK,QAAQ,GAAG,OAAA;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,KAAK,OAAoB,QAAgB,WAAgC;AACvE,UAAM,EAAE,SAAS,UAAU,MAAM,MAAA,IAAU,KAAK;AAGhD,UAAM,cAAc,CAAC,WAAW,MAAM,QAAQ;AAG9C,UAAM,eAAe,CAAC,WAAW,MAAM;AAGvC,UAAM,gBAAgB,cAAc,gBAAgB;AAGpD,UAAM,cAAc,MAAM,WAAW,eAAe;AAGpD,QAAI,WAAW,MAAM,QAAQ,cAAc;AAG3C,QAAI,OAAO;AACT,YAAM,MAAM,KAAK,IAAI,MAAM,OAAO,MAAM;AACxC,YAAM,MAAM,KAAK,IAAI,MAAM,OAAO,MAAM;AACxC,iBAAW,KAAK,IAAI,KAAK,KAAK,IAAI,KAAK,QAAQ,CAAC;AAAA,IAClD;AAEA,WAAO;AAAA,MACL,OAAO;AAAA,MACP,UAAU;AAAA,IAAA;AAAA,EAEd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,SAAS,OAAoB,QAAyB;AACpD,UAAM,EAAE,cAAc,UAAA,IAAc,KAAK;AACzC,UAAM,kBAAkB,KAAK,IAAI,MAAM,QAAQ,KAAK;AACpD,UAAM,sBAAsB,KAAK,IAAI,MAAM,QAAQ,MAAM,KAAK;AAC9D,WAAO,mBAAmB;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,aAAa,OAAoB,QAA6B;AAC5D,QAAI,KAAK,SAAS,OAAO,MAAM,GAAG;AAChC,aAAO,EAAE,OAAO,QAAQ,UAAU,EAAA;AAAA,IACpC;AACA,WAAO;AAAA,EACT;AACF;"}

package/dist/animation/tween.cjs

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const easing = require("./easing.cjs");
+function createTween(initial, config, scheduler) {
+  const target = { ...initial };
+  const startValues = { ...initial };
+  const keys = Object.keys(config.to);
+  const ease = config.ease ?? easing.Easing.quadOut;
+  const startTime = performance.now();
+  let frameHandle = null;
+  let completed = false;
+  if (config.duration <= 0) {
+    for (const key of keys) {
+      const toVal = config.to[key];
+      if (toVal !== void 0) {
+        target[key] = toVal;
+      }
+    }
+    config.onUpdate?.(target);
+    config.onComplete?.();
+    return {
+      target,
+      stop: () => {
+      },
+      isActive: false
+    };
+  }
+  frameHandle = scheduler.onFrame((_dt) => {
+    if (completed) return;
+    const elapsed = performance.now() - startTime;
+    const rawProgress = Math.min(elapsed / config.duration, 1);
+    const easedProgress = ease(rawProgress);
+    for (const key of keys) {
+      const toVal = config.to[key];
+      if (toVal !== void 0) {
+        const fromVal = startValues[key];
+        target[key] = fromVal + (toVal - fromVal) * easedProgress;
+      }
+    }
+    try {
+      config.onUpdate?.(target);
+    } catch {
+    }
+    if (rawProgress >= 1) {
+      completed = true;
+      frameHandle?.cancel();
+      try {
+        config.onComplete?.();
+      } catch {
+      }
+    }
+  });
+  return {
+    target,
+    stop: () => {
+      if (completed) return;
+      completed = true;
+      frameHandle?.cancel();
+    },
+    get isActive() {
+      return !completed;
+    }
+  };
+}
+exports.Easing = easing.Easing;
+exports.createTween = createTween;
+//# sourceMappingURL=tween.cjs.map

package/dist/animation/tween.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tween.cjs","sources":["../../src/animation/tween.ts"],"sourcesContent":["/**\n * Animation utilities — renderer-neutral tween engine.\n *\n * Provides time-based value interpolation with configurable easing.\n * Runs on HostScheduler.onFrame() — no renderer-specific tween system needed.\n *\n * This is the duration+easing counterpart to the spring-physics animation\n * (useSpring). Use createTween when you need exact duration control;\n * use useSpring for continuous physics-based motion.\n *\n * @migration(audit:surface-access) Phase 7 — new Core capability.\n *   Replaces scene.tweens.add() in portable components.\n */\n\nimport type { HostCancelHandle, HostScheduler } from '../host-adapter'\nimport { Easing, type EasingFn } from './easing'\n\n// Re-export for backward compatibility — all easing functions now live in easing.ts\nexport { Easing, type EasingFn } from './easing'\n\n// ---------------------------------------------------------------------------\n// Tween types\n// ---------------------------------------------------------------------------\n\n/**\n * Configuration for a tween animation.\n * @typeParam T - Record of numeric properties to animate\n */\nexport interface TweenConfig<T extends Record<string, number>> {\n  /** Target values (partial — only specified keys are animated) */\n  to: Partial<T>\n  /** Duration in milliseconds */\n  duration: number\n  /** Easing function (default: quadOut) */\n  ease?: EasingFn | undefined\n  /** Called every frame with the current interpolated target */\n  onUpdate?: ((target: T) => void) | undefined\n  /** Called when the tween completes naturally (not on stop()) */\n  onComplete?: (() => void) | undefined\n}\n\n/**\n * Handle to an active tween animation.\n */\nexport interface TweenHandle<T extends Record<string, number> = Record<string, number>> {\n  /** Current interpolated state (mutated each frame) */\n  readonly target: Readonly<T>\n  /** Stop the animation immediately. onComplete is NOT called. */\n  stop(): void\n  /** Whether the animation is still running */\n  readonly isActive: boolean\n}\n\n// ---------------------------------------------------------------------------\n// createTween\n// ---------------------------------------------------------------------------\n\n/**\n * Start a time-based value interpolation.\n *\n * Animates numeric properties of a plain object from their current values\n * to the specified target values over a fixed duration.\n *\n * @param initial - Starting values for all animated properties\n * @param config - Animation configuration (target, duration, easing, callbacks)\n * @param scheduler - HostScheduler for frame updates (from SurfaceContext)\n * @returns TweenHandle for tracking and cancellation\n *\n * @example\n * ```typescript\n * const surface = useSurface()\n * const tween = createTween(\n *   { dx: 0, dy: 0 },\n *   {\n *     to: { dx: 100, dy: 50 },\n *     duration: 250,\n *     ease: Easing.quadOut,\n *     onUpdate: (t) => updateScroll({ dx: t.dx, dy: t.dy }),\n *     onComplete: () => console.log('done'),\n *   },\n *   surface.scheduler,\n * )\n * // later: tween.stop()\n * ```\n */\nexport function createTween<T extends Record<string, number>>(\n  initial: T,\n  config: TweenConfig<T>,\n  scheduler: HostScheduler\n): TweenHandle<T> {\n  const target = { ...initial } as T\n  const startValues = { ...initial } as T\n  const keys = Object.keys(config.to) as (keyof T)[]\n  const ease = config.ease ?? Easing.quadOut\n  const startTime = performance.now()\n  let frameHandle: HostCancelHandle | null = null\n  let completed = false\n\n  // Duration ≤ 0: snap immediately\n  if (config.duration <= 0) {\n    for (const key of keys) {\n      const toVal = config.to[key]\n      if (toVal !== undefined) {\n        ;(target as Record<string, number>)[key as string] = toVal\n      }\n    }\n    config.onUpdate?.(target)\n    config.onComplete?.()\n    return {\n      target,\n      stop: () => {},\n      isActive: false,\n    }\n  }\n\n  frameHandle = scheduler.onFrame((_dt: number) => {\n    if (completed) return\n\n    const elapsed = performance.now() - startTime\n    const rawProgress = Math.min(elapsed / config.duration, 1)\n    const easedProgress = ease(rawProgress)\n\n    for (const key of keys) {\n      const toVal = config.to[key]\n      if (toVal !== undefined) {\n        const fromVal: number = startValues[key] as number\n        ;(target as Record<string, number>)[key as string] =\n          fromVal + (toVal - fromVal) * easedProgress\n      }\n    }\n\n    try {\n      config.onUpdate?.(target)\n    } catch {\n      // Swallow onUpdate errors — don't break the animation loop\n    }\n\n    if (rawProgress >= 1) {\n      completed = true\n      frameHandle?.cancel()\n      try {\n        config.onComplete?.()\n      } catch {\n        // Swallow onComplete errors\n      }\n    }\n  })\n\n  return {\n    target,\n    stop: () => {\n      if (completed) return\n      completed = true\n      frameHandle?.cancel()\n    },\n    get isActive(): boolean {\n      return !completed\n    },\n  }\n}\n"],"names":["Easing"],"mappings":";;;AAqFO,SAAS,YACd,SACA,QACA,WACgB;AAChB,QAAM,SAAS,EAAE,GAAG,QAAA;AACpB,QAAM,cAAc,EAAE,GAAG,QAAA;AACzB,QAAM,OAAO,OAAO,KAAK,OAAO,EAAE;AAClC,QAAM,OAAO,OAAO,QAAQA,OAAAA,OAAO;AACnC,QAAM,YAAY,YAAY,IAAA;AAC9B,MAAI,cAAuC;AAC3C,MAAI,YAAY;AAGhB,MAAI,OAAO,YAAY,GAAG;AACxB,eAAW,OAAO,MAAM;AACtB,YAAM,QAAQ,OAAO,GAAG,GAAG;AAC3B,UAAI,UAAU,QAAW;AACrB,eAAkC,GAAa,IAAI;AAAA,MACvD;AAAA,IACF;AACA,WAAO,WAAW,MAAM;AACxB,WAAO,aAAA;AACP,WAAO;AAAA,MACL;AAAA,MACA,MAAM,MAAM;AAAA,MAAC;AAAA,MACb,UAAU;AAAA,IAAA;AAAA,EAEd;AAEA,gBAAc,UAAU,QAAQ,CAAC,QAAgB;AAC/C,QAAI,UAAW;AAEf,UAAM,UAAU,YAAY,IAAA,IAAQ;AACpC,UAAM,cAAc,KAAK,IAAI,UAAU,OAAO,UAAU,CAAC;AACzD,UAAM,gBAAgB,KAAK,WAAW;AAEtC,eAAW,OAAO,MAAM;AACtB,YAAM,QAAQ,OAAO,GAAG,GAAG;AAC3B,UAAI,UAAU,QAAW;AACvB,cAAM,UAAkB,YAAY,GAAG;AACrC,eAAkC,GAAa,IAC/C,WAAW,QAAQ,WAAW;AAAA,MAClC;AAAA,IACF;AAEA,QAAI;AACF,aAAO,WAAW,MAAM;AAAA,IAC1B,QAAQ;AAAA,IAER;AAEA,QAAI,eAAe,GAAG;AACpB,kBAAY;AACZ,mBAAa,OAAA;AACb,UAAI;AACF,eAAO,aAAA;AAAA,MACT,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF,CAAC;AAED,SAAO;AAAA,IACL;AAAA,IACA,MAAM,MAAM;AACV,UAAI,UAAW;AACf,kBAAY;AACZ,mBAAa,OAAA;AAAA,IACf;AAAA,IACA,IAAI,WAAoB;AACtB,aAAO,CAAC;AAAA,IACV;AAAA,EAAA;AAEJ;;;"}

package/dist/animation/tween.d.ts

@@ -0,0 +1,60 @@
+import { HostScheduler } from '../host-adapter';
+import { EasingFn } from './easing';
+export { Easing, type EasingFn } from './easing';
+/**
+ * Configuration for a tween animation.
+ * @typeParam T - Record of numeric properties to animate
+ */
+export interface TweenConfig<T extends Record<string, number>> {
+    /** Target values (partial — only specified keys are animated) */
+    to: Partial<T>;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Easing function (default: quadOut) */
+    ease?: EasingFn | undefined;
+    /** Called every frame with the current interpolated target */
+    onUpdate?: ((target: T) => void) | undefined;
+    /** Called when the tween completes naturally (not on stop()) */
+    onComplete?: (() => void) | undefined;
+}
+/**
+ * Handle to an active tween animation.
+ */
+export interface TweenHandle<T extends Record<string, number> = Record<string, number>> {
+    /** Current interpolated state (mutated each frame) */
+    readonly target: Readonly<T>;
+    /** Stop the animation immediately. onComplete is NOT called. */
+    stop(): void;
+    /** Whether the animation is still running */
+    readonly isActive: boolean;
+}
+/**
+ * Start a time-based value interpolation.
+ *
+ * Animates numeric properties of a plain object from their current values
+ * to the specified target values over a fixed duration.
+ *
+ * @param initial - Starting values for all animated properties
+ * @param config - Animation configuration (target, duration, easing, callbacks)
+ * @param scheduler - HostScheduler for frame updates (from SurfaceContext)
+ * @returns TweenHandle for tracking and cancellation
+ *
+ * @example
+ * ```typescript
+ * const surface = useSurface()
+ * const tween = createTween(
+ *   { dx: 0, dy: 0 },
+ *   {
+ *     to: { dx: 100, dy: 50 },
+ *     duration: 250,
+ *     ease: Easing.quadOut,
+ *     onUpdate: (t) => updateScroll({ dx: t.dx, dy: t.dy }),
+ *     onComplete: () => console.log('done'),
+ *   },
+ *   surface.scheduler,
+ * )
+ * // later: tween.stop()
+ * ```
+ */
+export declare function createTween<T extends Record<string, number>>(initial: T, config: TweenConfig<T>, scheduler: HostScheduler): TweenHandle<T>;
+//# sourceMappingURL=tween.d.ts.map

package/dist/animation/tween.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tween.d.ts","sourceRoot":"","sources":["../../src/animation/tween.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAoB,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACtE,OAAO,EAAU,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AAGhD,OAAO,EAAE,MAAM,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AAMhD;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAC3D,iEAAiE;IACjE,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IACd,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,yCAAyC;IACzC,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;IAC5C,gEAAgE;IAChE,UAAU,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAA;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IACpF,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;IAC5B,gEAAgE;IAChE,IAAI,IAAI,IAAI,CAAA;IACZ,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1D,OAAO,EAAE,CAAC,EACV,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACtB,SAAS,EAAE,aAAa,GACvB,WAAW,CAAC,CAAC,CAAC,CAsEhB"}

package/dist/animation/tween.js

@@ -0,0 +1,67 @@
+import { Easing } from "./easing.js";
+function createTween(initial, config, scheduler) {
+  const target = { ...initial };
+  const startValues = { ...initial };
+  const keys = Object.keys(config.to);
+  const ease = config.ease ?? Easing.quadOut;
+  const startTime = performance.now();
+  let frameHandle = null;
+  let completed = false;
+  if (config.duration <= 0) {
+    for (const key of keys) {
+      const toVal = config.to[key];
+      if (toVal !== void 0) {
+        target[key] = toVal;
+      }
+    }
+    config.onUpdate?.(target);
+    config.onComplete?.();
+    return {
+      target,
+      stop: () => {
+      },
+      isActive: false
+    };
+  }
+  frameHandle = scheduler.onFrame((_dt) => {
+    if (completed) return;
+    const elapsed = performance.now() - startTime;
+    const rawProgress = Math.min(elapsed / config.duration, 1);
+    const easedProgress = ease(rawProgress);
+    for (const key of keys) {
+      const toVal = config.to[key];
+      if (toVal !== void 0) {
+        const fromVal = startValues[key];
+        target[key] = fromVal + (toVal - fromVal) * easedProgress;
+      }
+    }
+    try {
+      config.onUpdate?.(target);
+    } catch {
+    }
+    if (rawProgress >= 1) {
+      completed = true;
+      frameHandle?.cancel();
+      try {
+        config.onComplete?.();
+      } catch {
+      }
+    }
+  });
+  return {
+    target,
+    stop: () => {
+      if (completed) return;
+      completed = true;
+      frameHandle?.cancel();
+    },
+    get isActive() {
+      return !completed;
+    }
+  };
+}
+export {
+  Easing,
+  createTween
+};
+//# sourceMappingURL=tween.js.map

package/dist/animation/tween.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tween.js","sources":["../../src/animation/tween.ts"],"sourcesContent":["/**\n * Animation utilities — renderer-neutral tween engine.\n *\n * Provides time-based value interpolation with configurable easing.\n * Runs on HostScheduler.onFrame() — no renderer-specific tween system needed.\n *\n * This is the duration+easing counterpart to the spring-physics animation\n * (useSpring). Use createTween when you need exact duration control;\n * use useSpring for continuous physics-based motion.\n *\n * @migration(audit:surface-access) Phase 7 — new Core capability.\n *   Replaces scene.tweens.add() in portable components.\n */\n\nimport type { HostCancelHandle, HostScheduler } from '../host-adapter'\nimport { Easing, type EasingFn } from './easing'\n\n// Re-export for backward compatibility — all easing functions now live in easing.ts\nexport { Easing, type EasingFn } from './easing'\n\n// ---------------------------------------------------------------------------\n// Tween types\n// ---------------------------------------------------------------------------\n\n/**\n * Configuration for a tween animation.\n * @typeParam T - Record of numeric properties to animate\n */\nexport interface TweenConfig<T extends Record<string, number>> {\n  /** Target values (partial — only specified keys are animated) */\n  to: Partial<T>\n  /** Duration in milliseconds */\n  duration: number\n  /** Easing function (default: quadOut) */\n  ease?: EasingFn | undefined\n  /** Called every frame with the current interpolated target */\n  onUpdate?: ((target: T) => void) | undefined\n  /** Called when the tween completes naturally (not on stop()) */\n  onComplete?: (() => void) | undefined\n}\n\n/**\n * Handle to an active tween animation.\n */\nexport interface TweenHandle<T extends Record<string, number> = Record<string, number>> {\n  /** Current interpolated state (mutated each frame) */\n  readonly target: Readonly<T>\n  /** Stop the animation immediately. onComplete is NOT called. */\n  stop(): void\n  /** Whether the animation is still running */\n  readonly isActive: boolean\n}\n\n// ---------------------------------------------------------------------------\n// createTween\n// ---------------------------------------------------------------------------\n\n/**\n * Start a time-based value interpolation.\n *\n * Animates numeric properties of a plain object from their current values\n * to the specified target values over a fixed duration.\n *\n * @param initial - Starting values for all animated properties\n * @param config - Animation configuration (target, duration, easing, callbacks)\n * @param scheduler - HostScheduler for frame updates (from SurfaceContext)\n * @returns TweenHandle for tracking and cancellation\n *\n * @example\n * ```typescript\n * const surface = useSurface()\n * const tween = createTween(\n *   { dx: 0, dy: 0 },\n *   {\n *     to: { dx: 100, dy: 50 },\n *     duration: 250,\n *     ease: Easing.quadOut,\n *     onUpdate: (t) => updateScroll({ dx: t.dx, dy: t.dy }),\n *     onComplete: () => console.log('done'),\n *   },\n *   surface.scheduler,\n * )\n * // later: tween.stop()\n * ```\n */\nexport function createTween<T extends Record<string, number>>(\n  initial: T,\n  config: TweenConfig<T>,\n  scheduler: HostScheduler\n): TweenHandle<T> {\n  const target = { ...initial } as T\n  const startValues = { ...initial } as T\n  const keys = Object.keys(config.to) as (keyof T)[]\n  const ease = config.ease ?? Easing.quadOut\n  const startTime = performance.now()\n  let frameHandle: HostCancelHandle | null = null\n  let completed = false\n\n  // Duration ≤ 0: snap immediately\n  if (config.duration <= 0) {\n    for (const key of keys) {\n      const toVal = config.to[key]\n      if (toVal !== undefined) {\n        ;(target as Record<string, number>)[key as string] = toVal\n      }\n    }\n    config.onUpdate?.(target)\n    config.onComplete?.()\n    return {\n      target,\n      stop: () => {},\n      isActive: false,\n    }\n  }\n\n  frameHandle = scheduler.onFrame((_dt: number) => {\n    if (completed) return\n\n    const elapsed = performance.now() - startTime\n    const rawProgress = Math.min(elapsed / config.duration, 1)\n    const easedProgress = ease(rawProgress)\n\n    for (const key of keys) {\n      const toVal = config.to[key]\n      if (toVal !== undefined) {\n        const fromVal: number = startValues[key] as number\n        ;(target as Record<string, number>)[key as string] =\n          fromVal + (toVal - fromVal) * easedProgress\n      }\n    }\n\n    try {\n      config.onUpdate?.(target)\n    } catch {\n      // Swallow onUpdate errors — don't break the animation loop\n    }\n\n    if (rawProgress >= 1) {\n      completed = true\n      frameHandle?.cancel()\n      try {\n        config.onComplete?.()\n      } catch {\n        // Swallow onComplete errors\n      }\n    }\n  })\n\n  return {\n    target,\n    stop: () => {\n      if (completed) return\n      completed = true\n      frameHandle?.cancel()\n    },\n    get isActive(): boolean {\n      return !completed\n    },\n  }\n}\n"],"names":[],"mappings":";AAqFO,SAAS,YACd,SACA,QACA,WACgB;AAChB,QAAM,SAAS,EAAE,GAAG,QAAA;AACpB,QAAM,cAAc,EAAE,GAAG,QAAA;AACzB,QAAM,OAAO,OAAO,KAAK,OAAO,EAAE;AAClC,QAAM,OAAO,OAAO,QAAQ,OAAO;AACnC,QAAM,YAAY,YAAY,IAAA;AAC9B,MAAI,cAAuC;AAC3C,MAAI,YAAY;AAGhB,MAAI,OAAO,YAAY,GAAG;AACxB,eAAW,OAAO,MAAM;AACtB,YAAM,QAAQ,OAAO,GAAG,GAAG;AAC3B,UAAI,UAAU,QAAW;AACrB,eAAkC,GAAa,IAAI;AAAA,MACvD;AAAA,IACF;AACA,WAAO,WAAW,MAAM;AACxB,WAAO,aAAA;AACP,WAAO;AAAA,MACL;AAAA,MACA,MAAM,MAAM;AAAA,MAAC;AAAA,MACb,UAAU;AAAA,IAAA;AAAA,EAEd;AAEA,gBAAc,UAAU,QAAQ,CAAC,QAAgB;AAC/C,QAAI,UAAW;AAEf,UAAM,UAAU,YAAY,IAAA,IAAQ;AACpC,UAAM,cAAc,KAAK,IAAI,UAAU,OAAO,UAAU,CAAC;AACzD,UAAM,gBAAgB,KAAK,WAAW;AAEtC,eAAW,OAAO,MAAM;AACtB,YAAM,QAAQ,OAAO,GAAG,GAAG;AAC3B,UAAI,UAAU,QAAW;AACvB,cAAM,UAAkB,YAAY,GAAG;AACrC,eAAkC,GAAa,IAC/C,WAAW,QAAQ,WAAW;AAAA,MAClC;AAAA,IACF;AAEA,QAAI;AACF,aAAO,WAAW,MAAM;AAAA,IAC1B,QAAQ;AAAA,IAER;AAEA,QAAI,eAAe,GAAG;AACpB,kBAAY;AACZ,mBAAa,OAAA;AACb,UAAI;AACF,eAAO,aAAA;AAAA,MACT,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF,CAAC;AAED,SAAO;AAAA,IACL;AAAA,IACA,MAAM,MAAM;AACV,UAAI,UAAW;AACf,kBAAY;AACZ,mBAAa,OAAA;AAAA,IACf;AAAA,IACA,IAAI,WAAoB;AACtB,aAAO,CAAC;AAAA,IACV;AAAA,EAAA;AAEJ;"}

package/dist/animation/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Core animation value types — shared by tween, spring, and effect engine.
+ *
+ * These types define the common property set that all renderer nodes
+ * (Pixi, Phaser) can animate. Renderer-specific mappings translate
+ * AnimValues to native properties.
+ */
+/** Animatable numeric properties on a renderer node */
+export interface AnimValues {
+    x: number;
+    y: number;
+    scaleX: number;
+    scaleY: number;
+    rotation: number;
+    alpha: number;
+    [key: string]: number;
+}
+/** Configuration passed to applyEffect / effect definitions */
+export interface EffectConfig {
+    /** Intensity multiplier (0..2, default varies per effect) */
+    intensity?: number | undefined;
+    /** Duration in ms (default varies per effect) */
+    time?: number | undefined;
+    /** Shake/wobble magnitude */
+    magnitude?: number | undefined;
+    /** Slide direction */
+    direction?: 'left' | 'right' | 'up' | 'down' | undefined;
+    /** Callback when effect completes */
+    onComplete?: (() => void) | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/animation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/animation/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CACtB;AAED,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,sBAAsB;IACtB,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAAA;IACxD,qCAAqC;IACrC,UAAU,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAA;CACtC"}

package/dist/animation/useSpring.cjs

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const signalsCore = require("@preact/signals-core");
+const hooks = require("../hooks.cjs");
+const animatedSignal = require("./animated-signal.cjs");
+const springPhysics = require("./spring-physics.cjs");
+function useSpring(initialValue, config, onComplete) {
+  const resolvedConfig = typeof config === "string" ? springPhysics.SPRING_PRESETS[config] : config ?? springPhysics.SPRING_PRESETS.default;
+  const valueSignal = hooks.useRef(null);
+  if (valueSignal.current === null) {
+    valueSignal.current = animatedSignal.animatedSignal(initialValue);
+  }
+  const ctx = hooks.getCurrentCtx();
+  const scheduler = ctx?.surface?.scheduler ?? null;
+  const state = hooks.useRef({ value: initialValue, velocity: 0 });
+  const target = hooks.useRef({ value: initialValue });
+  const physics = hooks.useRef(new springPhysics.SpringPhysics(resolvedConfig));
+  const schedulerRef = hooks.useRef(null);
+  const wasAtRest = hooks.useRef(true);
+  if (scheduler && schedulerRef.current !== scheduler) {
+    schedulerRef.current = scheduler;
+  }
+  const setValueRef = hooks.useRef(
+    null
+  );
+  if (!setValueRef.current) {
+    setValueRef.current = (newTarget) => {
+      const nextTarget = typeof newTarget === "function" ? newTarget(target.current.value) : newTarget;
+      target.current.value = nextTarget;
+    };
+  }
+  hooks.useEffect(() => {
+    const currentScheduler = schedulerRef.current;
+    if (!currentScheduler) {
+      console.warn("useSpring: HostScheduler not found in surface context");
+      return;
+    }
+    const updateListener = (delta) => {
+      const currentTarget = target.current.value;
+      const currentState = state.current;
+      const atRest = physics.current.isAtRest(currentState, currentTarget);
+      if (wasAtRest.current && !atRest) {
+        resolvedConfig.onStart?.();
+      }
+      if (atRest && !wasAtRest.current && onComplete) {
+        onComplete();
+      }
+      wasAtRest.current = atRest;
+      if (atRest) {
+        const snapped = physics.current.snapIfAtRest(currentState, currentTarget);
+        if (snapped.value !== currentState.value && valueSignal.current) {
+          state.current = snapped;
+          valueSignal.current.value = snapped.value;
+        }
+        return;
+      }
+      const deltaSeconds = delta / 1e3;
+      const newState = physics.current.step(currentState, currentTarget, deltaSeconds);
+      resolvedConfig.onUpdate?.(newState.value);
+      if (valueSignal.current) {
+        state.current = newState;
+        valueSignal.current.value = newState.value;
+      }
+    };
+    const handle = currentScheduler.onFrame(updateListener);
+    return () => {
+      handle.cancel();
+    };
+  }, []);
+  if (!valueSignal.current) {
+    throw new Error("useSpring: Failed to initialize animated signal");
+  }
+  return [
+    valueSignal.current,
+    setValueRef.current
+  ];
+}
+function useSprings(initialValues, config) {
+  const keys = Object.keys(initialValues);
+  const springsMap = hooks.useRef(/* @__PURE__ */ new Map());
+  const schedulerRef = hooks.useRef(null);
+  const resolvedConfig = typeof config === "string" ? springPhysics.SPRING_PRESETS[config] : config ?? springPhysics.SPRING_PRESETS.default;
+  keys.forEach((key) => {
+    if (!springsMap.current.has(key)) {
+      const initialValue = initialValues[key];
+      const signal = animatedSignal.animatedSignal(initialValue);
+      const target = { value: initialValue };
+      const state = { value: initialValue, velocity: 0 };
+      const physics = new springPhysics.SpringPhysics(resolvedConfig);
+      springsMap.current.set(key, { signal, target, state, physics });
+    }
+  });
+  const ctx = hooks.getCurrentCtx();
+  const scheduler = ctx?.surface?.scheduler ?? null;
+  if (scheduler && schedulerRef.current !== scheduler) {
+    schedulerRef.current = scheduler;
+  }
+  hooks.useEffect(() => {
+    const currentScheduler = schedulerRef.current;
+    if (!currentScheduler) {
+      console.warn("useSprings: HostScheduler not found in surface context");
+      return;
+    }
+    const updateListener = (delta) => {
+      const deltaSeconds = delta / 1e3;
+      springsMap.current.forEach((spring) => {
+        const currentTarget = spring.target.value;
+        const currentState = spring.state;
+        if (spring.physics.isAtRest(currentState, currentTarget)) {
+          const snapped = spring.physics.snapIfAtRest(currentState, currentTarget);
+          if (snapped.value !== currentState.value) {
+            spring.state = snapped;
+            spring.signal.value = snapped.value;
+          }
+          return;
+        }
+        const newState = spring.physics.step(currentState, currentTarget, deltaSeconds);
+        spring.state = newState;
+        spring.signal.value = newState.value;
+      });
+    };
+    const handle = currentScheduler.onFrame(updateListener);
+    return () => {
+      handle.cancel();
+    };
+  }, []);
+  const signals = {};
+  keys.forEach((key) => {
+    const spring = springsMap.current.get(key);
+    if (spring) {
+      signals[key] = spring.signal;
+    }
+  });
+  const setValues = (values) => {
+    Object.entries(values).forEach(([key, value]) => {
+      const spring = springsMap.current.get(key);
+      if (spring) {
+        const nextTarget = typeof value === "function" ? value(spring.target.value) : value;
+        spring.target.value = nextTarget;
+      }
+    });
+  };
+  return [signals, setValues];
+}
+Object.defineProperty(exports, "computed", {
+  enumerable: true,
+  get: () => signalsCore.computed
+});
+exports.SPRING_PRESETS = springPhysics.SPRING_PRESETS;
+exports.useSpring = useSpring;
+exports.useSprings = useSprings;
+//# sourceMappingURL=useSpring.cjs.map

package/dist/animation/useSpring.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSpring.cjs","sources":["../../src/animation/useSpring.ts"],"sourcesContent":["/**\n * Spring animation hook\n * Provides physics-based animations using signals for direct updates.\n * Uses HostScheduler.onFrame() — no renderer-specific tick source needed.\n *\n * @migration(audit:surface-access) Phase 7 — moved to @number10/jsx-core ✅\n */\nimport { computed, type Signal } from '@preact/signals-core'\nimport { getCurrentCtx, useEffect, useRef, type HookContext } from '../hooks'\nimport type { HostScheduler } from '../host-adapter'\nimport { animatedSignal, type AnimatedSignal } from './animated-signal'\nimport {\n  SPRING_PRESETS,\n  SpringPhysics,\n  type SpringConfig,\n  type SpringState,\n} from './spring-physics'\n\n/**\n * Spring animation hook\n * Creates an animated signal that smoothly transitions to target values\n *\n * @param initialValue - Initial value\n * @param config - Spring configuration or preset name\n * @param onComplete - Optional callback when spring reaches rest\n * @returns Tuple of [animated signal, setter function]\n *\n * @example\n * ```tsx\n * // ✓ SAFE - leaf node\n * const [x, setX] = useSpring(0, 'wobbly')\n * <View x={x} width={50} height={50} backgroundColor={0xff0000} />\n *\n * // ✓ SAFE - transform properties\n * const [scale, setScale] = useSpring(1, 'default')\n * <View scale={scale}><Text text=\"Hello\" /></View>\n *\n * // ✗ UNSAFE - container with percentage children\n * const [width, setWidth] = useSpring(200, 'wobbly')\n * <View width={width}><NineSlice width=\"100%\" /></View> // BREAKS!\n * ```\n */\nexport function useSpring(\n  initialValue: number,\n  config?: SpringConfig | keyof typeof SPRING_PRESETS,\n  onComplete?: () => void\n): [AnimatedSignal, (target: number | ((prev: number) => number)) => void] {\n  // Resolve config\n  const resolvedConfig =\n    typeof config === 'string' ? SPRING_PRESETS[config] : (config ?? SPRING_PRESETS.default)\n\n  // Create animated signal\n  const valueSignal = useRef<AnimatedSignal | null>(null)\n  if (valueSignal.current === null) {\n    valueSignal.current = animatedSignal(initialValue)\n  }\n\n  // Capture scheduler from surface context during render\n  const ctx = getCurrentCtx() as HookContext | null\n  const scheduler = ctx?.surface?.scheduler ?? null\n\n  // Physics state\n  const state = useRef<SpringState>({ value: initialValue, velocity: 0 })\n  const target = useRef<Signal<number>>({ value: initialValue } as Signal<number>)\n  const physics = useRef(new SpringPhysics(resolvedConfig))\n  const schedulerRef = useRef<HostScheduler | null>(null)\n  const wasAtRest = useRef<boolean>(true)\n\n  // Update scheduler ref if it changes\n  if (scheduler && schedulerRef.current !== scheduler) {\n    schedulerRef.current = scheduler\n  }\n\n  // Setter function — stable reference via ref (avoids effect re-runs)\n  const setValueRef = useRef<((newTarget: number | ((prev: number) => number)) => void) | null>(\n    null\n  )\n  if (!setValueRef.current) {\n    setValueRef.current = (newTarget: number | ((prev: number) => number)) => {\n      const nextTarget =\n        typeof newTarget === 'function' ? newTarget(target.current.value) : newTarget\n      target.current.value = nextTarget\n    }\n  }\n\n  useEffect(() => {\n    const currentScheduler = schedulerRef.current\n    if (!currentScheduler) {\n      console.warn('useSpring: HostScheduler not found in surface context')\n      return\n    }\n\n    // Physics update loop\n    const updateListener = (delta: number) => {\n      const currentTarget = target.current.value\n      const currentState = state.current\n\n      // Check if at rest\n      const atRest = physics.current.isAtRest(currentState, currentTarget)\n\n      // Fire onStart when transitioning from rest to active\n      if (wasAtRest.current && !atRest) {\n        ;(resolvedConfig as SpringConfig).onStart?.()\n      }\n\n      // Call onComplete if just reached rest\n      if (atRest && !wasAtRest.current && onComplete) {\n        onComplete()\n      }\n      wasAtRest.current = atRest\n\n      // Skip if already at rest\n      if (atRest) {\n        // Snap to target\n        const snapped = physics.current.snapIfAtRest(currentState, currentTarget)\n        if (snapped.value !== currentState.value && valueSignal.current) {\n          state.current = snapped\n          valueSignal.current.value = snapped.value\n        }\n        return\n      }\n\n      // Perform physics step\n      const deltaSeconds = delta / 1000\n      const newState = physics.current.step(currentState, currentTarget, deltaSeconds)\n\n      // Fire onUpdate with current value every frame while active\n      ;(resolvedConfig as SpringConfig).onUpdate?.(newState.value)\n\n      // Update state and signal\n      if (valueSignal.current) {\n        state.current = newState\n        valueSignal.current.value = newState.value\n      }\n    }\n\n    const handle = currentScheduler.onFrame(updateListener)\n    return () => {\n      handle.cancel()\n    }\n  }, [])\n\n  if (!valueSignal.current) {\n    throw new Error('useSpring: Failed to initialize animated signal')\n  }\n\n  return [\n    valueSignal.current,\n    setValueRef.current as (target: number | ((prev: number) => number)) => void,\n  ]\n}\n\n/**\n * Multi-spring animation hook\n * Creates multiple animated signals that share the same configuration\n * @param initialValues - Object with initial values\n * @param config - Spring configuration or preset name\n * @returns Tuple of [animated signals object, setter function]\n *\n * @example\n * ```tsx\n * const [pos, setPos] = useSprings({ x: 0, y: 0 }, 'wobbly')\n * <View x={pos.x} y={pos.y} />\n * setPos({ x: 100, y: 200 })\n * ```\n */\nexport function useSprings<T extends Record<string, number>>(\n  initialValues: T,\n  config?: SpringConfig | keyof typeof SPRING_PRESETS\n): [\n  { [K in keyof T]: AnimatedSignal },\n  (values: Partial<{ [K in keyof T]: number | ((prev: number) => number) }>) => void,\n] {\n  const keys = Object.keys(initialValues) as (keyof T)[]\n  const springsMap = useRef<\n    Map<\n      keyof T,\n      {\n        signal: AnimatedSignal\n        target: { value: number }\n        state: SpringState\n        physics: SpringPhysics\n      }\n    >\n  >(new Map())\n  const schedulerRef = useRef<HostScheduler | null>(null)\n\n  // Resolve config\n  const resolvedConfig =\n    typeof config === 'string' ? SPRING_PRESETS[config] : (config ?? SPRING_PRESETS.default)\n\n  // Initialize springs manually (can't use hooks in loops!)\n  keys.forEach((key) => {\n    if (!springsMap.current.has(key)) {\n      const initialValue = initialValues[key] as number\n      const signal = animatedSignal(initialValue)\n      const target = { value: initialValue }\n      const state = { value: initialValue, velocity: 0 }\n      const physics = new SpringPhysics(resolvedConfig)\n      springsMap.current.set(key, { signal, target, state, physics })\n    }\n  })\n\n  // Capture scheduler from surface context during render\n  const ctx = getCurrentCtx() as HookContext | null\n  const scheduler = ctx?.surface?.scheduler ?? null\n\n  if (scheduler && schedulerRef.current !== scheduler) {\n    schedulerRef.current = scheduler\n  }\n\n  // Setup physics update loop\n  useEffect(() => {\n    const currentScheduler = schedulerRef.current\n    if (!currentScheduler) {\n      console.warn('useSprings: HostScheduler not found in surface context')\n      return\n    }\n\n    const updateListener = (delta: number) => {\n      const deltaSeconds = delta / 1000\n\n      springsMap.current.forEach((spring) => {\n        const currentTarget = spring.target.value\n        const currentState = spring.state\n\n        // Skip if already at rest\n        if (spring.physics.isAtRest(currentState, currentTarget)) {\n          const snapped = spring.physics.snapIfAtRest(currentState, currentTarget)\n          if (snapped.value !== currentState.value) {\n            spring.state = snapped\n            spring.signal.value = snapped.value\n          }\n          return\n        }\n\n        // Perform physics step\n        const newState = spring.physics.step(currentState, currentTarget, deltaSeconds)\n        spring.state = newState\n        spring.signal.value = newState.value\n      })\n    }\n\n    const handle = currentScheduler.onFrame(updateListener)\n    return () => {\n      handle.cancel()\n    }\n  }, [])\n\n  // Build result object\n  const signals = {} as { [K in keyof T]: AnimatedSignal }\n  keys.forEach((key) => {\n    const spring = springsMap.current.get(key)\n    if (spring) {\n      signals[key] = spring.signal\n    }\n  })\n\n  // Setter function\n  const setValues = (values: Partial<{ [K in keyof T]: number | ((prev: number) => number) }>) => {\n    Object.entries(values).forEach(([key, value]) => {\n      const spring = springsMap.current.get(key as keyof T)\n      if (spring) {\n        const nextTarget = typeof value === 'function' ? value(spring.target.value) : value\n        spring.target.value = nextTarget as number\n      }\n    })\n  }\n\n  return [signals, setValues]\n}\n\n/**\n * Export presets for convenience\n */\nexport { computed, SPRING_PRESETS }\n"],"names":["SPRING_PRESETS","useRef","animatedSignal","getCurrentCtx","SpringPhysics","useEffect"],"mappings":"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"}

package/dist/animation/useSpring.d.ts

@@ -0,0 +1,55 @@
+import { computed } from '@preact/signals-core';
+import { AnimatedSignal } from './animated-signal';
+import { SPRING_PRESETS, SpringConfig } from './spring-physics';
+/**
+ * Spring animation hook
+ * Creates an animated signal that smoothly transitions to target values
+ *
+ * @param initialValue - Initial value
+ * @param config - Spring configuration or preset name
+ * @param onComplete - Optional callback when spring reaches rest
+ * @returns Tuple of [animated signal, setter function]
+ *
+ * @example
+ * ```tsx
+ * // ✓ SAFE - leaf node
+ * const [x, setX] = useSpring(0, 'wobbly')
+ * <View x={x} width={50} height={50} backgroundColor={0xff0000} />
+ *
+ * // ✓ SAFE - transform properties
+ * const [scale, setScale] = useSpring(1, 'default')
+ * <View scale={scale}><Text text="Hello" /></View>
+ *
+ * // ✗ UNSAFE - container with percentage children
+ * const [width, setWidth] = useSpring(200, 'wobbly')
+ * <View width={width}><NineSlice width="100%" /></View> // BREAKS!
+ * ```
+ */
+export declare function useSpring(initialValue: number, config?: SpringConfig | keyof typeof SPRING_PRESETS, onComplete?: () => void): [AnimatedSignal, (target: number | ((prev: number) => number)) => void];
+/**
+ * Multi-spring animation hook
+ * Creates multiple animated signals that share the same configuration
+ * @param initialValues - Object with initial values
+ * @param config - Spring configuration or preset name
+ * @returns Tuple of [animated signals object, setter function]
+ *
+ * @example
+ * ```tsx
+ * const [pos, setPos] = useSprings({ x: 0, y: 0 }, 'wobbly')
+ * <View x={pos.x} y={pos.y} />
+ * setPos({ x: 100, y: 200 })
+ * ```
+ */
+export declare function useSprings<T extends Record<string, number>>(initialValues: T, config?: SpringConfig | keyof typeof SPRING_PRESETS): [
+    {
+        [K in keyof T]: AnimatedSignal;
+    },
+    (values: Partial<{
+        [K in keyof T]: number | ((prev: number) => number);
+    }>) => void
+];
+/**
+ * Export presets for convenience
+ */
+export { computed, SPRING_PRESETS };
+//# sourceMappingURL=useSpring.d.ts.map

package/dist/animation/useSpring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSpring.d.ts","sourceRoot":"","sources":["../../src/animation/useSpring.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,QAAQ,EAAe,MAAM,sBAAsB,CAAA;AAG5D,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvE,OAAO,EACL,cAAc,EAEd,KAAK,YAAY,EAElB,MAAM,kBAAkB,CAAA;AAEzB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,SAAS,CACvB,YAAY,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,OAAO,cAAc,EACnD,UAAU,CAAC,EAAE,MAAM,IAAI,GACtB,CAAC,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,KAAK,IAAI,CAAC,CAwGzE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACzD,aAAa,EAAE,CAAC,EAChB,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,OAAO,cAAc,GAClD;IACD;SAAG,CAAC,IAAI,MAAM,CAAC,GAAG,cAAc;KAAE;IAClC,CAAC,MAAM,EAAE,OAAO,CAAC;SAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;KAAE,CAAC,KAAK,IAAI;CACnF,CAkGA;AAED;;GAEG;AACH,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAA"}