spine-rigc 1.7.0 → 1.9.0

package/src/assertions/bodies/a08.ts

@@ -0,0 +1,76 @@
+/**
+ * A08, the body (issue #1025, step 4c of #380): every region an attachment
+ * resolves through is a region the atlas has, spelled exactly.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the atlas's
+ * region names and the skin entries' lookups are a fact
+ * (`../facts/region_joins.ts`) rather than a `TextureAtlas` built here and the
+ * raw JSON's walk. Why the rule runs before the round trip, and what A00 does
+ * about a miss it names, is argued above the `check` call in `validate()`,
+ * which stays there.
+ *
+ * `pathsWithNoRegion` is filled, not read: every lookup this body refuses for
+ * want of a region, which `validate()`'s A00 reads to defer to this rule rather
+ * than restate the miss. The model side hands a set nobody reads.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { RegionJoinFacts } from '../facts/region_joins.ts';
+import { SKIP_NO_ATTACHMENT_REGION_JOIN } from '../reasons.ts';
+
+export function a08RegionNamesMatchAttachments({ fail, skip }: Verdicts, facts: RegionJoinFacts, pathsWithNoRegion: Set<string>): void {
+  if (facts.regionNames === null) {
+    return skip(
+      'A08_REGION_NAMES_MATCH_ATTACHMENTS',
+      'the atlas text does not parse, so there are no region names to join against (A00 owns that failure)',
+    );
+  }
+  const regionNames = new Set(facts.regionNames);
+  if (facts.joins === null) {
+    return skip('A08_REGION_NAMES_MATCH_ATTACHMENTS', 'the skeleton JSON did not parse (A00 owns that failure)');
+  }
+  let joined = 0;
+  for (const join of facts.joins) {
+    // A `sequence` the walk will not guess at: say nothing rather than invent
+    // a region name. A00 still has the last word on it.
+    if (join.lookups === null) continue;
+    for (const lookup of join.lookups) {
+      joined++;
+      const at = `skin "${join.skin}" slot "${join.slot}" placeholder "${join.placeholder}"`;
+      const present = regionNames.has(lookup);
+      if (!present) pathsWithNoRegion.add(lookup);
+      if (lookup !== lookup.trim()) {
+        fail(
+          'A08_REGION_NAMES_MATCH_ATTACHMENTS',
+          `${at}: attachment "${join.name}" resolves through path ${JSON.stringify(lookup)}, which has stray ` +
+            `whitespace — the atlas is matched on the exact string, and ${
+              present
+                ? 'the region it finds carries the same padding'
+                : regionNames.has(lookup.trim())
+                  ? `the region this atlas has is ${JSON.stringify(lookup.trim())}, without it`
+                  : 'no region of this atlas carries it'
+            }`,
+        );
+      } else if (!present) {
+        // Not a guess and not a repair — a region the atlas DOES hold that
+        // differs from the wanted name only by case or padding. It is
+        // reported because it was measured, and where there is none the
+        // sentence says nothing at all.
+        const near = [...regionNames].find((r) => r.trim().toLowerCase() === lookup.toLowerCase());
+        fail(
+          'A08_REGION_NAMES_MATCH_ATTACHMENTS',
+          `${at}: attachment "${join.name}" wants region "${lookup}", which this atlas does not have${
+            near === undefined ? '' : ` — it does have ${JSON.stringify(near)}`
+          }. Either the skeleton's "path" or the atlas region name is the one that moved`,
+        );
+      }
+    }
+  }
+  for (const region of regionNames) {
+    if (region !== region.trim()) {
+      fail('A08_REGION_NAMES_MATCH_ATTACHMENTS', `atlas region ${JSON.stringify(region)} has stray whitespace`);
+    }
+  }
+  if (joined === 0 && regionNames.size === 0) {
+    return skip('A08_REGION_NAMES_MATCH_ATTACHMENTS', SKIP_NO_ATTACHMENT_REGION_JOIN);
+  }
+}

package/src/assertions/bodies/a11.ts

@@ -0,0 +1,15 @@
+/**
+ * A11, the body (issue #1025, step 4c of #380): no clipping attachment — the
+ * renderer skips them silently. A `renderer` rule, so `spine` never runs it.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the count is
+ * a fact (`../facts/skin_entries.ts`).
+ */
+import type { Verdicts } from '../harness.ts';
+import type { SkinEntryFacts } from '../facts/skin_entries.ts';
+
+export function a11NoClippingAttachments({ fail }: Verdicts, { clippingCount }: SkinEntryFacts): void {
+  if (clippingCount > 0) {
+    fail('A11_NO_CLIPPING_ATTACHMENTS', `${clippingCount} clipping attachment(s); the renderer skips them silently`);
+  }
+}

