@vgai/engine 0.5.0-canary.20260719.0 → 0.5.0

package/dist/audio/tone-offline-render.d.ts

@@ -0,0 +1,90 @@
+import { Offline } from 'tone';
+/**
+ * G2 — Integrate Tone with the Canonical Clock, OFFLINE-render half (spec
+ * §13 G2, and the G4/I6 seam it is deliberately shaped for). This module
+ * renders a Tone composition over an exact `[start, end)` time range to a
+ * real `AudioBuffer` via `Tone.Offline` — i.e. `OfflineAudioContext`, NOT a
+ * live real-time `AudioContext` — such that identical inputs produce
+ * bit-identical output samples on every call. This is what makes offline
+ * Tone audio safe to mux into a deterministically-rendered video (G4/I6):
+ * the video side already re-renders frame-by-frame from an exact clock
+ * position, and this is the audio side's equivalent — an exact re-render
+ * from an exact time range, not a live capture of whatever happened to play.
+ *
+ * ## Why this can't run in plain Node (documented, not assumed)
+ *
+ * `Tone.Offline` ultimately constructs a real `OfflineAudioContext`
+ * (via `standardized-audio-context`, Tone's own dependency). Node has no
+ * native Web Audio implementation, so `standardized-audio-context` throws
+ * `"Missing the native OfflineAudioContext constructor."` the moment
+ * `Tone.Offline(...)` is actually invoked — confirmed empirically against
+ * this repo's installed `tone@15.1.22` before writing this module (plain
+ * `import * as Tone from 'tone'` succeeds; calling `Tone.Offline(...)` in a
+ * Node process throws immediately). There is no lightweight polyfill in this
+ * repo's dependency tree, and installing a native Node Web Audio addon is
+ * out of scope for this unit (build-box constraints). The determinism proof
+ * for this module therefore runs in a REAL headless-Chromium page via
+ * Playwright — see `packages/engine/e2e/tests/tone-audio-g1-g2.spec.ts`
+ * — mirroring how I0 proved video-frame determinism. This module's own
+ * `packages/engine/test/audio/tone-offline-render.test.ts` covers everything
+ * that does NOT require a real `OfflineAudioContext` (range validation,
+ * synchronous pre-render cancellation) directly in Node.
+ *
+ * ## Composition contract
+ *
+ * `compose` is called by `Tone.Offline` itself, inside the offline context —
+ * build the SAME graph you would in real-time Tone code
+ * (`new Tone.Synth().toDestination()`, `context.transport.schedule(...)`,
+ * etc; see Tone's own `Offline` docs). Nothing about this wrapper changes
+ * Tone's native API surface — `compose`'s parameter is `Tone.Offline`'s own
+ * callback type, re-derived structurally (`Parameters<typeof Offline>[0]`)
+ * rather than duplicated, so this module can never drift from Tone's actual
+ * signature.
+ *
+ * ## Cancellation — cooperative, not a true mid-render abort
+ *
+ * The Web Audio spec gives `OfflineAudioContext` no `.close()`/cancel API
+ * once `startRendering()` is in flight, and neither does Tone. `signal`
+ * therefore provides COOPERATIVE cancellation only: if `signal` is already
+ * aborted before this function calls `Tone.Offline`, the render never
+ * starts at all (checked synchronously, before any `OfflineAudioContext` is
+ * created). If `signal` aborts WHILE a render is in flight, this function's
+ * returned promise rejects immediately with an `AbortError` — so a caller
+ * (e.g. a render-cancellation UI action) sees the render "stop" from its own
+ * perspective and never receives/uses the resulting buffer — even though
+ * the underlying browser-native render may keep running in the background
+ * until it would have finished anyway. This is an honest, documented
+ * limitation, not a gap: no browser API makes a stronger guarantee possible.
+ */
+/** Tone's own `Offline` callback signature, re-derived (not re-typed) so
+ *  this module can never drift from the real function it wraps. */
+export type ToneOfflineComposeFn = Parameters<typeof Offline>[0];
+export interface ToneOfflineRenderRequest {
+    /** Canonical/Theatre-time range start, in seconds. */
+    readonly start: number;
+    /** Canonical/Theatre-time range end, in seconds. Must be `> start`. */
+    readonly end: number;
+    /** Output sample rate. Default 44100 (CD-quality, FFmpeg's usual default). */
+    readonly sampleRate?: number;
+    /** Output channel count. Default 2 (stereo). */
+    readonly channels?: number;
+    /** Builds the Tone graph inside the offline context — Tone's native
+     *  `Offline` callback, unmodified. Receives local time `0` at `start`. */
+    readonly compose: ToneOfflineComposeFn;
+    /** Optional cooperative-cancellation signal — see module doc above. */
+    readonly signal?: AbortSignal;
+}
+export interface ToneOfflineRenderResult {
+    /** The rendered PCM, as a real (native) `AudioBuffer` — `.getChannelData(n)`
+     *  gives the Float32 samples for channel `n`, ready for a digest/RMS
+     *  computation or (eventually, G4/I6) FFmpeg muxing. */
+    readonly buffer: AudioBuffer;
+    readonly durationSeconds: number;
+    readonly sampleRate: number;
+    readonly channels: number;
+}
+/** Render `request.compose`'s Tone graph offline over `[start, end)`,
+ *  producing a deterministic `AudioBuffer`. See module doc for the
+ *  determinism/cancellation contract. */
+export declare function renderToneOffline(request: ToneOfflineRenderRequest): Promise<ToneOfflineRenderResult>;
+//# sourceMappingURL=tone-offline-render.d.ts.map

