rig-c 0.0.0-stage → 2.20.4

package/src/assertions/facts/mesh_attachments.ts

@@ -0,0 +1,100 @@
+/**
+ * The mesh attachments, as every body that reads a mesh sees them (issue
+ * #1025, step 4c of #380) — the census's F03, F05, F07 (vertex data), F08
+ * (mesh geometry) and F10 (the linked-mesh join), for A04, A13, A14, A15, A20,
+ * A21, A22, A28 and the mesh half of A23.
+ *
+ * ⭐ **One family** (issue #1054). Cut 4c-1 stated the meshes for A13, A14,
+ * A15 and A22 as a family of their own (`SkinMeshFacts`) and cut 4c-2 stated
+ * them again here; the two walked the same entries in the same order and
+ * agreed on every field they shared, and two families of one fact are two
+ * places for a supplier to disagree with itself. The size the budget and
+ * canvas rules read joined this one, and the bones a mesh's weights name are
+ * derived from `weights` (`weightBonesOf`) rather than stated beside them.
+ *
+ * ⭐ **The order is the file's**, as `./skin_entries.ts` states it: every
+ * skin in the file's order, and within a skin the entries slot by slot in the
+ * skeleton's slot order — the walk spine-core's `getAttachments()` makes and
+ * the model side reproduces by calling the emitter's own order.
+ *
+ * 🔸 **What a vertex's binding names is the bone's INDEX in the roster**,
+ * because two bodies print it (`A20`'s weight-0 clause and `A28`'s row
+ * shapes) and the index is what the file holds. The model document names a
+ * binding's bone by name; its supplier turns the name into the index the
+ * emitter writes (`boneIndexOf` in `src/emit_spine.ts`), called, and a weight
+ * into the float32 the runtime stores it as (`Math.fround`).
+ *
+ * 🔒 **`encoding` is the round trip's, and only the round trip's.** A clause
+ * whose subject is the Spine encoding — the flat vertex run's own coherence,
+ * a binding's index into the bone array — has no model-side subject: the
+ * document names bones and states the weighted form outright, and the run is
+ * written by the emitter (the card's point 2). Those clauses stay in
+ * `src/validate.ts`, which hands their findings to the body here, at the
+ * place in the walk the body used to print them, so the moved body and the
+ * kept clause print the lines the one body printed, in the same order. The
+ * model side supplies none, because it has no encoding to be wrong.
+ *
+ * Links nothing from the runtime: the shapes are plain values.
+ */
+
+/** One influence of a weighted vertex: the bone's index in the roster and the weight the runtime holds. */
+export interface MeshBinding {
+  readonly bone: number;
+  readonly weight: number;
+  /** The kept clause's finding about this binding's index (`A20`'s range rule), where it has one; never on the model side. */
+  readonly encoding?: string;
+}
+
+/** One mesh attachment of one skin, a linked mesh included (it loads as a mesh drawing its source's geometry). */
+export interface MeshEntry {
+  /** The attachment's own name: the entry's `name`, else its placeholder. */
+  readonly name: string;
+  readonly skin: string;
+  /** The slot it is filed under, and that slot's bone. */
+  readonly slot: string;
+  readonly slotBone: string;
+  readonly placeholder: string;
+  /** The file's link, when this entry takes its geometry from another mesh, or `null`. */
+  readonly link: { readonly source: string } | null;
+  /** The triangles it draws, as indices into its vertices — a link's are its source's. */
+  readonly triangles: readonly number[];
+  /** `worldVerticesLength`: two numbers per vertex. */
+  readonly worldVerticesLength: number;
+  /** Its `uvs`, as the runtime reads them (doubles). */
+  readonly regionUVs: readonly number[];
+  /** `hullLength`: two numbers per hull vertex. */
+  readonly hullLength: number;
+  /** Its `width` and `height` — a link's are its source's, which the runtime's `setSourceMesh` writes over the link's own. */
+  readonly width: number;
+  readonly height: number;
+  /** Per vertex its influences, in order — or `null` for an unweighted mesh. */
+  readonly weights: ReadonlyArray<readonly MeshBinding[]> | null;
+  /** The kept clauses' findings about this mesh's vertex run (`A04`'s encoding rules), in order; never on the model side. */
+  readonly encoding: readonly string[];
+}
+
+/** What A04, A20, A21, A28 and A23 read of the meshes. */
+export interface MeshFacts {
+  /** The bone roster's names, by index. */
+  readonly bones: readonly string[];
+  /** Every mesh attachment of every skin, in the file's walk order. */
+  readonly meshes: readonly MeshEntry[];
+}
+
+/**
+ * Every bone a mesh's weights name, in the weight run's order (repeats kept),
+ * by name — empty for an unweighted mesh. A binding whose index the roster
+ * does not hold names nothing here: that index is the encoding's fault, which
+ * `A20`'s kept clause names (`MeshBinding.encoding`), and no bone drives the
+ * mesh through it.
+ */
+export function weightBonesOf(facts: Pick<MeshFacts, 'bones'>, mesh: Pick<MeshEntry, 'weights'>): string[] {
+  const names: string[] = [];
+  for (const vertex of mesh.weights ?? []) {
+    for (const binding of vertex) {
+      const name = facts.bones[binding.bone];
+      if (name !== undefined) names.push(name);
+    }
+  }
+  return names;
+}

