rig-c 0.0.0-stage → 2.20.4

package/src/assertions/bodies/a47.ts

@@ -0,0 +1,126 @@
+/**
+ * A47, the body (issue #1025, step 4c of #380): an ik constraint muted for
+ * good — resting at mix 0 with no animation switching it on — is refused,
+ * unless the rig declares that the consumer drives its mix.
+ *
+ * The question A23, A36 and A37 ask of their own kinds, asked of the kind
+ * editor exports use most (issue #765): a constraint that rests muted and
+ * that no animation switches on parses, sits in the update cache and moves
+ * nothing. 🔑 Live is the runtime's own test, `!== 0`: `IkConstraint.update`
+ * returns on `mix === 0`, so a negative mix runs. Channel 0 of an ik frame is
+ * `mix`; the other four are softness, bend direction, compress and stretch.
+ * The argument with its measurements sits above the `check` call in
+ * `validate()`.
+ *
+ * Moved out of `src/validate.ts` whole: the bones, the target, the setup mix
+ * and the keyed ones are the rig's, the declaration the rig spec's.
+ *
+ * 🔩 A second clause reads the constraint's `bones` as a shape, whatever its
+ * mix (issue #1205): more than two bones, or a pair whose second bone's
+ * parent is not the first, is a constraint the solver cannot apply as drawn
+ * — `ikShapeFault` below, whose sentence the rig-spec parser prints too. A
+ * clause rather than an assertion of its own because it asks this body's
+ * question of the same object — does this ik do what it says — and a new
+ * registry entry would move every count the documents state.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { ConstraintFacts } from '../facts/constraints.ts';
+import { consumerDriven, consumerSkip, declaredButLive, declareIt, ikLive, noneKeysItsMixAbove0, REST_OR_KEY_ITS_MIX, switchedOn } from '../constraint_words.ts';
+import type { RigInfo } from '../../types.ts';
+
+/**
+ * What is wrong with an ik constraint's `bones` as a shape, in the sentence
+ * both the rig-spec parser and A47 print — or `null` when the shape is one
+ * the solver applies as drawn (issue #1205).
+ *
+ * - **A count other than one or two moves nothing.** The runtime's update
+ *   switches on the count with a case for one bone and one for two, so a
+ *   constraint over three or more is in the update cache and applies nothing
+ *   [measured: a chain under an ik over three bones and over four posed every
+ *   bone exactly where the same rig with no constraint did, 49 samples,
+ *   tolerance 0]. A list of none is refused before this (the compiler's
+ *   "needs a non-empty bones array"; an export's own loader).
+ * - **A pair whose second bone's parent is not the first solves another
+ *   triangle.** The two-bone solve places the second bone through the first's
+ *   matrix from the second's own local offset, so whatever stands between
+ *   them is left out of the chain it solves [measured on the same chain: a
+ *   bone between them at the child's origin left the tip 0.27–2.60 off the
+ *   target, a pair skipping a bone 18.95–22.25 off, and a zero-offset bone
+ *   between them at the parent's origin landed only while it held its
+ *   identity — turned 15° in setup, 3.50–4.11 off in every frame]. The rule
+ *   reads the parent and not the pose, because a pose that happens to agree
+ *   is not a rig that does. rigc's own reader of the model document refuses
+ *   both shapes too (`A00_MODEL_READ` on the core entry); this is the same
+ *   refusal on the side that reads a Spine file.
+ *
+ * `secondAncestors` is the second bone's ancestors, parent first, as the
+ * facts carry them.
+ */
+export function ikShapeFault(name: string, bones: readonly string[], secondAncestors: readonly string[]): string | null {
+  const quoted = (list: readonly string[]): string => list.map((b) => `"${b}"`).join(', ');
+  if (bones.length > 2) {
+    return (
+      `ik constraint "${name}" names ${bones.length} bones (${quoted(bones)}); the solver applies one or two, so a constraint ` +
+      `over ${bones.length} moves nothing — name one bone, or two where the second is the first's child`
+    );
+  }
+  if (bones.length !== 2 || secondAncestors[0] === bones[0]) return null;
+  const [first, second] = bones;
+  const at = secondAncestors.indexOf(first);
+  const why =
+    at > 0
+      ? `${quoted(secondAncestors.slice(0, at))} ${at === 1 ? 'stands' : 'stand'} between`
+      : secondAncestors.length === 0
+        ? `"${second}" has no parent`
+        : `"${first}" is not above it; its parent is "${secondAncestors[0]}"`;
+  return (
+    `ik constraint "${name}": "${second}" is not a child of "${first}" (${why}), so the two-bone solve is not of the ` +
+    `chain drawn — name "${second}"'s own parent as the first bone, or make "${second}" a child of "${first}"`
+  );
+}
+
+export function a47IkConstraintNotMutedThroughout({ fail, skip, stats }: Verdicts, facts: ConstraintFacts, rig: RigInfo | undefined): void {
+  const NAME = 'A47_IK_CONSTRAINT_NOT_MUTED_THROUGHOUT';
+  const constraints = facts.constraints.flatMap((c, index) => (c.ik === undefined ? [] : [{ name: c.name, ik: c.ik, index }]));
+  if (!constraints.length) return skip(NAME, 'the skeleton declares no ik constraint');
+  // The shape first, whatever the mix: a constraint the solver cannot apply as drawn is not exempted by a declaration of who sets its mix.
+  let shapeFaults = 0;
+  for (const { name, ik } of constraints) {
+    const fault = ikShapeFault(name, ik.bones, ik.secondAncestors);
+    if (fault === null) continue;
+    shapeFaults++;
+    fail(NAME, fault);
+  }
+  // Channel 0 is `mix`; the other four are softness, bend direction, compress and stretch.
+  const ikSwitchedOn = switchedOn(facts, (timeline) => timeline.kind === 'ik', 1, (_timeline, value, channel) => channel === 0 && ikLive(value));
+  const declared = consumerDriven(rig, 'ik');
+  const exempt: Array<[string, string]> = [];
+  for (const { name, ik: constraint, index } of constraints) {
+    const mix = constraint.mix;
+    const live = ikLive(mix) || ikSwitchedOn.has(index);
+    const why = declared.get(name);
+    if (why !== undefined) {
+      if (!live) exempt.push([name, why]);
+      else {
+        fail(
+          NAME,
+          declaredButLive(
+            `ik constraint "${name}"`,
+            ikLive(mix) ? `it rests at mix ${mix}` : 'an animation keys its mix above 0',
+          ),
+        );
+      }
+      continue;
+    }
+    if (live) continue;
+    fail(
+      NAME,
+      `ik constraint "${name}" has mix ${mix} at setup and ${noneKeysItsMixAbove0(facts.animations)}; ` +
+        `update() returns on mix 0, so ${constraint.bones.map((bone) => `"${bone}"`).join(' and ')} never ` +
+        `reach${constraint.bones.length === 1 ? 'es' : ''} for "${constraint.target}" — ${REST_OR_KEY_ITS_MIX}, ` +
+        declareIt('ik', name),
+    );
+  }
+  if (exempt.length) stats.ikConsumerDriven = exempt.map(([name]) => name).join(',');
+  if (exempt.length === constraints.length && shapeFaults === 0) return skip(NAME, consumerSkip('ik', exempt, facts.animations));
+}