package/dist/audio/tone-offline-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tone-offline-render.d.ts","sourceRoot":"","sources":["../../src/audio/tone-offline-render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH;mEACmE;AACnE,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjE,MAAM,WAAW,wBAAwB;IACvC,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;8EAC0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAuB;IACtC;;4DAEwD;IACxD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAKD;;yCAEyC;AACzC,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CA4ClC"}

package/dist/audio/tone-offline-render.js

@@ -0,0 +1,56 @@
+import { Offline } from 'tone';
+const DEFAULT_SAMPLE_RATE = 44100;
+const DEFAULT_CHANNELS = 2;
+/** Render `request.compose`'s Tone graph offline over `[start, end)`,
+ *  producing a deterministic `AudioBuffer`. See module doc for the
+ *  determinism/cancellation contract. */
+export async function renderToneOffline(request) {
+    const { start, end, sampleRate = DEFAULT_SAMPLE_RATE, channels = DEFAULT_CHANNELS, compose, signal, } = request;
+    if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) {
+        throw new Error(`[tone-offline-render] invalid range [${start}, ${end}) — end must be a finite number > start`);
+    }
+    if (!Number.isFinite(sampleRate) || sampleRate <= 0) {
+        throw new Error(`[tone-offline-render] sampleRate must be a finite number > 0, got ${sampleRate}`);
+    }
+    if (!Number.isInteger(channels) || channels <= 0) {
+        throw new Error(`[tone-offline-render] channels must be a positive integer, got ${channels}`);
+    }
+    // Cooperative cancellation, checked BEFORE ever constructing an
+    // OfflineAudioContext — an already-aborted signal must never start a
+    // render at all (see module doc).
+    if (signal?.aborted) {
+        throw createAbortError();
+    }
+    const durationSeconds = end - start;
+    const renderPromise = Offline(compose, durationSeconds, channels, sampleRate);
+    const toneBuffer = signal ? await raceAbort(renderPromise, signal) : await renderPromise;
+    const buffer = toneBuffer.get();
+    if (!buffer) {
+        throw new Error('[tone-offline-render] Tone.Offline resolved without a decoded AudioBuffer');
+    }
+    return {
+        buffer,
+        durationSeconds,
+        sampleRate: buffer.sampleRate,
+        channels: buffer.numberOfChannels,
+    };
+}
+function createAbortError() {
+    return new DOMException('[tone-offline-render] render canceled', 'AbortError');
+}
+/** Race `promise` against `signal` firing — resolves/rejects with whichever
+ *  happens first, without altering the underlying Web Audio render (see
+ *  module doc's "cooperative, not a true mid-render abort" section). */
+function raceAbort(promise, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(createAbortError());
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (err) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(err);
+        });
+    });
+}

