spine-rigc 1.9.0 → 1.9.2

package/src/compile.ts

@@ -318,9 +318,24 @@ const FRAME = 1 / 60;
  * returns, so the refusal below is raised there, inside `compile`, in these
  * words. Exported so the selftest hands it to the emitter the way the assembly
  * does (`MA03`, `MA08`).
+ *
+ * 🔢 **It returns the order the FILE keys, which is the comparator's order
+ * with every integer-like name first** (issue #1034). `animations` is a JSON
+ * object, and an object lists a key that is an array index (`5`, `10` — not
+ * `01`, `-a` or `2b`) before every other key, in ascending order, whatever
+ * order it was filled in. Measured on a probe keying `5, -a, 10, 2b, 01`: the
+ * comparator orders `-a, 01, 2b, 5, 10`, and `skeleton.json`, spine-core's
+ * `animations` and the `/3` document's `editorOrder` all list
+ * `5, 10, -a, 01, 2b`. The emitter keys the object either way, so no byte
+ * moves; what moves is every READER of a `rigc-compiled/2` or `/1` document,
+ * which derives the file's order by calling this function and was handed the
+ * comparator's list (`fileAnimationOrder` below). The comparator's own list is
+ * `editorNamesInOrder(names, 'animations')`. Skins are an array and keep the
+ * comparator's order (`editorSkinOrder`), and a skin's slot keys come back as
+ * an object's keys (`editorSlotKeyOrder`), which are the file's already.
  */
 export function editorAnimationOrder(names: readonly string[]): string[] {
-  return editorNamesInOrder(names, 'animations');
+  return keyedOrder(editorNamesInOrder(names, 'animations'));
 }
 
 /**
@@ -3514,17 +3529,12 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   // applies them, so a name pair the editor could key two ways is refused here
   // in the order it was refused at emission before this entry existed.
   //
-  // ⚠️ A name list the file KEYS is stated as the keys of an object filled in
-  // that order, not as the sorted list: the file's `animations` and a skin's
-  // `attachments` are JSON objects, and an object lists an integer-like key
-  // ("2", "10") before every other key, in ascending order, whatever order it
-  // was filled in. That is the order `skeleton.json` spells and its parser
-  // reads, so it is the order stated here; the skins are an array and keep the
-  // sort's.
-  const editorOrder: ModelEditorOrder = {
-    skins: EDITOR_ORDERS.skins(skins).map((skin) => ({ name: skin.name, slots: Object.keys(EDITOR_ORDERS.slotKeys(skin.attachments)) })),
-    animations: keyedOrder(EDITOR_ORDERS.animations([...animations.keys()])),
-  };
+  // ⚠️ A name list the file KEYS is the keys of an object filled in that
+  // order: an object lists an integer-like key ("2", "10") before every other
+  // key. Since issue #1034 that is `editorAnimationOrder`'s own result rather
+  // than a step applied here, so a reader deriving the order of a `/2` document
+  // (`fileAnimationOrder`) is handed the same list this states.
+  const editorOrder: ModelEditorOrder = editorOrderOver(skins, [...animations.keys()]);
 
   for (const slot of slots) {
     if (!boneNames.has(slot.bone)) throw new CompileError(`slot "${slot.name}" has no bone`);
@@ -3559,13 +3569,103 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
  */
 const EDITOR_ORDERS = { skins: editorSkinOrder, slotKeys: editorSlotKeyOrder, animations: editorAnimationOrder } as const;
 
-/** The order an object filled with `names`, in that order, lists its keys in — the order a JSON object keyed by them is spelled in. */
-function keyedOrder(names: readonly string[]): string[] {
+/**
+ * The order an object filled with `names`, in that order, lists its keys in —
+ * the order a JSON object keyed by them is spelled in, and the order
+ * spine-core reads it in: every array-index name (`5`, `10`; not `01`, `-a`,
+ * `2b`) first, ascending, then the rest as filled (issue #1034).
+ *
+ * ⭐ It is the rule for EVERY object the Spine file keys by a name, not only
+ * `animations`: the emitter fills each such object in the model's order — an
+ * animation's `slots`, `bones`, `ik`, `transform`, `path`, `physics` and
+ * `slider` groups and its `attachments` at all three levels (skin, slot,
+ * attachment) — so a reader walking one of them in the file's order walks
+ * this over the model's order (`src/deformstructure.ts`'s deform timelines,
+ * `src/assertions/model/constraints.ts`'s constraint timelines). Measured on a
+ * build whose `ik` group keys `leg_f_ik` then `5`: the file and spine-core list
+ * `5, leg_f_ik`.
+ */
+export function keyedOrder(names: readonly string[]): string[] {
   const keyed: Record<string, true> = {};
   for (const name of names) keyed[name] = true;
   return Object.keys(keyed);
 }
 
+/** A skin as far as its order reads it: its name and its table, keyed by slot. */
+interface OrderedSkin {
+  name: string;
+  attachments: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * The orders the Spine file lists `skins`, each skin's slot keys and
+ * `animations` in, over a model's skins and animation names: `EDITOR_ORDERS`,
+ * the functions `compile` hands the emitter, so this is the emitted order by
+ * construction rather than a second statement of it (issue #1034). `compileModel`
+ * states it in the model (`editorOrder`); `fileAnimationOrder` and `fileSkinOrder` derive it for a
+ * document that does not state it. A name set the editor could key two ways is
+ * refused here by name, as at emission.
+ */
+export function editorOrderOver(skins: readonly OrderedSkin[], animations: readonly string[]): ModelEditorOrder {
+  return { skins: editorSkinsOver(skins), animations: EDITOR_ORDERS.animations(animations) };
+}
+
+/** `editorOrderOver`'s skins alone: each skin's name and slot keys, in the file's order. */
+function editorSkinsOver(skins: readonly OrderedSkin[]): ModelEditorOrder['skins'] {
+  return EDITOR_ORDERS.skins(skins).map((skin) => ({ name: skin.name, slots: Object.keys(EDITOR_ORDERS.slotKeys(skin.attachments)) }));
+}
+
+/** What a reader of a model document holds that the file's orders are read or derived from: `CompiledDocument`'s fields. */
+export interface OrderedDocument {
+  skins: readonly OrderedSkin[];
+  animations: readonly { name: string }[];
+  stated: { editorOrder: ModelEditorOrder } | null;
+}
+
+/**
+ * The order the Spine file lists a model document's animations in — the one
+ * place a reader of the document gets it (issue #1034), with
+ * `fileSkinOrder` its sibling for the skins and their slot keys.
+ *
+ * - A `rigc-compiled/3` document STATES it (`editorOrder`, issue #1026), and
+ *   that statement is the one source: nothing derives it beside the document.
+ * - A `/2` or `/1` document does not, and it is derived by the emitter's own
+ *   rule over the document's names (`EDITOR_ORDERS`, as `editorOrderOver`
+ *   runs it) — the file's order for every name, integer-like ones included
+ *   (`editorAnimationOrder`'s 🔢). A name set the editor could key two ways is
+ *   refused by name (`CompileError`), as at emission.
+ */
+export function fileAnimationOrder(doc: OrderedDocument): readonly string[] {
+  return doc.stated !== null ? doc.stated.editorOrder.animations : EDITOR_ORDERS.animations(doc.animations.map((a) => a.name));
+}
+
+/** `fileAnimationOrder`'s sibling: the skins, each with its slot keys, in the order the Spine file lists them — stated by a `/3` document, derived for a `/2` or `/1` one. */
+export function fileSkinOrder(doc: OrderedDocument): ModelEditorOrder['skins'] {
+  return doc.stated !== null ? doc.stated.editorOrder.skins : editorSkinsOver(doc.skins);
+}
+
+/**
+ * `skins` in the order `order` lists them (`fileSkinOrder`), each
+ * with its slot keys in that order. The k-th entry of a name is the k-th skin
+ * of that name, so two skins answering to one name — a defect another check
+ * names — are neither merged nor dropped. A skin `order` does not list, or an
+ * entry naming no skin left, is this caller's defect (`readModel` refuses an
+ * `editorOrder` that is not a permutation of the document's skins), so it
+ * throws rather than walking a guess.
+ */
+export function skinsInFileOrder<T extends { name: string }>(skins: readonly T[], order: ModelEditorOrder['skins']): Array<{ skin: T; slots: readonly string[] }> {
+  const left = [...skins];
+  const out: Array<{ skin: T; slots: readonly string[] }> = [];
+  for (const entry of order) {
+    const at = left.findIndex((skin) => skin.name === entry.name);
+    if (at < 0) throw new Error(`internal: the file's skin order names skin "${entry.name}", which no skin left in the walk answers to`);
+    out.push({ skin: left[at], slots: entry.slots });
+    left.splice(at, 1);
+  }
+  if (left.length > 0) throw new Error(`internal: the file's skin order leaves out skin(s) ${left.map((skin) => `"${skin.name}"`).join(', ')}`);
+  return out;
+}
+
 /**
  * The fields `CompileResult` carries from the model, in the order it has
  * always carried them (`CarriedFromCompileResult`), by reference.

package/src/core/additive.ts

@@ -0,0 +1,468 @@
+/**
+ * What one timeline does when it is applied additively — the question A40
+ * asks of the timeline a later slider shares with an earlier one (issue
+ * #1025, cut 4c-5 of step 4c of #380). The validator asks the runtime by
+ * posing (`timelineAddBehaviour` in `src/validate.ts`): the timeline applied
+ * with `add` set, at alpha 1, `MixFrom.current`, no events, TWICE, at every
+ * time its own keys name, the midpoints between them and one past the last,
+ * from two start states — the setup pose, and the setup pose with every number
+ * a pose holds moved by `0.375`, every slot showing nothing and the draw order
+ * turned by one — under no skin and under every skin. A second application
+ * that moves the pose again is `accumulates`; one that moved it the first time
+ * and not the second is `overwrites`; one that never moves it is `inert`; the
+ * strongest any cell reads wins. This module answers the same question from
+ * the model document, with the core's own readings.
+ *
+ * ## The class is not a function of the timeline's kind alone
+ *
+ * Measured first, by posing the runtime's probe over a seeded population that
+ * reaches every timeline the catalogue lists (`src/timelines.ts`), each in
+ * three value variants — keys away from the setup, keys stating the setup
+ * values, keys stating the identity (0, scale 1, white, no draw-order move) —
+ * under no skin, the default skin and a second one, with targets active under
+ * one skin only (234 timelines, the core suite's `CO27`): of the 36
+ * spellings, 18 read one class on every timeline and 18 did not — every
+ * adding kind read `accumulates` on some timelines and `inert` on others, and
+ * a deform read all three. The kind decides what an application CAN do; three
+ * facts of the rig decide what it does:
+ *
+ * - **Whether its target is active under some skin.** A timeline whose bone,
+ *   slot bone or constraint is inactive under every view writes nothing:
+ *   `inert`, whatever its kind. The rules are the core's own — `activeBones`,
+ *   `slotTimelinesApply`, `constraintInactiveWhy` (an ik is gated on its
+ *   target, a transform on its source, a path on its slot's bone, a physics
+ *   constraint on its bone, a slider on its dial) — measured equal here on an
+ *   ik over a skin-required bone (applied) and onto one (not applied).
+ * - **Whether a deform or sequence timeline's attachment is shown.** Both
+ *   are gated on the slot showing the record they are keyed on, or a linked
+ *   mesh that plays its timelines (`timelineIdentity`); from the displaced
+ *   state the slot shows nothing, so only the setup state can be written. A
+ *   deform keyed on a record no view shows at setup is `inert`; a deform
+ *   whose every offset is 0 fills the empty deform array once and adds 0 the
+ *   second time — `overwrites`, not `accumulates`.
+ * - **Whether the value it adds is 0.** The ten bone value timelines, the
+ *   transform mixes, a path's position and mix, physics wind and gravity and
+ *   a slider's time and mix ADD: `current + v` (a scale `current + (v·setup −
+ *   setup)`, the setup's and not the current's — a displaced `scaleX` 1.875
+ *   over setup 1.5 keyed 3 read 4.875). Keyed to 0 (a scale to 1) they write
+ *   nothing at all: `inert`.
+ *
+ * So the class is a computation over the document, and the table below
+ * carries only what the kind contributes — what its application does when it
+ * writes, the runtime class the timeline loads as and the properties it
+ * registers. The rest is computed per cell, as the probe reads it.
+ *
+ * ## The cells, per kind
+ *
+ * - `adds`: each field `once = current + d`, `twice = once + d`, `d` the
+ *   keyed value at the time (`channelAt`, the runtime's curve as the core
+ *   reproduces it), a scale's `v·setup − setup`; `current` the setup value,
+ *   or the setup value plus `0.375`. A deform: the setup state holds no
+ *   deform, `once` is the keyed array (`deformAt`) and `twice` the core's
+ *   additive blend of it over itself at alpha 1 (`blendDeform`).
+ * - `writes`: the keyed value replaces the current one — a number through the
+ *   setup blend at alpha 1, `current + (v − current)`, a mass as its inverse; a
+ *   colour channel the keyed value clamped to [0, 1]; an ik's flags as keyed;
+ *   an inherit mode, an attachment by the name it resolves to under the view
+ *   (`shownAttachment`), a draw order (`drawOrderAt`) against the setup order
+ *   or the order turned by one; a sequence writes its frame wherever its
+ *   record is shown (the setup pose holds no frame index).
+ * - `writes nothing`: an event timeline (a slider fires none) and a physics
+ *   `reset` (no time passes between the two applications).
+ *
+ * A physics timeline naming no constraint (`*`) writes every active record
+ * whose `…Global` flag for its value is on (`unnamedPhysicsTargets`).
+ *
+ * ## Held
+ *
+ * The core suite's `CO27` poses the runtime's probe over the seeded
+ * population and holds every cell's letter, and every added field's three
+ * values at tolerance 0, to this module's; one row of the table flipped per
+ * class turns exactly the timelines using it red.
+ *
+ * ## 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, ModelVertices } from '../model.ts';
+import { channelAt, keyIndexAt, SLOT_COLOUR_TIMELINES, type BoneTimelineKind, type CoreKey, type SlotTimelineKind } from './animation.ts';
+import { constraintInactiveWhy, TRANSFORM_MIXES, TRANSFORM_PROPERTIES, type CoreConstraintRecord, type CoreIkKey } from './constraints.ts';
+import { EVERY_GLOBAL_PHYSICS, physicsActive, unnamedPhysicsTargets, type CorePhysicsRecord, type PhysicsTimelineKind } from './constraints_physics.ts';
+import { blendDeform, deformAt, timelineIdentity, type CoreDeformKey, type CoreSequenceKey } from './deform.ts';
+import { drawOrderAt, type CoreDrawOrderKey } from './draw_order.ts';
+import { activeBones, foldInheritMode, readColour, shownAttachment, shownRow, type CompiledDocument, type CoreAttachment } from './index.ts';
+import { slotTimelinesApply } from './skins.ts';
+
+/** What a kind's application does when it writes (the header's *The cells, per kind*). */
+export type AdditiveMode = 'adds' | 'writes' | 'writes nothing';
+
+/** What a timeline's property ids are followed by: its target's index (and, for an attachment's, the attachment), or nothing. */
+export type AdditiveAddress = 'bone' | 'slot' | 'attachment' | 'constraint' | 'none';
+
+/** One timeline spelling: the runtime class it loads as, the properties it registers in order, what its ids carry, and its mode. */
+export interface AdditiveRow {
+  runtimeClass: string;
+  properties: readonly string[];
+  address: AdditiveAddress;
+  mode: AdditiveMode;
+}
+
+const row = (runtimeClass: string, properties: readonly string[], address: AdditiveAddress, mode: AdditiveMode): AdditiveRow => ({ runtimeClass, properties, address, mode });
+
+/**
+ * Every timeline spelling a document's animation can hold, as measured (the
+ * header): the class name each loads as and the property ids it registers were
+ * read off the loaded timeline objects, and the mode off the probe's cells over
+ * the seeded population.
+ */
+export const ADDITIVE_APPLY: Readonly<Record<string, AdditiveRow>> = {
+  'bone rotate': row('RotateTimeline', ['rotate'], 'bone', 'adds'),
+  'bone translate': row('TranslateTimeline', ['x', 'y'], 'bone', 'adds'),
+  'bone translatex': row('TranslateXTimeline', ['x'], 'bone', 'adds'),
+  'bone translatey': row('TranslateYTimeline', ['y'], 'bone', 'adds'),
+  'bone scale': row('ScaleTimeline', ['scaleX', 'scaleY'], 'bone', 'adds'),
+  'bone scalex': row('ScaleXTimeline', ['scaleX'], 'bone', 'adds'),
+  'bone scaley': row('ScaleYTimeline', ['scaleY'], 'bone', 'adds'),
+  'bone shear': row('ShearTimeline', ['shearX', 'shearY'], 'bone', 'adds'),
+  'bone shearx': row('ShearXTimeline', ['shearX'], 'bone', 'adds'),
+  'bone sheary': row('ShearYTimeline', ['shearY'], 'bone', 'adds'),
+  'bone inherit': row('InheritTimeline', ['inherit'], 'bone', 'writes'),
+  'slot attachment': row('AttachmentTimeline', ['attachment'], 'slot', 'writes'),
+  'slot rgba': row('RGBATimeline', ['rgb', 'alpha'], 'slot', 'writes'),
+  'slot rgb': row('RGBTimeline', ['rgb'], 'slot', 'writes'),
+  'slot alpha': row('AlphaTimeline', ['alpha'], 'slot', 'writes'),
+  'slot rgba2': row('RGBA2Timeline', ['rgb', 'alpha', 'rgb2'], 'slot', 'writes'),
+  'slot rgb2': row('RGB2Timeline', ['rgb', 'rgb2'], 'slot', 'writes'),
+  'attachment deform': row('DeformTimeline', ['deform'], 'attachment', 'adds'),
+  'attachment sequence': row('SequenceTimeline', ['sequence'], 'attachment', 'writes'),
+  ik: row('IkConstraintTimeline', ['ikConstraint'], 'constraint', 'writes'),
+  transform: row('TransformConstraintTimeline', ['transformConstraint'], 'constraint', 'adds'),
+  'path position': row('PathConstraintPositionTimeline', ['pathConstraintPosition'], 'constraint', 'adds'),
+  'path spacing': row('PathConstraintSpacingTimeline', ['pathConstraintSpacing'], 'constraint', 'writes'),
+  'path mix': row('PathConstraintMixTimeline', ['pathConstraintMix'], 'constraint', 'adds'),
+  'physics inertia': row('PhysicsConstraintInertiaTimeline', ['physicsConstraintInertia'], 'constraint', 'writes'),
+  'physics strength': row('PhysicsConstraintStrengthTimeline', ['physicsConstraintStrength'], 'constraint', 'writes'),
+  'physics damping': row('PhysicsConstraintDampingTimeline', ['physicsConstraintDamping'], 'constraint', 'writes'),
+  'physics mass': row('PhysicsConstraintMassTimeline', ['physicsConstraintMass'], 'constraint', 'writes'),
+  'physics wind': row('PhysicsConstraintWindTimeline', ['physicsConstraintWind'], 'constraint', 'adds'),
+  'physics gravity': row('PhysicsConstraintGravityTimeline', ['physicsConstraintGravity'], 'constraint', 'adds'),
+  'physics mix': row('PhysicsConstraintMixTimeline', ['physicsConstraintMix'], 'constraint', 'writes'),
+  // A reset registers its property with no constraint index, named or not (measured: both read `physicsConstraintReset`).
+  'physics reset': row('PhysicsConstraintResetTimeline', ['physicsConstraintReset'], 'none', 'writes nothing'),
+  'slider time': row('SliderTimeline', ['sliderTime'], 'constraint', 'adds'),
+  'slider mix': row('SliderMixTimeline', ['sliderMix'], 'constraint', 'adds'),
+  drawOrder: row('DrawOrderTimeline', ['drawOrder'], 'none', 'writes'),
+  events: row('EventTimeline', ['event'], 'none', 'writes nothing'),
+};
+
+/** One timeline of a document's animation, as the core reads it — enough to pose the probe. */
+export type AdditiveTimeline =
+  | { group: 'bone'; word: BoneTimelineKind; bone: string; keys: readonly CoreKey[] }
+  | { group: 'slot'; word: SlotTimelineKind; slot: string; keys: readonly CoreKey[] }
+  | { group: 'ik'; word: 'ik'; constraint: string; keys: readonly CoreIkKey[] }
+  | { group: 'transform'; word: 'transform'; constraint: string; keys: readonly CoreKey[] }
+  | { group: 'path'; word: 'position' | 'spacing' | 'mix'; constraint: string; keys: readonly CoreKey[] }
+  | { group: 'physics'; word: PhysicsTimelineKind; constraint: string; keys: readonly CoreKey[] }
+  | { group: 'slider'; word: 'time' | 'mix'; constraint: string; keys: readonly CoreKey[] }
+  | { group: 'attachment'; word: 'deform'; skin: string; slot: string; attachment: string; keys: readonly CoreDeformKey[] }
+  | { group: 'attachment'; word: 'sequence'; skin: string; slot: string; attachment: string; keys: readonly CoreSequenceKey[] }
+  | { group: 'drawOrder'; word: 'drawOrder'; keys: readonly CoreDrawOrderKey[] }
+  | { group: 'events'; word: 'events'; times: readonly number[] };
+
+/** The spelling a timeline is a row of. */
+export function additiveSpelling(t: AdditiveTimeline): string {
+  if (t.group === 'ik' || t.group === 'transform' || t.group === 'drawOrder' || t.group === 'events') return t.group;
+  return `${t.group} ${t.word}`;
+}
+
+/** One view the probe poses under: the name the runtime's skin carries (`(none)` for no skin set) and the document under it. */
+export interface AdditiveView {
+  name: string;
+  doc: CompiledDocument;
+}
+
+/** What the probe moved one field to: before either application, after one, after two — each as the pose prints it. */
+export interface AdditiveValue {
+  /** `bone:<name>.<field>`, `constraint:<name>.<field>` or `slot:<name>.deform`, the pose field's own name. */
+  field: string;
+  t: number;
+  before: string;
+  once: string;
+  twice: string;
+}
+
+/** One view under one start state: the letter the probe reads (`A` a second application moved it, `W` only the first did, `-` nothing), and the values an adding kind moved. */
+export interface AdditiveCell {
+  view: string;
+  state: 'setup' | 'displaced';
+  letter: 'A' | 'W' | '-';
+  values: AdditiveValue[];
+}
+
+/** The class the probe reads: the strongest any cell reads. */
+export type AdditiveBehaviour = 'accumulates' | 'overwrites' | 'inert';
+
+/** The probe's displacement of every number a pose holds — the validator's `PROBE_DISPLACEMENT`, exact in binary. */
+export const ADDITIVE_DISPLACEMENT = 0.375;
+
+/** A plant: rows of the table read otherwise (the core suite's `CO27`). */
+export interface AdditivePlant {
+  rows?: Readonly<Record<string, AdditiveRow>>;
+}
+
+/** Every time the probe applies a timeline at: its keys' own times, the midpoints between them, and one past the last. */
+export function additiveTimes(times: readonly number[]): number[] {
+  const between: number[] = [];
+  for (let i = 1; i < times.length; i++) between.push((times[i - 1] + times[i]) / 2);
+  return [...times, ...between, (times.length ? times[times.length - 1] : 0) + 1];
+}
+
+const spell = (v: number): string => String(v);
+const clamp01 = (v: number): number => (v < 0 ? 0 : v > 1 ? 1 : v);
+
+/** One field moved by an adding kind: its two sums from `current`. */
+function added(values: AdditiveValue[], field: string, t: number, current: number, d: number): { wrote: boolean; again: boolean } {
+  const once = current + d;
+  const twice = once + d;
+  values.push({ field, t, before: spell(current), once: spell(once), twice: spell(twice) });
+  return { wrote: spell(once) !== spell(current), again: spell(twice) !== spell(once) };
+}
+
+/** The keyed channels at `t`, the probe's times all at or after the first key. */
+function channelsAt(keys: readonly CoreKey[], t: number): number[] {
+  const i = keyIndexAt(keys, t);
+  if (i < 0) return [];
+  return keys[i].values.map((_v, c) => channelAt(keys, i, c, t));
+}
+
+/** A number written through the setup blend at alpha 1: whether it moves `current`. */
+const blendMoves = (current: number, v: number): boolean => spell(current + (v - current)) !== spell(current);
+
+/** The setup value of a bone field. */
+function boneSetup(b: ModelBone, field: 'x' | 'y' | 'rotation' | 'scaleX' | 'scaleY' | 'shearX' | 'shearY'): number {
+  return b[field] ?? (field === 'scaleX' || field === 'scaleY' ? 1 : 0);
+}
+
+const BONE_FIELDS: Readonly<Record<Exclude<BoneTimelineKind, 'inherit'>, ReadonlyArray<'x' | 'y' | 'rotation' | 'scaleX' | 'scaleY' | 'shearX' | 'shearY'>>> = {
+  rotate: ['rotation'],
+  translate: ['x', 'y'],
+  translatex: ['x'],
+  translatey: ['y'],
+  scale: ['scaleX', 'scaleY'],
+  scalex: ['scaleX'],
+  scaley: ['scaleY'],
+  shear: ['shearX', 'shearY'],
+  shearx: ['shearX'],
+  sheary: ['shearY'],
+};
+
+/** A constraint's record under a view, by kind and name. */
+function recordOf(view: CompiledDocument, kind: CoreConstraintRecord['kind'], name: string): CoreConstraintRecord | undefined {
+  return view.constraints.find((c) => c.kind === kind && c.name === name)?.record;
+}
+
+/**
+ * Whether a constraint's timelines write into its pose under a view whose
+ * active bones are `active` — the solver's rule (`constraintInactiveWhy`,
+ * `physicsActive`) except for a slider, whose timelines write whatever its dial
+ * bone is: measured, a slider dialled by a skin-required bone keyed `mix`
+ * accumulated under no skin and the default skin, where the bone is inactive,
+ * as under the skin that lists the bone. The solver leaves such a slider
+ * unapplied; whether the runtime applies it was not measured here (the
+ * header's ⚠️).
+ */
+function applies(r: CoreConstraintRecord, active: ReadonlySet<string>): boolean {
+  if (r.kind === 'physics') return physicsActive(r, active);
+  const why = constraintInactiveWhy(r, active);
+  return why === null || (r.kind === 'slider' && why !== 'skin');
+}
+
+/** The fields an adding constraint timeline moves, with their setup values. */
+function constraintFields(t: AdditiveTimeline, r: CoreConstraintRecord): Array<{ field: string; setup: number; channel: number }> {
+  if (t.group === 'transform' && r.kind === 'transform') return TRANSFORM_PROPERTIES.map((p, channel) => ({ field: TRANSFORM_MIXES[p], setup: r.mixes[p], channel }));
+  if (t.group === 'path' && r.kind === 'path') {
+    if (t.word === 'position') return [{ field: 'position', setup: r.position, channel: 0 }];
+    if (t.word === 'mix') return [{ field: 'mixRotate', setup: r.mixRotate, channel: 0 }, { field: 'mixX', setup: r.mixX, channel: 1 }, { field: 'mixY', setup: r.mixY, channel: 2 }];
+    return [{ field: 'spacing', setup: r.spacing, channel: 0 }];
+  }
+  if (t.group === 'physics' && r.kind === 'physics' && t.word !== 'reset') {
+    if (t.word === 'mass') return [{ field: 'massInverse', setup: r.massInverse, channel: 0 }];
+    return [{ field: t.word, setup: r[t.word], channel: 0 }];
+  }
+  if (t.group === 'slider' && r.kind === 'slider') return [{ field: t.word, setup: r[t.word], channel: 0 }];
+  if (t.group === 'ik' && r.kind === 'ik') return [{ field: 'mix', setup: r.mix, channel: 0 }, { field: 'softness', setup: r.softness, channel: 1 }];
+  return [];
+}
+
+/** The vertices a shown record's deform array is computed on: its own, or a linked mesh's source's. */
+function deformVertices(view: CompiledDocument, record: CoreAttachment): ModelVertices | null {
+  const g = record.geometry;
+  if (g === undefined) return null;
+  const source = g.kind === 'linkedmesh' ? view.skins.find((k) => k.name === g.skin)?.attachments[g.slot]?.[g.source]?.geometry : g;
+  return source !== undefined && source.kind !== 'region' && source.kind !== 'linkedmesh' ? source.vertices : null;
+}
+
+/** One view, one start state: the letter and the values (the header's cells). */
+function cellOf(view: AdditiveView, state: 'setup' | 'displaced', t: AdditiveTimeline, mode: AdditiveMode): AdditiveCell {
+  const doc = view.doc;
+  const active = activeBones(doc);
+  const shift = state === 'setup' ? 0 : ADDITIVE_DISPLACEMENT;
+  const values: AdditiveValue[] = [];
+  let wrote = false;
+  let again = false;
+  const note = (r: { wrote: boolean; again: boolean }): void => {
+    wrote ||= r.wrote;
+    again ||= r.again;
+  };
+  const times = additiveTimes(t.group === 'events' ? t.times : t.keys.map((k) => k.time));
+  const done = (): AdditiveCell => ({ view: view.name, state, letter: again ? 'A' : wrote ? 'W' : '-', values });
+  if (mode === 'writes nothing') return done();
+  switch (t.group) {
+    case 'bone': {
+      const b = doc.bones.find((x) => x.name === t.bone);
+      if (b === undefined || !active.has(b.name)) return done();
+      if (t.word === 'inherit') {
+        // The displaced pose holds the mode's number plus 0.375, which no mode is; the setup pose holds the setup mode.
+        const setup = foldInheritMode(b.inheritMode ?? 'normal') ?? 'normal';
+        for (const time of times) {
+          const i = keyIndexAt(t.keys, time);
+          if (i < 0) continue;
+          if (state === 'displaced' || t.keys[i].mode !== setup) wrote = true;
+        }
+        return done();
+      }
+      const fields = BONE_FIELDS[t.word];
+      for (const time of times) {
+        const v = channelsAt(t.keys, time);
+        fields.forEach((field, c) => {
+          const setup = boneSetup(b, field);
+          const d = mode === 'adds' ? (field === 'scaleX' || field === 'scaleY' ? v[c] * setup - setup : v[c]) : Number.NaN;
+          if (mode === 'adds') note(added(values, `bone:${b.name}.${field}`, time, setup + shift, d));
+          else note({ wrote: blendMoves(setup + shift, v[c]), again: false });
+        });
+      }
+      return done();
+    }
+    case 'slot': {
+      const slot = doc.slots.find((s) => s.name === t.slot);
+      if (slot === undefined || !slotTimelinesApply(doc, slot, active)) return done();
+      if (t.word === 'attachment') {
+        const nameShown = (placeholder: string | null): string | null => {
+          if (placeholder === null) return null;
+          const s = shownAttachment(doc, { ...slot, setup: placeholder });
+          return s === null || 'conflict' in s ? null : shownRow(s).name;
+        };
+        // The setup pose shows the setup attachment; the displaced pose shows nothing.
+        const current = state === 'setup' ? nameShown(slot.setup) : null;
+        for (const time of times) {
+          const i = keyIndexAt(t.keys, time);
+          if (i >= 0 && nameShown(t.keys[i].name ?? null) !== current) wrote = true;
+        }
+        return done();
+      }
+      const shape = SLOT_COLOUR_TIMELINES[t.word];
+      const light = readColour(slot.color ?? 'ffffffff');
+      const dark = slot.dark === undefined ? null : readColour(slot.dark);
+      for (const time of times) {
+        const v = channelsAt(t.keys, time);
+        shape.channels.forEach((channel: string, c: number) => {
+          const second = channel.endsWith('2');
+          const at = ['r', 'g', 'b', 'a'].indexOf(second ? channel.slice(0, 1) : channel);
+          const setup = second ? (dark === null ? Number.NaN : dark[at]) : light[at];
+          if (spell(clamp01(v[c])) !== spell(setup + shift)) wrote = true;
+        });
+      }
+      return done();
+    }
+    case 'attachment': {
+      // The displaced pose shows nothing on any slot, and both timelines are gated on what a slot shows.
+      if (state === 'displaced') return done();
+      const identity = `${t.skin}/${t.slot}/${t.attachment}`;
+      for (const slot of doc.slots) {
+        if (!slotTimelinesApply(doc, slot, active)) continue;
+        const shown = shownAttachment(doc, slot);
+        if (shown === null || 'conflict' in shown || timelineIdentity(slot.name, shown) !== identity) continue;
+        if (t.word === 'sequence') {
+          if (shown.record.sequenceCount !== undefined && t.keys.length > 0) wrote = true;
+          continue;
+        }
+        const vertices = deformVertices(doc, shown.record);
+        if (vertices === null) continue;
+        for (const time of times) {
+          const target = deformAt(vertices, t.keys, time);
+          if (target === null) continue;
+          // From no deform, the additive blend at alpha 1 is the target (`blendDeform`); a second one adds `target − setup` to it.
+          const once = blendDeform(vertices, null, target, 1, true);
+          const twice = blendDeform(vertices, once, target, 1, true);
+          values.push({ field: `slot:${slot.name}.deform`, t: time, before: '[]', once: `[${once.join(',')}]`, twice: `[${twice.join(',')}]` });
+          wrote = true;
+          if (once.join(',') !== twice.join(',')) again = true;
+        }
+      }
+      return done();
+    }
+    case 'drawOrder': {
+      const count = doc.slots.length;
+      const setup = Array.from({ length: count }, (_v, i) => i);
+      const current = state === 'setup' ? setup : [...setup.slice(1), ...setup.slice(0, 1)];
+      for (const time of times) {
+        const order = drawOrderAt(count, t.keys, time);
+        if (order !== null && order.join(',') !== current.join(',')) wrote = true;
+      }
+      return done();
+    }
+    case 'events':
+      // A kind that writes moves the pose; an event timeline under a slider fires nothing (the table's mode), so only a plant reaches this.
+      if (mode === 'writes') wrote = true;
+      return done();
+    default: {
+      const records: CoreConstraintRecord[] =
+        t.group === 'physics' && t.constraint === EVERY_GLOBAL_PHYSICS
+          ? unnamedPhysicsTargets(
+              doc.constraints.flatMap((c): CorePhysicsRecord[] => (c.record?.kind === 'physics' ? [c.record] : [])),
+              t.word,
+              (r) => physicsActive(r, active),
+            )
+          : [recordOf(doc, t.group, t.constraint)].filter((r): r is CoreConstraintRecord => r !== undefined && applies(r, active));
+      for (const r of records) {
+        // A kind that writes with no field of its own to compare — only a plant makes a `reset` one — moves the pose wherever it applies.
+        if (t.group === 'physics' && t.word === 'reset' && mode === 'writes') wrote = true;
+        const fields = constraintFields(t, r);
+        for (const time of times) {
+          const v = channelsAt(t.keys, time);
+          for (const { field, setup, channel } of fields) {
+            const current = setup + shift;
+            if (mode === 'adds') note(added(values, `constraint:${r.name}.${field}`, time, current, v[channel]));
+            // A mass is keyed as a mass and posed as its inverse.
+            else if (field === 'massInverse') note({ wrote: spell(1 / (1 / current + (v[channel] - 1 / current))) !== spell(current), again: false });
+            else note({ wrote: blendMoves(current, v[channel]), again: false });
+          }
+          // An ik key's flags: the displaced pose moved the bend direction (a number); the setup pose holds the setup flags.
+          if (t.group === 'ik' && r.kind === 'ik') {
+            const i = keyIndexAt(t.keys, time);
+            const flags = i < 0 ? undefined : t.keys[i].flags;
+            if (flags !== undefined && (state === 'displaced' || flags.bendPositive !== r.bendPositive || flags.compress !== r.compress || flags.stretch !== r.stretch)) wrote = true;
+          }
+        }
+      }
+      return done();
+    }
+  }
+}
+
+/** Every cell of the probe over `views` — each view under the setup state, then the displaced one. */
+export function additiveCells(views: readonly AdditiveView[], t: AdditiveTimeline, plant: AdditivePlant = {}): AdditiveCell[] {
+  const rows = plant.rows ?? ADDITIVE_APPLY;
+  const spelled = additiveSpelling(t);
+  const r = rows[spelled];
+  if (r === undefined) throw new Error(`internal: "${spelled}" is no row of the additive table`);
+  return views.flatMap((view) => [cellOf(view, 'setup', t, r.mode), cellOf(view, 'displaced', t, r.mode)]);
+}
+
+/** The class the probe reads over its cells: `accumulates` where any cell does, `overwrites` where any cell only wrote, `inert` otherwise. */
+export function additiveBehaviour(cells: readonly AdditiveCell[]): AdditiveBehaviour {
+  if (cells.some((c) => c.letter === 'A')) return 'accumulates';
+  return cells.some((c) => c.letter === 'W') ? 'overwrites' : 'inert';
+}
+

package/src/core/constraints.ts

@@ -1402,12 +1402,22 @@ function solveTransform(state: SolverState, c: CoreTransformRecord): { changed:
 
 /** Why a constraint is not applied under the skin view posed (the header's measured rule), or null when it is. */
 function inactiveWhy(state: SolverState, c: CoreConstraintRecord): string | null {
+  return constraintInactiveWhy(c, state.active, state.rules);
+}
+
+/**
+ * Why a constraint is not applied under a skin view whose active bones are
+ * `active` (the header's measured rule), or null when it is — `inactiveWhy`'s
+ * reading, exported so the additive probe (`./additive.ts`, issue #1025) asks
+ * the rule the solver applies rather than a copy of it.
+ */
+export function constraintInactiveWhy(c: CoreConstraintRecord, active: ReadonlySet<string>, rules: Readonly<SolverRules> = RUNTIME_SOLVER_RULES): string | null {
   // A skin-required constraint of any kind is applied when an applied skin's list for its kind names it (issue #932, card #961; physics first by issue #956).
   if (c.skin && !c.listedBySkin) return 'skin';
   // A path constraint is active when its slot's bone is (`./constraints_path.ts`, *Which constraints run*); every other kind when every bone it names is.
   // A transform constraint is applied when its source is, to every bone it names, inactive ones included (issue #979: an inactive bone among them did not stop it moving the others, and it wrote into the inactive one). An ik naming an inactive bone is left unapplied: the runtime applies it from ancestors it has not brought up to date (the header's *Unposed bones*).
-  const named = c.kind === 'path' ? [c.slotBone] : c.kind === 'ik' ? (state.rules.ikOverInactiveFresh ? [c.target] : [...c.bones, c.target]) : c.kind === 'transform' ? (state.rules.transformIgnoresBoneActivity ? [c.source] : [...c.bones, c.source]) : c.kind === 'slider' ? (c.bone === null ? [] : [c.bone]) : [c.bone];
-  return named.every((n) => state.active.has(n)) ? null : 'inactive bone';
+  const named = c.kind === 'path' ? [c.slotBone] : c.kind === 'ik' ? (rules.ikOverInactiveFresh ? [c.target] : [...c.bones, c.target]) : c.kind === 'transform' ? (rules.transformIgnoresBoneActivity ? [c.source] : [...c.bones, c.source]) : c.kind === 'slider' ? (c.bone === null ? [] : [c.bone]) : [c.bone];
+  return named.every((n) => active.has(n)) ? null : 'inactive bone';
 }
 
 /**