@rig-c/review 0.0.0-stage → 0.2.1

package/examples/demo/SOURCE.md

@@ -0,0 +1,5 @@
+# Abstract lantern source study
+
+The SVG, synthetic canonical pose sequence coordinates, and short synthetic sine-wave chime were authored for this repository. They contain no imported or private art.
+
+This package deliberately has no compiled rig. It demonstrates source comparison, checkpoint notes, audio audition, explicit review status, and structured frame/target/category feedback. Playback becomes available when an agent supplies `model` pointing to a gated rigc build's `skeleton.model.json`, with its local page images. The pose sequence demonstrates the canonical `rig-pose-sequence/1` transport shape; its coordinates were authored here and were not extracted or measured from footage. This source sketch is not proof of rig quality.

package/examples/demo/lantern.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="800" height="800" viewBox="0 0 800 800">
+<rect width="800" height="800" fill="#182029"/>
+<circle cx="400" cy="390" r="270" fill="#202c38"/>
+<path d="M400 92V220" stroke="#89aaa9" stroke-width="16"/>
+<circle cx="400" cy="220" r="22" fill="#a8c8c3"/>
+<path d="M310 275L400 238L490 275L520 487L400 560L280 487Z" fill="#e9bb69" stroke="#f8dc9c" stroke-width="9"/>
+<path d="M310 275L400 320L490 275M400 320V560M280 487L400 435L520 487" fill="none" stroke="#b87e4b" stroke-width="10"/>
+<path d="M400 568V650M374 650H426" stroke="#89aaa9" stroke-width="13" stroke-linecap="round"/>
+<text x="400" y="733" text-anchor="middle" fill="#a8b9c3" font-family="sans-serif" font-size="20">ORIGINAL SOURCE STUDY · NO COMPILED MODEL</text>
+</svg>

package/examples/demo/pose.json