package/src/assertions/facts/region_joins.ts

@@ -0,0 +1,34 @@
+/**
+ * The join from an attachment to an atlas region, before anything loads it
+ * (issue #1025, step 4c of #380) — the census's F21 names plus the skin
+ * entries' region paths, as A08 reads them: every region name the atlas
+ * declares, and every lookup a skin entry will make.
+ *
+ * 🚨 **Both halves are read before the round trip, on purpose** (issue #589):
+ * A08 exists to name a miss the loader would refuse without naming the
+ * placeholder or the skin, so it cannot read what the loader produced. On the
+ * model side the same holds one step over — A08 runs behind the reader alone,
+ * not behind the region rule that stands in A00's place, so a miss is named by
+ * A08's sentence on both sides and the parse beside it refuses the same file.
+ *
+ * ⭐ **The order is the file's.** A08 prints one line per lookup that misses,
+ * in the order the skins, a skin's slot keys and a slot's placeholders stand in
+ * the file — the emitter's `editorSkinOrder` and `editorSlotKeyOrder`, called
+ * on the model side — and then one per padded region name, in the atlas's
+ * order.
+ *
+ * Links nothing from the runtime: `validate()` reads the region names off a
+ * `TextureAtlas` it builds for this alone and the lookups off the skeleton
+ * JSON; the model side reads both off the document (`../model/region_joins.ts`).
+ */
+import type { AttachmentRegionJoin } from '../region_lookups.ts';
+
+export type { AttachmentRegionJoin };
+
+/** What A08 reads. Each half is `null` when its file did not parse, and the body says which. */
+export interface RegionJoinFacts {
+  /** Every region the atlas declares, by its name as spelled (untrimmed), in the atlas's order. */
+  readonly regionNames: readonly string[] | null;
+  /** Every skin entry that resolves through a region, with the names it will look up, in the file's order. */
+  readonly joins: readonly AttachmentRegionJoin[] | null;
+}

package/src/assertions/facts/sequences.ts

