af-motion 0.0.0-stage → 1.0.0

package/dist/core/physics/inertia-types.d.ts

@@ -0,0 +1,355 @@
+/**
+ * AF Motion — Inertia, Momentum, Friction & Gravity Type System
+ *
+ * Strongly typed contracts for mass-aware momentum simulations,
+ * multi-model friction and drag resistance, external forces, and directional gravity.
+ */
+import type { PhysicsValue, IntegratorType, PhysicsSimulationContext, PhysicsStepOptions } from "./types.js";
+/**
+ * Advanced configuration options for inertia and momentum simulations.
+ */
+export interface AdvancedInertiaConfig {
+    /**
+     * Mass of the body in mass units / kilograms (m).
+     * Determines resistance to acceleration (F = m * a) and momentum (p = m * v).
+     * Must be finite and > 0. Default: 1.0.
+     */
+    mass?: number;
+    /**
+     * Viscous / exponential friction coefficient (gamma).
+     * Opposes velocity proportionally: F_viscous = -m * gamma * v.
+     * Must be finite and >= 0. Default: 4.0.
+     */
+    friction?: number;
+    /**
+     * Constant kinetic / Coulomb friction coefficient (mu).
+     * Opposes the direction of motion with constant magnitude: F_kinetic = -mu * m * norm(v).
+     * Must be finite and >= 0. Default: 0.
+     */
+    linearFriction?: number;
+    /**
+     * Aerodynamic drag / quadratic air resistance coefficient (c_d).
+     * Opposes velocity quadratically: F_drag = -c_d * |v| * v.
+     * Must be finite and >= 0. Default: 0.
+     */
+    drag?: number;
+    /**
+     * Directional gravity acceleration vector or scalar (g).
+     * Generates weight force: F_gravity = m * g.
+     * Scalar (e.g. 9.8 or 980) or vector (e.g. { x: 0, y: 9.8 } or { x: 0, y: -980, z: 0 }).
+     * Default: 0.
+     */
+    gravity?: PhysicsValue;
+    /**
+     * Optional maximum speed / terminal velocity clamp.
+     * If speed exceeds this value, velocity is clamped to this magnitude.
+     * Must be finite and > 0.
+     */
+    terminalVelocity?: number;
+    /**
+     * Minimum speed threshold below which motion is considered settled.
+     * Default: 0.5. Must be finite and >= 0.
+     */
+    minVelocity?: number;
+    /**
+     * Initial spatial position (scalar or vector).
+     * Default: 0.
+     */
+    from?: PhysicsValue;
+    /**
+     * Initial velocity vector or scalar (v0).
+     * Default: 0.
+     */
+    initialVelocity?: PhysicsValue;
+    /**
+     * Optional lower bound coordinate. If position exceeds lower bound,
+     * movement is clamped and velocity in that axis is zeroed.
+     */
+    min?: PhysicsValue;
+    /**
+     * Optional upper bound coordinate. If position exceeds upper bound,
+     * movement is clamped and velocity in that axis is zeroed.
+     */
+    max?: PhysicsValue;
+    /**
+     * Discrete fixed timestep in seconds for numerical integration steps.
+     * Default: 1/60 (~0.016667s). Must be finite and > 0.
+     */
+    timestep?: number;
+    /**
+     * Numerical integration algorithm.
+     * Default: 'semi-implicit-euler'.
+     */
+    integrator?: IntegratorType;
+    /**
+     * Simulation time progression multiplier.
+     * Default: 1.0. Must be finite and >= 0.
+     */
+    timeScale?: number;
+    /**
+     * Maximum sub-steps per frame to prevent the spiral of death.
+     * Default: 10. Must be an integer >= 1.
+     */
+    maxSubSteps?: number;
+    /**
+     * Precision threshold snapping small micro-velocities to zero.
+     * Default: 1e-5.
+     */
+    precision?: number;
+    /**
+     * Automatically start advancing on creation.
+     * Default: false.
+     */
+    autoStart?: boolean;
+    /**
+     * Respect system reduced motion preferences.
+     * Default: true.
+     */
+    respectReducedMotion?: boolean;
+}
+/**
+ * Complete snapshot of the inertia simulation state.
+ */
+export interface InertiaState {
+    /**
+     * Current spatial position (scalar or vector).
+     */
+    readonly position: PhysicsValue;
+    /**
+     * Current instantaneous velocity (scalar or vector).
+     */
+    readonly velocity: PhysicsValue;
+    /**
+     * Current instantaneous acceleration (scalar or vector).
+     */
+    readonly acceleration: PhysicsValue;
+    /**
+     * Total net force acting on the body: F_net = F_gravity + F_friction + F_drag + F_external.
+     */
+    readonly netForce: PhysicsValue;
+    /**
+     * Mass of the body.
+     */
+    readonly mass: number;
+    /**
+     * Whether the body has settled at rest.
+     */
+    readonly settled: boolean;
+    /**
+     * Current speed (Euclidean magnitude of velocity).
+     */
+    readonly speed: number;
+    /**
+     * Momentum vector or scalar (p = m * v).
+     */
+    readonly momentum: PhysicsValue;
+    /**
+     * Kinetic energy of the body: E_k = 0.5 * m * |v|^2.
+     */
+    readonly kineticEnergy: number;
+}
+/**
+ * Diagnostic result returned by each inertia simulation step.
+ */
+export interface InertiaStepResult {
+    readonly position: PhysicsValue;
+    readonly velocity: PhysicsValue;
+    readonly acceleration: PhysicsValue;
+    readonly netForce: PhysicsValue;
+    readonly settled: boolean;
+    readonly stepsTaken: number;
+    readonly clamped: boolean;
+    readonly context: PhysicsSimulationContext;
+}
+/**
+ * Standard inertia preset names.
+ */
+export type InertiaPresetName = "natural" | "heavy" | "light" | "high-friction" | "low-friction" | "air-resistance" | "gravity" | "zero-gravity" | "fast-deceleration";
+/**
+ * Named preset structure for inertia configurations.
+ */
+export interface InertiaPreset {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly config: Partial<AdvancedInertiaConfig>;
+}
+/**
+ * Callback signatures for inertia events.
+ */
+export type InertiaUpdateListener = (state: InertiaState, context: PhysicsSimulationContext) => void;
+export type InertiaSettleListener = (state: InertiaState, context: PhysicsSimulationContext) => void;
+export type InertiaCompleteListener = (state: InertiaState, context: PhysicsSimulationContext) => void;
+/**
+ * Options for creating an independent inertia simulation instance.
+ */
+export interface AdvancedInertiaOptions {
+    /**
+     * Configuration object or named preset identifier.
+     */
+    config?: AdvancedInertiaConfig | InertiaPresetName;
+    /**
+     * Starting position override.
+     */
+    from?: PhysicsValue;
+    /**
+     * Initial velocity override.
+     */
+    initialVelocity?: PhysicsValue;
+    /**
+     * Gravity vector/scalar override.
+     */
+    gravity?: PhysicsValue;
+    /**
+     * Called on every simulation step.
+     */
+    onUpdate?: InertiaUpdateListener;
+    /**
+     * Called once when the body decelerates to rest.
+     */
+    onSettle?: InertiaSettleListener;
+    /**
+     * Called once when the simulation reaches completion or settles.
+     */
+    onComplete?: InertiaCompleteListener;
+}
+/**
+ * Public controller interface for an active inertia simulation instance.
+ */
+export interface AdvancedInertiaControls {
+    /**
+     * Starts or resumes the inertia simulation.
+     */
+    start(): void;
+    /**
+     * Pauses the simulation without losing position, velocity, or momentum.
+     */
+    pause(): void;
+    /**
+     * Resumes a paused simulation.
+     */
+    resume(): void;
+    /**
+     * Stops the simulation and marks it idle.
+     */
+    stop(): void;
+    /**
+     * Resets the simulation to its initial state or baseline.
+     */
+    reset(newInitialState?: Partial<AdvancedInertiaConfig>): void;
+    /**
+     * Manually steps the inertia simulation forward by deltaTime seconds.
+     */
+    step(deltaTimeOrOptions?: number | PhysicsStepOptions): InertiaStepResult;
+    /**
+     * Applies an external force (F) that acts on the body.
+     * Can be sustained or continuous.
+     */
+    applyForce(force: PhysicsValue): void;
+    /**
+     * Clears any active continuous external force.
+     */
+    clearForce(): void;
+    /**
+     * Applies an instantaneous impulse (J), altering velocity by: delta_v = J / mass.
+     */
+    applyImpulse(impulse: PhysicsValue): void;
+    /**
+     * Injects or adds velocity to the current velocity vector.
+     */
+    injectVelocity(deltaVelocity: PhysicsValue): void;
+    /**
+     * Directly sets the current velocity vector.
+     */
+    setVelocity(newVelocity: PhysicsValue): void;
+    /**
+     * Directly overrides the current position coordinates.
+     */
+    setPosition(newPosition: PhysicsValue): void;
+    /**
+     * Inverts the direction of the velocity vector.
+     */
+    reverseVelocity(): void;
+    /**
+     * Dynamically updates the gravity vector.
+     */
+    setGravity(gravity: PhysicsValue): void;
+    /**
+     * Dynamically updates the friction coefficient.
+     */
+    setFriction(friction: number): void;
+    /**
+     * Updates the simulation time scaling factor dynamically.
+     */
+    setTimeScale(scale: number): void;
+    /**
+     * Returns a snapshot of the current state.
+     */
+    getState(): InertiaState;
+    /**
+     * Returns a snapshot of the current simulation context.
+     */
+    getContext(): PhysicsSimulationContext;
+    /**
+     * Returns the current resolved configuration.
+     */
+    getConfiguration(): Required<AdvancedInertiaConfig>;
+    /**
+     * Dynamically updates physical configuration parameters.
+     */
+    setConfiguration(config: Partial<AdvancedInertiaConfig>): void;
+    /**
+     * Returns whether the body has settled at rest.
+     */
+    isSettled(): boolean;
+    /**
+     * Returns whether the simulation has completed.
+     */
+    isCompleted(): boolean;
+    /**
+     * Returns whether the simulation is currently active and running.
+     */
+    isRunning(): boolean;
+    /**
+     * Returns whether the simulation is currently paused.
+     */
+    isPaused(): boolean;
+    /**
+     * Returns whether the simulation has been disposed.
+     */
+    isDisposed(): boolean;
+    /**
+     * Subscribes to step updates. Returns an unsubscribe function.
+     */
+    onUpdate(listener: InertiaUpdateListener): () => void;
+    /**
+     * Subscribes to settling events. Returns an unsubscribe function.
+     */
+    onSettle(listener: InertiaSettleListener): () => void;
+    /**
+     * Subscribes to completion events. Returns an unsubscribe function.
+     */
+    onComplete(listener: InertiaCompleteListener): () => void;
+    /**
+     * Disposes the simulation and releases all resources and listener subscriptions.
+     */
+    dispose(): void;
+}
+/**
+ * Options for animated inertia on the shared requestAnimationFrame loop.
+ */
+export interface AdvancedInertiaAnimationOptions extends AdvancedInertiaOptions {
+    /**
+     * Function invoked on each animation frame with updated inertia state and context.
+     */
+    onUpdate: InertiaUpdateListener;
+}
+/**
+ * Controls for RAF-driven animated inertia.
+ */
+export interface AdvancedInertiaAnimationControls extends AdvancedInertiaControls {
+    /**
+     * Cancels the animation, stopping the RAF loop and suppressing further callbacks.
+     */
+    cancel(): void;
+}