package/src/assertions/bodies/a13.ts

@@ -0,0 +1,51 @@
+/**
+ * A13, the body (issue #1025, step 4c of #380): the mesh slots and each mesh's
+ * triangles stay within the budget the rig declares.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the meshes
+ * are a fact (`../facts/skin_meshes.ts`) rather than the lists `validate()`'s
+ * prelude filled from spine-core's loaded skins, and the rig info is the
+ * caller's. Why the two budgets come from the rig and never from here stays
+ * above the `check` call in `validate()`.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { SkinMeshFacts } from '../facts/skin_meshes.ts';
+import { SKIP_NO_MESH_ATTACHMENT } from '../reasons.ts';
+import type { RigInfo } from '../../types.ts';
+
+export function a13MeshBudget({ fail, skip }: Verdicts, { meshes }: SkinMeshFacts, input: { rig?: RigInfo }): void {
+  const meshAttachments = meshes;
+  const meshSlots = new Set(meshes.map((mesh) => mesh.slot));
+  const slotBudget = input.rig?.meshSlotBudget ?? null;
+  const triangleBudget = input.rig?.meshTriangleBudget ?? null;
+  if (slotBudget === null && triangleBudget === null) {
+    return skip(
+      'A13_MESH_BUDGET',
+      input.rig
+        ? `the rig "${input.rig.archetype}" declares no \`invariants.meshSlots\` or \`invariants.meshTriangles\` budget`
+        : 'no rig info (validating a bare directory), so no budget is declared',
+    );
+  }
+  // Two clauses and only one of them has a subject that can vanish (#580).
+  // A slot budget is a ceiling on a COUNT, and zero is a count — "this rig
+  // uses 0 of its 3 mesh slots" is a measurement — so that half holds on a
+  // skeleton with no mesh. A triangle budget is a ceiling on each mesh, so a
+  // rig that declares only that one and carries no mesh has measured
+  // nothing at all.
+  if (slotBudget === null && meshAttachments.length === 0) {
+    return skip(
+      'A13_MESH_BUDGET',
+      `the rig "${input.rig?.archetype}" budgets mesh triangles and nothing else, and ${SKIP_NO_MESH_ATTACHMENT}`,
+    );
+  }
+  if (slotBudget !== null && meshSlots.size > slotBudget) {
+    fail('A13_MESH_BUDGET', `${meshSlots.size} mesh slots, the rig budgets ${slotBudget}`);
+  }
+  if (triangleBudget === null) return;
+  for (const mesh of meshAttachments) {
+    const tris = (mesh.triangles?.length ?? 0) / 3;
+    if (tris > triangleBudget) {
+      fail('A13_MESH_BUDGET', `mesh "${mesh.name}" has ${tris} triangles, the rig budgets ${triangleBudget}`);
+    }
+  }
+}

package/src/assertions/bodies/a14.ts

@@ -0,0 +1,35 @@
+/**
+ * A14, the body (issue #1025, step 4c of #380): no mesh spans the whole
+ * stage.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the meshes
+ * and the stage are facts (`../facts/skin_meshes.ts`, `../facts/stage.ts`)
+ * rather than spine-core's loaded skins and skeleton header. The `check` call
+ * stays in `validate()`.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { SkinMeshFacts } from '../facts/skin_meshes.ts';
+import type { StageFacts } from '../facts/stage.ts';
+
+export function a14NoFullFrameMesh({ fail, skip }: Verdicts, { meshes }: SkinMeshFacts, stage: StageFacts): void {
+  const meshAttachments = meshes;
+  const stageW = stage.width || 0;
+  const stageH = stage.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 (mesh.width >= stageW && mesh.height >= stageH) {
+      fail('A14_NO_FULL_FRAME_MESH', `mesh "${mesh.name}" spans the whole ${stageW}x${stageH} stage`);
+    }
+  }
+}

package/src/assertions/bodies/a15.ts

@@ -0,0 +1,97 @@
+/**
+ * A15, the body (issue #1025, step 4c of #380): `idle` keys no bone that
+ * drives a mesh, unless the rig declares that its idle deforms them.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the meshes
+ * and the bones that drive them are a fact (`../facts/skin_meshes.ts`) rather
+ * than spine-core's loaded skins and the weight run decoded here, the bones
+ * `idle` keys are a fact (`../facts/animated_bones.ts`) rather than the raw
+ * JSON, and the rig info is the caller's. Why the rule assumes meshes are
+ * mostly static, and why a painting rig may say otherwise, stays above the
+ * `check` call in `validate()`.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { MeshEntry, SkinMeshFacts } from '../facts/skin_meshes.ts';
+import type { AnimatedBoneFacts } from '../facts/animated_bones.ts';
+import type { RigInfo } from '../../types.ts';
+
+export function a15IdleNoMeshBoneKeys({ fail, skip }: Verdicts, { meshes }: SkinMeshFacts, animated: AnimatedBoneFacts, input: { rig?: RigInfo }): void {
+  const A15 = 'A15_IDLE_NO_MESH_BONE_KEYS';
+  /**
+   * Every mesh attachment, loaded, with the bones that drive it — its slot's
+   * bone, and, once weights exist, every bone its weights name. A ring mesh
+   * is driven by its CONTROL bone, a different bone from the slot's, and
+   * checking only the slot bone would let `idle` key the one bone that
+   * actually dirties the canvas every frame.
+   */
+  const meshDrivers: Array<{ mesh: MeshEntry; bones: Set<string> }> = [];
+  for (const mesh of meshes) {
+    const bones = new Set<string>([mesh.slotBone]);
+    for (const bone of mesh.weightBones) bones.add(bone);
+    meshDrivers.push({ mesh, bones });
+  }
+  const meshBoneNames = new Set<string>();
+  for (const { bones } of meshDrivers) for (const name of bones) meshBoneNames.add(name);
+  const declared = input.rig?.idleDrivesMeshes ?? null;
+  /**
+   * A declaration that switches off nothing is refused rather than skipped,
+   * the standard `consumerDrivenMix` is held to: an opt-out that exempts
+   * nothing reads exactly like one that worked, and the next reader cannot
+   * tell the rig that needs it from the rig it was copied onto.
+   */
+  const stale = (why: string): void => {
+    fail(
+      A15,
+      `the rig "${input.rig?.archetype}" declares invariants.idleDrivesMeshes ("${declared}"), but ${why}, so the ` +
+        'declaration switches off nothing — remove it',
+    );
+  };
+  // 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 idleBones = animated.bonesKeyedBy('idle');
+  if (idleBones === undefined) {
+    if (declared !== null) return stale('the skeleton declares no "idle" animation');
+    return skip(A15, 'the skeleton declares no "idle" animation, so nothing here can key a mesh-driving bone');
+  }
+  if (idleBones === null) {
+    if (declared !== null) return stale('"idle" carries no bone timeline at all');
+    return skip(A15, '"idle" carries no bone timeline at all, so there is no key to hold against the mesh-driving bones');
+  }
+  const keyed = idleBones.filter((name) => meshBoneNames.has(name));
+  if (declared !== null) {
+    if (keyed.length === 0) return stale('"idle" keys no bone that drives a mesh');
+    const keyedSet = new Set(keyed);
+    const moved = meshDrivers.filter(({ bones }) => [...bones].some((name) => keyedSet.has(name)));
+    // `worldVerticesLength` is two numbers per vertex whatever the encoding,
+    // which is the count the runtime recomputes; reading `vertices.length`
+    // would count a weighted mesh's bone entries instead.
+    const vertices = moved.reduce((sum, { mesh }) => sum + mesh.worldVerticesLength / 2, 0);
+    const SHOWN = 8;
+    const names =
+      keyed.slice(0, SHOWN).map((name) => `"${name}"`).join(', ') + (keyed.length > SHOWN ? ` +${keyed.length - SHOWN}` : '');
+    return skip(
+      A15,
+      `declared by the rig ("${declared}"): idle keys ${keyed.length} bone(s) that drive ${moved.length} mesh ` +
+        `attachment(s) totalling ${vertices} vertices — ${names} — and each of those meshes is recomputed on every ` +
+        'frame it is shown',
+    );
+  }
+  for (const [i, boneName] of keyed.entries()) {
+    // The case is named once, on the first line an agent reads, rather than
+    // after every bone: the first painting rig this met printed 42 of these,
+    // and 42 identical sentences read as 42 separate mistakes. It rides the
+    // first finding rather than being a finding of its own, so the count of
+    // FAIL lines is still the count of bones.
+    const hint =
+      i > 0
+        ? ''
+        : `. ${keyed.length} bone(s) keyed by idle drive meshes; if this idle is meant to deform them (a painting ` +
+          'rig), declare invariants.idleDrivesMeshes: { "why": … } in the rig spec — or, where the motion belongs to ' +
+          'a pivot above the mesh, key that pivot one link up (FACE.md §3)';
+    fail(A15, `idle keys bone "${boneName}", which drives a mesh — meshes never idle-skip${hint}`);
+  }
+}

