rig-c 0.0.0-stage → 2.20.4

package/src/trackgen.ts

@@ -0,0 +1,364 @@
+/**
+ * A group track's **per-member** values, evaluated from a model the spec states.
+ *
+ * ## Why this module exists
+ *
+ * `groups` keys several bones **identically**, which is the right tool for a
+ * wheel pair and the wrong one for a face: on a face the whole content of the
+ * motion is that each part gets a *different* number. `gallery/portrait`'s held
+ * 12° yaw was **20 tracks**, sixteen of them the same two properties on six
+ * sibling bones with identical times, identical easings and six different
+ * values — so `groups` bought exactly one of the sixteen, the pair that happened
+ * to share `cos t` (issue #295).
+ *
+ * And not one of those numbers was a judgement either. Each feature's own
+ * `translatex` is `x·(cos t − 1) − (z − R)·sin t` and its `scalex` is
+ * `cos(α − t)/cos α` — docs/FACE.md §3 and §5 derive both, and the *only* free
+ * parameter per member is its **depth**. So this is `src/deformgen.ts`'s move on
+ * the bone half of the same turn: **the spec states the model and the compiler
+ * states the numbers.**
+ *
+ * ⭐ **The depth table is the point, not the line count.** FACE §2's sharp edge
+ * is that `x` is in the file and `z` is not — `grep -c '"z"'` over the worked
+ * example's two specs returned `0` and `0`, and every depth that produced every
+ * number lived only in a README beside them. A `derive` key states each
+ * member's depth, so the table a reader needs in order to check a sign is in the
+ * file that uses it.
+ *
+ * ## What this is NOT, and the rules that keep it that way
+ *
+ * 1. **It never authors.** Every parameter arrives from the spec — the angle,
+ *    each member's depth, what the parent already carries. The one number read
+ *    off the rig is the member bone's own **setup position**, which is the same
+ *    licence `evaluateDeformTransform` has to read an attachment's setup
+ *    vertices: it is a coordinate the spec already states, resolved by name.
+ * 2. **It generates no in-betweens.** MOTION §7 refuses a `rigc tween`. A model
+ *    is evaluated **at one key**, from parameters that key states, and what
+ *    happens between two keys is still the timeline's own curve. Sweeping an
+ *    angle is editing one number per key.
+ * 3. **It does not do timing.** `stagger` already shifts a member's keys in
+ *    member order (AUTHORING §4.3), so nothing here takes a phase, an index or
+ *    a delay. Two mechanisms for one lag would mean two places to look for it.
+ * 4. **It is one closed form per kind, named and refusable.** There is no
+ *    expression language here and no `v` that is a formula string: a kind the
+ *    compiler does not know is refused *by name*, which is the whole reason a
+ *    reviewer can check a claim.
+ *
+ * ## Determinism
+ *
+ * Each closed form is a fixed sequence of float64 operations over numbers read
+ * from the spec, evaluated in **member order** — the group's own array order,
+ * never an iteration over an unordered set. The caller quantises with the
+ * compiler's `onModelGrid` — the model's 1e-6 resolution, then the float32 name
+ * every emitted number takes — so the same spec emits the same bytes and
+ * `A18_DETERMINISTIC_EMIT` proves it on a second independent compile.
+ */
+
+import { CompileError } from './errors.ts';
+
+/** The kinds this module evaluates, in the order the docs list them. */
+export const TRACK_DERIVE_KINDS = ['yaw', 'pitch'] as const;
+
+export type TrackDeriveKind = (typeof TRACK_DERIVE_KINDS)[number];
+
+/**
+ * A **2.5D turn**, read per member instead of per vertex.
+ *
+ * The members are treated as rigid parts sitting on a surface that turns about
+ * one axis, and the key is that rotation projected back onto the screen. `yaw`
+ * stands the axis vertically and reads each member's setup `x`; `pitch` lays it
+ * horizontally and reads `y`. docs/FACE.md §3 is the displacement's derivation
+ * and §5 the foreshortening's.
+ *
+ * ⚠️ **`depth` is a decision, not a measurement.** FACE §2: a depth is not
+ * readable off the art — it is a statement about a shape the drawing only
+ * implies. Derive its *sign* from the draw order and argue only about the size.
+ */
+export interface TrackDeriveTurn {
+  kind: TrackDeriveKind;
+  /** The turn, in degrees. Positive yaws toward −x, which is FACE §1's sign. */
+  degrees: number;
+  /**
+   * Each member's depth: `{ member: z }` on a group track, one number on a bone
+   * track. `z` runs **toward the viewer** (FACE §1), so a **larger** depth is
+   * **nearer** — a nose in front of the skull surface takes a bigger number than
+   * the socket beside it — and a **negative** depth is behind the axis, which is
+   * what makes the back of a head swing the other way (FACE §2).
+   *
+   * ⚠️ That sign is the one thing here no assertion can check, and this comment
+   * had it backwards until issue #350's neighbour
+   * ([#351](https://github.com/firejune/rigc/issues/351)). The closed form is
+   * the arbiter: `d = (x−about)·(cos t − 1) − (depth − carried)·sin t` gives a
+   * part with `depth > carried` a **negative** residual, and FACE §3 makes
+   * exactly that the nose diagnostic — *if the nose's residual is not negative,
+   * the depths are wrong*. That only holds if a larger depth means nearer.
+   */
+  depth: number | Record<string, number>;
+  /**
+   * The depth whose shift a **parent bone already applies**. Default 0.
+   *
+   * ⭐ This is FACE §3's shared-shift split, stated. Put a bone at the plate's
+   * own origin, key `−carried·sin t` there, and each member then keys only what
+   * is left: `x·(cos t − 1) + (carried − z)·sin t`. A residual is 1–6 units
+   * where a total is 30–40, and **that is an auditing decision before it is a
+   * rigging one** — nobody can eyeball a wrong sign in the second and everybody
+   * can in the first.
+   *
+   * 0 means the parent carries nothing, which is the honest reading for a part
+   * hanging off the head itself rather than off the shared-shift bone. It is
+   * deliberately not named for the surface it usually is: `surface: 0` would
+   * claim a skull surface at depth 0, and what the number means is *what has
+   * already been applied*.
+   */
+  carried?: number;
+  /** Where the axis crosses the driving coordinate, in the members' shared parent's space. Default 0. */
+  about?: number;
+}
+
+export type TrackDerive = TrackDeriveTurn;
+
+/**
+ * Which bone property each kind projects onto, and which setup coordinate it
+ * reads.
+ *
+ * ⭐ **The property picks the projection.** A turn does two things to a part
+ * sitting on a curved surface — it moves it, and it narrows it — and those are
+ * two Spine timelines rather than two models. So the track's `property`, which
+ * the author has already stated, says which half of the same turn this key is;
+ * a property the kind has no projection onto is refused by name rather than
+ * quietly driven by the wrong half.
+ */
+export const TRACK_DERIVE_PROJECTIONS: Record<
+  TrackDeriveKind,
+  { coordinate: 'x' | 'y'; shift: string; foreshorten: string }
+> = {
+  yaw: { coordinate: 'x', shift: 'translatex', foreshorten: 'scalex' },
+  pitch: { coordinate: 'y', shift: 'translatey', foreshorten: 'scaley' },
+};
+
+/** One member, as the compiler resolved it against the rig. */
+export interface TrackDeriveMember {
+  /** The bone's name. */
+  name: string;
+  /** Its setup coordinate on the kind's driving axis, in its parent's space. */
+  at: number;
+}
+
+/** One evaluated member row, for `explain` to print and a reviewer to check. */
+export interface TrackDeriveMemberValue {
+  member: string;
+  /** The setup coordinate read off the rig, already relative to `about`. */
+  at: number;
+  /** The depth the spec stated for this member. */
+  depth: number;
+  /** The emitted value, quantised by the caller's rounder. */
+  value: number;
+}
+
+/**
+ * What one evaluation did.
+ *
+ * `stated` is the spec's own parameters, `derived` the scalars the closed form
+ * got out of them, and `members` the per-member rows in member order — the
+ * three things that let somebody re-derive a row by hand. The values are the
+ * **emitted** ones, so the report and the artifact cannot disagree (the same
+ * rule `DeformTransformReport` holds to, and issue #319's `DEFORM` block reads
+ * that report rather than recomputing it).
+ */
+export interface TrackDeriveReport {
+  kind: TrackDeriveKind;
+  /** Which half of the turn this key is: the displacement or the foreshortening. */
+  projection: 'shift' | 'foreshorten';
+  /** The model as the spec states it. */
+  stated: string;
+  /** The closed form, written out. */
+  formula: string;
+  /** The scalars the closed form derived, e.g. `sin t = 0.207912`. */
+  derived: string[];
+  members: TrackDeriveMemberValue[];
+}
+
+/** The compiler's `onModelGrid` (1e-6, then float32), passed in so the quantiser stays in one place. */
+export type Rounder = (n: number) => number;
+
+/**
+ * Evaluate one `derive` over a track's members.
+ *
+ * `members` arrive in the group's own declared order, each with the setup
+ * coordinate the kind reads. The caller owns resolving those against the rig and
+ * refusing the cases where they do not mean one thing — by the time execution
+ * reaches here every `at` is measured from the same origin.
+ *
+ * Returns one value per member, in the same order, plus the report.
+ */
+export function evaluateTrackDerive(
+  derive: TrackDerive,
+  property: string,
+  members: readonly TrackDeriveMember[],
+  round: Rounder,
+  where: string,
+): TrackDeriveReport {
+  if (derive === null || typeof derive !== 'object' || Array.isArray(derive)) {
+    throw new CompileError(`${where}: "derive" is ${JSON.stringify(derive)}; it is an object with a "kind"`);
+  }
+  const kind = (derive as { kind?: unknown }).kind;
+  if (typeof kind !== 'string' || !(TRACK_DERIVE_KINDS as readonly string[]).includes(kind)) {
+    throw new CompileError(
+      `${where}: "derive" has kind ${JSON.stringify(kind)}; this spec evaluates ${TRACK_DERIVE_KINDS.join(', ')}. ` +
+        'A model that is none of those is still authorable as a per-member "v" map, or as one track per member.',
+    );
+  }
+  const turn = derive as TrackDeriveTurn;
+  const projections = TRACK_DERIVE_PROJECTIONS[kind as TrackDeriveKind];
+  const projection: 'shift' | 'foreshorten' =
+    property === projections.shift ? 'shift' : property === projections.foreshorten ? 'foreshorten' : refuseProperty(kind, property, where);
+
+  const degrees = num(turn.degrees, 'degrees', where);
+  const about = turn.about === undefined ? 0 : num(turn.about, 'about', where);
+  // `carried` is subtracted from a depth, and the foreshortening does not read a
+  // depth difference at all — it reads the member's own angle off the axis. So a
+  // `carried` here changes nothing, and a parameter that changes nothing is a
+  // reader's false lead about which model produced the numbers.
+  if (projection === 'foreshorten' && turn.carried !== undefined) {
+    throw new CompileError(
+      `${where}: derive ${kind} states carried=${JSON.stringify(turn.carried)} on a "${property}" track, and the ` +
+        'foreshortening reads no depth difference — it is cos(α − t)/cos α, where α is the member\'s own angle off the ' +
+        `axis. "carried" belongs on the "${projections.shift}" track, whose shared shift is the thing it names.`,
+    );
+  }
+  const carried = turn.carried === undefined ? 0 : num(turn.carried, 'carried', where);
+
+  const rad = (degrees * Math.PI) / 180;
+  const cosMinus1 = Math.cos(rad) - 1;
+  const sin = Math.sin(rad);
+
+  const values: TrackDeriveMemberValue[] = [];
+  for (const member of members) {
+    const depth = depthOf(turn.depth, member.name, members, where, kind);
+    const u = member.at - about;
+    if (projection === 'shift') {
+      values.push({ member: member.name, at: u, depth, value: round(u * cosMinus1 - (depth - carried) * sin) });
+      continue;
+    }
+    // A part behind the axis has no patch of front surface to foreshorten, and
+    // `atan2(u, z)` there is an angle measured round the back — so the closed
+    // form would silently evaluate a different model. Refused by name, which is
+    // also FACE §2's "derive the sign from the draw order" as a check.
+    if (depth <= 0) {
+      throw new CompileError(
+        `${where}: derive ${kind} projects onto "${property}" and member "${member.name}" states depth ${depth}. ` +
+          'Foreshortening is cos(α − t)/cos α with α = atan2(coordinate, depth), which needs the part to be IN FRONT ' +
+          'of the axis; at or behind it there is no front surface to narrow. A part behind the axis still takes the ' +
+          `"${projections.shift}" projection, where a negative depth is exactly what swings it the other way.`,
+      );
+    }
+    const alpha = Math.atan2(u, depth);
+    const scale = Math.cos(alpha - rad) / Math.cos(alpha);
+    if (scale <= 0) {
+      throw new CompileError(
+        `${where}: derive ${kind} turns member "${member.name}" (${projections.coordinate}=${u}, depth=${depth}) past ` +
+          `its own edge: α = ${round(alpha)} rad and the turn is ${round(rad)} rad, so cos(α − t) is ` +
+          `${round(Math.cos(alpha - rad))} and the scale would be ${round(scale)}. A scale at or below 0 mirrors the ` +
+          'drawing rather than narrowing it. The part has turned edge-on — the turn is past what this construction ' +
+          'carries, and FACE §8 is the page that picks a construction from the angle.',
+      );
+    }
+    values.push({ member: member.name, at: u, depth, value: round(scale) });
+  }
+
+  const c = projections.coordinate;
+  const stated =
+    `degrees=${degrees}` +
+    (projection === 'shift' && turn.carried !== undefined ? ` carried=${carried}` : '') +
+    (turn.about === undefined ? '' : ` about=${about}`);
+  const formula =
+    projection === 'shift'
+      ? `d${c} = (${c}−about)·(cos t − 1) − (depth − carried)·sin t`
+      : `scale${c.toUpperCase()} = cos(α − t) / cos α,   α = atan2(${c}−about, depth)`;
+  const derived =
+    projection === 'shift'
+      ? [
+          `t = ${round(rad)} rad`,
+          `cos t − 1 = ${round(cosMinus1)}`,
+          `sin t = ${round(sin)}`,
+          `shift the parent carries = −carried·sin t = ${round(-carried * sin)}`,
+        ]
+      : [`t = ${round(rad)} rad`, `cos t = ${round(Math.cos(rad))}, which is the value on the axis (α = 0)`];
+
+  return { kind: kind as TrackDeriveKind, projection, stated, formula, derived, members: values };
+}
+
+/**
+ * The property refusal, as its own function so the message can list both
+ * projections rather than only the one that missed.
+ */
+function refuseProperty(kind: string, property: string, where: string): never {
+  const p = TRACK_DERIVE_PROJECTIONS[kind as TrackDeriveKind];
+  throw new CompileError(
+    `${where}: derive ${kind} has no projection onto "${property}". It projects onto "${p.shift}" (the displacement, ` +
+      `FACE §3) and "${p.foreshorten}" (the narrowing, FACE §5), and onto nothing else — a turn about one axis moves ` +
+      `nothing along it, so a paired "translate"/"scale" would need a second channel this model does not state. ` +
+      'State the axis, or write the values as a per-member "v" map.',
+  );
+}
+
+/**
+ * One member's depth, from either shape of the field.
+ *
+ * A group track's `depth` is a map and a bone track's is one number, and each
+ * refuses the other's shape: a map on a bone track names members that track has
+ * no way to reach, and a number on a group track is the shared value `groups`
+ * already keys without any of this (issue #295's own starting point).
+ */
+function depthOf(
+  depth: unknown,
+  member: string,
+  members: readonly TrackDeriveMember[],
+  where: string,
+  kind: string,
+): number {
+  if (typeof depth === 'number') {
+    if (members.length !== 1) {
+      throw new CompileError(
+        `${where}: derive ${kind} states one depth ${depth} for ${members.length} members ` +
+          `(${members.map((m) => m.name).join(', ')}). One number for every member is the shared value a plain "v" ` +
+          'already keys — state a depth per member, as { "member": z, … }.',
+      );
+    }
+    return num(depth, 'depth', where);
+  }
+  if (depth === null || typeof depth !== 'object' || Array.isArray(depth)) {
+    throw new CompileError(
+      `${where}: derive ${kind} has depth ${JSON.stringify(depth)}; it is a number on a bone track and ` +
+        '{ "member": z, … } on a group track',
+    );
+  }
+  const table = depth as Record<string, unknown>;
+  const stated = Object.keys(table);
+  const known = new Set(members.map((m) => m.name));
+  for (const name of stated) {
+    if (!known.has(name)) {
+      throw new CompileError(
+        `${where}: derive ${kind} states a depth for "${name}", which this track does not key ` +
+          `(its members are: ${members.map((m) => m.name).join(', ')})`,
+      );
+    }
+  }
+  if (!(member in table)) {
+    throw new CompileError(
+      `${where}: derive ${kind} states no depth for member "${member}" ` +
+        `(it states: ${stated.length ? stated.join(', ') : 'nothing'}). ` +
+        'A depth is refused rather than defaulted: a member silently at depth 0 would be keyed with a DIFFERENT ' +
+        'model from the ones beside it, and that is exactly the error a table of six is written to make visible.',
+    );
+  }
+  return num(table[member], `depth.${member}`, where);
+}
+
+/** One required finite number, refused by field name rather than compiled as a NaN. */
+function num(value: unknown, field: string, where: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new CompileError(`${where}: derive field "${field}" is ${JSON.stringify(value)}; it is a finite number the spec has to state`);
+  }
+  return value;
+}

