@rig-c/review 0.6.0 → 0.7.0

package/src/chest-landmarks.ts

@@ -0,0 +1,122 @@
+/**
+ * Chest by landmarks (issue #105): the producer's `meshes.<part>.contour.bust` shorthand — three rig-px points (right
+ * apex, left apex, cleavage), `alpha`, `clearance`, optional bone names — and the two circles the producer derives from
+ * it (`bust_r`, `bust_l`). Pure: no DOM, no filesystem. Review draws these circles live and pre-checks the one geometric
+ * refusal (`CONFIG_BUST_CLEARANCE`); the producer derives them again from the entry and is the judge.
+ *
+ * The derivation is a transcription of `@rig-c/parts` 1.42.0 `src/config.ts` `deriveBustRegions` and the
+ * `CONFIG_BUST_CLEARANCE` test in its contour loader (docs/AUTHORING.md `meshes.<part>.contour`, issue #475):
+ *
+ *   dR = edgeLength(kx - rx, ky - ry); dL = edgeLength(kx - lx, ky - ly)
+ *   RR = Math.round(dR - clearance);   RL = Math.round(dL - clearance)
+ *   rR = Math.round(alpha * RR);       rL = Math.round(alpha * RL)
+ *   bust_r: cx rx, cy ry, r rR, band RR - rR; bust_l: cx lx, cy ly, r rL, band RL - rL
+ *   refused when clearance <= 0 || RR + RL >= D || rR <= 0 || rL <= 0 || bandR < 0 || bandL < 0  (D = |apex_r − apex_l|)
+ *
+ * Coordinates: every config position is rig px (the whole figure's frame, the compiled model's stage when the model is
+ * the rig's crop frame). A part image is that frame less the part's box less the producer's pad (`PAD = 4` in
+ * `src/rig.ts`): rig = part image + (box.x − 4, box.y − 4). `partToRig` / `rigToPart` are that translation.
+ */
+
+export const BUST_SPEC_FIELDS = ['apex_r', 'apex_l', 'cleavage', 'alpha', 'clearance', 'bone_r', 'bone_l', 'spacing'] as const;
+/** The producer's defaults (parts `DEFAULT_BUST_*`). */
+export const BUST_DEFAULTS = { alpha: 0.22, clearance: 3.8, spacing: 14, bone_r: 'boob_r', bone_l: 'boob_l' } as const;
+/** The transparent margin the producer pads every part image with (parts `src/rig.ts` `PAD`). */
+export const PART_PAD = 4;
+const GRID = 256;
+
+export type RigPoint = [number, number];
+/** The `contour.bust` entry as the config holds it; absent optional fields are the producer's defaults. */
+export interface BustSpec { apex_r: RigPoint; apex_l: RigPoint; cleavage: RigPoint; alpha?: number; clearance?: number; bone_r?: string; bone_l?: string; spacing?: number }
+/** A derived region in the config's circle shape (key order as parts writes it). */
+export interface DerivedBustRegion { name: 'bust_r' | 'bust_l'; shape: 'circle'; cx: number; cy: number; r: number; spacing: number; band: number; bone: string }
+export interface BustDerivation {
+  regions: [DerivedBustRegion, DerivedBustRegion];
+  /** The unrounded cleavage distances, the rounded outer radii and the apex distance the refusal reads. */
+  dR: number; dL: number; RR: number; RL: number; D: number;
+  /** `CONFIG_BUST_CLEARANCE` with the producer's detail, or null when the producer's test passes. */
+  refusal: string | null;
+}
+
+/** parts `src/length.ts`: `sqrt(dx·dx + dy·dy)`, not `Math.hypot`. */
+const edgeLength = (dx: number, dy: number) => Math.sqrt(dx * dx + dy * dy);
+/** The refusal's printed figures: parts `src/round.ts` `pyRound(x, n)` is `toFixed(n)` except at an exact binary tie (display only). */
+const pyRound = (value: number, digits: number) => Number(value.toFixed(digits));
+
+/** The producer's derivation and its `CONFIG_BUST_CLEARANCE` test, on the same numbers. */
+export function deriveBust(spec: BustSpec): BustDerivation {
+  const alpha = spec.alpha ?? BUST_DEFAULTS.alpha, clearance = spec.clearance ?? BUST_DEFAULTS.clearance, spacing = spec.spacing ?? BUST_DEFAULTS.spacing;
+  const boneR = spec.bone_r ?? BUST_DEFAULTS.bone_r, boneL = spec.bone_l ?? BUST_DEFAULTS.bone_l;
+  const [rx, ry] = spec.apex_r, [lx, ly] = spec.apex_l, [kx, ky] = spec.cleavage;
+  const D = edgeLength(lx - rx, ly - ry), dR = edgeLength(kx - rx, ky - ry), dL = edgeLength(kx - lx, ky - ly);
+  const RR = Math.round(dR - clearance), RL = Math.round(dL - clearance);
+  const rR = Math.round(alpha * RR), rL = Math.round(alpha * RL);
+  const bandR = RR - rR, bandL = RL - rL;
+  let refusal: string | null = null;
+  if (clearance <= 0 || RR + RL >= D || rR <= 0 || rL <= 0 || bandR < 0 || bandL < 0) {
+    const minClearance = Math.max(0, (dR + dL - D) / 2);
+    refusal = `CONFIG_BUST_CLEARANCE: contour.bust.clearance — is ${clearance} (giving R_r = ${RR}, R_l = ${RL}, R_r + R_l = ${RR + RL} px against apex distance D = ${pyRound(D, 2)} px, r_r = ${rR}, band_r = ${bandR}, r_l = ${rL}, band_l = ${bandL}); a clearance > 0 with R_r + R_l < D (clearance > ${pyRound(minClearance, 2)} px) and positive radii is required`;
+  }
+  return {
+    regions: [
+      { name: 'bust_r', shape: 'circle', cx: rx, cy: ry, r: rR, spacing, band: bandR, bone: boneR },
+      { name: 'bust_l', shape: 'circle', cx: lx, cy: ly, r: rL, spacing, band: bandL, bone: boneL },
+    ],
+    dR, dL, RR, RL, D, refusal,
+  };
+}
+
+export class BustSpecError extends Error { constructor(readonly code: string, detail: string) { super(`${code}: ${detail}`); } }
+const bad = (detail: string): never => { throw new BustSpecError('REBUILD_REQUEST_INVALID', detail); };
+const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+const onGrid = (v: number) => Number.isInteger(v * GRID);
+function point(v: unknown, field: string): RigPoint {
+  if (!Array.isArray(v) || v.length !== 2 || !v.every(n => typeof n === 'number' && Number.isFinite(n))) bad(`${field} must be [x, y], finite rig px`);
+  const [x, y] = v as [number, number];
+  if (!onGrid(x) || !onGrid(y)) bad(`${field} is off the 1/${GRID} px grid`);
+  return [x, y];
+}
+/**
+ * A `contour.bust` request, typed as the producer's loader types it (points on the 1/256 grid, `alpha` and `spacing`
+ * positive numbers, `clearance` a number, bone names non-empty strings); the geometry (`CONFIG_BUST_CLEARANCE`) and
+ * whether the bones resolve (`CONFIG_NAME_RESOLVES`) are the producer's to judge. Key order is the producer's.
+ */
+export function parseBustSpec(value: unknown, field = 'bust'): BustSpec {
+  if (!isObject(value)) return bad(`${field} must be an object`);
+  for (const key of Object.keys(value)) if (!(BUST_SPEC_FIELDS as readonly string[]).includes(key)) bad(`${field}.${key} is not a contour.bust field`);
+  const out: BustSpec = { apex_r: point(value.apex_r, `${field}.apex_r`), apex_l: point(value.apex_l, `${field}.apex_l`), cleavage: point(value.cleavage, `${field}.cleavage`) };
+  for (const key of ['alpha', 'clearance', 'spacing'] as const) {
+    if (!(key in value)) continue;
+    const n = value[key];
+    if (typeof n !== 'number' || !Number.isFinite(n) || (key !== 'clearance' && n <= 0)) bad(`${field}.${key} must be a finite number${key === 'clearance' ? '' : ' > 0'}`);
+    out[key] = n as number;
+  }
+  for (const key of ['bone_r', 'bone_l'] as const) {
+    if (!(key in value)) continue;
+    const name = value[key];
+    if (typeof name !== 'string' || !name || name.length > 128) bad(`${field}.${key} must name a bone`);
+    out[key] = name as string;
+  }
+  return out;
+}
+
+/**
+ * The part's `meshes.<part>` entry with `contour.regions` replaced by `contour.bust`: the landmarks are the chest, so
+ * the hand-written regions (whose circles the derived ones replace) are dropped; every other field is as written.
+ */
+export function bustMeshEntry(entry: Record<string, unknown>, spec: BustSpec): Record<string, unknown> {
+  const out = structuredClone(entry), contour = out.contour;
+  if (!isObject(contour)) throw new BustSpecError('REBUILD_PART_NOT_CONTOUR', 'the entry is not a contour; contour.bust applies to contour meshes only');
+  delete contour.regions;
+  const bust: Record<string, unknown> = {};
+  for (const key of BUST_SPEC_FIELDS) if (spec[key] !== undefined) bust[key] = Array.isArray(spec[key]) ? [...(spec[key] as RigPoint)] : spec[key];
+  contour.bust = bust;
+  return out;
+}
+
+/** The part's box in rig px as `parts.json` states it (`x`, `y` of the unpadded art). */
+export interface PartBox { x: number; y: number }
+/** Part image px → rig px: the image's origin is the box less the pad. */
+export const partToRig = ([x, y]: RigPoint, box: PartBox, pad = PART_PAD): RigPoint => [x + box.x - pad, y + box.y - pad];
+/** Rig px → part image px. */
+export const rigToPart = ([x, y]: RigPoint, box: PartBox, pad = PART_PAD): RigPoint => [x - box.x + pad, y - box.y + pad];

