spine-html 0.2.0 → 0.4.0

package/README.md

@@ -25,25 +25,49 @@ The idea has been floated on the official forum three times since 2014 and was n
 built — the blockers named were meshes, clipping, and DOM update overhead. This project
 is the experiment: how far does the DOM actually go, and how cheap is it?
 
-Measured so far (PoC, Chromium on Apple silicon):
+Measured so far (PoC, Apple silicon — headless and on-device numbers are labeled,
+they do **not** substitute for each other):
 
-- Rigid only (spineboy-ess): 10 skeletons / 180 slot images at **~0.03 ms skeleton math
-  + ~0.22 ms DOM writes per frame** — about 1.5% of a 60 fps frame budget.
-- With meshes (spineboy-pro): 1 skeleton = **~0.05 ms + ~0.5 ms render** (8 mesh
-  canvases, 323 triangles); 10 running skeletons = **~3.5 ms/frame** total.
-- Dirty-skip: 10 *static* skeletons (pose held) = **~0.4 ms/frame** on both Chromium
-  and WebKit — unchanged meshes reuse their raster, so idle parts cost nothing.
-  The same scene animating costs WebKit ~140 ms/frame (headless), which is the
-  remaining optimization target below.
+- Rigid only (spineboy-ess), headless Chromium: 10 skeletons / 180 slot images at
+  **~0.03 ms skeleton math + ~0.22 ms DOM writes per frame** — about 1.5% of a
+  60 fps frame budget. On-device Safari: 10 rigid skeletons hold **60 fps**.
+- With meshes (spineboy-pro), headless Chromium: 1 skeleton = **~0.05 ms + ~0.5 ms
+  render** (8 mesh canvases, 323 triangles); 10 running skeletons = **~3.5 ms/frame**
+  total, smooth.
+- Dirty-skip: 10 *static* skeletons (pose held) = **~0.4 ms/frame** headless and
+  **~0.6 ms** on-device Safari — unchanged meshes reuse their raster, so idle or
+  held parts cost nothing anywhere.
+- Real Safari (on-device), canvas2d mesh backend: in-callback JS stays **~4–5
+  ms/frame** for 10 running meshed skeletons — but the rAF rate tells the real
+  story: **meshed ×1 = 37 fps, meshed ×10 = 3–4 fps** (rigid-only ×10 = 60 fps).
+  The cost lives outside the frame callback, in the compositor/GPU process:
+  Safari antialiases canvas2d **clip paths**, so every triangle pays for an AA
+  mask. Chromium doesn't antialias clips and stays smooth. This is what the
+  optional WebGL mesh backend (below) removes.
+- Real Safari (on-device), **webgl mesh backend**: meshed ×1 holds **60 fps**
+  (vs 37 on canvas2d), and the meshed ×10 stress scene jumps **3–4 → 45 fps** —
+  80 mesh canvases / 3230 triangles redrawn every frame (0 reused, the worst
+  case), in-callback JS ~5.8 ms at dpr=1. The per-triangle clip-AA tax is gone;
+  the remaining gap to 60 is the blit/compositing cost of a 10-skeleton stress
+  scene, not a per-triangle cost.
+- Headless-WebKit numbers are a **software rasterizer** and measured up to 28×
+  off real Safari in both directions — useful for visual regression only, never
+  as Safari perf evidence.
 
 ## Status
 
-**Proof of concept.**
+**Production.** The questions this started as a PoC to answer — how far does the
+DOM actually go, and how cheap is it — are answered with on-device numbers: the
+practical scenario (a character or two, mostly holding pose, a few parts
+deforming) holds **60 fps on every engine measured**, and the 10-skeleton
+stress scene holds 45 fps on the weakest one (Safari, webgl backend). Ships
+with a self-contained test suite (backend visual parity + invariants) and CI.
 
 - ✅ Region attachments (rigid parts): exact affine mapping, draw-order via `z-index`,
   attachment swaps, alpha
 - ✅ Atlas unpacking at load time (90°-packed regions restored), so the rigid per-frame
