@aura3d/engine 3.0.0 → 4.0.0

package/dist/assets/AssetDecoderRegistry.js

@@ -0,0 +1,225 @@
+/**
+ * C-16 §7.4 — AssetDecoderRegistry (PRD-05 Phase 1).
+ *
+ * One registry per app. `require(ids)` lazy-loads the named decoders
+ * same-origin from `options.basePath` ("aura-decoders/"):
+ *   - meshopt → `${basePath}meshopt/` vendored ESM in browsers;
+ *     the `meshoptimizer` npm package in Node — both loaded lazily with
+ *     non-static specifiers so consumer bundlers never resolve them at
+ *     build time (the packages are optional peers of the engine pack).
+ *   - draco   → `${basePath}draco/` vendored UMD, only on `require(["draco"])`
+ *   - ktx2    → `${basePath}basis/` vendored Basis transcoder + a real
+ *               `GLTFImageDecoder` that transcodes via `selectKTX2TargetFormat`
+ * `diagnostics()` reports `{loaded, failed}`; after one retry a missing
+ * decoder throws `AssetDecoderUnavailable`; `dispose()` frees handles.
+ */
+import { AssetDecoderUnavailable, withDecoderTimeout } from "./decoderLoad.js";
+import { createMeshoptDecoder, createDracoDecoder } from "./GLTFCompressionDecoders.js";
+import { selectKTX2TargetFormat } from "./KTX2TargetSelection.js";
+import { ktx2TargetToTextureFormat, loadBasisTranscoderModule, transcodeKTX2BasisTexture } from "./KTX2BasisTextureTranscoder.js";
+import { decodeImageInBrowser, isKTX2BasisImage, readImageBytes } from "./gltf/ImageDecode.js";
+import { read as readKtx2Container, KHR_DF_MODEL_UASTC, KHR_DF_TRANSFER_SRGB } from "ktx-parse";
+export { AssetDecoderUnavailable };
+/** Reads the KTX2 container header (DFD colorModel/transfer/samples) with ktx-parse. */
+export function probeKTX2Header(bytes) {
+    const container = readKtx2Container(bytes);
+    const dfd = container.dataFormatDescriptor?.[0];
+    const source = dfd?.colorModel === KHR_DF_MODEL_UASTC ? "uastc" : "etc1s";
+    // ETC1S carries alpha in a second DFD sample; UASTC alpha is irrelevant to
+    // target selection (all UASTC targets are RGBA-capable).
+    const hasAlpha = source === "etc1s" ? (dfd?.samples?.length ?? 1) > 1 : true;
+    return { source, hasAlpha, colorSpace: dfd?.transferFunction === KHR_DF_TRANSFER_SRGB ? "srgb" : "linear" };
+}
+export function createAssetDecoderRegistry(options) {
+    const basePath = options.basePath.endsWith("/") ? options.basePath : `${options.basePath}/`;
+    const loaded = new Set();
+    const failed = [];
+    // Per-decoder promise cache: repeated require() calls reuse the in-flight
+    // or resolved decoder (lazy-load exactly once per registry).
+    const decoderPromises = new Map();
+    let disposed = false;
+    const withRetry = async (id, url, load) => {
+        if (disposed)
+            throw new AssetDecoderUnavailable(id, url);
+        try {
+            const value = await load();
+            loaded.add(id);
+            return value;
+        }
+        catch {
+            // One retry, then AssetDecoderUnavailable.
+            try {
+                const value = await load();
+                loaded.add(id);
+                return value;
+            }
+            catch {
+                failed.push({ id, url });
+                throw new AssetDecoderUnavailable(id, url);
+            }
+        }
+    };
+    const loadMeshopt = () => withRetry("meshopt", `${basePath}meshopt/meshopt_decoder.mjs`, async () => {
+        const mod = await loadMeshoptModule(basePath);
+        const decoder = (mod.MeshoptDecoder ?? mod.default?.MeshoptDecoder);
+        if (!decoder)
+            throw new Error("meshopt decoder did not export MeshoptDecoder");
+        if (decoder.ready)
+            await decoder.ready;
+        return createMeshoptDecoder(decoder);
+    });
+    const loadDraco = () => withRetry("draco", `${basePath}draco/draco_decoder.js`, () => withDecoderTimeout((async () => {
+        const factory = await loadUmdGlobal("draco", `${basePath}draco/`, "draco_decoder.js", "DracoDecoderModule");
+        // Emscripten MODULARIZE: a missing/SPA-fallback wasm aborts through
+        // `onAbort`; without it the factory promise never settles.
+        const instance = await new Promise((resolve, reject) => {
+            const config = {
+                onAbort: (reason) => reject(new Error(`draco decoder aborted: ${String(reason)}`))
+            };
+            try {
+                resolve(factory(config));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        if (instance && typeof instance === "object" && "ready" in instance) {
+            await instance.ready;
+        }
+        return createDracoDecoder(instance);
+    })(), "draco decoder load"));
+    const buildKtx2ImageDecoder = async () => {
+        const transcoderUrl = `${basePath}basis/`;
+        // Warm/verify the vendored transcoder (worker pool fetches its own copy;
+        // this also covers non-Worker environments where the module is shared).
+        await withRetry("ktx2", `${transcoderUrl}basis_transcoder.js`, () => loadBasisTranscoderModule(transcoderUrl).then(() => undefined));
+        loaded.add("ktx2");
+        return async (image, imageIndex, asset) => {
+            if (!isKTX2BasisImage(image)) {
+                return decodeImageInBrowser(image, imageIndex, asset, { maxTextureSize: options.maxTextureSize, qrAssets: true });
+            }
+            const bytes = new Uint8Array(await readImageBytes(asset, image));
+            const header = probeKTX2Header(bytes);
+            const targetFormat = selectKTX2TargetFormat(options.capabilities, header.source, header.hasAlpha, header.colorSpace);
+            const decoded = await transcodeKTX2BasisTexture(bytes, {
+                targetFormat,
+                colorSpace: header.colorSpace,
+                maxDimension: options.maxTextureSize,
+                transcoderUrl,
+                workerCount: options.workerCount
+            });
+            return { ...decoded, format: ktx2TargetToTextureFormat(decoded.format) };
+        };
+    };
+    return {
+        async require(decoders) {
+            if (decoders.length === 0)
+                return {};
+            const set = {};
+            for (const decoder of decoders) {
+                if (disposed)
+                    throw new AssetDecoderUnavailable(decoder, basePath);
+                let promise = decoderPromises.get(decoder);
+                if (!promise) {
+                    promise = decoder === "meshopt" ? loadMeshopt() : decoder === "draco" ? loadDraco() : buildKtx2ImageDecoder();
+                    decoderPromises.set(decoder, promise);
+                }
+                if (decoder === "meshopt")
+                    set.meshopt = (await promise);
+                else if (decoder === "draco")
+                    set.draco = (await promise);
+                else if (decoder === "ktx2")
+                    set.imageDecoder = (await promise);
+            }
+            return set;
+        },
+        diagnostics() {
+            return { loaded: [...loaded], failed: [...failed] };
+        },
+        dispose() {
+            disposed = true;
+            loaded.clear();
+            decoderPromises.clear();
+        }
+    };
+}
+/**
+ * meshopt resolves to the same-origin vendored ESM in browsers and to the
+ * `meshoptimizer` npm package under Node/tests. Both specifiers are
+ * deliberately non-static: they are runtime-optional loads and consumer
+ * bundlers must not be forced to resolve them at build time (the engine
+ * pack does not declare `meshoptimizer` as a hard dependency).
+ */
+async function loadMeshoptModule(basePath) {
+    if (typeof document !== "undefined" || typeof globalThis.importScripts === "function") {
+        return (await import(/* @vite-ignore */ `${basePath}meshopt/meshopt_decoder.mjs`));
+    }
+    const pkg = ["mesh", "optimizer"].join("");
+    return (await import(pkg));
+}
+async function nodeBuiltins() {
+    const spec = (name) => `node:${name}`;
+    const [fs, mod, url, path] = await Promise.all([import(spec("fs")), import(spec("module")), import(spec("url")), import(spec("path"))]);
+    return {
+        fs: fs,
+        module: mod,
+        url: url,
+        path: path
+    };
+}
+/** UMD decoder bundles bind a global only under a classic `<script>` load. */
+async function loadUmdGlobal(id, dirUrl, fileName, globalName) {
+    const url = `${dirUrl}${fileName}`;
+    if (typeof document === "undefined") {
+        // Node/tests: evaluate the vendored UMD copy as CJS.
+        const { fs, module: nodeModule, url: nodeUrl, path: nodePath } = await nodeBuiltins();
+        const { readFileSync, existsSync } = fs;
+        const { createRequire } = nodeModule;
+        const { fileURLToPath } = nodeUrl;
+        const { dirname } = nodePath;
+        const require2 = createRequire(import.meta.url);
+        const candidates = [
+            new URL(`../vendor/${id === "draco" ? "draco" : "basis"}/${fileName}`, import.meta.url),
+            new URL(`../../vendor/${id === "draco" ? "draco" : "basis"}/${fileName}`, import.meta.url)
+        ];
+        const fileUrl = candidates.find((candidate) => existsSync(candidate));
+        if (!fileUrl)
+            throw new Error(`vendored ${fileName} not found next to @aura3d/assets`);
+        const filePath = fileURLToPath(fileUrl);
+        const code = readFileSync(fileUrl, "utf8");
+        const box = { exports: {} };
+        new Function("module", "exports", "require", "__dirname", "__filename", code)(box, box.exports, require2, dirname(filePath), filePath);
+        const bound = box.exports[globalName] ?? box.exports.default ?? box.exports;
+        if (bound === undefined || (typeof bound !== "function" && typeof bound !== "object")) {
+            throw new Error(`${globalName} not bound by vendored ${fileName}`);
+        }
+        // Emscripten MODULARIZE factories need their wasm binary fed directly.
+        if (typeof bound === "function") {
+            const wasmFile = fileName.replace(/\.js$/, ".wasm");
+            const wasmUrl = new URL(wasmFile, fileUrl);
+            return (config) => {
+                const cfg = { ...config, wasmBinary: existsSync(wasmUrl) ? readFileSync(wasmUrl) : undefined };
+                return bound(cfg);
+            };
+        }
+        return bound;
+    }
+    return withDecoderTimeout(new Promise((resolve, reject) => {
+        const script = document.createElement("script");
+        script.src = url;
+        script.onload = () => {
+            const bound = globalThis[globalName];
+            if (bound === undefined)
+                reject(new Error(`${globalName} not bound by ${url}`));
+            else if (typeof bound === "function") {
+                // Emscripten MODULARIZE: same-object config/return; wasm via locateFile.
+                resolve((config) => bound({ ...config, locateFile: (file) => `${dirUrl}${file}` }));
+            }
+            else
+                resolve(bound);
+        };
+        script.onerror = () => reject(new Error(`script load failed: ${url}`));
+        document.head.appendChild(script);
+    }), `script load ${url}`);
+}
+//# sourceMappingURL=AssetDecoderRegistry.js.map

package/dist/assets/AssetDecoderRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssetDecoderRegistry.js","sourceRoot":"","sources":["../../../../packages/assets/src/AssetDecoderRegistry.ts"],"names":[],"mappings":"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"}

package/dist/assets/GLTFAnimationRuntime.d.ts

@@ -1,4 +1,6 @@
-import { AnimationAction, AnimationClip, AnimationMixer, type AnimationEvent, type AnimationMixerOptions, type AnimationValue, type GroundRaycaster, type LoopMode, type TwoBoneIkResult } from "../animation/browser-index.js";
+import { AnimationAction, AnimationClip, AnimationMixer, type RootMotionConsumption, type RootMotionSample, type AnimationEvent, type AnimationMixerOptions, type AnimationValue, type GroundRaycaster, type LoopMode, type TwoBoneIkResult } from "../animation/browser-index.js";
+import { PoseMixer, type CompiledClip, type PoseBuffer, type SkeletonBinding } from "../animation/lanes/index.js";
+import { type BakeRetargetedClipsOptions } from "../animation/lanes/index.js";
 import { Scene, type Mat4 } from "../scene/index.js";
 import type { GLTFAsset } from "./GLTFLoader.js";
 /**
@@ -6,6 +8,16 @@ import type { GLTFAsset } from "./GLTFLoader.js";
  * structural (instead of importing the rendering `Material`) so the animation runtime stays
  * decoupled from the renderer; the production bridge adapts the live material library.
  */
+/**
+ * T3.8 (PRD-06 §7.2) — options for `addClipsFrom`: the bake options plus the
+ * cache/worker plumbing (`cache`/`worker` default on, `engineVersion` defaults
+ * to the lane's retarget version key).
+ */
+export interface AddClipsFromRuntimeOptions extends BakeRetargetedClipsOptions {
+    readonly engineVersion?: string;
+    readonly cache?: boolean;
+    readonly worker?: boolean;
+}
 export interface GLTFSceneAnimationMaterialSink {
     readonly name: string;
     setAnimationParameter(parameter: string, value: number | readonly number[]): void;
@@ -33,6 +45,13 @@ export interface GLTFootPlantingLegConfig {
     readonly knee: string;
     readonly ankle: string;
     readonly pole?: readonly [number, number, number];
+    /** Optional measured joint-to-sole offset for asymmetric footwear. */
+    readonly ankleHeight?: number;
+    readonly contact?: boolean;
+    readonly support?: {
+        readonly id: string;
+        readonly delta: readonly [number, number, number];
+    };
 }
 export interface GLTFootPlantingConfig {
     readonly legs: readonly GLTFootPlantingLegConfig[];
@@ -42,6 +61,8 @@ export interface GLTFootPlantingConfig {
     readonly maxRayDistance?: number;
     readonly plantThreshold?: number;
     readonly hipDropFactor?: number;
+    /** False is a diagnostic control: ankle lock alone does not plant the skinned sole. */
+    readonly lockFootRotation?: boolean;
     /**
      * Actor-local → world matrix (column-major 16). The runtime skeleton usually lives in
      * import units (the certified walk girl is centimeter-scale) while `ground` speaks world
@@ -53,6 +74,36 @@ export interface GLTFootPlantingConfig {
     readonly worldFromLocal?: Mat4;
 }
 export interface GLTFootPlantingApplyResult {
+    /** Post-writeback world ankle positions, measured from scene transforms rather than IK targets. */
+    readonly feet?: readonly {
+        readonly side: "left" | "right";
+        readonly worldPosition: readonly [number, number, number];
+        readonly contactError: number;
+        readonly locked: boolean;
+    }[];
+    readonly surfaces?: readonly {
+        readonly side: "left" | "right";
+        readonly mesh: string;
+        readonly vertex: number;
+        readonly worldPosition: readonly [number, number, number];
+        readonly groundError: number | null;
+        readonly skinningProbe?: {
+            readonly position: readonly number[];
+            readonly joints: readonly number[];
+            readonly weights: readonly number[];
+            readonly matrices: readonly number[];
+            readonly modelMatrix: readonly number[];
+            readonly expectedWorldPosition: readonly number[];
+        };
+    }[];
+    readonly legDeformation?: readonly {
+        readonly side: "left" | "right";
+        readonly upperBefore: number;
+        readonly upperAfter: number;
+        readonly lowerBefore: number;
+        readonly lowerAfter: number;
+        readonly maxRelativeLengthChange: number;
+    }[];
     readonly groundedFeet: number;
     readonly averageTargetError: number;
     readonly lockedSides: readonly ("left" | "right")[];
@@ -72,7 +123,20 @@ export interface GLTFootPlantingApplyResult {
  *
  * Returns `undefined` only when there are no available clips.
  */
-export declare function resolveGLTFClipName(requested: string, available: readonly string[]): string | undefined;
+export type ResolveGLTFClipNameFallback = "error" | "first";
+export interface ResolveGLTFClipNameOptions {
+    /**
+     * What to return when levels 1-3 (exact/synonym/substring) all miss.
+     * `"first"` keeps the legacy pick-the-first-clip behavior; `"error"`
+     * returns `undefined` so the caller can warn and degrade. When omitted,
+     * the default follows the QR defaults resolution (§5.2 env/URL sources):
+     * `"error"` under 3.1 (`A3D_QR_ANIMATION`/`A3D_QR`/`?a3d-qr=` flag on),
+     * `"first"` otherwise. Callers that know the resolved flags (the
+     * compiler) should pass it explicitly.
+     */
+    readonly fallback?: ResolveGLTFClipNameFallback;
+}
+export declare function resolveGLTFClipName(requested: string, available: readonly string[], options?: ResolveGLTFClipNameOptions): string | undefined;
 export interface GLTFSceneAnimationClipBoneMask {
     /** Only apply tracks whose node name matches one of these (substring match), if present. */
     readonly include?: readonly string[];
@@ -139,6 +203,44 @@ export interface GLTFSceneAnimationApplyResult {
     readonly skinningPalettesUpdated: number;
     readonly missingTargets: readonly string[];
     readonly unsupportedTracks: readonly string[];
+    /**
+     * PRD-06 §9.8/§13 — wall-clock split of this apply's animation phase, in
+     * ms. Published only by the pose paths (`applyClips`, `applyPoseMixer`);
+     * `cpuMs` covers the whole call (mixer + constraints + springs + target
+     * application + palette build).
+     */
+    readonly phaseTimings?: GLTFSceneAnimationPhaseTimings;
+}
+/** PRD-06 §9.8 — per-phase wall-clock timings for one animation apply (ms). */
+export interface GLTFSceneAnimationPhaseTimings {
+    readonly mixerMs: number;
+    readonly constraintsMs: number;
+    readonly springsMs: number;
+    readonly paletteBytes: number;
+    readonly cpuMs: number;
+}
+/**
+ * T3.5 (PRD-06 §7.1) — a pose-space constraint entry on the runtime. Evaluated
+ * after the mixer writes the pose and before skinning palettes are built.
+ * `bones` lists the joint indices `evaluate` may touch so the runtime unions
+ * them into the emitted sampled targets even when no clip covers them.
+ */
+export interface GLTFPoseConstraint {
+    /** Joints this constraint may write (SkeletonBinding indices). */
+    readonly bones: readonly number[];
+    /**
+     * PRD-06 §9.8 — `"springs"` tags spring-chain constraints so the runtime's
+     * phase timings can split `springsMs` from `constraintsMs`.
+     */
+    readonly kind?: "springs";
+    /**
+     * Apply the constraint onto `pose`. `modelMatrix` maps world→model space
+     * (skeleton-root space); `context.dt` is the frame dt (applyPoseMixer) or the
+     * nominal 1/60 for stateless `applyClips` evaluation.
+     */
+    evaluate(pose: PoseBuffer, binding: SkeletonBinding, modelMatrix: readonly number[] | Float32Array, context: {
+        readonly dt: number;
+    }): void;
 }
 export interface GLTFSceneAnimationRuntimeSnapshot {
     readonly clipCount: number;
@@ -170,6 +272,8 @@ export interface GLTFSceneAnimationClipBindingDiagnostics {
 export interface GLTFSceneAnimationMixerOptions extends GLTFSceneAnimationRuntimeOptions {
     readonly autoPlay?: string | false;
     readonly mixer?: AnimationMixerOptions;
+    /** Called once per blended update; owns actor movement before foot placement. */
+    readonly consumeRootMotion?: (sample: RootMotionSample) => void;
 }
 export interface GLTFSceneAnimationMixerUpdateResult {
     readonly events: readonly AnimationEvent[];
@@ -306,15 +410,48 @@ export declare class GLTFImportedSkeletonIKController {
     solve(patch?: Partial<Pick<GLTFImportedSkeletonIKControllerOptions, "target" | "pole" | "weight" | "allowStretch" | "apply">>): GLTFImportedSkeletonIKResult;
     snapshot(): GLTFImportedSkeletonIKControllerSnapshot;
 }
+/** Column-major mat4 multiply written into a Float32Array slot — the T0.11 no-alloc palette path. Exported so the §13 palette-build micro-budget test measures the exact per-joint write the runtime performs. `a` is hoisted into scalars once per call so the inner writes are pure FMA-grade flops — the indexed-read loop measured ~1.3× over the §13 palette budget. */
+export declare function multiplyMat4Into(out: Float32Array, outOffset: number, a: ArrayLike<number>, b: ArrayLike<number>): void;
+/** Column-major general 4×4 inverse into `out` (adjugate / determinant, gl-matrix `mat4.invert`; 06-T0: out[7], out[10], out[11], out[14], out[15] previously used the wrong cofactor terms, so even inverse(identity) had out[11] = -1 and every skinning palette carried a non-affine row 3 that projected skinned vertices off-screen on the GPU). §13: `invertMat4` allocates two objects per call — over 600 frames that alone blows the steady-state budget. */
+export declare function invertMat4Into(out: Float32Array, a: ArrayLike<number>): Float32Array;
 export declare class GLTFSceneAnimationRuntime {
     private readonly options;
     private readonly clipsByName;
     private readonly nodesByName;
     private readonly morphRenderablesByNodeName;
     private readonly skinningBindings;
+    private disposed;
+    private readonly footBindMatrices;
+    private readonly footOrientationLocks;
+    private readonly footDescendantLocks;
+    private readonly footSurfaceVertices;
     private footPlanting;
     private footRig;
     private lastApply?;
+    /** T0.11 scratch for the per-joint palette multiply (inverseMeshWorld * jointWorld). */
+    private readonly paletteScratch;
+    /** §13: reusable scratch for the per-binding inverse world matrix (no alloc/frame). */
+    private readonly inverseWorldScratch;
+    /** §13: persistent result object for `refreshSkinningPalettes` (0 bytes/frame). */
+    private readonly paletteResult;
+    /**
+     * T1.7 (PRD-06) — the per-runtime pose pipeline backing `applyClips`: a
+     * scene-wide SkeletonBinding (every traversed node in order, rest pose = the
+     * node's local TRS at bind time), one PoseMixer, and the compiled clips.
+     * Rebuilt whenever `reindexScene` re-reads the node set.
+     */
+    private poseState?;
+    /**
+     * T3.5 — world→model matrix provider for pose constraints. Defaults to the
+     * scene root's world matrix; the `prd06.animation` actor extension installs
+     * the app-node transform when one is known.
+     */
+    private poseConstraintModelMatrix?;
+    /**
+     * Wall-clock (ms) of the last constraint evaluation under `applyClips` —
+     * its caller passes no dt, so constraint dynamics measure the real gap.
+     */
+    private lastConstraintEvalAtMs?;
     constructor(options: GLTFSceneAnimationRuntimeOptions);
     /**
      * Enable, replace, or clear (undefined) the foot-planting post-pass. Replacing the leg
@@ -324,15 +461,74 @@ export declare class GLTFSceneAnimationRuntime {
      * model nodes move, and world-space locks stay valid across that refresh.
      */
     setFootPlanting(config: GLTFootPlantingConfig | undefined): void;
+    /**
+     * Extract real authored displacement over unwrapped clip time, hand it to the physical
+     * authority once, then apply an in-place root pose and solve feet in the updated actor
+     * transform. Rejected movement is returned and discarded rather than accumulating drift.
+     * The caller refreshes footPlanting.worldFromLocal inside move after committing movement.
+     */
+    applyRootMotionClip(name: string, options: {
+        readonly fromTime: number;
+        readonly toTime: number;
+        readonly target: string;
+        readonly loop?: boolean;
+        readonly worldFromLocal: Mat4;
+        readonly move: (requested: readonly [number, number, number]) => readonly [number, number, number];
+    }): {
+        motion: RootMotionConsumption;
+        applyResult: GLTFSceneAnimationApplyResult;
+    };
+    /** Blend displacement and consumed poses with the same base/additive weights. */
+    applyRootMotionClips(samples: readonly {
+        readonly clipName: string;
+        readonly fromTime: number;
+        readonly toTime: number;
+        readonly target: string;
+        readonly loop?: boolean;
+        readonly weight?: number;
+        readonly additive?: boolean;
+    }[], options: {
+        readonly worldFromLocal: Mat4;
+        readonly move: (requested: readonly [number, number, number]) => readonly [number, number, number];
+    }): {
+        motion: RootMotionConsumption;
+        applyResult: GLTFSceneAnimationApplyResult;
+    };
+    /**
+     * T3.7 (PRD-06 §6.8) — resolve the root-motion translation track target for
+     * spec-level `play(clip, {rootMotion})`: with `bone` set, the bone's own
+     * `translation`/`position` track; without it, the clip's root-motion
+     * candidate (largest planar displacement on a hips/root/pelvis node, then
+     * any translation track by displacement). Throws when nothing qualifies.
+     */
+    rootMotionTargetFor(clipName: string, bone?: string): string;
+    /**
+     * T3.7 — yaw delta (radians, about local Y) authored on `bone`'s rotation
+     * track between `fromTime`/`toTime` (loop-aware). Returns 0 when the clip
+     * has no matching rotation track.
+     */
+    rootMotionYawDelta(clipName: string, bone: string | undefined, fromTime: number, toTime: number, loop: boolean): number;
     applyClipByName(name: string, time: number): GLTFSceneAnimationApplyResult;
     /** Names of every clip registered on this runtime, in declaration order. */
     clipNames(): readonly string[];
+    /**
+     * T0.6 (PRD-06) — the C-19 `AuraResolvedClipInfo` surface that backs the
+     * `prd06.animation` handle extension's `resolveAnimationClips()`: real GLB
+     * clip durations (plus channel counts and the 5 cm XZ-displacement
+     * root-motion candidate heuristic of T0.7) after the asset has loaded.
+     */
+    resolvedClipInfos(): readonly {
+        readonly name: string;
+        readonly duration: number;
+        readonly channelCount: number;
+        readonly hasRootMotionCandidate: boolean;
+    }[];
     /**
      * Resolve a requested clip name to the best available registered clip name
      * using fuzzy matching (exact -> synonym group -> substring -> first clip).
      * Returns `undefined` when the runtime has no clips.
      */
-    resolveClipName(name: string): string | undefined;
+    resolveClipName(name: string, options?: ResolveGLTFClipNameOptions): string | undefined;
     /**
      * Apply a clip selected by fuzzy name resolution. Unlike {@link applyClipByName}
      * this tolerates differing source clip names (e.g. requesting "idle" when the
@@ -340,8 +536,104 @@ export declare class GLTFSceneAnimationRuntime {
      */
     applyClipByNameFuzzy(name: string, time: number): GLTFSceneAnimationApplyResult;
     applyClip(clip: AnimationClip, time: number): GLTFSceneAnimationApplyResult;
+    /**
+     * T1.7 (PRD-06 §10) — re-implemented on the per-runtime `PoseMixer` in
+     * stateless mode (`evaluateSamples` with explicit per-sample times). Node
+     * translation/rotation/scale tracks bound to a scene node go through the
+     * pose pipeline (incremental-weight accumulate + rest fill + additive
+     * accumulators, three r185 `AnimationMixer` order); morph-weight, material
+     * and light pointer tracks keep the existing accumulator path, and so do
+     * node tracks aimed at nodes the binding does not cover (they keep their
+     * `missingTargets` reporting). Two documented semantic changes vs the old
+     * accumulator blend: partial-weight mixes fill the remainder from the rest
+     * pose instead of renormalising (rest blend), and a bone covered by the
+     * blend but not by a given channel resets that channel to rest (rest reset).
+     */
     applyClips(samples: readonly GLTFSceneAnimationClipSample[]): GLTFSceneAnimationApplyResult;
+    /**
+     * §10 (PRD-06) — the scene-wide pose binding the pose path evaluates on.
+     * Joints are every scene node in `traverse` order, resolved by node index
+     * (duplicate names bind all slots); the rest pose is each node's local TRS
+     * captured at bind time.
+     */
+    skeletons(): readonly SkeletonBinding[];
+    /** §10 (PRD-06) — the per-clip compiled tracks used by the pose path. */
+    compiledClips(): ReadonlyMap<string, CompiledClip>;
+    /** §10 (PRD-06) — the per-runtime PoseMixer `applyClips` evaluates on. */
+    mixer(): PoseMixer;
+    /**
+     * T3.8 (PRD-06 §7.2, C-19) — `actor.animation.addClipsFrom(source)` retarget-
+     * bakes another skeleton's compiled clips onto this runtime's skeleton and
+     * registers them by name (raw + compiled + mixer) so `play`/`playLayer`
+     * resolve them like loaded clips. The bake runs in `pose/retarget.worker.ts`
+     * when the platform has workers, otherwise in-process, and its output is
+     * cached in IndexedDB under `(engineVersion, sourceHash, targetHash)` so a
+     * rollback ignores newer caches. Returns the registered clip names.
+     */
+    addClipsFrom(source: {
+        readonly skeleton: SkeletonBinding;
+        readonly clips: ReadonlyMap<string, CompiledClip>;
+    } | Pick<GLTFSceneAnimationRuntime, "skeletons" | "compiledClips">, options?: AddClipsFromRuntimeOptions): Promise<readonly string[]>;
+    /**
+     * T1.9 (PRD-06 §10) — advance the per-runtime `PoseMixer` by `dt` seconds
+     * and write the evaluated pose to scene nodes in `applySampledTargets`
+     * order. `restPoseReset !== false` writes every bound bone (rest-filled
+     * channels reset); `false` writes only the bones covered by active actions'
+     * bound tracks, so uncovered bones keep their current scene values.
+     * Non-pose tracks (morph weights, material/light pointer, node tracks
+     * aimed at nodes outside the binding) keep the legacy accumulator path,
+     * sampled at each active action's own clock and effective weight.
+     */
+    applyPoseMixer(dt: number, options?: {
+        readonly label?: string;
+        readonly restPoseReset?: boolean;
+    }): GLTFSceneAnimationApplyResult;
+    /**
+     * T1.10 (PRD-06 §10, C-19 `blendMode: "additive"`/`additiveReference`) — lazily
+     * compile an additive variant of `clipName` via `makeClipAdditive` (reference
+     * defaults to the clip's own first frame) and register it on the mixer under
+     * a synthesized name. Returns the registered clip key for `clipAction`/`playLayer`.
+     */
+    ensureAdditiveClip(clipName: string, reference?: {
+        readonly clip?: string;
+        readonly time?: number;
+    }): string;
+    /**
+     * T1.10 (C-19 `animation.mask`) — bind-order joint names for `createBoneMask`.
+     */
+    skeletonJointNames(): readonly string[];
+    /**
+     * T3.5 — register a pose constraint. Entries evaluate in insertion order
+     * after each mixer write; returns a disposer that removes exactly this
+     * constraint (by identity — a duplicate spec stays).
+     */
+    addPoseConstraint(constraint: GLTFPoseConstraint): () => void;
+    /** T3.5 — drop every pose constraint (constant-time identity sweep). */
+    clearPoseConstraints(): void;
+    /** T3.5 — the count of live pose constraints (diagnostics/tests). */
+    poseConstraintCount(): number;
+    /** T3.5 — install the world→model matrix provider (actor extension). */
+    setPoseConstraintModelMatrix(provider: (() => readonly number[] | Float32Array) | undefined): void;
+    /**
+     * T3.5 — evaluate the constraint list in order onto the just-mixed pose and
+     * return the union of touched joint indices (empty when no constraints),
+     * plus the §9.8 wall-clock split between `"springs"`-tagged constraints and
+     * the rest.
+     */
+    private runPoseConstraints;
+    /** §9.8/§13 — CPU-side palette payload this runtime owns, bytes (16 f32/joint). */
+    private paletteBufferBytes;
+    private poseRuntime;
     applyAnimationValues(label: string, time: number, values: ReadonlyMap<string, AnimationValue>, unsupportedTracks?: readonly string[]): GLTFSceneAnimationApplyResult;
+    /**
+     * §16 S3 (PRD-06) — teardown frees the C-18 palette textures this runtime
+     * stamped, keyed on each skin binding (`skinningPaletteCache.release`).
+     * Morph array textures and CPU-morph scratch are released by the actor's
+     * own teardown (`prd06.animation` extension dispose / pipeline lifecycle),
+     * which is the layer that can see resolved `Geometry` objects — the scene
+     * layer here only knows geometry handles.
+     */
+    dispose(): void;
     /**
      * Render-time bridge: drive the loaded GLB from an externally-computed pose whose keys are GLB
      * **node names** (e.g. the output of `@aura3d/animation`'s `retargetHumanoidPose`, whose
@@ -362,9 +654,9 @@ export declare class GLTFSceneAnimationRuntime {
     reindexScene(): void;
     private findSceneLight;
     /**
-     * Foot-planting post-pass (E2): solves the configured leg chains against the ground and
-     * writes the solved hip/knee/ankle world positions back onto the skeleton. Position-only
-     * write-back (rotations stay as animated); missing leg nodes are reported in
+     * Foot-planting post-pass (E2): solves the configured leg chains against the ground,
+     * applies a shared pelvis reach correction, and rotates rigid hip/knee chains toward the
+     * solved targets. Missing leg nodes are reported in
      * `missingLegNodes` and skipped, never faked. Returns undefined when unconfigured.
      */
     private applyFootPlanting;
@@ -382,6 +674,8 @@ export declare class GLTFSceneAnimationRuntime {
      * so a light track matching no scene light is reported missing (diagnosed, never silent).
      */
     private applyLightTrackValue;
+    /** CPU skinning oracle using the exact palette submitted to rendering, not IK targets. */
+    sampleFootSurfaces(): NonNullable<GLTFootPlantingApplyResult["surfaces"]>;
     private refreshSkinningPalettes;
     private inspectClipBinding;
     private applySampledTargets;