package/dist/audio/wav-encode.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure PCM -> 16-bit WAV encoder (spec §15 I6 "Encode and Mux", audio half —
+ * `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md`). This module takes
+ * already-rendered Float32 channel data (e.g. `AudioBuffer.getChannelData(n)`
+ * from a `Tone.Offline` render, `audio/tone-offline-render.ts`) and produces
+ * a standard little-endian, 16-bit-PCM, interleaved RIFF/WAVE file as raw
+ * bytes — no `AudioBuffer`/`AudioContext` dependency, so this runs equally in
+ * a browser render-mode page (`runtime/render-audio-control.ts`) and in
+ * plain Node (this module's own `packages/engine/test/audio/wav-encode.test.ts`,
+ * no Playwright needed).
+ *
+ * 16-bit PCM (not 32-bit float) is the deliberate choice named by the I6 AC
+ * ("16-bit PCM WAV is fine") — it is universally decodable by every FFmpeg
+ * build without an extra format flag, keeping the video-mux step's ffmpeg
+ * invocation ordinary and portable.
+ */
+export interface PcmToWavInput {
+    /** One `Float32Array` per channel, each sample in `[-1, 1]` (values outside
+     *  that range are clamped, not thrown on — real synthesis can transiently
+     *  clip). All channels must have equal length. */
+    readonly channelData: readonly Float32Array[];
+    readonly sampleRate: number;
+}
+/** Encode `input` as a complete little-endian, 16-bit-PCM, interleaved
+ *  RIFF/WAVE file (44-byte canonical header + data chunk). Throws on an
+ *  empty/mismatched channel set rather than silently producing a malformed
+ *  file — this module's own contribution to the "fail loudly, never a
+ *  silent no-op" convention `runtime/render-control.ts` documents. */
+export declare function encodeWav16(input: PcmToWavInput): Uint8Array;
+/** RMS + peak over all channels/samples — the same "non-trivial audio, not
+ *  an all-zero buffer" sanity check `tone-audio-main.ts`'s fixture computes,
+ *  factored out here so both that fixture and the render-audio harness can
+ *  share one implementation instead of drifting copies. */
+export declare function pcmStats(channelData: readonly Float32Array[]): {
+    rms: number;
+    peak: number;
+};
+//# sourceMappingURL=wav-encode.d.ts.map

package/dist/audio/wav-encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wav-encode.d.ts","sourceRoot":"","sources":["../../src/audio/wav-encode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,aAAa;IAC5B;;sDAEkD;IAClD,QAAQ,CAAC,WAAW,EAAE,SAAS,YAAY,EAAE,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAeD;;;;sEAIsE;AACtE,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,UAAU,CAwD5D;AAED;;;2DAG2D;AAC3D,wBAAgB,QAAQ,CAAC,WAAW,EAAE,SAAS,YAAY,EAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAa5F"}

package/dist/audio/wav-encode.js

