spine-rigc 1.7.0 → 1.9.0

package/src/assertions/model/skin_members.ts

@@ -0,0 +1,62 @@
+/**
+ * The model side's supply of `SkinMemberFacts` (issue #1025, step 4c of
+ * #380): the bones, the constraints and each skin's lists, read off the
+ * document and joined the way the runtime's loader joins them.
+ *
+ * - **Bones**: the document's `bones` in order, each with its `skinRequired`
+ *   as stated (absent is not required) and its parent entry.
+ * - **Constraints**: the document's `constraints` in order — update order, the
+ *   order the emitter writes them in — each skin-required exactly when it
+ *   states `skin: true`, the field the emitter writes through unchanged.
+ * - **Skins**: in the emitter's order (`editorSkinOrder`, `src/compile.ts`); a
+ *   skin's bones as it lists them, each the FIRST bone of that name; its
+ *   constraints kind by kind in the emitter's key order
+ *   (`RIG_SKIN_CONSTRAINT_KEYS`, which `emitSkins` walks), each the first
+ *   constraint of that kind and name — the object the loader finds, and the
+ *   same object `constraints` holds, so a body asking whether one is listed
+ *   asks by identity. `readModel` refuses a skin listing a constraint of a
+ *   kind and name the document lacks; a bone name it lacks is this module's to
+ *   refuse, by name.
+ *
+ * Links nothing from the runtime.
+ */
+import { editorSkinOrder } from '../../compile.ts';
+import { RIG_SKIN_CONSTRAINT_KEYS } from '../../rig.ts';
+import type { MemberBone, MemberConstraint, MemberSkin, SkinMemberFacts } from '../facts/skin_members.ts';
+import { isObj } from '../values.ts';
+import type { ReadDocument } from './parse.ts';
+
+export function modelSkinMembers(read: ReadDocument): SkinMemberFacts {
+  const doc = read.doc;
+  const bones: MemberBone[] = [];
+  const boneByName = new Map<string, MemberBone>();
+  for (const bone of doc.bones) {
+    const parent = bone.parent === undefined ? null : boneByName.get(bone.parent);
+    if (parent === undefined) throw new Error(`internal: bone "${bone.name}" names parent "${bone.parent}", which the reader accepted and no earlier bone is`);
+    const entry: MemberBone = { name: bone.name, skinRequired: bone.skinRequired === true, parent };
+    bones.push(entry);
+    if (!boneByName.has(bone.name)) boneByName.set(bone.name, entry);
+  }
+  const constraints: Array<MemberConstraint & { kind: string }> = [];
+  const stated = Array.isArray(read.json.constraints) ? read.json.constraints.filter(isObj) : [];
+  for (const constraint of stated) {
+    constraints.push({ name: String(constraint.name), kind: String(constraint.kind), skinRequired: constraint.skin === true });
+  }
+  const skins: MemberSkin[] = editorSkinOrder(doc.skins).map((skin) => {
+    const listedBones = skin.bones.map((name) => {
+      const found = boneByName.get(name);
+      if (found === undefined) throw new Error(`skin "${skin.name}" lists bone "${name}", which is not a bone of the document`);
+      return found;
+    });
+    const listedConstraints: MemberConstraint[] = [];
+    for (const kind of RIG_SKIN_CONSTRAINT_KEYS) {
+      for (const name of skin.constraints[kind]) {
+        const found = constraints.find((c) => c.kind === kind && c.name === name);
+        if (found === undefined) throw new Error(`internal: skin "${skin.name}" lists ${kind} constraint "${name}", which the reader accepted and the document does not hold`);
+        listedConstraints.push(found);
+      }
+    }
+    return { name: skin.name, bones: listedBones, constraints: listedConstraints };
+  });
+  return { skins, bones, constraints };
+}

package/src/assertions/model/skin_meshes.ts

