rig-c 0.0.0-stage → 2.20.4

package/src/assertions/kinds.ts

@@ -0,0 +1,105 @@
+/**
+ * What kind of rule each assertion is, and which profile runs which kind
+ * (issue #1025, step 4c of #380).
+ *
+ * The table lives here rather than in `src/validate.ts` because two harnesses
+ * read it now: `validate()`'s `check`, which runs an assertion over what
+ * spine-core loaded, and the model side's (`./harness.ts`), which runs the
+ * same body over the model document and the core. A profile has to exclude
+ * the same rules on both sides, and two copies of the table is how one of
+ * them would come to exclude a rule the other runs. This module links nothing
+ * from the runtime, which is the condition for the model side to read it.
+ */
+
+/** The two rulebooks — `ValidateProfile` in `src/validate.ts`, where the choice between them is argued. */
+export type AssertionProfile = 'spine' | 'spine-html';
+
+/** The three kinds a rule can be; the table's own comment says what each means. */
+export type AssertionKind = 'validity' | 'renderer' | 'archetype';
+
+/**
+ * What kind of rule each assertion is. Every assertion has an entry, and
+ * `check()` throws on a name that has none — a new assertion must state its kind
+ * rather than defaulting into one, because the default would decide, silently,
+ * whether it runs on foreign data.
+ *
+ *   validity  — the file is wrong for any consumer. Runs under every profile.
+ *   renderer  — valid Spine that this project's renderer or frame budget refuses.
+ *   archetype — a structural rule about rigc's own formations, meaningless to a
+ *               skeleton rigc did not compile.
+ *
+ * Two assertions are MIXED and are marked `validity` here because their
+ * validity half must never stop running; their policy clauses are gated inside
+ * the assertion body against `profile`, and each such clause says so where it
+ * lives. They are A06 (size-vs-PNG and every region's rectangle inside the page
+ * it names are validity; pma and rotation are policy — the rectangle moved
+ * across that line in issue #694, and the reason is stated where it now sits;
+ * the policy clause about two regions over the same texels left A06 for
+ * `A49_PACKED_FOOTPRINTS_DO_NOT_OVERLAP` in issue #1099, a renderer rule of
+ * its own) and A20 (weight coherence is validity; requiring
+ * a mesh to be weighted at all is policy).
+ *
+ * A08 was the third until issue #574 retired its policy clause. It required a
+ * skin entry's placeholder to be spelled like the region it resolves to, under
+ * a renderer that resolves art by `path` and has never read a placeholder — so
+ * restating it as the renderer's own join made it a tautology over the validity
+ * half. The argument, with the renderer lines it is measured against, sits above
+ * `check('A08_…')`.
+ */
+export const ASSERTION_KIND: Readonly<Record<string, AssertionKind>> = {
+  A00_ROUNDTRIP_PARSE: 'validity',
+  A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS: 'validity',
+  A02_NO_BONE_TRANSFORM_KEY: 'validity',
+  A03_REGION_WIDTH_HEIGHT_FINITE: 'validity',
+  A04_MESH_TRIANGLES_AND_ENCODING: 'validity',
+  A05_CURVE_ARRAY_LENGTH: 'validity',
+  A06_ATLAS_PAGE_SIZE_MATCHES_PNG: 'validity', // mixed — see above
+  A07_ATLAS_TEXT_SHAPE: 'validity',
+  A08_REGION_NAMES_MATCH_ATTACHMENTS: 'validity', // no longer mixed — see above (#574)
+  A09_ANIMATION_DURATION_MATCHES_SPEC: 'validity',
+  A10_NO_NAN_AFTER_STEPPING: 'validity',
+  A11_NO_CLIPPING_ATTACHMENTS: 'renderer',
+  A12_NO_DARK_COLOR: 'renderer',
+  A13_MESH_BUDGET: 'renderer',
+  A14_NO_FULL_FRAME_MESH: 'renderer',
+  A15_IDLE_NO_MESH_BONE_KEYS: 'renderer',
+  A16_SKELETON_VERSION_4_3: 'validity',
+  A17_ATLAS_PAGE_FILES_EXIST: 'validity',
+  A18_DETERMINISTIC_EMIT: 'validity',
+  A19_OVERLAY_PNGS_HAVE_ALPHA: 'renderer',
+  A20_MESH_WEIGHTS_COHERENT: 'validity', // mixed — see above
+  A21_MESH_RIM_PINNED: 'archetype',
+  A22_MESH_UVS_IN_UNIT_RANGE: 'validity',
+  A23_PHYSICS_CONSTRAINT_EFFECTIVE: 'validity',
+  A24_AXIS_SPACE_STROKE: 'archetype',
+  A25_DETACHED_BONE_PARENTAGE: 'archetype',
+  A26_SLOT_DRAW_ORDER: 'archetype',
+  A27_REGION_NAME_MATCHES_PAGE_FILENAME: 'renderer',
+  A28_RIBBON_ROWS_SHARE_WEIGHTS: 'archetype',
+  A29_STROKE_WITHIN_CONTACT_DEPTH: 'archetype',
+  A30_STROKE_WITHIN_CAP_CONTAINMENT: 'archetype',
+  A31_DRAW_ORDER_OFFSETS_RESOLVE: 'validity',
+  A32_EVENT_KEYS_RESOLVE: 'validity',
+  A33_VERTEX_ATTACHMENT_GEOMETRY: 'validity',
+  A34_CONSTRAINT_TIMELINE_TARGETS: 'validity',
+  A35_DEFORM_KEYS_FIT_THE_ATTACHMENT: 'validity',
+  A36_PATH_CONSTRAINT_EFFECTIVE: 'validity',
+  A37_SLIDER_CONSTRAINT_EFFECTIVE: 'validity',
+  A38_SKIN_MEMBERS_ARE_SKIN_REQUIRED: 'validity',
+  A39_DEFORM_KEEPS_TRIANGLE_WINDING: 'archetype',
+  A40_SLIDERS_COMPOSE_ON_A_SHARED_TARGET: 'validity',
+  A42_DRIVEN_CONSTRAINTS_UPDATE_AFTER_THEIR_DRIVER: 'validity',
+  A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN: 'validity',
+  A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN: 'validity',
+  A45_SEPARABLE_COLOR_TIMELINES_OWN_THEIR_CHANNELS_AND_POSE_AS_WRITTEN: 'validity',
+  A46_SEQUENCE_ATTACHMENTS_SHOW_THE_FRAME_THE_FILE_STATES: 'validity',
+  A47_IK_CONSTRAINT_NOT_MUTED_THROUGHOUT: 'validity',
+  A48_TRANSFORM_CONSTRAINT_NOT_MUTED_THROUGHOUT: 'validity',
+  A49_PACKED_FOOTPRINTS_DO_NOT_OVERLAP: 'renderer',
+  A50_STAGE_BOX_IS_THE_STAGE: 'validity',
+};
+
+/** Whether `profile` runs a rule of `kind`: `spine` runs validity alone, `spine-html` every kind. */
+export function kindRunsUnder(kind: AssertionKind, profile: AssertionProfile): boolean {
+  return kind === 'validity' || profile === 'spine-html';
+}