-  path never touches a canvas
+  path never touches a canvas — a region that covers its whole page is passed through
+  uncut, and `revokeRegions()` frees the rest when a skeleton is unloaded
 - ✅ Mesh attachments (deform tier): small per-part canvases sized to the mesh's world
   bounds, interleaved with the rigid `<img>` slots in one stacking context — the DOM
   handles the bones, a rasterizer handles the warps
@@ -64,11 +88,25 @@ Measured so far (PoC, Chromium on Apple silicon):
   whole pixels) pay zero raster. 10 frozen spineboys: WebKit ~141 → ~0.5 ms/frame
 - ⬜ Clipping — deliberately unsupported (counted and skipped); layered transparent
   parts + `overflow: hidden` cover the practical cases
-- ⬜ WebKit cost for *continuously deforming* meshes: the per-triangle canvas2d path
-  is ~15× slower than Chromium and the cost is per-triangle, not per-pixel (a 0.4×
-  backing store measures the same as 1×) — an optional WebGL blit backend
-  (one offscreen GL context → `transferToImageBitmap` → per-part `bitmaprenderer`)
-  is the remaining candidate
+- ✅ Safari mesh cost root-caused by on-device triangulation (two corrections deep):
+  the early "~15× slower per-triangle path" was a **headless-WebKit artifact**
+  (software rasterization), and the follow-up "on par with Chromium" held only for
+  in-callback JS time. Real-Safari rAF rates — rigid ×10 = 60 fps, meshed ×1 =
+  37 fps, meshed ×10 = 3–4 fps with JS flat at ~4–5 ms — put the real cost in the
+  GPU process: Safari antialiases canvas2d **clip paths**, so the per-triangle clip
+  mapping pays a per-triangle AA-mask tax (the same AA that caused the seam cracks)
+- ✅ Optional WebGL blit backend for the mesh tier: `renderer.meshBackend =
+  'webgl'` (default stays `'canvas2d'`). All dirty meshes are shelf-packed into
+  **one shared offscreen WebGL context** (module-level — browsers cap contexts at
+  ~16), drawn as textured triangles with premultiplied alpha, then rect-blitted
+  onto the same per-part canvases with an unclipped `drawImage` — cheap on Safari.
+  Everything element-level is unchanged: z-index interleave, tint filter,
+  `mix-blend-mode`, dirty-skip, grow-only backing. GL rasterizes shared triangle
+  edges seamlessly, so this path needs no crack overdraw. Falls back to canvas2d
+  when WebGL is unavailable or the context is lost. Backend parity verified by
+  headless Chromium+WebKit screenshot diffs (glow / clipping / tint scenes;
+  sub-pixel edge differences only). On-device Safari, meshed ×10 with every mesh
+  redrawn per frame: **3–4 fps (canvas2d) → 45 fps (webgl)**
 
 ## Install
 
@@ -77,30 +115,21 @@ npm i spine-html @esotericsoftware/spine-core
 ```
 
 ```ts
-import { TextureAtlas, AtlasAttachmentLoader, SkeletonJson, Skeleton,
-  AnimationState, AnimationStateData, Physics } from '@esotericsoftware/spine-core';
-import { SpineHtmlRenderer, DomTexture, unpackRegions } from 'spine-html';
+import { Skeleton, AnimationState, AnimationStateData, Physics }
+  from '@esotericsoftware/spine-core';
+import { loadSkeletonAssets, SpineHtmlRenderer } from 'spine-html';
 
-// Load: parse the atlas, attach page images, unpack per-region bitmaps once.
-const atlas = new TextureAtlas(atlasText);
-const pageImages = new Map<string, HTMLImageElement>();
-for (const page of atlas.pages) {
-  const image = await loadImage(page.name); // your loader
-  page.setTexture(new DomTexture(image));
-  pageImages.set(page.name, image);
-}
-const regionImages = await unpackRegions(atlas, pageImages);
-const data = new SkeletonJson(new AtlasAttachmentLoader(atlas)).readSkeletonData(jsonText);
+const assets = await loadSkeletonAssets({
+  atlasUrl: '/spineboy/spineboy.atlas',
+  skeletonUrl: '/spineboy/spineboy-pro.json',
+});
 
 // A positioned element becomes the skeleton origin (Spine is Y-up: the
