@rig-c/review 0.14.0 → 0.15.0

package/web/main.ts

@@ -1,9 +1,11 @@
+import {timeOnlyBasis,feedbackTimingLabel,requireFeedbackFrames,isTimeOnlyFeedback} from '../src/stage-comment.ts';
+import {bindStageComments,type CommentPose} from './stage-comments.ts';
 import {discoverTurnDials,TurnState} from '../src/turn-pad.ts';
 import {bindTurnPad,type TurnPad} from './turn-pad.ts';
 import {PartExplorer,loadPartModel,partBounds} from './part-selection.ts';
 import {AnimationInspectionPanel} from './animation-inspection.ts';
 import {PartThumbnails,pageRegionTable} from './part-thumbnails.ts';
-import { loadModel, RigPlayer, type BoneAdjust, type ModelAssets, type PoseBounds } from '@rig-c/play';
+import { CanvasRenderer, loadModel, RigPlayer, type BoneAdjust, type ModelAssets, type PoseBounds } from '@rig-c/play';
 import {cameraFrame,cameraSignature,cameraFromSignature,assertCameraView,boundsFitSignature,dragSignature,zoomSignature,type CameraFrame,type CameraSignature} from './camera-view.ts';
 import {rendererStatus} from './renderer-status.ts';
 import {bindAppearance,bindPan,bindStageLayout,syncStageLayout,bindInspectorTabs,idleAvailable,initialIdleAnimation,automaticIdlePreview,bindLayerShortcuts,describeLayerToggles,type ViewPoint} from './view-controls.ts';
@@ -33,7 +35,7 @@ import {connectControl} from './control.ts';
 import {pageInstanceAccess,readOnlyReason} from './instance-access.ts';
 import {controlComparison,type ControlCommand,type ControlInspection,type ControlView} from '../src/control.ts';
 import {singleEligibility,videoReferenceAt,type InputState,type SingleLayout} from '../src/comparison-eligibility.ts';
-import {connectInspectionPersistence,serializableView,numericCamera,restoredZoom,restoreTransaction,captureInputs,restoreInputs,type InspectionBookmark,type InspectionBinding,type PersistenceConnection} from './inspection-persistence.ts';
+import {parseBookmark,connectInspectionPersistence,serializableView,numericCamera,restoredZoom,restoreTransaction,captureInputs,restoreInputs,type InspectionBookmark,type InspectionBinding,type PersistenceConnection} from './inspection-persistence.ts';
 import {initialPlayerAnimation,keptAnimation} from '../src/animation-selection.ts';
 import {initialReviewSelection} from '../src/open-selection.ts';
 import type {ReferenceBinding} from '../src/reference.ts';
@@ -62,7 +64,7 @@ import {assertRigFieldOps,RIG_FIELDS_READOUT_BARS,TURN_BONE} from '../src/rig-fi
 import {IDLE_READOUT_BARS,type LocalChannel} from '../src/idle-tracks.ts';
 import type {PatchOp} from '../src/config-patch.ts';
 
-interface ReviewResponse { initialAnimation?:string|null; manifest: ReviewManifest; referenceBinding?:ReferenceBinding; explicitReference?:{id:string;name:string;sha256:string;url:string}; sourceHash: string; reviewedSource: ReviewedSource; report: ReportSeeds | null; feedbackCatalog: FeedbackCatalog; assetsBase: string; capabilities: { playback: boolean; modeling: false; motion: false; feedback: boolean; audio: boolean } }
+interface ReviewResponse { referenceHashes?:Record<string,string>; initialAnimation?:string|null; manifest: ReviewManifest; referenceBinding?:ReferenceBinding; explicitReference?:{id:string;name:string;sha256:string;url:string}; sourceHash: string; reviewedSource: ReviewedSource; report: ReportSeeds | null; feedbackCatalog: FeedbackCatalog; assetsBase: string; capabilities: { playback: boolean; modeling: false; motion: false; feedback: boolean; audio: boolean } }
 interface PoseReference { schema: 'rig-review-pose/1'; coordinateSystem: 'image-pixels-y-down'; width: number; height: number; joints: { id: string; x: number; y: number; parent?: string }[] }
 interface SequenceJoint { state: 'observed' | 'occluded' | 'missing' | 'inferred'; at?: [number, number]; score?: number }
 interface PoseSequence { spec: 'rig-pose-sequence/1'; space: { units: 'picture-px'; origin: 'top-left'; y: 'down' }; width: number; height: number; source?: string; frames: { t: number; people: { id: string; joints: Record<string, SequenceJoint> }[] }[]; camera?: { s: number; tx: number; ty: number; inliers: number }[]; cameraSource?: unknown }
@@ -99,6 +101,7 @@ let lastFrame = 0;
 type CameraTarget='rig'|'reference';
 let cameraSync=true,activeCamera:CameraTarget='rig',cameraRestoring=false,cameraLayout='';
 const cameraFrames:Partial<Record<CameraTarget,CameraFrame>>={};
+let comments:ReturnType<typeof bindStageComments>|null=null;
 let view: 'compare' | 'reference' | 'rig' = 'compare';
 // Requested layout persists in the source-bound draft; the effective one follows actual load events only.
 let rigInput:InputState={state:'pending'},referenceInput:InputState={state:'absent'},effectiveView:SingleLayout|null=null;
@@ -696,18 +699,19 @@ function applyAxis(): void {
 }
 
 function renderProposals(): void {
+  comments?.refresh();
   const area = el('proposal-list'); area.replaceChildren();
   const warnings = el('feedback-warnings'); warnings.hidden = session.feedbackWarnings.length === 0;
   const unchecked = session.feedback.map(f => appliedCheckRefusal((f.context as Record<string, unknown> | undefined)?.applied)).find(Boolean) ?? null;
   el('feedback-applied-check').hidden = !unchecked; text('feedback-applied-check', unchecked ? `${unchecked} · Submit refuses this review; delete the entry written on that build or Apply a build that passes check.` : '');
   warnings.textContent = session.feedbackWarnings.length ? `${session.feedbackWarnings.length} validation warnings in existing feedback · original records are preserved. Review the marked entries, delete them and add valid replacements before submitting. The saved session that rig-review feedback exports keeps both the original records and warnings.` : '';
   for (const feedback of session.feedback) {
-    const item = document.createElement('div'); item.className = 'proposal-item'; const title = document.createElement('strong'); title.textContent = `${feedback.category} · ${feedback.target.kind}:${feedback.target.name} · F${feedback.frameStart}–${feedback.frameEnd}`; const description = document.createElement('span'); description.textContent = feedback.summary;
+    const item = document.createElement('div'); item.className = 'proposal-item'; const title = document.createElement('strong'); title.textContent = `${feedback.category} · ${feedback.target.kind}:${feedback.target.name} · ${feedbackTimingLabel(feedback)}`; const description = document.createElement('span'); description.textContent = feedback.summary;
     item.append(title, description);
     for (const warning of session.feedbackWarnings.filter(value => value.id === feedback.id)) { const note = document.createElement('p'); note.className = 'hint'; note.textContent = `Validation warning · ${warning.error}`; item.append(note); }
     const details = document.createElement('details'), summary = document.createElement('summary'), source = document.createElement('pre'); summary.textContent = 'Saved feedback and inspection context'; source.textContent = JSON.stringify(feedback, null, 2); details.append(summary, source);
     const remove = document.createElement('button'); remove.type = 'button'; remove.textContent = 'Delete'; remove.onclick = () => { session.feedback = session.feedback.filter(item => item.id !== feedback.id); session.feedbackWarnings = session.feedbackWarnings.filter(warning => warning.id !== feedback.id); markDirty(); renderProposals(); };
-    item.append(details, remove); area.append(item);
+    item.append(details);if((feedback.context as any)?.comment?.schema!=='rig-review-comment/1'||!submittedBaseline?.feedback.some(f=>f.id===feedback.id))item.append(remove); area.append(item);
   }
   updateSavedState();
 }