package/src/chest-regions.ts

@@ -7,6 +7,8 @@
 /** The generator's coordinate grid: every point is a multiple of 1/256 crop pixel. */
 export const CHEST_REGION_GRID = 256;
 export const CHEST_REGIONS_SPEC = 'family-chest-regions/1';
+/** An export holds 1–8 regions, the same set Apply · Rebuild accepts (#118); the public examples hold two. */
+export const CHEST_REGIONS_MAX = 8;
 
 export type CropPoint = [number, number];
 export type ChestSegment = string | [string, [number, number], [number, number]];
@@ -161,9 +163,11 @@ export function clampNonOverlapping(right: ChestCircle, left: ChestCircle, margi
   return { right: r, left: l, clamped };
 }
 
+/** The examples' sentence for their two regions; any other count lists the bones from screen-left to screen-right. */
 function coordinatesText(crop: { w: number; h: number }, regions: ChestRegionInput[]): string {
-  const [left, right] = [...regions].sort((a, b) => a.center[0] - b.center[0]);
-  return `${crop.w}x${crop.h} crop pixels, x screen-right and y down; ${left!.bone} screen-left, ${right!.bone} screen-right`;
+  const sorted = [...regions].sort((a, b) => a.center[0] - b.center[0]), frame = `${crop.w}x${crop.h} crop pixels, x screen-right and y down`;
+  if (sorted.length === 2) return `${frame}; ${sorted[0]!.bone} screen-left, ${sorted[1]!.bone} screen-right`;
+  return `${frame}; ${sorted.length === 1 ? `one region, ${sorted[0]!.bone}` : `${sorted.length} regions screen-left to screen-right: ${sorted.map(r => r.bone).join(', ')}`}`;
 }
 
 function segmentList(value: unknown): ChestSegment[] {
@@ -179,7 +183,7 @@ function segmentList(value: unknown): ChestSegment[] {
 export function buildChestRegions(input: ChestRegionsInput): ChestRegionsDocument {
   const w = finite(input.crop?.w, 'crop', 'w', 0, false), h = finite(input.crop?.h, 'crop', 'h', 0, false);
   if (typeof input.generator !== 'string' || !input.generator.trim()) throw new ChestRegionError('CHEST_REGIONS_GENERATOR_MISSING', '');
-  if (input.regions.length !== 2) throw new ChestRegionError('CHEST_REGIONS_COUNT', String(input.regions.length));
+  if (input.regions.length < 1 || input.regions.length > CHEST_REGIONS_MAX) throw new ChestRegionError('CHEST_REGIONS_COUNT', `${input.regions.length} (1–${CHEST_REGIONS_MAX})`);
   const c = input.contour;
   for (const field of ['tolerance', 'margin', 'spacing', 'maxEdge', 'stray'] as const) finite(c[field], 'contour', field, 0);
   if (typeof c.bridges !== 'boolean') throw new ChestRegionError('CHEST_REGION_VALUE_INVALID', 'contour bridges');
@@ -208,7 +212,9 @@ export function buildChestRegions(input: ChestRegionsInput): ChestRegionsDocumen
     if (points.some(([x, y]) => x < 0 || y < 0 || x > w || y > h)) throw new ChestRegionError('CHEST_REGION_OUT_OF_CROP', name);
     regions.push({ name, bone: region.bone, shape: 'polygon', points, spacing, band });
   }
-  if (chestRegionsOverlap(regions[0]!, regions[1]!)) throw new ChestRegionError('CHEST_REGIONS_OVERLAP', `${regions[0]!.name} ${regions[1]!.name}`);
+  for (let i = 0; i < regions.length; i++) for (let j = i + 1; j < regions.length; j++) {
+    if (chestRegionsOverlap(regions[i]!, regions[j]!)) throw new ChestRegionError('CHEST_REGIONS_OVERLAP', `${regions[i]!.name} ${regions[j]!.name}`);
+  }
   const mesh: ChestMesh = { contour: { tolerance: c.tolerance, margin: c.margin, spacing: c.spacing, maxEdge: c.maxEdge, stray: c.stray, bridges: c.bridges, regions } };
   if (input.r !== undefined) mesh.r = finite(input.r, 'mesh', 'r', 0);
   if (input.segments !== undefined) mesh.segments = segmentList(input.segments);

package/src/cli.ts

@@ -6,7 +6,8 @@ import { formatFeedbackIssues } from './feedback-export.ts';
 import {loadReferencedReview,selectedReference,assertReviewUnchanged} from './reference.ts';
 import {animationDiagnostic,selectAnimation} from './animation-selection.ts';
 import {shellWord} from './open-shell.ts';
-import {openReview,controlReview,loadOpenPackage,defaultStateDir,type OpenInputs} from './open.ts';
+import {openReview,controlReview,loadOpenPackage,defaultStateDir,handoffFlags,type OpenInputs} from './open.ts';
+import {checkHandoffFlags,HANDOFF_FLAGS} from './handoff.ts';
 import { readFeedbackSession, readFeedbackCompareSession } from './session-history.ts';
 import { startServer } from './server.ts';
 import { loadCompare } from './compare.ts';
@@ -15,7 +16,8 @@ import { readSession, type Feedback } from './session.ts';
 import { readCompareSession } from './compare-session.ts';
 import { exportReviewStrip, exportCompareStrip, stripJson, writeStripOutput, validateStripOutput } from './strip-export.ts';
 import type { StripInterval, StripRequest } from './strip.ts';
-const usage='Usage: rig-review open <dir> [--reference <video>] [--compare <dir>] [--animation <name>] [--control] [--direct]\n       open is managed by default: one loopback front at 127.0.0.1:4318 (RIG_REVIEW_FRONT_PORT overrides) serves /instances/<key>/; --direct serves the worker on its own port.\n       rig-review control <dir> [--reference <video>] [--compare <dir>] [--animation <name>] [--page <id> --expected-revision <n> --command <JSON> --wait-ms <n>]\n       rig-review feedback <dir> [--reference <video>] [--compare <dir>] [--animation <name>] [--format json|issue]\n       Usage: bun run review -- <review.json|output-directory> [--port 4317] [--checkpoint ID]\n       bun run check -- <review.json|output-directory>\n       bun run feedback -- <review.json|output-directory>\n       bun run review -- compare <a> <b> --reference <video> --animation <name> [--port 4317]\n       bun run check -- compare <a> <b> --reference <video> --animation <name>\n       bun run feedback -- compare <a> <b> --reference <video> --animation <name>';
+const handoffUsage='[--config <path> [--parts <dir>] [--source <png> --full <dir> [--head <dir>]]]';
+const usage='Usage: rig-review open <dir> [--reference <video>] [--compare <dir>] [--animation <name>] [--control] [--direct] '+handoffUsage+'\n       --config declares the producer handoff (wins over the review.json "producer" block and discovery of config.json, rig/config.json, ../config.json beside an opened out/); feedback and control take the same flags.\n       open is managed by default: one loopback front at 127.0.0.1:4318 (RIG_REVIEW_FRONT_PORT overrides) serves /instances/<key>/; --direct serves the worker on its own port.\n       rig-review control <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--page <id> --expected-revision <n> --command <JSON> --wait-ms <n>]\n       rig-review feedback <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--format json|issue]\n       Usage: bun run review -- <review.json|output-directory> [--port 4317] [--checkpoint ID]\n       bun run check -- <review.json|output-directory>\n       bun run feedback -- <review.json|output-directory>\n       bun run review -- compare <a> <b> --reference <video> --animation <name> [--port 4317]\n       bun run check -- compare <a> <b> --reference <video> --animation <name>\n       bun run feedback -- compare <a> <b> --reference <video> --animation <name>';
 async function stripCommand(args:string[],options:{stateDir?:string}){
   const compare=args[0]==='compare';if(compare)args.shift();const a=args.shift(),b=compare?args.shift():undefined;if(!a||compare&&!b)throw new Error('strip: expected package input(s)');
   let reference:string|undefined,referenceVideo:string|undefined,animation:string|undefined,basis:'a'|'b'|undefined,range:string|undefined,output:string|undefined,jsonOnly=false,all=false;
@@ -33,15 +35,23 @@ async function stripCommand(args:string[],options:{stateDir?:string}){
   else {if(basis)throw new Error('strip --basis: single package uses single basis');const p=await loadReferencedReview(a,referenceVideo);if(!reference)reference=selectedReference(p)?.binding.reference.id;roots=[p.root];if(all)intervals=fromFeedback((await readSession(p,options.stateDir)).feedback);if(output){await validateStripOutput(output,roots);if(!jsonOnly)await validateStripOutput(output+'.json',roots);}result=await exportReviewStrip(p,request(p.sourceHash));}
   if(output){await writeStripOutput(result,output,roots);console.log(`Strip exported: ${output}${result.png?' (PNG + .json provenance)':''}`);}else console.log(stripJson(result).trimEnd());
 }
+/** `--config` → `config` for the producer handoff flags (#101), else null. */
+function handoffOption(flag:string):(typeof HANDOFF_FLAGS)[number]|null {const name=flag.slice(2);return flag.startsWith('--')&&(HANDOFF_FLAGS as readonly string[]).includes(name)?name as (typeof HANDOFF_FLAGS)[number]:null;}
+/** The retrieval words for the handoff flags, in their fixed order. */
+const handoffWords=(inputs:OpenInputs)=>HANDOFF_FLAGS.flatMap(f=>inputs[f]!==undefined?['--'+f,inputs[f]!]:[]);
 export function parseOpenInputs(args:string[]):OpenInputs {
  const input=args.shift();if(!input||input.startsWith('--'))throw new Error(usage);const result:OpenInputs={input},seen=new Set<string>();
- while(args.length){const flag=args.shift()!;if(seen.has(flag))throw new Error(`OPEN_OPTION_INVALID ${flag}: Duplicate open option ${flag}`);seen.add(flag);if(flag==='--control'){result.control=true;continue;}if(flag==='--direct'){result.direct=true;continue;}const value=args.shift();if(value===undefined||value==='')throw new Error(`OPEN_OPTION_INVALID ${flag}: Missing value for ${flag}`);if(flag==='--reference')result.reference=value;else if(flag==='--compare')result.compare=value;else if(flag==='--animation')result.animation=value;else throw new Error(`OPEN_OPTION_INVALID ${flag}: Unknown open option ${flag}`);}return result;
+ while(args.length){const flag=args.shift()!;if(seen.has(flag))throw new Error(`OPEN_OPTION_INVALID ${flag}: Duplicate open option ${flag}`);seen.add(flag);if(flag==='--control'){result.control=true;continue;}if(flag==='--direct'){result.direct=true;continue;}const value=args.shift();if(value===undefined||value==='')throw new Error(`OPEN_OPTION_INVALID ${flag}: Missing value for ${flag}`);if(flag==='--reference')result.reference=value;else if(flag==='--compare')result.compare=value;else if(flag==='--animation')result.animation=value;else if(handoffOption(flag))result[handoffOption(flag)!]=value;else throw new Error(`OPEN_OPTION_INVALID ${flag}: Unknown open option ${flag}`);}
+ const problem=checkHandoffFlags(result);if(problem)throw new Error(`OPEN_OPTION_INVALID ${problem.split(':')[0]}: ${problem.slice(problem.indexOf(':')+2)}`);
+ if(result.compare!==undefined&&handoffFlags(result))throw new Error('OPEN_OPTION_INVALID --config: compare takes no producer handoff; open one package with --config');
+ return result;
 }
 async function controlCommand(args:string[],stateDir?:string){
  const input=args.shift();if(!input||input==='--help'||input==='-h'){console.log(usage);return;}
  const inputs:OpenInputs={input},options:Parameters<typeof controlReview>[1]={stateDir},seen=new Set<string>();
  while(args.length){const flag=args.shift()!;if(seen.has(flag))throw new Error(`Duplicate control option ${flag}`);seen.add(flag);const value=args.shift();if(value===undefined||value==='')throw new Error(`Missing value for ${flag}`);
   if(flag==='--reference')inputs.reference=value;else if(flag==='--compare')inputs.compare=value;else if(flag==='--animation')inputs.animation=value;
+  else if(handoffOption(flag))inputs[handoffOption(flag)!]=value;
   else if(flag==='--page')options.pageId=value;else if(flag==='--request-id')options.requestId=value;
   else if(flag==='--expected-revision'){const n=Number(value);if(!/^\d+$/.test(value)||!Number.isSafeInteger(n))throw new Error('--expected-revision: expected safe integer >= 0');options.expectedRevision=n;}
   else if(flag==='--wait-ms'){const n=Number(value);if(!/^\d+$/.test(value)||!Number.isSafeInteger(n)||n>30000)throw new Error('--wait-ms: expected integer 0..30000');options.waitMs=n;}
@@ -73,7 +83,7 @@ export function feedbackFormat(args:string[]):{args:string[];format:'json'|'issu
 function commandHelpRequested(args:readonly string[],command:'open'|'review'|'check'|'feedback'):boolean {
  if(args[0]==='--help'||args[0]==='-h')return true;
  const compare=command!=='open'&&args[0]==='compare';
- const flags=command==='open'?['--reference','--compare','--animation']:compare?['--reference','--animation','--port']:['--port','--checkpoint','--reference','--compare','--animation'];
+ const handoff=HANDOFF_FLAGS.map(f=>'--'+f),flags=command==='open'?['--reference','--compare','--animation',...handoff]:compare?['--reference','--animation','--port']:['--port','--checkpoint','--reference','--compare','--animation',...handoff];
  for(let i=compare?3:1;i<args.length;){
   const flag=args[i];if(flag==='--help'||flag==='-h')return true;
   if(command==='open'&&(flag==='--control'||flag==='--direct')){i++;continue;}if(!flags.includes(flag!))return false;i+=2;
@@ -84,7 +94,7 @@ export async function main(args:string[],options:{stateDir?:string}={}){
   options={stateDir:options.stateDir??defaultStateDir()};if(args[0]==='--')args.shift();
   if(args[0]==='control')return controlCommand(args.slice(1),options.stateDir);
   if(args[0]==='open'){const openArgs=args.slice(1);if(commandHelpRequested(openArgs,'open')){console.log(usage);return;}const inputs=parseOpenInputs(openArgs);const result=await openReview(inputs,options);// Launcher contract (README): stdout is the URL line alone; stderr is diagnostic, control notice, retrieval, in that order.
-    console.log(result.url);if(result.selection)console.error(animationDiagnostic(result.selection));if(inputs.control)console.error('Inspection control enabled; query the current connected page with rig-review control and the same inputs.');console.error(`Review ${result.reused?'reused':'started'}; feedback: rig-review feedback ${[result.inputs.input,...(result.inputs.compare?['--compare',result.inputs.compare]:[]),...(result.inputs.reference?['--reference',result.inputs.reference]:[]),...(result.inputs.animation?['--animation',result.inputs.animation]:[])].map(shellWord).join(' ')}`);return;}
+    console.log(result.url);if(result.selection)console.error(animationDiagnostic(result.selection));if(inputs.control)console.error('Inspection control enabled; query the current connected page with rig-review control and the same inputs.');console.error(`Review ${result.reused?'reused':'started'}; feedback: rig-review feedback ${[result.inputs.input,...(result.inputs.compare?['--compare',result.inputs.compare]:[]),...(result.inputs.reference?['--reference',result.inputs.reference]:[]),...(result.inputs.animation?['--animation',result.inputs.animation]:[]),...handoffWords(result.inputs)].map(shellWord).join(' ')}`);return;}
   if(args[0]==='strip'){args.shift();if(args.includes('--help')){console.log(usage+'\nStrip: strip <package> --reference <declared-video-id> --animation <name> (--frames FIRST:LAST | --all-feedback) [--json] [--out path]\n       strip compare <a> <b> --reference <video> --animation <name> --basis a|b (--frames FIRST:LAST | --all-feedback) [--json] [--out path]');return;}return stripCommand(args,options);}let command:'review'|'check'|'feedback'='review';if(args[0]==='check'||args[0]==='feedback'){command=args.shift() as 'check'|'feedback';}
   if(args[0]==='--help'||args[0]==='-h'){console.log(usage);return;}
   let format:'json'|'issue'='json';if(command==='feedback'){const parsed=feedbackFormat(args);args=parsed.args;format=parsed.format;}
@@ -102,10 +112,11 @@ export async function main(args:string[],options:{stateDir?:string}={}){
     if(command==='check'){console.log(`Comparison valid: ${p.response.title}\nSource SHA-256: ${p.response.sourceHash}\nAnimation: ${animation}\nReference SHA-256: ${p.response.reference.sha256}\nPlayback: two compiled models present`);return;}
     const capability=randomBytes(32).toString('hex'),server=await startCompareServer(p,{port,stateDir:options.stateDir,capability});console.log(`Compare ready: http://127.0.0.1:${server.port}/#cap=${capability}\nComparison: ${p.response.title}\nSource SHA-256: ${p.response.sourceHash}\nPress Ctrl+C to stop.`);return;
   }
-  const input=args.shift();if(!input)throw new Error(usage);let port=4317;let checkpoint:string|undefined,reference:string|undefined,compare:string|undefined,animation:string|undefined;
-  while(args.length){const flag=args.shift();const value=args.shift();if(!value)throw new Error(`Missing value for ${flag}`);if(flag==='--port'){port=Number(value);if(!Number.isInteger(port)||port<0||port>65535)throw new Error('--port: expected integer 0…65535');}else if(flag==='--checkpoint')checkpoint=value;else if(flag==='--reference')reference=value;else if(flag==='--compare')compare=value;else if(flag==='--animation')animation=value;else throw new Error(`Unknown option ${flag}\n${usage}`);}
+  const input=args.shift();if(!input)throw new Error(usage);let port=4317;let checkpoint:string|undefined,reference:string|undefined,compare:string|undefined,animation:string|undefined;const handoff:OpenInputs={input};
+  while(args.length){const flag=args.shift();const value=args.shift();if(!value)throw new Error(`Missing value for ${flag}`);if(handoffOption(flag!)){handoff[handoffOption(flag!)!]=value;continue;}if(flag==='--port'){port=Number(value);if(!Number.isInteger(port)||port<0||port>65535)throw new Error('--port: expected integer 0…65535');}else if(flag==='--checkpoint')checkpoint=value;else if(flag==='--reference')reference=value;else if(flag==='--compare')compare=value;else if(flag==='--animation')animation=value;else throw new Error(`Unknown option ${flag}\n${usage}`);}
+  const handoffProblem=checkHandoffFlags(handoff);if(handoffProblem)throw new Error(handoffProblem);if(compare&&handoffFlags(handoff))throw new Error('--config: compare takes no producer handoff');
   if(compare){if(command!=='feedback')throw new Error('--compare: use open or feedback');const loaded=await loadOpenPackage({input,compare,reference,animation});if(loaded.mode!=='compare')throw new Error('Expected comparison');printFeedback(await readFeedbackCompareSession(loaded.p,options.stateDir));return;}
-  const p=await loadReferencedReview(input,reference);// Serving starts on the report's clip when it names one; check and feedback validate only an explicit flag.
+  const p=await loadReferencedReview(input,reference,handoffFlags(handoff));// Serving starts on the report's clip when it names one; check and feedback validate only an explicit flag.
   const fromReport=command==='review'&&animation===undefined&&p.report?.animation!==undefined;
   const selection=animation!==undefined||fromReport?selectAnimation([{label:'single',catalog:p.feedbackCatalog,report:p.report}],animation,true):null;const initialAnimation=selection?.name;if(command==='feedback'){const saved=await readFeedbackSession(p,options.stateDir);await assertReviewUnchanged(p);printFeedback(saved);return;}if(command==='check'){console.log(`Package valid: ${p.manifest.title}\nRevision: ${p.manifest.revision}\nSource SHA-256: ${p.sourceHash}\nDeclared files: ${p.files.size}\nPlayback: ${p.manifest.model?'compiled model present':'unavailable (no model)'}`);return;}
   if(checkpoint&&!p.manifest.checkpoints.some(v=>v.id===checkpoint))throw new Error(`Unknown checkpoint ${checkpoint}`);

package/src/config-patch.ts

@@ -0,0 +1,213 @@
+/**
+ * Config patch (#102): the one data form every edit card produces. `rig-review-config-patch/1` names the producer config
+ * bytes it was made against (`config_sha256`), a list of RFC 6902-style operations over that config addressed by RFC 6901
+ * JSON Pointers, the producer it was made for and the producer op that rebuilds from the patched config. Pure: no IO,
+ * no clock. Review applies a patch only to a scratch copy of the config; the package's config is never written.
+ */
+import { createHash } from 'node:crypto';
+
+export const CONFIG_PATCH_SCHEMA = 'rig-review-config-patch/1';
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+export type PatchOpName = 'replace' | 'add' | 'remove';
+export const PATCH_OPS: readonly PatchOpName[] = ['replace', 'add', 'remove'];
+/**
+ * `name` (#103), optional: the `name` the entry at `/<list>/<index>` holds in the config the patch was made against — an
+ * edit card that addresses a named list entry by index records the name too, and the server refuses the patch
+ * (`EDIT_PATCH_NAME_MISMATCH`) unless the index resolves to that name.
+ */
+export interface PatchOp { op: PatchOpName; path: string; value?: JsonValue; name?: string }
+/** `rig` rebuilds the whole rig from the patched config; `remesh` re-fits one part from its patched `meshes.<part>` entry. */
+export type PatchCmd = 'rig' | 'remesh';
+export const PATCH_CMDS: readonly PatchCmd[] = ['rig', 'remesh'];
+export interface ConfigPatch {
+  schema: typeof CONFIG_PATCH_SCHEMA;
+  config_sha256: string;
+  ops: PatchOp[];
+  producer: { name: string; version: string };
+  op: { cmd: PatchCmd; args: string[] };
+}
+export const MAX_PATCH_OPS = 256;
+/** Flags a patch may pass to the producer op: no path, no command, every value from a closed set. */
+export const PATCH_FLAGS: Readonly<Record<string, readonly string[]>> = { '--idle-keys': ['ctl', 'direct'], '--page-edges': ['pot', 'free'], '--pack-shape': ['rect', 'polygon'] };
+const PART = /^[A-Za-z0-9_-]{1,64}$/;
+
+export class ConfigPatchError extends Error { constructor(readonly code: string, detail: string) { super(`${code}: ${detail}`); } }
+const invalid = (detail: string): never => { throw new ConfigPatchError('EDIT_PATCH_INVALID', detail); };
+const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+const sha256 = (text: string) => createHash('sha256').update(text).digest('hex');
+
+/** RFC 6901: "" is the whole document; otherwise "/" then tokens with "~1" = "/" and "~0" = "~"; any other "~" is invalid. */
+export function parsePointer(pointer: unknown): string[] {
+  if (typeof pointer !== 'string') throw new ConfigPatchError('EDIT_PATCH_POINTER_INVALID', `${JSON.stringify(pointer)} is not a string`);
+  if (pointer === '') return [];
+  if (!pointer.startsWith('/')) throw new ConfigPatchError('EDIT_PATCH_POINTER_INVALID', `${JSON.stringify(pointer)} does not start with "/"`);
+  return pointer.slice(1).split('/').map(token => {
+    if (/~(?![01])/.test(token)) throw new ConfigPatchError('EDIT_PATCH_POINTER_INVALID', `${JSON.stringify(pointer)} has a "~" that is not "~0" or "~1"`);
+    return token.replace(/~1/g, '/').replace(/~0/g, '~');
+  });
+}
+export const pointerToken = (token: string | number) => String(token).replace(/~/g, '~0').replace(/\//g, '~1');
+export const formatPointer = (tokens: readonly (string | number)[]) => tokens.map(t => '/' + pointerToken(t)).join('');
+
+function isJson(value: unknown, depth = 0): value is JsonValue {
+  if (depth > 64) return false;
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') return true;
+  if (typeof value === 'number') return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every(v => isJson(v, depth + 1));
+  return isObject(value) && Object.values(value).every(v => isJson(v, depth + 1));
+}
+
+/** The producer op's flags: `--part <name>` for remesh (required, once), plus the closed-set flags, each at most once. */
+function parseArgs(cmd: PatchCmd, args: unknown): string[] {
+  if (!Array.isArray(args) || args.length > 16 || !args.every(a => typeof a === 'string')) invalid('op.args must be an array of at most 16 strings');
+  const list = args as string[], seen = new Set<string>();
+  for (let i = 0; i < list.length; i += 2) {
+    const flag = list[i]!, value = list[i + 1];
+    if (seen.has(flag)) invalid(`op.args: ${flag} given twice`);
+    seen.add(flag);
+    if (value === undefined) invalid(`op.args: ${flag} has no value`);
+    if (flag === '--part' && cmd === 'remesh') { if (!PART.test(value!)) invalid('op.args: --part must name a part'); continue; }
+    const allowed = PATCH_FLAGS[flag];
+    if (!allowed) throw new ConfigPatchError('EDIT_PATCH_ARG_UNKNOWN', `op.args: ${flag} is not a flag a patch may pass to ${cmd} (allowed: ${[...(cmd === 'remesh' ? ['--part'] : []), ...Object.keys(PATCH_FLAGS)].join(', ')})`);
+    if (!allowed.includes(value!)) invalid(`op.args: ${flag} ${value} (allowed: ${allowed.join(' | ')})`);
+  }
+  if (cmd === 'remesh' && !seen.has('--part')) invalid('op.args: remesh needs --part <name>');
+  return [...list];
+}
+
+/** The patch document, exactly its keys; an unknown op name and a malformed pointer are refused by name. */
+export function parseConfigPatch(input: unknown): ConfigPatch {
+  if (!isObject(input)) return invalid('expected an object');
+  const keys = Object.keys(input).sort().join(',');
+  if (keys !== 'config_sha256,op,ops,producer,schema') invalid('expected exactly {schema, config_sha256, ops, producer, op}');
+  if (input.schema !== CONFIG_PATCH_SCHEMA) invalid(`schema must be ${CONFIG_PATCH_SCHEMA}`);
+  if (typeof input.config_sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(input.config_sha256)) invalid('config_sha256 must be a lowercase SHA-256');
+  const producer = input.producer;
+  if (!isObject(producer) || Object.keys(producer).sort().join(',') !== 'name,version' || typeof producer.name !== 'string' || typeof producer.version !== 'string' || !producer.name || !producer.version || producer.name.length > 128 || producer.version.length > 64) invalid('producer must be exactly {name, version}');
+  const op = input.op;
+  if (!isObject(op) || Object.keys(op).sort().join(',') !== 'args,cmd') invalid('op must be exactly {cmd, args}');
+  const cmd = (op as Record<string, unknown>).cmd;
+  if (!PATCH_CMDS.includes(cmd as PatchCmd)) throw new ConfigPatchError('EDIT_PATCH_CMD_UNKNOWN', `op.cmd ${JSON.stringify(cmd)} (supported: ${PATCH_CMDS.join(', ')})`);
+  const args = parseArgs(cmd as PatchCmd, (op as Record<string, unknown>).args);
+  if (!Array.isArray(input.ops) || input.ops.length < 1 || input.ops.length > MAX_PATCH_OPS) invalid(`ops must hold 1–${MAX_PATCH_OPS} operations`);
+  const ops = (input.ops as unknown[]).map((raw, i): PatchOp => {
+    if (!isObject(raw)) return invalid(`ops[${i}] must be an object`);
+    if (!PATCH_OPS.includes(raw.op as PatchOpName)) throw new ConfigPatchError('EDIT_PATCH_OP_UNKNOWN', `ops[${i}].op ${JSON.stringify(raw.op)} (supported: ${PATCH_OPS.join(', ')})`);
+    const name = raw.op as PatchOpName, want = name === 'remove' ? 'op,path' : 'op,path,value';
+    const keys = Object.keys(raw).filter(k => k !== 'name').sort().join(',');
+    if (keys !== want) invalid(`ops[${i}]: ${name} holds exactly ${want.split(',').join(', ')} (and an optional name)`);
+    const tokens = parsePointer(raw.path);
+    if (!tokens.length) throw new ConfigPatchError('EDIT_PATCH_POINTER_INVALID', `ops[${i}].path "" would replace the whole config`);
+    if (name !== 'remove' && !isJson(raw.value)) invalid(`ops[${i}].value is not JSON`);
+    const entryName = Object.hasOwn(raw, 'name') ? raw.name : undefined;
+    if (entryName !== undefined && (typeof entryName !== 'string' || !entryName || entryName.length > 128 || !namedEntry(tokens))) invalid(`ops[${i}].name must be a non-empty string naming the entry ${namedListText(tokens)} holds`);
+    const tag = entryName === undefined ? {} : { name: entryName as string };
+    return name === 'remove' ? { op: name, path: raw.path as string, ...tag } : { op: name, path: raw.path as string, value: raw.value as JsonValue, ...tag };
+  });
+  return { schema: CONFIG_PATCH_SCHEMA, config_sha256: input.config_sha256 as string, ops, producer: { name: (producer as Record<string, string>).name!, version: (producer as Record<string, string>).version! }, op: { cmd: cmd as PatchCmd, args } };
+}
+
+/** The patch's own bytes as review hashes them: key order fixed by the parser, no whitespace. */
+export const patchText = (patch: ConfigPatch) => JSON.stringify(parseConfigPatch(patch));
+export const patchSha256 = (patch: ConfigPatch) => sha256(patchText(patch));
+
+/** `EDIT_PATCH_STALE` unless the patch was made against exactly these config bytes. */
+export function assertPatchFresh(patch: Pick<ConfigPatch, 'config_sha256'>, configSha256: string): void {
+  if (patch.config_sha256 !== configSha256) throw new ConfigPatchError('EDIT_PATCH_STALE', `the patch was made against config ${patch.config_sha256.slice(0, 12)}…, the handoff config is ${configSha256.slice(0, 12)}…; read the config again and remake the patch`);
+}
+
+const INDEX = /^(0|[1-9][0-9]*)$/;
+/**
+ * The named list entry a pointer addresses, as `{list, index, key}`: a top-level list `/<list>/<i>` (named by `name`;
+ * a `bones` chain and a `stops` entry by `chain`), and since #115 `/assemble/cuts/<i>` (named by its `into`),
+ * `/assemble/patches/<i>` (by `name`) and `/limbs/<limb>/segments/<k>` (by its `part`). Null for any other pointer.
+ */
+export function namedEntry(tokens: readonly string[]): { list: string[]; index: number; keys: string[] } | null {
+  if (tokens[0] === 'assemble' && (tokens[1] === 'cuts' || tokens[1] === 'patches')) return tokens.length >= 3 && INDEX.test(tokens[2]!) ? { list: tokens.slice(0, 2), index: Number(tokens[2]), keys: [tokens[1] === 'cuts' ? 'into' : 'name'] } : null;
+  if (tokens[0] === 'limbs') return tokens.length >= 4 && tokens[2] === 'segments' && INDEX.test(tokens[3]!) ? { list: tokens.slice(0, 3), index: Number(tokens[3]), keys: ['part'] } : null;
+  if (tokens.length < 2 || !INDEX.test(tokens[1]!)) return null;
+  // A `bones` chain entry (#109) and a `stops` entry (#110) name themselves by `chain`; every other named entry by `name`.
+  return { list: tokens.slice(0, 1), index: Number(tokens[1]), keys: tokens[0] === 'bones' || tokens[0] === 'stops' ? ['name', 'chain'] : ['name'] };
+}
+const namedListText = (tokens: readonly string[]) => {
+  const tail = tokens[0] === 'assemble' ? '/assemble/cuts|patches/<index>' : tokens[0] === 'limbs' ? '/limbs/<limb>/segments/<index>' : `/${pointerToken(tokens[0] ?? '')}/<index>`;
+  return tail;
+};
+
+/** Every op that records a name must address, by index, a list entry of the unpatched config holding exactly that name (a `bones` chain: its `chain`). */
+export function assertOpNames(doc: JsonValue, ops: readonly PatchOp[]): void {
+  for (const [i, op] of ops.entries()) {
+    if (op.name === undefined) continue;
+    const at = namedEntry(parsePointer(op.path));
+    if (!at) throw new ConfigPatchError('EDIT_PATCH_NAME_MISMATCH', `ops[${i}] ${op.path} records "${op.name}", but it addresses no named list entry`);
+    let entries: JsonValue | undefined = doc;
+    for (const t of at.list) entries = isObject(entries) ? (entries as Record<string, JsonValue>)[t] : undefined;
+    const entry = Array.isArray(entries) ? entries[at.index] : undefined;
+    const held = isObject(entry) ? at.keys.map(k => (entry as Record<string, JsonValue>)[k]).find(v => v !== undefined) : undefined;
+    if (held !== op.name) throw new ConfigPatchError('EDIT_PATCH_NAME_MISMATCH', `ops[${i}] ${op.path} records "${op.name}", but ${formatPointer([...at.list, at.index])} ${held === undefined ? 'holds no named entry' : `is "${String(held)}"`} in the handoff config`);
+  }
+}
+
+const arrayIndex = (token: string, length: number, allowEnd: boolean, path: string): number => {
+  if (allowEnd && token === '-') return length;
+  if (!/^(0|[1-9][0-9]*)$/.test(token)) throw new ConfigPatchError('EDIT_PATCH_POINTER_INVALID', `${path}: "${token}" is not an array index`);
+  const index = Number(token);
+  if (index > length || (!allowEnd && index === length)) throw new ConfigPatchError('EDIT_PATCH_PATH_MISSING', `${path}: index ${index} is past the array's ${length} item(s)`);
+  return index;
+};
+
+/** Apply every op in order to a copy of `doc` (RFC 6902 semantics for replace/add/remove); the input is not touched. */
+export function applyConfigPatch(doc: JsonValue, ops: readonly PatchOp[]): JsonValue {
+  const root: { v: JsonValue } = { v: structuredClone(doc) };
+  for (const [i, op] of ops.entries()) {
+    const tokens = parsePointer(op.path), at = `ops[${i}] ${op.path}`;
+    let parent: JsonValue = root.v;
+    for (const [depth, token] of tokens.slice(0, -1).entries()) {
+      const where = formatPointer(tokens.slice(0, depth + 1));
+      if (Array.isArray(parent)) parent = parent[arrayIndex(token, parent.length, false, `${at} (at ${where})`)]!;
+      else if (isObject(parent) && Object.hasOwn(parent, token)) parent = (parent as Record<string, JsonValue>)[token]!;
+      else throw new ConfigPatchError('EDIT_PATCH_PATH_MISSING', `${at}: ${where} is not in the config`);
+    }
+    const last = tokens.at(-1)!;
+    if (Array.isArray(parent)) {
+      const index = arrayIndex(last, parent.length, op.op === 'add', at);
+      if (op.op === 'add') parent.splice(index, 0, structuredClone(op.value!));
+      else if (op.op === 'replace') parent[index] = structuredClone(op.value!);
+      else parent.splice(index, 1);
+    } else if (isObject(parent)) {
+      const target = parent as Record<string, JsonValue>;
+      if (op.op !== 'add' && !Object.hasOwn(target, last)) throw new ConfigPatchError('EDIT_PATCH_PATH_MISSING', `${at}: ${op.path} is not in the config`);
+      if (op.op === 'remove') delete target[last]; else target[last] = structuredClone(op.value!);
+    } else throw new ConfigPatchError('EDIT_PATCH_PATH_MISSING', `${at}: the parent of ${op.path} is not an object or array`);
+  }
+  return root.v;
+}
+
+/** Every JSON Pointer at which two documents differ: a changed leaf, a changed type, a key or index only one side has. Sorted. */
+export function jsonDiff(a: unknown, b: unknown): string[] {
+  const out: string[] = [];
+  const walk = (x: unknown, y: unknown, path: (string | number)[]) => {
+    if (Array.isArray(x) && Array.isArray(y)) {
+      for (let i = 0; i < Math.max(x.length, y.length); i++) { if (i >= x.length || i >= y.length) out.push(formatPointer([...path, i])); else walk(x[i], y[i], [...path, i]); }
+    } else if (isObject(x) && isObject(y)) {
+      for (const key of [...new Set([...Object.keys(x), ...Object.keys(y)])].sort()) {
+        if (!Object.hasOwn(x, key) || !Object.hasOwn(y, key)) out.push(formatPointer([...path, key])); else walk(x[key], y[key], [...path, key]);
+      }
+    } else if (x !== y) out.push(formatPointer(path));
+  };
+  walk(a, b, []);
+  return out;
+}
+
+/**
+ * For `remesh`: every op must stay inside `meshes.<part>` (the entry remesh takes); the config remesh reads is the
+ * handoff's own, unchanged. Returns the part.
+ */
+export function remeshPart(patch: ConfigPatch): string {
+  const index = patch.op.args.indexOf('--part'), part = patch.op.args[index + 1]!;
+  for (const [i, op] of patch.ops.entries()) {
+    const tokens = parsePointer(op.path);
+    if (tokens[0] !== 'meshes' || tokens[1] !== part || (tokens.length === 2 && op.op === 'remove')) throw new ConfigPatchError('EDIT_PATCH_OUT_OF_SCOPE', `ops[${i}] ${op.path}: a remesh patch edits /meshes/${pointerToken(part)} and below only (the rest of the config is what the rig was built from)`);
+  }
+  return part;
+}