@rig-c/play 0.0.0-stage → 1.8.0

package/dist/loadModel.d.ts

@@ -0,0 +1,112 @@
+import { type RegionImage } from './DomTexture.js';
+/**
+ * Loads a rig built by `rigc build`: the compiled model document
+ * (`skeleton.model.json`, spec `rigc-compiled/3`) and the page images its
+ * `pages` section names, cut into region bitmaps once.
+ *
+ * The document states everything the player reads — the skeleton, the
+ * animations, and where every region sits on its page — so the `.atlas` and
+ * `skeleton.json` the build writes beside it are not fetched. A Spine export
+ * (`.json`, `.skel`) is refused by name: this package poses the compiled model
+ * through `rig-c/core` and reads nothing else.
+ */
+export interface LoadModelOptions {
+    /** URL of the compiled model document (`skeleton.model.json`). */
+    modelUrl: string;
+    /**
+     * Maps a page name from the document's `pages` section to the URL its image
+     * lives at. Defaults to resolving the name against the model URL's
+     * directory: a build writes page names as paths relative to its own
+     * directory, which is where the document sits.
+     */
+    resolvePage?: (pageName: string, modelUrl: string) => string;
+    /**
+     * crossOrigin attribute for the page images. Needed when the images come
+     * from another origin: the region cut reads them into a canvas, and a
+     * tainted canvas cannot be exported (SecurityError from toBlob).
+     */
+    crossOrigin?: string;
+    /** fetch implementation, for custom headers or a test double. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * What the region cut produces — the rigid tier's per-region bitmaps, which
+     * only the DOM mode draws. `'blob'` (the default): `blob:` URLs the load
+     * owns and `dispose` frees. `'data'`: `data:` URLs, for a content policy or
+     * a snapshot that does not carry `blob:`; nothing to free. `'none'`: no cut
+     * at all, for a load that only ever draws in the canvas mode — the pages
+     * are loaded, `regionImages` is empty, and a DOM-mode player opened on the
+     * assets is refused by name.
+     */
+    regions?: RegionLoading;
+}
+/** `LoadModelOptions.regions`: how, or whether, the regions are cut. */
+export type RegionLoading = 'blob' | 'data' | 'none';
+/**
+ * What `new RigPlayer(root, assets)` draws from. The caller owns it: one load
+ * can back any number of players, and nothing a player does disposes it.
+ */
+export interface ModelAssets {
+    /** The document's spec, e.g. `rigc-compiled/3`. */
+    readonly spec: string;
+    /** Every animation the document carries, in its order, with the runtime's duration. */
+    readonly animations: ReadonlyArray<{
+        readonly name: string;
+        readonly duration: number;
+    }>;
+    /** Every skin the document declares, in its order. */
+    readonly skins: readonly string[];
+    /**
+     * The document's `stage` section, in world units (Y up): the stage the
+     * build declared — the rig's own framing, for laying out a stage — or null
+     * where the document has none. Where its value comes from is rigc's rule,
+     * not this package's (rigc `docs/AUTHORING.md`, *Where the rebuild's stage
+     * comes from*): a source that states a stage is written as stated, and a
+     * source that states none gets the setup pose's bounding box in its place.
+     * So one rig's `stage` is a declared frame and another's is a box, and the
+     * field does not say which. For the box of what a pose draws, read
+     * `player.bounds()`.
+     */
+    readonly stage: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    } | null;
+    /** How the regions were cut (`LoadModelOptions.regions`): `'none'` means `regionImages` is empty and only the canvas mode can draw. */
+    readonly regions: RegionLoading;
+    /** Unpacked per-region bitmaps, keyed by region name — the rigid tier's. Empty on a `regions: 'none'` load. */
+    readonly regionImages: Map<string, RegionImage>;
+    /** Page images, keyed by the document's page names — the mesh tier's. */
+    readonly pageImages: Map<string, HTMLImageElement>;
+    /**
+     * The document as `rig-c/core` read it. Opaque to callers: the player poses
+     * it, and its shape is rig-c's, not this package's.
+     */
+    readonly document: ModelDocument;
+    /**
+     * Frees the blob URLs this load created (see revokeRegions). Idempotent.
+     * Call it after the players drawing from these assets are disposed — a live
+     * <img> would be left pointing at a dead URL.
+     */
+    dispose(): void;
+}
+/** The read document, held for the player. Deliberately opaque. */
+export interface ModelDocument {
+    readonly spec: string;
+}
+/**
+ * Loads a rig built by `rigc build`.
+ *
+ * ```ts
+ * const assets = await loadModel({ modelUrl: '/rigs/walk/skeleton.model.json' });
+ * const player = new RigPlayer(root, assets);
+ * player.play('walk');
+ * // each frame: player.frame(dt)
+ * // …later: player.dispose(); assets.dispose();
+ * ```
+ *
+ * Page images load in parallel. If anything fails part-way, no blob URL is
+ * left behind.
+ */
+export declare function loadModel(options: LoadModelOptions): Promise<ModelAssets>;
+//# sourceMappingURL=loadModel.d.ts.map

