af-motion 0.0.0-stage → 1.0.0

package/dist/3d/physics/events.d.ts

@@ -0,0 +1,34 @@
+/**
+ * AF Motion — 3D Physics Event Bus & Observability
+ *
+ * Strongly-typed event emitter for physics world events, collision lifecycles,
+ * trigger encounters, and simulation metrics tracking with zero listener leaks.
+ */
+import type { PhysicsWorldEventMap } from "./types.js";
+export type PhysicsEventListener<K extends keyof PhysicsWorldEventMap> = (payload: PhysicsWorldEventMap[K]) => void;
+/**
+ * High-performance, leak-free event emitter for 3D physics worlds.
+ */
+export declare class PhysicsEventEmitter3D {
+    private readonly listeners;
+    /**
+     * Registers a listener for a physics event. Returns an unsubscribe function.
+     */
+    on<K extends keyof PhysicsWorldEventMap>(event: K, listener: PhysicsEventListener<K>): () => void;
+    /**
+     * Unregisters an existing listener.
+     */
+    off<K extends keyof PhysicsWorldEventMap>(event: K, listener: PhysicsEventListener<K>): void;
+    /**
+     * Dispatches an event to all registered listeners safely.
+     */
+    emit<K extends keyof PhysicsWorldEventMap>(event: K, payload: PhysicsWorldEventMap[K]): void;
+    /**
+     * Clears all registered listeners.
+     */
+    clear(): void;
+    /**
+     * Returns listener count for a specific event or in total.
+     */
+    listenerCount(event?: keyof PhysicsWorldEventMap): number;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * AF Motion — 3D Physics Architecture
+ *
+ * Dedicated framework-independent 3D physics engine foundation for rigid bodies,
+ * soft bodies, colliders, contact manifolds, constraints, and spatial queries.
+ */
+export * from "./types.js";
+export * from "./math.js";
+export * from "./material.js";
+export * from "./body/inertia.js";
+export * from "./collision/shapes.js";
+export * from "./collision/narrowphase.js";
+export * from "./collision/ccd.js";
+export * from "./spatial/spatial-hash.js";
+export * from "./events.js";
+export * from "./solver/types.js";
+export * from "./solver/integrators.js";
+export * from "./constraints/types.js";
+export * from "./constraints/advanced.js";
+export * from "./constraints/solver.js";
+export * from "./soft/types.js";
+export * from "./soft/pbd.js";
+export * from "./soft/soft-body.js";
+export * from "./soft/cloth.js";
+export * from "./soft/rope.js";
+export * from "./soft/collision.js";
+export * from "./soft/gpu.js";
+export * from "./world.js";
+export * from "./benchmark.js";

package/dist/3d/physics/material.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AF Motion — 3D Physics Materials & Combination Rules
+ *
+ * Reusable surface physical properties governing friction, restitution,
+ * damping, and density across collisions. Distinct from visual materials.
+ */
+import type { PhysicsMaterial } from "./types.js";
+/**
+ * Creates a validated PhysicsMaterial instance with sensible defaults.
+ */
+export declare function createPhysicsMaterial(options?: Partial<PhysicsMaterial>): PhysicsMaterial;
+/**
+ * Combines two surface friction values according to material combination rules.
+ */
+export declare function combineFriction(matA: PhysicsMaterial, matB: PhysicsMaterial): number;
+/**
+ * Combines two restitution coefficients according to material combination rules.
+ */
+export declare function combineRestitution(matA: PhysicsMaterial, matB: PhysicsMaterial): number;
+/**
+ * Curated standard physics material presets.
+ */
+export declare const MATERIAL_PRESETS: Record<string, Readonly<PhysicsMaterial>>;
+/**
+ * Retrieves a material preset by key name with fallback to default.
+ */
+export declare function getMaterialPreset(presetName: string): PhysicsMaterial;

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

@@ -0,0 +1,79 @@
+/**
+ * AF Motion — 3D Physics Mathematics & Spatial Transformations
+ *
+ * Framework-independent vector, quaternion, matrix, and transform operations.
+ * Designed with numerical precision safeguards, singularity protection, and zero runtime dependencies.
+ */
+import type { Vector3, Vector3Tuple, Quaternion, Transform3D, Matrix3, Matrix4, AABB3D } from "./types.js";
+export declare const EPSILON = 0.000001;
+export declare function isFiniteNumber(val: unknown): val is number;
+export declare function isFiniteVector3(v: unknown): v is Vector3;
+export declare function isFiniteQuaternion(q: unknown): q is Quaternion;
+export declare function clamp(val: number, min: number, max: number): number;
+export declare function roundPrecision(val: number, precision?: number): number;
+export declare function vec3(x?: number, y?: number, z?: number): Vector3;
+export declare function vec3Clone(v: Vector3): Vector3;
+export declare function vec3ToTuple(v: Vector3): Vector3Tuple;
+export declare function tupleToVec3(t: Vector3Tuple): Vector3;
+export declare function vec3Add(a: Vector3, b: Vector3): Vector3;
+export declare function vec3Sub(a: Vector3, b: Vector3): Vector3;
+export declare function vec3Scale(v: Vector3, s: number): Vector3;
+export declare function vec3Dot(a: Vector3, b: Vector3): number;
+export declare function vec3Cross(a: Vector3, b: Vector3): Vector3;
+export declare function vec3LengthSq(v: Vector3): number;
+export declare function vec3Length(v: Vector3): number;
+export declare function vec3Normalize(v: Vector3): Vector3;
+export declare function vec3SafeNormalize(v: Vector3, fallback?: Vector3): Vector3;
+export declare function vec3DistanceSq(a: Vector3, b: Vector3): number;
+export declare function vec3Distance(a: Vector3, b: Vector3): number;
+export declare function vec3Lerp(a: Vector3, b: Vector3, t: number): Vector3;
+export declare function vec3Min(a: Vector3, b: Vector3): Vector3;
+export declare function vec3Max(a: Vector3, b: Vector3): Vector3;
+export declare function vec3Equals(a: Vector3, b: Vector3, epsilon?: number): boolean;
+export declare function quat(x?: number, y?: number, z?: number, w?: number): Quaternion;
+export declare function quatIdentity(): Quaternion;
+export declare function quatClone(q: Quaternion): Quaternion;
+export declare function quatLengthSq(q: Quaternion): number;
+export declare function quatLength(q: Quaternion): number;
+export declare function quatNormalize(q: Quaternion): Quaternion;
+export declare function quatSafeNormalize(q: Quaternion, fallback?: Quaternion): Quaternion;
+export declare function quatMultiply(a: Quaternion, b: Quaternion): Quaternion;
+export declare function quatConjugate(q: Quaternion): Quaternion;
+export declare function quatInverse(q: Quaternion): Quaternion;
+export declare function quatDot(a: Quaternion, b: Quaternion): number;
+export declare function quatRotateVector(q: Quaternion, v: Vector3): Vector3;
+export declare function vec3TransformQuat(v: Vector3, q: Quaternion): Vector3;
+export declare function quatFromAxisAngle(axis: Vector3, angle: number): Quaternion;
+export declare function quatToAxisAngle(q: Quaternion): {
+    axis: Vector3;
+    angle: number;
+};
+export declare function quatFromEuler(x: number, y: number, z: number, order?: "XYZ" | "YXZ" | "ZXY"): Quaternion;
+export declare function quatToEuler(q: Quaternion, _order?: "XYZ"): Vector3;
+export declare function quatSlerp(a: Quaternion, b: Quaternion, t: number): Quaternion;
+export declare function quatEquals(a: Quaternion, b: Quaternion, epsilon?: number): boolean;
+export declare function mat3Identity(): Matrix3;
+export declare function mat3Diagonal(x: number, y: number, z: number): Matrix3;
+export declare function mat3FromQuaternion(q: Quaternion): Matrix3;
+export declare function mat3Multiply(a: Matrix3, b: Matrix3): Matrix3;
+export declare function mat3Transpose(m: Matrix3): Matrix3;
+export declare function mat3Invert(m: Matrix3): Matrix3;
+export declare function mat3TransformVector(m: Matrix3, v: Vector3): Vector3;
+export declare function mat4Identity(): Matrix4;
+export declare function mat4Compose(position: Vector3, rotation: Quaternion, scale?: Vector3): Matrix4;
+export declare function vec3TransformMat4(v: Vector3, m: Matrix4): Vector3;
+export declare function createTransform3D(position?: Vector3, rotation?: Quaternion, scale?: Vector3): Transform3D;
+export declare function cloneTransform3D(t: Transform3D): Transform3D;
+export declare function composeTransform3D(parent: Transform3D, child: Transform3D): Transform3D;
+export declare function invertTransform3D(t: Transform3D): Transform3D;
+export declare function localToWorldPoint(transform: Transform3D, localPoint: Vector3): Vector3;
+export declare function worldToLocalPoint(transform: Transform3D, worldPoint: Vector3): Vector3;
+export declare function localToWorldVector(transform: Transform3D, localVec: Vector3): Vector3;
+export declare function worldToLocalVector(transform: Transform3D, worldVec: Vector3): Vector3;
+export declare function createAABB3D(min?: Vector3, max?: Vector3): AABB3D;
+export declare function aabb3DFromMinMax(min: Vector3, max: Vector3): AABB3D;
+export declare function aabb3DContainsPoint(aabb: AABB3D, p: Vector3): boolean;
+export declare function aabb3DIntersects(a: AABB3D, b: AABB3D): boolean;
+export declare function aabb3DUnion(a: AABB3D, b: AABB3D): AABB3D;
+export declare function aabb3DEncapsulatePoint(aabb: AABB3D, p: Vector3): AABB3D;
+export declare function aabb3DTransform(aabb: AABB3D, transform: Transform3D): AABB3D;

package/dist/3d/physics/soft/cloth.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AF Motion — 3D Cloth Simulation Generator
+ *
+ * Generates grid-based deformable cloth meshes with structural, shear,
+ * and bending constraints, aerodynamic wind coupling, and tearable links.
+ */
+import type { SoftBodyState } from "../types.js";
+import type { ClothConfig } from "./types.js";
+/**
+ * Creates a production-grade 3D cloth simulation soft body.
+ */
+export declare function createCloth3D(config?: ClothConfig): SoftBodyState;

package/dist/3d/physics/soft/collision.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AF Motion — 3D Soft Body Collision Resolver
+ *
+ * Resolves contact and impulse momentum exchange between soft body particles
+ * and static geometry, ground planes, and dynamic/kinematic rigid bodies.
+ */
+import type { RigidBodyState } from "../types.js";
+import type { SoftBodyState } from "../types.js";
+/**
+ * Resolves collisions for all active soft bodies against rigid bodies and ground boundaries.
+ */
+export declare function resolveSoftBodyCollisions(softBodies: Iterable<SoftBodyState>, bodies: ReadonlyMap<string, RigidBodyState>, dt: number, groundY?: number, hasGround?: boolean): void;

package/dist/3d/physics/soft/gpu.d.ts

@@ -0,0 +1,19 @@
+/**
+ * AF Motion — 3D Soft Body GPU Acceleration Layer
+ *
+ * Integrates GPU compute assistance for large-scale cloth and soft-body
+ * simulations via WebGL2/WebGPU while providing 100% deterministic CPU fallback.
+ */
+import type { Vector3, RigidBodyState } from "../types.js";
+import type { SoftBodyState } from "../types.js";
+/**
+ * Checks whether GPU-assisted simulation compute is available in the current environment.
+ */
+export declare function isGPUAccelerationAvailable(): boolean;
+/**
+ * Simulates a soft body step using GPU compute if enabled and supported,
+ * otherwise transparently executing deterministic Position-Based Dynamics on CPU.
+ */
+export declare function simulateSoftBodyStep(softBody: SoftBodyState, dt: number, gravity: Vector3, iterations?: number, bodies?: ReadonlyMap<string, RigidBodyState>, windVector?: Vector3, onTear?: (softBodyId: string, pA: number, pB: number, strain: number) => void): {
+    usedGPU: boolean;
+};

package/dist/3d/physics/soft/pbd.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AF Motion — 3D Position-Based Dynamics (PBD & XPBD) Engine
+ *
+ * Implements numerical prediction, iterative non-linear constraint projection,
+ * XPBD compliance, volume preservation, shape matching, and velocity reconstruction.
+ */
+import type { Vector3, AABB3D, RigidBodyState } from "../types.js";
+import type { SoftBodyState } from "../types.js";
+/**
+ * Calculates the current closed mesh volume using the divergence theorem.
+ */
+export declare function computeMeshVolume(positions: Float32Array, indices: Uint32Array | Uint16Array | number[]): number;
+/**
+ * Computes an updated Axis-Aligned Bounding Box (AABB) for a soft body.
+ */
+export declare function computeSoftBodyAABB(positions: Float32Array, margin?: number): AABB3D;
+/**
+ * Solves one full Position-Based Dynamics time step for a soft body.
+ */
+export declare function stepPBD(softBody: SoftBodyState, dt: number, gravity: Vector3, iterations?: number, bodies?: ReadonlyMap<string, RigidBodyState>, windVector?: Vector3, onTear?: (softBodyId: string, pA: number, pB: number, strain: number) => void): void;

package/dist/3d/physics/soft/rope.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AF Motion — 3D Rope & Flexible Cable Generator
+ *
+ * Generates discretized rope, chain, and cable structures with structural
+ * stretch resistance, bending stiffness, endpoint pinning, and rigid-body coupling.
+ */
+import type { SoftBodyState } from "../types.js";
+import type { RopeConfig } from "./types.js";
+/**
+ * Creates a 3D simulated rope or flexible cable.
+ */
+export declare function createRope3D(config?: RopeConfig): SoftBodyState;
+/**
+ * Creates an articulated physical chain with rigid links and heavy segments.
+ */
+export declare function createChain3D(config?: RopeConfig): SoftBodyState;

package/dist/3d/physics/soft/soft-body.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AF Motion — Generic 3D Soft Body Generator
+ *
+ * Implements general volumetric deformable bodies, tetrahedral / polygonal
+ * surface meshes, volume conservation, and shape-matching preservation.
+ */
+import type { SoftBodyState } from "../types.js";
+import type { SoftBodyConfig } from "./types.js";
+/**
+ * Creates an independent 3D Soft Body instance.
+ */
+export declare function createSoftBody3D(config: SoftBodyConfig): SoftBodyState;

package/dist/3d/physics/soft/types.d.ts

@@ -0,0 +1,212 @@
+/**
+ * AF Motion — 3D Soft Body & PBD Types
+ *
+ * Type definitions for particle-based deformable bodies, Position-Based
+ * Dynamics (PBD / XPBD) constraints, cloth meshes, ropes, and flexible cables.
+ */
+import type { Vector3, PhysicsMaterial, Quaternion } from "../types.js";
+export type PBDConstraintType = "distance" | "structural" | "shear" | "bending" | "volume" | "shape-matching" | "attachment" | "pin";
+/**
+ * Base distance / edge constraint between two particles.
+ */
+export interface PBDDistanceConstraint {
+    type: "distance" | "structural" | "shear" | "bending";
+    /** Index of particle A. */
+    particleA: number;
+    /** Index of particle B. */
+    particleB: number;
+    /** Rest distance in world units. */
+    restLength: number;
+    /** XPBD compliance (inverse stiffness alpha). Default: 0 (rigid). */
+    compliance?: number;
+    /** Classical stiffness [0, 1]. Default: 1.0. */
+    stiffness?: number;
+    /** Internal damping coefficient. Default: 0.0. */
+    damping?: number;
+    /** Accumulated Lagrange multiplier for XPBD. */
+    multiplier?: number;
+    /** Whether this constraint can tear when stretched beyond threshold. */
+    tearable?: boolean;
+    /** Strain threshold for tearing ((d - d0) / d0). Default: 0.8 (80%). */
+    tearStrainThreshold?: number;
+    /** Whether this constraint has been torn/broken. */
+    torn?: boolean;
+}
+/**
+ * Closed mesh volume conservation constraint.
+ */
+export interface PBDVolumeConstraint {
+    type: "volume";
+    /** Triangle indices forming closed surface mesh [i0, j0, k0, i1, j1, k1, ...]. */
+    triangleIndices: Uint32Array | number[];
+    /** Rest volume in cubic units. */
+    restVolume: number;
+    /** Volume stiffness coefficient [0, 1]. */
+    stiffness?: number;
+    /** XPBD compliance for volume. */
+    compliance?: number;
+    /** Accumulated Lagrange multiplier. */
+    multiplier?: number;
+}
+/**
+ * Linear shape-matching constraint against rest coordinates.
+ */
+export interface PBDShapeMatchingConstraint {
+    type: "shape-matching";
+    /** Indices of particles involved in shape matching. */
+    particleIndices: number[];
+    /** Rest positions for each particle relative to rest center of mass. */
+    restOffsets: Float32Array;
+    /** Rest center of mass. */
+    restCenterOfMass: Vector3;
+    /** Shape-matching stiffness [0, 1]. */
+    stiffness: number;
+}
+/**
+ * Attachment constraint pinning a soft-body particle to a world position or rigid body.
+ */
+export interface PBDAttachmentConstraint {
+    type: "attachment";
+    /** Index of the soft-body particle. */
+    particleIndex: number;
+    /** Optional target rigid body ID. If undefined, attached to world space. */
+    targetBodyId?: string;
+    /** Local anchor on the rigid body, or world coordinate if targetBodyId is undefined. */
+    localPivot: Vector3;
+    /** Attachment stiffness [0, 1]. Default: 1.0. */
+    stiffness?: number;
+}
+/**
+ * Fixed pin constraint locking a particle in place.
+ */
+export interface PBDPinConstraint {
+    type: "pin";
+    /** Index of the pinned particle. */
+    particleIndex: number;
+    /** Fixed world position. */
+    position: Vector3;
+}
+export type PBDConstraint = PBDDistanceConstraint | PBDVolumeConstraint | PBDShapeMatchingConstraint | PBDAttachmentConstraint | PBDPinConstraint;
+export interface ParticleConfig {
+    position: Vector3;
+    mass?: number;
+    velocity?: Vector3;
+    pinned?: boolean;
+}
+export interface SoftBodyConfig {
+    id?: string;
+    /** Initial particle definitions or raw flat array [x0, y0, z0, ...]. */
+    particles: ParticleConfig[] | Float32Array;
+    /** Triangle indices for surface mesh [i0, j0, k0, ...]. */
+    indices?: Uint32Array | number[];
+    /** Custom PBD constraints. */
+    constraints?: PBDConstraint[];
+    /** Structural stiffness [0, 1]. Default: 0.9. */
+    stiffness?: number;
+    /** Internal velocity damping [0, 1]. Default: 0.05. */
+    damping?: number;
+    /** Volume preservation stiffness [0, 1]. Default: 0. */
+    volumeStiffness?: number;
+    /** Internal pneumatic pressure. Default: 0. */
+    pressure?: number;
+    /** Physics material (friction, restitution). */
+    material?: Partial<PhysicsMaterial>;
+    /** Whether any structural link can tear under strain. */
+    tearable?: boolean;
+    /** Strain threshold for tearing. Default: 0.8. */
+    tearStrainThreshold?: number;
+    /** Whether to enable GPU compute assistance where hardware allows. */
+    useGPU?: boolean;
+    /** User data. */
+    userData?: unknown;
+}
+export interface ClothConfig {
+    id?: string;
+    /** Total physical width in world units. Default: 2.0. */
+    width?: number;
+    /** Total physical height in world units. Default: 2.0. */
+    height?: number;
+    /** Number of grid segments along horizontal axis. Default: 10. */
+    segmentsX?: number;
+    /** Number of grid segments along vertical axis. Default: 10. */
+    segmentsY?: number;
+    /** Center position of the cloth mesh. Default: { x: 0, y: 2, z: 0 }. */
+    position?: Vector3;
+    /** Orientation plane or custom rotation quaternion. Default: "xy". */
+    orientation?: "xy" | "xz" | "yz" | Quaternion;
+    /** Total mass of the cloth in kg. Default: 1.0. */
+    mass?: number;
+    /** Structural spring stiffness [0, 1]. Default: 0.95. */
+    stiffness?: number;
+    /** Shear resistance stiffness [0, 1]. Default: 0.7. */
+    shearStiffness?: number;
+    /** Bending resistance stiffness [0, 1]. Default: 0.3. */
+    bendingStiffness?: number;
+    /** Velocity damping [0, 1]. Default: 0.02. */
+    damping?: number;
+    /** Array of specific particle indices to pin immovably. */
+    pinnedIndices?: number[];
+    /** Convenience: pin all 4 corner particles. */
+    pinCorners?: boolean;
+    /** Convenience: pin all particles along top edge. */
+    pinTopEdge?: boolean;
+    /** Wind aerodynamic forces. Default: false. */
+    windInteraction?: boolean | {
+        scale?: number;
+        dragCoefficient?: number;
+    };
+    /** Whether cloth can tear under extreme tensile strain. Default: false. */
+    tearable?: boolean;
+    /** Elongation strain threshold for tearing ((d - d0) / d0). Default: 1.0. */
+    tearStrainThreshold?: number;
+    /** Physics material. */
+    material?: Partial<PhysicsMaterial>;
+    /** Use GPU compute if available. */
+    useGPU?: boolean;
+    /** Custom user data. */
+    userData?: unknown;
+}
+export interface RopeConfig {
+    id?: string;
+    /** Total physical length of the rope in world units. Default: 5.0. */
+    length?: number;
+    /** Number of segments along the rope. Default: 20. */
+    segments?: number;
+    /** World start position. Default: { x: 0, y: 5, z: 0 }. */
+    startPosition?: Vector3;
+    /** Optional world end position. If omitted, hangs straight down along -Y. */
+    endPosition?: Vector3;
+    /** Direction vector if endPosition is omitted. Default: { x: 0, y: -1, z: 0 }. */
+    direction?: Vector3;
+    /** Total rope mass in kg. Default: 1.0. */
+    mass?: number;
+    /** Collision radius around particles in meters. Default: 0.05. */
+    radius?: number;
+    /** Stretch resistance stiffness [0, 1]. Default: 0.98. */
+    stiffness?: number;
+    /** Bending / straightness stiffness [0, 1]. Default: 0.4. */
+    bendingStiffness?: number;
+    /** Velocity damping [0, 1]. Default: 0.02. */
+    damping?: number;
+    /** Pin the start node in world space. Default: true. */
+    pinnedStart?: boolean;
+    /** Pin the end node in world space. Default: false. */
+    pinnedEnd?: boolean;
+    /** Attach start node to a dynamic/kinematic rigid body ID. */
+    attachStartToBodyId?: string;
+    /** Local attachment pivot on the start rigid body. */
+    attachStartPivot?: Vector3;
+    /** Attach end node to a dynamic/kinematic rigid body ID. */
+    attachEndToBodyId?: string;
+    /** Local attachment pivot on the end rigid body. */
+    attachEndPivot?: Vector3;
+    /** Physics material. */
+    material?: Partial<PhysicsMaterial>;
+    /** Tear threshold for breaking under extreme tension. */
+    tearable?: boolean;
+    tearStrainThreshold?: number;
+    /** Use GPU compute if available. */
+    useGPU?: boolean;
+    /** Custom user data. */
+    userData?: unknown;
+}

package/dist/3d/physics/solver/integrators.d.ts

@@ -0,0 +1,25 @@
+/**
+ * AF Motion — 3D Physics Solvers & Numerical Integrators
+ *
+ * Implements Symplectic Euler, Verlet, and RK4 time integrators,
+ * along with impulse-based collision resolution and constraint satisfaction.
+ * Incorporates true 3D rotational inertia tensors, static/dynamic Coulomb friction,
+ * resting velocity thresholds for stable stacking, and kinematic body support.
+ */
+import type { PhysicsIntegrator3D, CollisionSolver3D, ConstraintSolver3D } from "./types.js";
+import type { RigidBodyState, CollisionManifold3D, Constraint3D, Vector3 } from "../types.js";
+export declare class SymplecticEulerIntegrator3D implements PhysicsIntegrator3D {
+    readonly name = "symplectic-euler";
+    integrate(bodies: readonly RigidBodyState[], dt: number, gravity: Vector3): void;
+}
+export declare class ImpulseCollisionSolver3D implements CollisionSolver3D {
+    readonly name = "impulse-solver";
+    private readonly baumgarte;
+    private readonly slop;
+    private readonly restingVelocityThreshold;
+    resolveCollisions(manifolds: readonly CollisionManifold3D[], bodies: ReadonlyMap<string, RigidBodyState>, iterations: number, dt: number): void;
+}
+export declare class BasicConstraintSolver3D implements ConstraintSolver3D {
+    readonly name = "basic-constraint-solver";
+    solveConstraints(constraints: readonly Constraint3D[], bodies: ReadonlyMap<string, RigidBodyState>, iterations: number, _dt: number): void;
+}

package/dist/3d/physics/solver/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * AF Motion — 3D Physics Solver & Integrator Contracts
+ *
+ * Interfaces for numerical time integration, impulse-based collision resolution,
+ * and constraint satisfaction.
+ */
+import type { RigidBodyState, CollisionManifold3D, Constraint3D, Vector3 } from "../types.js";
+/**
+ * Interface for time integration of velocities, positions, and orientations.
+ */
+export interface PhysicsIntegrator3D {
+    readonly name: string;
+    integrate(bodies: readonly RigidBodyState[], dt: number, gravity: Vector3): void;
+}
+/**
+ * Interface for collision impulse and position correction solvers.
+ */
+export interface CollisionSolver3D {
+    readonly name: string;
+    resolveCollisions(manifolds: readonly CollisionManifold3D[], bodies: ReadonlyMap<string, RigidBodyState>, iterations: number, dt: number): void;
+}
+/**
+ * Interface for physical joint and constraint solvers.
+ */
+export interface ConstraintSolver3D {
+    readonly name: string;
+    solveConstraints(constraints: readonly Constraint3D[], bodies: ReadonlyMap<string, RigidBodyState>, iterations: number, dt: number): void;
+}

package/dist/3d/physics/spatial/spatial-hash.d.ts

@@ -0,0 +1,51 @@
+/**
+ * AF Motion — 3D Spatial Hashing & Broad-Phase Query System
+ *
+ * High-performance 3D spatial indexing for fast collision pair pruning,
+ * AABB volume queries, sphere proximity testing, and raycasting.
+ */
+import type { Collider3D, AABB3D, Ray3D, RayHit3D, SpatialFilter3D, Transform3D, Vector3 } from "../types.js";
+export interface SpatialQuery3DOptions {
+    cellSize?: number;
+}
+export interface SpatialQuery3D {
+    register(collider: Collider3D): void;
+    unregister(colliderId: string): void;
+    update(collider: Collider3D): void;
+    getPotentialPairs(): Array<[Collider3D, Collider3D]>;
+    queryAABB(aabb: AABB3D, filter?: SpatialFilter3D): Collider3D[];
+    querySphere(center: Vector3, radius: number, filter?: SpatialFilter3D): Collider3D[];
+    raycast(ray: Ray3D, filter?: SpatialFilter3D, getBodyTransform?: (bodyId?: string) => Transform3D): RayHit3D[];
+    raycastAny(ray: Ray3D, filter?: SpatialFilter3D, getBodyTransform?: (bodyId?: string) => Transform3D): boolean;
+    clear(): void;
+    getColliderCount(): number;
+}
+/**
+ * 3D Spatial Hash Broad-phase Grid.
+ */
+export declare class SpatialHash3D implements SpatialQuery3D {
+    private readonly cellSize;
+    private readonly invCellSize;
+    private readonly cells;
+    private readonly colliderToCells;
+    private readonly colliders;
+    private readonly globalColliders;
+    constructor(options?: SpatialQuery3DOptions);
+    private hashCoords;
+    private getCellsForAABB;
+    register(collider: Collider3D): void;
+    unregister(colliderId: string): void;
+    update(collider: Collider3D): void;
+    getPotentialPairs(): Array<[Collider3D, Collider3D]>;
+    queryAABB(aabb: AABB3D, filter?: SpatialFilter3D): Collider3D[];
+    querySphere(center: Vector3, radius: number, filter?: SpatialFilter3D): Collider3D[];
+    raycast(ray: Ray3D, filter?: SpatialFilter3D, getBodyTransform?: (bodyId?: string) => Transform3D): RayHit3D[];
+    raycastAny(ray: Ray3D, filter?: SpatialFilter3D, getBodyTransform?: (bodyId?: string) => Transform3D): boolean;
+    private matchesFilter;
+    clear(): void;
+    getColliderCount(): number;
+}
+/**
+ * Creates an extensible 3D spatial query / broad-phase acceleration structure.
+ */
+export declare function createSpatialQuery3D(options?: SpatialQuery3DOptions): SpatialQuery3D;