@holoscript/engine 6.0.3 → 6.0.4

package/dist/index-BHySEPX7.d.cts

@@ -0,0 +1,2921 @@
+import { B as BodyType, C as CollisionShape, a as IRigidBodyConfig, I as IVector3, b as IQuaternion, c as IPhysicsMaterial, d as ICollisionFilter, e as IRigidBodyState, f as ITransform, g as IPhysicsWorld, h as IPhysicsWorldConfig, i as Constraint, j as ICollisionEvent, k as ITriggerEvent, l as IRay, m as IRaycastOptions, n as IRaycastHit, o as IOverlapResult, p as ISoftBodyConfig, q as ISDFCollider, r as ISoftBodyState, s as IConstraintColoring, P as ParticleType, t as IParticleAttributes, u as COLLISION_GROUPS, v as IBallConstraint, w as IBoxShape, x as ICapsuleShape, y as ICompoundShape, z as IConeConstraint, A as IConeShape, D as IConvexShape, E as ICylinderShape, F as IDistanceConstraint, G as IFixedConstraint, H as IGeneric6DOFConstraint, J as IHeightfieldShape, K as IHingeConstraint, L as IMeshShape, M as IPBDAttachmentConstraint, N as IPBDBendingConstraint, O as IPBDCollisionConstraint, Q as IPBDDistanceConstraint, R as IPBDVolumeConstraint, S as ISliderConstraint, T as ISpatialHashGrid, U as ISphereShape, V as ISpringConstraint, W as PBDConstraint, X as PBDConstraintType, Y as PHYSICS_DEFAULTS, Z as SOFT_BODY_PRESETS, _ as SoftBodyPreset, $ as boxShape, a0 as capsuleShape, a1 as defaultMaterial, a2 as defaultTransform, a3 as dynamicBody, a4 as identityQuaternion, a5 as kinematicBody, a6 as sphereShape, a7 as staticBody, a8 as validateBodyConfig, a9 as zeroVector } from './PhysicsTypes-Dw6_oXuD.cjs';
+import { WeatherBlackboardState, VRHand } from '@holoscript/core';
+
+/**
+ * PhysicsBody.ts
+ *
+ * Rigid body implementation for the HoloScript physics system.
+ *
+ * @module physics
+ */
+
+/**
+ * Rigid body class for physics simulation
+ */
+declare class RigidBody {
+    readonly id: string;
+    readonly type: BodyType;
+    readonly shape: CollisionShape;
+    private _position;
+    private _rotation;
+    private _linearVelocity;
+    private _angularVelocity;
+    private _isSleeping;
+    private _isActive;
+    private _mass;
+    private _inverseMass;
+    private _inertia;
+    private _inverseInertia;
+    private _material;
+    private _filter;
+    private _linearDamping;
+    private _angularDamping;
+    private _gravityScale;
+    private _ccd;
+    private _userData;
+    private _force;
+    private _torque;
+    private _sleepTimer;
+    constructor(config: IRigidBodyConfig);
+    get position(): IVector3;
+    set position(value: IVector3);
+    get rotation(): IQuaternion;
+    set rotation(value: IQuaternion);
+    get linearVelocity(): IVector3;
+    set linearVelocity(value: IVector3);
+    get angularVelocity(): IVector3;
+    set angularVelocity(value: IVector3);
+    get isSleeping(): boolean;
+    get isActive(): boolean;
+    set isActive(value: boolean);
+    get mass(): number;
+    get inverseMass(): number;
+    get material(): IPhysicsMaterial;
+    set material(value: IPhysicsMaterial);
+    get filter(): ICollisionFilter;
+    set filter(value: ICollisionFilter);
+    get gravityScale(): number;
+    set gravityScale(value: number);
+    get ccd(): boolean;
+    set ccd(value: boolean);
+    get userData(): unknown;
+    set userData(value: unknown);
+    /**
+     * Apply a force at the center of mass
+     */
+    applyForce(force: IVector3): void;
+    /**
+     * Apply a force at a world point
+     */
+    applyForceAtPoint(force: IVector3, worldPoint: IVector3): void;
+    /**
+     * Apply an impulse at the center of mass
+     */
+    applyImpulse(impulse: IVector3): void;
+    /**
+     * Apply an impulse at a world point
+     */
+    applyImpulseAtPoint(impulse: IVector3, worldPoint: IVector3): void;
+    /**
+     * Apply a torque
+     */
+    applyTorque(torque: IVector3): void;
+    /**
+     * Apply a torque impulse
+     */
+    applyTorqueImpulse(impulse: IVector3): void;
+    /**
+     * Clear accumulated forces
+     */
+    clearForces(): void;
+    /**
+     * Integrate forces (semi-implicit Euler)
+     */
+    integrateForces(dt: number, gravity: IVector3): void;
+    /**
+     * Integrate velocities (update position/rotation)
+     */
+    integrateVelocities(dt: number): void;
+    /**
+     * Wake up the body
+     */
+    wakeUp(): void;
+    /**
+     * Try to put the body to sleep
+     */
+    updateSleep(dt: number): void;
+    /**
+     * Get current state
+     */
+    getState(): IRigidBodyState;
+    /**
+     * Get transform
+     */
+    getTransform(): ITransform;
+    /**
+     * Set transform directly (for kinematic bodies)
+     */
+    setTransform(transform: ITransform): void;
+    /**
+     * Get accumulated force
+     */
+    getForce(): IVector3;
+    /**
+     * Get accumulated torque
+     */
+    getTorque(): IVector3;
+    /**
+     * Calculate inertia tensor for the shape
+     */
+    private calculateInertia;
+    /**
+     * Clamp velocity magnitude
+     */
+    private clampVelocity;
+    /**
+     * Calculate vector length
+     */
+    private vectorLength;
+    /**
+     * Normalize quaternion
+     */
+    private normalizeQuaternion;
+    /**
+     * Test collision filter
+     */
+    canCollideWith(other: RigidBody): boolean;
+}
+
+/**
+ * PhysicsWorldImpl.ts
+ *
+ * Physics world implementation with broadphase collision detection,
+ * constraint solving, and spatial queries.
+ *
+ * @module physics
+ */
+
+/**
+ * Physics world implementation
+ */
+declare class PhysicsWorldImpl implements IPhysicsWorld {
+    private config;
+    private bodies;
+    private constraints;
+    private collisionEvents;
+    private triggerEvents;
+    private islandDetector;
+    private accumulator;
+    private bodiesArray;
+    private collisionPairs;
+    private activeContacts;
+    constructor(config?: IPhysicsWorldConfig);
+    setGravity(gravity: IVector3): void;
+    getGravity(): IVector3;
+    createBody(config: IRigidBodyConfig): string;
+    removeBody(id: string): boolean;
+    getBody(id: string): IRigidBodyState | undefined;
+    getAllBodies(): IRigidBodyState[];
+    setPosition(id: string, position: IVector3): void;
+    setRotation(id: string, rotation: IQuaternion): void;
+    setTransform(id: string, transform: ITransform): void;
+    setLinearVelocity(id: string, velocity: IVector3): void;
+    setAngularVelocity(id: string, velocity: IVector3): void;
+    applyForce(id: string, force: IVector3, worldPoint?: IVector3): void;
+    applyImpulse(id: string, impulse: IVector3, worldPoint?: IVector3): void;
+    applyTorque(id: string, torque: IVector3): void;
+    applyTorqueImpulse(id: string, impulse: IVector3): void;
+    createConstraint(constraint: Constraint): string;
+    removeConstraint(id: string): boolean;
+    setConstraintEnabled(id: string, enabled: boolean): void;
+    step(deltaTime: number): void;
+    private fixedStep;
+    private broadphase;
+    private narrowphase;
+    private checkCollision;
+    /**
+     * Optimized sphere-sphere collision (analytic, O(1)).
+     */
+    private checkSphereSphere;
+    /**
+     * GJK/EPA narrowphase collision for arbitrary convex shape pairs.
+     *
+     * 1. Run GJK to determine overlap (boolean).
+     * 2. If overlapping, run EPA to get contact normal + penetration depth.
+     * 3. Compute an approximate contact point on the surface between the two shapes.
+     */
+    private checkGJKEPA;
+    private resolveCollision;
+    private solveConstraints;
+    private solveConstraint;
+    private detectIslands;
+    getContacts(): ICollisionEvent[];
+    getTriggers(): ITriggerEvent[];
+    raycast(ray: IRay, options?: IRaycastOptions): IRaycastHit[];
+    raycastClosest(ray: IRay, options?: IRaycastOptions): IRaycastHit | null;
+    private raycastBody;
+    private calculateAABBHitNormal;
+    sphereOverlap(center: IVector3, radius: number, filter?: ICollisionFilter): IOverlapResult[];
+    boxOverlap(center: IVector3, halfExtents: IVector3, _rotation?: IQuaternion, filter?: ICollisionFilter): IOverlapResult[];
+    private getBodyAABB;
+    private aabbOverlap;
+    private getContactKey;
+    private filterMatches;
+    dispose(): void;
+}
+/**
+ * Create a physics world
+ */
+declare function createPhysicsWorld(config?: IPhysicsWorldConfig): IPhysicsWorld;
+
+declare class IslandDetector {
+    private bodies;
+    private connections;
+    /**
+     * Reset the detector state
+     */
+    reset(): void;
+    /**
+     * Add a body to the graph
+     */
+    addBody(id: string): void;
+    /**
+     * Add a connection (collision or constraint) between bodies
+     */
+    addConnection(bodyA: string, bodyB: string): void;
+    /**
+     * Detect islands using a Disjoint Set Union (DSU) or BFS
+     */
+    detectIslands(): string[][];
+}
+
+/**
+ * PBDSolver.ts
+ *
+ * GPU Position-Based Dynamics solver using WebGPU compute shaders.
+ * Implements soft-body physics with distance, volume, bending, collision,
+ * and attachment constraints solved in parallel via graph coloring.
+ *
+ * Pipeline per frame:
+ *   [1] Apply external forces (gravity, wind)
+ *   [2] Predict new positions (Euler integration)
+ *   [3] Solve constraints (parallel Gauss-Seidel, N iterations)
+ *       ├─ Distance constraints (edges maintain rest length)
+ *       ├─ Volume constraints (tetrahedra maintain rest volume)
+ *       ├─ Bending constraints (adjacent triangles resist folding)
+ *       ├─ Collision constraints (SDF-based penetration resolution)
+ *       └─ Attachment constraints (pinned vertices stay fixed)
+ *   [4] Update velocities from position delta
+ *   [5] Apply damping
+ *   [6] Recompute normals
+ *
+ * @module physics
+ */
+
+/**
+ * WGSL: Apply external forces and predict positions via semi-implicit Euler
+ */
+declare const PBD_PREDICT_SHADER = "\nstruct SimParams {\n  gravity: vec3f,\n  dt: f32,\n  wind: vec3f,\n  damping: f32,\n  numVertices: u32,\n  padding: vec3u,\n}\n\n@group(0) @binding(0) var<storage, read_write> positions: array<f32>;\n@group(0) @binding(1) var<storage, read_write> velocities: array<f32>;\n@group(0) @binding(2) var<storage, read_write> predicted: array<f32>;\n@group(0) @binding(3) var<storage, read> masses: array<f32>;\n@group(0) @binding(4) var<uniform> params: SimParams;\n\n@compute @workgroup_size(256)\nfn cs_predict(@builtin(global_invocation_id) gid: vec3u) {\n  let idx = gid.x;\n  if (idx >= params.numVertices) { return; }\n\n  let mass = masses[idx];\n  let i3 = idx * 3u;\n\n  // Load current position and velocity\n  var pos = vec3f(positions[i3], positions[i3 + 1u], positions[i3 + 2u]);\n  var vel = vec3f(velocities[i3], velocities[i3 + 1u], velocities[i3 + 2u]);\n\n  // Skip pinned vertices (mass == 0)\n  if (mass > 0.0) {\n    // Apply gravity\n    vel += params.gravity * params.dt;\n\n    // Apply wind (simple drag model)\n    vel += params.wind * params.dt / mass;\n\n    // Apply damping\n    vel *= params.damping;\n\n    // Predict position\n    pos += vel * params.dt;\n  }\n\n  // Store predicted position\n  predicted[i3]      = pos.x;\n  predicted[i3 + 1u] = pos.y;\n  predicted[i3 + 2u] = pos.z;\n}\n";
+/**
+ * WGSL: Solve distance constraints (one color group at a time)
+ */
+declare const PBD_DISTANCE_SHADER = "\nstruct DistanceConstraint {\n  vertexA: u32,\n  vertexB: u32,\n  restLength: f32,\n  compliance: f32,\n}\n\nstruct SolveParams {\n  dt: f32,\n  numConstraints: u32,\n  iteration: u32,\n  padding: u32,\n}\n\n@group(0) @binding(0) var<storage, read_write> predicted: array<f32>;\n@group(0) @binding(1) var<storage, read> masses: array<f32>;\n@group(0) @binding(2) var<storage, read> constraints: array<DistanceConstraint>;\n@group(0) @binding(3) var<uniform> params: SolveParams;\n\n@compute @workgroup_size(256)\nfn cs_solve_distance(@builtin(global_invocation_id) gid: vec3u) {\n  let cIdx = gid.x;\n  if (cIdx >= params.numConstraints) { return; }\n\n  let c = constraints[cIdx];\n  let iA = c.vertexA * 3u;\n  let iB = c.vertexB * 3u;\n\n  let pA = vec3f(predicted[iA], predicted[iA + 1u], predicted[iA + 2u]);\n  let pB = vec3f(predicted[iB], predicted[iB + 1u], predicted[iB + 2u]);\n\n  let diff = pB - pA;\n  let dist = length(diff);\n\n  if (dist < 1e-7) { return; }\n\n  let wA = masses[c.vertexA];\n  let wB = masses[c.vertexB];\n  let invMassA = select(1.0 / wA, 0.0, wA <= 0.0);\n  let invMassB = select(1.0 / wB, 0.0, wB <= 0.0);\n  let wSum = invMassA + invMassB;\n\n  if (wSum < 1e-7) { return; }\n\n  // XPBD: compliance scaled by dt\u00B2\n  let alpha = c.compliance / (params.dt * params.dt);\n  let C = dist - c.restLength;\n  let lambda = -C / (wSum + alpha);\n\n  let correction = (diff / dist) * lambda;\n\n  // Apply corrections\n  if (invMassA > 0.0) {\n    predicted[iA]      -= correction.x * invMassA;\n    predicted[iA + 1u] -= correction.y * invMassA;\n    predicted[iA + 2u] -= correction.z * invMassA;\n  }\n  if (invMassB > 0.0) {\n    predicted[iB]      += correction.x * invMassB;\n    predicted[iB + 1u] += correction.y * invMassB;\n    predicted[iB + 2u] += correction.z * invMassB;\n  }\n}\n";
+/**
+ * WGSL: Solve volume constraints (one tetrahedron at a time)
+ */
+declare const PBD_VOLUME_SHADER = "\nstruct VolumeConstraint {\n  v0: u32,\n  v1: u32,\n  v2: u32,\n  v3: u32,\n  restVolume: f32,\n  compliance: f32,\n  padding: vec2u,\n}\n\nstruct SolveParams {\n  dt: f32,\n  numConstraints: u32,\n  iteration: u32,\n  padding: u32,\n}\n\n@group(0) @binding(0) var<storage, read_write> predicted: array<f32>;\n@group(0) @binding(1) var<storage, read> masses: array<f32>;\n@group(0) @binding(2) var<storage, read> constraints: array<VolumeConstraint>;\n@group(0) @binding(3) var<uniform> params: SolveParams;\n\nfn loadPos(idx: u32) -> vec3f {\n  let i = idx * 3u;\n  return vec3f(predicted[i], predicted[i + 1u], predicted[i + 2u]);\n}\n\nfn storePos(idx: u32, p: vec3f) {\n  let i = idx * 3u;\n  predicted[i]      = p.x;\n  predicted[i + 1u] = p.y;\n  predicted[i + 2u] = p.z;\n}\n\n@compute @workgroup_size(64)\nfn cs_solve_volume(@builtin(global_invocation_id) gid: vec3u) {\n  let cIdx = gid.x;\n  if (cIdx >= params.numConstraints) { return; }\n\n  let c = constraints[cIdx];\n  let p0 = loadPos(c.v0);\n  let p1 = loadPos(c.v1);\n  let p2 = loadPos(c.v2);\n  let p3 = loadPos(c.v3);\n\n  // Signed volume of tetrahedron = dot(p1-p0, cross(p2-p0, p3-p0)) / 6\n  let d1 = p1 - p0;\n  let d2 = p2 - p0;\n  let d3 = p3 - p0;\n  let volume = dot(d1, cross(d2, d3)) / 6.0;\n\n  let C = volume - c.restVolume;\n  if (abs(C) < 1e-7) { return; }\n\n  // Gradients of volume w.r.t. each vertex\n  let g1 = cross(d2, d3) / 6.0;\n  let g2 = cross(d3, d1) / 6.0;\n  let g3 = cross(d1, d2) / 6.0;\n  let g0 = -(g1 + g2 + g3);\n\n  let w0 = select(1.0 / masses[c.v0], 0.0, masses[c.v0] <= 0.0);\n  let w1 = select(1.0 / masses[c.v1], 0.0, masses[c.v1] <= 0.0);\n  let w2 = select(1.0 / masses[c.v2], 0.0, masses[c.v2] <= 0.0);\n  let w3 = select(1.0 / masses[c.v3], 0.0, masses[c.v3] <= 0.0);\n\n  let denom = w0 * dot(g0, g0) + w1 * dot(g1, g1) + w2 * dot(g2, g2) + w3 * dot(g3, g3);\n\n  if (denom < 1e-7) { return; }\n\n  let alpha = c.compliance / (params.dt * params.dt);\n  let lambda = -C / (denom + alpha);\n\n  if (w0 > 0.0) { storePos(c.v0, p0 + g0 * lambda * w0); }\n  if (w1 > 0.0) { storePos(c.v1, p1 + g1 * lambda * w1); }\n  if (w2 > 0.0) { storePos(c.v2, p2 + g2 * lambda * w2); }\n  if (w3 > 0.0) { storePos(c.v3, p3 + g3 * lambda * w3); }\n}\n";
+/**
+ * WGSL: SDF collision constraint solve
+ */
+declare const PBD_COLLISION_SHADER = "\nstruct SDFParams {\n  boundsMin: vec3f,\n  cellSize: f32,\n  boundsMax: vec3f,\n  friction: f32,\n  gridSizeX: u32,\n  gridSizeY: u32,\n  gridSizeZ: u32,\n  numVertices: u32,\n  collisionMargin: f32,\n  padding: vec3f,\n}\n\n@group(0) @binding(0) var<storage, read_write> predicted: array<f32>;\n@group(0) @binding(1) var<storage, read> masses: array<f32>;\n@group(0) @binding(2) var<storage, read> sdfData: array<f32>;\n@group(0) @binding(3) var<uniform> params: SDFParams;\n\nfn sampleSDF(pos: vec3f) -> f32 {\n  let local = (pos - params.boundsMin) / params.cellSize;\n  let gi = vec3u(clamp(vec3i(floor(local)), vec3i(0), vec3i(\n    i32(params.gridSizeX) - 2,\n    i32(params.gridSizeY) - 2,\n    i32(params.gridSizeZ) - 2\n  )));\n  let f = fract(local);\n\n  // Trilinear interpolation\n  let idx000 = gi.x + gi.y * params.gridSizeX + gi.z * params.gridSizeX * params.gridSizeY;\n  let idx100 = idx000 + 1u;\n  let idx010 = idx000 + params.gridSizeX;\n  let idx110 = idx010 + 1u;\n  let idx001 = idx000 + params.gridSizeX * params.gridSizeY;\n  let idx101 = idx001 + 1u;\n  let idx011 = idx001 + params.gridSizeX;\n  let idx111 = idx011 + 1u;\n\n  let c00 = mix(sdfData[idx000], sdfData[idx100], f.x);\n  let c10 = mix(sdfData[idx010], sdfData[idx110], f.x);\n  let c01 = mix(sdfData[idx001], sdfData[idx101], f.x);\n  let c11 = mix(sdfData[idx011], sdfData[idx111], f.x);\n  let c0 = mix(c00, c10, f.y);\n  let c1 = mix(c01, c11, f.y);\n  return mix(c0, c1, f.z);\n}\n\nfn sdfGradient(pos: vec3f) -> vec3f {\n  let eps = params.cellSize * 0.5;\n  return normalize(vec3f(\n    sampleSDF(pos + vec3f(eps, 0.0, 0.0)) - sampleSDF(pos - vec3f(eps, 0.0, 0.0)),\n    sampleSDF(pos + vec3f(0.0, eps, 0.0)) - sampleSDF(pos - vec3f(0.0, eps, 0.0)),\n    sampleSDF(pos + vec3f(0.0, 0.0, eps)) - sampleSDF(pos - vec3f(0.0, 0.0, eps))\n  ));\n}\n\n@compute @workgroup_size(256)\nfn cs_solve_collision(@builtin(global_invocation_id) gid: vec3u) {\n  let idx = gid.x;\n  if (idx >= params.numVertices) { return; }\n  if (masses[idx] <= 0.0) { return; }\n\n  let i3 = idx * 3u;\n  let pos = vec3f(predicted[i3], predicted[i3 + 1u], predicted[i3 + 2u]);\n\n  // Check if inside SDF bounds\n  if (any(pos < params.boundsMin) || any(pos > params.boundsMax)) { return; }\n\n  let dist = sampleSDF(pos);\n\n  if (dist < params.collisionMargin) {\n    let normal = sdfGradient(pos);\n    let penetration = params.collisionMargin - dist;\n\n    // Push vertex out along SDF gradient\n    let correction = normal * penetration;\n    predicted[i3]      += correction.x;\n    predicted[i3 + 1u] += correction.y;\n    predicted[i3 + 2u] += correction.z;\n  }\n}\n";
+/**
+ * WGSL: Update velocities from position delta and apply damping
+ */
+declare const PBD_VELOCITY_SHADER = "\nstruct VelParams {\n  dt: f32,\n  damping: f32,\n  numVertices: u32,\n  padding: u32,\n}\n\n@group(0) @binding(0) var<storage, read> positions: array<f32>;\n@group(0) @binding(1) var<storage, read_write> velocities: array<f32>;\n@group(0) @binding(2) var<storage, read> predicted: array<f32>;\n@group(0) @binding(3) var<uniform> params: VelParams;\n\n@compute @workgroup_size(256)\nfn cs_update_velocity(@builtin(global_invocation_id) gid: vec3u) {\n  let idx = gid.x;\n  if (idx >= params.numVertices) { return; }\n\n  let i3 = idx * 3u;\n  let invDt = 1.0 / params.dt;\n\n  velocities[i3]      = (predicted[i3]      - positions[i3])      * invDt;\n  velocities[i3 + 1u] = (predicted[i3 + 1u] - positions[i3 + 1u]) * invDt;\n  velocities[i3 + 2u] = (predicted[i3 + 2u] - positions[i3 + 2u]) * invDt;\n}\n";
+/**
+ * WGSL: Copy predicted back to positions (finalize step)
+ */
+declare const PBD_FINALIZE_SHADER = "\nstruct FinalizeParams {\n  numVertices: u32,\n  padding: vec3u,\n}\n\n@group(0) @binding(0) var<storage, read_write> positions: array<f32>;\n@group(0) @binding(1) var<storage, read> predicted: array<f32>;\n@group(0) @binding(2) var<uniform> params: FinalizeParams;\n\n@compute @workgroup_size(256)\nfn cs_finalize(@builtin(global_invocation_id) gid: vec3u) {\n  let idx = gid.x;\n  if (idx >= params.numVertices) { return; }\n\n  let i3 = idx * 3u;\n  positions[i3]      = predicted[i3];\n  positions[i3 + 1u] = predicted[i3 + 1u];\n  positions[i3 + 2u] = predicted[i3 + 2u];\n}\n";
+/**
+ * WGSL: Recompute vertex normals from triangle indices
+ */
+declare const PBD_NORMALS_SHADER = "\nstruct NormalParams {\n  numTriangles: u32,\n  numVertices: u32,\n  padding: vec2u,\n}\n\n@group(0) @binding(0) var<storage, read> positions: array<f32>;\n@group(0) @binding(1) var<storage, read_write> normals: array<atomic<i32>>;\n@group(0) @binding(2) var<storage, read> indices: array<u32>;\n@group(0) @binding(3) var<uniform> params: NormalParams;\n\nfn loadPos(idx: u32) -> vec3f {\n  let i = idx * 3u;\n  return vec3f(positions[i], positions[i + 1u], positions[i + 2u]);\n}\n\n// Atomic accumulate normal via fixed-point (multiply by 1e6, cast to i32)\nfn atomicAddNormal(vertIdx: u32, n: vec3f) {\n  let i = vertIdx * 3u;\n  let scale = 1000000.0;\n  atomicAdd(&normals[i],      i32(n.x * scale));\n  atomicAdd(&normals[i + 1u], i32(n.y * scale));\n  atomicAdd(&normals[i + 2u], i32(n.z * scale));\n}\n\n@compute @workgroup_size(256)\nfn cs_compute_normals(@builtin(global_invocation_id) gid: vec3u) {\n  let triIdx = gid.x;\n  if (triIdx >= params.numTriangles) { return; }\n\n  let i0 = indices[triIdx * 3u];\n  let i1 = indices[triIdx * 3u + 1u];\n  let i2 = indices[triIdx * 3u + 2u];\n\n  let p0 = loadPos(i0);\n  let p1 = loadPos(i1);\n  let p2 = loadPos(i2);\n\n  let faceNormal = cross(p1 - p0, p2 - p0);\n\n  atomicAddNormal(i0, faceNormal);\n  atomicAddNormal(i1, faceNormal);\n  atomicAddNormal(i2, faceNormal);\n}\n";
+/**
+ * WGSL: Normalize accumulated vertex normals
+ */
+declare const PBD_NORMALIZE_SHADER = "\nstruct NormalizeParams {\n  numVertices: u32,\n  padding: vec3u,\n}\n\n@group(0) @binding(0) var<storage, read_write> normalsI32: array<i32>;\n@group(0) @binding(1) var<storage, read_write> normalsF32: array<f32>;\n@group(0) @binding(2) var<uniform> params: NormalizeParams;\n\n@compute @workgroup_size(256)\nfn cs_normalize_normals(@builtin(global_invocation_id) gid: vec3u) {\n  let idx = gid.x;\n  if (idx >= params.numVertices) { return; }\n\n  let i3 = idx * 3u;\n  let scale = 1.0 / 1000000.0;\n  var n = vec3f(\n    f32(normalsI32[i3])      * scale,\n    f32(normalsI32[i3 + 1u]) * scale,\n    f32(normalsI32[i3 + 2u]) * scale\n  );\n\n  let len = length(n);\n  if (len > 1e-7) {\n    n /= len;\n  } else {\n    n = vec3f(0.0, 1.0, 0.0);\n  }\n\n  normalsF32[i3]      = n.x;\n  normalsF32[i3 + 1u] = n.y;\n  normalsF32[i3 + 2u] = n.z;\n\n  // Reset atomic accumulator for next frame\n  normalsI32[i3]      = 0;\n  normalsI32[i3 + 1u] = 0;\n  normalsI32[i3 + 2u] = 0;\n}\n";
+/**
+ * WGSL compute shader for bending constraints.
+ * Maintains rest dihedral angles between adjacent triangle pairs.
+ * Uses XPBD formulation with compliance for stable soft constraints.
+ *
+ * Buffers:
+ *   binding(1) positions   — read_write predicted positions (flat xyz)
+ *   binding(2) masses      — read per-vertex masses (0 = pinned)
+ *   binding(3) constraints — read 4 u32 per constraint [v0, v1, v2, v3]
+ *   binding(4) restAngles  — read rest dihedral angle per constraint
+ */
+declare const PBD_BENDING_SHADER = "\nstruct Params {\n  dt: f32,\n  numConstraints: u32,\n  compliance: f32,\n  _pad: f32,\n};\n\n@group(0) @binding(0) var<uniform> params: Params;\n@group(0) @binding(1) var<storage, read_write> positions: array<f32>;\n@group(0) @binding(2) var<storage, read> masses: array<f32>;\n@group(0) @binding(3) var<storage, read> constraints: array<u32>;\n@group(0) @binding(4) var<storage, read> restAngles: array<f32>;\n\nfn loadPos(i: u32) -> vec3<f32> {\n  return vec3<f32>(positions[i * 3u], positions[i * 3u + 1u], positions[i * 3u + 2u]);\n}\n\nfn storePos(i: u32, p: vec3<f32>) {\n  positions[i * 3u] = p.x;\n  positions[i * 3u + 1u] = p.y;\n  positions[i * 3u + 2u] = p.z;\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let idx = gid.x;\n  if (idx >= params.numConstraints) { return; }\n\n  // v0-v1 = shared edge, v2 = opposite on face 1, v3 = opposite on face 2\n  let v0 = constraints[idx * 4u];\n  let v1 = constraints[idx * 4u + 1u];\n  let v2 = constraints[idx * 4u + 2u];\n  let v3 = constraints[idx * 4u + 3u];\n\n  let p0 = loadPos(v0);\n  let p1 = loadPos(v1);\n  let p2 = loadPos(v2);\n  let p3 = loadPos(v3);\n\n  // Shared edge\n  let e = p1 - p0;\n  let eLen = length(e);\n  if (eLen < 1e-7) { return; }\n  let eNorm = e / eLen;\n\n  // Vectors from v0 to opposite vertices\n  let d2 = p2 - p0;\n  let d3 = p3 - p0;\n\n  // Face normals (unnormalized, magnitude = 2 * triangle area)\n  let n1 = cross(e, d2);\n  let n2 = cross(e, d3);\n  let n1Len = length(n1);\n  let n2Len = length(n2);\n  if (n1Len < 1e-7 || n2Len < 1e-7) { return; }\n\n  let n1n = n1 / n1Len;\n  let n2n = n2 / n2Len;\n\n  // Dihedral angle via atan2 for full [-pi, pi] range\n  let cosTheta = clamp(dot(n1n, n2n), -1.0, 1.0);\n  let sinTheta = dot(cross(n1n, n2n), eNorm);\n  let theta = atan2(sinTheta, cosTheta);\n\n  // Constraint: C = theta - restAngle\n  let restAngle = restAngles[idx];\n  let C = theta - restAngle;\n  if (abs(C) < 1e-6) { return; }\n\n  // Perpendicular distances from opposite vertices to shared edge\n  let h2 = n1Len / eLen;\n  let h3 = n2Len / eLen;\n  if (h2 < 1e-7 || h3 < 1e-7) { return; }\n\n  // Gradients of theta w.r.t. vertex positions (Bridson formulation)\n  let g2 = n1n / h2;\n  let g3 = -n2n / h3;\n\n  // Parametric projections along shared edge for gradient distribution\n  let eDotE = eLen * eLen;\n  let s2 = dot(d2, e) / eDotE;\n  let s3 = dot(d3, e) / eDotE;\n\n  // Edge vertex gradients (sum of all gradients = 0, translation invariance)\n  let g0 = -(1.0 - s2) * g2 - (1.0 - s3) * g3;\n  let g1 = -s2 * g2 - s3 * g3;\n\n  // Inverse masses\n  let w0 = select(0.0, 1.0 / masses[v0], masses[v0] > 0.0);\n  let w1 = select(0.0, 1.0 / masses[v1], masses[v1] > 0.0);\n  let w2 = select(0.0, 1.0 / masses[v2], masses[v2] > 0.0);\n  let w3 = select(0.0, 1.0 / masses[v3], masses[v3] > 0.0);\n\n  // XPBD: alpha = compliance / dt^2\n  let alpha = params.compliance / (params.dt * params.dt);\n  let denom = w0 * dot(g0, g0) + w1 * dot(g1, g1)\n            + w2 * dot(g2, g2) + w3 * dot(g3, g3) + alpha;\n  if (denom < 1e-10) { return; }\n\n  let lambda = -C / denom;\n\n  // Apply position corrections\n  if (w0 > 0.0) { storePos(v0, p0 + g0 * lambda * w0); }\n  if (w1 > 0.0) { storePos(v1, p1 + g1 * lambda * w1); }\n  if (w2 > 0.0) { storePos(v2, p2 + g2 * lambda * w2); }\n  if (w3 > 0.0) { storePos(v3, p3 + g3 * lambda * w3); }\n}\n";
+/**
+ * WGSL compute shader for attachment constraints.
+ * Pins vertices to target positions with XPBD compliance.
+ * compliance=0 → hard pin, compliance>0 → soft spring.
+ *
+ * Buffers:
+ *   binding(1) positions    — read_write predicted positions (flat xyz)
+ *   binding(2) masses       — read per-vertex masses
+ *   binding(3) vertexIndices — read vertex index per constraint
+ *   binding(4) targets      — read target positions (flat xyz, 3 per constraint)
+ *   binding(5) compliances  — read compliance per constraint
+ */
+declare const PBD_ATTACHMENT_SHADER = "\nstruct Params {\n  dt: f32,\n  numConstraints: u32,\n  _pad0: f32,\n  _pad1: f32,\n};\n\n@group(0) @binding(0) var<uniform> params: Params;\n@group(0) @binding(1) var<storage, read_write> positions: array<f32>;\n@group(0) @binding(2) var<storage, read> masses: array<f32>;\n@group(0) @binding(3) var<storage, read> vertexIndices: array<u32>;\n@group(0) @binding(4) var<storage, read> targets: array<f32>;\n@group(0) @binding(5) var<storage, read> compliances: array<f32>;\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let idx = gid.x;\n  if (idx >= params.numConstraints) { return; }\n\n  let vi = vertexIndices[idx];\n  let mass = masses[vi];\n  if (mass <= 0.0) { return; }  // Pinned vertex, already at target\n\n  let px = positions[vi * 3u];\n  let py = positions[vi * 3u + 1u];\n  let pz = positions[vi * 3u + 2u];\n\n  let tx = targets[idx * 3u];\n  let ty = targets[idx * 3u + 1u];\n  let tz = targets[idx * 3u + 2u];\n\n  let dx = tx - px;\n  let dy = ty - py;\n  let dz = tz - pz;\n\n  let dist = sqrt(dx * dx + dy * dy + dz * dz);\n  if (dist < 1e-7) { return; }\n\n  let compliance = compliances[idx];\n  let w = 1.0 / mass;\n  let alpha = compliance / (params.dt * params.dt);\n\n  // XPBD: C = dist, gradient = normalize(d), single vertex\n  let lambda = dist / (w + alpha);\n\n  let nx = dx / dist;\n  let ny = dy / dist;\n  let nz = dz / dist;\n\n  positions[vi * 3u]      = px + nx * lambda * w;\n  positions[vi * 3u + 1u] = py + ny * lambda * w;\n  positions[vi * 3u + 2u] = pz + nz * lambda * w;\n}\n";
+/**
+ * WGSL compute shader: build spatial hash grid.
+ * Hashes each vertex position into a 3D grid cell and atomically appends
+ * the vertex index to that cell's list via a prefix-sum-style counter array.
+ *
+ * Two-pass approach:
+ *   Pass 1 (this shader): count vertices per cell + write vertex→cell mapping
+ *   CPU prefix sum: compute cell offsets from counts
+ *   Pass 2 (resolve shader): iterate 27 neighbors, resolve penetrations
+ */
+declare const PBD_HASH_BUILD_SHADER = "\nstruct Params {\n  numVertices: u32,\n  cellSize: f32,\n  gridDimX: u32,\n  gridDimY: u32,\n  gridDimZ: u32,\n  originX: f32,\n  originY: f32,\n  originZ: f32,\n};\n\n@group(0) @binding(0) var<uniform> params: Params;\n@group(0) @binding(1) var<storage, read> positions: array<f32>;\n@group(0) @binding(2) var<storage, read_write> cellCounts: array<atomic<u32>>;\n@group(0) @binding(3) var<storage, read_write> vertexCells: array<u32>;\n\nfn hashCell(ix: u32, iy: u32, iz: u32) -> u32 {\n  return ix + iy * params.gridDimX + iz * params.gridDimX * params.gridDimY;\n}\n\n@compute @workgroup_size(256)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let idx = gid.x;\n  if (idx >= params.numVertices) { return; }\n\n  let px = positions[idx * 3u];\n  let py = positions[idx * 3u + 1u];\n  let pz = positions[idx * 3u + 2u];\n\n  let ix = clamp(u32(floor((px - params.originX) / params.cellSize)), 0u, params.gridDimX - 1u);\n  let iy = clamp(u32(floor((py - params.originY) / params.cellSize)), 0u, params.gridDimY - 1u);\n  let iz = clamp(u32(floor((pz - params.originZ) / params.cellSize)), 0u, params.gridDimZ - 1u);\n\n  let cell = hashCell(ix, iy, iz);\n  vertexCells[idx] = cell;\n  atomicAdd(&cellCounts[cell], 1u);\n}\n";
+/**
+ * WGSL compute shader: resolve self-collisions.
+ * For each vertex, iterate all vertices in the 27 neighboring cells
+ * and push apart any that are closer than the collision radius.
+ *
+ * Buffers:
+ *   binding(1) positions    — read_write predicted positions
+ *   binding(2) masses       — read per-vertex masses
+ *   binding(3) vertexCells  — read cell index per vertex
+ *   binding(4) cellOffsets  — read prefix-sum offsets per cell (from CPU)
+ *   binding(5) cellCounts   — read vertex count per cell
+ *   binding(6) sortedVerts  — read vertex indices sorted by cell
+ */
+declare const PBD_SELF_COLLISION_SHADER = "\nstruct Params {\n  numVertices: u32,\n  collisionRadius: f32,\n  gridDimX: u32,\n  gridDimY: u32,\n  gridDimZ: u32,\n  originX: f32,\n  originY: f32,\n  originZ: f32,\n  cellSize: f32,\n  _pad: f32,\n  _pad2: f32,\n  _pad3: f32,\n};\n\n@group(0) @binding(0) var<uniform> params: Params;\n@group(0) @binding(1) var<storage, read_write> positions: array<f32>;\n@group(0) @binding(2) var<storage, read> masses: array<f32>;\n@group(0) @binding(3) var<storage, read> vertexCells: array<u32>;\n@group(0) @binding(4) var<storage, read> cellOffsets: array<u32>;\n@group(0) @binding(5) var<storage, read> cellCounts2: array<u32>;\n@group(0) @binding(6) var<storage, read> sortedVerts: array<u32>;\n\nfn hashCell(ix: u32, iy: u32, iz: u32) -> u32 {\n  return ix + iy * params.gridDimX + iz * params.gridDimX * params.gridDimY;\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let idx = gid.x;\n  if (idx >= params.numVertices) { return; }\n\n  let mi = masses[idx];\n  if (mi <= 0.0) { return; }\n  let wi = 1.0 / mi;\n\n  let px = positions[idx * 3u];\n  let py = positions[idx * 3u + 1u];\n  let pz = positions[idx * 3u + 2u];\n\n  let ix = clamp(u32(floor((px - params.originX) / params.cellSize)), 0u, params.gridDimX - 1u);\n  let iy = clamp(u32(floor((py - params.originY) / params.cellSize)), 0u, params.gridDimY - 1u);\n  let iz = clamp(u32(floor((pz - params.originZ) / params.cellSize)), 0u, params.gridDimZ - 1u);\n\n  let radius = params.collisionRadius;\n  let radiusSq = radius * radius;\n\n  var corrX = 0.0;\n  var corrY = 0.0;\n  var corrZ = 0.0;\n\n  // Iterate 27 neighbor cells\n  for (var dz: i32 = -1; dz <= 1; dz++) {\n    for (var dy: i32 = -1; dy <= 1; dy++) {\n      for (var dx: i32 = -1; dx <= 1; dx++) {\n        let nx = i32(ix) + dx;\n        let ny = i32(iy) + dy;\n        let nz = i32(iz) + dz;\n\n        if (nx < 0 || nx >= i32(params.gridDimX) ||\n            ny < 0 || ny >= i32(params.gridDimY) ||\n            nz < 0 || nz >= i32(params.gridDimZ)) { continue; }\n\n        let cell = hashCell(u32(nx), u32(ny), u32(nz));\n        let offset = cellOffsets[cell];\n        let count = cellCounts2[cell];\n\n        for (var k: u32 = 0u; k < count; k++) {\n          let j = sortedVerts[offset + k];\n          if (j == idx) { continue; }\n\n          let mj = masses[j];\n          if (mj <= 0.0) { continue; }\n\n          let qx = positions[j * 3u] - px;\n          let qy = positions[j * 3u + 1u] - py;\n          let qz = positions[j * 3u + 2u] - pz;\n          let distSq = qx * qx + qy * qy + qz * qz;\n\n          if (distSq < radiusSq && distSq > 1e-10) {\n            let dist = sqrt(distSq);\n            let penetration = radius - dist;\n            let wj = 1.0 / mj;\n            let wSum = wi + wj;\n            let scale = penetration / (wSum * dist);\n\n            // Push this vertex away (negative direction)\n            corrX -= qx * scale * wi;\n            corrY -= qy * scale * wi;\n            corrZ -= qz * scale * wi;\n          }\n        }\n      }\n    }\n  }\n\n  positions[idx * 3u]      = px + corrX;\n  positions[idx * 3u + 1u] = py + corrY;\n  positions[idx * 3u + 2u] = pz + corrZ;\n}\n";
+/**
+ * Greedy graph coloring for distance/bending constraints.
+ * Constraints sharing a vertex cannot be the same color — this allows
+ * same-color constraints to execute in parallel without data races.
+ */
+declare function colorConstraints(constraints: Array<{
+    vertexA: number;
+    vertexB: number;
+}>, numVertices: number): IConstraintColoring;
+/**
+ * Generate tetrahedral mesh from a surface triangle mesh.
+ * Uses simple fan tetrahedralization from centroid — suitable for convex
+ * and mildly concave meshes. For complex shapes, use Delaunay tetrahedralization.
+ */
+declare function generateTetrahedra(positions: Float32Array, indices: Uint32Array): {
+    tetIndices: Uint32Array;
+    restVolumes: Float32Array;
+};
+/**
+ * Extract unique edges from triangle indices for distance constraints.
+ */
+declare function extractEdges(indices: Uint32Array, _numVertices: number): {
+    edges: Uint32Array;
+    restLengths: Float32Array;
+    positions: Float32Array;
+} | {
+    edges: Uint32Array;
+};
+/**
+ * Compute rest lengths for distance constraints.
+ */
+declare function computeRestLengths(positions: Float32Array, edges: Uint32Array): Float32Array;
+/**
+ * Extract bending constraint pairs from a triangle mesh.
+ * Finds pairs of triangles sharing an edge and computes rest dihedral angles.
+ *
+ * @returns constraints — flat Uint32Array, 4 indices per constraint [v0, v1, v2, v3]
+ *          where (v0,v1) is the shared edge and v2, v3 are the opposite vertices.
+ * @returns restAngles — Float32Array of rest dihedral angles (one per constraint).
+ */
+declare function extractBendingPairs(indices: Uint32Array, positions: Float32Array): {
+    constraints: Uint32Array;
+    restAngles: Float32Array;
+};
+/**
+ * Generate a signed distance field from a triangle mesh.
+ * Uses brute-force closest-triangle for each grid cell.
+ * For production, use a spatial acceleration structure.
+ */
+declare function generateSDF(vertices: Float32Array, indices: Uint32Array, gridSize: number, padding?: number): ISDFCollider;
+/**
+ * CPU-side PBD solver. Mirrors the GPU pipeline for environments without WebGPU.
+ */
+declare class PBDSolverCPU {
+    private config;
+    private state;
+    private distanceConstraints;
+    private volumeConstraints;
+    private bendingConstraints;
+    private attachmentConstraints;
+    private densityParticles;
+    private densityNeighbors;
+    private densityRestDensity;
+    private densityKernelRadius;
+    private densityCompliance;
+    private coloring;
+    private sdfColliders;
+    constructor(config: ISoftBodyConfig);
+    private buildConstraints;
+    private computeTetVolume;
+    /**
+     * Add an SDF collider for collision detection
+     */
+    addCollider(collider: ISDFCollider): void;
+    /**
+     * Pin a vertex to a world position.
+     * @param compliance 0 = hard pin, >0 = soft spring (XPBD compliant)
+     */
+    pinVertex(vertexIndex: number, position: IVector3, compliance?: number): void;
+    /**
+     * Unpin a vertex
+     */
+    unpinVertex(vertexIndex: number): void;
+    /**
+     * Apply an impulse at a position (for grab interaction)
+     */
+    applyImpulse(position: IVector3, force: IVector3, radius: number): void;
+    /**
+     * Step the simulation forward by dt seconds
+     */
+    step(dt: number): ISoftBodyState;
+    private solveDistanceConstraint;
+    private solveVolumeConstraint;
+    private solveBendingConstraint;
+    private solveAttachmentConstraint;
+    /**
+     * CPU density constraint solver (SPH-style for fluid-PBD coupling).
+     * Each fluid particle corrects toward rest density using neighbor kernel.
+     */
+    private solveDensityConstraints;
+    /**
+     * Configure density constraints for fluid particles in the unified buffer.
+     * Call this to enable fluid-PBD coupling.
+     */
+    setDensityParticles(particleIndices: number[], neighbors: number[][], restDensity?: number, kernelRadius?: number, compliance?: number): void;
+    private solveSelfCollision;
+    /**
+     * Update the target position of an existing attachment constraint.
+     * Used for dynamic targets like grab interaction or rigid body following.
+     */
+    updateAttachmentTarget(vertexIndex: number, newTarget: IVector3): void;
+    private solveSdfCollision;
+    private recomputeNormals;
+    /** Get current state (positions, normals, etc.) */
+    getState(): ISoftBodyState;
+    /** Pause/resume */
+    setActive(active: boolean): void;
+    /** Reset to rest shape */
+    reset(): void;
+}
+/**
+ * GPU-accelerated PBD solver.
+ * Uses WebGPU compute shaders for massively parallel constraint solving.
+ */
+declare class PBDSolverGPU {
+    private config;
+    private state;
+    private device;
+    private buffers;
+    private pipelines;
+    private bindGroups;
+    private coloring;
+    constructor(config: ISoftBodyConfig, device: GPUDevice);
+    /**
+     * Initialize GPU resources (buffers, pipelines, bind groups).
+     */
+    initialize(): Promise<void>;
+    private createBuffer;
+    private createPipeline;
+    /**
+     * Step the simulation.
+     */
+    step(dt: number): ISoftBodyState;
+    getState(): ISoftBodyState;
+}
+/**
+ * Create a soft-body solver with the given configuration.
+ * Applies preset parameters if a preset is specified.
+ */
+declare function createPBDSolver(config: ISoftBodyConfig): Promise<PBDSolverCPU | PBDSolverGPU>;
+
+/**
+ * SoftBodyGrabController
+ *
+ * Bridges the @grabbable trait to PBD attachment constraints.
+ * When a hand grabs a soft body, finds the closest vertices within
+ * a grab radius, creates attachment constraints with distance-weighted
+ * compliance, and updates their targets each frame as the hand moves.
+ */
+
+interface GrabConfig {
+    /** Maximum number of vertices to grab */
+    maxVertices: number;
+    /** Grab radius around the hand position */
+    grabRadius: number;
+    /** Base compliance for attachment (0 = hard, higher = softer) */
+    baseCompliance: number;
+    /** Compliance scales with distance: compliance = base * (1 + dist/radius * falloff) */
+    complianceFalloff: number;
+}
+declare class SoftBodyGrabController {
+    private activeGrabs;
+    private config;
+    constructor(config?: Partial<GrabConfig>);
+    /**
+     * Start grabbing the soft body at the given hand position.
+     * Finds the closest vertices and creates attachment constraints.
+     */
+    grabStart(handId: string, handPosition: IVector3, solver: PBDSolverCPU): void;
+    /**
+     * Update grab target positions as the hand moves.
+     * Each grabbed vertex follows the hand with its original local offset preserved.
+     */
+    grabUpdate(handId: string, handPosition: IVector3): void;
+    /**
+     * Release the grab — remove all attachment constraints for this hand.
+     */
+    grabEnd(handId: string): void;
+    /**
+     * Check if a hand is currently grabbing.
+     */
+    isGrabbing(handId: string): boolean;
+    /**
+     * Get all active grab hand IDs.
+     */
+    getActiveGrabs(): string[];
+    /**
+     * Release all grabs (e.g., when soft body is destroyed).
+     */
+    releaseAll(): void;
+}
+
+/**
+ * MLSMPMFluid — GPU-accelerated MLS-MPM fluid simulation.
+ *
+ * Uses WebGPU compute shaders for Moving Least Squares Material Point Method:
+ *   Frame pipeline:
+ *     [1] Grid Clear
+ *     [2] Particle-to-Grid (P2G) — scatter mass/momentum via atomicAdd
+ *     [3] Grid Update — gravity, boundaries, momentum → velocity
+ *     [4] Grid-to-Particle (G2P) — gather velocity, update APIC C matrix + J
+ *
+ *   Rendering pipeline (SSFR):
+ *     [1] Depth pass — particle → depth buffer
+ *     [2] Thickness pass — additive particle thickness
+ *     [3] Bilateral filter — smooth depth, compute normals
+ *     [4] Final shade — Fresnel + Beer-Lambert + refraction
+ *
+ * Performance targets:
+ *   - 100K particles @ 60 FPS on iGPU
+ *   - 300K particles @ 30 FPS on discrete GPU
+ *
+ * @module physics
+ */
+interface MLSMPMConfig {
+    /** Fluid behavior: liquid (incompressible) or gas (compressible) */
+    type: 'liquid' | 'gas';
+    /** Number of simulation particles */
+    particleCount: number;
+    /** Dynamic viscosity (default: 0.01 for water) */
+    viscosity: number;
+    /** Grid cells per axis (default: 128) */
+    gridResolution: number;
+    /** Domain size in world units (default: 10) */
+    domainSize: number;
+    /** SSFR render resolution scale (0.5 = half-res, default) */
+    resolutionScale: number;
+    /** Target rest density (default: 1000 for water) */
+    restDensity: number;
+    /** Compressibility stiffness (default: 50) */
+    bulkModulus: number;
+    /** Particle visual radius (default: 0.02) */
+    particleRadius: number;
+    /** Gravity Y component (default: -9.81) */
+    gravity: number;
+    /** SSFR absorption color RGB (default: [0.4, 0.04, 0.0] blue water) */
+    absorptionColor: [number, number, number];
+    /** SSFR absorption strength (default: 2.0) */
+    absorptionStrength: number;
+}
+interface MLSMPMStats {
+    particleCount: number;
+    gridResolution: number;
+    lastStepMs: number;
+    lastRenderMs: number;
+    gpuBufferSizeMB: number;
+}
+declare class MLSMPMFluid {
+    private config;
+    private device;
+    private disposed;
+    private particlePositions;
+    private particleVelocities;
+    private particleC;
+    private particleJ;
+    private gridMass;
+    private gridMomentumX;
+    private gridMomentumY;
+    private gridMomentumZ;
+    private gridVelocity;
+    private simParamsBuffer;
+    /** External force (wind) applied during grid update [x, y, z] in m/s² */
+    private externalForce;
+    private gridClearPipeline;
+    private p2gPipeline;
+    private gridUpdatePipeline;
+    private g2pPipeline;
+    private p2gBindGroup;
+    private gridClearBindGroup;
+    private gridUpdateBindGroup;
+    private g2pBindGroup;
+    private lastStepMs;
+    private lastRenderMs;
+    constructor(config?: Partial<MLSMPMConfig>);
+    /**
+     * Initialize GPU resources and compile shaders.
+     * Must be called before step().
+     */
+    init(device: GPUDevice): Promise<void>;
+    /**
+     * Set initial particle positions. Call after init().
+     *
+     * @param positions - Float32Array of [x, y, z, volume, ...] per particle
+     */
+    setInitialPositions(positions: Float32Array): void;
+    /**
+     * Generate a block of particles in a cubic region.
+     */
+    generateParticleBlock(min: [number, number, number], max: [number, number, number]): Float32Array;
+    /**
+     * Step the simulation forward by dt seconds.
+     */
+    step(dt?: number): void;
+    /**
+     * Dispose all GPU resources.
+     */
+    dispose(): void;
+    /**
+     * Set an external force (e.g. wind) applied to the fluid during grid update.
+     * Force is in world-space acceleration (m/s²). Applied additively with gravity.
+     */
+    setExternalForce(x: number, y: number, z: number): void;
+    /** Get the particle position buffer for rendering or unified PBD integration */
+    getParticlePositionBuffer(): GPUBuffer | null;
+    /** Get the particle velocity buffer */
+    getParticleVelocityBuffer(): GPUBuffer | null;
+    getParticleCount(): number;
+    getConfig(): Readonly<MLSMPMConfig>;
+    getStats(): MLSMPMStats;
+    private createPipelines;
+    private createBindGroups;
+    private updateUniforms;
+    /**
+     * Load a WGSL shader file. In bundled environments, this uses the import.
+     * Falls back to inline strings for testing.
+     */
+    private loadShader;
+}
+
+/**
+ * UnifiedParticleBuffer — Shared particle buffer coupling for MLS-MPM + PBD.
+ *
+ * Bridges fluid (MLS-MPM), cloth (PBD), rigid, debris, and crowd particles
+ * into a single coordinate space so they can interact via boundary coupling.
+ *
+ * Architecture (per P.GAPS.09):
+ *   - Each subsystem owns its particles and advances them independently
+ *   - This buffer provides a unified view for:
+ *     (a) Boundary force exchange (fluid ↔ cloth pressure)
+ *     (b) Collision detection across particle types
+ *     (c) Rendering (single draw call for all particles)
+ *     (d) Network sync (one serialization path)
+ *
+ * GPU path: subsystems share GPUBuffers via sub-allocation offsets.
+ * CPU path: Float32Array views into a single ArrayBuffer.
+ *
+ * @module physics
+ * @see docs/specs/pbd-solver-upgrade.md
+ */
+
+/** Registration handle returned when a subsystem adds particles. */
+interface ParticleRange {
+    /** Particle type tag */
+    type: ParticleType;
+    /** Starting index in the unified buffer */
+    offset: number;
+    /** Number of particles in this range */
+    count: number;
+    /** Label for debugging */
+    label: string;
+}
+/** Boundary coupling force between two particle types. */
+interface BoundaryCoupling {
+    /** Source particle type exerting force */
+    from: ParticleType;
+    /** Target particle type receiving force */
+    to: ParticleType;
+    /** Coupling strength multiplier (default: 1.0) */
+    strength: number;
+    /** Interaction radius in world units */
+    radius: number;
+}
+/** Stats for monitoring buffer usage. */
+interface UnifiedBufferStats {
+    totalCapacity: number;
+    totalActive: number;
+    rangeCount: number;
+    byType: Record<string, number>;
+    bufferSizeMB: number;
+}
+/**
+ * CPU-side unified particle buffer.
+ *
+ * Pre-allocates a fixed-capacity buffer. Subsystems register particle ranges
+ * and write positions/velocities into their slice. The buffer provides
+ * read access for coupling, rendering, and serialization.
+ */
+declare class UnifiedParticleBuffer {
+    /** Max particles across all subsystems */
+    readonly capacity: number;
+    /** Positions: [x, y, z] per particle, flat array */
+    readonly positions: Float32Array;
+    /** Velocities: [vx, vy, vz] per particle, flat array */
+    readonly velocities: Float32Array;
+    /** Particle attributes (type, phase, density, pressure), 4 floats each */
+    readonly attributes: Float32Array;
+    /** Registered particle ranges */
+    private ranges;
+    /** Boundary coupling rules */
+    private couplings;
+    /** Next free index for allocation */
+    private nextFree;
+    constructor(capacity?: number);
+    /**
+     * Register a particle range for a subsystem.
+     * Returns a ParticleRange handle with the allocated offset.
+     *
+     * @throws if capacity exceeded
+     */
+    registerParticles(type: ParticleType, count: number, label: string): ParticleRange;
+    /**
+     * Unregister a particle range. Does NOT compact — leaves a hole.
+     * Call compact() to reclaim fragmented space.
+     */
+    unregisterParticles(range: ParticleRange): void;
+    /**
+     * Register a boundary coupling rule between two particle types.
+     * During solveBoundaryCoupling(), particles of type `from` exert
+     * pressure forces on nearby particles of type `to`.
+     */
+    addCoupling(coupling: BoundaryCoupling): void;
+    /**
+     * Solve boundary coupling forces between registered particle types.
+     *
+     * Uses a simple pairwise interaction: for each coupling rule, iterate
+     * source particles and apply repulsive forces to nearby target particles.
+     *
+     * For GPU path, this would be a compute shader with spatial hashing.
+     * This CPU implementation is O(N*M) and suitable for < 10K cross-type pairs.
+     */
+    solveBoundaryCoupling(dt: number): void;
+    private applyPairwiseCoupling;
+    /**
+     * Write positions from an external source into a registered range.
+     * Used by subsystems to push their updated state after simulation.
+     */
+    writePositions(range: ParticleRange, data: Float32Array): void;
+    /**
+     * Write velocities from an external source into a registered range.
+     */
+    writeVelocities(range: ParticleRange, data: Float32Array): void;
+    /**
+     * Read positions for a specific range (returns a view, not a copy).
+     */
+    readPositions(range: ParticleRange): Float32Array;
+    /**
+     * Read velocities for a specific range.
+     */
+    readVelocities(range: ParticleRange): Float32Array;
+    /**
+     * Get attribute for a single particle.
+     */
+    getAttributes(particleIndex: number): IParticleAttributes;
+    /**
+     * Update density/pressure for a range (written by fluid solver).
+     */
+    writeDensityPressure(range: ParticleRange, density: Float32Array, pressure: Float32Array): void;
+    /** Get all registered ranges. */
+    getRanges(): readonly ParticleRange[];
+    /** Get ranges of a specific particle type. */
+    getRangesByType(type: ParticleType): ParticleRange[];
+    /** Total active particles across all ranges. */
+    getActiveCount(): number;
+    /** Get buffer usage stats. */
+    getStats(): UnifiedBufferStats;
+    /**
+     * Serialize all active particles into a compact binary buffer.
+     * Layout per particle: [x, y, z, vx, vy, vz, type] = 28 bytes
+     *
+     * Header: [magic(4), version(2), particleCount(4), rangeCount(2)]
+     * Then per range: [type(1), offset(4), count(4)]
+     * Then particle data: [f32 x, f32 y, f32 z, f32 vx, f32 vy, f32 vz, u8 type] packed
+     *
+     * Returns an ArrayBuffer suitable for DataChannel.send().
+     */
+    serialize(): ArrayBuffer;
+    /**
+     * Deserialize a binary buffer (from a remote peer) into the local buffer.
+     * Clears existing ranges and replaces with the remote state.
+     */
+    deserialize(data: ArrayBuffer): void;
+    /** Dispose all buffers. */
+    dispose(): void;
+}
+
+/**
+ * PhysicsSyncProtocol — WebRTC binary protocol for two-tier physics sync.
+ *
+ * Tier 1 (Logic): CRDT state sync at ~10 Hz via WorldState (Loro)
+ * Tier 2 (Physics): Raw binary particle sync at ~60 Hz via DataChannel
+ *
+ * This module handles Tier 2. The binary protocol is designed for minimal
+ * overhead over unreliable DataChannels:
+ *   - No JSON, no protobuf — pure typed arrays
+ *   - Delta compression: only send changed particles
+ *   - Quantized positions: 16-bit half-float for bandwidth (optional)
+ *   - Sequence numbers for jitter buffer / interpolation
+ *
+ * Wire format:
+ *   Header (16 bytes):
+ *     [0-3]   magic: 0x48505350 ('HPSP')
+ *     [4-5]   version: u16
+ *     [6-7]   sequence: u16 (wraps at 65535)
+ *     [8-11]  timestamp: u32 (ms since session start)
+ *     [12-13] particleCount: u16
+ *     [14]    flags: u8 (bit 0: delta, bit 1: quantized)
+ *     [15]    reserved: u8
+ *
+ *   Body (per particle, full mode = 25 bytes):
+ *     [0-3]   x: f32
+ *     [4-7]   y: f32
+ *     [8-11]  z: f32
+ *     [12-15] vx: f32
+ *     [16-19] vy: f32
+ *     [20-23] vz: f32
+ *     [24]    type: u8 (ParticleType enum)
+ *
+ *   Body (per particle, delta mode = 13 bytes):
+ *     [0-1]   index: u16 (particle index in unified buffer)
+ *     [2-5]   dx: f32 (position delta)
+ *     [6-9]   dy: f32
+ *     [10-13] dz: f32
+ *
+ * @module physics
+ * @see P.GAPS.09: Two-tier sync
+ * @see G.GAPS.07: NEVER use CRDT for particle sync
+ */
+
+interface PhysicsSyncConfig {
+    /** Target send rate in Hz (default: 60) */
+    sendRate: number;
+    /** Delta threshold — only send particles that moved more than this (default: 0.001) */
+    deltaThreshold: number;
+    /** Max particles per packet (default: 1000, ~25KB full / ~14KB delta) */
+    maxParticlesPerPacket: number;
+    /** Whether to use delta compression (default: true) */
+    useDelta: boolean;
+    /** Jitter buffer size in frames (default: 3) */
+    jitterBufferSize: number;
+    /** Interpolation method: 'none' | 'linear' | 'hermite' (default: 'linear') */
+    interpolation: 'none' | 'linear' | 'hermite';
+}
+interface SyncPacketHeader {
+    magic: number;
+    version: number;
+    sequence: number;
+    timestamp: number;
+    particleCount: number;
+    flags: number;
+}
+interface SyncStats {
+    packetsSent: number;
+    packetsReceived: number;
+    bytesPerSecond: number;
+    averageLatencyMs: number;
+    deltaRatio: number;
+    droppedPackets: number;
+}
+/**
+ * Encodes physics state from a UnifiedParticleBuffer into binary packets
+ * and sends them over a WebRTC DataChannel.
+ */
+declare class PhysicsSyncSender {
+    private config;
+    private sequence;
+    private sessionStartMs;
+    private lastPositions;
+    private packetsSent;
+    private bytesSent;
+    private lastStatResetMs;
+    private sendInterval;
+    constructor(config?: Partial<PhysicsSyncConfig>);
+    /**
+     * Start periodic sending. Calls encode() and sends over the channel.
+     */
+    startSending(buffer: UnifiedParticleBuffer, channel: {
+        send(data: ArrayBuffer): void;
+        readyState: string;
+    }): void;
+    /** Stop periodic sending. */
+    stopSending(): void;
+    /**
+     * Encode current buffer state into a binary packet.
+     * Returns null if no particles need sending.
+     */
+    encode(buffer: UnifiedParticleBuffer): ArrayBuffer | null;
+    private encodeFull;
+    private encodeDelta;
+    private writeHeader;
+    getStats(): Pick<SyncStats, 'packetsSent' | 'bytesPerSecond'>;
+    resetStats(): void;
+    dispose(): void;
+}
+/**
+ * Decodes binary physics packets and applies them to a local UnifiedParticleBuffer.
+ * Provides a jitter buffer for smooth interpolation.
+ */
+declare class PhysicsSyncReceiver {
+    private config;
+    private jitterBuffer;
+    private lastSequence;
+    private packetsReceived;
+    private droppedPackets;
+    private latencySum;
+    private sessionStartMs;
+    constructor(config?: Partial<PhysicsSyncConfig>);
+    /**
+     * Feed a raw packet from a DataChannel message event.
+     * Decodes the header and body, pushes to jitter buffer.
+     */
+    receivePacket(data: ArrayBuffer, buffer: UnifiedParticleBuffer): void;
+    private applyFull;
+    private applyDelta;
+    private pushToJitterBuffer;
+    /**
+     * Interpolate between buffered frames for smooth rendering.
+     * Call this at render time with the current render timestamp.
+     *
+     * @param renderTimestamp - ms since session start at render time
+     * @param buffer - target buffer to write interpolated state into
+     */
+    interpolate(renderTimestamp: number, buffer: UnifiedParticleBuffer): void;
+    getStats(): SyncStats;
+    dispose(): void;
+}
+/**
+ * Parse just the header of a physics sync packet.
+ * Useful for routing or filtering before full decode.
+ */
+declare function parsePacketHeader(data: ArrayBuffer): SyncPacketHeader | null;
+
+/**
+ * PIDController.ts
+ *
+ * Generic PID (Proportional-Integral-Derivative) controller with:
+ * - Configurable inner/outer cascade loop timing
+ * - Setpoint tracking with ramp-rate limiting
+ * - Velocity monitoring via filtered derivative
+ * - Thread-safe design for VR 90fps (11.1ms frame budget)
+ * - Anti-windup (clamping + back-calculation)
+ * - Derivative-on-measurement (avoids derivative kick)
+ *
+ * The generic type parameter T allows the controller to operate on
+ * scalar numbers, IVector3, quaternion error signals, or any type
+ * that implements the PIDControllable arithmetic interface.
+ *
+ * @module physics
+ * @reference W.032 (virtual economy PID), P.030.01 (control loop timing)
+ * @reference Trait constant: 'pid_controller' (robotics-industrial.ts)
+ */
+
+/**
+ * Arithmetic operations required for a type to be used with PIDController<T>.
+ *
+ * Implementations provided for `number` and `IVector3` below.
+ * Users can supply custom adapters for quaternion errors, joint-space vectors, etc.
+ */
+interface PIDArithmetic<T> {
+    /** Return the zero / identity element */
+    zero(): T;
+    /** a + b */
+    add(a: T, b: T): T;
+    /** a - b */
+    sub(a: T, b: T): T;
+    /** scalar * a */
+    scale(scalar: number, a: T): T;
+    /** Scalar magnitude (L2 norm for vectors, abs for scalars) */
+    magnitude(a: T): number;
+    /** Component-wise clamp between min and max scalars */
+    clamp(a: T, min: number, max: number): T;
+    /** Deep copy */
+    clone(a: T): T;
+}
+/**
+ * Arithmetic adapter for scalar `number` values.
+ */
+declare const ScalarArithmetic: PIDArithmetic<number>;
+/**
+ * Arithmetic adapter for IVector3 values.
+ */
+declare const Vector3Arithmetic: PIDArithmetic<IVector3>;
+/**
+ * PID gain parameters.
+ */
+interface PIDGains {
+    /** Proportional gain */
+    kP: number;
+    /** Integral gain */
+    kI: number;
+    /** Derivative gain */
+    kD: number;
+}
+/**
+ * Loop timing configuration for the cascade controller.
+ *
+ * The outer loop runs at `outerHz` and feeds its output as the setpoint
+ * for the inner loop, which runs at `innerHz`.
+ *
+ * For VR at 90fps, the inner loop should be >= 90Hz (typically 200-1000Hz
+ * when sub-stepping physics). The outer loop can be 30-90Hz for position control.
+ */
+interface LoopTimingConfig {
+    /** Inner loop frequency in Hz (default: 200) */
+    innerHz: number;
+    /** Outer loop frequency in Hz (default: 60) */
+    outerHz: number;
+}
+/**
+ * Full PID controller configuration.
+ */
+interface PIDControllerConfig<T> {
+    /** Unique controller identifier */
+    id: string;
+    /** Inner-loop PID gains (velocity/effort control) */
+    innerGains: PIDGains;
+    /** Outer-loop PID gains (position/setpoint control) */
+    outerGains: PIDGains;
+    /** Loop timing (Hz) */
+    timing: LoopTimingConfig;
+    /** Output limits (symmetric: -limit to +limit) */
+    outputLimit: number;
+    /** Integral term limit (anti-windup clamp) */
+    integralLimit: number;
+    /** Setpoint ramp rate per second (0 = instant) */
+    setpointRampRate: number;
+    /** Velocity limit for safety monitoring */
+    velocityLimit: number;
+    /** Derivative low-pass filter coefficient (0-1, higher = more filtering) */
+    derivativeFilterAlpha: number;
+    /** Initial setpoint */
+    initialSetpoint: T;
+    /**
+     * Enable derivative-on-measurement instead of derivative-on-error.
+     * Avoids "derivative kick" when setpoint changes abruptly. (default: true)
+     */
+    derivativeOnMeasurement: boolean;
+    /**
+     * Enable back-calculation anti-windup.
+     * When output saturates, the integral is reduced proportionally. (default: true)
+     */
+    backCalculationAntiWindup: boolean;
+    /** Back-calculation gain (Kb). Typically 1/kD or sqrt(kP/kI). */
+    backCalculationGain: number;
+}
+/**
+ * Default configuration factory.
+ */
+declare function defaultPIDConfig<T>(id: string, initialSetpoint: T, overrides?: Partial<PIDControllerConfig<T>>): PIDControllerConfig<T>;
+/**
+ * Fixed-size ring buffer for velocity history.
+ *
+ * Uses a simple circular array with modular indexing. In a single-threaded
+ * JS context this is inherently safe. For SharedArrayBuffer workers, the
+ * caller wraps reads/writes in Atomics (see `ThreadSafePIDState`).
+ */
+declare class VelocityRingBuffer {
+    private readonly buffer;
+    private readonly capacity;
+    private head;
+    private count;
+    constructor(capacity: number);
+    /** Push a magnitude sample. O(1). */
+    push(value: number): void;
+    /** Peek at the most recent sample. */
+    latest(): number;
+    /** Compute average over the buffer. */
+    average(): number;
+    /** Compute peak (maximum absolute) over the buffer. */
+    peak(): number;
+    /** Current sample count. */
+    size(): number;
+    /** Clear the buffer. */
+    clear(): void;
+}
+/**
+ * Observable state of a PID controller, safe to read from any thread/worker.
+ */
+interface PIDControllerState<T> {
+    /** Controller ID */
+    readonly id: string;
+    /** Current setpoint (possibly ramped) */
+    readonly setpoint: T;
+    /** Target setpoint (user-requested, before ramping) */
+    readonly targetSetpoint: T;
+    /** Latest measurement */
+    readonly measurement: T;
+    /** Current error (setpoint - measurement) */
+    readonly error: T;
+    /** Current integral accumulator */
+    readonly integral: T;
+    /** Current derivative term */
+    readonly derivative: T;
+    /** Outer-loop output (feeds inner-loop setpoint) */
+    readonly outerOutput: T;
+    /** Inner-loop output (final control output) */
+    readonly innerOutput: T;
+    /** Current output magnitude */
+    readonly outputMagnitude: number;
+    /** Whether output is saturated */
+    readonly isSaturated: boolean;
+    /** Current velocity magnitude */
+    readonly velocityMagnitude: number;
+    /** Whether velocity exceeds limit */
+    readonly isVelocityExceeded: boolean;
+    /** Accumulated simulation time (seconds) */
+    readonly elapsedTime: number;
+    /** Inner loop tick count */
+    readonly innerTickCount: number;
+    /** Outer loop tick count */
+    readonly outerTickCount: number;
+}
+/**
+ * PIDController<T> — Generic cascaded (inner/outer loop) PID controller.
+ *
+ * ## Architecture
+ *
+ * ```
+ * User Setpoint --> [Ramp Limiter] --> Outer Loop (position) --> Inner Loop (velocity) --> Output
+ *                                           ^                          ^
+ *                                           |                          |
+ *                                      measurement               measurement derivative
+ * ```
+ *
+ * ## Thread Safety
+ *
+ * All mutable state is contained within this class. The `getState()` method
+ * returns a frozen snapshot that can be safely read from render/worker threads.
+ * Internal computation uses no allocations in the hot path (pre-allocated math
+ * results via the arithmetic adapter).
+ *
+ * ## VR 90fps Constraint
+ *
+ * A single `step()` call completes in ~0.01-0.05ms (measured on i7-13700K).
+ * This is well within the 11.1ms frame budget. The `innerHz` setting allows
+ * sub-stepping at higher rates for smoother control, while the outer loop
+ * runs at a comfortable rate for setpoint tracking.
+ *
+ * ## Usage Example
+ *
+ * ```typescript
+ * // Scalar PID for a single-axis servo
+ * const servo = new PIDController(
+ *   defaultPIDConfig('servo-1', 0),
+ *   ScalarArithmetic,
+ * );
+ * servo.setSetpoint(90); // target 90 degrees
+ * const output = servo.step(currentAngle, 1/90); // at 90Hz
+ *
+ * // Vector3 PID for 3D position tracking
+ * const tracker = new PIDController(
+ *   defaultPIDConfig('pos-tracker', { x: 0, y: 0, z: 0 }),
+ *   Vector3Arithmetic,
+ * );
+ * tracker.setSetpoint({ x: 1, y: 2, z: 3 });
+ * const force = tracker.step(currentPosition, 1/200);
+ * ```
+ */
+declare class PIDController<T> {
+    private readonly config;
+    private readonly math;
+    private readonly outerLoop;
+    private readonly innerLoop;
+    private targetSetpoint;
+    private currentSetpoint;
+    private lastMeasurement;
+    private lastOuterOutput;
+    private lastInnerOutput;
+    private outerAccumulator;
+    private innerAccumulator;
+    private readonly outerDt;
+    private readonly innerDt;
+    private elapsedTime;
+    private innerTickCount;
+    private outerTickCount;
+    private readonly velocityHistory;
+    private currentVelocityMagnitude;
+    private isSaturated;
+    private isVelocityExceeded;
+    constructor(config: PIDControllerConfig<T>, math: PIDArithmetic<T>);
+    /**
+     * Set the target setpoint. If `setpointRampRate > 0`, the actual setpoint
+     * will ramp towards this target over time.
+     */
+    setSetpoint(target: T): void;
+    /**
+     * Get the current (possibly ramped) setpoint.
+     */
+    getSetpoint(): T;
+    /**
+     * Get the user-requested target setpoint.
+     */
+    getTargetSetpoint(): T;
+    /**
+     * Advance the controller by `dt` seconds, given the current measurement.
+     *
+     * This method handles the cascade timing internally:
+     * - Accumulates time for outer and inner loops
+     * - Runs outer loop at `outerHz` to produce a velocity/effort setpoint
+     * - Runs inner loop at `innerHz` using that setpoint
+     *
+     * @param measurement - Current process variable (e.g., position, angle)
+     * @param dt - Wall-clock delta time in seconds
+     * @returns The final control output
+     */
+    step(measurement: T, dt: number): T;
+    /**
+     * Simplified single-loop step (no cascade).
+     *
+     * Uses only the outer-loop gains for direct PID control.
+     * Useful for simple single-axis applications where cascade is overkill.
+     *
+     * @param measurement - Current process variable
+     * @param dt - Time delta in seconds
+     * @returns Control output
+     */
+    stepSingle(measurement: T, dt: number): T;
+    private updateSetpointRamp;
+    /**
+     * Returns a frozen snapshot of the controller state.
+     *
+     * This snapshot is safe to pass to render threads, Web Workers,
+     * or SharedArrayBuffer consumers. All values are deep-copied.
+     */
+    getState(): PIDControllerState<T>;
+    /**
+     * Get current velocity magnitude.
+     */
+    getVelocityMagnitude(): number;
+    /**
+     * Get average velocity over the history buffer.
+     */
+    getAverageVelocity(): number;
+    /**
+     * Get peak velocity from history buffer.
+     */
+    getPeakVelocity(): number;
+    /**
+     * Whether the velocity has exceeded the configured limit.
+     */
+    getIsVelocityExceeded(): boolean;
+    /**
+     * Update outer-loop gains at runtime.
+     * Creates a new outer loop with updated gains while preserving timing state.
+     */
+    setOuterGains(gains: PIDGains): void;
+    /**
+     * Update inner-loop gains at runtime.
+     */
+    setInnerGains(gains: PIDGains): void;
+    /**
+     * Reset controller to initial state.
+     * Clears integral windup, derivative history, velocity buffer.
+     */
+    reset(): void;
+    /**
+     * Get the controller configuration (read-only).
+     */
+    getConfig(): Readonly<PIDControllerConfig<T>>;
+    /**
+     * Get the controller ID.
+     */
+    getId(): string;
+}
+/**
+ * PIDControllerTrait — HoloScript trait wrapper for the generic PID controller.
+ *
+ * This matches the 'pid_controller' trait constant from robotics-industrial.ts
+ * and follows the same pattern as AIDriverTrait, VehicleSystem, etc.
+ */
+interface PIDControllerTraitConfig {
+    /** Controller ID */
+    id: string;
+    /** Control mode: 'scalar' for single-axis, 'vector3' for 3D */
+    mode: 'scalar' | 'vector3';
+    /** PID gains for outer loop */
+    outerGains?: Partial<PIDGains>;
+    /** PID gains for inner loop */
+    innerGains?: Partial<PIDGains>;
+    /** Timing configuration */
+    timing?: Partial<LoopTimingConfig>;
+    /** Output limit */
+    outputLimit?: number;
+    /** Integral limit (anti-windup) */
+    integralLimit?: number;
+    /** Setpoint ramp rate (units/sec, 0 = instant) */
+    setpointRampRate?: number;
+    /** Velocity limit for safety */
+    velocityLimit?: number;
+    /** Derivative filter alpha (0-1) */
+    derivativeFilterAlpha?: number;
+}
+/**
+ * Create a scalar PIDController from a trait config.
+ */
+declare function createScalarPIDController(config: PIDControllerTraitConfig): PIDController<number>;
+/**
+ * Create a Vector3 PIDController from a trait config.
+ */
+declare function createVector3PIDController(config: PIDControllerTraitConfig): PIDController<IVector3>;
+/**
+ * Factory function matching HoloScript trait pattern.
+ * Dispatches on config.mode to create the appropriate controller type.
+ */
+declare function createPIDControllerTrait(config: PIDControllerTraitConfig): PIDController<number> | PIDController<IVector3>;
+
+/**
+ * PhysicsActivation.ts
+ *
+ * Sleep/Wake activation system for character cloth and hair simulation.
+ * Determines WHEN physics solvers run (not HOW they run), providing massive
+ * performance savings for idle characters.
+ *
+ * 4-state machine: SLEEPING -> WAKING -> ACTIVE -> SETTLING -> SLEEPING
+ *
+ * Trigger sources: character velocity, wind force, external collision,
+ * animation events, gravity changes.
+ *
+ * Integrates with:
+ * - WeatherBlackboard (environment/WeatherBlackboard.ts) for global wind
+ * - ClothSim (physics/ClothSim.ts) for PBD cloth
+ * - PBDSolver (physics/PBDSolver.ts) for unified PBD pipeline
+ * - Spring-chain hair and strand-based GPU hair (wraps around existing solvers)
+ *
+ * Vision: research/2026-03-26_holoscript-characters-as-code-vision.md Section 8D
+ * Patterns: P.CHAR.005 (Physics Sleep/Wake), P.CHAR.006 (Environment Wind Zones)
+ * Gotchas: G.CHAR.005 (no pop on wake), G.CHAR.006 (EMA smoothing for self-wind)
+ *
+ * @module physics
+ */
+
+/**
+ * Physics activation state machine states.
+ *
+ * SLEEPING  — Baked rest pose, zero simulation cost.
+ * WAKING   — Blending from rest pose to simulated state (0.2-0.5s).
+ * ACTIVE   — Full physics simulation running.
+ * SETTLING — Sim continues with high damping (3-5x), capturing rest pose on sleep.
+ */
+declare enum PhysicsActivationState {
+    /** Baked rest pose. Zero sim cost. Hair/cloth perfectly still. */
+    SLEEPING = "SLEEPING",
+    /** Smoothly blend FROM rest pose TO sim over wake_blend duration. Prevents pop. */
+    WAKING = "WAKING",
+    /** Full physics simulation. PBD cloth, spring-chain hair, wind response. */
+    ACTIVE = "ACTIVE",
+    /** Sim runs with cranked damping. When all vertices < epsilon, capture rest pose -> SLEEPING. */
+    SETTLING = "SETTLING"
+}
+/**
+ * Types of triggers that can wake a sleeping simulation.
+ */
+declare enum ActivationTriggerType {
+    /** Character root bone velocity exceeds threshold */
+    VELOCITY = "velocity",
+    /** Wind force on any vertex exceeds threshold */
+    WIND = "wind",
+    /** External collision contact detected */
+    COLLISION = "collision",
+    /** Animation state machine fires a wake event */
+    ANIMATION = "animation",
+    /** Gravity vector changes */
+    GRAVITY = "gravity"
+}
+/**
+ * Wind zone types for localized wind sources.
+ */
+declare enum WindZoneType {
+    /** Radiates from a point (e.g., fireplace updraft) */
+    POINT = "point",
+    /** Directional cone (e.g., open window, vent) */
+    DIRECTIONAL = "directional",
+    /** Uniform across entire scene (e.g., battlefield wind) */
+    GLOBAL = "global"
+}
+/**
+ * Threshold-based trigger config (velocity, wind, gravity).
+ */
+interface ThresholdTriggerConfig {
+    /** Force/velocity magnitude that causes a wake from SLEEPING */
+    wake: number;
+    /** Force/velocity magnitude below which the trigger is considered inactive */
+    sleep: number;
+    /** How long the value must stay below `sleep` before trigger is considered cleared (seconds) */
+    sleepDelay: number;
+}
+/**
+ * Collision trigger config (any contact = wake).
+ */
+interface CollisionTriggerConfig {
+    /** true = any collision wakes (default). false = disabled */
+    wake: boolean;
+    /** Seconds after last contact before collision trigger clears */
+    sleepDelay: number;
+}
+/**
+ * Animation event trigger config.
+ */
+interface AnimationTriggerConfig {
+    /** Animation state machine events that trigger a wake */
+    events: string[];
+}
+/**
+ * Combined trigger configuration block.
+ * All fields are optional — if omitted, that trigger source is disabled.
+ */
+interface ActivationTriggers {
+    velocity?: ThresholdTriggerConfig;
+    wind?: ThresholdTriggerConfig;
+    collision?: CollisionTriggerConfig;
+    animation?: AnimationTriggerConfig;
+    gravity?: ThresholdTriggerConfig;
+}
+/**
+ * A single point on the locomotion intensity curve.
+ * Speed in m/s, intensity 0-1.
+ */
+interface IntensityCurvePoint {
+    speed: number;
+    intensity: number;
+}
+/**
+ * Default intensity curve from vision doc:
+ * idle=0, walk(1.4)=0.2, jog(3.0)=0.5, run(5.0)=0.7, Sprint(8.0)=1.0
+ */
+declare const DEFAULT_INTENSITY_CURVE: IntensityCurvePoint[];
+/**
+ * Locomotion-driven physics intensity configuration.
+ */
+interface LocomotionConfig {
+    /** Enable self-wind from character movement (headwind opposing motion) */
+    selfWind: boolean;
+    /** Scale factor for self-wind (0-1). 0.6 = 60% of velocity as opposing wind */
+    selfWindScale: number;
+    /** Intensity curve mapping velocity to sim intensity 0-1 */
+    intensityCurve: IntensityCurvePoint[];
+    /** EMA alpha for velocity smoothing (G.CHAR.006). Lower = smoother. Default 0.1 */
+    emaAlpha: number;
+}
+/**
+ * Default locomotion config.
+ */
+declare const DEFAULT_LOCOMOTION_CONFIG: LocomotionConfig;
+/**
+ * Gust cycle configuration for periodic wind surges.
+ */
+interface GustConfig {
+    /** Time between gusts in seconds */
+    interval: number;
+    /** Peak force multiplier during gust */
+    strength: number;
+    /** How long each gust lasts in seconds */
+    duration: number;
+}
+/**
+ * An environment wind zone (localized or global wind source).
+ */
+interface WindZone {
+    /** Unique identifier */
+    id: string;
+    /** Zone type */
+    type: WindZoneType;
+    /** World-space position (for POINT and DIRECTIONAL) */
+    position?: IVector3;
+    /** Force direction (normalized for DIRECTIONAL/GLOBAL) */
+    direction: IVector3;
+    /** Base force magnitude */
+    force: number;
+    /** Effective radius (for POINT zones) */
+    radius?: number;
+    /** Cone half-angle in radians (for DIRECTIONAL zones) */
+    coneAngle?: number;
+    /** Turbulence amount 0-1 (adds noise to force) */
+    turbulence: number;
+    /** Optional gust cycle */
+    gust?: GustConfig;
+    /** Whether zone is active */
+    enabled: boolean;
+}
+/**
+ * Full physics activation controller configuration.
+ *
+ * HoloScript syntax maps directly:
+ * ```holoscript
+ * activation {
+ *   mode: trigger_based
+ *   rest_pose: "cape_rest.glb"
+ *   triggers { velocity: {wake: 0.1, sleep: 0.05, sleep_delay: 0.5s} ... }
+ *   wake_blend: 0.3s
+ *   settle_damping: 3.0
+ *   settle_threshold: 0.001
+ * }
+ * ```
+ */
+interface PhysicsActivationConfig {
+    /** Activation mode: 'trigger_based' for sleep/wake, 'always_on' to skip activation */
+    mode: 'trigger_based' | 'always_on';
+    /** Trigger configuration */
+    triggers: ActivationTriggers;
+    /** Duration of WAKING blend from rest pose to sim (seconds). Default 0.3 */
+    wakeBlendDuration: number;
+    /** Damping multiplier during SETTLING state. Default 3.0 */
+    settleDamping: number;
+    /** Velocity epsilon below which all vertices are considered at rest. Default 0.001 */
+    settleThreshold: number;
+    /** Maximum SETTLING duration before forcing sleep (seconds). Default 2.0 */
+    maxSettleDuration: number;
+    /** Locomotion-driven intensity config (optional) */
+    locomotion?: LocomotionConfig;
+}
+/**
+ * Default activation config.
+ */
+declare const DEFAULT_ACTIVATION_CONFIG: PhysicsActivationConfig;
+/**
+ * Manages environment wind zones and computes aggregate wind force at a point.
+ * Connects to WeatherBlackboard for global/ambient wind.
+ */
+declare class WindZoneManager {
+    private zones;
+    private time;
+    /**
+     * Add or update a wind zone.
+     */
+    addZone(zone: WindZone): void;
+    /**
+     * Remove a wind zone by ID.
+     */
+    removeZone(id: string): boolean;
+    /**
+     * Get a wind zone by ID.
+     */
+    getZone(id: string): WindZone | undefined;
+    /**
+     * Get all registered wind zones.
+     */
+    getAllZones(): WindZone[];
+    /**
+     * Advance internal time (for gust cycles).
+     */
+    advanceTime(dt: number): void;
+    /**
+     * Get the current internal time.
+     */
+    getTime(): number;
+    /**
+     * Compute the aggregate wind force at a world-space position,
+     * combining all active wind zones + optional WeatherBlackboard ambient wind.
+     *
+     * @param worldPos - Sample point in world space
+     * @param weather - Optional WeatherBlackboard state for ambient wind
+     * @returns Aggregate wind force vector
+     */
+    computeWindAt(worldPos: IVector3, weather?: WeatherBlackboardState): IVector3;
+    /**
+     * Compute a single zone's contribution at a point.
+     */
+    private computeZoneContribution;
+}
+/**
+ * Smooths a 3D velocity vector using Exponential Moving Average.
+ * Prevents hair/cloth whip on instant direction changes (G.CHAR.006).
+ *
+ * EMA formula: smoothed = alpha * current + (1 - alpha) * previous
+ * Lower alpha = smoother (more lag), higher alpha = more responsive.
+ */
+declare class VelocitySmoother {
+    private smoothedX;
+    private smoothedY;
+    private smoothedZ;
+    private initialized;
+    private readonly alpha;
+    constructor(alpha?: number);
+    /**
+     * Update with a new raw velocity sample and return smoothed result.
+     */
+    update(raw: IVector3): IVector3;
+    /**
+     * Get current smoothed velocity without updating.
+     */
+    getCurrent(): IVector3;
+    /**
+     * Get the magnitude of the current smoothed velocity.
+     */
+    getSpeed(): number;
+    /**
+     * Reset to uninitialized state.
+     */
+    reset(): void;
+}
+/**
+ * Evaluates the physics intensity (0-1) from a speed value using
+ * the configured intensity curve (piecewise linear interpolation).
+ */
+declare function evaluateIntensityCurve(speed: number, curve: IntensityCurvePoint[]): number;
+/**
+ * Compute the self-wind vector from character velocity.
+ * Self-wind opposes movement direction (headwind effect).
+ *
+ * @param smoothedVelocity - EMA-smoothed character velocity
+ * @param scale - Self-wind scale factor (0-1)
+ * @returns Opposing wind force vector
+ */
+declare function computeSelfWind(smoothedVelocity: IVector3, scale: number): IVector3;
+/**
+ * Per-frame input to the activation controller.
+ */
+interface ActivationUpdateInput {
+    /** Character root bone velocity (raw, will be EMA-smoothed internally) */
+    characterVelocity?: IVector3;
+    /** External wind force at simulation position */
+    windForce?: IVector3;
+    /** Current gravity vector (for gravity change detection) */
+    gravity?: IVector3;
+}
+/**
+ * Per-simulation activation controller.
+ *
+ * One controller per cloth/hair simulation instance. Manages the 4-state
+ * sleep/wake machine, evaluates triggers, computes locomotion intensity,
+ * and provides blending parameters for the owning solver.
+ *
+ * The controller does NOT run physics itself. It tells the solver:
+ * - Whether to simulate this frame (isSimulating())
+ * - What damping to use (getEffectiveDamping())
+ * - What wind force to apply (getEffectiveWind())
+ * - The current blend weight for WAKING transitions (getBlendWeight())
+ * - The current physics intensity from locomotion (getIntensity())
+ *
+ * Usage:
+ * ```typescript
+ * const ctrl = new PhysicsActivationController(config);
+ * // Each frame:
+ * ctrl.update(dt, { characterVelocity, windForce, ... });
+ * if (ctrl.isSimulating()) {
+ *   solver.setDamping(ctrl.getEffectiveDamping(baseDamping));
+ *   solver.setWind(ctrl.getEffectiveWind());
+ *   solver.step(dt);
+ * }
+ * ```
+ */
+declare class PhysicsActivationController {
+    private state;
+    private config;
+    private stateTime;
+    private triggerStates;
+    private velocitySmoother;
+    private currentIntensity;
+    private selfWindVector;
+    private currentWindForce;
+    private maxVertexVelocity;
+    private previousGravity;
+    private activeAnimationEvents;
+    constructor(config?: Partial<PhysicsActivationConfig>);
+    /**
+     * Get the current activation state.
+     */
+    getState(): PhysicsActivationState;
+    /**
+     * Whether the physics solver should run this frame.
+     * SLEEPING = false, all others = true.
+     * If mode is 'always_on', always returns true.
+     */
+    isSimulating(): boolean;
+    /**
+     * Get the current blend weight for WAKING transitions.
+     * 0.0 = fully rest pose, 1.0 = fully simulated.
+     * Returns 1.0 for ACTIVE and SETTLING states.
+     */
+    getBlendWeight(): number;
+    /**
+     * Get the effective damping multiplier.
+     * During SETTLING, damping is multiplied by settleDamping (3-5x).
+     * Otherwise returns 1.0 (no modification to base damping).
+     */
+    getEffectiveDampingMultiplier(): number;
+    /**
+     * Apply the activation damping multiplier to a base damping value.
+     * Clamps result to [0, 1].
+     */
+    getEffectiveDamping(baseDamping: number): number;
+    /**
+     * Get current physics intensity from locomotion (0-1).
+     * Controls stiffness reduction, wind multiplier, inertia response.
+     */
+    getIntensity(): number;
+    /**
+     * Get the current self-wind vector from character locomotion.
+     * Opposes movement direction (headwind effect).
+     */
+    getSelfWind(): IVector3;
+    /**
+     * Get the last computed external wind force at the simulation's position.
+     */
+    getWindForce(): IVector3;
+    /**
+     * Get the total effective wind = external wind + self-wind.
+     */
+    getEffectiveWind(): IVector3;
+    /**
+     * Get how long the controller has been in the current state (seconds).
+     */
+    getStateTime(): number;
+    /**
+     * Check if any trigger is currently active.
+     */
+    hasActiveTrigger(): boolean;
+    /**
+     * Check if a specific trigger type is currently active.
+     */
+    isTriggerActive(type: ActivationTriggerType): boolean;
+    /**
+     * Get the configuration.
+     */
+    getConfig(): Readonly<PhysicsActivationConfig>;
+    /**
+     * Notify the controller of an animation event (e.g., "jump", "attack").
+     * If the event matches a configured trigger, it activates.
+     */
+    notifyAnimationEvent(eventName: string): void;
+    /**
+     * Notify the controller of a collision event.
+     */
+    notifyCollision(): void;
+    /**
+     * Provide the maximum vertex velocity for SETTLING convergence check.
+     * The solver should call this each frame with the max velocity across all particles.
+     */
+    reportMaxVertexVelocity(velocity: number): void;
+    /**
+     * Force an immediate transition to a specific state.
+     * Use with caution — typically the state machine manages transitions.
+     */
+    forceState(state: PhysicsActivationState): void;
+    /**
+     * Main update. Call once per frame before running the physics solver.
+     *
+     * @param dt - Delta time in seconds
+     * @param input - Frame input (velocity, wind, gravity)
+     */
+    update(dt: number, input?: ActivationUpdateInput): void;
+    private updateVelocityTrigger;
+    private updateWindTrigger;
+    private updateAnimationTrigger;
+    private updateGravityTrigger;
+    private updateCollisionTriggerDecay;
+    private decayTriggerDelays;
+    private updateLocomotion;
+    private updateStateMachine;
+    private transitionTo;
+}
+
+/**
+ * SoftBodyAdapter
+ *
+ * Bridges the HoloScript Entity/Node system with the SoftBodySolver (PBD).
+ * Handles the conversion of Mesh vertices to Particles and syncs them back.
+ *
+ * @version 1.0.0
+ */
+declare class SoftBodyAdapter {
+    private solver;
+    private node;
+    private vertexMapping;
+    constructor(node: any, config: any);
+    update(dt: number): void;
+    private createSoftBodyFromMesh;
+    private syncBackToMesh;
+}
+
+interface Particle {
+    position: [number, number, number];
+    previousPosition: [number, number, number];
+    velocity: [number, number, number];
+    invMass: number;
+}
+interface DistanceConstraint {
+    p1: number;
+    p2: number;
+    restLength: number;
+    stiffness: number;
+}
+declare class SoftBodySolver {
+    private particles;
+    private constraints;
+    private gravity;
+    private substeps;
+    constructor(particles: Particle[], constraints: DistanceConstraint[]);
+    /**
+     * Step the simulation using PBD.
+     */
+    step(dt: number): void;
+    private predictPositions;
+    private solveConstraints;
+    private updateVelocities;
+    getParticles(): Particle[];
+    getConstraints(): DistanceConstraint[];
+}
+
+/**
+ * VRPhysicsBridge.ts
+ *
+ * Bridges the gap between WebXR input (Hands/Headset) and the Physics Engine.
+ * Responsibilities:
+ * 1. Create/Update Kinematic Bodies for hands/fingers.
+ * 2. Sync velocity for throwing mechanics.
+ * 3. Manage collision layers for hands (to avoid self-collision if needed).
+ */
+
+declare class VRPhysicsBridge {
+    private world;
+    private handBodies;
+    private lastPositions;
+    private lastRotations;
+    private onHaptic;
+    constructor(world: IPhysicsWorld, onHaptic?: (hand: 'left' | 'right', intensity: number, duration: number) => void);
+    update(vrContext: {
+        hands: {
+            left: VRHand | null;
+            right: VRHand | null;
+        };
+    }, delta: number): void;
+    private checkCollisions;
+    updateHand(hand: VRHand | null, side: 'left' | 'right', delta: number): void;
+    getHandBodyId(side: 'left' | 'right'): string | null;
+}
+
+/**
+ * ClothSim.ts
+ *
+ * Mass-spring cloth simulation: particle grid, distance constraints,
+ * pin points, wind, gravity, and self-collision.
+ *
+ * @module physics
+ */
+interface ClothParticle {
+    x: number;
+    y: number;
+    z: number;
+    prevX: number;
+    prevY: number;
+    prevZ: number;
+    mass: number;
+    pinned: boolean;
+}
+interface ClothConstraint {
+    particleA: number;
+    particleB: number;
+    restLength: number;
+    stiffness: number;
+}
+interface ClothConfig {
+    gravity: number;
+    damping: number;
+    iterations: number;
+    wind: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+declare class ClothSim {
+    private particles;
+    private constraints;
+    private config;
+    private width;
+    private height;
+    constructor(config?: Partial<ClothConfig>);
+    createGrid(width: number, height: number, spacing: number): void;
+    private addConstraint;
+    pin(index: number): void;
+    unpin(index: number): void;
+    pinTopRow(): void;
+    update(dt: number): void;
+    setWind(x: number, y: number, z: number): void;
+    getParticle(index: number): ClothParticle | undefined;
+    getParticleCount(): number;
+    getConstraintCount(): number;
+    getGridSize(): {
+        width: number;
+        height: number;
+    };
+    getAABB(): {
+        min: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        max: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    };
+}
+
+/**
+ * ConstraintSolver.ts
+ *
+ * Sequential Impulse constraint solver for the HoloScript physics engine.
+ * Supports all 8 constraint types defined in PhysicsTypes.ts.
+ *
+ * Features:
+ * - Warm starting for convergence acceleration
+ * - Baumgarte stabilization for drift correction
+ * - Motor and limit support for hinge/slider joints
+ *
+ * @module physics
+ */
+
+interface ConstraintSolverConfig {
+    iterations: number;
+    baumgarte: number;
+    warmStarting: boolean;
+    slop: number;
+}
+declare class ConstraintSolver {
+    private config;
+    private solved;
+    constructor(config?: Partial<ConstraintSolverConfig>);
+    /**
+     * Add a constraint to be solved.
+     */
+    addConstraint(constraint: Constraint, bodyA: IRigidBodyState, bodyB?: IRigidBodyState | null): void;
+    /**
+     * Remove a constraint by ID.
+     */
+    removeConstraint(constraintId: string): boolean;
+    /**
+     * Get all active constraints.
+     */
+    getConstraints(): Constraint[];
+    /**
+     * Solve all constraints for one timestep.
+     * Returns velocity corrections to apply to rigid bodies.
+     */
+    solve(dt: number): Map<string, {
+        linearVelocity: IVector3;
+        angularVelocity: IVector3;
+    }>;
+    /**
+     * Get broken constraint IDs.
+     */
+    getBrokenConstraints(): string[];
+    /**
+     * Clear all constraints.
+     */
+    clear(): void;
+    private solveConstraint;
+    private solveFixed;
+    private solveDistance;
+    private solveSpring;
+    private solveHinge;
+    private solveBall;
+    private solveSlider;
+    private solveCone;
+    private solveGeneric6DOF;
+    private applyWarmStart;
+    private accumulateCorrection;
+}
+
+/**
+ * DeformableMesh.ts
+ *
+ * Deformable mesh: vertex displacement, spring-damper networks,
+ * shape matching for volume preservation, and impact deformation.
+ *
+ * @module physics
+ */
+interface DeformVertex {
+    rest: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    current: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    velocity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    mass: number;
+    locked: boolean;
+}
+interface DeformSpring {
+    a: number;
+    b: number;
+    restLength: number;
+    stiffness: number;
+    damping: number;
+}
+interface DeformConfig {
+    stiffness: number;
+    damping: number;
+    shapeMatchingStrength: number;
+    maxDisplacement: number;
+    plasticity: number;
+}
+declare class DeformableMesh {
+    private vertices;
+    private springs;
+    private config;
+    private restCentroid;
+    constructor(config?: Partial<DeformConfig>);
+    setVertices(positions: Array<{
+        x: number;
+        y: number;
+        z: number;
+    }>): void;
+    addSpring(a: number, b: number, stiffness?: number, damping?: number): void;
+    autoConnectRadius(radius: number): void;
+    private computeRestCentroid;
+    applyImpact(center: {
+        x: number;
+        y: number;
+        z: number;
+    }, radius: number, force: number): void;
+    update(dt: number): void;
+    getVertices(): DeformVertex[];
+    getVertex(index: number): DeformVertex | undefined;
+    getVertexCount(): number;
+    getSpringCount(): number;
+    getDisplacement(index: number): number;
+    getMaxDisplacement(): number;
+}
+
+/**
+ * FluidSim.ts
+ *
+ * SPH fluid: particle-based fluid simulation, viscosity,
+ * surface tension, boundary handling, and density queries.
+ *
+ * @module physics
+ */
+interface FluidParticle {
+    position: [number, number, number];
+    velocity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    density: number;
+    pressure: number;
+    mass: number;
+}
+interface FluidConfig {
+    restDensity: number;
+    gasConstant: number;
+    viscosity: number;
+    surfaceTension: number;
+    gravity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    smoothingRadius: number;
+    timeStep: number;
+    boundaryMin: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    boundaryMax: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    boundaryDamping: number;
+}
+declare class FluidSim {
+    private particles;
+    private config;
+    constructor(config?: Partial<FluidConfig>);
+    addParticle(position: [number, number, number], velocity?: {
+        x: number;
+        y: number;
+        z: number;
+    }): void;
+    addBlock(min: {
+        x: number;
+        y: number;
+        z: number;
+    }, max: {
+        x: number;
+        y: number;
+        z: number;
+    }, spacing: number): number;
+    private poly6;
+    private spikyGrad;
+    private viscosityLaplacian;
+    update(): void;
+    private enforceBoundaries;
+    getParticles(): FluidParticle[];
+    getParticleCount(): number;
+    getAverageDensity(): number;
+    getKineticEnergy(): number;
+    clear(): void;
+    setConfig(config: Partial<FluidConfig>): void;
+}
+
+/**
+ * JointSystem.ts
+ *
+ * Physics joint types: hinge, ball, slider, spring, distance, fixed.
+ * Constraint solving, breakable joints, and motor forces.
+ *
+ * @module physics
+ */
+type JointType = 'hinge' | 'ball' | 'slider' | 'spring' | 'distance' | 'fixed';
+interface JointDef {
+    id: string;
+    type: JointType;
+    bodyA: string;
+    bodyB: string;
+    anchorA: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    anchorB: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    axis?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    limits?: {
+        min: number;
+        max: number;
+    };
+    breakForce: number;
+    stiffness: number;
+    damping: number;
+    motorSpeed: number;
+    motorForce: number;
+    broken: boolean;
+    enabled: boolean;
+}
+interface JointState {
+    currentForce: number;
+    currentAngle: number;
+    currentDistance: number;
+}
+declare class JointSystem {
+    private joints;
+    private states;
+    private bodyJoints;
+    createJoint(type: JointType, bodyA: string, bodyB: string, config?: Partial<JointDef>): JointDef;
+    removeJoint(id: string): boolean;
+    solve(dt: number): void;
+    setMotor(id: string, speed: number, force: number): void;
+    setEnabled(id: string, enabled: boolean): void;
+    setAngle(id: string, angle: number): void;
+    setDistance(id: string, dist: number): void;
+    getJoint(id: string): JointDef | undefined;
+    getState(id: string): JointState | undefined;
+    getJointCount(): number;
+    getBrokenJoints(): JointDef[];
+    getJointsForBody(bodyId: string): JointDef[];
+    private distance3D;
+}
+
+/**
+ * RagdollController.ts
+ *
+ * Ragdoll physics: bone chain definition, joint limits,
+ * active/ragdoll blending, and impulse application.
+ *
+ * @module physics
+ */
+interface RagdollBone {
+    id: string;
+    name: string;
+    parentId: string | null;
+    position: [number, number, number];
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    velocity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    angularVelocity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    mass: number;
+    length: number;
+    jointLimits: {
+        min: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        max: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    };
+}
+interface RagdollConfig {
+    gravity: number;
+    damping: number;
+    iterations: number;
+}
+type RagdollState = 'active' | 'ragdoll' | 'blending';
+declare class RagdollController {
+    private bones;
+    private rootBone;
+    private state;
+    private blendFactor;
+    private blendSpeed;
+    private config;
+    constructor(config?: Partial<RagdollConfig>);
+    addBone(name: string, parentId: string | null, mass: number, length: number, limits?: {
+        min: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        max: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    }): RagdollBone;
+    removeBone(name: string): boolean;
+    activate(): void;
+    goRagdoll(): void;
+    startBlend(toRagdoll?: boolean): void;
+    getState(): RagdollState;
+    getBlendFactor(): number;
+    update(dt: number): void;
+    applyImpulse(boneId: string, impulse: {
+        x: number;
+        y: number;
+        z: number;
+    }): void;
+    getBone(id: string): RagdollBone | undefined;
+    getBoneCount(): number;
+    getRootBone(): RagdollBone | undefined;
+    getChildren(boneId: string): RagdollBone[];
+}
+
+/**
+ * RagdollSystem.ts
+ *
+ * Ragdoll physics system for articulated character bodies.
+ * Creates rigid body chains with cone/hinge constraints for humanoid and quadruped skeletons.
+ *
+ * @module physics
+ */
+
+interface BoneDefinition {
+    id: string;
+    parentBone?: string;
+    length: number;
+    radius: number;
+    mass: number;
+    localOffset: IVector3;
+    jointType: 'cone' | 'hinge';
+    jointLimits?: {
+        swingSpan1?: number;
+        swingSpan2?: number;
+        twistSpan?: number;
+        low?: number;
+        high?: number;
+    };
+}
+interface RagdollDefinition {
+    id: string;
+    bones: BoneDefinition[];
+}
+interface RagdollInstance {
+    id: string;
+    definition: RagdollDefinition;
+    bodies: IRigidBodyConfig[];
+    constraints: Constraint[];
+    rootPosition: IVector3;
+}
+declare const HUMANOID_PRESET: BoneDefinition[];
+declare const QUADRUPED_PRESET: BoneDefinition[];
+declare class RagdollSystem {
+    private ragdolls;
+    /**
+     * Create a ragdoll from a definition at a given world position.
+     */
+    createRagdoll(definition: RagdollDefinition, rootPosition: IVector3): RagdollInstance;
+    /**
+     * Create humanoid ragdoll from preset.
+     */
+    createHumanoid(id: string, rootPosition: IVector3): RagdollInstance;
+    /**
+     * Create quadruped ragdoll from preset.
+     */
+    createQuadruped(id: string, rootPosition: IVector3): RagdollInstance;
+    /**
+     * Get a ragdoll instance by ID.
+     */
+    getRagdoll(id: string): RagdollInstance | undefined;
+    /**
+     * Remove a ragdoll.
+     */
+    removeRagdoll(id: string): boolean;
+    /**
+     * Get total mass of a ragdoll.
+     */
+    getTotalMass(id: string): number;
+}
+
+/**
+ * RaycastSystem.ts
+ *
+ * Raycasting: ray-AABB, ray-sphere, ray-plane intersection tests,
+ * distance sorting, layer masks, and batch queries.
+ *
+ * @module physics
+ */
+interface Ray {
+    origin: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    direction: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+interface AABB {
+    min: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    max: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+interface Sphere {
+    center: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    radius: number;
+}
+interface Plane {
+    normal: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    distance: number;
+}
+interface RayHit {
+    entityId: string;
+    distance: number;
+    point: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    normal: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+interface Collider {
+    entityId: string;
+    type: 'aabb' | 'sphere' | 'plane';
+    shape: AABB | Sphere | Plane;
+    layer: number;
+}
+declare class RaycastSystem {
+    private colliders;
+    addCollider(collider: Collider): void;
+    removeCollider(entityId: string): void;
+    getColliderCount(): number;
+    raycast(ray: Ray, maxDistance?: number, layerMask?: number): RayHit | null;
+    raycastAll(ray: Ray, maxDistance?: number, layerMask?: number): RayHit[];
+    private rayAABB;
+    private raySphere;
+    private rayPlane;
+    private normalize;
+}
+
+/**
+ * RopeSystem.ts
+ *
+ * Verlet rope/chain: segment links, tension, pin/attach points,
+ * gravity, damping, and length constraints.
+ *
+ * @module physics
+ */
+interface RopeNode {
+    position: [number, number, number];
+    previous: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    mass: number;
+    pinned: boolean;
+}
+interface RopeConfig {
+    segmentCount: number;
+    segmentLength: number;
+    gravity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    damping: number;
+    iterations: number;
+    elasticity: number;
+}
+interface RopeAttachment {
+    nodeIndex: number;
+    entityId: string;
+    offset: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+declare class RopeSystem {
+    private ropes;
+    createRope(id: string, start: {
+        x: number;
+        y: number;
+        z: number;
+    }, end: {
+        x: number;
+        y: number;
+        z: number;
+    }, config?: Partial<RopeConfig>): void;
+    pinNode(ropeId: string, nodeIndex: number): void;
+    unpinNode(ropeId: string, nodeIndex: number): void;
+    attach(ropeId: string, attachment: RopeAttachment): void;
+    update(dt: number): void;
+    getRopeNodes(ropeId: string): RopeNode[];
+    getRopeLength(ropeId: string): number;
+    getTension(ropeId: string, nodeIndex: number): number;
+    getRopeCount(): number;
+    removeRope(id: string): void;
+}
+
+/**
+ * TriggerZone.ts
+ *
+ * Trigger zones: enter/stay/exit callbacks, shape overlap tests,
+ * zone stacking, and entity tracking.
+ *
+ * @module physics
+ */
+type TriggerEvent = 'enter' | 'stay' | 'exit';
+type TriggerCallback = (entityId: string, zoneId: string, event: TriggerEvent) => void;
+interface TriggerShape {
+    type: 'box' | 'sphere';
+    position: [number, number, number];
+    halfExtents?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    radius?: number;
+}
+interface TriggerZoneConfig {
+    id: string;
+    shape: TriggerShape;
+    enabled: boolean;
+    tags: string[];
+}
+declare class TriggerZoneSystem {
+    private zones;
+    private callbacks;
+    private occupants;
+    addZone(config: TriggerZoneConfig): void;
+    removeZone(id: string): void;
+    enableZone(id: string, enabled: boolean): void;
+    onTrigger(zoneId: string, callback: TriggerCallback): void;
+    private fire;
+    update(entities: Array<{
+        id: string;
+        position: [number, number, number];
+        radius?: number;
+    }>): void;
+    private overlaps;
+    isInside(entityId: string, zoneId: string): boolean;
+    getOccupants(zoneId: string): string[];
+    getZonesForEntity(entityId: string): string[];
+    getZoneCount(): number;
+}
+
+/**
+ * VehicleSystem.ts
+ *
+ * Raycast vehicle physics system.
+ * Implements suspension springs, wheel friction, steering, and drivetrain simulation.
+ *
+ * @module physics
+ */
+
+interface WheelConfig {
+    id: string;
+    connectionPoint: IVector3;
+    direction: IVector3;
+    axle: IVector3;
+    suspensionRestLength: number;
+    suspensionStiffness: number;
+    suspensionDamping: number;
+    maxSuspensionTravel: number;
+    wheelRadius: number;
+    frictionSlip: number;
+    isSteering: boolean;
+    isDriving: boolean;
+    rollInfluence: number;
+}
+interface VehicleDefinition {
+    id: string;
+    chassisMass: number;
+    chassisSize: IVector3;
+    wheels: WheelConfig[];
+    maxSteerAngle: number;
+    maxEngineForce: number;
+    maxBrakeForce: number;
+}
+interface WheelState {
+    config: WheelConfig;
+    suspensionLength: number;
+    suspensionForce: number;
+    contactPoint: IVector3 | null;
+    isGrounded: boolean;
+    rotation: number;
+    steerAngle: number;
+    skidFactor: number;
+}
+interface VehicleState {
+    id: string;
+    definition: VehicleDefinition;
+    position: IVector3;
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+    linearVelocity: IVector3;
+    angularVelocity: IVector3;
+    wheels: WheelState[];
+    speed: number;
+    engineForce: number;
+    brakeForce: number;
+    steerAngle: number;
+}
+declare function createDefaultCar(id: string): VehicleDefinition;
+declare function createTruck(id: string): VehicleDefinition;
+declare class VehicleSystem {
+    private vehicles;
+    /**
+     * Create a vehicle from a definition at a given position.
+     */
+    createVehicle(definition: VehicleDefinition, position: IVector3): VehicleState;
+    /**
+     * Update vehicle physics for one timestep.
+     */
+    update(vehicleId: string, dt: number): VehicleState | null;
+    setThrottle(vehicleId: string, throttle: number): void;
+    setBrake(vehicleId: string, brake: number): void;
+    setSteering(vehicleId: string, steering: number): void;
+    getVehicle(vehicleId: string): VehicleState | undefined;
+    removeVehicle(vehicleId: string): boolean;
+    private getForwardVector;
+}
+
+/**
+ * SpatialHash.ts
+ *
+ * Grid-based spatial hash for broad-phase collision detection:
+ * insert/remove/query, cell management, and neighbor iteration.
+ *
+ * @module physics
+ */
+interface SpatialEntry {
+    id: string;
+    x: number;
+    y: number;
+    z: number;
+    radius: number;
+}
+declare class SpatialHash {
+    private cellSize;
+    private cells;
+    private entries;
+    constructor(cellSize: number);
+    insert(entry: SpatialEntry): void;
+    remove(id: string): void;
+    update(id: string, x: number, y: number, z: number): void;
+    queryPoint(x: number, y: number, z: number): string[];
+    queryRadius(x: number, y: number, z: number, radius: number): string[];
+    getNearbyPairs(): Array<[string, string]>;
+    private getCellsForEntry;
+    private cellKey;
+    getEntryCount(): number;
+    getCellCount(): number;
+    clear(): void;
+}
+
+/**
+ * Physics module
+ *
+ * Provides rigid body dynamics, collision detection, constraint solving,
+ * and spatial queries for the HoloScript engine.
+ *
+ * @module physics
+ */
+
+type index_AABB = AABB;
+type index_ActivationTriggerType = ActivationTriggerType;
+declare const index_ActivationTriggerType: typeof ActivationTriggerType;
+type index_ActivationTriggers = ActivationTriggers;
+type index_ActivationUpdateInput = ActivationUpdateInput;
+type index_AnimationTriggerConfig = AnimationTriggerConfig;
+declare const index_BodyType: typeof BodyType;
+type index_BoneDefinition = BoneDefinition;
+type index_BoundaryCoupling = BoundaryCoupling;
+declare const index_COLLISION_GROUPS: typeof COLLISION_GROUPS;
+type index_ClothConfig = ClothConfig;
+type index_ClothConstraint = ClothConstraint;
+type index_ClothParticle = ClothParticle;
+type index_ClothSim = ClothSim;
+declare const index_ClothSim: typeof ClothSim;
+type index_Collider = Collider;
+declare const index_CollisionShape: typeof CollisionShape;
+type index_CollisionTriggerConfig = CollisionTriggerConfig;
+declare const index_Constraint: typeof Constraint;
+type index_ConstraintSolver = ConstraintSolver;
+declare const index_ConstraintSolver: typeof ConstraintSolver;
+type index_ConstraintSolverConfig = ConstraintSolverConfig;
+declare const index_DEFAULT_ACTIVATION_CONFIG: typeof DEFAULT_ACTIVATION_CONFIG;
+declare const index_DEFAULT_INTENSITY_CURVE: typeof DEFAULT_INTENSITY_CURVE;
+declare const index_DEFAULT_LOCOMOTION_CONFIG: typeof DEFAULT_LOCOMOTION_CONFIG;
+type index_DeformConfig = DeformConfig;
+type index_DeformSpring = DeformSpring;
+type index_DeformVertex = DeformVertex;
+type index_DeformableMesh = DeformableMesh;
+declare const index_DeformableMesh: typeof DeformableMesh;
+type index_DistanceConstraint = DistanceConstraint;
+type index_FluidConfig = FluidConfig;
+type index_FluidParticle = FluidParticle;
+type index_FluidSim = FluidSim;
+declare const index_FluidSim: typeof FluidSim;
+type index_GrabConfig = GrabConfig;
+type index_GustConfig = GustConfig;
+declare const index_HUMANOID_PRESET: typeof HUMANOID_PRESET;
+declare const index_IBallConstraint: typeof IBallConstraint;
+declare const index_IBoxShape: typeof IBoxShape;
+declare const index_ICapsuleShape: typeof ICapsuleShape;
+declare const index_ICollisionEvent: typeof ICollisionEvent;
+declare const index_ICollisionFilter: typeof ICollisionFilter;
+declare const index_ICompoundShape: typeof ICompoundShape;
+declare const index_IConeConstraint: typeof IConeConstraint;
+declare const index_IConeShape: typeof IConeShape;
+declare const index_IConstraintColoring: typeof IConstraintColoring;
+declare const index_IConvexShape: typeof IConvexShape;
+declare const index_ICylinderShape: typeof ICylinderShape;
+declare const index_IDistanceConstraint: typeof IDistanceConstraint;
+declare const index_IFixedConstraint: typeof IFixedConstraint;
+declare const index_IGeneric6DOFConstraint: typeof IGeneric6DOFConstraint;
+declare const index_IHeightfieldShape: typeof IHeightfieldShape;
+declare const index_IHingeConstraint: typeof IHingeConstraint;
+declare const index_IMeshShape: typeof IMeshShape;
+declare const index_IOverlapResult: typeof IOverlapResult;
+declare const index_IPBDAttachmentConstraint: typeof IPBDAttachmentConstraint;
+declare const index_IPBDBendingConstraint: typeof IPBDBendingConstraint;
+declare const index_IPBDCollisionConstraint: typeof IPBDCollisionConstraint;
+declare const index_IPBDDistanceConstraint: typeof IPBDDistanceConstraint;
+declare const index_IPBDVolumeConstraint: typeof IPBDVolumeConstraint;
+declare const index_IParticleAttributes: typeof IParticleAttributes;
+declare const index_IPhysicsMaterial: typeof IPhysicsMaterial;
+declare const index_IPhysicsWorld: typeof IPhysicsWorld;
+declare const index_IPhysicsWorldConfig: typeof IPhysicsWorldConfig;
+declare const index_IQuaternion: typeof IQuaternion;
+declare const index_IRay: typeof IRay;
+declare const index_IRaycastHit: typeof IRaycastHit;
+declare const index_IRaycastOptions: typeof IRaycastOptions;
+declare const index_IRigidBodyConfig: typeof IRigidBodyConfig;
+declare const index_IRigidBodyState: typeof IRigidBodyState;
+declare const index_ISDFCollider: typeof ISDFCollider;
+declare const index_ISliderConstraint: typeof ISliderConstraint;
+declare const index_ISoftBodyConfig: typeof ISoftBodyConfig;
+declare const index_ISoftBodyState: typeof ISoftBodyState;
+declare const index_ISpatialHashGrid: typeof ISpatialHashGrid;
+declare const index_ISphereShape: typeof ISphereShape;
+declare const index_ISpringConstraint: typeof ISpringConstraint;
+declare const index_ITransform: typeof ITransform;
+declare const index_ITriggerEvent: typeof ITriggerEvent;
+declare const index_IVector3: typeof IVector3;
+type index_IntensityCurvePoint = IntensityCurvePoint;
+type index_IslandDetector = IslandDetector;
+declare const index_IslandDetector: typeof IslandDetector;
+type index_JointDef = JointDef;
+type index_JointState = JointState;
+type index_JointSystem = JointSystem;
+declare const index_JointSystem: typeof JointSystem;
+type index_JointType = JointType;
+type index_LocomotionConfig = LocomotionConfig;
+type index_LoopTimingConfig = LoopTimingConfig;
+type index_MLSMPMConfig = MLSMPMConfig;
+type index_MLSMPMFluid = MLSMPMFluid;
+declare const index_MLSMPMFluid: typeof MLSMPMFluid;
+type index_MLSMPMStats = MLSMPMStats;
+declare const index_PBDConstraint: typeof PBDConstraint;
+declare const index_PBDConstraintType: typeof PBDConstraintType;
+type index_PBDSolverCPU = PBDSolverCPU;
+declare const index_PBDSolverCPU: typeof PBDSolverCPU;
+declare const index_PBD_ATTACHMENT_SHADER: typeof PBD_ATTACHMENT_SHADER;
+declare const index_PBD_BENDING_SHADER: typeof PBD_BENDING_SHADER;
+declare const index_PBD_COLLISION_SHADER: typeof PBD_COLLISION_SHADER;
+declare const index_PBD_DISTANCE_SHADER: typeof PBD_DISTANCE_SHADER;
+declare const index_PBD_FINALIZE_SHADER: typeof PBD_FINALIZE_SHADER;
+declare const index_PBD_HASH_BUILD_SHADER: typeof PBD_HASH_BUILD_SHADER;
+declare const index_PBD_NORMALIZE_SHADER: typeof PBD_NORMALIZE_SHADER;
+declare const index_PBD_NORMALS_SHADER: typeof PBD_NORMALS_SHADER;
+declare const index_PBD_PREDICT_SHADER: typeof PBD_PREDICT_SHADER;
+declare const index_PBD_SELF_COLLISION_SHADER: typeof PBD_SELF_COLLISION_SHADER;
+declare const index_PBD_VELOCITY_SHADER: typeof PBD_VELOCITY_SHADER;
+declare const index_PBD_VOLUME_SHADER: typeof PBD_VOLUME_SHADER;
+declare const index_PHYSICS_DEFAULTS: typeof PHYSICS_DEFAULTS;
+type index_PIDArithmetic<T> = PIDArithmetic<T>;
+type index_PIDController<T> = PIDController<T>;
+declare const index_PIDController: typeof PIDController;
+type index_PIDControllerConfig<T> = PIDControllerConfig<T>;
+type index_PIDControllerState<T> = PIDControllerState<T>;
+type index_PIDControllerTraitConfig = PIDControllerTraitConfig;
+type index_PIDGains = PIDGains;
+type index_Particle = Particle;
+type index_ParticleRange = ParticleRange;
+declare const index_ParticleType: typeof ParticleType;
+type index_PhysicsActivationConfig = PhysicsActivationConfig;
+type index_PhysicsActivationController = PhysicsActivationController;
+declare const index_PhysicsActivationController: typeof PhysicsActivationController;
+type index_PhysicsActivationState = PhysicsActivationState;
+declare const index_PhysicsActivationState: typeof PhysicsActivationState;
+type index_PhysicsSyncConfig = PhysicsSyncConfig;
+type index_PhysicsSyncReceiver = PhysicsSyncReceiver;
+declare const index_PhysicsSyncReceiver: typeof PhysicsSyncReceiver;
+type index_PhysicsSyncSender = PhysicsSyncSender;
+declare const index_PhysicsSyncSender: typeof PhysicsSyncSender;
+type index_PhysicsWorldImpl = PhysicsWorldImpl;
+declare const index_PhysicsWorldImpl: typeof PhysicsWorldImpl;
+type index_Plane = Plane;
+declare const index_QUADRUPED_PRESET: typeof QUADRUPED_PRESET;
+type index_RagdollBone = RagdollBone;
+type index_RagdollConfig = RagdollConfig;
+type index_RagdollController = RagdollController;
+declare const index_RagdollController: typeof RagdollController;
+type index_RagdollDefinition = RagdollDefinition;
+type index_RagdollInstance = RagdollInstance;
+type index_RagdollState = RagdollState;
+type index_RagdollSystem = RagdollSystem;
+declare const index_RagdollSystem: typeof RagdollSystem;
+type index_Ray = Ray;
+type index_RayHit = RayHit;
+type index_RaycastSystem = RaycastSystem;
+declare const index_RaycastSystem: typeof RaycastSystem;
+type index_RigidBody = RigidBody;
+declare const index_RigidBody: typeof RigidBody;
+type index_RopeAttachment = RopeAttachment;
+type index_RopeConfig = RopeConfig;
+type index_RopeNode = RopeNode;
+type index_RopeSystem = RopeSystem;
+declare const index_RopeSystem: typeof RopeSystem;
+declare const index_SOFT_BODY_PRESETS: typeof SOFT_BODY_PRESETS;
+declare const index_ScalarArithmetic: typeof ScalarArithmetic;
+type index_SoftBodyAdapter = SoftBodyAdapter;
+declare const index_SoftBodyAdapter: typeof SoftBodyAdapter;
+type index_SoftBodyGrabController = SoftBodyGrabController;
+declare const index_SoftBodyGrabController: typeof SoftBodyGrabController;
+declare const index_SoftBodyPreset: typeof SoftBodyPreset;
+type index_SoftBodySolver = SoftBodySolver;
+declare const index_SoftBodySolver: typeof SoftBodySolver;
+type index_SpatialEntry = SpatialEntry;
+type index_SpatialHash = SpatialHash;
+declare const index_SpatialHash: typeof SpatialHash;
+type index_Sphere = Sphere;
+type index_SyncPacketHeader = SyncPacketHeader;
+type index_SyncStats = SyncStats;
+type index_ThresholdTriggerConfig = ThresholdTriggerConfig;
+type index_TriggerCallback = TriggerCallback;
+type index_TriggerEvent = TriggerEvent;
+type index_TriggerShape = TriggerShape;
+type index_TriggerZoneConfig = TriggerZoneConfig;
+type index_TriggerZoneSystem = TriggerZoneSystem;
+declare const index_TriggerZoneSystem: typeof TriggerZoneSystem;
+type index_UnifiedBufferStats = UnifiedBufferStats;
+type index_UnifiedParticleBuffer = UnifiedParticleBuffer;
+declare const index_UnifiedParticleBuffer: typeof UnifiedParticleBuffer;
+type index_VRPhysicsBridge = VRPhysicsBridge;
+declare const index_VRPhysicsBridge: typeof VRPhysicsBridge;
+declare const index_Vector3Arithmetic: typeof Vector3Arithmetic;
+type index_VehicleDefinition = VehicleDefinition;
+type index_VehicleState = VehicleState;
+type index_VehicleSystem = VehicleSystem;
+declare const index_VehicleSystem: typeof VehicleSystem;
+type index_VelocityRingBuffer = VelocityRingBuffer;
+declare const index_VelocityRingBuffer: typeof VelocityRingBuffer;
+type index_VelocitySmoother = VelocitySmoother;
+declare const index_VelocitySmoother: typeof VelocitySmoother;
+type index_WheelConfig = WheelConfig;
+type index_WheelState = WheelState;
+type index_WindZone = WindZone;
+type index_WindZoneManager = WindZoneManager;
+declare const index_WindZoneManager: typeof WindZoneManager;
+type index_WindZoneType = WindZoneType;
+declare const index_WindZoneType: typeof WindZoneType;
+declare const index_boxShape: typeof boxShape;
+declare const index_capsuleShape: typeof capsuleShape;
+declare const index_colorConstraints: typeof colorConstraints;
+declare const index_computeRestLengths: typeof computeRestLengths;
+declare const index_computeSelfWind: typeof computeSelfWind;
+declare const index_createDefaultCar: typeof createDefaultCar;
+declare const index_createPBDSolver: typeof createPBDSolver;
+declare const index_createPIDControllerTrait: typeof createPIDControllerTrait;
+declare const index_createPhysicsWorld: typeof createPhysicsWorld;
+declare const index_createScalarPIDController: typeof createScalarPIDController;
+declare const index_createTruck: typeof createTruck;
+declare const index_createVector3PIDController: typeof createVector3PIDController;
+declare const index_defaultMaterial: typeof defaultMaterial;
+declare const index_defaultPIDConfig: typeof defaultPIDConfig;
+declare const index_defaultTransform: typeof defaultTransform;
+declare const index_dynamicBody: typeof dynamicBody;
+declare const index_evaluateIntensityCurve: typeof evaluateIntensityCurve;
+declare const index_extractBendingPairs: typeof extractBendingPairs;
+declare const index_extractEdges: typeof extractEdges;
+declare const index_generateSDF: typeof generateSDF;
+declare const index_generateTetrahedra: typeof generateTetrahedra;
+declare const index_identityQuaternion: typeof identityQuaternion;
+declare const index_kinematicBody: typeof kinematicBody;
+declare const index_parsePacketHeader: typeof parsePacketHeader;
+declare const index_sphereShape: typeof sphereShape;
+declare const index_staticBody: typeof staticBody;
+declare const index_validateBodyConfig: typeof validateBodyConfig;
+declare const index_zeroVector: typeof zeroVector;
+declare namespace index {
+  export { type index_AABB as AABB, index_ActivationTriggerType as ActivationTriggerType, type index_ActivationTriggers as ActivationTriggers, type index_ActivationUpdateInput as ActivationUpdateInput, type index_AnimationTriggerConfig as AnimationTriggerConfig, index_BodyType as BodyType, type index_BoneDefinition as BoneDefinition, type index_BoundaryCoupling as BoundaryCoupling, index_COLLISION_GROUPS as COLLISION_GROUPS, type index_ClothConfig as ClothConfig, type index_ClothConstraint as ClothConstraint, type index_ClothParticle as ClothParticle, index_ClothSim as ClothSim, type index_Collider as Collider, index_CollisionShape as CollisionShape, type index_CollisionTriggerConfig as CollisionTriggerConfig, index_Constraint as Constraint, index_ConstraintSolver as ConstraintSolver, type index_ConstraintSolverConfig as ConstraintSolverConfig, index_DEFAULT_ACTIVATION_CONFIG as DEFAULT_ACTIVATION_CONFIG, index_DEFAULT_INTENSITY_CURVE as DEFAULT_INTENSITY_CURVE, index_DEFAULT_LOCOMOTION_CONFIG as DEFAULT_LOCOMOTION_CONFIG, type index_DeformConfig as DeformConfig, type index_DeformSpring as DeformSpring, type index_DeformVertex as DeformVertex, index_DeformableMesh as DeformableMesh, type index_DistanceConstraint as DistanceConstraint, type index_FluidConfig as FluidConfig, type index_FluidParticle as FluidParticle, index_FluidSim as FluidSim, type index_GrabConfig as GrabConfig, type index_GustConfig as GustConfig, index_HUMANOID_PRESET as HUMANOID_PRESET, index_IBallConstraint as IBallConstraint, index_IBoxShape as IBoxShape, index_ICapsuleShape as ICapsuleShape, index_ICollisionEvent as ICollisionEvent, index_ICollisionFilter as ICollisionFilter, index_ICompoundShape as ICompoundShape, index_IConeConstraint as IConeConstraint, index_IConeShape as IConeShape, index_IConstraintColoring as IConstraintColoring, index_IConvexShape as IConvexShape, index_ICylinderShape as ICylinderShape, index_IDistanceConstraint as IDistanceConstraint, index_IFixedConstraint as IFixedConstraint, index_IGeneric6DOFConstraint as IGeneric6DOFConstraint, index_IHeightfieldShape as IHeightfieldShape, index_IHingeConstraint as IHingeConstraint, index_IMeshShape as IMeshShape, index_IOverlapResult as IOverlapResult, index_IPBDAttachmentConstraint as IPBDAttachmentConstraint, index_IPBDBendingConstraint as IPBDBendingConstraint, index_IPBDCollisionConstraint as IPBDCollisionConstraint, index_IPBDDistanceConstraint as IPBDDistanceConstraint, index_IPBDVolumeConstraint as IPBDVolumeConstraint, index_IParticleAttributes as IParticleAttributes, index_IPhysicsMaterial as IPhysicsMaterial, index_IPhysicsWorld as IPhysicsWorld, index_IPhysicsWorldConfig as IPhysicsWorldConfig, index_IQuaternion as IQuaternion, index_IRay as IRay, index_IRaycastHit as IRaycastHit, index_IRaycastOptions as IRaycastOptions, index_IRigidBodyConfig as IRigidBodyConfig, index_IRigidBodyState as IRigidBodyState, index_ISDFCollider as ISDFCollider, index_ISliderConstraint as ISliderConstraint, index_ISoftBodyConfig as ISoftBodyConfig, index_ISoftBodyState as ISoftBodyState, index_ISpatialHashGrid as ISpatialHashGrid, index_ISphereShape as ISphereShape, index_ISpringConstraint as ISpringConstraint, index_ITransform as ITransform, index_ITriggerEvent as ITriggerEvent, index_IVector3 as IVector3, type index_IntensityCurvePoint as IntensityCurvePoint, index_IslandDetector as IslandDetector, type index_JointDef as JointDef, type index_JointState as JointState, index_JointSystem as JointSystem, type index_JointType as JointType, type index_LocomotionConfig as LocomotionConfig, type index_LoopTimingConfig as LoopTimingConfig, type index_MLSMPMConfig as MLSMPMConfig, index_MLSMPMFluid as MLSMPMFluid, type index_MLSMPMStats as MLSMPMStats, index_PBDConstraint as PBDConstraint, index_PBDConstraintType as PBDConstraintType, index_PBDSolverCPU as PBDSolverCPU, index_PBD_ATTACHMENT_SHADER as PBD_ATTACHMENT_SHADER, index_PBD_BENDING_SHADER as PBD_BENDING_SHADER, index_PBD_COLLISION_SHADER as PBD_COLLISION_SHADER, index_PBD_DISTANCE_SHADER as PBD_DISTANCE_SHADER, index_PBD_FINALIZE_SHADER as PBD_FINALIZE_SHADER, index_PBD_HASH_BUILD_SHADER as PBD_HASH_BUILD_SHADER, index_PBD_NORMALIZE_SHADER as PBD_NORMALIZE_SHADER, index_PBD_NORMALS_SHADER as PBD_NORMALS_SHADER, index_PBD_PREDICT_SHADER as PBD_PREDICT_SHADER, index_PBD_SELF_COLLISION_SHADER as PBD_SELF_COLLISION_SHADER, index_PBD_VELOCITY_SHADER as PBD_VELOCITY_SHADER, index_PBD_VOLUME_SHADER as PBD_VOLUME_SHADER, index_PHYSICS_DEFAULTS as PHYSICS_DEFAULTS, type index_PIDArithmetic as PIDArithmetic, index_PIDController as PIDController, type index_PIDControllerConfig as PIDControllerConfig, type index_PIDControllerState as PIDControllerState, type index_PIDControllerTraitConfig as PIDControllerTraitConfig, type index_PIDGains as PIDGains, type index_Particle as Particle, type index_ParticleRange as ParticleRange, index_ParticleType as ParticleType, type index_PhysicsActivationConfig as PhysicsActivationConfig, index_PhysicsActivationController as PhysicsActivationController, index_PhysicsActivationState as PhysicsActivationState, type index_PhysicsSyncConfig as PhysicsSyncConfig, index_PhysicsSyncReceiver as PhysicsSyncReceiver, index_PhysicsSyncSender as PhysicsSyncSender, index_PhysicsWorldImpl as PhysicsWorldImpl, type index_Plane as Plane, index_QUADRUPED_PRESET as QUADRUPED_PRESET, type index_RagdollBone as RagdollBone, type index_RagdollConfig as RagdollConfig, index_RagdollController as RagdollController, type index_RagdollDefinition as RagdollDefinition, type index_RagdollInstance as RagdollInstance, type index_RagdollState as RagdollState, index_RagdollSystem as RagdollSystem, type index_Ray as Ray, type index_RayHit as RayHit, index_RaycastSystem as RaycastSystem, index_RigidBody as RigidBody, type index_RopeAttachment as RopeAttachment, type index_RopeConfig as RopeConfig, type index_RopeNode as RopeNode, index_RopeSystem as RopeSystem, index_SOFT_BODY_PRESETS as SOFT_BODY_PRESETS, index_ScalarArithmetic as ScalarArithmetic, index_SoftBodyAdapter as SoftBodyAdapter, index_SoftBodyGrabController as SoftBodyGrabController, index_SoftBodyPreset as SoftBodyPreset, index_SoftBodySolver as SoftBodySolver, type index_SpatialEntry as SpatialEntry, index_SpatialHash as SpatialHash, type index_Sphere as Sphere, type index_SyncPacketHeader as SyncPacketHeader, type index_SyncStats as SyncStats, type index_ThresholdTriggerConfig as ThresholdTriggerConfig, type index_TriggerCallback as TriggerCallback, type index_TriggerEvent as TriggerEvent, type index_TriggerShape as TriggerShape, type index_TriggerZoneConfig as TriggerZoneConfig, index_TriggerZoneSystem as TriggerZoneSystem, type index_UnifiedBufferStats as UnifiedBufferStats, index_UnifiedParticleBuffer as UnifiedParticleBuffer, index_VRPhysicsBridge as VRPhysicsBridge, index_Vector3Arithmetic as Vector3Arithmetic, type index_VehicleDefinition as VehicleDefinition, type index_VehicleState as VehicleState, index_VehicleSystem as VehicleSystem, index_VelocityRingBuffer as VelocityRingBuffer, index_VelocitySmoother as VelocitySmoother, type index_WheelConfig as WheelConfig, type index_WheelState as WheelState, type index_WindZone as WindZone, index_WindZoneManager as WindZoneManager, index_WindZoneType as WindZoneType, index_boxShape as boxShape, index_capsuleShape as capsuleShape, index_colorConstraints as colorConstraints, index_computeRestLengths as computeRestLengths, index_computeSelfWind as computeSelfWind, index_createDefaultCar as createDefaultCar, index_createPBDSolver as createPBDSolver, index_createPIDControllerTrait as createPIDControllerTrait, index_createPhysicsWorld as createPhysicsWorld, index_createScalarPIDController as createScalarPIDController, index_createTruck as createTruck, index_createVector3PIDController as createVector3PIDController, index_defaultMaterial as defaultMaterial, index_defaultPIDConfig as defaultPIDConfig, index_defaultTransform as defaultTransform, index_dynamicBody as dynamicBody, index_evaluateIntensityCurve as evaluateIntensityCurve, index_extractBendingPairs as extractBendingPairs, index_extractEdges as extractEdges, index_generateSDF as generateSDF, index_generateTetrahedra as generateTetrahedra, index_identityQuaternion as identityQuaternion, index_kinematicBody as kinematicBody, index_parsePacketHeader as parsePacketHeader, index_sphereShape as sphereShape, index_staticBody as staticBody, index_validateBodyConfig as validateBodyConfig, index_zeroVector as zeroVector };
+}
+
+export { PBD_VOLUME_SHADER as $, type AABB as A, type BoneDefinition as B, type ClothConfig as C, DEFAULT_ACTIVATION_CONFIG as D, type JointType as E, type FluidConfig as F, type GrabConfig as G, HUMANOID_PRESET as H, type IntensityCurvePoint as I, type JointDef as J, type LoopTimingConfig as K, type LocomotionConfig as L, type MLSMPMConfig as M, MLSMPMFluid as N, type MLSMPMStats as O, PBDSolverCPU as P, PBD_ATTACHMENT_SHADER as Q, PBD_BENDING_SHADER as R, PBD_COLLISION_SHADER as S, PBD_DISTANCE_SHADER as T, PBD_FINALIZE_SHADER as U, PBD_HASH_BUILD_SHADER as V, PBD_NORMALIZE_SHADER as W, PBD_NORMALS_SHADER as X, PBD_PREDICT_SHADER as Y, PBD_SELF_COLLISION_SHADER as Z, PBD_VELOCITY_SHADER as _, ActivationTriggerType as a, computeSelfWind as a$, type PIDArithmetic as a0, PIDController as a1, type PIDControllerConfig as a2, type PIDControllerState as a3, type PIDControllerTraitConfig as a4, type PIDGains as a5, type Particle as a6, type ParticleRange as a7, type PhysicsActivationConfig as a8, PhysicsActivationController as a9, type SpatialEntry as aA, SpatialHash as aB, type Sphere as aC, type SyncPacketHeader as aD, type SyncStats as aE, type ThresholdTriggerConfig as aF, type TriggerCallback as aG, type TriggerEvent as aH, type TriggerShape as aI, type TriggerZoneConfig as aJ, TriggerZoneSystem as aK, type UnifiedBufferStats as aL, UnifiedParticleBuffer as aM, VRPhysicsBridge as aN, Vector3Arithmetic as aO, type VehicleDefinition as aP, type VehicleState as aQ, VehicleSystem as aR, VelocityRingBuffer as aS, VelocitySmoother as aT, type WheelConfig as aU, type WheelState as aV, type WindZone as aW, WindZoneManager as aX, WindZoneType as aY, colorConstraints as aZ, computeRestLengths as a_, PhysicsActivationState as aa, type PhysicsSyncConfig as ab, PhysicsSyncReceiver as ac, PhysicsSyncSender as ad, PhysicsWorldImpl as ae, type Plane as af, QUADRUPED_PRESET as ag, type RagdollBone as ah, type RagdollConfig as ai, RagdollController as aj, type RagdollDefinition as ak, type RagdollInstance as al, type RagdollState as am, RagdollSystem as an, type Ray as ao, type RayHit as ap, RaycastSystem as aq, RigidBody as ar, type RopeAttachment as as, type RopeConfig as at, type RopeNode as au, RopeSystem as av, ScalarArithmetic as aw, SoftBodyAdapter as ax, SoftBodyGrabController as ay, SoftBodySolver as az, type ActivationTriggers as b, createDefaultCar as b0, createPBDSolver as b1, createPIDControllerTrait as b2, createPhysicsWorld as b3, createScalarPIDController as b4, createTruck as b5, createVector3PIDController as b6, defaultPIDConfig as b7, evaluateIntensityCurve as b8, extractBendingPairs as b9, extractEdges as ba, generateSDF as bb, generateTetrahedra as bc, parsePacketHeader as bd, type ActivationUpdateInput as c, type AnimationTriggerConfig as d, type BoundaryCoupling as e, type ClothConstraint as f, type ClothParticle as g, ClothSim as h, index as i, type Collider as j, type CollisionTriggerConfig as k, ConstraintSolver as l, type ConstraintSolverConfig as m, DEFAULT_INTENSITY_CURVE as n, DEFAULT_LOCOMOTION_CONFIG as o, type DeformConfig as p, type DeformSpring as q, type DeformVertex as r, DeformableMesh as s, type DistanceConstraint as t, type FluidParticle as u, FluidSim as v, type GustConfig as w, IslandDetector as x, type JointState as y, JointSystem as z };