@@ -0,0 +1,90 @@
+/**
+ * The model side's supply of `SkinMeshFacts` (issue #1025, step 4c of #380):
+ * every mesh and linked-mesh record of every skin, read off the document in the
+ * file's walk order.
+ *
+ * - **The order** is `fileOrderedEntries`'s (`./skin_entries.ts`): the skins by
+ *   the emitter's `editorSkinOrder`, the slots in the document's slot order, a
+ *   slot's records in its table's order — the walk the selftest measures equal
+ *   to spine-core's `getAttachments()`.
+ * - **A linked mesh's geometry is its source's**, read through the core's own
+ *   joins rather than a copy of them: the vertices through `sourceOfDoc` and
+ *   the UVs and triangles through the draw walk's `meshOf` (`drawWalkOf`), both
+ *   in `src/core/index.ts`; and its `width` and `height` are the source
+ *   record's too, the two numbers `setSourceMesh` overwrites the link's own
+ *   with. `readModel` refuses a link whose source does not resolve, so a miss
+ *   here is this module's defect.
+ * - **The bones a mesh's weights name** are its bindings' bone names, in the
+ *   bindings' order — the document states a weighted vertex by bone NAME, and
+ *   the Spine file's index run is the emitter's encoding of exactly that list.
+ * - **`worldVerticesLength`** is two per vertex: `2 · bindings.length` for a
+ *   weighted mesh, `xy.length` for a plain one — the derivation
+ *   `src/deformstructure.ts` already makes for the deform survey.
+ * - **`width` and `height`** are the record's, off the document's JSON: the
+ *   core's geometry reader keeps a mesh's vertices, UVs and triangles and not
+ *   its size, which no pose reads.
+ *
+ * Links nothing from the runtime.
+ */
+import { drawWalkOf, shownRow, sourceOfDoc } from '../../core/index.ts';
+import type { ModelVertices } from '../../model.ts';
+import type { MeshEntry, SkinMeshFacts } from '../facts/skin_meshes.ts';
+import { isObj } from '../values.ts';
+import type { ReadDocument } from './parse.ts';
+import { fileOrderedEntries } from './skin_entries.ts';
+
+/** A record's own `width` and `height` as the document states them, found by skin (the first of that name, as a link resolves its skin), slot and placeholder. */
+function statedSize(read: ReadDocument, skin: string, slot: string, placeholder: string): { width: number; height: number } {
+  const skins = Array.isArray(read.json.skins) ? read.json.skins : [];
+  const found = skins.find((k: unknown) => isObj(k) && k.name === skin);
+  const table = isObj(found) && isObj(found.attachments) ? found.attachments[slot] : undefined;
+  const record = isObj(table) ? table[placeholder] : undefined;
+  if (!isObj(record) || typeof record.width !== 'number' || typeof record.height !== 'number') {
+    throw new Error(`internal: skin "${skin}" slot "${slot}" placeholder "${placeholder}" is a mesh record the document states no width and height for`);
+  }
+  return { width: record.width, height: record.height };
+}
+
+export function modelSkinMeshes(read: ReadDocument): SkinMeshFacts {
+  const doc = read.doc;
+  const sourceVertices = sourceOfDoc(doc);
+  const walk = drawWalkOf(doc, []);
+  const slotBone = new Map(doc.slots.map((slot) => [slot.name, slot.bone] as const));
+  const meshes: MeshEntry[] = [];
+  for (const entry of fileOrderedEntries(read)) {
+    if (entry.record.kind !== 'mesh' && entry.record.kind !== 'linkedmesh') continue;
+    const g = entry.record.geometry;
+    let vertices: ModelVertices;
+    let uvs: number[];
+    let triangles: number[];
+    let size: { width: number; height: number };
+    if (g?.kind === 'mesh') {
+      ({ vertices, uvs, triangles } = g);
+      size = statedSize(read, entry.skin, entry.slot, entry.placeholder);
+    } else if (g?.kind === 'linkedmesh') {
+      const source = sourceVertices(g.skin, g.slot, g.source);
+      const drawn = walk.meshOf(g.skin, g.slot, g.source);
+      if (typeof source === 'string' || drawn === undefined) throw new Error(`internal: skin "${entry.skin}" slot "${entry.slot}" placeholder "${entry.placeholder}": ${typeof source === 'string' ? source : 'its source draws no mesh'}, and the reader accepted it`);
+      vertices = source;
+      ({ uvs, triangles } = drawn);
+      size = statedSize(read, g.skin, g.slot, g.source);
+    } else {
+      // `readModel` reads every mesh and link record's geometry or refuses the document, so a record without one is this module's defect.
+      throw new Error(`internal: skin "${entry.skin}" slot "${entry.slot}" placeholder "${entry.placeholder}" is a ${entry.record.kind} record the reader returned without its geometry`);
+    }
+    const bone = slotBone.get(entry.slot);
+    if (bone === undefined) throw new Error(`internal: skin "${entry.skin}" names slot "${entry.slot}", which the reader accepted and the document does not hold`);
+    meshes.push({
+      name: shownRow(entry).name,
+      slot: entry.slot,
+      slotBone: bone,
+      triangles,
+      width: size.width,
+      height: size.height,
+      regionUVs: uvs,
+      worldVerticesLength: vertices.weighted ? 2 * vertices.bindings.length : vertices.xy.length,
+      weightBones: vertices.weighted ? vertices.bindings.flatMap((vertex) => vertex.map((binding) => binding.bone)) : [],
+    });
+  }
+  return { meshes };
+}