@@ -0,0 +1,85 @@
+/**
+ * Numbered series and the frame a slot shows (issue #1025, cut 4c-3 of step
+ * 4c of #380) — the census's F02, F03, F18 and R4 as A46 reads them: every
+ * skin entry that draws a region, as the file states it and whether the
+ * runtime loaded it; every sequence timeline, as the file states it; an
+ * animation's duration; and what a slot shows at a time.
+ *
+ * ⭐ **Attachments by address, never by object.** A46 used to key what it knew
+ * by the loaded attachment object and to ask whether the slot shows "the keyed
+ * attachment or one playing its timelines" by identity. An object is the
+ * runtime's; an address — `skin`, `slot`, `placeholder`, the triple the file
+ * files an entry under and a timeline names it by — is the file's, and on the
+ * runtime's side each loaded entry is exactly one object (one per skin, slot
+ * and placeholder, which `Skin.getAttachment` is keyed by). So `posedFrame`
+ * answers with addresses: the entry the slot shows, and the entry whose
+ * timelines it plays (itself, or a linked mesh's source when the link plays
+ * its source's timelines).
+ *
+ * ⭐ **The file's order and spelling where A46 walks and prints**: the skins in
+ * the file's order, a skin's slot keys and a slot's placeholders in it; every
+ * `sequence` block and key as the file spells it, since A46 parses them itself
+ * and prints what it found.
+ *
+ * Links nothing from the runtime: `validate()` reads it off the skeleton JSON
+ * and the loaded skeleton (`spineSequenceFacts`), the model side off the
+ * document and the core (`../model/sequences.ts`).
+ */
+
+/** A skin entry's address: `skin`, `slot`, `placeholder`, joined by NULs. */
+export type EntryAddress = string;
+
+/** The address of one skin entry. */
+export function entryAddress(skin: string, slot: string, placeholder: string): EntryAddress {
+  return `${skin}\u0000${slot}\u0000${placeholder}`;
+}
+
+/** One skin entry that draws a region — a region, a mesh or a linked mesh. */
+export interface SequenceSkinEntry {
+  readonly skin: string;
+  readonly slot: string;
+  readonly placeholder: string;
+  /** The entry's `name`, `path` and `sequence` as the file spells them (`undefined` where it states none). */
+  readonly name: unknown;
+  readonly path: unknown;
+  readonly sequence: unknown;
+  /** Whether the runtime loaded an attachment for the entry: its slot exists and the skin holds it. */
+  readonly loaded: boolean;
+}
+
+/** One sequence timeline — an attachment's `sequence` that the file states as a list — the address it keys, and its keys as the file spells them. */
+export interface SequenceTimeline {
+  readonly animation: string;
+  readonly skin: string;
+  readonly slot: string;
+  readonly placeholder: string;
+  readonly keys: readonly unknown[];
+}
+
+/** What a slot shows at one pose. */
+export interface PosedSequence {
+  /** The entry the slot shows. */
+  readonly shown: EntryAddress;
+  /** The entry whose timelines it plays: itself, or the source of a linked mesh that plays its source's. */
+  readonly playsAs: EntryAddress;
+  /** The atlas region the shown entry's series resolves to at this pose, or `null` for none. */
+  readonly region: string | null;
+}
+
+/** What A46 reads. */
+export interface SequenceFacts {
+  /** Every skin entry of a region, mesh or linked mesh, in the file's order: skins, then each skin's slot keys, then a slot's placeholders. */
+  readonly entries: readonly SequenceSkinEntry[];
+  /** Every animation's sequence timelines, in the file's order: animations, then skins, slots and placeholders as the animation keys them. */
+  readonly timelines: readonly SequenceTimeline[];
+  /** Whether the skeleton has a slot of this name. */
+  hasSlot(slot: string): boolean;
+  /** The runtime's duration of an animation, or `null` for no animation of that name. */
+  duration(animation: string): number | null;
+  /**
+   * What the slot shows with the animation applied at `time` on a fresh,
+   * non-looping track from the setup pose, no skin set — `null` when it
+   * shows nothing.
+   */
+  posedFrame(animation: string, slot: string, time: number): PosedSequence | null;
+}

package/src/assertions/facts/skeleton_roster.ts

