rig-play 1.3.0 → 1.4.0

package/README.md

@@ -338,6 +338,23 @@ calling it twice is a no-op. Load once for the page's lifetime and you can
 ignore it; load and unload repeatedly without it and you leak an atlas per
 cycle.
 
+### Loading for the canvas mode only, and `data:` regions
+
+The region cut makes the rigid tier's bitmaps, which only the DOM mode draws.
+`loadModel({ regions })` says what to do about it:
+
+- `'blob'` (default) — `blob:` URLs the load owns; `assets.dispose()` frees them.
+- `'data'` — `data:` URLs instead, for a content policy or a snapshot that does
+  not carry `blob:`. The same PNG bytes, inline; nothing is minted, so there is
+  nothing to free, and the base64 lives as long as the map does.
+- `'none'` — no cut: the pages load, `assets.regionImages` is empty, and the
+  load is for the canvas mode. A DOM-mode player opened on it — `new RigPlayer`
+  without `mode: 'canvas'`, or `player.mode = 'dom'` — is refused by name, and
+  a refused mode change leaves the player as it was.
+
+`assets.regions` records the choice. `unpackRegions` takes the same thing as
+`{ encoding: 'blob' | 'data' }`.
+
 ### Pages that ship at another resolution
 
 A page image may ship at a resolution its document does not declare — a
@@ -389,7 +406,8 @@ the page's own URL holds premultiplied pixels (see below).
 ### What unloading frees
 
 `revokeRegions()` — and `assets.dispose()`, which calls it — frees the blob URLs
-`unpackRegions` minted, and nothing else. The page images are held by
+`unpackRegions` minted, and nothing else (a `regions: 'data'` or `'none'` load
+minted none, so it frees nothing). The page images are held by
 `assets.pageImages` and by every player drawing from them, so a page is
 released once you drop the assets and every player is disposed. With the
 `webgl` mesh backend the shared blitter also uploads each page image on first