package/src/assertions/mesh_kinds.ts

@@ -0,0 +1,56 @@
+/**
+ * What built a mesh, as the bodies that hold generator topology to its own
+ * rules ask it (issue #1025, step 4c of #380) — `A20`, `A21` and `A28`. Moved
+ * here from `validate()`'s closures unchanged but for what they read: a mesh
+ * entry of `./facts/mesh_attachments.ts` rather than a loaded attachment and
+ * the prelude's link map. Links nothing from the runtime.
+ */
+import type { RigInfo } from '../types.ts';
+import type { MeshEntry } from './facts/mesh_attachments.ts';
+
+/**
+ * What built this mesh. ring unless the rig says otherwise; absent rig info
+ * reads as ring (legacy).
+ *
+ * 🚨 `authored` is not a third topology, it is the ABSENCE of one rigc may
+ * assume. Geometry that came in through the rig spec was drawn by somebody
+ * with an editor, and its rim, its row pairing and its entry edge are
+ * whatever that person made them. The `||` fallback below used to hand such
+ * a mesh the string `ring`, and A21 then checked ring topology on a shape
+ * that was never a ring — 40 failures on correct data (issue #44).
+ *
+ * 🔗 A LINKED mesh borrows another attachment's geometry, so no generator
+ * topology is a claim about THIS attachment — and the ARTIFACT says which
+ * ones they are (the entry's `link`, read off the file's own `source` keys).
+ * It is read from there rather than off `meshKinds` for two reasons, and the
+ * second is the load-bearing one.
+ *
+ *   1. `meshKinds` is keyed by SLOT, and a link's slot is not its
+ *      geometry's: a link to a `ring` in another slot looked up the LINK's
+ *      slot, found nothing, and took the `|| 'ring'` fallback — issue #44's
+ *      own default, reached by a new route. Measured before this clause on
+ *      a correct rig (a ring on slot "sa", a link to it on slot "sb"):
+ *      **8 A21 failures**, `mesh "sb" rim vertex 0 is pinned to "a", not
+ *      the slot bone "b"`, one per hull vertex. The rim is pinned exactly
+ *      where the ring's own slot put it, which is the only place it could
+ *      be.
+ *   2. Writing the link into `meshKinds` instead would have overwritten
+ *      the source's kind wherever the two share a slot, which is the
+ *      commonest linked mesh there is — silencing A21 on the mesh rigc
+ *      DID build. A gate turned off by a feature is worse than a gate
+ *      that skips something it cannot measure.
+ */
+export function meshKindOf(mesh: MeshEntry, rig: RigInfo | undefined): RigInfo['meshKinds'][string] {
+  if (mesh.link !== null) return 'authored';
+  return rig?.meshKinds[mesh.slot] || 'ring';
+}
+
+/**
+ * Meshes whose topology is not rigc's to have an opinion about, by name and
+ * with the reason each one is on the list — the string several skips need.
+ */
+export function authoredMeshNames(list: readonly MeshEntry[], rig: RigInfo | undefined): string[] {
+  return list
+    .filter((m) => meshKindOf(m, rig) === 'authored')
+    .map((m) => (m.link === null ? `"${m.name}"` : `"${m.name}" (linked to "${m.link.source}")`));
+}

