@rig-c/review 0.0.0-stage → 0.2.1

package/src/compare-presentation.ts

@@ -0,0 +1,43 @@
+/** Consumer presentation bookkeeping. Preparing a pose never claims it was drawn. */
+import {drawSynchronizedPair,prepareSynchronizedPair,type CompareTrace,type ReferenceSample,type InspectionPlayer,type CompareDomain} from './compare-playhead.ts';
+export interface PresentationState {
+ status:'unknown'|'drawn'|'held'|'failed';target:ReferenceSample|null;prepared:CompareTrace|null;lastDrawn:CompareTrace|null;inspection:CompareTrace|null;
+ callbacks:number;dropped:number;deadlineMisses:number;presentationGaps:number;lastPoseMs:number;lastDrawMs:number;lastLatenessMs:number;drawBudgetEstimateMs:number;nextReferenceEstimateMs:number|null;currentDisplayLatenessMs:number|null;deadlineKnownCallbacks:number;deadlineUnknownCallbacks:number;deadlineKind:'paused'|'next-reference-estimate'|'unknown';
+}
+export class ComparePresentation {
+ private value:PresentationState={status:'unknown',target:null,prepared:null,lastDrawn:null,inspection:null,callbacks:0,dropped:0,deadlineMisses:0,presentationGaps:0,lastPoseMs:0,lastDrawMs:0,lastLatenessMs:0,drawBudgetEstimateMs:0,nextReferenceEstimateMs:null,currentDisplayLatenessMs:null,deadlineKnownCallbacks:0,deadlineUnknownCallbacks:0,deadlineKind:'unknown'};
+ private recentDraw:number[]=[];private previousPresented:number|null=null;
+ snapshot():PresentationState{return {...this.value,target:this.value.target?{...this.value.target}:null,prepared:this.value.prepared?{...this.value.prepared}:null,lastDrawn:this.value.lastDrawn?{...this.value.lastDrawn}:null,inspection:this.value.inspection?{...this.value.inspection}:null};}
+ private finish(now:number,deadline:number|null):void {this.value.lastLatenessMs=deadline===null?0:Math.max(0,now-deadline);if(this.value.lastLatenessMs>0)this.value.deadlineMisses++;}
+ private draw(a:InspectionPlayer,b:InspectionPlayer,trace:CompareTrace,now:()=>number):void {
+  const start=now();try{drawSynchronizedPair(a,b);}catch(error){this.value.status='failed';this.value.lastDrawn=null;this.value.inspection=null;throw error;}
+  this.value.lastDrawMs=now()-start;this.recentDraw.push(this.value.lastDrawMs);if(this.recentDraw.length>20)this.recentDraw.shift();
+  const sorted=[...this.recentDraw].sort((x,y)=>x-y);this.value.drawBudgetEstimateMs=sorted[Math.max(0,Math.ceil(sorted.length*.95)-1)]!;
+  this.value.lastDrawn={...trace};
+ }
+ /** Paused inspection has no presentation deadline and keeps deterministic replay. */
+ inspect(sample:ReferenceSample,a:InspectionPlayer,b:InspectionPlayer,domain:CompareDomain,now:()=>number):PresentationState {
+  this.previousPresented=null;this.value.deadlineKind='paused';this.value.nextReferenceEstimateMs=null;this.value.currentDisplayLatenessMs=null;this.value.target={...sample};this.value.inspection=null;const start=now();
+  try{const trace=prepareSynchronizedPair(sample,a,b,domain);this.value.prepared=trace;this.value.lastPoseMs=now()-start;this.draw(a,b,trace,now);this.value.inspection={...trace};this.value.status='drawn';this.value.lastLatenessMs=0;return this.snapshot();}
+  catch(error){this.value.status='failed';this.value.inspection=null;throw error;}
+ }
+ /** Always submit the latest observed pair immediately. Synchronous seek/draw
+  * cannot receive a newer JavaScript callback midway. Lateness is classified
+  * afterward; the estimated next reference boundary never suppresses drawing. */
+ present(sample:ReferenceSample,expectedDisplayTime:number|null,presentedFrames:number|null,a:InspectionPlayer,b:InspectionPlayer,domain:CompareDomain,now:()=>number,nextIntervalSeconds:number|null=null):PresentationState {
+  this.value.callbacks++;this.value.target={...sample};this.value.inspection=null;this.value.prepared=null;this.value.lastPoseMs=0;this.value.lastDrawMs=0;
+  const estimate=expectedDisplayTime!==null&&Number.isFinite(expectedDisplayTime)&&nextIntervalSeconds!==null&&Number.isFinite(nextIntervalSeconds)&&nextIntervalSeconds>0?expectedDisplayTime+nextIntervalSeconds*1000:null;
+  this.value.nextReferenceEstimateMs=estimate!==null&&Number.isFinite(estimate)?estimate:null;
+  this.value.deadlineKind=this.value.nextReferenceEstimateMs===null?'unknown':'next-reference-estimate';
+  if(this.value.nextReferenceEstimateMs===null)this.value.deadlineUnknownCallbacks++;else this.value.deadlineKnownCallbacks++;
+  if(presentedFrames!==null){if(this.previousPresented!==null)this.value.presentationGaps+=Math.max(0,presentedFrames-this.previousPresented-1);this.previousPresented=presentedFrames;}
+  const started=now();
+  try{
+   const trace=prepareSynchronizedPair(sample,a,b,domain);this.value.prepared=trace;this.value.lastPoseMs=now()-started;
+   this.draw(a,b,trace,now);const finished=now();this.finish(finished,this.value.nextReferenceEstimateMs);
+   this.value.currentDisplayLatenessMs=expectedDisplayTime===null?null:Math.max(0,finished-expectedDisplayTime);
+   this.value.status='drawn';if(this.value.deadlineKind==='next-reference-estimate'&&this.value.lastLatenessMs===0)this.value.inspection={...trace};
+   return this.snapshot();
+  }catch(error){this.value.status='failed';this.value.inspection=null;throw error;}
+ }
+}

package/src/compare-server.ts

