af-motion 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,265 @@
+/**
+ * AF Motion — Physics-Based Motion Composition Type System
+ *
+ * Defines contracts for multi-system physics composition, reusable behaviors,
+ * multi-body orchestration, deterministic lifecycle controls, and choreography integration.
+ */
+import type { PhysicsValue, PhysicsSimulationContext, PhysicsLifecycleState } from "./types.js";
+import type { CollisionBody, CollisionBodyConfig, CollisionConstraint, CollisionConstraintConfig, CollisionContact, CollisionWorld } from "./collision-types.js";
+/**
+ * Supported physics behavior types.
+ */
+export type PhysicsBehaviorType = "spring" | "inertia" | "gravity" | "bounded" | "collision" | "constrained" | "hybrid" | "multi-force";
+/**
+ * Context provided to a physics behavior during each simulation sub-step.
+ */
+export interface BehaviorExecutionContext {
+    readonly body: CollisionBody;
+    readonly allBodies: ReadonlyMap<string, CollisionBody>;
+    readonly dt: number;
+    readonly time: number;
+    readonly tick: number;
+    readonly world?: CollisionWorld;
+}
+/**
+ * Core interface for a modular physics motion behavior.
+ */
+export interface PhysicsBehavior {
+    /**
+     * Unique identifier for the behavior instance.
+     */
+    readonly id: string;
+    /**
+     * Behavioral classification.
+     */
+    readonly type: PhysicsBehaviorType;
+    /**
+     * Execution priority order (lower runs earlier; default: 0).
+     */
+    readonly priority?: number;
+    /**
+     * IDs of bodies this behavior applies to. If empty or omitted, applies to all dynamic bodies.
+     */
+    readonly targetBodyIds?: readonly string[];
+    /**
+     * Invoked on each discrete simulation sub-step.
+     */
+    step(context: BehaviorExecutionContext): void;
+    /**
+     * Evaluates whether this behavior has settled to rest.
+     */
+    isSettled?(body: CollisionBody): boolean;
+    /**
+     * Cleans up resources when the behavior is detached or disposed.
+     */
+    dispose?(): void;
+}
+/**
+ * Multi-body composition snapshot state.
+ */
+export interface PhysicsCompositionState {
+    readonly time: number;
+    readonly tick: number;
+    readonly lifecycle: PhysicsLifecycleState;
+    readonly settled: boolean;
+    readonly bodies: ReadonlyMap<string, CollisionBody>;
+    readonly contacts: readonly CollisionContact[];
+    readonly activeBehaviors: readonly string[];
+}
+/**
+ * Listener callback signatures for composition events.
+ */
+export type PhysicsCompositionUpdateListener = (state: PhysicsCompositionState) => void;
+export type PhysicsCompositionSettleListener = (state: PhysicsCompositionState) => void;
+export type PhysicsCompositionCompleteListener = (state: PhysicsCompositionState) => void;
+/**
+ * Configuration options for creating a unified PhysicsComposition.
+ */
+export interface PhysicsCompositionConfig {
+    /**
+     * Optional custom identifier for the composition instance.
+     */
+    id?: string;
+    /**
+     * Global simulation fixed timestep in seconds. Default: 1/60.
+     */
+    timestep?: number;
+    /**
+     * Maximum sub-steps per frame to prevent the spiral of death. Default: 10.
+     */
+    maxSubSteps?: number;
+    /**
+     * Global time scale multiplier. Default: 1.0.
+     */
+    timeScale?: number;
+    /**
+     * Global gravity vector applied to dynamic bodies.
+     */
+    gravity?: PhysicsValue;
+    /**
+     * Global bounding box region for all bodies.
+     */
+    bounds?: {
+        min: PhysicsValue;
+        max: PhysicsValue;
+    };
+    /**
+     * Initial rigid bodies participating in the composition.
+     */
+    bodies?: CollisionBodyConfig[];
+    /**
+     * Initial kinematic constraints.
+     */
+    constraints?: CollisionConstraintConfig[];
+    /**
+     * Initial modular motion behaviors.
+     */
+    behaviors?: PhysicsBehavior[];
+    /**
+     * Whether to automatically start simulation on creation. Default: false.
+     */
+    autoStart?: boolean;
+    /**
+     * Respect system reduced motion preferences. Default: true.
+     */
+    respectReducedMotion?: boolean;
+}
+/**
+ * Unified control interface for a multi-system physics composition.
+ */
+export interface PhysicsCompositionControls {
+    /**
+     * Starts simulation progression.
+     */
+    start(): void;
+    /**
+     * Pauses simulation progression.
+     */
+    pause(): void;
+    /**
+     * Resumes paused simulation.
+     */
+    resume(): void;
+    /**
+     * Stops simulation progression.
+     */
+    stop(): void;
+    /**
+     * Resets simulation coordinates and time to initial state.
+     */
+    reset(): void;
+    /**
+     * Advances simulation deterministically by deltaTime seconds.
+     */
+    step(deltaTime?: number): PhysicsCompositionState;
+    /**
+     * Releases all resources, behaviors, listeners, and bodies.
+     */
+    dispose(): void;
+    /**
+     * Returns a snapshot of the current composition state.
+     */
+    getState(): PhysicsCompositionState;
+    /**
+     * Returns a snapshot of the simulation context.
+     */
+    getContext(): PhysicsSimulationContext;
+    /**
+     * Dynamically adds a new body to the composition.
+     */
+    addBody(config: CollisionBodyConfig): CollisionBody;
+    /**
+     * Removes a body by ID.
+     */
+    removeBody(id: string): boolean;
+    /**
+     * Retrieves a body by ID.
+     */
+    getBody(id: string): CollisionBody | undefined;
+    /**
+     * Returns all participating bodies.
+     */
+    getBodies(): CollisionBody[];
+    /**
+     * Dynamically adds a behavior to the composition.
+     */
+    addBehavior(behavior: PhysicsBehavior): void;
+    /**
+     * Removes a behavior by ID.
+     */
+    removeBehavior(id: string): boolean;
+    /**
+     * Returns all active behaviors.
+     */
+    getBehaviors(): PhysicsBehavior[];
+    /**
+     * Dynamically adds a physical constraint.
+     */
+    addConstraint(config: CollisionConstraintConfig): CollisionConstraint;
+    /**
+     * Removes a constraint by ID.
+     */
+    removeConstraint(id: string): boolean;
+    /**
+     * Returns all active constraints.
+     */
+    getConstraints(): CollisionConstraint[];
+    /**
+     * Accesses the underlying collision world instance.
+     */
+    getWorld(): CollisionWorld;
+    /**
+     * Returns whether all active behaviors and bodies are settled at rest.
+     */
+    isSettled(): boolean;
+    /**
+     * Returns whether the composition is currently active and running.
+     */
+    isRunning(): boolean;
+    /**
+     * Returns whether the composition is paused.
+     */
+    isPaused(): boolean;
+    /**
+     * Returns whether the composition has been disposed.
+     */
+    isDisposed(): boolean;
+    /**
+     * Subscribes to step updates. Returns an unsubscribe function.
+     */
+    onUpdate(listener: PhysicsCompositionUpdateListener): () => void;
+    /**
+     * Subscribes to settle events. Returns an unsubscribe function.
+     */
+    onSettle(listener: PhysicsCompositionSettleListener): () => void;
+    /**
+     * Subscribes to completion events. Returns an unsubscribe function.
+     */
+    onComplete(listener: PhysicsCompositionCompleteListener): () => void;
+}
+/**
+ * Standard composition recipe descriptor.
+ */
+export interface PhysicsCompositionRecipe {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    create(overrides?: Partial<PhysicsCompositionConfig>): PhysicsCompositionConfig;
+}
+/**
+ * Options for adapting a physics composition into a choreography sequence or participant.
+ */
+export interface PhysicsChoreographyOptions {
+    /**
+     * Label for choreography tracking.
+     */
+    label?: string;
+    /**
+     * Start delay in milliseconds before the physics composition begins advancing. Default: 0.
+     */
+    delay?: number;
+    /**
+     * Optional maximum run duration in milliseconds before forcing completion.
+     */
+    timeout?: number;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * AF Motion — Physics Composition Validation & Safety Engine
+ *
+ * Enforces consistency across multi-body setups, constraints, behaviors, and timings.
+ * Prevents circular dependencies, conflicting ownership, and invalid body references.
+ */
+import type { PhysicsCompositionConfig } from "./composition-types.js";
+import type { PhysicsValidationResult } from "./validation.js";
+/**
+ * Thrown when a physics composition configuration is invalid.
+ */
+export declare class PhysicsCompositionValidationError extends Error {
+    readonly errors: readonly string[];
+    constructor(message: string, errors?: readonly string[]);
+}
+/**
+ * Thrown when a composition contains conflicting systems or mutually exclusive constraints.
+ */
+export declare class PhysicsCompositionConflictError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates a complete PhysicsCompositionConfig object.
+ */
+export declare function validatePhysicsCompositionConfig(config: unknown): PhysicsValidationResult;
+/**
+ * Asserts that a PhysicsCompositionConfig is valid or throws PhysicsCompositionValidationError.
+ */
+export declare function assertValidPhysicsCompositionConfig(config: unknown): asserts config is PhysicsCompositionConfig;
+/**
+ * Safely corrects an invalid or incomplete PhysicsCompositionConfig to valid defaults.
+ */
+export declare function correctPhysicsCompositionConfig(config?: Partial<PhysicsCompositionConfig>): PhysicsCompositionConfig;

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

@@ -0,0 +1,37 @@
+/**
+ * AF Motion — Foundational & Advanced Motion Physics Engine
+ *
+ * Public modular exports for physics simulations, deterministic stepping,
+ * vector mathematics, validation, presets, lifecycle controls,
+ * advanced mass-spring-damper engines, inertia/gravity/drag engines,
+ * collision/constraint dynamics, and multi-system motion composition.
+ */
+export * from "./types.js";
+export * from "./math.js";
+export * from "./validation.js";
+export * from "./presets.js";
+export * from "./stepper.js";
+export * from "./simulation.js";
+export * from "./spring-types.js";
+export * from "./spring-math.js";
+export * from "./spring-presets.js";
+export * from "./spring-validation.js";
+export * from "./spring-simulation.js";
+export * from "./spring-animation.js";
+export * from "./inertia-types.js";
+export * from "./inertia-math.js";
+export * from "./inertia-presets.js";
+export * from "./inertia-validation.js";
+export * from "./inertia-simulation.js";
+export * from "./inertia-animation.js";
+export * from "./collision-types.js";
+export * from "./collision-detection.js";
+export * from "./collision-response.js";
+export * from "./collision-constraints.js";
+export * from "./collision-world.js";
+export * from "./composition-types.js";
+export * from "./composition-validation.js";
+export * from "./composition-behaviors.js";
+export * from "./composition-engine.js";
+export * from "./composition-recipes.js";
+export * from "./composition-choreography.js";

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

@@ -0,0 +1,11 @@
+/**
+ * AF Motion — Shared RAF Animated Inertia Integration
+ *
+ * Integrates Advanced Inertia, Momentum, Friction & Gravity Physics with the library's
+ * shared animation frame scheduler (subscribeAnimationFrames), honoring reduced-motion accessibility.
+ */
+import type { AdvancedInertiaAnimationOptions, AdvancedInertiaAnimationControls } from "./inertia-types.js";
+/**
+ * Animates an advanced inertia / momentum physics simulation using the shared RAF frame scheduler.
+ */
+export declare function animateAdvancedInertia(options: AdvancedInertiaAnimationOptions): AdvancedInertiaAnimationControls;

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

@@ -0,0 +1,56 @@
+/**
+ * AF Motion — Inertia, Momentum, Friction & Gravity Mathematical Model
+ *
+ * Implements force composition, multi-model friction (viscous, kinetic, quadratic drag),
+ * gravitational acceleration, momentum, and terminal velocity across 1D, 2D, and 3D.
+ */
+import type { PhysicsValue } from "./types.js";
+/**
+ * Computes momentum vector or scalar: p = m * v.
+ */
+export declare function calculateMomentum(velocity: PhysicsValue, mass: number): PhysicsValue;
+/**
+ * Computes kinetic energy: E_k = 0.5 * m * |v|^2.
+ */
+export declare function calculateKineticEnergy(velocity: PhysicsValue, mass: number): number;
+/**
+ * Computes the normalized unit direction of a velocity vector.
+ * Returns a zero vector if speed is zero.
+ */
+export declare function velocityDirection(velocity: PhysicsValue): PhysicsValue;
+/**
+ * Computes total net force acting on a body from all active components:
+ *   F_net = F_gravity + F_friction + F_kinetic + F_drag + F_external
+ */
+export declare function calculateNetForce(velocity: PhysicsValue, mass: number, gravity: PhysicsValue, friction: number, linearFriction: number, drag: number, externalForce: PhysicsValue): PhysicsValue;
+/**
+ * Computes instantaneous acceleration: a = F_net / m.
+ */
+export declare function calculateInertiaAcceleration(velocity: PhysicsValue, mass: number, gravity: PhysicsValue, friction: number, linearFriction: number, drag: number, externalForce: PhysicsValue): {
+    acceleration: PhysicsValue;
+    netForce: PhysicsValue;
+};
+/**
+ * Applies terminal velocity limit if speed exceeds maximum allowed threshold.
+ */
+export declare function applyTerminalVelocity(velocity: PhysicsValue, terminalVelocity?: number): PhysicsValue;
+/**
+ * Checks whether a body has decelerated to rest.
+ */
+export declare function isInertiaSettled(velocity: PhysicsValue, gravity: PhysicsValue, externalForce: PhysicsValue, minVelocity: number): boolean;
+/**
+ * Clamps coordinates within optional spatial bounds [min, max], zeroing velocity on collided axes.
+ */
+export declare function applyPositionBounds(position: PhysicsValue, velocity: PhysicsValue, minBound?: PhysicsValue, maxBound?: PhysicsValue): {
+    position: PhysicsValue;
+    velocity: PhysicsValue;
+};
+/**
+ * Performs a single semi-implicit Euler integration step for inertia simulation.
+ */
+export declare function integrateInertiaStep(pos: PhysicsValue, vel: PhysicsValue, mass: number, gravity: PhysicsValue, friction: number, linearFriction: number, drag: number, externalForce: PhysicsValue, terminalVelocity: number | undefined, dt: number): {
+    position: PhysicsValue;
+    velocity: PhysicsValue;
+    acceleration: PhysicsValue;
+    netForce: PhysicsValue;
+};

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

@@ -0,0 +1,25 @@
+/**
+ * AF Motion — Inertia, Momentum, Friction & Gravity Presets
+ *
+ * Defines and registers standard presets for inertia simulations:
+ * Natural, Heavy, Light, High Friction, Low Friction, Air Resistance,
+ * Gravity, Zero Gravity, and Fast Deceleration.
+ */
+import type { InertiaPreset, InertiaPresetName, AdvancedInertiaConfig } from "./inertia-types.js";
+export declare const INERTIA_PRESETS: Record<InertiaPresetName, InertiaPreset>;
+/**
+ * Retrieves a registered inertia preset by name or identifier.
+ */
+export declare function getInertiaPreset(idOrName: string): InertiaPreset | undefined;
+/**
+ * Returns a list of all 9 registered inertia presets.
+ */
+export declare function listInertiaPresets(): readonly InertiaPreset[];
+/**
+ * Default fallback inertia parameters.
+ */
+export declare const DEFAULT_INERTIA_CONFIG: Required<AdvancedInertiaConfig>;
+/**
+ * Resolves a partial configuration or preset identifier into a complete AdvancedInertiaConfig.
+ */
+export declare function resolveInertiaConfig(presetOrConfig?: InertiaPresetName | string | Partial<AdvancedInertiaConfig>): Required<AdvancedInertiaConfig>;

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

@@ -0,0 +1,11 @@
+/**
+ * AF Motion — Advanced Inertia, Momentum, Friction & Gravity Simulation Engine
+ *
+ * Implements headless momentum simulations combining mass, multi-model friction,
+ * aerodynamic drag, directional gravity, external forces, and impulses.
+ */
+import type { AdvancedInertiaOptions, AdvancedInertiaControls } from "./inertia-types.js";
+/**
+ * Creates an independent, headless inertia and momentum simulation instance.
+ */
+export declare function createInertiaSimulation(options?: AdvancedInertiaOptions): AdvancedInertiaControls;