spine-rigc 2.11.1 → 2.13.0

package/skills/rigc/SKILL.md

@@ -49,7 +49,10 @@ through `@esotericsoftware/spine-core`: install it beside the package
 (`bun add -d @esotericsoftware/spine-core`) and the same `rigc` runs them, and
 `build` runs the round trip as well. Without it they are refused by name, and
 `build` writes the same files gated without the parse — `rigc --version` names the
-entry that ran.
+entry that ran. In the parse's place that `build` runs two rules of its own over
+rigc's model document, `A00_MODEL_READ` and `A00_MODEL_REGIONS_ON_PAGES`; they are
+not registry assertions, so its summary counts two more, and AUTHORING §5.2 has a
+row for each.
 
 ## The loop
 
@@ -81,7 +84,12 @@ entry that ran.
    `rigc vote --candidate <a> --candidate <b>` when several candidates are green and
    only a person can choose between them.
 6. `rigc validate <out>` re-gates artifacts already on disk, and
-   `rigc <command> --help` is each command's own flag table.
+   `rigc <command> --help` is each command's own flag table. `rigc repack <out>
+   --out <dir>` packs a build again under `build --pack`'s packing flags when its
+   parts were not kept, and writes only after every region and the skeleton are
+   shown unchanged (`--accept-skeleton-differences` writes a rebuild whose skeleton
+   differs, every difference printed; `--stage-box <slot>` reads a build's stage box)
+   — AUTHORING §0.4.
 7. Every finished unit ends with `rigc preview --candidate <out>`, and the report
    names the `.html` it wrote. The hand-off to a person is part of the work.
 

package/src/assertions/bodies/a50.ts

@@ -0,0 +1,97 @@
+/**
+ * A50, the body (issue #1168): the stage box a rig asked for is the stage —
+ * in the Spine files a consumer ships, read back the way that consumer reads
+ * it.
+ *
+ * Since issue #907 the Spine header carries the setup-pose bounding box and the
+ * stage is stated only in `skeleton.model.json`, which a consumer does not ship.
+ * A rig that asks (`skeleton.stageBox`) carries the stage as a bounding-box
+ * attachment, whose numbers `compile` writes from the stage. This rule holds
+ * that box to the stage the document states, on both readings a consumer has:
+ *
+ *   1. **The data.** The slot carries, in the `default` skin under the asked
+ *      name, an unweighted bounding box of four vertices, and its stored
+ *      vertices are the stage's corners — `(x, y)`, `(x + w, y)`,
+ *      `(x + w, y + h)`, `(x, y + h)` — each exactly, as the float32 the
+ *      runtime loads. That is what a reader of the attachment gets without
+ *      posing anything.
+ *   2. **The setup pose.** Its world vertices at the setup pose — constraints
+ *      applied, no physics, no skin set — are those corners as the runtime
+ *      poses them on an unrotated root: through the frame the core computes
+ *      for a root that states no transform (`worldTransforms` in
+ *      `../../core/world.ts`, whose unrotated `b` is cos 90° at the runtime's
+ *      pi, −2.3e-8, not 0), compared on the header's grid
+ *      (`headerBoxNumber` in `../../compile.ts`) — the tolerance the header's
+ *      own box is held at. A constraint that moves the box's bone at setup
+ *      is caught here and nowhere else: `compile` poses no constraint.
+ *
+ * **SKIP** where nothing asks: an export or a directory with no `/3` document,
+ * and a document that states a stage and no box — a rig that does not ask is
+ * unmeasured, never certified.
+ *
+ * Links nothing from the runtime.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { StageBoxFacts } from '../facts/stage_box.ts';
+import { worldTransforms } from '../../core/world.ts';
+import { headerBoxNumber } from '../../compile.ts';
+
+const CODE = 'A50_STAGE_BOX_IS_THE_STAGE';
+
+/** The stage's four corners in Spine world, bottom-left first and counter-clockwise — the order `compile` writes. */
+export function stageCorners(stage: { x: number; y: number; width: number; height: number }): number[] {
+  const right = stage.x + stage.width;
+  const top = stage.y + stage.height;
+  return [stage.x, stage.y, right, stage.y, right, top, stage.x, top];
+}
+
+export function a50StageBoxIsTheStage({ fail, skip }: Verdicts, facts: StageBoxFacts): void {
+  const { asked } = facts;
+  if (asked === null) return skip(CODE, facts.why);
+  const where = `the stage box (slot "${asked.slot}", attachment "${asked.attachment}")`;
+  const { x, y, width, height } = asked.stage;
+  const required = `the stage ${x},${y} ${width}x${height}`;
+  if (!facts.slot) return fail(CODE, `${where}: the skeleton has no slot "${asked.slot}", so a consumer finds no stage — ${required} — in it`);
+  const held = facts.held;
+  if (held === null) {
+    return fail(CODE, `${where}: the default skin holds no attachment "${asked.attachment}" on slot "${asked.slot}", so a consumer finds no stage — ${required} — in it`);
+  }
+  if (held.type !== 'boundingbox') {
+    return fail(CODE, `${where}: the attachment is a ${held.type}, not a bounding box — ${required} travels as a boundingbox attachment, which every runtime returns by slot and name`);
+  }
+  if (held.weighted) {
+    return fail(CODE, `${where}: the box's vertices are bound to bones, and the stage is four unweighted corners in the root's space — ${required}`);
+  }
+  const corners = stageCorners(asked.stage);
+  if (held.stored.length !== corners.length) {
+    return fail(CODE, `${where}: the box holds ${held.stored.length / 2} vertices, and the stage is 4 corners — ${required}`);
+  }
+  let faults = 0;
+  for (let i = 0; i < corners.length; i += 2) {
+    const want = [Math.fround(corners[i]), Math.fround(corners[i + 1])];
+    const found = [held.stored[i], held.stored[i + 1]];
+    if (found[0] !== want[0] || found[1] !== want[1]) {
+      faults++;
+      fail(CODE, `${where}: vertex ${i / 2} is stored as (${found[0]}, ${found[1]}) and the stage's corner is (${want[0]}, ${want[1]}) — ${required}, bottom-left first and counter-clockwise`);
+    }
+  }
+  if (faults > 0) return;
+  if (typeof held.world === 'string') return fail(CODE, `${where}: its setup pose cannot be read — ${held.world}`);
+  // The runtime's frame of a root that states no transform, as the core computes it.
+  const frame = worldTransforms([{ name: 'root' }]).get('root');
+  if (frame === undefined) throw new Error('internal: the core posed no frame for an unrotated root');
+  for (let i = 0; i < corners.length; i += 2) {
+    const cx = Math.fround(corners[i]);
+    const cy = Math.fround(corners[i + 1]);
+    const want = [headerBoxNumber(cx * frame.a + cy * frame.b + frame.worldX), headerBoxNumber(cx * frame.c + cy * frame.d + frame.worldY)];
+    const found = [headerBoxNumber(held.world[i]), headerBoxNumber(held.world[i + 1])];
+    if (found[0] !== want[0] || found[1] !== want[1]) {
+      fail(
+        CODE,
+        `${where}: vertex ${i / 2} poses at (${found[0]}, ${found[1]}) at the setup pose and the stage's corner poses at ` +
+          `(${want[0]}, ${want[1]}) on an unrotated root, on the header's grid — something moves the box's bone at setup ` +
+          '(a constraint, or a pose the root does not state), so the box a consumer reads is not the stage',
+      );
+    }
+  }
+}

