@rig-c/core 2.85.0 → 2.86.0

package/README.md

@@ -588,7 +588,7 @@ material, like the gallery: a clone runs them.
 | `ingest` | Read a skeleton back into specs. [`ingest` in the CLI reference](docs/AUTHORING.md#cmd-ingest) |
 | `split` | Separate disconnected mesh pieces. [`split` in the CLI reference](docs/AUTHORING.md#cmd-split) |
 | `explain` | Print the compiled rig as a table. [`explain` in the CLI reference](docs/AUTHORING.md#cmd-explain) |
-| `render` | Write PNG frames and a contact sheet. [`render` in the CLI reference](docs/AUTHORING.md#cmd-render) |
+| `render` | Write PNG frames and a contact sheet, or a named dial’s geometry-only parallax reading. [`render` in the CLI reference](docs/AUTHORING.md#cmd-render) |
 | `preview` | Write a playable HTML preview. [`preview` in the CLI reference](docs/AUTHORING.md#cmd-preview) |
 | `vote` | Make a ballot and record its answer. [`vote` in the CLI reference](docs/AUTHORING.md#cmd-vote) |
 | `pose` | Read part placements from a picture. [`pose` in the CLI reference](docs/AUTHORING.md#cmd-pose) |

package/docs/AUTHORING.md

@@ -378,6 +378,7 @@ What the flags mean:
 | `--show`, `--dim`, `--at`, `--zoom` | `inspect` only — what it draws, whether the art is faded, which times of `--animation` it poses and the bone, slot or folds it frames to; §13 says each, with the refusals |
 | `--geometry` | `render` only: also write a `geometry.json` into each frame directory — per frame, every bone's world transform and every slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry and topology, on the frames' own grid and viewport. Every other file is byte for byte what the render writes without it. Refused with `--slot`/`--hide`, because the geometry is the whole pose whatever is drawn — **§8.2** |
 | `--extremes-only` | `render` only: imply `--extremes`, but write only `extremes.json` and readable `extremes.png` with the same bytes. Pose the same grid; rasterize only the setup/min/max pictures used by the plate. No ordinary frame PNGs, contact sheet or `frames.json`. Takes no `--sheet`, `--sheet-format`, `--page-edges`, `--geometry`, `--folds`, `--pass-through`, `--seam`, `--overlaps` or `--angle-range`; drop the named flag or use `--extremes` instead — **§8.11** |
+| `--parallax` | `render` only: a named slider dial, through the core poser. Write `parallax.json` and a readable `parallax.png` into `--out` on a fixed 9-value grid. This is a separate dial render mode, with `--skin`, `--max`, `--candidate`, `--atlas` and `--poser core`; it takes no animation, fps, subset, other diagnostic, sheet, environment or viewport flag. A missing dial is refused by name; unavailable fits report SKIP, never a pass — **§8.12** |
 | `--extremes` | `render` only: add `extremes.json` and an `EXTREMES` line per set; a moving set with comparable geometry and readable images also gets a native six-panel `extremes.png`: setup, geometry-pair min/max and three premultiplied RGBA diffs with a legend. Per-channel extrema are independent of that geometry pair; valid channels survive geometry/image SKIPs, and channel refusals are named separately. Still or uncomparable geometry is a named SKIP, with no invented pair or PNG; observation failures do not change a successful render's exit status. Supports `--slot`/`--hide` on both posers, on the whole rig's viewport. Without the flag, no extremes observations are added — **§8.11** |
 | `--folds` | `render` only: also read which mesh triangles **fold** — turn over against the setup pose — and write a `folds.json` into each frame directory: per mesh, the frames with a folded triangle, the worst frame's count and which triangles, by index, with their world box and setup-pose area. One printed line per mesh that folds; a triangle degenerate or inverted at the setup pose is said once and never counted. A reading, not a gate. Every other file is byte for byte what the render writes without it, `geometry.json` included. Refused with `--slot`/`--hide`, for `--geometry`'s reason — **§8.3** |
 | `--pass-through` | `render` only: `<cloth>:<leg>[,<cloth>:<leg>…]` — also read where each cloth slot **passes through** its leg slot, and write a `pass-through.json` into each frame directory: the frames where the cloth draws over the leg and its drawn side lies inside the leg's drawn outline by 2 steps or more, each with the depth and the world box. One printed line per pair, and one per frame that passes through. The first name must draw over the second for a frame to be read — the declared order, never both. A reading, not a gate. Every other file is byte for byte what the render writes without it. An unknown slot, a slot that draws on no frame, a malformed list and a pair named twice are refused by name, and so is `--slot`/`--hide` beside it — **§8.5** |
@@ -9734,6 +9735,78 @@ Without `--extremes` the existing frames and files are unchanged. The flag adds
 its observations alongside them. A SKIP removes a stale `extremes.png` for that
 set so an earlier pair cannot masquerade as the current reading.
 
+### 8.12 Geometry of a value-driven turn — `render --parallax <dial>`
+
+```sh
+bun cli_core.ts render --candidate gallery/look/build --parallax yaw --max 640 --out parallax/
+```
+
+This reads a **slider constraint name**, not its animation or driving bone name.
+It writes `parallax.json` (`rigc-parallax/1`) and, when the images and extremes
+are readable, `parallax.png` at the output root. Use a dedicated output directory;
+no ordinary frames or `frames.json` are written in this mode. An unavailable
+picture removes an earlier `parallax.png` and leaves a named JSON SKIP. Ordinary
+render without the flag keeps its files and posing path unchanged.
+
+On current compiled models, depth coherence and near/far travel always report
+SKIP: this adapter supplies neither per-vertex depth nor a world projection axis.
+Geometry residuals and layer spread are still read from the posed vertices.
+
+Only a rigc build with a matching `skeleton.model.json`, posed by the core, is
+accepted; a Spine export, mismatched model or `--poser spine` is refused. Keep the
+model beside the build, or rebuild it. A missing slider is refused by name with
+the available slider names. `--animation`, `--fps`, subset, other diagnostics,
+sheet, environment and viewport flags are refused together rather than ignored.
+`--skin` selects the same skin as ordinary render; `--max` sizes the picture.
+
+The setup pose and nine evenly spaced dial values are independent reset poses,
+not a track playing the lookup animation. Other inputs stay at setup; all
+constraints are applied, and other sliders may respond to the driven bone or its
+constraint chain. Physics is reset at every value. A bone-driven dial uses `from..max` when the model states
+`max`; without it the last animation time is inverted through the mapping. A
+bone-less slider uses `0..duration`, in seconds. The grid is numerically ascending even for a negative mapping; the declared
+endpoints remain in `sampling.range`. The JSON states the exact grid,
+requested values, actual applied times, drive field and setup value. The core's
+existing dial override preserves the bones' setup values for additive/nonadditive
+blends. Local properties are driven directly; a world property is solved through
+a responsive local field and verified against the actual property and mapped
+time. Unreachable values (including world rotation wrapping), inactive sliders
+or a zero/nonfinite range are named; no successful drive is invented.
+
+Every **sample is fitted separately** from setup positions to that sample's
+positions. Fitting displacements as though they were positions, or pooling
+different dial values into one map, is a different question and is not done.
+
+| JSON reading | Definition and unavailable cases |
+| --- | --- |
+| `samples[].meshes[].affine` | Forward geometric least squares, normalized with independent centroids and isotropic RMS scales, solved by reorthogonalized QR. World residual RMS divided by world RMS setup-to-sample motion over the same vertices. |
+| `homography` | A normalized inhomogeneous linear initializer and an affine initializer, each refined for up to 80 damped geometric least-squares iterations. Report the smallest finite **forward geometric** residual found, not the algebraic initializer objective. This is a local numerical fit, **not a certified global optimum**. |
+| `layers.spread` | One affine fit over the whole comparable rig, regions and meshes including stationary layers. Compute each layer's mean residual vector, then the unweighted RMS distance of those vectors from their mean, in world px. `ratio` divides by the whole fit's RMS motion. One layer is insufficient. Dense meshes influence the whole fit more; the spread itself weights layers equally. |
+| `depth` | Signed Spearman with average ranks between declared per-vertex depth and setup-to-sample motion projected onto a declared world turn axis. Opposite extrema can reverse the sign. Constant depth or constant projected motion has undefined correlation. Near/far travel means RMS travel of vertices at the maximum/minimum declared depth divided by absolute dial distance from setup, in world px per dial unit. A generic slider declares no turn axis. Current compiled models retain depth summaries and provenance, **not vertex depth samples**, so these quantities are explicitly SKIP; neither a summary range nor motion is used to reconstruct depth. |
+
+Meshes appearing without setup correspondence are named SKIPs, not omitted.
+No vertices, unequal vertex counts, missing attachments, singular maps, deficient
+fit rank and nonfinite coordinates report named SKIPs. A stationary or unresolved
+RMS-motion denominator reports SKIP with a null ratio. Affine fits with at most
+three correspondences and homographies with at most four are saturated, so their
+ratios are unavailable: four nondegenerate points can fit arbitrary motion, and
+zero there cannot test paper. Numeric tolerance is a resolution check, never a
+quality threshold. `READ` means a measurement was obtained; there is no PASS.
+
+The picture has six panels at one fitted pixel scale: setup, dial minimum, dial
+maximum, premultiplied RGBA absolute max/min difference, and two affine-residual
+heat maps at original mesh vertices. Blue is zero, red is the largest world
+residual across those two maps, with that value in the legend; unavailable
+vertices stay dark. An empty or unreadable picture never supplies a score.
+
+**This cannot certify volume.** A rigid flat sheet under orthographic projection
+is affine; a perspective sheet is projective. But sloped depth can also be affine,
+and an articulated collection of flat surfaces need not share a map. Nonlinear
+2D warps can produce large residuals without depth. The reading measures geometry,
+not draw order, colour, occlusion, tears, ghost lines or rendered optical flow.
+Compare the two fits, the per-sample curves and an explicit control before
+attributing residual to relief. No assertion, pass mark or build gate is added.
+
 ## 9. Checking against the frames — `rigc check`
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.85.0",
+  "version": "2.86.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": {

package/src/cli/core_commands.ts

@@ -1,3 +1,4 @@
+import { sampleParallax, parallaxPlate } from '../parallax_render.ts';
 import { textureScaleReading, textureScaleLines, TEXTURE_SCALE_FPS } from '../texture_scale.ts';
 import { extremesOf, extremesText, extremesPlate, extremesLine, extremesRefusal } from '../extremes.ts';
 /**
@@ -776,6 +777,36 @@ export function cmdRender(flags: Record<string, string>): void {
     { skeleton: skeletonPath, atlas: atlasPath },
     posersAsked(flags),
   );
+  if (flags.parallax !== undefined) {
+    for (const flag of ['animation', 'fps', 'slot', 'hide', 'geometry', 'folds', 'extremes', 'extremes-only', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'viewport', 'viewport-from']) {
+      if (flags[flag] !== undefined) throw new UsageError(`--parallax takes no --${flag}: it samples one named dial on its own 9-value grid; drop --${flag} or run ordinary render separately`);
+    }
+    if (flags.poser !== undefined && flags.poser !== 'core') throw new UsageError('--parallax requires --poser core: it reads only a rigc compiled model');
+    const modelText = modelTextBeside(skeletonPath, skeletonText);
+    if (modelText === undefined || choice.core === null) throw new UsageError('--parallax requires a matching skeleton.model.json and the core poser; rebuild the candidate and keep its model beside skeleton.json');
+    const selectedSkin = readSkinFlag(flags, [...facts.skins]);
+    let result: ReturnType<typeof sampleParallax>;
+    try { result = sampleParallax(modelText, atlasText ?? '', flags.parallax, selectedSkin); }
+    catch (error) {
+      if (error instanceof CoreInputError) throw new UsageError(error.message);
+      throw error;
+    }
+    let picture: Plate | null = null;
+    try {
+      picture = parallaxPlate(result, pages, maxSide);
+      if (picture !== null) result.reading.picture = { status: 'READ', reason: 'setup, dial extremes, diff and affine residual heat maps', file: 'parallax.png' };
+    } catch (error) { result.reading.picture.reason = `picture unavailable: ${error instanceof Error ? error.message : String(error)}`; }
+    mkdirSync(outRoot, { recursive: true });
+    writeFileSync(join(outRoot, 'parallax.json'), JSON.stringify(result.reading, null, 2) + '\n');
+    if (picture !== null) picture.writePng(join(outRoot, 'parallax.png'));
+    else rmSync(join(outRoot, 'parallax.png'), { force: true });
+    console.log(`  ..    poser core — named dial ${JSON.stringify(flags.parallax)}, independent reset poses`);
+    console.log(`  ..    PARALLAX ${JSON.stringify(flags.parallax)} ${result.reading.status}: ${result.reading.reason} -> ${outRoot}`);
+    for (const sample of result.reading.samples) {
+      for (const mesh of sample.meshes) console.log(`  ..    PARALLAX ${JSON.stringify(mesh.slot + '/' + mesh.attachment)} dial=${sample.value} affine=${mesh.affine.ratio ?? 'SKIP'} homography=${mesh.homography.ratio ?? 'SKIP'}`);
+    }
+    return;
+  }
   const only = readAnimationFlag(flags, [...facts.animations]);
   const skin = readSkinFlag(flags, [...facts.skins]);
   const subset = readSlotSubsetFlags(flags, facts, skin);

package/src/cli/shared.ts

@@ -1066,6 +1066,7 @@ const FLAG_MEANINGS: Record<string, string> = {
     'Each frame with a moving pair also gets an outline plate, overlaps-f<NNNN>.png: every slot in a moving pair as its contour in its own ' +
     'colour, dashed where a slot drawn later covers it, named at its top. The render reports what was drawn; who should be in front is the ' +
     "author's, and the draw-order key in the motion spec is the remedy. A reading, not a gate. Not with --slot/--hide",
+  parallax: 'read one named slider dial through the core poser on 9 evenly spaced values: parallax.json plus setup/extreme/diff/affine-residual heat-map parallax.png; geometry only, no assertion or pass threshold. A separate dial render mode; takes no animation, fps, other diagnostics, sheet, subset, environment or viewport flags',
   'extremes-only': 'write only extremes.json and readable extremes.png per set, with the same posed grid and bytes as --extremes; no ordinary frame PNGs, contact.png or frames.json. Implies --extremes; takes no --sheet, --sheet-format, --page-edges, --geometry, --folds, --pass-through, --seam, --overlaps or --angle-range',
   extremes: 'also write extremes.json and a native six-panel extremes.png per set: setup, geometry-pair min/max and premultiplied RGBA diffs, with a legend. Per-channel extrema are recorded separately and valid channels survive geometry/image SKIPs; channel refusals are named separately. Still geometry reports SKIP; a reading, not a gate. Attachment identity/count changes record a named SKIP without changing render exit; supports --slot/--hide on both posers',
   seam:
@@ -1297,6 +1298,7 @@ const FLAG_VALUES: Record<string, string> = {
   'pass-through': '<cloth>:<leg>[,<cloth>:<leg>…]',
   seam: '<slot>:<slot>[,<slot>:<slot>…]',
   'angle-range': '<bone>:<relative-to>[,…]',
+  parallax: '<dial>',
   'sheet-format': 'json-hash',
   'viewport-from': '<frames.json|dir>',
   reference: '<dir|skeleton.json>',
@@ -1763,12 +1765,13 @@ export const COMMANDS: CommandDoc[] = [
       'rigc render … --environment <schedule.json>   (the wind and gravity the physics answers, in time)',
       'rigc render … --pass-through <cloth>:<leg>[,…]   (the frames where a cloth drawn over a leg passes through it)',
       'rigc render … --seam <slot>:<slot>[,…]   (joint gaps, visible ghosts and each named slot’s background exposure)',
+      'rigc render … --parallax <dial>   (geometry reading on the named dial, model/core only)',
       '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', 'extremes', 'extremes-only', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'extremes', 'extremes-only', 'parallax', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'poser', 'out'],
     overrides: {
       'page-edges': {
         meaning:

package/src/core/hooks.ts

@@ -104,6 +104,8 @@ export type DialOverride = { bone: string; field: DialBoneField; value: number }
 
 /** A dial pose, and its two readings (the header's *A dial*). */
 export interface CoreDialPose extends CoreSurveyPose {
+  /** Complete posed slot order, including slots without a shown attachment. */
+  drawOrder: readonly string[];
   /** The slider's property read off its bone, or `null` on a bone-less slider. */
   read: number | null;
   applied: number;
@@ -167,8 +169,8 @@ export function poseDial(doc: CompiledDocument, override: DialOverride, slider:
   const view = overridden(doc, override);
   const record = sliderRecordOf(view, slider);
   const posed = poseSetup(view, RAW_PLANT, freshStepContext());
-  const missing = posed.absent.filter(([b]) => b === 'setup.bones' || b === 'setup.slots');
-  if (missing.length > 0 || posed.world === null || posed.setup.slots === null) throw new CoreInputError(`the dial pose leaves ${missing.map(([b, w]) => `${b} out (${w})`).join('; ') || 'the bones out'}`);
+  const missing = posed.absent.filter(([b]) => b === 'setup.bones' || b === 'setup.slots' || b === 'setup.drawOrder');
+  if (missing.length > 0 || posed.world === null || posed.setup.slots === null || posed.setup.drawOrder === null) throw new CoreInputError(`the dial pose leaves ${missing.map(([b, w]) => `${b} out (${w})`).join('; ') || 'the bones out'}`);
   if (posed.shown === null) throw new CoreInputError('the dial pose leaves the shown records out (a timeline keys a placeholder several skins fill)');
   // The solver's last state, for the reading: the same pass `poseSetup` ran, with its `settled` sink.
   const active = activeBones(view);
@@ -187,7 +189,7 @@ export function poseDial(doc: CompiledDocument, override: DialOverride, slider:
   }
   const read = record.bone === null ? null : sourceValue(settled, { source: record.bone, localSource: record.local, offsets: ZERO_OFFSETS }, record.property);
   const ran = applied.find((a) => a.name === slider);
-  return { doc: view, world: posed.world, slots: posed.setup.slots, shown: posed.shown, read, applied: ran === undefined ? record.time : ran.time };
+  return { doc: view, world: posed.world, slots: posed.setup.slots, shown: posed.shown, drawOrder: posed.setup.drawOrder, read, applied: ran === undefined ? record.time : ran.time };
 }
 
 /** `skin/slot/placeholder` — the identity a deform timeline keys a record under (`timelineIdentity`). */

package/src/core/raw.ts

@@ -1,3 +1,4 @@
+import { poseDial, type DialOverride } from './hooks.ts';
 /**
  * The core's raw entry (issue #966, step 3b of issue #380): one pose, or one
  * animation walked at the caller's own steps, returned as the doubles the
@@ -476,6 +477,18 @@ export function poseRawSetup(doc: CompiledDocument, plant: CorePlant = {}): RawP
   return setupPoseIn(doc, plant, RAW_MODE);
 }
 
+/** A value-driven reset pose, using the same dial override as the independent deform survey. */
+export function poseRawDial(doc: CompiledDocument, override: DialOverride, slider: string, plant: CorePlant = {}): { pose: RawPose; read: number | null; applied: number } {
+  const result = poseDial(doc, override, slider);
+  const { world, shown } = result;
+  const drawOrder = [...result.drawOrder];
+  const drawn = rawDrawn(result.doc, shown, world, drawOrder, plant);
+  return { read: result.read, applied: result.applied, pose: {
+    trackTime: 0, animationTime: 0, bones: rawBones(result.doc, world), slots: [...result.slots], drawOrder,
+    ...drawn, events: [], shown: [...shown],
+  } };
+}
+
 /** A table key to read, with an optional skin-view override; omitted skin keeps the supplied view. */
 export interface SetupMeshTarget {
   readonly slot: string;

package/src/parallax.ts

@@ -0,0 +1,208 @@
+/** Geometry-only observations for a dial; no assertion or acceptance threshold. */
+export type FitKind = 'affine' | 'homography';
+export interface MotionFit {
+  status: 'READ' | 'SKIP'; reason: string; method: string;
+  vertices: number; motionRms: number | null; rms: number | null; ratio: number | null;
+  /** Observed minus fitted positions, world x/y; used by the residual picture. */
+  residuals: number[];
+}
+export interface ParallaxMesh {
+  slot: string; attachment: string; kind: 'mesh' | 'region'; vertices: number[];
+  /** Only actual per-vertex declarations, never inferred from motion or a depth range. */
+  depths?: number[];
+  /** Runtime source identity, deliberately excluded from serialized readings. */
+  identity?: object;
+}
+export interface DialSample { value: number; meshes: ParallaxMesh[] }
+const method = (kind: FitKind): string => kind === 'affine'
+  ? 'per-sample forward geometric least squares, centered isotropic coordinates, reorthogonalized QR'
+  : 'per-sample normalized inhomogeneous linear initializer and affine initializer, forward geometric LM refinement (80 iterations each); lowest finite objective found, not certified global optimum';
+/** Scaled sum of squares avoids intermediate over/underflow using only reproducible arithmetic. */
+const norm = (a: readonly number[]): number => {
+  const scale = a.reduce((largest, v) => Math.max(largest, Math.abs(v)), 0);
+  if (scale === 0) return 0;
+  return scale * Math.sqrt(a.reduce((sum, v) => { const r = v / scale; return sum + r * r; }, 0));
+};
+const rms = (a: readonly number[]): number => norm(a) / Math.sqrt(a.length / 2);
+
+/** Tiny full-column-rank least squares; twice-reorthogonalized QR, no normal-equation initializer. */
+function leastSquares(rows: number[][], rhs: number[]): number[] | null {
+  const n = rows[0]?.length ?? 0;
+  if (n === 0 || rows.length < n) return null;
+  const q: number[][] = [], r: number[][] = Array.from({ length: n }, () => new Array<number>(n).fill(0));
+  for (let j = 0; j < n; j++) {
+    const v = rows.map((row) => row[j]);
+    const original = norm(v);
+    for (let pass = 0; pass < 2; pass++) for (let k = 0; k < j; k++) {
+      const dot = q[k].reduce((s, a, i) => s + a * v[i], 0);
+      r[k][j] += dot;
+      for (let i = 0; i < v.length; i++) v[i] -= dot * q[k][i];
+    }
+    r[j][j] = norm(v);
+    if (r[j][j] <= 1e-10 * Math.max(1, original)) return null;
+    q.push(v.map((a) => a / r[j][j]));
+  }
+  const x = q.map((v) => v.reduce((s, a, i) => s + a * rhs[i], 0));
+  for (let j = n - 1; j >= 0; j--) {
+    for (let k = j + 1; k < n; k++) x[j] -= r[j][k] * x[k];
+    x[j] /= r[j][j];
+  }
+  return x.every(Number.isFinite) ? x : null;
+}
+function normalized(a: readonly number[]): { points: number[]; scale: number } | null {
+  const n = a.length / 2, x0 = a[0], y0 = a[1];
+  const cx = a.reduce((s, v, i) => s + (i % 2 ? 0 : (v - x0) / n), 0) + x0;
+  const cy = a.reduce((s, v, i) => s + (i % 2 ? (v - y0) / n : 0), 0) + y0;
+  const centered = a.map((v, i) => v - (i % 2 ? cy : cx));
+  const scale = rms(centered);
+  return Number.isFinite(scale) && scale > 0 ? { points: centered.map((v) => v / scale), scale } : null;
+}
+function predict(h: number[], x: number, y: number): [number, number] | null {
+  const den = 1 + h[6] * x + h[7] * y;
+  if (Math.abs(den) < 1e-9 || !Number.isFinite(den)) return null;
+  const out: [number, number] = [(h[0] * x + h[1] * y + h[2]) / den, (h[3] * x + h[4] * y + h[5]) / den];
+  return out.every(Number.isFinite) ? out : null;
+}
+function errors(h: number[], p: number[], t: number[]): number[] | null {
+  const out: number[] = [];
+  for (let i = 0; i < p.length; i += 2) {
+    const got = predict(h, p[i], p[i + 1]);
+    if (got === null) return null;
+    out.push(t[i] - got[0], t[i + 1] - got[1]);
+  }
+  return out;
+}
+const sse = (a: number[]): number => a.reduce((s, v) => s + v * v, 0);
+/** LM minimizes actual forward x/y distances, rather than the initializer's algebraic objective. */
+function refine(start: number[], p: number[], t: number[]): number[] {
+  let h = [...start], lambda = 1e-4;
+  for (let iteration = 0; iteration < 80; iteration++) {
+    const e = errors(h, p, t);
+    if (e === null) break;
+    const rows: number[][] = [];
+    for (let i = 0; i < p.length; i += 2) {
+      const x = p[i], y = p[i + 1], den = 1 + h[6] * x + h[7] * y;
+      const got = predict(h, x, y)!;
+      rows.push([x / den, y / den, 1 / den, 0, 0, 0, -got[0] * x / den, -got[0] * y / den]);
+      rows.push([0, 0, 0, x / den, y / den, 1 / den, -got[1] * x / den, -got[1] * y / den]);
+    }
+    // Damped least squares as an augmented QR problem; numerical failures never become a score.
+    const rhs = [...e];
+    for (let j = 0; j < 8; j++) {
+      rows.push(Array.from({ length: 8 }, (_, k) => k === j ? Math.sqrt(lambda) : 0)); rhs.push(0);
+    }
+    const step = leastSquares(rows, rhs);
+    if (step === null) break;
+    const candidate = h.map((v, i) => v + step[i]);
+    const next = errors(candidate, p, t);
+    if (next !== null && sse(next) < sse(e)) {
+      h = candidate; lambda = Math.max(1e-12, lambda / 3);
+      if (norm(step) < 1e-12) break;
+    } else { lambda *= 10; if (lambda > 1e12) break; }
+  }
+  return h;
+}
+export function fitMotion(source: readonly number[], target: readonly number[], kind: FitKind): MotionFit {
+  const result: MotionFit = { status: 'SKIP', reason: '', method: method(kind), vertices: source.length / 2, motionRms: null, rms: null, ratio: null, residuals: [] };
+  const skip = (reason: string): MotionFit => ({ ...result, reason, rms: null, ratio: null, residuals: [] });
+  if (source.length !== target.length || source.length % 2 || !source.length || [...source, ...target].some((v) => !Number.isFinite(v))) return skip('no comparable finite x/y vertices');
+  if (source.length / 2 <= (kind === 'affine' ? 3 : 4)) return skip(`at most ${kind === 'affine' ? 3 : 4} correspondences: a saturated ${kind} fit cannot test relief`);
+  const a = normalized(source), b = normalized(target);
+  if (a === null || b === null) return skip('zero extent or non-finite normalization');
+  const motion = rms(source.map((v, i) => target[i] - v));
+  result.motionRms = motion;
+  const coordinateUlp = Number.EPSILON * Math.max(...source.map(Math.abs), ...target.map(Math.abs));
+  if (motion <= Math.max(a.scale * 1e-12, coordinateUlp * 16)) return skip('stationary or below coordinate resolution: RMS motion denominator unavailable');
+  const p = a.points, t = b.points;
+  const rows: number[][] = [], rhs: number[] = [];
+  for (let i = 0; i < p.length; i += 2) {
+    const x = p[i], y = p[i + 1];
+    rows.push([x, y, 1, 0, 0, 0]); rhs.push(t[i]);
+    rows.push([0, 0, 0, x, y, 1]); rhs.push(t[i + 1]);
+  }
+  const affine = leastSquares(rows, rhs);
+  if (affine === null) return skip('rank deficient source geometry');
+  let h = [...affine, 0, 0];
+  if (kind === 'homography') {
+    const projectiveRows = rows.map((row, i) => [...row, -rhs[i] * p[2 * Math.floor(i / 2)], -rhs[i] * p[2 * Math.floor(i / 2) + 1]]);
+    const linear = leastSquares(projectiveRows, rhs);
+    if (linear === null) return skip('rank deficient homography design');
+    const starts = [h, linear].map((start) => refine(start, p, t)).filter((start) => errors(start, p, t) !== null);
+    if (!starts.length) return skip('homography prediction denominator unavailable');
+    h = starts.reduce((best, next) => sse(errors(next, p, t)!) < sse(errors(best, p, t)!) ? next : best);
+  }
+  const det = h[0] * (h[4] - h[5] * h[7]) - h[1] * (h[3] - h[5] * h[6]) + h[2] * (h[3] * h[7] - h[4] * h[6]);
+  if (Math.abs(det) < 1e-10) return skip('singular fitted map');
+  const e = errors(h, p, t);
+  if (e === null) return skip('fitted map has unavailable prediction denominator');
+  result.residuals = e.map((v) => v * b.scale);
+  result.rms = rms(result.residuals); result.ratio = result.rms / motion;
+  if (![result.rms, result.ratio].every(Number.isFinite)) return skip('non-finite geometric residual');
+  return { ...result, status: 'READ', reason: 'geometry only; zero residual does not certify flatness or volume' };
+}
+function ranks(a: number[]): number[] {
+  const sorted = a.map((value, i) => ({ value, i })).sort((a, b) => a.value - b.value);
+  const out: number[] = [];
+  for (let i = 0; i < sorted.length;) {
+    let end = i + 1; while (end < sorted.length && sorted[end].value === sorted[i].value) end++;
+    for (let k = i; k < end; k++) out[sorted[k].i] = (i + end - 1) / 2;
+    i = end;
+  }
+  return out;
+}
+export function spearman(a: number[], b: number[]): number | null {
+  if (a.length !== b.length || a.length < 2 || [...a, ...b].some((v) => !Number.isFinite(v))) return null;
+  const x = ranks(a), y = ranks(b), mean = (a.length - 1) / 2;
+  let xy = 0, xx = 0, yy = 0;
+  for (let i = 0; i < x.length; i++) { const u = x[i] - mean, v = y[i] - mean; xy += u * v; xx += u * u; yy += v * v; }
+  return xx > 0 && yy > 0 ? xy / Math.sqrt(xx * yy) : null;
+}
+function depthReading(rest: ParallaxMesh, target: ParallaxMesh, delta: number, axis?: [number, number]) {
+  const skip = (reason: string) => ({ status: 'SKIP' as const, reason, spearman: null, nearTravel: null, farTravel: null, units: 'world px / dial unit' });
+  const z = rest.depths;
+  if (z === undefined || z.length * 2 !== rest.vertices.length || z.some((v) => !Number.isFinite(v))) return skip('declared per-vertex depth unavailable; model depth summaries are not vertex depths');
+  const lo = Math.min(...z), hi = Math.max(...z);
+  if (lo === hi) return skip('constant declared depth: ranks and near/far split undefined');
+  if (!Number.isFinite(delta) || delta === 0) return skip('zero or unavailable dial distance from setup');
+  if (axis === undefined) return skip('turn axis unavailable: a generic slider does not declare a world turn axis');
+  const d = rest.vertices.map((v, i) => target.vertices[i] - v);
+  const along = z.map((_, i) => d[2 * i] * axis[0] + d[2 * i + 1] * axis[1]);
+  const rho = spearman(z, along);
+  const travel = (near: boolean): number => {
+    const indices = z.flatMap((v, i) => (near ? v === hi : v === lo) ? [i] : []);
+    return Math.sqrt(indices.reduce((s, i) => s + d[2 * i] ** 2 + d[2 * i + 1] ** 2, 0) / indices.length) / Math.abs(delta);
+  };
+  return { status: rho === null ? 'SKIP' as const : 'READ' as const, reason: rho === null ? 'constant motion along axis: correlation undefined' : 'signed setup-to-sample projected motion; sign may reverse at opposite extremes', spearman: rho, nearTravel: travel(true), farTravel: travel(false), units: 'world px / dial unit' };
+}
+export function parallaxOf(dial: string, rest: ParallaxMesh[], samples: DialSample[], setupValue?: number, axis?: [number, number]) {
+  const rows = samples.map((sample) => {
+    const pairs = rest.map((r) => ({ r, t: sample.meshes.find((m) => m.slot === r.slot && m.attachment === r.attachment && m.kind === r.kind && (r.identity === undefined || m.identity === r.identity)) }));
+    const comparable = pairs.filter((p): p is { r: ParallaxMesh; t: ParallaxMesh } => p.t !== undefined && p.t.vertices.length === p.r.vertices.length);
+    const meshes = pairs.filter((p) => p.r.kind === 'mesh').map(({ r, t }) => {
+      const target = t?.vertices ?? [];
+      return { slot: r.slot, attachment: r.attachment, affine: fitMotion(r.vertices, target, 'affine'), homography: fitMotion(r.vertices, target, 'homography'), depth: t === undefined || target.length !== r.vertices.length ? { status: 'SKIP' as const, reason: 'attachment correspondence unavailable', spearman: null, nearTravel: null, farTravel: null, units: 'world px / dial unit' } : depthReading(r, t, sample.value - (setupValue ?? NaN), axis) };
+    });
+    const appearing = sample.meshes.filter((t) => !rest.some((r) => r.slot === t.slot && r.attachment === t.attachment && r.kind === t.kind));
+    for (const t of appearing.filter((t) => t.kind === 'mesh')) meshes.push({
+      slot: t.slot, attachment: t.attachment, affine: fitMotion([], t.vertices, 'affine'), homography: fitMotion([], t.vertices, 'homography'),
+      depth: { status: 'SKIP', reason: 'no setup correspondence for appearing mesh', spearman: null, nearTravel: null, farTravel: null, units: 'world px / dial unit' },
+    });
+    const whole = fitMotion(comparable.flatMap((p) => p.r.vertices), comparable.flatMap((p) => p.t.vertices), 'affine');
+    const centers: Array<{ slot: string; attachment: string; residual: [number, number] }> = [];
+    let offset = 0;
+    if (whole.status === 'READ') for (const { r } of comparable) {
+      const n = r.vertices.length / 2;
+      if (n > 0) centers.push({ slot: r.slot, attachment: r.attachment, residual: [0, 1].map((axis) => r.vertices.reduce((s, _, i) => s + (i % 2 === axis ? whole.residuals[offset + i] / n : 0), 0)) as [number, number] });
+      offset += r.vertices.length;
+    }
+    const center = [0, 1].map((k) => centers.reduce((s, c) => s + c.residual[k] / centers.length, 0));
+    const spread = centers.length > 1 ? Math.sqrt(centers.reduce((s, c) => s + (c.residual[0] - center[0]) ** 2 + (c.residual[1] - center[1]) ** 2, 0) / centers.length) : null;
+    return { value: sample.value, meshes, layers: { status: spread === null ? 'SKIP' : 'READ', reason: spread === null ? 'need a moving full-rank whole-rig fit and at least two comparable layers' : 'unweighted RMS spread of per-layer mean residual vectors after one whole-rig affine fit; regions and meshes, including stationary layers', spread, ratio: spread === null || whole.motionRms === null ? null : spread / whole.motionRms, units: 'world px', whole, centers, omitted: [...pairs.filter((p) => !comparable.includes(p as { r: ParallaxMesh; t: ParallaxMesh })).map((p) => [p.r.slot, p.r.attachment]), ...appearing.map((t) => [t.slot, t.attachment])] } };
+  });
+  const hasVertices = rest.some((r) => r.vertices.length > 0);
+  const measured = rows.some((s) => s.layers.status === 'READ' || s.meshes.some((m) => m.affine.status === 'READ' || m.homography.status === 'READ'));
+  return { spec: 'rigc-parallax/1', dial, status: measured ? 'READ' : 'SKIP', reason: !hasVertices ? 'no vertices to fit' : measured ? 'observations only; no flatness or volume certificate' : 'no moving full-rank comparable fits on this grid', setupValue: setupValue ?? null, axis: axis ?? null,
+    method: { grid: 'independent setup-to-sample position fits; never pool different dial values into one map', normalization: 'residual RMS / setup-to-sample RMS motion, same vertices, world px; no stationary denominator', scope: 'original mesh and region vertices before clipping/visibility; surface on meshes only; no draw order, colour, occlusion or optical flow', limitations: 'non-affine articulation or deformation can produce relief readings without depth; orthographic sloped depth can be affine; zero does not prove paper; homography refinement is local, not a global optimum certificate' }, samples: rows };
+}
+export type ParallaxReading = ReturnType<typeof parallaxOf>;
+export const parallaxText = (reading: ParallaxReading): string => JSON.stringify(reading, null, 2) + '\n';

package/src/parallax_render.ts

@@ -0,0 +1,112 @@
+import { hypot2 } from './numeric.ts';
+import { attachmentSource } from './render_channels.ts';
+/** Named-dial sampling through the core poser, independent reset poses, no timeline playback. */
+import { corePoser } from './render_core.ts';
+import { readModel, CoreInputError, underSkin, underNoSkin } from './core/index.ts';
+import { sliderRecordOf, DIAL_BONE_FIELDS, type DialBoneField } from './core/hooks.ts';
+import { parallaxOf, type ParallaxMesh, type ParallaxReading } from './parallax.ts';
+import { renderFrame, TRANSPARENT_BACKGROUND, viewportFor, type Frame, type Posed } from './render_shared.ts';
+import { Plate } from '../tools/plate.ts';
+import { premultipliedDiff } from './extremes.ts';
+
+export function sampleParallax(modelText: string, atlasText: string, dial: string, skin?: string) {
+  const doc = readModel(modelText);
+  const view = skin === undefined ? underNoSkin(doc) : underSkin(doc, skin);
+  const record = sliderRecordOf(view, dial); // Names the missing dial before any output is made.
+  const raw = JSON.parse(modelText) as { constraints: Array<{ kind: string; name: string; max?: number }> };
+  const declared = raw.constraints.find((c) => c.kind === 'slider' && c.name === dial);
+  const duration = record.timelines.duration;
+  const start = record.bone === null ? 0 : record.from;
+  const finish = record.bone === null ? duration : declared?.max ?? (record.scale === 0 ? NaN : record.from + (duration - record.to) / record.scale);
+  if (![start, finish].every(Number.isFinite) || start === finish) throw new CoreInputError(`--parallax dial ${JSON.stringify(dial)}: no finite nonzero range (from ${start}, max ${finish}); declare a range or a nonzero mapping`);
+  const poser = corePoser(modelText, atlasText);
+  const frame = (posed: Posed, index: number): Frame => ({ index, time: 0, pieces: posed.pieces({ subset: undefined, unclipped: false, texture: false }), attachments: posed.attachments(true) });
+  const setup = frame(poser.setup(skin), -1);
+  const geometry = (f: Frame): ParallaxMesh[] => (f.attachments ?? []).map((a) => ({
+    slot: a.slot, attachment: a.attachment, vertices: [...a.vertices], identity: attachmentSource(a),
+    kind: (attachmentSource(a) as { kind?: string } | undefined)?.kind === 'region' ? 'region' : 'mesh',
+  }));
+  const bone = view.bones.find((b) => b.name === record.bone);
+  const base = (field: DialBoneField): number => bone?.[field] ?? (field === 'scaleX' || field === 'scaleY' ? 1 : 0);
+  const ask = (field: DialBoneField | null, value: number) => poser.dial(dial, field === null || record.bone === null ? { slider: dial, time: value } : { bone: record.bone, field, value }, skin);
+  const fields = record.bone === null ? [] : record.local ? [record.property === 'rotate' ? 'rotation' as const : record.property] : [...DIAL_BONE_FIELDS];
+  let field: DialBoneField | null = fields[0] ?? null;
+  let u0 = field === null ? record.time : base(field), v0 = record.time, gain = 1;
+  if (record.bone !== null) {
+    let best = 0;
+    for (const candidate of fields) {
+      const u = base(candidate), a = ask(candidate, u).read, b = ask(candidate, u + 1).read;
+      if (a !== null && b !== null && Math.abs(b - a) > best) { best = Math.abs(b - a); field = candidate; u0 = u; v0 = a; gain = b - a; }
+    }
+    if (best < 1e-10) throw new CoreInputError(`--parallax dial ${JSON.stringify(dial)}: no driving bone field moves its property; inspect constraints on ${JSON.stringify(record.bone)}`);
+  }
+  const setupValue = record.bone === null ? record.time : v0;
+  const samples: Array<{ value: number; meshes: ParallaxMesh[]; appliedTime: number | null; reason: string | null }> = [];
+  const frames: Frame[] = [];
+  const values = Array.from({ length: 9 }, (_, i) => Math.min(start, finish) + Math.abs(finish - start) * i / 8);
+  for (const [index, value] of values.entries()) {
+    let drive = u0 + (value - v0) / gain;
+    let previous = u0, previousRead = v0;
+    let result: ReturnType<typeof ask> | undefined;
+    let reason: string | null = null;
+    for (let iteration = 0; iteration < 16; iteration++) {
+      if (!Number.isFinite(drive) || Math.abs(drive) > 2 ** 24) { reason = 'dial drive is outside finite ±2^24'; break; }
+      result = ask(field, drive);
+      const read = result.read ?? drive;
+      if (Math.abs(read - value) <= 1e-9 * (1 + Math.abs(value))) break;
+      if (read === previousRead) { reason = 'dial reader did not respond to the drive'; break; }
+      const next = drive + (value - read) * (drive - previous) / (read - previousRead);
+      previous = drive; previousRead = read; drive = next;
+    }
+    const actual = result?.read ?? drive;
+    if (Math.abs(actual - value) > 1e-9 * (1 + Math.abs(value))) reason ??= 'dial reader did not reach requested value (world rotation may wrap)';
+    const wantedTime = record.bone === null ? value : record.to + (value - record.from) * record.scale;
+    const appliedTime = record.bone === null ? wantedTime : record.loop ? duration + wantedTime % duration : Math.max(0, wantedTime);
+    if (result === undefined || !Number.isFinite(result.applied) || Math.abs(result.applied - appliedTime) > 1e-7 * (1 + Math.abs(appliedTime))) reason ??= 'slider did not apply the time its mapping requested (inactive or overwritten)';
+    if (reason !== null || result === undefined) { samples.push({ value, meshes: [], appliedTime: result?.applied ?? null, reason }); continue; }
+    const f = frame(result.posed, index); frames.push(f);
+    samples.push({ value, meshes: geometry(f), appliedTime: result.applied, reason: null });
+  }
+  const reading = { ...parallaxOf(dial, geometry(setup), samples, setupValue),
+    sampling: { poser: 'core', skin: skin ?? null, range: [start, finish], values, setupValue, driveField: field, reset: 'independent Physics.reset per value; other inputs stay at setup; all constraints are applied and other sliders may respond to the driven bone; no animation track is played', depth: 'unavailable: adapter supplies no per-vertex depth or world turn axis; compiled model retains depth summaries only; no inference from motion', samples: samples.map(({ meshes: _meshes, ...s }) => s) },
+    picture: { status: 'SKIP' as 'READ' | 'SKIP', reason: 'no drawable comparable extremes', file: null as string | null },
+  };
+  return { reading, setup, frames, values, rest: geometry(setup) };
+}
+
+/** Setup, dial min/max, native diffs and affine-residual heat maps; one shared fitted world box. */
+export function parallaxPlate(sampled: ReturnType<typeof sampleParallax>, pages: Map<string, Plate>, maxSide: number): Plate | null {
+  const { reading, setup, frames } = sampled;
+  const left = frames.find((f) => f.index === 0), right = frames.find((f) => f.index === 8);
+  if (left === undefined || right === undefined) return null;
+  const all = [setup, ...frames].flatMap((f) => (f.attachments ?? []).flatMap((a) => a.vertices));
+  if (!all.length) return null;
+  const xs = all.filter((_, i) => i % 2 === 0), ys = all.filter((_, i) => i % 2 === 1);
+  const viewport = viewportFor(Math.min(...xs), Math.min(...ys), Math.max(...xs), Math.max(...ys), maxSide);
+  if (![viewport.scale, viewport.width, viewport.height].every(Number.isFinite)) return null;
+  const image = (f: Frame): Plate => renderFrame(f, pages, viewport, TRANSPARENT_BACKGROUND);
+  const base = image(setup), min = image(left), max = image(right);
+  const heatMax = Math.max(0, ...[0, 8].flatMap((i) => reading.samples[i].meshes.flatMap((m) => m.affine.residuals.flatMap((_, k, a) => k % 2 ? [] : [hypot2(a[k], a[k + 1])]))));
+  const heat = (f: Frame, index: number): Plate => {
+    const out = new Plate(viewport.width, viewport.height);
+    out.rect(0, 0, out.width, out.height, [20, 20, 20, 255]);
+    for (const mesh of reading.samples[index].meshes) {
+      const a = f.attachments?.find((a) => a.slot === mesh.slot && a.attachment === mesh.attachment);
+      if (a === undefined || mesh.affine.status !== 'READ') continue;
+      for (let k = 0; k < a.vertices.length; k += 2) {
+        const residual = hypot2(mesh.affine.residuals[k], mesh.affine.residuals[k + 1]);
+        const v = heatMax > 0 ? residual / heatMax : 0;
+        out.rect(Math.round((a.vertices[k] - viewport.minX) * viewport.scale) - 1, Math.round((viewport.maxY - a.vertices[k + 1]) * viewport.scale) - 1, 3, 3, [Math.round(255 * v), Math.round(160 * (1 - v)), Math.round(255 * (1 - v)), 255]);
+      }
+    }
+    return out;
+  };
+  const panels = [base, min, max, premultipliedDiff(max, min), heat(left, 0), heat(right, 8)];
+  const legend = `setup | dial min ${sampled.values[0]} | dial max ${sampled.values[8]} | abs(max-min) | affine residual min | affine residual max. Blue=0 red=${heatMax.toPrecision(5)} world px; dark=unavailable. Geometry only, original mesh vertices; no visibility claim. Scale ${viewport.scale.toPrecision(5)} px/world unit.`;
+  const width = viewport.width * panels.length, columns = Math.max(1, Math.floor(width / 6)), lines = Math.ceil(legend.length / columns);
+  const out = new Plate(width, viewport.height + 9 * lines + 4);
+  panels.forEach((panel, k) => { for (let y = 0; y < panel.height; y++) out.data.set(panel.data.subarray(y * panel.width * 4, (y + 1) * panel.width * 4), (y * width + k * panel.width) * 4); });
+  out.rect(0, viewport.height, width, out.height - viewport.height, [0, 0, 0, 255]);
+  for (let i = 0; i < lines; i++) out.text(legend.slice(i * columns, (i + 1) * columns), 0, viewport.height + 2 + i * 9, 1, [255, 255, 255, 255]);
+  return out;
+}

package/src/render_core.ts

@@ -1,3 +1,4 @@
+import type { DialOverride } from './core/hooks.ts';
 import { localChannels, deformChannels, identifyAttachment } from './render_channels.ts';
 import type { ChannelValue } from './render_shared.ts';
 /**
@@ -102,7 +103,7 @@ import { atlasRegionLookup, parseAtlasText } from './atlas.ts';
 import { pagesOfAtlas, spineFileSha256, type ModelPage } from './model.ts';
 import { clipThrough, type ClipShape, type ShapeClipper } from './core/clipping.ts';
 import { activeBones, CoreInputError, readModel, sourceOfDoc, underNoSkin, underSkin, type CompiledDocument, type CoreSlotRow } from './core/index.ts';
-import { PHYSICS_CLOCK_LEAD, physicsClockStep, poseRawAnimationEach, poseRawSetup, type RawDrawn, type RawPose, type StepEnvironment } from './core/raw.ts';
+import { PHYSICS_CLOCK_LEAD, physicsClockStep, poseRawAnimationEach, poseRawDial, poseRawSetup, type RawDrawn, type RawPose, type StepEnvironment } from './core/raw.ts';
 import type { TimelinePlant } from './core/animation.ts';
 import { stepPhysics, type PhysicsStepper } from './core/constraints_physics.ts';
 import { CORE_DEFAULT_SKIN, lookupSkins } from './core/skins.ts';
@@ -735,7 +736,7 @@ export function corePoser(
   skeleton?: { path: string; bytes: Uint8Array },
   through: ShapeClipper = clipThrough,
   plants: CorePoserPlants = {},
-): Poser {
+): Poser & { dial(name: string, override: DialOverride, skin?: string): { posed: Posed; read: number | null; applied: number } } {
   const doc = readModel(modelText, where);
   // The document poses the rig it was built with; the Spine file beside it must be that build's (issue #968).
   if (skeleton !== undefined) {
@@ -777,6 +778,11 @@ export function corePoser(
     bones: doc.bones.map((b) => ({ name: b.name, parent: b.parent ?? null })),
     slots: doc.slots.map((s) => ({ name: s.name, bone: s.bone })),
     subset: (opts, skin) => subsetOver(roster, opts, skin),
+    dial: (name, override, skin) => {
+      const input = inputOf(skin);
+      const result = poseRawDial(input.doc, override, name, { through });
+      return { posed: corePosed(input, result.pose, through, []), read: result.read, applied: result.applied };
+    },
     setup: (skin, channels) => {
       const input = inputOf(skin);
       let values: ChannelValue[] | undefined;