spine-html 1.13.0 → 1.14.0

package/README.md

@@ -685,6 +685,77 @@ firing events or drawing. A non-finite value, a bone the document does not have,
 or an error the function throws refuses that step in the core's words, and the
 track is reopened by the next `play` or `seek`.
 
+The callback also receives a `BoneAdjustContext` from the core:
+
+```ts
+player.adjust = (bones, ctx) => {
+  bones.bone('head').rotation = 12 * (ctx.trackTime ?? 0);
+};
+```
+
+`ctx.trackTime` is the **current track-0 entry's unwrapped seconds**, starting at
+0 for each new entry. Loops do not wrap it, and a nonlooping entry keeps counting
+past its duration. `ctx.animation` names that entry. Without a track-0 entry both
+are null; an explicit empty entry has **numeric trackTime and null animation**.
+Upper tracks supply no fallback. `ctx.globalTime` is the core walk's running sum
+of steps in seconds, so it can differ from a new entry's time. Neither clock is
+wall time, wrapped animation time, nor the physics clock's small lead. Unary
+callbacks remain compatible. The hook runs once after composition, including a
+crossfade, rather than once for each contributing entry.
+
+Seek evaluates its replay times (`seekStep` plus any final remainder), independent
+of the currently displayed player time. Exact cache hits may reuse a pose without
+calling the hook. A continuous walk and seek are bit-identical for an **unchanged
+patch and matched history**: the same animation, environment, adjustment, reset
+and step partition. Closed-over callback state still needs `repose()` or the
+adjust setter to invalidate cached poses. Pause, zero advance and renderer mode
+changes add no evaluations; explicit `repose()` keeps the same context time.
+
+### Live physics parameters
+
+```ts
+player.play('hang');
+player.setPhysicsParameters('link_1_phys', { damping: 0.4, wind: 8 });
+player.readPhysicsParameters('link_1_phys'); // { override, effective }
+player.clearPhysicsParameters('link_1_phys');
+```
+
+`setPhysicsParameters(name, patch)` forwards a per-player patch of `strength`,
+`damping`, `inertia`, `wind`, `gravity`, and `mix` to the core. Omitted fields keep
+their standing override. Values are runtime scalars with no clamping, conversion,
+new clock or solver. The core applies them **after authored/keyed values and
+sliders, before the integrator**. Unknown constraints, a non-physics constraint,
+unknown fields and non-finite/non-number values are refused atomically by name.
+These methods require a live track: before `play`/`queue`, set, read and clear
+refuse with `no live track` instead of creating one. The model and other players
+sharing its assets are untouched.
+
+`PhysicsParameterRead` contains detached readonly snapshots: `override` is the
+pending patch or null; `effective` is the six values from the last active
+evaluation, or null until evaluated. An inactive constraint can retain its last
+active values within that live core instance. Setting or clearing changes no
+pose, time or physics state, and **does not evaluate**: effective keeps the last
+values until a normal evaluation (or an explicitly requested `repose()`). Clear
+removes the patch; authored keys resume at the next evaluation. It preserves
+integrated history and does not instantly undo the motion caused by old values.
+
+The player retains the **current standing patch** across new play, seek, skin
+replay and promotion to composed tracks. Like `environment()`, it records no
+historical changes. **After a mid-run patch change, a backward seek recomputes the
+past interval with the patch standing now**, under the current environment; it
+does not reproduce the old trajectory across that change. New single tracks and
+new composed tracks first evaluate their ordinary authored first pose, then
+receive the standing patch as pending, with no extra adjustment callback. At
+seek time 0, effective can therefore still be the initial authored value while
+override already reports the patch. The next normal core evaluation uses it.
+Changing entries on existing composed tracks follows that core instance's
+lifetime. Existing seek/skin restrictions after composition remain unchanged.
+
+Set/clear invalidate seek caches without re-posing. Seek snapshots retain the
+public effective read alongside their held pose, so backward and exact cache
+hits report that pose's evaluation rather than the frontier's latest evaluation.
+Readback itself never advances, evaluates or resets physics.
+
 ### One load, several players
 
 One `loadModel` backs any number of players: the regions are cut once, and
@@ -1043,8 +1114,9 @@ name, and unloading is still elements first, bitmaps second.
 | dark (two-colour) tint: unsupported | `DomRenderer`: unsupported. `CanvasRenderer`: drawn | Carried as `dark` on a `PosedSlot`. The canvas mode's canvas2d fallback draws alpha only. |
 | `renderer.dispose()` | `player.dispose()` | Then `assets.dispose()`, as before. `DomRenderer.dispose()` and `CanvasRenderer.dispose()` exist for a renderer you constructed yourself. |
 | `skeleton.findBone('head').worldX`, `.worldY`, `.a` … `.d` | `player.bone('head')` | `{ x, y, a, b, c, d, rotationX, rotationY, scaleX, scaleY, active }`, the core's world transform for the pose the player holds (the setup pose before `play`). An unknown name is refused by name. Since 1.1.0. |
