lecodes-sdk 0.19.1 → 0.20.0

package/dist/types/gl/Locomotion.d.ts

@@ -1,6 +1,8 @@
 import { Aspect } from "../core/Aspect";
 import { Vec3, type Vec3Like } from "../math/vec";
-import { Animator, type FeetOptions, type WarpOptions } from "./animation/Animator";
+import { Animator } from "./animation/Animator";
+import type { FeetOptions } from "./animation/Feet";
+import type { WarpOptions } from "./animation/Warp";
 import type { Node } from "./Node";
 /** How fast the character wants to go: the gait picks its clips and its speed. */
 export type Gait = "walk" | "run" | "sprint";

package/dist/types/gl/animation/Animator.d.ts

@@ -1,219 +1,87 @@
 import { Aspect } from "../../core/Aspect";
-import { Vec3 } from "../../math/vec";
 import type { Node } from "../Node";
 import type { AnimationClip } from "./AnimationClip";
-import { type ActiveClip, type ClipCurves, type ClipEventHandler, type KneeAxisReport, type LayerOptions, type LoopDef, type LoopOptions, type PlayOptions, type StepHandler, type StopOptions } from "./core";
+import { type ActiveClip, type ClipInfo, type ClipEventHandler, type LayerOptions, type LoopDef, type LoopOptions, type PlayOptions, type StopOptions } from "./core";
+import { Feet } from "./Feet";
+import { Warp } from "./Warp";
 import type { Loop } from "./Loop";
 import type { Layer } from "./Layer";
 import type { Playback } from "./Playback";
 /** Level of detail for a GLB instance (docs/lod-plan.md): `'auto'` = the engine's pick by screen size and
  *  visibility, or a fixed level 0 (full) … 3 (coarsest mesh, animation every 4th frame without fingers). */
 export type LodMode = "auto" | 0 | 1 | 2 | 3;