package/src/assertions/facts/stage_box.ts

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

package/src/assertions/kinds.ts

@@ -97,6 +97,7 @@ export const ASSERTION_KIND: Readonly<Record<string, AssertionKind>> = {
   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. */

package/src/assertions/model/index.ts

@@ -63,6 +63,9 @@ import { a38SkinMembersAreSkinRequired } from '../bodies/a38.ts';
 import { a06AtlasPageSizeMatchesPng } from '../bodies/a06.ts';
 import { a19OverlayPngsHaveAlpha } from '../bodies/a19.ts';
 import { a49PackedFootprintsDoNotOverlap } from '../bodies/a49.ts';
+import { a50StageBoxIsTheStage } from '../bodies/a50.ts';
+import { modelStageBox } from './stage_box.ts';
+import type { StageBoxFacts } from '../facts/stage_box.ts';
 import { a27RegionNameMatchesPageFilename } from '../bodies/a27.ts';
 import { modelAnimatedBones } from './animated_bones.ts';
 import { modelSkinMembers } from './skin_members.ts';
@@ -193,6 +196,8 @@ export interface ModelSupply {
   sliderComposition: (read: ReadDocument) => SliderCompositionFacts;
   constraintTargets: (read: ReadDocument) => ConstraintTargetFacts;
   steppedPoses: (read: ReadDocument) => SteppedPoseFacts;
+  /** The stage box the document asks for and what its default skin holds there (issue #1168, `./stage_box.ts`). */
+  stageBox: (read: ReadDocument) => StageBoxFacts;
   /** The rig info the document declares (issue #1054, `./declared.ts`); a caller's `rig` beside it is refused by name. */
   rigInfo: (read: ReadDocument, input: ModelValidateInput) => RigInfo;
   /** Each animation's declared duration as the document states it (issue #1054); a caller's `declaredDurations` beside it is refused by name. */
@@ -223,6 +228,7 @@ export const MODEL_SUPPLY: ModelSupply = {
   sliderComposition: modelSliderComposition,
   constraintTargets: modelConstraintTargets,
   steppedPoses: modelSteppedPoses,
+  stageBox: modelStageBox,
   rigInfo: (read, input) => {
     refuseDeclaredBeside(read, input, 'rig');
     return modelRigInfo(read);
@@ -306,6 +312,7 @@ export const MOVED_ASSERTIONS: readonly MovedAssertion[] = [
   { code: 'A06_ATLAS_PAGE_SIZE_MATCHES_PNG', run: (v, read, input, supply) => a06AtlasPageSizeMatchesPng(v, supply.atlasRegions(read, input), input, input.profile === 'spine-html'), unread: SKIP_NO_ATLAS },
   { code: 'A19_OVERLAY_PNGS_HAVE_ALPHA', run: (v, read, input, supply) => a19OverlayPngsHaveAlpha(v, supply.atlasRegions(read, input), supply.stage(read, input), supply.skinEntries(read), { atlasDir: input.atlasDir, rig: supply.rigInfo(read, input) }), unread: SKIP_NO_ATLAS },
   { code: 'A49_PACKED_FOOTPRINTS_DO_NOT_OVERLAP', run: (v, read, input, supply) => a49PackedFootprintsDoNotOverlap(v, supply.atlasRegions(read, input), supply.regionJoins(read), supply.meshes(read)), unread: SKIP_NO_ATLAS },
+  { code: 'A50_STAGE_BOX_IS_THE_STAGE', run: (v, read, _input, supply) => a50StageBoxIsTheStage(v, supply.stageBox(read)), unread: SKIP_NO_MODEL },
   { code: 'A24_AXIS_SPACE_STROKE', run: (v, read, input, supply) => a24AxisSpaceStroke(v, supply.boneTimelines(read), { rig: supply.rigInfo(read, input) }), unread: SKIP_NO_MODEL, beforeTheParse: true },
   { code: 'A25_DETACHED_BONE_PARENTAGE', run: (v, read, input, supply) => a25DetachedBoneParentage(v, supply.skeletonRoster(read), { rig: supply.rigInfo(read, input) }), unread: SKIP_NO_MODEL, beforeTheParse: true },
   { code: 'A26_SLOT_DRAW_ORDER', run: (v, read, input, supply) => a26SlotDrawOrder(v, supply.skeletonRoster(read), { rig: supply.rigInfo(read, input) }), unread: SKIP_NO_MODEL, beforeTheParse: true },

package/src/assertions/model/stage_box.ts

@@ -0,0 +1,51 @@
+/**
+ * The model side's supply of `StageBoxFacts` (issue #1168): the box the
+ * document's `stage.box` asks for, and what the document's `default` skin
+ * holds there — its record as the runtime would load it, and its world
+ * vertices at the setup pose as rigc's core poses them (`poseSetup` under no
+ * skin, constraints applied, then `worldVertices`, the function every vertex
+ * attachment of the core is posed by — no second arithmetic for the box).
+ *
+ * A `/2` or `/1` document states no stage and asks nothing; a `/3` document
+ * whose stage states no box asks nothing, and neither does one that declares no
+ * stage. The core's poses are held to spine-core's at tolerance 0 by
+ * `tools/core_gate.ts`, which is what lets this side and the round trip print
+ * one line.
+ *
+ * Links nothing from the runtime.
+ */
+import { activeBones, poseSetup, rawNumber, underNoSkin } from '../../core/index.ts';
+import { worldVertices } from '../../core/vertices.ts';
+import { SKIP_NO_STAGE_BOX, type StageBoxFacts, type StageBoxHeld } from '../facts/stage_box.ts';
+import type { ReadDocument } from './parse.ts';
+
+export function modelStageBox(read: ReadDocument): StageBoxFacts {
+  const doc = read.doc;
+  const stage = doc.stated?.stage;
+  if (doc.stated === null || stage === undefined || stage === null) return { asked: null, why: SKIP_NO_STAGE_BOX, slot: false, held: null };
+  if (stage.box === undefined) return { asked: null, why: SKIP_NO_STAGE_BOX, slot: false, held: null };
+  const asked = { slot: stage.box.slot, attachment: stage.box.attachment, stage: { x: stage.x, y: stage.y, width: stage.width, height: stage.height } };
+  const slot = doc.slots.find((s) => s.name === asked.slot);
+  if (slot === undefined) return { asked, why: '', slot: false, held: null };
+  const record = doc.skins.find((k) => k.name === 'default')?.attachments[asked.slot]?.[asked.attachment];
+  if (record === undefined) return { asked, why: '', slot: true, held: null };
+  const g = record.geometry;
+  const type = record.kind === 'linkedmesh' ? 'mesh' : record.kind;
+  if (g === undefined || g.kind !== 'boundingbox') return { asked, why: '', slot: true, held: { type, weighted: false, stored: [], world: '' } };
+  const vertices = g.vertices;
+  const stored = vertices.weighted ? [] : vertices.xy.map(Math.fround);
+  const held: StageBoxHeld = { type, weighted: vertices.weighted, stored, world: poseWorld(read, slot.bone, vertices) };
+  return { asked, why: '', slot: true, held };
+}
+
+/** The box's world vertices at the setup pose under no skin, or why there are none. */
+function poseWorld(read: ReadDocument, bone: string, vertices: Parameters<typeof worldVertices>[0]): number[] | string {
+  const view = underNoSkin(read.doc);
+  if (!activeBones(view).has(bone)) return `its bone "${bone}" is inactive with no skin set, so nothing poses it`;
+  const posed = poseSetup(view, { round: rawNumber });
+  const world = posed.world;
+  if (world === null) return posed.absent.find(([block]) => block === 'setup.bones')?.[1] ?? "rigc's core does not pose this setup pose";
+  const frame = world.get(bone);
+  if (frame === undefined) return `its bone "${bone}" has no setup world transform`;
+  return worldVertices(vertices, frame, world);
+}

package/src/atlas.ts

@@ -249,8 +249,13 @@ export function pageFootprint(region: { width: number; height: number; degrees:
  * field". Four values maximum, because that is where the runtime stops (`if (i
  * === 4) return 4`) and a fifth would silently mean something here that it does
  * not mean there.
+ *
+ * Exported for `src/repack.ts` (issue #1169), which reads the keys a page and a
+ * region state — the ones this parser drops (`filter`, `format`, `repeat`,
+ * `split`, `pad`) included — with this function rather than a second spelling
+ * of the format, and holds what it walked to `parseAtlasText`'s regions.
  */
-function readEntry(line: string | null): { key: string; values: string[] } | null {
+export function readEntry(line: string | null): { key: string; values: string[] } | null {
   if (line === null) return null;
   const trimmed = line.trim();
   if (trimmed.length === 0) return null;

package/src/cli/core_commands.ts

@@ -34,6 +34,7 @@ import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
 import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser } from '../render_shared.ts';
 import { type CompileResult } from '../types.ts';
 import { attachmentRegionJoins } from '../region_joins.ts';
+import { cmdRepack } from './repack.ts';
 import { ATLAS_ABSENT, COMMANDS, type CommandRun, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPoserFlag, readSkeletonText, readVersion, resolveCut, resolveDrawable, runCheck, SkillsInstallError, STAGELESS_FRAMING, UsageError, writeJson, documentStageBeside } from './shared.ts';
 import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
@@ -1299,6 +1300,7 @@ export function cmdIngest(flags: Record<string, string>, positional: string[]):
   if (documentStage !== undefined) {
     console.log(`  ..    stage  ${documentStage === null ? 'none declared' : `${documentStage.width} x ${documentStage.height}`} — read from the ${MODEL_DOCUMENT_FILE} beside it (its spine.sha256 is this skeleton's); the header's box is the setup-pose bounding box`);
   }
+  if (flags['stage-box'] !== undefined) console.log(`  ..    stage  read from the bounding box in slot "${flags['stage-box']}" (--stage-box); the header's box is the setup-pose bounding box`);
   let result: { rig: unknown; motion: unknown; findings: IngestFinding[] };
   try {
     result = ingest(readJsonFile(skeletonPath), {
@@ -1307,6 +1309,7 @@ export function cmdIngest(flags: Record<string, string>, positional: string[]):
       art,
       images: specImages,
       stage,
+      ...(flags['stage-box'] === undefined ? {} : { stageBox: flags['stage-box'] }),
       source: basename(skeletonPath),
       version: readVersion(),
     });
@@ -1552,8 +1555,11 @@ export function cmdSkills(flags: Record<string, string>, positional: string[]):
  * the pages where the compile measured them — the files the round trip's own
  * A17 reads on `cli.ts` — and A18 compares the documents as written, the
  * copies' names in them. Under `--pack` the two are one text.
+ *
+ * Exported for the selftest's `RPK` plants (issue #1169), which run `repack`
+ * through this entry's dispatch with a hook between the lift and the build.
  */
-const MODEL_AND_TEXT_GATE: BuildGate = {
+export const MODEL_AND_TEXT_GATE: BuildGate = {
   heading: (profile) =>
     `  ..    validate (the model side over the document + the round trip's rules restated over the emitted text, profile ${profile}; this entry links no spine-core, so the round trip does not run)`,
   run: ({ result, atlasText, atlasDir, modelText, reEmit, profile }) => {
@@ -1592,10 +1598,13 @@ const MODEL_AND_TEXT_GATE: BuildGate = {
  * The bodies the second entry runs under a name whose full-entry body is the
  * runtime's (`runtime.core` in `COMMANDS`, issue #1060) — registered by
  * `cli_core.ts` alone, beside `CORE_COMMAND_RUNS`. `build` is `runBuild` with
- * this entry's gate: it writes what `cli.ts build` writes.
+ * this entry's gate: it writes what `cli.ts build` writes. `repack` (issue
+ * #1169) is `./repack.ts`'s body with the same gate, for the same reason: it
+ * is `build --pack` run over a build's own lifted regions.
  */
 export const CORE_ENTRY_RUNS: Readonly<Record<string, CommandRun>> = {
   build: ({ flags }) => runBuild(flags, MODEL_AND_TEXT_GATE),
+  repack: (args) => cmdRepack(args, MODEL_AND_TEXT_GATE),
 };
 
 /**