package/src/assertions/bodies/a48.ts

@@ -0,0 +1,83 @@
+/**
+ * A48, the body (issue #1025, step 4c of #380): a transform constraint muted
+ * for good on every mix it reads is refused, unless the rig declares that the
+ * consumer drives its mix.
+ *
+ * 🔑 **A transform mix is read only for a property the constraint drives.**
+ * The early return in `TransformConstraint.update` is over all six mixes, but
+ * it is not what decides whether anything moves: each `to` entry reads its own
+ * mix (`ToRotate.mix` is `mixRotate`, …). At setup the parser only reads a mix
+ * whose property is declared, so the two tests agree there — but a timeline
+ * key that omits a mix is read as 1 (`SkeletonJson.js`, every `getValue(…, 1)`),
+ * so a key of `mixRotate: 0` alone on a rotate-only constraint passes the
+ * six-mix test on five mixes nothing reads. [measured] that key poses every
+ * bone exactly where no constraint does, and so does one keying `mixX` 1 on
+ * the same constraint. So this reads the mixes of the declared `to` kinds,
+ * at setup and on every value a key poses — the fact's `mixes`, `null` where
+ * the constraint declares no `to` of that property. Live is `!== 0`
+ * (`ikLive`'s note).
+ *
+ * Moved out of `src/validate.ts` whole: the declared `to` kinds, the setup
+ * mixes and the keyed ones are the rig's, the declaration the rig spec's.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { ConstraintFacts } from '../facts/constraints.ts';
+import { consumerDriven, consumerSkip, declaredButLive, declareIt, noneKeysItsMixAbove0, switchedOn } from '../constraint_words.ts';
+import type { RigInfo } from '../../types.ts';
+
+export function a48TransformConstraintNotMutedThroughout({ fail, skip, stats }: Verdicts, facts: ConstraintFacts, rig: RigInfo | undefined): void {
+  const NAME = 'A48_TRANSFORM_CONSTRAINT_NOT_MUTED_THROUGHOUT';
+  const constraints = facts.constraints.flatMap((c, index) => (c.transform === undefined ? [] : [{ name: c.name, transform: c.transform, index }]));
+  if (!constraints.length) return skip(NAME, 'the skeleton declares no transform constraint');
+  /** Which of the six channels `constraint` reads at all: the ones whose `to` kind it declares. */
+  const transformReads = (index: number): boolean[] => (facts.constraints[index]?.transform?.mixes ?? []).map((mix) => mix !== null);
+  const transformSwitchedOn = switchedOn(facts, (timeline) => timeline.kind === 'transform', 6, (timeline, value, channel) => {
+    const constraint = facts.constraints[timeline.constraint];
+    return constraint?.transform !== undefined && transformReads(timeline.constraint)[channel] && value !== 0;
+  });
+  const declared = consumerDriven(rig, 'transform');
+  const exempt: Array<[string, string]> = [];
+  for (const { name, transform: constraint, index } of constraints) {
+    const where = `transform constraint "${name}"`;
+    const pose: Record<string, number> = {};
+    for (const mix of constraint.mixes) if (mix !== null) pose[mix.field] = mix.setup;
+    const read = constraint.mixes.flatMap((mix) => (mix === null ? [] : [mix.field]));
+    if (read.length === 0) {
+      // No `to` at all: no mix is ever read, so neither remedy below applies.
+      fail(
+        NAME,
+        `${where} drives no property — its \`properties\` name no \`to\` — so no mix it carries is ever read and it ` +
+          'moves nothing; declare the property it should drive',
+      );
+      continue;
+    }
+    const resting = read.filter((field) => pose[field] !== 0);
+    const live = resting.length > 0 || transformSwitchedOn.has(index);
+    const why = declared.get(name);
+    if (why !== undefined) {
+      if (!live) exempt.push([name, why]);
+      else {
+        fail(
+          NAME,
+          declaredButLive(
+            where,
+            resting.length ? `it rests at ${resting.map((field) => `${field} ${pose[field]}`).join(', ')}` : 'an animation keys its mix above 0',
+          ),
+        );
+      }
+      continue;
+    }
+    if (live) continue;
+    fail(
+      NAME,
+      `${where} drives ${read.map((field) => field.slice(3).replace(/^./, (c) => c.toLowerCase())).join(', ')} and has ` +
+        `${read.map((field) => `${field} ${pose[field]}`).join(', ')} at setup, and ` +
+        `${noneKeysItsMixAbove0(facts.animations)}; a mix is read only for a property the constraint drives, and ` +
+        `update() skips each one at 0, so nothing ever moves ${constraint.bones.map((bone) => `"${bone}"`).join(', ')} — ` +
+        `rest ${read.length === 1 ? read[0] : `one of ${read.join(', ')}`} above 0, or key its mix above 0 in an animation, ` +
+        declareIt('transform', name),
+    );
+  }
+  if (exempt.length) stats.transformConsumerDriven = exempt.map(([name]) => name).join(',');
+  if (exempt.length === constraints.length) return skip(NAME, consumerSkip('transform', exempt, facts.animations));
+}