@@ -753,7 +757,7 @@ async function exportStrip(): Promise<void> {
       for (const feedback of session.feedback) {
         const context = feedback.context;
         if (!context || typeof context !== 'object' || Array.isArray(context) || context.animation !== selectedAnimation) throw new Error(`Feedback ${feedback.id}: Its animation is missing or differs from the selected animation. Batch export supports ranges from the same animation only.`);
-        intervals.push({ id: feedback.id, feedbackId: feedback.id, basis: 'single', frameStart: feedback.frameStart, frameEnd: feedback.frameEnd });
+        intervals.push({ id: feedback.id, feedbackId: feedback.id, basis: 'single', ...requireFeedbackFrames(feedback) });
       }
     } else {
       const start = input('feedback-start').value.trim(), end = input('feedback-end').value.trim();
@@ -889,7 +893,7 @@ function bind(): void {
     saving = true; updateSavedState(); const savedPayload = JSON.stringify(session);
     try { const saved = await api<ReviewSession>('/api/session', { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: savedPayload });
       if (JSON.stringify(session) === savedPayload) { session = saved; dirty = false; } else session.updatedAt = saved.updatedAt;
-      await persistence?.submitted(saved);renderProvenance();
+      submittedBaseline=structuredClone(saved);comments?.refresh();await persistence?.submitted(saved);renderProvenance();renderProposals();
       message(dirty ? 'Changes were made during submission. Submit again.' : 'Submitted the selected review status, feedback and source provenance.');
     } catch (error) { message(`Submission failed: ${errorText(error)}`, true); } finally { saving = false; updateSavedState(); }
   };
@@ -942,7 +946,7 @@ function bind(): void {
   requirementsPanel=bindRequirementsPanel({check:runRequirements,seek:seekReading,animation:()=>animation,slot:()=>parts?.value()?.slot??null,hash:sha256Hex});
   const tickResize=new ResizeObserver(()=>renderReadingTicks());tickResize.observe(el('transport'));viewDisposers.push(()=>tickResize.disconnect());
   viewDisposers.push(bindStageLayout(el('stage-layout'),fitCamera));
-  for(const target of ['rig','reference'] as const)viewDisposers.push(bindPan(el(target+'-viewport'),(dx,dy)=>cameraAction(()=>panCamera(target,dx,dy))));
+  for(const target of ['rig','reference'] as const)viewDisposers.push(bindPan(el(target+'-viewport'),(dx,dy)=>cameraAction(()=>panCamera(target,dx,dy)),()=>!comments?.active()));
   for(const [id,key] of [['layer-images','images'],['layer-mesh','mesh'],['layer-bones','bones']] as const)input(id).onchange=()=>{layers[key]=input(id).checked;redrawOverlay(false);};
   viewDisposers.push(bindLayerShortcuts(document));describeLayerToggles(document,el('layer-state').textContent??'');
   input('idle-repeat').onchange=()=>{renderIdle();if(canRepeatIdle())void playPreview();};
@@ -952,7 +956,7 @@ function bind(): void {
   document.addEventListener('visibilitychange',()=>{if(document.hidden){const resume=playing;pause();suspendedPreview=resume;}else if(suspendedPreview){suspendedPreview=false;void playPreview();}});
   const resize = new ResizeObserver(fitCamera); resize.observe(el('rig-viewport')); resize.observe(el('reference-viewport'));
   window.addEventListener('beforeunload', event => { if (dirty) { event.preventDefault(); event.returnValue = ''; } });
-  window.addEventListener('pagehide', () => { persistence?.dispose();turnPad?.dispose();workspace?.dispose();pause();controlDispose?.();appearance?.dispose();viewDisposers.forEach(dispose=>dispose());overlays?.dispose(); player?.dispose(); assets?.dispose(); resize.disconnect(); });
+  window.addEventListener('pagehide', () => { comments?.dispose();persistence?.dispose();turnPad?.dispose();workspace?.dispose();pause();controlDispose?.();appearance?.dispose();viewDisposers.forEach(dispose=>dispose());overlays?.dispose(); player?.dispose(); assets?.dispose(); resize.disconnect(); });
 }
 
 async function start(): Promise<void> {
@@ -982,13 +986,13 @@ async function start(): Promise<void> {
     else if (readOnly) message(readOnly, true);
     else message(data.manifest.model ? 'Record review status and structured feedback while preserving sources. Motion is read only.' : 'No rig supplied. Review the available references and checkpoints.');
     requestAnimationFrame(tick);
-    const restored=await setupPersistence();await loadRebuildStatus();void loadRequirements();renderChest();restoreEnvironment();physicsPanel?.restore();bonesPanel?.restore();cutsPanel?.restore();clothPanel?.restore();idlePanel?.restore();rigFieldsPanel?.restore();meshPanel?.restore();void refreshDensityStrip();renderIdle();if(!restored&&canRepeatIdle()&&automaticIdlePreview(assets?.animations.map(item=>item.name)??[],animation,first,!!requestedId))void playPreview();
+    const restored=await setupPersistence();setupComments();await loadRebuildStatus();void loadRequirements();renderChest();restoreEnvironment();physicsPanel?.restore();bonesPanel?.restore();cutsPanel?.restore();clothPanel?.restore();idlePanel?.restore();rigFieldsPanel?.restore();meshPanel?.restore();void refreshDensityStrip();renderIdle();if(!restored&&canRepeatIdle()&&automaticIdlePreview(assets?.animations.map(item=>item.name)??[],animation,first,!!requestedId))void playPreview();
     // Only an instance that serves agent control is asked for its config: a plain open has no control endpoint (#164).
     if(!readOnly&&writes.control!==false)controlDispose=connectControl({sourceHash:data.sourceHash,mode:'single',route:access.route,headers:()=>access.headers(),observe:controlState,apply:applyControl,onStatus:value=>text('control-state',value)});
   } catch (error) { message(`Could not open review package: ${errorText(error)}`, true); text('dirty', 'Load failed'); }
 }
 /** `feedback` is the review dialog, not an Inspector section: a user action opens it; a restored older bookmark that saved it selects nothing. */
-function showInspector(name:string,reveal=true):void {if(name==='feedback'){if(reveal)openReview();return;}if(reveal)workspace?.revealInspector();document.querySelector<HTMLButtonElement>(`[data-inspector="${name}"]`)?.click();}
+function showInspector(name:string,reveal=true):void {if(name==='feedback'){if(reveal)openReview();return;}if(reveal)workspace?.revealInspector();const selector=document.querySelector<HTMLButtonElement>(`[data-inspector="${name}"]`);if(selector&&selector.getAttribute('aria-pressed')!=='true'&&selector.getAttribute('aria-selected')!=='true')selector.click();}
 function bindInspector():void {bindInspectorTabs(()=>{workspace?.afterTab();fitCamera();},()=>workspace?.beforeTab());}
 /** Opening the review pauses playback, as selecting Feedback did. Its inputs stay in the document whether or not it is open, so the draft keeps them. */
 function openReview():void {const dialog=el<HTMLDialogElement>('review-dialog');for(const drawer of document.querySelectorAll<HTMLDialogElement>('dialog.workspace-drawer[open]'))drawer.close();pause();if(!dialog.open)dialog.showModal();}
@@ -1019,7 +1023,7 @@ async function playPreview():Promise<void> {
  if(video&&referenceInput.state==='loaded'){try{await video.play();}catch(error){pause();message(`Playback is paused: ${errorText(error)}. Use Play to retry.`,true);return;}}
  if(intent!==playbackIntent||!desiredPlay){if(!desiredPlay)video?.pause();return;}playing=true;lastFrame=0;player?.resume();button('play').textContent='Ⅱ';button('play').setAttribute('aria-label','Pause');
 }
-function localDraft():boolean{return dirty||!!input('feedback-summary').value.trim()||!!input('feedback-start').value.trim()||!!input('feedback-end').value.trim()||!!select('feedback-category').value||!!input('feedback-target-name').value.trim()&&input('feedback-target-name').value!==data.manifest.id;}
+function localDraft():boolean{return !!comments?.draft()||dirty||!!input('feedback-summary').value.trim()||!!input('feedback-start').value.trim()||!!input('feedback-end').value.trim()||!!select('feedback-category').value||!!input('feedback-target-name').value.trim()&&input('feedback-target-name').value!==data.manifest.id;}
 function controlState():ControlInspection {
  const box=assets?.stage??player?.bounds(),center=box?{x:box.x+box.width/2,y:box.y+box.height/2}:null;
  return {part:parts?.value()??null,partGeneration:parts?.observation()?.generation??null,view:numericView(),theme:appearance?.get()??'system',layout:'auto',effectiveLayout:el('stage-layout').dataset.orientation==='vertical'?'column':'row',cameras:{rig:{zoom:player?zoom:1,pan:{x:center&&cameraCenter?(center.x-cameraCenter.x)*rigScale:0,y:center&&cameraCenter?(cameraCenter.y-center.y)*rigScale:0}},reference:{zoom:referenceSize?referenceZoom:1,pan:{x:referenceSize&&referenceCenter?(referenceSize.width/2-referenceCenter.x)*referenceScale:0,y:referenceSize&&referenceCenter?(referenceSize.height/2-referenceCenter.y)*referenceScale:0}}},animation:animation||null,time:player?.time??time,playing,loop:canRepeatIdle()?'idle':'off',layers:{images:!!player&&layers.images,meshes:!!player&&layers.mesh,bones:!!player&&layers.bones},ready:!!data,seeking:seekingControl||!!video?.seeking||!!persistence?.restoring(),dirty:localDraft(),busy:saving||stripBusy||!!persistence?.restoring(),feedbackEligible:!persistence?.restoring(),comparison:controlComparison(layoutEligibility()),capabilities:{camera:!!player,referenceCamera:!!referenceSize,animation:!!player,time:duration>0,playback:duration>0,layers:{images:!!player,meshes:!!player,bones:!!player}}};
@@ -1043,7 +1047,7 @@ async function applyControl(command:ControlCommand,signal:AbortSignal):Promise<v
   pause();seekingControl=true;try{await inspectControlTime(command.seconds,signal);}finally{seekingControl=false;}
  }
 }
-async function inspectControlTime(target:number,signal:AbortSignal):Promise<void> {
+async function inspectControlTime(target:number,signal:AbortSignal,preserveSeconds=false):Promise<void> {
  if(signal.aborted)throw new Error('CONTROL_SUPERSEDED');
  // #191: a control seek is a clip move like the transport's: a seek to 0 restarts the wind clock while the exported world is in use.
  clipMoved({kind:'seek',to:target});
@@ -1054,7 +1058,8 @@ async function inspectControlTime(target:number,signal:AbortSignal):Promise<void
  const commit=(actual:number)=>{
   if(signal.aborted||media!==video)throw new Error('CONTROL_SUPERSEDED');
   if(!Number.isFinite(actual)||actual<0||actual>duration)throw new Error('CONTROL_TIME_OUTSIDE_DOMAIN');
-  if(player){player.seek(actual);drawRig(()=>player!.draw());}time=actual;
+  const seconds=preserveSeconds?target:actual;
+  if(player){player.seek(seconds);drawRig(()=>player!.draw());}time=seconds;
   controlledVideoSample={media,position:media.currentTime,time:actual};if(axisInspection&&duration>0){const axis=data.manifest.axes.find(item=>item.id===select('axis-select').value&&item.animation===animation);if(axis){const value=axis.min+actual/duration*(axis.max-axis.min);input('axis-value').value=String(value);text('axis-value-label',value.toFixed(3));}}renderSequenceFrame();renderTransport();
  };
  try{const actual=await decodedControlTime(media,target,signal);if(signal.aborted||media!==video)throw new Error('CONTROL_SUPERSEDED');commit(actual);if(Math.abs(actual-target)>1e-6)message(`Reference decoded ${actual.toFixed(4)} s · requested ${target.toFixed(4)} s. The rig and saved view use the decoded timestamp.`);}
@@ -1088,8 +1093,8 @@ function numericView():ControlView {
 function renderNumericView():void {const node=document.getElementById('view-coordinates');if(node)node.textContent=JSON.stringify(numericView(),null,2);}
 function inspectionBinding():InspectionBinding{return {mode:'single',sourceHash:data.sourceHash,rigs:[data.reviewedSource.rig?.sha256??null]};}
 function inspectionBookmark():InspectionBookmark {return {schema:'rig-review-inspection/1',binding:inspectionBinding(),animation:animation||null,time:player?.time??time,theme:appearance?.get()??'system',layers:{images:layers.images,meshes:layers.mesh,bones:layers.bones},view:numericView(),selection:{...(turnPad?{turn:turnPad.snapshot()}:{}),part:parts?.value()??null,view,checkpoint:checkpoint?.id??null,reference:select('reference-select').value||null,person:selectedPerson||null,inspector:selectedInspector()??'view',partSet:select('part-set').disabled?null:select('part-set').value,axis:axisInspection?{id:select('axis-select').value,value:Number(input('axis-value').value)}:null}};}
-async function restoreInspection(bookmark:InspectionBookmark,signal:AbortSignal):Promise<void> {
- await restoreTransaction(()=>prepareInspection(bookmark,signal),()=>({bookmark:inspectionBookmark(),inputs:captureInputs()}),()=>applyInspection(bookmark,signal),async previous=>{await applyInspection(previous.bookmark,new AbortController().signal);restoreInputs(previous.inputs);renderFeedbackRange();});
+async function restoreInspection(bookmark:InspectionBookmark,signal:AbortSignal,preserveSeconds=false):Promise<void> {
+ await restoreTransaction(()=>prepareInspection(bookmark,signal),()=>({bookmark:inspectionBookmark(),inputs:captureInputs()}),()=>applyInspection(bookmark,signal,preserveSeconds),async previous=>{await applyInspection(previous.bookmark,new AbortController().signal);restoreInputs(previous.inputs);renderFeedbackRange();});
 }
 /** Read the SELECTED reference without replacing the currently inspected DOM/player. */
 async function inspectionReferenceInfo(id:string|null,signal:AbortSignal):Promise<{width:number;height:number;duration:number|null;people:string[]}> {
@@ -1123,7 +1128,7 @@ async function prepareInspection(bookmark:InspectionBookmark,signal:AbortSignal)
  // Range fitting belongs to the transactional apply after that layout is measured.
  if(signal.aborted)throw new Error('Inspection restore superseded');
 }
-async function applyInspection(bookmark:InspectionBookmark,signal:AbortSignal):Promise<void> {
+async function applyInspection(bookmark:InspectionBookmark,signal:AbortSignal,preserveSeconds=false):Promise<void> {
  cameraRestoring=true;try{
  const selection=bookmark.selection;
  if(turnPad){if(selection.turn)turnPad.restore(selection.turn);else{turnPad.state.reset();turnPad.restore(turnPad.snapshot());}}
@@ -1134,12 +1139,15 @@ async function applyInspection(bookmark:InspectionBookmark,signal:AbortSignal):P
  if(bookmark.animation&&player)chooseAnimation(bookmark.animation);
  if(selection.axis){select('axis-select').value=selection.axis.id;chooseAxis();input('axis-value').value=String(selection.axis.value);applyAxis();}
  if(selection.partSet!==undefined&&player){if(selection.partSet||player.sets().length)player.setSet(selection.partSet||null);select('part-set').value=selection.partSet??'';}
- if(bookmark.time!==null){if(video&&video.readyState<1)await waitReferenceMetadata(video,signal);await inspectControlTime(bookmark.time,signal);}
+ if(bookmark.time!==null){if(video&&video.readyState<1)await waitReferenceMetadata(video,signal);await inspectControlTime(bookmark.time,signal,preserveSeconds);}
  if(selection.person!==undefined){selectedPerson=selection.person??'';select('person-select').value=selectedPerson;lastPoseFrame=-1;renderSequenceFrame();}
  if(selection.view)setView(selection.view);
  appearance?.set(bookmark.theme);
  Object.assign(layers,{images:bookmark.layers.images,mesh:bookmark.layers.meshes,bones:bookmark.layers.bones});input('layer-images').checked=layers.images;input('layer-mesh').checked=layers.mesh;input('layer-bones').checked=layers.bones;
- if(selection.inspector)showInspector(selection.inspector,false);syncStageLayout(el('stage-layout'));fitCamera();
+ if(selection.inspector)showInspector(selection.inspector,false);syncStageLayout(el('stage-layout'));
+ // Mode changes schedule workspace layout and resize observers. Settle them
+ // while restoration is held, before measuring/applying the saved pane camera.
+ await new Promise<void>(resolve=>requestAnimationFrame(()=>requestAnimationFrame(()=>resolve())));if(signal.aborted)throw new Error('Inspection restore superseded');fitCamera();
  const camera=bookmark.view.cameras.rig,ref=bookmark.view.cameras.reference,rigViewport=el('rig-viewport'),referenceViewport=el('reference-viewport');
  const nextZoom=camera&&player&&rigViewport.clientWidth&&rigViewport.clientHeight?restoredZoom(camera,rigScale/zoom,rigViewport.clientWidth,rigViewport.clientHeight):camera?.zoom??null;
  const nextReferenceZoom=ref&&referenceSize&&referenceViewport.clientWidth&&referenceViewport.clientHeight?restoredZoom(ref,referenceScale/referenceZoom,referenceViewport.clientWidth,referenceViewport.clientHeight):ref?.zoom??null;
@@ -1151,7 +1159,7 @@ async function applyInspection(bookmark:InspectionBookmark,signal:AbortSignal):P
 }
 async function waitReferenceMetadata(media:HTMLVideoElement,signal:AbortSignal):Promise<void> {if(media.readyState>=1)return;await new Promise<void>((resolve,reject)=>{const clean=()=>{clearTimeout(timer);media.removeEventListener('loadedmetadata',ready);media.removeEventListener('error',fail);signal.removeEventListener('abort',fail);};const ready=()=>{clean();resolve();},fail=()=>{clean();reject(new Error('Saved reference metadata unavailable'));};const timer=setTimeout(fail,10000);media.addEventListener('loadedmetadata',ready,{once:true});media.addEventListener('error',fail,{once:true});signal.addEventListener('abort',fail,{once:true});});}
 async function setupPersistence():Promise<boolean> {
- persistence=await connectInspectionPersistence({scope:'single:'+data.manifest.id+':'+data.sourceHash,binding:inspectionBinding(),baseline:submittedBaseline!,session:()=>session,reviewDirty:()=>dirty,restoreSession:(value,isDirty)=>{session=value;dirty=isDirty;select('review-status').value=session.status;renderProposals();renderCheckpoint();renderCheckpoints();updateSavedState();},bookmark:inspectionBookmark,restoreBookmark:restoreInspection,
+ persistence=await connectInspectionPersistence({scope:'single:'+data.manifest.id+':'+data.sourceHash,binding:inspectionBinding(),baseline:submittedBaseline!,session:()=>session,reviewDirty:()=>dirty,restoreSession:(value,isDirty)=>{session=value;dirty=isDirty;select('review-status').value=session.status;renderProposals();renderCheckpoint();renderCheckpoints();updateSavedState();},bookmark:inspectionBookmark,restoreBookmark:(b,s)=>restoreInspection(b,s,session.feedback.some(f=>isTimeOnlyFeedback(f)&&JSON.stringify((f.context as any).comment.bookmark)===JSON.stringify(b))),
  ui:()=>({inspectorScroll:workspace?.scroll()??'{}',...(inspectorBlocks?activeBlocksUI(inspectorBlocks.state()):{}),reportCategory:select('report-category').value,reportPage,reportEvent:selectedReportEvent?.id??null,reportTime:selectedReportTime??null,reportTarget:selectedReportTarget??null}),restoreUI:value=>{if(typeof value.reportCategory==='string'&&[...select('report-category').options].some(o=>o.value===value.reportCategory))select('report-category').value=value.reportCategory;if(typeof value.reportPage==='number'&&Number.isSafeInteger(value.reportPage)&&value.reportPage>=0)reportPage=value.reportPage;selectedReportEvent=typeof value.reportEvent==='string'?data.report?.categories.flatMap(c=>c.events).find(e=>e.id===value.reportEvent)??null:null;selectedReportTime=typeof value.reportTime==='number'?value.reportTime:undefined;selectedReportTarget=typeof value.reportTarget==='number'?value.reportTarget:undefined;renderReportEvents();renderReportSelection();workspace?.restoreScroll(value.inspectorScroll);inspectorBlocks?.restore(restoreActiveBlocksUI(value));},afterInputs:()=>{const target=input('feedback-target-name').value;renderFeedbackTargets(true);if(select('feedback-target-kind').value!=='rig')input('feedback-target-name').value=target;renderFeedbackRange();text('audio-volume-label',`${Math.round(Number(input('audio-volume').value)*100)}%`);},onConflict:value=>{draftConflict=value;updateSavedState();},onStatus:value=>{text('draft-state',value);el('draft-state').title=value;text('review-draft-state',value);}});
  return persistence.restored;
 }
@@ -2109,3 +2117,28 @@ async function meshFolds():Promise<string[]> {
  return lines;
 }
 void start();
+
+
+/** Only live, unrecorded authoring effects block capture; unsent form ops alone do not. */
+function commentCaptureRefusal():string|null {
+ if(appliedOnStage)return 'COMMENT_APPLIED_BUILD_UNSUPPORTED: return to the inspected source before commenting on this applied scratch build';
+ if(rebuildBusy)return 'COMMENT_SOURCE_BUSY: wait for the rebuild or candidate model replacement before commenting';
+ const preview=idleAdjust?'Idle tracks':dialAdjust?'Rig fields turn dial':physicsPreview.read().length?'Physics live overrides':stripPending?'Density strip candidate':
+  meshEditor?.overlay()?'Edit Mesh':bonesPanel?.overlay()?'Bones anchors':cutsPanel&&(cutsPanel.overlayRegions().length||cutsPanel.overlayMarkers().length)?'Cuts/patches/joints':
+  clothPanel?.overlayRegions().length?'Cloth links':meshPanel&&(meshPanel.overlayRegions().length||meshPanel.overlayCircles().length)?'Mesh regions':
+  chestRegions().length||chestCircles().length||chestMarkers().length?'Chest regions/landmarks':rigFieldsPanel?.handles().length?'Rig fields stage handles':
+  (()=>{const handles=document.getElementById('idle-handles');return handles&&!handles.hidden&&handles.childElementCount>0;})()?'Idle tracks stage handles':null;
+ return preview?`COMMENT_UNAPPLIED_PREVIEW: ${preview} is active; leave or disable that preview before commenting (nothing is cleared or applied automatically)`:null;
+}
+function setupComments():void {
+ comments=bindStageComments({toolbar:el('stage-comment').parentElement!,viewports:{rig:el('rig-viewport'),reference:el('reference-viewport')},
+  pose:view=>{
+   if(view!=='rig'&&view!=='reference')return null;const workspaceMode=document.querySelector<HTMLElement>('[data-mode][aria-pressed="true"]')?.dataset.mode;if(workspaceMode!=='rig'&&workspaceMode!=='playback')return null;const camera=numericView().cameras[view],pane=el(view+'-viewport');if(!camera||pane.clientWidth<=0||pane.clientHeight<=0)return null;
+   const renderer=player?.renderer;const current=player?.time??time,index=frameAtTime(activeFrameClock(),current),referenceId=view==='reference'?select('reference-select').value||null:null,referenceHash=referenceId?data.referenceHashes?.[referenceId]??(data.explicitReference?.id===referenceId?data.explicitReference.sha256:null):null;
+   return {mode:workspaceMode==='playback'?'animate':'setup',capture:{pane,root:view==='rig'?el('rig-root'):undefined,images:view==='reference'||layers.images,canvas:view==='rig'&&renderer instanceof CanvasRenderer?renderer.canvas:undefined,backend:renderer instanceof CanvasRenderer?renderer.backendActive:renderer?.meshBackendActive??'canvas2d'},camera,frame:index===null?null:{index,basis:'producer'},...(index===null?{timeBasis:timeOnlyBasis}:{}),time:current,animation:animation||null,turn:turnPad?.snapshot()??null,sourceHash:data.sourceHash,modelHash:view==='reference'?null:stageModelHash,referenceHash,referenceId,rig:data.manifest.id,...(view==='reference'?{media:video??el('reference-content').querySelector('img')??undefined}:{posed:parts?.frame('single'),assets:assets??undefined})} as CommentPose;
+  },
+  pause:async()=>{const running=playing||!!video&&!video.paused;pause();if(running&&video&&video.readyState>=1){seekingControl=true;try{await inspectControlTime(player?.time??time,new AbortController().signal);}finally{seekingControl=false;}}if(turnPad)turnPad.restore({...turnPad.snapshot(),held:true},false);},bookmark:inspectionBookmark,restore:(b,timed)=>restoreInspection(parseBookmark(b,inspectionBinding()),new AbortController().signal,!!timed),feedback:()=>session.feedback,
+  locked:id=>!!submittedBaseline?.updatedAt&&submittedBaseline.feedback.some(f=>f.id===id),add:f=>session.feedback.push(f),changed:()=>{markDirty();renderProposals();persistence?.save();},error:value=>message(value,true),
+  refusal:commentCaptureRefusal,blocked:()=>saving||!!persistence?.restoring()||seekingControl||!!video?.seeking||!!rebuildBusy||!!appliedOnStage,shortcutBlocked:()=>!!meshEditor?.active()
+ });
+}

package/web/stage-comments.ts

@@ -0,0 +1,107 @@
+/** One gesture into the existing feedback record. No authoring or HTTP endpoint. */
+import type {ModelAssets,PosedFrame} from '@rig-c/play';
+import {paintInspectionViewport,pixelAlignedCrop,type ViewportCapture} from './viewport-capture.ts';
+import type {Feedback} from '../src/session.ts';
+import type {ControlNumericCamera} from '../src/control.ts';
+import {drawnSlots,region,projectMark,unprojectMark,parseStageComment,feedbackTimingLabel,type MarkRegion,type MarkPoint,type StageComment} from '../src/stage-comment.ts';
+import {textEntryFocused} from './view-controls.ts';
+export interface CommentPose {
+ mode:StageComment['mode'];camera:ControlNumericCamera;frame:StageComment['frame'];timeBasis?:StageComment['timeBasis'];time:number;animation:string|null;
+ turn:unknown;sourceHash:string;modelHash:string|null;referenceHash:string|null;referenceId:string|null;frameReason?:string;
+ capture?:ViewportCapture;rig:string;side?:'a'|'b';posed?:PosedFrame;assets?:ModelAssets;media?:HTMLVideoElement|HTMLImageElement;
+}
+interface Host {
+ toolbar:HTMLElement;viewports:Partial<Record<StageComment['viewport'],HTMLElement>>;
+ pose:(view:StageComment['viewport'])=>CommentPose|null;pause:()=>Promise<void>;
+ bookmark:()=>unknown;restore:(bookmark:unknown,timeOnly?:boolean)=>Promise<void>;
+ feedback:()=>Feedback[];locked:(id:string)=>boolean;
+ add:(feedback:Feedback,side?:'a'|'b')=>void;changed:()=>void;error:(message:string)=>void;
+ refusal?:()=>string|null;blocked:()=>boolean;shortcutBlocked?:()=>boolean;
+}
+const markOf=(f:Feedback):StageComment|null=>{try{const c=f.context as Record<string,unknown>|undefined;return c?.comment?parseStageComment(c.comment):null;}catch{return null;}};
+const copy=<T>(v:T):T=>JSON.parse(JSON.stringify(v));
+function rectElement(r:MarkRegion):HTMLDivElement{const node=document.createElement('div');node.className='stage-comment-region';Object.assign(node.style,{left:r.x+'px',top:r.y+'px',width:Math.max(2,r.width)+'px',height:Math.max(2,r.height)+'px'});return node;}
+async function crop(pose:CommentPose,r:MarkRegion):Promise<StageComment['crop']>{
+ if(!pose.capture)throw new Error('COMMENT_CROP_UNAVAILABLE: viewport pixel source unavailable');
+ const camera=pose.camera,padding=24,rawLeft=Math.max(0,Math.floor(r.x-padding)),rawTop=Math.max(0,Math.floor(r.y-padding)),pane=pose.capture.pane,bounds=pane.getBoundingClientRect(),ratio=globalThis.devicePixelRatio||1;
+ const {x:left,y:top,width,height}=pixelAlignedCrop({x:rawLeft,y:rawTop,width:Math.min(camera.viewport.width-rawLeft,Math.ceil(r.width+2*padding)),height:Math.min(camera.viewport.height-rawTop,Math.ceil(r.height+2*padding))},{x:bounds.left+pane.clientLeft,y:bounds.top+pane.clientTop},ratio);
+ if(width<=0||height<=0)throw new Error('COMMENT_CROP_UNAVAILABLE: mark is outside the viewport');
+ const scale=Math.min(ratio,768/width,768/height),out=document.createElement('canvas');out.width=Math.max(1,Math.round(width*scale));out.height=Math.max(1,Math.round(height*scale));const ctx=out.getContext('2d')!;ctx.scale(scale,scale);ctx.translate(-left,-top);
+ paintInspectionViewport(ctx,{x:left,y:top,width,height},pose.capture,pose);
+ ctx.strokeStyle=getComputedStyle(document.documentElement).getPropertyValue('--link').trim();ctx.lineWidth=2/scale;ctx.strokeRect(r.x,r.y,Math.max(3,r.width),Math.max(3,r.height));
+ const png=out.toDataURL('image/png');if(png.length>200000)throw new Error('COMMENT_CROP_LIMIT: mark a smaller region (PNG limit 150 KiB)');
+ const bytes=Uint8Array.from(atob(png.split(',')[1]!),c=>c.charCodeAt(0)),sha256=[...new Uint8Array(await crypto.subtle.digest('SHA-256',bytes))].map(n=>n.toString(16).padStart(2,'0')).join('');
+ return {path:`comment-crops/${sha256}.png`,sha256,png,width:out.width,height:out.height};
+}
+export function bindStageComments(host:Host):{refresh:()=>void;dispose:()=>void;active:()=>boolean;draft:()=>boolean}{
+ const toggle=document.getElementById('stage-comment') as HTMLButtonElement,listToggle=document.getElementById('stage-comment-list-toggle') as HTMLButtonElement;
+ const list=document.createElement('section');list.id='stage-comment-list';list.className='stage-comment-list stage-comment-ui';list.setAttribute('aria-label','Stage comments');list.hidden=true;
+ // An absolute overlay is not stage chrome: workspace measures stack children
+ // to allocate Inspector height. Keep the list in its positioned main instead.
+ const workspace=host.toolbar.closest('main');if(workspace)workspace.append(list);else host.toolbar.after(list);
+ const refusalNote=document.createElement('small');refusalNote.id='stage-comment-refusal';refusalNote.setAttribute('role','status');refusalNote.hidden=true;toggle.after(refusalNote);toggle.setAttribute('aria-describedby',refusalNote.id);const originalTitle=toggle.title;
+ const updateRefusal=()=>{const reason=host.refusal?.()??null;toggle.disabled=!!reason;toggle.title=reason??originalTitle;refusalNote.textContent=reason??'';refusalNote.hidden=!reason;return reason;};
+ const layers=new Map<StageComment['viewport'],HTMLDivElement>();for(const [key,pane]of Object.entries(host.viewports)){const layer=document.createElement('div');layer.className='stage-comment-layer';pane!.append(layer);layers.set(key as StageComment['viewport'],layer);}
+ let enabled=false,disposed=false,pending:{view:StageComment['viewport'];start:MarkPoint;end:MarkPoint;mode:StageComment['mode'];id:number;interaction:number;settled:Promise<void>}|null=null,composer:HTMLFormElement|null=null,draftMark:{view:StageComment['viewport'];mode:StageComment['mode'];screen:MarkRegion}|null=null,busy=false,last='',raf=0,interaction=0;
+ const setEnabled=(value:boolean)=>{if(value){const reason=updateRefusal();if(reason){host.error(reason);return;}}if(value&&(host.blocked()||host.shortcutBlocked?.())){host.error('COMMENT_BUSY: close the active editor or wait for the inspection to settle');return;}enabled=value;toggle.setAttribute('aria-pressed',String(value));for(const pane of Object.values(host.viewports))pane!.classList.toggle('stage-comment-mode',value);};
+ const cancel=()=>{++interaction;const previous=pending;pending=null;if(previous){const pane=host.viewports[previous.view];if(pane?.hasPointerCapture(previous.id))pane.releasePointerCapture(previous.id);}composer?.remove();composer=null;draftMark=null;last='';};
+ const assertCapture=()=>{const reason=updateRefusal();if(reason){cancel();setEnabled(false);host.error(reason);throw new Error(reason);}if(host.blocked())throw new Error('COMMENT_BUSY: wait for inspection');};
+ const jump=async(f:Feedback)=>{const mark=markOf(f);if(!mark)return;const panes=Object.values(host.viewports).map(p=>({pane:p!,visibility:p!.style.visibility}));try{cancel();for(const {pane}of panes)pane.style.visibility='hidden';await host.restore(mark.bookmark,mark.frame===null);last='';}catch(error){host.error(String(error));}finally{for(const {pane,visibility}of panes)pane.style.visibility=visibility;}};
+ const renderList=()=>{list.replaceChildren();const title=document.createElement('strong');title.textContent='Comments';list.append(title);const all=host.feedback().filter(f=>markOf(f));listToggle.textContent=`Comments (${all.length})`;if(!all.length){const empty=document.createElement('p');empty.textContent='Mark a point or region, then type. Enter saves · Escape cancels.';list.append(empty);}for(const [i,f]of all.entries()){
+  const mark=markOf(f)!,row=document.createElement('div');row.className='stage-comment-item';row.dataset.commentId=f.id;
+  const go=document.createElement('button');go.type='button';go.textContent=`${i+1} · ${mark.mode.toUpperCase()} · ${mark.viewport.toUpperCase()} · ${mark.frame?`F${mark.frame.index} (${mark.frame.basis})`:feedbackTimingLabel(f)} · ${f.summary}`;go.onclick=()=>void jump(f);row.append(go);
+  if(!host.locked(f.id)){const edit=document.createElement('button');edit.textContent='Edit';edit.onclick=async()=>{await jump(f);openComposer(mark.viewport,mark.screen,f);};const remove=document.createElement('button');remove.textContent='Delete';remove.onclick=()=>{const all=host.feedback(),index=all.findIndex(x=>x.id===f.id);if(index>=0)all.splice(index,1);cancel();host.changed();refresh();};row.append(edit,remove);}else{const submitted=document.createElement('span');submitted.textContent='Submitted';row.append(submitted);}list.append(row);
+ }};
+ const refresh=()=>{last='';renderList();};
+ const openComposer=(view:StageComment['viewport'],screen:MarkRegion,existing?:Feedback,placementMode=host.pose(view)?.mode)=>{
+  try{assertCapture();}catch{return;}
+  if(!placementMode||host.pose(view)?.mode!==placementMode){cancel();return;}
+  composer?.remove();draftMark={view,mode:placementMode,screen};const generation=interaction;const pane=host.viewports[view]!,form=composer=document.createElement('form');form.className='stage-comment-composer stage-comment-ui';form.setAttribute('aria-label','Comment composer');
+  const field=document.createElement('input');field.type='text';field.maxLength=1000;field.setAttribute('aria-label','Comment text');field.placeholder='Describe this spot…';field.value=existing?.summary??'';
+  const hint=document.createElement('small');hint.textContent='Enter saves · Escape cancels';const error=document.createElement('p');error.setAttribute('role','alert');form.append(field,hint,error);pane.append(form);
+  Object.assign(form.style,{left:Math.max(4,Math.min(screen.x+screen.width+8,pane.clientWidth-294))+'px',top:Math.max(4,Math.min(screen.y+screen.height+8,pane.clientHeight-110))+'px'});
+  // Capture all view context now; camera or dial changes while typing cannot rebind the mark.
+  const pose=host.pose(view),bookmark=copy(host.bookmark()),turn=pose?copy(pose.turn):null;
+  if(pose&&!pose.frame&&!pose.timeBasis)error.textContent=pose.frameReason??'COMMENT_FRAME_UNAVAILABLE: no explicit frame index';
+  const previous=existing?markOf(existing):null;
+  const prepared=previous?Promise.resolve(previous.crop):pose?crop(pose,screen):Promise.reject(new Error('COMMENT_VIEW_UNAVAILABLE'));
+  prepared.catch(()=>{});
+  form.onkeydown=e=>{if(e.key==='Escape'){e.preventDefault();e.stopPropagation();cancel();pane.focus();}};
+  form.onsubmit=async e=>{e.preventDefault();if(busy)return;if(generation!==interaction||host.pose(view)?.mode!==placementMode){cancel();return;}const summary=field.value.trim();if(!summary){field.focus();return;}try{
+   assertCapture();if(host.blocked())throw new Error('COMMENT_BUSY: wait for inspection');if(!pose||!pose.frame&&!pose.timeBasis)throw new Error(pose?.frameReason??'COMMENT_FRAME_UNAVAILABLE: provide an explicit producer clock or a decoded reference frame index');
+   busy=true;field.disabled=true;
+   if(existing){if(host.locked(existing.id))throw new Error('COMMENT_SUBMITTED: submitted evidence is immutable');existing.summary=summary;}
+   else{
+    const world=region(unprojectMark(screen,pose.camera),unprojectMark({x:screen.x+screen.width,y:screen.y+screen.height},pose.camera));
+    const slots=pose.posed?drawnSlots(pose.posed,world):[];
+    const comment:StageComment={schema:'rig-review-comment/1',mode:placementMode,viewport:view,frame:pose.frame,...(pose.timeBasis?{timeBasis:pose.timeBasis}:{}),time:pose.time,animation:pose.animation,sourceHash:pose.sourceHash,modelHash:pose.modelHash,referenceHash:pose.referenceHash,referenceId:pose.referenceId,camera:copy(pose.camera),screen,world,slots,crop:await prepared,bookmark};
+    assertCapture();if(host.blocked())throw new Error('COMMENT_BUSY: wait for inspection');
+    if(disposed||generation!==interaction||host.pose(view)?.mode!==placementMode)return;
+    const n=pose.frame?.index??null;host.add({id:crypto.randomUUID(),frameStart:n,frameEnd:n,target:slots[0]?{kind:'slot',name:slots[0].slot}:{kind:'rig',name:pose.rig},category:'defect',summary,context:{animation:pose.animation,time:pose.time,frame:pose.frame?.basis==='producer'?n:null,...(turn?{turn:turn as any}:{}),interval:n===null?null:{frameStart:n,frameEnd:n,inclusive:true},comment:comment as any}},pose.side);
+   }
+   cancel();host.changed();refresh();
+  }catch(e){error.textContent=e instanceof Error?e.message:String(e);field.disabled=false;field.focus();}finally{busy=false;}};
+  field.focus();last='';
+ };
+ const disposers:(()=>void)[]=[];
+ for(const [key,pane]of Object.entries(host.viewports)){
+  const view=key as StageComment['viewport'],local=(e:PointerEvent)=>{const r=pane!.getBoundingClientRect();return {x:Math.max(0,Math.min(pane!.clientWidth,e.clientX-r.left-pane!.clientLeft)),y:Math.max(0,Math.min(pane!.clientHeight,e.clientY-r.top-pane!.clientTop))};};
+  const down=(e:PointerEvent)=>{if(enabled){try{assertCapture();}catch{return;}}if(!enabled||e.button!==0||!e.isPrimary||host.blocked()||(e.target as Element).closest('.stage-comment-ui,button,input'))return;e.preventDefault();e.stopImmediatePropagation();cancel();const at=local(e),mode=host.pose(view)?.mode;if(!mode)return;const generation=interaction;pending={view,start:at,end:at,mode,id:e.pointerId,interaction:generation,settled:host.pause()};pending.settled.catch(e=>{if(interaction===generation&&!disposed)host.error(String(e));});pane!.setPointerCapture(e.pointerId);};
+  const move=(e:PointerEvent)=>{if(!pending||pending.id!==e.pointerId)return;e.preventDefault();e.stopImmediatePropagation();pending.end=local(e);draftMark={view,mode:pending.mode,screen:region(pending.start,pending.end)};last='';};
+  const up=async(e:PointerEvent)=>{if(!pending||pending.id!==e.pointerId)return;e.preventDefault();e.stopImmediatePropagation();const p=pending;pending=null;if(pane!.hasPointerCapture(e.pointerId))pane!.releasePointerCapture(e.pointerId);try{await p.settled;assertCapture();if(disposed||interaction!==p.interaction||!enabled)return;const r=Math.hypot(p.end.x-p.start.x,p.end.y-p.start.y)<4?region(p.start,p.start):region(p.start,p.end);openComposer(view,r,undefined,p.mode);}catch(error){host.error(String(error));cancel();}};
+  const abort=(e:PointerEvent)=>{if(pending?.view===view&&pending.id===e.pointerId)cancel();};
+  pane!.addEventListener('pointerdown',down,true);pane!.addEventListener('pointermove',move,true);pane!.addEventListener('pointerup',up,true);pane!.addEventListener('pointercancel',abort,true);pane!.addEventListener('lostpointercapture',abort,true);
+  disposers.push(()=>{pane!.removeEventListener('pointerdown',down,true);pane!.removeEventListener('pointermove',move,true);pane!.removeEventListener('pointerup',up,true);pane!.removeEventListener('pointercancel',abort,true);pane!.removeEventListener('lostpointercapture',abort,true);});
+ }
+ const key=(e:KeyboardEvent)=>{if(e.key==='Escape'&&(pending||composer||enabled&&!host.shortcutBlocked?.()&&!textEntryFocused(e.target))){e.preventDefault();cancel();setEnabled(false);return;}if(e.defaultPrevented||e.repeat||e.ctrlKey||e.metaKey||e.altKey||textEntryFocused(e.target)||host.shortcutBlocked?.())return;if(e.key.toLowerCase()==='c'){e.preventDefault();setEnabled(!enabled);}else if(e.key==='Escape'&&enabled){cancel();setEnabled(false);}};
+ window.addEventListener('blur',cancel);document.addEventListener('keydown',key);toggle.onclick=()=>setEnabled(!enabled);listToggle.onclick=()=>{list.hidden=!list.hidden;listToggle.setAttribute('aria-expanded',String(!list.hidden));refresh();};
+ const paint=()=>{if(disposed)return;const refusal=updateRefusal();if(refusal&&(enabled||pending||composer)){cancel();setEnabled(false);host.error(refusal);}const all=host.feedback().map(f=>({f,mark:markOf(f)})).filter(x=>x.mark);
+ const poses=new Map([...layers.keys()].map(view=>[view,host.pose(view)]));
+ if(draftMark&&poses.get(draftMark.view)?.mode!==draftMark.mode||pending&&poses.get(pending.view)?.mode!==pending.mode)cancel();
+ const signature=JSON.stringify([refusal,all.map(({f,mark})=>[f.id,f.summary,mark!.mode,mark!.world]),[...poses].map(([view,p])=>[view,p?.mode,p?.animation,p?.frame,p?.timeBasis,p?.time,p?.turn,p?.camera,p?.referenceId,p?.referenceHash]),draftMark]);
+ if(signature!==last){last=signature;for(const layer of layers.values())layer.replaceChildren();for(const [i,{f,mark:m}]of all.entries()){
+  const mark=m!,pose=poses.get(mark.viewport),layer=layers.get(mark.viewport);if(refusal||!pose||!layer||pose.mode!==mark.mode||pose.animation!==mark.animation||pose.sourceHash!==mark.sourceHash||pose.modelHash!==mark.modelHash||pose.referenceId!==mark.referenceId||pose.referenceHash!==mark.referenceHash||JSON.stringify(pose.frame)!==JSON.stringify(mark.frame)||JSON.stringify(pose.timeBasis??null)!==JSON.stringify(mark.timeBasis??null)||Math.abs(pose.time-mark.time)>1e-7||JSON.stringify(pose.turn)!==JSON.stringify((f.context as any)?.turn??null))continue;
+  const a=projectMark(mark.world,pose.camera),b=projectMark({x:mark.world.x+mark.world.width,y:mark.world.y+mark.world.height},pose.camera),r=region(a,b),box=rectElement(r),pin=document.createElement('button');pin.type='button';pin.className='stage-comment-pin stage-comment-ui';pin.textContent=String(i+1);pin.setAttribute('aria-label',`Comment ${i+1}: ${f.summary}`);pin.title=f.summary;Object.assign(pin.style,{left:r.x+'px',top:r.y+'px'});pin.onclick=()=>{list.hidden=false;renderList();};layer.append(box,pin);
+ }if(draftMark)layers.get(draftMark.view)?.append(rectElement(draftMark.screen));}raf=requestAnimationFrame(paint);};
+ refresh();paint();return {active:()=>enabled,draft:()=>!!composer||!!pending,refresh,dispose:()=>{disposed=true;cancelAnimationFrame(raf);cancel();window.removeEventListener('blur',cancel);document.removeEventListener('keydown',key);for(const dispose of disposers)dispose();for(const layer of layers.values())layer.remove();list.remove();refusalNote.remove();}};
+}

package/web/styles.css

@@ -304,3 +304,6 @@ footer.status-bar{flex-wrap:nowrap}
 .turn-pad output{font-variant-numeric:tabular-nums;color:var(--fg-strong)}
 .turn-pad button[aria-pressed=true]{border-color:var(--pass);color:var(--pass)}
 #turn-pad-host>p{margin:0 12px 6px}
+
+/* Source-bound stage comments; the layer never intercepts ordinary inspection. */
+main{position:relative}.stage-comment-mode{cursor:crosshair}.stage-comment-mode video{pointer-events:none}.stage-comment-layer{position:absolute;inset:0;pointer-events:none;z-index:20;overflow:hidden}.stage-comment-region{position:absolute;border:2px solid var(--link);pointer-events:none}.stage-comment-pin{position:absolute;transform:translate(-50%,-50%);border-radius:50%;min-width:26px;height:26px;padding:2px 5px;background:var(--link);color:var(--btn-fg);pointer-events:auto}.stage-comment-composer{position:absolute;z-index:30;width:286px;padding:10px;background:var(--rv-panel);border:1px solid var(--link);border-radius:6px;box-shadow:0 4px 20px var(--rv-backdrop)}.stage-comment-composer input{width:100%}.stage-comment-composer small{display:block;margin-top:6px;color:var(--fg-muted)}.stage-comment-composer p{color:var(--fail);margin:4px 0}.stage-comment-list{position:absolute;z-index:40;right:8px;top:55px;width:310px;max-width:90%;max-height:60%;overflow:auto;background:var(--rv-panel);border:1px solid var(--border-strong);padding:12px;border-radius:6px}.stage-comment-item{padding:8px 0;border-bottom:1px solid var(--border)}.stage-comment-item>button:first-child{display:block;width:100%;text-align:left;overflow-wrap:anywhere}.stage-comment-item span{display:block;color:var(--fg-muted)}

package/web/turn-pad.ts

@@ -1,5 +1,5 @@
 import {TurnState,type TurnDial,type TurnSnapshot,type TurnAxis,pointerPosition} from '../src/turn-pad.ts';
-export interface TurnPad {state:TurnState;snapshot():TurnSnapshot;restore(value:unknown):void;dispose():void}
+export interface TurnPad {state:TurnState;snapshot():TurnSnapshot;restore(value:unknown,redraw?:boolean):void;dispose():void}
 /** One pad owns the shared values. It never touches the model document or writes animation keys. */
 export function bindTurnPad(options:{host:HTMLElement;stages:HTMLElement[];dials:readonly TurnDial[];draw:(state:TurnState)=>void;save:()=>void;blocked?:()=>boolean;error:(text:string)=>void}):TurnPad|null {
  const {host,stages,dials}=options;if(!dials.length)return null;
@@ -22,5 +22,5 @@ export function bindTurnPad(options:{host:HTMLElement;stages:HTMLElement[];dials
  let disposed=false,last=0,raf=0;
  const step=(now:number)=>{if(disposed)return;if(!document.hidden&&!options.blocked?.()&&state.step(last?Math.min((now-last)/1000,.1):0))commit();last=now;raf=requestAnimationFrame(step);};
  host.append(panel);commit();raf=requestAnimationFrame(step);
- return {state,snapshot:()=>state.snapshot(),restore(value){state.restore(value);commit();},dispose(){disposed=true;if(saveTimer)clearTimeout(saveTimer);cancelAnimationFrame(raf);for(const stage of stages)stage.removeEventListener('pointermove',move);panel.remove();}};
+ return {state,snapshot:()=>state.snapshot(),restore(value,redraw=true){state.restore(value);if(redraw)commit();else{render();options.save();}},dispose(){disposed=true;if(saveTimer)clearTimeout(saveTimer);cancelAnimationFrame(raf);for(const stage of stages)stage.removeEventListener('pointermove',move);panel.remove();}};
 }

package/web/viewport-capture.ts

@@ -0,0 +1,73 @@
+/** Pixel composition for the inspection viewport; no DOM serialization or screenshot API. */
+import {CanvasRenderer,type CanvasBackend,type ModelAssets,type PosedFrame} from '@rig-c/play';
+import type {ControlNumericCamera} from '../src/control.ts';
+import {projectMark,type MarkRegion} from '../src/stage-comment.ts';
+export interface CaptureRect {x:number;y:number;width:number;height:number}
+/** Untransformed replaced canvases are painted at snapped device-pixel edges by the page compositor. */
+export function displayedCanvasRect(rect:CaptureRect,origin:{x:number;y:number},ratio=1):CaptureRect{
+ const x=Math.round(rect.x*ratio)/ratio,y=Math.round(rect.y*ratio)/ratio;
+ return {x:x-origin.x,y:y-origin.y,width:Math.round((rect.x+rect.width)*ratio)/ratio-x,height:Math.round((rect.y+rect.height)*ratio)/ratio-y};
+}
+/** Keep whole displayed device pixels. Fractional CSS pane placement must not resample an already composited screenshot again. */
+export function pixelAlignedCrop(area:CaptureRect,origin:{x:number;y:number},ratio=1):CaptureRect{
+ const x=Math.ceil((origin.x+area.x)*ratio)/ratio-origin.x,y=Math.ceil((origin.y+area.y)*ratio)/ratio-origin.y;
+ return {x,y,width:Math.max(0,Math.floor((origin.x+area.x+area.width)*ratio)/ratio-origin.x-x),height:Math.max(0,Math.floor((origin.y+area.y+area.height)*ratio)/ratio-origin.y-y)};
+}
+export interface BackgroundLayer {rect:CaptureRect;color:string;image:string;size:string;position:string}
+export interface PixelLayer {image:CanvasImageSource;rect:CaptureRect;opacity:number}
+export interface ViewportCapture {pane:HTMLElement;root?:HTMLElement;images:boolean;canvas?:HTMLCanvasElement;backend:CanvasBackend}
+const transparent=(color:string)=>color==='transparent'||/^rgba\([^)]*,\s*0\s*\)$/.test(color);
+/** Read only this app's computed backgrounds, in their actual viewport coordinates. */
+export function viewportBackground(pane:HTMLElement):BackgroundLayer[]{
+ const origin=pane.getBoundingClientRect(),x=origin.left+pane.clientLeft,y=origin.top+pane.clientTop,result:BackgroundLayer[]=[];
+ for(let node:HTMLElement|null=pane;node;node=node.parentElement){const style=getComputedStyle(node),rect=node.getBoundingClientRect();result.unshift({rect:{x:rect.left+node.clientLeft-x,y:rect.top+node.clientTop-y,width:node.clientWidth,height:node.clientHeight},color:style.backgroundColor,image:style.backgroundImage,size:style.backgroundSize,position:style.backgroundPosition});}
+ return result;
+}
+/** These are the app's solid, stage-ellipse and grid backgrounds, not an HTML rasterizer. */
+export function paintBackground(ctx:CanvasRenderingContext2D,layers:BackgroundLayer[],area:CaptureRect):void {
+ for(const layer of layers){const r=layer.rect;if(!transparent(layer.color)){ctx.fillStyle=layer.color;ctx.fillRect(r.x,r.y,r.width,r.height);}if(!layer.image||layer.image==='none')continue;
+  const colors=layer.image.match(/rgba?\([^)]+\)|#[\da-f]+/gi)??[];if(!layer.image.startsWith('radial-gradient(')||colors.length!==2)throw new Error('COMMENT_BACKGROUND_UNAVAILABLE: unsupported viewport background');
+  const sizes=layer.size.split(/\s+/).map(Number.parseFloat),radius=layer.image.match(/\)\s+([\d.]+)px/);
+  if(radius&&sizes.length===2&&sizes.every(n=>Number.isFinite(n)&&n>0)){
+   const [sx,sy]=sizes as [number,number],position=layer.position.split(/\s+/),offset=(v:string,extent:number,tile:number)=>v.endsWith('%')?(extent-tile)*parseFloat(v)/100:parseFloat(v);
+   const ox=r.x+offset(position[0]??'0%',r.width,sx),oy=r.y+offset(position[1]??'0%',r.height,sy);ctx.save();ctx.beginPath();ctx.rect(r.x,r.y,r.width,r.height);ctx.clip();ctx.fillStyle=colors[0]!;
+   for(let y=oy+Math.floor((area.y-oy)/sy)*sy+sy/2;y<area.y+area.height+sy;y+=sy)for(let x=ox+Math.floor((area.x-ox)/sx)*sx+sx/2;x<area.x+area.width+sx;x+=sx){ctx.beginPath();ctx.arc(x,y,Number(radius[1]),0,Math.PI*2);ctx.fill();}ctx.restore();
+  }else{
+   const position=layer.image.match(/at\s+([\d.]+)%\s+([\d.]+)%/),end=layer.image.match(/([\d.]+)%\s*\)$/);if(!position||!end)throw new Error('COMMENT_BACKGROUND_UNAVAILABLE: unknown stage ellipse');
+   const cx=r.width*Number(position[1])/100,cy=r.height*Number(position[2])/100,rx=Math.max(cx,r.width-cx)*Math.SQRT2,ry=Math.max(cy,r.height-cy)*Math.SQRT2;if(rx<=0||ry<=0)continue;
+   ctx.save();ctx.translate(r.x+cx,r.y+cy);ctx.scale(rx,ry);const gradient=ctx.createRadialGradient(0,0,0,0,0,1);gradient.addColorStop(0,colors[0]!);gradient.addColorStop(Number(end[1])/100,colors[1]!);gradient.addColorStop(1,colors[1]!);ctx.fillStyle=gradient;ctx.fillRect(-cx/rx,-cy/ry,r.width/rx,r.height/ry);ctx.restore();
+  }
+ }
+}
+export function paintViewportLayers(ctx:CanvasRenderingContext2D,area:CaptureRect,background:BackgroundLayer[],images:boolean,drawImages:()=>void,overlays:PixelLayer[]):void {
+ ctx.save();ctx.beginPath();ctx.rect(area.x,area.y,area.width,area.height);ctx.clip();paintBackground(ctx,background,area);if(images)drawImages();
+ for(const layer of overlays){ctx.save();ctx.globalAlpha=layer.opacity;ctx.drawImage(layer.image,layer.rect.x,layer.rect.y,layer.rect.width,layer.rect.height);ctx.restore();}ctx.restore();
+}
+function displayedPixels(canvas:HTMLCanvasElement,pane:HTMLElement,snap=true):PixelLayer|null {
+ const style=getComputedStyle(canvas);if(style.display==='none'||style.visibility==='hidden'||Number(style.opacity)===0)return null;const a=canvas.getBoundingClientRect(),b=pane.getBoundingClientRect(),origin={x:b.left+pane.clientLeft,y:b.top+pane.clientTop};return {image:canvas,rect:snap&&style.transform==='none'?displayedCanvasRect({x:a.left,y:a.top,width:a.width,height:a.height},origin,globalThis.devicePixelRatio||1):{x:a.left-origin.x,y:a.top-origin.y,width:a.width,height:a.height},opacity:Number(style.opacity)};
+}
+/** Copy only unambiguous, normal-filter DOM rasters whose z matches the public held frame.
+ * CSS transforms are read from the actual displayed elements; no private player fields. */
+function displayedRig(ctx:CanvasRenderingContext2D,capture:ViewportCapture,frame:PosedFrame,camera:ControlNumericCamera):boolean {
+ const root=capture.root;if(!root)return false;const children=[...root.children].filter((n):n is HTMLImageElement|HTMLCanvasElement=>n instanceof HTMLImageElement||n instanceof HTMLCanvasElement).filter(n=>getComputedStyle(n).display!=='none');
+ const byZ=new Map<number,HTMLImageElement|HTMLCanvasElement>();for(const node of children){const style=getComputedStyle(node),z=Number(style.zIndex);if(style.filter!=='none'||style.transformOrigin!=='0px 0px'||!Number.isSafeInteger(z)||byZ.has(z))return false;byZ.set(z,node);}
+ if(children.length!==frame.order.length||frame.order.some(row=>!byZ.has(row.z)))return false;
+ const r=root.getBoundingClientRect(),p=capture.pane.getBoundingClientRect(),rootMatrix=new DOMMatrix(getComputedStyle(root).transform);if(!rootMatrix.is2D||rootMatrix.b!==0||rootMatrix.c!==0||rootMatrix.a<=0||rootMatrix.d<=0||getComputedStyle(root).transformOrigin!=='0px 0px')return false;
+ const plans=frame.order.map(row=>{const node=byZ.get(row.z)!,style=getComputedStyle(node);return {row,node,style,m:new DOMMatrix(style.transform),width:parseFloat(style.width),height:parseFloat(style.height)};});if(plans.some(p=>!p.m.is2D||![p.width,p.height].every(n=>Number.isFinite(n)&&n>0)))return false;
+ for(const {row,node,style,m,width,height}of plans){
+  ctx.save();if(row.clip){ctx.beginPath();if(row.clip.inverse)ctx.rect(0,0,camera.viewport.width,camera.viewport.height);for(let i=0;i<row.clip.polygon.length;i+=2){const at=projectMark({x:row.clip.polygon[i]!,y:row.clip.polygon[i+1]!},camera);if(i===0)ctx.moveTo(at.x,at.y);else ctx.lineTo(at.x,at.y);}ctx.closePath();ctx.clip(row.clip.inverse?'evenodd':'nonzero');}
+  ctx.globalAlpha=Number(style.opacity);ctx.globalCompositeOperation=style.mixBlendMode==='plus-lighter'?'lighter':style.mixBlendMode==='normal'?'source-over':style.mixBlendMode as GlobalCompositeOperation;
+  ctx.transform(rootMatrix.a*m.a,rootMatrix.d*m.b,rootMatrix.a*m.c,rootMatrix.d*m.d,r.left-p.left-capture.pane.clientLeft+rootMatrix.a*m.e,r.top-p.top-capture.pane.clientTop+rootMatrix.d*m.f);ctx.drawImage(node,0,0,width,height);ctx.restore();
+ }return true;
+}
+export function paintInspectionViewport(ctx:CanvasRenderingContext2D,area:MarkRegion,capture:ViewportCapture,pose:{camera:ControlNumericCamera;posed?:PosedFrame;assets?:ModelAssets;media?:HTMLVideoElement|HTMLImageElement}):void {
+ const overlays=[...capture.pane.querySelectorAll<HTMLCanvasElement>('canvas')].filter(node=>!capture.root?.contains(node)&&node!==capture.canvas).map(node=>displayedPixels(node,capture.pane)).filter((v):v is PixelLayer=>v!==null);
+ paintViewportLayers(ctx,area,viewportBackground(capture.pane),capture.images,()=>{
+  if(capture.canvas){const pixels=displayedPixels(capture.canvas,capture.pane,!capture.root?.contains(capture.canvas));if(pixels){ctx.save();ctx.globalAlpha=pixels.opacity;ctx.drawImage(pixels.image,pixels.rect.x,pixels.rect.y,pixels.rect.width,pixels.rect.height);ctx.restore();return;}}
+  if(pose.posed&&pose.assets){if(displayedRig(ctx,capture,pose.posed,pose.camera))return;
+   if(capture.backend==='canvas2d'&&pose.posed.order.some(row=>row.tint.slice(0,3).some(c=>c!==1)||row.dark?.some(c=>c!==0)))throw new Error('COMMENT_CAPTURE_UNAVAILABLE: Canvas2D cannot reproduce active RGB/dark tint');
+   const root=document.createElement('div'),renderer=new CanvasRenderer(root,pose.assets.pageImages);try{renderer.backend=capture.backend;renderer.viewport={...pose.camera.visible};renderer.pixelRatio=pose.camera.viewport.width/pose.camera.visible.width;renderer.render(pose.posed);ctx.drawImage(renderer.canvas,0,0,pose.camera.viewport.width,pose.camera.viewport.height);}finally{renderer.dispose();}
+  }else if(pose.media){const media=pose.media,style=getComputedStyle(media),a=media.getBoundingClientRect(),b=capture.pane.getBoundingClientRect();if(!transparent(style.backgroundColor)){ctx.fillStyle=style.backgroundColor;ctx.fillRect(a.left-b.left-capture.pane.clientLeft,a.top-b.top-capture.pane.clientTop,a.width,a.height);}const w=media instanceof HTMLVideoElement?media.videoWidth:media.naturalWidth,h=media instanceof HTMLVideoElement?media.videoHeight:media.naturalHeight,first=projectMark({x:0,y:0},pose.camera),last=projectMark({x:w,y:h},pose.camera);ctx.drawImage(media,first.x,first.y,last.x-first.x,last.y-first.y);
+  }else throw new Error('COMMENT_CROP_UNAVAILABLE: this viewport has no rendered pixels');
+ },overlays);
+}