package/dist/loadModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadModel.d.ts","sourceRoot":"","sources":["../src/loadModel.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAgC,MAAM,iBAAiB,CAAC;AAEjF;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7D;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzF,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACnH,uIAAuI;IACvI,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,+GAA+G;IAC/G,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAChD,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACnD;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC;;;;OAIG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAgED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CA0C/E"}

package/dist/pixelRatio.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The one forced layout both renderers share: how many device pixels one of
+ * the root's CSS pixels covers on screen, read off a throwaway box.
+ *
+ * A renderer rasters at `world × pixelRatio` in the root's own coordinates,
+ * so a `transform: scale(z)` on an ancestor — how a pan/zoom stage is built —
+ * oversamples by 1/z² in backing pixels unless the zoom is folded into the
+ * ratio. Neither renderer measures this on its own: it is a layout read, and
+ * there is no per-frame layout read anywhere in this library. The caller
+ * invokes `syncPixelRatio()` when a zoom or a resize settles.
+ */
+/**
+ * Measures `root`'s effective on-screen scale once and returns the ratio now
+ * in effect: `devicePixelRatio × scale` when that differs from `current` by
+ * more than the deadband, else `current` unchanged. A root that is not laid
+ * out (a `display: none` ancestor, a detached root) measures nothing, so
+ * nothing is decided and `current` comes back. Appends a hidden box to the
+ * root, reads its rect, removes it — the root's children are the same
+ * elements in the same order on both sides of the call.
+ */
+export declare function syncedPixelRatio(root: HTMLElement, current: number): number;
+//# sourceMappingURL=pixelRatio.d.ts.map

package/dist/pixelRatio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pixelRatio.d.ts","sourceRoot":"","sources":["../src/pixelRatio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAcH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA2B3E"}

package/dist/player.d.ts

