@rig-c/review 0.4.0 → 0.6.0

package/web/mesh-editor.ts

@@ -0,0 +1,268 @@
+/**
+ * Mesh edit (Setup): a view-bar toggle, an editor bar of sub-modes (Modify / Create / Delete / Edges) and direct
+ * manipulation of the selected slot's actual mesh on the rig pane. Everything is a typed delta (`src/mesh-edit.ts`)
+ * previewed over the original triangulation; nothing is retriangulated, written into the package or sent to a
+ * producer — Apply · Rebuild refuses by name as the chest editor's does.
+ */
+import type {PosedSlot} from '@rig-c/play';
+import type {CropWorldMapping} from '../src/chest-regions.ts';
+import {
+ MESH_EDIT_NO_MESH,MESH_EDIT_PREVIEW_NOTE,MESH_EDIT_SELECT_SLOT,MeshEditSession,affineOf,applyAffine,applyMeshOps,attachmentHashText,draftOps,hitMesh,
+ invertAffine,meshEditDocument,parseMeshDraft,screenDeltaToCrop,verticesInBox,writeMeshDraft,type MeshEditDocument,type MeshEditResult,type MeshOp,type MeshSource,
+ type MeshView,type ScreenPoint,type Vec,
+} from '../src/mesh-edit.ts';
+import {MODELING_INPUT_UNAVAILABLE,requestRebuild} from './chest-editor.ts';
+import type {OverlayMeshEdit,OverlayPoint,OverlayProject} from './rig-overlays.ts';
+import {textEntryFocused} from './view-controls.ts';
+
+export type MeshMode='modify'|'create'|'delete'|'edges';
+export const meshModes:readonly MeshMode[]=['modify','create','delete','edges'];
+/** Single-key sub-mode shortcuts. Free of I / M / B (layers), Space (pan), Enter, arrows (nudge) and Z (undo). */
+export const meshModeKeys:Readonly<Record<string,MeshMode>>=Object.freeze({v:'modify',c:'create',x:'delete',e:'edges'});
+export const meshModeLabel:Readonly<Record<MeshMode,string>>=Object.freeze({modify:'Modify',create:'Create',delete:'Delete',edges:'Edges'});
+export const meshEditVisible=(inspector:string|undefined)=>inspector==='rig';
+
+export type MeshKeyAction={type:'mode';mode:MeshMode}|{type:'escape'}|{type:'undo'}|{type:'redo'}|{type:'nudge';dx:number;dy:number};
+interface KeyLike {key:string;shiftKey:boolean;ctrlKey:boolean;metaKey:boolean;altKey:boolean;repeat?:boolean;defaultPrevented?:boolean;target:unknown}
+/** Focus inside these keeps its own keys (tabs, separators, the part list, menus and buttons use arrows/Escape). */
+const ownKeys='[role=separator],[role=tab],[data-part-list],[data-part-search],details,dialog';
+/** Keyboard map while mesh edit is on. Text entry keeps every key. */
+export function meshEditShortcut(event:KeyLike,state:{active:boolean;mode:MeshMode|null;selected:number}):MeshKeyAction|null {
+ if(!state.active||event.defaultPrevented||typeof event.key!=='string'||textEntryFocused(event.target))return null;
+ const key=event.key.toLowerCase(),within=(selector:string)=>{const node=event.target as {closest?:(s:string)=>unknown}|null;return !!node&&typeof node.closest==='function'&&!!node.closest(selector);};
+ if((event.metaKey||event.ctrlKey)&&!event.altKey&&key==='z')return event.shiftKey?{type:'redo'}:{type:'undo'};
+ if(event.metaKey||event.ctrlKey||event.altKey)return null;
+ if(key==='escape')return within('dialog[open],details[open]')?null:{type:'escape'};
+ if(event.key.startsWith('Arrow')){
+  if(state.mode!=='modify'||!state.selected||within(ownKeys))return null;
+  const step=event.shiftKey?10:1,d=({ArrowLeft:[-step,0],ArrowRight:[step,0],ArrowUp:[0,-step],ArrowDown:[0,step]} as Record<string,[number,number]>)[event.key];
+  return d?{type:'nudge',dx:d[0],dy:d[1]}:null;
+ }
+ if(event.repeat||event.shiftKey)return null;
+ const mode=meshModeKeys[key];return mode?{type:'mode',mode}:null;
+}
+
+/** World → crop through the inverse of the crop mapping (crop px, x right, y down). */
+export function cropFromWorld(mapping:Extract<CropWorldMapping,{available:true}>):((x:number,y:number)=>Vec)|null {
+ const inverse=invertAffine(affineOf((x,y)=>mapping.toWorld(x,y)));if(!inverse)return null;
+ return (x,y)=>{const p=applyAffine(inverse,x,y);return [Math.round(p.x*100)/100,Math.round(p.y*100)/100];};
+}
+type SourceResult={ok:true;source:Omit<MeshSource,'hash'>;entry:unknown}|{ok:false;code:string};
+/**
+ * The actual mesh of the selected slot: the active attachment's entry in the hash-verified model, and the slot's last
+ * drawn posed vertices mapped to crop px. A count or triangle mismatch between the two is refused.
+ */
+export function meshEditSource(input:{slot:string|null;activeAttachment:{skin:string;attachment:string}|null;row:PosedSlot|undefined;model:unknown;mapping:CropWorldMapping}):SourceResult {
+ const {slot}=input;if(!slot)return {ok:false,code:`${MESH_EDIT_SELECT_SLOT}: select one slot in the parts list; whole-rig mesh edit is not a thing`};
+ const noMesh=(why:string)=>({ok:false as const,code:`${MESH_EDIT_NO_MESH} ${slot}: ${why}`});
+ const active=input.activeAttachment;if(!active)return noMesh('no active attachment at the held pose');
+ const model=input.model as {skins?:{name?:unknown;attachments?:Record<string,Record<string,unknown>>}[]}|null;
+ const entry=model?.skins?.find(skin=>skin.name===active.skin)?.attachments?.[slot]?.[active.attachment] as {kind?:unknown;uvs?:unknown;triangles?:unknown;hull?:unknown}|undefined;
+ if(!entry||entry.kind!=='mesh')return noMesh(`${active.skin} / ${active.attachment} is not a mesh attachment`);
+ if(!input.row||input.row.kind!=='mesh')return noMesh('the slot is not drawn as a mesh at the held pose');
+ if(!input.mapping.available)return {ok:false,code:`${input.mapping.reason}: mesh edit needs the crop mapping`};
+ const triangles=entry.triangles,uvs=entry.uvs,hull=entry.hull;
+ if(!Array.isArray(triangles)||!Array.isArray(uvs)||typeof hull!=='number'||!Number.isSafeInteger(hull)||hull<0)return noMesh('the model entry has no triangles, uvs or hull');
+ const count=uvs.length/2,posed=input.row.vertices;
+ if(posed.length/2!==count||hull>count||input.row.triangles.length!==triangles.length||input.row.triangles.some((v,i)=>v!==triangles[i]))return {ok:false,code:`MESH_EDIT_SOURCE_MISMATCH: ${slot} drawn mesh (${posed.length/2} vertices) differs from the model attachment (${count})`};
+ const toCrop=cropFromWorld(input.mapping);if(!toCrop)return {ok:false,code:'MESH_EDIT_MAPPING_SINGULAR'};
+ const vertices:Vec[]=[];for(let i=0;i<posed.length;i+=2)vertices.push(toCrop(posed[i]!,posed[i+1]!));
+ return {ok:true,source:{slot,skin:active.skin,attachment:active.attachment,vertices,triangles:[...triangles] as number[],hull},entry};
+}
+export async function sha256Hex(text:string):Promise<string> {return [...new Uint8Array(await crypto.subtle.digest('SHA-256',new TextEncoder().encode(text)))].map(b=>b.toString(16).padStart(2,'0')).join('');}
+
+export interface MeshEditorHost {
+ pane:HTMLElement;canvas:HTMLElement;
+ project:()=>OverlayProject|null;
+ mapping:()=>CropWorldMapping;
+ inspector:()=>string|undefined;
+ /** The selected slot's source, or the refusal that names why there is none. */
+ source:()=>SourceResult;
+ /** How the vertices were obtained (pose, mapping), for the export. */
+ basis:()=>string;
+ /** Hold the pose being edited still. */
+ pause:()=>void;
+ changed:()=>void;
+ download:(document:MeshEditDocument)=>void;
+ message:(text:string,error?:boolean)=>void;
+ confirm:(text:string)=>boolean;
+ token:(name:string)=>string;
+}
+export interface MeshEditor {active:()=>boolean;overlay:()=>OverlayMeshEdit|null;sync:()=>void;selectionChanged:()=>void;dispose:()=>void;session:()=>MeshEditSession|null;mode:()=>MeshMode|null}
+
+type Drag={pointer:number;start:ScreenPoint;ids:number[];base:MeshView;ops:MeshOp[]}|{pointer:number;start:ScreenPoint;box:ScreenPoint;add:boolean};
+
+export function bindMeshEditor(host:MeshEditorHost):MeshEditor {
+ const node=<T extends HTMLElement>(id:string)=>document.getElementById(id) as T;
+ const toggle=node<HTMLButtonElement>('mesh-edit'),bar=node<HTMLElement>('mesh-editor-bar'),status=node<HTMLElement>('mesh-editor-status'),draft=node<HTMLTextAreaElement>('mesh-edit-draft');
+ const chestToggle=document.getElementById('chest-edit') as HTMLButtonElement|null;
+ let active=false,entering=false,mode:MeshMode|null=null,session:MeshEditSession|null=null,space=false,drag:Drag|null=null,pending:number|null=null,hover:ReturnType<typeof hitMesh>=null,note='',noteError=false;
+ let preview:MeshView|null=null;const selected=new Set<number>();
+ const view=()=>preview??session?.view()??null;
+ const cropToScreen=()=>{const project=host.project(),mapping=host.mapping();if(!project||!mapping.available)return null;return affineOf((x,y)=>{const w=mapping.toWorld(x,y);return project(w.x,w.y);});};
+ const screenPoints=():(ScreenPoint|null)[]=>{const m=cropToScreen(),v=view();if(!m||!v)return [];return v.vertices.map(p=>p?applyAffine(m,p[0],p[1]):null);};
+ const toCrop=(p:ScreenPoint):Vec|null=>{const m=cropToScreen(),inverse=m&&invertAffine(m);if(!inverse)return null;const q=applyAffine(inverse,p.x,p.y);return [q.x,q.y];};
+ const local=(event:PointerEvent):ScreenPoint=>{const rect=host.canvas.getBoundingClientRect();return {x:event.clientX-rect.left,y:event.clientY-rect.top};};
+ const hint:Record<MeshMode,string>={
+  modify:'drag a vertex or edge · Shift-click selects more · drag empty space to box-select · arrows nudge 1 px (Shift 10)',
+  create:'click empty space to add a vertex · click an edge to split it',
+  delete:'click a vertex (with its edges) or an edge to remove it · hull edges stay',
+  edges:'click vertex A then vertex B to add a constraint edge · click a constraint edge to remove it',
+ };
+ const sync=()=>{
+  const visible=meshEditVisible(host.inspector());toggle.hidden=!visible;
+  if(!visible&&active){setActive(false);return;}
+  toggle.setAttribute('aria-pressed',String(active));bar.hidden=!active;
+  for(const button of bar.querySelectorAll<HTMLButtonElement>('[data-mesh-mode]'))button.setAttribute('aria-pressed',String(button.dataset.meshMode===mode));
+  node<HTMLButtonElement>('mesh-undo').disabled=!session?.canUndo();node<HTMLButtonElement>('mesh-redo').disabled=!session?.canRedo();node<HTMLButtonElement>('mesh-reset').disabled=!session?.canUndo()&&!session?.ops().length;
+  if(!session){status.textContent='';return;}
+  const s=session.source,count=session.ops().length;
+  status.textContent=`${note?note+' · ':''}${count} op${count===1?'':'s'} · ${MESH_EDIT_PREVIEW_NOTE} · ${mode?hint[mode]:'no sub-mode — Escape again leaves mesh edit'} · Space-drag pans`;
+  status.title=`${s.slot} / ${s.skin} / ${s.attachment} · ${s.vertices.length} vertices · ${s.triangles.length/3} triangles · hull ${s.hull} · ${status.textContent}`;
+  status.classList.toggle('error',noteError);
+  if(mode)host.pane.dataset.meshMode=mode;else delete host.pane.dataset.meshMode;
+ };
+ const say=(text:string,error=false)=>{note=text;noteError=error;if(text)host.message(text,error);sync();};
+ const persist=()=>{if(!session)return;const text=writeMeshDraft(parseMeshDraft(draft.value),session.source,session.ops());if(text.length>32768){say('MESH_EDIT_DRAFT_LIMIT: the local draft is full — download the JSON; edits after this are not kept on reload',true);return;}draft.value=text;draft.dispatchEvent(new Event('input',{bubbles:true}));};
+ /** Reports a step: a refusal by its code, a no-op by its reason, a change by what it did. */
+ const after=(result:MeshEditResult,what:()=>string)=>{
+  if(!result.ok)say(result.code,true);
+  else if(result.changed){persist();say('');host.message(`${what()} · ${MESH_EDIT_PREVIEW_NOTE}`);}
+  else say(result.code??'');
+  host.changed();
+ };
+ const lastAdded=()=>(session?.view().vertices.length??1)-1;
+ const setMode=(next:MeshMode|null)=>{mode=next;pending=null;drag=null;preview=null;sync();host.changed();};
+ const leave=()=>{active=false;mode=null;session=null;drag=null;preview=null;pending=null;hover=null;selected.clear();note='';delete host.pane.dataset.meshHover;delete host.pane.dataset.meshMode;};
+ const setActive=(on:boolean)=>{if(!on){leave();sync();host.changed();return;}void enter();};
+ const enter=async()=>{
+  if(entering)return;entering=true;
+  try{
+   const result=host.source();if(!result.ok){leave();sync();host.message(result.code,true);host.changed();return;}
+   const hash=await sha256Hex(attachmentHashText(result.entry)),source:MeshSource={...result.source,hash};
+   const restored=draftOps(parseMeshDraft(draft.value),source);session=new MeshEditSession(source,restored??[]);
+   if(chestToggle?.getAttribute('aria-pressed')==='true')chestToggle.click();
+   host.pause();active=true;mode='modify';selected.clear();pending=null;note=restored?.length?`restored ${restored.length} draft op${restored.length===1?'':'s'}`:'';noteError=false;
+   sync();host.changed();
+  }finally{entering=false;}
+ };
+ toggle.addEventListener('click',()=>setActive(!active));
+ for(const button of bar.querySelectorAll<HTMLButtonElement>('[data-mesh-mode]'))button.addEventListener('click',()=>setMode(button.dataset.meshMode as MeshMode));
+ const undo=()=>{if(session?.undo()){selected.clear();persist();say('');host.changed();}};
+ const redo=()=>{if(session?.redo()){selected.clear();persist();say('');host.changed();}};
+ node<HTMLButtonElement>('mesh-undo').addEventListener('click',undo);node<HTMLButtonElement>('mesh-redo').addEventListener('click',redo);
+ node<HTMLButtonElement>('mesh-reset').addEventListener('click',()=>{if(!session)return;if(!host.confirm(`Drop the whole mesh-edit delta for ${session.source.slot} / ${session.source.attachment}? This cannot be undone.`))return;session.reset();selected.clear();persist();say('delta reset');host.changed();});
+ node<HTMLButtonElement>('mesh-download').addEventListener('click',()=>{if(session)host.download(meshEditDocument(session,host.basis()));});
+ node<HTMLButtonElement>('mesh-apply').addEventListener('click',()=>{const result=requestRebuild((text,error)=>host.message(text,error));say(result.error,true);});
+ const keyDown=(event:KeyboardEvent)=>{
+  if(event.code==='Space'&&!textEntryFocused(event.target))space=true;
+  const action=meshEditShortcut(event,{active,mode,selected:selected.size});if(!action)return;
+  event.preventDefault();event.stopPropagation();
+  if(action.type==='mode')setMode(action.mode);
+  else if(action.type==='escape'){if(mode)setMode(null);else setActive(false);}
+  else if(action.type==='undo')undo();else if(action.type==='redo')redo();
+  else if(session)after(session.record(session.moveOps([...selected],action.dx,action.dy)),()=>`nudged ${selected.size} vertex${selected.size===1?'':'es'} by ${action.dx}, ${action.dy} crop px`);
+ };
+ const keyUp=(event:KeyboardEvent)=>{if(event.code==='Space')space=false;};
+ const blur=()=>{space=false;};
+ const down=(event:PointerEvent)=>{
+  if(!active||!mode||!session||space||!event.isPrimary||event.button!==0)return;
+  const target=event.target;if(target instanceof Element&&target.closest('button,input,select,textarea,a,summary'))return;
+  // In a sub-mode every primary press edits; the viewport's pan never sees it (Space-drag still pans).
+  event.stopPropagation();event.preventDefault();
+  const p=local(event),points=screenPoints(),current=session.view(),hit=hitMesh(points,current.edges,p,event.pointerType==='touch');
+  const capture=()=>host.pane.setPointerCapture(event.pointerId);
+  if(mode==='modify'){
+   if(hit?.kind==='vertex'){
+    if(event.shiftKey){if(selected.has(hit.v))selected.delete(hit.v);else selected.add(hit.v);host.changed();return;}
+    if(!selected.has(hit.v)){selected.clear();selected.add(hit.v);}
+    drag={pointer:event.pointerId,start:p,ids:[...selected],base:current,ops:[]};capture();host.changed();return;
+   }
+   if(hit?.kind==='edge'){
+    if(event.shiftKey){selected.add(hit.a);selected.add(hit.b);host.changed();return;}
+    if(!(selected.has(hit.a)&&selected.has(hit.b))){selected.clear();selected.add(hit.a);selected.add(hit.b);}
+    drag={pointer:event.pointerId,start:p,ids:[...selected],base:current,ops:[]};capture();host.changed();return;
+   }
+   if(!event.shiftKey)selected.clear();
+   drag={pointer:event.pointerId,start:p,box:p,add:event.shiftKey};capture();host.changed();return;
+  }
+  if(mode==='create'){
+   if(hit?.kind==='vertex'){say('Create: that is a vertex already — click empty space or an edge');return;}
+   const at=toCrop(hit?.kind==='edge'?hit.at:p);if(!at)return;
+   const edge=hit?.kind==='edge'?[hit.a,hit.b] as [number,number]:undefined;after(session.addVertex(at,edge),()=>edge?`edge ${edge[0]}–${edge[1]} split by vertex ${lastAdded()}`:`vertex ${lastAdded()} added`);return;
+  }
+  if(mode==='delete'){
+   if(hit?.kind==='vertex'){const v=hit.v;selected.delete(v);after(session.removeVertex(v),()=>`vertex ${v} removed with its edges`);}
+   else if(hit?.kind==='edge'){const {a,b}=hit;after(session.deleteEdge(a,b),()=>`edge ${a}–${b} removed`);}
+   return;
+  }
+  // Edges
+  if(hit?.kind==='vertex'){
+   if(pending===null||pending===hit.v){pending=pending===hit.v?null:hit.v;say(pending===null?'':`edge from ${hit.v}: click the second vertex`);host.changed();return;}
+   const from=pending,to=hit.v,had=!!session.findEdge(from,to);pending=null;after(session.toggleConstraint(from,to),()=>`constraint edge ${from}–${to} ${had?'removed':'added'}`);return;
+  }
+  if(hit?.kind==='edge'){const {a,b}=hit;pending=null;after(session.toggleConstraint(a,b),()=>`constraint edge ${a}–${b} removed`);return;}
+  pending=null;say('');host.changed();
+ };
+ const move=(event:PointerEvent)=>{
+  if(drag&&event.pointerId===drag.pointer){
+   event.stopPropagation();const p=local(event);
+   if('box' in drag){drag.box=p;host.changed();return;}
+   const m=cropToScreen(),d=m&&screenDeltaToCrop(m,p.x-drag.start.x,p.y-drag.start.y);if(!d||!session)return;
+   drag.ops=session.moveOps(drag.ids,d[0],d[1],drag.base);
+   try{preview=applyMeshOps(session.source,[...session.ops(),...drag.ops]);}catch{preview=null;}
+   host.changed();return;
+  }
+  if(!active||!mode||space||!session)return;
+  const next=hitMesh(screenPoints(),session.view().edges,local(event),event.pointerType==='touch');
+  const key=(h:typeof next)=>h?h.kind==='vertex'?`v${h.v}`:`e${h.a}:${h.b}`:'';
+  if(key(next)!==key(hover)){hover=next;if(next)host.pane.dataset.meshHover=next.kind;else delete host.pane.dataset.meshHover;host.changed();}
+ };
+ const end=(event:PointerEvent)=>{
+  if(!drag||event.pointerId!==drag.pointer)return;const finished=drag;drag=null;preview=null;
+  if(host.pane.hasPointerCapture(event.pointerId))host.pane.releasePointerCapture(event.pointerId);
+  if('box' in finished){
+   if(event.type!=='pointercancel'){const ids=verticesInBox(screenPoints(),finished.start,finished.box);if(!finished.add)selected.clear();for(const v of ids)selected.add(v);}
+   host.changed();return;
+  }
+  if(event.type==='pointercancel'||!session){host.changed();return;}
+  const moved=new Set(finished.ops.map(op=>op.op==='move'?op.v:-1)).size;after(session.record(finished.ops),()=>`moved ${moved} vertex${moved===1?'':'es'}`);
+ };
+ host.pane.addEventListener('pointerdown',down,true);host.pane.addEventListener('pointermove',move,true);
+ for(const type of ['pointerup','pointercancel'] as const)host.pane.addEventListener(type,end,true);
+ document.addEventListener('keydown',keyDown,true);window.addEventListener('keyup',keyUp,true);window.addEventListener('blur',blur);
+ const observer=new MutationObserver(()=>sync());
+ for(const selector of document.querySelectorAll('[data-inspector]'))observer.observe(selector,{attributes:true,attributeFilter:['aria-pressed','aria-selected']});
+ // The chest editor and mesh edit both own the pane's pointer; turning one on turns the other off.
+ const chestObserver=new MutationObserver(()=>{if(active&&chestToggle?.getAttribute('aria-pressed')==='true'){setActive(false);}});
+ if(chestToggle)chestObserver.observe(chestToggle,{attributes:true,attributeFilter:['aria-pressed']});
+ const overlay=():OverlayMeshEdit|null=>{
+  const v=view(),mapping=host.mapping();if(!active||!session||!v||!mapping.available)return null;
+  const world=(p:Vec):OverlayPoint=>mapping.toWorld(p[0],p[1]),s=session.source,source=s.vertices;
+  const hoverKey=hover?.kind==='edge'?`${Math.min(hover.a,hover.b)}:${Math.max(hover.a,hover.b)}`:'';
+  const triangles:OverlayPoint[][]=[];for(let i=0;i+2<s.triangles.length;i+=3){const ids=[s.triangles[i]!,s.triangles[i+1]!,s.triangles[i+2]!];if(ids.every(id=>source[id]))triangles.push(ids.map(id=>world(source[id]!)));}
+  type EdgeRow=OverlayMeshEdit['edges'][number];type VertexRow=OverlayMeshEdit['vertices'][number];
+  const edges:EdgeRow[]=[];
+  for(const e of v.removedEdges){const a=v.vertices[e.a]??source[e.a]??null,b=v.vertices[e.b]??source[e.b]??null;if(a&&b)edges.push({from:world(a),to:world(b),kind:'removed'});}
+  for(const e of v.edges){const a=v.vertices[e.a],b=v.vertices[e.b];if(a&&b)edges.push({from:world(a),to:world(b),kind:e.kind,hover:`${e.a}:${e.b}`===hoverKey});}
+  const ghosts=[...v.moved].flatMap(([id,from])=>{const to=v.vertices[id];return to?[{from:world(from),to:world(to)}]:[];});
+  const vertices=v.vertices.flatMap((p,id):VertexRow[]=>{
+   if(!p){const at=source[id];return at?[{at:world(at),state:'removed',selected:false,hover:false,pending:false}]:[];}
+   return [{at:world(p),state:v.added.has(id)?'added':v.moved.has(id)?'moved':'source',selected:selected.has(id),hover:hover?.kind==='vertex'&&hover.v===id,pending:pending===id}];
+  });
+  const box=drag&&'box' in drag?{from:drag.start,to:drag.box}:undefined;
+  const t=host.token;
+  return {triangles,edges,ghosts,vertices,...(box?{box}:{}),colors:{veil:t('--rv-mesh-veil'),edge:t('--rv-mesh-edge'),hull:t('--rv-mesh-hull'),constraint:t('--rv-mesh-constraint'),removed:t('--rv-mesh-removed'),vertex:t('--rv-mesh-vertex'),ink:t('--rv-mesh-ink'),selected:t('--rv-mesh-selected'),added:t('--rv-mesh-added'),hover:t('--rv-mesh-hover'),box:t('--rv-mesh-box'),boxFill:t('--rv-mesh-box-fill')}};
+ };
+ const selectionChanged=()=>{
+  if(!active||!session)return;const result=host.source();
+  if(!result.ok){leave();sync();host.message(result.code,true);host.changed();return;}
+  if(result.source.slot!==session.source.slot||result.source.attachment!==session.source.attachment||result.source.skin!==session.source.skin){leave();void enter();}
+ };
+ sync();
+ return {
+  active:()=>active,overlay,sync,selectionChanged,session:()=>session,mode:()=>mode,
+  dispose:()=>{observer.disconnect();chestObserver.disconnect();host.pane.removeEventListener('pointerdown',down,true);host.pane.removeEventListener('pointermove',move,true);for(const type of ['pointerup','pointercancel'] as const)host.pane.removeEventListener(type,end,true);document.removeEventListener('keydown',keyDown,true);window.removeEventListener('keyup',keyUp,true);window.removeEventListener('blur',blur);},
+ };
+}
+export {MODELING_INPUT_UNAVAILABLE};