@@ -0,0 +1,63 @@
+import {createControlServer,type ControlIdentity} from './control-server.ts';
+import {openGate,staleOpenStatus,accessGate,openNonceGate,stampOpen,type OpenIdentity} from './open-protocol.ts';
+import { readFile } from 'node:fs/promises';
+import { appRoot, buildWeb } from './build.ts';
+import { packagePath, safeFile } from './manifest.ts';
+import { assertCompareUnchanged, safeCompareReference, type ComparePackage } from './compare.ts';
+import { serveReference } from './reference.ts';
+import {referenceFrameIndex} from './reference-frame-index.ts';
+import { exportCompareStrip, stripJson } from './strip-export.ts';
+import { readCompareSession, saveCompareSession } from './compare-session.ts';
+
+const headers={'X-Content-Type-Options':'nosniff','Cache-Control':'no-store','Content-Security-Policy':"default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' blob: data:; media-src 'self'; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'",'Referrer-Policy':'no-referrer'};
+const json=(value:unknown,status=200)=>Response.json(value,{status,headers});
+async function bodyJson(req:Request):Promise<unknown>{
+  if(!/^application\/json(?:\s*;|$)/i.test(req.headers.get('content-type')??''))throw new Error('Expected application/json');
+  if(Number(req.headers.get('content-length')??0)>1024*1024)throw new Error('Session payload exceeds 1 MiB');
+  if(!req.body)throw new Error('JSON body required');const reader=req.body.getReader(),chunks:Uint8Array[]=[];let size=0;
+  while(true){const {value,done}=await reader.read();if(done)break;size+=value.length;if(size>1024*1024){await reader.cancel();throw new Error('Session payload exceeds 1 MiB');}chunks.push(value);}
+  const bytes=new Uint8Array(size);let offset=0;for(const chunk of chunks){bytes.set(chunk,offset);offset+=chunk.length;}return JSON.parse(new TextDecoder().decode(bytes));
+}
+function serveAsset(req:Request,path:string):Response{
+  const file=Bun.file(path),size=file.size;const assetHeaders={...headers,'Content-Security-Policy':"default-src 'none'; script-src 'none'; sandbox",'Content-Type':file.type||'application/octet-stream','Accept-Ranges':'bytes'};
+  const range=req.headers.get('range');if(range){const match=/^bytes=(\d*)-(\d*)$/.exec(range);let start=0,end=size-1;
+    if(!match||(!match[1]&&!match[2]))return new Response(null,{status:416,headers:{...assetHeaders,'Content-Range':`bytes */${size}`}});
+    if(!match[1])start=Math.max(0,size-Number(match[2]));else{start=Number(match[1]);if(match[2])end=Math.min(end,Number(match[2]));}
+    if(!Number.isSafeInteger(start)||!Number.isSafeInteger(end)||start<0||start>=size||end<start)return new Response(null,{status:416,headers:{...assetHeaders,'Content-Range':`bytes */${size}`}});
+    return new Response(req.method==='HEAD'?null:file.slice(start,end+1),{status:206,headers:{...assetHeaders,'Content-Range':`bytes ${start}-${end}/${size}`,'Content-Length':String(end-start+1)}});
+  }
+  return new Response(req.method==='HEAD'?null:file,{headers:{...assetHeaders,'Content-Length':String(size)}});
+}
+/** `capability` (open workers and foreground CLI serving) gates every non-GET request; tests may omit it. */
+export async function startCompareServer(p:ComparePackage,options:{port?:number;stateDir?:string;open?:OpenIdentity;activity?:()=>void;control?:ControlIdentity;capability?:string}={}){
+  const bundle=await buildWeb('compare');
+  const frames=referenceFrameIndex(p.referencePath,p.response.binding.reference.sha256,p.response.sourceHash);
+  const control=options.control?createControlServer({identity:options.control,sourceHash:p.response.sourceHash,mode:'compare',unchanged:()=>assertCompareUnchanged(p),activity:options.activity}):null;
+  const handle=async(req:Request,port:number|undefined):Promise<Response>=>{try{
+    const url=new URL(req.url),origin=`http://127.0.0.1:${port}`;
+    if(url.origin!==origin)return json({error:'Loopback host required'},403);
+    const refused=openNonceGate(req,options.open)??accessGate(req,options.capability);if(refused)return refused;
+    const controlled=await control?.(req,origin);if(controlled)return controlled;
+    options.activity?.();const gate=openGate(req,options.open);if(gate){if(gate.status===200){try{await assertCompareUnchanged(p);}catch{return staleOpenStatus(options.open!);}}return gate;}
+    if(req.method==='PUT'&&url.pathname==='/api/compare/session'){
+      if(req.headers.get('origin')!==origin)return json({error:'Same-origin Origin required'},403);
+      return json(await saveCompareSession(p,await bodyJson(req),options.stateDir));
+    }
+    if(req.method==='POST'&&url.pathname==='/api/compare/strip'){
+      if(req.headers.get('origin')!==origin)return json({error:'Same-origin Origin required'},403);
+      const result=await exportCompareStrip(p,await bodyJson(req));
+      return new Response(result.png?new Uint8Array(result.png):stripJson(result),{headers:{...headers,'Content-Type':result.png?'image/png':'application/json; charset=utf-8','Content-Disposition':`attachment; filename="review-strip.${result.png?'png':'json'}"`}});
+    }
+    if(req.method!=='GET'&&req.method!=='HEAD')return json({error:'Method not allowed'},405);
+    if(url.pathname==='/api/compare/reference-frames'){if(url.search)return json({error:'Reference frame index accepts no parameters'},400);await assertCompareUnchanged(p);await safeCompareReference(p);return json(await frames());}
+    if(url.pathname==='/api/compare'){await assertCompareUnchanged(p);return json(p.response);}
+    if(url.pathname==='/api/compare/session')return json(await readCompareSession(p,options.stateDir));
+    if(url.pathname==='/compare-reference')return await serveReference(req,await safeCompareReference(p),p.response.binding.reference.sha256,headers);
+    if(url.pathname.startsWith('/compare-assets/')){const match=/^\/compare-assets\/(a|b)\/(.+)$/.exec(url.pathname);if(!match)return json({error:'Unknown comparison side'},404);const side=match[1] as 'a'|'b',path=packagePath(decodeURIComponent(match[2]!));if(!p[side].files.has(path))return json({error:'Asset not declared by package'},404);return serveAsset(req,await safeFile(p[side].root,path));}
+    if(url.pathname==='/main.js')return new Response(req.method==='HEAD'?null:bundle,{headers:{...headers,'Content-Type':'text/javascript'}});
+    if(url.pathname==='/'||url.pathname==='/index.html')return new Response(req.method==='HEAD'?null:await readFile(appRoot+'web/compare.html'),{headers:{...headers,'Content-Type':'text/html; charset=utf-8'}});
+    if(url.pathname==='/styles.css')return new Response(req.method==='HEAD'?null:await readFile(appRoot+'web/compare.css'),{headers:{...headers,'Content-Type':'text/css'}});
+    return json({error:'Not found'},404);
+  }catch(e){const message=e instanceof Error?e.message:'Request failed';return json({error:message},message.includes('inputs changed')?409:400);}};
+  return Bun.serve({hostname:'127.0.0.1',port:options.port??4317,async fetch(req,server){return stampOpen(req,await handle(req,server.port),options.open);}});
+}

package/src/compare-session.ts