@@ -0,0 +1,45 @@
+/**
+ * The skeleton's bones and slots as the file lists them (issue #1025, cut 4c-4
+ * of #380) — the census's F01 and F02, the halves of them that A12, A25 and
+ * A26 read: each bone's name and its parent's, and each slot's name and
+ * whether it declares a dark colour, in the file's order.
+ *
+ * ⭐ **The order is a value.** The slots array IS the draw order, and A26
+ * holds it to the rig's table index for index; A12 prints one line per dark
+ * slot in that order. The emitter writes both arrays in the model's own order
+ * and never re-sorts them (`emitBones`, `emitSlots` in `src/emit_spine.ts`), so
+ * the document's lists are the file's.
+ *
+ * ⚠️ **Read as the bodies always read the raw JSON.** A slot is any object in
+ * the array, its name `String(name)` (a slot with no string name reads
+ * `"undefined"`, as it always printed) and `dark` whether the key is present at
+ * all; a bone is an object whose name is a string, its parent the string the
+ * file states or `null`. `validate()` reads them off the skeleton JSON
+ * (`rawSkeletonRoster`), which it parses before the round trip, so a file the
+ * loader refuses is still read; the model side reads them off the document
+ * (`../model/skeleton_roster.ts`).
+ *
+ * Links nothing from the runtime.
+ */
+
+/** A bone as the rules over parentage read it. */
+export interface RosterBone {
+  readonly name: string;
+  /** The parent's name, or `null` for a root (or a parent the file does not spell as a string). */
+  readonly parent: string | null;
+}
+
+/** A slot as the rules over the draw order and the dark colour read it. */
+export interface RosterSlot {
+  readonly name: string;
+  /** Whether the slot declares a dark colour — the key's presence, which is all A12 asks. */
+  readonly dark: boolean;
+}
+
+/** What A12, A25 and A26 read of the skeleton's arrays. */
+export interface SkeletonRosterFacts {
+  /** The bones, in the file's order. */
+  readonly bones: readonly RosterBone[];
+  /** The slots, in the file's order — the draw order. */
+  readonly slots: readonly RosterSlot[];
+}

package/src/assertions/facts/skin_entries.ts

@@ -0,0 +1,37 @@
+/**
+ * The skin entries, as the bodies that walk them read them (issue #1025, step
+ * 4c of #380) — the census's F03, F05 and F06: every skin's attachments, of
+ * which kind each is, and a region's name and size.
+ *
+ * ⭐ **The order is a fact, and it is the file's.** A body that prints one
+ * line per offending entry prints them in the order this list holds them, so a
+ * supplier that walked another order would print the same findings in another
+ * order — a different report about the same rig. The order is the one
+ * spine-core's loaded skins list their entries in: the skins in the file's
+ * order (`default` first, the rest in the editor's order the emitter writes —
+ * `editorSkinOrder` in `src/compile.ts`), and within a skin the entries slot by
+ * slot in the skeleton's slot order, each slot's in the order its table states
+ * them. The model side produces it by calling the emitter's own order, never
+ * by restating it (`../model/skin_entries.ts`); the selftest measures the two
+ * walks equal on every multi-skin build it makes.
+ *
+ * Links nothing from the runtime: a spine-core `RegionAttachment` satisfies
+ * the entry shape structurally, which is how `validate()` supplies it.
+ */
+
+/** One region attachment: the name it loaded under (its `name`, else its placeholder), the region path it resolves through (its `path`, else that name) and its size. */
+export interface RegionEntry {
+  readonly name: string;
+  readonly width: number;
+  readonly height: number;
+  /** Read by A19 (issue #1025, cut 4c-1), which exempts a base plate by the region it draws; the runtime types it as possibly unset, and reads it with the name as fallback. */
+  readonly path?: string;
+}
+
+/** What the skins hold, for A03, A11 and A19. */
+export interface SkinEntryFacts {
+  /** Every region attachment of every skin, in the file's walk order (the header's ⭐). */
+  readonly regionAttachments: readonly RegionEntry[];
+  /** How many clipping attachments the skins hold, every skin counted. */
+  readonly clippingCount: number;
+}

package/src/assertions/facts/skin_members.ts