@@ -0,0 +1,97 @@
+/**
+ * Pure PCM -> 16-bit WAV encoder (spec §15 I6 "Encode and Mux", audio half —
+ * `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md`). This module takes
+ * already-rendered Float32 channel data (e.g. `AudioBuffer.getChannelData(n)`
+ * from a `Tone.Offline` render, `audio/tone-offline-render.ts`) and produces
+ * a standard little-endian, 16-bit-PCM, interleaved RIFF/WAVE file as raw
+ * bytes — no `AudioBuffer`/`AudioContext` dependency, so this runs equally in
+ * a browser render-mode page (`runtime/render-audio-control.ts`) and in
+ * plain Node (this module's own `packages/engine/test/audio/wav-encode.test.ts`,
+ * no Playwright needed).
+ *
+ * 16-bit PCM (not 32-bit float) is the deliberate choice named by the I6 AC
+ * ("16-bit PCM WAV is fine") — it is universally decodable by every FFmpeg
+ * build without an extra format flag, keeping the video-mux step's ffmpeg
+ * invocation ordinary and portable.
+ */
+const BYTES_PER_SAMPLE = 2; // 16-bit PCM
+const WAV_HEADER_BYTES = 44;
+function clamp(value, lo, hi) {
+    return Math.min(hi, Math.max(lo, value));
+}
+function writeAsciiString(view, offset, text) {
+    for (let i = 0; i < text.length; i++) {
+        view.setUint8(offset + i, text.charCodeAt(i));
+    }
+}
+/** Encode `input` as a complete little-endian, 16-bit-PCM, interleaved
+ *  RIFF/WAVE file (44-byte canonical header + data chunk). Throws on an
+ *  empty/mismatched channel set rather than silently producing a malformed
+ *  file — this module's own contribution to the "fail loudly, never a
+ *  silent no-op" convention `runtime/render-control.ts` documents. */
+export function encodeWav16(input) {
+    const { channelData, sampleRate } = input;
+    const numChannels = channelData.length;
+    if (numChannels === 0) {
+        throw new Error('[wav-encode] channelData must contain at least one channel');
+    }
+    if (!Number.isFinite(sampleRate) || sampleRate <= 0) {
+        throw new Error(`[wav-encode] sampleRate must be a finite number > 0, got ${sampleRate}`);
+    }
+    const numFrames = channelData[0]?.length ?? 0;
+    for (let ch = 0; ch < numChannels; ch++) {
+        const len = channelData[ch]?.length ?? -1;
+        if (len !== numFrames) {
+            throw new Error(`[wav-encode] channel ${ch} has length ${len}, expected ${numFrames} (all channels must match)`);
+        }
+    }
+    const blockAlign = numChannels * BYTES_PER_SAMPLE;
+    const byteRate = sampleRate * blockAlign;
+    const dataSize = numFrames * blockAlign;
+    const buffer = new ArrayBuffer(WAV_HEADER_BYTES + dataSize);
+    const view = new DataView(buffer);
+    // RIFF chunk descriptor
+    writeAsciiString(view, 0, 'RIFF');
+    view.setUint32(4, 36 + dataSize, true);
+    writeAsciiString(view, 8, 'WAVE');
+    // fmt subchunk (PCM)
+    writeAsciiString(view, 12, 'fmt ');
+    view.setUint32(16, 16, true); // subchunk size for PCM
+    view.setUint16(20, 1, true); // audio format 1 = PCM
+    view.setUint16(22, numChannels, true);
+    view.setUint32(24, sampleRate, true);
+    view.setUint32(28, byteRate, true);
+    view.setUint16(32, blockAlign, true);
+    view.setUint16(34, BYTES_PER_SAMPLE * 8, true); // bits per sample
+    // data subchunk
+    writeAsciiString(view, 36, 'data');
+    view.setUint32(40, dataSize, true);
+    let offset = WAV_HEADER_BYTES;
+    for (let i = 0; i < numFrames; i++) {
+        for (let ch = 0; ch < numChannels; ch++) {
+            const sample = clamp(channelData[ch]?.[i] ?? 0, -1, 1);
+            const intSample = Math.round(sample < 0 ? sample * 0x8000 : sample * 0x7fff);
+            view.setInt16(offset, intSample, true);
+            offset += BYTES_PER_SAMPLE;
+        }
+    }
+    return new Uint8Array(buffer);
+}
+/** RMS + peak over all channels/samples — the same "non-trivial audio, not
+ *  an all-zero buffer" sanity check `tone-audio-main.ts`'s fixture computes,
+ *  factored out here so both that fixture and the render-audio harness can
+ *  share one implementation instead of drifting copies. */
+export function pcmStats(channelData) {
+    let sumSquares = 0;
+    let peak = 0;
+    let count = 0;
+    for (const data of channelData) {
+        for (let i = 0; i < data.length; i++) {
+            const v = data[i] ?? 0;
+            sumSquares += v * v;
+            peak = Math.max(peak, Math.abs(v));
+            count++;
+        }
+    }
+    return { rms: count > 0 ? Math.sqrt(sumSquares / count) : 0, peak };
+}