-// skeleton grows upward from it).
-const skeleton = new Skeleton(data);
-const state = new AnimationState(new AnimationStateData(data));
+// skeleton grows upward from it). Layout and scaling are the caller's.
+const skeleton = new Skeleton(assets.data);
+const state = new AnimationState(new AnimationStateData(assets.data));
 state.setAnimation(0, 'walk', true);
-const renderer = new SpineHtmlRenderer(rootElement, regionImages);
-// Mesh canvases raster at devicePixelRatio by default; if you scale the
-// root element, fold that scale in so the raster matches the screen:
-// renderer.pixelRatio = devicePixelRatio * rootScale;
+const renderer = new SpineHtmlRenderer(rootElement, assets.regionImages);
 
 function frame(delta: number) {
   state.update(delta);
@@ -109,11 +138,106 @@ function frame(delta: number) {
   skeleton.updateWorldTransform(Physics.update);
   renderer.render(skeleton);
 }
+
+// Unloading (a cutscene ends, a level swaps): elements first, bitmaps second.
+// The unpacked regions are blob URLs — nothing else frees them.
+renderer.dispose();
+assets.dispose();
 ```
 
 `spine-html` is a third-party renderer and is not affiliated with or endorsed by
 Esoteric Software.
 
+### 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:
+
+```ts
+import { TextureAtlas, AtlasAttachmentLoader, SkeletonJson }
+  from '@esotericsoftware/spine-core';
+import { DomTexture, unpackRegions, revokeRegions } from 'spine-html';
+
+const atlas = new TextureAtlas(atlasText);
+const pageImages = new Map<string, HTMLImageElement>();
+for (const page of atlas.pages) {
+  const image = await loadImage(page.name); // your loader
+  page.setTexture(new DomTexture(image));
+  pageImages.set(page.name, image);
+}
+const regionImages = await unpackRegions(atlas, pageImages);
+const data = new SkeletonJson(new AtlasAttachmentLoader(atlas)).readSkeletonData(jsonText);
+
+// …and on unload, after every renderer using them is disposed:
+revokeRegions(regionImages);
+```
+
+`unpackRegions` mints one blob URL per region; `revokeRegions` is its
+counterpart. It only frees URLs `unpackRegions` created, so a map you built
+yourself (below) and page images reused by the whole-page pass-through survive
+it — and 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.
+
+### One part per page (loose part PNGs)
+
+Not every pipeline runs the Spine editor's texture packer. If your parts are
+loose PNGs, declare each one as its own atlas page — a blank line closes a page
+block, the next line opens the next:
+
+```
+head.png
+size: 512, 512
+head
+bounds: 0, 0, 512, 512
+
+torso.png
+size: 640, 480
+torso
+bounds: 0, 0, 640, 480
+```
+
+`spine-core` parses this as a normal multi-page atlas and nothing here needs a
+flag. Two things to know:
+
+- **`size:` must be the PNG's real pixel size.** UVs are derived from it
+  (`region.x / page.width`), and a wrong value skews the mesh tier while the
+  rigid tier still looks fine — a confusing failure to chase.
+- Regions like these cover their whole page, so `unpackRegions` hands the page
+  image straight through instead of cutting and re-encoding it. Load cost for
+  this atlas shape is just the image loads.
+
+For a **rigid-only** skeleton you can skip atlas unpacking altogether and hand
+the renderer a map you build yourself — meshes cannot, because the deform tier
+samples the page bitmap through the atlas region:
+
+```ts
+const regionImages = new Map([
+  ['head', { url: '/parts/head.png', width: 512, height: 512 }],
+]);
+const renderer = new SpineHtmlRenderer(rootElement, regionImages);
+```
+
+### Runtime knobs and what they cost
+
+- `renderer.pixelRatio` — mesh-canvas backing pixels per CSS pixel (defaults to
+  `devicePixelRatio`; if you scale the root element, fold that scale in so the
+  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:
+  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.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
+  mesh once (no reallocation), so it is fine to expose as a user setting.
+- `renderer.triangleExpand` — clip overdraw in px that closes antialiased mesh
+  seams (default 0.5). Also re-rasters every mesh once when changed.
+
 ## Demo (this repository)
 
 ```bash
@@ -127,15 +251,49 @@ The official spineboy example assets are downloaded automatically on first `dev`
 
 Debug knobs (query string): `?skel=pro|ess` `?anim=walk` `?count=10` pick the scene,
 `?tint=ff8080` tints the whole skeleton, `?dpr=2` overrides the mesh-canvas backing
-ratio, `?timescale=0` freezes the pose (every mesh should report "reused"), and
-`?expand=0` disables the crack-closing clip overdraw.
+ratio, `?timescale=0` freezes the pose (every mesh should report "reused"),
+`?expand=0` disables the crack-closing clip overdraw, `?backend=webgl` rasterizes
+meshes through the shared WebGL blitter (also a live header select; the stats line
+names the active backend), and `?time=1.2` seeks every instance to the same pose
+for deterministic captures.
+
+## Tests
+
+```bash
+bun run test   # builds + serves the demo, then runs chromium + webkit
+```
+
+Playwright drives the demo (`tests/`, config in `playwright.config.ts`; CI
+runs the same suite on ubuntu). The visual check is **A/B within one run**:
+no golden snapshots are committed (they rot across platforms/GPUs) — instead
+the same deterministic pose (`?time` + `?timescale=0`) is screenshotted with
+`?backend=canvas2d` and `?backend=webgl` in the same engine and the buffers
+are diffed directly with a shift-tolerant comparison, so missing parts,
+wrong colors, and tint/blend divergence fail regardless of platform.
+Hairline seams are guarded by a deterministic canary (`?expand=0` must
+change the canvas2d raster), and counter tests pin the dirty-skip /
+grow-only-backing / clip-skip invariants plus spine-core's region corner
+order (BL, UL, UR, BR).
+
+The loading path is not observable in a rendered frame, so it gets its own
+page (`tests/harness.html`, a second build entry) that exposes the library to
+the specs directly. Its oracle is the browser: a revoked object URL stops
+resolving, so blob ownership — every unpacked URL freed, nothing the caller
+owns touched, nothing stranded by a failed load — is asserted rather than
+assumed.
+
+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
+perf oracle is the demo's stats line on a real device.
 
 ## How it works
 
 1. `@esotericsoftware/spine-core` loads the skeleton and drives `AnimationState`,
    constraints, and physics — all CPU-side, renderer-agnostic.
 2. At load time each atlas region is cut into its own bitmap (rotation restored), one
-   blob URL per region.
+   blob URL per region — except regions that already cover their whole page, which are
+   used as they are.
 3. Per frame, for each slot in draw order: `computeWorldVertices` yields the region's
    four corners in world space (order **BL, UL, UR, BR** — note the comments inside
    `computeWorldVertices` are stale). Flip Y (Spine is Y-up), derive the affine from

package/dist/DomTexture.d.ts

@@ -10,7 +10,11 @@ export declare class DomTexture extends Texture {
     dispose(): void;
 }
 export interface RegionImage {
-    /** Blob URL of the unpacked (rotation-restored) region pixels. */
+    /**
+     * URL of the unpacked (rotation-restored) region pixels: a blob URL minted
+     * by unpackRegions, the page image URL itself when the region covers its
+     * whole page, or anything the caller put there in a hand-built map.
+     */
     url: string;
     /** Unpacked width in atlas pixels. */
     width: number;
@@ -20,10 +24,35 @@ export interface RegionImage {
 /**
  * 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
- * touches a canvas. Returns blob URLs keyed by region name.
+ * touches a canvas. Returns image URLs keyed by region name.
  *
  * This is a loading-pipeline step, not a rendering step: after this runs,
  * 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.
+ *
+ * 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.
  */
 export declare function unpackRegions(atlas: TextureAtlas, pageImages: Map<string, HTMLImageElement>): 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
+ * `renderer.dispose()`, since a live <img> would keep pointing at a dead URL).
+ *
+ * Only URLs this module created are revoked: entries the caller supplied
+ * itself (a hand-built map of loose part PNGs) and page images reused
+ * verbatim by the whole-page pass-through are left alone. Idempotent —
+ * revoking twice is a no-op, so it is safe on a map that is shared or
+ * partially reused.
+ *
+ * The map keeps its entries; drop the reference (or reload) afterwards, since
+ * the URLs no longer resolve.
+ */
+export declare function revokeRegions(images: Map<string, RegionImage>): void;
 //# sourceMappingURL=DomTexture.d.ts.map

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,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;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,CAiCnC"}
+{"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"}

package/dist/DomTexture.js

@@ -9,44 +9,121 @@ export class DomTexture extends Texture {
     setWraps(_uWrap, _vWrap) { }
     dispose() { }
 }
+/**
+ * Blob URLs minted by unpackRegions, i.e. the ones this module owns.
+ *
+ * Ownership has to be tracked because a RegionImage map is not necessarily
+ * ours: callers may hand the renderer a map built from their own URLs (loose
+ * part PNGs need no unpacking at all). revokeRegions() therefore frees only
+ * what is listed here and leaves caller-owned URLs untouched.
+ */
+const ownedUrls = new Set();
+/** Revokes `url` if unpackRegions minted it. Idempotent, caller-safe. */
+function revokeOwned(url) {
+    if (!ownedUrls.delete(url))
+        return;
+    URL.revokeObjectURL(url);
+}
 /**
  * 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
- * touches a canvas. Returns blob URLs keyed by region name.
+ * touches a canvas. Returns image URLs keyed by region name.
  *
  * This is a loading-pipeline step, not a rendering step: after this runs,
  * 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.
+ *
+ * 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.
  */
 export async function unpackRegions(atlas, pageImages) {
     const result = new Map();
-    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;
-        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);
-        }
-        else {
-            ctx.drawImage(image, atlasRegion.x, atlasRegion.y, w, h, 0, 0, w, h);
+    // 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 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);
+            }
+            else {
+                ctx.drawImage(image, atlasRegion.x, atlasRegion.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);
+            put(atlasRegion.name, { url, width: w, height: h });
         }
-        const blob = await new Promise((resolve, reject) => {
-            canvas.toBlob((b) => (b ? resolve(b) : reject(new Error('toBlob failed'))), 'image/png');
-        });
-        result.set(atlasRegion.name, { url: URL.createObjectURL(blob), width: w, height: h });
+    }
+    catch (error) {
+        revokeRegions(result);
+        throw error;
     }
     return result;
 }