package/src/assertions/model/slot_colour.ts

@@ -0,0 +1,80 @@
+/**
+ * The model side's supply of `SlotColourFacts` (issue #1025, step 4c of #380).
+ *
+ * - **The slot timelines, in the file's order and spelling.** The document
+ *   holds each animation's slot timelines in the order they are applied, with
+ *   every key as the compiler built it; the Spine file keys the animations in
+ *   the editor's order and passes every key through two passes. So the
+ *   animations are put in order by `editorAnimationOrder` (`src/compile.ts`,
+ *   the function the emitter is handed), and the timelines are laid out as the
+ *   file lays them and handed to the emitter's own `withoutParserDefaults` and
+ *   `inEditorKeyOrder` (`src/keyorder.ts`) — so a key field the emitter would
+ *   leave out at the parser's default is left out here too, and a body
+ *   printing `JSON.stringify(key.value)` prints what it prints over the file.
+ *   Nothing here restates either rule.
+ * - **Whether an animation exists**: the document's own roster.
+ * - **A slot's posed colour**: the core's raw entry (`poseRawAnimation`,
+ *   `src/core/raw.ts`) taking one step of the time on a fresh non-looping
+ *   track, under the view the core poses with no skin set (`noSkinView`,
+ *   `src/render_core.ts`) — the reading of what `validate()` does through
+ *   spine-core (a fresh skeleton, no skin, setup pose, the track stepped to the
+ *   time and applied). Its slot rows are the ones `CR03` holds bit for bit to
+ *   spine-core on every frame of the nineteen recipes; that the two readings
+ *   print the same A45 line is the selftest's supplier check, on every call
+ *   that poses one (`VF02`). A channel the pose read as no number is NaN, as a
+ *   non-finite channel reads on the runtime's side.
+ *
+ * Links nothing from the runtime.
+ */
+import { editorAnimationOrder } from '../../compile.ts';
+import type { CompiledDocument } from '../../core/index.ts';
+import { poseRawAnimation } from '../../core/raw.ts';
+import { inEditorKeyOrder, withoutParserDefaults } from '../../keyorder.ts';
+import { noSkinView } from '../../render_core.ts';
+import type { SlotColourFacts, SlotTimelines } from '../facts/slot_colour.ts';
+import { isObj, type Json } from '../values.ts';
+import type { ReadDocument } from './parse.ts';
+
+const list = (v: unknown): Json[] => (Array.isArray(v) ? v.filter(isObj) : []);
+
+/** Every animation's slot timelines as the Spine file states them: `animations.<name>.slots.<slot>.<timeline> = keys`. */
+export function fileSlotTimelines(read: ReadDocument): SlotTimelines[] {
+  const byName = new Map<string, Json>();
+  for (const anim of list(read.json.animations)) if (typeof anim.name === 'string') byName.set(anim.name, anim);
+  const animations: Json = {};
+  for (const name of editorAnimationOrder([...byName.keys()])) {
+    const slots: Json = {};
+    for (const slot of list((byName.get(name) as Json).slots)) {
+      if (typeof slot.name !== 'string') continue;
+      const timelines: Json = {};
+      for (const timeline of list(slot.timelines)) {
+        if (typeof timeline.name === 'string') timelines[timeline.name] = list(timeline.keys).map((key) => ({ ...key }));
+      }
+      slots[slot.name] = timelines;
+    }
+    // An animation keying no slot writes no `slots` group — `emitAnimation`'s `if (animation.slots.size)`.
+    animations[name] = Object.keys(slots).length > 0 ? { slots } : {};
+  }
+  const file = inEditorKeyOrder(withoutParserDefaults({ animations }));
+  const out: SlotTimelines[] = [];
+  for (const [animation, anim] of Object.entries(file.animations)) {
+    if (!isObj(anim) || !isObj(anim.slots)) continue;
+    for (const [slot, timelines] of Object.entries(anim.slots)) if (isObj(timelines)) out.push({ animation, slot, timelines });
+  }
+  return out;
+}
+
+export function modelSlotColour(read: ReadDocument): SlotColourFacts {
+  let view: CompiledDocument | null = null;
+  return {
+    slotTimelines: fileSlotTimelines(read),
+    hasAnimation: (name) => read.doc.animations.some((a) => a.name === name),
+    posedSlot: (animation, slot, time) => {
+      view ??= noSkinView(read.doc);
+      const row = poseRawAnimation(view, animation, [time], {}, 'animation')[1].slots.find((r) => r[0] === slot);
+      if (row === undefined) return undefined;
+      const channel = (v: number | null): number => (v === null ? Number.NaN : v);
+      return { color: { r: channel(row[2]), g: channel(row[3]), b: channel(row[4]), a: channel(row[5]) } };
+    },
+  };
+}