package/dist/core/physics/inertia-validation.d.ts

@@ -0,0 +1,22 @@
+/**
+ * AF Motion — Inertia & Gravity Validation & Correction
+ *
+ * Enforces parameter sanity and numerical stability for momentum and force simulations.
+ */
+import type { AdvancedInertiaConfig } from "./inertia-types.js";
+import type { PhysicsValidationResult } from "./validation.js";
+/**
+ * Validates an AdvancedInertiaConfig object.
+ */
+export declare function validateInertiaConfig(config: unknown): PhysicsValidationResult;
+/**
+ * Asserts that an inertia configuration is valid, throwing PhysicsValidationError if invalid.
+ */
+export declare function assertValidInertiaConfig(config: unknown): asserts config is AdvancedInertiaConfig;
+/**
+ * Safely corrects an invalid inertia configuration.
+ */
+export declare function correctInertiaConfig(config?: Partial<AdvancedInertiaConfig>): {
+    corrected: Required<AdvancedInertiaConfig>;
+    corrections: string[];
+};

package/dist/core/physics/math.d.ts

@@ -0,0 +1,99 @@
+/**
+ * AF Motion — Foundational Physics Math & Vector Utilities
+ *
+ * Framework-independent vector and numerical operations for physics simulations.
+ * Guarantees numerical stability, finite float validation, and vector safety.
+ */
+import type { PhysicsVector, PhysicsValue } from "./types.js";
+/**
+ * Checks whether a given value is a strictly finite number.
+ */
+export declare function isFiniteNumber(val: unknown): val is number;
+/**
+ * Checks whether a given value is a PhysicsVector object with finite components.
+ */
+export declare function isPhysicsVector(val: unknown): val is PhysicsVector;
+/**
+ * Checks whether a given value is a valid scalar or vector PhysicsValue.
+ */
+export declare function isPhysicsValue(val: unknown): val is PhysicsValue;
+/**
+ * Clamps a scalar number between a minimum and maximum bound.
+ */
+export declare function clamp(val: number, min: number, max: number): number;
+/**
+ * Applies a precision threshold, snapping values close to zero to exactly 0.
+ */
+export declare function roundPrecision(val: number, precision: number): number;
+/**
+ * Creates a new PhysicsVector instance.
+ */
+export declare function createVector(x: number, y?: number, z?: number): PhysicsVector;
+/**
+ * Creates a deep clone of a vector.
+ */
+export declare function cloneVector(v: PhysicsVector): PhysicsVector;
+/**
+ * Clones a scalar or vector PhysicsValue.
+ */
+export declare function clonePhysicsValue(val: PhysicsValue): PhysicsValue;
+/**
+ * Adds two vectors component-wise.
+ */
+export declare function addVectors(a: PhysicsVector, b: PhysicsVector): PhysicsVector;
+/**
+ * Subtracts vector b from vector a component-wise (a - b).
+ */
+export declare function subVectors(a: PhysicsVector, b: PhysicsVector): PhysicsVector;
+/**
+ * Scales a vector by a scalar factor.
+ */
+export declare function scaleVector(v: PhysicsVector, factor: number): PhysicsVector;
+/**
+ * Computes the Euclidean magnitude (length) of a vector.
+ */
+export declare function magnitude(v: PhysicsVector): number;
+/**
+ * Computes the dot product of two vectors.
+ */
+export declare function dot(a: PhysicsVector, b: PhysicsVector): number;
+/**
+ * Computes the Euclidean distance between two vectors.
+ */
+export declare function distance(a: PhysicsVector, b: PhysicsVector): number;
+/**
+ * Normalizes a vector to unit length. Returns a zero vector if magnitude is 0.
+ */
+export declare function normalize(v: PhysicsVector): PhysicsVector;
+/**
+ * Component-wise linear interpolation (lerp) between two vectors.
+ */
+export declare function lerpVectors(a: PhysicsVector, b: PhysicsVector, alpha: number): PhysicsVector;
+/**
+ * Adds two PhysicsValues (both scalar, both vector, or scalar-vector compatible).
+ */
+export declare function addValues(a: PhysicsValue, b: PhysicsValue): PhysicsValue;
+/**
+ * Subtracts PhysicsValue b from PhysicsValue a (a - b).
+ */
+export declare function subValues(a: PhysicsValue, b: PhysicsValue): PhysicsValue;
+/**
+ * Scales a PhysicsValue by a scalar multiplier.
+ */
+export declare function scaleValue(v: PhysicsValue, factor: number): PhysicsValue;
+/**
+ * Returns the Euclidean magnitude / absolute value of a PhysicsValue.
+ */
+export declare function valueMagnitude(val: PhysicsValue): number;
+/**
+ * Snaps scalar or vector components under a precision threshold to 0.
+ */
+export declare function applyPrecision(val: PhysicsValue, precision: number): PhysicsValue;
+/**
+ * Checks whether a PhysicsValue has settled to effectively zero within precision.
+ */
+export declare function isZeroValue(val: PhysicsValue, precision: number): boolean;
+/**
+ * Performs linear interpolation between two PhysicsValues.
+ */
+export declare function lerpValues(a: PhysicsValue, b: PhysicsValue, alpha: number): PhysicsValue;

