spine-rigc 1.9.0 → 1.9.2

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/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/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[];
+}

package/src/assertions/facts/two_colour.ts

@@ -0,0 +1,52 @@
+/**
+ * The two-colour tint (issue #1025, cut 4c-3 of step 4c of #380) — the
+ * census's F02, F18, F22 and R4 as A43 reads them: the dark colour each slot
+ * states and the one the runtime loaded for it, the slot timelines the file
+ * keys, and a slot's light and dark colour posed at a time.
+ *
+ * ⭐ **The file's spelling where A43 prints it, the runtime's reading where it
+ * compares.** A43 parses the stated hex itself — a check that read the
+ * required value out of the parser it checks would agree with it whatever it
+ * did — so the stated `dark` and every key are handed over as the file spells
+ * them; the loaded and the posed colours are the values the runtime holds.
+ *
+ * The slot timelines are `SlotColourFacts`' (`./slot_colour.ts`): one walk of
+ * the file's animations, in its order and its spelling, which A45 reads too.
+ *
+ * Links nothing from the runtime: `validate()` reads it off the skeleton JSON
+ * and the loaded skeleton (`spineTwoColourFacts`), the model side off the
+ * document and the core (`../model/two_colour.ts`).
+ */
+import type { SlotTimelines } from './slot_colour.ts';
+
+/** A dark colour as loaded or posed: three channels, NaN where the reading was no number. */
+export interface DarkColour {
+  readonly r: number;
+  readonly g: number;
+  readonly b: number;
+}
+
+/** A slot's two colours, posed. */
+export interface PosedTint {
+  readonly light: { readonly r: number; readonly g: number; readonly b: number; readonly a: number };
+  /** `null` where the posed slot holds no dark colour. */
+  readonly dark: DarkColour | null;
+}
+
+/** What A43 reads. */
+export interface TwoColourFacts {
+  /** Every slot whose entry states `dark` as a string, in the file's slot order, name and value as the file spells them. */
+  readonly slotDarks: ReadonlyArray<{ readonly slot: string; readonly dark: string }>;
+  /** The setup dark colour the loaded skeleton holds for the slot, or `null` for none (or no such slot). */
+  loadedDark(slot: string): DarkColour | null;
+  /** Every (animation, slot) pair whose timelines the file keys, in the file's order and spelling. */
+  readonly slotTimelines: readonly SlotTimelines[];
+  /** Whether the skeleton holds an animation of this name. */
+  hasAnimation(name: string): boolean;
+  /**
+   * The slot's light and dark 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.
+   */
+  posedTint(animation: string, slot: string, time: number): PosedTint | undefined;
+}

package/src/assertions/inward_advance.ts

@@ -0,0 +1,58 @@
+/**
+ * The deepest inward advance the animation data asks for, in axis pixels —
+ * shared by A29 and A30 (issue #1025, cut 4c-4 of #380), moved here from
+ * `src/validate.ts` unchanged but for what it reads: the bone timelines are a
+ * fact (`./facts/bone_timelines.ts`) rather than the raw JSON.
+ *
+ * Shared by A29 and A30 because they bound the SAME quantity against two
+ * different measured facts. Two things spend the same clearance and so are added:
+ *
+ *   * the stroke — a translateX on a bone in the axis subtree. A24 guarantees
+ *     there is no hidden screen-space component to miss.
+ *   * the mass bone's own inward keys. It typically hangs outside the axis
+ *     subtree, so its keys are screen-space by design and get PROJECTED onto the
+ *     axis rather than read as axis coordinates. Ignoring them would let a rig
+ *     pass while a recoil key closed the last few pixels.
+ *
+ * Links nothing from the runtime.
+ */
+import type { RigInfo } from '../types.ts';
+import type { BoneTimelineFacts } from './facts/bone_timelines.ts';
+import { isObj, type Json } from './values.ts';
+
+export function deepestInwardAdvance({ boneTimelines }: BoneTimelineFacts, rig: RigInfo): { total: number; describe: () => string } {
+  const subtree = new Set(rig.axisSubtree);
+  let strokeMax = 0;
+  let strokeWhere = '';
+  let massMax = 0;
+  let massWhere = '';
+  for (const { animation: animName, bone: boneName, timelines } of boneTimelines) {
+    if (!isObj(timelines)) continue;
+    const keys = (timelines as Json).translate;
+    if (!Array.isArray(keys)) continue;
+    for (const key of keys) {
+      if (!isObj(key)) continue;
+      if (subtree.has(boneName)) {
+        // +x is inward along the axis; a retracted key is negative and spends
+        // no clearance, so only the inward extreme matters.
+        const x = Number(key.x ?? 0);
+        if (Number.isFinite(x) && x > strokeMax) {
+          strokeMax = x;
+          strokeWhere = `${animName}.${boneName} t=${String(key.time ?? 0)}`;
+        }
+      } else if (boneName === rig.massBone && rig.inwardUnit) {
+        const inward = Number(key.x ?? 0) * rig.inwardUnit[0] + Number(key.y ?? 0) * rig.inwardUnit[1];
+        if (Number.isFinite(inward) && inward > massMax) {
+          massMax = inward;
+          massWhere = `${animName}.${boneName} t=${String(key.time ?? 0)}`;
+        }
+      }
+    }
+  }
+  return {
+    total: strokeMax + massMax,
+    describe: () =>
+      `deepest inward advance is ${(strokeMax + massMax).toFixed(3)}px (stroke ${strokeMax.toFixed(3)} at ${strokeWhere}` +
+      `${massMax > 0 ? ` + mass ${massMax.toFixed(3)} at ${massWhere}` : ''})`,
+  };
+}