package/src/assertions/model/stage.ts

@@ -0,0 +1,28 @@
+/**
+ * The model side's supply of `StageFacts` (issue #1025, step 4c of #380): the
+ * stage a `rigc-compiled/3` document states (`stated.stage`, issue #1026), or,
+ * for a `/2` or `/1` document, which does not, the stage its caller gives.
+ * A `/3` document given one anyway is refused (`refuseGivenBeside`).
+ *
+ * ⚠️ A caller that gives no stage at all is refused by name rather than read as
+ * "the skeleton declares none": those are two different statements, and only
+ * the second is one the caller made. A stage stated as `null` IS that second
+ * statement, and reads as both extents absent, the way the runtime loads a
+ * header with neither key.
+ *
+ * Links nothing from the runtime.
+ */
+import type { StageFacts } from '../facts/stage.ts';
+import { refuseGivenBeside, type ModelGiven } from './given.ts';
+import type { ReadDocument } from './parse.ts';
+
+export function modelStage(read: ReadDocument, given: ModelGiven | undefined): StageFacts {
+  refuseGivenBeside(read, given);
+  // The document's own statement (issue #1026): `null` is a skeleton that declares none, read as both extents absent.
+  if (read.doc.stated !== null) {
+    const stage = read.doc.stated.stage;
+    return { width: stage?.width, height: stage?.height };
+  }
+  if (given === undefined) throw new Error(`the caller gave no stage; a ${read.doc.spec} document does not state one, so the model side cannot read it`);
+  return { width: given.stage?.width, height: given.stage?.height };
+}

package/src/assertions/model/vertex_polygons.ts