@@ -0,0 +1,453 @@
+import { CanvasRenderer } from './CanvasRenderer.js';
+import { DomRenderer, type MeshBackend } from './DomRenderer.js';
+import type { ModelAssets } from './loadModel.js';
+import { type PosedFrame } from './posedFrame.js';
+/**
+ * Plays a rig built by `rigc build` on a DOM root.
+ *
+ * The player owns the track and the renderer: `play` opens an animation on a
+ * live track (`openTrack` from `rig-c/core`), each `frame(dt)` steps it by
+ * `dt × timeScale`, turns the pose into a `PosedFrame` and hands that to its
+ * renderer — a `DomRenderer` (`mode: 'dom'`, the default) or a
+ * `CanvasRenderer` (`mode: 'canvas'`). Everything the pose holds is computed by
+ * the core from the compiled model document; this class schedules and draws.
+ */
+/**
+ * How a player draws: `'dom'` — elements, the rigid tier as `<img>` and the
+ * mesh tier on per-part canvases (`DomRenderer`); `'canvas'` — the whole frame
+ * into one `<canvas>` through the shared WebGL context (`CanvasRenderer`).
+ */
+export type RenderMode = 'dom' | 'canvas';
+export interface RigPlayerOptions {
+    /**
+     * The skin to pose under. Absent is the runtime's "no skin set" — a fresh
+     * skeleton whose `setSkin` was never called (`underNoSkin`): no skin's bones
+     * or constraints applied, every slot resolved through the default skin.
+     */
+    skin?: string;
+    /** The per-pose adjustment of bone locals (`player.adjust`), set from the first pose. */
+    adjust?: BoneAdjust | null;
+    /** Which slots this player draws (`player.slots`); every slot when absent. */
+    slots?: SlotFilter | null;
+    /** How the player draws (see `RenderMode`). Default `'dom'`. Can be changed later through `mode`. */
+    mode?: RenderMode;
+    /** The mesh tier's rasterizer (see `DomRenderer.meshBackend`) — the DOM mode only. */
+    meshBackend?: MeshBackend;
+    /**
+     * The step `seek` walks the track forward with, in seconds. A seek is
+     * "reopen, then step to the time", never a jump: a physics rig has history,
+     * and the pose at a time depends on the steps taken to reach it.
+     */
+    seekStep?: number;
+    /**
+     * Stand the player on rig-c's live tracks from the first `play`, so the
+     * first composing call — a mix, another track, a queue, a clear — never
+     * replays. Without it a plain `play` runs on the single live track, and the
+     * first composing call carries it over by replaying the time played in
+     * `seekStep` increments (there is no hand-over of a live track's physics
+     * state in the core), which on a stage that idled a while is one long
+     * frame. Pick the single track for a rig whose animations key what the
+     * tracks do not mix (constraints, sequences, the draw order, a path's
+     * deform); pick the tracks for layering.
+     */
+    tracks?: boolean;
+}
+/** What `on('event', …)` hands a listener: one event key the step crossed. */
+export interface RigEvent {
+    name: string;
+    /** The key's time in the animation. */
+    time: number;
+    int: number;
+    float: number;
+    string: string | null;
+    /**
+     * The track whose current entry fired it. The core's pose lists a step's
+     * events in track order without naming the track, so the player attributes
+     * them by counting what each track's current entry fires over the step;
+     * when that count does not match the pose (an entry replaced inside the
+     * step), the step's events carry no track rather than a guessed one.
+     */
+    track?: number;
+}
+/** What `on('complete', …)` hands a listener: the entry that completed, and its track. */
+export interface RigComplete {
+    animation: string;
+    track: number;
+}
+/** How `play` starts an entry, and `queue` queues one. */
+export interface PlayOptions {
+    /** Loop; true by default. */
+    loop?: boolean;
+    /** The track; 0 by default. A base on 0, a layer over it on 1, a one-shot on 2. */
+    track?: number;
+    /** Seconds the entry this one replaces mixes out over; 0 (the default) cuts. */
+    mix?: number;
+    /**
+     * The entry's weight, from 0 to 1 (1 by default), multiplied into every
+     * timeline it applies — the same clip at 0.6 and at 0.85. Change it while
+     * the entry plays with `setAlpha`. It does not touch events (fired at any
+     * alpha, 0 included) or attachments (kept at any alpha).
+     */
+    alpha?: number;
+    /**
+     * The entry adds its keyed bone and deform values to what the tracks below
+     * posed, rather than replacing them — a layer keying the same bone channels
+     * as the base without covering its motion (false by default). Fixed when the
+     * entry is set or queued. A rotation is added as it stands, with no
+     * shortest-angle wrap; mixing out, an additive entry fades with its alpha
+     * and is never held.
+     */
+    additive?: boolean;
+}
+export interface QueueOptions extends PlayOptions {
+    /**
+     * At or below 0 (the default 0): the entry starts when the one before it
+     * completes, less this entry's `mix` — a one-shot then mixes into the next
+     * over its last `mix` seconds. Above 0: that many seconds after the entry
+     * before it starts.
+     */
+    delay?: number;
+}
+/** A track's current entry as the player reads it (`entry(track)`). */
+export interface TrackEntry {
+    /** What it plays; null for the empty animation a `clear` left. */
+    animation: string | null;
+    loop: boolean;
+    /** The entry's own track time, from its start. */
+    trackTime: number;
+    /** The animation time it applies at now: the track time wrapped, or held at the duration. */
+    animationTime: number;
+    duration: number;
+    /** The entry's weight as it stands (`PlayOptions.alpha`, `setAlpha`). */
+    alpha: number;
+    /** Whether the entry adds (`PlayOptions.additive`). */
+    additive: boolean;
+}
+type Listener<T> = (payload: T) => void;
+/**
+ * One rig on one root.
+ *
+ * ```ts
+ * const player = new RigPlayer(root, assets);
+ * player.play('walk');
+ * requestAnimationFrame(function tick(now) { player.frame(dt); requestAnimationFrame(tick); });
+ * ```
+ */
+/**
+ * One bone's local values at a pose, read and written in place: the seven
+ * channels the runtime's bone has, in its units (degrees, world-unit
+ * translation, scale factors, shear in degrees). What `BoneAdjust` receives
+ * through `AdjustableBones.bone`.
+ */
+export interface BoneLocals {
+    rotation: number;
+    x: number;
+    y: number;
+    scaleX: number;
+    scaleY: number;
+    shearX: number;
+    shearY: number;
+}
+/** The bones of one pose, by name, as a `BoneAdjust` sees them. */
+export interface AdjustableBones {
+    /** The document's bones, in its order. */
+    readonly names: readonly string[];
+    /** One bone's locals, read and written in place; a name the document has no bone for is refused by name. */
+    bone(name: string): BoneLocals;
+}
+/**
+ * A caller's adjustment of a pose's bone locals — a breath's scale, a look's
+ * rotation, a mouth's `scaleY` — called once per pose after the animation's
+ * timelines and before the world transforms, constraints and physics (the
+ * core's `openTrack({ adjust })`, held to the Spine runtime at tolerance 0
+ * by rig-c). **A write lasts one pose**: the core poses every step from the
+ * setup pose, so a value the caller wants held is written again each pose,
+ * and nothing compounds. A non-finite value, an unknown bone, or an error the
+ * function throws refuses that step in the core's words.
+ */
+export type BoneAdjust = (bones: AdjustableBones) => void;
+/**
+ * Where a bone is in the pose the player holds — world units, Y up, the
+ * numbers `rig-c/core` posed (`RawBone`): the world matrix `a b c d`, the
+ * world position, the world rotation of each axis in degrees and the world
+ * scale of each, and whether the bone is active under the player's skin.
+ */
+export interface BoneWorld {
+    name: string;
+    active: boolean;
+    x: number;
+    y: number;
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    rotationX: number;
+    rotationY: number;
+    scaleX: number;
+    scaleY: number;
+}
+/**
+ * Which slots a player draws: an allow list of slot names, or a predicate
+ * over the name. The pose is the whole rig's whatever the filter — bones,
+ * constraints, physics, `bone()` and `adjust` are untouched — and only the
+ * draw is filtered. A clipping slot the filter leaves out does not clip.
+ */
+export type SlotFilter = readonly string[] | ((slot: string) => boolean);
+/** A box in world units, Y up: `y` is the bottom edge. */
+export interface PoseBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare class RigPlayer {
+    /**
+     * The renderer this player draws through — its knobs and counters are the
+     * caller's to read and set. A `DomRenderer` in the DOM mode, a
+     * `CanvasRenderer` in the canvas mode; a new object after `mode` changes.
+     */
+    get renderer(): DomRenderer | CanvasRenderer;
+    /** Multiplies every step. 0 holds the pose (nothing is re-posed); negative is refused by the track. */
+    timeScale: number;
+    /** The player's whole-rig colour, r g b a — multiplied into every slot's tint. Not a document value. */
+    color: [number, number, number, number];
+    private active;
+    private readonly root;
+    private readonly assets;
+    private readonly meshBackend;
+    private view;
+    private source;
+    private readonly read;
+    private skinName;
+    private readonly seekStep;
+    /**
+     * The single live track (`openTrack`): what a plain `play` on track 0 runs
+     * on, as every 1.x player did — one animation, every construct the core
+     * poses, `seek` and a skin change by reopening. Null once the player is
+     * composed.
+     */
+    private track;
+    /**
+     * The live tracks (`openTracks`): opened by the first composing call — a
+     * `play` with a mix or on another track, a `queue`, a `clear` — from the
+     * single track's animation stepped to its time. The mixing is the Spine
+     * runtime's, which does not mix a constraint, sequence, draw-order or
+     * path-deform timeline, so such an animation is refused here and plays on
+     * the single track only.
+     */
+    private tracks;
+    /** Track 0's animation and loop as `play` last set them — what `seek` and a skin change reopen. */
+    private animation;
+    private loop;
+    /** One past the highest track touched — how many `current(track)` reads a step takes. */
+    private trackCount;
+    /** `RigPlayerOptions.tracks`: every play opens the live tracks, never the single track. */
+    private readonly trackMode;
+    /** Set once anything beyond a plain play on track 0 happened: a mix, another track, a queue, a clear. `seek` and `skin` then cannot replay and refuse. */
+    private beyondBase;
+    private paused;
+    private pose;
+    private setup;
+    private adjustFn;
+    private slotFilter;
+    /** `slotFilter` as a predicate; every slot when null. */
+    private draws;
+    /** Handed to every track the player opens; reads the current `adjust` so setting it later needs no reopen. */
+    private readonly adjustHook;
+    private readonly listeners;
+    constructor(root: HTMLElement, assets: ModelAssets, options?: RigPlayerOptions);
+    /**
+     * How the player draws. Setting it swaps the renderer without reloading
+     * anything: the old one is disposed (its elements removed, its GPU pages
+     * handed back), the new one is created over the same root and the same
+     * assets, `pixelRatio` and `clipping` carry over, and the pose the player
+     * holds is drawn again at once.
+     */
+    get mode(): RenderMode;
+    set mode(mode: RenderMode);
+    private create;
+    /** What track 0 plays, or null before `play` and after a `clear` of track 0 has mixed out. */
+    get current(): string | null;
+    /** The player's time — the running sum of the steps since `play` (or the last `seek`). */
+    get time(): number;
+    /**
+     * Plays `name` on a track — track 0 by default, which is what `play(name)`
+     * has always meant: the first `play` opens the tracks at their first pose
+     * with the physics reset there, and the pose is drawn on the next `frame`.
+     * Later calls replace what the track plays: the entry it replaces mixes out
+     * over `mix` seconds (0 cuts), and every entry queued on that track is
+     * dropped. The pose the player holds is re-posed at once, so a held player
+     * shows the change on its next `draw`. The mixing is the Spine runtime's,
+     * which rig-c holds at tolerance 0; an animation keying what the tracks do
+     * not mix — a constraint, a sequence, the draw order, a path's deform — is
+     * refused here, by name, in the core's words.
+     */
+    play(name: string, options?: PlayOptions): void;
+    /**
+     * Queues `name` after the last entry on `track` (`QueueOptions`): with
+     * `delay` at or below 0 it starts when that entry completes less its own
+     * `mix`, so a one-shot hands over to it across a mix; on an empty track it
+     * is set. Before any `play`, the tracks are opened for it.
+     */
+    queue(name: string, options?: QueueOptions): void;
+    /**
+     * Mixes `track` out to nothing over `mix` seconds — the layer or one-shot
+     * gone and the tracks below showing through. Track 0 cleared shows the
+     * setup pose. The pose the player holds is re-posed at once.
+     */
+    clear(track?: number, options?: {
+        mix?: number;
+    }): void;
+    /**
+     * Queues a mix out to nothing after the last entry on `track`, over `mix`
+     * seconds; with `delay` 0 (the default) the mix ends as that entry
+     * completes, so a one-shot queued this way plays once and fades out over
+     * its last `mix` seconds.
+     */
+    queueClear(track?: number, options?: {
+        mix?: number;
+        delay?: number;
+    }): void;
+    /**
+     * Sets the weight of `track`'s current entry, from 0 to 1, from the next pose
+     * on — the pose the player holds is re-posed at once, so a held player shows
+     * it on its next `draw`. An entry it is mixing from keeps its own weight. A
+     * track playing nothing, or a weight outside 0..1, is refused in the core's
+     * words. On the single track this composes: the player moves onto the tracks.
+     */
+    setAlpha(track: number, alpha: number): void;
+    /** `track`'s current entry, or null where it plays nothing (and before `play`). */
+    entry(track?: number): TrackEntry | null;
+    /** Whether the player is composed: on the live tracks rather than the single track. */
+    get composed(): boolean;
+    /**
+     * The live tracks, opened by the first composing call (or by the first
+     * `play` under `tracks: true`). A single track in play is carried over by
+     * replay: track 0 set to its animation, pose 0 taken by `start()` (the
+     * player's — nothing steps before it) and the tracks stepped to the single
+     * track's time in `seekStep` increments, so a physics rig's history
+     * restarts there and nothing is fired on the way. The core offers no
+     * hand-over of a live track's state, so that replay costs one pose per
+     * `seekStep` of time played — which `tracks: true` avoids entirely.
+     */
+    private compose;
+    /** Stops stepping; `frame` keeps drawing the pose it holds. */
+    pause(): void;
+    /** Resumes stepping after `pause`. */
+    resume(): void;
+    /**
+     * Moves a single animation on track 0 to `time`: the tracks are reopened
+     * with that animation and stepped forward in `seekStep` increments (the
+     * last one shorter) until the time is reached. Events and completes crossed
+     * on the way are not fired. It has a meaning for one animation on one
+     * track only — the player cannot replay when a mix, a second track or a
+     * queue was asked for — so after any of those it refuses by name; step the
+     * player forward instead.
+     */
+    seek(time: number): void;
+    /** Whatever is open, opened again with track 0's animation as `play` last set it, at pose 0: the single track, or the tracks under `tracks: true`. */
+    private reopen;
+    /** Steps whatever is open forward to `time` in `seekStep` increments, the last one shorter. */
+    private stepTo;
+    /** Adds a listener; returns a function that removes it. */
+    on(type: 'event', listener: Listener<RigEvent>): () => void;
+    on(type: 'complete', listener: Listener<RigComplete>): () => void;
+    /**
+     * Advances the track by `dt × timeScale` seconds and draws the pose —
+     * `advance(dt)` then `draw()`.
+     */
+    frame(dt: number): void;
+    /**
+     * Steps the track by `dt × timeScale` seconds and fires the step's listeners,
+     * without drawing. A paused player, or a step of zero, keeps the pose it
+     * holds without re-posing it, so a held rig costs the renderer's dirty
+     * checks and nothing else.
+     */
+    advance(dt: number): void;
+    /** Draws the pose the player holds. */
+    draw(): void;
+    /**
+     * The skin the rig is posed under — `RigPlayerOptions.skin`, or undefined
+     * for no skin set. Setting it re-resolves the pose under the new skin
+     * (which attachment each slot shows, which bones and constraints are
+     * active) and keeps the animation, its loop and its track time: the track
+     * is reopened under the new skin and stepped to the same time the way
+     * `seek` does, so a physics rig's history restarts there and nothing is
+     * fired on the way. The pose is drawn on the next `draw`/`frame`. An
+     * unknown skin is refused by name, and the player is left as it was.
+     */
+    get skin(): string | undefined;
+    set skin(name: string | undefined);
+    /**
+     * Which slots this player draws (`SlotFilter`), or null for every slot.
+     * Settable on a live player: the next `draw` shows it, and `bounds()` reads
+     * the drawn slots. An allow list naming a slot the document does not have
+     * is refused by name. The pose is the whole rig's: `bone()`, `adjust`, the
+     * events and the tracks see no filter.
+     */
+    get slots(): SlotFilter | null;
+    set slots(filter: SlotFilter | null);
+    /**
+     * The per-pose adjustment of bone locals (`BoneAdjust`), or null for none.
+     * It is applied by every track the player opens — `play`, the reopen inside
+     * `seek` — and by the pose drawn again after `mode` changes, on every pose
+     * the animation is applied to, the first one included. Setting it re-poses
+     * the pose the player holds at once (`repose`), so a held or paused player
+     * shows the change on its next `draw` without a step.
+     */
+    get adjust(): BoneAdjust | null;
+    set adjust(fn: BoneAdjust | null);
+    /**
+     * Poses the held pose again at the same track time, through the current
+     * `adjust`, without stepping, firing or drawing. A paused player and a zero
+     * step re-pose nothing, so a caller whose adjustment reads its own state
+     * (a mouth driven while the body is held) calls this when that state
+     * changed, then `draw`. Nothing before `play`.
+     */
+    repose(): void;
+    /**
+     * Where `name` is in the pose the player holds — the pose of the last
+     * `advance`/`frame`/`seek`, or the setup pose before `play`. Read off the
+     * core's pose, so it is the same in `dom` and `canvas` mode and costs nothing
+     * until called. An unknown bone is refused by name.
+     */
+    bone(name: string): BoneWorld;
+    /**
+     * The box of what the pose the player holds draws, in world units, Y up:
+     * every region's four corners and every mesh's vertices, in the same frame
+     * record the renderer takes (`posedFrame`). A slot under a clip counts only
+     * inside the clip polygon's own box (an inverse clip removes nothing from
+     * the count); bounding boxes, paths and points are not drawn and do not
+     * count. `null` when nothing draws. The same numbers in `dom` and `canvas`
+     * mode; nothing is computed until called.
+     */
+    bounds(): PoseBounds | null;
+    /** The pose the reads above see: the track's, or the setup pose before `play` (posed once). */
+    private posed;
+    /**
+     * The pose the player holds, as the frame record the renderer draws — under
+     * this player's `slots` filter, or under `slots` given here instead (a
+     * second renderer over the same assets drawing this player's pose on
+     * another root: `other.render(player.posedFrame(['hand_f']))`, the one rig
+     * posed once).
+     */
+    posedFrame(slots?: SlotFilter | null): PosedFrame;
+    /** Removes the renderer's elements and hands its GPU pages back. The assets stay the caller's. */
+    dispose(): void;
+    /** The single track's step: its events (track 0) and its complete, as every 1.x player fired them. */
+    private dispatchSingle;
+    /**
+     * The step's events, then its completes, each with its track. The core
+     * fires a track's keys from its current entry (`pose.events`, in track
+     * order and in the runtime's order across a wrap) — an entry mixing out
+     * fires none — and leaves `complete` to the player, which derives it per
+     * track from that track's current entry: on a looping entry, once on a step
+     * whose whole cycles rose; on a held one, on the step that reaches its
+     * duration. An entry replaced inside the step — by `play`, or by a queued
+     * entry starting at its completion less the mix — is no longer current and
+     * completes no more than it fires, which is the runtime's rule too.
+     */
+    private dispatch;
+}
+export {};
+//# sourceMappingURL=player.d.ts.map

package/dist/player.d.ts.map

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