package/src/assertions/model/animation_durations.ts

@@ -0,0 +1,57 @@
+/**
+ * The model side's supply of `AnimationDurationFacts` (issue #1025, cut 4c-3
+ * of step 4c of #380): the document's animations in the file's order, each
+ * with the runtime's duration and every timeline's own duration.
+ *
+ * Every number is the core's reading, through functions rigc already runs:
+ *
+ * - **The roster's order** is the file's, `fileAnimationOrder` (`src/compile.ts`,
+ *   issue #1034): a `rigc-compiled/3` document's stated `editorOrder`, else the
+ *   emitter's own rule over the document's names — integer-like names first,
+ *   as the file keys them.
+ * - **An animation's duration** is `CoreAnimationTimelines.duration`, the last
+ *   key time of every timeline as float32 — the value `tools/pose_oracle.ts
+ *   compare` holds equal to spine-core's on its `animations` roster.
+ * - **A timeline's own duration** is its last key's time as the core read it
+ *   (float32): each bone and slot timeline, each constraint timeline in the
+ *   order the runtime builds them (`modelConstraintTimelineSources`), each
+ *   attachment's deform and sequence timeline, the draw order and the events.
+ *   How many timelines that makes is the count the runtime builds
+ *   (`timelineCount`, which the selftest's `VF10` holds equal to the runtime's
+ *   on every slider animation); a walk that lists another count is this
+ *   module's defect and throws by name rather than handing A09 a list of the
+ *   wrong length.
+ *
+ * Links nothing from the runtime.
+ */
+import { fileAnimationOrder } from '../../compile.ts';
+import type { AnimationDuration, AnimationDurationFacts } from '../facts/animation_durations.ts';
+import { modelConstraintTimelineSources, timelineCount } from './constraints.ts';
+import type { ReadDocument } from './parse.ts';
+
+/** The last of `times`, which the core read in key order. */
+const lastOf = (times: ReadonlyArray<{ time: number }>): number[] => (times.length === 0 ? [] : [times[times.length - 1].time]);
+
+export function modelAnimationDurations(read: ReadDocument): AnimationDurationFacts {
+  const constraintTimelines = modelConstraintTimelineSources(read);
+  const animations: AnimationDuration[] = [];
+  for (const name of fileAnimationOrder(read.doc)) {
+    const anim = read.doc.animations.find((a) => a.name === name);
+    if (anim === undefined) continue;
+    const t = anim.timelines;
+    const durations: number[] = [];
+    for (const target of [...t.bones, ...t.slots]) for (const tl of target.timelines) durations.push(...lastOf(tl.keys));
+    for (const source of constraintTimelines) if (source.animation === name) durations.push(...lastOf(source.keys));
+    for (const a of t.attachments) {
+      if (a.deform !== null) durations.push(...lastOf(a.deform));
+      if (a.sequence !== null) durations.push(...lastOf(a.sequence));
+    }
+    durations.push(...lastOf(t.drawOrder), ...lastOf(t.events));
+    const built = timelineCount(t);
+    if (durations.length !== built) {
+      throw new Error(`internal: animation "${name}": the durations walk lists ${durations.length} timeline(s) and the core reads ${built}`);
+    }
+    animations.push({ name, duration: t.duration, timelineDurations: durations });
+  }
+  return { animations };
+}

