spine-rigc 1.5.3 → 1.6.2

package/src/core/draw_order.ts

@@ -0,0 +1,125 @@
+/**
+ * Construct 4 of the core, its remainder (issue #955, step 2f of issue #380):
+ * the draw order — at the setup pose, and a draw-order timeline's at a
+ * sample time and under a slider.
+ *
+ * Every rule below was measured by posing hand-written skeletons through
+ * `tools/pose_oracle.ts dump` (spine-core 4.3.13) and reading the slot names
+ * the dump lists (`drawOrder`); nothing here was written from the runtime's
+ * source. The core suite's `CD` controls hold the same skeletons against the
+ * core.
+ *
+ * - **The setup order is the slot order** (`ModelSlot`: the model's slot
+ *   array is the draw order), on every probe and on 19 of 19 recipes.
+ * - **A key's moves are a permutation of the SETUP order**, whatever the
+ *   order before it: each moved slot lands at its setup index plus its
+ *   offset, and the slots no key moves fill the remaining places in setup
+ *   order. The moves are applied as a set — the model holds them in the order
+ *   the spec states them, and the order they are listed in changes nothing.
+ * - **Before the first key the setup order; a key with no moves restores
+ *   it.** Measured on 3,600 samples of 120 random timelines (three to eight
+ *   slots, one to four keys, one to three moves each, empty keys among them):
+ *   0 misses.
+ * - **Key times are float32**, as every key's (`./animation.ts`).
+ * - **A slider applies its animation's draw-order key after the sample's, at
+ *   any mix but 0, and writes nothing before its first key**: a slider at
+ *   0.5 over a key at 0.3 moving the first of three slots two places read
+ *   `s1, s2, s0` at setup at mix 1, 0.5, 0.01 and −1, and the setup order at
+ *   mix 0 and at a time before the key.
+ *
+ * 🚫 **Two moves landing on one place are refused by `readModel`, by name.**
+ * The writer refuses a slot moved twice and a destination outside the slots
+ * (`compileDrawOrder` in `src/compile.ts`), not two slots sent to one
+ * destination; the runtime's fill then leaves a slot out and lists another
+ * twice (the compiler's note on the parser), which is a parser's accident
+ * and not an order to reproduce.
+ */
+import type { ModelSlot } from '../model.ts';
+import { keyIndexAt } from './animation.ts';
+
+/** One draw-order key, as read: its time (float32) and its moves as slot indices, empty for the setup order. */
+export interface CoreDrawOrderKey {
+  time: number;
+  moves: Array<{ slot: number; offset: number }>;
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/**
+ * An animation record's `drawOrder` keys, read: times strictly increasing,
+ * every move naming a slot of the document once per key, a whole offset
+ * landing inside the slots, no two moves landing on one place.
+ */
+export function readDrawOrderKeys(value: unknown, label: string, slots: readonly ModelSlot[], problems: string[]): CoreDrawOrderKey[] {
+  const where = `${label}.drawOrder`;
+  if (!Array.isArray(value)) {
+    problems.push(`${where} is not a list`);
+    return [];
+  }
+  const indexOf = new Map(slots.map((s, i) => [s.name, i]));
+  const out: CoreDrawOrderKey[] = [];
+  let last = -Infinity;
+  value.forEach((k, i) => {
+    const at = `${where}[${i}]`;
+    if (!isRecord(k)) {
+      problems.push(`${at} is not an object`);
+      return;
+    }
+    for (const key of Object.keys(k)) if (key !== 'time' && key !== 'offsets') problems.push(`${at}: field "${key}" is not one a draw-order key carries; it carries [time, offsets]`);
+    const t = k.time;
+    if (typeof t !== 'number' || !Number.isFinite(t) || t < 0) problems.push(`${at}: time is ${JSON.stringify(t)}, not a finite time at or after 0`);
+    else if (t <= last) problems.push(`${at}: time ${t} is not after the key before it — the writer refuses key times that do not strictly increase`);
+    if (typeof t === 'number' && Number.isFinite(t)) last = Math.max(last, t);
+    const moves: CoreDrawOrderKey['moves'] = [];
+    if (k.offsets !== undefined) {
+      if (!Array.isArray(k.offsets)) problems.push(`${at}: offsets is not a list`);
+      else {
+        const landed = new Map<number, string>();
+        k.offsets.forEach((o: unknown, j: number) => {
+          const oat = `${at}.offsets[${j}]`;
+          if (!isRecord(o) || typeof o.slot !== 'string') {
+            problems.push(`${oat} names no slot`);
+            return;
+          }
+          const index = indexOf.get(o.slot);
+          if (index === undefined) {
+            problems.push(`${oat}: "${o.slot}" is not a slot of this document`);
+            return;
+          }
+          if (typeof o.offset !== 'number' || !Number.isInteger(o.offset)) {
+            problems.push(`${oat}: slot "${o.slot}" offset is ${JSON.stringify(o.offset)}, not a whole number`);
+            return;
+          }
+          if (moves.some((m) => m.slot === index)) problems.push(`${oat}: slot "${o.slot}" is moved twice in one key`);
+          const to = index + o.offset;
+          if (to < 0 || to >= slots.length) problems.push(`${oat}: slot "${o.slot}" is at ${index} and offset ${o.offset} lands at ${to}, outside the ${slots.length} slots`);
+          else if (landed.has(to)) problems.push(`${oat}: slot "${o.slot}" lands at ${to}, where slot "${landed.get(to)}" lands too — two moves on one place leave a slot out of the runtime's order`);
+          else landed.set(to, o.slot);
+          moves.push({ slot: index, offset: o.offset });
+        });
+      }
+    }
+    out.push({ time: Math.fround(typeof t === 'number' && Number.isFinite(t) ? t : 0), moves });
+  });
+  return out;
+}
+
+/** The slot indices in the order a key's moves put them — the header's permutation of the setup order. */
+export function orderOf(count: number, moves: CoreDrawOrderKey['moves']): number[] {
+  const order = new Array<number>(count).fill(-1);
+  for (const m of moves) order[m.slot + m.offset] = m.slot;
+  const moved = new Set(moves.map((m) => m.slot));
+  const rest = Array.from({ length: count }, (_v, i) => i).filter((i) => !moved.has(i));
+  let next = 0;
+  for (let i = 0; i < count; i++) if (order[i] === -1) order[i] = rest[next++];
+  return order;
+}
+
+/** What evaluates a draw-order timeline: `drawOrderAt` unless a plant passes another. */
+export type DrawOrderEvaluator = (count: number, keys: readonly CoreDrawOrderKey[], t: number) => number[] | null;
+
+/** The order a timeline sets at `t` as slot indices, or `null` before its first key. */
+export function drawOrderAt(count: number, keys: readonly CoreDrawOrderKey[], t: number): number[] | null {
+  const i = keyIndexAt(keys, t);
+  return i < 0 ? null : orderOf(count, keys[i].moves);
+}

package/src/core/events.ts

@@ -0,0 +1,135 @@
+/**
+ * Construct 4 of the core, its remainder (issue #955, step 2f of issue #380):
+ * the events an animation's event timeline fires between two samples — the
+ * oracle's per-sample `events` block, `[name, time, int, float, string]`.
+ *
+ * Every rule below was measured by posing hand-written skeletons through
+ * `tools/pose_oracle.ts dump` (spine-core 4.3.13) and reading the block back;
+ * nothing here was written from the runtime's source. The core suite's `CD`
+ * controls hold the same skeletons against the core.
+ *
+ * - **A sample lists the keys whose time is in `(previous sample's t, t]`**,
+ *   the first sample's interval opening at −1: an event keyed at 0.25 fired
+ *   at the sample at 0.25 and not at the one after; one keyed at 0 fired at
+ *   the first sample; on an animation of duration 0 every sample sits at 0,
+ *   and the keys at 0 fired at the first sample alone.
+ * - **Key times are float32**: an event keyed at 0.1 (float32
+ *   0.10000000149) did not fire at a sample at 0.1 but at the next.
+ * - **In key order**: two events keyed at one time fired in the order the
+ *   keys are listed.
+ * - **The row's time is the key's (float32), and each of `int`, `float`,
+ *   `string` is the key's where it states one, else the event
+ *   definition's, else the parser's `0`, `0`, `""`** — an event declared with
+ *   no string read `""`, not `null` (so `tools/pose_oracle.ts`' header, which
+ *   said `null`, was wrong about the runtime and says so now). `volume` and
+ *   `balance` are the audio's, and the block does not carry them.
+ * - **`float` is the double the document states**, the definition's and the
+ *   key's alike: `0.1000065`, which rounds to `0.100007` as a double and to
+ *   `0.100006` through `Math.fround`, read `0.100007` from each.
+ * - A slider fires no event into the block: the oracle lists the events of
+ *   the sample's own animation.
+ */
+import { gridRound } from './index.ts';
+
+/** An event definition, as the model states it (`ModelEvent`): the payload a key falls back to. */
+export interface CoreEventDef {
+  name: string;
+  int: number;
+  float: number;
+  string: string;
+}
+
+/** One event key, as read: its time (float32) and the payload it fires with, each field resolved. */
+export interface CoreEventKey {
+  time: number;
+  name: string;
+  int: number;
+  float: number;
+  string: string;
+}
+
+/** One row of a sample's `events` block: `[name, time, int, float, string]`, the oracle's row. */
+export type CoreEventRow = [string, number | null, number, number | null, string | null];
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const EVENT_DEF_FIELDS = ['name', 'int', 'float', 'string', 'audio', 'volume', 'balance'] as const;
+const EVENT_KEY_FIELDS = ['time', 'name', 'int', 'float', 'string', 'volume', 'balance'] as const;
+
+function payload(raw: Record<string, unknown>, at: string, problems: string[]): { int?: number; float?: number; string?: string } {
+  const out: { int?: number; float?: number; string?: string } = {};
+  if (raw.int !== undefined) {
+    if (typeof raw.int !== 'number' || !Number.isInteger(raw.int)) problems.push(`${at}: int is ${JSON.stringify(raw.int)}, not a whole number`);
+    else out.int = raw.int;
+  }
+  if (raw.float !== undefined) {
+    if (typeof raw.float !== 'number' || !Number.isFinite(raw.float)) problems.push(`${at}: float is ${JSON.stringify(raw.float)}, not a finite number`);
+    else out.float = raw.float;
+  }
+  if (raw.string !== undefined) {
+    if (typeof raw.string !== 'string') problems.push(`${at}: string is ${JSON.stringify(raw.string)}, not a string`);
+    else out.string = raw.string;
+  }
+  for (const key of ['volume', 'balance'] as const) if (raw[key] !== undefined && (typeof raw[key] !== 'number' || !Number.isFinite(raw[key]))) problems.push(`${at}: ${key} is ${JSON.stringify(raw[key])}, not a finite number`);
+  return out;
+}
+
+/** The document's `events` section, read: a list of named definitions, each name once, each field of its type. */
+export function readEventDefs(value: unknown, problems: string[]): Map<string, CoreEventDef> {
+  const out = new Map<string, CoreEventDef>();
+  if (!Array.isArray(value)) {
+    problems.push('events is not a list');
+    return out;
+  }
+  value.forEach((raw, i) => {
+    const at = `events[${i}]`;
+    if (!isRecord(raw) || typeof raw.name !== 'string' || raw.name === '') {
+      problems.push(`${at} names no event`);
+      return;
+    }
+    for (const key of Object.keys(raw)) if (!(EVENT_DEF_FIELDS as readonly string[]).includes(key)) problems.push(`${at} "${raw.name}": field "${key}" is not one this reader knows; it reads [${EVENT_DEF_FIELDS.join(', ')}]`);
+    if (raw.audio !== undefined && typeof raw.audio !== 'string') problems.push(`${at} "${raw.name}": audio is ${JSON.stringify(raw.audio)}, not a string`);
+    if (out.has(raw.name)) problems.push(`${at}: event "${raw.name}" is declared twice`);
+    const p = payload(raw, `${at} "${raw.name}"`, problems);
+    out.set(raw.name, { name: raw.name, int: p.int ?? 0, float: p.float ?? 0, string: p.string ?? '' });
+  });
+  return out;
+}
+
+/** An animation record's `events` keys, read: each names a declared event, times do not go backwards (equal times are two firings), each field of its type. */
+export function readEventKeys(value: unknown, label: string, defs: ReadonlyMap<string, CoreEventDef>, problems: string[]): CoreEventKey[] {
+  const where = `${label}.events`;
+  if (!Array.isArray(value)) {
+    problems.push(`${where} is not a list`);
+    return [];
+  }
+  const out: CoreEventKey[] = [];
+  let last = -Infinity;
+  value.forEach((raw, i) => {
+    const at = `${where}[${i}]`;
+    if (!isRecord(raw)) {
+      problems.push(`${at} is not an object`);
+      return;
+    }
+    for (const key of Object.keys(raw)) if (!(EVENT_KEY_FIELDS as readonly string[]).includes(key)) problems.push(`${at}: field "${key}" is not one an event key carries; it carries [${EVENT_KEY_FIELDS.join(', ')}]`);
+    const t = raw.time;
+    if (typeof t !== 'number' || !Number.isFinite(t) || t < 0) problems.push(`${at}: time is ${JSON.stringify(t)}, not a finite time at or after 0`);
+    else if (t < last) problems.push(`${at}: time ${t} is before the key before it — the writer refuses event times that go backwards`);
+    if (typeof t === 'number' && Number.isFinite(t)) last = Math.max(last, t);
+    const def = typeof raw.name === 'string' ? defs.get(raw.name) : undefined;
+    if (def === undefined) {
+      problems.push(`${at}: event ${JSON.stringify(raw.name)} is not declared in the document's events`);
+      return;
+    }
+    const p = payload(raw, at, problems);
+    out.push({ time: Math.fround(typeof t === 'number' && Number.isFinite(t) ? t : 0), name: def.name, int: p.int ?? def.int, float: p.float ?? def.float, string: p.string ?? def.string });
+  });
+  return out;
+}
+
+/** What lists the events fired over `(last, t]`: `eventsFired` unless a plant passes another. */
+export type EventsFired = (keys: readonly CoreEventKey[], last: number, t: number, round?: (v: number) => number | null) => CoreEventRow[];
+
+/** The rows of the keys fired over `(last, t]`, in key order — the header's rules, rounded as the oracle rounds. */
+export function eventsFired(keys: readonly CoreEventKey[], last: number, t: number, round: (v: number) => number | null = gridRound): CoreEventRow[] {
+  return keys.filter((k) => k.time > last && k.time <= t).map((k): CoreEventRow => [k.name, round(k.time), k.int, round(k.float), k.string]);
+}

package/src/core/hooks.ts

@@ -0,0 +1,249 @@
+/**
+ * The core's hooks for the deform survey (issue #969, step 3e of issue #380):
+ * the poses `src/deformmeasure.ts` takes, and what it reads off them, in full
+ * doubles — the raw entry's arithmetic (`./raw.ts`) reached at the survey's
+ * own seams rather than at a renderer's.
+ *
+ * The survey poses a skeleton two ways and reads four things off it. Each is
+ * an entry here, and each was measured against spine-core 4.3.13 running the
+ * survey's own recipe on hand-written documents and on every built row of the
+ * tree, at tolerance 0 — every double equal, every float32 equal to the bit
+ * (the selftest's `DM` controls; the PR of issue #969 carries the counts). The
+ * runtime's source was not read.
+ *
+ * - **A jump** (`poseJump`) — `deformmeasure.ts`'s `poseAt`: a fresh skeleton,
+ *   the setup pose, `update(0)`, `Physics.reset`; then ONE step of `time`
+ *   (`AnimationState.update(time)`, `apply`, `Skeleton.update(time)`,
+ *   `Physics.update`). It is the raw walk's `setup` reset with one step
+ *   (`poseRawAnimation(doc, animation, [time], {}, 'setup')`, measured there),
+ *   returning what the walk computes and does not hand out: the world
+ *   transforms, the slot rows and every slot's shown record with the deform
+ *   array its timelines set.
+ * - **A dial** (`poseDial`) — the survey's slider probe: the setup pose with ONE
+ *   local field of one bone overridden (`bone.pose[field] = u` after
+ *   `setupPose`) or one bone-less slider's time overridden
+ *   (`slider.pose.time = u`), `update(0)`, `Physics.reset`. The override is
+ *   the pose's, not the setup's: a slider's non-additive blend still reads the
+ *   bone's SETUP value (`CoreSliderRecord.setup`), so the view carries the
+ *   overridden bone and the slider records keep the ones they were read with.
+ *   Two readings come back:
+ *   - `read` — the dial's property as `FromProperty.value(skeleton,
+ *     bone.appliedPose, local, zeros)` returns it after the whole update (and,
+ *     under `local`, after `BonePose.validateLocalTransform`): `sourceValue` in
+ *     `./constraints.ts` with no offset, over the solver's LAST state — every
+ *     bone's local values as the constraints left them (`applyConstraints`'
+ *     `settled`), its world as they left it;
+ *   - `applied` — `SliderPose.time` off the applied pose: the time
+ *     `sliderTime` computed when the slider ran, before its animation's loop
+ *     wrap (`SliderApplication.time`); a slider that did not run (mix 0, or
+ *     not active under the skin) keeps its pose's time, the record's `time`
+ *     (the override, on a bone-less dial).
+ * - **The mesh's world vertices with the slot's deform as posed, cleared, or
+ *   replaced** (`meshWorld`) — `VertexAttachment.computeWorldVertices(skeleton,
+ *   slot, …)` over the slot's `appliedPose.deform`: an empty array reads the
+ *   attachment's own vertices (float32, `worldVertices`' default coords); a
+ *   non-empty one IS the vertex array — positions unweighted, offsets added to
+ *   each binding's float32 coordinate weighted (`deformedVertices`) — read as
+ *   the doubles it holds (`EXACT_COORDS`). The array is the slot's, not the
+ *   attachment's: the runtime reads whatever the slot carries, so the posed
+ *   array is the one the shown record's timelines set (`ShownGeometry.deform`)
+ *   whichever record the vertices are asked of — including another mesh's
+ *   array, when the slot shows another mesh that a timeline deforms. That
+ *   array is read as the runtime reads it whatever its length: its first
+ *   `deformLength` numbers, and NaN past its end (an unweighted mesh reads the
+ *   array AS its positions; a weighted one adds it binding by binding) —
+ *   measured on a slot switched to a three-vertex mesh while a four-vertex
+ *   one's key is asked of it, and on the reverse (`DM02`).
+ * - **What a slot shows and at what alpha** (`slotDraw`): the slot row's shown
+ *   name and light alpha, the shown record's timeline identity
+ *   (`timelineIdentity` in `./deform.ts` — the runtime's
+ *   `Attachment.timelineAttachment` compared by record) and its own colour's
+ *   alpha on a mesh or linked mesh (1 on anything else, as the survey reads
+ *   `shown instanceof MeshAttachment ? shown.color.a : 1`).
+ * - **Float32 rows** (`float32Rows`): the survey holds world vertices in a
+ *   `Float32Array` (`computeWorldVertices` into one), so the core's doubles are
+ *   stored through the same conversion — a store, `Math.fround` per value.
+ *
+ * ⛔ Nothing is posed that the core would leave out: a construct the raw entry
+ * refuses (`./raw.ts`), a block the setup pose leaves absent that the survey
+ * reads (bones, slots, the shown records), a record the survey names that the
+ * view does not hold — each is a `CoreInputError` naming it, and the survey's
+ * seam then says which poser it used and why.
+ *
+ * ## Purity
+ *
+ * As the rest of the core: nothing from the Spine runtime package, nothing
+ * from `src/transform.ts`, no clock, no randomness, no I/O.
+ */
+import type { ModelBone } from '../model.ts';
+import { activeBones, constraintRecords, CoreInputError, poseSetup, rawNumber, readColour, shownAttachment, type CompiledDocument, type CorePlant, type CoreSlotRow } from './index.ts';
+import { posedBoneWorld, posedSlots } from './animation.ts';
+import { applyConstraints, constraintsAbsentWhy, pathAnimationsWhy, sourceValue, type SolverState, type TransformProperty } from './constraints.ts';
+import { freshStepContext, steppedPreviousPassWhy } from './constraints_physics.ts';
+import type { CoreSliderRecord, SliderApplication } from './constraints_slider.ts';
+import { attachmentStates, deformedVertices, deformLength, timelineIdentity } from './deform.ts';
+import { EXACT_COORDS, worldVertices, type ShownGeometry } from './vertices.ts';
+import { worldTransforms, type CoreWorld } from './world.ts';
+
+const RAW_PLANT: CorePlant = { round: rawNumber };
+
+/** The six local fields a dial can drive, as a `ModelBone` names them. */
+export const DIAL_BONE_FIELDS = ['rotation', 'x', 'y', 'scaleX', 'scaleY', 'shearY'] as const;
+export type DialBoneField = (typeof DIAL_BONE_FIELDS)[number];
+
+/** One pose the survey reads: the view it was posed under, the world transforms, the slot rows and the shown records. */
+export interface CoreSurveyPose {
+  doc: CompiledDocument;
+  world: ReadonlyMap<string, CoreWorld>;
+  slots: readonly CoreSlotRow[];
+  shown: readonly ShownGeometry[];
+}
+
+/** A dial's override: one bone's local field, or one bone-less slider's time. */
+export type DialOverride = { bone: string; field: DialBoneField; value: number } | { slider: string; time: number };
+
+/** A dial pose, and its two readings (the header's *A dial*). */
+export interface CoreDialPose extends CoreSurveyPose {
+  /** The slider's property read off its bone, or `null` on a bone-less slider. */
+  read: number | null;
+  applied: number;
+}
+
+/** The slider record `name` of the view, refused by name when it has none. */
+export function sliderRecordOf(doc: CompiledDocument, name: string): CoreSliderRecord {
+  const c = doc.constraints.find((x) => x.kind === 'slider' && x.name === name);
+  if (c?.record?.kind !== 'slider') throw new CoreInputError(`the model document carries no slider "${name}" (it declares [${doc.constraints.filter((x) => x.kind === 'slider').map((x) => x.name).join(', ')}])`);
+  return c.record;
+}
+
+/**
+ * The jump (the header's first entry): the setup pose reset, then one step of
+ * `time`, as `poseRawAnimation(doc, animation, [time], {}, 'setup')` walks it.
+ */
+export function poseJump(doc: CompiledDocument, animation: string, time: number): CoreSurveyPose {
+  const anim = doc.animations.find((a) => a.name === animation);
+  if (anim === undefined) throw new CoreInputError(`animation "${animation}" is not one of this document's [${doc.animations.map((a) => a.name).join(', ')}]`);
+  if (!Number.isFinite(time) || time < 0) throw new CoreInputError(`the jump's time is ${time}, not a finite time at or above 0`);
+  const why = constraintsAbsentWhy(doc) ?? pathAnimationsWhy(doc) ?? steppedPreviousPassWhy(doc);
+  if (why !== null) throw new CoreInputError(`the jump leaves the bones out: ${why}`);
+  const ctx = freshStepContext();
+  const reset = poseSetup(doc, RAW_PLANT, ctx);
+  const resetWhy = reset.absent.filter(([b]) => b === 'setup.bones');
+  if (resetWhy.length > 0 || reset.world === null) throw new CoreInputError(`the jump's reset pose leaves ${resetWhy.map(([b, w]) => `${b} out (${w})`).join('; ') || 'the bones out'}`);
+  ctx.phase = 'update';
+  const t = time < anim.timelines.duration ? time : anim.timelines.duration;
+  const before = ctx.time;
+  ctx.time += time;
+  const sliders: SliderApplication[] = [];
+  const posed = posedBoneWorld(doc, anim.timelines, t, RAW_PLANT, anim.constraints, sliders, { ctx, before });
+  const placeholders = new Map<string, string | null>();
+  const slots = posedSlots(doc, anim.timelines, t, RAW_PLANT, sliders, placeholders);
+  if (slots.conflicts.length > 0) throw new CoreInputError(`the jump leaves the slots out: ${slots.conflicts.join('; ')}`);
+  const states = attachmentStates(doc, shownAttachment, placeholders, { timelines: anim.timelines, t }, sliders, {});
+  if (states.why.length > 0) throw new CoreInputError(`the jump leaves the attachments out: ${states.why.join('; ')}`);
+  return { doc, world: posed.world, slots: slots.rows, shown: states.shown };
+}
+
+/** The view with the override written into the pose — a bone's local field, or a slider record's time. */
+function overridden(doc: CompiledDocument, override: DialOverride): CompiledDocument {
+  if ('bone' in override) {
+    if (!doc.bones.some((b) => b.name === override.bone)) throw new CoreInputError(`the dial's bone "${override.bone}" is not a bone of the model document`);
+    return { ...doc, bones: doc.bones.map((b): ModelBone => (b.name === override.bone ? { ...b, [override.field]: override.value } : b)) };
+  }
+  sliderRecordOf(doc, override.slider);
+  return {
+    ...doc,
+    constraints: doc.constraints.map((c) => (c.kind === 'slider' && c.name === override.slider && c.record?.kind === 'slider' ? { ...c, record: { ...c.record, time: override.time } } : c)),
+  };
+}
+
+const ZERO_OFFSETS: Record<TransformProperty, number> = { rotate: 0, x: 0, y: 0, scaleX: 0, scaleY: 0, shearY: 0 };
+
+/**
+ * The dial (the header's second entry): the setup pose with `override`
+ * written into it, every physics state reset, and `slider`'s two readings.
+ */
+export function poseDial(doc: CompiledDocument, override: DialOverride, slider: string): CoreDialPose {
+  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'}`);
+  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);
+  const applied: SliderApplication[] = [];
+  const sink: { state: SolverState | null } = { state: null };
+  const again = applyConstraints(view.bones, worldTransforms(view.bones, active), active, constraintRecords(view), null, applied, freshStepContext(), (state) => {
+    sink.state = state;
+  });
+  const settled = sink.state;
+  if (settled === null) throw new CoreInputError('the dial pose\'s solver left no state to read');
+  for (const [name, w] of posed.world) {
+    const v = again.get(name);
+    if (v === undefined || v.a !== w.a || v.b !== w.b || v.c !== w.c || v.d !== w.d || v.worldX !== w.worldX || v.worldY !== w.worldY) {
+      throw new CoreInputError(`the dial pose's two passes disagree on bone "${name}" — the reading would not be the pose's`);
+    }
+  }
+  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 };
+}
+
+/** `skin/slot/placeholder` — the identity a deform timeline keys a record under (`timelineIdentity`). */
+export function recordIdentity(skin: string, slot: string, placeholder: string): string {
+  return `${skin}/${slot}/${placeholder}`;
+}
+
+/**
+ * The world vertices of the mesh record `skin/slot/placeholder` drawn on
+ * `slot` (the header's third entry): with the slot's deform as posed
+ * (`posed`), cleared (`cleared`), or replaced by `deform`. Doubles; the
+ * survey stores them through `float32Rows`.
+ */
+export function meshWorld(pose: CoreSurveyPose, slot: string, record: { skin: string; slot: string; placeholder: string }, deform: 'posed' | 'cleared' | ArrayLike<number>): number[] {
+  const where = recordIdentity(record.skin, record.slot, record.placeholder);
+  const g = pose.doc.skins.find((k) => k.name === record.skin)?.attachments[record.slot]?.[record.placeholder]?.geometry;
+  if (g?.kind !== 'mesh') throw new CoreInputError(`${where} is not a mesh record of the model document`);
+  const slotRecord = pose.doc.slots.find((s) => s.name === slot);
+  if (slotRecord === undefined) throw new CoreInputError(`slot "${slot}" is not a slot of the model document`);
+  const bone = pose.world.get(slotRecord.bone);
+  if (bone === undefined) throw new CoreInputError(`slot "${slot}"'s bone "${slotRecord.bone}" has no world transform`);
+  const array: readonly number[] =
+    deform === 'cleared' ? [] : deform === 'posed' ? (pose.shown.find((s) => s.slot === slot)?.deform ?? []) : Array.from(deform);
+  if (array.length === 0) return worldVertices(g.vertices, bone, pose.world);
+  // The slot's array read as the runtime reads it whatever its length: its first `deformLength` numbers, and NaN past its end (the header's third entry).
+  const length = deformLength(g.vertices);
+  const fitted = array.length === length ? array : Array.from({ length }, (_v, i) => (i < array.length ? array[i] : Number.NaN));
+  return worldVertices(deformedVertices(g.vertices, fitted), bone, pose.world, EXACT_COORDS);
+}
+
+/** What one slot shows and at what alpha (the header's fourth entry). */
+export interface CoreSlotDraw {
+  /** The shown attachment's name, or `null` for none. */
+  shown: string | null;
+  /** The shown record's timeline identity (`timelineIdentity`), or `null` when none can key it. */
+  identity: string | null;
+  /** The slot's light alpha as posed. */
+  slotAlpha: number;
+  /** The shown record's own colour alpha on a mesh or linked mesh; 1 otherwise. */
+  attachmentAlpha: number;
+}
+
+export function slotDraw(pose: CoreSurveyPose, slot: string): CoreSlotDraw {
+  const row = pose.slots.find((r) => r[0] === slot);
+  if (row === undefined) throw new CoreInputError(`slot "${slot}" has no row in the pose`);
+  const slotAlpha = row[5];
+  if (slotAlpha === null) throw new CoreInputError(`slot "${slot}"'s alpha is not finite`);
+  const shown = pose.shown.find((s) => s.slot === slot);
+  const record = shown === undefined ? undefined : pose.doc.skins.find((k) => k.name === shown.skin)?.attachments[slot]?.[shown.placeholder];
+  if (shown === undefined || record === undefined) return { shown: row[1], identity: null, slotAlpha, attachmentAlpha: 1 };
+  const identity = timelineIdentity(slot, { skin: shown.skin, placeholder: shown.placeholder, record });
+  const mesh = record.kind === 'mesh' || record.kind === 'linkedmesh';
+  return { shown: row[1], identity, slotAlpha, attachmentAlpha: mesh && record.color !== undefined ? readColour(record.color)[3] : 1 };
+}
+
+/** Doubles stored as the survey stores world vertices: one `Float32Array`, each value through the store's `Math.fround`. */
+export function float32Rows(values: readonly number[]): Float32Array {
+  return Float32Array.from(values);
+}