-/** What `Animator.warp` turns on. Speeds are m/s, angles degrees, distances metres. */
-export type WarpOptions = {
-    /** Fit the stride to the speed the body actually travels at. `[min, max]` clamps the scale
-     *  (default 0.85…1.2). It is a CORRECTION: a pack whose takes already read right at the speeds it
-     *  is played at wants none of this, and a wide range only lets the legs be stretched into shapes
-     *  nobody recorded. Open it for a pack that must cover speeds it was never recorded at. */
-    stride?: boolean | [number, number];
-    /** Turn the lower body toward where the body really travels; a number caps the turn in degrees
-     *  (default 20). The spine counter-turns, so the chest keeps facing where it faced — the whole twist
-     *  lives in one joint, which is why a few degrees read as a lean and a lot reads as a broken back.
-     *  Only applied while the gait LOOP shows: a start, a turn or a stop walks a path of its own. */
-    orientation?: boolean | number;
-    /** Below this speed — the game's or the clip's — both warps are off (default 0.2). */
-    minSpeed?: number;
-    /** How far the pelvis may drop to keep a stretched leg from locking straight (default 0.25). */
-    pelvis?: number;
-    /** The stride scale's own spring, seconds (default 0.15). The body's speed is continuous but the
-     *  shown clip's recorded one steps at every switch, so the scale is smoothed rather than followed. */
-    strideTime?: number;
-};
-/** What `Animator.feet` sets: which bones the feet are, and what the engine does with them. Distances
- *  are metres, times seconds. Every key is optional and only the keys given change — set the bones
- *  once, switch the lock on somewhere else. */
-export type FeetOptions = {
-    /** The contact bones per side — `'LeftFoot'`, or with a toe / ball `['LeftFoot', 'LeftToeBase']`.
-     *  Default: classified from the bone names (Mixamo / Unity / Blender / UE). Set them for a rig the
-     *  classifier misses; it re-bakes every clip's contacts and phase. */
-    left?: string | string[];
-    right?: string | string[];
-    /** FOOT LOCK: a foot the shown clip calls planted (its baked contacts, else a runtime detector) is
-     *  pinned where it landed — heel to ball, rolling as the clip rolls — and the leg re-solved to keep it
-     *  there while the body moves on. What hides the last of a transition's slide: the pose the new clip
-     *  starts from is not the one the old clip ended in, and the difference used to be dragged out of
-     *  the standing foot over the blend. Off by default; a `Locomotion` turns it on. */
-    lock?: boolean;
-    /** GROUND IK: each foot is put on the ground the engine probes under it (stairs, a slope, a kerb),
-     *  aligned to its normal, and the pelvis lowered so the lower leg can reach — the feet stop hanging
-     *  in the air on a step down and sinking into a step up. Needs a physics world to probe; without
-     *  one the ground is the node's own plane. Off by default. */
-    ik?: boolean;
-    /** How far the pelvis may drop for the ground (default 0.35). */
-    pelvis?: number;
-    /** The anchor's leash: a locked foot never absorbs more residual than this — beyond it the anchor
-     *  follows the animation instead of fighting it (default 0.10). */
-    unlockDistance?: number;
-    /** The lock's ease in / out, seconds (default 0.08 / 0.12). */
-    lockIn?: number;
-    lockOut?: number;
-    /** 0..1: how much the foot tilts onto the ground normal (default 1). */
-    align?: number;
-    /** The probe ray's reach above and below the ankle (default 0.6) — a step taller than this is a
-     *  hole to the probe. */
-    probe?: number;
-    /** The lock plants only once the animated ankle moves slower than this, m/s (default 0.2: a foot
-     *  the take itself holds still). Raise it to pin a foot a transition is still dragging — a run
-     *  entered from standing lands its first foot while the offset from the idle still decays. */
-    plantSpeed?: number;
-};
-/** One foot after this frame's evaluation (`Animator.foot`): whether the lock holds it, the lock's
- *  weight (eased 0…1), where it was pinned and where the leg was asked to put the ankle — all world. */
-export type FootState = {
-    locked: boolean;
-    weight: number;
-    anchor: Vec3;
-    target: Vec3;
-};
 export declare class Animator extends Aspect<"anim", Node> {
     static readonly aspect = "anim";
     private _c;
     private _rootMotion;
     private _rootRotation;
-    /** Animation level of detail. `'auto'` (default): a character small on screen or out of view is
-     *  evaluated every 2nd / 4th frame and stops sampling its finger, toe and twist joints; `'full'`:
-     *  every frame, every joint, whatever the distance — a hero seen through a scope, a cutscene actor.
-     *  Independent of `Model.lod` (the mesh level). No-op on hosts without the LOD pass. */
-    get lod(): "auto" | "full";
-    set lod(v: "auto" | "full");
+    /** The feet: the contact bones, the foot lock, ground IK, footstep events. See `Feet`. */
+    feet: Feet;
+    /** The warp: stride and orientation fitted to the body's real motion, the step warp dials. See `Warp`. */
+    warp: Warp;
     onAttach(): void;
     onDetach(): void;
-    /** The clip list, in order: the GLB's embedded clips (file order), then the clips you added. An
-     *  added clip with an embedded clip's name takes its place. */
+    /** The clip list, in order: the GLB's embedded clips, then the clips you added (an added clip with an
+     *  embedded clip's name takes its place). */
     get clips(): readonly AnimationClip[];
-    /** One clip by name, or by index into `clips` — e.g. to `slice()` it. `undefined` if there is none. */
+    /** One clip by name or index — the resource: its name, duration, tracks, events. `undefined` if none. */
     clip(ref: string | number): AnimationClip | undefined;
-    /** Add a clip under a name (default: its own `name`) — from another file, procedural, or sliced.
-     *  Overrides an embedded clip of the same name. Chainable. */
+    /** Add a clip under a name (default: its own) — from another file, procedural, or sliced. Chainable. */
     addClip(name: string | AnimationClip, clip?: AnimationClip): this;
-    /** Play a one-shot on the base layer — by name, index, or the first clip with no argument. It
-     *  takes the layer over from whatever it showed, transitioned over `fade` (default 0.2 s).
-     *  Returns a Playback: `await` it — it resolves at the clip's hand-over (`true`; `false` if cut
-     *  short), and what you start right after is what the clip hands the layer to (another one-shot,
-     *  `playLoop(next)`; nothing = back to the loop). */
+    /** What the engine measured about a clip on THIS skeleton (unlike `clip()`, which is the file's data):
+     *  speed, travel, turn, the foot contacts, the gait phase, its cycle, and comparisons with other clips.
+     *  Binds the clip on first ask. `undefined` if there is no such clip. */
+    clipInfo(clip: string | number): ClipInfo | undefined;
+    /** Play a one-shot: by name, index, or the first clip. It takes the layer over from whatever it showed,
+     *  transitioned over `fade`. `await` the Playback: it resolves at the hand-over (`true`, or `false` if cut
+     *  short), and what you start right then is what the clip hands over to (nothing = back to the loop). */
     play(clip?: string | number, options?: PlayOptions): Playback;
-    /** Set the base layer's LOOP — what it shows when no one-shot plays: a clip (`playLoop('Idle')`) or
-     *  a blend space (`playLoop({ Idle: 0, Run: 6 })`, drive the returned object's `value`). Takes the
-     *  layer over from whatever plays — a one-shot included (it is cut short) — transitioned over
-     *  `fade`. `stop()` removes it. */
+    /** Set the LOOP — what shows when no one-shot plays: a clip, or a blend space (`{ Idle: 0, Run: 6 }`, drive
+     *  the returned object's `value`). Takes the layer over, a one-shot included. `stop()` removes it. */
     playLoop(def: LoopDef, options?: LoopOptions): Loop | undefined;
-    /** Fade everything out, on every layer (loops included) → rest pose. */
+    /** Fade everything out, on every layer → the rest pose. */
     stop(options?: StopOptions): this;
-    /** The base layer's current loop (the object the last `playLoop()` returned), if any. */
+    /** The current loop (the object the last `playLoop()` returned), if any. */
     get loop(): Loop | undefined;
-    /** A one-shot on the base layer hasn't handed over yet. */
+    /** A one-shot hasn't handed over yet. */
     get busy(): boolean;
-    /** What every layer shows this frame with its weight: one one-shot, or a loop's members with their
-     *  blend shares (a debug overlay's list). */
+    /** What every layer shows this frame, with weights: a one-shot, or a loop's members with their shares. */
     get active(): ActiveClip[];
-    /** Where the base layer is in the GAIT CYCLE: 0 at a left-foot-down, 0.5 at a right-foot-down,
-     *  whether a loop or a one-shot shows it. -1 when what plays has no cycle (an idle, a hit reaction).
-     *  This is the number `play(clip, { phase: 'match' })` matches against. */
+    /** Where the base layer is in the GAIT CYCLE: 0 at a left-foot-down, 0.5 at a right-foot-down; -1 when
+     *  what plays has no cycle. What `play(clip, { phase: 'match' })` matches against. */
     get phase(): number;
-    /** The native animator's id — 0 until something is played or bound. Engine-facing code only. */
-    get _id(): number;
-    /** Bind a clip to the base layer without playing it and return its native slot (-1 = no such clip);
-     *  creates the native animator on first use. What a Locomotion registers its set with. */
-    _slot(clip: string | number): number;
-    /** What the engine measured on a clip once it was bound to this skeleton: foot contacts, the gait
-     *  phase φ(t), and the root's travel / yaw / speed — a controller reads these instead of shipping
-     *  measured tables. Binds the clip on first ask. `undefined` if there is no such clip. */
-    curves(clip: string | number): ClipCurves | undefined;
-    /** The skeleton's calibrated KNEE HINGE AXIS for a side (thigh-local, unit) with its confidence
-     *  report — measured once over every bound clip's knee rotation track; the ground truth
-     *  `curves(clip).kneePoleAt` predicts bend planes from. Undefined = no leg chain, or no knee
-     *  motion bound to calibrate from. */
-    kneeAxis(side: "left" | "right"): KneeAxisReport | undefined;
-    /** STEP WARP v2 knobs (the warp rewrite): `stride` scales each foot's travel-direction offset
-     *  from its hip (the step shortens / lengthens), `lift` = metres ADDED to its height
-     *  (swing-gated; 0 = neutral, negative = a shuffle; half of what it adds raises the pelvis —
-     *  the body steps higher with the foot), `pitch` (degrees, + = toes up) rotates each foot about
-     *  its lateral axis, `slope` (degrees, + = ascending) the invisible staircase — feet on the
-     *  incline + auto pitch; raise the character by tan(slope) × the stride-scaled clip travel to
-     *  hold each planted foot on its tread. Solved in the calibrated knee hinge plane.
-     *  Omit / null = off. A tuning bench's dial — locomotion will drive this itself later. */
-    setStepWarp(options?: {
-        stride?: number;
-        lift?: number;
-        pitch?: number;
-        slope?: number;
-    } | null): void;
-    /** Scrub: set `clip`'s playhead directly, seconds — for inspectors and debug boards (pair with
-     *  `speed = 0`). The clip should be the one showing; nothing is faded or re-picked. */
-    seek(clip: string | number, time: number): void;
-    /** `clip`'s current playhead, seconds (-1 = not bound). */
+    /** A clip's playhead, seconds (-1 = not bound). */
     time(clip: string | number): number;
-    /** Re-aim a playing turn clip's warp (`play({ turn })`) to `deg` for the whole clip — the scale lands on what is
-     *  still to come; `undefined` = off. */
+    /** Scrub a clip's playhead, seconds — inspectors and debug boards (pair with `speed = 0`). Nothing is
+     *  faded or re-picked. */
+    seek(clip: string | number, time: number): void;
+    /** Re-aim a playing turn clip's warp (`play({ turn })`) to `deg` for the rest of the clip; `undefined` = off. */
     setTurn(clip: string | number, deg: number | undefined): void;
-    /** THE FEET (docs/animation-v2-plan.md §2.9): which bones they are, and what the engine does with
-     *  them after the clips are composited — the foot LOCK (a planted foot stays where it landed while the
-     *  body moves on) and GROUND IK (each foot on the ground probed under it, the pelvis lowered). Only
-     *  the keys given change, so the bones and the behaviour can be set from different places:
-     *
-     *      model.anim.feet = { left: 'LeftFoot', right: 'RightFoot' }   // a rig the classifier misses
-     *      model.anim.feet = { lock: true }                              // (a Locomotion does this itself)
-     *      model.anim.feet = { lock: true, ik: true, pelvis: 0.3 }       // stairs and slopes
-     *
-     *  The engine probes the ground itself (against what a character can stand on) and reads the
-     *  CharacterController's ground state; nothing is fed per frame. See `FeetOptions`. */
-    set feet(f: FeetOptions);
-    private readonly _feetOpts;
-    /** One foot's state after this frame's evaluation — where the lock holds it and with what weight
-     *  (a debug beam under the foot). `undefined` on a host without the feet stage, or before anything
-     *  played. */
-    foot(side: "left" | "right"): FootState | undefined;
-    /** WARPING (docs/animation-v2-plan.md §2.7) — the pose is fitted to what the body actually does,
-     *  after the clips are composited and before the feet:
-     *
-     *  `stride` — each leg's hip→foot vector is scaled ALONG the travel direction by the ratio of the
-     *    game speed to the shown clip's own (clamped, default 0.6…1.5), the foot height kept, and the
-     *    pelvis lowered when that would overextend a leg. A walk played at 1.9 m/s stops skating; a
-     *    speed between two gaits becomes continuous instead of "two clips and a crossfade".
-     *  `orientation` — the lower body turns from the clip's travel direction toward the one the body
-     *    really travels in (capped, default 60°) and the spine counter-turns, so the chest keeps its
-     *    facing. Arcs and strafing stop needing a clip per angle.
-     *
-     *  Both need to know the body's motion, which a `Locomotion` feeds every frame; without one, set
-     *  `_creator.animatorSetMotion` yourself or leave warping off. Off by default.
-     *
-     *      model.anim.warp = true                                  // both, with the defaults
-     *      model.anim.warp = { stride: [0.7, 1.4], orientation: 45 }
-     */
-    set warp(w: WarpOptions | boolean);
-    /** A foot planted (world position) — audio, dust, decals. Fires for what the BASE layer shows,
-     *  from the clip's own contacts; a clip with no contacts fires nothing. */
-    onStep(cb: StepHandler): this;
-    offStep(cb: StepHandler): this;
-    /** A new layer on top (masked override / additive). The returned object is its handle. */
-    addLayer(options?: LayerOptions): Layer;
-    on(event: string, cb: ClipEventHandler): this;
-    off(event: string, cb: ClipEventHandler): this;
     /** Global playback rate: 0.3 = slow-mo, 0 = pause. */
     get speed(): number;
     set speed(v: number);
-    /** Root motion: the root bone's horizontal travel comes OFF the pose and moves the node instead —
-     *  or its CharacterController (on this node or an ancestor) as a velocity, so it collides. For
-     *  clips whose hips actually travel (Mixamo without "In Place", lunges, rolls). A character that
-     *  moves under a `Locomotion` gets this from its displacement mode instead. */
+    /** Clip events (`clip.addEvent(0.4, 'hit')` → `anim.on('hit', …)`). */
+    on(event: string, cb: ClipEventHandler): this;
+    off(event: string, cb: ClipEventHandler): this;
+    /** A new layer on top (masked override / additive); the returned object is its handle. */
+    addLayer(options?: LayerOptions): Layer;
+    /** The root bone's horizontal travel comes OFF the pose and moves the node — or its CharacterController
+     *  (on this node or an ancestor) as a velocity, so it collides. For clips whose hips actually travel. A
+     *  character under a `Locomotion` gets this from its displacement mode instead. */
     get rootMotion(): boolean;
     set rootMotion(on: boolean);
-    /** With `rootMotion`, the root bone's TURN (its yaw about the node's up, since the clip's first
-     *  frame) is root motion too: it comes off the pose and turns the node the travel lands on — the
-     *  character (or the model) faces where a turn-start / turn-in-place / arc clip took it, and the
-     *  crossfade into the next clip keeps that heading instead of swinging back. Off by default: a
-     *  walk cycle's hip sway is a turn too, and most rigs want it in the pose; turn it on for a rig
-     *  whose root bone carries the heading (`lecodes assets retarget --root-rotation yaw`). */
+    /** With `rootMotion`: the root bone's TURN is root motion too — it comes off the pose and turns the node,
+     *  so a turn clip leaves the character facing where it took it. Off by default (a walk's hip sway is a
+     *  turn too); on for a rig whose root carries the heading (`lecodes assets retarget --root-rotation yaw`). */
     get rootRotation(): boolean;
     set rootRotation(on: boolean);
+    /** `'auto'` (default): a character small on screen or out of view is evaluated every 2nd / 4th frame
+     *  without its finger, toe and twist joints; `'full'`: every frame, every joint (a hero seen through a
+     *  scope). Independent of `Model.lod`, the mesh level. */
+    get lod(): "auto" | "full";
+    set lod(v: "auto" | "full");
+    /** The native animator's id — 0 until something is played or bound. */
+    get _id(): number;
+    /** Bind a clip to the base layer without playing it; its native slot (-1 = no such clip). */
+    _slot(clip: string | number): number;
 }