package/dist/core/physics/presets.d.ts

@@ -0,0 +1,28 @@
+/**
+ * AF Motion — Foundational Physics Presets
+ *
+ * Built-in presets for common simulation frequencies, precision thresholds,
+ * and playback speeds.
+ */
+import type { PhysicsConfiguration, PhysicsPreset } from "./types.js";
+export declare const PHYSICS_PRESET_STANDARD: PhysicsPreset;
+export declare const PHYSICS_PRESET_HIGH_PRECISION: PhysicsPreset;
+export declare const PHYSICS_PRESET_LOW_OVERHEAD: PhysicsPreset;
+export declare const PHYSICS_PRESET_BULLET_TIME: PhysicsPreset;
+export declare const PHYSICS_PRESET_FAST_FORWARD: PhysicsPreset;
+/**
+ * Retrieves a registered physics preset by ID or name.
+ */
+export declare function getPhysicsPreset(idOrName: string): PhysicsPreset | undefined;
+/**
+ * Returns a list of all available physics presets.
+ */
+export declare function listPhysicsPresets(): readonly PhysicsPreset[];
+/**
+ * Registers a new custom physics preset.
+ */
+export declare function registerPhysicsPreset(preset: PhysicsPreset): void;
+/**
+ * Resolves a partial configuration or preset identifier into a full PhysicsConfiguration.
+ */
+export declare function resolvePhysicsConfig(presetOrConfig?: string | Partial<PhysicsConfiguration>): Required<PhysicsConfiguration>;