-| `bone.scaleY = …` on a `Skeleton` between `state.apply` and `updateWorldTransform` | `RigPlayerOptions.adjust`, `player.adjust`, `player.repose()` | A function called once per pose with the pose's bone locals (`bones.bone('mouth').scaleY = v`). A write lasts one pose: the core poses every step from the setup pose, so write the value you want, every pose — nothing compounds. See *Adjusting bones*. Since 1.2.0. |
+| `bone.scaleY = …` on a `Skeleton` between `state.apply` and `updateWorldTransform` | `RigPlayerOptions.adjust`, `player.adjust`, `player.repose()` | A function `(bones, ctx)` called once per pose with the pose's bone locals and current-entry context (unary callbacks remain valid) (`bones.bone('mouth').scaleY = v`). A write lasts one pose: the core poses every step from the setup pose, so write the value you want, every pose — nothing compounds. See *Adjusting bones*. Since 1.2.0. |
 | `skeleton.getBounds(offset, size)` | `player.bounds()` | `{ x, y, width, height }` or null, world units, Y up: the box of every drawn region's corners and mesh's vertices, a slot under a clip counted inside the clip's own box. `ModelAssets.stage` remains the declared framing, not this box. Since 1.1.0. |
+| live named physics constraint tuning | `player.setPhysicsParameters(name, patch)`, `readPhysicsParameters(name)`, `clearPhysicsParameters(name)` | Six scalar fields, per-player pending patch plus last evaluated effective values. Clear resumes authored values without resetting history. Replay uses the current standing patch, with no historical journal. See *Live physics parameters*. |
 | named setup mesh geometry | `readSetupMesh(assets, { slot, attachment, skin? })` | Detached full-double world x/y (Y up), triangles and hull for any named mesh/linked mesh, including non-setup selections; no player/time mutation. Selected geometry includes setup-slider deform; unselected geometry is stored geometry through unchanged setup matrices. See the measured official-runtime distinction under *Reading the pose*. |
 
 ### No counterpart in 1.0.0

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export { type CanvasBackend, CanvasRenderer, type CanvasViewport } from './Canva
 export { DomRenderer, type MeshBackend, type MeshSourceRect } from './DomRenderer.js';
 export { type PageLayout, type PageRegion, type RegionEncoding, type RegionImage, revokeRegions, type UnpackRegionsOptions, unpackRegions } from './DomTexture.js';
 export { type LoadModelOptions, loadModel, type ModelAssets, type ModelDocument, readSetupMesh, type RegionLoading, type RigSet, type SetupMesh, type SetupMeshTarget } from './loadModel.js';
-export { type AdjustableBones, type BoneAdjust, type BoneLocals, type BoneWorld, type PlayOptions, type PoseBounds, type QueueOptions, type RenderMode, type RigComplete, type RigEnvironment, type RigEvent, RigPlayer, type RigPlayerOptions, type SlotFilter, type SlotIdentity, type SlotIdentityReason, type SlotIdentitySnapshot, type TrackEntry } from './player.js';
+export { type AdjustableBones, type BoneAdjust, type BoneAdjustContext, type BoneLocals, type BoneWorld, type PhysicsParameters, type PhysicsParameterPatch, type PhysicsParameterRead, type PlayOptions, type PoseBounds, type QueueOptions, type RenderMode, type RigComplete, type RigEnvironment, type RigEvent, RigPlayer, type RigPlayerOptions, type SlotFilter, type SlotIdentity, type SlotIdentityReason, type SlotIdentitySnapshot, type TrackEntry } from './player.js';
 export type { BlendMode, PosedClip, PosedFrame, PosedMesh, PosedRegion, PosedSlot, } from './posedFrame.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACtF,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnK,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9L,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,KAAK,oBAAoB,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC7W,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACtF,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnK,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9L,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,KAAK,oBAAoB,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACpd,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -436,23 +436,23 @@ function slotSwitches(slots, slot) {
   }
   return index.get(slot);
 }
