spine-html 0.4.1 → 0.5.1

package/NOTICE.md

@@ -14,6 +14,7 @@ redistribution includes the Spine Runtimes license and copyright notice.
 
 ## Example assets
 
-The spineboy skeleton, atlas, and images used by the demo are owned by Esoteric
-Software. They are **not redistributed** in this repository; `scripts/fetch-assets.sh`
-downloads them from the official spine-runtimes repository for local evaluation.
+The spineboy skeleton exports (JSON and binary), atlas, and images used by the demo
+and the tests are owned by Esoteric Software. They are **not redistributed** in this
+repository; `scripts/fetch-assets.sh` downloads them from the official spine-runtimes
+repository for local evaluation.

package/README.md

@@ -148,12 +148,78 @@ assets.dispose();
 `spine-html` is a third-party renderer and is not affiliated with or endorsed by
 Esoteric Software.
 
+### One atlas, several skeletons
+
+Skeletons that share an atlas — a character's `-ess` and `-pro` exports, a whole
+cast packed onto one page — load in two steps instead. Calling
+`loadSkeletonAssets` once per skeleton would fetch and unpack the same pages
+again and mint a second set of region blob URLs:
+
+```ts
+import { loadAtlasAssets, loadSkeletonJson, SpineHtmlRenderer } from 'spine-html';
+
+const shared = await loadAtlasAssets({ atlasUrl: '/spineboy/spineboy.atlas' });
+const [essData, proData] = await Promise.all([
+  loadSkeletonJson(shared, '/spineboy/spineboy-ess.json'),
+  loadSkeletonJson(shared, '/spineboy/spineboy-pro.json'),
+]);
+
+const ess = new SpineHtmlRenderer(essRoot, shared.regionImages);
+const pro = new SpineHtmlRenderer(proRoot, shared.regionImages);
+
+// Unloading: every renderer first, then the one dispose() that owns the bitmaps.
+ess.dispose();
+pro.dispose();
+shared.dispose();
+```
+
+`loadAtlasAssets` takes the atlas half of the options above (`resolvePage`,
+`crossOrigin`, `fetch`) and `loadSkeletonJson` the skeleton half (`scale`,
+`fetch`). Ownership is the thing to keep straight: the atlas assets belong to
+the caller, reading a skeleton against them never frees them, and one
+`regionImages` map is meant to be handed to several renderers — so there is
+exactly one `dispose()` for however many skeletons were read. `loadSkeletonJson`
+asks only for `{ atlas }`, so a caller that built its atlas by hand (below) can
+still use it for the read. `loadSkeletonAssets` is these two calls with the
+atlas half kept private: use it for one atlas and one skeleton, this for the
+rest.
+
+### Binary exports (`.skel`)
+
+Binary exports are read by a second parser, `SkeletonBinary`, which is as big as
+the JSON one. It lives behind its own entry point so that consumers who only
+ever read `.json` never carry it:
+
+```ts
+import { loadAtlasAssets, SpineHtmlRenderer } from 'spine-html';
+import { loadSkeletonBinary } from 'spine-html/binary';
+
+const shared = await loadAtlasAssets({ atlasUrl: '/spineboy/spineboy.atlas' });
+const data = await loadSkeletonBinary(shared, '/spineboy/spineboy-pro.skel');
+
+const renderer = new SpineHtmlRenderer(rootElement, shared.regionImages);
+// Unloading, as above: renderer.dispose(); shared.dispose();
+```
+
+`loadSkeletonBinary` is `loadSkeletonJson` with the parser swapped: same
+arguments, the same `{ scale, fetch }` options, the same ownership rule — it
+never frees `assets`, whichever way it ends. Those two calls are the binary path
+in full. There is no one-call `loadSkeletonAssetsBinary`, because the atlas half
+is precisely what a caller reading binary usually wants kept in hand, and hiding
+it again would only earn back a line.
+
+The subpath is the whole mechanism, so import it as written: pulling
+`loadSkeletonBinary` out of `'spine-html'` is not possible, by design. Worth
+knowing about the format itself: binary exports are version-locked to the
+runtime that reads them, so a `.skel` written by an editor newer than your
+installed `@esotericsoftware/spine-core` fails in the read, not in the fetch.
+
 ### Loading it yourself
 
 `loadSkeletonAssets` is optional sugar over five `spine-core` calls, and the
 package works without it. Drop to the low-level path whenever you need
