spine-html 0.5.1 → 0.6.0

package/README.md

@@ -86,8 +86,29 @@ with a self-contained test suite (backend visual parity + invariants) and CI.
 - ✅ Dirty-skip: a mesh whose canvas-space vertices didn't change reuses last frame's
   raster — the CSS translate still tracks it, so parts that hold a pose (or move by
   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
+- ✅ Clipping attachments as element-level CSS `clip-path`: spine-core's semantics
+  (one active clip at a time, applied from the clip's slot through its end slot
+  inclusive), with the polygon expressed in each element's own local frame — the
+  inverse of the `<img>` matrix for rigid slots, the canvas translate for mesh
+  slots. Covers **part masks** (a clip with a real end slot, like this repository's
+  own `portal` animation) and **whole-skeleton clips** (an end slot that never
+  arrives, which takes a fast path: one `clip-path` on the root instead of one per
+  element). **Inverse clips** are supported too: the region they keep has a hole
+  in it, so it needs two rings, and `polygon()` carries only one — a box and a
+  polygon listed inside one `polygon()` become a single self-intersecting ring
+  whose even-odd fill leaves a wedge along the seam between them (measured, on a
+  corner of spineboy's boot). So an inverse clip is written as a two-subpath
+  `path(evenodd, …)` whose outer ring is the element's own box. The whole feature
+  is element-level, so both mesh backends see the same thing and neither raster
+  path knows clipping exists; `renderer.clipping = false`
+  restores the old counted-and-skipped behaviour. Concave polygons go to CSS as
+  authored — the convex decomposition spine's CPU clipper performs exists to feed a
+  triangle rasterizer and has no job here. Two things this does not do: Spine's
+  clipper convexifies an *inverse* polygon (convex hull) where CSS clips it as
+  authored, so the two agree exactly when that polygon is convex — which is the
+  shape `inverse` is meant for; and the cost of many simultaneous `clip-path`s on
+  real-device Safari is **not measured** (the headless numbers that exist are not
+  Safari evidence — see Measured above)
 - ✅ 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
@@ -247,6 +268,77 @@ 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.
 
+### Pages that ship at another resolution
+
+A page image may ship at a resolution its atlas does not declare — a
+half-resolution texture build, or an @2x variant, with the `size:` line left as
+the packer wrote it. Nothing here needs a flag for that. A region's bounds are
+read **relative to the declared page size** and scaled onto the image's natural
+size, which is exactly how `spine-core` derives the UVs the mesh tier samples
+with (`region.u = region.x / page.width`), so both tiers land on the same
+pixels at any resolution:
+
+```
+hero.png
+size: 4096, 4096     # what the packer wrote
+                     # hero.png itself ships 2048×2048
+```
+
+Each unpacked bitmap comes out at the **native resolution of the pixels it was
+cut from** — half-resolution pages cost a quarter of the cut pixels, and
+nothing is upscaled back — while `RegionImage.width`/`height` stay in **atlas
+units**. Those two numbers are the `<img>` layout box and the denominator of
+its CSS matrix, so the skeleton poses identically and the browser scales the
+smaller bitmap into the same box, the way a GPU samples a smaller texture
+through the same UVs. Ship one atlas and swap the images per device if you
+like.
+
+The corollary: a `size:` line that is simply **wrong** is now wrong for the
+whole renderer rather than for the mesh tier alone. Bounds are read against
+what the atlas declares, so a page declared at a size its artwork was not
+packed at reads every region from the wrong place in both tiers — correct the
+`size:` line, which is what every other Spine runtime needs too.
+
+### Premultiplied pages (`pma: true`)
+
+The Spine texture packer premultiplies alpha by default, and says so with a page
+line:
+
+```
+hero.png
+size: 2048, 2048
+pma: true
+```
+
+Such a page's RGB is already multiplied by its alpha, and nothing is asked of
+you: the flag is read off the atlas and each tier is handed the page in the
+convention it actually consumes. The `webgl` mesh backend uploads the texels
+unconverted (its blend already expects premultiplied source — lossless). The DOM
+and canvas2d tiers cannot: an `<img>` and `drawImage` composite straight alpha by
+definition, so they read a straight-alpha derivation of the page —
+`rgb = round(rgb * 255 / a)`, computed once and shared by the region cuts and
+the mesh raster. Without it every semi-transparent texel is multiplied by its
+alpha a second time and draws darker than it was authored: soft edges, soft
+shadows, glows.
+
+What it costs: **one page-sized canvas per premultiplied page image**
+(width × height × 4 bytes — 1 MiB for a 1024×256 page, 16 MiB for a 2048×2048
+one), alive as long as you hold the page image and released with it; the cache
+is weak, so there is nothing to free by hand. A page with no `pma:` line derives
+nothing and takes exactly the path it always did. The division is 8-bit and
+starts from a canvas read, which has itself quantized a premultiplied texel, so
+a very transparent texel can land a few levels off — exact at alpha 0 and 255,
+within one level of 255 above alpha 128, and a little more below that, by an
+amount that belongs to the browser's canvas rather than to this package (some
+rasterizers round premultiplied storage several times more coarsely than
+others). It is bounded by what that canvas already costs, and it is invisible
+wherever the texel is: a texel at alpha 11 is ~4% opaque. The `webgl` backend,
+having no such step, is exact.
+
+One consequence worth knowing if your atlas is one part per page: a whole-page
+region on a premultiplied page is **cut** rather than handed through, because
+the page's own URL holds premultiplied pixels (see below).
+
 ### What unloading frees
 
 `revokeRegions()` — and `assets.dispose()`, which just calls it — frees the blob
@@ -297,12 +389,20 @@ 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.
+- **`size:` is the frame every coordinate is read in**, so each page's
+  `bounds` must be written against the `size:` above them. The two need not be
+  the PNG's pixel size — that is the point of the section above, and a
+  half-resolution `head.png` under `size: 512, 512` works — but a `size:` that
+  matches neither the bounds nor the artwork reads every region from the wrong
+  place, in both tiers.
 - 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.
+  image straight through instead of cutting and re-encoding it — at any image
+  resolution, since covering the page is a statement about the declared size.
+  Load cost for this atlas shape is just the image loads. The exception is a
+  page marked `pma: true`: its URL holds premultiplied pixels, which an `<img>`
+  would composite as straight alpha, so those regions are cut from the
+  straight-alpha derivation like any other (and the blob is revoked by
+  `revokeRegions` like any other).
 
 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
@@ -350,6 +450,36 @@ const renderer = new SpineHtmlRenderer(rootElement, regionImages);
   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.
+- `renderer.clipping` — apply clipping attachments (default `true`). What it
+  writes is one CSS `clip-path` per element the active clip covers, in that
+  element's own local frame; nothing reaches the raster backends, and a clip is
+  not part of the mesh dirty signature, so a mesh that held still keeps reusing
+  its raster under a moving clip. **Writes happen on change only**: each
+  clip-path is cached exactly as `transform` is, coordinates are quantized to
+  1/1000 of a local unit so float jitter cannot defeat that cache, and a static
+  polygon over a static pose therefore costs **zero style writes per frame after
+  the first** — `renderer.clipWriteCount` is the check, alongside
+  `clipCount` (applied) and `clipSkipCount` (not applied: switched off, a second
+  clip met while one was active, an inactive bone, a degenerate polygon).
+  **The whole-skeleton fast path**: when the clip starts before anything has been
+  drawn and never ends, one `clip-path` goes on the root instead of one per
+  element. The root is *your* element, so its inline `clip-path` is **borrowed,
+  not taken** — saved on the first write and put back verbatim when the clip
+  stops covering the frame, when `clipping` goes `false`, and by `dispose()`.
+  Per-element clip-paths and the root clip-path are never both in force for the
+  same clip. Two things to know about that path: the polygon is written in the
+  root's **border box** frame, which is where absolutely-positioned slot elements
+  start too *unless the root has a CSS border* (a border would offset the
+  whole-skeleton clip by its width — keep borders off the render root, which is
+  the normal shape for a 0×0 origin element); and an inverse clip never takes it,
+  because its CSS form needs an outer ring around a box and the root has none.
+  One further consequence of that path: a `clip-path` other than `none` makes an
+  element a stacking context (CSS Masking), so a whole-skeleton clip isolates
+  `mix-blend-mode` slots from backdrops *outside* the root — which a root
+  carrying a `transform` (the usual pan/zoom stage) already does. Per-element
+  clips do not change blending, since a blended slot is its own stacking context
+  either way. Setting `clipping = false` removes every clip-path this renderer
+  wrote.
 
 **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
@@ -383,8 +513,9 @@ Debug knobs (query string): `?skel=pro|ess` `?anim=walk` `?count=10` pick the sc
 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.
+names the active backend), `?clipping=0` turns clipping attachments back off (they
+are then counted and skipped, as before v0.6 — try it on `?anim=portal`), and
+`?time=1.2` seeks every instance to the same pose for deterministic captures.
 
 ## Tests
 
