@rig-c/core 2.69.0 → 2.71.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.69.0",
+  "version": "2.71.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {
@@ -19,6 +19,7 @@
     "./errors": "./src/errors.ts",
     "./meshcompare": "./src/meshcompare.ts",
     "./core": "./src/core/entry.ts",
+    "./runtime": "./src/runtime/index.ts",
     "./cli": "./cli.ts",
     "./package.json": "./package.json",
     "./*.ts": "./*.ts",
@@ -32,7 +33,7 @@
     "./*": "./*.ts"
   },
   "engines": {
-    "bun": ">=1.2.0"
+    "bun": ">=1.4.0"
   },
   "license": "MIT",
   "author": "firejune",
@@ -106,6 +107,8 @@
     "@esotericsoftware/spine-core": "4.3.13",
     "@types/bun": "^1.4.0",
     "eslint": "^10.9.0",
+    "phaser": "3.90.0",
+    "pixi.js": "8.22.0",
     "spine-html": "^0.4.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.67.0",

package/skills/rigc/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc
 description: Author, build and validate Spine 4.3 skeleton data (skeleton.json plus its .atlas) from loose part PNGs with rigc, the rig compiler that verifies its own output with named assertions before writing it. Use for any request to make a Spine rig or Spine animation from PNG parts, or where the source is a Live2D, Unity or video model whose pictures you can render, to run or read rigc build, validate, render, preview, check or vote, or to write or fix a *.rig.json or *.motion.json spec; it says which shipped guide to open for the need at hand. Not for Live2D conversion, cutting an illustration into parts, or real-time face tracking.
 license: MIT
-compatibility: Requires Bun 1.2 or later. The tool is the npm package rig-c (bunx rig-c, or bun add -d rig-c); the command it installs is rigc.
+compatibility: Requires Bun 1.4 or later. The tool is the npm package rig-c (bunx rig-c, or bun add -d rig-c); the command it installs is rigc.
 ---
 
 # rigc — a rig compiler for agents

package/skills/rigc-face/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-face
 description: Author a face on plain Spine data with rigc — a blink, a gaze shift, a breathing portrait and a head turn a few degrees off axis, built from deform timelines and per-part parallax. Use when the request is a talking or living portrait, a standing character, an expression or a head turn, such as "rig this face", "make the portrait blink and look around" or "turn the head". Not for Live2D file conversion, cutting a face illustration into parts, or VTuber-style real-time face tracking.
 license: MIT
-compatibility: Requires Bun 1.2 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package rig-c.
 ---
 
 # Face — a turn, a gaze and a blink

package/skills/rigc-ingest/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-ingest
 description: Work with a Spine skeleton.json somebody else authored — exported from the Spine editor or another tool — using rigc. Read and validate it, understand a complaint rigc raised about it, decompile it into rigc specs with `rigc ingest`, normalise, re-pivot or rename it, and extend it with an animation it does not have. Use when the input is an existing skeleton.json with its .atlas and page images rather than loose part PNGs. Not for Live2D file conversion or runtime tracking.
 license: MIT
-compatibility: Requires Bun 1.2 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package rig-c.
 ---
 
 # Ingest — a skeleton you did not author

package/skills/rigc-motion/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-motion
 description: Author a Spine animation with rigc from key poses — an idle, a loop, a move from one picture to another — with timing and spacing, ease in and out, anticipation, arcs, overlap, follow-through, squash and stretch, and candidate variants a person can choose between. Use when the request is a movement on an existing or planned rig, in the animator's words too: "animate this rig", "make it breathe", "go from pose A to pose B", "make it feel heavier", "the cape should follow through". Not for Live2D, separating an image into parts, or real-time tracking.
 license: MIT
-compatibility: Requires Bun 1.2 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package rig-c.
 ---
 
 # Motion — what goes between two poses

package/skills/rigc-rigging/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-rigging
 description: Decide a Spine rig's hierarchy with rigc — how many bones, where each pivot sits, what hangs off what, offsets, chains and what a chain can reach, siblings versus chains, constraints as structure — and which of those decisions the reference frames can check. Use when the request is a skeleton from loose part PNGs, such as "rig these parts", "make a Spine skeleton" or "where do the joints go", before any motion is authored. Not for Live2D, cutting an illustration into parts, or VTuber-style tracking.
 license: MIT
-compatibility: Requires Bun 1.2 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package rig-c.
 ---
 
 # Rigging — the hierarchy itself

package/src/assertions/report.ts