@@ -0,0 +1,71 @@
+/**
+ * The model side's supply of `PolygonFacts` (issue #1025, step 4c of #380):
+ * the document's bounding boxes, clipping attachments and paths, and the
+ * clip ends it states.
+ *
+ * - **The polygons** in the loaded walk's order, `fileOrderedEntries`
+ *   (`./skin_entries.ts`). A polygon's `worldVerticesLength` is twice the
+ *   `vertexCount` the record states — the number the emitter copies into the
+ *   file, which the parser doubles into the length it reads the vertices to
+ *   (`readVertices`); the selftest compares it with spine-core's on every
+ *   call. A path's `closed` and `lengths` are the core's reading of the record
+ *   (`readGeometry`: `closed` absent reads the parser's `false`).
+ * - **The clip ends** in the order the file spells them: the skins by the
+ *   emitter's `editorSkinOrder`, each skin's slot keys by its
+ *   `editorSlotKeyOrder` (both `src/compile.ts`, the functions `emitSkins` is
+ *   handed), each slot's records in table order — every clipping record that
+ *   states an `end`, with the `end` as it states it.
+ *
+ * `encoding` is empty on every polygon: the document states the weighted
+ * form outright, so a run's decode has no subject here.
+ *
+ * Links nothing from the runtime.
+ */
+import { editorSkinOrder, editorSlotKeyOrder } from '../../compile.ts';
+import { shownRow } from '../../core/index.ts';
+import type { ClipEnd, PolygonEntry, PolygonFacts } from '../facts/vertex_polygons.ts';
+import { isObj, type Json } from '../values.ts';
+import { fileOrderedEntries } from './skin_entries.ts';
+import type { ReadDocument } from './parse.ts';
+
+/** The document's own record of one skin entry, as the JSON spells it. */
+export function documentRecord(read: ReadDocument, skin: string, slot: string, placeholder: string): Json {
+  const skins = Array.isArray(read.json.skins) ? read.json.skins.filter(isObj) : [];
+  const table = skins.find((s) => s.name === skin)?.attachments;
+  const record = isObj(table) && isObj(table[slot]) ? (table[slot] as Json)[placeholder] : undefined;
+  if (!isObj(record)) throw new Error(`internal: skin "${skin}" slot "${slot}" placeholder "${placeholder}" is a record the reader returned and the document does not spell`);
+  return record;
+}
+
+/** Every record of the document in the order the Spine file spells it: skins, then each skin's slot keys, then the slot's table. */
+export function fileSpelledEntries(read: ReadDocument): Array<{ skin: string; slot: string; placeholder: string; record: Json }> {
+  const out: Array<{ skin: string; slot: string; placeholder: string; record: Json }> = [];
+  for (const skin of editorSkinOrder(read.doc.skins)) {
+    for (const [slot, table] of Object.entries(editorSlotKeyOrder(skin.attachments))) {
+      for (const placeholder of Object.keys(table)) out.push({ skin: skin.name, slot, placeholder, record: documentRecord(read, skin.name, slot, placeholder) });
+    }
+  }
+  return out;
+}
+
+const WHAT: Readonly<Record<string, string>> = { boundingbox: 'bounding box', clipping: 'clipping attachment', path: 'path' };
+
+export function modelPolygonFacts(read: ReadDocument): PolygonFacts {
+  const polygons: PolygonEntry[] = [];
+  for (const entry of fileOrderedEntries(read)) {
+    const g = entry.record.geometry;
+    if (g === undefined || (g.kind !== 'boundingbox' && g.kind !== 'clipping' && g.kind !== 'path')) continue;
+    const stated = documentRecord(read, entry.skin, entry.slot, entry.placeholder).vertexCount;
+    polygons.push({
+      what: `${WHAT[g.kind]} "${shownRow(entry).name}"`,
+      worldVerticesLength: typeof stated === 'number' ? stated * 2 : Number.NaN,
+      path: g.kind === 'path' ? { closed: g.closed, lengths: g.lengths } : null,
+      encoding: [],
+    });
+  }
+  const clipEnds: ClipEnd[] = [];
+  for (const { slot, placeholder, record } of fileSpelledEntries(read)) {
+    if (record.kind === 'clipping' && record.end !== undefined) clipEnds.push({ placeholder, slot, end: record.end });
+  }
+  return { polygons, clipEnds, slots: read.doc.slots.map((s) => s.name) };
+}

package/src/assertions/reasons.ts