@@ -583,7 +601,7 @@ name, and unloading is still elements first, bitmaps second.
 | holding a pose (the caller stopped advancing) | `player.pause()`, `player.resume()` | `frame` keeps drawing the held pose. |
 | moving to a time (the caller's own, on the spine-core side) | `player.seek(time)`, `RigPlayerOptions.seekStep`, `player.time` | A seek reopens the animation and steps forward in `seekStep` increments (1/60 s by default). Events and completes crossed on the way are not fired. |
 | events (the caller's own listener on the spine-core side) | `player.on('event', listener)`, `player.on('complete', listener)` | `'event'` hands a `RigEvent` (`name`, `time`, `int`, `float`, `string`); `'complete'` hands `{ animation }`. `on` returns a function that removes the listener. |
-| skin (set by the caller on its `Skeleton`) | `RigPlayerOptions.skin` | A constructor option. The names are in `ModelAssets.skins`. Without it the rig is posed with no skin set. |
+| skin (set by the caller on its `Skeleton`) | `RigPlayerOptions.skin`, `player.skin` | A constructor option, and settable on a live player since 1.4.0: the pose re-resolves under the new skin and the track keeps its animation, loop and time (reopened and stepped there, as `seek` does). The names are in `ModelAssets.skins`. Without it the rig is posed with no skin set. |
 | `SpineHtmlRenderer` | `DomRenderer`, reached as `player.renderer` | In `mode: 'dom'`, the default. `mode: 'canvas'` is new and makes `player.renderer` a `CanvasRenderer`. |
 | `new SpineHtmlRenderer(root, regionImages)` | `new DomRenderer(root, regionImages, pages?)` | Only for drawing your own frames; `RigPlayer` constructs its renderer. `pages` is the page-image map the mesh tier samples (`ModelAssets.pageImages`). A hand-built `regionImages` map is still accepted. |
 | `renderer.render(skeleton)` | `renderer.render(frame)` | Takes a `PosedFrame`, not a skeleton. `player.posedFrame()` returns the one the player would draw. |
@@ -618,9 +636,6 @@ export, for which 1.0.0 declares nothing:
   load, several players.
 - **More than one track, mixing between animations, or queueing one after another.**
   `RigPlayer` declares one track; `play` reopens it at the animation's first pose.
-- **Changing the skin after construction.** `skin` is a `RigPlayerOptions` field and
-  `RigPlayer` declares no way to change it later; a second player over the same assets
-  is the declared route.
 - **Changing one slot from code** (its attachment, its colour). `RigPlayer` declares only
   the whole-rig `color`. The frame record is a plain object, so a caller that draws its
   own frames through `DomRenderer.render` or `CanvasRenderer.render` decides what is in

package/dist/DomTexture.d.ts

@@ -90,6 +90,16 @@ export declare function straightAlphaDerivations(): number;
  * happens once it has.
  */
 export declare function straightAlphaSource(page: HTMLImageElement, pma: boolean): PageSource;
+/**
+ * How a cut region's PNG is handed to the `<img>`: a `blob:` URL this module
+ * owns and `revokeRegions` frees (the default), or a `data:` URL that owns
+ * nothing and needs no revoke.
+ */
+export type RegionEncoding = 'blob' | 'data';
+export interface UnpackRegionsOptions {
+    /** `'blob'` by default. */
+    encoding?: RegionEncoding;
+}
 /**
  * Cuts every region of a page layout — a model document's `pages` section —
  * out of its page image into its own bitmap once at load time, restoring 90°
@@ -151,7 +161,7 @@ export declare function straightAlphaSource(page: HTMLImageElement, pma: boolean
  * unpackRegions() with a revokeRegions(); a caller that loads once for the
  * page lifetime can ignore it.
  */
-export declare function unpackRegions(pages: readonly PageLayout[], pageImages: ReadonlyMap<string, HTMLImageElement>): Promise<Map<string, RegionImage>>;
+export declare function unpackRegions(pages: readonly PageLayout[], pageImages: ReadonlyMap<string, HTMLImageElement>, options?: UnpackRegionsOptions): Promise<Map<string, RegionImage>>;
 /**
  * Frees the blob URLs unpackRegions minted for `images` — the counterpart of
  * unpackRegions, to call once the skeletons using them are gone (after

package/dist/DomTexture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DomTexture.d.ts","sourceRoot":"","sources":["../src/DomTexture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;CAChC;AAQD,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;OASG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;CAChB;AAkBD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAqC9D;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,EAAE,OAAO,GAAG,UAAU,CAcpF;AAgSD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAChD,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CA0EnC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,IAAI,CAEpE"}
+{"version":3,"file":"DomTexture.d.ts","sourceRoot":"","sources":["../src/DomTexture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;CAChC;AAQD,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;OASG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;CAChB;AAkBD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAqC9D;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,EAAE,OAAO,GAAG,UAAU,CAcpF;AAuSD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7C,MAAM,WAAW,oBAAoB;IACnC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,EACjD,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CA4EnC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,IAAI,CAEpE"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { type CanvasBackend, CanvasRenderer, type CanvasViewport } from './CanvasRenderer.js';
 export { DomRenderer, type MeshBackend } from './DomRenderer.js';
-export { type PageLayout, type PageRegion, type RegionImage, revokeRegions, unpackRegions } from './DomTexture.js';
-export { type LoadModelOptions, loadModel, type ModelAssets, type ModelDocument } from './loadModel.js';
+export { type PageLayout, type PageRegion, type RegionEncoding, type RegionImage, revokeRegions, type UnpackRegionsOptions, unpackRegions } from './DomTexture.js';
+export { type LoadModelOptions, loadModel, type ModelAssets, type ModelDocument, type RegionLoading } from './loadModel.js';
 export { type AdjustableBones, type BoneAdjust, type BoneLocals, type BoneWorld, type PoseBounds, type RenderMode, type RigEvent, RigPlayer, type RigPlayerOptions } from './player.js';
 export type { BlendMode, PosedClip, PosedFrame, PosedMesh, PosedRegion, PosedSlot, } from './posedFrame.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnH,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACxG,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACxL,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnK,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5H,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACxL,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -5236,7 +5236,7 @@ function cutBackingPixels(placed, pageImages) {
   const plan = planCut(placed, image);
   return plan.cw * plan.ch;
 }
-async function cutRegion(placed, pageImages) {
+async function cutRegion(placed, pageImages, encoding) {
   const { region, page } = placed;
   const image = pageImages.get(page.name);
   if (!image) throw new Error(`Missing page image: ${page.name}`);
@@ -5255,6 +5255,7 @@ async function cutRegion(placed, pageImages) {
   }
   const source = straightAlphaSource(image, page.pma === true);
   ctx.drawImage(source, plan.sx, plan.sy, plan.sw, plan.sh, 0, 0, plan.sw, plan.sh);
+  if (encoding === "data") return { url: canvas.toDataURL("image/png"), width: w, height: h };
   const blob = await new Promise((resolve, reject) => {
     canvas.toBlob((b) => b ? resolve(b) : reject(new Error("toBlob failed")), "image/png");
   });
@@ -5262,7 +5263,9 @@ async function cutRegion(placed, pageImages) {
   ownedUrls.add(url);
   return { url, width: w, height: h };
 }
-async function unpackRegions(pages, pageImages) {
+async function unpackRegions(pages, pageImages, options = {}) {
+  const encoding = options.encoding ?? "blob";
+  if (encoding !== "blob" && encoding !== "data") throw new Error(`encoding must be 'blob' or 'data', got ${String(options.encoding)}`);
   const regions = pages.flatMap((page) => page.regions.map((region) => ({ region, page })));
   const cuts = new Array(regions.length);
   let failedIndex = -1;
@@ -5283,7 +5286,7 @@ async function unpackRegions(pages, pageImages) {
     const job = { done: false, promise: Promise.resolve() };
     job.promise = (async () => {
       try {
-        cuts[index] = await cutRegion(region, pageImages);
+        cuts[index] = await cutRegion(region, pageImages, encoding);
       } catch (error) {
         if (failedIndex === -1 || index < failedIndex) {
           failedIndex = index;
@@ -7128,6 +7131,10 @@ async function loadModel(options) {
       `${modelUrl} is a Spine export; this player reads a compiled model document (${CORE_DOCUMENT_SPECS[0]}, skeleton.model.json) — build it with \`rigc build\``
     );
   }
+  const regions = options.regions ?? "blob";
+  if (regions !== "blob" && regions !== "data" && regions !== "none") {
+    throw new Error(`regions must be 'blob', 'data' or 'none', got ${String(options.regions)}`);
+  }
   const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
   const resolvePage = options.resolvePage ?? resolveAgainstModel;
   const read = readModelText(await fetchText(fetchImpl, modelUrl), modelUrl);
@@ -7138,13 +7145,14 @@ async function loadModel(options) {
       pageImages.set(page.name, await loadImage(resolvePage(page.name, modelUrl), crossOrigin));
     })
   );
-  const regionImages = await unpackRegions(pages, pageImages);
+  const regionImages = regions === "none" ? /* @__PURE__ */ new Map() : await unpackRegions(pages, pageImages, { encoding: regions });
   let disposed = false;
   return {
     spec: read.spec,
     animations: read.doc.animations.map((a) => ({ name: a.name, duration: a.timelines.duration })),
     skins: read.doc.skins.map((s) => s.name),
     stage: stageOf(read.doc),
+    regions,
     regionImages,
     pageImages,
     document: read,
@@ -7311,6 +7319,8 @@ class RigPlayer {
   meshBackend;
   view;
   source;
+  read;
+  skinName;
   seekStep;
   track = null;
   animation = null;
@@ -7329,6 +7339,8 @@ class RigPlayer {
   };
   constructor(root, assets, options = {}) {
     const read = assets.document;
+    this.read = read;
+    this.skinName = options.skin;
     this.view = options.skin === void 0 ? underNoSkin(read.doc) : underSkin(read.doc, options.skin);
     this.source = frameSource(this.view, read.parsed);
     this.seekStep = options.seekStep ?? 1 / 60;
@@ -7367,6 +7379,11 @@ class RigPlayer {
       return renderer2;
     }
     if (mode !== "dom") throw new Error(`mode must be 'dom' or 'canvas', got ${String(mode)}`);
+    if (this.assets.regions === "none") {
+      throw new Error(
+        "these assets were loaded with regions: 'none' (no region bitmaps, for the canvas mode only); the DOM mode needs a load with regions 'blob' or 'data'"
+      );
+    }
     const renderer = new DomRenderer(this.root, this.assets.regionImages, this.assets.pageImages);
     if (this.meshBackend) renderer.meshBackend = this.meshBackend;
     return renderer;
@@ -7406,6 +7423,10 @@ class RigPlayer {
     if (this.animation === null) throw new Error("seek before play: no animation is open");
     if (!(time >= 0) || !Number.isFinite(time)) throw new Error(`seek time must be a finite time at or above 0, got ${String(time)}`);
     this.open();
+    this.stepTo(time);
+  }
+  /** Steps the freshly opened track forward to `time` in `seekStep` increments, the last one shorter. */
+  stepTo(time) {
     const track = this.track;
     const steps = Math.floor(time / this.seekStep);
     for (let i = 0; i < steps; i++) this.pose = track.step(this.seekStep);
@@ -7445,6 +7466,32 @@ class RigPlayer {
     if (this.pose === null) return;
     this.renderer.render(this.posedFrame());
   }
+  /**
+   * 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() {
+    return this.skinName;
+  }
+  set skin(name) {
+    if (name === this.skinName) return;
+    const view = name === void 0 ? underNoSkin(this.read.doc) : underSkin(this.read.doc, name);
+    this.view = view;
+    this.source = frameSource(view, this.read.parsed);
+    this.skinName = name;
+    this.setup = null;
+    if (this.animation !== null && this.track !== null) {
+      const time = this.track.trackTime;
+      this.open();
+      this.stepTo(time);
+    }
+  }
   /**
    * 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