package/dist/types/gl/animation/Feet.d.ts

@@ -0,0 +1,85 @@
+import { Vec3 } from "../../math/vec";
+import type { KneeAxisReport, StepHandler } from "./core";
+/** The feet settings (`anim.feet.set()` / the properties of `anim.feet`). Distances are metres, times
+ *  seconds. Every key is optional and only the keys given change. */
+export type FeetOptions = {
+    /** The contact bones per side — `'LeftFoot'`, or with a toe / ball `['LeftFoot', 'LeftToeBase']`.
+     *  Default: classified from the bone names (Mixamo / Unity / Blender / UE). Setting them re-bakes
+     *  every clip's contacts and phase. */
+    left?: string | string[];
+    right?: string | string[];
+    /** FOOT LOCK: a foot the shown clip calls planted is pinned where it landed — heel to ball, rolling
+     *  as the clip rolls — and the leg re-solved to keep it there while the body moves on. Off by default. */
+    lock?: boolean;
+    /** GROUND IK: each foot is put on the ground the engine probes under it (stairs, a slope, a kerb),
+     *  aligned to its normal, the pelvis lowered so the leg can reach. Needs a physics world to probe;
+     *  without one the ground is the node's own plane. Off by default. */
+    ik?: boolean;
+    /** How far the pelvis may drop for the ground (default 0.35). */
+    pelvis?: number;
+    /** A locked foot never absorbs more residual than this — beyond it the anchor follows the animation
+     *  instead of fighting it (default 0.10). */
+    unlockDistance?: number;
+    /** The lock's ease in / out, seconds (default 0.08 / 0.12). */
+    lockIn?: number;
+    lockOut?: number;
+    /** 0..1: how much the foot tilts onto the ground normal (default 1). */
+    align?: number;
+    /** The probe ray's reach above and below the ankle (default 0.6). */
+    probe?: number;
+    /** The lock plants only once the animated ankle moves slower than this, m/s (default 0.2). Raise it
+     *  to pin a foot a transition is still dragging. */
+    plantSpeed?: number;
+};
+/** One foot after this frame's evaluation (`anim.feet.state(side)`): whether the lock holds it, the
+ *  lock's weight (eased 0…1), where it was pinned and where the leg was asked to put the ankle — all world. */
+export type FootState = {
+    locked: boolean;
+    weight: number;
+    anchor: Vec3;
+    target: Vec3;
+};
+export declare class Feet {
+    private readonly _c;
+    private readonly _o;
+    /** Change several settings at once; only the keys given change. Chainable. */
+    set(options: FeetOptions): this;
+    /** The current settings (what was set; unset keys are the engine's defaults). */
+    get options(): Readonly<FeetOptions>;
+    get lock(): boolean;
+    set lock(v: boolean);
+    get ik(): boolean;
+    set ik(v: boolean);
+    get pelvis(): number;
+    set pelvis(v: number);
+    get unlockDistance(): number;
+    set unlockDistance(v: number);
+    get lockIn(): number;
+    set lockIn(v: number);
+    get lockOut(): number;
+    set lockOut(v: number);
+    get align(): number;
+    set align(v: number);
+    get probe(): number;
+    set probe(v: number);
+    get plantSpeed(): number;
+    set plantSpeed(v: number);
+    /** The contact bones (`undefined` = classified from the names). */
+    get left(): string | string[] | undefined;
+    set left(v: string | string[] | undefined);
+    get right(): string | string[] | undefined;
+    set right(v: string | string[] | undefined);
+    /** One foot's state after this frame's evaluation — where the lock holds it and with what weight
+     *  (a debug beam under the foot). `undefined` on a host without the feet stage, or before anything played. */
+    state(side: "left" | "right"): FootState | undefined;
+    /** The skeleton's calibrated KNEE HINGE AXIS for a side (thigh-local, unit) with its confidence report —
+     *  measured once over every bound clip's knee rotation track. `undefined` = no leg chain, or no knee
+     *  motion bound to calibrate from. */
+    kneeAxis(side: "left" | "right"): KneeAxisReport | undefined;
+    /** A foot planted (world position) — audio, dust, decals. Fires for what the BASE layer shows, from
+     *  the clip's own contacts; a clip with no contacts fires nothing. */
+    onStep(cb: StepHandler): this;
+    offStep(cb: StepHandler): this;
+    private pushBones;
+    private push;
+}