@@ -0,0 +1,53 @@
+/**
+ * What a skin activates, and what asks to be activated (issue #1025, step 4c
+ * of #380) — the census's F01, F04 and F12 as A38 reads them: every bone with
+ * its parent and its `skinRequired` flag, every constraint in update order with
+ * its flag, and each skin's own `bones` and constraint lists.
+ *
+ * 🔑 **A constraint is an object, not a name.** A skin lists constraint
+ * OBJECTS, and two constraints of one name under two kinds are two objects a
+ * skin may list separately (issue #692) — so a skin's `constraints` hold the
+ * very entries `constraints` holds, and a body asks whether one is listed by
+ * identity. A bone's `parent` is the bone entry itself, so the ancestor chain is
+ * walked by reference too.
+ *
+ * ⭐ **The order is the file's.** A38 prints one line per offending member:
+ * skins in the file's order (the emitter's, `editorSkinOrder`), a skin's bones
+ * as it lists them and its constraints kind by kind in the order the file keys
+ * them (`ik`, `transform`, `path`, `physics`, `slider` — `RIG_SKIN_CONSTRAINT_KEYS`,
+ * the emitter's), then the bones in the skeleton's order and the constraints in
+ * update order.
+ *
+ * Links nothing from the runtime: spine-core's loaded `SkeletonData` satisfies
+ * the shape structurally, which is how `validate()` supplies it, and the model
+ * side builds it from the document (`../model/skin_members.ts`).
+ */
+
+/** One bone: its name, whether it is skin-required, and its parent entry. */
+export interface MemberBone {
+  readonly name: string;
+  readonly skinRequired: boolean;
+  readonly parent: MemberBone | null;
+}
+
+/** One constraint: its name and whether it is skin-required. */
+export interface MemberConstraint {
+  readonly name: string;
+  readonly skinRequired: boolean;
+}
+
+/** One skin: its name and the bones and constraint entries it lists. */
+export interface MemberSkin {
+  readonly name: string;
+  readonly bones: readonly MemberBone[];
+  readonly constraints: readonly MemberConstraint[];
+}
+
+/** What A38 reads. */
+export interface SkinMemberFacts {
+  readonly skins: readonly MemberSkin[];
+  /** Every bone, in the skeleton's order. */
+  readonly bones: readonly MemberBone[];
+  /** Every constraint, in update order. */
+  readonly constraints: readonly MemberConstraint[];
+}

package/src/assertions/facts/slider_composition.ts

@@ -0,0 +1,78 @@
+/**
+ * The sliders and the timelines their animations key, as A40 reads them
+ * (issue #1025, cut 4c-5 of step 4c of #380) — the census's F01–F04, F12,
+ * F15, F18, F19 and R3.
+ *
+ * ⭐ **The order is the runtime's.** The sliders in the `constraints` array's
+ * order, which is the update order and the order A40 calls "earlier" and
+ * "later" in; each animation's timelines in the order the runtime builds
+ * them — the slot timelines, the bone timelines, then ik, transform, path,
+ * physics, slider, the attachments' deform and sequence, the draw order and
+ * the events, each group's targets in the order the file keys them [measured:
+ * an animation keying `events`, `drawOrder`, `attachments`, `slider`,
+ * `physics`, `path`, `transform`, `ik`, `slots`, `bones` in that key order
+ * loads them slots, bones, ik, transform, path, physics, slider, deform,
+ * sequence, draw order, events]; each timeline's properties in the order it
+ * registers them. A40 groups the timelines by property in that order and
+ * prints one line per property shared, so the order is a fact both suppliers
+ * state, not a sort either applies.
+ *
+ * 🔑 **A property is named by an id both suppliers spell the same way**: the
+ * property's name, then the index of the bone, slot or constraint it
+ * addresses in the skeleton's order (`-1` for a physics timeline naming no
+ * constraint), then — for a deform or sequence timeline — the attachment it
+ * is keyed on as `skin/slot/placeholder`. The runtime spells the last as an
+ * object's serial number, which is the runtime's and not the rig's, so its
+ * supplier maps each attachment object to the address it is filed under; a
+ * physics `reset` and the draw-order and event timelines carry no index at
+ * all (measured: a named `reset` reads `physicsConstraintReset` alone).
+ *
+ * 🔸 **What applying a timeline additively does is a question, not a value.**
+ * It is posed — twice, with `add`, from two start states, under every skin —
+ * so a body asks for it (`behaviour`), and only for the timelines it needs:
+ * the validator answers with the runtime's probe, the model side with the
+ * core's (`src/core/additive.ts`), and the selftest puts every question a
+ * body asks to both.
+ *
+ * Links nothing from the runtime.
+ */
+
+/** What applying a timeline twice with `add` does (`src/core/additive.ts`' header). */
+export type AddBehaviour = 'accumulates' | 'overwrites' | 'inert';
+
+/** One property a timeline registers: the id it is shared by, the property's name, and the target and property as A40's sentence names them. */
+export interface SliderTimelineProperty {
+  readonly id: string;
+  readonly property: string;
+  readonly names: string;
+}
+
+/** One timeline of a slider's animation. */
+export interface SliderTimelineFact {
+  /** The runtime class it loads as — the word A40's sentence names `apply` on. */
+  readonly runtimeClass: string;
+  readonly properties: readonly SliderTimelineProperty[];
+}
+
+/** One slider constraint. */
+export interface SliderFact {
+  readonly name: string;
+  /** Its position in the skeleton's `constraints` array. */
+  readonly index: number;
+  /** Its setup `mix`. */
+  readonly mix: number;
+  readonly additive: boolean;
+  readonly skinRequired: boolean;
+  /** The skins whose `slider` list names it, in the skeleton's skin order. */
+  readonly skins: readonly string[];
+  /** The animation it applies, with its timelines in the runtime's order — or `null` where it applies none. */
+  readonly animation: { readonly name: string; readonly timelines: readonly SliderTimelineFact[] } | null;
+}
+
+/** What A40 reads beside the constraint facts. */
+export interface SliderCompositionFacts {
+  /** Every slider, in the `constraints` array's order. */
+  readonly sliders: readonly SliderFact[];
+  /** What the `timeline`-th timeline of `animation` does when it is applied twice with `add` — posed. */
+  behaviour(animation: string, timeline: number): AddBehaviour;
+}