+/**
+ * Frees the blob URLs unpackRegions minted for `images` — the counterpart of
+ * unpackRegions, to call once the skeletons using them are gone (after
+ * `renderer.dispose()`, since a live <img> would keep pointing at a dead URL).
+ *
+ * Only URLs this module created are revoked: entries the caller supplied
+ * itself (a hand-built map of loose part PNGs) and page images reused
+ * verbatim by the whole-page pass-through are left alone. Idempotent —
+ * revoking twice is a no-op, so it is safe on a map that is shared or
+ * partially reused.
+ *
+ * The map keeps its entries; drop the reference (or reload) afterwards, since
+ * the URLs no longer resolve.
+ */
+export function revokeRegions(images) {
+    for (const image of images.values())
+        revokeOwned(image.url);
+}
 //# sourceMappingURL=DomTexture.js.map

package/dist/DomTexture.js.map

@@ -1 +1 @@
-{"version":3,"file":"DomTexture.js","sourceRoot":"","sources":["../src/DomTexture.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,GAKR,MAAM,8BAA8B,CAAC;AAEtC;;;;GAIG;AACH,MAAM,OAAO,UAAW,SAAQ,OAAO;IACrC,UAAU,CAAC,UAAyB,EAAE,UAAyB,IAAS,CAAC;IACzE,QAAQ,CAAC,MAAmB,EAAE,MAAmB,IAAS,CAAC;IAC3D,OAAO,KAAU,CAAC;CACnB;AAWD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAmB,EACnB,UAAyC;IAEzC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAC;IAE9C,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QACnC,MAAM,WAAW,GAAG,MAA4B,CAAC;QACjD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpD,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAE5E,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC;QACvB,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;QACxB,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAChD,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC;QACjB,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QAClB,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAEpD,IAAI,MAAM,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;YAC1B,qEAAqE;YACrE,0DAA0D;YAC1D,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YACpB,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;YACzB,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACvE,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACvE,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACvD,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;QAC3F,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IACxF,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"DomTexture.js","sourceRoot":"","sources":["../src/DomTexture.ts"],"names":[],"mappings":"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"}

package/dist/MeshGlBlitter.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared offscreen WebGL rasterizer for the mesh (deform) tier.
+ *
+ * One module-level context serves every renderer instance: browsers cap live
+ * WebGL contexts (16 on Chrome/Safari) and a page can hold many renderers, so
+ * per-renderer contexts would evict each other. Per flush, every dirty mesh is
+ * shelf-packed into a rect of the offscreen canvas, its triangles are drawn
+ * textured (atlas page texture, premultiplied alpha), and each rect is blitted
+ * onto the mesh's per-part 2d canvas with an unclipped drawImage rect copy.
+ *
+ * Why this exists: Safari antialiases canvas2d clip paths, so the standard
+ * per-triangle clip+transform+drawImage mapping pays a per-triangle AA-mask
+ * cost in the GPU process — invisible to in-callback JS timing, but it
+ * rAF-limits heavy scenes. GL rasterizes shared triangle edges seamlessly
+ * (no clip, no crack overdraw needed), and the remaining canvas2d work is a
+ * plain rect blit.
+ *
+ * The offscreen buffer is scratch space: rects are scissor-cleared and
+ * redrawn every flush and read back in the same task, so neither
+ * 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).
+ */
+export interface MeshBlitJob {
+    /** Destination per-part canvas; the blit clears its full backing first. */
+    canvas: HTMLCanvasElement;
+    /** Atlas page image the mesh samples (cached as a GL texture on first use). */
+    page: HTMLImageElement;
+    /** Bbox-relative vertices in CSS px, x/y interleaved (indexed via `triangles`). */
+    vertices: Float64Array;
+    /** Normalized page UVs aligned with `vertices`. */
+    uvs: ArrayLike<number>;
+    /** Triangle index list into vertex/UV pairs. */
+    triangles: ArrayLike<number>;
+    /** Backing-store pixels per CSS px. */
+    ratio: number;
+    /** Rasterized region in device px — the packed rect and the blit both use it. */
+    width: number;
+    height: number;
+}
+declare class MeshGlBlitter {
+    lost: boolean;
+    private readonly canvas;
+    private readonly gl;
+    private readonly uResolution;
+    private readonly textures;
+    private readonly maxSize;
+    private vertexData;
+    /** Per-job packed rect origins, filled by flush(). */
+    private packX;
+    private packY;
+    constructor();
+    /**
+     * Rasterize every job into the offscreen buffer, then blit each rect onto
+     * its per-part canvas. Returns false when the context is lost (or the jobs
+     * cannot fit) so the caller can rasterize the batch on the canvas2d path.
+     */
+    flush(jobs: MeshBlitJob[]): boolean;
+    private compile;
+    private textureFor;
+}
+/**
+ * The module-level blitter, created on first use. Returns null when WebGL is
+ * unavailable or the shared context has been lost — callers then stay on the
+ * canvas2d path.
+ */
+export declare function getMeshGlBlitter(): MeshGlBlitter | null;
+export {};
+//# sourceMappingURL=MeshGlBlitter.d.ts.map

package/dist/MeshGlBlitter.d.ts.map

@@ -0,0 +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"}