package/src/assertions/model/animated_bones.ts

@@ -0,0 +1,38 @@
+/**
+ * The model side's supply of `AnimatedBoneFacts` (issue #1025, step 4c of
+ * #380): an animation's bone timelines as the document lists them.
+ *
+ * The document writes each animation's `bones` as a list in the model's map
+ * order, and the emitter writes the Spine file's `bones` group from that same
+ * map, entry for entry, leaving the group out when it is empty
+ * (`emitAnimation`'s `if (animation.bones.size)`) — so an empty list is a file
+ * with no `bones` group, and an animation the document does not hold is one the
+ * file does not key. The first animation of a name answers, as the file's
+ * object would hold only one.
+ *
+ * 🔢 **The order is `keyedOrder` over the list's, not the list's** (issue
+ * #1039). The group is an object keyed by bone name, so the file lists an
+ * array-index name (`5`, `10`) first whatever order the emitter filled it in —
+ * measured on a walk whose tracks key `-a, 5, 2b, 10, …`: the document lists
+ * that, the file and spine-core `5, 10, -a, 2b, …`, and A15 prints one line per
+ * keyed bone in the file's order.
+ *
+ * Links nothing from the runtime.
+ */
+import { keyedOrder } from '../../compile.ts';
+import type { AnimatedBoneFacts } from '../facts/animated_bones.ts';
+import { isObj } from '../values.ts';
+import type { ReadDocument } from './parse.ts';
+
+export function modelAnimatedBones(read: ReadDocument): AnimatedBoneFacts {
+  const animations = Array.isArray(read.json.animations) ? read.json.animations.filter(isObj) : [];
+  return {
+    bonesKeyedBy: (name) => {
+      const animation = animations.find((a) => a.name === name);
+      if (animation === undefined) return undefined;
+      const bones = Array.isArray(animation.bones) ? animation.bones.filter(isObj) : [];
+      if (bones.length === 0) return null;
+      return keyedOrder(bones.map((bone) => String(bone.name)));
+    },
+  };
+}

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/atlas_pages.ts

@@ -0,0 +1,15 @@
+/**
+ * The model side's supply of `AtlasPageFacts` (issue #1025, step 4c of #380):
+ * the document's `pages` section, which `build` spells from the atlas text it
+ * writes (`pagesOfAtlas` in `src/model.ts`), so the page names are the ones
+ * the written atlas names, in its order and trimmed as the parser trims them.
+ * A `rigc-compiled/1` document states no pages, and reads as no atlas.
+ *
+ * Links nothing from the runtime.
+ */
+import type { AtlasPageFacts } from '../facts/atlas_pages.ts';
+import type { ReadDocument } from './parse.ts';
+
+export function modelAtlasPages(read: ReadDocument): AtlasPageFacts {
+  return { atlas: read.doc.pages === null ? null : { pages: read.doc.pages.map((page) => ({ name: page.name })) } };
+}