package/web/part-selection.ts

@@ -14,10 +14,12 @@ export function partCatalog(value:unknown,expected:readonly string[]):PartEntry[
  let count=0;for(const [i,v]of model.skins.entries()){const skin=object(v,`skin ${i}`),skinName=name(skin.name,'skin.name');const slots=object(skin.attachments??{},'skin.attachments');for(const [slot,raw]of Object.entries(slots)){const entry=bySlot.get(slot);if(!entry)throw new Error(`Part catalog unknown slot ${slot}`);for(const [attachment,a]of Object.entries(object(raw,'slot attachments'))){if(++count>100000)throw new Error('Part declaration count exceeds 100000');const spec=object(a,'attachment');entry.declarations.push({skin:skinName,attachment:name(attachment,'attachment name'),kind:name(spec.kind,'attachment.kind'),path:typeof spec.path==='string'?name(spec.path,'attachment.path'):null});}}}
  return entries;
 }
-export async function loadPartCatalog(url:string,sha256:string,slots:readonly string[],fetcher:typeof fetch=fetch):Promise<PartEntry[]>{
+export async function loadPartCatalog(url:string,sha256:string,slots:readonly string[],fetcher:typeof fetch=fetch):Promise<PartEntry[]>{return (await loadPartModel(url,sha256,slots,fetcher)).entries;}
+/** The hash-bound catalog plus the parsed model document it was read from (for the page regions thumbnails cut). */
+export async function loadPartModel(url:string,sha256:string,slots:readonly string[],fetcher:typeof fetch=fetch):Promise<{entries:PartEntry[];model:unknown}>{
  const response=await fetcher(url);if(!response.ok)throw new Error('Part catalog model unavailable');const bytes=await response.arrayBuffer();if(bytes.byteLength>128*1024*1024)throw new Error('Part catalog exceeds 128 MiB');
  const hash=[...new Uint8Array(await crypto.subtle.digest('SHA-256',bytes))].map(v=>v.toString(16).padStart(2,'0')).join('');if(hash!==sha256)throw new Error('PART_SOURCE_CHANGED: model bytes differ from reviewed SHA-256');
- return partCatalog(JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(bytes)),slots);
+ const model:unknown=JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(bytes));return {entries:partCatalog(model,slots),model};
 }
 /** Resolve clips on the whole frame first. Filtering player.slots would drop clipping slots. */
 export function selectedFrame(full:PosedFrame,part:ControlPart|null,side:ControlPart['side']):PosedFrame{return part?.side===side&&part.mode==='solo'?{...(full.generation===undefined?{}:{generation:full.generation}),order:full.order.filter(row=>row.slot===part.slot)}:full;}