@@ -0,0 +1,127 @@
+/**
+ * What a SKIP says, by what the assertion was denied (issues #568, #580, #608).
+ *
+ * Moved here from `src/validate.ts` by issue #1025 (step 4c of #380), words
+ * unchanged: an assertion body now lives in a module that links nothing from
+ * the runtime (`./bodies/`), and the bodies print these sentences on both
+ * sides — over what spine-core loaded and over the model document. A sentence
+ * kept in the file that links spine-core could not be read by the second.
+ * `src/validate.ts` re-exports every one, so nothing that imported them from
+ * there moves.
+ */
+
+/**
+ * What a SKIP says when `A00_ROUNDTRIP_PARSE` handed an assertion nothing to
+ * look at.
+ *
+ * Two of them rather than one, because what an assertion was denied is the whole
+ * content of its SKIP: `A20` wanted the loaded skeleton and `A06` wanted the
+ * loaded atlas, and a reader who is told which can tell a rule that is waiting
+ * on the parse from one that is waiting on the art. Both point at A00 instead of
+ * restating its detail, which the FAIL row prints in full.
+ *
+ * Exported so a control compares against them rather than quoting them — the
+ * same reason `ASSERTION_NAMES` is exported.
+ */
+export const SKIP_NO_SKELETON = 'the round trip did not produce a skeleton to measure (A00 owns that failure)';
+export const SKIP_NO_ATLAS = 'the round trip did not produce an atlas to measure (A00 owns that failure)';
+/**
+ * The third of them, and it is NOT waiting on A00 (issue #608): the atlas parsed
+ * and it has no pages, which is what a compile that measured no art writes. The
+ * four rules whose only subject is a page — A06, A17, A19, A27 — have nothing to
+ * look at, and an empty loop walking out of `check()` is reported as a PASS.
+ */
+/*
+ * **An empty subject list: SKIP or PASS, and which one is derived (issue #580).**
+ *
+ * `check()` records a pass when a body runs to its end without a `fail()` or a
+ * `skip()`, so a body whose main construct is a loop over a list that is EMPTY
+ * passes having measured nothing — the vacuous green one ring out from the bare
+ * `return` guards issue #568 converted. Two different things can be true of such
+ * a loop, and the criterion decides between them by reading the rule's own name
+ * and its `fail()` sentences rather than by preference:
+ *
+ *   * A name of the form ⟨subject⟩_⟨property⟩ — `REGION_WIDTH_HEIGHT_FINITE`,
+ *     `MESH_TRIANGLES_AND_ENCODING`, `PHYSICS_CONSTRAINT_EFFECTIVE`,
+ *     `ATLAS_PAGE_SIZE_MATCHES_PNG` — quantifies over the subject it names, and
+ *     its `fail()` names a member of that subject, the value found and the value
+ *     required. With no member, nothing was measured: it **SKIPs**, and the
+ *     reason names the subject that was absent.
+ *   * A name of the form NO_⟨construct⟩ — `NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS`,
+ *     `NO_BONE_TRANSFORM_KEY`, `NO_CLIPPING_ATTACHMENTS`, `NO_DARK_COLOR`,
+ *     `NO_FULL_FRAME_MESH` — quantifies over occurrences of something a correct
+ *     artifact has NONE of, and its `fail()` reports that the construct is
+ *     present rather than measuring a value on it. Zero occurrences IS the
+ *     measurement, so it **PASSes**: the loop is a search of the artifact, and
+ *     the artifact is what it measured.
+ *   * A name carrying both halves takes each at its word.
+ *     `A15_IDLE_NO_MESH_BONE_KEYS` is the pattern and already reads this way: no
+ *     `idle` animation, or an `idle` with no bone timeline, is the named subject
+ *     absent and SKIPs; no mesh-driving bone among the bones `idle` does key is
+ *     the construct absent and passes. `A10_NO_NAN_AFTER_STEPPING` was the same
+ *     shape until issue #902, and is the next bullet's now: #882 gave it a
+ *     setup-pose clause whose subject is the bones, beside the stepping clause
+ *     whose subject is the animations.
+ *   * An assertion with more than one clause SKIPs only when EVERY clause had
+ *     nothing to measure, which is the shape `A09`, `A33` and `A38` already
+ *     carry (`polygons.length === 0 && endsChecked === 0`), and `A10` since #902.
+ *     `A13_MESH_BUDGET` is why the clause is stated: a declared slot budget is
+ *     measured against a count of mesh slots, and zero is a count, so that half
+ *     passes on a rig with no mesh — while a rig that declares only a TRIANGLE
+ *     budget has nothing left to measure and skips.
+ *
+ * ⚠️ What the criterion is not allowed to become is a table of assertions with
+ * their verdicts written beside them. Every row above is decided by reading the
+ * name and the sentences the assertion already prints, so a rule added tomorrow
+ * is decided by the same reading and nobody re-opens this question.
+ */
+
+/**
+ * What a SKIP says when the artifact carries no member of the subject a rule
+ * quantifies over (issue #580), by subject.
+ *
+ * One constant per SUBJECT rather than one per assertion, for the reason the two
+ * above are two: what the rule was denied is the whole content of its SKIP, and
+ * three rules denied the same thing should say so in the same words. Exported so
+ * a control compares against them rather than quoting them.
+ */
+export const SKIP_NO_REGION_ATTACHMENT = 'the skeleton carries no region attachment';
+export const SKIP_NO_MESH_ATTACHMENT = 'the skeleton carries no mesh attachment';
+export const SKIP_NO_ANIMATION = 'the skeleton carries no animation';
+/**
+ * A10's (issue #902): its setup clause reads the bones and its stepping clause
+ * the animations, so it skips only when the skeleton carries neither — and the
+ * sentence is `SKIP_NO_ANIMATION`'s with the second subject added, so the two
+ * cannot drift into different words for the same absence.
+ */
+export const SKIP_NO_POSE = `${SKIP_NO_ANIMATION} and no bone, so there is no setup pose to read and nothing to step`;
+export const SKIP_NO_TIMELINE = 'no animation here carries a timeline';
+export const SKIP_NO_PHYSICS_CONSTRAINT = 'the skeleton declares no physics constraint';
+export const SKIP_NO_ATLAS_PAGE = 'the atlas declares no page';
+export const SKIP_NO_ATLAS_REGION = 'the atlas declares no region';
+export const SKIP_NO_ATTACHMENT_REGION_JOIN =
+  'no attachment names a region and the atlas declares none, so there is no attachment-to-region join to hold';
+export const SKIP_NO_TWO_COLOR_TINT =
+  'no slot declares a "dark" colour and no animation keys an "rgba2" or "rgb2" timeline, so there is no two-colour tint to read back';
+export const SKIP_NO_SEPARABLE_COLOR =
+  'no animation keys an "rgb" or "alpha" timeline, so there is no separable slot colour to read back';
+export const SKIP_NO_LINKED_MESH = 'no attachment in this skeleton takes its geometry from another one';
+export const SKIP_NO_SEQUENCE =
+  'no attachment carries a "sequence" block and no animation keys a "sequence" timeline, so there is no numbered series to read back';
+/**
+ * A09's, which predates this list and joins it rather than being rewritten: it
+ * is the same fact about the same subject, and a control that compares against
+ * eight constants and quotes the ninth is a control with a hand-kept exception
+ * in it.
+ */
+export const SKIP_NO_DECLARED_DURATION =
+  'the motion spec declares no animations and the skeleton has none — a static rig has no duration to compare';
+
+/**
+ * The model side's `SKIP_NO_SKELETON` (issue #1025): the reader refused the
+ * document, or the document names a region its pages lack, so a body that
+ * reads the model has nothing to read. It names the two model-side parse
+ * rules rather than A00, because on this side there is no round trip — the
+ * reader and the region rule are what stand in its place (`./model/parse.ts`).
+ */
+export const SKIP_NO_MODEL = 'the model side read no document to measure (A00_MODEL_READ or A00_MODEL_REGIONS_ON_PAGES owns that failure)';