package/dist/core/physics/simulation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AF Motion — Foundational Physics Simulation Engine
+ *
+ * Implements independent, extensible physics simulations with complete lifecycle
+ * management, deterministic stepping, state inspection, and event subscriptions.
+ */
+import type { PhysicsControls, PhysicsSimulationOptions } from "./types.js";
+/**
+ * Creates an independent, fully isolated physics simulation instance.
+ */
+export declare function createPhysicsSimulation(options?: PhysicsSimulationOptions): PhysicsControls;

package/dist/core/physics/spring-animation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AF Motion — Shared RAF Animated Spring Integration
+ *
+ * Integrates Advanced Spring Physics with the library's shared animation frame
+ * scheduler (subscribeAnimationFrames), honoring reduced-motion accessibility.
+ */
+import type { AdvancedSpringAnimationOptions, AdvancedSpringAnimationControls } from "./spring-types.js";
+/**
+ * Animates an advanced spring using the library's shared RAF frame scheduler.
+ */
+export declare function animateAdvancedSpring(options: AdvancedSpringAnimationOptions): AdvancedSpringAnimationControls;

package/dist/core/physics/spring-math.d.ts

@@ -0,0 +1,47 @@
+/**
+ * AF Motion — Spring Mathematics & Dynamic Calculations
+ *
+ * Implements the second-order mass-spring-damper equations of motion:
+ *   F = -k(x - target) - c*v
+ *   a = F / m
+ * Supports scalars, 2D vectors, and 3D vectors polymorphically.
+ */
+import type { PhysicsValue } from "./types.js";
+import type { SpringDampingBehavior } from "./spring-types.js";
+/**
+ * Computes the undamped natural frequency (omega0 = sqrt(k / m)) in radians per second.
+ */
+export declare function calculateNaturalFrequency(stiffness: number, mass: number): number;
+/**
+ * Computes the dimensionless damping ratio (zeta = c / (2 * sqrt(k * m))).
+ */
+export declare function calculateDampingRatio(stiffness: number, damping: number, mass: number): number;
+/**
+ * Classifies the damping behavior into underdamped, critically damped, or overdamped.
+ */
+export declare function classifyDampingBehavior(dampingRatio: number): SpringDampingBehavior;
+/**
+ * Calculates instantaneous acceleration from the mass-spring-damper equation:
+ *   a = (k * (target - position) - c * velocity) / mass
+ */
+export declare function calculateSpringAcceleration(position: PhysicsValue, velocity: PhysicsValue, target: PhysicsValue, stiffness: number, damping: number, mass: number): PhysicsValue;
+/**
+ * Evaluates whether a spring has settled at equilibrium within rest thresholds.
+ */
+export declare function isSpringSettled(position: PhysicsValue, velocity: PhysicsValue, target: PhysicsValue, restDelta: number, restSpeed: number): boolean;
+/**
+ * Performs a single semi-implicit Euler integration step for a spring.
+ */
+export declare function integrateSpringEuler(currentPos: PhysicsValue, currentVel: PhysicsValue, target: PhysicsValue, stiffness: number, damping: number, mass: number, dt: number): {
+    position: PhysicsValue;
+    velocity: PhysicsValue;
+    acceleration: PhysicsValue;
+};
+/**
+ * High-precision RK4 step for spring integration.
+ */
+export declare function integrateSpringRK4(pos: PhysicsValue, vel: PhysicsValue, target: PhysicsValue, k: number, c: number, m: number, dt: number): {
+    position: PhysicsValue;
+    velocity: PhysicsValue;
+    acceleration: PhysicsValue;
+};

