rig-c 0.0.0-stage → 2.20.4

package/src/core/constraints_slider.ts

@@ -0,0 +1,635 @@
+/**
+ * Construct 5 of the core, third cut (issue #938, step 2e-iii of issue
+ * #380): the slider constraint at the setup pose and at a sample time, with
+ * its timelines. A slider applies an animation — the one constraint kind
+ * that writes bones' LOCAL values and slots rather than a world transform.
+ *
+ * Every rule below was measured by posing hand-written skeletons through
+ * `tools/pose_oracle.ts dump` (spine-core 4.3.13, `--skin all`,
+ * `--physics none`) and reading the rows back — a bone's local values through
+ * `localSource` transform constraints written onto spare bones, a slot's row
+ * as the dump prints it — then held at tolerance 0 by the core suite's `CQ`
+ * controls. Nothing here was written from the runtime's source.
+ *
+ * ## Where it stands: the update order
+ *
+ * A slider is one more constraint in the document's order (`./constraints.ts`,
+ * *The update order*): it reads its dial bone as the constraints before it
+ * left it, writes the local values of the bones its animation keys, and those
+ * bones and everything below them are posed again before the next
+ * constraint. **Every bone its animation keys is posed again, whether or not
+ * a timeline wrote it** (issue #989): a slider before a timeline's first key
+ * writes nothing (below), and the bone is still posed again from its local
+ * values — which is observable only on a bone an earlier constraint moved in
+ * world space, whose world transform the runtime then rebuilds from the
+ * local values read back from it (`localFromWorld` in `./constraints.ts`,
+ * last-bit lossy against the world it came from). Measured on the three rigs
+ * of `CQ06`'s population the lcg never drew (each a world-space transform on
+ * `b2`, then a slider before its first key keying `b2` or its parent): `b2`'s
+ * y column read 1e-7 relative off with the world kept, exact with it posed
+ * again; so did every bone below. A slider at `mix` 0 poses nothing again
+ * (the same three at mix 0 read exact only without it), nor does a bone
+ * the animation names with no timeline (a `"b2": {}` entry). `CZ01` holds
+ * the three, and plants the reading before.
+ *
+ * The runtime's setup pose and every sample apply it: at setup
+ * the sliders compose on the setup pose; at a sample on the pose the sample's
+ * own animation left (applied at alpha 1 from the setup pose, construct 4),
+ * so **the sample's animation first, then each slider in constraint order**.
+ *
+ * ## The time it applies its animation at
+ *
+ * - **Bone-less**: the slider's `time` (a `slider` timeline's `time` key at a
+ *   sample), as it is: a negative time is a time before the animation's keys.
+ * - **With a `bone`**: `to + (value − from) · scale`, `value` the dial's
+ *   `property` read exactly as a transform constraint reads its source with
+ *   no offset (`sourceValue` in `./constraints.ts`): `local` the local field
+ *   as earlier constraints left it, unwrapped; world `rotate` the x column's
+ *   angle brought into [0, 360); world `x`, `y` the origin; world `scaleX`,
+ *   `scaleY` the column lengths; world `shearY` the angle between the columns
+ *   less 90. Measured on a dial under a parent turned 30° and scaled 2 in x:
+ *   a local 10° at `scale` 0.01 read time 0.1, a world 10° read 0.350384 (the
+ *   x column at 35.0384°), a world −50° read 359.21° (0.35921 at 0.001).
+ *   Then `max(0, time)` — a dial at −50° applied the first frame — or, with
+ *   `loop`, `duration + (time mod duration)`: 3 over a 2 s animation read 1,
+ *   −0.5 read 1.5. A stated `time` beside a `bone` is not read (the bone won).
+ * - The animation is then applied at that time, wrapped `time mod duration`
+ *   when `loop` (a bone-less 3.25 over 1 s read 0.25, which is before the
+ *   first key at 0.5 and so applied nothing), `duration` being the runtime's
+ *   (`./animation.ts`, the last key time as float32). ⚠️ A dial looping over
+ *   an animation of duration 0 computes `0 + (time mod 0)`, NaN — and the
+ *   runtime still applied the animation's one key (a rotate keyed 45 on a
+ *   bone at 20 read 65, as the same slider without `loop` and the bone-less
+ *   form looping at 0 and at 0.5 did): every key of such an animation sits
+ *   at 0, so the core applies it at 0. The compiler refuses the shape (A37);
+ *   a foreign file can still carry it.
+ *
+ * ## How it composes: the current pose, the mix, `additive`
+ *
+ * Each timeline of the slider's animation, in the animation's order, blends
+ * from the CURRENT pose — whatever the setup, the sample's animation and the
+ * constraints before it left — with `alpha` the slider's `mix`:
+ *
+ * - **Before the timeline's first key it writes nothing** (the current pose
+ *   stands: a slider at 0.2 over a rotate keyed from 0.5 left 20° at setup
+ *   and the sample's 50° alike). Not the setup value, as a sample's own
+ *   animation writes (construct 4).
+ * - **`mix` 0 applies nothing at all** — not even an attachment key.
+ * - `rotate`, `translate`/`x`/`y`, `shear`/`x`/`y`: `current + (setup + v −
+ *   current) · mix`; **`additive`**: `current + v · mix`. Measured on setup
+ *   rotation 20 and a sample at 50, the slider's value 150: 170 at mix 1,
+ *   110 at 0.5, −10 at −0.5 (no clamp); additive 200 and 125. No wrap to the
+ *   short way round: 50 toward 290 at 0.3 read 122.
+ * - `scale`/`x`/`y`: the target is `setup · v`; `current' + (target −
+ *   current') · mix` where `current'` is |current| with the TARGET's sign — a
+ *   setup `scaleY` 0.5 toward −0.5 at mix 0.5 read −0.5, not 0 — and ⚠️ at
+ *   mix exactly 1 the target itself (issue #989: `current' + (target −
+ *   current')·1` reads 11 of `CZ02`'s 50 absolute bones at mix 1 last-bit
+ *   off under `--raw`, the target none); **additive**: `current + (v · setup
+ *   − setup) · mix` (a current 6 on setup 2, v 3 read 10; issue #989:
+ *   `(v − 1) · setup · mix`, the reading before, reads 65 of `CZ02`'s 250
+ *   additive bones last-bit off, this none). The other kinds read 1,122 of
+ *   1,122 probes of issue #989's scratch population bit-exact at every mix,
+ *   over the setup and over a current an earlier slider moved, and were left
+ *   as they are.
+ * - `inherit`: the key's mode, from its first key on (`CQ06` holds it).
+ * - Slot colours (`rgba`, `rgb`, `alpha`, `rgba2`, `rgb2`): each channel the
+ *   timeline names moves from the current value toward the key's by the mix
+ *   and is then clamped to [0, 1] — ⚠️ at mix exactly 1 it IS the key's value:
+ *   `current + (v − current)·1` read 1 ulp off spine-core on 30 of 13,950
+ *   slot readings of issue #969's hand-written population (`DM01`), the key's
+ *   value on none (a mix of −1 read alpha 0, of 2 read
+ *   0.87451 from 0.12549 toward 0.5); `additive` changes nothing for them.
+ * - `attachment`: the key's placeholder from its first key on, whatever the
+ *   mix above 0 (0.01 switched it); `null` shows nothing.
+ *
+ * ## Its timelines
+ *
+ * A sample's animation may key a slider's `time` and `mix` (one channel
+ * each, construct 4's key search and curves, float32 key values). Before the
+ * first key the slider's own value; a key omitting `value` reads 1 (the
+ * compiler's note on the parser, measured again by `CQ07`). A bone-driven
+ * slider ignores a `time` key: its time is its dial's.
+ *
+ * The keyed value reaches the slider through the setup blend at alpha 1,
+ * `own + (value − own)·1` with `own` the slider's own `time` or `mix` —
+ * the rule the ik, transform and path timelines follow (`./constraints.ts`,
+ * *The timelines*). The two agree on the grid and part in the last bit: a
+ * mix keyed linearly from 0.462 to 0.152 read 0.3521456338160804 as keyed
+ * and 0.35214563381608044 through the blend at one sample, and the
+ * partial-mix blend of a shear key then carried that ulp into the pose (issue
+ * #991, which found it on a looped dial; the loop, the dial and the
+ * translate key it was reduced with each turned out incidental — the same
+ * rig without them misses on 44 to 71 of 200 draws of its two mix values as
+ * keyed and on none through the blend). Measured on the issue's scratch
+ * population — 500 rigs of one or two sliders, looped and unlooped dials and
+ * bone-less ones, over own mixes in [−1, 2], mix keys and time keys in
+ * linear, stepped and Bézier segments, under `--raw` at tolerance 0 — the
+ * value as keyed read 351 of 500 exact, the blend on `mix` alone 465, on
+ * `time` alone 375, on both 500. `CZ03` holds a reduced rig and plants the
+ * value as keyed.
+ *
+ * ## What is left out, by name
+ *
+ * A slider whose animation keys a constraint timeline (ik, transform, path,
+ * slider — writing a later constraint's pose, issue #665's case) is not
+ * posed: the document's bones are absent, naming it; so is one whose
+ * animation deforms a curve a path constraint walks (unmeasured). A slider's
+ * deform, sequence and draw-order keys are posed since issue #955, after the
+ * sample's own (`./deform.ts`, `./draw_order.ts`; they were `sliderAttachmentsWhy`'s
+ * absence before). Its physics timelines are posed since issue #1049 (below),
+ * and events a slider does not fire, so neither leaves anything out.
+ *
+ * ## Its physics timelines (issue #1049)
+ *
+ * Under `Physics.none` a physics constraint applies nothing
+ * (`./constraints_physics.ts`), so neither do a slider's physics keys. Under
+ * the step they do, and until issue #1049 the core applied none of them: on
+ * the selftest's own builds where a dial's animation keys `wind` or
+ * `gravity` of a constraint declared after it, every bone the constraint
+ * drives left spine-core from the third step (`tip` worldX
+ * 14.87037037037037 against 12.092592592592593 at 0.025 s), and with a slot
+ * on that bone `render` drew wrong frames with no refusal. Measured against
+ * spine-core 4.3.13's output only — A10's looping walk, `render`'s recipe at
+ * 60 and 12 fps and the oracle's stepped grid under `--raw`, on 400 compiled
+ * rigs of one or two sliders and one or two physics constraints in random
+ * order, every kind keyed, at tolerance 0 — the rule is:
+ *
+ * - **A slider writes its physics keys into the pass's physics records, at
+ *   its place in the update order**, at the time it applies its animation at
+ *   (`at`), after the step's own animation posed them; a physics constraint
+ *   after it steps with what it wrote, one before it has already stepped.
+ *   Applying the writes to every constraint of the pass whatever its place
+ *   read 239 of the 400 rigs off; not applying them, 205.
+ * - **A write lasts one pass.** The next step's records start again from the
+ *   step's own animation: a write that stood where the step's animation does
+ *   not key read 323 of 400 off.
+ * - **Before the timeline's first key it writes nothing**, as for bones.
+ * - **`wind`, `gravity` under `additive`: `current + v·mix`.** Every other
+ *   value (`inertia`, `strength`, `damping`, `mass`, `mix`), and every value
+ *   of a slider that is not additive: `current + (v − current)·mix`, with
+ *   `current` the value as the pass holds it (the step's own animation and
+ *   any slider before). Adding every kind read 104 of 400 off; blending from
+ *   the setup value (before the step's own animation), 80; writing the key
+ *   itself at mix exactly 1, 20 — in the last bit.
+ * - **A `mass` key blends the mass**, `1 / (m + (v − m)·mix)` with `m =
+ *   1 / massInverse`; blending the inverse read 28 of 400 off.
+ * - **A `reset` key fires nothing** — the slider applies its animation at one
+ *   time, from that time, so no key is crossed (the path-slider suite's
+ *   `PS159` measured the same on the pose); firing a key at or before `at` on
+ *   every pass read 112 of 400 off.
+ * - The timeline naming no constraint (`*`) writes every active constraint
+ *   whose `…Global` flag for that value is on, as a step's own does.
+ *
+ * `CO31` holds the rule on the `core_gate` probe rows and a seeded population
+ * on all three entries; `CO32` plants each rejected reading (`SolverRules`).
+ *
+ * ## 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 { channelAt, keyIndexAt, type CoreAnimationTimelines, type CoreCurve, type CoreKey } from './animation.ts';
+import { sourceValue, TRANSFORM_PROPERTIES, type CoreConstraintRecord, type SolverRules, type SolverState, type TransformProperty } from './constraints.ts';
+import type { CompiledDocument, CoreAnimation } from './index.ts';
+import { EVERY_GLOBAL_PHYSICS, physicsActive, physicsState, resetPhysicsState, unnamedPhysicsTargets, type CorePhysicsRecord, type CorePhysicsTimeline, type PhysicsStepContext } from './constraints_physics.ts';
+
+/** The fields a slider's record may carry after `kind`, `name`, `declaredIn` (`buildRigConstraint` in `src/compile.ts`). */
+export const SLIDER_FIELDS = ['animation', 'additive', 'loop', 'mix', 'bone', 'property', 'from', 'to', 'scale', 'max', 'local', 'time', 'skin'] as const;
+
+/** A slider, read: its animation's timelines and every setup value of the bones they key, so it can be applied with no other part of the document. */
+export interface CoreSliderRecord {
+  kind: 'slider';
+  name: string;
+  animation: string;
+  timelines: CoreAnimationTimelines;
+  /** Its animation's physics timelines, in the animation's order (issue #1049) — set by `readModel` once the animations' constraint timelines are read, which is after the records. */
+  physics: readonly CorePhysicsTimeline[];
+  /** The setup bones its animation keys, by name — what a non-additive key's value is added to. */
+  setup: ReadonlyMap<string, ModelBone>;
+  additive: boolean;
+  loop: boolean;
+  mix: number;
+  time: number;
+  /** The dial, or `null` for the bone-less form. */
+  bone: string | null;
+  property: TransformProperty;
+  from: number;
+  to: number;
+  scale: number;
+  local: boolean;
+  skin: boolean;
+  /** An applied skin's `slider` list names it — what applies a skin-required one (`./constraints.ts`'s header); set per skin view by `underSkin` in `./index.ts`. */
+  listedBySkin: boolean;
+}
+
+/** One slider's timelines in one animation: the `time` and `mix` keys, `null` where not keyed. */
+export interface CoreSliderTimeline {
+  name: string;
+  time: CoreKey[] | null;
+  mix: CoreKey[] | null;
+}
+
+/** A slider as it was applied: its animation, at which time, with which alpha — what the slots are posed from after the bones. */
+export interface SliderApplication {
+  name: string;
+  timelines: CoreAnimationTimelines;
+  at: number;
+  alpha: number;
+  /** The slider's `additive` — how its deform timelines blend (`./deform.ts`). */
+  additive: boolean;
+  /** #969: the time it stored — `sliderTime`, before the animation's loop wrap — what the runtime's `SliderPose.time` reads (`./hooks.ts`). */
+  time: number;
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/**
+ * A slider's record, read field by field — every field the writer can write
+ * for the kind and no other, each of its type, the animation one of the
+ * document's, the dial a bone of it — or `undefined` with the problems named.
+ * An absent field reads the parser's value (the header): `mix` 1, `time`,
+ * `from`, `to` 0, `scale` 1, the flags false.
+ */
+export function readSliderRecord(raw: Record<string, unknown>, name: string, where: string, bones: readonly ModelBone[], animations: readonly CoreAnimation[], problems: string[]): CoreSliderRecord | undefined {
+  const before = problems.length;
+  for (const key of Object.keys(raw)) {
+    if (key === 'kind' || key === 'name' || key === 'declaredIn') continue;
+    if (!(SLIDER_FIELDS as readonly string[]).includes(key)) problems.push(`${where}: field "${key}" is not one this reader knows; it reads [${SLIDER_FIELDS.join(', ')}]`);
+  }
+  const num = (key: string, dflt: number): number => {
+    const v = raw[key];
+    if (v === undefined) return dflt;
+    if (typeof v !== 'number' || !Number.isFinite(v)) {
+      problems.push(`${where}: ${key} is ${JSON.stringify(v)}, not a finite number`);
+      return dflt;
+    }
+    return v;
+  };
+  const flag = (key: string): boolean => {
+    const v = raw[key];
+    if (v === undefined) return false;
+    if (typeof v !== 'boolean') {
+      problems.push(`${where}: ${key} is ${JSON.stringify(v)}, not a boolean`);
+      return false;
+    }
+    return v;
+  };
+  const anim = animations.find((a) => a.name === raw.animation);
+  if (anim === undefined) problems.push(`${where}: a slider's animation is ${JSON.stringify(raw.animation)}, not an animation of this document`);
+  const byName = new Map(bones.map((b) => [b.name, b]));
+  let bone: string | null = null;
+  if (raw.bone !== undefined) {
+    if (typeof raw.bone !== 'string' || !byName.has(raw.bone)) problems.push(`${where}: bone is ${JSON.stringify(raw.bone)}, not a bone of this document`);
+    else bone = raw.bone;
+  }
+  let property: TransformProperty = 'rotate';
+  if (raw.property !== undefined) {
+    const p = TRANSFORM_PROPERTIES.find((x) => x === raw.property);
+    if (p === undefined) problems.push(`${where}: property is ${JSON.stringify(raw.property)}, none of ${TRANSFORM_PROPERTIES.join(', ')}`);
+    else property = p;
+  }
+  num('max', 0);
+  const loop = flag('loop');
+  const setup = new Map<string, ModelBone>();
+  for (const target of anim?.timelines.bones ?? []) {
+    const b = byName.get(target.name);
+    if (b !== undefined) setup.set(b.name, b);
+  }
+  const record: CoreSliderRecord = {
+    kind: 'slider', name, animation: anim?.name ?? '', timelines: anim?.timelines ?? { declared: 0, duration: 0, bones: [], slots: [], later: [], attachments: [], drawOrder: [], events: [] }, physics: [], setup,
+    additive: flag('additive'), loop, mix: num('mix', 1), time: num('time', 0), bone, property,
+    from: num('from', 0), to: num('to', 0), scale: num('scale', 1), local: flag('local'), skin: flag('skin'), listedBySkin: false,
+  };
+  return problems.length === before ? record : undefined;
+}
+
+/**
+ * The slider timelines of one animation record's `constraints.slider`, read:
+ * each names a declared slider, each of its timelines is `time` or `mix` and
+ * appears once, its keys strictly increase in time and carry `time`, `value`
+ * and `curve` only.
+ */
+export function readSliderTimelines(value: unknown, label: string, declared: ReadonlyArray<{ kind: string; name: string }>, problems: string[]): CoreSliderTimeline[] {
+  const out: CoreSliderTimeline[] = [];
+  if (!Array.isArray(value)) return out;
+  value.forEach((entry, i) => {
+    const at = `${label}.constraints.slider[${i}]`;
+    if (!isRecord(entry) || typeof entry.name !== 'string') {
+      problems.push(`${at} names no slider`);
+      return;
+    }
+    if (!declared.some((c) => c.kind === 'slider' && c.name === entry.name)) problems.push(`${at}: "${entry.name}" is not a slider of this document`);
+    const tl: CoreSliderTimeline = { name: entry.name, time: null, mix: null };
+    if (!Array.isArray(entry.timelines)) {
+      problems.push(`${at}: timelines is not a list`);
+      return;
+    }
+    entry.timelines.forEach((raw: unknown, j: number) => {
+      const tat = `${at}.timelines[${j}]`;
+      if (!isRecord(raw) || (raw.name !== 'time' && raw.name !== 'mix')) {
+        problems.push(`${tat}: ${JSON.stringify(isRecord(raw) ? raw.name : raw)} is not a slider timeline; a slider keys time and mix`);
+        return;
+      }
+      const which = raw.name;
+      if (tl[which] !== null) problems.push(`${tat}: "${which}" is keyed twice on slider "${entry.name}"`);
+      tl[which] = readKeys(raw.keys, `${tat} "${which}"`, problems);
+    });
+    out.push(tl);
+  });
+  return out;
+}
+
+function readKeys(value: unknown, at: string, problems: string[]): CoreKey[] {
+  const keys: CoreKey[] = [];
+  if (!Array.isArray(value) || value.length === 0) {
+    problems.push(`${at}: keys is not a non-empty list`);
+    return keys;
+  }
+  let last = -Infinity;
+  value.forEach((k: unknown, j: number) => {
+    const kat = `${at}.keys[${j}]`;
+    if (!isRecord(k)) {
+      problems.push(`${kat} is not an object`);
+      return;
+    }
+    for (const key of Object.keys(k)) if (key !== 'time' && key !== 'value' && key !== 'curve') problems.push(`${kat}: field "${key}" is not one this reader knows; it reads [time, value, curve]`);
+    const time = k.time;
+    if (typeof time !== 'number' || !Number.isFinite(time) || time < 0) {
+      problems.push(`${kat}: time is ${JSON.stringify(time)}, not a finite time at or after 0`);
+      return;
+    }
+    if (time <= last) problems.push(`${kat}: time ${time} is not after the key before it — the writer refuses key times that do not strictly increase`);
+    last = Math.max(last, time);
+    let v = 1;
+    if (k.value !== undefined) {
+      if (typeof k.value !== 'number' || !Number.isFinite(k.value)) problems.push(`${kat}: value is ${JSON.stringify(k.value)}, not a finite number`);
+      else v = k.value;
+    }
+    let curve: CoreCurve = 'linear';
+    if (k.curve !== undefined) {
+      if (j === value.length - 1) problems.push(`${kat}: the last key carries a curve, which eases to no key — the writer refuses it`);
+      else if (k.curve === 'stepped') curve = 'stepped';
+      else if (Array.isArray(k.curve) && k.curve.length === 4 && k.curve.every((n) => typeof n === 'number' && Number.isFinite(n))) curve = k.curve as number[];
+      else problems.push(`${kat}: curve is ${JSON.stringify(k.curve)}, not "stepped" nor 4 finite numbers`);
+    }
+    keys.push({ time: Math.fround(time), values: [Math.fround(v)], stated: { time, values: [v] }, curve });
+  });
+  return keys;
+}
+
+/** What evaluates one channel of a key and finds the key — construct 4's unless a plant passes others. */
+export interface SliderTimelinePlant {
+  channel?: (keys: readonly CoreKey[], index: number, channel: number, t: number) => number;
+  search?: (keys: readonly CoreKey[], t: number) => number;
+}
+
+/** A slider record with its timelines' `time` and `mix` at `t` in place of its own (the header's *Its timelines*). */
+export function posedSlider(r: CoreSliderRecord, timelines: readonly CoreSliderTimeline[], t: number, plant: SliderTimelinePlant = {}): CoreSliderRecord {
+  const tl = timelines.find((x) => x.name === r.name);
+  if (tl === undefined) return r;
+  const search = plant.search ?? keyIndexAt;
+  const channel = plant.channel ?? channelAt;
+  // Through the setup blend at alpha 1, `own + (value − own)·1` (issue #991), as the ik, transform and path timelines are: the value as keyed read 351 of 500 of the issue's scratch population bit-exact under --raw, the blend 500 (CZ03).
+  const at = (keys: CoreKey[] | null, own: number): number => {
+    if (keys === null) return own;
+    const i = search(keys, t);
+    return i < 0 ? own : own + (channel(keys, i, 0, t) - own) * 1;
+  };
+  return { ...r, time: at(tl.time, r.time), mix: at(tl.mix, r.mix) };
+}
+
+/** The time a slider applies its animation at (the header's rule), before the animation's own loop wrap. */
+export function sliderTime(state: SolverState, r: CoreSliderRecord): number {
+  if (r.bone === null) return r.time;
+  const value = sourceValue(state, { source: r.bone, localSource: r.local, offsets: ZERO_OFFSETS }, r.property);
+  const time = r.to + (value - r.from) * r.scale;
+  const d = r.timelines.duration;
+  // Looping over a duration of 0 is NaN in the runtime, and it applied the keys: every key of such an animation sits at 0.
+  if (r.loop && d === 0) return 0;
+  return r.loop ? d + (time % d) : Math.max(0, time);
+}
+
+const ZERO_OFFSETS: Record<TransformProperty, number> = { rotate: 0, x: 0, y: 0, scaleX: 0, scaleY: 0, shearY: 0 };
+
+/** The channels of a timeline at `t`, or `null` before its first key — when a slider writes nothing. */
+function valuesAt(keys: readonly CoreKey[], t: number): number[] | null {
+  const i = keyIndexAt(keys, t);
+  if (i < 0) return null;
+  return keys[i].values.map((_v, c) => channelAt(keys, i, c, t));
+}
+
+/**
+ * Apply one slider to the solver's bones (the header's composition rules):
+ * its local values move, and the bones written are returned for the update
+ * loop to pose again with everything below them. The application is pushed
+ * onto `applied` for the slots.
+ */
+export function applySlider(state: SolverState, r: CoreSliderRecord, applied?: SliderApplication[], physics?: SliderPhysicsTarget): string[] {
+  if (r.mix === 0) return [];
+  const time = sliderTime(state, r);
+  const d = r.timelines.duration;
+  const at = r.loop && d !== 0 ? time % d : time;
+  applied?.push({ name: r.name, timelines: r.timelines, at, alpha: r.mix, additive: r.additive, time });
+  const alpha = r.mix;
+  if (physics !== undefined && state.rules.sliderWritesPhysics) applySliderPhysics(r, at, alpha, physics);
+  const changed: string[] = [];
+  for (const target of r.timelines.bones) {
+    const index = state.index.get(target.name);
+    const setup = r.setup.get(target.name);
+    if (index === undefined || setup === undefined) continue;
+    const b = state.bones[index];
+    let wrote = false;
+    for (const tl of target.timelines) {
+      if (tl.kind === 'inherit') {
+        const i = keyIndexAt(tl.keys, at);
+        if (i < 0) continue;
+        b.inheritMode = tl.keys[i].mode;
+        wrote = true;
+        continue;
+      }
+      const v = valuesAt(tl.keys, at);
+      if (v === null) continue;
+      wrote = true;
+      const add = (field: 'x' | 'y' | 'rotation' | 'shearX' | 'shearY', i: number): void => {
+        const current = b[field] ?? 0;
+        b[field] = r.additive ? current + v[i] * alpha : current + ((setup[field] ?? 0) + v[i] - current) * alpha;
+      };
+      const times = (field: 'scaleX' | 'scaleY', i: number): void => {
+        const current = b[field] ?? 1;
+        const s = setup[field] ?? 1;
+        if (r.additive) {
+          // #989: the key's product with the setup less the setup, then the mix — `(v − 1)·setup·mix` reads last-bit off (CZ02).
+          b[field] = state.rules.sliderAdditiveScaleProduct ? current + (v[i] * s - s) * alpha : current + (v[i] - 1) * s * alpha;
+          return;
+        }
+        const target = s * v[i];
+        // #989: at mix exactly 1 the target itself — `from + (target − from)·1` reads last-bit off (CZ02).
+        if (alpha === 1 && state.rules.sliderScaleMixOneIsTarget) {
+          b[field] = target;
+          return;
+        }
+        const from = Math.abs(current) * Math.sign(target);
+        b[field] = from + (target - from) * alpha;
+      };
+      switch (tl.kind) {
+        case 'rotate': add('rotation', 0); break;
+        case 'translate': add('x', 0); add('y', 1); break;
+        case 'translatex': add('x', 0); break;
+        case 'translatey': add('y', 0); break;
+        case 'shear': add('shearX', 0); add('shearY', 1); break;
+        case 'shearx': add('shearX', 0); break;
+        case 'sheary': add('shearY', 0); break;
+        case 'scale': times('scaleX', 0); times('scaleY', 1); break;
+        case 'scalex': times('scaleX', 0); break;
+        case 'scaley': times('scaleY', 0); break;
+      }
+    }
+    // #989: a bone the animation keys is posed again whether or not a timeline wrote it (the header's update order).
+    if (wrote || (state.rules.sliderReposesKeyedBones && target.timelines.length > 0)) changed.push(target.name);
+  }
+  return changed;
+}
+
+/** The physics records a stepped pass carries, by name — what a slider's physics timelines write and a later physics constraint steps with (issue #1049, the header's *Its physics timelines*). */
+export interface SliderPhysicsTarget {
+  records: Map<string, CorePhysicsRecord>;
+  /** Each record's setup values, before the step's own animation — what a planted blend from the setup reads. */
+  setup: ReadonlyMap<string, CorePhysicsRecord>;
+  active: (r: CorePhysicsRecord) => boolean;
+  rules: Readonly<SolverRules>;
+  ctx: PhysicsStepContext;
+  /** What the sliders wrote this pass, by constraint and field — kept only under the planted reading that a write outlasts its pass. */
+  written: Map<string, Partial<Record<PhysicsField, number>>>;
+}
+
+/** The fields of a physics record a timeline writes. */
+type PhysicsField = 'inertia' | 'strength' | 'damping' | 'massInverse' | 'wind' | 'gravity' | 'mix';
+
+/**
+ * The physics records of one stepped pass, ready for the sliders to write
+ * (issue #1049): every physics record as the step's own animation posed it.
+ * Under the planted reading that a slider's write outlasts its pass, what
+ * the sliders wrote on the step before stands wherever the step's own
+ * animation does not key it (`PhysicsStepContext.keyedNow`).
+ */
+export function sliderPhysicsTarget(records: readonly CoreConstraintRecord[], active: ReadonlySet<string>, ctx: PhysicsStepContext, rules: Readonly<SolverRules>): SliderPhysicsTarget {
+  const posed = new Map(records.flatMap((r): Array<[string, CorePhysicsRecord]> => (r.kind === 'physics' ? [[r.name, r]] : [])));
+  const out = new Map(posed);
+  const written = new Map<string, Partial<Record<PhysicsField, number>>>();
+  if (!rules.sliderPhysicsLastsOnePass) {
+    for (const [name, fields] of ctx.carried ?? new Map<string, Partial<Record<PhysicsField, number>>>()) {
+      const r = out.get(name);
+      if (r === undefined) continue;
+      const next = { ...r };
+      const kept: Partial<Record<PhysicsField, number>> = {};
+      for (const [f, v] of Object.entries(fields) as Array<[PhysicsField, number]>) {
+        if (ctx.keyedNow?.has(`${name}/${f}`)) continue;
+        next[f] = v;
+        kept[f] = v;
+      }
+      out.set(name, next);
+      written.set(name, kept);
+    }
+    ctx.carried = written;
+  }
+  return { records: out, setup: ctx.setupRecords ?? posed, active: (r) => physicsActive(r, active), rules, ctx, written };
+}
+
+/** The value kinds a slider's physics timeline adds under `additive` (`./additive.ts`'s table); the rest write. */
+const PHYSICS_ADDS: ReadonlySet<string> = new Set(['wind', 'gravity']);
+
+/** A slider's physics timelines applied at `at` with alpha `alpha` onto the pass's physics records (the header's *Its physics timelines*). */
+function applySliderPhysics(r: CoreSliderRecord, at: number, alpha: number, target: SliderPhysicsTarget): void {
+  const rules = target.rules;
+  for (const tl of r.physics) {
+    const named = target.records.get(tl.name);
+    const targets = tl.name === EVERY_GLOBAL_PHYSICS ? unnamedPhysicsTargets([...target.records.values()], tl.kind, target.active) : named !== undefined && target.active(named) ? [named] : [];
+    if (tl.kind === 'reset') {
+      // A slider applies its animation at one time, from that time: no key is crossed, so a reset key fires nothing (PS159).
+      if (!rules.sliderPhysicsResetIsDead && tl.keys.some((k) => k.time <= at)) for (const p of targets) resetPhysicsState(physicsState(target.ctx, p.name), target.ctx.time);
+      continue;
+    }
+    const i = keyIndexAt(tl.keys, at);
+    if (i < 0) continue;
+    const v = channelAt(tl.keys, i, 0, at);
+    const adds = r.additive && (PHYSICS_ADDS.has(tl.kind) || !rules.sliderPhysicsAddsWindGravityOnly);
+    for (const p of targets) {
+      const from = rules.sliderPhysicsFromCurrent ? p : (target.setup.get(p.name) as CorePhysicsRecord);
+      const next = { ...p };
+      let field: PhysicsField;
+      if (tl.kind === 'mass') {
+        field = 'massInverse';
+        if (rules.sliderPhysicsBlendsMass) {
+          const m = 1 / from.massInverse;
+          next.massInverse = 1 / (adds ? 1 / p.massInverse + v * alpha : m + (v - m) * alpha);
+        } else next.massInverse = adds ? p.massInverse + (1 / v) * alpha : from.massInverse + (1 / v - from.massInverse) * alpha;
+      } else {
+        field = tl.kind;
+        next[field] = adds ? p[field] + v * alpha : from[field] + (v - from[field]) * alpha;
+      }
+      target.records.set(p.name, next);
+      if (!rules.sliderPhysicsLastsOnePass) target.written.set(p.name, { ...target.written.get(p.name), [field]: next[field] });
+    }
+  }
+}
+
+/** A slot's pose as the sliders move it: what it shows, its light colour and its dark colour (`null` when it states none). */
+export interface SlotPoseState {
+  placeholder: string | null;
+  light: number[];
+  dark: number[] | null;
+}
+
+const clamp01 = (v: number): number => (v < 0 ? 0 : v > 1 ? 1 : v);
+/** Each colour timeline's channels, as indices into `light` (0–3) and `dark` (4–6). */
+const COLOUR_CHANNELS: Record<string, readonly number[]> = { rgba: [0, 1, 2, 3], rgb: [0, 1, 2], alpha: [3], rgba2: [0, 1, 2, 3, 4, 5, 6], rgb2: [0, 1, 2, 4, 5, 6] };
+
+/** Every slider application's slot timelines on one slot, in order (the header's slot rules). */
+export function applySliderSlots(slot: string, pose: SlotPoseState, applications: readonly SliderApplication[]): void {
+  for (const app of applications) {
+    for (const target of app.timelines.slots) {
+      if (target.name !== slot) continue;
+      for (const tl of target.timelines) {
+        if (tl.kind === 'attachment') {
+          const i = keyIndexAt(tl.keys, app.at);
+          if (i >= 0) pose.placeholder = tl.keys[i].name ?? null;
+          continue;
+        }
+        const v = valuesAt(tl.keys, app.at);
+        if (v === null) continue;
+        COLOUR_CHANNELS[tl.kind].forEach((at, i) => {
+          // #969: at mix 1 the key's value itself, not `current + (v − current)·1`, which is last-bit off it (measured, below).
+          if (at < 4) pose.light[at] = app.alpha === 1 ? clamp01(v[i]) : clamp01(pose.light[at] + (v[i] - pose.light[at]) * app.alpha);
+          else if (pose.dark !== null) pose.dark[at - 4] = app.alpha === 1 ? clamp01(v[i]) : clamp01(pose.dark[at - 4] + (v[i] - pose.dark[at - 4]) * app.alpha);
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Why the document's bones cannot be posed because of a slider, or null: a
+ * slider whose animation keys a constraint timeline other than physics, or
+ * deforms a curve a path constraint walks (the header's *What is left out*),
+ * named with the animation and the kinds or the attachments.
+ */
+export function sliderBonesWhy(doc: CompiledDocument): string | null {
+  const found: string[] = [];
+  for (const c of doc.constraints) {
+    if (c.kind !== 'slider') continue;
+    const anim = doc.animations.find((a) => a.name === c.animation);
+    if (anim === undefined) continue;
+    const k = anim.constraints;
+    const sliderTimelines = k.slider.reduce((n, s) => n + (s.time === null ? 0 : 1) + (s.mix === null ? 0 : 1), 0);
+    const paths = k.path.reduce((n, p) => n + [p.position, p.spacing, p.mix].filter((x) => x !== undefined).length, 0);
+    const kinds = [k.ik.length > 0 ? 'ik' : null, k.transform.length > 0 ? 'transform' : null, paths > 0 ? 'path' : null, sliderTimelines > 0 ? 'slider' : null].filter((x): x is string => x !== null);
+    if (kinds.length > 0) found.push(`slider "${c.name}" applies animation "${c.animation}", which keys ${kinds.join(', ')} constraint timelines — a slider writing a later constraint's pose is not posed by this cut`);
+    // A path constraint walks its slot's curve as the constraints before it left it; a slider's deform of that curve is not measured (issue #955).
+    const walked = doc.constraints.flatMap((p) => (p.record?.kind === 'path' ? [p.record.slot] : []));
+    const deformsPath = anim.timelines.attachments.filter((a) => a.deform !== null && walked.includes(a.slot) && doc.skins.find((s) => s.name === a.skin)?.attachments[a.slot]?.[a.attachment]?.geometry?.kind === 'path');
+    if (deformsPath.length > 0) found.push(`slider "${c.name}" applies animation "${c.animation}", which deforms walked path attachment(s) ${deformsPath.map((a) => `"${a.skin}/${a.slot}/${a.attachment}"`).join(', ')} — a slider's deform of a curve a path constraint walks is not posed by this cut`);
+  }
+  return found.length === 0 ? null : found.join('; ');
+}