@@ -0,0 +1,26 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { isDeepStrictEqual } from 'node:util';
+import { choice, object } from './manifest.ts';
+import { parseFeedback, readPackageFeedback, validatePackageFeedback, type FeedbackWarning, type Feedback } from './session.ts';
+import { assertCompareUnchanged, type CompareBinding, type ComparePackage } from './compare.ts';
+
+export interface CompareFeedback extends Feedback {side:'a'|'b'}
+export interface CompareSession {schema:'rig-review-compare-session/1';id:string;revision:'compare/1';sourceHash:string;binding:CompareBinding;status:'pending'|'approved'|'changes-requested';feedback:CompareFeedback[];feedbackWarnings:FeedbackWarning[];updatedAt:string|null}
+export function freshCompareSession(p:ComparePackage):CompareSession {const d=p.response;return {schema:'rig-review-compare-session/1',id:d.id,revision:d.revision,sourceHash:d.sourceHash,binding:d.binding,status:'pending',feedback:[],feedbackWarnings:[],updatedAt:null};}
+export function parseCompareSession(input:unknown,p:ComparePackage,strict=true):CompareSession {
+  const value=object(input,'compare session'),fresh=freshCompareSession(p);
+  for(const key of ['schema','id','revision','sourceHash'] as const)if(value[key]!==fresh[key])throw new Error(`compare session.${key}: does not match loaded comparison`);
+  if(!isDeepStrictEqual(value.binding,fresh.binding))throw new Error('compare session.binding: does not match both source hashes, rig/motion identities, reference hash and animation');
+  if(value.corrections!==undefined)throw new Error('compare session.corrections: motion authoring proposals are not accepted');
+  if(!Array.isArray(value.feedback)||value.feedback.length>1000)throw new Error('compare session.feedback: expected array <= 1000');
+  const feedbackWarnings:FeedbackWarning[]=[];
+  const feedback:CompareFeedback[]=value.feedback.map((item:unknown)=>{const side=choice(object(item,'feedback').side,['a','b'] as const,'feedback.side'),parsed=parseFeedback(item,strict);if(strict)return {...validatePackageFeedback(parsed,p[side],p.response.animation),side};const read=readPackageFeedback(parsed,p[side],p.response.animation);if(read.warning)feedbackWarnings.push(read.warning);return {...read.feedback,side};});
+  if(new Set(feedback.map(f=>f.id)).size!==feedback.length)throw new Error('compare session.feedback: duplicate ids');
+  return {...fresh,status:choice(value.status,['pending','approved','changes-requested'] as const,'compare session.status'),feedback,feedbackWarnings,updatedAt:new Date().toISOString()};
+}
+export function compareSessionFile(p:ComparePackage,stateDir=join(homedir(),'.local','state','rig-c-review')):string {const key=createHash('sha256').update(JSON.stringify(['compare',p.response.sourceHash,p.response.binding])).digest('hex');return join(stateDir,key+'.json');}
+export async function readCompareSession(p:ComparePackage,stateDir?:string):Promise<CompareSession>{await assertCompareUnchanged(p);try{const value=JSON.parse(await readFile(compareSessionFile(p,stateDir),'utf8'));return {...parseCompareSession(value,p,false),updatedAt:value.updatedAt};}catch(e){if((e as NodeJS.ErrnoException).code==='ENOENT')return freshCompareSession(p);throw e;}}
+export async function saveCompareSession(p:ComparePackage,input:unknown,stateDir?:string):Promise<CompareSession>{const value=parseCompareSession(input,p);await assertCompareUnchanged(p);const file=compareSessionFile(p,stateDir);await mkdir(join(file,'..'),{recursive:true,mode:0o700});const tmp=file+'.'+crypto.randomUUID()+'.tmp';await writeFile(tmp,JSON.stringify(value,null,2)+'\n',{mode:0o600});await rename(tmp,file);return value;}

package/src/compare.ts

@@ -0,0 +1,57 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { loadReview, object, safeFile, string, type ReviewManifest, type ReviewedSource, type ReviewPackage } from './manifest.ts';
+import type { FeedbackCatalog } from './feedback-validation.ts';
+import type { ReportSeeds } from './report.ts';
+
+export interface CompareInputs {a:string;b:string;reference:string;animation:string}
+export interface CompareBinding {
+  a:{sourceHash:string;reviewedSource:ReviewedSource};
+  b:{sourceHash:string;reviewedSource:ReviewedSource};
+  reference:{name:string;sha256:string};animation:string;
+}
+export interface CompareSide {manifest:ReviewManifest;report:ReportSeeds|null;feedbackCatalog:FeedbackCatalog;sourceHash:string;reviewedSource:ReviewedSource;assetsBase:'/compare-assets/a/'|'/compare-assets/b/'}
+export interface CompareResponse {mode:'compare';id:string;title:string;revision:'compare/1';sourceHash:string;binding:CompareBinding;animation:string;a:CompareSide;b:CompareSide;reference:{name:string;sha256:string;url:'/compare-reference'}}
+export interface ComparePackage {inputs:CompareInputs;a:ReviewPackage;b:ReviewPackage;referencePath:string;response:CompareResponse}
+
+async function hashFile(path:string):Promise<string>{
+  const before=await stat(path);if(!before.isFile())throw new Error('compare.reference: expected regular local video file');
+  const hash=createHash('sha256');for await(const chunk of createReadStream(path))hash.update(chunk);
+  const after=await stat(path);if(before.size!==after.size||before.mtimeMs!==after.mtimeMs)throw new Error('compare.reference changed while hashing');return hash.digest('hex');
+}
+async function requireAnimation(p:ReviewPackage,animation:string,side:'a'|'b'):Promise<void>{
+  if(!p.manifest.model||!p.reviewedSource.rig)throw new Error(`compare.${side}.model: expected compiled model for playback`);
+  const bytes=await readFile(await safeFile(p.root,p.manifest.model));
+  if(createHash('sha256').update(bytes).digest('hex')!==p.reviewedSource.rig.sha256)throw new Error(`compare.${side} inputs changed while reading animation`);
+  const model=object(JSON.parse(bytes.toString('utf8')),`compare.${side}.model`);
+  if(!Array.isArray(model.animations))throw new Error(`compare.${side}.model.animations: expected array`);
+  const found=model.animations.map((value,i)=>object(value,`compare.${side}.animations[${i}]`)).find(value=>value.name===animation);
+  if(!found)throw new Error(`compare.${side}.animation: model has no animation ${JSON.stringify(animation)}`);
+  if(typeof found.duration!=='number'||!Number.isFinite(found.duration)||found.duration<0)throw new Error(`compare.${side}.animation.duration: expected finite number >= 0`);
+}
+
+/** Three explicit local inputs; a package manifest cannot select the external reference. */
+export async function loadCompare(inputs:CompareInputs):Promise<ComparePackage>{
+  const animation=string(inputs.animation,'compare.animation');
+  const [a,b,referencePath]=await Promise.all([loadReview(inputs.a),loadReview(inputs.b),realpath(resolve(inputs.reference))]);
+  if(!/\.(mp4|webm|mov)$/i.test(referencePath))throw new Error('compare.reference: expected local mp4, webm or mov file');
+  await Promise.all([requireAnimation(a,animation,'a'),requireAnimation(b,animation,'b')]);
+  const reference={name:basename(referencePath),sha256:await hashFile(referencePath)};
+  const binding:CompareBinding={a:{sourceHash:a.sourceHash,reviewedSource:a.reviewedSource},b:{sourceHash:b.sourceHash,reviewedSource:b.reviewedSource},reference,animation};
+  const sourceHash=createHash('sha256').update(JSON.stringify(binding)).digest('hex');
+  return {inputs:{a:a.manifestPath,b:b.manifestPath,reference:referencePath,animation},a,b,referencePath,response:{mode:'compare',id:'compare-'+sourceHash.slice(0,16),title:`${a.manifest.title} / ${b.manifest.title}`,revision:'compare/1',sourceHash,binding,animation,a:{manifest:a.manifest,report:a.report,feedbackCatalog:a.feedbackCatalog,sourceHash:a.sourceHash,reviewedSource:a.reviewedSource,assetsBase:'/compare-assets/a/'},b:{manifest:b.manifest,report:b.report,feedbackCatalog:b.feedbackCatalog,sourceHash:b.sourceHash,reviewedSource:b.reviewedSource,assetsBase:'/compare-assets/b/'},reference:{...reference,url:'/compare-reference'}}};
+}
+
+export async function assertCompareUnchanged(p:ComparePackage):Promise<void>{
+  try{const current=await loadCompare(p.inputs);if(current.response.sourceHash!==p.response.sourceHash)throw new Error('source hash differs');}
+  catch(e){throw new Error(`Comparison inputs changed. Restart compare to bind feedback to current inputs. ${e instanceof Error?e.message:String(e)}`);}
+}
+
+/** Re-resolve the one CLI-selected reference before each byte-range read. */
+export async function safeCompareReference(p:ComparePackage):Promise<string>{
+  const current=await realpath(p.referencePath);
+  if(current!==p.referencePath||!(await stat(current)).isFile())throw new Error('compare.reference: expected the originally selected canonical regular file (no symlink replacement)');
+  return current;
+}

