@rig-c/review 0.5.0 → 0.7.0

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/physics-panel.ts

@@ -0,0 +1,151 @@
+/**
+ * Animate · Physics tuning panel (#103), page side: the rows `tuningRows` reads, one row editor (sliders, number fields
+ * and x / y / rotate toggles from `rowControls`), the chain ramp, the pending-ops list with per-op revert, Apply and
+ * Reset, the Apply status and the check readout. The panel's inputs carry no ids, so the source draft keeps only the
+ * pending-ops record (`#physics-pending`) and never counts a control per constraint.
+ */
+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';
+
+export interface PhysicsPanelDeps {
+ apply:(ops:PatchOp[])=>Promise<void>;
+ reset:()=>Promise<void>;
+ /** Link bones as pane pixels on the drawn frame, for picking a chain on stage; null when nothing is drawn. */
+ bonePoints:(bones:readonly string[])=>Map<string,{x:number;y:number}>|null;
+ pane:HTMLElement;
+ /** The draft record changed (the panel already wrote `#physics-pending`). */
+ saved:()=>void;
+}
+export interface PhysicsPanel {
+ load(table:TuningTable,bones:readonly {name:string;parent?:string|null}[]):void;
+ rows():TuningRow[];chains():PhysicsChain[];edits():PendingEdit[];
+ set(name:string,field:PhysicsField,value:number):void;
+ ramp(chainId:string,field:PhysicsField,root:number,tip:number):void;
+ select(name:string):void;
+ restore():void;clear():void;
+ applied(ops:readonly PatchOp[]|null):void;
+ status(text:string,error:boolean):void;
+ readout(lines:{name:string;before:string;after:string}[]):void;
+ busy(value:boolean):void;
+ dispose():void;
+}
+
+const node=<T extends HTMLElement>(id:string)=>{const found=document.getElementById(id);if(!found)throw new Error(`Missing UI element: ${id}`);return found as T;};
+const make=<K extends keyof HTMLElementTagNameMap>(tag:K,props:Record<string,unknown>={},...children:(Node|string)[]):HTMLElementTagNameMap[K]=>{const item=document.createElement(tag);Object.assign(item,props);item.append(...children);return item;};
+const shown=(value:number|undefined)=>value===undefined?'—':String(Number(value.toPrecision(6)));
+
+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');
+ 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();};
+ 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 renderRows(){
+  const editable=table.filter(r=>r.editable);
+  const head=make('tr',{},...['Constraint','#',...TUNING_FIELDS,'x','y','rotate'].map(label=>make('th',{scope:'col',textContent:label})));
+  const body=make('tbody');
+  for(const r of editable){
+   const current=(field:PhysicsField)=>edits.get(`/constraints/${r.configIndex}/${field}`)?.value;
+   const name=make('button',{type:'button',textContent:r.name,className:'physics-row-pick',title:`config.constraints[${r.configIndex}] · bone ${r.bone??'—'}`});name.setAttribute('aria-pressed',String(selected===r.name));
+   name.onclick=()=>{selected=r.name;render();};
+   const cells=[...TUNING_FIELDS,...COMPONENT_FIELDS].map(field=>{const now=current(field),cell=make('td',{textContent:shown(now??r.values[field])});if(now!==undefined)cell.className='pending';else if(r.values[field]===undefined){cell.className='absent';cell.title='Not in the config (the producer default applies)';}return cell;});
+   const line=make('tr',{},make('th',{scope:'row'},name),make('td',{textContent:String(r.configIndex)}),...cells);if(selected===r.name)line.className='selected';body.append(line);
+  }
+  rowsArea.replaceChildren(make('table',{className:'physics-table'},make('thead',{},head),body));
+  const others=table.filter(r=>!r.editable);
+  const lockedBody=make('tbody');
+  for(const r of others){const line=make('tr',{},make('th',{scope:'row',textContent:r.name}),make('td',{textContent:r.kind}),make('td',{className:'physics-reason',textContent:r.reason??''}));line.dataset.notEditable='true';lockedBody.append(line);}
+  locked.replaceChildren(make('p',{className:'eyebrow',textContent:`NOT EDITABLE · ${others.length}`}),make('table',{className:'physics-table physics-locked-table'},make('thead',{},make('tr',{},...['Constraint','Kind','Reason'].map(l=>make('th',{scope:'col',textContent:l})))),lockedBody));
+  locked.hidden=!others.length;
+ }
+ function renderEditor(){
+  const r=selected?row(selected):undefined;
+  if(!r){editor.replaceChildren(make('p',{className:'hint',textContent:'Pick a constraint row or a chain to edit it.'}));return;}
+  const view=rowControls(r,edits),title=make('p',{className:'physics-editor-title'},make('strong',{textContent:r.name}),` · ${r.kind} · bone ${r.bone??'—'} · ${r.configIndex===null?'not in the config':`/constraints/${r.configIndex}`}`);
+  if(!view.editable){const reason=make('p',{className:'hint error physics-reason',textContent:view.reason});editor.replaceChildren(title,reason);return;}
+  const list=make('div',{className:'physics-controls'});
+  for(const control of view.controls){
+   if(control.kind==='slider'){
+    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);
+    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;
+    box.onchange=()=>tryChange(()=>setEdit(edits,r,control.field,componentValue(r,control.field,box.checked)));
+    list.append(make('label',{className:control.pending?'physics-toggle pending':'physics-toggle'},box,`${control.field}${control.base===null?'':` (${shown(control.base)})`}`));
+   }
+  }
+  editor.replaceChildren(title,list);
+ }
+ function renderPending(){
+  const items=[...edits.values()];
+  pending.replaceChildren(...items.map(e=>{
+   const revert=make('button',{type:'button',textContent:'Revert',disabled:busy});revert.setAttribute('aria-label',`Revert ${e.path}`);
+   revert.onclick=()=>{const next=new Map(edits);next.delete(e.path);change(next);};
+   const applied=appliedOps.includes(JSON.stringify({op:e.op,path:e.path,value:e.value,name:e.name}));
+   return make('li',{className:applied?'applied':''},make('code',{textContent:`${e.op} ${e.path}`}),` ${e.from===null?'(absent)':shown(e.from)} → ${shown(e.value)} · ${e.name}${applied?' · applied':''}`,revert);
+  }));
+  if(!items.length)pending.append(make('li',{className:'hint',textContent:'No pending ops.'}));
+  applyButton.disabled=busy||!items.length;resetButton.disabled=busy;
+ }
+ function renderChains(){
+  const keep=chainSelect.value;
+  chainSelect.replaceChildren(make('option',{value:'',textContent:chains.length?'Select a chain':'No chain of two or more links'}),...chains.map(c=>make('option',{value:c.id,textContent:c.label})));
+  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();}
+
+ 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);};
+ function seedRamp(chain:PhysicsChain){const field=rampField.value as PhysicsField,value=(r:TuningRow)=>edits.get(`/constraints/${r.configIndex}/${field}`)?.value??r.values[field];const root=value(chain.links[0]!),tip=value(chain.links.at(-1)!);rampRoot.value=root===undefined?'':String(root);rampTip.value=tip===undefined?'':String(tip);}
+ rampButton.onclick=()=>{const chain=chains.find(c=>c.id===chainSelect.value);if(!chain){panelStatus('PHYSICS_CHAIN_NONE: select a chain first',true);return;}
+  const root=Number(rampRoot.value),tip=Number(rampTip.value);if(!rampRoot.value.trim()||!rampTip.value.trim()||!Number.isFinite(root)||!Number.isFinite(tip)){panelStatus('PHYSICS_VALUE_INVALID: the ramp needs a finite root and tip value',true);return;}
+  tryChange(()=>applyRamp(edits,chain,rampField.value as PhysicsField,root,tip));panelStatus(`Ramped ${rampField.value} over ${chain.links.length} links (${root} → ${tip}); Apply rebuilds.`,false);};
+ pick.onclick=()=>{picking=!picking;pick.setAttribute('aria-pressed',String(picking));deps.pane.dataset.physicsPick=String(picking);panelStatus(picking?'Click a chain on the stage (a link bone within 24 px).':'',false);};
+ const onPick=(event:PointerEvent)=>{
+  if(!picking||event.button!==0)return;
+  const points=deps.bonePoints(chains.flatMap(c=>c.links.map(l=>l.bone!)));if(!points)return;
+  const box=deps.pane.getBoundingClientRect(),chain=nearestChain(chains,points,{x:event.clientX-box.left,y:event.clientY-box.top});
+  event.stopPropagation();event.preventDefault();picking=false;pick.setAttribute('aria-pressed','false');deps.pane.dataset.physicsPick='false';
+  if(!chain){panelStatus('PHYSICS_CHAIN_NONE: no chain link bone within 24 px of the click',true);return;}
+  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));};
+ 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;}
+   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();
+  },
+  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();},
+  clear(){change(new Map());},
+  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});},
+ };
+ render();
+ return panel;
+}

