@rig-c/review 0.10.4 → 0.11.0

package/web/mesh-editor.ts

@@ -1,8 +1,8 @@
 /**
  * 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. The mesh is the slot's attachment in the compiled
- * model document at the **setup pose** (#100): the stored vertices placed through the setup-pose bones of a never-played
- * player (`web/setup-pose.ts`, shared with Setup · Weights) and drawn over the stage with the stage's own camera — the
+ * model document at the **setup pose** (#100): Play's public readSetupMesh coordinates, topology and hull
+ * (`web/setup-pose.ts`, shared with Setup · Weights), drawn over the stage with the stage's own camera — the
  * stage itself stays paused at the pose it held, under the veil. Everything is a typed delta (`src/mesh-edit.ts`,
  * `basis: "setup"`) previewed over the original triangulation; nothing is retriangulated or written into the package
  * from here. Apply · Rebuild (#135) hands the exported document to the host, which sends it through the shared runner as
@@ -11,7 +11,7 @@
  * inspected build, and the local draft keeps the applied delta (edits over the revision are not written to it).
  */
 import type {CropWorldMapping} from '../src/chest-regions.ts';
-import {placeSetupMesh,readSetupMesh,setupModel} from '../src/setup-mesh.ts';
+import {readStoredSetupMesh,setupModel} from '../src/setup-mesh.ts';
 import {
  MESH_EDIT_CODES,MESH_EDIT_NO_MESH,MESH_EDIT_PREVIEW_NOTE,MESH_EDIT_RIG_UNAVAILABLE,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,
@@ -56,7 +56,7 @@ export function cropFromWorld(mapping:Extract<CropWorldMapping,{available:true}>
 type SourceResult={ok:true;source:Omit<MeshSource,'hash'>;entry:unknown;world:number[]}|{ok:false;code:string};
 /**
  * The selected slot's mesh in setup space: its attachment's entry in the hash-verified compiled model document (the
- * attachment the setup pose resolves), its stored vertices placed through the setup-pose bones (`world`, flat x, y)
+ * attachment the public setup identity resolves), its public readSetupMesh vertices (`world`, flat x, y)
  * and mapped to crop px. Refuses, in order: no model document (`MESH_EDIT_MODEL_UNAVAILABLE`), whole rig, no setup pose,
  * a non-mesh or linked attachment, no crop mapping.
  */
@@ -66,17 +66,18 @@ export function meshEditSource(input:{slot:string|null;model:unknown;pose:(slot:
  let pose:SetupPose|null;
  try{pose=input.pose(slot);}catch(error){return {ok:false,code:`${MESH_EDIT_RIG_UNAVAILABLE}: ${error instanceof Error?error.message:String(error)}`};}
  if(!pose)return {ok:false,code:`${MESH_EDIT_RIG_UNAVAILABLE}: no rig loaded`};
- const read=readSetupMesh(input.model,slot,pose.identity,MESH_EDIT_CODES);if(!read.ok)return read;
+ const read=readStoredSetupMesh(input.model,slot,pose.identity,MESH_EDIT_CODES);if(!read.ok)return !pose.identity&&pose.reason?{ok:false,code:`${read.code} (${pose.reason})`}:read;
  const mesh=read.mesh,noMesh=(why:string)=>({ok:false as const,code:`${MESH_EDIT_NO_MESH} ${slot}: ${why}`});
  if(mesh.linked)return noMesh(`${mesh.skin} / ${mesh.attachment} is a linked mesh of ${mesh.source.slot} / ${mesh.source.attachment}; edit its source mesh`);
- if(mesh.hull===null)return noMesh('the model entry stores no hull');
  if(!input.mapping.available)return {ok:false,code:`${input.mapping.reason}: mesh edit needs the crop mapping`};
- let world:number[]|null;
- try{world=placeSetupMesh(mesh,pose.world);}catch(error){return {ok:false,code:`${MESH_EDIT_RIG_UNAVAILABLE}: ${error instanceof Error?error.message:String(error)}`};}
- if(!world)return {ok:false,code:`MESH_EDIT_SOURCE_MISMATCH: ${slot} has a non-finite setup-pose vertex`};
+ let geometry:ReturnType<SetupPose['readMesh']>;
+ try{geometry=pose.readMesh();}catch(error){return {ok:false,code:`${MESH_EDIT_RIG_UNAVAILABLE}: ${error instanceof Error?error.message:String(error)}`};}
+ if(!geometry||geometry.slot!==slot||geometry.skin!==mesh.skin||geometry.attachment!==mesh.attachment||geometry.vertices.length!==mesh.vertices.length*2)return {ok:false,code:`MESH_EDIT_SOURCE_MISMATCH: ${slot} setup geometry does not match its stored identity or vertex count`};
+ if(geometry.hull===null)return noMesh('the model entry stores no hull');
+ const world=geometry.vertices;
  const toCrop=cropFromWorld(input.mapping);if(!toCrop)return {ok:false,code:'MESH_EDIT_MAPPING_SINGULAR'};
  const vertices:Vec[]=[];for(let i=0;i<world.length;i+=2)vertices.push(toCrop(world[i]!,world[i+1]!));
- return {ok:true,source:{slot,skin:mesh.skin,attachment:mesh.attachment,vertices,triangles:mesh.triangles,hull:mesh.hull},entry:mesh.entry,world};
+ return {ok:true,source:{slot,skin:mesh.skin,attachment:mesh.attachment,vertices,triangles:geometry.triangles,hull:geometry.hull},entry:mesh.entry,world};
 }
 /** Apply · Rebuild with an empty delta: nothing is sent. */
 export const MESH_EDIT_NOTHING_PENDING='MESH_EDIT_NOTHING_PENDING: the delta holds no op; nothing is sent';

package/web/physics-panel.ts

@@ -6,6 +6,7 @@
  */
 import {applyRamp,componentValue,draftEdits,draftText,nearestChain,patchOps,physicsChains,rowControls,setEdit,TUNING_FIELDS,COMPONENT_FIELDS,type PendingEdit,type PhysicsChain,type PhysicsField,type TuningRow,type TuningTable} from '../src/physics-tuning.ts';
 import type {PatchOp} from '../src/config-patch.ts';
+import type {PhysicsPreviewRead} from './preview.ts';
 
 export interface PhysicsPanelDeps {
  apply:(ops:PatchOp[])=>Promise<void>;
@@ -15,6 +16,9 @@ export interface PhysicsPanelDeps {
  pane:HTMLElement;
  /** The draft record changed (the panel already wrote `#physics-pending`). */
  saved:()=>void;
+ /** Pending six-field overrides only; the caller uses Play's public live API. */
+ preview:(edits:readonly PendingEdit[])=>PhysicsPreviewRead[];
+ previewRead:()=>PhysicsPreviewRead[];
 }
 export interface PhysicsPanel {
  load(table:TuningTable,bones:readonly {name:string;parent?:string|null}[]):void;
@@ -23,6 +27,7 @@ export interface PhysicsPanel {
  ramp(chainId:string,field:PhysicsField,root:number,tip:number):void;
  select(name:string):void;
  restore():void;clear():void;
+ clearPreview():void;refreshPreview():void;
  applied(ops:readonly PatchOp[]|null):void;
  status(text:string,error:boolean):void;
  readout(lines:{name:string;before:string;after:string}[]):void;
@@ -38,15 +43,31 @@ export function bindPhysicsPanel(deps:PhysicsPanelDeps):PhysicsPanel {
  const state=node('physics-panel-state'),rowsArea=node('physics-rows'),editor=node('physics-row-editor'),locked=node('physics-locked'),pending=node('physics-pending-list');
  const chainSelect=node<HTMLSelectElement>('physics-chain'),pick=node<HTMLButtonElement>('physics-chain-pick'),rampField=node<HTMLSelectElement>('physics-ramp-field'),rampRoot=node<HTMLInputElement>('physics-ramp-root'),rampTip=node<HTMLInputElement>('physics-ramp-tip'),rampButton=node<HTMLButtonElement>('physics-ramp');
  const applyButton=node<HTMLButtonElement>('physics-apply'),resetButton=node<HTMLButtonElement>('physics-reset-build'),status=node('physics-apply-status'),readoutArea=node('physics-readout'),draft=node<HTMLTextAreaElement>('physics-pending');
+ const previewBox=document.querySelector<HTMLInputElement>('#physics-panel [data-physics-preview]')!,previewClear=node<HTMLButtonElement>('physics-preview-clear'),previewLabel=node('physics-preview-label');
  let table:TuningRow[]=[],chains:PhysicsChain[]=[],edits=new Map<string,PendingEdit>(),selected:string|null=null,appliedOps:string[]=[],busy=false,picking=false;
  rampField.replaceChildren(...[...TUNING_FIELDS,...COMPONENT_FIELDS].map(f=>make('option',{value:f,textContent:f})));
  rampField.value='damping';
 
  const save=()=>{draft.value=draftText(edits);draft.dispatchEvent(new Event('input',{bubbles:true}));deps.saved();};
- const change=(next:Map<string,PendingEdit>)=>{edits=next;save();render();};
+ let previewActive=false;
+ const change=(next:Map<string,PendingEdit>,live=false)=>{edits=next;save();drivePreview();if(live){renderRows();renderPending();}else render();};
  const tryChange=(make:()=>Map<string,PendingEdit>)=>{try{change(make());}catch(error){panelStatus(error instanceof Error?error.message:String(error),true);}};
  function panelStatus(text:string,error:boolean){status.textContent=text;status.title=text;status.classList.toggle('error',error);}
  const row=(name:string)=>table.find(r=>r.name===name&&r.configIndex!==null)??table.find(r=>r.name===name);
+ function showPreview(reads:PhysicsPreviewRead[]){
+  const message=reads.length?`preview — Apply decides · ${reads.map(({name,read})=>`${name}: pending ${JSON.stringify(read.override)} · last evaluated ${JSON.stringify(read.effective)}`).join(' · ')}`:'Preview off · mass and x/y/rotate require Apply. Clear resumes authored values on the next evaluation; integrated history is kept.';
+  if(message!==previewLabel.textContent){previewLabel.textContent=message;previewLabel.title=message;}
+  previewLabel.classList.remove('error');
+ }
+ function drivePreview(){
+  try{
+   const reads=deps.preview(previewBox.checked&&!busy?[...edits.values()].filter(e=>!appliedOps.includes(JSON.stringify({op:e.op,path:e.path,value:e.value,name:e.name}))):[]);
+   previewActive=reads.length>0;showPreview(reads);
+  }catch(error){previewActive=false;previewLabel.textContent=error instanceof Error?error.message:String(error);previewLabel.title=previewLabel.textContent;previewLabel.classList.add('error');}
+ }
+ function clearPreview(){deps.preview([]);previewActive=false;showPreview([]);}
+ previewBox.onchange=()=>drivePreview();
+ previewClear.onclick=()=>{previewBox.checked=false;clearPreview();};
 
  function renderRows(){
   const editable=table.filter(r=>r.editable);
@@ -77,8 +98,8 @@ export function bindPhysicsPanel(deps:PhysicsPanelDeps):PhysicsPanel {
     const label=`${r.name} ${control.field}`;
     const range=make('input',{type:'range',min:String(control.min),max:String(control.max),step:String(control.step),value:String(control.value),disabled:busy});range.setAttribute('aria-label',label);range.dataset.field=control.field;
     const number=make('input',{type:'number',step:'any',value:String(control.value),disabled:busy,inputMode:'decimal'});number.setAttribute('aria-label',`${label} value`);number.dataset.field=control.field;
-    const commit=(raw:string)=>{const value=Number(raw);if(raw.trim()===''||!Number.isFinite(value)){panelStatus(`PHYSICS_VALUE_INVALID: ${r.name}.${control.field} must be a finite number`,true);return;}tryChange(()=>setEdit(edits,r,control.field,value));};
-    range.onchange=()=>commit(range.value);range.oninput=()=>{number.value=range.value;};number.onchange=()=>commit(number.value);
+    const commit=(raw:string,live=false)=>{const value=Number(raw);if(raw.trim()===''||!Number.isFinite(value)){panelStatus(`PHYSICS_VALUE_INVALID: ${r.name}.${control.field} must be a finite number`,true);return;}try{change(setEdit(edits,r,control.field,value),live);}catch(error){panelStatus(error instanceof Error?error.message:String(error),true);}};
+    range.onchange=()=>commit(range.value);range.oninput=()=>{number.value=range.value;commit(range.value,true);};number.onchange=()=>commit(number.value);
     list.append(make('label',{className:control.pending?'physics-control pending':'physics-control'},make('span',{textContent:control.field}),range,number,make('output',{textContent:control.pending?`was ${shown(control.base)}`:''})));
    }else{
     const box=make('input',{type:'checkbox',checked:control.on,disabled:busy});box.setAttribute('aria-label',`${r.name} ${control.field} component`);box.dataset.field=control.field;
@@ -105,7 +126,7 @@ export function bindPhysicsPanel(deps:PhysicsPanelDeps):PhysicsPanel {
   if(chains.some(c=>c.id===keep))chainSelect.value=keep;
   for(const control of [chainSelect,rampField,rampRoot,rampTip,rampButton,pick])control.disabled=busy||!chains.length;
  }
- function render(){renderRows();renderEditor();renderPending();renderChains();}
+ function render(){renderRows();renderEditor();renderPending();renderChains();previewBox.disabled=busy;previewClear.disabled=busy;}
 
  chainSelect.onchange=()=>{const chain=chains.find(c=>c.id===chainSelect.value);if(chain){selected=chain.links[0]!.name;seedRamp(chain);render();}};
  rampField.onchange=()=>{const chain=chains.find(c=>c.id===chainSelect.value);if(chain)seedRamp(chain);};
@@ -123,29 +144,31 @@ export function bindPhysicsPanel(deps:PhysicsPanelDeps):PhysicsPanel {
   chainSelect.value=chain.id;chainSelect.dispatchEvent(new Event('change'));panelStatus(`Picked ${chain.label}.`,false);
  };
  deps.pane.addEventListener('pointerdown',onPick,{capture:true});
- applyButton.onclick=()=>{if(!edits.size||busy)return;void deps.apply(patchOps(edits));};
+ applyButton.onclick=()=>{if(!edits.size||busy)return;clearPreview();void deps.apply(patchOps(edits));};
  resetButton.onclick=()=>{if(busy)return;void deps.reset();};
 
  const panel:PhysicsPanel={
   load(value,bones){
-   if(!value.available){table=[];chains=[];state.textContent=value.reason;state.classList.add('error');render();return;}
+   if(!value.available){clearPreview();table=[];chains=[];edits=new Map();state.textContent=value.reason;state.classList.add('error');render();return;}
    table=value.rows;chains=physicsChains(table,bones);
    const editable=table.filter(r=>r.editable).length;
    state.classList.remove('error');state.textContent=`${editable} physics constraints editable from the handoff config · ${table.length-editable} not editable (reasons below) · ${chains.length} chains from bone parentage`;
-   edits=draftEdits(draft.value,table);render();
+   edits=draftEdits(draft.value,table);if(previewActive)drivePreview();render();
   },
   rows:()=>table.map(r=>({...r,values:{...r.values}})),chains:()=>chains.map(c=>({...c,links:[...c.links]})),edits:()=>[...edits.values()].map(e=>({...e})),
   set(name,field,value){const r=row(name);if(!r)throw new Error(`PHYSICS_ROW_UNKNOWN: ${name}`);change(setEdit(edits,r,field,value));},
   ramp(chainId,field,root,tip){const chain=chains.find(c=>c.id===chainId);if(!chain)throw new Error(`PHYSICS_CHAIN_UNKNOWN: ${chainId}`);change(applyRamp(edits,chain,field,root,tip));},
   select(name){selected=name;chainSelect.value='';render();},
-  restore(){edits=draftEdits(draft.value,table);render();},
+  restore(){clearPreview();edits=draftEdits(draft.value,table);render();},
   clear(){change(new Map());},
+  clearPreview,
+  refreshPreview(){if(previewActive)try{showPreview(deps.previewRead());}catch(error){previewLabel.textContent=error instanceof Error?error.message:String(error);previewLabel.classList.add('error');}},
   applied(ops){appliedOps=(ops??[]).map(o=>JSON.stringify({op:o.op,path:o.path,value:o.value,name:o.name}));renderPending();},
   status:panelStatus,
   readout(lines){readoutArea.replaceChildren(...lines.flatMap(l=>[make('div',{className:'physics-readout-line'},make('span',{className:'eyebrow',textContent:'BEFORE'}),make('code',{textContent:l.before,title:l.before})),make('div',{className:'physics-readout-line'},make('span',{className:'eyebrow',textContent:'AFTER'}),make('code',{textContent:l.after,title:l.after}))]));},
   busy(value){busy=value;render();},
-  dispose(){deps.pane.removeEventListener('pointerdown',onPick,{capture:true});},
+  dispose(){clearPreview();deps.pane.removeEventListener('pointerdown',onPick,{capture:true});},
  };
- render();
+ showPreview([]);render();
  return panel;
 }

package/web/preview.ts

@@ -0,0 +1,52 @@
+/** Review's preview adapters. All posing, parameter validation and history belong to published Play. */
+import type {BoneAdjust,PhysicsParameterPatch,PhysicsParameterRead,RigPlayer} from '@rig-c/play';
+import {previewLocal,SETUP_DEFAULT,type LocalChannel,type PreviewPlan} from '../src/idle-tracks.ts';
+import type {PendingEdit} from '../src/physics-tuning.ts';
+
+export interface BoneSetup {names:readonly string[];get(bone:string):Partial<Record<LocalChannel,number>>|undefined}
+
+/** Preserve the core's evaluation context through the idle + turn composition. */
+export function composeAdjust(a:BoneAdjust|null,b:BoneAdjust|null):BoneAdjust|null {
+ return a&&b?(bones,ctx)=>{a(bones,ctx);b(bones,ctx);}:a??b;
+}
+
+/** Uses the existing idle preview conversion; no player clock or seek compensation. */
+export function idlePreviewAdjust(plan:PreviewPlan,setup:BoneSetup):BoneAdjust|null {
+ const writes=plan.writes.map(w=>({w,setup:setup.get(w.bone)?.[w.channel]??SETUP_DEFAULT[w.channel]}));
+ return writes.length?(bones,ctx)=>{
+  if(ctx.trackTime===null)return;
+  for(const {w,setup:s} of writes)bones.bone(w.bone)[w.channel]=previewLocal(w,s,ctx.trackTime);
+ }:null;
+}
+
+export const LIVE_PHYSICS_FIELDS=['strength','damping','inertia','wind','gravity','mix'] as const;
+type PhysicsPlayer=Pick<RigPlayer,'setPhysicsParameters'|'readPhysicsParameters'|'clearPhysicsParameters'>;
+export interface PhysicsPreviewRead {name:string;read:PhysicsParameterRead}
+
+/** Owns only this panel's pending overrides. Set/read/clear never evaluate, seek or reset physics. */
+export class PhysicsPreview {
+ private player:PhysicsPlayer|null=null;
+ private patches=new Map<string,PhysicsParameterPatch>();
+ sync(player:PhysicsPlayer|null,edits:readonly PendingEdit[]):PhysicsPreviewRead[] {
+  const next=new Map<string,PhysicsParameterPatch>();
+  for(const e of edits)if((LIVE_PHYSICS_FIELDS as readonly string[]).includes(e.field)){
+   next.set(e.name,{...next.get(e.name),[e.field]:e.value});
+  }
+  if(this.player!==player){this.clear();this.player=player;}
+  if(!player){if(next.size)throw new Error('PHYSICS_PREVIEW_UNAVAILABLE: no live player');return [];}
+  for(const [name,patch] of this.patches){
+   const wanted=next.get(name);
+   // Play merges patches: removing a field must clear the old patch before setting the remaining fields.
+   if(!wanted||Object.keys(patch).some(k=>!(k in wanted))){player.clearPhysicsParameters(name);this.patches.delete(name);}
+  }
+  for(const [name,patch] of next)if(JSON.stringify(this.patches.get(name))!==JSON.stringify(patch)){
+   player.setPhysicsParameters(name,patch);this.patches.set(name,patch);
+  }
+  return this.read();
+ }
+ read():PhysicsPreviewRead[] {return this.player?[...this.patches.keys()].map(name=>({name,read:this.player!.readPhysicsParameters(name)})):[];}
+ clear():void {
+  for(const name of this.patches.keys())this.player?.clearPhysicsParameters(name);
+  this.patches.clear();this.player=null;
+ }
+}

package/web/setup-pose.ts

@@ -1,26 +1,27 @@
 /**
- * The setup pose, read from the published player: a throwaway `RigPlayer` over the loaded assets that never plays, so
- * its `bone()` and `slotIdentity()` answer the setup pose (the published `posedFrame()` is empty before `play`). Shared
- * by Setup · Weights (#107) and Edit Mesh (#100). The stage player is never touched; the throwaway one is disposed
- * before this returns, so every bone the caller may ask for is read here.
+ * Setup identity through the published player, followed by named geometry through Play's public readSetupMesh.
+ * The short-lived player reads identity only: setup sliders can select an attachment different from slot.setup.
+ * It never plays or reads bone matrices, and never touches the stage player.
  */
-import {RigPlayer,type ModelAssets,type RenderMode} from '@rig-c/play';
-import type {WorldTransform} from '../src/setup-mesh.ts';
+import {RigPlayer,readSetupMesh,type ModelAssets,type RenderMode,type SetupMesh,type SlotIdentityReason} from '@rig-c/play';
 
 export interface SetupPose {
- /** The slot's attachment at the setup pose, or null when it shows none there. */
+ /** Exact supplying table/key, or the public null identity (never guessed from declarations). */
  identity:{skin:string;attachment:string}|null;
- /** A named bone's setup-pose world transform; throws for a bone that was not read. */
- world:(bone:string)=>WorldTransform;
+ /** Active skin selection, distinct from the supplying table in identity.skin. Null means a fresh no-skin player. */
+ skin:string|null;
+ reason:SlotIdentityReason|null;
+ /** Detached geometry from the public API; lazy so callers can name non-mesh/linked refusals first. */
+ readMesh:()=>SetupMesh|null;
 }
-/** Reads `slot`'s setup-pose identity and every bone in `bones` (unknown names are skipped). Throws what the player throws. */
-export function readSetupPose(assets:ModelAssets,slot:string,bones:readonly string[],root:HTMLElement,mode:RenderMode='dom'):SetupPose {
- const player=new RigPlayer(root,assets,{mode,slots:[slot]});
+/** Reads setup identity without advancing time. Throws public setup/identity/geometry refusals unchanged. */
+export function readSetupPose(assets:ModelAssets,slot:string,root:HTMLElement,mode:RenderMode='dom',skin?:string):SetupPose {
+ const player=new RigPlayer(root,assets,{mode,slots:[slot],...(skin===undefined?{}:{skin})});
  try{
-  const row=player.slotIdentity().slots.find(r=>r.slot===slot),identity=row&&row.attachment&&row.skin?{skin:row.skin,attachment:row.attachment}:null;
-  const map=new Map<string,WorldTransform>();
-  for(const name of bones){try{const b=player.bone(name);map.set(name,{x:b.x,y:b.y,a:b.a,b:b.b,c:b.c,d:b.d});}catch{/* not a bone of this rig */}}
-  return {identity,world:name=>{const t=map.get(name);if(!t)throw new Error(`no setup-pose transform for bone ${name}`);return t;}};
+  const snapshot=player.slotIdentity(),row=snapshot.slots.find(r=>r.slot===slot);
+  const identity=row&&row.attachment!==null&&row.skin!==null?{skin:row.skin,attachment:row.attachment}:null;
+  return {identity,skin:snapshot.skin,reason:row?.reason??null,
+   readMesh:()=>identity?readSetupMesh(assets,{slot,attachment:identity.attachment,skin:snapshot.skin}):null};
  }finally{player.dispose();}
 }
 /** The bone names a compiled model document declares, in stored order. */

package/web/weights-view.ts

@@ -3,11 +3,10 @@
  * coloured by that bone's stored weight on the theme's ramp (0 → 1), or switch to max influence and every vertex takes
  * its dominant bone's colour; hovering a vertex reads its stored value. Weights come from the compiled model document
  * (`src/weights.ts` over the shared reader `src/setup-mesh.ts`); vertex positions come from the published player's
- * setup pose (`web/setup-pose.ts`, a second `RigPlayer` over the same assets that never plays — the same placement
- * Edit Mesh uses). Nothing is edited, applied, recorded or sent.
+ * readSetupMesh API (`web/setup-pose.ts`, shared with Edit Mesh). A never-played player reads setup identity only.
+ * Nothing is edited, applied, recorded or sent.
  */
-import type {ModelAssets,RenderMode} from '@rig-c/play';
-import {placeSetupMesh} from '../src/setup-mesh.ts';
+import type {ModelAssets,RenderMode,SetupMesh as PlaySetupMesh} from '@rig-c/play';
 import {WEIGHTS_SELECT_SLOT,dominantInfluence,meanColor,meshWeights,rampColor,weightOf,weightText,weightsModel,type MeshWeights} from '../src/weights.ts';
 import {modelBoneNames,readSetupPose} from './setup-pose.ts';
 import type {OverlayPoint,OverlayProject,OverlayWeights} from './rig-overlays.ts';
@@ -20,19 +19,20 @@ export const WEIGHTS_SOURCE_MISMATCH='WEIGHTS_SOURCE_MISMATCH';
 export const WEIGHTS_RIG_UNAVAILABLE='WEIGHTS_RIG_UNAVAILABLE';
 
 /** The selected slot's mesh at the setup pose: world vertices (one per stored vertex), triangles and identity. */
-export interface SetupMesh {slot:string;vertices:number[];triangles:number[];identity:{skin:string;attachment:string}|null}
+export interface SetupMesh extends PlaySetupMesh {identity:{skin:string;attachment:string}|null}
 export type SetupMeshResult={ok:true;mesh:SetupMesh;weights:MeshWeights}|{ok:false;code:string};
 /**
- * The slot's attachment is the one the setup pose resolves (`readSetupPose`); its stored vertices are placed through
- * the setup-pose bones (`placeSetupMesh`). The stage player is not touched.
+ * The public setup identity names the target. Play owns its setup coordinates, topology, hull and deform.
+ * The active skin selection is passed independently of the identity's supplying table; the stage is not touched.
  */
-export function setupPoseMesh(assets:ModelAssets,model:unknown,slot:string,root:HTMLElement,mode:RenderMode='dom'):SetupMeshResult {
+export function setupPoseMesh(assets:ModelAssets,model:unknown,slot:string,root:HTMLElement,mode:RenderMode='dom',skin?:string):SetupMeshResult {
  const available=weightsModel(model);if(!available.ok)return available;
  try{
-  const pose=readSetupPose(assets,slot,modelBoneNames(model),root,mode);
-  const result=meshWeights(model,slot,pose.identity);if(!result.ok)return result;
-  const vertices=placeSetupMesh(result.weights,pose.world);if(!vertices)return {ok:false,code:`${WEIGHTS_SOURCE_MISMATCH}: ${slot} has a non-finite setup-pose vertex`};
-  return {ok:true,weights:result.weights,mesh:{slot,vertices,triangles:result.weights.triangles,identity:pose.identity}};
+  const pose=readSetupPose(assets,slot,root,mode,skin);
+  const result=meshWeights(model,slot,pose.identity);if(!result.ok)return !pose.identity&&pose.reason?{ok:false,code:`${result.code} (${pose.reason})`}:result;
+  const mesh=pose.readMesh();
+  if(!mesh||mesh.slot!==slot||mesh.skin!==result.weights.skin||mesh.attachment!==result.weights.attachment||mesh.vertices.length!==result.weights.vertices.length*2)return {ok:false,code:`${WEIGHTS_SOURCE_MISMATCH}: ${slot} setup geometry does not match its stored identity or vertex count`};
+  return {ok:true,weights:result.weights,mesh:{...mesh,identity:pose.identity}};
  }catch(error){return {ok:false,code:`${WEIGHTS_RIG_UNAVAILABLE}: ${error instanceof Error?error.message:String(error)}`};}
 }