rig-review 0.20.0 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -11,8 +11,8 @@ The app provides one inspection workspace for setup geometry and motion, compile
11
11
  [Play](https://github.com/rig-c/play) → **Adapter** (consumer integration).
12
12
 
13
13
  Review is the human inspection and source-bound feedback gate in this delivery
14
- flow. It inspects the upstream build without replacing Core's compiler gate or
15
- authoring motion. Review itself uses the published Play runtime for previews;
14
+ flow. It inspects the upstream build without replacing Core's compiler gate, and
15
+ its motion edits are data the installed producer builds in scratch. Review itself uses the published Play runtime for previews;
16
16
  the chain describes delivery and feedback responsibilities, not runtime import
17
17
  order. Adapter denotes downstream consumer integration, without depending on the
18
18
  published adapters (`@rig-c/pixi`, `@rig-c/phaser`, `@rig-c/three`) or changing
@@ -1,6 +1,6 @@
1
1
  # Read-only animation inspection
2
2
 
3
- Animate → Transport offers a timeline, a stored-curve view and a bone tree for the current compiled build. These are inspection controls: no key authoring, motion.json writes, producer operations or output/patch schema changes. Two-build comparison is outside this feature.
3
+ Animate → Transport offers a timeline, a stored-curve view and a bone tree for the current compiled build. The bone value tracks of `motion.animations_from` are editable (#235): an edit is a pending op, and Apply builds it through the installed producer into scratch. The package's files are never written. Two-build comparison is outside this feature.
4
4
 
5
5
  The timeline lists bone groups followed by slot groups, one lane per stored timeline, with a mark per key including simultaneous keys. Key times remain exact seconds. Clicking a mark seeks through the existing transport; transport movement updates its playhead. No FPS is inferred. A selected bone filters its direct bone tracks; a selected slot filters that slot's tracks. Whole rig clears the filter.
6
6
 
package/docs/DESIGN.md CHANGED
@@ -30,7 +30,7 @@ Edits reach the producer as data (issue #102): every edit card states its edit a
30
30
 
31
31
  Physics tuning (#103) edits only what the handoff config declares: a constraint row is resolved by `name` (and kind) against the config, never by index alone, and every op records both the index (its pointer) and the name, which the server checks (`EDIT_PATCH_NAME_MISMATCH`). Rows the rig stage adds (the `turn` twins) have no config field and are shown not editable with the reason. An Apply reloads under the world it was pressed in so before and after are seen under one wind, gust and jolt state; review judges no value (a mass of 0 is rigc's `A23` to refuse). A build whose check FAILed may be loaded and looked at, but a review written on it is not submitted (`EDIT_SUBMIT_UNCHECKED`). Published Play 1.14.0 supplies the six-field live preview (#206): strength, damping, inertia, wind, gravity and mix use its public set/read/clear methods; mass and component toggles still require Apply. Slider input updates the pending override; the label distinguishes it from the last evaluated effective values. The next evaluation uses the patch; a paused page explicitly re-poses the held time without seeking. Clear removes overrides while preserving pending ops and integrated history, and authored values resume at the next evaluation; it does not undo the old trajectory. Apply and model replacement clear the preview. It is labelled "preview — Apply decides" and is never recorded as applied state. Play replays the current standing patch, not historical edits: backward seek recomputes with today's patch, and a newly opened track's first authored pose precedes its pending patch. The readout's BEFORE for the inspected build is that build's own check: once the baseline reproduces, `rig-parts check` runs on the baseline output (byte-identical to the inspected rig) in the background, and its summary is stored beside the baseline record.
32
32
 
33
- The producer writes motion in scratch; review never authors keys. Idle tracks (#104) edit the idle the producer keys, never the package's motion.json: every edit is a config patch op at `/motion/tracks/<i>/…` or `/motion/blink/…`, and the producer (`retune` on parts 1.44.0+, else `rig --config`; then `check`) writes the keys. The panel offers only what the producer accepts where its rule is closed — a period is `motion.duration / n` (rig-parts `periodFits`: the duration over the period within 1e-9 of a whole number) — and pre-checks the pending idle under the producer's own names and words (`CONFIG_PERIOD_DIVIDES_DURATION`, `CONFIG_BONE_PROPERTY_KEYED_ONCE`, `CONFIG_NAME_RESOLVES`, `RIG_BLINK_INSIDE_IDLE`), so a refusal before Apply is the producer's line, and the producer judges again on Apply. The preview (decision on #104: allowed) drives the edited bones through play's `adjust` with the producer's sine `v(t) = base + amp·sin(2π(t/period − phase))` on the bone the inspected idle keys (`<bone>_ctl` under ctl keys, read off the handoff rig, never guessed: a property the idle does not key yet is refused by name, `IDLE_PREVIEW_TARGET_UNKNOWN`); it uses Play 1.14.0's `BoneAdjust` context `trackTime` through both composed adjustments, with no displayed player clock or seek-compensation re-pose. Bit-exact seek/continuous equivalence requires the unchanged patch, animation, environment, reset and step partition. It is labelled "preview — Apply decides", is cleared on Apply and Reset, and is never recorded or submitted. Blink edits are eased keys and are not previewed.
33
+ The producer writes motion in scratch; review never writes a source key. A timeline edit (#235) is a list of ops on a scratch copy of `motion.animations_from`, built by the installed producer. Idle tracks (#104) edit the idle the producer keys, never the package's motion.json: every edit is a config patch op at `/motion/tracks/<i>/…` or `/motion/blink/…`, and the producer (`retune` on parts 1.44.0+, else `rig --config`; then `check`) writes the keys. The panel offers only what the producer accepts where its rule is closed — a period is `motion.duration / n` (rig-parts `periodFits`: the duration over the period within 1e-9 of a whole number) — and pre-checks the pending idle under the producer's own names and words (`CONFIG_PERIOD_DIVIDES_DURATION`, `CONFIG_BONE_PROPERTY_KEYED_ONCE`, `CONFIG_NAME_RESOLVES`, `RIG_BLINK_INSIDE_IDLE`), so a refusal before Apply is the producer's line, and the producer judges again on Apply. The preview (decision on #104: allowed) drives the edited bones through play's `adjust` with the producer's sine `v(t) = base + amp·sin(2π(t/period − phase))` on the bone the inspected idle keys (`<bone>_ctl` under ctl keys, read off the handoff rig, never guessed: a property the idle does not key yet is refused by name, `IDLE_PREVIEW_TARGET_UNKNOWN`); it uses Play 1.14.0's `BoneAdjust` context `trackTime` through both composed adjustments, with no displayed player clock or seek-compensation re-pose. Bit-exact seek/continuous equivalence requires the unchanged patch, animation, environment, reset and step partition. It is labelled "preview — Apply decides", is cleared on Apply and Reset, and is never recorded or submitted. Blink edits are eased keys and are not previewed.
34
34
 
35
35
  The Mesh panel (#106) edits one part's `meshes.<part>` entry as the producer's config loader reads it and rebuilds that part with `remesh --mesh`; it is a mesh-density and region editor for the producer's own parameters, not a mesher — review triangulates nothing, and the only geometry it writes is region points (whole rig px) and circle centres. The submitted patch is exactly one op, `replace /meshes/<part>`, so nothing else in the config can move with it. It offers the modes whose fields it draws (grid, contour); `influence` waits until the producer documents it in `remesh`. Its pre-check is the config loader's rules in the loader's names; what the rig stage measures (the keep-radius floor, bridges, heat sources, the remesh rules) is the producer's to say, and comes back verbatim. After a build, three counts must agree — `remesh.json`'s after-count, the revision model's triangles and what the overlay draws — and the panel names each, so an overlay still drawing the old mesh is visible as a disagreement, not hidden.
36
36
 
package/docs/PANELS.md CHANGED
@@ -227,9 +227,9 @@ serving use per-port origins and keep them separate.
227
227
 
228
228
  ## Inspect animation keys
229
229
 
230
- Animate → **Transport** opens the read-only Timeline, Curves and Bone tree views of the build currently on stage. The timeline preserves every stored bone/slot track and key time; click a key to seek, or scrub the transport to move its playhead. Bone selection filters its direct tracks. Tree, Parts and stage selections stay synchronized; enable **Bone points** to pick a bone on stage. Selecting a bone highlights all directly attached Parts rows without inventing a selected slot.
230
+ Animate keeps its timeline in a panel of its own beside the other blocks, with Timeline, Curves and Bone tree views of the build currently on stage. Bone value tracks of `motion.animations_from` are editable: an edit is a pending op, previewed on the stage, and **Apply · Rebuild** builds it through the installed producer into scratch. Other tracks say why they are read-only, and compare mode is read-only (`ANIMATION_COMPARE_READ_ONLY`). The timeline preserves every stored bone/slot track and key time; click a key to seek, or scrub the transport to move its playhead. Bone selection filters its direct tracks. Tree, Parts and stage selections stay synchronized; enable **Bone points** to pick a bone on stage. Selecting a bone highlights all directly attached Parts rows without inventing a selected slot.
231
231
 
232
- Curves show the compiled skeleton’s exact linear, stepped or cubic Bézier segments and stored handles. The separately labeled **Runtime evaluation** cursor/readout uses Play’s ten-piece Float32 interpolation, which can differ from the cubic. Its local value includes setup rotation/translation and scale multiplication, in stored timeline order, before constraints and previews. Rotation is unwrapped local degrees. **Inspect time** accepts exact seconds; frame labels require the existing explicit clock. These views author no keys and change no package, motion, patch or review format. See [animation inspection](ANIMATION_INSPECTION.md) for the numeric validation and reproduction commands.
232
+ Curves show the compiled skeleton’s exact linear, stepped or cubic Bézier segments and stored handles. On an editable bone value track, **Segment** picks the outgoing key, **Mode** switches between linear, stepped and cubic Bézier, and dragging the two handles on the plot edits the segment’s `[cx1, cy1, cx2, cy2]` (`set_key_curve` / `set_key_ease` ops, coalesced on the same key and previewed live on the stage before **Apply · Rebuild**). The separately labeled **Runtime evaluation** cursor/readout uses Play’s ten-piece Float32 interpolation, which can differ from the cubic. Its local value includes setup rotation/translation and scale multiplication, in stored timeline order, before constraints and previews. Rotation is unwrapped local degrees. **Inspect time** accepts exact seconds; frame labels require the existing explicit clock. Nothing is written into the package. See [animation inspection](ANIMATION_INSPECTION.md) for the numeric validation and reproduction commands.
233
233
 
234
234
  ## Inspect a part
235
235
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rig-review",
3
- "version": "0.20.0",
3
+ "version": "0.21.0",
4
4
  "type": "module",
5
5
  "description": "Local human rig inspection and structured feedback export",
6
6
  "license": "MIT",
@@ -6,6 +6,7 @@ import {
6
6
  } from './animation-inspection.ts';
7
7
 
8
8
  export const MOTION_SPEC_VERSION = 'rigc-motion/1';
9
+ export const MAX_ANIMATION_OPS = 200;
9
10
 
10
11
  export type EasingTuple = readonly [number, number, number, number];
11
12
 
@@ -382,9 +383,11 @@ export interface AnimationEditGate {
382
383
  editable: boolean;
383
384
  code:
384
385
  | 'OK'
386
+ | 'ANIMATION_SOURCE_LOADING'
385
387
  | 'ANIMATION_IDLE_GOVERNED_BY_TURN_PAD'
386
388
  | 'ANIMATION_SOURCE_MISSING'
387
- | 'ANIMATION_NOT_IN_SOURCE';
389
+ | 'ANIMATION_NOT_IN_SOURCE'
390
+ | 'ANIMATION_COMPARE_READ_ONLY';
388
391
  reason: string | null;
389
392
  note: string | null;
390
393
  }
@@ -1039,6 +1042,7 @@ export function applyAnimationOp(
1039
1042
  text: string,
1040
1043
  op: AnimationSourceOp,
1041
1044
  baseText?: string,
1045
+ fallbackEasings?: Readonly<Record<string, EasingTuple>>,
1042
1046
  ): AppliedAnimationOpsResult {
1043
1047
  const { doc, classification, keys } = resolveEditableTrack(text, op.animation, op.track);
1044
1048
  const channels = classification.channels;
@@ -1217,7 +1221,10 @@ export function applyAnimationOp(
1217
1221
  if (op.ease === 'stepped') {
1218
1222
  throw new Error('ANIMATION_EASING_STEPPED_USE_CURVE: "stepped" is a curve mode; use curve: "stepped"');
1219
1223
  }
1220
- const easings = isRecord(doc.easings) ? doc.easings : {};
1224
+ const easings = {
1225
+ ...(fallbackEasings ?? {}),
1226
+ ...(isRecord(doc.easings) ? doc.easings : {}),
1227
+ };
1221
1228
  if (!Array.isArray(easings[op.ease])) {
1222
1229
  throw new Error(`ANIMATION_EASING_UNKNOWN: unknown easing "${op.ease}"`);
1223
1230
  }
@@ -1267,7 +1274,10 @@ export function applyAnimationOp(
1267
1274
  if (op.ease === 'stepped') {
1268
1275
  throw new Error('ANIMATION_EASING_STEPPED_USE_CURVE: "stepped" is a curve mode; use curve: "stepped"');
1269
1276
  }
1270
- const easings = isRecord(doc.easings) ? doc.easings : {};
1277
+ const easings = {
1278
+ ...(fallbackEasings ?? {}),
1279
+ ...(isRecord(doc.easings) ? doc.easings : {}),
1280
+ };
1271
1281
  if (!Array.isArray(easings[op.ease])) {
1272
1282
  throw new Error(`ANIMATION_EASING_UNKNOWN: unknown easing "${op.ease}"`);
1273
1283
  }
@@ -1651,11 +1661,13 @@ function coalesceSetKeyValueOp(
1651
1661
  */
1652
1662
  export class AnimationOpBuilder {
1653
1663
  readonly baseText: string;
1664
+ readonly fallbackEasings?: Readonly<Record<string, EasingTuple>>;
1654
1665
  private currentText: string;
1655
1666
  private readonly history: Array<{ op: AnimationSourceOp; textBefore: string }> = [];
1656
1667
 
1657
- constructor(baseText: string) {
1668
+ constructor(baseText: string, fallbackEasings?: Readonly<Record<string, EasingTuple>>) {
1658
1669
  this.baseText = baseText;
1670
+ this.fallbackEasings = fallbackEasings;
1659
1671
  this.currentText = baseText;
1660
1672
  }
1661
1673
 
@@ -1684,14 +1696,16 @@ export class AnimationOpBuilder {
1684
1696
  if (
1685
1697
  sameKeyTarget &&
1686
1698
  ((op.op === 'set_key_time' && last.op.op === 'set_key_time') ||
1687
- (op.op === 'set_key_value' && last.op.op === 'set_key_value'))
1699
+ (op.op === 'set_key_value' && last.op.op === 'set_key_value') ||
1700
+ ((op.op === 'set_key_curve' || op.op === 'set_key_ease') &&
1701
+ (last.op.op === 'set_key_curve' || last.op.op === 'set_key_ease')))
1688
1702
  ) {
1689
1703
  const replayFrom = last.textBefore;
1690
1704
  const coalescedOp =
1691
1705
  op.op === 'set_key_value' && last.op.op === 'set_key_value'
1692
1706
  ? coalesceSetKeyValueOp(replayFrom, last.op, op)
1693
1707
  : op;
1694
- const res = applyAnimationOp(replayFrom, coalescedOp, this.baseText);
1708
+ const res = applyAnimationOp(replayFrom, coalescedOp, this.baseText, this.fallbackEasings);
1695
1709
  this.history.pop();
1696
1710
  if (res.text === this.baseText) {
1697
1711
  this.history.length = 0;
@@ -1707,7 +1721,7 @@ export class AnimationOpBuilder {
1707
1721
  return res;
1708
1722
  }
1709
1723
 
1710
- const res = applyAnimationOp(this.currentText, op, this.baseText);
1724
+ const res = applyAnimationOp(this.currentText, op, this.baseText, this.fallbackEasings);
1711
1725
  if (res.text === this.baseText) {
1712
1726
  this.history.length = 0;
1713
1727
  this.currentText = this.baseText;
@@ -1716,11 +1730,111 @@ export class AnimationOpBuilder {
1716
1730
  if (res.text === this.currentText) {
1717
1731
  return { text: this.currentText, changedSpans: [] };
1718
1732
  }
1733
+ if (this.history.length >= MAX_ANIMATION_OPS) {
1734
+ throw new Error(
1735
+ `ANIMATION_OPS_TOO_MANY: pending operations cannot exceed MAX_ANIMATION_OPS (${MAX_ANIMATION_OPS})`,
1736
+ );
1737
+ }
1719
1738
  this.history.push({ op, textBefore: this.currentText });
1720
1739
  this.currentText = res.text;
1721
1740
  return res;
1722
1741
  }
1723
1742
 
1743
+ /**
1744
+ * Move a selection of `(track, key)` pairs in `animation` by `deltaTime` seconds
1745
+ * atomically. When `deltaTime > 0`, keys on the same track are moved from right to left
1746
+ * so an earlier key does not collide with its not-yet-moved right neighbor; when
1747
+ * `deltaTime < 0`, from left to right. Refuses with `ANIMATION_OPS_TOO_MANY` (restoring
1748
+ * the builder's prior state) if the move would exceed `MAX_ANIMATION_OPS`.
1749
+ */
1750
+ moveSelection(
1751
+ animation: string,
1752
+ selections: ReadonlyArray<{ track: number; key: number }>,
1753
+ deltaTime: number,
1754
+ ): AppliedAnimationOpsResult {
1755
+ if (!Number.isFinite(deltaTime)) {
1756
+ throw new Error(`ANIMATION_KEY_TIME_INVALID: deltaTime must be finite, got ${String(deltaTime)}`);
1757
+ }
1758
+ if (selections.length === 0 || deltaTime === 0) {
1759
+ return { text: this.currentText, changedSpans: [] };
1760
+ }
1761
+ const byTrack = new Map<number, number[]>();
1762
+ for (const sel of selections) {
1763
+ let arr = byTrack.get(sel.track);
1764
+ if (!arr) {
1765
+ arr = [];
1766
+ byTrack.set(sel.track, arr);
1767
+ }
1768
+ if (!arr.includes(sel.key)) arr.push(sel.key);
1769
+ }
1770
+ const totalSelected = [...byTrack.values()].reduce((acc, a) => acc + a.length, 0);
1771
+ if (totalSelected > MAX_ANIMATION_OPS) {
1772
+ throw new Error(
1773
+ `ANIMATION_OPS_TOO_MANY: selection move of ${totalSelected} keys exceeds MAX_ANIMATION_OPS (${MAX_ANIMATION_OPS})`,
1774
+ );
1775
+ }
1776
+ const savedText = this.currentText;
1777
+ const savedHistory = this.history.map((h) => ({ ...h }));
1778
+ const changedSpans: { start: number; end: number }[] = [];
1779
+ try {
1780
+ const sortedTracks = [...byTrack.keys()].sort((a, b) => a - b);
1781
+ const targetTimes = new Map<string, number>();
1782
+ for (const track of sortedTracks) {
1783
+ const { keys } = resolveEditableTrack(this.currentText, animation, track);
1784
+ for (const key of byTrack.get(track)!) {
1785
+ const k = keys[key];
1786
+ if (!k) {
1787
+ throw new Error(`ANIMATION_KEY_OUT_OF_RANGE: key index ${key} out of [0, ${keys.length - 1}]`);
1788
+ }
1789
+ targetTimes.set(`${track}:${key}`, cleanMotionNumber(k.t + deltaTime));
1790
+ }
1791
+ }
1792
+
1793
+ // Coalesce with a trailing batch of set_key_time ops on the same selection
1794
+ let suffixStart = this.history.length;
1795
+ while (suffixStart > 0) {
1796
+ const prev = this.history[suffixStart - 1]!.op;
1797
+ if (
1798
+ prev.op === 'set_key_time' &&
1799
+ prev.animation === animation &&
1800
+ targetTimes.has(`${prev.track}:${prev.key}`)
1801
+ ) {
1802
+ suffixStart--;
1803
+ } else {
1804
+ break;
1805
+ }
1806
+ }
1807
+ if (suffixStart < this.history.length) {
1808
+ this.currentText = this.history[suffixStart]!.textBefore;
1809
+ this.history.length = suffixStart;
1810
+ }
1811
+
1812
+ for (const track of sortedTracks) {
1813
+ const { keys } = resolveEditableTrack(this.currentText, animation, track);
1814
+ const keyIndices = [...byTrack.get(track)!].sort((a, b) => {
1815
+ const shiftA = targetTimes.get(`${track}:${a}`)! - keys[a]!.t;
1816
+ return shiftA >= 0 ? b - a : a - b;
1817
+ });
1818
+ for (const key of keyIndices) {
1819
+ const res = this.apply({
1820
+ op: 'set_key_time',
1821
+ animation,
1822
+ track,
1823
+ key,
1824
+ time: targetTimes.get(`${track}:${key}`)!,
1825
+ });
1826
+ changedSpans.push(...res.changedSpans);
1827
+ }
1828
+ }
1829
+ return { text: this.currentText, changedSpans };
1830
+ } catch (err) {
1831
+ this.currentText = savedText;
1832
+ this.history.length = 0;
1833
+ this.history.push(...savedHistory);
1834
+ throw err;
1835
+ }
1836
+ }
1837
+
1724
1838
  undo(): boolean {
1725
1839
  const last = this.history.pop();
1726
1840
  if (!last) return false;
@@ -1739,10 +1853,21 @@ export class AnimationOpBuilder {
1739
1853
  // Pending-preview adapter into src/animation-inspection.ts (Correction 7)
1740
1854
  // ---------------------------------------------------------------------------
1741
1855
 
1856
+ const KEY_TIME_GRID = 360000;
1857
+
1742
1858
  function f32(n: number): number {
1743
1859
  return Math.fround(n);
1744
1860
  }
1745
1861
 
1862
+ /**
1863
+ * Match `@rig-c/core/src/compile.ts` `keyTime(n)`: snap times within 5e-7 of the
1864
+ * 1/360000s grid before Float32 rounding so preview keys match compiled keys.
1865
+ */
1866
+ export function compiledKeyTime(n: number): number {
1867
+ const grid = Math.round(n * KEY_TIME_GRID) / KEY_TIME_GRID;
1868
+ return f32(Math.abs(n - grid) <= 5e-7 ? grid : n);
1869
+ }
1870
+
1746
1871
  function resolveKeyCurveForInspection(
1747
1872
  key: { t: number; v: readonly number[]; ease?: string; curve?: readonly number[] | 'stepped' },
1748
1873
  nextKey: { t: number; v: readonly number[] } | undefined,
@@ -1750,7 +1875,7 @@ function resolveKeyCurveForInspection(
1750
1875
  ): number[] | 'stepped' | undefined {
1751
1876
  if (!nextKey) return undefined;
1752
1877
  if (key.curve !== undefined) {
1753
- return key.curve === 'stepped' ? 'stepped' : [...key.curve];
1878
+ return key.curve === 'stepped' ? 'stepped' : key.curve.map(f32);
1754
1879
  }
1755
1880
  if (key.ease === undefined) return undefined;
1756
1881
  if (key.ease === 'stepped') return 'stepped';
@@ -1766,10 +1891,10 @@ function resolveKeyCurveForInspection(
1766
1891
  const v1 = key.v[c]!;
1767
1892
  const dv = nextKey.v[c]! - v1;
1768
1893
  out.push(
1769
- cleanMotionNumber(key.t + dt * hx1),
1770
- cleanMotionNumber(v1 + dv * hy1),
1771
- cleanMotionNumber(key.t + dt * hx2),
1772
- cleanMotionNumber(v1 + dv * hy2),
1894
+ f32(key.t + dt * hx1),
1895
+ f32(v1 + dv * hy1),
1896
+ f32(key.t + dt * hx2),
1897
+ f32(v1 + dv * hy2),
1773
1898
  );
1774
1899
  }
1775
1900
  return out;
@@ -1799,9 +1924,9 @@ export function draftTrackToInspectionTrack(
1799
1924
  throw new Error(`ANIMATION_TRACK_READ_ONLY: unsupported bone property "${track.property}"`);
1800
1925
  }
1801
1926
  const storedKeys: StoredKey[] = track.keys.map((k, idx) => {
1802
- const entry: StoredKey = { time: k.t };
1927
+ const entry: StoredKey = { time: compiledKeyTime(k.t) };
1803
1928
  channelSpec.forEach((ch, c) => {
1804
- entry[ch.field] = k.v[c]!;
1929
+ entry[ch.field] = f32(k.v[c]!);
1805
1930
  });
1806
1931
  const curve = resolveKeyCurveForInspection(k, track.keys[idx + 1], easings);
1807
1932
  if (curve !== undefined) {
@@ -1826,6 +1951,7 @@ export function draftTrackToInspectionTrack(
1826
1951
  export function overlayDraftOnInspection(
1827
1952
  inspection: AnimationInspection,
1828
1953
  draftMotionText: string,
1954
+ fallbackEasings?: Readonly<Record<string, EasingTuple>>,
1829
1955
  ): AnimationInspection {
1830
1956
  const doc = JSON.parse(draftMotionText) as Record<string, unknown>;
1831
1957
  if (!isRecord(doc.animations)) return inspection;
@@ -1833,9 +1959,13 @@ export function overlayDraftOnInspection(
1833
1959
  if (!isRecord(anim) || !Array.isArray(anim.tracks)) return inspection;
1834
1960
  const rawTracks = anim.tracks as unknown[];
1835
1961
 
1836
- const easings = isRecord(doc.easings)
1837
- ? (doc.easings as Readonly<Record<string, EasingTuple>>)
1838
- : undefined;
1962
+ const easings: Readonly<Record<string, EasingTuple>> | undefined =
1963
+ isRecord(doc.easings) || fallbackEasings
1964
+ ? {
1965
+ ...(fallbackEasings ?? {}),
1966
+ ...(isRecord(doc.easings) ? (doc.easings as Readonly<Record<string, EasingTuple>>) : {}),
1967
+ }
1968
+ : undefined;
1839
1969
  const classifications = classifyAnimationTracks(doc, inspection.name);
1840
1970
  const replacementByKey = new Map<string, InspectionTrack>();
1841
1971
 
@@ -149,6 +149,8 @@ export interface AppliedAnimation {
149
149
  check: CheckSummary | null;
150
150
  files: FilesDiff | null;
151
151
  modelHash: string;
152
+ /** #112: the exported `rigc-environment/1` schedule Apply's check read, when "Use for readings" was on. */
153
+ environment?: { sha256: string; steps: number };
152
154
  }
153
155
  /** One producer document against the inspected one: `count` differing JSON Pointers, the first `MAX_DIFF_PATHS` listed. */
154
156
  export interface DocumentDiff { file: ProducerDocument; count: number; paths: string[] }
@@ -293,7 +295,7 @@ export function parseAppliedContext(value: unknown): void {
293
295
  return;
294
296
  }
295
297
  if (value.schema === APPLIED_ANIMATION_SCHEMA) {
296
- const v = exact(value, 'animationsFrom,args,buildId,check,compiler,configHash,files,line,modelHash,ops,opsSha256,producer,schema', field);
298
+ const v = exact(value, `animationsFrom,args,buildId,check,compiler,configHash,${Object.hasOwn(value, 'environment') ? 'environment,' : ''}files,line,modelHash,ops,opsSha256,producer,schema`, field);
297
299
  if (![v.buildId, v.configHash, v.opsSha256, v.modelHash].every(hex)) throw new Error(`${field}: buildId, configHash, opsSha256 and modelHash are SHA-256 hex`);
298
300
  const af = exact(v.animationsFrom, 'afterSha256,beforeSha256,path', `${field}.animationsFrom`);
299
301
  if (typeof af.path !== 'string' || !af.path || !hex(af.beforeSha256) || !hex(af.afterSha256)) throw new Error(`${field}.animationsFrom: {path, beforeSha256, afterSha256 (SHA-256 hex)}`);
@@ -303,6 +305,7 @@ export function parseAppliedContext(value: unknown): void {
303
305
  tool(v.producer, `${field}.producer`); tool(v.compiler, `${field}.compiler`); lineOrNull(v.line, `${field}.line`);
304
306
  parseCheck(v.check, `${field}.check`);
305
307
  parseFilesDiff(v.files, `${field}.files`);
308
+ if (Object.hasOwn(v, 'environment')) { const e = exact(v.environment, 'sha256,steps', `${field}.environment`); if (!hex(e.sha256) || !Number.isSafeInteger(e.steps) || (e.steps as number) < 1) throw new Error(`${field}.environment: {sha256 (SHA-256 hex), steps ≥ 1}`); }
306
309
  return;
307
310
  }
308
311
  throw new Error(`${field}.schema: expected ${APPLIED_REGIONS_SCHEMA}, ${APPLIED_PATCH_SCHEMA} (patch ${CONFIG_PATCH_SCHEMA}), ${APPLIED_DELTA_SCHEMA} (mesh-edit delta), ${APPLIED_RETARGET_SCHEMA} (retarget) or ${APPLIED_ANIMATION_SCHEMA} (animation)`);
@@ -328,8 +331,9 @@ export function appliedSummary(value: unknown): string | null {
328
331
  const a = value as AppliedAnimation;
329
332
  const anims = [...new Set(a.ops.map(o => o.animation))];
330
333
  const check = a.check ? `check ${a.check.pass === null ? 'not read' : a.check.pass ? 'PASS' : 'FAIL'}` : 'check not run';
334
+ const env = a.environment ? ` under the exported world (${a.environment.steps} step(s), sha256 ${a.environment.sha256.slice(0, 16)})` : '';
331
335
  const diff = a.files ? ` · ${filesDiffText(a.files)}` : '';
332
- return `animation ${a.opsSha256.slice(0, 12)}… (${a.ops.length} op(s) on ${anims.join(', ')}; ${a.animationsFrom.path} ${a.animationsFrom.beforeSha256.slice(0, 12)}… → ${a.animationsFrom.afterSha256.slice(0, 12)}…) with ${producer.package} ${producer.version} · ${check}${diff} · model ${model}…`;
336
+ return `animation ${a.opsSha256.slice(0, 12)}… (${a.ops.length} op(s) on ${anims.join(', ')}; ${a.animationsFrom.path} ${a.animationsFrom.beforeSha256.slice(0, 12)}… → ${a.animationsFrom.afterSha256.slice(0, 12)}…) with ${producer.package} ${producer.version} · ${check}${env}${diff} · model ${model}…`;
333
337
  }
334
338
  const a = value as AppliedPatch, paths = a.patch.ops.map(o => `${o.op} ${o.path}`);
335
339
  const check = a.check ? `check ${a.check.pass === null ? 'not read' : a.check.pass ? 'PASS' : 'FAIL'}` : 'check not run';
@@ -71,22 +71,22 @@ const REGIONS: readonly {
71
71
  key: 'animateBlockRow',
72
72
  placeholder: '<!-- shared:animate-block-row -->',
73
73
  start: '<nav class="block-row" aria-label="Animate blocks">',
74
- end: '<section id="transport"',
75
- compareEnd: '<section id="transport"',
74
+ end: '<section id="motion-tools">',
75
+ compareEnd: '<div class="compare-info">',
76
76
  },
77
77
  {
78
78
  key: 'transportStrips',
79
79
  placeholder: '<!-- shared:transport-strips -->',
80
80
  start: '<div id="reading-ticks"',
81
81
  end: '</section><section id="frame-controls"',
82
- compareEnd: '</section><div class="compare-info">',
82
+ compareEnd: '</section><section id="animation-inspection"',
83
83
  },
84
84
  {
85
85
  key: 'animatePanels',
86
86
  placeholder: '<!-- shared:animate-panels -->',
87
87
  start: '<section id="motion-tools">',
88
- end: '</section></div></section></main>',
89
- compareEnd: '</section><section id="inspector-feedback"',
88
+ end: '</div></section></div></section></main>',
89
+ compareEnd: '</div></section><section id="inspector-feedback"',
90
90
  },
91
91
  ];
92
92
 
package/src/rebuild.ts CHANGED
@@ -401,7 +401,7 @@ export function parseAnimationRequest(input: unknown): AnimationRequest {
401
401
  if (typeof v.animationsFromHash !== 'string' || !/^[a-f0-9]{64}$/.test(v.animationsFromHash)) bad('animationsFromHash');
402
402
  const args = parseAnimationArgs(v.args);
403
403
  if (!Array.isArray(v.ops)) return bad('ops must be an array');
404
- if (v.ops.length > MAX_ANIMATION_OPS) return bad(`ops must hold at most ${MAX_ANIMATION_OPS} entries`);
404
+ if (v.ops.length > MAX_ANIMATION_OPS) throw new RebuildError('ANIMATION_OPS_TOO_MANY', `ops must hold at most ${MAX_ANIMATION_OPS} entries (got ${v.ops.length})`);
405
405
  if (v.ops.length === 0) throw new RebuildError('ANIMATION_OPS_EMPTY', 'ops must hold at least 1 operation; nothing to apply');
406
406
  const ops = v.ops.map((op, i) => {
407
407
  try { return parseAnimationSourceOp(op, `ops[${i}]`); }
@@ -409,9 +409,9 @@ export function parseAnimationRequest(input: unknown): AnimationRequest {
409
409
  });
410
410
  return { configHash: v.configHash as string, animationsFromHash: v.animationsFromHash as string, ops, args };
411
411
  }
412
- /** Deterministic: the package, the config bytes, the handoff animations_from bytes, the canonical ops bytes, both tool versions and any non-default rig flags. No clock. */
413
- export function animationId(input: { sourceHash: string; configHash: string; animationsFromHash: string; opsText: string; producer: string; compiler: string; args?: readonly string[] }): string {
414
- return sha256(JSON.stringify([REBUILD_SCHEMA, 'animation', input.sourceHash, input.configHash, input.animationsFromHash, input.opsText, input.producer, input.compiler, ...(input.args?.length ? [input.args] : [])]));
412
+ /** Deterministic: the package, the config bytes, the handoff animations_from bytes, the canonical ops bytes, both tool versions, any non-default rig flags, and any exported environment schedule. No clock. */
413
+ export function animationId(input: { sourceHash: string; configHash: string; animationsFromHash: string; opsText: string; producer: string; compiler: string; args?: readonly string[]; environment?: string }): string {
414
+ return sha256(JSON.stringify([REBUILD_SCHEMA, 'animation', input.sourceHash, input.configHash, input.animationsFromHash, input.opsText, input.producer, input.compiler, ...(input.args?.length ? [input.args] : []), ...(input.environment ? ['environment', input.environment] : [])]));
415
415
  }
416
416
  export interface AnimationJob {
417
417
  schema: typeof REBUILD_SCHEMA; kind: 'animation'; id: string; status: RebuildStatus; reused: boolean; op: 'rig';
@@ -422,6 +422,15 @@ export interface AnimationJob {
422
422
  check: CheckSummary | null;
423
423
  files: FilesDiff | null;
424
424
  build: RebuildBuild | null;
425
+ environment?: ApplyWorld['record'];
426
+ }
427
+ export interface AnimationSourceStatus {
428
+ available: boolean;
429
+ reason: string | null;
430
+ path: string | null;
431
+ sha256: string | null;
432
+ text: string | null;
433
+ easings: Record<string, [number, number, number, number]> | null;
425
434
  }
426
435
  /**
427
436
  * Deterministic: the package, the config bytes, the patch's own bytes and both tool versions. No clock. A retune-routed
@@ -721,10 +730,81 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
721
730
  producer: resolved.ok ? tool(resolved.producer) : null, compiler: resolved.ok ? tool(resolved.compiler) : null,
722
731
  // #114: what the retarget editor offers — the pose producer, the declared sequences, the rig's bones and animations.
723
732
  retarget: await retargetStatus(inputs),
733
+ // #235: the handoff's motion.animations_from file (path, sha256, text) and the rig's easings table for the timeline editor.
734
+ animations: await animationsStatus(inputs),
724
735
  reason,
725
736
  running,
726
737
  };
727
738
  }
739
+ /** #235: what the keyed animation editor starts from. */
740
+ async function animationsStatus(inputs: ProducerInputs | null): Promise<AnimationSourceStatus> {
741
+ if (!inputs) {
742
+ return {
743
+ available: false,
744
+ reason: p.handoff ? handoffGap(p.handoff) : (p.handoffReason ?? modelingHandoffMissing(null)),
745
+ path: null,
746
+ sha256: null,
747
+ text: null,
748
+ easings: null,
749
+ };
750
+ }
751
+ let easings: Record<string, [number, number, number, number]> | null = null;
752
+ try {
753
+ const rigMotion = JSON.parse(await readFile(join(inputs.rig, 'motion.json'), 'utf8')) as { easings?: unknown };
754
+ if (rigMotion.easings && typeof rigMotion.easings === 'object' && !Array.isArray(rigMotion.easings)) {
755
+ easings = rigMotion.easings as Record<string, [number, number, number, number]>;
756
+ }
757
+ } catch { /* optional */ }
758
+ const configDoc = object(JSON.parse(inputs.configText), 'config');
759
+ const motion = configDoc.motion && typeof configDoc.motion === 'object' && !Array.isArray(configDoc.motion) ? configDoc.motion as Record<string, unknown> : null;
760
+ const relFrom = typeof motion?.animations_from === 'string' && motion.animations_from.trim() ? motion.animations_from : null;
761
+ if (!relFrom) {
762
+ return {
763
+ available: false,
764
+ reason: 'ANIMATION_SOURCE_MISSING: config.json does not declare an "animations_from" motion spec file.',
765
+ path: null,
766
+ sha256: null,
767
+ text: null,
768
+ easings,
769
+ };
770
+ }
771
+ let absFrom: string;
772
+ try { absFrom = await realpath(resolve(dirname(inputs.config), relFrom)); }
773
+ catch {
774
+ return {
775
+ available: false,
776
+ reason: `ANIMATION_SOURCE_MISSING: config motion.animations_from (${relFrom}) does not exist`,
777
+ path: relFrom,
778
+ sha256: null,
779
+ text: null,
780
+ easings,
781
+ };
782
+ }
783
+ const showFrom = relative(await realpath(p.root), absFrom).split(sep).join('/') || '.';
784
+ const handoffFile = inputs.handoff.files.find(f => f.path === showFrom);
785
+ if (!handoffFile) {
786
+ return {
787
+ available: false,
788
+ reason: `ANIMATION_SOURCE_MISSING: config motion.animations_from (${showFrom}) is missing from the handoff`,
789
+ path: showFrom,
790
+ sha256: null,
791
+ text: null,
792
+ easings,
793
+ };
794
+ }
795
+ const text = await readFile(absFrom, 'utf8'), hash = sha256(text);
796
+ if (hash !== handoffFile.sha256) {
797
+ return {
798
+ available: false,
799
+ reason: `REBUILD_INPUTS_CHANGED: ${showFrom} changed since the review was opened; restart review`,
800
+ path: showFrom,
801
+ sha256: hash,
802
+ text: null,
803
+ easings,
804
+ };
805
+ }
806
+ return { available: true, reason: null, path: showFrom, sha256: hash, text, easings };
807
+ }
728
808
  /** #111: what the cloth recipe form starts from. */
729
809
  async function clothStatus(handoff: Handoff, inputs: ProducerInputs, resolved: ReturnType<typeof resolveProducer>) {
730
810
  const config = object(JSON.parse(inputs.configText), 'config');
@@ -1523,7 +1603,7 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
1523
1603
  }
1524
1604
 
1525
1605
  /** #235: spliced `animations_from` → `<dir>/animations.json`, `<dir>/config.json` pointing at it → `rig-parts rig` → compile → `rig-parts check`. */
1526
- function executeAnimation(job: AnimationJob, dir: string, inputs: ProducerInputs, resolved: Resolved, scratchConfig: string, splicedAnimations: string): Promise<void> {
1606
+ function executeAnimation(job: AnimationJob, dir: string, inputs: ProducerInputs, resolved: Resolved, scratchConfig: string, splicedAnimations: string, world: ApplyWorld | null = null): Promise<void> {
1527
1607
  const args = job.request.args ?? [], producer = resolved.producer;
1528
1608
  return apply(job, dir, inputs, resolved, {
1529
1609
  cmd: 'rig', spec: 'rig',
@@ -1541,17 +1621,18 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
1541
1621
  }, {
1542
1622
  diff: files => { job.files = files; },
1543
1623
  check: (summary: CheckSummary, wallMs: number | null) => { job.wallMs.check = wallMs; job.check = summary; },
1624
+ world,
1544
1625
  });
1545
1626
  }
1546
1627
 
1547
1628
  /**
1548
- * `POST /api/rebuild` with `{animation: {configHash, animationsFromHash, ops, args?}}` (#235): applies the cumulative
1629
+ * `POST /api/rebuild` with `{animation: {configHash, animationsFromHash, ops, args?}, environment?}` (#235): applies the cumulative
1549
1630
  * span-preserving ops directly to the handoff's `motion.animations_from` text (`REBUILD_ANIMATIONS_STALE` when
1550
1631
  * `animationsFromHash` does not match the handoff file), writes `<dir>/animations.json` and `<dir>/config.json` in
1551
1632
  * scratch, and runs `rig-parts rig` + `rigc build` + `check`. Empty or no-op ops (leaving `animations_from` equal to
1552
1633
  * the handoff text) are refused before anything is written or run; producer refusals return by name with nothing landed.
1553
1634
  */
1554
- async function startAnimation(input: unknown): Promise<{ status: number; body: unknown }> {
1635
+ async function startAnimation(input: unknown, world: ApplyWorld | null = null, rawEnvironment?: unknown): Promise<{ status: number; body: unknown }> {
1555
1636
  const request = parseAnimationRequest(input);
1556
1637
  assertStateOutside();
1557
1638
  await options.unchanged();
@@ -1574,7 +1655,15 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
1574
1655
  throw new RebuildError('REBUILD_ANIMATIONS_STALE', 'the animations_from file changed since the editor read it; reload');
1575
1656
  }
1576
1657
 
1577
- const builder = new AnimationOpBuilder(baseAnimText);
1658
+ let fallbackEasings: Record<string, [number, number, number, number]> | undefined;
1659
+ try {
1660
+ const rigMotion = JSON.parse(await readFile(join(inputs.rig, 'motion.json'), 'utf8')) as { easings?: unknown };
1661
+ if (rigMotion.easings && typeof rigMotion.easings === 'object' && !Array.isArray(rigMotion.easings)) {
1662
+ fallbackEasings = rigMotion.easings as Record<string, [number, number, number, number]>;
1663
+ }
1664
+ } catch { /* optional */ }
1665
+
1666
+ const builder = new AnimationOpBuilder(baseAnimText, fallbackEasings);
1578
1667
  try {
1579
1668
  for (const op of request.ops) builder.apply(op);
1580
1669
  } catch (e) {
@@ -1594,6 +1683,10 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
1594
1683
 
1595
1684
  const resolved = resolveProducer(options.starts);
1596
1685
  if (!resolved.ok) return { status: 200, body: { status: 'refused', error: resolved.error, producerLine: resolved.error } };
1686
+ if (world && !versionAtLeast(resolved.producer.version, CHECK_ENVIRONMENT_SINCE)) {
1687
+ const error = modelingProducerTooOld(resolved.producer.version || 'unknown', CHECK_ENVIRONMENT_SINCE, 'rig-parts check --environment');
1688
+ return { status: 200, body: { status: 'refused', error, producerLine: error } };
1689
+ }
1597
1690
  try { assertWholeRigBaseline(await settledBaseline()); } catch (e) { if (e instanceof BaselineError) throw new RebuildError(e.code, e.message.slice(e.code.length + 2)); throw e; }
1598
1691
 
1599
1692
  const opsText = animationOpsText(effectiveOps), opsSha256 = sha256(opsText), afterSha256 = sha256(splicedAnimText);
@@ -1605,6 +1698,7 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
1605
1698
  producer: `${resolved.producer.package}@${resolved.producer.version}`,
1606
1699
  compiler: `${resolved.compiler.package}@${resolved.compiler.version}`,
1607
1700
  args: request.args,
1701
+ ...(world ? { environment: world.record.sha256 } : {}),
1608
1702
  });
1609
1703
  const current = jobs.get(id);
1610
1704
  if (current?.status === 'running') return { status: 202, body: snapshot(current) };
@@ -1620,6 +1714,7 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
1620
1714
  ops: effectiveOps,
1621
1715
  ...(request.args.length ? { args: request.args } : {}),
1622
1716
  },
1717
+ ...(world && rawEnvironment !== undefined ? { environment: rawEnvironment } : {}),
1623
1718
  };
1624
1719
 
1625
1720
  return reserve(`REBUILD_BUSY: rebuild ${id} is still running`, async () => {
@@ -1652,9 +1747,10 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
1652
1747
  check: null,
1653
1748
  files: null,
1654
1749
  build: null,
1750
+ ...(world ? { environment: world.record } : {}),
1655
1751
  };
1656
1752
  jobs.set(id, job); running = id; bodies.set(id, recordedBody);
1657
- void executeAnimation(job, dir, inputs, resolved, scratchCfgText, splicedAnimText).finally(() => { if (running === id) running = null; });
1753
+ void executeAnimation(job, dir, inputs, resolved, scratchCfgText, splicedAnimText, world).finally(() => { if (running === id) running = null; });
1658
1754
  return { status: 202, body: snapshot(job) };
1659
1755
  });
1660
1756
  }
@@ -1662,8 +1758,11 @@ export function createRebuilds(p: ReviewPackage, options: RebuildOptions) {
1662
1758
  /** `POST /api/rebuild`: refusals are returned before anything is written or run. */
1663
1759
  async function start(input: unknown): Promise<{ status: number; body: unknown }> {
1664
1760
  if (input && typeof input === 'object' && !Array.isArray(input) && Object.hasOwn(input, 'animation')) {
1665
- if (Object.keys(input).length !== 1) bad('expected exactly {animation}');
1666
- return startAnimation((input as { animation: unknown }).animation);
1761
+ const keys = Object.keys(input).sort().join(',');
1762
+ if (keys !== 'animation' && keys !== 'animation,environment') bad('expected exactly {animation} or {animation, environment}');
1763
+ const rawEnv = Object.hasOwn(input, 'environment') ? (input as { environment: unknown }).environment : undefined;
1764
+ const world = rawEnv !== undefined ? parseApplyWorld(rawEnv) : null;
1765
+ return startAnimation((input as { animation: unknown }).animation, world, rawEnv);
1667
1766
  }
1668
1767
  if (input && typeof input === 'object' && !Array.isArray(input) && Object.hasOwn(input, 'retarget')) {
1669
1768
  if (Object.keys(input).length !== 1) bad('expected exactly {retarget}');