spine-rigc 0.22.2 → 0.23.0

package/src/validate.ts

@@ -114,13 +114,19 @@ export const CLI_DEFAULT_PROFILE: ValidateProfile = 'spine';
  *   archetype — a structural rule about rigc's own formations, meaningless to a
  *               skeleton rigc did not compile.
  *
- * Three assertions are MIXED and are marked `validity` here because their
+ * Two assertions are MIXED and are marked `validity` here because their
  * validity half must never stop running; their policy clauses are gated inside
  * the assertion body against `profile`, and each such clause says so where it
  * lives. They are A06 (size-vs-PNG is validity; pma / rotation / full-page
- * coverage are policy), A08 (the attachment→region join is validity; requiring
- * the two names to be identical is policy) and A20 (weight coherence is
- * validity; requiring a mesh to be weighted at all is policy).
+ * coverage are policy) and A20 (weight coherence is validity; requiring a mesh
+ * to be weighted at all is policy).
+ *
+ * A08 was the third until issue #574 retired its policy clause. It required a
+ * skin entry's placeholder to be spelled like the region it resolves to, under
+ * a renderer that resolves art by `path` and has never read a placeholder — so
+ * restating it as the renderer's own join made it a tautology over the validity
+ * half. The argument, with the renderer lines it is measured against, sits above
+ * `check('A08_…')`.
  */
 const ASSERTION_KIND: Record<string, 'validity' | 'renderer' | 'archetype'> = {
   A00_ROUNDTRIP_PARSE: 'validity',
@@ -131,7 +137,7 @@ const ASSERTION_KIND: Record<string, 'validity' | 'renderer' | 'archetype'> = {
   A05_CURVE_ARRAY_LENGTH: 'validity',
   A06_ATLAS_PAGE_SIZE_MATCHES_PNG: 'validity', // mixed — see above
   A07_ATLAS_TEXT_SHAPE: 'validity',
-  A08_REGION_NAMES_MATCH_ATTACHMENTS: 'validity', // mixed — see above
+  A08_REGION_NAMES_MATCH_ATTACHMENTS: 'validity', // no longer mixed — see above (#574)
   A09_ANIMATION_DURATION_MATCHES_SPEC: 'validity',
   A10_NO_NAN_AFTER_STEPPING: 'validity',
   A11_NO_CLIPPING_ATTACHMENTS: 'renderer',
@@ -183,6 +189,22 @@ export function assertionCountForProfile(profile: ValidateProfile): number {
   return ASSERTION_NAMES.filter((name) => ASSERTION_KIND[name] === 'validity').length;
 }
 
+/**
+ * What a SKIP says when `A00_ROUNDTRIP_PARSE` handed an assertion nothing to
+ * look at.
+ *
+ * Two of them rather than one, because what an assertion was denied is the whole
+ * content of its SKIP: `A20` wanted the loaded skeleton and `A06` wanted the
+ * loaded atlas, and a reader who is told which can tell a rule that is waiting
+ * on the parse from one that is waiting on the art. Both point at A00 instead of
+ * restating its detail, which the FAIL row prints in full.
+ *
+ * Exported so a control compares against them rather than quoting them — the
+ * same reason `ASSERTION_NAMES` is exported.
+ */
+export const SKIP_NO_SKELETON = 'the round trip did not produce a skeleton to measure (A00 owns that failure)';
+export const SKIP_NO_ATLAS = 'the round trip did not produce an atlas to measure (A00 owns that failure)';
+
 export interface ValidateInput {
   skeletonText: string;
   atlasText: string;
@@ -1282,8 +1304,20 @@ export function validate(input: ValidateInput): ValidateReport {
     check('A14_NO_FULL_FRAME_MESH', () => {
       const stageW = data.width || 0;
       const stageH = data.height || 0;
+      // ⚠️ A stage-less skeleton has nothing for a mesh to span, and this rule
+      // used to report that as a PASS — the `stageW && stageH` guard below reads
+      // as a measurement of a 0x0 stage that no mesh can reach. It was only ever
+      // reachable from a foreign file until a rig spec could *declare* no stage
+      // (issue #578), and a pass certifying an unmeasured rig is the exact
+      // failure mode `A21_MESH_RIM_PINNED`'s `|| 'ring'` default was (#44).
+      if (!stageW || !stageH) {
+        return skip(
+          'A14_NO_FULL_FRAME_MESH',
+          'the skeleton declares no stage size, so there is no full frame for a mesh to span',
+        );
+      }
       for (const mesh of meshAttachments) {
-        if (stageW && stageH && mesh.width >= stageW && mesh.height >= stageH) {
+        if (mesh.width >= stageW && mesh.height >= stageH) {
           fail('A14_NO_FULL_FRAME_MESH', `mesh "${mesh.name}" spans the whole ${stageW}x${stageH} stage`);
         }
       }
@@ -1307,8 +1341,19 @@ export function validate(input: ValidateInput): ValidateReport {
           }
         }
       }
+      // The same shape as A06's and A17's guards, found by auditing for it
+      // (#568): a rig with no `idle` at all has nothing here to be wrong, and a
+      // rule that reports "held" over a subject that does not exist is the
+      // vacuous pass this file's own doctrine refuses. The two states get their
+      // own sentences because they are different absences — no such animation,
+      // versus one that keys no bone.
       const idle = isObj(raw?.animations) ? (raw.animations as Json).idle : undefined;
-      if (!isObj(idle) || !isObj(idle.bones)) return;
+      if (!isObj(idle)) {
+        return skip('A15_IDLE_NO_MESH_BONE_KEYS', 'the skeleton declares no "idle" animation, so nothing here can key a mesh-driving bone');
+      }
+      if (!isObj(idle.bones)) {
+        return skip('A15_IDLE_NO_MESH_BONE_KEYS', '"idle" carries no bone timeline at all, so there is no key to hold against the mesh-driving bones');
+      }
       for (const boneName of Object.keys(idle.bones as Json)) {
         if (meshBoneNames.has(boneName)) {
           fail('A15_IDLE_NO_MESH_BONE_KEYS', `idle keys bone "${boneName}", which drives a mesh — meshes never idle-skip`);
@@ -2486,7 +2531,46 @@ export function validate(input: ValidateInput): ValidateReport {
       stats.skinMembers = listed;
     });
 
-    // --- A08: region names exact-match attachment names --------------------
+    // --- A08: every attachment's path resolves to a region the atlas has ---
+    //
+    // 🗑️ A08 used to be MIXED: the join above is validity, and a second clause
+    // gated on `spine-html` required the skin entry's PLACEHOLDER to be spelled
+    // exactly like the region it resolves to ("v0 requires them identical").
+    // That clause is retired (issue #574), and the reason is that the renderer
+    // it was profiled under never performed the join it described.
+    //
+    // `spine-html@0.4.1` resolves art in two steps and the placeholder is in
+    // neither. `DomTexture.js:78,102` builds the image map with
+    // `put(atlasRegion.name, …)` over every region of the atlas, and
+    // `SpineHtmlRenderer.js:172` reads it back as
+    // `const regionImage = region && this.regionImages.get(region.name)`, where
+    // `region` came off the attachment — which `AtlasAttachmentLoader` resolved
+    // through `path`. Every published version of that renderer keys the same way
+    // (checked 0.1.0 through 0.4.1, the whole series). Nothing in it reads an
+    // attachment's name, let alone its placeholder.
+    //
+    // ⇒ Restated as the join the renderer actually performs, the clause compares
+    // `path` against the region `path` resolved — a tautology, and the same
+    // string the validity check above already requires the atlas to hold. An
+    // assertion that cannot fail is not a gate, so it is removed rather than
+    // kept as a duplicate.
+    //
+    // ⚠️ It was not merely inert, either: it refused rigs on both sides of the
+    // convention it was written for. `path` exists precisely so a placeholder
+    // may differ from the PNG basename (R5), and since issue #567 a placeholder
+    // two named skins share is emitted as `<skin>/<placeholder>` with `path`
+    // restated to the basename — the only spelling the Spine editor holds. Under
+    // the old clause that shape, and any rig that merely named a part something
+    // other than its placeholder, was red under `spine-html` while the editor
+    // imported it and the renderer drew it.
+    //
+    // 📏 What is left, measured rather than assumed: only the LAST loop can
+    // fire. Both attachment-join clauses are preempted by the loader —
+    // `AtlasAttachmentLoader.findRegion` throws
+    // `Region not found in atlas: <path> (attachment: <name>)` for a path that
+    // names no region and for one padded with whitespace alike, so A00 reports
+    // it and A08 never runs. `PS90` is the mutant for the loop that does fire,
+    // and it is the first mutant this assertion has ever had.
     check('A08_REGION_NAMES_MATCH_ATTACHMENTS', () => {
       const regionNames = new Set(atlas!.regions.map((r) => r.name));
       for (const skin of data.skins) {
@@ -2500,16 +2584,6 @@ export function validate(input: ValidateInput): ValidateReport {
           if (!regionNames.has(lookup)) {
             fail('A08_REGION_NAMES_MATCH_ATTACHMENTS', `attachment "${entry.placeholder}" wants region "${lookup}", which the atlas does not have`);
           }
-          // 📐 PROFILE. That the join RESOLVES is validity — an attachment
-          // pointing at a region the atlas does not have is a hole in the rig
-          // whoever loads it. That the two names are IDENTICAL is rigc's v0
-          // policy: it holds because a region name IS the PNG basename here, and
-          // rigc's own packer keeps it that way (issue #4), while a foreign
-          // packer renames regions by design (spineboy's `path` differs from its
-          // placeholder in 26 attachments).
-          if (policy && entry.placeholder !== lookup) {
-            fail('A08_REGION_NAMES_MATCH_ATTACHMENTS', `attachment "${entry.placeholder}" resolves to region "${lookup}"; v0 requires them identical`);
-          }
         }
       }
       for (const region of atlas!.regions) {
@@ -2620,15 +2694,26 @@ export function validate(input: ValidateInput): ValidateReport {
   // --- A06 / A17 / A19: the atlas against the PNGs on disk ------------------
   // Case 6h: a `size:` that disagrees with the file loads fine and collapses
   // every UV — rigid stays correct, meshes sample a corner scrap.
+  //
+  // 🚨 The guard is a SKIP and never a bare `return` (issue #568). A `return`
+  // inside `check()` leaves the failure count and the skip count where they
+  // were, which is precisely how that function decides an assertion PASSED — so
+  // for as long as this line read `if (!atlas) return;` a candidate whose atlas
+  // the round trip could not load was reported green by the two rules whose only
+  // subject IS the atlas. It was measured on a fixture carrying a page that
+  // declares twice the size of its PNG, the exact defect A06 names when the
+  // parse succeeds: with a region also removed so the round trip threw, A06
+  // printed `PASS`. Everything below reads `atlas.pages`, so a report of "held"
+  // here is a report about zero pages.
   check('A17_ATLAS_PAGE_FILES_EXIST', () => {
-    if (!atlas) return;
+    if (!atlas) return skip('A17_ATLAS_PAGE_FILES_EXIST', SKIP_NO_ATLAS);
     for (const page of atlas.pages) {
       const abs = resolve(input.atlasDir, page.name);
       if (!existsSync(abs)) fail('A17_ATLAS_PAGE_FILES_EXIST', `page "${page.name}" is not on disk at ${abs}`);
     }
   });
   check('A06_ATLAS_PAGE_SIZE_MATCHES_PNG', () => {
-    if (!atlas) return;
+    if (!atlas) return skip('A06_ATLAS_PAGE_SIZE_MATCHES_PNG', SKIP_NO_ATLAS);
     for (const page of atlas.pages) {
       const abs = resolve(input.atlasDir, page.name);
       if (!existsSync(abs)) continue; // A17 owns this
@@ -2667,8 +2752,12 @@ export function validate(input: ValidateInput): ValidateReport {
     // overlapping rectangles put one drawing inside another's.
     //
     // ⚠️ Rotation stays refused either way, and that is not the same clause: it
-    // is about rigc's own packer never turning a region, and `extractRegion`
-    // refusing to read one back.
+    // is about rigc's own packer never turning a region, which is a statement
+    // about what rigc WRITES. It stopped being a statement about what rigc can
+    // read in issue #570 — `extractRegion` now lifts a rotated region back off
+    // its page as a transcription of `MeshAttachment.computeUVs` — and the two
+    // must not be re-merged: an artifact under the renderer's own rulebook that
+    // rigc did not pack is still a foreign artifact, whatever rigc can measure.
     const regionsPerPage = new Map<string, TextureAtlasRegion[]>();
     for (const region of atlas.regions) {
       const on = regionsPerPage.get(region.page.name);
@@ -2745,7 +2834,11 @@ export function validate(input: ValidateInput): ValidateReport {
   // that does not ask — the reader opted in, and the message is where they find
   // out what they opted into.
   check('A19_OVERLAY_PNGS_HAVE_ALPHA', () => {
-    if (!atlas) return;
+    // A SKIP for the same reason A06's is (#568). This one is invisible under
+    // `spine`, where the profile excludes the rule before its body runs — and
+    // that is exactly why it was worth finding: `--profile spine-html` reported
+    // it, and A27 below, green on an atlas nothing had read.
+    if (!atlas) return skip('A19_OVERLAY_PNGS_HAVE_ALPHA', SKIP_NO_ATLAS);
     const stageW = skeletonData?.width ?? 0;
     const stageH = skeletonData?.height ?? 0;
     const basePages = new Set<string>();
@@ -2941,14 +3034,24 @@ export function validate(input: ValidateInput): ValidateReport {
     }
   });
 
-  // --- A26: draw order matches the rig's slot table ------------------------
+  // --- A26: the slots array IS the rig's slot table ------------------------
   //
   // The slots array IS the draw order (z-index = array index), so a formation
   // whose illusion depends on one part occluding another depends on one
   // adjacency in that array — and nothing in the file objects to the wrong
   // order. On a still frame it can even look plausible. The rig's own slot list
-  // is the canonical table; a cut that fills only some of those slots emits a
-  // SUBSEQUENCE of it, which is what this checks.
+  // is the canonical table, and this checks the emitted array against it in
+  // both directions: nothing out of order, and nothing missing.
+  //
+  // ⚠️ The second half is new with issue #575 and the first half is why it had
+  // to be. This clause used to accept any SUBSEQUENCE of the table, because the
+  // compiler dropped a slot no skin filled and the gate was written around that
+  // — so the defect #575 filed was licensed by the assertion that was supposed
+  // to catch it: two production exports declaring 53 and 61 slots built green
+  // at 51 and 57. `compile` now emits every declared slot, empty if nothing
+  // fills it, so a shorter array is a loss and is named as one here. A slot
+  // missing from the array moves every slot below it up one index, which is
+  // what a `drawOrder` key's offsets are counted against.
   check('A26_SLOT_DRAW_ORDER', () => {
     if (!input.rig) return skip('A26_SLOT_DRAW_ORDER', 'no rig info (validating a bare directory)');
     const order = input.rig.slotOrder;
@@ -2976,6 +3079,17 @@ export function validate(input: ValidateInput): ValidateReport {
       }
       at = found + 1;
     }
+    const emitted = new Set(names);
+    const missing = order.filter((name) => !emitted.has(name));
+    if (missing.length > 0) {
+      fail(
+        'A26_SLOT_DRAW_ORDER',
+        `the rig "${input.rig.archetype}" declares ${order.length} slot(s) and the skeleton has ${names.length}: ` +
+          `${missing.map((name) => `"${name}"`).join(', ')} ${missing.length === 1 ? 'is' : 'are'} declared and ` +
+          'not emitted. A slot nothing fills is emitted with no setup attachment, not dropped — dropping one ' +
+          'moves every slot below it up one index',
+      );
+    }
   });
 
   // --- A27: region name == the PNG's basename ------------------------------
@@ -2987,7 +3101,7 @@ export function validate(input: ValidateInput): ValidateReport {
   // would load with the wrong pixels under the right name. One part per page (A06
   // forces it) makes the check exact.
   check('A27_REGION_NAME_MATCHES_PAGE_FILENAME', () => {
-    if (!atlas) return;
+    if (!atlas) return skip('A27_REGION_NAME_MATCHES_PAGE_FILENAME', SKIP_NO_ATLAS);
     const perPage = new Map<string, number>();
     for (const region of atlas.regions) perPage.set(region.page.name, (perPage.get(region.page.name) ?? 0) + 1);
     for (const region of atlas.regions) {
@@ -3173,6 +3287,52 @@ export function validate(input: ValidateInput): ValidateReport {
     }
   });
 
+  // --- every assertion leaves a row ----------------------------------------
+  //
+  // 🔒 **A missing row is the vacuous pass one level up** (issue #568). Twenty
+  // assertions live inside `if (skeletonData) {` above, so a round trip that
+  // throws does not skip them — it never reaches them, and they appear in none
+  // of the four lists. Measured on a fixture whose atlas was missing a region
+  // the skeleton names: 13 of 42 printed a verdict, 9 more printed `PROF`, and
+  // 20 printed nothing at all. The run exits 1 and the reader is right to fix
+  // A00 first, which is exactly why the silence survives — nobody counts the
+  // rows on a red run. A report that names 22 of 42 and says nothing about the
+  // rest is telling a reader that those rules are fine, in the only way a
+  // report can: by not mentioning them.
+  //
+  // ⚠️ The sweep DERIVES its list rather than keeping one, because a hand-kept
+  // roster of "assertions behind the round trip" is a second place to update
+  // and would be wrong the first time somebody moved a `check` call. Anything
+  // `ASSERTION_NAMES` knows that reached here with no row did not run, and what
+  // it is honest to say about it is decided by the state:
+  //
+  //   * the profile does not carry that kind of rule — `PROF`, the same verdict
+  //     `check()`'s own guard would have recorded had the call been reached;
+  //   * the round trip produced nothing — `SKIP`, naming that;
+  //   * anything else — a FAIL, **by name**. An assertion that vanished while
+  //     the skeleton was loaded is a defect in this file, and inventing a SKIP
+  //     for it would be the same silence one ring further out. The one state
+  //     the sweep is allowed to explain is the one it can prove.
+  const reported = new Set<string>([
+    ...passed,
+    ...failures.map((f) => f.assertion),
+    ...skipped.map((s) => s.assertion),
+    ...profileSkipped.map((p) => p.assertion),
+  ]);
+  for (const name of ASSERTION_NAMES) {
+    if (reported.has(name)) continue;
+    const kind = ASSERTION_KIND[name];
+    if (kind !== 'validity' && !policy) profileSkipped.push({ assertion: name, kind });
+    else if (!roundTrip) skip(name, SKIP_NO_SKELETON);
+    else {
+      fail(
+        name,
+        'the assertion left no row: its body was never reached, and the round trip that would explain that ' +
+          'succeeded. A guard above returned before the call — find it and make it a SKIP naming what was absent',
+      );
+    }
+  }
+
   return { failures, passed, skipped, profileSkipped, profile, stats };
 }
 
@@ -3273,6 +3433,24 @@ export function reportLines(report: ValidateReport): string[] {
   for (const s of report.skipped) lines.push(`  SKIP  ${s.assertion}: ${s.reason}`);
   for (const p of report.profileSkipped) lines.push(`  PROF  ${p.assertion}: ${p.kind} rule, not in profile "${report.profile}"`);
   for (const f of report.failures) lines.push(`  FAIL  ${f.assertion}: ${f.detail}`);
+  // How many of them MEASURED anything, which is the figure the rows above do
+  // not hand a reader (issue #568). Counting `PASS` lines answers a different
+  // question — before the sweep that closed #568 a run could print seven of
+  // them over a candidate on which five rules had not executed at all.
+  //
+  // ⚠️ Every figure here is a count of ASSERTIONS and not of rows, which is why
+  // the failed side is a Set: `fail()` is called once per finding, so one
+  // assertion can print six `FAIL` lines, and a line-count would report 47 of
+  // 42. The four buckets partition `ASSERTION_NAMES`, so the total is derived
+  // by adding them rather than stated — a `42` written here would be the one
+  // number in the report that no run could contradict.
+  const failed = new Set(report.failures.map((f) => f.assertion));
+  const measured = report.passed.length + failed.size;
+  const total = measured + report.skipped.length + report.profileSkipped.length;
+  lines.push(
+    `  ..    ${total} assertions: ${measured} measured (${report.passed.length} passed, ${failed.size} failed), ` +
+      `${report.skipped.length} skipped, ${report.profileSkipped.length} not in profile "${report.profile}"`,
+  );
   return lines;
 }
 

package/tools/editor_roundtrip.ts

@@ -2,8 +2,9 @@
  * The editor round trip, as a tool (issue #374).
  *
  * `build` → import into the Spine editor → export back to JSON → gate, `diff`,
- * `render` and `check` the export against the build it came from. It is the one
- * measurement that answers *"does the editor accept what rigc wrote, and does
+ * `render` and `check` the export against the build it came from — the last two
+ * **once per skin the build declares** (issue #571; see `skinBlocks`). It is the
+ * one measurement that answers *"does the editor accept what rigc wrote, and does
  * what comes back still play the same"*, and on its first run it found three
  * emitter defects (#368 `hull`/`edges`, #369 hold curves, #370
  * `skeleton.images`) before proving that a human edit survives the trip.
@@ -383,6 +384,123 @@ function checkFigures(reportPath: string): string[] {
   );
 }
 
+/**
+ * The largest per-animation `meanMae` in one check report, or `null` when there
+ * is no report to read one from.
+ *
+ * ⚠️ `check`'s exit code is not a verdict — there is no pass mark in it, by
+ * design, any more than there is one in `diff` — so a per-skin roll-up built on
+ * exit codes alone reports every skin as fine and reports it in the column a
+ * reader looks at. This is the figure that actually moves when one skin's art
+ * comes back wrong, which is what makes the roll-up a roll-up (issue #571).
+ */
+function worstMeanMae(reportPath: string): number | null {
+  if (!existsSync(reportPath)) return null;
+  const report = JSON.parse(readFileSync(reportPath, 'utf8')) as { animations?: Array<{ meanMae?: number }> };
+  const values = (report.animations ?? []).map((a) => a.meanMae).filter((v): v is number => typeof v === 'number');
+  return values.length === 0 ? null : Math.max(...values);
+}
+
+// ---------------------------------------------------------------------------
+// step 5's per-skin plan (issue #571)
+// ---------------------------------------------------------------------------
+//
+// 🚨 Step 5 used to render and check ONCE, with no skin, which draws the default
+// skin and nothing else. On a rig whose named skins carry the contested art that
+// is a comparison of blank against blank: the ninth round trip read `check`
+// 0.0000 on a rig where the construct under test lives in a named skin, and the
+// zero was true and empty at once. So the plan below is one block PER DECLARED
+// SKIN, and a skin whose art the editor moved is a red row with its own name on
+// it rather than a figure nobody rendered.
+//
+// ⭐ Split out as pure functions for the reason `shapeOf`/`shapeDiff` are: the
+// `ERT` suite has no editor and never will, and a loop that can only be read by
+// driving one is a loop nobody has seen work.
+
+/**
+ * The skins a skeleton file declares, in the order the file lists them.
+ *
+ * ⚠️ Off the FILE rather than off `spine-core`: this is the build's own
+ * `skeleton.json`, read before any of it is loaded, and the tool's other summary
+ * (`shapeOf`) reads the same file the same way. A skeleton with no `skins` array
+ * at all comes back empty, which is a different fact from `["default"]` and is
+ * carried as one — see `skinBlocks`.
+ */
+export function skinsDeclaredBy(path: string): string[] {
+  const parsed = JSON.parse(readFileSync(path, 'utf8')) as { skins?: Array<{ name?: unknown }> };
+  const out: string[] = [];
+  for (const skin of parsed.skins ?? []) {
+    // A skin with no usable name is counted under one rather than dropped: a
+    // block that vanished would be a skin nobody rendered and nobody missed.
+    out.push(typeof skin?.name === 'string' && skin.name !== '' ? skin.name : '(unnamed)');
+  }
+  return out;
+}
+
+/** One render-and-check block of step 5: which skin, where its frames go. */
+export interface SkinBlock {
+  /** The skin this block poses under — `null` when the skeleton declares none. */
+  skin: string | null;
+  /** The heading printed above the block, which is where the skin's name is read. */
+  heading: string;
+  /** `--skin <name>`, or nothing at all when there is no skin to name. */
+  args: string[];
+  buildFrames: string;
+  exportFrames: string;
+  checkJson: string;
+}
+
+/**
+ * A directory name for one skin's frames: its index, then what of its name is a
+ * filename.
+ *
+ * The index leads because **a skin name is not a path**. The Spine editor writes
+ * folders into skin names with `/`, so `goblins/green` would land two levels
+ * down or collide with a sibling, and any scheme that replaces the offending
+ * characters can map two distinct skins onto one directory. The index cannot
+ * collide, and it is the skeleton's own ordering rather than a number invented
+ * here.
+ */
+function skinDirName(name: string, index: number): string {
+  return `${index}-${name.replace(/[^A-Za-z0-9._-]+/g, '_')}`;
+}
+
+/**
+ * Step 5's plan: one block per declared skin, or exactly one block when the
+ * skeleton declares no skin at all.
+ *
+ * ⭐ The no-skin case keeps the old paths (`render-build`, `render-export`,
+ * `check.json`) because for such a skeleton there is nothing to distinguish, and
+ * a run whose output moved would be a run whose ledgers all have to be re-read
+ * for no measurement gained. A skinned skeleton files each block under its own
+ * directory, so the frames of two skins can never overwrite each other — which
+ * is the failure that would turn "one block per skin" back into one block.
+ */
+export function skinBlocks(skins: string[], out: string, fps: number): SkinBlock[] {
+  if (skins.length === 0) {
+    return [
+      {
+        skin: null,
+        heading: `## 5 render both @${fps}fps, check the export against the build's own frames (no skin declared)`,
+        args: [],
+        buildFrames: join(out, 'render-build'),
+        exportFrames: join(out, 'render-export'),
+        checkJson: join(out, 'check.json'),
+      },
+    ];
+  }
+  return skins.map((skin, i) => ({
+    skin,
+    heading:
+      `## 5.${i + 1}/${skins.length} skin "${skin}" — render both @${fps}fps, check the export against the ` +
+      "build's own frames",
+    args: ['--skin', skin],
+    buildFrames: join(out, 'render-build', skinDirName(skin, i)),
+    exportFrames: join(out, 'render-export', skinDirName(skin, i)),
+    checkJson: join(out, `check-${skinDirName(skin, i)}.json`),
+  }));
+}
+
 /** The shape of a skeleton file, for the field-by-field comparison. */
 export interface Shape {
   spine: string;
@@ -719,18 +837,48 @@ function main(): void {
   // console layout for them would break the first time that layout is tidied.
   for (const line of movedMeasures(diffJson)) emit(`  ${line}`);
 
-  emit('');
-  emit(`## 5 render both @${opts.fps}fps, check the export against the build's own frames`);
-  run(rigc.cmd, [...rigc.prefix, 'render', '--candidate', opts.build, '--fps', String(opts.fps), '--out', join(opts.out, 'render-build')], 900);
-  run(rigc.cmd, [...rigc.prefix, 'render', '--candidate', cand, '--fps', String(opts.fps), '--out', join(opts.out, 'render-export')], 900);
-  const check = run(
-    rigc.cmd,
-    [...rigc.prefix, 'check', '--candidate', cand, '--frames', join(opts.out, 'render-build'), '--json', join(opts.out, 'check.json')],
-    900,
-  );
-  emit(`  exit=${check.status}`);
-  for (const line of verdictLines(check.stdout)) emit(`  ${line}`);
-  for (const line of checkFigures(join(opts.out, 'check.json'))) emit(`  ${line}`);
+  // 🔒 The skins come off the BUILD, which is the side under test: a skin the
+  // export dropped altogether then reads as a block whose check fails by name,
+  // where enumerating the export's own skins would quietly stop looking for it.
+  const blocks = skinBlocks(skinsDeclaredBy(source), opts.out, opts.fps);
+  const checks: Array<{ skin: string | null; status: number | null; mae: number | null }> = [];
+  for (const block of blocks) {
+    emit('');
+    emit(block.heading);
+    run(rigc.cmd, [...rigc.prefix, 'render', '--candidate', opts.build, '--fps', String(opts.fps), ...block.args, '--out', block.buildFrames], 900);
+    run(rigc.cmd, [...rigc.prefix, 'render', '--candidate', cand, '--fps', String(opts.fps), ...block.args, '--out', block.exportFrames], 900);
+    const check = run(
+      rigc.cmd,
+      [...rigc.prefix, 'check', '--candidate', cand, '--frames', block.buildFrames, ...block.args, '--json', block.checkJson],
+      900,
+    );
+    emit(`  exit=${check.status}`);
+    for (const line of verdictLines(check.stdout)) emit(`  ${line}`);
+    for (const line of checkFigures(block.checkJson)) emit(`  ${line}`);
+    checks.push({ skin: block.skin, status: check.status, mae: worstMeanMae(block.checkJson) });
+  }
+  // The roll-up, so a loss in one skin of many is a line somebody reads rather
+  // than a row buried in the block above it. The mark is on the LARGEST figure
+  // and only where the skins disagree: `check` has no pass mark to compare
+  // against and this tool does not get to invent one, but "these skins did not
+  // come back the same" is a fact the run itself produced.
+  if (blocks.length > 1) {
+    const figures = checks.map((c) => c.mae).filter((v): v is number => v !== null);
+    const worst = figures.length === 0 ? null : Math.max(...figures);
+    const agreed = figures.length === checks.length && new Set(figures).size === 1;
+    emit('');
+    emit(`  per skin  ${checks.length} block(s)`);
+    for (const { skin, status, mae } of checks) {
+      emit(
+        `    ${String(skin).padEnd(20)} check exit=${status}  worst mean MAE ` +
+          `${mae === null ? '(no report)' : mae.toFixed(4)}` +
+          `${status === 0 ? '' : '   ⚠️ this skin did not come back'}` +
+          `${!agreed && mae !== null && mae === worst ? `   ⚠️ the worst of the ${checks.length} skins` : ''}`,
+      );
+    }
+    if (agreed) emit(`    ⤷ every skin came back at the same figure, so no skin is carrying a difference the others are not.`);
+  }
+  const checksClean = checks.every((c) => c.status === 0);
 
   emit('');
   emit('## 6 what the editor rewrote');
@@ -741,15 +889,18 @@ function main(): void {
   keepLog();
   emit('');
   emit(`log: ${logPath}`);
-  // The verdict is the gate's and the check's, not this tool's opinion of them.
-  process.exit(gate.status === 0 && check.status === 0 ? 0 : 1);
+  // The verdict is the gate's and EVERY skin's check, not this tool's opinion of
+  // them: one skin coming back wrong is the whole run coming back wrong, which
+  // is the half a single un-skinned check could not say.
+  process.exit(gate.status === 0 && checksClean ? 0 : 1);
 }
 
-// ⭐ Guarded so `shapeOf` and `shapeDiff` can be READ by a control that has no
-// editor (issue #561). Every other `ERT` case drives this file as a subprocess,
-// which is the right shape for a refusal; step 6's summary is a pure function of
-// two skeleton files, and driving an editor — or four rigc subcommands — to
-// reach it would be paying for a round trip to test arithmetic. Run as a
+// ⭐ Guarded so `shapeOf`, `shapeDiff`, `skinsDeclaredBy` and `skinBlocks` can be
+// READ by a control that has no editor (issues #561, #571). Every other `ERT`
+// case drives this file as a subprocess, which is the right shape for a refusal;
+// step 6's summary is a pure function of two skeleton files and step 5's plan is
+// a pure function of one, and driving an editor — or four rigc subcommands — to
+// reach either would be paying for a round trip to test arithmetic. Run as a
 // program this is unchanged: `bun tools/editor_roundtrip.ts …` makes this module
 // the entry, so `import.meta.main` is true.
 if (import.meta.main) main();