package/src/assertions/region_lookups.ts

@@ -0,0 +1,61 @@
+/**
+ * The region names one skin entry will make a loader look up (issue #1025,
+ * step 4c of #380) — moved here from `src/validate.ts` unchanged, because A08's
+ * body now runs on both sides and the model side links nothing from the
+ * runtime. `src/validate.ts` re-exports both names, so nothing that imported
+ * them from there moves.
+ */
+import { frameRegionName } from '../core/uvs.ts';
+import { isObj } from './values.ts';
+
+/**
+ * The atlas region names one raw skin entry will make the loader look up — or
+ * `null` when the file states a sequence this walk cannot predict.
+ *
+ * ⚠️ Measured against the loader rather than reasoned out, because a join that
+ * merely looks right is the thing A08 exists to refuse. `readSequence`
+ * (`dist/SkeletonJson.js:641-649`) turns an absent or null `sequence` into
+ * `new Sequence(1, false)` — one lookup, at the bare path — and a present one
+ * into `new Sequence(count ?? 0, true)`, so a sequence map with no `count`
+ * looks up nothing at all. Each frame's name is the core's `frameRegionName`
+ * (`src/core/uvs.ts`): `start + i`, left-padded with zeros to `digits`, after
+ * the path (issue #1015). `PS127` records what the loader asks for and compares,
+ * and the core suite holds the frame names to `Sequence.getPath` over 7,680
+ * cases.
+ *
+ * Nothing in `examples/` carries a `sequence` (measured: 0 occurrences across
+ * all twelve editor exports), so without this the assertion would have read a
+ * sequence's base path as a region name and refused correct foreign data —
+ * `A21_MESH_RIM_PINNED`'s old `|| 'ring'` default, one file over.
+ */
+export function attachmentRegionLookups(sequence: unknown, path: string): string[] | null {
+  if (sequence === undefined || sequence === null) return [path];
+  if (!isObj(sequence)) return null;
+  const whole = (value: unknown, fallback: number): number | null => {
+    if (value === undefined) return fallback;
+    return typeof value === 'number' && Number.isInteger(value) ? value : null;
+  };
+  const count = whole(sequence.count, 0);
+  const start = whole(sequence.start, 1);
+  const digits = whole(sequence.digits, 0);
+  if (count === null || start === null || digits === null || count < 0) return null;
+  const series = { count, start, digits, setup: 0 };
+  const lookups: string[] = [];
+  for (let i = 0; i < count; i++) lookups.push(frameRegionName(path, series, i));
+  return lookups;
+}
+
+/** One skin entry's join onto the atlas, as the loader will perform it. */
+export interface AttachmentRegionJoin {
+  skin: string;
+  slot: string;
+  placeholder: string;
+  /** The attachment's own name — the entry's `name` when it states one, else the placeholder. */
+  name: string;
+  /**
+   * Every atlas region name the loader will ask this atlas for, in the order it
+   * asks. Empty for a `sequence` with no `count`, and `null` for a sequence map
+   * this walk will not guess at.
+   */
+  lookups: string[] | null;
+}