package/dist/character/cloth-sim.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Character primitive — Jolt soft-body cloth grids (capes, skirts, banners)
+ * on top of the raw `jolt-physics` WASM bindings.
+ *
+ * THIN COMPOSITION HELPER, not a wrapper (CLAUDE.md "use libraries
+ * directly"): every export assembles the library's own objects
+ * (`Jolt.SoftBodySharedSettings`, `Jolt.Body`, `Jolt.JoltInterface`) —
+ * nothing from the library is re-exported. This file never imports the WASM
+ * module itself — the caller does the async `JoltInit()` and passes the
+ * resolved module in, mirroring `setup-physics.ts`'s `setupPhysics(rapier:
+ * typeof RAPIER, ...)` pattern for Rapier. `import type Jolt from
+ * 'jolt-physics/wasm-compat'` below is TYPE-ONLY (erased at compile time —
+ * no runtime WASM import here).
+ *
+ * Sharp edges this module exists partly to contain (see the mission brief /
+ * `cloth-hair-bench/jolt-cloth.ts`'s header for the full discovery):
+ *   - `Body.GetMotionProperties()` needs the `Jolt.castObject` downcast to
+ *     `Jolt.SoftBodyMotionProperties` to reach `GetVertex`.
+ *   - `SoftBodySharedSettings.CreateConstraints` takes a POINTER-typed
+ *     1-element `ArraySoftBodySharedSettingsVertexAttributes` (push_back,
+ *     not resize+at — `.at()` on these embind vectors returns a copy).
+ *   - Kinematic pins must set BOTH `SoftBodyVertex.mPosition` and
+ *     `.mVelocity` (finite-differenced) every tick, or the cloth's own
+ *     constraint solver fights a teleporting anchor.
+ *   - NO per-frame embind allocations (reviewer finding on Phase 1's
+ *     spike, which leaked a `new Jolt.Vec3(...)`/`new Jolt.RVec3(...)` per
+ *     pinned vertex per frame): `tick()` below preallocates ONE `Jolt.Vec3`
+ *     for position and ONE for velocity and reuses them via `.Set(...)` —
+ *     embind property setters (`vertex.mPosition = tmpVec3`) copy the value
+ *     in, so reassigning the SAME wrapper object across many vertices in one
+ *     frame is safe. `KinematicCollider.moveTo` does the same with one
+ *     `Jolt.RVec3` + one `Jolt.Quat` (identity, orientation is not simulated
+ *     here) allocated once at construction.
+ *   - CONSTRUCTION-TIME embind temporaries need `Jolt.destroy(...)` too, once
+ *     Jolt has copied their data out (reviewer finding on Phase 2 — these
+ *     were leaking WASM heap per build/dispose cycle even with `tick()`
+ *     itself allocation-free). Two different lifetimes are at play:
+ *     - Per-vertex/per-face grid temporaries (`SoftBodySharedSettingsVertex`
+ *       + its `Float3`, `SoftBodySharedSettingsFace`, the single
+ *       `vertexAttr`) are copied BY VALUE into `sharedSettings`'s own
+ *       storage the instant `push_back`/the property setter runs — freed
+ *       right there, matching the reuse-then-`Jolt.destroy()`-once pattern
+ *       in Jolt's own `soft-body-creator.js` sample. `bodyCreation`
+ *       (`SoftBodyCreationSettings`) is the same story: `CreateSoftBody`
+ *       copies what it needs, so it's freed right after — same contract as
+ *       `JoltSettings` → `JoltInterface` below.
+ *     - `sharedSettings` itself (`SoftBodySharedSettings`) is different: it
+ *       is REFCOUNTED (`AddRef`/`Release`/`GetRefCount` in the vendored
+ *       typings, like `Shape`) and the body reads it every step
+ *       (`SoftBodyMotionProperties.GetSettings()`) for face/constraint
+ *       topology. Refcounted RefTargets are freed BY JOLT ITSELF when the
+ *       last reference drops (Release of the final ref IS the delete) —
+ *       so it gets NO explicit `Jolt.destroy(...)` at all: destroying
+ *       `bodyCreation` releases the ctor's ref, and `dispose()`'s
+ *       `DestroyBody` releases the body's (last) ref, which deletes it.
+ *       An explicit destroy on top would be a use-after-free (empirically
+ *       confirmed with a `GetRefCount()` probe against real Jolt WASM).
+ *       Same rule for the collider's `Shape`: `destroy(creation)` releases
+ *       the creation-settings ref, `DestroyBody` releases the body's —
+ *       never destroy the shape directly.
+ *   - The preallocated tick-loop temporaries described above (`tmpPos`/
+ *     `tmpVel` in `buildClothGrid`, `tmpPos`/`identityQuat` in
+ *     `buildKinematicCollider`) are plain (non-refcounted) `Vec3`/`RVec3`/
+ *     `Quat` wrappers reused for the object's whole lifetime — freed in that
+ *     object's own `dispose()`.
+ */
+import type JoltNS from 'jolt-physics/wasm-compat';
+import * as THREE from 'three';
+/** The type of an ALREADY-INITIALIZED `jolt-physics/wasm-compat` module
+ *  (i.e. what `await JoltInit()` resolves to) — the parameter type every
+ *  function below takes instead of importing/initializing Jolt itself. */
+export type JoltModule = typeof JoltNS;
+export interface JoltWorld {
+    jolt: JoltModule;
+    joltInterface: JoltNS.JoltInterface;
+    physicsSystem: JoltNS.PhysicsSystem;
+    bodyInterface: JoltNS.BodyInterface;
+    /** The single "moving" object layer every body built through this world's
+     *  helpers is placed on (cloth + kinematic colliders all collide with
+     *  each other; nothing here needs more than one moving layer). */
+    movingLayer: number;
+    /** Advance the simulation by `dt` seconds (`options.collisionSteps` Jolt
+     *  collision sub-steps). Position any kinematic bodies (colliders, cloth
+     *  pins) for this frame BEFORE calling `step` — this is what
+     *  `ClothGrid.tick` does internally. */
+    step(dt: number): void;
+    dispose(): void;
+}
+export interface JoltWorldOptions {
+    gravity?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Jolt collision sub-steps per `step()` call. Soft-body contact has no
+     *  CCD — a cloth vertex moving faster than its collision radius per
+     *  collision step TUNNELS through kinematic colliders (measured live on a
+     *  whipping cape). 2 halves the per-step travel for ~2x the (sub-ms) sim
+     *  cost. @default 1 */
+    collisionSteps?: number;
+}
+export declare function createJoltWorld(jolt: JoltModule, options?: JoltWorldOptions): JoltWorld;
+export type KinematicColliderShape = {
+    kind: 'sphere';
+    radius: number;
+} | {
+    kind: 'capsule';
+    radius: number;
+    halfHeight: number;
+};
+export interface KinematicCollider {
+    body: JoltNS.Body;
+    /** Move the collider to `worldPos` (identity rotation — these fixtures
+     *  only need translation) for tick `dt`. Call BEFORE the cloth grid's
+     *  `tick()` for the same frame (that is what steps the Jolt world). */
+    moveTo(worldPos: THREE.Vector3, dt: number): void;
+    dispose(): void;
+}
+export declare function buildKinematicCollider(world: JoltWorld, shape: KinematicColliderShape): KinematicCollider;
+export interface ClothPin {
+    row: number;
+    col: number;
+}
+export interface ClothGridOptions {
+    cols: number;
+    rows: number;
+    /** World-space rest position for grid vertex (row, col) — row 0 is
+     *  conventionally the top/pinned edge, but that's a caller convention,
+     *  not enforced here. */
+    restPosition(row: number, col: number): THREE.Vector3;
+    /** Which vertices are pinned (kinematically driven every tick, infinite
+     *  mass). Default: every vertex in row 0. */
+    pins?: ClothPin[];
+    vertexMassKg?: number;
+    compliance?: number;
+    shearCompliance?: number;
+    bendCompliance?: number;
+    numIterations?: number;
+    gravityFactor?: number;
+    /** Collision radius of every cloth vertex (Jolt `mVertexRadius`), metres.
+     *  The default 0 lets a pressed vertex sit exactly ON (and, under
+     *  sustained gait-driven contact, sink INTO) a collider surface; a few cm
+     *  here keeps the cloth standing off colliders and makes contact
+     *  resolution far more robust against sinking. @default 0 (Jolt's own) */
+    vertexRadius?: number;
+    /** Jolt `mLinearDamping` for the soft body (higher = calmer cloth).
+     *  @default Jolt's own default */
+    linearDamping?: number;
+    color?: number;
+    /** @default true */
+    doubleSided?: boolean;
+}
+export interface ClothGrid {
+    cols: number;
+    rows: number;
+    vertexCount: number;
+    /** Pin list this grid was built with, in the order `tick()`'s
+     *  `pinTargets` must match. */
+    pins: ClothPin[];
+    mesh: THREE.Mesh;
+    geometry: THREE.BufferGeometry;
+    /** One tick: overwrite each pinned vertex's position/velocity from
+     *  `pinTargets[i]` (world-space, matching `pins` order — velocity is
+     *  finite-differenced against the previous call), STEP the owning
+     *  `JoltWorld` (this is the only thing in this module that calls
+     *  `world.step`, so build at most one `ClothGrid` per `JoltWorld` unless
+     *  you step the world yourself and skip that side effect), then sync
+     *  `geometry`'s `position` attribute + recompute normals from the
+     *  simulated vertices. Position any kinematic colliders for this frame
+     *  BEFORE calling this. */
+    tick(dt: number, pinTargets: readonly THREE.Vector3[]): void;
+    /** World-space position of every vertex, row-major (`row * cols + col`).
+     *  Reuses `out` if given (avoids an allocation for callers sampling every
+     *  frame, e.g. a numeric collision-clearance check). */
+    samplePoints(out?: THREE.Vector3[]): THREE.Vector3[];
+    dispose(): void;
+}
+export declare function buildClothGrid(world: JoltWorld, scene: THREE.Scene, options: ClothGridOptions): ClothGrid;
+//# sourceMappingURL=cloth-sim.d.ts.map

package/dist/character/cloth-sim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth-sim.d.ts","sourceRoot":"","sources":["../../src/character/cloth-sim.ts"],"names":[],"mappings":"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"}