spine-rigc 2.55.0 → 2.57.0

package/src/stop.ts

@@ -0,0 +1,472 @@
+/**
+ * `stops` — a swinging chain held off a leg (issue #1413).
+ *
+ * Spine has no collider and no angle limit — a physics constraint's `limit` is
+ * a velocity cap — so a skirt chain driven by physics swings its hem straight
+ * through the thigh it hangs in front of. The working stand-in, tuned by hand on
+ * a dancer's pleated skirt, is a small network per chain: a point on the leg, a
+ * frame that aims at it from the chain's root, the swinging link's rotation
+ * copied onto that frame, and the DRAWN link — the one the mesh is weighted to —
+ * held by a transform clamp, so it may swing away from the leg and not past its
+ * rest angle toward it. One declaration here expands to exactly that network,
+ * and to nothing else: what it writes is what an author would write by hand,
+ * bone for bone and constraint for constraint, which `LG01` holds byte for byte.
+ *
+ * ⭐ **The expansion happens before anything else reads the rig.** `parseRigSpec`
+ * calls `expandStops` ahead of its own name resolution, so every reader after it
+ * — the parse's own checks, `compile`, the gate — sees ordinary bones and
+ * constraints and nothing that knows a stop was there. A stop therefore cannot
+ * buy an exemption, a default or a code path of its own: it is spelling.
+ *
+ * Every position and angle is the declaration's, or derived from it and the
+ * setup pose the rig spec states — no value is measured off the art and none is
+ * defaulted. What is derived, and from what:
+ *
+ *   - the point bone's `x`/`y` are `at`, in `against`'s local space, as written;
+ *   - the frame hangs where the first link hangs — its parent, `x`, `y` and
+ *     `length` are the link's — and its `rotation` points it at the point;
+ *   - the drawn link's rest rotation in the frame is the angle from the aim line
+ *     to the link, so at rest the drawn link lies on the link;
+ *   - which way is **inward** is the way from the link toward the aim line: the
+ *     point is on the leg, so turning toward it is turning into the leg;
+ *   - the clamp's two bounds are that rest angle moved by `inward` and `outward`.
+ *
+ * The angles are read in the exact frame (`computeExactFrameTransforms`): they
+ * are statements about the rig as authored, the rule `src/transform.ts` states
+ * for what is measured rather than bound.
+ */
+import { CompileError } from './errors.ts';
+import type { RigBone, RigConstraint, RigIkConstraint, RigSpec, RigStop, RigTransformConstraint } from './rig.ts';
+import {
+  computeExactFrameTransforms,
+  directionDegrees,
+  localDirectionDegrees,
+  toWorld,
+  type BoneTransform,
+} from './transform.ts';
+
+/**
+ * A planted wrong expansion, for the selftest's mutants (`LG` controls) — each
+ * a mistake a hand-built network could carry and still build green.
+ *
+ *   - `swapRange` — inward taken the other way round, so the clamp holds the
+ *     link off the side it should swing to and lets it into the leg;
+ *   - `aimAtAgainst` — the frame aimed at the `against` bone's origin rather
+ *     than at the point on it;
+ *   - `appendConstraints` — every generated constraint at the end of the
+ *     array, after the physics of the links below, which then swing from a
+ *     drawn link not yet clamped.
+ *
+ * @internal
+ */
+export interface StopPlant {
+  swapRange?: boolean;
+  aimAtAgainst?: boolean;
+  appendConstraints?: boolean;
+}
+
+/** The names one stop generates, all derived from its `chain` and its links' names. */
+export interface StopNames {
+  /** `<chain>_touch` — the point, a child of `against`. */
+  point: string;
+  /** `<chain>_stop` — the frame, aimed at the point. */
+  frame: string;
+  /** `<chain>_stop_aim` — the ik constraint that aims it. */
+  aim: string;
+  /** `<first link>_rel` — the first link's rotation, copied onto the frame. */
+  rel: string;
+  /** `<first link>_rel_copy` — the transform constraint that copies it. */
+  copy: string;
+  /** `<link>_d` per link — the drawn link. */
+  drawn: string[];
+  /** `<link>_clamp` per link — the transform constraint that holds it. */
+  clamp: string[];
+}
+
+/** The generated names of a stop, in one place so the refusals and the expansion cannot spell them apart. */
+export function stopNames(chain: string, links: readonly string[]): StopNames {
+  return {
+    point: `${chain}_touch`,
+    frame: `${chain}_stop`,
+    aim: `${chain}_stop_aim`,
+    rel: `${links[0]}_rel`,
+    copy: `${links[0]}_rel_copy`,
+    drawn: links.map((l) => `${l}_d`),
+    clamp: links.map((l) => `${l}_clamp`),
+  };
+}
+
+function isObj(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** One stop, read and checked: every field present, every name resolved. */
+interface ReadStop {
+  who: string;
+  chain: string;
+  links: string[];
+  against: string;
+  at: [number, number];
+  inward: number;
+  outward: number;
+  lower: { inward: number; outward: number } | null;
+  names: StopNames;
+}
+
+/** The transform fields a drawn link copies from its link (the frame copies `x`, `y` and `length` only). */
+const TWIN_FIELDS = ['length', 'x', 'y', 'rotation', 'scaleX', 'scaleY', 'shearX', 'shearY', 'inherit'] as const;
+
+/** A degree bound a clamp can reach: a local rotation read off a world copy is in (-180, 180]. */
+const BOUND = 180;
+
+/** An angle in (-540, 540) brought into (-180, 180] by at most one whole turn. */
+function halfTurn(deg: number): number {
+  if (deg > 180) return deg - 360;
+  if (deg <= -180) return deg + 360;
+  return deg;
+}
+
+/**
+ * The rig spec with every `stops` entry expanded into the bones and constraints
+ * it stands for, or the spec itself when it declares no `stops`.
+ *
+ * Bones: the frame immediately before the first link; the first link's `_rel`
+ * and `_d` immediately after it; each lower link's `_d` immediately after that
+ * link; the point after every other bone. Constraints: the aim immediately
+ * before the last constraint that writes the first link, the copy and the first
+ * clamp immediately after it, and each lower clamp immediately after the last
+ * constraint that writes its link — so the frame is aimed before the link
+ * swings, and every swing is copied and clamped before anything below it reads
+ * the drawn link.
+ *
+ * The returned spec keeps `stops` as written, so `compile` can refuse a link a
+ * motion-spec physics table also drives (that table is emitted after every rig
+ * constraint, past the clamps); nothing emits it.
+ */
+export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {}): RigSpec {
+  const declared: unknown = spec.stops;
+  if (declared === undefined) return spec;
+  if (!Array.isArray(declared)) {
+    throw new CompileError(`${where}: "stops" is ${JSON.stringify(declared)}; it is an array of { "chain", "links", "against", "at", "inward", "outward", "lower"? }`);
+  }
+  const authored = new Map<string, RigBone>();
+  for (const bone of spec.bones) if (isObj(bone) && typeof bone.name === 'string') authored.set(bone.name, bone);
+  const constraints = spec.constraints ?? [];
+
+  // -- 1. every field, every name ----------------------------------------------
+  const stops: ReadStop[] = [];
+  const stoppedBy = new Map<string, string>();
+  for (const [i, entry] of declared.entries()) {
+    if (!isObj(entry)) throw new CompileError(`${where}: stops[${i}] is ${JSON.stringify(entry)}; a stop is an object`);
+    const chain = entry.chain;
+    if (typeof chain !== 'string' || chain.length === 0) {
+      throw new CompileError(`${where}: stops[${i}] needs a "chain" — the name its point, frame and aim are called after ("<chain>_touch", "<chain>_stop", "<chain>_stop_aim")`);
+    }
+    const who = `${where}: stop "${chain}"`;
+    const links: unknown = entry.links;
+    if (!Array.isArray(links) || links.length === 0 || !links.every((l): l is string => typeof l === 'string')) {
+      throw new CompileError(`${who} states "links" ${JSON.stringify(links) ?? 'absent'}; it is the chain's swinging links, root first — a non-empty array of bone names`);
+    }
+    for (const [k, link] of links.entries()) {
+      const bone = authored.get(link);
+      if (bone === undefined) throw new CompileError(`${who}: links[${k}] names bone "${link}", which this rig does not declare`);
+      const other = stoppedBy.get(link);
+      if (other !== undefined) {
+        throw new CompileError(
+          `${who}: links[${k}] "${link}" is already stopped by stop "${other}" — one drawn link "${link}_d" and one clamp "${link}_clamp" per link, so a link is stopped once`,
+        );
+      }
+      stoppedBy.set(link, chain);
+      if (bone.from !== undefined) {
+        throw new CompileError(`${who}: links[${k}] "${link}" takes its place from the manifest ("from"), and a stop copies the link's stated x, y and rotation onto its drawn link — state them`);
+      }
+      if (bone.parent === undefined) {
+        throw new CompileError(`${who}: links[${k}] "${link}" is the skeleton's root, and a stop hangs its frame and its drawn link where the link hangs — a link has a parent`);
+      }
+    }
+    const against = entry.against;
+    if (typeof against !== 'string' || against.length === 0) {
+      throw new CompileError(`${who} needs "against" — the bone the point rides on, the leg the chain is held off`);
+    }
+    if (!authored.has(against)) throw new CompileError(`${who}: "against" names bone "${against}", which this rig does not declare`);
+    const at: unknown = entry.at;
+    if (at === undefined) {
+      throw new CompileError(`${who} states no "at" — the point on "${against}" the frame aims at, [x, y] in "${against}"'s local space; the compiler places no point of its own`);
+    }
+    if (!Array.isArray(at) || at.length !== 2 || !at.every((v): v is number => typeof v === 'number')) {
+      throw new CompileError(`${who} states "at" ${JSON.stringify(at)}; it is [x, y], two numbers in "${against}"'s local space`);
+    }
+    const range = (node: Record<string, unknown>, field: string): { inward: number; outward: number } => {
+      const out: Record<'inward' | 'outward', number> = { inward: 0, outward: 0 };
+      for (const end of ['inward', 'outward'] as const) {
+        const v = node[end];
+        if (typeof v !== 'number') {
+          throw new CompileError(
+            `${who} states no "${field}${end}" — degrees from the link's rest angle, counted positive away from "${against}"; the range is [inward, outward], and the compiler states neither end for you`,
+          );
+        }
+        out[end] = v;
+      }
+      if (out.inward > out.outward) {
+        throw new CompileError(
+          `${who}: "${field}inward" ${out.inward} is greater than "${field}outward" ${out.outward} — the range is [inward, outward] in degrees counted positive away from "${against}", and this one holds no angle`,
+        );
+      }
+      return out;
+    };
+    const first = range(entry, '');
+    const lowerRaw = entry.lower;
+    let lower: { inward: number; outward: number } | null = null;
+    if (links.length > 1) {
+      if (!isObj(lowerRaw)) {
+        throw new CompileError(`${who} states no "lower" — the range [inward, outward] each link below the first may turn through off its own rest bend; the chain has ${links.length - 1} of them`);
+      }
+      lower = range(lowerRaw, 'lower.');
+    } else if (lowerRaw !== undefined) {
+      throw new CompileError(`${who} states "lower" and its chain has one link — there is no link below the first for it to hold`);
+    }
+    stops.push({ who, chain, links, against, at: [at[0], at[1]], inward: first.inward, outward: first.outward, lower, names: stopNames(chain, links) });
+  }
+
+  // -- 2. the generated names are new -------------------------------------------
+  const generatedBones = new Map<string, string>();
+  const generatedConstraints = new Map<string, string>();
+  const authoredConstraints = new Set(constraints.filter(isObj).map((c) => `${String(c.type)} ${String(c.name)}`));
+  for (const stop of stops) {
+    const { names } = stop;
+    const lowerDrawn = names.drawn.slice(1);
+    for (const name of [names.frame, names.rel, names.drawn[0], ...lowerDrawn, names.point]) {
+      if (authored.has(name)) throw new CompileError(`${stop.who} generates bone "${name}", which this rig already declares — rename the bone, or the stop's "chain"`);
+      const by = generatedBones.get(name);
+      if (by !== undefined) throw new CompileError(`${stop.who} generates bone "${name}", which stop "${by}" generates too — rename one "chain"`);
+      generatedBones.set(name, stop.chain);
+    }
+    for (const [type, name] of [['ik', names.aim], ['transform', names.copy], ...names.clamp.map((c) => ['transform', c] as const)] as const) {
+      const key = `${type} ${name}`;
+      if (authoredConstraints.has(key)) throw new CompileError(`${stop.who} generates ${type} constraint "${name}", which this rig already declares — rename the constraint, or the stop's "chain"`);
+      const by = generatedConstraints.get(key);
+      if (by !== undefined) throw new CompileError(`${stop.who} generates ${type} constraint "${name}", which stop "${by}" generates too — rename one "chain"`);
+      generatedConstraints.set(key, stop.chain);
+    }
+  }
+
+  // -- 3. what swings each link ---------------------------------------------------
+  const writes = (c: unknown, bone: string): boolean => {
+    if (!isObj(c)) return false;
+    if (c.type === 'physics') return c.bone === bone;
+    if (c.type === 'ik' || c.type === 'transform' || c.type === 'path') return Array.isArray(c.bones) && c.bones.includes(bone);
+    return false;
+  };
+  const lastWriter = (stop: ReadStop, k: number): number => {
+    const link = stop.links[k];
+    let at = -1;
+    constraints.forEach((c, i) => {
+      if (writes(c, link)) at = i;
+    });
+    if (at < 0) {
+      throw new CompileError(
+        `${stop.who}: links[${k}] "${link}" is written by no constraint of this rig spec — a stop holds a link something swings (a physics, ik, transform or path constraint in "constraints"), and its copy and clamp run right after that. A physics constraint in the motion spec's table is emitted after every rig constraint, past the clamp; declare it here`,
+      );
+    }
+    return at;
+  };
+
+  // -- 4. the tree the expansion makes, by name ----------------------------------
+  const parentOf = new Map<string, string | undefined>();
+  for (const [name, bone] of authored) parentOf.set(name, bone.parent);
+  for (const stop of stops) {
+    const { names, links } = stop;
+    parentOf.set(names.frame, authored.get(links[0])?.parent);
+    parentOf.set(names.rel, names.frame);
+    parentOf.set(names.drawn[0], names.frame);
+    for (let k = 1; k < links.length; k++) parentOf.set(names.drawn[k], authored.get(links[k])?.parent);
+    parentOf.set(names.point, stop.against);
+  }
+  const ancestry = (name: string): string[] => {
+    const out: string[] = [];
+    const seen = new Set<string>();
+    for (let at = parentOf.get(name); at !== undefined && !seen.has(at); at = parentOf.get(at)) {
+      seen.add(at);
+      out.push(at);
+    }
+    return out;
+  };
+  for (const stop of stops) {
+    const { names, links } = stop;
+    for (let k = 1; k < links.length; k++) {
+      if (!ancestry(links[k]).includes(names.drawn[k - 1])) {
+        throw new CompileError(
+          `${stop.who}: links[${k}] "${links[k]}" does not hang below "${names.drawn[k - 1]}", the drawn link of links[${k - 1}] — a chain's next link hangs from the drawn link above it, so the clamp that holds that one carries this one; parent it there`,
+        );
+      }
+    }
+    const held = new Set([names.frame, names.rel, ...names.drawn, ...links]);
+    const under = [stop.against, ...ancestry(stop.against)].find((b) => held.has(b));
+    if (under !== undefined) {
+      throw new CompileError(`${stop.who}: "against" "${stop.against}" hangs below "${under}", which the stop moves — the point would swing with the chain it holds off; name the leg`);
+    }
+  }
+
+  // -- 5. the angles, off the setup pose as stated -------------------------------
+  const generated = new Map<string, RigBone>();
+  const known = (name: string): RigBone | undefined => authored.get(name) ?? generated.get(name);
+  const before = new Map<number, RigConstraint[]>();
+  const after = new Map<number, RigConstraint[]>();
+  const appended: RigConstraint[] = [];
+  const queue = (map: Map<number, RigConstraint[]>, at: number, c: RigConstraint): void => {
+    if (plant.appendConstraints) appended.push(c);
+    else map.set(at, [...(map.get(at) ?? []), c]);
+  };
+  const conformal = (m: BoneTransform): boolean => {
+    const scale = Math.max(Math.abs(m.a), Math.abs(m.b), Math.abs(m.c), Math.abs(m.d));
+    return m.a * m.d - m.b * m.c > 0 && Math.abs(m.a - m.d) <= 1e-9 * scale && Math.abs(m.b + m.c) <= 1e-9 * scale;
+  };
+  const clampOf = (name: string, source: string, target: string, lo: number, hi: number): RigTransformConstraint => ({
+    name,
+    type: 'transform',
+    source,
+    bones: [target],
+    localSource: true,
+    localTarget: true,
+    clamp: true,
+    properties: { rotate: { offset: lo, to: { rotate: { offset: lo, max: hi, scale: 1 } } } },
+    mixRotate: 1,
+  });
+  const bounds = (stop: ReadStop, rest: number, sign: number, range: { inward: number; outward: number }, field: string, what: string): [number, number] => {
+    const a = rest - sign * range.outward;
+    const b = rest - sign * range.inward;
+    for (const [end, value] of [['outward', a], ['inward', b]] as const) {
+      if (Math.abs(value) > BOUND) {
+        throw new CompileError(
+          `${stop.who}: "${field}${end}" ${range[end]} puts ${what}'s bound at ${value}°, past ±${BOUND}° — the clamp reads a local rotation in (-180, 180], so a bound past it is never reached and the range it states is not the one that holds`,
+        );
+      }
+    }
+    return [Math.min(a, b), Math.max(a, b)];
+  };
+
+  for (const stop of stops) {
+    const { names, links, who } = stop;
+    const link = authored.get(links[0]) as RigBone;
+    const parent = link.parent as string;
+    // The bones the angles are read through, root first: the first link's
+    // ancestry and the leg's, each parent before its child.
+    const chain: RigBone[] = [];
+    const listed = new Set<string>();
+    for (const tip of [links[0], stop.against]) {
+      for (const name of [...ancestry(tip).reverse(), tip]) {
+        if (listed.has(name)) continue;
+        const bone = known(name);
+        if (bone === undefined) {
+          throw new CompileError(`${who}: "${tip}" hangs below "${name}", which a later stop generates — declare that stop first, so its angles are known when this one is read`);
+        }
+        if (bone.from !== undefined) {
+          throw new CompileError(`${who}: "${name}" takes its place from the manifest ("from"), and a stop's angles are read off the setup pose this rig spec states — state its x, y and rotation`);
+        }
+        listed.add(name);
+        chain.push(bone);
+      }
+    }
+    const frames = computeExactFrameTransforms(chain);
+    const parentFrame = frames.get(parent) as BoneTransform;
+    if (!conformal(parentFrame)) {
+      throw new CompileError(
+        `${who}: "${parent}", where the frame hangs, is scaled unevenly, sheared or reflected at the setup pose — the frame's angles add to its parent's only through a rotation and an even scale, and inward is a turn's sense`,
+      );
+    }
+    for (let k = 1; k < links.length; k++) {
+      for (let at = authored.get(links[k])?.parent; at !== undefined && at !== names.drawn[k - 1]; at = parentOf.get(at)) {
+        const bone = authored.get(at);
+        if (bone === undefined) break;
+        const plain = (bone.scaleX ?? 1) === (bone.scaleY ?? 1) && (bone.scaleX ?? 1) > 0 && (bone.shearX ?? 0) === 0 && (bone.shearY ?? 0) === 0 && (bone.inherit ?? 'normal') === 'normal';
+        if (!plain) {
+          throw new CompileError(
+            `${who}: "${at}", between links[${k}] "${links[k]}" and the drawn link above it, is scaled unevenly, sheared, reflected or inherits other than normally — a lower clamp reads the link's turn in its parent, and inward is a turn's sense`,
+          );
+        }
+      }
+    }
+    const linkFrame = frames.get(links[0]) as BoneTransform;
+    const point = toWorld(frames.get(stop.against) as BoneTransform, stop.at[0], stop.at[1]);
+    const target = plant.aimAtAgainst ? [(frames.get(stop.against) as BoneTransform).worldX, (frames.get(stop.against) as BoneTransform).worldY] : point;
+    const dx = target[0] - linkFrame.worldX;
+    const dy = target[1] - linkFrame.worldY;
+    if (dx === 0 && dy === 0) {
+      throw new CompileError(`${who}: "at" [${stop.at.join(', ')}] on "${stop.against}" sits on the root of "${links[0]}" at the setup pose — the frame aims from the root at the point, and there is no direction to a point it stands on`);
+    }
+    const aim = directionDegrees(dx, dy);
+    // Each angle is brought into (-180, 180] by one whole turn at most, so a
+    // link and an aim already in range subtract with no turn added and taken
+    // away again — the rest angle is the plain difference an author computes.
+    const rest = halfTurn(halfTurn(linkFrame.worldRotation) - aim);
+    if (rest === 0) {
+      throw new CompileError(
+        `${who}: "at" [${stop.at.join(', ')}] on "${stop.against}" lies on "${links[0]}"'s own line at the setup pose — inward is the turn from the link toward the point, and a point on the link's line has no side`,
+      );
+    }
+    // Inward turns the link toward the aim line: counter-clockwise when the link
+    // lies clockwise of it (a negative rest angle), clockwise otherwise.
+    const sign = (rest < 0 ? 1 : -1) * (plant.swapRange ? -1 : 1);
+    const [lo, hi] = bounds(stop, rest, sign, stop, '', `"${names.drawn[0]}"`);
+
+    const frame: RigBone = { name: names.frame, parent };
+    if (link.x !== undefined) frame.x = link.x;
+    if (link.y !== undefined) frame.y = link.y;
+    if (link.length !== undefined) frame.length = link.length;
+    frame.rotation = localDirectionDegrees(parentFrame, dx, dy);
+    const onFrame = (name: string): RigBone => {
+      const bone: RigBone = { name, parent: names.frame };
+      if (link.length !== undefined) bone.length = link.length;
+      bone.rotation = rest;
+      return bone;
+    };
+    generated.set(names.frame, frame);
+    generated.set(names.rel, onFrame(names.rel));
+    generated.set(names.drawn[0], onFrame(names.drawn[0]));
+    for (let k = 1; k < links.length; k++) {
+      const source = authored.get(links[k]) as RigBone;
+      const twin: RigBone = { name: names.drawn[k], parent: source.parent };
+      for (const field of TWIN_FIELDS) {
+        if (source[field] !== undefined) Object.assign(twin, { [field]: source[field] });
+      }
+      generated.set(names.drawn[k], twin);
+    }
+    generated.set(names.point, { name: names.point, parent: stop.against, x: stop.at[0], y: stop.at[1] });
+
+    const firstWriter = lastWriter(stop, 0);
+    const aimAt: RigIkConstraint = { name: names.aim, type: 'ik', bones: [names.frame], target: plant.aimAtAgainst ? stop.against : names.point, mix: 1 };
+    queue(before, firstWriter, aimAt);
+    queue(after, firstWriter, { name: names.copy, type: 'transform', source: links[0], bones: [names.rel], properties: { rotate: { to: { rotate: {} } } }, mixRotate: 1 });
+    queue(after, firstWriter, clampOf(names.clamp[0], names.rel, names.drawn[0], lo, hi));
+    for (let k = 1; k < links.length; k++) {
+      const source = authored.get(links[k]) as RigBone;
+      const [l, h] = bounds(stop, source.rotation ?? 0, sign, stop.lower as { inward: number; outward: number }, 'lower.', `"${names.drawn[k]}"`);
+      queue(after, lastWriter(stop, k), clampOf(names.clamp[k], links[k], names.drawn[k], l, h));
+    }
+  }
+
+  // -- 6. spliced in -------------------------------------------------------------
+  const bones: RigBone[] = [];
+  const firstOf = new Map<string, ReadStop>();
+  const lowerOf = new Map<string, { stop: ReadStop; k: number }>();
+  for (const stop of stops) {
+    firstOf.set(stop.links[0], stop);
+    for (let k = 1; k < stop.links.length; k++) lowerOf.set(stop.links[k], { stop, k });
+  }
+  const take = (name: string): RigBone => generated.get(name) as RigBone;
+  for (const bone of spec.bones) {
+    const first = isObj(bone) ? firstOf.get(bone.name) : undefined;
+    if (first !== undefined) bones.push(take(first.names.frame));
+    bones.push(bone);
+    if (first !== undefined) bones.push(take(first.names.rel), take(first.names.drawn[0]));
+    const lower = isObj(bone) ? lowerOf.get(bone.name) : undefined;
+    if (lower !== undefined) bones.push(take(lower.stop.names.drawn[lower.k]));
+  }
+  for (const stop of stops) bones.push(take(stop.names.point));
+  const out: RigConstraint[] = [];
+  constraints.forEach((c, i) => {
+    out.push(...(before.get(i) ?? []), c, ...(after.get(i) ?? []));
+  });
+  out.push(...appended);
+  return { ...spec, bones, constraints: out };
+}