package/dist/types/gl/animation/Warp.d.ts

@@ -0,0 +1,53 @@
+/** What `anim.warp` turns on. Speeds are m/s, angles degrees, distances metres. */
+export type WarpOptions = {
+    /** Fit the stride to the speed the body actually travels at. `[min, max]` clamps the scale (default
+     *  0.85…1.2). A CORRECTION: a pack whose takes already read right at the speeds it is played at wants
+     *  none of this; open the range for a pack that must cover speeds it was never recorded at. */
+    stride?: boolean | [number, number];
+    /** Turn the lower body toward where the body really travels; a number caps the turn in degrees
+     *  (default 20). The whole twist lives in one joint: a few degrees read as a lean, a lot as a broken
+     *  back. Only applied while the gait LOOP shows — a start, a turn or a stop walks a path of its own. */
+    orientation?: boolean | number;
+    /** Below this speed — the game's or the clip's — both warps are off (default 0.2). */
+    minSpeed?: number;
+    /** How far the pelvis may drop to keep a stretched leg from locking straight (default 0.25). */
+    pelvis?: number;
+    /** The stride scale's own spring, seconds (default 0.15): the shown clip's recorded speed steps at every
+     *  switch, so the scale is smoothed rather than followed. */
+    strideTime?: number;
+};
+/** STEP WARP dials (`anim.warp.step`): `stride` scales each foot's travel-direction offset from its hip,
+ *  `lift` = metres ADDED to its height (swing-gated; negative = a shuffle; half of it raises the pelvis),
+ *  `pitch` (degrees, + = toes up) rotates each foot about its lateral axis, `slope` (degrees, + = ascending)
+ *  the invisible staircase — feet on the incline, auto pitch, the character raised to hold each planted
+ *  foot on its tread. A tuning bench's dial; locomotion will drive this itself later. */
+export type StepWarpOptions = {
+    stride?: number;
+    lift?: number;
+    pitch?: number;
+    slope?: number;
+};
+export declare class Warp {
+    private readonly _c;
+    private _o;
+    private _step;
+    /** Replace the settings: `true` = both warps with the defaults, `false` / `{}` = off, or the options.
+     *  (Replaces, does not merge — what is not asked for is off.) Chainable. */
+    set(w: WarpOptions | boolean): this;
+    /** The current settings. */
+    get options(): Readonly<WarpOptions>;
+    get stride(): boolean | [number, number];
+    set stride(v: boolean | [number, number]);
+    get orientation(): boolean | number;
+    set orientation(v: boolean | number);
+    get minSpeed(): number;
+    set minSpeed(v: number);
+    get pelvis(): number;
+    set pelvis(v: number);
+    get strideTime(): number;
+    set strideTime(v: number);
+    /** The step warp dials; `null` = off. */
+    get step(): StepWarpOptions | null;
+    set step(v: StepWarpOptions | null | undefined);
+    private push;
+}