package/src/comparison-eligibility.ts

@@ -0,0 +1,54 @@
+/** Layout offers follow actual load events. A declared path, a stored request or a placeholder never establishes an input. */
+export type InputState={state:'loaded'}|{state:'pending'}|{state:'absent'}|{state:'failed';reason:string}|{state:'out-of-domain';reason:string};
+export const singleLayouts=['compare','reference','rig'] as const;
+export const pairLayouts=['compare','a','b','reference'] as const;
+export type SingleLayout=typeof singleLayouts[number];
+export type PairLayout=typeof pairLayouts[number];
+export type ComparisonLayout=SingleLayout|PairLayout;
+/** Review has no producer candidate handoff yet; this is stated, not drawn. */
+export const candidateUnavailable={state:'unavailable',reason:'no producer handoff'} as const;
+export interface Eligibility<L extends ComparisonLayout> {
+ mode:'single'|'compare';requested:L;effective:L|null;usable:L[];reasons:Partial<Record<L,string>>;candidate:typeof candidateUnavailable;
+}
+export interface PairEligibility extends Eligibility<PairLayout> {feedback:boolean;playback:boolean;static:boolean}
+export interface SingleInputs {rig:InputState;reference:InputState;requested:SingleLayout}
+export type PairDomain={end:number}|{refused:string}|null;
+export interface PairInputs {a:InputState;b:InputState;reference:InputState;domain:PairDomain;requested?:PairLayout}
+
+const prose:Record<InputState['state'],string>={loaded:'',pending:'not rendered yet',absent:'not supplied',failed:'',['out-of-domain']:''};
+/** Named reason for an input that cannot be drawn. Codes are stable; detail is display text. */
+export function inputReason(name:'RIG'|'REFERENCE'|'A'|'B',input:InputState):string|null {
+ if(input.state==='loaded')return null;
+ if(input.state==='failed')return `${name}_FAILED: ${input.reason}`;
+ if(input.state==='out-of-domain')return `${name}_OUT_OF_DOMAIN: ${input.reason}`;
+ return `${name}_${input.state.toUpperCase()}: ${name==='REFERENCE'&&input.state==='pending'?'held time not decoded yet':prose[input.state]}`;
+}
+function settle<L extends ComparisonLayout>(mode:'single'|'compare',requested:L,order:readonly L[],reasons:Partial<Record<L,string>>,fallback:readonly L[]):Eligibility<L> {
+ const usable=order.filter(layout=>reasons[layout]===undefined);
+ const effective=usable.includes(requested)?requested:fallback.find(layout=>usable.includes(layout))??null;
+ return {mode,requested,effective,usable,reasons,candidate:candidateUnavailable};
+}
+/** Single review: side by side needs an actually drawn rig AND a decoded reference. */
+export function singleEligibility(value:SingleInputs):Eligibility<SingleLayout> {
+ const rig=inputReason('RIG',value.rig),reference=inputReason('REFERENCE',value.reference),reasons:Partial<Record<SingleLayout,string>>={};
+ if(rig)reasons.rig=rig;if(reference)reasons.reference=reference;
+ if(rig||reference)reasons.compare=[rig,reference].filter(Boolean).join(' · ');
+ return settle('single',value.requested,singleLayouts,reasons,value.requested==='reference'?['reference','rig']:['rig','reference']);
+}
+/** A held time outside a video's real domain is refused, never clamped. */
+export function videoReferenceAt(held:number,duration:number):InputState {
+ if(!Number.isFinite(duration)||duration<0)return {state:'failed',reason:'video duration is not finite'};
+ if(!Number.isFinite(held)||held<0||held>duration)return {state:'out-of-domain',reason:`held time ${held} s is outside the video domain 0–${duration} s`};
+ return {state:'pending'};
+}
+/** Two builds: the pair needs both sides, the shared video and a valid common domain. A failed side leaves the survivor usable alone. */
+export function pairEligibility(value:PairInputs):PairEligibility {
+ const a=inputReason('A',value.a),b=inputReason('B',value.b),reference=inputReason('REFERENCE',value.reference),reasons:Partial<Record<PairLayout,string>>={};
+ if(a)reasons.a=a;if(b)reasons.b=b;if(reference)reasons.reference=reference;
+ const domain=value.domain,end=domain&&'end' in domain&&Number.isFinite(domain.end)&&domain.end>=0?domain.end:null;
+ const domainReason=a||b||reference?null:domain===null?'DOMAIN_PENDING: shared domain not established':'refused' in domain?`DOMAIN_REFUSED: ${domain.refused}`:end===null?'DOMAIN_REFUSED: shared end is not finite':null;
+ if(a||b||reference||domainReason)reasons.compare=[a,b,reference,domainReason].filter(Boolean).join(' · ');
+ const result=settle('compare',value.requested??'compare',pairLayouts,reasons,['a','b','reference']);
+ const pair=result.usable.includes('compare');
+ return {...result,feedback:pair,playback:pair&&end!==null&&end>0,static:pair&&end===0};
+}

package/src/control-server.ts

