spine-rigc 1.2.0 → 1.2.1

package/docs/AUTHORING.md

@@ -152,12 +152,15 @@ one directory of `f0000.png`, `f0001.png`… named after the candidate animation
 shows (or pair the two with `--as`): `check` accepts a set with no `frames.json`
 and takes its rate from `--fps` (§9). What that set cannot carry is its
 **background**, which the sidecar would have recorded — so render it onto an
-**opaque** background of the colour `check`'s no-`frames.json` note names
-(`232, 232, 232, 255` in this release). The content box is found against that
-colour and alpha is not read: measured on the 24 frames of `gallery/look`'s `turn`,
-the same drawn pixels read MAE mean **2.25** over that grey, **5.19** over white and
-**20.37** over a transparent background, where the fit took the whole 234×256
-frame for the figure — all three at exit 0 with the same notes. A port with no
+**opaque** background of the colour `check`'s no-`frames.json` note names, the one
+after *"the background is this build's default,"*. Running `check` once on any
+frame set with no sidecar prints it, so read it there before rendering rather than
+from a copy here. The content box is found against that colour and alpha is not
+read, so a reference that is not opaque is **refused**, naming the frames and the
+first pixel whose alpha is not 255 (§9). A background that is opaque but another
+colour is not refused and costs you: measured on the 24 frames of `gallery/look`'s
+`turn`, the same drawn pixels read MAE mean **2.25** over the note's colour and
+**5.19** over white, at exit 0 with the same notes. A port with no
 reference frames is **unmeasured, not finished**: green from `build` says the file
 is valid and nothing about whether it is the source's picture. And the parts are
 the source's own texture cut along its drawables, **never a screenshot of it** — a
@@ -214,7 +217,12 @@ What the flags mean:
 
 `render` also takes `--fps <n>` (the rate it samples at, default 12 — the same
 protocol rate the reference frames use) and `--max <px>` (the long side of a
-frame, default 256). Three commands take `--out`: a directory for `render`
+frame, default 256). A clipping attachment is applied as the runtime applies it —
+spine-core's own `SkeletonClipping`, in spine-webgl's call order — so a slot from
+the clip's through its `end` slot draws only what falls inside the polygon, in
+`render`, `check` and every other picture rigc's own rasteriser draws (`preview`
+plays in Spine's player, which always clipped); the framing box still counts
+what the clip removes, so adding or keying a mask moves no pixel it leaves drawn. Three commands take `--out`: a directory for `render`
 (default `render/`), the `.html` file for `preview` (default `preview.html`) and
 for `vote` (default `ballot.html`).
 
@@ -6173,6 +6181,31 @@ sampled at, and without it the 12 fps protocol rate is assumed and the report sa
 so rather than letting the assumption look like a measurement. Passing `--fps` with
 a value the sidecar contradicts is an error, not an override.
 
+A set with no sidecar is one of two things, and the `⚠️ no frames.json` note says
+which advice goes with which: **a rigc render older than the sidecar** is fixed by
+rendering it again with `rigc render`, and **a foreign source** — a Live2D, Unity or
+video player, whose frames predate nothing — needs the three things the sidecar
+would have said, supplied by whoever made them: an opaque background of the colour
+the note names, `--fps` at the rate it was rendered, and a directory named after
+the candidate animation it shows or `--as <that animation>`. Two of those are
+refused by name when they are wrong, because a figure would come out of either:
+
+```
+rigc check error: --frames frames/turn has no frames.json, and 24 of its 24 compared reference frame(s) are not opaque (f0000.png, f0001.png, f0002.png, and 21 more): f0000.png has alpha 0 at (0, 0), where every pixel must be 255. Without a sidecar the frames are read against the background colour 232, 232, 232, 255 with alpha unread, so a pixel that is not opaque counts by its colour bytes alone: a transparent background counts as drawn and puts the figure over the whole frame, a number about the transparent area and not the rig, which --viewport does not change. Render the frames onto an opaque background of 232, 232, 232, 255.
+rigc check error: no reference frame could be compared, so there is nothing to frame against: the frames were matched to a candidate animation by name, and the candidate has no animation called "idle" (the directory's own name) — it declares [sweep, tilt, turn]. Pass --as <name> with the one these frames show, or name the directory after it
+```
+
+The test is every pixel's alpha, not the border's: a pixel that is not opaque is
+not yet a colour — what it shows depends on what it is composited over — so one
+pixel of alpha 254 in one frame is refused too, naming that frame and that pixel.
+The first is a refusal rather than a note because pinning does not rescue it:
+`--viewport` set to the box the frames were drawn in reads MAE **0.00** on the
+opaque set and **32.90** on the same set made transparent, on every one of its 24
+frames — the transparent area times its distance from the background colour, which
+is a figure about the background and not about the rig. `--as` takes **one**
+candidate animation name; the `<candidate>=<reference>` pair is `diff`'s spelling,
+and `check` refuses it as a name the candidate does not declare.
+
 `--viewport <x>,<y>,<width>,<height>` pins your candidate's world box instead of
 fitting it. Two uses:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Rig compiler for Spine — declarative rig specs in, Spine 4.3 skeleton data out, verified by a spine-core round-trip. Built so AI agents can author rigs and check their own work; the output imports into the Spine editor.",
   "type": "module",
   "bin": {

package/src/check.ts

@@ -1169,11 +1169,20 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
         duration: disk[disk.length - 1].index / fps,
       },
     ];