@@ -0,0 +1,244 @@
+{
+  "spec": "rig-pose-sequence/1",
+  "space": {
+    "units": "picture-px",
+    "origin": "top-left",
+    "y": "down"
+  },
+  "width": 800,
+  "height": 800,
+  "source": "synthetic-schema-example-not-a-Nova-extraction",
+  "frames": [
+    {
+      "t": 0,
+      "people": [
+        {
+          "id": "sample",
+          "joints": {
+            "neck": {
+              "state": "observed",
+              "at": [
+                400,
+                220
+              ],
+              "score": 1
+            },
+            "r_shoulder": {
+              "state": "observed",
+              "at": [
+                310,
+                275
+              ]
+            },
+            "r_elbow": {
+              "state": "observed",
+              "at": [
+                280,
+                387
+              ]
+            },
+            "r_wrist": {
+              "state": "observed",
+              "at": [
+                280,
+                487
+              ]
+            },
+            "l_shoulder": {
+              "state": "observed",
+              "at": [
+                490,
+                275
+              ]
+            },
+            "l_elbow": {
+              "state": "observed",
+              "at": [
+                520,
+                387
+              ]
+            },
+            "l_wrist": {
+              "state": "observed",
+              "at": [
+                520,
+                487
+              ]
+            },
+            "r_hip": {
+              "state": "observed",
+              "at": [
+                374,
+                560
+              ]
+            },
+            "l_hip": {
+              "state": "observed",
+              "at": [
+                426,
+                560
+              ]
+            },
+            "nose": {
+              "state": "missing"
+            }
+          }
+        }
+      ]
+    },
+    {
+      "t": 0.5,
+      "people": [
+        {
+          "id": "sample",
+          "joints": {
+            "neck": {
+              "state": "observed",
+              "at": [
+                420,
+                220
+              ],
+              "score": 1
+            },
+            "r_shoulder": {
+              "state": "observed",
+              "at": [
+                330,
+                275
+              ]
+            },
+            "r_elbow": {
+              "state": "observed",
+              "at": [
+                300,
+                387
+              ]
+            },
+            "r_wrist": {
+              "state": "observed",
+              "at": [
+                300,
+                487
+              ]
+            },
+            "l_shoulder": {
+              "state": "observed",
+              "at": [
+                510,
+                275
+              ]
+            },
+            "l_elbow": {
+              "state": "observed",
+              "at": [
+                540,
+                387
+              ]
+            },
+            "l_wrist": {
+              "state": "observed",
+              "at": [
+                540,
+                487
+              ]
+            },
+            "r_hip": {
+              "state": "observed",
+              "at": [
+                394,
+                560
+              ]
+            },
+            "l_hip": {
+              "state": "observed",
+              "at": [
+                446,
+                560
+              ]
+            },
+            "nose": {
+              "state": "missing"
+            }
+          }
+        }
+      ]
+    },
+    {
+      "t": 1,
+      "people": [
+        {
+          "id": "sample",
+          "joints": {
+            "neck": {
+              "state": "observed",
+              "at": [
+                400,
+                220
+              ],
+              "score": 1
+            },
+            "r_shoulder": {
+              "state": "observed",
+              "at": [
+                310,
+                275
+              ]
+            },
+            "r_elbow": {
+              "state": "observed",
+              "at": [
+                280,
+                387
+              ]
+            },
+            "r_wrist": {
+              "state": "observed",
+              "at": [
+                280,
+                487
+              ]
+            },
+            "l_shoulder": {
+              "state": "observed",
+              "at": [
+                490,
+                275
+              ]
+            },
+            "l_elbow": {
+              "state": "observed",
+              "at": [
+                520,
+                387
+              ]
+            },
+            "l_wrist": {
+              "state": "observed",
+              "at": [
+                520,
+                487
+              ]
+            },
+            "r_hip": {
+              "state": "observed",
+              "at": [
+                374,
+                560
+              ]
+            },
+            "l_hip": {
+              "state": "observed",
+              "at": [
+                426,
+                560
+              ]
+            },
+            "nose": {
+              "state": "missing"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}

package/examples/demo/review.json

@@ -0,0 +1,67 @@
+{
+  "schema": "rig-review/1",
+  "id": "abstract-lantern",
+  "title": "Lantern \u00b7 first inspection",
+  "revision": "source-study-1",
+  "references": [
+    {
+      "id": "source",
+      "label": "Original geometric study",
+      "type": "image",
+      "path": "lantern.svg",
+      "width": 800,
+      "height": 800
+    },
+    {
+      "id": "pose",
+      "label": "Canonical pose sequence \u00b7 synthetic example",
+      "type": "pose",
+      "path": "pose.json"
+    }
+  ],
+  "animations": [],
+  "checkpoints": [
+    {
+      "id": "silhouette",
+      "title": "Check silhouette and hanging joint",
+      "workspace": "modeling",
+      "reference": "source",
+      "note": "This original abstract SVG is source material. No compiled model is included; record structured feedback rather than assuming playback."
+    },
+    {
+      "id": "joints",
+      "title": "Check the intended joint chain",
+      "workspace": "modeling",
+      "reference": "pose",
+      "note": "An authored synthetic rig-pose-sequence/1 schema example, not extracted from footage. Picture pixels, top-left origin, Y down; no rig binding is inferred."
+    },
+    {
+      "id": "sound",
+      "title": "Audition the proposed soft chime",
+      "workspace": "motion",
+      "note": "Play the local original tone and leave an audio note. No animation timing is claimed."
+    }
+  ],
+  "authoring": [
+    {
+      "label": "Source provenance and next build",
+      "path": "SOURCE.md"
+    }
+  ],
+  "audio": {
+    "clips": [
+      {
+        "id": "chime",
+        "label": "Original synthetic chime",
+        "path": "chime.wav"
+      }
+    ],
+    "cues": [
+      {
+        "id": "sample",
+        "clip": "chime",
+        "time": 0
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@rig-c/review",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "type": "module",
+  "description": "Local human rig inspection and structured feedback export",
+  "license": "MIT",
+  "scripts": {
+    "review": "bun src/cli.ts",
+    "check": "bun src/cli.ts check",
+    "demo": "bun src/cli.ts examples/demo/review.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "build": "bun src/build.ts",
+    "feedback": "bun src/cli.ts feedback",
+    "open": "bun src/cli.ts open",
+    "smoke": "bun scripts/install-smoke.ts"
+  },
+  "dependencies": {
+    "@napi-rs/canvas": "1.0.11",
+    "@rig-c/play": "1.12.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "bin": {
+    "rig-review": "src/cli.ts"
+  },
+  "files": [
+    "src",
+    "web",
+    "examples/demo",
+    "docs/REVIEW_PACKAGE.md",
+    "docs/DESIGN.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rig-c/review.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/animation-selection.ts

@@ -0,0 +1,29 @@
+/** Actual catalog membership selects a clip; report timing never invents one. */
+import type {FeedbackCatalog} from './feedback-validation.ts';
+import type {ReportSeeds} from './report.ts';
+export interface AnimationSelection {name:string;source:'cli'|'report'|'unique';reportPaths?:string[]}
+interface Source {label:string;catalog:Pick<FeedbackCatalog,'animations'>;report:Pick<ReportSeeds,'animation'|'path'>|null}
+export function selectAnimation(sources:Source[],explicit?:string,allowStatic=false):AnimationSelection|null {
+ if(!sources.length||sources.length>2)throw new Error('open.animation: expected one or two actual catalogs');
+ if(explicit!==undefined&&(!explicit.trim()))throw new Error('open.animation: expected nonempty animation name');
+ const requireName=(name:string)=>{for(const source of sources){if(source.catalog.animations===null)throw new Error(`open.${source.label}.animation: validation unavailable without compiled model`);if(!source.catalog.animations.some(clip=>clip.name===name))throw new Error(`open.${source.label}.animation: model has no animation ${JSON.stringify(name)}`);}};
+ if(explicit!==undefined){requireName(explicit);return {name:explicit,source:'cli'};}
+ if(allowStatic&&sources.length===1&&sources[0]!.catalog.animations===null)return null;
+ const reports=sources.filter(source=>source.report?.animation!==undefined);
+ const names=[...new Set(reports.map(source=>source.report!.animation!))];
+ if(names.length>1)throw new Error(`open.animation: conflicting report animations: ${reports.map(source=>`${source.label}=${JSON.stringify(source.report!.animation)}`).join(', ')}; select --animation explicitly`);
+ if(names.length===1){requireName(names[0]!);return {name:names[0]!,source:'report',reportPaths:[...new Set(reports.map(source=>source.report!.path))]};}
+ if(sources.some(source=>source.catalog.animations===null))throw new Error('open.animation: validation unavailable without compiled models');
+ const common=sources[0]!.catalog.animations!.filter(clip=>sources.every(source=>source.catalog.animations!.some(other=>other.name===clip.name))).map(clip=>clip.name);
+ if(allowStatic&&sources.length===1&&sources[0]!.catalog.animations!.length===0)return null;
+ if(common.length!==1)throw new Error(`open.animation: expected --animation; ${sources.length>1?'common animations':'model animations'}: ${common.join(', ')||'(none)'}`);
+ return {name:common[0]!,source:'unique'};
+}
+export function animationDiagnostic(selection:AnimationSelection):string {
+ return `animation: ${selection.name} (${selection.source==='cli'?'from --animation':selection.source==='report'?'from '+selection.reportPaths!.join(', '):'unique actual clip'})`;
+}
+/** Runtime init validates again against loaded public assets; never fall back on stale hints. */
+export function initialPlayerAnimation(names:readonly string[],selected:string|undefined,checkpoint?:{animation?:string}):string|null {
+ const name=checkpoint?.animation??selected;if(name!==undefined){if(!names.includes(name))throw new Error(`initial.animation: model has no animation ${JSON.stringify(name)}`);return name;}
+ return names[0]??null;
+}

package/src/build.ts

@@ -0,0 +1,8 @@
+import { fileURLToPath } from 'node:url';
+export const appRoot=fileURLToPath(new URL('..',import.meta.url));
+export async function buildWeb(mode:'single'|'compare'='single'):Promise<Blob> {
+  const result=await Bun.build({entrypoints:[appRoot+(mode==='compare'?'web/compare.ts':'web/main.ts')],target:'browser',format:'esm',minify:false});
+  if(!result.success)throw new Error(result.logs.map(v=>v.message).join('\n'));
+  const output=result.outputs.find(v=>v.path.endsWith('.js'));if(!output)throw new Error('frontend bundle: JavaScript output missing');return output;
+}
+if(import.meta.main){await buildWeb();await buildWeb('compare');console.log('Frontend bundles built successfully (single and compare).');}

package/src/cli.ts

@@ -0,0 +1,116 @@
+#!/usr/bin/env bun
+import {randomBytes} from 'node:crypto';
+import {parseControlCommand} from './control.ts';
+import { loadReview } from './manifest.ts';
+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 { readFeedbackSession, readFeedbackCompareSession } from './session-history.ts';
+import { startServer } from './server.ts';
+import { loadCompare } from './compare.ts';
+import { startCompareServer } from './compare-server.ts';
+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>';
+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;
+  while(args.length){const flag=args.shift();if(flag==='--json'){jsonOnly=true;continue;}if(flag==='--all-feedback'){all=true;continue;}const value=args.shift();if(!value)throw new Error(`Missing value for ${flag}`);if(flag==='--reference')reference=value;else if(flag==='--reference-video')referenceVideo=value;else if(flag==='--animation')animation=value;else if(flag==='--basis'){if(value!=='a'&&value!=='b')throw new Error('strip --basis: expected a | b');basis=value;}else if(flag==='--frames')range=value;else if(flag==='--out')output=value;else throw new Error(`Unknown strip option ${flag}`);}
+  if(!animation||(!reference&&!referenceVideo))throw new Error('strip: --animation and explicit --reference are required (single uses declared reference id, compare uses local video)');
+  if(all===!!range)throw new Error('strip: choose exactly one --frames FIRST:LAST or --all-feedback');
+  if(all&&basis)throw new Error('strip --basis: use with --frames; feedback batches retain each recorded side');
+  if(!jsonOnly&&!output)throw new Error('strip: PNG requires --out outside source packages');
+  let intervals:StripInterval[]=[];
+  if(range){const match=/^(\d+):(\d+)$/.exec(range);if(!match)throw new Error('strip --frames: expected inclusive FIRST:LAST');if(compare&&!basis)throw new Error('strip --basis: explicitly select a | b');intervals=[{id:'selection',basis:compare?basis!:'single',frameStart:Number(match[1]),frameEnd:Number(match[2])}];}
+  const request=(hash:string):StripRequest=>({format:jsonOnly?'json':'png',sourceHash:hash,animation:animation!,...(compare?{}:{referenceId:reference}),intervals});
+  const fromFeedback=(feedback:(Feedback&{side?:'a'|'b'})[])=>feedback.map(f=>{const context=f.context;if(!context||typeof context!=='object'||Array.isArray(context)||context.animation!==animation)throw new Error('strip --all-feedback: every interval must identify the selected animation');return {id:f.id,feedbackId:f.id,basis:compare?f.side!:'single' as const,frameStart:f.frameStart,frameEnd:f.frameEnd};});
+  let result,roots:string[];
+  if(compare){if(referenceVideo)throw new Error('strip compare: use --reference local-video');const p=await loadCompare({a,b:b!,reference:reference!,animation});roots=[p.a.root,p.b.root];if(all)intervals=fromFeedback((await readCompareSession(p,options.stateDir)).feedback);if(output){await validateStripOutput(output,roots);if(!jsonOnly)await validateStripOutput(output+'.json',roots);}result=await exportCompareStrip(p,request(p.response.sourceHash));}
+  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());
+}
+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(`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(`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(`Unknown open option ${flag}`);}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(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;}
+  else if(flag==='--command'){if(value.length>8192)throw new Error('--command: JSON exceeds 8 KiB');options.command=parseControlCommand(JSON.parse(value));}
+  else throw new Error(`Unknown control option ${flag}`);
+ }
+ const result=await controlReview(inputs,options);console.log(JSON.stringify(result,null,2));if(options.command&&(result as {status?:string}).status!=='applied')process.exitCode=2;
+}
+/** Formatting is CLI-only; session lookup/save contracts remain unchanged. */
+export function feedbackFormat(args:string[]):{args:string[];format:'json'|'issue'} {
+ const remaining:string[]=[];let format:'json'|'issue'='json',seen=false,inputs=-1;
+ for(let i=0;i<args.length;i++){
+  const token=args[i]!;
+  // Compare owns its next two positional inputs, even when they look like flags.
+  if(inputs>0){remaining.push(token);inputs--;continue;}
+  if(token==='--format'){
+   if(seen)throw new Error('feedback --format: duplicate option');seen=true;
+   const value=args[++i];if(value!=='json'&&value!=='issue')throw new Error('feedback --format: expected json | issue');format=value;continue;
+  }
+  remaining.push(token);
+  if(inputs<0){inputs=token==='compare'?2:0;continue;}
+  // The existing CLI consumes option/value pairs. Leave their validation to it;
+  // in particular, --animation may legitimately own the value "--format".
+  const value=args[++i];if(value!==undefined)remaining.push(value);
+ }
+ return {args:remaining,format};
+}
+/** Help flags are options; positional inputs and known option values remain literal. */
+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'];
+ 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;
+ }
+ return false;
+}
+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);console.log(result.url);if(inputs.control)console.error('Inspection control enabled; query the current connected page with rig-review control and the same inputs.');if(result.selection)console.error(animationDiagnostic(result.selection));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;}
+  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;}
+  // Feedback formatting assigns --format/value ownership before the help pass.
+  if(commandHelpRequested(args,command)){console.log(usage);return;}
+  const printFeedback=(session:Parameters<typeof formatFeedbackIssues>[0])=>console.log(format==='issue'?formatFeedbackIssues(session).trimEnd():JSON.stringify(session,null,2));
+  if(args[0]==='compare'){
+    args.shift();const a=args.shift(),b=args.shift();if(!a||!b)throw new Error(usage);let reference:string|undefined,animation:string|undefined,port=4317;
+    while(args.length){const flag=args.shift(),value=args.shift();if(!value)throw new Error(`Missing value for ${flag}`);if(flag==='--reference')reference=value;else if(flag==='--animation')animation=value;else if(flag==='--port'){port=Number(value);if(!Number.isInteger(port)||port<0||port>65535)throw new Error('--port: expected integer 0…65535');}else throw new Error(`Unknown compare option ${flag}`);}
+    if(!reference)throw new Error('compare: --reference and --animation are required');
+    // A report naming the clip stands in for --animation; without one the flag stays required.
+    if(animation===undefined){const [ra,rb]=await Promise.all([loadReview(a),loadReview(b)]);if(ra.report?.animation===undefined&&rb.report?.animation===undefined)throw new Error('compare: --reference and --animation are required');const selection=selectAnimation([{label:'a',catalog:ra.feedbackCatalog,report:ra.report},{label:'b',catalog:rb.feedbackCatalog,report:rb.report}])!;animation=selection.name;console.error(animationDiagnostic(selection));}
+    const p=await loadCompare({a,b,reference,animation});
+    if(command==='feedback'){printFeedback(await readFeedbackCompareSession(p,options.stateDir));return;}
+    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}`);}
+  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 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}`);
+  // Foreground serving uses the same `#cap=` fragment handoff as open: the printed link alone can submit.
+  const capability=randomBytes(32).toString('hex'),server=await startServer(p,{port,stateDir:options.stateDir,initialAnimation,capability});const url=new URL(`http://127.0.0.1:${server.port}/`);if(checkpoint)url.searchParams.set('checkpoint',checkpoint);url.hash='cap='+capability;
+  if(fromReport&&selection)console.error(animationDiagnostic(selection));
+  console.log(`Review ready: ${url}\nPackage: ${p.manifest.title} (${p.manifest.revision})\nSource SHA-256: ${p.sourceHash}\nPress Ctrl+C to stop.`);
+}
+if(import.meta.main)main(Bun.argv.slice(2)).catch(e=>{console.error(e instanceof Error?e.message:e);process.exitCode=1;});

