@rig-c/review 0.4.0 → 0.6.0

package/src/environment.ts

@@ -0,0 +1,213 @@
+/**
+ * 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;
+}
+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.
+  },
+  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};
+}
+
+/** 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 response=await fetcher(url);if(!response.ok)return {available:false,reason:`PHYSICS_CONSTRAINTS_UNAVAILABLE: model request failed (${response.status})`};
+ const bytes=await response.arrayBuffer();if(bytes.byteLength>128*1024*1024)return {available:false,reason:'PHYSICS_CONSTRAINTS_UNAVAILABLE: 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 {available:false,reason:'PHYSICS_CONSTRAINTS_UNAVAILABLE: model bytes differ from reviewed SHA-256'};
+ try{return physicsConstraints(JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(bytes)));}
+ catch(error){return {available:false,reason:`PHYSICS_CONSTRAINTS_UNAVAILABLE: ${error instanceof Error?error.message:String(error)}`};}
+}
+
+/** 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,7 @@ 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';
 type Category = Feedback['category'];
 type Side = 'single' | 'a' | 'b';
 type ParsedFeedbackSession = FeedbackHistory<ReviewSession | CompareSession>;
@@ -155,6 +156,12 @@ 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 []; }
+}
 /** 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 +192,8 @@ 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), '',
           '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/mesh-edit.ts

@@ -0,0 +1,287 @@
+/**
+ * Mesh edit (Setup): a typed delta over the actual loaded mesh attachment of one slot. Pure — no DOM, no I/O.
+ *
+ * The source is the attachment the hash-verified model declares, with its vertices taken from the last drawn pose of
+ * that slot and mapped to crop pixels (x right, y down) through the same crop mapping as the chest regions. Ops are
+ * recorded in order; nothing is retriangulated here — the preview draws the delta over the original triangulation and
+ * the producer (#45) owns the mesher. Vertex ids are stable: the source vertices keep their indices, an added vertex
+ * takes the next id after every vertex that existed before it, and a removed vertex keeps its id (it is only marked).
+ */
+export type Vec = [number, number];
+export type MeshOp =
+  | { op: 'move'; v: number; from: Vec; to: Vec }
+  | { op: 'add'; at: Vec; onEdge?: [number, number] }
+  | { op: 'remove'; v: number }
+  | { op: 'edge'; a: number; b: number }
+  | { op: 'unedge'; a: number; b: number };
+export type EdgeKind = 'hull' | 'interior' | 'constraint';
+export interface MeshEdge { a: number; b: number; kind: EdgeKind }
+export interface MeshSource {
+  slot: string; skin: string; attachment: string;
+  /** Crop px, x right, y down, one per source vertex. */
+  vertices: readonly Vec[];
+  triangles: readonly number[];
+  /** The model's `hull`: the first `hull` vertices, in order, are the hull. */
+  hull: number;
+  /** SHA-256 of the attachment's entry in the hash-verified model (see `attachmentHashText`). */
+  hash: string;
+}
+export interface MeshView {
+  /** Current position per vertex id; null when removed. */
+  vertices: (Vec | null)[];
+  edges: MeshEdge[];
+  /** Edges the delta removed (explicitly, or with a removed vertex), for the preview. */
+  removedEdges: MeshEdge[];
+  added: Set<number>;
+  /** Moved vertex id → its source (or creation) position. */
+  moved: Map<number, Vec>;
+  removed: Set<number>;
+}
+export type MeshEditResult = { ok: true; changed: boolean; code?: string } | { ok: false; code: string };
+
+export const MESH_EDIT_SCHEMA = 'rig-review-mesh-edit/1';
+export const MESH_EDIT_BINDING_SCHEMA = 'rig-review-mesh-edit-binding/1';
+export const MESH_EDIT_DRAFT_SCHEMA = 'rig-review-mesh-edit-draft/1';
+export const MESH_EDIT_SELECT_SLOT = 'MESH_EDIT_SELECT_SLOT';
+export const MESH_EDIT_NO_MESH = 'MESH_EDIT_NO_MESH';
+export const MESH_EDIT_HULL_EDGE = 'MESH_EDIT_HULL_EDGE';
+export const MESH_EDIT_EDGE_EXISTS = 'MESH_EDIT_EDGE_EXISTS';
+export const MESH_EDIT_TRIANGULATION_EDGE = 'MESH_EDIT_TRIANGULATION_EDGE';
+export const MESH_EDIT_INVALID_OP = 'MESH_EDIT_INVALID_OP';
+export const MESH_EDIT_OPS_LIMIT = 'MESH_EDIT_OPS_LIMIT';
+/** The draft rides in one form field (≤ 32768 characters), so the delta is bounded. */
+export const MESH_EDIT_MAX_OPS = 300;
+export const MESH_EDIT_PREVIEW_NOTE = 'preview only — the producer retriangulates';
+/** Screen-space hit radii in CSS px. */
+export const MESH_HIT = Object.freeze({ vertex: 6, vertexTouch: 8, edge: 4 });
+
+const round = (value: number) => Math.round(value * 100) / 100;
+export const roundVec = (p: { x: number; y: number } | Vec): Vec => Array.isArray(p) ? [round(p[0]), round(p[1])] : [round(p.x), round(p.y)];
+export const edgeKey = (a: number, b: number) => (a < b ? `${a}:${b}` : `${b}:${a}`);
+const isHullPair = (a: number, b: number, hull: number) => a < hull && b < hull && (Math.abs(a - b) === 1 || Math.abs(a - b) === hull - 1) && hull > 2;
+
+/** The original triangulation's unique edges; consecutive hull vertices (and the closing pair) are hull edges. */
+export function sourceEdges(source: Pick<MeshSource, 'triangles' | 'hull' | 'vertices'>): MeshEdge[] {
+  const seen = new Map<string, MeshEdge>(), n = source.vertices.length;
+  const add = (a: number, b: number) => { if (a === b || a < 0 || b < 0 || a >= n || b >= n) return; const key = edgeKey(a, b); if (!seen.has(key)) seen.set(key, { a: Math.min(a, b), b: Math.max(a, b), kind: isHullPair(a, b, source.hull) ? 'hull' : 'interior' }); };
+  for (let i = 0; i + 2 < source.triangles.length; i += 3) { const t = source.triangles; add(t[i]!, t[i + 1]!); add(t[i + 1]!, t[i + 2]!); add(t[i + 2]!, t[i]!); }
+  for (let i = 0; i < source.hull && source.hull > 2; i++) add(i, (i + 1) % source.hull);
+  return [...seen.values()];
+}
+
+const finiteVec = (v: unknown): v is Vec => Array.isArray(v) && v.length === 2 && v.every(n => typeof n === 'number' && Number.isFinite(n));
+const index = (v: unknown): v is number => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+
+/** Replays ops over the source. Throws `MESH_EDIT_INVALID_OP` naming the first op that does not apply. */
+export function applyMeshOps(source: MeshSource, ops: readonly MeshOp[]): MeshView {
+  const view: MeshView = { vertices: source.vertices.map(v => [v[0], v[1]] as Vec), edges: [], removedEdges: [], added: new Set(), moved: new Map(), removed: new Set() };
+  const edges = new Map(sourceEdges(source).map(e => [edgeKey(e.a, e.b), { ...e }]));
+  const fail = (i: number, why: string): never => { throw new Error(`${MESH_EDIT_INVALID_OP}: op ${i} ${why}`); };
+  const live = (v: unknown, i: number): number => { if (!index(v) || v >= view.vertices.length || !view.vertices[v]) fail(i, `names no live vertex ${String(v)}`); return v as number; };
+  const removeEdge = (key: string) => { const edge = edges.get(key); if (edge) { edges.delete(key); view.removedEdges.push(edge); } };
+  ops.forEach((op, i) => {
+    switch (op?.op) {
+      case 'move': {
+        const v = live(op.v, i); if (!finiteVec(op.from) || !finiteVec(op.to)) fail(i, 'needs finite from/to');
+        if (!view.moved.has(v)) view.moved.set(v, [...view.vertices[v]!] as Vec);
+        view.vertices[v] = [op.to[0], op.to[1]]; break;
+      }
+      case 'add': {
+        if (!finiteVec(op.at)) fail(i, 'needs a finite at');
+        const id = view.vertices.length;
+        if (op.onEdge !== undefined) {
+          if (!Array.isArray(op.onEdge) || op.onEdge.length !== 2) fail(i, 'onEdge must be a pair');
+          const [a, b] = [live(op.onEdge![0], i), live(op.onEdge![1], i)], key = edgeKey(a, b), edge = edges.get(key);
+          if (!edge) fail(i, `splits a missing edge ${a}-${b}`);
+          edges.delete(key); view.vertices.push([op.at[0], op.at[1]]);
+          edges.set(edgeKey(a, id), { a: Math.min(a, id), b: Math.max(a, id), kind: edge!.kind });
+          edges.set(edgeKey(id, b), { a: Math.min(b, id), b: Math.max(b, id), kind: edge!.kind });
+        } else view.vertices.push([op.at[0], op.at[1]]);
+        view.added.add(id); break;
+      }
+      case 'remove': {
+        const v = live(op.v, i); view.vertices[v] = null; view.removed.add(v); view.moved.delete(v);
+        for (const [key, edge] of [...edges]) if (edge.a === v || edge.b === v) removeEdge(key);
+        break;
+      }
+      case 'edge': {
+        const a = live(op.a, i), b = live(op.b, i); if (a === b) fail(i, 'joins a vertex to itself');
+        if (edges.has(edgeKey(a, b))) fail(i, `duplicates edge ${a}-${b}`);
+        edges.set(edgeKey(a, b), { a: Math.min(a, b), b: Math.max(a, b), kind: 'constraint' }); break;
+      }
+      case 'unedge': {
+        const a = live(op.a, i), b = live(op.b, i), edge = edges.get(edgeKey(a, b));
+        if (!edge) fail(i, `removes a missing edge ${a}-${b}`); if (edge!.kind === 'hull') fail(i, `removes hull edge ${a}-${b}`);
+        removeEdge(edgeKey(a, b)); break;
+      }
+      default: fail(i, 'has an unknown op');
+    }
+  });
+  view.edges = [...edges.values()];
+  return view;
+}
+
+/** The ordered delta with per-action undo/redo. One user action (a drag of an edge or of a multi-selection) is one step of one or more ops. */
+export class MeshEditSession {
+  private list: MeshOp[] = [];
+  private steps: number[] = [];
+  private redoSteps: MeshOp[][] = [];
+  private current: MeshView;
+  constructor(readonly source: MeshSource, ops: readonly MeshOp[] = []) {
+    this.current = applyMeshOps(source, ops); this.list = ops.map(op => structuredClone(op)); this.steps = this.list.map(() => 1);
+  }
+  ops(): MeshOp[] { return this.list.map(op => structuredClone(op)); }
+  view(): MeshView { return this.current; }
+  canUndo(): boolean { return this.steps.length > 0; }
+  canRedo(): boolean { return this.redoSteps.length > 0; }
+  /** Records one step; refuses the whole step when any op does not apply. */
+  record(ops: readonly MeshOp[]): MeshEditResult {
+    if (!ops.length) return { ok: true, changed: false };
+    if (this.list.length + ops.length > MESH_EDIT_MAX_OPS) return { ok: false, code: `${MESH_EDIT_OPS_LIMIT}: at most ${MESH_EDIT_MAX_OPS} ops per attachment — download and reset to continue` };
+    let next: MeshView;
+    try { next = applyMeshOps(this.source, [...this.list, ...ops]); } catch (error) { return { ok: false, code: error instanceof Error ? error.message : String(error) }; }
+    this.list.push(...ops.map(op => structuredClone(op))); this.steps.push(ops.length); this.redoSteps = []; this.current = next;
+    return { ok: true, changed: true };
+  }
+  undo(): boolean {
+    const count = this.steps.pop(); if (count === undefined) return false;
+    this.redoSteps.push(this.list.splice(this.list.length - count, count));
+    this.current = applyMeshOps(this.source, this.list); return true;
+  }
+  redo(): boolean {
+    const ops = this.redoSteps.pop(); if (!ops) return false;
+    this.list.push(...ops); this.steps.push(ops.length); this.current = applyMeshOps(this.source, this.list); return true;
+  }
+  reset(): void { this.list = []; this.steps = []; this.redoSteps = []; this.current = applyMeshOps(this.source, []); }
+
+  /** Moves vertices by a crop-px offset from their positions at `base` (the drag's start view): one move op per vertex. */
+  moveOps(ids: readonly number[], dx: number, dy: number, base: MeshView = this.current): MeshOp[] {
+    if (!Number.isFinite(dx) || !Number.isFinite(dy) || (dx === 0 && dy === 0)) return [];
+    return [...new Set(ids)].flatMap(v => { const from = base.vertices[v]; if (!from) return []; const to = roundVec([from[0] + dx, from[1] + dy]); return to[0] === from[0] && to[1] === from[1] ? [] : [{ op: 'move' as const, v, from: [from[0], from[1]] as Vec, to }]; });
+  }
+  /** Create: a vertex on empty space, or a split of an edge at the click point. */
+  addVertex(at: Vec, onEdge?: [number, number]): MeshEditResult { return this.record([{ op: 'add', at: roundVec(at), ...(onEdge ? { onEdge: [onEdge[0], onEdge[1]] as [number, number] } : {}) }]); }
+  /** Delete on a vertex: the vertex and its edges. */
+  removeVertex(v: number): MeshEditResult { return this.record([{ op: 'remove', v }]); }
+  /** Delete on an edge: any edge but a hull edge. */
+  deleteEdge(a: number, b: number): MeshEditResult {
+    const edge = this.findEdge(a, b); if (!edge) return { ok: false, code: `${MESH_EDIT_INVALID_OP}: no edge ${a}-${b}` };
+    if (edge.kind === 'hull') return { ok: false, code: `${MESH_EDIT_HULL_EDGE}: ${a}-${b} is a hull edge and cannot be removed` };
+    return this.record([{ op: 'unedge', a, b }]);
+  }
+  /**
+   * Edges mode on a pair: a new pair adds a constraint edge; an existing constraint edge is removed; a hull edge is
+   * refused; any other existing edge is a duplicate and records nothing.
+   */
+  toggleConstraint(a: number, b: number): MeshEditResult {
+    if (a === b) return { ok: true, changed: false };
+    const edge = this.findEdge(a, b);
+    if (!edge) return this.record([{ op: 'edge', a, b }]);
+    if (edge.kind === 'hull') return { ok: false, code: `${MESH_EDIT_HULL_EDGE}: ${a}-${b} is a hull edge and cannot be removed` };
+    if (edge.kind === 'constraint') return this.record([{ op: 'unedge', a, b }]);
+    return { ok: true, changed: false, code: `${MESH_EDIT_EDGE_EXISTS}: ${a}-${b} is already a triangulation edge` };
+  }
+  findEdge(a: number, b: number): MeshEdge | undefined { const key = edgeKey(a, b); return this.current.edges.find(e => edgeKey(e.a, e.b) === key); }
+}
+
+export interface ScreenPoint { x: number; y: number }
+export type MeshHit = { kind: 'vertex'; v: number } | { kind: 'edge'; a: number; b: number; t: number; at: ScreenPoint };
+/** Screen-space hit test: the nearest vertex within the radius wins over any edge; then the nearest edge within 4 px. */
+export function hitMesh(points: readonly (ScreenPoint | null)[], edges: readonly Pick<MeshEdge, 'a' | 'b'>[], p: ScreenPoint, touch = false): MeshHit | null {
+  const radius = touch ? MESH_HIT.vertexTouch : MESH_HIT.vertex;
+  let best: MeshHit | null = null, bestDistance = Infinity;
+  points.forEach((q, v) => { if (!q) return; const d = Math.hypot(p.x - q.x, p.y - q.y); if (d <= radius && d < bestDistance) { best = { kind: 'vertex', v }; bestDistance = d; } });
+  if (best) return best;
+  for (const edge of edges) {
+    const a = points[edge.a], b = points[edge.b]; if (!a || !b) continue;
+    const dx = b.x - a.x, dy = b.y - a.y, length = dx * dx + dy * dy; if (length === 0) continue;
+    const t = Math.max(0, Math.min(1, ((p.x - a.x) * dx + (p.y - a.y) * dy) / length)), at = { x: a.x + dx * t, y: a.y + dy * t }, d = Math.hypot(p.x - at.x, p.y - at.y);
+    if (d <= MESH_HIT.edge && d < bestDistance) { best = { kind: 'edge', a: edge.a, b: edge.b, t, at }; bestDistance = d; }
+  }
+  return best;
+}
+/** Vertex ids inside a screen rectangle (any corner order). */
+export function verticesInBox(points: readonly (ScreenPoint | null)[], from: ScreenPoint, to: ScreenPoint): number[] {
+  const [x0, x1] = [Math.min(from.x, to.x), Math.max(from.x, to.x)], [y0, y1] = [Math.min(from.y, to.y), Math.max(from.y, to.y)];
+  return points.flatMap((p, v) => p && p.x >= x0 && p.x <= x1 && p.y >= y0 && p.y <= y1 ? [v] : []);
+}
+
+/** A 2D affine map x' = a x + c y + e, y' = b x + d y + f. */
+export interface Affine { a: number; b: number; c: number; d: number; e: number; f: number }
+/** Samples an affine function at three points. */
+export function affineOf(fn: (x: number, y: number) => ScreenPoint): Affine {
+  const o = fn(0, 0), x = fn(1, 0), y = fn(0, 1);
+  return { a: x.x - o.x, b: x.y - o.y, c: y.x - o.x, d: y.y - o.y, e: o.x, f: o.y };
+}
+export function invertAffine(m: Affine): Affine | null {
+  const det = m.a * m.d - m.b * m.c; if (!Number.isFinite(det) || Math.abs(det) < 1e-12) return null;
+  return { a: m.d / det, b: -m.b / det, c: -m.c / det, d: m.a / det, e: (m.c * m.f - m.d * m.e) / det, f: (m.b * m.e - m.a * m.f) / det };
+}
+export const applyAffine = (m: Affine, x: number, y: number): ScreenPoint => ({ x: m.a * x + m.c * y + m.e, y: m.b * x + m.d * y + m.f });
+/** A screen-px offset as a crop-px offset through the inverse of crop → screen. */
+export function screenDeltaToCrop(cropToScreen: Affine, dx: number, dy: number): Vec | null {
+  const inverse = invertAffine(cropToScreen); if (!inverse) return null;
+  return [inverse.a * dx + inverse.c * dy, inverse.b * dx + inverse.d * dy];
+}
+
+/** The text hashed for `source.hash`: the attachment's entry from the hash-verified model, as `JSON.stringify` writes it. */
+export const attachmentHashText = (entry: unknown) => JSON.stringify(entry);
+
+export interface MeshEditDocument {
+  schema: typeof MESH_EDIT_SCHEMA;
+  slot: string; skin: string; attachment: string;
+  source: { vertexCount: number; triangleCount: number; hullLength: number; hash: string };
+  units: string; basis: string; preview: string;
+  ops: MeshOp[];
+}
+export function meshEditDocument(session: MeshEditSession, basis: string): MeshEditDocument {
+  const s = session.source;
+  return {
+    schema: MESH_EDIT_SCHEMA, slot: s.slot, skin: s.skin, attachment: s.attachment,
+    source: { vertexCount: s.vertices.length, triangleCount: Math.floor(s.triangles.length / 3), hullLength: s.hull, hash: s.hash },
+    units: 'crop px, x right, y down; vertex ids are source indices, added vertices take the next id in op order, removed ids are not reused',
+    basis, preview: `${MESH_EDIT_PREVIEW_NOTE}; the ops are a request over the original triangulation, not a mesh`,
+    ops: session.ops(),
+  };
+}
+export function meshEditBinding(input: { fileSha256: string; sourceHash: string; reviewedSource: { viewerVersion: string; runtimeVersion: string; rig: { sha256: string } | null; motion: { sha256: string } | null }; exportedAt: string; mapping: string; attachment: { slot: string; skin: string; name: string; sha256: string } }) {
+  return {
+    schema: MESH_EDIT_BINDING_SCHEMA,
+    file: { name: 'mesh-edit.json', sha256: input.fileSha256 },
+    package: input.sourceHash,
+    model: input.reviewedSource.rig?.sha256 ?? null,
+    motion: input.reviewedSource.motion?.sha256 ?? null,
+    attachment: { ...input.attachment },
+    exportedAt: input.exportedAt,
+    tools: { viewerVersion: input.reviewedSource.viewerVersion, runtimeVersion: input.reviewedSource.runtimeVersion },
+    mapping: input.mapping,
+    evidence: 'Mesh edit is review evidence, not an approval. Nothing was written into the package; retriangulation and regeneration are the producer path.',
+  };
+}
+
+/** Draft: per attachment, the ops bound to the attachment hash. A draft for another hash is not restored. */
+export interface MeshEditDraft { schema: typeof MESH_EDIT_DRAFT_SCHEMA; entries: Record<string, { hash: string; ops: MeshOp[] }> }
+export const draftKey = (s: Pick<MeshSource, 'slot' | 'skin' | 'attachment'>) => `${s.skin}/${s.slot}/${s.attachment}`;
+export function parseMeshDraft(text: string): MeshEditDraft {
+  const empty: MeshEditDraft = { schema: MESH_EDIT_DRAFT_SCHEMA, entries: {} };
+  if (!text.trim()) return empty;
+  let value: unknown; try { value = JSON.parse(text); } catch { return empty; }
+  const o = value as Partial<MeshEditDraft> | null;
+  if (!o || typeof o !== 'object' || o.schema !== MESH_EDIT_DRAFT_SCHEMA || !o.entries || typeof o.entries !== 'object' || Array.isArray(o.entries)) return empty;
+  const entries: MeshEditDraft['entries'] = {};
+  for (const [key, entry] of Object.entries(o.entries)) {
+    if (['__proto__', 'constructor', 'prototype'].includes(key) || !entry || typeof entry.hash !== 'string' || !/^[a-f0-9]{64}$/.test(entry.hash) || !Array.isArray(entry.ops) || entry.ops.length > MESH_EDIT_MAX_OPS) continue;
+    entries[key] = { hash: entry.hash, ops: entry.ops as MeshOp[] };
+  }
+  return { schema: MESH_EDIT_DRAFT_SCHEMA, entries };
+}
+/** Ops a draft holds for this source, or null when the draft has none or names another hash / an op that does not apply. */
+export function draftOps(draft: MeshEditDraft, source: MeshSource): MeshOp[] | null {
+  const entry = draft.entries[draftKey(source)]; if (!entry || entry.hash !== source.hash) return null;
+  try { applyMeshOps(source, entry.ops); return entry.ops; } catch { return null; }
+}
+export function writeMeshDraft(draft: MeshEditDraft, source: MeshSource, ops: readonly MeshOp[]): string {
+  const entries = { ...draft.entries }; const key = draftKey(source);
+  if (ops.length) entries[key] = { hash: source.hash, ops: ops.map(op => structuredClone(op)) }; else delete entries[key];
+  return Object.keys(entries).length ? JSON.stringify({ schema: MESH_EDIT_DRAFT_SCHEMA, entries }) : '';
+}