package/src/assertions/bodies/a49.ts

@@ -0,0 +1,81 @@
+/**
+ * A49, the body (issue #1099): no two regions on one page draw over each
+ * other — refused only where their rectangles overlap **and** what they draw
+ * overlaps, so a mesh's region may sit over a neighbour's rectangle wherever
+ * its hull is not. The footprint, and why the test is exactly A06's old tiling
+ * clause for two rectangles, is `../footprints.ts`.
+ *
+ * ⭐ **The clause it replaces.** A06 held, under `spine-html`, that no two
+ * region rectangles on one page overlap. A rectangle's footprint is the
+ * rectangle, so on every pair A06 refused where neither region is a readable
+ * mesh hull — every editor alias, every sequence frame, every rotated region,
+ * every plant of two rectangles over the same texels — this refuses the same
+ * pair, printing the same two rectangles first. What it accepts that A06 did
+ * not is a pair whose rectangles overlap where a hull leaves the rectangle
+ * transparent: what `--pack-shape polygon` writes.
+ *
+ * 🔸 **Nothing about the padding.** A06 never held a gap between two
+ * rectangles, and the padding a pack was made with is on no file the gate
+ * reads — not the atlas, not the model document; only the `pack:` line on
+ * stdout states it. The `2 · padding` the packer keeps between footprints is
+ * the packer's promise, held by `PK81`.
+ *
+ * 📐 **Renderer kind, the profile the clause ran under.** Two regions over the
+ * same texels is what an editor's packer writes for an alias or a sequence:
+ * measured over the ten atlases in `examples/`, 49 pairs on four pages, and a
+ * correct editor export. A rule that refused them under `spine` would be one
+ * consumer's convention refusing everybody else's data.
+ *
+ * The order of the lines is the atlas's: pages as they come, and within a page
+ * each pair in region order — the order A06's clause printed them in.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { AtlasRegionFacts } from '../facts/atlas_regions.ts';
+import type { MeshFacts } from '../facts/mesh_attachments.ts';
+import type { RegionJoinFacts } from '../facts/region_joins.ts';
+import { footprintOverlap, rectanglesOverlap, regionFootprints, type RegionFootprint } from '../footprints.ts';
+import { SKIP_NO_ATLAS, SKIP_NO_ATLAS_PAGE, SKIP_NO_ATLAS_REGION, SKIP_NO_ATLAS_REGION_PAIR } from '../reasons.ts';
+
+const NAME = 'A49_PACKED_FOOTPRINTS_DO_NOT_OVERLAP';
+
+/** A number for the sentence: to four places, trailing zeros dropped — `347`, `81.5`, `1916.5512`. */
+const texels = (n: number): string => n.toFixed(4).replace(/\.?0+$/, '');
+
+const rectSaid = (f: RegionFootprint): string => `"${f.region.name}" (${f.rect.x},${f.rect.y} ${f.rect.width}x${f.rect.height})`;
+
+export function a49PackedFootprintsDoNotOverlap({ fail, skip }: Verdicts, facts: AtlasRegionFacts, joins: RegionJoinFacts, meshes: MeshFacts | null): void {
+  const { atlas } = facts;
+  if (!atlas) return skip(NAME, SKIP_NO_ATLAS);
+  if (atlas.pages.length === 0) return skip(NAME, SKIP_NO_ATLAS_PAGE);
+  if (atlas.regions.length === 0) return skip(NAME, SKIP_NO_ATLAS_REGION);
+  const feet = regionFootprints(facts, joins, meshes);
+  const perPage = new Map<string, RegionFootprint[]>();
+  for (const foot of feet) {
+    const on = perPage.get(foot.region.page.name);
+    if (on) on.push(foot);
+    else perPage.set(foot.region.page.name, [foot]);
+  }
+  if ([...perPage.values()].every((on) => on.length < 2)) return skip(NAME, SKIP_NO_ATLAS_REGION_PAIR);
+  for (const [pageName, on] of perPage) {
+    for (let i = 0; i < on.length; i++) {
+      for (let j = i + 1; j < on.length; j++) {
+        const a = on[i];
+        const b = on[j];
+        if (!rectanglesOverlap(a, b)) continue;
+        const shared = footprintOverlap(a, b);
+        if (shared === null) continue;
+        const where =
+          a.whole && b.whole
+            ? `the two rectangles share ${texels(shared.box.x0)},${texels(shared.box.y0)} ${texels(shared.box.x1 - shared.box.x0)}x${texels(shared.box.y1 - shared.box.y0)}`
+            : `what they draw overlaps by ${texels(shared.area)} texel(s) of area inside ${texels(shared.box.x0)},${texels(shared.box.y0)} ` +
+              `${texels(shared.box.x1 - shared.box.x0)}x${texels(shared.box.y1 - shared.box.y0)}`;
+        fail(
+          NAME,
+          `regions ${rectSaid(a)} and ${rectSaid(b)} overlap on page "${pageName}", and so do their footprints — ` +
+            `"${a.region.name}" draws ${a.drawn}, "${b.region.name}" draws ${b.drawn}; ${where}. One drawing samples ` +
+            "texels that are the other's: move one region clear of the other's footprint, or pack the page again",
+        );
+      }
+    }
+  }
+}