package/src/compare-playhead.ts

@@ -0,0 +1,55 @@
+/** Both inspection players reopen on exactly the same fixed-step history. */
+import { frameAtTime, type FrameClock } from './frame-clock.ts';
+
+export const compareSeekStep = 1 / 60;
+export interface CompareDomain { start: 0; end: number }
+export interface ReferenceSample { time: number; source: 'video-frame' | 'current-time' }
+export interface InspectionPlayer { readonly time: number; pause(): void; seek(time: number): void; draw(): void }
+export interface CompareTrace { reference: number; a: number; b: number; source: ReferenceSample['source'] }
+
+/** Feedback can describe only a successfully synchronized inspection state. */
+export function feedbackTrace(ready: boolean, seeking: boolean, trace: CompareTrace | null): CompareTrace | null {
+  return ready && !seeking ? trace : null;
+}
+
+/** Runtime accumulation may differ by an admitted ULP; the validated master
+ * mediaTime is the timestamp each side's explicit producer clock interprets. */
+export function inspectionFrame(clock: FrameClock | null | undefined, trace: CompareTrace | null): number | null {
+  return trace ? frameAtTime(clock, trace.reference) : null;
+}
+
+export function commonDomain(referenceDuration: number, aDuration: number, bDuration: number): CompareDomain {
+  for (const [name, value] of [['reference', referenceDuration], ['a', aDuration], ['b', bDuration]] as const) {
+    if (!Number.isFinite(value) || value < 0) throw new Error(`compare ${name} duration: expected finite seconds >= 0`);
+  }
+  return { start: 0, end: Math.min(referenceDuration, aDuration, bDuration) };
+}
+
+export function requireCommonTime(time: number, domain: CompareDomain): void {
+  if (!Number.isFinite(time) || time < domain.start || time > domain.end) throw new Error(`compare time ${time}: outside shared domain ${domain.start}–${domain.end} s`);
+}
+
+/** No frame(dt), resume, per-side clamp or loop exists on this inspection path. */
+export function prepareSynchronizedPair(sample: ReferenceSample, a: InspectionPlayer, b: InspectionPlayer, domain: CompareDomain): CompareTrace {
+  requireCommonTime(sample.time, domain);
+  a.pause(); b.pause();
+  // Prepare both poses before either draw. A refusal is a failed pair, never a
+  // success trace made by copying the requested time into the returned values.
+  a.seek(sample.time); b.seek(sample.time);
+  const trace = { reference: sample.time, a: a.time, b: b.time, source: sample.source };
+  if (![trace.a, trace.b].every(Number.isFinite) || Math.abs(trace.a - sample.time) > 1e-9 || Math.abs(trace.b - sample.time) > 1e-9 || trace.a !== trace.b) throw new Error(`compare playhead mismatch: reference=${trace.reference}, a=${trace.a}, b=${trace.b}`);
+  return trace;
+}
+
+export function drawSynchronizedPair(a:InspectionPlayer,b:InspectionPlayer):void {a.draw();b.draw();}
+
+export function seekSynchronizedPair(sample: ReferenceSample,a:InspectionPlayer,b:InspectionPlayer,domain:CompareDomain):CompareTrace {
+ const trace=prepareSynchronizedPair(sample,a,b,domain);drawSynchronizedPair(a,b);return trace;
+}
+
+/** The browser adapter resolves only after the reference seek has completed. */
+export async function seekAfterReference(requested: number, seekReference: (time: number) => Promise<ReferenceSample>, a: InspectionPlayer, b: InspectionPlayer, domain: CompareDomain): Promise<CompareTrace> {
+  requireCommonTime(requested, domain);
+  const presented = await seekReference(requested);
+  return seekSynchronizedPair(presented, a, b, domain);
+}