@@ -92,7 +94,10 @@ export class PartInspection {
 
  feedback():Record<string,Json>|null {const value=this.observation();return value?{...value,identity:value.identity?{...value.identity}:null,activeAttachment:value.activeAttachment?{...value.activeAttachment}:null,bounds:value.bounds?{...value.bounds}:null,declarations:value.declarations.map(item=>({...item}))}:null;}
 }
+/** Draws a row's thumbnail into its icon element, or leaves the type glyph; returns the tooltip note naming which and why. */
+export interface PartThumbnailSource {show(icon:HTMLElement,entry:PartEntry,identity:ControlPartIdentity|null,glyph:string):string}
 export class PartExplorer extends PartInspection {
+ private thumbnails=new Map<ControlPart['side'],PartThumbnailSource>();private rowParts=new Map<HTMLButtonElement,{icon:HTMLElement;label:HTMLElement}>();
  private rows=new Map<string,HTMLButtonElement>();private rowEntries=new Map<HTMLButtonElement,PartEntry>();private detailKey='';private orderKey='';private selectionKey='';
  private detailNodes:{title:HTMLHeadingElement;info:HTMLParagraphElement;declarations:HTMLParagraphElement;bounds:HTMLParagraphElement;unavailable:HTMLParagraphElement;feedback:HTMLButtonElement;status:HTMLParagraphElement}|null=null;
  constructor(private host:HTMLElement,private detail:HTMLElement,private changed:(previous:ControlPart|null)=>void,private target:(part:ControlPart)=>void){
@@ -102,7 +107,7 @@ export class PartExplorer extends PartInspection {
   this.whole.onclick=()=>this.action(()=>this.select(null));this.solo.onchange=()=>this.action(()=>{if(this.selected)this.select({...this.selected,mode:this.solo.checked?'solo':'context'});});this.renderList();this.renderDetail();
  }
  private get search(){return this.host.querySelector<HTMLInputElement>('[data-part-search]')!;}private get list(){return this.host.querySelector<HTMLElement>('[data-part-list]')!;}private get solo(){return this.host.querySelector<HTMLInputElement>('[data-part-solo]')!;}private get whole(){return this.host.querySelector<HTMLButtonElement>('[data-part-whole]')!;}
- register(side:ControlPart['side'],entries:PartEntry[],player:PartPlayer){super.register(side,entries,player);this.renderList();}
+ register(side:ControlPart['side'],entries:PartEntry[],player:PartPlayer,thumbnails?:PartThumbnailSource){super.register(side,entries,player);if(thumbnails)this.thumbnails.set(side,thumbnails);else this.thumbnails.delete(side);this.renderList();}
  refuseCatalog(side:ControlPart['side'],error:unknown):void {super.refuseCatalog(side,error);this.renderList();this.renderDetail();}
  select(value:ControlPart|null):void {const previous=this.value();super.select(value);this.renderSelection();this.renderDetail();this.changed(previous);}
  /** Runs on every drawn frame. The held copy and Solo draw are per frame; the list is rewritten only when what it shows changed. */
@@ -110,10 +115,13 @@ export class PartExplorer extends PartInspection {
  /** Everything the rows and Solo control display: selection, per-side drawn slots in order, and identity. Generation is excluded. */
  private viewKey():string {let key=JSON.stringify([this.selected,[...this.refused]]);for(const [side,state]of this.sides){key+='\u0001'+side+'\u0002'+(state.frame?state.frame.order.map(row=>row.slot).join('\u0000'):'\u0003');for(const row of state.identity?.slots??[])key+='\u0002'+row.slot+'\u0000'+row.z+'\u0000'+row.skin+'\u0000'+row.attachment+'\u0000'+row.reason;}return key;}
  private action(run:()=>void){try{run();}catch(error){this.renderSelection(true);this.host.querySelector<HTMLElement>('[data-part-status]')!.textContent=`Part selection refused: ${error instanceof Error?error.message:String(error)}`;}}
- private renderList(){this.rows.clear();this.rowEntries.clear();this.list.replaceChildren();const query=this.search.value;for(const [side,state]of this.sides)for(const entry of orderedParts(state.entries,state.frame,state.identity)){if(!entry.slot.includes(query))continue;const row=document.createElement('button');row.type='button';row.dataset.side=side;row.dataset.slot=entry.slot;row.title=`${entry.slot} · bone ${entry.bone}`;row.textContent=`${entry.declarations.some(d=>d.kind==='mesh')?'◈':'◇'} ${side==='single'?'':side.toUpperCase()+' · '}${entry.slot}`;row.onclick=()=>this.action(()=>this.select({side,slot:entry.slot,mode:this.selected?.mode??'context'}));const item=document.createElement('li');item.append(row);this.list.append(item);this.rows.set(JSON.stringify([side,entry.slot]),row);this.rowEntries.set(row,entry);}this.orderKey='';this.reorder();this.renderSelection(true);}
+ private renderList(){this.rows.clear();this.rowEntries.clear();this.rowParts.clear();this.list.replaceChildren();const query=this.search.value;for(const [side,state]of this.sides)for(const entry of orderedParts(state.entries,state.frame,state.identity)){if(!entry.slot.includes(query))continue;const row=document.createElement('button');row.type='button';row.dataset.side=side;row.dataset.slot=entry.slot;row.title=`${entry.slot} · bone ${entry.bone}`;const icon=document.createElement('span'),label=document.createElement('span');icon.className='part-thumb';icon.setAttribute('aria-hidden','true');icon.textContent=entry.declarations.some(d=>d.kind==='mesh')?'◈':'◇';label.className='part-label';label.textContent=`${side==='single'?'':side.toUpperCase()+' · '}${entry.slot}`;row.append(icon,label);this.rowParts.set(row,{icon,label});
+   // Selecting the selected slot again (click, or Space/Enter on the focused row) returns to Whole rig.
+   row.onclick=()=>this.action(()=>{const live=this.live();this.select(live?.side===side&&live.slot===entry.slot?null:{side,slot:entry.slot,mode:this.selected?.mode??'context'});});const item=document.createElement('li');item.append(row);this.list.append(item);this.rows.set(JSON.stringify([side,entry.slot]),row);this.rowEntries.set(row,entry);}this.orderKey='';this.reorder();this.renderSelection(true);}
  private statusText():string {const refused=[...this.refused].map(([side,r])=>`${side==='single'?'':side.toUpperCase()+' '}${r.code}`);if(refused.length)return `Parts unavailable · ${refused.join(' · ')}. The rig keeps drawing whole; selection, Solo and feedback targeting are off ${[...this.refused.values()].some(r=>r.catalog)?'until the package reloads with a matching catalog':'until a frame with a valid identity snapshot'}.`;return this.sides.size?`${[...this.sides.values()].reduce((n,s)=>n+s.entries.length,0)} declared slots · ${this.rows.size} results`:'No compiled rig catalog available';}
  private reorder(){const keys=[...this.sides].flatMap(([side,state])=>orderedParts(state.entries,state.frame,state.identity).map(entry=>JSON.stringify([side,entry.slot]))).filter(key=>this.rows.has(key)),key=JSON.stringify(keys);if(key===this.orderKey)return;this.orderKey=key;const active=document.activeElement;for(const item of keys){const row=this.rows.get(item)!;this.list.append(row.parentElement!);}if(active instanceof HTMLElement&&this.list.contains(active)&&document.activeElement!==active)active.focus({preventScroll:true});}
- private renderSelection(force=false){const key=this.viewKey();if(!force&&key===this.selectionKey)return;this.selectionKey=key;const status=this.host.querySelector<HTMLElement>('[data-part-status]')!;status.textContent=this.statusText();if(this.refused.size)this.host.dataset.parts='unavailable';else delete this.host.dataset.parts;const drawnBySide=new Map([...this.sides].map(([side,state])=>[side,new Set(state.frame?.order.map(row=>row.slot)??[])]));this.whole.setAttribute('aria-pressed',String(!this.selected));this.solo.disabled=!this.live();this.solo.checked=this.live()?.mode==='solo';for(const [key,row]of this.rows){row.setAttribute('aria-pressed',String(key===JSON.stringify([this.live()?.side,this.live()?.slot])));const refusal=this.refused.get(row.dataset.side as ControlPart['side']);row.disabled=!!refusal;if(refusal){const label=`${row.dataset.side==='single'?'':row.dataset.side!.toUpperCase()+' · '}${row.dataset.slot} · parts unavailable · ${refusal.code}`;if(row.textContent!==label)row.textContent=label;row.title=label;row.setAttribute('aria-label',label);row.dataset.drawn='false';continue;}const state=this.sides.get(row.dataset.side as ControlPart['side']);const drawn=drawnBySide.get(row.dataset.side as ControlPart['side'])?.has(row.dataset.slot!);row.dataset.drawn=String(!!drawn);const entry=this.rowEntries.get(row),identity=entry?partIdentity(state?.identity??null,row.dataset.slot!):null;row.title=`${row.dataset.slot} · ${state?.frame?drawn?'drawn':'not drawn':'awaiting draw'}${identity?identity.reason?' · '+identity.reason:' · '+identity.skin+' / '+identity.attachment:' · awaiting identity snapshot'}`;const label=`${entry?.declarations.some(d=>d.kind==='mesh')?'◈':'◇'} ${row.dataset.side==='single'?'':row.dataset.side!.toUpperCase()+' · '}${row.dataset.slot} · ${state?.frame?drawn?'drawn':'not drawn':'awaiting draw'} · ${identity?identity.reason?'no active attachment · '+identity.reason:identity.skin+' / '+identity.attachment:'awaiting identity snapshot'}`;if(row.textContent!==label)row.textContent=label;row.setAttribute('aria-label',`${row.textContent} · ${state?.frame?drawn?'drawn':'not drawn':'awaiting draw'}`);}}
+ private renderSelection(force=false){const key=this.viewKey();if(!force&&key===this.selectionKey)return;this.selectionKey=key;const status=this.host.querySelector<HTMLElement>('[data-part-status]')!;status.textContent=this.statusText();if(this.refused.size)this.host.dataset.parts='unavailable';else delete this.host.dataset.parts;const drawnBySide=new Map([...this.sides].map(([side,state])=>[side,new Set(state.frame?.order.map(row=>row.slot)??[])]));this.whole.setAttribute('aria-pressed',String(!this.selected));this.solo.disabled=!this.live();this.solo.checked=this.live()?.mode==='solo';for(const [key,row]of this.rows){row.setAttribute('aria-pressed',String(key===JSON.stringify([this.live()?.side,this.live()?.slot])));const refusal=this.refused.get(row.dataset.side as ControlPart['side']);row.disabled=!!refusal;const parts=this.rowParts.get(row)!;if(refusal){const label=`${row.dataset.side==='single'?'':row.dataset.side!.toUpperCase()+' · '}${row.dataset.slot} · parts unavailable · ${refusal.code}`;if(parts.label.textContent!==label){parts.label.textContent=label;parts.icon.textContent='';delete parts.icon.dataset.thumbnailPlan;}row.title=label;row.setAttribute('aria-label',label);row.dataset.drawn='false';continue;}const state=this.sides.get(row.dataset.side as ControlPart['side']);const drawn=drawnBySide.get(row.dataset.side as ControlPart['side'])?.has(row.dataset.slot!);row.dataset.drawn=String(!!drawn);const entry=this.rowEntries.get(row),identity=entry?partIdentity(state?.identity??null,row.dataset.slot!):null;const glyph=entry?.declarations.some(d=>d.kind==='mesh')?'◈':'◇',source=this.thumbnails.get(row.dataset.side as ControlPart['side']),note=entry&&source?source.show(parts.icon,entry,identity,glyph):null;if(!note&&parts.icon.textContent!==glyph){parts.icon.textContent=glyph;delete parts.icon.dataset.thumbnailPlan;}
+   row.title=`${row.dataset.slot} · ${state?.frame?drawn?'drawn':'not drawn':'awaiting draw'}${identity?identity.reason?' · '+identity.reason:' · '+identity.skin+' / '+identity.attachment:' · awaiting identity snapshot'}${note?' · '+note:''}`;const label=`${row.dataset.side==='single'?'':row.dataset.side!.toUpperCase()+' · '}${row.dataset.slot} · ${state?.frame?drawn?'drawn':'not drawn':'awaiting draw'} · ${identity?identity.reason?'no active attachment · '+identity.reason:identity.skin+' / '+identity.attachment:'awaiting identity snapshot'}`;if(parts.label.textContent!==label)parts.label.textContent=label;row.setAttribute('aria-label',`${glyph} ${label} · ${state?.frame?drawn?'drawn':'not drawn':'awaiting draw'}`);}}
  private renderDetail(){
   const observation=this.observation(),refusal=this.selected?this.refused.get(this.selected.side):[...this.refused.values()][0],key=JSON.stringify([observation,refusal??null]);if(key===this.detailKey)return;this.detailKey=key;
   // Keep focused controls connected while the selected pose's bounds animate.

package/web/part-thumbnails.ts

@@ -0,0 +1,76 @@
+/** Slot thumbnails cut from the actual page images by the region the compiled model declares for the drawn attachment.
+ * Nothing is inferred from the art: an attachment without a declared, unrotated page region shows its type icon and a
+ * named reason, and a whole page is never shown as a part. */
+import type {ControlPartIdentity} from '../src/control.ts';
+import type {PartEntry,PartThumbnailSource} from './part-selection.ts';
+
+export interface PageRegion {page:string;name:string;x:number;y:number;width:number;height:number;degrees:number}
+export interface PageRegionTable {pages:Map<string,{width:number;height:number}>;regions:Map<string,PageRegion[]>;absent:string|null}
+/** The source rectangle on the page, as page UVs (the page spanning [0, 1]) and as page pixels derived from them. */
+export interface ThumbnailCrop {kind:'crop';key:string;page:string;region:string;u0:number;v0:number;u1:number;v1:number;sx:number;sy:number;sw:number;sh:number}
+export interface ThumbnailIcon {kind:'icon';key:string;reason:string}
+export type ThumbnailPlan=ThumbnailCrop|ThumbnailIcon;
+/** CSS box edge; the canvas backing store is twice that. */
+export const thumbnailBox=24,thumbnailScale=2;
+
+const record=(v:unknown):Record<string,unknown>|null=>v&&typeof v==='object'&&!Array.isArray(v)?v as Record<string,unknown>:null;
+const finite=(v:unknown,min:number):v is number=>typeof v==='number'&&Number.isFinite(v)&&v>=min;
+/** Reads `pages[].regions[]` of a `rigc-compiled/3` document. A malformed entry is dropped (its attachment shows the icon), never repaired. */
+export function pageRegionTable(model:unknown):PageRegionTable {
+ const pages=new Map<string,{width:number;height:number}>(),regions=new Map<string,PageRegion[]>(),list=record(model)?.pages;
+ if(!Array.isArray(list))return {pages,regions,absent:'the model has no pages section'};
+ for(const raw of list.slice(0,256)){
+  const page=record(raw);if(!page||typeof page.name!=='string'||!finite(page.width,1)||!finite(page.height,1)||!Array.isArray(page.regions))continue;
+  pages.set(page.name,{width:page.width,height:page.height});
+  for(const value of page.regions.slice(0,100000)){const r=record(value);if(!r||typeof r.name!=='string'||!finite(r.x,0)||!finite(r.y,0)||!finite(r.width,1)||!finite(r.height,1))continue;const region:PageRegion={page:page.name,name:r.name,x:r.x,y:r.y,width:r.width,height:r.height,degrees:typeof r.degrees==='number'?r.degrees:0};regions.set(r.name,[...regions.get(r.name)??[],region]);}
+ }
+ return {pages,regions,absent:null};
+}
+/** What a row shows for the attachment the held public identity says is active. */
+export function thumbnailPlan(table:PageRegionTable,entry:PartEntry,identity:ControlPartIdentity|null):ThumbnailPlan {
+ if(!identity)return {kind:'icon',key:'',reason:'awaiting identity snapshot'};
+ if(identity.reason!==null||identity.attachment===null||identity.skin===null)return {kind:'icon',key:'',reason:`no active attachment (${identity.reason??'none'})`};
+ const key=JSON.stringify([identity.skin,identity.attachment]),declaration=entry.declarations.find(d=>d.skin===identity.skin&&d.attachment===identity.attachment);
+ if(!declaration)return {kind:'icon',key,reason:`THUMBNAIL_UNDECLARED: ${identity.skin} / ${identity.attachment} is not in the catalog`};
+ if(declaration.kind!=='region'&&declaration.kind!=='mesh')return {kind:'icon',key,reason:`${declaration.kind} attachment draws no page image`};
+ if(table.absent)return {kind:'icon',key,reason:`THUMBNAIL_REGION_UNAVAILABLE: ${table.absent}`};
+ const name=declaration.path??declaration.attachment,found=table.regions.get(name)??[];
+ if(!found.length)return {kind:'icon',key,reason:`THUMBNAIL_NO_PAGE_REGION: the model declares no page region "${name}"`};
+ if(found.length>1)return {kind:'icon',key,reason:`THUMBNAIL_AMBIGUOUS_REGION: ${found.length} page regions are named "${name}" (sequence frames)`};
+ const region=found[0]!,page=table.pages.get(region.page)!;
+ if(region.degrees!==0)return {kind:'icon',key,reason:`THUMBNAIL_ROTATED_REGION: "${name}" is packed at ${region.degrees}°`};
+ if(region.x+region.width>page.width||region.y+region.height>page.height)return {kind:'icon',key,reason:`THUMBNAIL_REGION_OUTSIDE_PAGE: "${name}" exceeds ${region.page}`};
+ const u0=region.x/page.width,v0=region.y/page.height,u1=(region.x+region.width)/page.width,v1=(region.y+region.height)/page.height;
+ // Page pixels back from the UVs, rounded off float residue (a region edge sits on a whole or half texel).
+ const px=(value:number)=>Math.round(value*1e6)/1e6;
+ return {kind:'crop',key,page:region.page,region:name,u0,v0,u1,v1,sx:px(u0*page.width),sy:px(v0*page.height),sw:px((u1-u0)*page.width),sh:px((v1-v0)*page.height)};
+}
+/** Destination rectangle on the backing store: the crop fitted inside the box, aspect kept, centred. */
+export function thumbnailFit(sw:number,sh:number,size=thumbnailBox*thumbnailScale):{dx:number;dy:number;dw:number;dh:number} {
+ const scale=Math.min(size/sw,size/sh),dw=sw*scale,dh=sh*scale;return {dx:(size-dw)/2,dy:(size-dh)/2,dw,dh};
+}
+type PageImage=CanvasImageSource&{complete?:boolean;naturalWidth?:number};
+/** Lazy (IntersectionObserver) drawing, one cached bitmap per attachment key. */
+export class PartThumbnails implements PartThumbnailSource {
+ private cache=new Map<string,HTMLCanvasElement>();private pending=new Map<Element,ThumbnailCrop>();private observer:IntersectionObserver|null=null;
+ constructor(private table:PageRegionTable,private images:ReadonlyMap<string,PageImage>){
+  if(typeof IntersectionObserver==='function')this.observer=new IntersectionObserver(items=>{for(const item of items)if(item.isIntersecting){const plan=this.pending.get(item.target);this.observer?.unobserve(item.target);this.pending.delete(item.target);if(plan)this.paint(item.target as HTMLCanvasElement,plan);}});
+ }
+ show(icon:HTMLElement,entry:PartEntry,identity:ControlPartIdentity|null,glyph:string):string {
+  const plan=thumbnailPlan(this.table,entry,identity),image=plan.kind==='crop'?this.images.get(plan.page):undefined;
+  const shown:ThumbnailPlan=plan.kind==='crop'&&!image?{kind:'icon',key:plan.key,reason:`THUMBNAIL_PAGE_UNAVAILABLE: page ${plan.page} is not loaded`}:plan;
+  const stamp=JSON.stringify(shown);
+  if(icon.dataset.thumbnailPlan!==stamp){
+   icon.dataset.thumbnailPlan=stamp;for(const child of icon.querySelectorAll('canvas')){this.observer?.unobserve(child);this.pending.delete(child);}
+   if(shown.kind==='crop'){const canvas=document.createElement('canvas');canvas.width=canvas.height=thumbnailBox*thumbnailScale;canvas.setAttribute('aria-hidden','true');icon.replaceChildren(canvas);icon.dataset.thumbnail='image';if(this.observer){this.pending.set(canvas,shown);this.observer.observe(canvas);}else this.paint(canvas,shown);}
+   else{icon.textContent=glyph;icon.dataset.thumbnail='icon';}
+  }
+  return shown.kind==='crop'?`thumbnail: region ${shown.region} on ${shown.page}`:`type icon: ${shown.reason}`;
+ }
+ private paint(canvas:HTMLCanvasElement,plan:ThumbnailCrop):void {
+  let source=this.cache.get(plan.key);
+  if(!source){const image=this.images.get(plan.page);if(!image)return;source=document.createElement('canvas');source.width=source.height=thumbnailBox*thumbnailScale;const fit=thumbnailFit(plan.sw,plan.sh);source.getContext('2d')?.drawImage(image,plan.sx,plan.sy,plan.sw,plan.sh,fit.dx,fit.dy,fit.dw,fit.dh);this.cache.set(plan.key,source);}
+  const context=canvas.getContext('2d');if(!context)return;context.clearRect(0,0,canvas.width,canvas.height);context.drawImage(source,0,0);
+ }
+ dispose():void {this.observer?.disconnect();this.pending.clear();this.cache.clear();}
+}

package/web/rig-overlays.ts

@@ -14,7 +14,35 @@ export interface OverlaySnapshot {
  available:boolean;needsCapture:boolean;meshEdges:number;boneCount:number;
  capabilities:{images:boolean;mesh:boolean;bones:boolean};warnings:string[];
 }
-export interface OverlayView {project:OverlayProject;settings:RigOverlaySettings;dpr?:number}
+/** Designation polygons in rig world coordinates (Setup's Chest regions tool); colours are theme token values. */
+export interface OverlayRegion {name:string;points:OverlayPoint[];stroke:string;fill:string}
+/**
+ * A circle designation in rig world units (crop px = world px under the crop mapping): core r at full weight, dashed
+ * outer circle at r + band. With handles it is the chest editor's drawing (centre, core edge on the right, band on
+ * top, a label under the outer circle). Colours are theme token values.
+ */
+export interface OverlayCircle {center:OverlayPoint;r:number;band:number;label?:string;/** Label rows below the outer circle, so two labels never overlap. */labelRow?:number;handles:boolean;flash?:boolean;colors:{stroke:string;fill:string;handle:string;ink:string;labelBg:string;flash:string}}
+/**
+ * Mesh edit preview in rig world coordinates: the selected slot's original triangles (cut out of the veil that dims the
+ * rest of the rig), the edges after the delta by kind, moved-vertex ghosts and the vertices as handles. A box is in
+ * canvas px. It is drawn over the original triangulation; nothing here retriangulates. Colours are theme token values.
+ */
+export interface OverlayMeshEdit {
+ triangles:readonly OverlayPoint[][];
+ edges:readonly {from:OverlayPoint;to:OverlayPoint;kind:'hull'|'interior'|'constraint'|'removed';hover?:boolean}[];
+ ghosts:readonly {from:OverlayPoint;to:OverlayPoint}[];
+ vertices:readonly {at:OverlayPoint;state:'source'|'moved'|'added'|'removed';selected:boolean;hover:boolean;pending:boolean}[];
+ box?:{from:OverlayPoint;to:OverlayPoint};
+ colors:{veil:string;edge:string;hull:string;constraint:string;removed:string;vertex:string;ink:string;selected:string;added:string;hover:string;box:string;boxFill:string};
+}
+export interface OverlayView {project:OverlayProject;settings:RigOverlaySettings;dpr?:number;regions?:readonly OverlayRegion[];circles?:readonly OverlayCircle[];meshEdit?:OverlayMeshEdit|null}
+/** Canvas-pixel geometry of a circle designation, the same numbers the editor hit-tests against. */
+export function projectCircle(project:OverlayProject,circle:Pick<OverlayCircle,'center'|'r'|'band'>):{center:OverlayPoint;pxR:number;pxBand:number}|null {
+ const {x,y}=circle.center,center=project(x,y),edge=project(x+circle.r,y),top=project(x,y+circle.r+circle.band);
+ if(![center,edge,top].every(finite))return null;
+ const pxR=Math.max(2,Math.hypot(edge.x-center.x,edge.y-center.y));
+ return {center,pxR,pxBand:Math.max(pxR+2,Math.hypot(top.x-center.x,top.y-center.y))};
+}
 export interface OverlayRefresh extends OverlayView {player:OverlayPlayer|null;bones:readonly BoneOverlaySpec[];frame?:PosedFrame;selectedSlot?:string|null}
 const point=(x:number,y:number):OverlayPoint=>({x,y});
 const finite=(p:OverlayPoint)=>Number.isFinite(p.x)&&Number.isFinite(p.y);
@@ -91,7 +119,7 @@ export class RigOverlays {
   this.geometry=input.player?captureRigGeometry(input.player,input.bones,input.settings,input.frame,input.selectedSlot):null;
   return this.redraw(input);
  }
- redraw({project,settings,dpr=globalThis.devicePixelRatio??1}:OverlayView):OverlaySnapshot{
+ redraw({project,settings,dpr=globalThis.devicePixelRatio??1,regions=[],circles=[],meshEdit=null}:OverlayView):OverlaySnapshot{
   if(this.disposed)return this.unavailable('Overlay has been disposed');
   this.host.rigRoot.style.visibility=settings.images?this.visibility:'hidden';
   const warnings=[...(this.geometry?.warnings??[])],ctx=this.host.canvas.getContext('2d');
@@ -132,10 +160,53 @@ export class RigOverlays {
     ctx.fillStyle='#ffe26b';ctx.strokeStyle='#44310d';ctx.lineWidth=1;ctx.beginPath();ctx.arc(center.x,center.y,2.8,0,Math.PI*2);ctx.fill();ctx.stroke();
    }
   }
-  if(this.geometry?.selection.length){ctx.globalAlpha=1;ctx.strokeStyle='#ffbb47';ctx.lineWidth=2;ctx.setLineDash([5,3]);ctx.beginPath();for(const edge of this.geometry.selection)line(edge);ctx.stroke();ctx.setLineDash([]);}
+  // Designations are drawn over the drawn rig only; they are values the reviewer typed, not rig geometry.
+  if(this.playerAvailable)for(const region of regions){
+   const points=region.points.map(projected);if(points.length<3||points.some(p=>!p))continue;
+   ctx.globalAlpha=1;ctx.setLineDash([]);ctx.beginPath();ctx.moveTo(points[0]!.x,points[0]!.y);for(const p of points.slice(1))ctx.lineTo(p!.x,p!.y);ctx.closePath();
+   ctx.fillStyle=region.fill;ctx.fill();ctx.strokeStyle=region.stroke;ctx.lineWidth=1.6;ctx.stroke();
+  }
+  if(this.playerAvailable)for(const circle of circles){
+   const at=projectCircle(project,circle);if(!at)continue;const {center,pxR,pxBand}=at,c=circle.colors;
+   ctx.globalAlpha=.95;
+   ctx.beginPath();ctx.setLineDash([5,4]);ctx.strokeStyle=c.stroke;ctx.lineWidth=1.6;ctx.arc(center.x,center.y,pxBand,0,Math.PI*2);ctx.stroke();
+   ctx.beginPath();ctx.setLineDash([]);ctx.fillStyle=c.fill;ctx.lineWidth=2.2;ctx.arc(center.x,center.y,pxR,0,Math.PI*2);ctx.fill();ctx.stroke();
+   if(!circle.handles)continue;
+   ctx.globalAlpha=1;
+   ctx.beginPath();ctx.moveTo(center.x-7,center.y);ctx.lineTo(center.x+7,center.y);ctx.moveTo(center.x,center.y-7);ctx.lineTo(center.x,center.y+7);ctx.stroke();
+   for(const [x,y,fill,stroke] of [[center.x,center.y,c.handle,c.stroke],[center.x+pxR,center.y,c.stroke,c.ink],[center.x,center.y-pxBand,c.ink,c.stroke]] as const){ctx.beginPath();ctx.fillStyle=fill;ctx.strokeStyle=stroke;ctx.lineWidth=2;ctx.arc(x,y,4.5,0,Math.PI*2);ctx.fill();ctx.stroke();}
+   if(circle.label){
+    ctx.font='600 11px ui-monospace, monospace';const width=ctx.measureText(circle.label).width+8,lx=center.x-width/2,ly=center.y+pxBand+14+(circle.labelRow??0)*17;
+    ctx.fillStyle=circle.flash?c.flash:c.labelBg;ctx.fillRect(lx,ly-11,width,15);ctx.fillStyle=circle.flash?c.ink:c.stroke;ctx.fillText(circle.label,lx+4,ly);
+   }
+  }
+  ctx.globalAlpha=1;
+  if(this.playerAvailable&&meshEdit)this.drawMeshEdit(ctx,meshEdit,projected,width,height);
+  if(this.geometry?.selection.length&&!meshEdit){ctx.globalAlpha=1;ctx.strokeStyle='#ffbb47';ctx.lineWidth=2;ctx.setLineDash([5,3]);ctx.beginPath();for(const edge of this.geometry.selection)line(edge);ctx.stroke();ctx.setLineDash([]);}
   ctx.restore();
   return this.snapshot(true,needsCapture,warnings);
  }
+ private drawMeshEdit(ctx:CanvasRenderingContext2D,edit:OverlayMeshEdit,projected:(p:OverlayPoint)=>OverlayPoint|null,width:number,height:number):void{
+  const c=edit.colors;ctx.save();ctx.globalAlpha=1;ctx.setLineDash([]);
+  // The rest of the rig dims; the edited slot's own triangles are cut out of the veil so its art stays at full opacity.
+  ctx.fillStyle=c.veil;ctx.fillRect(0,0,width,height);
+  ctx.globalCompositeOperation='destination-out';ctx.fillStyle=c.ink;ctx.beginPath();
+  for(const triangle of edit.triangles){const points=triangle.map(projected);if(points.length<3||points.some(p=>!p))continue;ctx.moveTo(points[0]!.x,points[0]!.y);for(const p of points.slice(1))ctx.lineTo(p!.x,p!.y);ctx.closePath();}
+  ctx.fill();ctx.globalCompositeOperation='source-over';
+  const segment=(from:OverlayPoint,to:OverlayPoint)=>{const a=projected(from),b=projected(to);if(a&&b){ctx.moveTo(a.x,a.y);ctx.lineTo(b.x,b.y);}};
+  const stroke=(kind:OverlayMeshEdit['edges'][number]['kind'],color:string,width:number,dash:number[]=[])=>{ctx.beginPath();ctx.setLineDash(dash);ctx.strokeStyle=color;ctx.lineWidth=width;for(const e of edit.edges)if(e.kind===kind)segment(e.from,e.to);ctx.stroke();};
+  stroke('removed',c.removed,1.4,[4,3]);stroke('interior',c.edge,1);stroke('constraint',c.constraint,2.4);stroke('hull',c.hull,2.2);
+  ctx.beginPath();ctx.setLineDash([2,3]);ctx.strokeStyle=c.ink;ctx.lineWidth=1;for(const g of edit.ghosts)segment(g.from,g.to);ctx.stroke();
+  ctx.beginPath();ctx.setLineDash([]);ctx.strokeStyle=c.hover;ctx.lineWidth=3.2;for(const e of edit.edges)if(e.hover)segment(e.from,e.to);ctx.stroke();
+  for(const v of edit.vertices){
+   const p=projected(v.at);if(!p)continue;
+   if(v.state==='removed'){ctx.beginPath();ctx.strokeStyle=c.removed;ctx.lineWidth=1.6;ctx.moveTo(p.x-4,p.y-4);ctx.lineTo(p.x+4,p.y+4);ctx.moveTo(p.x+4,p.y-4);ctx.lineTo(p.x-4,p.y+4);ctx.stroke();continue;}
+   const r=v.selected?4.6:3.4;ctx.beginPath();ctx.fillStyle=v.selected?c.selected:v.state==='added'?c.added:c.vertex;ctx.strokeStyle=v.state==='moved'?c.selected:c.ink;ctx.lineWidth=v.state==='moved'?2:1.2;ctx.arc(p.x,p.y,r,0,Math.PI*2);ctx.fill();ctx.stroke();
+   if(v.hover||v.pending){ctx.beginPath();ctx.strokeStyle=v.pending?c.constraint:c.hover;ctx.lineWidth=2;ctx.arc(p.x,p.y,7.5,0,Math.PI*2);ctx.stroke();}
+  }
+  if(edit.box){const {from,to}=edit.box,x=Math.min(from.x,to.x),y=Math.min(from.y,to.y),w=Math.abs(to.x-from.x),h=Math.abs(to.y-from.y);ctx.fillStyle=c.boxFill;ctx.fillRect(x,y,w,h);ctx.setLineDash([4,3]);ctx.strokeStyle=c.box;ctx.lineWidth=1;ctx.strokeRect(x+.5,y+.5,w,h);}
+  ctx.restore();
+ }
  clear():void{
   this.geometry=null;this.playerAvailable=false;
   const ctx=this.host.canvas.getContext('2d');if(ctx){ctx.save();ctx.setTransform(1,0,0,1,0,0);ctx.clearRect(0,0,this.host.canvas.width,this.host.canvas.height);ctx.restore();}