package/dist/types/gl/animation/core.d.ts

@@ -48,8 +48,17 @@ export type LoopOptions = {
      *  over from a start / turn clip wants). The members share one clock, so this is every member's phase. */
     phase?: number | "match";
 };
-/** What a layer loops: one clip (name / index), or a blend space `{ name: position }`. */
-export type LoopDef = string | number | Record<string, BlendPosition>;
+/** A blend member with its CYCLE given explicitly: `at` = its position, `offset` = its gait phase at t = 0
+ *  (0 = a left-foot-down, 0.5 = a right-foot-down, 0–1), `cycles` = how many gait cycles the clip holds
+ *  (a two-stride loop: 2). Both are measured offline from the clip's foot marks. Members given as a
+ *  bare position run in normalized time and have no cycle (nothing phase-matches to them). */
+export type BlendMember = {
+    at: BlendPosition;
+    offset?: number;
+    cycles?: number;
+};
+/** What a layer loops: one clip (name / index), or a blend space `{ name: position | { at, offset, cycles } }`. */
+export type LoopDef = string | number | Record<string, BlendPosition | BlendMember>;
 /** One clip the layer shows this frame — `layer.active` / `anim.active` (a debug overlay's list). */
 export type ActiveClip = {
     name: string;
@@ -73,9 +82,28 @@ export type LayerOptions = {
 export type ClipEventHandler = (clip: string, layer: Layer) => void;
 /** A foot planted: which one, and where in the world it landed. */
 export type StepHandler = (side: "left" | "right", position: Vec3) => void;
-/** What the engine measured on a clip once it was bound to this skeleton (`anim.curves('Walk')`).
+/** A loop's GAIT CYCLE as two numbers — what a blend member's `{ offset, cycles }` wants: φ(t) = offset +
+ *  cycles · t / duration, 0 = a left-foot-down. `residual` = the worst foot-down's distance from that line
+ *  (cycles; a clean loop sits under 0.03), `steps` = the foot-downs it was fitted through. */
+export type ClipCycle = {
+    offset: number;
+    cycles: number;
+    residual: number;
+    steps: number;
+};
+/** A loop's cycle found by POSE against a reference loop (`clipInfo(clip).alignTo(ref)`): the `{ offset,
+ *  cycles }` under which it shows the reference's pose at the reference's phase. `score` = the fit at that
+ *  alignment (metres, the joint distance + velocity measure), `margin` = how much worse the runner-up
+ *  alignment ≥ 0.2 cycle away is — near 0 means ambiguous (a mirror pair, an in-place idle). */
+export type ClipAlign = {
+    offset: number;
+    cycles: number;
+    score: number;
+    margin: number;
+};
+/** What the engine measured on a clip once it was bound to this skeleton (`anim.clipInfo('Walk')`).
  *  The root curves are of the clip's ROOT bone — its travel is what root motion would move. */
-export type ClipCurves = {
+export type ClipInfo = {
     /** total horizontal root travel, metres */
     travel: number;
     /** mean root speed over the clip, m/s */
@@ -84,6 +112,17 @@ export type ClipCurves = {
     turn: number;
     /** the root barely moves — an in-place clip */
     inPlace: boolean;
+    /** The gait cycle fitted through the foot contacts (a foot already down at t = 0 is not a step) —
+     *  the numbers a blend member takes as `{ offset, cycles }`. Undefined: no steps. */
+    cycle(): ClipCycle | undefined;
+    /** This loop's cycle found by POSE against `reference` (its cycle given, else `reference`'s `cycle()`,
+     *  else offset 0 / one cycle — the answer is then relative to the reference's own time). Reads no marks:
+     *  a markless loop (swimming, breathing, an upper-body sway) gets a cycle, and a marked one gets a
+     *  second opinion — a mirrored anchor shows as a 0.5 disagreement with `cycle()`. Undefined: nothing to compare. */
+    alignTo(reference: string | number, cycle?: {
+        offset: number;
+        cycles: number;
+    }): ClipAlign | undefined;
     /** the clip has a gait cycle (feet planting in turn) — `phaseAt` is meaningful */
     hasPhase: boolean;
     /** When each foot TOUCHES the ground, seconds — the phase anchor. `still` is the window inside it
@@ -185,7 +224,7 @@ export type ClipCurves = {
      *  relative to the root, no turn). Starts, stops and turns are not. */
     cyclic: boolean;
 };
-/** The calibrated knee hinge-axis report (`anim.kneeAxis('left')`): the axis in the thigh's local
+/** The calibrated knee hinge-axis report (`anim.feet.kneeAxis('left')`): the axis in the thigh's local
  *  frame, and the calibration's own confidence — the angular spread of its measurements (radians;
  *  a real knee comes in at a few degrees) over `samples` consecutive-frame deltas of the pack.
  *  `plant` = the calibrated PLANT HEIGHTS (model space): where the ankle / toe actually sit under
@@ -309,7 +348,7 @@ export declare class Core {
     /** A bound clip's current playhead, seconds (-1 = not bound). */
     timeOf(ref: string | number): number;
     /** What the engine measured on the clip once it was bound to this skeleton — binds it if needed. */
-    curves(ref: string | number): ClipCurves | undefined;
+    clipInfo(ref: string | number): ClipInfo | undefined;
     /** The skeleton's calibrated knee hinge axis for a side, with its confidence report — measured once
      *  over every bound clip's knee rotation track. Undefined = no leg chain / no knee motion bound. */
     kneeAxis(side: "left" | "right"): KneeAxisReport | undefined;
@@ -321,7 +360,7 @@ export declare class Core {
      *  own lateral axis — a slope's foot rotation; `slope` (degrees, + = ascending) is the INVISIBLE
      *  STAIRCASE: foot heights follow the incline (leading foot higher) and the feet auto-pitch by
      *  the same angle — pair it with raising the character by tan(slope) × the stride-scaled clip
-     *  travel (`curves(clip).travelAt`), which holds every planted foot's world height constant on
+     *  travel (`clipInfo(clip).travelAt`), which holds every planted foot's world height constant on
      *  its own tread. Solved in the calibrated knee hinge plane with a SOFT reach (a leg at its limit
      *  keeps a residual knee bend instead of popping against the clamp), and whenever a leg would
      *  overreach — a descent, a long stride — the pelvis lowers by exactly the excess (weighted by

package/dist/types/inject.d.ts

@@ -60,6 +60,7 @@ export { easeIn, easeOut, easeInOut } from "./animate/easings";
 export { QRScanner } from "./plugins/qr";
 export { CameraView, type CameraFacing } from "./plugins/camera";
 export { Geolocation, type GeoPosition, type GeoOptions, type GeoWatch } from "./plugins/geolocation";
+export { MapView, type MapOptions, type MapStyle, type MapStyleName, type MapCamera, type MapTap, type LngLat, type CameraMove, type FitOptions, type MapPaddingValues, type MarkerItem, type MarkerTap, type MarkerLayer, type MarkerLayerOptions, type LineLayer, type LineLayerOptions, type UserLocationOptions, } from "./plugins/map";
 export { Push, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/push";
 export { OAuth, type OAuthCredential, type OAuthProviderName } from "./plugins/oauth";
 export { Service } from "./plugins/service";
@@ -94,11 +95,15 @@ export { Gearbox } from "./gl/Gearbox";
 export { AnimationClip } from "./gl/animation/AnimationClip";
 export type { ClipDef, ClipTrackDef, ClipKey } from "./gl/animation/AnimationClip";
 export { Animator } from "./gl/animation/Animator";
-export type { WarpOptions, FeetOptions, FootState } from "./gl/animation/Animator";
+export type { LodMode } from "./gl/animation/Animator";
+export { Feet } from "./gl/animation/Feet";
+export type { FeetOptions, FootState } from "./gl/animation/Feet";
+export { Warp } from "./gl/animation/Warp";
+export type { WarpOptions, StepWarpOptions } from "./gl/animation/Warp";
 export { Playback } from "./gl/animation/Playback";
 export { Loop } from "./gl/animation/Loop";
 export { Layer } from "./gl/animation/Layer";
-export type { PlayOptions, StopOptions, LayerOptions, LoopOptions, LoopDef, BlendPosition, ActiveClip } from "./gl/animation/core";
+export type { PlayOptions, StopOptions, LayerOptions, LoopOptions, LoopDef, BlendPosition, BlendMember, ActiveClip, ClipInfo, ClipCycle, ClipAlign, KneeAxisReport, StepHandler, ClipEventHandler } from "./gl/animation/core";
 export { IK } from "./gl/IK";
 export type { IKTwoBone, IKLookAt } from "./gl/IK";
 export { Light } from "./gl/Light";