@@ -0,0 +1,83 @@
+import {randomUUID,timingSafeEqual} from 'node:crypto';
+import {controlInteger,controlObject,controlString,parseControlInspection,parseControlRequest,type ControlDelivery,type ControlInspection,type ControlMode,type ControlReceipt,type ControlRequest} from './control.ts';
+export interface ControlIdentity {token:string;instanceKey:string}
+interface Page {id:string;token:string;revision:number;inspection:ControlInspection;seen:number;queue:string[];inflight:string|null}
+interface Entry {request:ControlRequest;receipt:ControlReceipt;created:number;dispatched?:number}
+const response=(v:unknown,status=200)=>Response.json(v,{status,headers:{'Cache-Control':'no-store','X-Content-Type-Options':'nosniff'}});
+function bearer(req:Request,token:string):boolean{const actual=Buffer.from(req.headers.get('authorization')??''),expected=Buffer.from('Bearer '+token);return actual.length===expected.length&&timingSafeEqual(actual,expected);}
+export async function readControlBody(req:Request,timeoutMs=2000):Promise<unknown>{
+ if(!/^application\/json(?:\s*;|$)/i.test(req.headers.get('content-type')??''))throw new Error('CONTROL_JSON_REQUIRED');
+ if(!req.body)throw new Error('CONTROL_JSON_REQUIRED');const reader=req.body.getReader();let timer:ReturnType<typeof setTimeout>|undefined;
+ try{return await Promise.race([(async()=>{const chunks:Uint8Array[]=[];let size=0;while(true){const next=await reader.read();if(next.done)break;size+=next.value.length;if(size>16384)throw new Error('CONTROL_BODY_LIMIT: maximum 16 KiB');chunks.push(next.value);}const bytes=new Uint8Array(size);let at=0;for(const chunk of chunks){bytes.set(chunk,at);at+=chunk.length;}return JSON.parse(new TextDecoder().decode(bytes));})(),new Promise<never>((_,reject)=>{timer=setTimeout(()=>reject(new Error('CONTROL_BODY_TIMEOUT')),timeoutMs);})]);}
+ finally{if(timer)clearTimeout(timer);void reader.cancel().catch(()=>{});}
+}
+/** Per-worker bounded ephemeral inspection mailbox. No file, package or feedback mutation. */
+export function createControlServer(options:{identity:ControlIdentity;sourceHash:string;mode:ControlMode;unchanged:()=>Promise<void>;activity?:()=>void;now?:()=>number}){
+ const pages=new Map<string,Page>(),entries=new Map<string,Entry>(),requests=new Map<string,string>();const now=options.now??Date.now;
+ function expire(){
+  const time=now();for(const [id,page]of pages)if(time-page.seen>30000||page.inflight&&time-(entries.get(page.inflight)?.dispatched??time)>30000){for(const entry of entries.values())if(entry.request.pageId===id&&['queued','dispatched'].includes(entry.receipt.status)){entry.receipt.status=entry.receipt.status==='queued'?'rejected':'outcome-unknown';entry.receipt.error='CONTROL_PAGE_EXPIRED';}pages.delete(id);}
+  for(const entry of entries.values())if(entry.receipt.status==='queued'&&time-entry.created>10000){entry.receipt.status='rejected';entry.receipt.error='CONTROL_COMMAND_EXPIRED';}
+ }
+ function snapshot(){return {schema:'rig-review-control-state/1',instanceKey:options.identity.instanceKey,sourceHash:options.sourceHash,mode:options.mode,pages:[...pages.values()].map(p=>({pageId:p.id,revision:p.revision,inspection:p.inspection}))};}
+ function pageFor(req:Request,id:unknown):Page{const page=pages.get(controlString(id,'control.pageId'));if(!page||!bearer(req,page.token))throw new Error('CONTROL_PAGE_CAPABILITY_REQUIRED');return page;}
+ function errorStatus(message:string){return /CAPABILITY_REQUIRED/.test(message)?403:/STALE|INPUTS_CHANGED|BUSY|EXPIRED|NO_PAGE/.test(message)?409:400;}
+ return async function handle(req:Request,origin:string):Promise<Response|null>{
+  const url=new URL(req.url);if(!url.pathname.startsWith('/api/control'))return null;
+  try{
+   if(url.origin!==origin||url.search)return response({error:'CONTROL_LOOPBACK_PATH_REQUIRED'},403);
+   expire();
+   if(url.pathname==='/api/control/config'&&req.method==='GET')return response({schema:'rig-review-control-config/1',enabled:true,sourceHash:options.sourceHash,instanceKey:options.identity.instanceKey,mode:options.mode});
+   const agent=bearer(req,options.identity.token);
+   if(url.pathname==='/api/control'&&req.method==='GET'){if(!agent)return response({error:'CONTROL_CAPABILITY_REQUIRED'},403);await options.unchanged();return response(snapshot());}
+   if(url.pathname.startsWith('/api/control/receipts/')&&req.method==='GET'){
+    if(!agent)return response({error:'CONTROL_CAPABILITY_REQUIRED'},403);const entry=entries.get(url.pathname.slice('/api/control/receipts/'.length));return entry?response(entry.receipt):response({error:'CONTROL_RECEIPT_NOT_FOUND'},404);
+   }
+   if(req.method!=='POST')return response({error:'CONTROL_METHOD_NOT_ALLOWED'},405);
+   if(req.headers.get('origin')!==origin||req.headers.get('sec-fetch-site')==='cross-site')return response({error:'CONTROL_SAME_ORIGIN_REQUIRED'},403);
+   if(url.pathname==='/api/control/commands'){
+    if(!agent)return response({error:'CONTROL_CAPABILITY_REQUIRED'},403);
+    const input=parseControlRequest(await readControlBody(req));if(input.sourceHash!==options.sourceHash||input.instanceKey!==options.identity.instanceKey)return response({error:'CONTROL_STALE_BINDING'},409);
+    const existing=requests.get(input.requestId);if(existing){const entry=entries.get(existing)!;if(JSON.stringify(entry.request)!==JSON.stringify(input))return response({error:'CONTROL_REQUEST_ID_CONFLICT'},409);return response(entry.receipt);}
+    const page=pages.get(input.pageId);if(!page)return response({error:'CONTROL_NO_PAGE'},409);
+    if(input.expectedRevision!==page.revision)return response({error:'CONTROL_STALE_STATE'},409);
+    if(page.queue.filter(id=>entries.get(id)?.receipt.status==='queued').length>=8)return response({error:'CONTROL_QUEUE_BUSY'},409);
+    await options.unchanged();
+    // Recheck after asynchronous hashing: a concurrent poll/command may have won.
+    const concurrent=requests.get(input.requestId);if(concurrent){const entry=entries.get(concurrent)!;return JSON.stringify(entry.request)===JSON.stringify(input)?response(entry.receipt):response({error:'CONTROL_REQUEST_ID_CONFLICT'},409);}
+    if(pages.get(page.id)!==page||input.expectedRevision!==page.revision)return response({error:'CONTROL_STALE_STATE'},409);
+    page.queue=page.queue.filter(id=>entries.get(id)?.receipt.status==='queued');if(page.queue.length>=8)return response({error:'CONTROL_QUEUE_BUSY'},409);
+    while(entries.size>=64){const old=[...entries].find(([,v])=>!['queued','dispatched'].includes(v.receipt.status));if(!old)return response({error:'CONTROL_RECEIPTS_BUSY'},409);requests.delete(old[1].request.requestId);entries.delete(old[0]);}
+    const commandId=randomUUID(),receipt:ControlReceipt={commandId,requestId:input.requestId,pageId:page.id,status:'queued',revision:page.revision,inspection:null};entries.set(commandId,{request:input,receipt,created:now()});requests.set(input.requestId,commandId);page.queue.push(commandId);options.activity?.();return response(receipt,202);
+   }
+   if(url.pathname==='/api/control/register'){
+    const input=controlObject(await readControlBody(req),['sourceHash','inspection'],'control.register');if(input.sourceHash!==options.sourceHash)return response({error:'CONTROL_STALE_BINDING'},409);
+    const inspection=parseControlInspection(input.inspection);if(pages.size>=4)return response({error:'CONTROL_PAGES_BUSY'},409);await options.unchanged();if(pages.size>=4)return response({error:'CONTROL_PAGES_BUSY'},409);
+    const page:Page={id:randomUUID(),token:randomUUID(),revision:0,inspection,seen:now(),queue:[],inflight:null};pages.set(page.id,page);options.activity?.();return response({pageId:page.id,pageToken:page.token,revision:0},201);
+   }
+   if(url.pathname!=='/api/control/poll'&&url.pathname!=='/api/control/ack'&&url.pathname!=='/api/control/close')return response({error:'CONTROL_NOT_FOUND'},404);
+   // Read the bounded body only after identifying a live page capability.
+   const tokenPage=[...pages.values()].find(p=>bearer(req,p.token));if(!tokenPage)return response({error:'CONTROL_PAGE_CAPABILITY_REQUIRED'},403);
+   const input=controlObject(await readControlBody(req),url.pathname.endsWith('/ack')?['pageId','revision','inspection','commandId','status','error']:url.pathname.endsWith('/close')?['pageId']:['pageId','revision','inspection','active'],'control.page');
+   const page=pageFor(req,input.pageId);if(url.pathname.endsWith('/close')){for(const entry of entries.values())if(entry.request.pageId===page.id&&['queued','dispatched'].includes(entry.receipt.status)){entry.receipt.status=entry.receipt.status==='dispatched'?'outcome-unknown':'rejected';entry.receipt.error='CONTROL_PAGE_CLOSED';}pages.delete(page.id);return response({closed:true});}
+   const revision=controlInteger(input.revision,'control.revision'),inspection=parseControlInspection(input.inspection);if(revision<page.revision)return response({error:'CONTROL_STALE_STATE'},409);page.seen=now();
+   if(url.pathname.endsWith('/ack')){
+    const id=controlString(input.commandId,'control.commandId'),entry=entries.get(id);if(!entry||entry.request.pageId!==page.id||page.inflight!==id)return response({error:'CONTROL_STALE_ACK'},409);
+    if(!['applied','rejected','failed','superseded'].includes(String(input.status)))throw new Error('control.status: invalid acknowledgment');
+    if(input.status==='applied'&&revision!==entry.request.expectedRevision+1)throw new Error('control.revision: applied acknowledgment must advance exactly once');
+    await options.unchanged();if(pages.get(page.id)!==page||page.inflight!==id||page.revision>revision)return response({error:'CONTROL_STALE_ACK'},409);entry.receipt={...entry.receipt,status:input.status as ControlReceipt['status'],revision,inspection,...(input.error===undefined?{}:{error:controlString(input.error,'control.error',1024)})};page.inflight=null;
+   }
+   page.revision=revision;page.inspection=inspection;
+   if(input.active===true)options.activity?.();
+   if(url.pathname.endsWith('/ack'))return response({acknowledged:true});
+   if(input.active!==true&&input.active!==false)throw new Error('control.active: expected boolean');
+   if(page.inflight)return response({command:null});
+   while(page.queue.length){const id=page.queue.shift()!,entry=entries.get(id);if(!entry||entry.receipt.status!=='queued')continue;
+    if(entry.request.expectedRevision!==revision){entry.receipt.status='superseded';entry.receipt.error='CONTROL_STALE_STATE';continue;}
+    try{await options.unchanged();}catch(error){entry.receipt.status='rejected';entry.receipt.error='CONTROL_INPUTS_CHANGED';throw error;}
+    if(page.inflight||pages.get(page.id)!==page||page.revision!==revision){entry.receipt.status='superseded';entry.receipt.error='CONTROL_STALE_STATE';return response({command:null});}
+    page.inflight=id;entry.dispatched=now();entry.receipt.status='dispatched';const command:ControlDelivery={commandId:id,request:entry.request};return response({command});
+   }
+   return response({command:null});
+  }catch(error){const message=error instanceof Error?error.message:String(error);return response({error:message},/inputs changed/i.test(message)?409:errorStatus(message));}
+ };
+}