package/src/assertions/bodies/a50.ts

@@ -0,0 +1,97 @@
+/**
+ * A50, the body (issue #1168): the stage box a rig asked for is the stage —
+ * in the Spine files a consumer ships, read back the way that consumer reads
+ * it.
+ *
+ * Since issue #907 the Spine header carries the setup-pose bounding box and the
+ * stage is stated only in `skeleton.model.json`, which a consumer does not ship.
+ * A rig that asks (`skeleton.stageBox`) carries the stage as a bounding-box
+ * attachment, whose numbers `compile` writes from the stage. This rule holds
+ * that box to the stage the document states, on both readings a consumer has:
+ *
+ *   1. **The data.** The slot carries, in the `default` skin under the asked
+ *      name, an unweighted bounding box of four vertices, and its stored
+ *      vertices are the stage's corners — `(x, y)`, `(x + w, y)`,
+ *      `(x + w, y + h)`, `(x, y + h)` — each exactly, as the float32 the
+ *      runtime loads. That is what a reader of the attachment gets without
+ *      posing anything.
+ *   2. **The setup pose.** Its world vertices at the setup pose — constraints
+ *      applied, no physics, no skin set — are those corners as the runtime
+ *      poses them on an unrotated root: through the frame the core computes
+ *      for a root that states no transform (`worldTransforms` in
+ *      `../../core/world.ts`, whose unrotated `b` is cos 90° at the runtime's
+ *      pi, −2.3e-8, not 0), compared on the header's grid
+ *      (`headerBoxNumber` in `../../compile.ts`) — the tolerance the header's
+ *      own box is held at. A constraint that moves the box's bone at setup
+ *      is caught here and nowhere else: `compile` poses no constraint.
+ *
+ * **SKIP** where nothing asks: an export or a directory with no `/3` document,
+ * and a document that states a stage and no box — a rig that does not ask is
+ * unmeasured, never certified.
+ *
+ * Links nothing from the runtime.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { StageBoxFacts } from '../facts/stage_box.ts';
+import { worldTransforms } from '../../core/world.ts';
+import { headerBoxNumber } from '../../compile.ts';
+
+const CODE = 'A50_STAGE_BOX_IS_THE_STAGE';
+
+/** The stage's four corners in Spine world, bottom-left first and counter-clockwise — the order `compile` writes. */
+export function stageCorners(stage: { x: number; y: number; width: number; height: number }): number[] {
+  const right = stage.x + stage.width;
+  const top = stage.y + stage.height;
+  return [stage.x, stage.y, right, stage.y, right, top, stage.x, top];
+}
+
+export function a50StageBoxIsTheStage({ fail, skip }: Verdicts, facts: StageBoxFacts): void {
+  const { asked } = facts;
+  if (asked === null) return skip(CODE, facts.why);
+  const where = `the stage box (slot "${asked.slot}", attachment "${asked.attachment}")`;
+  const { x, y, width, height } = asked.stage;
+  const required = `the stage ${x},${y} ${width}x${height}`;
+  if (!facts.slot) return fail(CODE, `${where}: the skeleton has no slot "${asked.slot}", so a consumer finds no stage — ${required} — in it`);
+  const held = facts.held;
+  if (held === null) {
+    return fail(CODE, `${where}: the default skin holds no attachment "${asked.attachment}" on slot "${asked.slot}", so a consumer finds no stage — ${required} — in it`);
+  }
+  if (held.type !== 'boundingbox') {
+    return fail(CODE, `${where}: the attachment is a ${held.type}, not a bounding box — ${required} travels as a boundingbox attachment, which every runtime returns by slot and name`);
+  }
+  if (held.weighted) {
+    return fail(CODE, `${where}: the box's vertices are bound to bones, and the stage is four unweighted corners in the root's space — ${required}`);
+  }
+  const corners = stageCorners(asked.stage);
+  if (held.stored.length !== corners.length) {
+    return fail(CODE, `${where}: the box holds ${held.stored.length / 2} vertices, and the stage is 4 corners — ${required}`);
+  }
+  let faults = 0;
+  for (let i = 0; i < corners.length; i += 2) {
+    const want = [Math.fround(corners[i]), Math.fround(corners[i + 1])];
+    const found = [held.stored[i], held.stored[i + 1]];
+    if (found[0] !== want[0] || found[1] !== want[1]) {
+      faults++;
+      fail(CODE, `${where}: vertex ${i / 2} is stored as (${found[0]}, ${found[1]}) and the stage's corner is (${want[0]}, ${want[1]}) — ${required}, bottom-left first and counter-clockwise`);
+    }
+  }
+  if (faults > 0) return;
+  if (typeof held.world === 'string') return fail(CODE, `${where}: its setup pose cannot be read — ${held.world}`);
+  // The runtime's frame of a root that states no transform, as the core computes it.
+  const frame = worldTransforms([{ name: 'root' }]).get('root');
+  if (frame === undefined) throw new Error('internal: the core posed no frame for an unrotated root');
+  for (let i = 0; i < corners.length; i += 2) {
+    const cx = Math.fround(corners[i]);
+    const cy = Math.fround(corners[i + 1]);
+    const want = [headerBoxNumber(cx * frame.a + cy * frame.b + frame.worldX), headerBoxNumber(cx * frame.c + cy * frame.d + frame.worldY)];
+    const found = [headerBoxNumber(held.world[i]), headerBoxNumber(held.world[i + 1])];
+    if (found[0] !== want[0] || found[1] !== want[1]) {
+      fail(
+        CODE,
+        `${where}: vertex ${i / 2} poses at (${found[0]}, ${found[1]}) at the setup pose and the stage's corner poses at ` +
+          `(${want[0]}, ${want[1]}) on an unrotated root, on the header's grid — something moves the box's bone at setup ` +
+          '(a constraint, or a pose the root does not state), so the box a consumer reads is not the stage',
+      );
+    }
+  }
+}