package/dist/core/physics/spring-presets.d.ts

@@ -0,0 +1,29 @@
+/**
+ * AF Motion — Standard Spring Presets & Registry Integration
+ *
+ * Defines and registers calibrated spring physics presets:
+ * Gentle, Smooth, Snappy, Bouncy, Stiff, Heavy, Soft, Elastic, Critical.
+ */
+import type { SpringPreset, SpringPresetName, AdvancedSpringConfig } from "./spring-types.js";
+export declare const SPRING_PRESETS: Record<SpringPresetName, SpringPreset>;
+/**
+ * Retrieves a registered spring preset by name or identifier.
+ */
+export declare function getSpringPreset(idOrName: string): SpringPreset | undefined;
+/**
+ * Returns a list of all 9 registered spring presets.
+ */
+export declare function listSpringPresets(): readonly SpringPreset[];
+/**
+ * Computes the critical damping coefficient for any given stiffness and mass:
+ *   c_crit = 2 * sqrt(k * m)
+ */
+export declare function calculateCriticalDamping(stiffness: number, mass: number): number;
+/**
+ * Default fallback spring parameters.
+ */
+export declare const DEFAULT_SPRING_CONFIG: Required<AdvancedSpringConfig>;
+/**
+ * Resolves a partial configuration or preset identifier into a complete AdvancedSpringConfig.
+ */
+export declare function resolveSpringConfig(presetOrConfig?: SpringPresetName | string | Partial<AdvancedSpringConfig>): Required<AdvancedSpringConfig>;

package/dist/core/physics/spring-simulation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AF Motion — Advanced Spring Physics Simulation Engine
+ *
+ * Implements independent, headless mass-spring-damper simulations with
+ * dynamic retargeting, velocity injection, damping regimes, and settling detection.
+ */
+import type { AdvancedSpringOptions, AdvancedSpringControls } from "./spring-types.js";
+/**
+ * Creates an independent, headless spring simulation instance.
+ */
+export declare function createSpringSimulation(options?: AdvancedSpringOptions): AdvancedSpringControls;