package/src/control.ts

@@ -0,0 +1,132 @@
+/** Inspection-only protocol. Source identity and human review decisions are not commands. */
+import {singleLayouts,pairLayouts,type ComparisonLayout,type Eligibility} from './comparison-eligibility.ts';
+export type ControlMode='single'|'compare';
+export type ControlCameraTarget='rig'|'a'|'b'|'reference';
+export interface ControlCamera {zoom:number;pan:{x:number;y:number}}
+export interface ControlLayers {images:boolean;meshes:boolean;bones:boolean}
+/** Observed camera coordinates, independent of viewport-specific CSS pan. */
+export interface ControlNumericCamera {
+ space:'world'|'image';center:{x:number;y:number};zoom:number;
+ viewport:{width:number;height:number};visible:{x:number;y:number;width:number;height:number};
+}
+export interface ControlView {
+ schema:'rig-review-view/1';
+ cameraSync?:boolean;activeCamera?:ControlCameraTarget;
+ cameras:{rig:ControlNumericCamera|null;a:ControlNumericCamera|null;b:ControlNumericCamera|null;reference:ControlNumericCamera|null};
+}
+export type PartIdentityReason='hidden'|'no-attachment'|'timeline-null'|'set-hide';
+/** Persistable exact target at the bookmarked pose. Generation is observation only. */
+export interface ControlPartIdentity {attachment:string|null;skin:string|null;reason:PartIdentityReason|null;set:string|null;activeSkin:string|null}
+export function parsePartIdentity(value:unknown):ControlPartIdentity {
+ const o=controlObject(value,['attachment','skin','reason','set','activeSkin'],'control.part.identity');
+ const nullable=(value:unknown,name:string)=>value===null?null:controlString(value,name,512);
+ const result={attachment:nullable(o.attachment,'part.attachment'),skin:nullable(o.skin,'part.skin'),reason:o.reason===null?null:choice(o.reason,['hidden','no-attachment','timeline-null','set-hide'] as const,'part.reason'),set:nullable(o.set,'part.set'),activeSkin:nullable(o.activeSkin,'part.activeSkin')};
+ if(result.reason===null?(result.attachment===null||result.skin===null):(result.attachment!==null||result.skin!==null))throw new Error('PART_IDENTITY_SHAPE: resolved key/owning skin or explicit null reason required');return result;
+}
+export interface ControlPart {side:'single'|'a'|'b';slot:string;mode:'context'|'solo';identity?:ControlPartIdentity}
+export function parseControlPart(value:unknown):ControlPart|null {if(value===null)return null;const o=controlObject(value,['side','slot','mode','identity'],'control.part');return {side:choice(o.side,['single','a','b'] as const,'control.part.side'),slot:controlString(o.slot,'control.part.slot',512),mode:choice(o.mode,['context','solo'] as const,'control.part.mode'),...(o.identity===undefined?{}:{identity:parsePartIdentity(o.identity)})};}
+/** Observed layout offer: requested (source-bound draft), effective (actually visible) and a named reason per unavailable layout. */
+export interface ControlComparison {mode:'single'|'compare';requestedLayout:ComparisonLayout;effectiveLayout:ComparisonLayout|null;usableLayouts:ComparisonLayout[];reasons:Partial<Record<ComparisonLayout,string>>;candidate:{state:'unavailable';reason:'no producer handoff'}}
+export function controlComparison(value:Eligibility<ComparisonLayout>):ControlComparison {return {mode:value.mode,requestedLayout:value.requested,effectiveLayout:value.effective,usableLayouts:[...value.usable],reasons:{...value.reasons},candidate:{...value.candidate}};}
+export function parseControlComparison(value:unknown):ControlComparison {
+ const o=controlObject(value,['mode','requestedLayout','effectiveLayout','usableLayouts','reasons','candidate'],'control.comparison');
+ const mode=choice(o.mode,['single','compare'] as const,'control.comparison.mode'),layouts:readonly ComparisonLayout[]=mode==='single'?singleLayouts:pairLayouts;
+ const requested=choice(o.requestedLayout,layouts,'control.comparison.requestedLayout');
+ if(!Array.isArray(o.usableLayouts)||o.usableLayouts.length>layouts.length)throw new Error('control.comparison.usableLayouts: expected layout list');
+ const usable=o.usableLayouts.map(item=>choice(item,layouts,'control.comparison.usableLayouts'));if(new Set(usable).size!==usable.length)throw new Error('control.comparison.usableLayouts: duplicate layout');
+ const effective=o.effectiveLayout===null?null:choice(o.effectiveLayout,layouts,'control.comparison.effectiveLayout');
+ if(effective===null?usable.length>0:!usable.includes(effective))throw new Error('control.comparison.effectiveLayout: must be a usable layout, null only when none is usable');
+ if(usable.includes(requested)&&effective!==requested)throw new Error('control.comparison.effectiveLayout: a usable request is effective');
+ const r=controlObject(o.reasons,layouts,'control.comparison.reasons'),reasons:Partial<Record<ComparisonLayout,string>>={};
+ for(const layout of layouts){if(usable.includes(layout)){if(r[layout]!==undefined)throw new Error(`control.comparison.reasons.${layout}: usable layout has no refusal`);}else reasons[layout]=controlString(r[layout],`control.comparison.reasons.${layout}`,1024);}
+ const c=controlObject(o.candidate,['state','reason'],'control.comparison.candidate');if(c.state!=='unavailable'||c.reason!=='no producer handoff')throw new Error('control.comparison.candidate: no candidate source exists');
+ return {mode,requestedLayout:requested,effectiveLayout:effective,usableLayouts:usable,reasons,candidate:{state:'unavailable',reason:'no producer handoff'}};
+}
+export interface ControlInspection {
+ theme:'system'|'dark'|'light';layout:'auto';effectiveLayout:'row'|'column'|null;
+ cameras:{rig:ControlCamera;reference:ControlCamera;a?:ControlCamera;b?:ControlCamera};animation:string|null;time:number|null;
+ playing:boolean;loop:'idle'|'off';layers:ControlLayers;ready:boolean;seeking:boolean;
+ dirty:boolean;busy:boolean;feedbackEligible:boolean;view?:ControlView;comparison?:ControlComparison;part?:ControlPart|null;partGeneration?:number|null;
+ capabilities:{camera:boolean;referenceCamera:boolean;animation:boolean;time:boolean;playback:boolean;layers:ControlLayers};
+}
+export type ControlCommand=
+ |{type:'theme';value:'system'|'dark'|'light'}|{type:'layout';value:'auto'}
+ |{type:'camera';target:ControlCameraTarget;zoom:number;pan:{x:number;y:number}}
+ |{type:'fit';target:ControlCameraTarget}|{type:'camera-sync';value:boolean}|{type:'playback';value:'play'|'pause'}
+ |{type:'animation';name:string}|{type:'time';seconds:number}|({type:'layers'}&ControlLayers);
+export interface ControlRequest {schema:'rig-review-control-command/1';requestId:string;pageId:string;instanceKey:string;sourceHash:string;expectedRevision:number;command:ControlCommand}
+export interface ControlDelivery {commandId:string;request:ControlRequest}
+export type ControlOutcome='queued'|'dispatched'|'applied'|'rejected'|'failed'|'superseded'|'outcome-unknown';
+export interface ControlReceipt {commandId:string;requestId:string;pageId:string;status:ControlOutcome;error?:string;revision:number;inspection:ControlInspection|null}
+export function controlObject(v:unknown,keys:readonly string[],name:string):Record<string,unknown>{
+ if(!v||typeof v!=='object'||Array.isArray(v)||Object.getPrototypeOf(v)!==Object.prototype)throw new Error(`${name}: expected object`);
+ const o=v as Record<string,unknown>;for(const key of Object.keys(o))if(!keys.includes(key))throw new Error(`${name}.${key}: unknown field`);return o;
+}
+export function controlString(v:unknown,name:string,max=128):string{if(typeof v!=='string'||!v||v.length>max||/[\x00-\x1f]/.test(v))throw new Error(`${name}: expected nonempty text <= ${max}`);return v;}
+export function controlInteger(v:unknown,name:string):number{if(typeof v!=='number'||!Number.isSafeInteger(v)||v<0)throw new Error(`${name}: expected safe integer >= 0`);return v;}
+function num(v:unknown,name:string,min:number,max:number):number{if(typeof v!=='number'||!Number.isFinite(v)||v<min||v>max)throw new Error(`${name}: expected finite ${min}..${max}`);return v;}
+function bool(v:unknown,name:string):boolean{if(typeof v!=='boolean')throw new Error(`${name}: expected boolean`);return v;}
+function choice<T extends string>(v:unknown,values:readonly T[],name:string):T{if(typeof v!=='string'||!values.includes(v as T))throw new Error(`${name}: expected ${values.join(' | ')}`);return v as T;}
+function pan(v:unknown,limit=65536){const o=controlObject(v,['x','y'],'control.pan');return {x:num(o.x,'control.pan.x',-limit,limit),y:num(o.y,'control.pan.y',-limit,limit)};}
+/** Sync scales CSS displacement by pane size; observed pan is not a command input. */
+function camera(v:unknown):ControlCamera{const o=controlObject(v,['zoom','pan'],'control.camera');return {zoom:num(o.zoom,'control.camera.zoom',.25,8),pan:pan(o.pan,Number.MAX_SAFE_INTEGER)};}
+function layers(v:unknown):ControlLayers{const o=controlObject(v,['images','meshes','bones'],'control.layers');return {images:bool(o.images,'control.layers.images'),meshes:bool(o.meshes,'control.layers.meshes'),bones:bool(o.bones,'control.layers.bones')};}
+export function parseControlView(v:unknown):ControlView{
+ const o=controlObject(v,['schema','cameras','cameraSync','activeCamera'],'control.view');
+ if(o.schema!=='rig-review-view/1')throw new Error('control.view.schema: expected rig-review-view/1');
+ const c=controlObject(o.cameras,['rig','a','b','reference'],'control.view.cameras');
+ const numeric=(value:unknown,id:'rig'|'a'|'b'|'reference'):ControlNumericCamera|null=>{
+  if(value===null)return null;
+  const name=`control.view.cameras.${id}`,camera=controlObject(value,['space','center','zoom','viewport','visible'],name);
+  const space=id==='reference'?'image':'world';
+  if(camera.space!==space)throw new Error(`${name}.space: expected ${space}`);
+  const center=controlObject(camera.center,['x','y'],`${name}.center`),viewport=controlObject(camera.viewport,['width','height'],`${name}.viewport`),visible=controlObject(camera.visible,['x','y','width','height'],`${name}.visible`);
+  const coordinate=(value:unknown,field:string)=>num(value,`${name}.${field}`,-Number.MAX_SAFE_INTEGER,Number.MAX_SAFE_INTEGER);
+  const positive=(value:unknown,field:string,max:number)=>{const n=num(value,`${name}.${field}`,0,max);if(n===0)throw new Error(`${name}.${field}: expected positive dimension`);return n;};
+  return {space,center:{x:coordinate(center.x,'center.x'),y:coordinate(center.y,'center.y')},zoom:num(camera.zoom,`${name}.zoom`,.25,8),viewport:{width:positive(viewport.width,'viewport.width',65536),height:positive(viewport.height,'viewport.height',65536)},visible:{x:coordinate(visible.x,'visible.x'),y:coordinate(visible.y,'visible.y'),width:positive(visible.width,'visible.width',Number.MAX_SAFE_INTEGER),height:positive(visible.height,'visible.height',Number.MAX_SAFE_INTEGER)}};
+ };
+ return {schema:'rig-review-view/1',...(o.cameraSync===undefined?{}:{cameraSync:bool(o.cameraSync,'control.view.cameraSync')}),...(o.activeCamera===undefined?{}:{activeCamera:choice(o.activeCamera,['rig','a','b','reference'] as const,'control.view.activeCamera')}),cameras:{rig:numeric(c.rig,'rig'),a:numeric(c.a,'a'),b:numeric(c.b,'b'),reference:numeric(c.reference,'reference')}};
+}
+export function parseControlCommand(v:unknown):ControlCommand{
+ const base=controlObject(v,['type','value','target','zoom','pan','name','seconds','images','meshes','bones'],'control.command');
+ const type=choice(base.type,['theme','layout','camera','fit','camera-sync','playback','animation','time','layers'] as const,'control.command.type');
+ const keys={theme:['type','value'],layout:['type','value'],camera:['type','target','zoom','pan'],fit:['type','target'],'camera-sync':['type','value'],playback:['type','value'],animation:['type','name'],time:['type','seconds'],layers:['type','images','meshes','bones']}[type];controlObject(v,keys,'control.command');
+ if(type==='theme')return {type,value:choice(base.value,['system','dark','light'] as const,'control.theme')};
+ if(type==='layout')return {type,value:choice(base.value,['auto'] as const,'control.layout')};
+ if(type==='camera')return {type,target:choice(base.target,['rig','a','b','reference'] as const,'control.target'),zoom:num(base.zoom,'control.zoom',.25,8),pan:pan(base.pan)};
+ if(type==='fit')return {type,target:choice(base.target,['rig','a','b','reference'] as const,'control.target')};
+ if(type==='camera-sync')return {type,value:bool(base.value,'control.cameraSync')};
+ if(type==='playback')return {type,value:choice(base.value,['play','pause'] as const,'control.playback')};
+ if(type==='animation')return {type,name:controlString(base.name,'control.animation')};
+ if(type==='time')return {type,seconds:num(base.seconds,'control.seconds',0,Number.MAX_SAFE_INTEGER)};
+ return {type,images:bool(base.images,'control.layers.images'),meshes:bool(base.meshes,'control.layers.meshes'),bones:bool(base.bones,'control.layers.bones')};
+}
+export function parseControlInspection(v:unknown):ControlInspection{
+ const o=controlObject(v,['theme','layout','effectiveLayout','cameras','animation','time','playing','loop','layers','ready','seeking','dirty','busy','feedbackEligible','capabilities','view','part','partGeneration','comparison'],'control.inspection');
+ const c=controlObject(o.cameras,['rig','reference','a','b'],'control.cameras'),a=controlObject(o.capabilities,['camera','referenceCamera','animation','time','playback','layers'],'control.capabilities');
+ return {...(o.view===undefined?{}:{view:parseControlView(o.view)}),...(o.comparison===undefined?{}:{comparison:parseControlComparison(o.comparison)}),...(o.part===undefined?{}:{part:parseControlPart(o.part)}),...(o.partGeneration===undefined?{}:{partGeneration:o.partGeneration===null?null:controlInteger(o.partGeneration,'control.partGeneration')}),theme:choice(o.theme,['system','dark','light'] as const,'control.theme'),layout:choice(o.layout,['auto'] as const,'control.layout'),effectiveLayout:o.effectiveLayout===null?null:choice(o.effectiveLayout,['row','column'] as const,'control.effectiveLayout'),cameras:{rig:camera(c.rig),reference:camera(c.reference),...(c.a===undefined?{}:{a:camera(c.a)}),...(c.b===undefined?{}:{b:camera(c.b)})},animation:o.animation===null?null:controlString(o.animation,'control.animation'),time:o.time===null?null:num(o.time,'control.time',0,Number.MAX_SAFE_INTEGER),playing:bool(o.playing,'control.playing'),loop:choice(o.loop,['idle','off'] as const,'control.loop'),layers:layers(o.layers),ready:bool(o.ready,'control.ready'),seeking:bool(o.seeking,'control.seeking'),dirty:bool(o.dirty,'control.dirty'),busy:bool(o.busy,'control.busy'),feedbackEligible:bool(o.feedbackEligible,'control.feedbackEligible'),capabilities:{camera:bool(a.camera,'control.capabilities.camera'),referenceCamera:bool(a.referenceCamera,'control.capabilities.referenceCamera'),animation:bool(a.animation,'control.capabilities.animation'),time:bool(a.time,'control.capabilities.time'),playback:bool(a.playback,'control.capabilities.playback'),layers:layers(a.layers)}};
+}
+export function parseControlRequest(v:unknown):ControlRequest{
+ const o=controlObject(v,['schema','requestId','pageId','instanceKey','sourceHash','expectedRevision','command'],'control.request');
+ if(o.schema!=='rig-review-control-command/1')throw new Error('control.schema: expected rig-review-control-command/1');
+ for(const field of ['instanceKey','sourceHash'])if(typeof o[field]!=='string'||!/^[a-f0-9]{64}$/.test(o[field] as string))throw new Error(`control.${field}: expected SHA-256`);
+ return {schema:o.schema,requestId:controlString(o.requestId,'control.requestId'),pageId:controlString(o.pageId,'control.pageId'),instanceKey:o.instanceKey as string,sourceHash:o.sourceHash as string,expectedRevision:controlInteger(o.expectedRevision,'control.expectedRevision'),command:parseControlCommand(o.command)};
+}
+/** Shared preflight; adapters additionally validate actual names/domains before mutation. */
+export function preflightControl(command:ControlCommand,state:ControlInspection,mode:ControlMode):void{
+ if(state.busy)throw new Error('CONTROL_BUSY: inspection update in progress');
+ if(['animation','time','playback'].includes(command.type)&&state.dirty)throw new Error('CONTROL_UNSUBMITTED_CHANGES: preserve the current feedback draft');
+ if(['animation','time','playback'].includes(command.type)&&(!state.ready||state.seeking))throw new Error('CONTROL_NOT_READY: inspection is not settled');
+ const cap=state.capabilities;
+ if(command.type==='animation'&&mode==='compare'&&command.name!==state.animation)throw new Error('CONTROL_REBIND_REQUIRED: comparison animation is source-bound');
+ if(command.type==='animation'&&!cap.animation)throw new Error('CONTROL_UNAVAILABLE: animation');
+ if(command.type==='time'&&!cap.time)throw new Error('CONTROL_UNAVAILABLE: time');
+ if(command.type==='playback'&&!cap.playback)throw new Error('CONTROL_UNAVAILABLE: playback');
+ if(command.type==='camera-sync'&&state.view?.cameraSync===undefined)throw new Error('CONTROL_UNAVAILABLE: camera sync');
+ if(command.type==='camera'||command.type==='fit'){
+  const target=command.target;
+  if((target==='a'||target==='b')&&(mode!=='compare'||!cap.camera||!state.cameras[target]&&!state.view?.cameras[target]))throw new Error(`CONTROL_UNAVAILABLE: ${target} camera`);
+  if((target==='rig'&&!cap.camera)||(target==='reference'&&!cap.referenceCamera))throw new Error(`CONTROL_UNAVAILABLE: ${target} camera`);
+ }
+ if(command.type==='layers')for(const name of ['images','meshes','bones'] as const)if(command[name]!==state.layers[name]&&!cap.layers[name])throw new Error(`CONTROL_UNAVAILABLE: ${name}`);
+}