@@ -20,7 +20,7 @@ export const VALIDATE_PROFILES: readonly AssertionProfile[] = ['spine', 'rig-pla
  * the target and never the alias.
  */
 export function profileAliasLine(alias: string, target: AssertionProfile): string {
-  return `rigc: --profile ${alias} is deprecated and reads as --profile ${target}, the same rules; it is accepted until the next minor release — pass --profile ${target}`;
+  return `rigc: --profile ${alias} is deprecated and reads as --profile ${target}, the same rules; it is accepted until the next major release — pass --profile ${target}`;
 }
 
 /**

package/src/atlas.ts

@@ -775,6 +775,11 @@ export interface PackInput {
   absPath: string;
   width: number;
   height: number;
+  /**
+   * Already-drawn pixels (`render --sheet`), used in place of `readPlate(absPath)`
+   * when given so an in-memory crop is not written out only to be read back in.
+   */
+  plate?: Plate;
   /**
    * What the region's attachments draw (`packFootprints`), read only under
    * `shape: 'polygon'`. Absent means the rectangle.
@@ -2535,7 +2540,7 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
     const owners: Array<{ source: Plate; place: Placement; shape: CellShape }> = [];
     for (const place of onPage) {
       const input = byRegion.get(place.region)!;
-      const source = readPlate(input.absPath);
+      const source = input.plate ?? readPlate(input.absPath);
       if (source.width !== input.width || source.height !== input.height) {
         // The size in the atlas came from the PNG's IHDR (`readPngInfo`); this is
         // the decoded image. They disagreeing means the file changed between the

package/src/cli/core_commands.ts

@@ -40,6 +40,7 @@ import { outsideLine, outsideViewport, pinnedRecord, readViewportBox, viewportOf
 import { PASS_THROUGH_FILE, passFrameLine, type PassPair, passSummaryLine, passThroughFileOf, passThroughOf, passThroughText, PassThroughError, readPassPairs } from '../passthrough.ts';
 import type { Plate } from '../../tools/plate.ts';
 import { OVERLAPS_FILE, OverlapError, overlapLine, overlapPlate, overlapsFileOf, overlapsOf, overlapsPlateFile, overlapsText, plateParticipants, staticLine } from '../overlaps.ts';
+import { buildSheetSet, SHEET_MANIFEST_FILE, type SheetSetPack, SheetUsageError, sheetRigNameOf, sheetSidecarRecord, sheetSourceOf } from '../sheet.ts';
 import { readSeamPairs, SEAM_FILE, seamFileOf, seamLine, SeamError, type SeamPair, seamsOf, seamText } from '../seam.ts';
 import { environmentCollisions, environmentFrame, EnvironmentError, environmentResponse, readEnvironmentSchedule, type EnvironmentStep } from '../environment.ts';
 import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
@@ -49,7 +50,7 @@ import { attachmentRegionJoins } from '../region_joins.ts';
 import { cmdRepack } from './repack.ts';
 import { writeWhole } from './write_whole.ts';
 import { GUIDE_FILE, GUIDE_RULE_TABLES_ELSEWHERE, guideAnswer, refusalLine } from '../guide.ts';
-import { ATLAS_ABSENT, COMMANDS, type CommandRun, DelegateError, modelTextBeside, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, GuideError, 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 { ATLAS_ABSENT, COMMANDS, type CommandRun, DelegateError, modelTextBeside, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, GuideError, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPageEdges, readPoserFlag, readSheetFormat, 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';
 import { spawnSync } from 'node:child_process';
@@ -656,6 +657,18 @@ export function cmdRender(flags: Record<string, string>): void {
   const maxSide = readPositiveNumber(flags, 'max', 256, 16);
   // A box given rather than fitted (issue #1414), read before a line is printed, so a malformed one is refused first.
   const given = readGivenViewport(flags);
+  const wantsSheet = flags.sheet !== undefined;
+  if (flags['sheet-format'] !== undefined && !wantsSheet) {
+    throw new UsageError('--sheet-format takes --sheet: pass --sheet alongside --sheet-format <format>, or drop --sheet-format');
+  }
+  if (flags['page-edges'] !== undefined && !wantsSheet) {
+    throw new UsageError(
+      '--page-edges on render takes --sheet: without --sheet, render writes loose f####.png frames and contact.png, ' +
+        'which have no packed atlas pages. Pass --sheet or drop --page-edges',
+    );
+  }
+  const sheetFormat = wantsSheet ? readSheetFormat(flags) : undefined;
+  const sheetPageEdges = wantsSheet ? readPageEdges(flags) : undefined;
   const outRoot = resolve(flags.out ?? 'render');
   const geometry = flags.geometry !== undefined;
   // The fold reading (issue #1383) is its own flag rather than a part of --geometry, so a caller that asked for
@@ -953,9 +966,45 @@ export function cmdRender(flags: Record<string, string>): void {
         }
       }
     }
-    return { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings };
+    const sheetPacks = new Map<string, SheetSetPack>();
+    if (wantsSheet) {
+      const modelDocText = modelTextBeside(skeletonPath, skeletonText) ?? null;
+      const rigName = sheetRigNameOf(skeletonPath, modelDocText, skeletonText);
+      const source = sheetSourceOf(skeletonPath, skeletonText, modelDocText);
+      const pinned = given === undefined ? undefined : pinnedRecord(given.by, outsideViewport(sampled, viewport));
+      for (const [name, frames] of sampled) {
+        const animation = name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name;
+        const setName = frameSetDir(name, fps);
+        try {
+          sheetPacks.set(
+            name,
+            buildSheetSet({
+              rigName,
+              setName,
+              animation,
+              fps,
+              maxSide,
+              viewport,
+              frames,
+              atlasPages: pages,
+              source,
+              format: sheetFormat,
+              pageEdges: sheetPageEdges,
+              skin,
+              subset,
+              environment: environment?.steps,
+              pinned,
+            }),
+          );
+        } catch (err) {
+          if (err instanceof SheetUsageError) throw new UsageError(err.message);
+          throw err;
+        }
+      }
+    }
+    return { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings, sheetPacks };
   });
-  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings } = posed.value;
+  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings, sheetPacks } = posed.value;
   console.log(`  ..    poser    ${posed.note}`);
   if (environment !== undefined) {
     const response = environmentResponse(skeletonText);
@@ -1014,6 +1063,14 @@ export function cmdRender(flags: Record<string, string>): void {
       writeFileSync(join(dir, OVERLAPS_FILE), overlapsText(overlapReading.file));
       for (const [index, plate] of overlapReading.plates) plate.writePng(join(dir, overlapsPlateFile(index)));
     }
+    const sheetPack = sheetPacks.get(name);
+    if (sheetPack !== undefined) {
+      for (const page of sheetPack.pages) {
+        page.plate.writePng(join(dir, page.image));
+        writeFileSync(join(dir, page.table), page.jsonText);
+      }
+      writeFileSync(join(dir, SHEET_MANIFEST_FILE), sheetPack.manifestText);
+    }
     const duration = frames[frames.length - 1].time;
     const physics = physicsDeclared.length === 0 ? undefined : physicsSteppedOf(frames, fps);
     sets.push({
@@ -1026,6 +1083,7 @@ export function cmdRender(flags: Record<string, string>): void {
       duration,
       ...(physics === undefined ? {} : { physics: { stepped: physics.stepped.length, fps } }),
       ...(overlapReading === undefined ? {} : { overlaps: overlapsRecord(overlapReading.file, overlapReading.plates.size) }),
+      ...(sheetPack === undefined ? {} : { sheet: sheetSidecarRecord(sheetPack) }),
     });
     const how = frames.length === 1 ? 'a single pose' : `${duration.toFixed(3)}s`;
     const folding = foldReading?.meshes.filter((m) => m.worst !== null).length ?? 0;
@@ -1038,7 +1096,11 @@ export function cmdRender(flags: Record<string, string>): void {
       overlapReading === undefined
         ? ''
         : ` + ${OVERLAPS_FILE} (${overlapReading.file.pairs.filter((p) => p.varies).length} moving pair(s), ${overlapReading.plates.size} outline plate(s))`;
-    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}${seamNote}${overlapNote}`;
+    const sheetNote =
+      sheetPack === undefined
+        ? ''
+        : ` + ${sheetPack.pages.map((p) => `${p.image} + ${p.table}`).join(' + ')} + ${SHEET_MANIFEST_FILE} (${sheetPack.pages.length} page(s), ${sheetPack.pageEdges})`;
+    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${sheetNote}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}${seamNote}${overlapNote}`;
     console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
     if (physics !== undefined) console.log(`  ..    ${physicsLine(physics.stepped, physicsDeclared, fps, frames.length)}`);
     for (const mesh of foldReading?.meshes ?? []) {
@@ -2313,7 +2375,7 @@ function resolveDelegate(name: string): string | null {
 
 /**
  * Whether the Bun running this hands an empty argument to a process it starts
- * (issue #1465). Bun 1.2.0 — the declared minimum — does not: `["a", "", "b"]`
+ * (issue #1465). Bun 1.2.0 (then the declared minimum) does not: `["a", "", "b"]`
  * reaches the child as `["a", "b"]`, through `spawnSync` and `Bun.spawnSync`
  * alike and whatever the child is; 1.4.2 hands it over. That is measured here
  * rather than read off a version number, by starting this Bun twice with
@@ -2466,7 +2528,7 @@ function cmdDelegate(command: string, raw: readonly string[]): void {
   // `rigc review -- <dir>` reached the bin as `<dir>` (measured, issue #1486). One given here is the one dropped, and
   // the arguments after it arrive as they were.
   const ran = spawnSync(process.execPath, [bin, '--', ...argv], { stdio: 'inherit' });
-  // ⚠️ The exit and the signal are read before `error`: Bun 1.2.0 — the declared minimum — sets `error` on every
+  // ⚠️ The exit and the signal are read before `error`: Bun 1.2.0 (then the declared minimum) sets `error` on every
   // child that exits non-zero, so reading it first refused review's own exit 7 as "could not run". `error` is a
   // launch that failed only where the child left neither a status nor a signal.
   if (typeof ran.status === 'number') process.exit(ran.status);

package/src/cli/shared.ts

@@ -41,6 +41,7 @@ import { FOLDS_FILE } from '../folds.ts';
 import { DRAWN_ALPHA, PASS_THROUGH_FILE, PASS_THROUGH_RUN } from '../passthrough.ts';
 import { SEAM_FILE } from '../seam.ts';
 import { OVERLAPS_FILE } from '../overlaps.ts';
+import { DEFAULT_SHEET_FORMAT, SHEET_FORMATS, SHEET_MANIFEST_FILE, SHEET_MANIFEST_SPEC, SHEET_PADDING, SHEET_PAGE_SIZE, type SheetFormat } from '../sheet.ts';
 import { readViewportBox, ViewportError } from '../viewportpin.ts';
 import { parseJsonWithPosition } from '../json-position.ts';
 import { RUNG_IDS } from '../ladder.ts';
@@ -151,7 +152,7 @@ export { PACKAGE_ROOT, readPackageMeta, readVersion };
  * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
  * halves together by reading `--help` rather than by naming a flag.
  */
-const BOOLEAN_FLAGS = new Set(['all', 'all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'folds', 'overlaps', 'accept-skeleton-differences', 'keep-pages', 'dim']);
+const BOOLEAN_FLAGS = new Set(['all', 'all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'folds', 'overlaps', 'sheet', 'accept-skeleton-differences', 'keep-pages', 'dim']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -1078,6 +1079,15 @@ const FLAG_MEANINGS: Record<string, string> = {
     'pair per set: the lowest and the highest angle in degrees, the span, and the frame each was first reached on. Read on the frames\' own ' +
     'grid, so a peak between two frames is not read. A reading, not a gate: nothing is written. An unknown bone, a bone against itself, ' +
     'a malformed list and a pair named twice are refused by name, and so is a bone with no direction on a frame (a world matrix of zero)',
+  sheet:
+    `also pack each rendered set's frames over a transparent [0, 0, 0, 0] canvas into deterministic RGBA8 sprite sheet page(s) ` +
+    `(\`sheet.png\`, \`sheet2.png\`, …; max edge ${SHEET_PAGE_SIZE}, padding ${SHEET_PADDING} with clamped edge extrusion, trimmed to alpha > 0 ` +
+    'with a 1x1 transparent sentinel for empty frames), a shared TexturePacker-style JSON-Hash table per page (`sheet.json`, `sheet2.json`, …; ' +
+    `\`anchor\` at world (0, 0)), and \`${SHEET_MANIFEST_FILE}\` (\`${SHEET_MANIFEST_SPEC}\`) ` +
+    'in each set directory; diagnostic `f####.png` and `contact.png` stay over opaque `BACKGROUND` unchanged',
+  'sheet-format':
+    `the table format \`render --sheet\` writes beside each sheet page (default \`${DEFAULT_SHEET_FORMAT}\`, verified against pixi.js@8.22.0 and phaser@3.90.0 by tools/sheet_readers.ts; known formats: ${SHEET_FORMATS.join(', ')}). ` +
+    'Takes --sheet',
   'viewport-from':
     "draw on an earlier render's grid exactly — the box, the scale and the pixel size its frames.json records (the file, or the " +
     'directory `render --out` wrote it into) — so a world point lands on the same pixel in both renders. A slot that reaches past ' +
@@ -1285,6 +1295,7 @@ const FLAG_VALUES: Record<string, string> = {
   'pass-through': '<cloth>:<leg>[,<cloth>:<leg>…]',
   seam: '<slot>:<slot>[,<slot>:<slot>…]',
   'angle-range': '<bone>:<relative-to>[,…]',
+  'sheet-format': 'json-hash',
   'viewport-from': '<frames.json|dir>',
   reference: '<dir|skeleton.json>',
   'reference-atlas': '<path>',
@@ -1753,9 +1764,15 @@ export const COMMANDS: CommandDoc[] = [
       'rigc render … --overlaps   (which slot each frame drew over which, by name, with an outline plate)',
       'rigc render … --angle-range <bone>:<relative-to>[,…]   (how far a bone turns against another, per animation)',
       'rigc render … --viewport <x,y,w,h> | --viewport-from <frames.json>   (a box given, not fitted: two renders on one pixel grid)',
+      'rigc render … --sheet [--sheet-format json-hash] [--page-edges pot|free]   (deterministic sprite sheets + JSON hash table + sheet-manifest.json per set)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'pass-through', 'seam', 'overlaps', 'angle-range', 'environment', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'poser', 'out'],
     overrides: {
+      'page-edges': {
+        meaning:
+          `what each sprite sheet page's edges may be, --sheet only (default ${DEFAULT_PAGE_EDGES}, max edge ${SHEET_PAGE_SIZE}, padding ${SHEET_PADDING}): ` +
+          'pot is a power of two on both; free chooses the smallest-area rectangle up to the max edge that holds the trimmed frames',
+      },
       out: {
         value: '<dir>',
         meaning:
@@ -2252,6 +2269,17 @@ export function readPageEdges(flags: Record<string, string>): PageEdges {
   return found;
 }
 
+/**
+ * Read `--sheet-format`, or its default — `json-hash` (issue #1560).
+ */
+export function readSheetFormat(flags: Record<string, string>): SheetFormat {
+  const raw = flags['sheet-format'];
+  if (raw === undefined) return DEFAULT_SHEET_FORMAT;
+  const found = SHEET_FORMATS.find((f) => f === raw);
+  if (!found) throw new UsageError(`--sheet-format ${JSON.stringify(raw)}; known formats: ${SHEET_FORMATS.join(', ')}`);
+  return found;
+}
+
 /**
  * Read `--pack-shape`, or its default — `rect` (issue #1099).
  *

package/src/cli/write_whole.ts

@@ -3,7 +3,7 @@
  * refusal — the writer a command uses for a document too large to trust to
  * `console.log` (issue #1487).
  *
- * ⚖️ Why not `console.log`: on Bun 1.2.0, the declared minimum, one ~322 KB
+ * ⚖️ Why not `console.log`: on Bun 1.2.0 (then the declared minimum), one ~322 KB
  * line with non-ASCII in it came out 330,634 bytes for 330,632, a stray
  * `\xe2\x00` at a 64 KiB chunk boundary — to a file, a pipe and a slow pipe
  * alike. And on a stdout whose pipe is non-blocking (a parent set `O_NONBLOCK`

package/src/compile.ts

@@ -3015,6 +3015,46 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   // The same for a `soft` mask's per-vertex level, which a deform envelope's
   // `mask` reads (issue #1413). Never emitted either.
   const attachmentSoftMasks = new Map<string, DeformSoftMask>();
+  // `skin/slot/attachment` -> per-axis narrowing mode when a deform turn key on
+  // that attachment declares `narrowing: false` (issue #1584), so `sampleMeshDepth`
+  // evaluates `turnCeiling` with the `asin(|A₀ / A_axis|)` closed form that
+  // matches `A39` on the keyed turn.
+  const attachmentTurnNarrowing = new Map<string, { yaw?: boolean; pitch?: boolean }>();
+  const attachmentTurnNarrowingBy = new Map<string, { yaw?: { mode: boolean; anim: string }; pitch?: { mode: boolean; anim: string } }>();
+  withMotionSource(() => {
+    for (const [turnAnimName, turnAnim] of Object.entries(motion.animations ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+      for (const turnTrack of turnAnim.deform ?? []) {
+        const turnDeformSkin = turnTrack.skin ?? DEFAULT_SKIN;
+        const turnTriple = `${turnDeformSkin}/${turnTrack.slot}/${turnTrack.attachment}`;
+        for (const turnKey of turnTrack.keys ?? []) {
+          const turnSpec = turnKey.transform as { kind?: unknown; narrowing?: unknown } | undefined;
+          if (turnSpec && (turnSpec.kind === 'yaw' || turnSpec.kind === 'pitch')) {
+            const turnAxis = turnSpec.kind;
+            const turnNarrowMode = turnSpec.narrowing !== false;
+            const turnPrev = attachmentTurnNarrowingBy.get(turnTriple)?.[turnAxis];
+            if (turnPrev !== undefined && turnPrev.mode !== turnNarrowMode) {
+              const turnFalseAnim = turnNarrowMode ? turnPrev.anim : turnAnimName;
+              const turnTrueAnim = turnNarrowMode ? turnAnimName : turnPrev.anim;
+              throw new CompileError(
+                `deform ${turnTriple} keys "${turnAxis}" with narrowing=false in animation "${turnFalseAnim}" and with narrowing=true in animation "${turnTrueAnim}". ` +
+                  'An attachment\'s turn ceiling on one axis is either asin(|A₀ / A_axis|) (without narrowing) or atan(|A₀ / A_axis|) (with narrowing) — ' +
+                  `mixing both on one attachment and axis would report one ceiling where two apply. Use one "narrowing" setting across every "${turnAxis}" key on ${turnTriple}.`,
+                'CE_COMPILE_DEFORM_TURN_NARROWING_MIXED',
+              );
+            }
+            const curBy = attachmentTurnNarrowingBy.get(turnTriple) ?? {};
+            if (curBy[turnAxis] === undefined) curBy[turnAxis] = { mode: turnNarrowMode, anim: turnAnimName };
+            attachmentTurnNarrowingBy.set(turnTriple, curBy);
+            if (!turnNarrowMode) {
+              const cur = attachmentTurnNarrowing.get(turnTriple) ?? {};
+              cur[turnAxis] = false;
+              attachmentTurnNarrowing.set(turnTriple, cur);
+            }
+          }
+        }
+      }
+    }
+  });
 
   for (const rigSlot of rig.slots) {
     const part = partBySlot.get(rigSlot.name);
@@ -3183,6 +3223,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
           imagesDir,
           depths: attachmentDepths,
           softMasks: attachmentSoftMasks,
+          turnNarrowing: attachmentTurnNarrowing.get(`${skinName}/${rigSlot.name}/${placeholder}`),
           slotNames: new Set(rig.slots.map((s) => s.name)),
           atlasRegions: atlasIn === null ? null : atlasIn.byName,
           links: pendingLinks,
@@ -4333,6 +4374,12 @@ interface AttachmentContext {
    * emitted, for `depths`' reason.
    */
   softMasks: Map<string, DeformSoftMask>;
+  /**
+   * Per-axis `narrowing` mode when a deform turn key on this attachment states
+   * `"narrowing": false` (issue #1584), so `sampleMeshDepth` computes the turn
+   * ceiling with `asin(|A₀ / A_axis|)` on that axis.
+   */
+  turnNarrowing?: { yaw?: boolean; pitch?: boolean };
   /** Every slot the rig declares — a clipping attachment's `end` resolves here. */
   slotNames: Set<string>;
   /**
@@ -6324,6 +6371,7 @@ function sampleMeshDepth(
         points.map(([px, py]) => toBind(px, py)),
         z,
         triangles,
+        ctx.turnNarrowing === undefined ? undefined : { narrowing: ctx.turnNarrowing },
       ),
     },
   };

package/src/core/animation.ts

@@ -189,11 +189,12 @@ import {
   foldInheritMode,
   gridRound,
   readBlend,
-  readColour,
   shownAttachment,
   shownRow,
   slidersKeyingWhy,
   sourceOfDoc,
+  viewColours,
+  WHITE,
   type CompiledDocument,
   type CoreAnimation,
   type CoreBoneRow,
@@ -834,12 +835,15 @@ export function posedSlots(
   /** Filled with each slot's placeholder once the sample's own timelines have moved it, before the sliders — what the attachments are posed from (`attachmentStates`). */
   placeholders?: Map<string, string | null>,
 ): { rows: CoreSlotRow[]; conflicts: string[] } {
-  const colour = plant.colour ?? readColour;
+  // The view's stated colours, read once (`viewColours`); a planted reader of the light colour is called as it always was.
+  const stated = viewColours(doc);
+  const colour = plant.colour ?? stated;
   const byName = new Map(timelines.slots.map((s) => [s.name, s]));
   return slotRowsFrom(doc, plant, sliders, placeholders, (slot, live) => {
     let placeholder = slot.setup;
-    const light = slot.color === undefined ? [1, 1, 1, 1] : colour(slot.color);
-    const setupDark = slot.dark === undefined ? null : readColour(slot.dark);
+    const setupLight = slot.color === undefined ? WHITE : colour(slot.color);
+    const light = [setupLight[0], setupLight[1], setupLight[2], setupLight[3]];
+    const setupDark = slot.dark === undefined ? null : stated(slot.dark);
     const dark = setupDark === null ? null : [setupDark[0], setupDark[1], setupDark[2]];
     for (const tl of live ? (byName.get(slot.name)?.timelines ?? []) : []) {
       if (tl.kind === 'attachment') {
@@ -848,7 +852,6 @@ export function posedSlots(
         continue;
       }
       const v = valuesAt(tl.keys, t, plant);
-      const setupLight = slot.color === undefined ? [1, 1, 1, 1] : colour(slot.color);
       const channels = SLOT_COLOUR_TIMELINES[tl.kind].channels;
       channels.forEach((name, i) => {
         const at = { r: 0, g: 1, b: 2, a: 3, r2: 4, g2: 5, b2: 6 }[name];
@@ -955,15 +958,22 @@ export function posedBoneRows(doc: CompiledDocument, timelines: CoreAnimationTim
 /** `posedBoneRows`, with the world transforms the rows were read off — what the sample's attachments are posed through. */
 export function posedBoneWorld(doc: CompiledDocument, timelines: CoreAnimationTimelines, t: number, plant: TimelinePlant = {}, constraints?: CoreConstraintTimelines, sliders?: SliderApplication[], step?: PoseStep): { rows: CoreBoneRow[]; world: Map<string, CoreWorld> } {
   const posed = posedBoneStep(doc, timelines, t, plant, constraints, sliders, step);
-  return { rows: stepRows(posed), world: posed.world };
+  const stage = plant.stage;
+  if (stage !== undefined) stage.begin('readout');
+  const rows = stepRows(posed);
+  if (stage !== undefined) stage.end('readout');
+  return { rows, world: posed.world };
 }
 
 /**
  * `posedBoneWorld`'s world transforms without its rows (issue #1179, the
  * second part): the same pose by the same operations in the same order, since
  * `stepRows` only reads the world once it is posed. A walk reads `world` and
- * no row, so the scan's walk (`scanWalkIn` in `./raw.ts`, A10's) asks for
- * this; the raw entry's walk still forms the rows it does not read, unchanged.
+ * no row, so every walk asks for this — the scan's (`scanWalkIn` in
+ * `./raw.ts`, A10's), the raw entry's batch walks and the live track's step.
+ * The rows were the only thing the other variant adds, and their rounding
+ * (`rawNumber`, `keptNumber`) refuses nothing, so leaving them out moves no
+ * number and no refusal of a walk.
  */
 export function posedBoneWorldAlone(doc: CompiledDocument, timelines: CoreAnimationTimelines, t: number, plant: TimelinePlant, constraints: CoreConstraintTimelines | undefined, sliders: SliderApplication[] | undefined, step: PoseStep | undefined): Map<string, CoreWorld> {
   return posedBoneStep(doc, timelines, t, plant, constraints, sliders, step).world;
@@ -997,20 +1007,34 @@ function stepRows(posed: PosedStep): CoreBoneRow[] {
 
 /** `posedBoneWorld` up to its rows, refusing a bone the evaluator gave no transform (`PosedStep`). */
 function posedBoneStep(doc: CompiledDocument, timelines: CoreAnimationTimelines, t: number, plant: TimelinePlant, constraints: CoreConstraintTimelines | undefined, sliders: SliderApplication[] | undefined, step: PoseStep | undefined): PosedStep {
+  const stage = plant.stage;
+  if (stage !== undefined) stage.begin('timeline');
   const bones = posedBones(doc, timelines, t, plant);
+  if (stage !== undefined) stage.end('timeline');
   // One step of the stepped phase (issue #956, `./constraints_physics.ts`): the physics records posed by their timelines and stepped under the walk's context; the deformed curve a path walks as above.
-  if (constraints !== undefined && step !== undefined) return steppedLocals(doc, bones, plant, () => pathDeformed(doc, posedRecords(constraintRecords(doc), constraints, t), timelines, t, plant), constraints.physicsKeyed ?? [], t, sliders, step);
+  if (constraints !== undefined && step !== undefined) {
+    return steppedLocals(doc, bones, plant, () => pathDeformed(doc, posedRecords(constraintRecords(doc), constraints, t), timelines, t, plant), constraints.physicsKeyed ?? [], t, sliders, step);
+  }
   const active = activeBones(doc);
   // The caller's adjustment, after the timelines and before anything reads the locals (`LocalAdjust`).
-  if (step?.adjustment !== undefined) adjustLocals(doc, bones, step.adjustment.callback, step.adjustment.context);
-  let world = (plant.evaluate ?? worldTransforms)(bones, active);
+  if (step?.adjustment !== undefined) {
+    if (stage !== undefined) stage.begin('timeline');
+    adjustLocals(doc, bones, step.adjustment.callback, step.adjustment.context);
+    if (stage !== undefined) stage.end('timeline');
+  }
+  if (stage !== undefined) stage.begin('world');
+  const initialWorld = (plant.evaluate ?? worldTransforms)(bones, active);
+  if (stage !== undefined) stage.end('world');
+  let world = initialWorld;
   if (constraints !== undefined) {
+    if (stage !== undefined) stage.begin('constraints');
     const setupRecords = constraintRecords(doc);
     // A path walks the curve the sample's deform timelines left on its slot (`./deform.ts`); a slider's deform of a walked path leaves the bones out (`pathAnimationsWhy`).
     const records = pathDeformed(doc, posedRecords(setupRecords, constraints, t), timelines, t, plant);
     // A path constraint may read a slot bone the runtime has not yet brought up to date in this pass, as the previous pass left it (`./constraints_path.ts`, *Which slot bone*); `poseAnimations` holds that pass to the setup pose's reading.
     const previous = setupRecords.some((r) => r.kind === 'path') ? applyConstraints(doc.bones, (plant.evaluate ?? worldTransforms)(doc.bones, active), active, plant.constraints ? plant.constraints(setupRecords) : setupRecords, null, undefined, undefined, undefined, solverRules(plant.solver)) : null;
-    world = applyConstraints(bones, world, active, plant.constraints ? plant.constraints(records) : records, previous, sliders, undefined, undefined, solverRules(plant.solver));
+    world = applyConstraints(bones, initialWorld, active, plant.constraints ? plant.constraints(records) : records, previous, sliders, undefined, undefined, solverRules(plant.solver));
+    if (stage !== undefined) stage.end('constraints');
   }
   for (const b of bones) if (world.get(b.name) === undefined) throw new CoreInputError(`the evaluator returned no transform for bone "${b.name}"`);
   return { bones, world, active, round: plant.round ?? gridRound };
@@ -1027,27 +1051,35 @@ function posedBoneStep(doc: CompiledDocument, timelines: CoreAnimationTimelines,
  * past the timelines for both.
  */
 function steppedLocals(doc: CompiledDocument, bones: ModelBone[], plant: TimelinePlant, records: () => CoreConstraintRecord[], physicsKeyed: NonNullable<CoreConstraintTimelines['physicsKeyed']>, t: number, sliders: SliderApplication[] | undefined, step: PoseStep): PosedStep {
+  const stage = plant.stage;
   const active = activeBones(doc);
   // The caller's adjustment, after the timelines and before anything reads the locals (`LocalAdjust`).
-  if (step.adjustment !== undefined) adjustLocals(doc, bones, step.adjustment.callback, step.adjustment.context);
-  let world = (plant.evaluate ?? worldTransforms)(bones, active);
+  if (step.adjustment !== undefined) {
+    if (stage !== undefined) stage.begin('timeline');
+    adjustLocals(doc, bones, step.adjustment.callback, step.adjustment.context);
+    if (stage !== undefined) stage.end('timeline');
+  }
+  if (stage !== undefined) stage.begin('world');
+  const initialWorld = (plant.evaluate ?? worldTransforms)(bones, active);
+  if (stage !== undefined) {
+    stage.end('world');
+    stage.begin('constraints');
+  }
   const stepped = stepPhysicsRecords(records(), physicsKeyed, t, active, step.ctx, step.before);
-  world = applyConstraints(bones, world, active, plant.constraints ? plant.constraints(stepped) : stepped, null, sliders, step.ctx, undefined, solverRules(plant.solver));
+  const world = applyConstraints(bones, initialWorld, active, plant.constraints ? plant.constraints(stepped) : stepped, null, sliders, step.ctx, undefined, solverRules(plant.solver));
+  if (stage !== undefined) stage.end('constraints');
   for (const b of bones) if (world.get(b.name) === undefined) throw new CoreInputError(`the evaluator returned no transform for bone "${b.name}"`);
   return { bones, world, active, round: plant.round ?? gridRound };
 }
 
 /**
- * `steppedLocals`' world transforms, the oracle's rows formed beside them when
- * `rows` is set (as `posedBoneWorld` forms them and `posedBoneWorldAlone` does
- * not): the live tracks' entry to the stepped phase (`./tracks.ts`). The
- * document's constraint records as they stand — the live tracks mix no
- * constraint timeline — and no physics timeline keyed.
+ * `steppedLocals`' world transforms, without the oracle's rows (as
+ * `posedBoneWorldAlone` poses them): the live tracks' entry to the stepped
+ * phase (`./tracks.ts`). The document's constraint records as they stand —
+ * the live tracks mix no constraint timeline — and no physics timeline keyed.
  */
-export function steppedLocalsWorld(doc: CompiledDocument, bones: ModelBone[], plant: TimelinePlant, sliders: SliderApplication[], step: PoseStep, rows: boolean): Map<string, CoreWorld> {
-  const posed = steppedLocals(doc, bones, plant, () => constraintRecords(doc), [], 0, sliders, step);
-  if (rows) stepRows(posed);
-  return posed.world;
+export function steppedLocalsWorld(doc: CompiledDocument, bones: ModelBone[], plant: TimelinePlant, sliders: SliderApplication[], step: PoseStep): Map<string, CoreWorld> {
+  return steppedLocals(doc, bones, plant, () => constraintRecords(doc), [], 0, sliders, step).world;
 }
 
 /** Each path record with the curve its slot shows deformed by the sample's own deform timelines at `t` (`./deform.ts`), or as it was. */