@@ -401,9 +532,24 @@ 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
+grow-only-backing / clip-counter invariants plus spine-core's region corner
 order (BL, UL, UR, BR).
 
+Clipping gets its own oracle (`tests/clipping.spec.ts`), because a clip-path
+that went through the wrong transform still parses and still counts as applied.
+A clipped capture is compared against the **unclipped** capture of the same
+slots masked in **screen space** by the world polygon — built once through the
+stage transform, never through an element's local frame, so the check cannot
+agree with the renderer by sharing its mistake. What it asserts is occupancy,
+not pixel values: outside a 3 px band around the polygon's outline (where the
+browser's clip-path antialiasing and the canvas `ctx.clip()` the oracle uses
+legitimately differ), **no artwork may survive where the polygon excludes it
+and none may go missing where it does not** — both counts absolute, no budget.
+Pixel values are logged but not asserted, because a clipped element is drawn
+through a mask and its silhouettes come out a shade different all over the
+picture; a control capture, clipped by a polygon that removes nothing, pins
+that down by coming back byte-identical to the unclipped one.
+
 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

package/dist/DomTexture.d.ts

@@ -16,11 +16,64 @@ export interface RegionImage {
      * whole page, or anything the caller put there in a hand-built map.
      */
     url: string;
-    /** Unpacked width in atlas pixels. */
+    /**
+     * Unpacked width in **atlas units** — the region's own `width`, not the
+     * bitmap's pixel width. The two differ whenever the page image ships at a
+     * resolution its atlas `size:` line does not mention (see cutRegion): a
+     * half-resolution page yields a bitmap half this wide. This is the layout
+     * box the rigid tier writes onto its `<img>` and the denominator of the CSS
+     * matrix it builds, so it stays in the frame the skeleton is authored in
+     * and the browser scales the bitmap into it — the same thing a GPU does
+     * when it samples normalized UVs from a texture of any resolution.
+     */
     width: number;
-    /** Unpacked height in atlas pixels. */
+    /** Unpacked height in atlas units — see `width`. */
     height: number;
 }