package/src/assertions/facts/slot_colour.ts

@@ -0,0 +1,43 @@
+/**
+ * Slot colour timelines and the colour a slot poses at (issue #1025, step 4c
+ * of #380) — the census's F18 and R4: the animations and the slot timelines
+ * they key, and one slot's light colour posed by the runtime's rule.
+ *
+ * ⭐ **The file's order, and the file's spelling.** A45's first clause names
+ * the timeline "which the file states last" as the one that wins, so the order
+ * of a slot's timelines is a value and not a presentation; and its findings
+ * print a key's `time`, `color` and `value` as the file states them. So the
+ * list holds, for every animation in the order the file keys them and every
+ * slot in the order the animation keys them, that slot's timelines in the
+ * file's order, each key as the file spells it. `validate()` reads it off the
+ * skeleton JSON; the model side produces it from the document by calling the
+ * emitter's own order and its own parser-default and key-order passes
+ * (`../model/slot_colour.ts`), so a key the emitter would write without a field
+ * reads without it here too.
+ */
+
+/** One animation's timelines on one slot: timeline name -> keys, as the file states them. */
+export interface SlotTimelines {
+  readonly animation: string;
+  readonly slot: string;
+  readonly timelines: Readonly<Record<string, unknown>>;
+}
+
+/** A slot's light colour as posed: four channels, NaN where the pose read no number. */
+export interface PosedSlotColour {
+  readonly color: { readonly r: number; readonly g: number; readonly b: number; readonly a: number };
+}
+
+/** What A45 reads. */
+export interface SlotColourFacts {
+  /** Every (animation, slot) pair whose timelines the file keys, in the header's order. */
+  readonly slotTimelines: readonly SlotTimelines[];
+  /** Whether the skeleton holds an animation of this name. */
+  hasAnimation(name: string): boolean;
+  /**
+   * The slot's colour with the animation applied at `time` on a fresh,
+   * non-looping track from the setup pose, no skin set — or `undefined` for a
+   * slot the skeleton does not have.
+   */
+  posedSlot(animation: string, slot: string, time: number): PosedSlotColour | undefined;
+}

package/src/assertions/facts/stage.ts