package/src/assertions/model/bone_timelines.ts

@@ -0,0 +1,56 @@
+/**
+ * The model side's supply of `BoneTimelineFacts` (issue #1025, cut 4c-4 of
+ * #380): every animation's bone timelines as the Spine file states them.
+ *
+ * The same reading A45's slot timelines are given (`fileSlotTimelines` in
+ * `./slot_colour.ts`), over the `bones` group: the animations put in the
+ * file's order by `editorAnimationOrder` (`src/compile.ts`, the function the
+ * emitter is handed), each animation's bones and their timelines laid out as
+ * the file lays them (`animations.<name>.bones.<bone>.<timeline> = keys`, in
+ * the document's order, which is the order `emitAnimation` writes the model's
+ * map in), and the whole handed to the emitter's own `withoutParserDefaults`
+ * and `inEditorKeyOrder` (`src/keyorder.ts`) — so a key field the emitter
+ * leaves out at the parser's default (`time: 0`, a translate key's `y: 0`) is
+ * left out here too, and a body printing a key's `time` prints what it prints
+ * over the file. Nothing here restates either rule.
+ *
+ * Links nothing from the runtime.
+ */
+import { editorAnimationOrder } from '../../compile.ts';
+import { inEditorKeyOrder, withoutParserDefaults } from '../../keyorder.ts';
+import type { BoneTimelineFacts, BoneTimelines } from '../facts/bone_timelines.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 bone timelines as the Spine file states them: `animations.<name>.bones.<bone>.<timeline> = keys`. */
+export function fileBoneTimelines(read: ReadDocument): BoneTimelines[] {
+  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 bones: Json = {};
+    for (const bone of list((byName.get(name) as Json).bones)) {
+      if (typeof bone.name !== 'string') continue;
+      const timelines: Json = {};
+      for (const timeline of list(bone.timelines)) {
+        if (typeof timeline.name === 'string') timelines[timeline.name] = list(timeline.keys).map((key) => ({ ...key }));
+      }
+      bones[bone.name] = timelines;
+    }
+    // An animation keying no bone writes no `bones` group — `emitAnimation`'s `if (animation.bones.size)`.
+    animations[name] = Object.keys(bones).length > 0 ? { bones } : {};
+  }
+  const file = inEditorKeyOrder(withoutParserDefaults({ animations }));
+  const out: BoneTimelines[] = [];
+  for (const [animation, anim] of Object.entries(file.animations)) {
+    if (!isObj(anim) || !isObj(anim.bones)) continue;
+    for (const [bone, timelines] of Object.entries(anim.bones)) out.push({ animation, bone, timelines });
+  }
+  return out;
+}
+
+export function modelBoneTimelines(read: ReadDocument): BoneTimelineFacts {
+  return { boneTimelines: fileBoneTimelines(read) };
+}

package/src/assertions/model/constraint_targets.ts