+/**
+ * Page pixels in the alpha convention a DOM/canvas2d consumer needs: the page
+ * image itself, or the derived canvas below when the page is premultiplied.
+ */
+export type PageSource = HTMLImageElement | HTMLCanvasElement;
+/**
+ * How many straight-alpha page derivations have been built in this document.
+ *
+ * Deterministic (no GC in the path) and monotonic, so a test reads it before
+ * and after and asserts the *difference*. Exported for the tests only — it is
+ * not re-exported from index.ts and the `exports` map denies deep imports, so
+ * it is not package API. (The same arrangement as `liveTextureCount` on the GL
+ * blitter, and for the same reason: a cache that works is invisible.)
+ */
+export declare function straightAlphaDerivations(): number;
+/**
+ * The page as a straight-alpha source: the image itself when `pma` is false,
+ * otherwise its (cached) un-premultiplied derivation.
+ *
+ * `rgb = round(rgb * 255 / a)`, clamped, with `a === 0` left at (0,0,0,0) —
+ * there is no colour to recover from a fully transparent texel.
+ *
+ * **Precision.** The division is done in 8 bits and cannot be done anywhere
+ * else: a 2D canvas stores premultiplied colour, so `getImageData` hands back
+ * `round(round(u * a / 255) * 255 / a)` for a file value `u`, already quantized
+ * by the read (measured on both engines: put→get moves a value by up to 127 at
+ * a = 1). The colour a low-alpha texel composites to is therefore off by at
+ * most ~min(a, 127.5/a + 0.5) of 255 — nothing at a = 255 or a = 0, ≤ 1 above
+ * a = 128, worst ~12 around a = 11, and bounded by `a` below that. Writing the
+ * values back is exact, not a second premultiply: the canvas quantizer is
+ * idempotent, so putting a value that came out of it stores it unchanged
+ * (measured: a second round trip moves nothing on either engine). The remaining
+ * error is one-way rounding on near-invisible texels, against a defect that
+ * darkened every semi-transparent texel by up to 59 luma.
+ *
+ * A page image that cannot be read — no 2D context, or a cross-origin image
+ * without CORS, where `getImageData` throws — falls back to the page itself and
+ * caches *that*: the colour is then as wrong as it is today, but it happens
+ * once per image instead of once per frame, and no frame throws. (The cut path
+ * already fails on such an image at `toBlob`, so only the mesh tier can get
+ * here.) An image that has not decoded yet is left uncached, so the derivation
+ * happens once it has.
+ */
+export declare function straightAlphaSource(page: HTMLImageElement, pma: boolean): PageSource;
 /**
  * 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
@@ -30,7 +83,23 @@ 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 in cutRegion.
+ * page image URL — see the pass-through in planCut.
+ *
+ * **A page may ship at a resolution its atlas does not declare.** Half-size
+ * texture builds and @2x variants are normal, and no option is needed for
+ * them: a region's bounds are read relative to the declared page size and
+ * scaled onto the image's natural size, which is exactly how spine-core
+ * derives the UVs the mesh tier already samples with. Each bitmap comes out at
+ * the native resolution of the pixels it was cut from, and the `RegionImage`
+ * sizes beside it stay in atlas units, so nothing downstream has to know.
+ *
+ * *Behaviour change (0.5.1 → next).* An atlas whose `size:` line is simply
+ * wrong — bounds written in image pixels under a page declared some other size
+ * — used to be cut "as the coordinates say", because the cut read the image
+ * directly. It is now read the way every other Spine runtime reads it:
+ * relative to the declared size. Such an atlas rendered with a skewed mesh
+ * tier and an intact rigid tier before; now both tiers agree, and the fix is
+ * to correct the `size:` line.
  *
  * **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

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;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"}
+{"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;;;;;;;;;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;AAgQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;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"}