package/src/session.ts

@@ -5,6 +5,7 @@ import { isDeepStrictEqual } from 'node:util';
 import { homedir } from 'node:os';
 import {referenceBinding,type ReferenceBinding} from './reference.ts';
 import { validateFeedbackSelection } from './feedback-validation.ts';
+import { parseEnvironmentContext } from './environment.ts';
 import { choice, object, string, type Json, type ReviewPackage, type ReviewedSource } from './manifest.ts';
 export interface Feedback {id:string;frameStart:number;frameEnd:number;target:{kind:'bone'|'slot'|'rig';name:string};category:'defect'|'quality';summary:string;context?:Json}
 export function parseFeedback(item:unknown,strict=true):Feedback {
@@ -25,6 +26,8 @@ export function validatePackageFeedback(feedback:Feedback,p:ReviewPackage,animat
   if(context.interval!==undefined&&!isDeepStrictEqual(context.interval,interval))throw new Error('feedback.context.interval: must match chosen inclusive frameStart/frameEnd');
   if(context.animation!==undefined&&context.animation!==null&&typeof context.animation!=='string')throw new Error('feedback.context.animation: expected animation name or null');
   if(animation!==undefined&&context.animation!==undefined&&context.animation!==null&&context.animation!==animation)throw new Error('feedback.context.animation: does not match selected comparison animation');
+  // Older records without an environment stay valid; a present one must have the recorded shape.
+  if(context.environment!==undefined)parseEnvironmentContext(context.environment);
   const selected=animation??(typeof context.animation==='string'?context.animation:null);
   validateFeedbackSelection(p.feedbackCatalog,{frameStart:feedback.frameStart,frameEnd:feedback.frameEnd,target:feedback.target,animation:selected});
   return {...feedback,context:{...context,...(animation===undefined?{}:{animation}),interval} as Json};