@rig-c/review 0.5.0 → 0.7.0

package/src/cut-edits.ts

@@ -0,0 +1,184 @@
+/**
+ * Cuts, patches and limbs (#115): the producer config's `assemble.cuts`, `assemble.patches` and `limbs` as the Setup
+ * Cuts block edits them on the stage. Every coordinate is rig px of the setup pose, y down — the space of `parts.json`
+ * and of the cut polygons and patch boxes (rig-parts AUTHORING §3, `assemble.cuts`: "non-negative integer rig pixels").
+ *
+ *  - a cut's polygon vertex is one anchor at `/assemble/cuts/<i>/polygon/<k>`, a `replace` op naming the cut by `into`;
+ *  - a patch's box is two corner anchors whose edit is one `replace` at `/assemble/patches/<i>/box` naming the patch;
+ *  - a limb segment below a joint has its `range` (`[min, max]` degrees from rest, `min <= 0 <= max`), a `replace` (or
+ *    `add` when the config states none, `remove` to drop it) at `/limbs/<limb>/segments/<k>/range` naming its `part`; its
+ *    joint is the lower bone's origin, which is a `bones` anchor (`src/bone-anchors.ts`) — a joint drag is a bone op;
+ *  - a new cut is `add /assemble/cuts/-` with `{from, into, polygon, draw, overlap}` (no `under`: review paints no image)
+ *    plus `add /regions/<into>` (the coverage rule wants every part a mesh or a region); a new patch is
+ *    `add /assemble/patches/-` with `{name, box, alpha, draw}` plus `add /regions/<name>` (a patch is always a region).
+ *
+ * What only the producer can judge (a polygon point past the rig, two cuts overlapping, a cut taking no pixel, an
+ * `under` no longer the polygon box's size, a name already taken, a range out of order) is the producer's refusal,
+ * shown verbatim. Review refuses before sending only what is not the loader's type: a non-integer or negative point, a
+ * polygon under three points, a range that is not two numbers. Pure: no IO, no DOM.
+ */
+import type { JsonValue, PatchOp } from './config-patch.ts';
+
+export type RigPoint = [number, number];
+export type PatchBox = [number, number, number, number];
+export type CutDraw = 'back' | 'front' | { before: string };
+export interface ConfigCut { index: number; from: string; into: string; polygon: RigPoint[]; draw: CutDraw; overlap: number; under: string | null }
+export interface ConfigPatchEntry { index: number; name: string; box: PatchBox; alpha: string; draw: CutDraw }
+export interface ConfigLimbSegment { limb: string; index: number; part: string; from: string; bone: string; joint: string | null; range: [number, number] | null }
+export interface CutsSource { cuts: ConfigCut[]; patches: ConfigPatchEntry[]; segments: ConfigLimbSegment[]; plan: string[]; skipped: string[] }
+
+const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+const intPoint = (v: unknown): RigPoint | null => Array.isArray(v) && v.length === 2 && v.every(n => typeof n === 'number' && Number.isFinite(n)) ? [v[0] as number, v[1] as number] : null;
+const draw = (v: unknown): CutDraw | null => v === 'back' || v === 'front' ? v : isObject(v) && typeof v.before === 'string' ? { before: v.before } : null;
+
+/** The config's cuts, patches, limb segments and plan part names as written; an unreadable entry is named in `skipped`. */
+export function cutsSource(config: unknown): CutsSource {
+  const out: CutsSource = { cuts: [], patches: [], segments: [], plan: [], skipped: [] };
+  if (!isObject(config)) return out;
+  const assemble = isObject(config.assemble) ? config.assemble : {};
+  if (Array.isArray(assemble.plan)) for (const row of assemble.plan) if (Array.isArray(row) && typeof row[0] === 'string') out.plan.push(row[0]);
+  if (Array.isArray(assemble.cuts)) assemble.cuts.forEach((q, index) => {
+    const polygon = isObject(q) && Array.isArray(q.polygon) ? q.polygon.map(intPoint) : [];
+    const d = isObject(q) ? draw(q.draw) : null;
+    if (!isObject(q) || typeof q.from !== 'string' || typeof q.into !== 'string' || !d || typeof q.overlap !== 'number' || polygon.length < 3 || polygon.some(p => !p)) { out.skipped.push(`assemble.cuts[${index}] is not {from, into, polygon, draw, overlap}`); return; }
+    out.cuts.push({ index, from: q.from, into: q.into, polygon: polygon as RigPoint[], draw: d, overlap: q.overlap, under: typeof q.under === 'string' ? q.under : null });
+  });
+  if (Array.isArray(assemble.patches)) assemble.patches.forEach((q, index) => {
+    const d = isObject(q) ? draw(q.draw) : null;
+    if (!isObject(q) || typeof q.name !== 'string' || !Array.isArray(q.box) || q.box.length !== 4 || !q.box.every(n => typeof n === 'number' && Number.isFinite(n)) || typeof q.alpha !== 'string' || !d) { out.skipped.push(`assemble.patches[${index}] is not {name, box, alpha, draw}`); return; }
+    out.patches.push({ index, name: q.name, box: [...q.box] as PatchBox, alpha: q.alpha, draw: d });
+  });
+  if (isObject(config.limbs)) for (const [limb, entry] of Object.entries(config.limbs)) {
+    if (!isObject(entry) || !Array.isArray(entry.segments)) { out.skipped.push(`limbs.${limb} has no segments`); continue; }
+    entry.segments.forEach((sg, index) => {
+      if (!isObject(sg) || typeof sg.part !== 'string' || typeof sg.from !== 'string' || typeof sg.bone !== 'string') { out.skipped.push(`limbs.${limb}.segments[${index}] is not {part, from, bone}`); return; }
+      const range = Array.isArray(sg.range) && sg.range.length === 2 && sg.range.every(n => typeof n === 'number' && Number.isFinite(n)) ? [sg.range[0], sg.range[1]] as [number, number] : null;
+      out.segments.push({ limb, index, part: sg.part, from: sg.from, bone: sg.bone, joint: typeof sg.joint === 'string' ? sg.joint : null, range });
+    });
+  }
+  return out;
+}
+
+export class CutEditError extends Error { constructor(readonly code: string, detail: string) { super(`${code}: ${detail}`); } }
+
+/** One pending edit, keyed by its pointer; `value` is the whole new value at that pointer (or `null` to remove a range). */
+export type CutEdit =
+  | { kind: 'vertex'; path: string; name: string; label: string; from: RigPoint; value: RigPoint }
+  | { kind: 'box'; path: string; name: string; label: string; from: PatchBox; value: PatchBox }
+  | { kind: 'range'; path: string; name: string; label: string; from: [number, number] | null; value: [number, number] | null };
+/** A new cut or patch, placed on the stage; it becomes two `add` ops (the entry and its `regions` bone). */
+export type CutAdd =
+  | { kind: 'cut'; from: string; into: string; polygon: RigPoint[]; draw: CutDraw; overlap: number; bone: string }
+  | { kind: 'patch'; name: string; box: PatchBox; alpha: 'silhouette' | 'box'; draw: CutDraw; bone: string };
+
+export const vertexPath = (cut: number, k: number) => `/assemble/cuts/${cut}/polygon/${k}`;
+export const boxPath = (patch: number) => `/assemble/patches/${patch}/box`;
+export const rangePath = (limb: string, k: number) => `/limbs/${limb.replace(/~/g, '~0').replace(/\//g, '~1')}/segments/${k}/range`;
+
+/** A rig px value as the loader takes it: a non-negative integer (`CONFIG_FIELD_TYPE` otherwise). */
+function rigInt(v: number, what: string): number {
+  if (!Number.isInteger(v) || v < 0) throw new CutEditError('CUTS_VALUE_INVALID', `${what} must be a non-negative integer of rig px (the config's polygons and boxes are)`);
+  return v;
+}
+const same = (a: readonly number[] | null, b: readonly number[] | null) => a === b || (!!a && !!b && a.length === b.length && a.every((v, i) => v === b[i]));
+
+/** Set a cut vertex; a value equal to the config's removes the pending edit. */
+export function setVertex(edits: ReadonlyMap<string, CutEdit>, cut: ConfigCut, k: number, value: RigPoint): Map<string, CutEdit> {
+  const from = cut.polygon[k];
+  if (!from) throw new CutEditError('CUTS_VERTEX_UNKNOWN', `${cut.into} has no vertex ${k}`);
+  const v: RigPoint = [rigInt(value[0], `${cut.into} vertex ${k} x`), rigInt(value[1], `${cut.into} vertex ${k} y`)];
+  const next = new Map(edits), path = vertexPath(cut.index, k);
+  if (same(v, from)) next.delete(path); else next.set(path, { kind: 'vertex', path, name: cut.into, label: `${cut.into} vertex ${k}`, from: [...from], value: v });
+  return next;
+}
+/** Set a patch box (`[x0, y0, x1, y1]`, `x1`/`y1` exclusive); a box equal to the config's removes the edit. */
+export function setBox(edits: ReadonlyMap<string, CutEdit>, patch: ConfigPatchEntry, value: PatchBox): Map<string, CutEdit> {
+  const v = value.map((n, i) => rigInt(n, `${patch.name} box[${i}]`)) as PatchBox;
+  if (v[2] <= v[0] || v[3] <= v[1]) throw new CutEditError('CUTS_VALUE_INVALID', `${patch.name} box must have x1 > x0 and y1 > y0`);
+  const next = new Map(edits), path = boxPath(patch.index);
+  if (same(v, patch.box)) next.delete(path); else next.set(path, { kind: 'box', path, name: patch.name, label: `${patch.name} box`, from: [...patch.box] as PatchBox, value: v });
+  return next;
+}
+/** Set (or with null, drop) a segment's range; only a segment below a joint takes one (the loader's `CONFIG_KEY_KNOWN`). */
+export function setRange(edits: ReadonlyMap<string, CutEdit>, segment: ConfigLimbSegment, value: [number, number] | null): Map<string, CutEdit> {
+  if (!segment.joint) throw new CutEditError('CUTS_RANGE_UPPER', `${segment.part} is the upper segment of ${segment.limb}; only a segment below a joint takes a range`);
+  if (value && !value.every(n => typeof n === 'number' && Number.isFinite(n))) throw new CutEditError('CUTS_VALUE_INVALID', `${segment.part} range must be two numbers of degrees`);
+  const next = new Map(edits), path = rangePath(segment.limb, segment.index);
+  if (same(value, segment.range)) next.delete(path); else next.set(path, { kind: 'range', path, name: segment.part, label: `${segment.limb} ${segment.joint} range (${segment.part})`, from: segment.range ? [...segment.range] : null, value: value ? [...value] : null });
+  return next;
+}
+/** Where a vertex stands now: its pending value, else the config's. */
+export const vertexAt = (edits: ReadonlyMap<string, CutEdit>, cut: ConfigCut, k: number): RigPoint => (edits.get(vertexPath(cut.index, k)) as Extract<CutEdit, { kind: 'vertex' }> | undefined)?.value ?? cut.polygon[k]!;
+export const boxAt = (edits: ReadonlyMap<string, CutEdit>, patch: ConfigPatchEntry): PatchBox => (edits.get(boxPath(patch.index)) as Extract<CutEdit, { kind: 'box' }> | undefined)?.value ?? patch.box;
+export const rangeAt = (edits: ReadonlyMap<string, CutEdit>, s: ConfigLimbSegment): [number, number] | null => { const e = edits.get(rangePath(s.limb, s.index)) as Extract<CutEdit, { kind: 'range' }> | undefined; return e ? e.value : s.range; };
+
+/** A drag moves a point by the pointer's delta snapped to whole rig px. */
+export const dragPoint = (from: RigPoint, start: RigPoint, now: RigPoint): RigPoint => [0, 1].map(i => { const d = Math.round(now[i]! - start[i]!); return from[i]! + (d === 0 ? 0 : d); }) as RigPoint;
+
+/**
+ * The pending edits and additions as config patch ops, in order: the edits (each one op at its own pointer, naming its
+ * entry), then each addition's entry and its `regions` bone. A new name is not checked against the config: the
+ * producer's `CONFIG_PART_UNIQUE` says so, verbatim.
+ */
+export function cutOps(edits: ReadonlyMap<string, CutEdit>, adds: readonly CutAdd[], config: unknown): PatchOp[] {
+  const ops: PatchOp[] = [];
+  for (const e of edits.values()) {
+    if (e.kind === 'range') {
+      if (e.value === null) ops.push({ op: 'remove', path: e.path, name: e.name });
+      else ops.push({ op: e.from === null ? 'add' : 'replace', path: e.path, value: [...e.value], name: e.name });
+    } else ops.push({ op: 'replace', path: e.path, value: [...e.value], name: e.name });
+  }
+  const assemble = isObject(config) && isObject(config.assemble) ? config.assemble : {};
+  let cuts = Array.isArray(assemble.cuts) ? assemble.cuts.length : null, patches = Array.isArray(assemble.patches) ? assemble.patches.length : null;
+  let regions = isObject(config) && isObject(config.regions);
+  for (const a of adds) {
+    const list = a.kind === 'cut' ? 'cuts' : 'patches', has = a.kind === 'cut' ? cuts !== null : patches !== null;
+    const entry: JsonValue = a.kind === 'cut'
+      ? { from: a.from, into: a.into, polygon: a.polygon.map(p => [rigInt(p[0], `${a.into} x`), rigInt(p[1], `${a.into} y`)]), draw: a.draw as JsonValue, overlap: rigInt(a.overlap, `${a.into} overlap`) }
+      : { name: a.name, box: a.box.map((n, i) => rigInt(n, `${a.name} box[${i}]`)), alpha: a.alpha, draw: a.draw as JsonValue };
+    if (a.kind === 'cut' && a.polygon.length < 3) throw new CutEditError('CUTS_POLYGON_SHORT', `${a.into} needs at least three points`);
+    ops.push(has ? { op: 'add', path: `/assemble/${list}/-`, value: entry } : { op: 'add', path: `/assemble/${list}`, value: [entry] });
+    if (a.kind === 'cut') cuts = (cuts ?? 0) + 1; else patches = (patches ?? 0) + 1;
+    const name = a.kind === 'cut' ? a.into : a.name;
+    if (!regions) { ops.push({ op: 'add', path: '/regions', value: {} }); regions = true; }
+    ops.push({ op: 'add', path: `/regions/${name.replace(/~/g, '~0').replace(/\//g, '~1')}`, value: a.bone });
+  }
+  return ops;
+}
+
+/**
+ * A segment's range as an arc for the overlay: the joint (the lower bone's origin), the bone's rest direction (rig px,
+ * y down) and the two ends `min`, `max` turned counter-clockwise on screen (rigc's sense), sampled every `step` degrees.
+ */
+export function rangeArc(joint: RigPoint, toward: RigPoint, range: [number, number], radius: number, step = 5): RigPoint[] {
+  const rest = Math.atan2(toward[1] - joint[1], toward[0] - joint[0]);
+  const [lo, hi] = range[0] <= range[1] ? range : [range[1], range[0]];
+  const out: RigPoint[] = [[joint[0], joint[1]]];
+  for (let d = lo; ; d = Math.min(hi, d + step)) {
+    // Counter-clockwise on screen with y down is a negative angle in rig px.
+    const a = rest - (d * Math.PI) / 180;
+    out.push([joint[0] + radius * Math.cos(a), joint[1] + radius * Math.sin(a)]);
+    if (d >= hi) break;
+  }
+  return out;
+}
+
+export const CUTS_DRAFT_SCHEMA = 'rig-review-cuts-draft/1';
+export const cutsDraftText = (edits: ReadonlyMap<string, CutEdit>, adds: readonly CutAdd[]) => JSON.stringify({ schema: CUTS_DRAFT_SCHEMA, edits: [...edits.values()], adds });
+/** Edits back from a draft, kept only where the pointer still names the same entry with the same config value. */
+export function cutsDraft(text: string, source: CutsSource): { edits: Map<string, CutEdit>; adds: CutAdd[] } {
+  const empty = { edits: new Map<string, CutEdit>(), adds: [] as CutAdd[] };
+  let doc: unknown;
+  try { doc = JSON.parse(text); } catch { return empty; }
+  if (!isObject(doc) || doc.schema !== CUTS_DRAFT_SCHEMA || !Array.isArray(doc.edits)) return empty;
+  let edits = new Map<string, CutEdit>();
+  for (const e of doc.edits as CutEdit[]) {
+    try {
+      if (e.kind === 'vertex') { const m = /^\/assemble\/cuts\/(\d+)\/polygon\/(\d+)$/.exec(e.path); const cut = m ? source.cuts.find(c => c.index === Number(m[1])) : undefined; if (cut && cut.into === e.name && same(cut.polygon[Number(m![2])] ?? null, e.from)) edits = setVertex(edits, cut, Number(m![2]), e.value); }
+      else if (e.kind === 'box') { const patch = source.patches.find(q => boxPath(q.index) === e.path); if (patch && patch.name === e.name && same(patch.box, e.from)) edits = setBox(edits, patch, e.value); }
+      else if (e.kind === 'range') { const s = source.segments.find(g => rangePath(g.limb, g.index) === e.path); if (s && s.part === e.name && same(s.range, e.from)) edits = setRange(edits, s, e.value); }
+    } catch { /* a draft value the editor would refuse is dropped */ }
+  }
+  const adds = Array.isArray(doc.adds) ? (doc.adds as CutAdd[]).filter(a => isObject(a) && (a.kind === 'cut' || a.kind === 'patch')) : [];
+  return { edits, adds };
+}