+    // Two sources write a set like this, and they need opposite advice (issue
+    // #842): a rigc render older than the sidecar is fixed by rendering it again,
+    // while a foreign player's frames predate nothing and no rigc tool renders
+    // their source — what they need is the three things the sidecar would have
+    // said, supplied by whoever made them.
     notes.push(
-      `no ${FRAMES_SIDECAR} at ${located.root} or beside it — this frame set predates the sidecar. The rate is ` +
+      `no ${FRAMES_SIDECAR} at ${located.root} or beside it. The rate is ` +
         `--fps ${fps}${options.fps === undefined ? ' (the protocol default, not a measurement of these frames)' : ''} ` +
-        `and the background is this build's default (${BACKGROUND.join(', ')}). Re-render the set with ` +
-        'bench/render_reference.ts and both become facts about the frames.',
+        `and the background is this build's default, ${BACKGROUND.join(', ')}; neither is read from the frames. ` +
+        'A set with no sidecar is one of two things. A rigc render older than the sidecar: re-render it with ' +
+        '`rigc render` (bench/render_reference.ts for an editor export) and both become facts about the frames. ' +
+        `A foreign source — a Live2D, Unity or video player: render it onto an opaque background of ` +
+        `${BACKGROUND.join(', ')}, pass --fps at the rate it was rendered, and name the directory after the ` +
+        'candidate animation it shows, or pass --as <that animation>.',
     );
     // The set root is the animation directory itself here, so reads resolve
     // against its parent the way a sidecar layout does.
@@ -1226,8 +1235,36 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
   // `EDGE_FRACTION`. A handful of frames is enough: the level is a property of the
   // palette, not of a pose, and reading every frame twice to learn it is waste.
   const level = pairs.length === 0 ? BACKGROUND_TOLERANCE : edgeLevelOf(located.root, pairs, background);
+  // Without a sidecar the background is an assumption, and it is an assumption
+  // about a COLOUR: the box and the union alpha are found against it with alpha
+  // unread. So a reference that is not opaque is refused rather than scored
+  // (issue #842). Measured on gallery/look's `turn` with its background made
+  // transparent and the candidate pinned by --viewport to the box the frames were
+  // drawn in — where the same set over the assumed grey reads MAE 0.00 exactly —
+  // it read 32.90 on every one of the 24 frames, which is the transparent area's
+  // share of the frame times its distance from the grey: a figure about the
+  // background, not the rig, and no framing moves it. A frame set WITH a sidecar
+  // is `render`'s, which composites onto the colour it records, so it is not asked.
+  const translucent: TranslucentFrame[] | null = located.sidecar ? null : [];
   const referenceBoxes =