package/src/assertions/constraint_words.ts

@@ -0,0 +1,169 @@
+/**
+ * What the constraint bodies share (issue #1025, step 4c of #380): the one
+ * reading of "does an animation switch this on", the one predicate a path or
+ * slider mix is judged by, the physics components, and the sentences A23,
+ * A36, A37, A47 and A48 say alike. Moved here from `src/validate.ts`, each
+ * unchanged but for what `switchedOn` reads — the facts
+ * (`./facts/constraints.ts`) rather than the loaded timelines — because the
+ * bodies that read them moved, and a second copy is how two rules come to
+ * disagree. `src/validate.ts` imports what A40 still reads.
+ *
+ * Links nothing from the runtime.
+ */
+import type { ConstraintFacts, ConstraintTimeline } from './facts/constraints.ts';
+import type { RigInfo } from '../types.ts';
+
+/**
+ * Every component a physics constraint can drive (`PhysicsConstraintData`), the
+ * vocabulary A23 reads when it asks whether a constraint drives anything.
+ *
+ * 📏 It stood beside a second set, the components "the Spine editor models",
+ * read by A41 (the editor round-trip rule) and measured in issue #540 as
+ * `x` and `y`. Issue #1196 measured what that was really seeing, on Spine 4.3.23
+ * and 4.3.26: the editor imports a physics constraint's `rotate`, `scaleX` and
+ * `shearX` into its project and its JSON and binary exports omit them **only on
+ * a bone with no length** — on any bone with a length (0.01, 1, 40 tried) all
+ * three come back, and the editor's own example export keeps 18 of 18 `rotate`
+ * constraints through the same trip. A23 refuses those components on a
+ * zero-length bone (issue #1195), so a rig that passes it has nothing the editor drops, and
+ * A41, its declaration and its set were retired rather than reworded.
+ */
+export const PHYSICS_COMPONENTS = ['x', 'y', 'rotate', 'scaleX', 'shearX'] as const;
+
+/**
+ * The half of a muted-at-rest refusal that says what was searched, and how
+ * widely — one text for `A23`, `A36` and `A37`, which ask one question of three
+ * constraint kinds (issues #743, #752). A rig with no animation at all says
+ * "none of the 0 animations" rather than implying somebody keyed something.
+ */
+export function noneKeysItsMixAbove0(animations: number): string {
+  return `none of the ${animations} animation${animations === 1 ? '' : 's'} keys its mix above 0`;
+}
+
+/** The two repairs a muted-at-rest refusal names, since either one is a rig the runtime plays. */
+export const REST_OR_KEY_ITS_MIX = 'rest it above 0, or key its mix above 0 in an animation';
+
+/**
+ * The one predicate a path or slider mix is judged by, at setup and on every
+ * value a key poses: above 0, where `update()` does anything at all.
+ */
+export const mixLive = (value: number): boolean => value > 0;
+
+/**
+ * 🔑 **An ik or transform mix is live by the runtime's own test, `!== 0`, and
+ * not `mixLive`'s `> 0`.** `IkConstraint.update` returns on `mix === 0` and a
+ * transform's inner loop applies a property only when `to.mix(pose) !== 0`, so
+ * a negative mix runs. That is not a corner: [measured] five transform
+ * constraints across four of the editor's own example exports rest at mixX =
+ * mixY = −1, nothing keys them, and each moves its bones at setup against the
+ * same constraint with every mix 0. A `> 0` reading refuses all five.
+ * (`A36`/`A37` still read `> 0` — a path or slider resting negative is a
+ * question for their own card.)
+ */
+export const ikLive = (value: number): boolean => value !== 0;
+
+/**
+ * The constraints some animation keys to a value `live` accepts, on any of the
+ * first `channels` channels of a timeline `owns` claims — the one answer to
+ * "does anything switch this on" for `A23`, `A36`, `A37`, `A40`, `A47` and
+ * `A48` (issues #743, #752), as positions in `facts.constraints`.
+ *
+ * ⭐ It replaced `keyedBy`, which read the raw JSON and took a non-empty key
+ * array as the answer, and it did so rather than teaching that one to read
+ * values, because the raw file is the wrong place to read a value: a path
+ * `mix` key that omits `mixRotate` means 1 (`SkeletonJson.js:1011-1013`), a
+ * `mixY` it omits means that key's `mixX`, and a Bezier between two keys
+ * poses values neither key states. So this reads every value a channel poses
+ * — each key's own and every sample of each Bézier segment the parser built
+ * between two keys (`ConstraintTimeline.channelValues`): spine-core's loaded
+ * timelines on one side, the core's reading of the document on the other.
+ * [measured] the reading `keyedBy` gave was wrong in the accepting
+ * direction: a path constraint and a slider, both muted at rest and keyed to
+ * 0 only, pose every bone exactly where the same rig with no timeline does
+ * (max |Δ| 0.000000 over 60 steps at 60 fps) and both passed.
+ *
+ * A timeline naming no constraint is the physics family's global form, and
+ * its `reach` says who it writes; every other constraint timeline names its
+ * one constraint.
+ *
+ * `live` is handed the channel as well as the value, because not every
+ * channel of every constraint timeline is a mix (issue #765): an ik frame is
+ * mix, softness, bend direction, compress and stretch, so a bend direction of
+ * +1 is not a key that switches anything on, and a transform frame carries
+ * six mixes of which only the ones for a property the constraint drives are
+ * ever read. `channels` is how many leading channels the caller's `live` can
+ * accept a value on.
+ */
+export function switchedOn(
+  facts: ConstraintFacts,
+  owns: (timeline: ConstraintTimeline) => boolean,
+  channels: number,
+  live: (timeline: ConstraintTimeline, value: number, channel: number) => boolean,
+): Set<number> {
+  const reached = new Set<number>();
+  for (const timeline of facts.timelines) {
+    if (!owns(timeline)) continue;
+    let keysLive = false;
+    for (let channel = 0; channel < channels && !keysLive; channel++) {
+      keysLive = timeline.channelValues(channel).some((value) => live(timeline, value, channel));
+    }
+    if (!keysLive) continue;
+    for (const one of timeline.reach) reached.add(one);
+  }
+  return reached;
+}
+
+// 🔑 **The third door: the consumer drives the mix (issue #784).** A muted
+// constraint nothing in the file switches on is either a leftover or a dial
+// a game turns from code, and the two export as the same bytes — so the rig
+// spec says which, in `invariants.consumerDrivenMix`, and a declared
+// constraint is not measured by `A47` / `A48`. What that buys is never a pass
+// on it:
+//
+//   * every constraint of the kind declared — nothing is left to measure, so
+//     the rule SKIPs, naming each constraint, the declaration and its `why`;
+//   * some declared and some not — the rest are measured, and the declared
+//     ones go on the stats line, which is `A39`'s shape for `deformMayFold`.
+//     A SKIP there would put "nothing measured" over a rule that measured,
+//     and the summary would count a measured rule as skipped (`reportLines`'
+//     four buckets partition the registry, one row per rule).
+//
+// ⛔ A declared constraint the file ALSO switches on — resting live, or keyed
+// above 0 — is refused: the declaration exempts nothing there, which is the
+// shape `deformMayFold` on a slot with no mesh is refused for. [measured]
+// (`scratchpad/consumerdriven_runtime.ts`) an ik keyed at mix 0.5 with code
+// writing 1: code before `state.apply` is overwritten (applied mix 0.5),
+// code after it wins (1.0) — so which author holds a frame is the order of
+// the consumer's own loop, a fact about the scene rather than the object.
+
+/** The rig's consumer-driven declarations of one kind: constraint name -> why. */
+export function consumerDriven(rig: RigInfo | undefined, type: 'ik' | 'transform'): Map<string, string> {
+  return new Map((rig?.consumerDrivenMix ?? []).filter((e) => e.type === type).map((e) => [e.constraint, e.why]));
+}
+
+/** The third repair a muted-throughout refusal names. */
+export function declareIt(type: 'ik' | 'transform', name: string): string {
+  return (
+    `or declare that the consumer drives its mix, in the rig spec as invariants.consumerDrivenMix: ` +
+    `[{ "constraint": "${name}", "type": "${type}", "why": … }]`
+  );
+}
+
+/** The refusal of a declaration that exempts nothing. */
+export function declaredButLive(where: string, how: string): string {
+  return (
+    `${where} is declared in the rig spec as invariants.consumerDrivenMix, and the file already switches it on — ` +
+    `${how} — so the declaration exempts nothing; drop the entry. Where code also sets that mix, which of the two ` +
+    'holds on a frame is the order of the consumer\'s own loop: `state.apply` overwrites a mix written before it, ' +
+    'and a mix written after it replaces the key'
+  );
+}
+
+/** The SKIP when every constraint of the kind is declared consumer-driven. */
+export function consumerSkip(kind: string, exempt: Array<[string, string]>, animations: number): string {
+  return (
+    `every ${kind} constraint here is declared in the rig spec as invariants.consumerDrivenMix, so its mix is the ` +
+    `consumer's to set and nothing in this file shows it moving — ${exempt.map(([name, why]) => `"${name}" (why: ${why})`).join('; ')}: ` +
+    `${exempt.length === 1 ? 'it rests' : 'each rests'} muted and ${noneKeysItsMixAbove0(animations)}`
+  );
+}