package/src/assertions/model/atlas_regions.ts

@@ -0,0 +1,76 @@
+/**
+ * The model side's supply of `AtlasRegionFacts` (issue #1025, step 4c of
+ * #380): the document's `pages` section — which `build` spells from the atlas
+ * text it writes (`pagesOfAtlas` in `src/model.ts`, the reader `PKR01` holds
+ * field for field to spine-core's `TextureAtlas`) — with each page's `pma` as
+ * a `rigc-compiled/3` document states it (issue #1026), or, for a `/2`
+ * document, which does not, as the caller gives it.
+ *
+ * - The pages and their regions in the document's order, which is the atlas
+ *   file's; each region carries the page it sits on.
+ * - `findRegion` is the core's lookup, called: `documentPageLookup`
+ *   (`src/core/uvs.ts`), the first region of exactly that spelling with pages
+ *   in order — the runtime's `findRegion`, measured there.
+ * - A `rigc-compiled/1` document states no pages, and reads as no atlas.
+ *
+ * ⚠️ On a `/2` document `pma` is the one value here the document does not
+ * hold. A caller that gives none, or gives a list that is not one value per
+ * page, is refused by name rather than read as `false`: a page's claim the
+ * caller did not state is not a claim of straight alpha. On a `/3` document a
+ * caller that gives one anyway is refused too (`refuseGivenBeside`): the
+ * document is the statement, and a second source for the same fact is how a
+ * verdict comes to read one value while the document says another.
+ *
+ * Links nothing from the runtime.
+ */
+import { documentPageLookup } from '../../core/uvs.ts';
+import type { ModelPageRegion } from '../../model.ts';
+import type { AtlasRegionEntry, AtlasRegionFacts, AtlasRegionPage } from '../facts/atlas_regions.ts';
+import type { ReadDocument } from './parse.ts';
+import { refuseGivenBeside, type ModelGiven } from './given.ts';
+
+export function modelAtlasRegions(read: ReadDocument, given: ModelGiven | undefined): AtlasRegionFacts {
+  refuseGivenBeside(read, given);
+  const pages = read.doc.pages;
+  if (pages === null) return { atlas: null };
+  // A rigc-compiled/3 document states each page's pma (issue #1026); `readModel` requires it on every /3 page.
+  const pma = read.doc.stated !== null ? pages.map((page) => page.pma) : given?.pma;
+  if (pma === undefined || pma.length !== pages.length || pma.some((v) => typeof v !== 'boolean')) {
+    throw new Error(`the caller gave ${pma === undefined ? 'no' : pma.length} page pma value(s) for the document's ${pages.length} page(s); a ${read.doc.spec} document does not state pma, so the model side cannot read a page without it`);
+  }
+  const outPages: AtlasRegionPage[] = [];
+  const regions: AtlasRegionEntry[] = [];
+  const byRecord = new Map<ModelPageRegion, AtlasRegionEntry>();
+  pages.forEach((page, i) => {
+    const at: AtlasRegionPage = { name: page.name, width: page.width, height: page.height, pma: pma[i] === true };
+    outPages.push(at);
+    for (const region of page.regions) {
+      const entry: AtlasRegionEntry = {
+        name: region.name,
+        page: at,
+        x: region.x,
+        y: region.y,
+        width: region.width,
+        height: region.height,
+        degrees: region.degrees,
+        offsetX: region.offsetX,
+        offsetY: region.offsetY,
+        originalWidth: region.originalWidth,
+        originalHeight: region.originalHeight,
+      };
+      regions.push(entry);
+      byRecord.set(region, entry);
+    }
+  });
+  const lookup = documentPageLookup(pages);
+  return {
+    atlas: {
+      pages: outPages,
+      regions,
+      findRegion: (name) => {
+        const found = lookup(name);
+        return found === null ? null : (byRecord.get(found.region) ?? null);
+      },
+    },
+  };
+}

package/src/assertions/model/bone_timelines.ts

@@ -0,0 +1,58 @@
+/**
+ * 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`,
+ * filled in the document's order, which is the order `emitAnimation` writes
+ * the model's map in — and read back out of that object, so an array-index
+ * bone name comes first as it does in the file: issue #1039 measured this
+ * reader already walking the file's order), 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) };
+    },
+  };
+}