-function applyAttachment(now, values, timelines, t, blend, evalDeform, blendOf2, evalFrame) {
-  if (now === null || now.identity === null) return values;
+function applyAttachment(now, values2, timelines, t, blend, evalDeform, blendOf2, evalFrame) {
+  if (now === null || now.identity === null) return values2;
   const matching = matchingAttachments(timelines, now.identity);
-  if (matching === void 0) return values;
-  values ??= { deform: null, frame: null, seen: [] };
-  if (!values.seen.includes(now.identity)) values.seen.push(now.identity);
+  if (matching === void 0) return values2;
+  values2 ??= { deform: null, frame: null, seen: [] };
+  if (!values2.seen.includes(now.identity)) values2.seen.push(now.identity);
   for (const a of matching) {
     if (a.deform !== null && now.vertices !== null) {
       const target = evalDeform(now.vertices, a.deform, t);
-      if (target !== null) values.deform = blend === null ? target : blendOf2(now.vertices, values.deform, target, blend.alpha, blend.additive);
+      if (target !== null) values2.deform = blend === null ? target : blendOf2(now.vertices, values2.deform, target, blend.alpha, blend.additive);
     }
     if (a.sequence !== null && now.count !== void 0) {
       const f = evalFrame(a.sequence, now.count, t);
-      if (f !== null) values.frame = f;
+      if (f !== null) values2.frame = f;
     }
   }
-  return values;
+  return values2;
 }
 function attachmentStates(doc, resolve, placeholders, sample, sliders, plant = {}, mixed) {
   const evalDeform = plant.deform ?? deformAt;
@@ -466,9 +466,9 @@ function attachmentStates(doc, resolve, placeholders, sample, sliders, plant = {
     const live = gate(doc, slot, active);
     let placeholder = placeholders.get(slot.name) ?? null;
     const base = live ? mixed?.get(slot.name) : void 0;
-    let values = base === void 0 || base.deform === null && base.seen.length === 0 ? null : { deform: base.deform, frame: null, seen: [...base.seen] };
+    let values2 = base === void 0 || base.deform === null && base.seen.length === 0 ? null : { deform: base.deform, frame: null, seen: [...base.seen] };
     let now = identityOf(doc, resolve, slot, placeholder);
-    if (sample !== null && live) values = applyAttachment(now, values, sample.timelines.attachments, sample.t, null, evalDeform, blendOf2, evalFrame);
+    if (sample !== null && live) values2 = applyAttachment(now, values2, sample.timelines.attachments, sample.t, null, evalDeform, blendOf2, evalFrame);
     if (live) for (const app of sliders) {
       const switches = slotSwitches(app.timelines.slots, slot.name);
       if (switches !== void 0) for (const keys of switches) {
@@ -476,26 +476,26 @@ function attachmentStates(doc, resolve, placeholders, sample, sliders, plant = {
         if (i < 0) continue;
         const next = keys[i].name ?? null;
         if (next !== placeholder) {
-          if (values !== null) {
-            values.deform = null;
-            values.frame = null;
+          if (values2 !== null) {
+            values2.deform = null;
+            values2.frame = null;
           }
           placeholder = next;
           now = identityOf(doc, resolve, slot, placeholder);
         }
       }
-      values = applyAttachment(now, values, app.timelines.attachments, app.at, app, evalDeform, blendOf2, evalFrame);
+      values2 = applyAttachment(now, values2, app.timelines.attachments, app.at, app, evalDeform, blendOf2, evalFrame);
     }
     if (now === null) continue;
-    const entry = values === null || values.deform === null && values.frame === null ? now.entry : { ...now.entry };
+    const entry = values2 === null || values2.deform === null && values2.frame === null ? now.entry : { ...now.entry };
     shown.push(entry);
-    if (values !== null && values.seen.length > 0 && now.fillers.length > 1) {
-      why.push(`slot "${slot.name}" shows placeholder "${now.entry.placeholder}", which skins ${now.fillers.join(", ")} fill, and ${values.seen.map((x) => `"${x}"`).join(", ")} key(s) it — which record --skin all shows, and so whether the timeline moves it, is the Spine file's skin order, not the model's`);
+    if (values2 !== null && values2.seen.length > 0 && now.fillers.length > 1) {
+      why.push(`slot "${slot.name}" shows placeholder "${now.entry.placeholder}", which skins ${now.fillers.join(", ")} fill, and ${values2.seen.map((x) => `"${x}"`).join(", ")} key(s) it — which record --skin all shows, and so whether the timeline moves it, is the Spine file's skin order, not the model's`);
       continue;
     }
-    if (values !== null) {
-      if (values.deform !== null) entry.deform = values.deform;
-      if (values.frame !== null) entry.frame = values.frame;
+    if (values2 !== null) {
+      if (values2.deform !== null) entry.deform = values2.deform;
+      if (values2.frame !== null) entry.frame = values2.frame;
     }
   }
   return { shown, why };
@@ -1236,16 +1236,16 @@ function readPathGeometry(raw, vertices, where, problems) {
   if (problems.length !== before) return void 0;
   return { kind: "path", vertices, closed: raw.closed === true, constantSpeed: raw.constantSpeed !== false, lengths };
 }
-function roundedRow(values, round) {
-  for (let i = 0; i < values.length; i++) {
-    const r = round(values[i]);
-    if (Object.is(r, values[i])) continue;
-    const out = values.slice(0, i);
+function roundedRow(values2, round) {
+  for (let i = 0; i < values2.length; i++) {
+    const r = round(values2[i]);
+    if (Object.is(r, values2[i])) continue;
+    const out = values2.slice(0, i);
     out.push(r);
-    for (let j = i + 1; j < values.length; j++) out.push(round(values[j]));
+    for (let j = i + 1; j < values2.length; j++) out.push(round(values2[j]));
     return out;
   }
-  return values;
+  return values2;
 }
 function poseGeometry(shown, world, sourceOf, round, plant = {}, draw) {
   const region = plant.region ?? regionCorners;
@@ -3431,7 +3431,8 @@ function applyConstraints(bones, world, active, records, previous = null, applie
     if (c.kind === "physics") {
       if (physics !== void 0) {
         const w = { ...state.world.get(c.bone) };
-        const posed = physicsPose?.records.get(c.name) ?? c;
+        const authored = physicsPose?.records.get(c.name) ?? c;
+        const posed = physics.parameters?.apply(authored) ?? authored;
         if ((physics.step ?? stepPhysics)(posed, w, bone(state, c.bone).length ?? 0, physics)) {
           state.world.set(c.bone, w);
           changed = [c.bone];
@@ -3712,7 +3713,7 @@ function readBoneTimeline(kind, keysValue, where, problems) {
     }
     const channels = BONE_TIMELINE_CHANNELS[kind];
     unknownKeyFields(raw, ["time", ...channels, "curve"], at, problems);
-    const values = channels.map((c) => {
+    const values2 = channels.map((c) => {
       const v = raw[c];
       if (typeof v !== "number" || !Number.isFinite(v)) {
         problems.push(`${at}: ${c} is ${JSON.stringify(v)}, not a finite number — the writer states every channel on every key`);
@@ -3720,7 +3721,7 @@ function readBoneTimeline(kind, keysValue, where, problems) {
       }
       return v;
     });
-    return { time: Math.fround(time), values: values.map(Math.fround), stated: { time, values }, curve: readCurve(raw, channels.length, i === listed.length - 1, at, problems) };
+    return { time: Math.fround(time), values: values2.map(Math.fround), stated: { time, values: values2 }, curve: readCurve(raw, channels.length, i === listed.length - 1, at, problems) };
   });
 }
 function hexChannels(hex, count) {
@@ -3737,22 +3738,22 @@ function readSlotTimeline(kind, keysValue, where, problems) {
       return { time: Math.fround(time), values: [], stated: { time, values: [] }, curve: "stepped", name: typeof raw.name === "string" ? raw.name : null };
     }
     const shape = SLOT_COLOUR_TIMELINES[kind];
-    let values = [];
+    let values2 = [];
     if (kind === "alpha") {
       unknownKeyFields(raw, ["time", "value", "curve"], at, problems);
       const v = raw.value;
       if (typeof v !== "number" || !Number.isFinite(v)) problems.push(`${at}: value is ${JSON.stringify(v)}, not a finite number`);
-      else values = [v];
+      else values2 = [v];
     } else {
       unknownKeyFields(raw, ["time", ...shape.fields.map(([f]) => f), "curve"], at, problems);
       for (const [field, digits] of shape.fields) {
         const v = raw[field];
         if (!isHex(v, digits)) problems.push(`${at}: ${field} is ${JSON.stringify(v)}, not ${digits} hex digits — the one spelling the writer gives a ${kind} key's ${field}`);
-        else values.push(...hexChannels(v, field === "dark" || digits === 6 ? 3 : 4));
+        else values2.push(...hexChannels(v, field === "dark" || digits === 6 ? 3 : 4));
       }
     }
-    if (values.length !== shape.channels.length) values = shape.channels.map(() => 0);
-    return { time: Math.fround(time), values: values.map(Math.fround), stated: { time, values }, curve: readCurve(raw, shape.channels.length, i === listed.length - 1, at, problems) };
+    if (values2.length !== shape.channels.length) values2 = shape.channels.map(() => 0);
+    return { time: Math.fround(time), values: values2.map(Math.fround), stated: { time, values: values2 }, curve: readCurve(raw, shape.channels.length, i === listed.length - 1, at, problems) };
   });
 }
 function constraintKeyTimes(value, where, problems) {
@@ -4048,7 +4049,7 @@ class StepLocals {
     this.write("shearY", v);
   }
 }
-function adjustLocals(doc, bones, adjust) {
+function adjustLocals(doc, bones, adjust, context) {
   const views = /* @__PURE__ */ new Map();
   const names = doc.bones.map((b) => b.name);
   adjust({
@@ -4063,7 +4064,7 @@ function adjustLocals(doc, bones, adjust) {
       }
       return view;
     }
-  });
+  }, context);
 }
 const clamp01$1 = (v) => v < 0 ? 0 : v > 1 ? 1 : v;
 function posedSlots(doc, timelines, t, plant = {}, sliders = [], placeholders) {
@@ -4150,7 +4151,7 @@ function posedBoneStep(doc, timelines, t, plant, constraints, sliders, step) {
   const bones = posedBones(doc, timelines, t, plant);
   if (constraints !== void 0 && step !== void 0) return steppedLocals(doc, bones, plant, () => pathDeformed(doc, posedRecords(constraintRecords(doc), constraints, t), timelines, t, plant), constraints.physicsKeyed ?? [], t, sliders, step);
   const active = activeBones(doc);
-  if (step?.adjust !== void 0) adjustLocals(doc, bones, step.adjust);
+  if (step?.adjustment !== void 0) adjustLocals(doc, bones, step.adjustment.callback, step.adjustment.context);
   let world = (plant.evaluate ?? worldTransforms)(bones, active);
   if (constraints !== void 0) {
     const setupRecords = constraintRecords(doc);
@@ -4163,7 +4164,7 @@ function posedBoneStep(doc, timelines, t, plant, constraints, sliders, step) {
 }
 function steppedLocals(doc, bones, plant, records, physicsKeyed, t, sliders, step) {
   const active = activeBones(doc);
-  if (step.adjust !== void 0) adjustLocals(doc, bones, step.adjust);
+  if (step.adjustment !== void 0) adjustLocals(doc, bones, step.adjustment.callback, step.adjustment.context);
   let world = (plant.evaluate ?? worldTransforms)(bones, active);
   const stepped = stepPhysicsRecords(records(), physicsKeyed, t, active, step.ctx, step.before);
   world = applyConstraints(bones, world, active, plant.constraints ? plant.constraints(stepped) : stepped, null, sliders, step.ctx, void 0, solverRules(plant.solver));
@@ -5021,11 +5022,11 @@ function drawnGeometry(doc, shown, world, order, plant, mode) {
   if (geometry.drawnClipped === null) throw new CoreInputError(`the raw pose leaves the clipped triangles out: ${geometry.drawnClippedWhy}`);
   return { rows: geometry.attachments, clips: geometry.clips, drawnClipped: geometry.drawnClipped };
 }
-function numbersOf(values, what, mode) {
-  return allNumbers(values) ? values : values.map((v) => numberOf(v, what, mode));
+function numbersOf(values2, what, mode) {
+  return allNumbers(values2) ? values2 : values2.map((v) => numberOf(v, what, mode));
 }
-function allNumbers(values) {
-  for (const v of values) if (v === null) return false;
+function allNumbers(values2) {
+  for (const v of values2) if (v === null) return false;
   return true;
 }
 function rawDrawn(doc, shown, world, order, plant, mode = RAW_MODE) {
@@ -5171,6 +5172,7 @@ function openWalk(doc, anim, plant, reset, mode, shape, adjust, before) {
   const why = constraintsAbsentWhy(doc) ?? pathAnimationsWhy(doc) ?? steppedPreviousPassWhy(doc);
   if (why !== null) throw new CoreInputError(`the raw walk leaves the bones out: ${why}`);
   const ctx = freshStepContext(plant.physicsStep);
+  before?.(ctx);
   if (mode.loop && mode.wrapResets !== false) ctx.loop = true;
   const track = { doc, anim, duration: anim.timelines.duration, mode, plant, raw: { ...plant, ...roundPlant(mode) }, resolve: plant.shown ?? shownAttachment, shape, ctx, adjust, trackTime: 0, last: -1 };
   if (reset === "setup") {
@@ -5193,8 +5195,9 @@ function stepWalk(track, dt, first = false) {
   ctx.time += mode.clock === void 0 ? dt : mode.clock(dt, t - (first ? 0 : Math.max(last, 0)));
   const fire = plant.events ?? eventsFired;
   const keys = anim.timelines.events;
+  const adjustment = adjust === void 0 ? void 0 : { callback: adjust, context: { trackTime, animation: anim.name, globalTime: trackTime } };
   const pose = poseStepFrom(doc, plant, resolve, shape, mode, ctx, first, trackTime, t, {
-    world: (sliders) => shape.rows ? posedBoneWorld(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before, adjust }).world : posedBoneWorldAlone(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before, adjust }),
+    world: (sliders) => shape.rows ? posedBoneWorld(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before, adjustment }).world : posedBoneWorldAlone(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before, adjustment }),
     slots: (sliders, placeholders) => posedSlots(doc, anim.timelines, t, raw, sliders, placeholders),
     drawOrder: anim.timelines.drawOrder,
     at: t,
@@ -5242,12 +5245,56 @@ function openRawTracksPath(doc, plant) {
     step: (first, trackTime, animationTime, posers) => poseStepFrom(doc, plant, resolve, RAW_SHAPE, RAW_MODE, ctx, first, trackTime, animationTime, posers)
   };
 }
-function openRawTrack(doc, animation, plant, reset, mode, adjust) {
-  return openWalk(doc, animationOf(doc, animation), plant, reset, mode, RAW_SHAPE, adjust);
+function openRawTrack(doc, animation, plant, reset, mode, adjust, before) {
+  return openWalk(doc, animationOf(doc, animation), plant, reset, mode, RAW_SHAPE, adjust, before);
 }
 function stepRawTrack(track, dt) {
   return stepWalk(track, dt);
 }
+const FIELDS = ["strength", "damping", "inertia", "wind", "gravity", "mix"];
+const values = (r) => ({ strength: r.strength, damping: r.damping, inertia: r.inertia, wind: r.wind, gravity: r.gravity, mix: r.mix });
+class LivePhysicsParameters {
+  constructor(doc) {
+    this.doc = doc;
+    this.overrides = /* @__PURE__ */ new Map();
+    this.evaluated = /* @__PURE__ */ new Map();
+  }
+  named(name) {
+    const constraint = this.doc.constraints.find((c) => c.name === name);
+    if (constraint === void 0) throw new CoreInputError(`physics parameters: no constraint "${String(name)}"; this document declares [${this.doc.constraints.map((c) => c.name).join(", ")}]`);
+    if (constraint.kind !== "physics") throw new CoreInputError(`physics parameters: constraint "${name}" is ${constraint.kind}, not physics`);
+  }
+  set(name, patch) {
+    this.named(name);
+    if (typeof patch !== "object" || patch === null || Array.isArray(patch)) throw new CoreInputError(`physics parameters: constraint "${name}" patch is ${String(patch)}, not an object of finite fields [${FIELDS.join(", ")}]`);
+    const checked = {};
+    for (const key of Reflect.ownKeys(patch)) {
+      if (typeof key !== "string" || !FIELDS.includes(key)) throw new CoreInputError(`physics parameters: constraint "${name}" field "${String(key)}" is unknown; expected [${FIELDS.join(", ")}]`);
+      const field = key;
+      const value = patch[field];
+      if (typeof value !== "number" || !Number.isFinite(value)) throw new CoreInputError(`physics parameters: constraint "${name}" field "${field}" is ${String(value)}, not a finite number`);
+      checked[field] = value;
+    }
+    if (Reflect.ownKeys(checked).length > 0) this.overrides.set(name, { ...this.overrides.get(name), ...checked });
+  }
+  read(name) {
+    this.named(name);
+    const patch = this.overrides.get(name);
+    const effective = this.evaluated.get(name);
+    return { override: patch === void 0 ? null : { ...patch }, effective: effective === void 0 ? null : { ...effective } };
+  }
+  clear(name) {
+    this.named(name);
+    this.overrides.delete(name);
+  }
+  /** Called only for an active constraint, after the sliders and immediately before its step. */
+  apply(record) {
+    const patch = this.overrides.get(record.name);
+    const posed = patch === void 0 ? record : { ...record, ...patch };
+    this.evaluated.set(record.name, values(posed));
+    return posed;
+  }
+}
 const HELD = { loop: false, keep: false };
 const LOOPED = { loop: true, keep: false, live: true };
 function openTrack(doc, animation, options, plant = {}) {
@@ -5257,11 +5304,15 @@ function openTrack(doc, animation, options, plant = {}) {
   if (options.clock !== void 0 && typeof options.clock !== "function") throw new CoreInputError(`the live track's options.clock is ${typeof options.clock}, not a function`);
   const mode = options.loop ? LOOPED : HELD;
   const clock = options.clock === void 0 ? void 0 : checkedClock(options.clock, "the live track's");
-  const { track, first } = openRawTrack(doc, animation, plant, options.reset, clock === void 0 ? mode : { ...mode, clock: (dt) => clock(dt) }, options.adjust);
-  return new Track(track, first);
+  const parameters = new LivePhysicsParameters(doc);
+  const { track, first } = openRawTrack(doc, animation, plant, options.reset, clock === void 0 ? mode : { ...mode, clock: (dt) => clock(dt) }, options.adjust, (ctx) => {
+    ctx.parameters = parameters;
+  });
+  return new Track(track, first, parameters);
 }
 class Track {
-  constructor(track, first) {
+  constructor(track, first, parameters) {
+    this.parameters = parameters;
     this.steps = 0;
     this.refused = null;
     this.track = track;
@@ -5284,6 +5335,17 @@ class Track {
     this.live("setEnvironment");
     setEnvironmentOn(this.track.ctx, environment, "the live track's");
   }
+  setPhysicsParameters(name, patch) {
+    this.live("setPhysicsParameters");
+    this.parameters.set(name, patch);
+  }
+  readPhysicsParameters(name) {
+    return this.parameters.read(name);
+  }
+  clearPhysicsParameters(name) {
+    this.live("clearPhysicsParameters");
+    this.parameters.clear(name);
+  }
   physicsTranslate(x, y) {
     this.live("physicsTranslate");
     translateOn(this.track.ctx, x, y, "the live track's");
@@ -6215,6 +6277,8 @@ class Tracks {
     this.time = 0;
     this.refused = null;
     this.mixer = new Mixer(doc, plant);
+    this.parameters = new LivePhysicsParameters(doc);
+    this.path.ctx.parameters = this.parameters;
   }
   get trackTime() {
     return this.time;
@@ -6226,6 +6290,17 @@ class Tracks {
     this.live("setEnvironment");
     setEnvironmentOn(this.path.ctx, environment, "the live tracks'");
   }
+  setPhysicsParameters(name, patch) {
+    this.live("setPhysicsParameters");
+    this.parameters.set(name, patch);
+  }
+  readPhysicsParameters(name) {
+    return this.parameters.read(name);
+  }
+  clearPhysicsParameters(name) {
+    this.live("clearPhysicsParameters");
+    this.parameters.clear(name);
+  }
   physicsTranslate(x, y) {
     this.live("physicsTranslate");
     translateOn(this.path.ctx, x, y, "the live tracks'");
@@ -6330,9 +6405,14 @@ class Tracks {
     ctx.time += this.clock === void 0 ? dt : this.clock(dt);
     const pose = new Pose(doc, this.plant);
     const animationTime = this.mixer.apply(pose);
+    const entry = this.mixer.tracks[0] ?? null;
+    const adjustment = this.adjust === void 0 ? void 0 : {
+      callback: this.adjust,
+      context: { trackTime: entry?.trackTime ?? null, animation: entry?.anim.name ?? null, globalTime: this.time }
+    };
     const mixed = new Map(doc.slots.map((s, k) => [s.name, { deform: pose.slots[k].deform, seen: pose.slots[k].seen }]));
     return path.step(first, this.time, animationTime, {
-      world: (sliders) => steppedLocalsWorld(doc, pose.bones, path.raw, sliders, { ctx, before, adjust: this.adjust }),
+      world: (sliders) => steppedLocalsWorld(doc, pose.bones, path.raw, sliders, { ctx, before, adjustment }),
       slots: (sliders, placeholders) => slotRowsFrom(doc, path.raw, sliders, placeholders, (_slot, _live) => {
         const s = pose.slots[doc.slots.indexOf(_slot)];
         return { placeholder: s.placeholder, light: s.light, dark: s.dark };
@@ -9104,12 +9184,16 @@ class RigPlayer {
   setsByName;
   activeSet = null;
   adjustFn = null;
+  /** Current preview patches, reapplied through the public core API on replay; no edit history. */
+  physicsPatches = /* @__PURE__ */ new Map();
+  /** Public read snapshots belonging to a restored seek pose, not the core's private evaluation cache. */
+  heldParameters = null;
   slotFilter = null;
   /** `slotFilter` as a predicate; every slot when null. */
   draws = () => true;
   /** Handed to every track the player opens; reads the current `adjust` so setting it later needs no reopen. */
-  adjustHook = (locals) => {
-    if (this.adjustFn !== null) this.adjustFn(locals);
+  adjustHook = (locals, ctx) => {
+    if (this.adjustFn !== null) this.adjustFn(locals, ctx);
   };
   listeners = {
     event: /* @__PURE__ */ new Set(),
@@ -9206,7 +9290,7 @@ class RigPlayer {
       this.animation = name;
       this.loop = loop;
       this.track = openTrack(this.view, name, { loop, reset: "animation", adjust: this.adjustHook, clock: physicsClockStep });
-      this.setRawPose(this.track.first);
+      this.setRawPose(this.initializeSingle(this.track));
       this.applyEnvironment(this.track);
       return;
     }
@@ -9312,6 +9396,7 @@ class RigPlayer {
     this.tracks = tracks;
     this.track = null;
     this.setRawPose(tracks.start());
+    this.applyPhysicsParameters(tracks);
     this.applyEnvironment(tracks);
     if (time > 0) this.stepTo(time);
     return tracks;
@@ -9319,10 +9404,54 @@ class RigPlayer {
   /** Stores `raw` and applies `activeSet` when one is active. Zero work when `activeSet === null`. */
   setRawPose(raw) {
     this.rawPose = raw;
+    this.heldParameters = null;
     this.pose = this.activeSet === null ? raw : applySetToPose(this.view, raw, this.activeSet);
     this.poseGeneration++;
     this.cachedIdentity = null;
   }
+  /**
+   * Sets a named physics constraint's pending patch, after keyed/slider values
+   * and before the integrator on the next evaluation. No pose or clock change.
+   * Unknown names/kinds/fields and non-finite values are refused atomically by
+   * the core. Requires a live track (call play/queue first).
+   */
+  setPhysicsParameters(name, patch) {
+    const live = this.requirePhysicsTrack("setPhysicsParameters", name);
+    live.setPhysicsParameters(name, patch);
+    const standing = live.readPhysicsParameters(name).override;
+    if (standing !== null) this.physicsPatches.set(name, standing);
+    this.clearSeekCache();
+  }
+  /** Pending override and the held pose's last active evaluation, detached. Does not evaluate a pose. */
+  readPhysicsParameters(name) {
+    const read = this.requirePhysicsTrack("readPhysicsParameters", name).readPhysicsParameters(name);
+    if (this.heldParameters === null) return read;
+    const effective = this.heldParameters.get(name)?.effective ?? null;
+    return { override: read.override, effective: effective === null ? null : { ...effective } };
+  }
+  /** Removes only the patch; authored values resume next evaluation. Physics history is retained. */
+  clearPhysicsParameters(name) {
+    this.requirePhysicsTrack("clearPhysicsParameters", name).clearPhysicsParameters(name);
+    this.physicsPatches.delete(name);
+    this.clearSeekCache();
+  }
+  requirePhysicsTrack(operation, name) {
+    const live = this.stepper();
+    if (live === null) throw new Error(`${operation}(${JSON.stringify(name)}) before play: no live track`);
+    return live;
+  }
+  /** No private parameter state is copied into the core's seek snapshots. */
+  readParameters(live) {
+    return new Map(this.view.constraints.filter((c) => c.kind === "physics").map((c) => [c.name, live.readPhysicsParameters(c.name)]));
+  }
+  applyPhysicsParameters(live) {
+    for (const [name, patch] of this.physicsPatches) live.setPhysicsParameters(name, patch);
+  }
+  /** Like the environment, standing patches are pending after the ordinary first pose; no extra evaluation. */
+  initializeSingle(live) {
+    this.applyPhysicsParameters(live);
+    return live.first;
+  }
   /**
    * The world the rig's physics answers (#121): `wind` and `gravity`, as
    * spine-core's skeleton-level `windX/windY` and `gravityX/gravityY` — x to
@@ -9401,6 +9530,7 @@ class RigPlayer {
       restoreStepperState(stepper, exactHit.state);
       this.rawPose = exactHit.rawPose;
       this.pose = exactHit.pose;
+      this.heldParameters = exactHit.parameters;
       this.poseGeneration++;
       this.cachedIdentity = null;
       return;
@@ -9412,24 +9542,32 @@ class RigPlayer {
       if (cache.frontierSteps <= SEEK_FINE_STEP_LIMIT || cache.frontierSteps % SEEK_COARSE_STRIDE === 0) {
         cache.grid.set(cache.frontierSteps, {
           state: captureStepperState(cache.frontier),
-          rawPose: raw
+          rawPose: raw,
+          parameters: this.readParameters(cache.frontier)
         });
       }
     }
+    let parameters;
     const gridHit = cache.grid.get(steps);
     if (gridHit !== void 0) {
       restoreStepperState(stepper, gridHit.state);
       this.rawPose = gridHit.rawPose;
+      parameters = gridHit.parameters;
     } else {
       const baseStep = steps - steps % SEEK_COARSE_STRIDE;
       const baseSnap = cache.grid.get(baseStep);
       restoreStepperState(stepper, baseSnap.state);
       this.rawPose = baseSnap.rawPose;
       for (let i = baseStep; i < steps; i++) this.rawPose = stepper.step(this.seekStep);
+      parameters = this.readParameters(stepper);
     }
     const rest = time - stepper.trackTime;
-    if (rest > 0) this.rawPose = stepper.step(rest);
+    if (rest > 0) {
+      this.rawPose = stepper.step(rest);
+      parameters = this.readParameters(stepper);
+    }
     if (this.rawPose !== null) this.setRawPose(this.rawPose);
+    this.heldParameters = parameters;
     if (this.rawPose !== null && this.pose !== null) {
       if (cache.exact.size >= SEEK_EXACT_LIMIT) {
         const oldest = cache.exact.keys().next().value;
@@ -9438,7 +9576,8 @@ class RigPlayer {
       cache.exact.set(time, {
         state: captureStepperState(stepper),
         rawPose: this.rawPose,
-        pose: this.pose
+        pose: this.pose,
+        parameters
       });
     }
   }
@@ -9459,16 +9598,17 @@ class RigPlayer {
       const tracks = openTracks(this.view, { reset: "animation", adjust: this.adjustHook, clock: physicsClockStep });
       tracks.setAnimation(0, this.animation, { loop: this.loop, mixDuration: 0 });
       firstPose = tracks.start();
+      this.applyPhysicsParameters(tracks);
       this.applyEnvironment(tracks);
       frontier = tracks;
     } else {
       const track = openTrack(this.view, this.animation, { loop: this.loop, reset: "animation", adjust: this.adjustHook, clock: physicsClockStep });
-      firstPose = track.first;
+      firstPose = this.initializeSingle(track);
       this.applyEnvironment(track);
       frontier = track;
     }
     const grid = /* @__PURE__ */ new Map();
-    grid.set(0, { state: captureStepperState(frontier), rawPose: firstPose });
+    grid.set(0, { state: captureStepperState(frontier), rawPose: firstPose, parameters: this.readParameters(frontier) });
     this.seekCache = {
       mode,
       frontier,
@@ -9486,11 +9626,12 @@ class RigPlayer {
       this.trackCount = 1;
       this.tracks = tracks;
       this.setRawPose(tracks.start());
+      this.applyPhysicsParameters(tracks);
       this.applyEnvironment(tracks);
       return;
     }
     this.track = openTrack(this.view, this.animation, { loop: this.loop, reset: "animation", adjust: this.adjustHook, clock: physicsClockStep });
-    this.setRawPose(this.track.first);
+    this.setRawPose(this.initializeSingle(this.track));
     this.applyEnvironment(this.track);
   }
   /** What is open: the tracks, the single track, or nothing before `play`. */