package/src/environment.ts

@@ -0,0 +1,226 @@
+/**
+ * Inspection-only environment for Animate: a pure wind model (base, breeze, gust),
+ * the jolt packet, the drag-to-trail mapping and the read-only physics constraint
+ * list. Nothing here writes the model or motion; the player stays the only solver.
+ *
+ * The wind model ports the semantics of the public parts-examples viewer's
+ * `wind-controls.mjs`: the same breeze formula, gust envelope, repeat period and
+ * limits. Its clock is advanced by the caller with the step the player takes, so a
+ * paused player freezes the gust.
+ */
+import type {Json} from './manifest.ts';
+
+export const BASE_WIND_LIMIT=100;
+export const MAX_GUST_PEAK=200;
+export const MIN_GUST_DURATION=0.1;
+export const MAX_GUST_DURATION=20;
+export const GUST_DURATION=2.4;
+export const GUST_PEAK=48;
+export const GUST_PERIOD=6;
+export const GRAVITY_MIN=0;
+export const GRAVITY_MAX=4;
+export const GRAVITY_DEFAULT=1;
+/** `@rig-c/play`'s start values (`environment(null)`): x right, y down. */
+export const RUNTIME_START={wind:[1,0] as [number,number],gravity:[0,1] as [number,number]};
+
+const bounded=(value:number,min:number,max:number,name:string):number=>{
+ if(!Number.isFinite(value)||value<min||value>max)throw new RangeError(`${name} must be finite and within [${min}, ${max}]`);
+ return value;
+};
+
+/** The gentle breeze at clock time `t`. */
+export function breezeAt(t:number):number {return 2*Math.sin(2.2*t)+0.8*Math.sin(5.1*t);}
+/** One gust pulse `peak·sin²(π·age/duration)` inside `[0, duration)`, 0 outside. */
+export function gustEnvelope(age:number,peak:number,duration:number):number {
+ return age>=0&&age<duration?peak*Math.sin(Math.PI*age/duration)**2:0;
+}
+/** Repeat period: never shorter than GUST_PERIOD, and 0.6 s of calm after a long pulse. */
+export function gustPeriod(duration:number):number {return Math.max(GUST_PERIOD,duration+0.6);}
+
+export interface WindSnapshot {version:1;base:number;breeze:boolean;repeat:boolean;gustPeak:number;gustDuration:number}
+export interface WindReading {
+ base:number;breeze:boolean;repeat:boolean;time:number;
+ /** The breeze term (0 when the breeze is off). */
+ gentle:number;gust:number;gusting:boolean;
+ /** Seconds since the active pulse began, or null when no pulse was started. */
+ gustAge:number|null;
+ wind:number;gustPeak:number;gustDuration:number;activeGustPeak:number;activeGustDuration:number;
+}
+export interface WindModel {
+ read():WindReading;snapshot():WindSnapshot;restore(value:WindSnapshot|null):void;
+ setBase(value:number):void;setGustPeak(value:number):void;setGustDuration(value:number):void;
+ setBreeze(value:boolean):void;setRepeat(value:boolean):void;triggerGust():void;
+ advance(dt:number):WindReading;
+ /** The whole standing state, clock and active pulse included (#103: an Apply's reload resumes the same world). */
+ state():WindState;resume(value:WindState):void;
+}
+export interface WindState {snapshot:WindSnapshot;time:number;gustStart:number|null;gustDirection:number;nextGust:number|null;activeGustPeak:number;activeGustDuration:number}
+export const defaultWindSnapshot=():WindSnapshot=>({version:1,base:0,breeze:false,repeat:false,gustPeak:GUST_PEAK,gustDuration:GUST_DURATION});
+
+export function createWindModel():WindModel {
+ let base=0,breeze=false,repeat=false,time=0,gustStart:number|null=null,gustDirection=1,nextGust:number|null=null;
+ let gustPeak=GUST_PEAK,gustDuration=GUST_DURATION,activeGustPeak=GUST_PEAK,activeGustDuration=GUST_DURATION;
+ function start(at:number):void {
+  gustStart=at;gustDirection=base<0?-1:1;activeGustPeak=gustPeak;activeGustDuration=gustDuration;
+  if(repeat)nextGust=at+gustPeriod(activeGustDuration);
+ }
+ function read():WindReading {
+  const age=gustStart===null?activeGustDuration:time-gustStart;
+  const gusting=age>=0&&age<activeGustDuration;
+  const gust=gusting?gustDirection*gustEnvelope(age,activeGustPeak,activeGustDuration):0;
+  const gentle=breeze?breezeAt(time):0;
+  return {base,breeze,repeat,time,gentle,gust,gusting,gustAge:gustStart===null?null:age,wind:base+gentle+gust,gustPeak,gustDuration,activeGustPeak,activeGustDuration};
+ }
+ return {
+  read,
+  snapshot:()=>({version:1,base,breeze,repeat,gustPeak,gustDuration}),
+  restore(value){
+   const s=value===null?defaultWindSnapshot():value;
+   if(!s||typeof s!=='object'||Array.isArray(s)||s.version!==1)throw new RangeError('wind snapshot must be a version 1 object');
+   // Validate the complete configuration before changing the standing state.
+   const nextBase=bounded(s.base,-BASE_WIND_LIMIT,BASE_WIND_LIMIT,'base wind');
+   const nextPeak=bounded(s.gustPeak,0,MAX_GUST_PEAK,'gust peak');
+   const nextDuration=bounded(s.gustDuration,MIN_GUST_DURATION,MAX_GUST_DURATION,'gust duration');
+   if(typeof s.breeze!=='boolean'||typeof s.repeat!=='boolean')throw new RangeError('wind snapshot breeze and repeat must be booleans');
+   base=nextBase;gustPeak=nextPeak;gustDuration=nextDuration;breeze=s.breeze;repeat=s.repeat;
+   time=0;gustStart=null;gustDirection=1;nextGust=null;activeGustPeak=gustPeak;activeGustDuration=gustDuration;
+   if(repeat)start(0);
+  },
+  setBase(value){base=bounded(value,-BASE_WIND_LIMIT,BASE_WIND_LIMIT,'base wind');},
+  setGustPeak(value){gustPeak=bounded(value,0,MAX_GUST_PEAK,'gust peak');},
+  setGustDuration(value){gustDuration=bounded(value,MIN_GUST_DURATION,MAX_GUST_DURATION,'gust duration');},
+  setBreeze(value){breeze=Boolean(value);},
+  // A click cannot interrupt a pulse.
+  triggerGust(){if(!read().gusting)start(time);},
+  setRepeat(value){
+   const enabled=Boolean(value);if(enabled===repeat)return;repeat=enabled;
+   if(repeat){if(read().gusting)nextGust=gustStart!+gustPeriod(activeGustDuration);else start(time);}
+   else nextGust=null; // Finish the active pulse before returning to base.
+  },
+  state:()=>({snapshot:{version:1,base,breeze,repeat,gustPeak,gustDuration},time,gustStart,gustDirection,nextGust,activeGustPeak,activeGustDuration}),
+  resume(value){
+   const saved=structuredClone(value);this.restore(saved.snapshot);
+   time=saved.time;gustStart=saved.gustStart;gustDirection=saved.gustDirection;nextGust=saved.nextGust;activeGustPeak=saved.activeGustPeak;activeGustDuration=saved.activeGustDuration;
+  },
+  advance(dt){
+   if(!Number.isFinite(dt)||dt<0||!Number.isFinite(time+dt))throw new RangeError('wind dt must be finite, non-negative and keep a finite clock');
+   time+=dt;
+   if(repeat&&nextGust!==null&&time>=nextGust){const interval=gustPeriod(gustDuration);start(nextGust+Math.floor((time-nextGust)/interval)*interval);}
+   return read();
+  },
+ };
+}
+
+/** The value `player.environment` receives for a reading: wind along x, gravity down. */
+export function environmentFor(reading:WindReading,gravity:number):{wind:[number,number];gravity:[number,number]} {
+ return {wind:[reading.wind,0],gravity:[0,bounded(gravity,GRAVITY_MIN,GRAVITY_MAX,'gravity')]};
+}
+
+const fixed=(value:number,digits=1)=>(Object.is(value,-0)?0:value).toFixed(digits);
+/** `wind: base + breeze + gust = total` with the gust phase and the stepped clock. */
+export function windReadout(reading:WindReading,gravity:number):string {
+ const phase=reading.gusting&&reading.gustAge!==null?` · gust ${reading.gustAge.toFixed(2)}/${reading.activeGustDuration.toFixed(2)} s`:'';
+ return `wind: ${fixed(reading.base)} + ${fixed(reading.gentle)} + ${fixed(reading.gust)} = ${fixed(reading.wind)} · gravity ${fixed(gravity,2)} · t ${reading.time.toFixed(3)} s${phase}`;
+}
+export const RUNTIME_START_READOUT=`Runtime start values · wind [${RUNTIME_START.wind.join(', ')}] · gravity [${RUNTIME_START.gravity.join(', ')}] · controls not applied`;
+
+/** The example's jolt: translate (18, −10), then the inverse 0.09 s later. */
+export interface JoltStep {at:number;x:number;y:number}
+export const JOLT_DELAY=0.09;
+export function joltPacket(start:number):JoltStep[] {return [{at:start,x:18,y:-10},{at:start+JOLT_DELAY,x:-18,y:10}];}
+/** Splits a queue into the steps due at `now` (in order) and the rest. */
+export function dueJolts(queue:readonly JoltStep[],now:number):{due:JoltStep[];pending:JoltStep[]} {
+ const due:JoltStep[]=[],pending:JoltStep[]=[];for(const step of queue)(step.at<=now?due:pending).push(step);
+ due.sort((a,b)=>a.at-b.at);return {due,pending};
+}
+
+/** A page-pixel pointer delta as `player.moved` wants it: ÷ the root's scale, y negated (world y up). */
+export function dragMoved(dx:number,dy:number,scale:number):{x:number;y:number}|null {
+ if(!Number.isFinite(dx)||!Number.isFinite(dy)||!Number.isFinite(scale)||scale<=0)return null;
+ return {x:dx/scale,y:-dy/scale};
+}
+
+/** Columns read as the compiled model declares them; an absent field stays absent. */
+export const PHYSICS_FIELDS=['wind','gravity','inertia','strength','damping','mix'] as const;
+export type PhysicsField=typeof PHYSICS_FIELDS[number];
+export interface PhysicsConstraintRow {name:string;bone:string|null;declaredIn:string|null;values:Partial<Record<PhysicsField,number>>}
+export type PhysicsConstraints={available:true;rows:PhysicsConstraintRow[]}|{available:false;reason:string};
+export const CONSTRAINT_MIX_READONLY='CONSTRAINT_MIX_READONLY: @rig-c/play exposes no per-constraint mix';
+
+/** Lists the document's `constraints` entries of kind `physics` in their order; nothing is computed or defaulted. */
+export function physicsConstraints(document:unknown):PhysicsConstraints {
+ if(!document||typeof document!=='object'||Array.isArray(document))return {available:false,reason:'PHYSICS_CONSTRAINTS_UNAVAILABLE: model document is not an object'};
+ const list=(document as Record<string,unknown>).constraints;
+ if(!Array.isArray(list))return {available:false,reason:'PHYSICS_CONSTRAINTS_UNAVAILABLE: model declares no constraints list'};
+ const rows:PhysicsConstraintRow[]=[];
+ for(const item of list){
+  if(!item||typeof item!=='object'||Array.isArray(item))continue;
+  const entry=item as Record<string,unknown>;if(entry.kind!=='physics')continue;
+  if(typeof entry.name!=='string'||!entry.name)return {available:false,reason:'PHYSICS_CONSTRAINTS_UNAVAILABLE: a physics constraint has no name'};
+  const values:Partial<Record<PhysicsField,number>>={};
+  for(const field of PHYSICS_FIELDS){const value=entry[field];if(typeof value==='number'&&Number.isFinite(value))values[field]=value;}
+  rows.push({name:entry.name,bone:typeof entry.bone==='string'?entry.bone:null,declaredIn:typeof entry.declaredIn==='string'?entry.declaredIn:null,values});
+ }
+ if(!rows.length)return {available:false,reason:'PHYSICS_CONSTRAINTS_UNAVAILABLE: model declares no physics constraints'};
+ return {available:true,rows};
+}
+
+/** The reviewed model document, its bytes hash-checked against the reviewed identity first. */
+export async function loadModelDocument(url:string,sha256:string,fetcher:typeof fetch=fetch):Promise<{ok:true;document:unknown}|{ok:false;reason:string}> {
+ const response=await fetcher(url);if(!response.ok)return {ok:false,reason:`model request failed (${response.status})`};
+ const bytes=await response.arrayBuffer();if(bytes.byteLength>128*1024*1024)return {ok:false,reason:'model exceeds 128 MiB'};
+ const hash=[...new Uint8Array(await crypto.subtle.digest('SHA-256',bytes))].map(v=>v.toString(16).padStart(2,'0')).join('');
+ if(hash!==sha256)return {ok:false,reason:'model bytes differ from reviewed SHA-256'};
+ try{return {ok:true,document:JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(bytes))};}
+ catch(error){return {ok:false,reason:error instanceof Error?error.message:String(error)};}
+}
+/** Reads the reviewed model bytes (hash-checked against the reviewed identity) and lists its physics constraints. */
+export async function loadPhysicsConstraints(url:string,sha256:string,fetcher:typeof fetch=fetch):Promise<PhysicsConstraints> {
+ const loaded=await loadModelDocument(url,sha256,fetcher);
+ return loaded.ok?physicsConstraints(loaded.document):{available:false,reason:`PHYSICS_CONSTRAINTS_UNAVAILABLE: ${loaded.reason}`};
+}
+
+/** What a feedback record keeps of the environment it was written under. */
+export interface EnvironmentContext {
+ applied:boolean;
+ wind:{base:number;breeze:boolean;gust:{peak:number;duration:number;repeat:boolean;active:boolean;value:number};total:number};
+ gravity:number;
+ /** What the player reported standing when the note was written (x right, y down). */
+ standing:{wind:[number,number];gravity:[number,number]};
+}
+export function environmentContext(reading:WindReading,gravity:number,applied:boolean,standing:{wind:readonly number[];gravity:readonly number[]}):EnvironmentContext {
+ return {applied,wind:{base:reading.base,breeze:reading.breeze,gust:{peak:reading.gusting?reading.activeGustPeak:reading.gustPeak,duration:reading.gusting?reading.activeGustDuration:reading.gustDuration,repeat:reading.repeat,active:reading.gusting,value:reading.gust},total:reading.wind},gravity,standing:{wind:[standing.wind[0]!,standing.wind[1]!],gravity:[standing.gravity[0]!,standing.gravity[1]!]}};
+}
+
+const fail=(field:string,expected:string):never=>{throw new Error(`feedback.context.environment${field}: expected ${expected}`);};
+const exactKeys=(value:unknown,keys:readonly string[],field:string):Record<string,unknown>=>{
+ if(!value||typeof value!=='object'||Array.isArray(value))fail(field,'object');
+ const o=value as Record<string,unknown>;
+ for(const key of Object.keys(o))if(!keys.includes(key))fail(field,`only ${keys.join(', ')}`);
+ return o;
+};
+const finite=(value:unknown,field:string):number=>typeof value==='number'&&Number.isFinite(value)?value:fail(field,'finite number');
+const flag=(value:unknown,field:string):boolean=>typeof value==='boolean'?value:fail(field,'boolean');
+const pair=(value:unknown,field:string):[number,number]=>Array.isArray(value)&&value.length===2?[finite(value[0],field),finite(value[1],field)]:fail(field,'[x, y]');
+/** Validates `context.environment`; null means no compiled model was drawn. Absent stays valid for older records. */
+export function parseEnvironmentContext(value:unknown):EnvironmentContext|null {
+ if(value===null)return null;
+ const o=exactKeys(value,['applied','wind','gravity','standing'],'');
+ const wind=exactKeys(o.wind,['base','breeze','gust','total'],'.wind'),gust=exactKeys(wind.gust,['peak','duration','repeat','active','value'],'.wind.gust'),standing=exactKeys(o.standing,['wind','gravity'],'.standing');
+ const result:EnvironmentContext={applied:flag(o.applied,'.applied'),
+  wind:{base:finite(wind.base,'.wind.base'),breeze:flag(wind.breeze,'.wind.breeze'),gust:{peak:finite(gust.peak,'.wind.gust.peak'),duration:finite(gust.duration,'.wind.gust.duration'),repeat:flag(gust.repeat,'.wind.gust.repeat'),active:flag(gust.active,'.wind.gust.active'),value:finite(gust.value,'.wind.gust.value')},total:finite(wind.total,'.wind.total')},
+  gravity:finite(o.gravity,'.gravity'),standing:{wind:pair(standing.wind,'.standing.wind'),gravity:pair(standing.gravity,'.standing.gravity')}};
+ if(Math.abs(result.wind.base)>BASE_WIND_LIMIT)fail('.wind.base',`within ±${BASE_WIND_LIMIT}`);
+ if(result.wind.gust.peak<0||result.wind.gust.peak>MAX_GUST_PEAK)fail('.wind.gust.peak',`within [0, ${MAX_GUST_PEAK}]`);
+ if(result.wind.gust.duration<MIN_GUST_DURATION||result.wind.gust.duration>MAX_GUST_DURATION)fail('.wind.gust.duration',`within [${MIN_GUST_DURATION}, ${MAX_GUST_DURATION}]`);
+ if(result.gravity<GRAVITY_MIN||result.gravity>GRAVITY_MAX)fail('.gravity',`within [${GRAVITY_MIN}, ${GRAVITY_MAX}]`);
+ return result;
+}
+/** One line for issue text: "under gust 48 / wind 30". */
+export function environmentSummary(value:EnvironmentContext):string {
+ const s=value.standing,standing=`standing wind [${s.wind.join(', ')}] · gravity [${s.gravity.join(', ')}]`;
+ if(!value.applied)return `runtime start values · ${standing}`;
+ const w=value.wind,gust=w.gust.active?`gust ${w.gust.peak} over ${w.gust.duration} s (now ${fixed(w.gust.value)})`:`gust idle (peak ${w.gust.peak}, ${w.gust.duration} s)`;
+ return `wind ${w.base}${w.breeze?' + breeze':''} · ${gust}${w.gust.repeat?' · repeat':''} · total ${fixed(w.total)} · gravity ${value.gravity} · ${standing}`;
+}
+export const environmentJson=(value:EnvironmentContext):Json=>JSON.parse(JSON.stringify(value)) as Json;