@@ -0,0 +1,82 @@
+/**
+ * The model side's supply of `ConstraintTargetFacts` (issue #1025, cut 4c-5
+ * of step 4c of #380): the document's constraints and every animation's
+ * constraint groups, laid out as the Spine file lays them.
+ *
+ * - **The constraints**: the document's, in its order — which the emitter
+ *   writes the `constraints` array in — each its name and its kind, the word
+ *   the file spells its `type` with.
+ * - **The animations**: in the file's order (`fileAnimationOrder`, issue
+ *   #1034); in each the five groups in A34's fixed order, a group only where
+ *   the document holds an entry for it (`emitAnimation` writes a group only
+ *   when the model holds something for it); each group's entries in the order
+ *   the file keys them — an object the emitter fills in the document's order,
+ *   so its names land as `keyedOrder` lands them, built here as that object;
+ *   the timeline naming no physics constraint under the empty name the
+ *   emitter spells it with, where the document spells it `*`
+ *   (`EVERY_GLOBAL_PHYSICS`); each entry's timelines in the document's order,
+ *   which the emitter writes unchanged (a name-keyed map no key-order pass
+ *   touches, `src/keyorder.ts`). A document the reader accepted states every
+ *   key array as a non-empty list, a named group's entry as named timelines,
+ *   and only constraints of the kind its group names, so the clauses that
+ *   refuse those shapes have nothing to fire on here.
+ * - **The reach** of a physics timeline naming none: the core's own reading,
+ *   `unnamedReach` (`./constraints.ts`, which poses the timeline through
+ *   `posedPhysics` and reads which records took the key), over the document's
+ *   physics records in its order. The reader refuses a physics timeline name
+ *   it does not know, so every name asked of it is one the core poses.
+ *
+ * Links nothing from the runtime.
+ */
+import { fileAnimationOrder } from '../../compile.ts';
+import { EVERY_GLOBAL_PHYSICS, PHYSICS_TIMELINE_KINDS, type CorePhysicsRecord } from '../../core/constraints_physics.ts';
+import type { ConstraintTargetFacts, TargetAnimation, TargetEntry, TargetKeyArray } from '../facts/constraint_targets.ts';
+import { isObj, type Json } from '../values.ts';
+import { unnamedReach } from './constraints.ts';
+import type { ReadDocument } from './parse.ts';
+
+const list = (v: unknown): Json[] => (Array.isArray(v) ? v.filter(isObj) : []);
+const keyArray = (timeline: string, keys: unknown): TargetKeyArray => ({ timeline, keys: Array.isArray(keys) ? { count: keys.length } : { spelled: `${JSON.stringify(keys)}` } });
+
+/** One group's entries as the file keys them: an object filled in the document's order, read back in its key order. */
+function fileEntries(group: 'ik' | 'transform' | 'path' | 'physics' | 'slider', entries: readonly Json[]): TargetEntry[] {
+  const keyed: Record<string, TargetEntry> = {};
+  for (const entry of entries) {
+    if (typeof entry.name !== 'string') continue;
+    const name = group === 'physics' && entry.name === EVERY_GLOBAL_PHYSICS ? '' : entry.name;
+    keyed[name] =
+      group === 'ik' || group === 'transform'
+        ? { name, bare: null, keyArrays: [keyArray('', entry.keys)] }
+        : { name, bare: null, keyArrays: list(entry.timelines).flatMap((t) => (typeof t.name === 'string' ? [keyArray(t.name, t.keys)] : [])) };
+  }
+  return Object.values(keyed);
+}
+
+export function modelConstraintTargets(read: ReadDocument): ConstraintTargetFacts {
+  const { doc } = read;
+  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: TargetAnimation[] = [];
+  for (const name of fileAnimationOrder(doc)) {
+    const anim = byName.get(name);
+    if (anim === undefined) continue;
+    const groups: TargetAnimation['groups'][number][] = [];
+    const constraints = isObj(anim.constraints) ? anim.constraints : {};
+    for (const group of ['ik', 'transform', 'path', 'physics', 'slider'] as const) {
+      const entries = list(constraints[group]);
+      if (entries.length > 0) groups.push({ group, entries: fileEntries(group, entries) });
+    }
+    animations.push({ name, groups });
+  }
+  const records = doc.constraints.flatMap((c): CorePhysicsRecord[] => (c.record?.kind === 'physics' ? [c.record] : []));
+  return {
+    constraints: doc.constraints.map((c) => ({ name: c.name, type: c.kind, spelled: c.name })),
+    groupsByAnimation: animations,
+    reach: (timeline) => {
+      const kind = PHYSICS_TIMELINE_KINDS.find((k) => k === timeline);
+      if (kind === undefined) return null;
+      const reached = unnamedReach(records, kind);
+      return { resets: kind === 'reset', reached: records.filter((r) => reached.has(r.name)).map((r) => r.name) };
+    },
+  };
+}