package/web/readings-panel.ts

@@ -0,0 +1,105 @@
+/**
+ * Animate · Readings (#108), page side: the pickers (Folds and Overlaps toggles; a cloth:leg pass-through pair and a
+ * slot:slot seam pair from the model's slots; a bone and the bone it is read against), Run, the per-pair worst-frame
+ * lines and the timeline ticks on the transport scrub — two colours, the inspected build above the scratch build — each
+ * tick a button that seeks to its frame's time. The server runs `rigc render`; this draws what came back.
+ */
+import {readingTicks,ticksOnClip,TICK_EDGE,worstLine,type ReadingBuild,type ReadingRequest,type ReadingResult,type ReadingTick} from '../src/readings.ts';
+
+export interface ReadingsJobView {id:string;status:'running'|'done'|'failed';error:string|null;request:{animation:string;readings:ReadingRequest[];environment:{wind:[number,number];gravity:[number,number]}|null};environment:{requested:boolean;flag:boolean;passed:boolean};compiler:{package:string;version:string};runs:{build:ReadingBuild;id:string;modelHash:string;results:ReadingResult[]}[]}
+export interface ReadingsRefusal {status:'refused';error:string}
+export interface ReadingsPanel {
+ catalog(slots:readonly string[],bones:readonly string[]):void;
+ /** The readings the pickers name, or the line saying what is missing. */
+ requests():{readings:ReadingRequest[]}|{error:string};
+ busy(value:boolean):void;
+ status(text:string,error:boolean):void;
+ /** Worst-frame lines for a finished job; each line seeks to its worst frame. */
+ lines(job:ReadingsJobView|null):void;
+ /** The ticks on the scrub for the drawn animation and its duration; hidden when the job's animation is not the one drawn. */
+ ticks(job:ReadingsJobView|null,animation:string,duration:number):ReadingTick[];
+ shownLines():string[];
+}
+export interface ReadingsPanelDeps {run:()=>void;seek:(animation:string,frame:number,time:number|null,label:string)=>void}
+
+const node=<T extends HTMLElement>(id:string)=>{const found=document.getElementById(id);if(!found)throw new Error(`Missing UI element: ${id}`);return found as T;};
+const make=<K extends keyof HTMLElementTagNameMap>(tag:K,props:Record<string,unknown>={},...children:(Node|string)[]):HTMLElementTagNameMap[K]=>{const item=document.createElement(tag);Object.assign(item,props);item.append(...children);return item;};
+/** The range input's thumb travels inside the track by about its own width; ticks sit under the thumb's centre. */
+const THUMB=14;
+export const EDGE=TICK_EDGE;
+
+export function bindReadingsPanel(deps:ReadingsPanelDeps):ReadingsPanel {
+ const folds=node<HTMLInputElement>('readings-folds'),overlaps=node<HTMLInputElement>('readings-overlaps');
+ const pairs={
+  pass:{on:node<HTMLInputElement>('readings-pass-on'),a:node<HTMLInputElement>('readings-pass-cloth'),b:node<HTMLInputElement>('readings-pass-leg')},
+  seam:{on:node<HTMLInputElement>('readings-seam-on'),a:node<HTMLInputElement>('readings-seam-a'),b:node<HTMLInputElement>('readings-seam-b')},
+  angle:{on:node<HTMLInputElement>('readings-angle-on'),a:node<HTMLInputElement>('readings-angle-bone'),b:node<HTMLInputElement>('readings-angle-relative')},
+ };
+ const run=node<HTMLButtonElement>('readings-run'),status=node('readings-status'),list=node('readings-worst'),strip=node('reading-ticks'),transport=node('transport'),scrub=node<HTMLInputElement>('scrub');
+ let shown:string[]=[],enabled=false,isBusy=false;
+ // Typing both names of a pair turns its picker on; clearing one turns it off.
+ for(const pair of Object.values(pairs)){const sync=()=>{pair.on.checked=!!pair.a.value.trim()&&!!pair.b.value.trim();};pair.a.addEventListener('input',sync);pair.b.addEventListener('input',sync);}
+ run.onclick=()=>deps.run();
+ const setRun=()=>{run.disabled=!enabled||isBusy;};
+
+ function requests(){
+  const readings:ReadingRequest[]=[];
+  if(folds.checked)readings.push({kind:'folds'});
+  const pair=(p:typeof pairs.pass,what:string)=>{const a=p.a.value.trim(),b=p.b.value.trim();if(!p.on.checked)return null;if(!a||!b)return `READINGS_PAIR_INCOMPLETE: ${what} needs both names`;return [a,b] as const;};
+  const pass=pair(pairs.pass,'pass-through');if(typeof pass==='string')return {error:pass};if(pass)readings.push({kind:'pass-through',cloth:pass[0],leg:pass[1]});
+  const seam=pair(pairs.seam,'seam');if(typeof seam==='string')return {error:seam};if(seam)readings.push({kind:'seam',a:seam[0],b:seam[1]});
+  if(overlaps.checked)readings.push({kind:'overlaps'});
+  const angle=pair(pairs.angle,'angle range');if(typeof angle==='string')return {error:angle};if(angle)readings.push({kind:'angle-range',bone:angle[0],relative:angle[1]});
+  return readings.length?{readings}:{error:'READINGS_NONE_CHOSEN: pick at least one reading'};
+ }
+
+ function lines(job:ReadingsJobView|null){
+  list.replaceChildren();shown=[];
+  if(!job)return;
+  for(const run of job.runs)for(const result of run.results){
+   const many=result.status==='read'&&result.items.length>1;
+   const line=worstLine(run.build,result),frame=result.worst?.frame??null;
+   const item=make('li',{className:`readings-line ${run.build}${result.status==='read'?'':' error'}`});
+   const swatch=make('span',{className:`tick-swatch ${run.build}`});swatch.setAttribute('aria-hidden','true');
+   if(frame!==null){const go=make('button',{type:'button',className:'readings-go',textContent:line,title:line});go.onclick=()=>deps.seek(job.request.animation,frame,result.fps?frame/result.fps:null,`${run.build} · ${result.label} worst`);item.append(swatch,go);}
+   else item.append(swatch,make('code',{textContent:line,title:line}));
+   shown.push(line);
+   if(many){
+    // Folds and overlaps read many meshes or pairs: each one's own worst line, folded away under the reading's.
+    const details=make('details',{className:'readings-items'}),summary=make('summary',{textContent:`${result.items.length} ${result.reading.kind==='folds'?'folding meshes':'moving pairs'}`});details.append(summary);
+    const inner=make('ul');for(const sub of result.items){const text=worstLine(run.build,result,sub),f=sub.worst?.frame??null;const li=make('li');if(f!==null){const go=make('button',{type:'button',className:'readings-go',textContent:text,title:text});go.onclick=()=>deps.seek(job.request.animation,f,result.fps?f/result.fps:null,`${run.build} · ${result.reading.kind} ${sub.pair} worst`);li.append(go);}else li.append(make('code',{textContent:text}));inner.append(li);}
+    details.append(inner);item.append(details);
+   }
+   list.append(item);
+  }
+ }
+
+ function ticks(job:ReadingsJobView|null,animation:string,duration:number):ReadingTick[]{
+  strip.replaceChildren();
+  const all=job?readingTicks(job.runs):[],visible=job?ticksOnClip(all,job.request.animation,animation,duration):[];
+  strip.hidden=!visible.length;transport.classList.toggle('has-reading-ticks',!!visible.length);
+  if(!visible.length)return visible;
+  // Under the scrub's track: its own box inside the transport row.
+  strip.style.left=`${scrub.offsetLeft+THUMB/2}px`;strip.style.width=`${Math.max(0,scrub.offsetWidth-THUMB)}px`;strip.style.top=`${scrub.offsetTop+scrub.offsetHeight}px`;
+  // One button per (build, frame): the labels of every reading that lists the frame, so overlapping ticks stay one target.
+  const byFrame=new Map<string,ReadingTick[]>();for(const t of visible){const key=`${t.build}:${t.frame}`;byFrame.set(key,[...(byFrame.get(key)??[]),t]);}
+  for(const group of byFrame.values()){
+   const first=group[0]!,label=`${first.build} · F${first.frame} · ${first.time!.toFixed(4)} s · ${group.map(t=>t.label).join(', ')}`;
+   const tick=make('button',{type:'button',className:`reading-tick ${first.build}`,title:label});tick.setAttribute('aria-label',label);tick.dataset.frame=String(first.frame);tick.dataset.build=first.build;
+   const at=Math.min(first.time!,duration);tick.style.left=`${(at/duration)*100}%`;tick.onclick=()=>deps.seek(job!.request.animation,first.frame,first.time,label);
+   strip.append(tick);
+  }
+  return visible;
+ }
+
+ return {
+  catalog(slots,bones){
+   node('readings-slots').replaceChildren(...slots.map(s=>make('option',{value:s})));node('readings-bones').replaceChildren(...bones.map(b=>make('option',{value:b})));
+   enabled=true;setRun();
+  },
+  requests,
+  busy(value){isBusy=value;setRun();run.textContent=value?'Running…':'Run readings';},
+  status(text,error){status.textContent=text;status.title=text;status.classList.toggle('error',error);},
+  lines,ticks,shownLines:()=>[...shown],
+ };
+}