-    pairs.length === 0 ? [] : referenceContentBoxes(located.root, pairs, background, level, pixelWidth, pixelHeight);
+    pairs.length === 0
+      ? []
+      : referenceContentBoxes(located.root, pairs, background, level, pixelWidth, pixelHeight, translucent);
+  if (translucent !== null && translucent.length > 0) {
+    const first = translucent[0];
+    const shown = translucent.slice(0, TRANSLUCENT_NAMED).map((t) => basename(t.file));
+    throw new CheckError(
+      `--frames ${options.framesDir} has no ${FRAMES_SIDECAR}, and ${translucent.length} of its ${pairs.length} ` +
+        `compared reference frame(s) are not opaque (${shown.join(', ')}${
+          translucent.length > shown.length ? `, and ${translucent.length - shown.length} more` : ''
+        }): ${basename(first.file)} has alpha ${first.alpha} at (${first.x}, ${first.y}), where every pixel must ` +
+        `be 255. Without a sidecar the frames are read against the background colour ${BACKGROUND.join(', ')} ` +
+        'with alpha unread, so a pixel that is not opaque counts by its colour bytes alone: a transparent ' +
+        'background counts as drawn and puts the figure over the whole frame, a number about the transparent ' +
+        'area and not the rig, which --viewport does not change. Render the frames onto an opaque background of ' +
+        `${BACKGROUND.join(', ')}.`,
+    );
+  }
 
   const scope: FramingScope = options.framing ?? 'per-shot';
   const slices = sliceBySet(prepared, referenceBoxes);
@@ -1287,7 +1324,14 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
       topFit = reportFor(fit, pinned, { ...pinnedShape, agrees: fitDistance(fit) <= COINCIDENT_PIXELS, refinement });
     }
   } else if (referenceBoxes.every((b) => b === null)) {
-    throw new CheckError('no reference frame could be compared, so there is nothing to frame against');
+    throw new CheckError(
+      `no reference frame could be compared, so there is nothing to frame against${nothingToFrameWhy(
+        prepared,
+        posable.data.animations.map((a) => a.name),
+        options.as,
+        located.sidecar !== null,
+      )}`,
+    );
   } else if (scope === 'shared' || prepared.length === 1) {
     const framed = frameCandidate(
       prepared,
@@ -1725,7 +1769,38 @@ function edgeLevelOf(root: string, pairs: FramePair[], background: RGBA): number
   return histogram.level();
 }
 
-/** Each reference frame's own content box, and a check that they are one grid. */
+/** How many translucent reference frames the refusal names before it counts the rest. */
+const TRANSLUCENT_NAMED = 3;
+
+/** The first pixel of a reference frame that is not fully opaque — see `referenceContentBoxes`. */
+interface TranslucentFrame {
+  file: string;
+  x: number;
+  y: number;
+  alpha: number;
+}
+
+/** The first pixel whose alpha is not 255, in row order, or null when the frame is opaque. */
+function firstTranslucentPixel(plate: Plate): { x: number; y: number; alpha: number } | null {
+  for (let i = 3; i < plate.data.length; i += 4) {
+    if (plate.data[i] !== 255) {
+      const at = (i - 3) / 4;
+      return { x: at % plate.width, y: Math.floor(at / plate.width), alpha: plate.data[i] };
+    }
+  }
+  return null;
+}
+
+/**
+ * Each reference frame's own content box, and a check that they are one grid.
+ *
+ * `translucent`, when given, collects every frame that is not fully opaque. The
+ * content box and the union alpha are found against the background COLOUR and
+ * alpha is never read (`backgroundDistance`), so a transparent pixel is drawn to
+ * both of them whatever its colour bytes say. It is collected here rather than in
+ * a pass of its own because this is where every compared frame is already
+ * decoded, and a frame that is not compared cannot move a figure.
+ */
 function referenceContentBoxes(
   root: string,
   pairs: FramePair[],
@@ -1733,6 +1808,7 @@ function referenceContentBoxes(
   level: number,
   pixelWidth: number,
   pixelHeight: number,
+  translucent: TranslucentFrame[] | null,
 ): Array<ContentBox | null> {
   return pairs.map((pair) => {
     const plate = readPlateFrom(root, pair.file);
@@ -1742,6 +1818,10 @@ function referenceContentBoxes(
           'the frames and the sidecar disagree about their own size',
       );
     }
+    if (translucent !== null) {
+      const at = firstTranslucentPixel(plate);
+      if (at !== null) translucent.push({ file: pair.file, ...at });
+    }
     return contentBoxOfPlate(plate, background, level);
   });
 }
@@ -2398,6 +2478,46 @@ function prepareSet(
   };
 }
 