-something it does not do — one atlas shared by several skeletons, a binary
-export, images that are already in memory:
+something no loader does — images that are already in memory, an atlas that is
+not fetched from a URL at all:
 
 ```ts
 import { TextureAtlas, AtlasAttachmentLoader, SkeletonJson }
@@ -181,6 +247,35 @@ it — and calling it twice is a no-op. Load once for the page's lifetime and yo
 can ignore it; load and unload repeatedly without it and you leak an atlas per
 cycle.
 
+### What unloading frees
+
+`revokeRegions()` — and `assets.dispose()`, which just calls it — frees the blob
+URLs `unpackRegions` minted, and nothing else. The rest is pinned by objects you
+own: an atlas **page image** is held by the `DomTexture` you attached to its
+page, and `SkeletonData` reaches that same image through every attachment
+(`region.texture.getImage()`), so a page is released only once the atlas, the
+skeleton data and every renderer drawing from them are gone. `atlas.dispose()`
+does not do it — `DomTexture.dispose()` is a no-op, because the image is yours.
+With the `webgl` mesh backend the shared blitter also uploads each page image on
+first use, but that GL texture is not the module's forever: every renderer
+drawing the page holds a reference to it, `renderer.dispose()` hands those back,
+and the texture is deleted once the last renderer using that page is disposed —
+a later frame that needs the page uploads it again. The cache is keyed weakly by
+the page image, so a renderer dropped without `dispose()` costs GPU memory until
+the context is lost, but never keeps the image itself alive.
+
+A meshed skeleton samples the page bitmap every frame, so its decoded form stays
+in use: a floor on the order of `page width × page height × 4` bytes per page —
+1 MiB for spineboy's single 1024×256 page. A rigid-only skeleton draws nothing
+from the page after `unpackRegions`, and what a merely reachable, undrawn image
+costs is up to the browser, not measurable from script.
+
+Unload in this order:
+
+1. `renderer.dispose()`, for every renderer using the images.
+2. `revokeRegions(regionImages)` (or `assets.dispose()`).
+3. Drop your references to the atlas and the skeleton data.
+
 ### One part per page (loose part PNGs)
 
 Not every pipeline runs the Spine editor's texture packer. If your parts are
@@ -227,10 +322,28 @@ const renderer = new SpineHtmlRenderer(rootElement, regionImages);
   raster matches the screen: `devicePixelRatio * rootScale`). **Writing it
   reallocates every mesh canvas backing store on the next frame**, and each
   reallocation recreates a GPU surface — the cost that took real Safari to ~3 fps
-  when it happened per frame. Set it when a layout settles, never per frame:
+  when it happened per frame. Each canvas is then sized from what the new ratio
+  needs, in both directions: lowering the ratio gives the backing pixels back
+  (the backing is grow-only *within* a ratio, not across a change of one). Set
+  it when a layout settles, never per frame:
   debounce resize drags and quantize the value instead of tracking it
   continuously. `renderer.canvasReallocCount` is the check — it must fall back to
   zero within a second or two.
+- `renderer.syncPixelRatio()` — measures the root's effective on-screen scale
+  and sets `pixelRatio` to `devicePixelRatio × scale`, returning the ratio now
+  in effect. It appends a hidden 100 px box to the root, reads its box once and
+  removes it (the root itself is usually 0×0), so it is **one forced layout per
+  call** — which is exactly why the renderer never calls it for you: there is no
+  per-frame layout read anywhere in this library. Call it when a zoom or a
+  layout *settles* (gesture end, debounced resize), not during the drag. A
+  change under 0.1% is ignored, so layout jitter cannot churn GPU surfaces, and
+  a root that is not laid out (a `display: none` ancestor) leaves the ratio
+  alone. Under an ancestor rotation the measured box is inflated and the ratio
+  errs high — oversampling costs pixels, undersampling costs picture.
+- `renderer.meshBackingPixels` — allocated mesh-canvas backing pixels
+  (Σ width × height), computed on demand. This is what `pixelRatio` moves
+  quadratically, and the cheapest way to see an oversampling stage; the demo
+  prints it in the stats line as `backing N Mpx`.
 - `renderer.meshBackend` — `'canvas2d'` (default) or `'webgl'`; same output, but
   heavy deforming scenes on Safari want `'webgl'` (see Measured above). Falls back
   to canvas2d automatically when WebGL is unavailable. Switching re-rasters every
@@ -238,6 +351,22 @@ const renderer = new SpineHtmlRenderer(rootElement, regionImages);
 - `renderer.triangleExpand` — clip overdraw in px that closes antialiased mesh
   seams (default 0.5). Also re-rasters every mesh once when changed.
 
+**A zoomable stage.** The mesh tier rasters at `world × pixelRatio` in the
+root's own coordinates, and it cannot see a CSS transform above the root — so
+the most natural pan/zoom stage, `transform: scale(zoom)` on an ancestor, makes
+it oversample by `1/zoom²` in backing pixels until the zoom is folded in. The
+picture stays correct throughout, which is what makes this easy to ship: only
+the allocation and the frame rate move. Call `syncPixelRatio()` when the zoom
+settles, or set `pixelRatio = devicePixelRatio * zoom` yourself. Measured
+on-device (Chromium, dpr 2, stage under `scale(0.25)`, ~2.2 M CSS px on screen):
+
+| scene | `pixelRatio` | `meshBackingPixels` | fps |
+| --- | --- | --- | --- |
+| 57 meshes | `devicePixelRatio` (2) | 139.1 Mpx | 14–21 |
+| 57 meshes | `dpr × zoom` (0.5) | 9.1 Mpx | 61 |
+| 92 meshes | `devicePixelRatio` (2) | 141.1 Mpx | 36–39 |
+| 92 meshes | `dpr × zoom` (0.5) | 9.1 Mpx | 60–61 |
+
 ## Demo (this repository)
 
 ```bash