package/src/transform.ts

@@ -0,0 +1,310 @@
+/**
+ * Setup-pose world transforms, and their inverses.
+ *
+ * The mesh tier used to get away with "bind = world - bone origin", and the
+ * compiler asserted the precondition it needed: every bone translation-only. The
+ * joint archetype breaks that on purpose — `axis` carries the cut's angle and the
+ * grips carry their radial facing — so the shortcut has to become a real inverse.
+ *
+ * ⚠️ A rotated parent would NOT have failed loudly under the old shortcut. It
+ * would have sheared every weighted vertex at setup and looked like a badly
+ * measured polygon. That is why the old code refused rotation instead of ignoring
+ * it, and why this file exists rather than a relaxed assertion.
+ *
+ * The composition, for a bone with a parent in the `normal` mode:
+ *
+ *   la = cos(rot)      lb = cos(rot + 90) = -sin(rot)
+ *   lc = sin(rot)      ld = sin(rot + 90) =  cos(rot)
+ *   a = pa*la + pb*lc  b = pa*lb + pb*ld
+ *   c = pc*la + pd*lc  d = pc*lb + pd*ld
+ *   worldX = pa*x + pb*y + parent.worldX
+ *
+ * ⚠️ **Scale, shear and `inherit` are honoured, and that is a correction** (issue
+ * #804). This header said *"scale and shear are not emitted by rigc, so they are
+ * fixed at 1 and 0 here"* long after the rig spec gained `scaleX`/`scaleY`/
+ * `shearX`/`shearY`/`inherit` and `ingest` began carrying them from every export
+ * that states them — so every setup measurement over a scaled bone was taken on
+ * a skeleton the runtime never builds. A 50/50-weighted probe path over one bone
+ * at scale 2 measured **0.752×** the runtime's own `PathConstraint.curves` on the
+ * build's posed geometry, and a production rig's weighted path 2.35×. The
+ * weights were blended all along; the matrices they were blended through were
+ * wrong.
+ *
+ * ⭐ **`computeWorldTransforms` is the core's evaluator** (`worldTransforms` in
+ * [`src/core/world.ts`](core/world.ts), issue #1015), whose every rule — the five
+ * inherit modes, the collapsed parent axis, the operation orders — was measured
+ * against the runtime's pose dump and is held there by the core suite. Since
+ * issue #1021 it runs under the runtime's own arithmetic (`RUNTIME_ARITHMETIC`,
+ * the evaluator's default), so the matrices every point is bound through are the
+ * ones the runtime poses the build with, to the bit. This file keeps what is the
+ * compiler's own: the coordinate contract, the refusals by name, the world
+ * rotation a region cancels, and the inverses.
+ *
+ * ⚠️ **Why the runtime's arithmetic and not the textbook's** (issue #1021). A
+ * point is bound by inverting a setup matrix; the runtime then poses it through
+ * its own. The two used to differ in the last bits — `Math.PI` against the
+ * runtime's 3.1415927, `[cos, −sin, sin, cos]` against the y column taken at
+ * `rotation + 90`, radians to degrees by division against multiplication — and
+ * that is not noise below the file's precision: an unrotated root reads
+ * `b = −2.3e-8` in the runtime, so a point 256 units above its bone was bound
+ * 5.9e-6 off before the float32 spelling was even applied. Measured from inside
+ * `compile` (every authored world position `toBoneLocal` was handed) against
+ * spine-core's pose of the emitted build, the old arithmetic put `gallery/look`'s
+ * 312 bound points up to 8.6e-5 from where they were authored (RMS 5.1e-5) and
+ * `gallery/flex`'s 258 up to 2.3e-5; the runtime's puts every one of them at the
+ * float32 floor — the distance the float32 spelling of the exact inverse alone
+ * accounts for (look 8.1e-6, flex 4.1e-6). `CO24` holds it.
+ *
+ * 🔸 **The rule has a second half: what is MEASURED reads the exact frame.**
+ * The runtime's arithmetic is for what is bound — the matrices a point is
+ * inverted through. Anything the compiler measures of the authored rig and
+ * reports, compares against a threshold, sorts by or refuses on is a statement
+ * about the spec, and reads `computeExactFrameTransforms` (below): a depth turn
+ * ceiling, a ring's control angles, a `segments` mesh's segments and falloff.
+ * An angle the author stated as 90 has to print as 90.
+ */
+import type { ModelBone } from './model.ts';
+import { modeMatrix, RUNTIME_ARITHMETIC, worldTransforms, type CoreWorld, type WorldArithmetic } from './core/world.ts';
+
+/**
+ * What `computeWorldTransforms` reads off a bone — a structural type, so both a
+ * Spine bone (`SpineBone`, what spine-parts and every skeleton reader hold) and
+ * a compiled-model bone (`ModelBone`, what `compile` holds) satisfy it as they
+ * are, without a cast.
+ *
+ * The two differ in one key, the inherit mode: Spine 4.3 spells it `inherit`
+ * and the model `inheritMode`. The union below admits exactly one of the two on
+ * any one bone (the other is `never`), so a bone carrying both is a type error
+ * rather than a question of which one wins, and the mode is read as
+ * `inheritMode ?? inherit` — whichever the bone has.
+ */
+export type PosableBone = {
+  name: string;
+  parent?: string;
+  x?: number;
+  y?: number;
+  rotation?: number;
+  scaleX?: number;
+  scaleY?: number;
+  shearX?: number;
+  shearY?: number;
+} & ({ inherit?: string; inheritMode?: never } | { inheritMode?: string; inherit?: never });
+
+export interface BoneTransform {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  worldX: number;
+  worldY: number;
+  /** World rotation in degrees, CCW, y up. What a region attachment cancels. */
+  worldRotation: number;
+}
+
+export class TransformError extends Error {}
+
+/**
+ * Crop pixels (y down, origin top-left) -> Spine world (y up, origin at the
+ * bottom-left of the crop).
+ *
+ * This is the whole coordinate contract, and it is also the viewer's: the
+ * renderer's root element sits at the BOTTOM-left of the stage because
+ * spine-html negates world Y (Spine is Y-up, CSS is Y-down).
+ *
+ * It lived in `src/archetype.ts` until the archetype tables left the code, which
+ * was the wrong home for it anyway — it is not a property of any formation.
+ */
+export function cropToSpineY(cropY: number, cropHeight: number): number {
+  return cropHeight - cropY;
+}
+
+/**
+ * The textbook's arithmetic — `Math.PI`, a bone with the default scale and no
+ * shear framed as `[cos, −sin, sin, cos]`, radians to degrees by dividing by
+ * the degree factor — in which an unrotated bone's frame is the identity
+ * exactly. Every point the compiler binds goes through the runtime's instead
+ * (the header's ⚠️); this is what `computeExactFrameTransforms` evaluates
+ * under, and nothing else.
+ */
+const EXACT_FRAME_ARITHMETIC: WorldArithmetic = {
+  radiansPerDegree: Math.PI / 180,
+  degreesOf: (radians) => radians / (Math.PI / 180),
+  rotationOnlyFrame: true,
+};
+
+/**
+ * World transform of every bone, in declaration order.
+ *
+ * Bones must be declared parents-first, which is also what `SkeletonJson`
+ * requires (it resolves `parent` by name against the bones already read), so a
+ * violation here is a violation there.
+ *
+ * The matrices and origins are the core's (`worldTransforms`, under the
+ * runtime's arithmetic — the header's ⚠️). What is decided here is what the core does not say:
+ * an undeclared parent and an `inherit` no mode answers to are refused by name
+ * as `TransformError`, a bone whose `parent` is empty is a root as it always was
+ * here, and `worldRotation` is read off the matrix — a root with the default
+ * scale and no shear keeps its stated rotation, unwrapped. The angle is turned
+ * into degrees as the runtime turns one (`RUNTIME_DEG`, by multiplying), so
+ * the rotation a region writes to cancel it is read back by the runtime as
+ * that angle.
+ */
+export function computeWorldTransforms(bones: readonly PosableBone[]): Map<string, BoneTransform> {
+  return evaluate(bones, RUNTIME_ARITHMETIC);
+}
+
+/**
+ * The same bones under `EXACT_FRAME_ARITHMETIC`: the frame the compiler
+ * MEASURES the authored rig in, and binds nothing through (issue #1021) — a
+ * mesh's depth turn ceiling (`sampleMeshDepth` in `compile.ts`), a ring's
+ * control angles (`ringControlAngles`, which orders the split and refuses a
+ * tie by printing the angle), and a `segments` mesh's segments, the distances
+ * its falloff and `minWeight` read and its shared-origin refusal. It differs from
+ * `computeWorldTransforms` only in the last bits, and that is exactly why it is
+ * kept (issue #1021): the ceiling is a statement about the authored mesh, and
+ * its reader treats an axis whose area term is exactly zero as one that cannot
+ * fold. The runtime frames an unrotated bone with `b = −2.3e-8`, so in its
+ * bind space a sheet whose depth rises linearly in x — which cannot fold a
+ * pitch at any angle — reads a pitch ceiling of 89.99997°, and `gallery/look`'s
+ * two hair locks gained four such ceilings with their counts (`TC03`, `TC06`
+ * went red on it). A control angle read through the runtime's frame printed
+ * an authored 90 as 89.99999734089101 in its tie refusal (`RF46`). On the 19
+ * recipes the only bytes this keeps from moving are look's ceilings; no
+ * emitted position goes through it.
+ */
+export function computeExactFrameTransforms(bones: readonly PosableBone[]): Map<string, BoneTransform> {
+  return evaluate(bones, EXACT_FRAME_ARITHMETIC);
+}
+
+function evaluate(bones: readonly PosableBone[], arithmetic: WorldArithmetic): Map<string, BoneTransform> {
+  const model: ModelBone[] = [];
+  const declared = new Set<string>();
+  for (const bone of bones) {
+    const parent = bone.parent ? bone.parent : undefined;
+    if (parent !== undefined && !declared.has(parent)) {
+      throw new TransformError(`bone "${bone.name}" names parent "${parent}", which is not declared before it`);
+    }
+    model.push({
+      name: bone.name,
+      parent,
+      x: bone.x,
+      y: bone.y,
+      rotation: bone.rotation,
+      scaleX: bone.scaleX,
+      scaleY: bone.scaleY,
+      shearX: bone.shearX,
+      shearY: bone.shearY,
+      inheritMode: parent === undefined ? undefined : inheritMode(bone),
+    });
+    declared.add(bone.name);
+  }
+  const worlds = worldTransforms(model, null, modeMatrix, arithmetic);
+  const out = new Map<string, BoneTransform>();
+  for (const bone of model) {
+    const w = worlds.get(bone.name) as CoreWorld;
+    const plain = (bone.scaleX ?? 1) === 1 && (bone.scaleY ?? 1) === 1 && (bone.shearX ?? 0) === 0 && (bone.shearY ?? 0) === 0;
+    const worldRotation = bone.parent === undefined && plain ? (bone.rotation ?? 0) : (arithmetic.degreesOf(Math.atan2(w.c, w.a)) + 360) % 360;
+    out.set(bone.name, { a: w.a, b: w.b, c: w.c, d: w.d, worldX: w.worldX, worldY: w.worldY, worldRotation });
+  }
+  return out;
+}
+
+type InheritMode = 'normal' | 'onlyTranslation' | 'noRotationOrReflection' | 'noScale' | 'noScaleOrReflection';
+
+const INHERIT_MODES: readonly InheritMode[] = ['normal', 'onlyTranslation', 'noRotationOrReflection', 'noScale', 'noScaleOrReflection'];
+
+/**
+ * A bone's `inherit`, folded the way `Utils.enumValue` folds it — the first
+ * letter and nothing else. A spelling the runtime cannot resolve is refused by
+ * name rather than read as normal: the runtime's switch matches no case and
+ * leaves the matrix where it was, and the rig spec's parse refuses that
+ * spelling first (issue #733), so reaching this throw is rigc's own defect.
+ */
+function inheritMode(bone: PosableBone): InheritMode {
+  const value = bone.inheritMode ?? bone.inherit;
+  if (value === undefined) return 'normal';
+  const folded = value.length === 0 ? value : value[0].toLowerCase() + value.slice(1);
+  const mode = INHERIT_MODES.find((m) => m === folded);
+  if (!mode) {
+    throw new TransformError(`bone "${bone.name}" inherit is ${JSON.stringify(value)}, which the runtime resolves to no mode`);
+  }
+  return mode;
+}
+
+/**
+ * World point -> the bone's local space. Used for bind coordinates and offsets.
+ *
+ * ⚠️ **Not rounded**, since issue #716. It used to round to six decimals here,
+ * which made this file a second emitter: `buildBone` and the region placement
+ * wrote its result straight into the skeleton. The emitted number's precision
+ * is one decision, `f32` in `compile.ts`, so the callers quantise what they
+ * emit and this returns the double.
+ */
+export function toBoneLocal(m: BoneTransform, worldX: number, worldY: number): [number, number] {
+  const det = m.a * m.d - m.b * m.c;
+  if (!Number.isFinite(det) || Math.abs(det) < 1e-9) {
+    throw new TransformError(`bone transform is singular (det ${det}); a zero-scale bone cannot hold bind coordinates`);
+  }
+  const px = worldX - m.worldX;
+  const py = worldY - m.worldY;
+  return [(px * m.d - py * m.b) / det, (py * m.a - px * m.c) / det];
+}
+
+/**
+ * A world **displacement** -> the bone's local space: rotation and scale only,
+ * with the translation left out.
+ *
+ * ⭐ Not a variant of `toBoneLocal` for convenience — it is the other half of a
+ * different identity. `computeWorldVertices` composes a weighted vertex as
+ * `Σ wᵢ · (Rᵢ · (bindᵢ + deformᵢ) + tᵢ)`, so the translation `tᵢ` lands on the
+ * vertex once and never on the offset. Writing `Rᵢ⁻¹ · D` into every influence
+ * therefore moves the vertex by exactly `D · Σ wᵢ`, which is `D` because the
+ * weights close at 1 (issue #389). Running a displacement through `toBoneLocal`
+ * instead would subtract the bone's origin from it and land the vertex
+ * somewhere nobody asked for.
+ *
+ * ⚠️ **Not rounded**, for `toWorld`'s reason: the caller quantises the one
+ * number it emits, and rounding an intermediate would bias it.
+ */
+export function toBoneLocalVector(m: BoneTransform, worldDX: number, worldDY: number): [number, number] {
+  const det = m.a * m.d - m.b * m.c;
+  if (!Number.isFinite(det) || Math.abs(det) < 1e-9) {
+    throw new TransformError(`bone transform is singular (det ${det}); a zero-scale bone cannot carry a displacement`);
+  }
+  return [(worldDX * m.d - worldDY * m.b) / det, (worldDY * m.a - worldDX * m.c) / det];
+}
+
+/**
+ * A bone-local point -> world. The inverse of `toBoneLocal`, and the direction
+ * `VertexAttachment.computeWorldVertices` takes at setup.
+ *
+ * ⚠️ **Not rounded**, and that is the difference from every other function here.
+ * Its callers measure with the result — a path's arc lengths are a sum over many
+ * of these — so quantising each point first would bias the sum by up to half a
+ * step per sample. Round the answer, not the samples.
+ */
+export function toWorld(m: BoneTransform, localX: number, localY: number): [number, number] {
+  return [m.a * localX + m.b * localY + m.worldX, m.c * localX + m.d * localY + m.worldY];
+}
+
+/**
+ * Normalise degrees into (-180, 180], which is how an editor shows a rotation.
+ *
+ * Not rounded, for `toBoneLocal`'s reason: a caller that emits the angle
+ * quantises it with `f32`, and one that compares or measures with it wants the
+ * double.
+ */
+export function normaliseDegrees(deg: number): number {
+  let v = ((deg % 360) + 360) % 360;
+  if (v > 180) v -= 360;
+  return v;
+}
+
+/**
+ * Screen degrees (y down, the convention the manifest and the art share) ->
+ * Spine degrees (y up, CCW). One negation, stated once, so no other file has to
+ * remember which way the y flip goes.
+ */
+export function screenToSpineDegrees(screenDeg: number): number {
+  return normaliseDegrees(-screenDeg);
+}