spine-rigc 1.9.2 → 1.9.4

package/src/slots.ts

@@ -54,7 +54,7 @@ import {
   type Frame,
   type Footprint,
   type Viewport,
-} from './render.ts';
+} from './render_shared.ts';
 
 /** Components smaller than this are antialiasing crumbs, not parts. */
 const MIN_COMPONENT_PIXELS = 4;

package/src/spine_side.ts

@@ -0,0 +1,123 @@
+/**
+ * The seam the Spine side registers into (issue #1052, step 4e of #380).
+ *
+ * ⭐ Everything rigc does without spine-core lives in modules that link
+ * nothing of it — the posing seam and its samplers, the candidate and its
+ * poser choice, the framing and the rasteriser (`./render_shared.ts`), the
+ * deform survey's choice of reader (`./deformbuild.ts`). Where one of those
+ * reaches an input only the runtime can read — a Spine export, `--poser
+ * spine`, a fallback the poser line names, a skeleton spine-core already
+ * parsed — it asks this registry for the Spine side instead of importing it.
+ * The modules that link the runtime fill it when they are loaded:
+ * `./render.ts` registers the posing side (spine-core's poser, the export's
+ * loader, its atlas reader), `./deformmeasure.ts` the survey's spine-core
+ * reader and poser. So a program that imports either of them — `cli.ts`, the
+ * tools, the selftest — behaves exactly as it did before the registry
+ * existed, and an entry that imports neither links nothing of the runtime and
+ * refuses such an input by name (`SpineRuntimeError`, the sentence below).
+ *
+ * 🔒 Nothing here is a fallback or a default. With nothing registered, the
+ * question "what would spine-core say about this input" has no answer, and
+ * the refusal says which input asked it and why it needed the runtime.
+ */
+import type { DeformSurvey } from './deformsurvey.ts';
+import type { DeformSurveyInput } from './deformbuild.ts';
+import type { Poser, SkeletonFacts, SkinRoster, SubstituteRegion } from './render_shared.ts';
+
+/**
+ * A skeleton spine-core parsed, as the side of the seam that does not link
+ * the runtime holds it: opaque. Only the module that registered the posing
+ * side reads it (`SkeletonData` in `./render.ts`), so nothing here names the
+ * runtime's type.
+ */
+export type SpineSkeletonData = object;
+
+/**
+ * Posing an input through spine-core when the runtime cannot be reached —
+ * refused naming the input and why it needs the runtime (issue #1014).
+ *
+ * A Spine export, `--poser spine` and a fallback the poser line names are what
+ * spine-core is loaded for; a rigc build the core poses reads nothing through
+ * it. So the one run that can meet a runtime it cannot use is one of those
+ * three, and it says so rather than surfacing whatever the first access threw.
+ *
+ * Since issue #1052 it is also the refusal of an entry that registered no
+ * Spine side (`SPINE_SIDE_ABSENT`): the same three inputs, the same sentence,
+ * and the reason is that the runtime is not linked at all.
+ */
+export class SpineRuntimeError extends Error {}
+
+/** What `render` and `check` say after the reason, naming what the runtime is for. */
+export const POSING_RUNTIME_TAIL =
+  'spine-core is what poses a Spine export, --poser spine and a fallback the poser line names; ' +
+  'a rigc build the core poses reads nothing through it';
+
+/** What `explain`'s deform survey says after the reason. */
+export const SURVEY_RUNTIME_TAIL =
+  'spine-core is what reads and poses a Spine export, --poser spine and a fallback the survey names; ' +
+  'a rigc build the core poses reads nothing through it';
+
+/**
+ * The reason an entry that registered no Spine side gives — in the place the
+ * runtime's own error stands when it is linked and cannot be used.
+ */
+export const SPINE_SIDE_ABSENT = 'the runtime side is not installed in this entry, which links nothing of spine-core';
+
+/** The one sentence a run that needs the runtime and cannot use it is refused in — `tail` says what the runtime is for. */
+export function spineRuntimeSentence(label: string, why: string, reason: string, tail: string): string {
+  return `${label} is posed through spine-core (${why}), and the runtime could not be used: ${reason}. ${tail}`;
+}
+
+/** What `./render.ts` registers: spine-core's poser, the export's loader and its atlas reader. */
+export interface SpinePosingSide {
+  /** Touch the runtime once and refuse by name when it cannot be used (`SpineRuntimeError`). */
+  requireRuntime(label: string, why: string): void;
+  /** A skeleton parsed against its atlas; a pair the runtime cannot load is `refuse`'s refusal, given the runtime's message. */
+  skeletonData(skeletonText: string, atlasText: string, refuse: (runtime: string) => Error): SpineSkeletonData;
+  /** What `render` and `check` read off a skeleton spine-core parsed, `atlasText` the atlas it was parsed through. */
+  facts(data: SpineSkeletonData, atlasText: string | null): SkeletonFacts;
+  /** spine-core's implementation of the posing seam over a parsed skeleton. */
+  poser(data: SpineSkeletonData): Poser;
+  /** The skin roster of a parsed skeleton, as the runtime flags its bones under each skin. */
+  skinRoster(data: SpineSkeletonData): SkinRoster;
+  /** The page names an atlas declares, in its order, as the runtime's atlas reader reads them. */
+  atlasPageNames(atlasText: string): string[];
+  /** An atlas's pages and regions as the runtime reads them, for a texture substitution. */
+  substitution(atlasText: string): { pages: string[]; regions: Map<string, SubstituteRegion> };
+}
+
+/** What `./deformmeasure.ts` registers: the deform survey read and posed through spine-core. */
+export interface SpineSurveySide {
+  /** The survey of `input`'s Spine skeleton through the runtime; `why` the reason the survey names (`null`: `--poser spine`). */
+  throughSpine(label: string, why: string | null, input: DeformSurveyInput, exempt: ReadonlySet<string>): DeformSurvey;
+}
+
+let posing: SpinePosingSide | null = null;
+let survey: SpineSurveySide | null = null;
+
+/** Called by `./render.ts` when it is loaded. */
+export function registerSpinePosing(side: SpinePosingSide): void {
+  posing = side;
+}
+
+/** Called by `./deformmeasure.ts` when it is loaded. */
+export function registerSpineSurvey(side: SpineSurveySide): void {
+  survey = side;
+}
+
+/** The posing side, or a refusal of `label` (needed for `why`) naming the runtime as absent. */
+export function spinePosingFor(label: string, why: string): SpinePosingSide {
+  if (posing === null) throw new SpineRuntimeError(spineRuntimeSentence(label, why, SPINE_SIDE_ABSENT, POSING_RUNTIME_TAIL));
+  return posing;
+}
+
+/** The survey side, or a refusal of `label` (needed for `why`) naming the runtime as absent. */
+export function spineSurveyFor(label: string, why: string): SpineSurveySide {
+  if (survey === null) throw new SpineRuntimeError(spineRuntimeSentence(label, why, SPINE_SIDE_ABSENT, SURVEY_RUNTIME_TAIL));
+  return survey;
+}
+
+/** Which sides are registered in this process — what an entry's own report of itself reads. */
+export function registeredSpineSides(): { posing: boolean; survey: boolean } {
+  return { posing: posing !== null, survey: survey !== null };
+}