package/src/assertions/values.ts

@@ -0,0 +1,39 @@
+/**
+ * How an assertion body reads a value — the helpers the bodies under
+ * `./bodies/` share with the ones still in `src/validate.ts` (issue #1025,
+ * step 4c of #380), moved here unchanged so both read a value one way. Links
+ * nothing from the runtime.
+ */
+
+/** A JSON object as `JSON.parse` returns it. */
+export type Json = Record<string, unknown>;
+
+/** A JSON object, and not an array or `null`. */
+export function isObj(v: unknown): v is Json {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * The time to pose a key at so that the runtime is AT it: the later of the
+ * file's number and that number as spine-core stores it (issue #771).
+ *
+ * 🚨 Every timeline keeps its key times in a `Float32Array`
+ * (`Utils.newFloatArray`), and a key time the float cannot hold exactly is
+ * stored at the nearest one — for `0.2`, `0.20000000298…`, which is LATER than
+ * the double `0.2`. Stepped to the file's own number, a timeline is then just
+ * BEFORE its key: before a first key it writes the setup value (`time <
+ * frames[0]`), and past a stepped key it still holds the one before
+ * (`frames[i] > time`). That is a pose one float step from the key, not the
+ * key's — measured on the selftest's own `ingest_probe`, whose `alpha` key at
+ * 0.2 posed the setup 1.0 and was refused as `the key states value 0.4`.
+ *
+ * ⚠️ The later of the two rather than `Math.fround` alone: where the float
+ * rounds DOWN, the file's number is already past the stored key, and a runtime
+ * built without typed arrays stores the double itself — in both, the file's
+ * number is the one at or after the key. What a key time rounds to is the
+ * runtime's storage and not the file's statement, so a rule judging what a KEY
+ * states poses at the key; the rounding itself is nothing an author can repair.
+ */
+export function atStoredKey(time: number): number {
+  return Math.max(time, Math.fround(time));
+}