package/src/transform.ts

@@ -287,6 +287,26 @@ export function toWorld(m: BoneTransform, localX: number, localY: number): [numb
   return [m.a * localX + m.b * localY + m.worldX, m.c * localX + m.d * localY + m.worldY];
 }
 
+/**
+ * The direction of a displacement, in degrees CCW from +x, y up, in (-180, 180]
+ * — radians to degrees by the exact frame's division (`EXACT_FRAME_ARITHMETIC`),
+ * so an angle read here off `computeExactFrameTransforms` and that frame's own
+ * `worldRotation` are one arithmetic. Not rounded, for `toWorld`'s reason.
+ */
+export function directionDegrees(dx: number, dy: number): number {
+  return EXACT_FRAME_ARITHMETIC.degreesOf(Math.atan2(dy, dx));
+}
+
+/**
+ * A world displacement's direction in a bone's local space — the rotation a
+ * child of that bone states to point along it. `toBoneLocalVector`, then
+ * `directionDegrees`; a stop's frame (`src/stop.ts`) is aimed with it.
+ */
+export function localDirectionDegrees(m: BoneTransform, worldDX: number, worldDY: number): number {
+  const [lx, ly] = toBoneLocalVector(m, worldDX, worldDY);
+  return directionDegrees(lx, ly);
+}
+
 /**
  * Normalise degrees into (-180, 180], which is how an editor shows a rotation.
  *

package/src/viewportpin.ts

@@ -0,0 +1,168 @@
+/**
+ * A render's box given rather than fitted — `rigc render --viewport` and
+ * `rigc render --viewport-from` (issue #1414) — and what the frames leave out of it.
+ *
+ * ⭐ **Why a box is given.** `render` fits its box to the rig it draws, so two
+ * candidates — a rig before and after a polish — land on two grids (377×480 against
+ * 385×480 on the run that asked for this), and a comparison of their pixels needs a
+ * transform written by hand. A given box puts both on one grid: the same world box
+ * and the same pixel size, so a world point lands on the same pixel in both.
+ *
+ * Two ways to give it, and only two:
+ *
+ * - `--viewport <x,y,w,h>` — a world box, y up, `x,y` its bottom-left corner: the
+ *   spelling `check --viewport` and `inspect --viewport` already take, and the
+ *   numbers `frames.json`'s `viewport` records. Its pixel size follows from `--max`
+ *   as a fitted box's does.
+ * - `--viewport-from <frames.json | render root>` — an earlier render's grid exactly:
+ *   its box, its scale and its pixel size as that `frames.json` records them, so the
+ *   second render is on the first one's pixels to the bit. `--max` is refused beside
+ *   it, because the file already fixes the pixel size.
+ *
+ * ⚠️ **Nothing is cropped silently.** A given box can leave part of the rig out,
+ * which a fitted box — measured over the rig's own poses at 60 fps and padded —
+ * is built not to. Each frame is the box — what lies past it is not
+ * drawn — so every slot whose drawn geometry reaches past it is named, by set and
+ * frame, with how far and on which side, and `frames.json` records the same list
+ * under `pinned` (`outsideViewport`).
+ *
+ * Pure: no clock, no randomness, no runtime.
+ */
+import { indexRuns } from './folds.ts';
+import { FRAMES_SPEC, type Frame, type PinnedViewport, type Viewport, unionBounds, viewportOfSize } from './render_shared.ts';
+
+/** A given box that cannot be used — said by name. */
+export class ViewportError extends Error {}
+
+/** `--viewport`'s value: four numbers, `x,y,w,h`, the world box, y up — refused by name otherwise. Shared by `render`, `check` and `inspect`. */
+export function readViewportBox(raw: string): { x: number; y: number; width: number; height: number } {
+  const parts = raw.split(',').map((s) => Number(s.trim()));
+  if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
+    throw new ViewportError('--viewport takes four numbers: <x>,<y>,<width>,<height> — the world box, y up');
+  }
+  if (parts[2] <= 0 || parts[3] <= 0) throw new ViewportError('--viewport width and height must be positive');
+  return { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
+}
+
+/**
+ * The grid a `frames.json` records — `value` is the parsed file, `where` its path —
+ * as the viewport a second render draws on: the box, the scale and the pixel size
+ * exactly as written (`viewportOfSize`, the reading `check` takes of the same
+ * block). Refused naming the field and its value where the file is not a frame
+ * set's sidecar or its `viewport` is not a grid.
+ */
+export function viewportOfFramesFile(value: unknown, where: string): Viewport {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new ViewportError(`--viewport-from ${where}: the file is not a JSON object`);
+  const file = value as Record<string, unknown>;
+  if (file.spec !== FRAMES_SPEC) {
+    throw new ViewportError(`--viewport-from ${where}: spec is ${JSON.stringify(file.spec)}, and the grid is read off a frame set's ${FRAMES_SPEC} sidecar — the frames.json \`render\` writes`);
+  }
+  const v = file.viewport;
+  if (typeof v !== 'object' || v === null || Array.isArray(v)) throw new ViewportError(`--viewport-from ${where}: no viewport object`);
+  const box = v as Record<string, unknown>;
+  const field = (name: string, rule: 'finite' | 'positive' | 'pixels'): number => {
+    const n = box[name];
+    const ok =
+      typeof n === 'number' &&
+      Number.isFinite(n) &&
+      (rule === 'finite' || n > 0) &&
+      (rule !== 'pixels' || Number.isInteger(n));
+    if (!ok) {
+      const need = rule === 'finite' ? 'a finite number' : rule === 'positive' ? 'a number above 0' : 'a whole number of pixels above 0';
+      throw new ViewportError(`--viewport-from ${where}: viewport.${name} is ${JSON.stringify(n) ?? 'absent'}; it must be ${need}`);
+    }
+    return n as number;
+  };
+  return viewportOfSize(
+    field('x', 'finite'),
+    field('y', 'finite'),
+    field('width', 'positive'),
+    field('height', 'positive'),
+    field('scale', 'positive'),
+    field('pixelWidth', 'pixels'),
+    field('pixelHeight', 'pixels'),
+  );
+}
+
+/** The four sides of a box, world terms, y up, in the order a line names them. */
+export const SIDES = ['left', 'right', 'bottom', 'top'] as const;
+export type Side = (typeof SIDES)[number];
+
+/** One slot that reaches past the box on one set: the frames, how far at most (world units) and on which sides. */
+export interface OutsideReading {
+  set: string;
+  slot: string;
+  frames: number[];
+  /** The farthest any of its vertices reaches past the box, on any frame and side, world units. */
+  most: number;
+  sides: Side[];
+}
+
+/**
+ * A wrong reading the suite plants to see its control go red (issue #1414):
+ * `ownBox` measures each set against the box its own frames fill rather than the
+ * given one — a reading that ignores the viewport.
+ */
+export interface OutsidePlant {
+  ownBox?: true;
+}
+
+/**
+ * Every slot whose drawn geometry reaches past `viewport` — a piece's posed
+ * vertex strictly outside the box, as the framing measures a piece — per set in
+ * `sets`' order, the slots in the order they first reach past it. Read off the
+ * frames as drawn: a slot `--slot`/`--hide` leaves out draws no piece and is not
+ * read, and a clip's cut is what is read.
+ */
+export function outsideViewport(sets: ReadonlyMap<string, readonly Frame[]>, viewport: Viewport, plant: OutsidePlant = {}): OutsideReading[] {
+  const out: OutsideReading[] = [];
+  for (const [set, frames] of sets) {
+    const box = plant.ownBox === true ? unionBounds([[...frames]]) : viewport;
+    const bySlot = new Map<string, { frames: Set<number>; most: number; sides: Set<Side> }>();
+    for (const frame of frames) {
+      for (const piece of frame.pieces) {
+        for (let i = 0; i + 1 < piece.world.length; i += 2) {
+          const x = piece.world[i];
+          const y = piece.world[i + 1];
+          const past: Array<[Side, number]> = [
+            ['left', box.minX - x],
+            ['right', x - box.maxX],
+            ['bottom', box.minY - y],
+            ['top', y - box.maxY],
+          ];
+          for (const [side, by] of past) {
+            if (!(by > 0)) continue;
+            let slot = bySlot.get(piece.slot);
+            if (slot === undefined) {
+              slot = { frames: new Set(), most: 0, sides: new Set() };
+              bySlot.set(piece.slot, slot);
+            }
+            slot.frames.add(frame.index);
+            slot.most = Math.max(slot.most, by);
+            slot.sides.add(side);
+          }
+        }
+      }
+    }
+    for (const [slot, read] of bySlot) {
+      out.push({ set, slot, frames: [...read.frames].sort((a, b) => a - b), most: read.most, sides: SIDES.filter((s) => read.sides.has(s)) });
+    }
+  }
+  return out;
+}
+
+/** `frames.json`'s `pinned` record for a given box and its reading. */
+export function pinnedRecord(by: PinnedViewport['by'], outside: readonly OutsideReading[]): PinnedViewport {
+  return { by, outside: outside.map(({ set, slot, frames }) => ({ set, slot, frames })) };
+}
+
+/**
+ * The printed line for one slot past the box: the set, the slot, the frames, how
+ * far at most and on which sides — and what happens to what lies past it.
+ */
+export function outsideLine(r: OutsideReading, fps: number): string {
+  return (
+    `${JSON.stringify(r.set)}: slot ${JSON.stringify(r.slot)} reaches past the box on ${r.frames.length} frame(s) [${indexRuns(r.frames)}] at ${fps} fps, ` +
+    `by up to ${r.most.toFixed(2)} units (${r.sides.join(', ')}) — what lies past the box is not drawn: each frame is the box`
+  );
+}