+/**
+ * What the "nothing to frame against" refusal adds when the sets can say why.
+ *
+ * The one reason a whole run has no reference box that a reader can act on is a
+ * name that matched no candidate animation, and `prepareSet` already composed
+ * that per set — then the refusal fired before any set was reported, so the one
+ * sentence that named the fix never reached the reader (issue #842). This says
+ * where each name came from, because the fix differs: a directory name is
+ * renamed or overridden, an `--as` is corrected. Empty when every set matched,
+ * so the refusal's other causes keep the sentence they had.
+ */
+function nothingToFrameWhy(
+  prepared: PreparedSet[],
+  have: string[],
+  as: string | undefined,
+  sidecar: boolean,
+): string {
+  const unmatched = prepared.filter((p) => p.missing !== null);
+  if (unmatched.length === 0) return '';
+  const declared = `it declares [${have.join(', ') || 'none'}]`;
+  if (as !== undefined) {
+    return (
+      `: --as ${JSON.stringify(as)} names no animation of the candidate — ${declared}. --as takes one candidate ` +
+      'animation name, the one these frames show'
+    );
+  }
+  const tried = unmatched.map((p) => {
+    const name = JSON.stringify(p.set.animation);
+    if (sidecar) return `${name} (what ${FRAMES_SIDECAR} records for set ${JSON.stringify(p.set.dir)})`;
+    return p.set.dir === p.set.animation
+      ? `${name} (the directory's own name)`
+      : `${name} (the directory ${JSON.stringify(p.set.dir)}, its @fps suffix dropped)`;
+  });
+  return (
+    `: the frames were matched to a candidate animation by name, and the candidate has no animation called ` +
+    `${tried.join(', ')} — ${declared}. Pass --as <name> with the one these frames show, or name the ` +
+    'directory after it'
+  );
+}
+
 function checkOneSet(
   root: string,
   prepared: PreparedSet,

package/src/render.ts

@@ -23,6 +23,13 @@
  *   real runtime would. Each triangle is then filled with barycentric UV
  *   interpolation.
  *
+ * A **clipping attachment** draws no pixel of its own and removes the pixels of
+ * every slot from the one carrying it through its `end` slot. `piecesOf` runs
+ * spine-core's own `SkeletonClipping` beside the draw-order walk, in the call
+ * sequence spine-webgl's `SkeletonRenderer.draw` runs, so a slot inside a clip
+ * reaches the rasteriser as the geometry the runtime draws rather than as the
+ * attachment's whole (issue #844).
+ *
  * ⭐ **Sampling is bilinear on both paths, and the source is straight alpha —
  * so the interpolation is premultiplied.** One filter rather than two is not a
  * detail: `check` measures a candidate against reference frames, and a mesh
@@ -80,14 +87,17 @@ import {
   AnimationState,
   AnimationStateData,
   AtlasAttachmentLoader,
+  ClippingAttachment,
   MeshAttachment,
   Physics,
   RegionAttachment,
   Skeleton,
+  SkeletonClipping,
   SkeletonJson,
   TextureAtlas,
   TextureAtlasRegion,
   type SkeletonData,
+  type Slot,
 } from '@esotericsoftware/spine-core';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -361,6 +371,19 @@ export interface PoseOptions {
   slots?: string[];
   /** Draw every slot but these — see `slots`. */
   hidden?: string[];
+  /**
+   * Pose every attachment whole, with no clipping attachment applied — set by
+   * `framingViewport` and by nothing that draws.
+   *
+   * ⭐ **The framing box counts what a clip removes**, for the reason it counts
+   * what `--slot`/`--hide` leave out: the box is a property of the shot, and a
+   * clip is a statement about which pixels of it are drawn. Framed on the
+   * clipped geometry, a rig's viewport would move the moment a clip is added or
+   * keyed, and every frame set already on disk for it — `frames.json`'s world
+   * box, the grid `check` compares on — would stop describing the frames a
+   * second render writes.
+   */
+  unclipped?: boolean;
 }
 
 /**
@@ -758,6 +781,35 @@ export function sampleAll(data: SkeletonData, fps: number, opts?: PoseOptions):
  * type that is neither is skipped rather than refused: a bounding box, a point
  * and a clipping attachment are all things a rig legitimately carries and none
  * of them draws a pixel.
+ *
+ * ## A clipping attachment is skipped as a piece and applied as a mask
+ *
+ * It draws nothing, and it removes what every slot from its own through its
+ * `end` slot draws outside its polygon. Skipping it outright drew those pixels —
+ * measured on a port whose eye masks clip the irises: the blink frame read MAE
+ * 1.07 against 0.53 at an open eye, with both irises drawn over closed lids,
+ * where spine-webgl reads 0.16 (issue #844). So spine-core's own
+ * `SkeletonClipping` runs beside the walk, and the call sequence is
+ * spine-webgl's `SkeletonRenderer.draw` (branch `4.3`) step for step: at a
+ * clipping attachment `clipEnd(slot)` then `clipStart(skeleton, slot, clip)` and
+ * nothing drawn; at every other slot, drawn or not, `clipEnd(slot)` after it,
+ * which is what ends a clip AT its end slot rather than before it; `clipEnd()`
+ * after the walk. The polygon, its convex decomposition, `inverse` and `convex`
+ * are the clipper's, so there is no second opinion about any of them here.
+ *
+ * A slot inside a clip hands its world vertices, its triangles — a region's are
+ * the runtime's own `0 1 2 2 3 0` — and its UVs to `clipTrianglesUnpacked`, and
+ * the piece carries what comes back. ⚠️ **Only when the clipper says it clipped**,
+ * exactly as spine-webgl uses the result only when `clipTriangles` returns
+ * true: an attachment wholly inside the polygon draws its own geometry, so a
+ * region there is still a `Quad` and its pixels are the unclipped ones to the
+ * bit. One that is cut becomes a `Mesh` — the clipper's output is a triangle
+ * list — and one wholly outside becomes a mesh with no triangle, which keeps the
+ * slot in the frame, undrawn, rather than absent.
+ *
+ * The clip is applied whatever `slots`/`hidden` draw: a hidden clip still masks
+ * what is shown, so a subset frame is the whole frame's pixels for those slots.
+ * `unclipped` turns it off for the framing box alone — see its note.
  */
 export function piecesOf(skeleton: Skeleton, opts?: PoseOptions): Piece[] {
   // A skin is chosen before a skeleton is posed, and this one is already posed —
@@ -776,63 +828,127 @@ export function piecesOf(skeleton: Skeleton, opts?: PoseOptions): Piece[] {
   // application point is, rather than matching no piece in silence.
   const subset = slotSubsetOf(skeleton.data, opts, skeleton.skin?.name);
   const named = subset === undefined ? undefined : new Set(subset.names);
+  const clipper = opts?.unclipped === true ? null : new SkeletonClipping();
   const pieces: Piece[] = [];
   for (const slot of skeleton.drawOrder.appliedPose) {
-    if (subset !== undefined && named !== undefined && named.has(slot.data.name) !== (subset.mode === 'slots')) continue;
-    const pose = slot.appliedPose;
-    const attachment = pose.attachment;
-    if (!attachment) continue;
-    const isMesh = attachment instanceof MeshAttachment;
-    if (!isMesh && !(attachment instanceof RegionAttachment)) continue;
-
-    const index = attachment.sequence.resolveIndex(pose);
-    const region = attachment.sequence.regions[index];
-    if (!(region instanceof TextureAtlasRegion)) {
-      throw new Error(
-        `slot "${slot.data.name}" attachment "${attachment.name}" resolved to no atlas region; ` +
-          'the attachment names a region the atlas does not have',
-      );
-    }
-    const colour = pose.color;
-    const own = attachment.color;
-    const tint: [number, number, number, number] = [
-      colour.r * own.r,
-      colour.g * own.g,
-      colour.b * own.b,
-      colour.a * own.a,
-    ];
-    // The dark colour is the SLOT's alone — an attachment has a `color` and no
-    // dark one, so there is nothing to multiply it by. Read off `appliedPose`
-    // like the light colour, so an `rgba2` timeline reaches the picture.
-    const darkPose = pose.darkColor;
-    const dark: [number, number, number] | undefined =
-      darkPose === null ? undefined : [darkPose.r, darkPose.g, darkPose.b];
-    const common = { tint, dark, slot: slot.data.name, page: region.page.name };
-    const texture = opts?.texture !== true ? undefined : artUvsOf(attachment, region);
-
-    if (isMesh) {
-      // `worldVerticesLength` is 2 per vertex whether or not the mesh is
-      // weighted — the weight runs live in `vertices`, not here — so this is the
-      // full output length and the whole mesh is computed in one call. Deform
-      // offsets, if the pose carries any, are applied inside it.
-      const world = new Array<number>(attachment.worldVerticesLength).fill(0);
-      attachment.computeWorldVertices(skeleton, slot, 0, attachment.worldVerticesLength, world, 0, 2);
-      pieces.push({
-        kind: 'mesh',
-        ...common,
-        texture,
-        world,
-        uvs: attachment.sequence.getUVs(index),
-        triangles: attachment.triangles,
-      });
+    const attachment = slot.appliedPose.attachment;
+    if (attachment instanceof ClippingAttachment) {
+      if (clipper !== null) {
+        clipper.clipEnd(slot);
+        // spine-webgl ends the clip at a slot whose bone is inactive and starts
+        // none there; the order of the two calls is the same either way.
+        if (slot.bone.active) clipper.clipStart(skeleton, slot, attachment);
+      }
       continue;
     }
+    const drawn = subset === undefined || named === undefined || named.has(slot.data.name) === (subset.mode === 'slots');
+    const piece = drawn ? pieceOf(skeleton, slot, opts, clipper) : null;
+    if (piece !== null) pieces.push(piece);
+    clipper?.clipEnd(slot);
+  }
+  clipper?.clipEnd();
+  return pieces;
+}
+
+/** The runtime's own triangulation of a region's quad — spine-webgl's `QUAD_TRIANGLES`. */
+const QUAD_TRIANGLES = [0, 1, 2, 2, 3, 0];
 
+/**
+ * One slot's posed drawable, or `null` for an attachment that draws nothing —
+ * clipped by `clipper` when a clip is active over it (see `piecesOf`).
+ */
+function pieceOf(
+  skeleton: Skeleton,
+  slot: Slot,
+  opts: PoseOptions | undefined,
+  clipper: SkeletonClipping | null,
+): Piece | null {
+  const pose = slot.appliedPose;
+  const attachment = pose.attachment;
+  if (!attachment) return null;
+  const isMesh = attachment instanceof MeshAttachment;
+  if (!isMesh && !(attachment instanceof RegionAttachment)) return null;
+
+  const index = attachment.sequence.resolveIndex(pose);
+  const region = attachment.sequence.regions[index];
+  if (!(region instanceof TextureAtlasRegion)) {
+    throw new Error(
+      `slot "${slot.data.name}" attachment "${attachment.name}" resolved to no atlas region; ` +
+        'the attachment names a region the atlas does not have',
+    );
+  }
+  const colour = pose.color;
+  const own = attachment.color;
+  const tint: [number, number, number, number] = [
+    colour.r * own.r,
+    colour.g * own.g,
+    colour.b * own.b,
+    colour.a * own.a,
+  ];
+  // The dark colour is the SLOT's alone — an attachment has a `color` and no
+  // dark one, so there is nothing to multiply it by. Read off `appliedPose`
+  // like the light colour, so an `rgba2` timeline reaches the picture.
+  const darkPose = pose.darkColor;
+  const dark: [number, number, number] | undefined =
+    darkPose === null ? undefined : [darkPose.r, darkPose.g, darkPose.b];
+  const common = { tint, dark, slot: slot.data.name, page: region.page.name };
+  const texture = opts?.texture !== true ? undefined : artUvsOf(attachment, region);
+  const uvs = attachment.sequence.getUVs(index);
+
+  let piece: Piece;
+  let triangles: number[];
+  if (isMesh) {
+    // `worldVerticesLength` is 2 per vertex whether or not the mesh is
+    // weighted — the weight runs live in `vertices`, not here — so this is the
+    // full output length and the whole mesh is computed in one call. Deform
+    // offsets, if the pose carries any, are applied inside it.
+    const world = new Array<number>(attachment.worldVerticesLength).fill(0);
+    attachment.computeWorldVertices(skeleton, slot, 0, attachment.worldVerticesLength, world, 0, 2);
+    triangles = attachment.triangles;
+    piece = { kind: 'mesh', ...common, texture, world, uvs, triangles };
+  } else {
     const world = new Array<number>(8).fill(0);
     attachment.computeWorldVertices(slot, attachment.getOffsets(pose), world, 0, 2);
-    pieces.push({ kind: 'region', ...common, texture, world, uvs: attachment.sequence.getUVs(index) });
+    triangles = QUAD_TRIANGLES;
+    piece = { kind: 'region', ...common, texture, world, uvs };
   }
-  return pieces;
+  if (clipper === null || !clipper.isClipping()) return piece;
+  return clippedPiece(piece, triangles, uvs, clipper);
+}
+
+/**
+ * `piece` as the active clip leaves it, or `piece` itself when the clipper cut
+ * nothing — see `piecesOf`.
+ *
+ * The page UVs and the original-art UVs (`PieceTexture`, when the piece carries
+ * them) each go through their own `clipTrianglesUnpacked` call over the same
+ * vertices and triangles. The clipper's geometry depends on the positions alone
+ * and it interpolates a UV set barycentrically inside each source triangle, so
+ * the two calls cut the same polygons and each UV set lands on them — which is
+ * what lets `substituteTexture` re-seat a clipped piece exactly as it re-seats a
+ * whole one, through the drawing's own coordinates. The vertex count is compared
+ * all the same, because a clipped piece whose two UV sets disagreed on it would
+ * sample the wrong texels and say nothing.
+ */
+function clippedPiece(piece: Piece, triangles: number[], uvs: Float32Array, clipper: SkeletonClipping): Piece {
+  if (!clipper.clipTrianglesUnpacked(piece.world, 0, triangles, triangles.length, uvs, 2)) return piece;
+  const world = Array.from(clipper.clippedVerticesTyped);
+  const clippedUvs = Array.from(clipper.clippedUVsTyped);
+  const clipped = Array.from(clipper.clippedTrianglesTyped);
+  let texture = piece.texture;
+  if (texture !== undefined) {
+    clipper.clipTrianglesUnpacked(piece.world, 0, triangles, triangles.length, texture.artUvs, 2);
+    const artUvs = Array.from(clipper.clippedUVsTyped);
+    if (artUvs.length !== clippedUvs.length) {
+      throw new Error(
+        `slot "${piece.slot}": the clip cut ${clippedUvs.length / 2} vertices for the page UVs and ` +
+          `${artUvs.length / 2} for the original-art UVs over the same geometry`,
+      );
+    }
+    texture = { region: texture.region, artUvs };
+  }
+  const { tint, dark, slot, page } = piece;
+  return { kind: 'mesh', tint, dark, slot, page, texture, world, uvs: clippedUvs, triangles: clipped };
 }
 
 // ---------------------------------------------------------------------------
@@ -1227,8 +1343,12 @@ export function framingViewport(data: SkeletonData, maxSide: number, opts?: Pose
   // `--slot`/`--hide` leave out still counts toward the box, so a frame with a
   // part hidden lands on the pixel grid of the frame with it and the two overlay.
   // A subset framed to its own extent would move every pixel it kept.
+  //
+  // A clip is taken off for the same reason (issue #844): what it removes still
+  // counts toward the box, so adding or keying a mask moves no pixel it leaves
+  // drawn — see `PoseOptions.unclipped`.
   const { slots: _drawn, hidden: _hidden, ...whole } = opts ?? {};
-  const framed = opts === undefined ? undefined : whole;
+  const framed: PoseOptions = { ...whole, unclipped: true };
   const sets =
     data.animations.length === 0
       ? [sampleSetupPose(data, framed)]