package/src/assertions/bodies/a17.ts

@@ -0,0 +1,26 @@
+/**
+ * A17, the body (issue #1025, step 4c of #380): every page the atlas names is
+ * a file on disk, resolved against the directory the atlas sits in.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the pages are
+ * a fact (`../facts/atlas_pages.ts`), and the directory is the caller's. Why
+ * the guard is a SKIP and never a bare `return` (issues #568, #608) is argued
+ * above the `check` call in `validate()`, which stays there with A06 and A19.
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { Verdicts } from '../harness.ts';
+import type { AtlasPageFacts } from '../facts/atlas_pages.ts';
+import { SKIP_NO_ATLAS, SKIP_NO_ATLAS_PAGE } from '../reasons.ts';
+
+export function a17AtlasPageFilesExist({ fail, skip }: Verdicts, { atlas }: AtlasPageFacts, input: { atlasDir: string }): void {
+  if (!atlas) return skip('A17_ATLAS_PAGE_FILES_EXIST', SKIP_NO_ATLAS);
+  // The other absence, one ring in (#580): the atlas LOADED and declares no
+  // page, so there is no file to find missing. `!atlas` and "zero pages" print
+  // different reasons because they are different facts about the artifact.
+  if (atlas.pages.length === 0) return skip('A17_ATLAS_PAGE_FILES_EXIST', SKIP_NO_ATLAS_PAGE);
+  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}`);
+  }
+}

package/src/assertions/bodies/a19.ts

@@ -0,0 +1,295 @@
+/**
+ * A19, the body (issue #1025, step 4c of #380): every overlay part can draw a
+ * transparent pixel — only the base plate may be opaque.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the pages and
+ * regions are a fact (`../facts/atlas_regions.ts`), the stage is a fact
+ * (`../facts/stage.ts`), the region attachments are the skins' fact
+ * (`../facts/skin_entries.ts`), and the directory and the rig info are the
+ * caller's. Why transparency is not the same thing as an alpha channel (#215)
+ * stays above the `check` call in `validate()`.
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { Verdicts } from '../harness.ts';
+import type { AtlasRegionEntry, AtlasRegionFacts } from '../facts/atlas_regions.ts';
+import type { SkinEntryFacts } from '../facts/skin_entries.ts';
+import type { StageFacts } from '../facts/stage.ts';
+import { SKIP_NO_ATLAS, SKIP_NO_ATLAS_PAGE } from '../reasons.ts';
+import { pageFootprint } from '../../atlas.ts';
+import { colourTypeName, readPngHeader } from '../../png.ts';
+import { readPlate } from '../../../tools/plate.ts';
+import type { RigInfo } from '../../types.ts';
+
+export function a19OverlayPngsHaveAlpha({ fail, skip }: Verdicts, { atlas }: AtlasRegionFacts, stage: StageFacts, { regionAttachments }: Pick<SkinEntryFacts, 'regionAttachments'>, input: { atlasDir: string; rig?: RigInfo }): void {
+  // 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);
+  if (atlas.pages.length === 0) return skip('A19_OVERLAY_PNGS_HAVE_ALPHA', SKIP_NO_ATLAS_PAGE);
+  const stageW = stage.width ?? 0;
+  const stageH = stage.height ?? 0;
+  // 🔒 **Which image is the base plate is decided ONCE, and the rig's own
+  // statement decides it** (issue #770). A cut manifest names its base plate
+  // — the part whose window IS the crop — and that needs no stage box; the
+  // size of an attachment against the stage is read only when the build
+  // names none, because it is then the only statement there is (every build
+  // from a rig spec, and `validate <dir>`, which has no rig at all). Both
+  // routes below read the same two sets, so they cannot disagree about it.
+  //
+  // ⚠️ Before this, "at least the stage's size" was the only reading, and a
+  // stageless manifest rig came out with no base plate: the packed build was
+  // refused for its plate's opaque texels while the loose build of the same
+  // rig passed on the file's colour type. The order is a rule rather than a
+  // coincidence of the fixtures, where the two readings agree: a stage stated
+  // small enough for an overlay to "cover" is exactly where they part.
+  const named = input.rig?.basePlates ?? [];
+  const basePages = new Set<string>();
+  const baseRegions = new Set<string>();
+  const exempt = (name: string): void => {
+    const region = atlas.findRegion(name);
+    if (region) {
+      basePages.add(region.page.name);
+      baseRegions.add(region.name);
+    }
+  };
+  if (named.length > 0) {
+    for (const name of named) exempt(name);
+  } else {
+    for (const att of regionAttachments) {
+      if (stageW && stageH && att.width >= stageW && att.height >= stageH) exempt(att.path || att.name);
+    }
+  }
+  // The escape hatch is named the way it is reachable. With a base plate the
+  // rig names, that plate; with none but a stage, the size reading; and with
+  // neither, nothing here decides which image is the plate — so the sentence
+  // says what would, rather than pointing at a door that is not there.
+  const undecided =
+    'Only a base plate may be opaque, and nothing here decides which image that is: this skeleton declares no ' +
+    'stage size to measure one against, and ';
+  const exemption =
+    named.length > 0
+      ? `Only the base plate the rig names (${named.map((name) => JSON.stringify(name)).join(', ')}, the part ` +
+        "whose window is the cut manifest's crop) may be opaque."
+      : stageW && stageH
+        ? `Only the one image big enough to cover the whole stage (${stageW}x${stageH}) may be opaque.`
+        : input.rig
+          ? `${undecided}the build names no base plate. Either would decide it: give the rig spec a "skeleton" ` +
+            'stage the plate covers, or build from a cut manifest, whose base plate is the part whose window is ' +
+            'the crop.'
+          : `${undecided}no rig was given to name one. Either would decide it: state a "skeleton" stage the plate ` +
+            'covers, or validate with the specs it was built from (--rig, --motion and the --manifest, whose base ' +
+            'plate is the part whose window is the crop).';
+  // 🚨 Counted per page for the unpacked convention and per REGION on a shared
+  // page, and the split is not a convenience (issue #266, follow-up 2). A
+  // packed page's own file all but always declares transparency — the gutter
+  // and whatever is left over of the page are transparent — so the file-level
+  // question is answered "yes" by the packing itself, whatever the parts on it
+  // look like. Asking it that way once packs became gateable under this profile
+  // would have turned this assertion into a pass that measures nothing, which
+  // is the failure mode this file exists to prevent. So a shared page is opened
+  // and each region's own rectangle is measured instead.
+  const sharedPages = new Map<string, AtlasRegionEntry[]>();
+  for (const region of atlas.regions) {
+    const on = sharedPages.get(region.page.name);
+    if (on) on.push(region);
+    else sharedPages.set(region.page.name, [region]);
+  }
+  for (const page of atlas.pages) {
+    const abs = resolve(input.atlasDir, page.name);
+    if (!existsSync(abs)) continue;
+    const on = sharedPages.get(page.name) ?? [];
+    // 🔒 **A page that is not a PNG is a non-measurement for every part on
+    // it** (issue #732), stated the way #705's and #715's are: a FAIL naming
+    // what was not read, because `skip()` is per assertion and would delete
+    // the verdicts on every other page of the same report. The file's
+    // identity is `A06`'s to judge, and this sentence points there. A page
+    // holding nothing but the full-stage base plate has no part to judge and
+    // says nothing, exactly as a readable one would.
+    const header = readPngHeader(abs);
+    if (header.problem !== null) {
+      const shared = on.length > 1;
+      const parts = shared ? on.filter((region) => !baseRegions.has(region.name)).map((region) => region.name) : [];
+      if (shared ? parts.length === 0 : basePages.has(page.name)) continue;
+      const subject = shared
+        ? `the ${parts.length} part(s) on shared page "${page.name}" (${parts.map((name) => JSON.stringify(name)).join(', ')}) are`
+        : `part image "${page.name}" is`;
+      fail(
+        'A19_OVERLAY_PNGS_HAVE_ALPHA',
+        `${subject} not measured: this rule reads a page's alpha out of its PNG, and the file cannot be read as ` +
+          'one, so it states nothing about whether any of them can draw a transparent pixel. What the file is ' +
+          "belongs to A06_ATLAS_PAGE_SIZE_MATCHES_PNG, which names it. This is renderer policy, and it belongs to " +
+          '--profile spine-html: the default --profile spine does not run this check.',
+      );
+      continue;
+    }
+    if (on.length > 1) {
+      // 🚨 A rotated region is refused by A06 under this profile, so this
+      // reading was assumed to be cosmetic — a rectangle printed beside a
+      // failure already standing. It is not: the loop below OPENS the
+      // rectangle and stops at the first transparent texel, so a rectangle
+      // wider than the drawing runs into the transparent gutter, finds its
+      // texel there and names nothing. With the transpose applied at 90 only,
+      // two fully opaque parts on one page were measured green at
+      // `rotate: 270` and red at 0, 90 and 180 — this assertion's own verdict,
+      // flipped by the rotation it does not judge (issue #579). The footprint
+      // is `pageFootprint`'s, which every other reader of it now calls.
+      // 🚨 **The scan counts what it READ, and zero texels read is not a
+      // verdict** (issue #705). The `continue` above walks past every
+      // coordinate that is not on the page, so a rectangle none of whose
+      // texels are on it came out of this loop with `transparent` still
+      // false — indistinguishable from a solid drawing — and the sentence
+      // below then stated opacity over texels nobody had opened. Measured on
+      // a pack shaped like #707's: `part "block" is opaque in every one of
+      // its 12x8 texels`, over **0 of 96**, on art carrying 36 clear texels
+      // where it was packed. That is the message-as-UI defect in one line —
+      // the reader is sent to re-export a part whose alpha was never the
+      // problem, and the rectangle that is the problem belongs to A06.
+      //
+      // ⚠️ It is a FAIL rather than a SKIP, and the report's own shape
+      // decides that rather than taste. `skip()` is per ASSERTION, so
+      // skipping here would delete the verdicts on every other part of the
+      // page — on that same pack the second part is genuinely opaque and is
+      // named — and adding a skip BESIDE those failures puts A19 in two of
+      // the four buckets `reportLines` adds up, which prints `45 assertions`
+      // where the registry holds 44. What is left is a failure that says
+      // what was not measured, which is also what "green means measured"
+      // requires: a part this rule could not read must not be certified by
+      // it.
+      const plate = readPlate(abs);
+      // 🚨 **The scan's coordinates are the atlas's, so a file that is not the
+      // declared grid is a non-measurement for every region on it** (issue
+      // #715), and #705's clause above does not cover it. That one fires when
+      // a rectangle has NO texel on the page; a page whose image is a rescale
+      // of the declared size leaves most rectangles partly on it, at
+      // coordinates that address a different part of the picture. Measured on
+      // a two-region pack at a uniform 0.5: the opaque part's failure
+      // DISAPPEARED — the scan found a transparent texel 32 texels away from
+      // it and returned — while the other printed #705's sentence over 0 of
+      // 256 texels. A verdict and a silence, both about texels nobody located.
+      //
+      // A FAIL for #705's reason, word for word: `skip()` is per assertion and
+      // would delete the verdicts on every other page in the same report.
+      if (plate.width !== page.width || plate.height !== page.height) {
+        for (const region of on) {
+          if (baseRegions.has(region.name)) continue;
+          const { width, height } = pageFootprint(region);
+          fail(
+            'A19_OVERLAY_PNGS_HAVE_ALPHA',
+            `part "${region.name}" is not measured: this rule opens the page at the coordinates the atlas ` +
+              `states, and page "${page.name}" declares ${page.width}x${page.height} over a ` +
+              `${plate.width}x${plate.height} image, so the ${width}x${height} rectangle at ${region.x},` +
+              `${region.y} is not where "${region.name}"'s texels are on this file and this rule states ` +
+              'nothing about whether it can draw a transparent pixel. The page grid is ' +
+              "A06_ATLAS_PAGE_SIZE_MATCHES_PNG's to judge, and it names the ratio and how to declare the page " +
+              'honestly. This is renderer policy, and it belongs to --profile spine-html: the default ' +
+              '--profile spine does not run this check.',
+          );
+        }
+        continue;
+      }
+      for (const region of on) {
+        if (baseRegions.has(region.name)) continue;
+        const { width, height } = pageFootprint(region);
+        const declared = width * height;
+        let read = 0;
+        let transparent = false;
+        for (let y = region.y; y < region.y + height && !transparent; y++) {
+          for (let x = region.x; x < region.x + width; x++) {
+            if (x < 0 || y < 0 || x >= plate.width || y >= plate.height) continue;
+            read++;
+            if (plate.get(x, y)[3] < 255) {
+              transparent = true;
+              break;
+            }
+          }
+        }
+        if (transparent) continue;
+        // The page's size here is the DECODED image's and not the `size:`
+        // line's, because it is the bound this scan actually clipped
+        // against; where the two disagree A06 says so in its own sentence.
+        if (read === 0) {
+          fail(
+            'A19_OVERLAY_PNGS_HAVE_ALPHA',
+            `part "${region.name}" is not measured: this rule read 0 of the ${declared} texels of its ` +
+              `${width}x${height} rectangle at ${region.x},${region.y} on page "${page.name}", whose image is ` +
+              `${plate.width}x${plate.height}, so it states nothing about whether "${region.name}" can draw a ` +
+              "transparent pixel. A region's rectangle is A06_ATLAS_PAGE_SIZE_MATCHES_PNG's to judge, and one " +
+              'that runs off its page is refused there by name. This is renderer policy, and it belongs to ' +
+              '--profile spine-html: the default --profile spine does not run this check.',
+          );
+          continue;
+        }
+        // A rectangle partly on the page states the verdict over the texels
+        // it read and says how many of the declared ones that was. A whole
+        // rectangle prints the sentence it has always printed, to the byte.
+        const over =
+          read === declared
+            ? `every one of its ${width}x${height} texels on shared page "${page.name}"`
+            : `every one of the ${read} texels of its ${width}x${height} rectangle at ${region.x},${region.y} ` +
+              `that are on shared page "${page.name}", whose image is ${plate.width}x${plate.height} — the ` +
+              `other ${declared - read} of the ${declared} it declares are not on the page and are not ` +
+              'measured here';
+        fail(
+          'A19_OVERLAY_PNGS_HAVE_ALPHA',
+          `part "${region.name}" is opaque in ${over}, so it would paint a solid rectangle over whatever is ` +
+            `drawn behind it. Re-export the part with transparency and pack again. ${exemption} This is ` +
+            'renderer policy, and it belongs to --profile spine-html: the default --profile spine does not run ' +
+            'this check.',
+        );
+      }
+      continue;
+    }
+    const info = header.info;
+    if (basePages.has(page.name)) continue; // the base plate: opaque is correct
+    // The header is the FAST NEGATIVE and only that (#215's rule, unchanged):
+    // a colour type 0, 2 or 3 file with no tRNS chunk has nowhere to keep a
+    // transparent texel, so it is refused without opening it.
+    if (!info.hasTransparency) {
+      fail(
+        'A19_OVERLAY_PNGS_HAVE_ALPHA',
+        `part image "${page.name}" cannot be transparent anywhere: it is colour type ${info.colourType} ` +
+          `(${colourTypeName(info.colourType)}) with no tRNS chunk, so it would paint a solid rectangle over ` +
+          'whatever is drawn behind it. Re-export it with transparency — as RGBA, or as an indexed or greyscale ' +
+          `PNG that keeps its tRNS chunk. ${exemption} This is renderer policy, and it belongs to --profile ` +
+          'spine-html: the default --profile spine does not run this check.',
+      );
+      continue;
+    }
+    // 🚨 **A header that says "could be transparent" is not an answer, and
+    // the texels decide it exactly as they do on a shared page** (issue
+    // #777). Until this the loose route stopped here, so a part saved as
+    // RGBA passed whether or not any texel used the channel: on the
+    // articulated fixture, stageless, an overlay rewritten as colour type 6
+    // with 0 of its 16,000 texels below full alpha PASSED loose and was
+    // refused by `--pack` of the same rig, over the same texels. The runtime
+    // draws those texels, not the file's declaration, so the loose verdict
+    // was the false green. The rectangle is the whole decoded image — on a
+    // loose page the file IS the part, so no atlas coordinate is read and
+    // #705's and #715's non-measurements cannot arise here — and the scan
+    // stops at the first clear texel, as the shared page's does.
+    const plate = readPlate(abs);
+    let transparent = false;
+    for (let y = 0; y < plate.height && !transparent; y++) {
+      for (let x = 0; x < plate.width; x++) {
+        if (plate.get(x, y)[3] < 255) {
+          transparent = true;
+          break;
+        }
+      }
+    }
+    if (transparent) continue;
+    const holds = info.hasAlpha
+      ? `colour type ${info.colourType} (${colourTypeName(info.colourType)}) carries an alpha channel`
+      : `colour type ${info.colourType} (${colourTypeName(info.colourType)}) carries a tRNS chunk`;
+    fail(
+      'A19_OVERLAY_PNGS_HAVE_ALPHA',
+      `part image "${page.name}" is opaque in every one of its ${plate.width}x${plate.height} texels, so it ` +
+        `would paint a solid rectangle over whatever is drawn behind it: its file can hold transparency — ${holds} ` +
+        '— and no texel uses it. Re-export the part with the transparency it is meant to have. ' +
+        `${exemption} This is renderer policy, and it belongs to --profile spine-html: the default --profile ` +
+        'spine does not run this check.',
+    );
+  }
+}