@@ -0,0 +1,27 @@
+/**
+ * The stage the skeleton states (issue #1025, step 4c of #380) — the census's
+ * F11: the setup-pose box's width and height, which A14 measures a mesh against
+ * and A19 measures an attachment against.
+ *
+ * ⚠️ **`undefined` is a value here, and it is the runtime's.** A skeleton that
+ * declares no stage loads with `width` and `height` undefined (measured through
+ * spine-core 4.3.13: a header with neither key reads both as `undefined`, not
+ * 0), and the two rules read that absence differently on purpose — A14 skips,
+ * A19 names the base plate it cannot decide. So the fact carries the absence
+ * rather than a number standing in for it, and each body reads it as it always
+ * did.
+ *
+ * A `rigc-compiled/3` document states it (`stage`, issue #1026), and since
+ * issue #907 that is the only place a rigc build states it: the Spine header
+ * carries the setup-pose bounding box. So both suppliers read a rigc build's
+ * stage off its document (`spineStage` in `../../validate.ts`,
+ * `../model/stage.ts`); an export, which has no document, is read off its
+ * header.
+ * Links nothing from the runtime.
+ */
+
+/** The stage's two extents, each `undefined` where the skeleton states none. */
+export interface StageFacts {
+  readonly width: number | undefined;
+  readonly height: number | undefined;
+}

package/src/assertions/facts/stage_box.ts

@@ -0,0 +1,65 @@
+/**
+ * The stage box a rig asked for and what the skeleton holds there (issue
+ * #1168) — what `A50_STAGE_BOX_IS_THE_STAGE` reads.
+ *
+ * ⭐ **The question is asked by the model document and answered by the
+ * skeleton.** The document states which slot and attachment carry the stage
+ * (`stage.box`, `ModelStage.box`) and the stage they were written from; a Spine
+ * file carries no such statement, so an export, a bare directory and a
+ * document that states no box all ask nothing and the body SKIPs, naming which.
+ * What answers is read off the skeleton: through spine-core's loaded
+ * `SkeletonData` and a skeleton posed at setup (`spineStageBox` in
+ * `../../validate.ts`), or through the document's records and rigc's core
+ * poser (`../model/stage_box.ts`).
+ *
+ * Links nothing from the runtime.
+ */
+
+/** The box the document says the rig asked for, and the stage it was written from. */
+export interface StageBoxAsked {
+  readonly slot: string;
+  readonly attachment: string;
+  readonly stage: { readonly x: number; readonly y: number; readonly width: number; readonly height: number };
+}
+
+/** The attachment the slot carries under the asked name, in the `default` skin. */
+export interface StageBoxHeld {
+  /**
+   * The attachment's type in the format's words — `boundingbox`, `region`,
+   * `mesh`, `clipping`, `path`, `point` — as the runtime loads it: a linked
+   * mesh loads as a `mesh`, so both suppliers spell it so.
+   */
+  readonly type: string;
+  /** Whether its vertices are bound to bones (a weighted run) rather than stated in the slot bone's space. */
+  readonly weighted: boolean;
+  /** The vertex numbers it holds as loaded — `x, y` per vertex for an unweighted box. Empty for a type that holds none. */
+  readonly stored: readonly number[];
+  /**
+   * Its world vertices at the setup pose — constraints applied, no physics,
+   * no skin set — `x, y` per vertex; or why there are none (its bone is
+   * inactive, the setup pose cannot be posed).
+   */
+  readonly world: readonly number[] | string;
+}
+
+/** What A50 reads. */
+export interface StageBoxFacts {
+  /** The box the rig asked for, or `null` where nothing asks — and then `why` says what asked nothing. */
+  readonly asked: StageBoxAsked | null;
+  /** The SKIP's reason where `asked` is `null`; empty otherwise. */
+  readonly why: string;
+  /** Whether the skeleton has a slot of the asked name. */
+  readonly slot: boolean;
+  /** The `default` skin's attachment of the asked name on that slot, or `null` for none (no default skin, nothing under that name). */
+  readonly held: StageBoxHeld | null;
+}
+
+/**
+ * The SKIP wherever nothing asks: a `/3` document whose stage states no box, a
+ * document that declares no stage, a `/2` or `/1` document, or none at all (an
+ * export, a bare directory). One sentence for all of them, because the rule
+ * reads one fact — that no box was asked for — and two suppliers that differ
+ * only in whether a caller handed the document over must print one line.
+ */
+export const SKIP_NO_STAGE_BOX =
+  'nothing asks for a stage box: no rigc-compiled/3 model document beside this skeleton states one (stage.box, from the rig spec\'s skeleton.stageBox) — a rig that does not ask, or an export, carries no stage in its Spine files to measure';