@@ -282,6 +411,15 @@ resolving, so blob ownership — every unpacked URL freed, nothing the caller
 owns touched, nothing stranded by a failed load — is asserted rather than
 assumed.
 
+The server is part of the test: a run tests whatever is being served on its
+port. Two checkouts of this repository on one machine (a worktree, a second
+clone) default to the same port 4321 and reuse an existing server, so the
+second run quietly tests the first one's build — green, and about the wrong
+tree. Give each concurrent checkout its own port with `TEST_PORT`
+(`TEST_PORT=4333 bun run test`); setting it also disables server reuse, so a
+busy port fails the run instead of being borrowed. Unset, nothing changes:
+port 4321, reuse unless `CI`.
+
 Standing rule: **headless numbers are never Safari performance evidence** —
 nothing in the suite asserts timing, and headless-WebKit fps/ms readings do
 not transfer (software rasterizer, measured up to 28× off real Safari). The

package/dist/DomTexture.d.ts

@@ -30,14 +30,37 @@ export interface RegionImage {
  * rendering is pure DOM (one <img> per slot, one CSS matrix write per frame).
  *
  * A region that covers its whole page unrotated skips the cut and reuses the
- * page image URL — see the pass-through below.
+ * page image URL — see the pass-through in cutRegion.
+ *
+ * **The cuts run concurrently.** PNG encoding is asynchronous and the browser
+ * does it off the main thread, so the encodes are started together and awaited
+ * together instead of one `toBlob` per iteration: awaited in series a load
+ * costs the *sum* of every encode, which a throttled document turns into one
+ * full throttle period per region (measured: a single 8×8 `toBlob` took 7.5 s
+ * to call back in a hidden desktop Chromium pane). How many run at once is
+ * bounded by CUT_BACKING_BUDGET_PX above, not by an option.
+ *
+ * Concurrency changes nothing a caller can observe:
+ *
+ * - **Order.** The returned map is keyed in `atlas.regions` order whatever
+ *   order the blobs arrive in — the map is built after the cuts settle, from
+ *   the region list, not from the arrivals.
+ * - **Duplicate names.** The last region of a given name in atlas order wins,
+ *   and the shadowed URL is revoked (and dropped from the ledger) rather than
+ *   stranded.
+ * - **Failure.** Every URL this call minted is revoked before the error
+ *   propagates, *including cuts that were still in flight when the first
+ *   failure happened* — their blobs arrive later, and a load that walked away
+ *   from them would mint owned URLs nobody could ever revoke. So a failure
+ *   stops new cuts from starting but still waits for the started ones, and the
+ *   error it raises is the one from the earliest region in atlas order (what
+ *   the serial loop used to throw). Nothing here rejects unobserved.
  *
  * The blob URLs stay alive until revokeRegions() frees them — a document-wide
  * allocation the GC cannot reclaim on its own. Callers that load and unload
  * skeletons repeatedly (cutscenes, level transitions) must pair every
  * unpackRegions() with a revokeRegions(); a caller that loads once for the
- * page lifetime can ignore it. If this function throws part-way through,
- * everything it already minted is revoked before the error propagates.
+ * page lifetime can ignore it.
  */
 export declare function unpackRegions(atlas: TextureAtlas, pageImages: Map<string, HTMLImageElement>): Promise<Map<string, RegionImage>>;
 /**

package/dist/DomTexture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DomTexture.d.ts","sourceRoot":"","sources":["../src/DomTexture.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,YAAY,EAEZ,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AAEtC;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,OAAO;IACrC,UAAU,CAAC,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,aAAa,GAAG,IAAI;IACtE,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;IACxD,OAAO,IAAI,IAAI;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;CAChB;AAkBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,GACxC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAqEnC;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,OAAO,EACL,OAAO,EACP,YAAY,EAEZ,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AAEtC;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,OAAO;IACrC,UAAU,CAAC,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,aAAa,GAAG,IAAI;IACtE,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;IACxD,OAAO,IAAI,IAAI;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;CAChB;AAsGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,GACxC,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"}

package/dist/DomTexture.js

@@ -24,6 +24,81 @@ function revokeOwned(url) {
         return;
     URL.revokeObjectURL(url);
 }
+/**
+ * Backing pixels the cuts still waiting for their PNG encode may hold at once.
+ *
+ * A started cut keeps its canvas alive until `toBlob` calls back, so starting
+ * every region at once peaks at Σ(region area) of canvas backing — on top of
+ * the decoded pages, which stay resident throughout. Measured by counting the
+ * simultaneously-alive cut canvases and their backing at `toBlob` (chromium):
+ * the demo's 40-region 1024×256 atlas peaks at all 40 cuts and 194,742 px
+ * (0.19 Mpx ≈ 0.74 MiB), which is nothing; a synthetic 256-region atlas on
+ * four 2048×2048 pages peaks at 16.78 Mpx ≈ 64 MiB, which doubles that
+ * atlas's resident cost for the length of the load.
+ *
+ * So the cuts are started against a budget rather than all at once. 4 Mpx is
+ * one 2048×2048 page's worth (≈ 16 MiB at 4 bytes/px): small atlases still run
+ * every region concurrently (spineboy: all 40, budget never engaged), and the
+ * synthetic one runs 64 cuts at a time — 4 waves instead of 256 serial
+ * encodes, for a quarter of the peak. A single region bigger than the budget
+ * is started anyway when nothing else is in flight, so the budget can never
+ * starve a cut.
+ */
+const CUT_BACKING_BUDGET_PX = 4 * 1024 * 1024;
+/**
+ * One region's bitmap: the whole-page pass-through, or a cut canvas encoded to
+ * a blob URL this module then owns.
+ *
+ * Everything before the `toBlob` await runs synchronously, so calling this is
+ * what "starts" a cut: the canvas is painted and the encode is handed to the
+ * browser before control comes back.
+ */
+async function cutRegion(region, pageImages) {
+    const image = pageImages.get(region.page.name);
+    if (!image)
+        throw new Error(`Missing page image: ${region.page.name}`);
+    const w = region.width;
+    const h = region.height;
+    // Whole-page pass-through: an unrotated region covering its entire page
+    // would be cut into a pixel-for-pixel copy of the page image, so reuse
+    // the page URL instead — no canvas, no PNG re-encode, no second decoded
+    // copy in memory, and nothing to revoke afterwards. Atlases written as
+    // one part per page (the loose-part-PNG workflow, where every part is
+    // declared its own page) hit this for every single region.
+    //
+    // The test is against the image, not the atlas `size:` line: a page
+    // declared at the wrong size still goes through the cut, since the cut
+    // is what the region's coordinates actually describe.
+    if (region.degrees === 0 &&
+        region.x === 0 &&
+        region.y === 0 &&
+        w === image.naturalWidth &&
+        h === image.naturalHeight) {
+        return { url: image.src, width: w, height: h };
+    }
+    const canvas = document.createElement('canvas');
+    canvas.width = w;
+    canvas.height = h;
+    const ctx = canvas.getContext('2d');
+    if (!ctx)
+        throw new Error('2d context unavailable');
+    if (region.degrees === 90) {
+        // The region is packed rotated: it occupies an h×w rect in the page.
+        // Rotate it back so the bitmap is in artwork orientation.
+        ctx.translate(0, h);
+        ctx.rotate(-Math.PI / 2);
+        ctx.drawImage(image, region.x, region.y, h, w, 0, 0, h, w);
+    }
+    else {
+        ctx.drawImage(image, region.x, region.y, w, h, 0, 0, w, h);
+    }
+    const blob = await new Promise((resolve, reject) => {
+        canvas.toBlob((b) => (b ? resolve(b) : reject(new Error('toBlob failed'))), 'image/png');
+    });
+    const url = URL.createObjectURL(blob);
+    ownedUrls.add(url);
+    return { url, width: w, height: h };
+}
 /**
  * Cuts every atlas region out of the page image into its own bitmap once at
  * load time, restoring 90° packing rotation, so the per-frame path never
@@ -33,78 +108,106 @@ function revokeOwned(url) {
  * rendering is pure DOM (one <img> per slot, one CSS matrix write per frame).
  *
  * A region that covers its whole page unrotated skips the cut and reuses the
- * page image URL — see the pass-through below.
+ * page image URL — see the pass-through in cutRegion.
+ *
+ * **The cuts run concurrently.** PNG encoding is asynchronous and the browser
+ * does it off the main thread, so the encodes are started together and awaited
+ * together instead of one `toBlob` per iteration: awaited in series a load
+ * costs the *sum* of every encode, which a throttled document turns into one
+ * full throttle period per region (measured: a single 8×8 `toBlob` took 7.5 s
+ * to call back in a hidden desktop Chromium pane). How many run at once is
+ * bounded by CUT_BACKING_BUDGET_PX above, not by an option.
+ *
+ * Concurrency changes nothing a caller can observe:
+ *
+ * - **Order.** The returned map is keyed in `atlas.regions` order whatever
+ *   order the blobs arrive in — the map is built after the cuts settle, from
+ *   the region list, not from the arrivals.
+ * - **Duplicate names.** The last region of a given name in atlas order wins,
+ *   and the shadowed URL is revoked (and dropped from the ledger) rather than
+ *   stranded.
+ * - **Failure.** Every URL this call minted is revoked before the error
+ *   propagates, *including cuts that were still in flight when the first
+ *   failure happened* — their blobs arrive later, and a load that walked away
+ *   from them would mint owned URLs nobody could ever revoke. So a failure
+ *   stops new cuts from starting but still waits for the started ones, and the
+ *   error it raises is the one from the earliest region in atlas order (what
+ *   the serial loop used to throw). Nothing here rejects unobserved.
  *
  * The blob URLs stay alive until revokeRegions() frees them — a document-wide
  * allocation the GC cannot reclaim on its own. Callers that load and unload
  * skeletons repeatedly (cutscenes, level transitions) must pair every
  * unpackRegions() with a revokeRegions(); a caller that loads once for the
- * page lifetime can ignore it. If this function throws part-way through,
- * everything it already minted is revoked before the error propagates.
+ * page lifetime can ignore it.
  */
 export async function unpackRegions(atlas, pageImages) {
-    const result = new Map();
-    // Duplicate region names would otherwise strand the shadowed URL in the
-    // ledger with nothing left pointing at it.
-    const put = (name, entry) => {
-        const shadowed = result.get(name);
-        if (shadowed)
-            revokeOwned(shadowed.url);
-        result.set(name, entry);
-    };
-    try {
-        for (const region of atlas.regions) {
-            const atlasRegion = region;
-            const image = pageImages.get(atlasRegion.page.name);
-            if (!image)
-                throw new Error(`Missing page image: ${atlasRegion.page.name}`);
-            const w = region.width;
-            const h = region.height;
-            // Whole-page pass-through: an unrotated region covering its entire page
-            // would be cut into a pixel-for-pixel copy of the page image, so reuse
-            // the page URL instead — no canvas, no PNG re-encode, no second decoded
-            // copy in memory, and nothing to revoke afterwards. Atlases written as
-            // one part per page (the loose-part-PNG workflow, where every part is
-            // declared its own page) hit this for every single region.
-            //
-            // The test is against the image, not the atlas `size:` line: a page
-            // declared at the wrong size still goes through the cut, since the cut
-            // is what the region's coordinates actually describe.
-            if (region.degrees === 0 &&
-                atlasRegion.x === 0 &&
-                atlasRegion.y === 0 &&
-                w === image.naturalWidth &&
-                h === image.naturalHeight) {
-                put(atlasRegion.name, { url: image.src, width: w, height: h });
-                continue;
+    const regions = atlas.regions;
+    const cuts = new Array(regions.length);
+    // The earliest-in-atlas-order failure is the one that propagates, so that a
+    // broken atlas reports the same region whichever encode happens to land
+    // first.
+    let failedIndex = -1;
+    let failure;
+    let inFlight = [];
+    let inFlightPixels = 0;
+    for (let index = 0; index < regions.length && failedIndex === -1; index++) {
+        const region = regions[index];
+        if (!region)
+            continue;
+        // A pass-through allocates no canvas, but it also resolves without waiting
+        // for anything, so charging it the region's area costs at most one drain.
+        const pixels = region.width * region.height;
+        while (inFlight.length > 0 && inFlightPixels + pixels > CUT_BACKING_BUDGET_PX) {
+            await Promise.race(inFlight.map((job) => job.promise));
+            inFlight = inFlight.filter((job) => !job.done);
+            if (failedIndex !== -1)
+                break;
+        }
+        if (failedIndex !== -1)
+            break;
+        inFlightPixels += pixels;
+        const job = { done: false, promise: Promise.resolve() };
+        // Jobs settle, they never reject: the failure is recorded here so that
+        // nothing is left for an unhandled-rejection handler to find.
+        job.promise = (async () => {
+            try {
+                cuts[index] = await cutRegion(region, pageImages);
             }
-            const canvas = document.createElement('canvas');
-            canvas.width = w;
-            canvas.height = h;
-            const ctx = canvas.getContext('2d');
-            if (!ctx)
-                throw new Error('2d context unavailable');
-            if (region.degrees === 90) {
-                // The region is packed rotated: it occupies an h×w rect in the page.
-                // Rotate it back so the bitmap is in artwork orientation.
-                ctx.translate(0, h);
-                ctx.rotate(-Math.PI / 2);
-                ctx.drawImage(image, atlasRegion.x, atlasRegion.y, h, w, 0, 0, h, w);
+            catch (error) {
+                if (failedIndex === -1 || index < failedIndex) {
+                    failedIndex = index;
+                    failure = error;
+                }
             }
-            else {
-                ctx.drawImage(image, atlasRegion.x, atlasRegion.y, w, h, 0, 0, w, h);
+            finally {
+                inFlightPixels -= pixels;
+                job.done = true;
             }
-            const blob = await new Promise((resolve, reject) => {
-                canvas.toBlob((b) => (b ? resolve(b) : reject(new Error('toBlob failed'))), 'image/png');
-            });
-            const url = URL.createObjectURL(blob);
-            ownedUrls.add(url);
-            put(atlasRegion.name, { url, width: w, height: h });
-        }
+        })();
+        inFlight.push(job);
+    }
+    // Every cut this call started is settled after this, so the cleanup below
+    // reaches the blobs that arrived after the first failure too.
+    await Promise.all(inFlight.map((job) => job.promise));
+    if (failedIndex !== -1) {
+        for (const cut of cuts)
+            if (cut)
+                revokeOwned(cut.url);
+        throw failure;
     }
-    catch (error) {
-        revokeRegions(result);
-        throw error;
+    const result = new Map();
+    for (let index = 0; index < regions.length; index++) {
+        const region = regions[index];
+        const cut = cuts[index];
+        if (!region || !cut)
+            continue;
+        // Duplicate region names would otherwise strand the shadowed URL in the
+        // ledger with nothing left pointing at it. Map.set keeps the key where it
+        // first appeared, so atlas order survives the overwrite.
+        const shadowed = result.get(region.name);
+        if (shadowed)
+            revokeOwned(shadowed.url);
+        result.set(region.name, cut);
     }
     return result;
 }

package/dist/DomTexture.js.map

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

package/dist/MeshGlBlitter.d.ts

@@ -20,6 +20,13 @@
  * preserveDrawingBuffer nor cross-frame content is relied on. The buffer
  * grows quantized and never shrinks, mirroring the per-part backing policy
  * (reallocating GPU surfaces per frame is a Safari killer).
+ *
+ * Page textures are the one thing here with a lifetime, and since this object
+ * outlives every renderer they are reference-counted: a renderer retains each
+ * page it queues a job for and releases them in dispose(), and the last
+ * release deletes the GL texture (a later job re-uploads it). The cache is
+ * keyed weakly by the page image, so a consumer that never disposes still
+ * loses nothing but GPU memory — this object never pins the caller's image.
  */
 export interface MeshBlitJob {
     /** Destination per-part canvas; the blit clears its full backing first. */
@@ -40,10 +47,22 @@ export interface MeshBlitJob {
 }
 declare class MeshGlBlitter {
     lost: boolean;
+    /**
+     * Page textures created minus deleted, i.e. how many uploads are live right
+     * now. Deterministic (no GC in the path), which is what the lifetime tests
+     * assert against — see tests/gl-textures.spec.ts.
+     */
+    liveTextureCount: number;
     private readonly canvas;
     private readonly gl;
     private readonly uResolution;
-    private readonly textures;
+    /**
+     * Weak by the page image on purpose: a consumer that forgets dispose()
+     * leaks its texture until context loss, but dropping the image still lets
+     * the image (and then the WebGLTexture this entry holds) be collected.
+     * Reassigned wholesale on context loss, never iterated.
+     */
+    private textures;
     private readonly maxSize;
     private vertexData;
     /** Per-job packed rect origins, filled by flush(). */
@@ -56,6 +75,29 @@ declare class MeshGlBlitter {
      * cannot fit) so the caller can rasterize the batch on the canvas2d path.
      */
     flush(jobs: MeshBlitJob[]): boolean;
+    /**
+     * Declares one more user of `page`. The upload itself stays lazy (the first
+     * flush that binds the page does it) — this only counts, so that the last
+     * release() can free the texture instead of the module holding it forever.
+     * Callers retain once per page and hand the same page back exactly once;
+     * SpineHtmlRenderer keeps that ledger and settles it in dispose().
+     */
+    retain(page: HTMLImageElement): void;
+    /**
+     * Gives back one retain(). The GL texture goes when the last user of the
+     * page is gone; a later job for the same page simply uploads it again. A
+     * page the cache does not know (a release after a context loss dropped
+     * everything, or a double dispose) is a no-op, so this is safe to call
+     * unconditionally.
+     */
+    release(page: HTMLImageElement): void;
+    /**
+     * Context loss invalidates every texture handle at once. Drop the cache and
+     * the count instead of carrying dead handles (deleting them is pointless —
+     * the GPU side is already gone) and let the next frames re-upload if the
+     * caller keeps drawing; the renderer meanwhile falls back to canvas2d.
+     */
+    private markLost;
     private compile;
     private textureFor;
 }

package/dist/MeshGlBlitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MeshGlBlitter.d.ts","sourceRoot":"","sources":["../src/MeshGlBlitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,MAAM,EAAE,iBAAiB,CAAC;IAC1B,+EAA+E;IAC/E,IAAI,EAAE,gBAAgB,CAAC;IACvB,mFAAmF;IACnF,QAAQ,EAAE,YAAY,CAAC;IACvB,mDAAmD;IACnD,GAAG,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACvB,gDAAgD;IAChD,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAC7B,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AA4BD,cAAM,aAAa;IACjB,IAAI,UAAS;IAEb,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAC3D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAwB;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuB;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6C;IACtE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,UAAU,CAA0B;IAC5C,sDAAsD;IACtD,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,KAAK,CAAgB;;IAoD7B;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,OAAO;IAwGnC,OAAO,CAAC,OAAO;IAYf,OAAO,CAAC,UAAU;CAmBnB;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CASvD"}
+{"version":3,"file":"MeshGlBlitter.d.ts","sourceRoot":"","sources":["../src/MeshGlBlitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,MAAM,EAAE,iBAAiB,CAAC;IAC1B,+EAA+E;IAC/E,IAAI,EAAE,gBAAgB,CAAC;IACvB,mFAAmF;IACnF,QAAQ,EAAE,YAAY,CAAC;IACvB,mDAAmD;IACnD,GAAG,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACvB,gDAAgD;IAChD,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAC7B,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAoCD,cAAM,aAAa;IACjB,IAAI,UAAS;IACb;;;;OAIG;IACH,gBAAgB,SAAK;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAC3D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAwB;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuB;IACnD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAgD;IAChE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,UAAU,CAA0B;IAC5C,sDAAsD;IACtD,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,KAAK,CAAgB;;IAoD7B;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,OAAO;IAwGnC;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI;IAMpC;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI;IAarC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,OAAO;IAYf,OAAO,CAAC,UAAU;CA6BnB;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CASvD"}