package/src/feedback-export.ts

@@ -4,6 +4,9 @@ import type { CompareBinding } from './compare.ts';
 import type { CompareSession } from './compare-session.ts';
 import type { FeedbackHistory, HistoryRetrieval } from './session-history.ts';
 import type { ReferenceBinding } from './reference.ts';
+import { environmentSummary, parseEnvironmentContext } from './environment.ts';
+import { appliedSummary } from './applied-context.ts';
+import { requirementsSummaryLine } from './requirements.ts';
 type Category = Feedback['category'];
 type Side = 'single' | 'a' | 'b';
 type ParsedFeedbackSession = FeedbackHistory<ReviewSession | CompareSession>;
@@ -155,6 +158,24 @@ function jsonBlock(value: unknown): string {
   return `${fence}json\n${json}\n${fence}`;
 }
 
+/** "Under gust 48 / wind 30": a readable line when the record carries a valid environment; the raw context still follows. */
+function environmentLine(context: Json | undefined): string[] {
+  if (context === undefined || context === null || typeof context !== 'object' || Array.isArray(context) || !('environment' in context)) return [];
+  try { const value = parseEnvironmentContext(context.environment); return [`- Environment: ${value === null ? 'no compiled model drawn' : feedbackMarkdownText(environmentSummary(value))}`]; }
+  catch { return []; }
+}
+/** "Applied: patch … · check PASS": the build the note was written on, when the record carries a valid applied state. */
+function appliedLine(context: Json | undefined): string[] {
+  if (context === undefined || context === null || typeof context !== 'object' || Array.isArray(context) || !('applied' in context)) return [];
+  const text = appliedSummary(context.applied);
+  return text === null ? [] : [`- Applied: ${feedbackMarkdownText(text)}`];
+}
+/** "Requirements: 3 declared · requirements file sha256 … · requirements: …": the declared requirements the note carries (#113). */
+function requirementsLine(context: Json | undefined): string[] {
+  if (context === undefined || context === null || typeof context !== 'object' || Array.isArray(context) || !('requirements' in context)) return [];
+  const text = requirementsSummaryLine(context.requirements);
+  return text === null ? [] : [`- Requirements: ${feedbackMarkdownText(text)}`];
+}
 /** Local issue-ready text only. No issue creation, clock inference or source IO. */
 export function formatFeedbackIssues(input: ParsedFeedbackSession): string {
   const model = groupFeedbackIssues(input), md = feedbackMarkdownText;
@@ -185,7 +206,10 @@ export function formatFeedbackIssues(input: ParsedFeedbackSession): string {
           `- Target: ${md(item.target.kind)}: ${md(item.target.name)}`,
           `- Inclusive frames: ${item.frameStart}–${item.frameEnd}`,
           `- Side: ${item.side}`,
-          `- Summary: ${md(item.summary)}`, '',
+          `- Summary: ${md(item.summary)}`,
+          ...environmentLine(item.context),
+          ...appliedLine(item.context),
+          ...requirementsLine(item.context), '',
           'Selected build identity:', '', jsonBlock(item.selectedSource));
         if (model.pairedBinding) lines.push('', 'Paired comparison binding:', '', jsonBlock(model.pairedBinding));
         if (item.warnings.length) lines.push('', 'Validation warnings (record retained):', '', jsonBlock(item.warnings));

package/src/front.ts

@@ -55,6 +55,17 @@ export function frontRoute(mode:'single'|'compare',method:string,path:string):Ro
  const reads=mode==='single'?['/api/review','/review-reference']:['/api/compare','/api/compare/reference-frames','/compare-reference'];
  if(reads.includes(path))return read?get:null;
  if((mode==='single'?/^\/assets\/[^/]/:/^\/compare-assets\/(a|b)\/[^/]/).test(path))return read?get:null;
+ // Apply · Rebuild (single only): status, one typed request, a job's status and its served scratch build.
+ if(mode==='single'&&path==='/api/rebuild')return read?get:method==='POST'?{mutation:true,limit:64*1024,timeoutMs:30000,control:false}:null;
+ if(mode==='single'&&(/^\/api\/rebuild\/[a-f0-9]{64}$/.test(path)||/^\/rebuild\/[a-f0-9]{64}\/[^/]/.test(path)))return read?get:null;
+ // Bones check (#109, single only): one typed request {ops, configHash}, answered in the response.
+ if(mode==='single'&&path==='/api/bones-check')return method==='POST'?{mutation:true,limit:64*1024,timeoutMs:60000,control:false}:null;
+ // Readings (#108, single only): one typed request, then its job's status.
+ if(mode==='single'&&path==='/api/readings')return method==='POST'?{mutation:true,limit:16*1024,timeoutMs:30000,control:false}:null;
+ if(mode==='single'&&/^\/api\/readings\/[a-f0-9]{64}$/.test(path))return read?get:null;
+ // Declared requirements (#113, single only): the stage's catalog, one typed request, then its job's status.
+ if(mode==='single'&&path==='/api/requirements')return read?get:method==='POST'?{mutation:true,limit:64*1024,timeoutMs:30000,control:false}:null;
+ if(mode==='single'&&/^\/api\/requirements\/[a-f0-9]{64}$/.test(path))return read?get:null;
  return null;
 }
 async function boundedBody(req:Request,limit:number,timeoutMs=10000):Promise<ArrayBuffer>{