package/src/assertions/facts/stepped_poses.ts

@@ -0,0 +1,74 @@
+/**
+ * The stepped poses (issue #1025, cut 4c-5a of step 4c of #380) — the census's
+ * F01, F18, R4 (the posed `inherit`) and R5 as A10 reads them: the skeleton's
+ * setup pose with every physics state reset, every animation walked on a
+ * LOOPING track from that pose in equal steps, and a bone's inheritance mode
+ * posed at one time on a fresh, non-looping track.
+ *
+ * ⭐ **A pose is handed over whole, non-finite values in place.** A10's
+ * subject is the first number of a pose that is not finite, so a supplier
+ * that refused such a pose, or wrote it as something else, would answer a
+ * different question. The runtime's supplier reads what spine-core posed; the
+ * model side's is the core's looping walk (`src/core/walk.ts`), which returns
+ * the value rather than refusing it.
+ *
+ * 🔸 **The inheritance mode is `null` where the pose holds a mode**, and the
+ * value it holds, as `String` spells it, where it holds none — the one bone
+ * reading that can be wrong with every number finite (#733): the runtime's
+ * lookup leaves a spelling it does not resolve as no mode at all.
+ *
+ * The bone timelines A10 walks for its `inherit` keys are `BoneTimelineFacts`
+ * (`./bone_timelines.ts`), the family A24, A29 and A30 read.
+ *
+ * Links nothing from the runtime: `validate()` supplies it from spine-core
+ * (`spineSteppedPoses`), the model side from the document and the core
+ * (`../model/stepped_poses.ts`).
+ */
+import type { PosedVertices, WorldTransform } from '../../nonfinite.ts';
+
+/** One bone of a pose: its world transform as computed, and its inheritance mode — `null` for a mode, else the value held. */
+export interface SteppedBone extends WorldTransform {
+  readonly inherit: string | null;
+}
+
+/** One slot of a pose: its light colour and its dark colour (`null` for a slot holding none), as computed. */
+export interface SteppedSlot {
+  readonly name: string;
+  readonly colour: readonly [number, number, number, number];
+  readonly dark: readonly [number, number, number] | null;
+}
+
+/** One pose: every bone in skeleton order, every region and mesh shown in draw order, every slot in setup order. */
+export interface SteppedFrame {
+  readonly bones: readonly SteppedBone[];
+  readonly drawn: readonly PosedVertices[];
+  readonly slots: readonly SteppedSlot[];
+}
+
+/** What A10 reads. */
+export interface SteppedPoseFacts {
+  /** The skeleton's bone count. */
+  readonly boneCount: number;
+  /** The animations, in the file's order, each with the runtime's duration (the last key of every timeline, as float32). */
+  readonly steppedAnimations: ReadonlyArray<{ readonly name: string; readonly duration: number }>;
+  /** Whether the skeleton holds an animation of this name. */
+  hasAnimation(name: string): boolean;
+  /** Whether the skeleton holds a bone of this name. */
+  hasBone(name: string): boolean;
+  /**
+   * The bone's inheritance mode with the animation applied at `time` on a
+   * fresh, non-looping track from the setup pose, every physics state reset
+   * before it — `null` where the pose holds a mode, else that value spelled by
+   * `String`, and `undefined` for a bone the skeleton does not have.
+   */
+  posedInherit(animation: string, bone: string, time: number): string | null | undefined;
+  /** How the file spells a bone's setup `inherit`: `JSON.stringify` of the stated value (`"undefined"` for none). */
+  statedInherit(bone: string): string;
+  /** The setup pose, every physics state reset, before any animation is set. */
+  setup(): SteppedFrame;
+  /**
+   * The animation set on a LOOPING track over that setup pose, then `frames`
+   * steps of `step` each — the poses after steps 1 to `frames`, in order.
+   */
+  walk(animation: string, step: number, frames: number): SteppedFrame[];
+}