package/src/validate.ts

@@ -87,7 +87,7 @@ import { a11NoClippingAttachments } from './assertions/bodies/a11.ts';
 import { a17AtlasPageFilesExist } from './assertions/bodies/a17.ts';
 import { a45SeparableColorTimelinesOwnTheirChannelsAndPoseAsWritten } from './assertions/bodies/a45.ts';
 import { attachmentRegionLookups, type AttachmentRegionJoin } from './assertions/region_lookups.ts';
-import type { MeshEntry, SkinMeshFacts } from './assertions/facts/skin_meshes.ts';
+import { attachmentRegionJoins } from './region_joins.ts';
 import type { AnimatedBoneFacts } from './assertions/facts/animated_bones.ts';
 import type { RegionJoinFacts } from './assertions/facts/region_joins.ts';
 import type { StageFacts } from './assertions/facts/stage.ts';
@@ -458,46 +458,9 @@ const SPINE_4_3: SpineGeneration = '4.3';
 // sides, and the model side links nothing from the runtime. Re-exported here.
 export { attachmentRegionLookups, type AttachmentRegionJoin };
 
-/**
- * Every atlas-region lookup `AtlasAttachmentLoader` will perform, read off the
- * RAW skeleton JSON — before the loader is asked, which is the whole point.
- *
- * 🚨 This is a SECOND implementation of a join `spine-core` already performs,
- * and the tree's standing judgment about a second opinion on somebody else's
- * format is that it is measured rather than asserted: `PS127` runs the loader
- * with its `findRegion` recording what it asked for, and compares. A wrong walk
- * here would refuse correct foreign data by name, which is the one failure that
- * would be worse than the silence #589 removed.
- *
- * Which entries resolve a region is the parser's list, not a guess:
- * `SkeletonJson.readAttachment` (`dist/SkeletonJson.js:524-575`) calls the
- * loader with a path for `region`, `mesh` and `linkedmesh` — a linked mesh
- * resolves its own region before the `source` branch — and for nothing else.
- * `type` defaults to `region` (`:527`), `name` to the placeholder (`:526`) and
- * `path` to the name (`:529`, `:560`): three names that default into one
- * another, which is why a report printing only the last of them cannot say
- * what to change.
- */
-export function attachmentRegionJoins(raw: unknown): AttachmentRegionJoin[] {
-  const joins: AttachmentRegionJoin[] = [];
-  if (!isObj(raw) || !Array.isArray(raw.skins)) return joins;
-  for (const skin of raw.skins as unknown[]) {
-    if (!isObj(skin) || !isObj(skin.attachments)) continue;
-    const skinName = typeof skin.name === 'string' ? skin.name : '(unnamed)';
-    for (const [slot, entries] of Object.entries(skin.attachments)) {
-      if (!isObj(entries)) continue;
-      for (const [placeholder, entry] of Object.entries(entries)) {
-        if (!isObj(entry)) continue;
-        const type = entry.type === undefined ? 'region' : entry.type;
-        if (type !== 'region' && type !== 'mesh' && type !== 'linkedmesh') continue;
-        const name = typeof entry.name === 'string' ? entry.name : placeholder;
-        const path = typeof entry.path === 'string' ? entry.path : name;
-        joins.push({ skin: skinName, slot, placeholder, name, lookups: attachmentRegionLookups(entry.sequence, path) });
-      }
-    }
-  }
-  return joins;
-}
+// `attachmentRegionJoins` is `./region_joins.ts`'s since issue #1052: `explain` reads it, and an entry that links
+// nothing of the runtime has to be able to load what `explain` reads. Re-exported here.
+export { attachmentRegionJoins };
 
 /**
  * The mesh keys the `source` branch never reaches — the geometry a linked mesh
@@ -923,7 +886,6 @@ export function runtimeFacts(skeletonText: string, atlasText: string): {
   skinEntries: SkinEntryFacts;
   atlasPages: AtlasPageFacts;
   slotColour: SlotColourFacts;
-  skinMeshes: SkinMeshFacts;
   animatedBones: AnimatedBoneFacts;
   skinMembers: SkinMemberFacts;
   regionJoins: RegionJoinFacts;
@@ -946,7 +908,6 @@ export function runtimeFacts(skeletonText: string, atlasText: string): {
     skinEntries: spineSkinEntries(data),
     atlasPages: { atlas },
     slotColour: spineSlotColourFacts(raw, data),
-    skinMeshes: spineSkinMeshes(data),
     animatedBones: spineAnimatedBones(raw),
     skinMembers: data,
     regionJoins: spineRegionJoins(atlasText, raw),
@@ -1274,48 +1235,6 @@ export function spineSequenceFacts(raw: Json | null, data: ReturnType<SkeletonJs
   };
 }
 
-/**
- * The runtime's supply of `SkinMeshFacts` (issue #1025, cut 4c-1): every
- * loaded `MeshAttachment` of every skin, linked meshes included, in the loaded
- * skins' order — the walk this file's prelude makes for `meshAttachments` —
- * with its slot and that slot's bone, and the bones its weights name decoded
- * off the loaded index run, a bone index the skeleton lacks left out as A15
- * always left it out. The model side's supply is
- * `./assertions/model/skin_meshes.ts`.
- */
-export function spineSkinMeshes(data: ReturnType<SkeletonJson['readSkeletonData']>): SkinMeshFacts {
-  const meshes: MeshEntry[] = [];
-  for (const skin of data.skins) {
-    for (const entry of skin.getAttachments()) {
-      const mesh = entry.attachment;
-      if (!(mesh instanceof MeshAttachment)) continue;
-      const weightBones: string[] = [];
-      if (mesh.bones) {
-        for (let i = 0; i < mesh.bones.length; ) {
-          const boneCount = mesh.bones[i++];
-          for (let n = 0; n < boneCount; n++, i++) {
-            const bone = data.bones[mesh.bones[i]];
-            if (bone) weightBones.push(bone.name);
-          }
-        }
-      }
-      const slot = data.slots[entry.slotIndex];
-      meshes.push({
-        name: mesh.name,
-        slot: slot.name,
-        slotBone: slot.boneData.name,
-        triangles: mesh.triangles,
-        width: mesh.width,
-        height: mesh.height,
-        regionUVs: mesh.regionUVs,
-        worldVerticesLength: mesh.worldVerticesLength,
-        weightBones,
-      });
-    }
-  }
-  return { meshes };
-}
-
 /**
  * The runtime's supply of `AnimatedBoneFacts` (issue #1025, cut 4c-1): read
  * off the skeleton JSON, as A15 always read the bones `idle` keys — an
@@ -1410,6 +1329,8 @@ export function spineMeshFacts(data: ReturnType<SkeletonJson['readSkeletonData']
         worldVerticesLength: att.worldVerticesLength,
         regionUVs: Array.from(att.regionUVs ?? []),
         hullLength: att.hullLength,
+        width: att.width,
+        height: att.height,
         weights,
         encoding,
       });
@@ -2634,8 +2555,7 @@ export function validate(input: ValidateInput): ValidateReport {
     // the runtime's supply of `SkinEntryFacts`, in the loaded skins' own order
     // (issue #1025).
     const skinEntries = spineSkinEntries(data);
-    // What the mesh rules that moved read of the skins (issue #1025, cut 4c-1).
-    const skinMeshes = spineSkinMeshes(data);
+    // What the mesh rules that moved read of the skins (issue #1025, cut 4c-1) is the one family of the meshes since issue #1054, `loadedMeshFacts`.
 
     // --- A03: every region has finite width/height (case 6c) ---------------
     check('A03_REGION_WIDTH_HEIGHT_FINITE', () => a03RegionWidthHeightFinite(verdicts, skinEntries));
@@ -2657,8 +2577,8 @@ export function validate(input: ValidateInput): ValidateReport {
     // constant in the validator would fail correct foreign data in the name of
     // somebody else's canvas. A rig that declares no budget has nothing to be
     // measured against, and the assertion says so instead of inventing a wall.
-    check('A13_MESH_BUDGET', () => a13MeshBudget(verdicts, skinMeshes, input));
-    check('A14_NO_FULL_FRAME_MESH', () => a14NoFullFrameMesh(verdicts, skinMeshes, spineStage(data)));
+    check('A13_MESH_BUDGET', () => a13MeshBudget(verdicts, loadedMeshFacts(), input));
+    check('A14_NO_FULL_FRAME_MESH', () => a14NoFullFrameMesh(verdicts, loadedMeshFacts(), spineStage(data)));
 
     // --- A15: idle must not key a mesh-driving bone (dirty-skip lever) -----
     //
@@ -2669,7 +2589,7 @@ export function validate(input: ValidateInput): ValidateReport {
     // of them weighted meshes, and an `idle` whose job is to move them — so the
     // rig can say so in `invariants.idleDrivesMeshes`, and the rule then reports
     // what the declaration costs instead of refusing each bone.
-    check('A15_IDLE_NO_MESH_BONE_KEYS', () => a15IdleNoMeshBoneKeys(verdicts, skinMeshes, spineAnimatedBones(raw), input));
+    check('A15_IDLE_NO_MESH_BONE_KEYS', () => a15IdleNoMeshBoneKeys(verdicts, loadedMeshFacts(), spineAnimatedBones(raw), input));
 
     // --- A20/A21/A22: the mesh checks the parser will never make ------------
     //
@@ -2684,7 +2604,7 @@ export function validate(input: ValidateInput): ValidateReport {
 
     check('A21_MESH_RIM_PINNED', () => a21MeshRimPinned(verdicts, loadedMeshFacts(), input.rig));
 
-    check('A22_MESH_UVS_IN_UNIT_RANGE', () => a22MeshUvsInUnitRange(verdicts, skinMeshes));
+    check('A22_MESH_UVS_IN_UNIT_RANGE', () => a22MeshUvsInUnitRange(verdicts, loadedMeshFacts()));
 
     // --- A39: a deform key that turns a triangle inside out ------------------
     //

package/src/assertions/facts/skin_meshes.ts

@@ -1,49 +0,0 @@
-/**
- * The skins' mesh entries, as the budget and canvas rules read them (issue
- * #1025, step 4c of #380) — the census's F03, F05 and F08 for A13, A14, A15 and
- * A22: every mesh a skin holds, linked meshes included, with where it sits
- * (its slot and that slot's bone), how big it is (its size, its triangle list,
- * its authored UVs and how many coordinates its vertices make) and which bones
- * its weights name.
- *
- * ⭐ **A linked mesh is the geometry it draws.** The runtime loads a link as a
- * mesh whose triangles, UVs, vertices, weights, width and height are its
- * source's (`setSourceMesh` overwrites the link's own `width` and `height`),
- * so an entry for a link carries its source's — the model side reads them
- * through the core's own join, `sourceOfDoc`, never a copy of the rule.
- *
- * ⭐ **The order is the file's**, as `./skin_entries.ts` states it: skins in
- * the emitter's order, a skin's entries slot by slot in the skeleton's slot
- * order, each slot's in its table's order. A13 and A22 print one line per
- * offending mesh in this order.
- *
- * Links nothing from the runtime: `validate()` reads each entry off
- * spine-core's loaded `MeshAttachment`, and the model side off the document
- * (`../model/skin_meshes.ts`).
- */
-
-/** One mesh entry of one skin. */
-export interface MeshEntry {
-  /** The name it loaded under: its `name`, else its placeholder. */
-  readonly name: string;
-  /** The slot whose table holds it. */
-  readonly slot: string;
-  /** That slot's bone. */
-  readonly slotBone: string;
-  /** Its triangle list, three vertex indices per triangle. */
-  readonly triangles: readonly number[];
-  readonly width: number;
-  readonly height: number;
-  /** The UVs the file authored, two per vertex — the runtime's `regionUVs`, not the page-space `uvs` a renderer computes. */
-  readonly regionUVs: ArrayLike<number>;
-  /** Two per vertex, whatever the vertex encoding — the count the runtime recomputes. */
-  readonly worldVerticesLength: number;
-  /** Every bone its weights name, in the weight run's order (repeats kept); empty for an unweighted mesh. */
-  readonly weightBones: readonly string[];
-}
-
-/** What A13, A14, A15 and A22 read of the skins. */
-export interface SkinMeshFacts {
-  /** Every mesh entry of every skin, in the file's walk order. */
-  readonly meshes: readonly MeshEntry[];
-}

package/src/assertions/model/skin_meshes.ts

@@ -1,90 +0,0 @@
-/**
- * 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 file's order (`fileSkinOrder`, issue #1034), 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 };
-}