@rig-c/review 0.6.0 → 0.7.0

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],
+ };
+}

package/web/rebuild-client.ts

@@ -0,0 +1,216 @@
+/**
+ * Apply · Rebuild, page side (#99): the chest editor's rows become the producer's region entries, one typed request
+ * goes to `/api/rebuild`, the job's lines stream back by polling, and the applied state is recorded. No DOM here
+ * (main.ts owns the elements and the player); the server owns every path and the producer's flags.
+ */
+import {ellipsePolygon} from '../src/chest-regions.ts';
+import type {BustSpec} from '../src/chest-landmarks.ts';
+import {CONFIG_PATCH_SCHEMA,type ConfigPatch,type PatchCmd,type PatchOp} from '../src/config-patch.ts';
+import {APPLIED_DELTA_SCHEMA,APPLIED_PATCH_SCHEMA,APPLIED_RETARGET_SCHEMA,filesDiffText,type AppliedAssembled,type AppliedDelta,type AppliedPatch,type AppliedRetarget,type CheckSummary,type FilesDiff} from '../src/applied-context.ts';
+import type {MotionSummary,RetargetFlags,RetargetLine,RetargetRecord} from '../src/retarget.ts';
+export type {ConfigPatch,PatchOp,AppliedPatch,AppliedDelta,AppliedRetarget,CheckSummary,BustSpec};
+import {chestContourFields,chestRegionRows,chestRowId,type ChestFieldReader} from './chest-regions-tool.ts';
+import type {InspectedCheckView} from '../src/physics-tuning.ts';
+
+export type RegionEntry=
+ |{name:string;shape:'circle';cx:number;cy:number;r:number;bone:string;spacing:number;band:number}
+ |{name:string;bone:string;shape:'polygon';points:[number,number][];spacing:number;band:number};
+/** The producer handoff (#101) as `/api/rebuild` reports it: paths relative to the package root, how it was found. */
+export interface HandoffView {how:'declared'|'discovered';via:string;outside:boolean;config:{path:string;sha256:string};parts:string|null;rig:string|null;files:{path:string;sha256:string}[];missing:string[]}
+export interface BaselineView {status:'running'|'reproduced'|'not-reproduced'|'refused'|'failed';firstDifference:string|null;hashes:{baseline:{rigJson:string|null;tree:string};inspected:{rigJson:string|null;tree:string}}|null;line:string;wallMs:number|null}
+export interface RetargetStatusView {available:boolean;reason:string|null;producer:{package:string;version:string}|null;compiler:{package:string;version:string}|null;rig:string|null;sequences:{id:string;label:string;path:string;cleaned:boolean;frames:number;people:string[]}[];bones:string[];animations:string[]}
+export interface RebuildStatusView {retarget?:RetargetStatusView;available:boolean;handoff:HandoffView|null;baseline:BaselineView|null;inputs:{config:string;parts:string|null;rig:string|null;configHash:string}|null;parts:{name:string;regions:unknown[]}[];contour:Record<string,Record<string,unknown>>;meshes?:Record<string,unknown>;constraints?:unknown[]|null;bones?:unknown[]|null;fields?:Record<string,unknown>|null;cuts?:{config:Record<string,unknown>;build:string|null}|null;inspectedCheck?:InspectedCheckView|null;idle?:import('../src/idle-tracks.ts').IdleStatus|null;producer:{package:string;version:string}|null;compiler:{package:string;version:string}|null;reason:string|null}
+export interface RebuildJobView {id:string;status:'running'|'built'|'refused'|'failed';reused:boolean;lines:string[];producerLine:string|null;exitCode:number|null;wallMs:{remesh:number|null;compile:number|null};build:{modelUrl:string;modelHash:string;files:Record<string,string>}|null;request:{part:string;regions:RegionEntry[];configHash:string;entrySha256:string;bust?:BustSpec};producer:{package:string;version:string};compiler:{package:string;version:string}}
+export interface RebuildRefusal {status:'refused';error:string;producerLine:string|null}
+/** #99 regions or #105 landmarks: exactly one of `regions` and `bust`. */
+export type RebuildRequestBody={part:string;regions:RegionEntry[];configHash:string}|{part:string;bust:BustSpec;configHash:string};
+/** What the draft keeps and the feedback context carries: the exact last applied inputs and the producer's line. */
+export interface AppliedRecord {schema:'rig-review-applied/1';buildId:string;part:string;regions:RegionEntry[];bust?:BustSpec;configHash:string;entrySha256:string;producer:{package:string;version:string};compiler:{package:string;version:string};line:string|null;modelHash:string}
+
+const number=(read:ChestFieldReader,id:string)=>{const raw=(read(id)?.value??'').trim();if(!raw)return null;const value=Number(raw);return Number.isFinite(value)?value:Number.NaN;};
+
+/** Rows with a centre x are designated; a row with equal semi-axes and no clip is the config's circle, else the 32-sample polygon. */
+export function designatedRegions(read:ChestFieldReader):{regions:RegionEntry[]}|{error:string} {
+ const regions:RegionEntry[]=[];
+ for(const row of chestRegionRows){
+  if(number(read,chestRowId(row,'cx'))===null)continue;
+  const name=(read(chestRowId(row,'name'))?.value??'').trim(),bone=(read(chestRowId(row,'bone'))?.value??'').trim(),tag=`row ${row+1}`;
+  if(!name)return {error:`REBUILD_REGION_INCOMPLETE: ${tag} name`};if(!bone)return {error:`REBUILD_REGION_INCOMPLETE: ${name} bone`};
+  const values:Record<string,number|null>={};
+  for(const field of ['cx','cy','ax','ay','spacing','band','clip'] as const){values[field]=number(read,chestRowId(row,field));if(Number.isNaN(values[field]))return {error:`REBUILD_REGION_INCOMPLETE: ${name} ${field}`};}
+  for(const field of ['cy','ax','spacing','band'] as const)if(values[field]===null)return {error:`REBUILD_REGION_INCOMPLETE: ${name} ${field}`};
+  const {cx,cy,ax,spacing,band,clip}=values as Record<string,number>,ay=values.ay??ax;
+  if(ax===ay&&values.clip===null)regions.push({name,shape:'circle',cx,cy,r:ax,bone,spacing,band});
+  else regions.push({name,bone,shape:'polygon',points:ellipsePolygon([cx,cy],[ax,ay],32,values.clip===null?undefined:clip),spacing,band});
+ }
+ return regions.length?{regions}:{error:'REBUILD_REGION_INCOMPLETE: no region has a centre'};
+}
+
+/** The contour part to rebuild: the one whose regions name the first designated bone, else the only one, else none. */
+export function pickPart(status:Pick<RebuildStatusView,'parts'>,regions:readonly RegionEntry[]):string|null {
+ const bones=new Set(regions.map(r=>r.bone));
+ const named=status.parts.filter(p=>p.regions.some(r=>!!r&&typeof r==='object'&&bones.has(String((r as {bone?:unknown}).bone))));
+ if(named.length===1)return named[0]!.name;
+ return status.parts.length===1?status.parts[0]!.name:null;
+}
+
+/** The part a landmarks Apply rebuilds: the contour part whose entry already states `contour.bust`, else as for regions. */
+export function pickBustPart(status:Pick<RebuildStatusView,'parts'|'contour'>,derived:readonly RegionEntry[]):string|null {
+ const stated=status.parts.filter(p=>{const c=status.contour[p.name]?.contour;return !!c&&typeof c==='object'&&'bust' in (c as Record<string,unknown>);});
+ return stated.length===1?stated[0]!.name:pickPart(status,derived);
+}
+/**
+ * A landmarks Apply (#105): `{part, bust, configHash}`, or the line that refuses it before anything is sent — a point not
+ * placed, or review's pre-check of the producer's `CONFIG_BUST_CLEARANCE` on the same numbers. Bone names are the
+ * producer's to resolve (`CONFIG_NAME_RESOLVES` comes back verbatim).
+ */
+export function landmarksRequest(status:Pick<RebuildStatusView,'parts'|'contour'|'inputs'>,read:import('./chest-editor.ts').LandmarkRead):{body:RebuildRequestBody;part:string}|{error:string} {
+ if('error' in read)return {error:read.error};
+ if('missing' in read)return {error:`LANDMARKS_INCOMPLETE: place ${read.missing.join(', ')}`};
+ if(read.derived.refusal)return {error:read.derived.refusal};
+ if(!status.inputs)return {error:'REBUILD_STATUS_UNAVAILABLE'};
+ const part=pickBustPart(status,read.derived.regions);
+ if(!part)return {error:`REBUILD_PART_AMBIGUOUS: the config states ${status.parts.length} contour meshes and the landmark bones name none of them alone`};
+ return {part,body:{part,bust:read.spec,configHash:status.inputs.configHash}};
+}
+
+/**
+ * Field values that start the editor from the producer config: the first contour part's circle regions (at most two
+ * rows) and its contour numbers. Only for an untouched editor — `null` once any row has a centre.
+ */
+export function seedFields(status:Pick<RebuildStatusView,'parts'|'contour'>,read:ChestFieldReader):Record<string,string>|null {
+ if(chestRegionRows.some(row=>(read(chestRowId(row,'cx'))?.value??'').trim()))return null;
+ const part=status.parts.find(p=>p.regions.length),entry=part?status.contour[part.name]:undefined;if(!part||!entry)return null;
+ const out:Record<string,string>={},contour=(entry.contour??{}) as Record<string,unknown>;
+ part.regions.slice(0,chestRegionRows.length).forEach((value,row)=>{
+  const r=value as Record<string,unknown>;if(r.shape!=='circle')return;
+  for(const [field,key] of [['name','name'],['bone','bone'],['cx','cx'],['cy','cy'],['ax','r'],['ay','r'],['spacing','spacing'],['band','band']] as const)if(r[key]!==undefined)out[chestRowId(row,field)]=String(r[key]);
+ });
+ for(const [key,id] of chestContourFields)if(typeof contour[key]==='number')out[id]=String(contour[key]);
+ if(typeof contour.bridges==='boolean')out['chest-bridges']=String(contour.bridges);
+ if(typeof entry.r==='number')out['chest-r']=String(entry.r);
+ if(Array.isArray(entry.segments))out['chest-segments']=JSON.stringify(entry.segments);
+ return Object.keys(out).length?out:null;
+}
+
+/**
+ * Landmark field values (#105) from a config entry that already states `contour.bust`, for an untouched Landmarks mode
+ * only (`null` once any landmark has a value). Absent alpha / clearance seed the producer's defaults.
+ */
+export function seedLandmarks(status:Pick<RebuildStatusView,'parts'|'contour'>,read:ChestFieldReader):Record<string,string>|null {
+ if(['apex_r','apex_l','cleavage'].some(k=>(read(`lm-${k}-x`)?.value??'').trim()||(read(`lm-${k}-y`)?.value??'').trim()))return null;
+ for(const p of status.parts){
+  const bust=(status.contour[p.name]?.contour as Record<string,unknown>|undefined)?.bust as Record<string,unknown>|undefined;if(!bust||typeof bust!=='object')continue;
+  const out:Record<string,string>={};
+  for(const k of ['apex_r','apex_l','cleavage'])if(Array.isArray(bust[k])&&(bust[k] as unknown[]).length===2){out[`lm-${k}-x`]=String((bust[k] as number[])[0]);out[`lm-${k}-y`]=String((bust[k] as number[])[1]);}
+  for(const k of ['alpha','clearance'])if(typeof bust[k]==='number')out[`lm-${k}`]=String(bust[k]);
+  for(const k of ['bone_r','bone_l'])if(typeof bust[k]==='string')out[`lm-${k}`]=bust[k] as string;
+  return Object.keys(out).length?out:null;
+ }
+ return null;
+}
+
+export const appliedRecord=(job:RebuildJobView):AppliedRecord=>({schema:'rig-review-applied/1',buildId:job.id,part:job.request.part,regions:job.request.regions,...(job.request.bust?{bust:job.request.bust}:{}),configHash:job.request.configHash,entrySha256:job.request.entrySha256,producer:job.producer,compiler:job.compiler,line:job.producerLine,modelHash:job.build!.modelHash});
+export function parseApplied(text:string):AppliedRecord|AppliedPatch|AppliedDelta|AppliedRetarget|null {try{const value=JSON.parse(text);return value?.schema==='rig-review-applied/1'||value?.schema===APPLIED_PATCH_SCHEMA||value?.schema===APPLIED_DELTA_SCHEMA||value?.schema===APPLIED_RETARGET_SCHEMA?value as AppliedRecord|AppliedPatch|AppliedDelta|AppliedRetarget:null;}catch{return null;}}
+
+/** A patch Apply's job (#102): the patch and its hash, the op/compile/check wall clocks, check's summary and the rig.json diff. */
+/** #115: a build job's assemble readout (`AssembledView` in src/rebuild.ts). */
+export type AssembledJobView=import('../src/rebuild.ts').AssembledView;
+export interface PatchJobView {id:string;kind:'patch';op?:'rig'|'retune'|'remesh'|'build';assembled?:AssembledJobView;status:'running'|'built'|'refused'|'failed';reused:boolean;lines:string[];producerLine:string|null;exitCode:number|null;wallMs:{op:number|null;compile:number|null;check:number|null};check:CheckSummary|null;diff:{count:number;paths:string[]}|null;files?:FilesDiff|null;remesh?:import('../src/mesh-entry.ts').RemeshCounts&{modelTriangles:number|null}|null;build:{modelUrl:string;modelHash:string;files:Record<string,string>}|null;request:{patch:ConfigPatch;patchSha256:string;configHash:string};producer:{package:string;version:string};compiler:{package:string;version:string}}
+export interface PatchRequestBody {patch:ConfigPatch}
+/** Edit Mesh's delta Apply (#135): `remesh --delta`, the per-file diff and the part's counts; remesh's own gate holds check. */
+export interface DeltaJobView {id:string;kind:'delta';op:'remesh';status:'running'|'built'|'refused'|'failed';reused:boolean;lines:string[];producerLine:string|null;exitCode:number|null;wallMs:{op:number|null;compile:number|null};files:FilesDiff|null;remesh:import('../src/mesh-entry.ts').RemeshCounts&{modelTriangles:number|null}|null;build:{modelUrl:string;modelHash:string;files:Record<string,string>}|null;request:{part:string;delta:Record<string,unknown>;deltaSha256:string;configHash:string};producer:{package:string;version:string};compiler:{package:string;version:string}}
+/** `{part, delta, configHash}`: the server owns every path and flag; the delta is the editor's export as it stands. */
+export interface DeltaRequestBody {part:string;delta:import('../src/mesh-edit.ts').MeshEditDocument;configHash:string}
+/** A retarget Apply's job (#114): clean, retarget, compile; every FAIL line of the step that refused, verbatim; the listed lines. */
+export interface RetargetJobView {id:string;kind:'retarget';op:'retarget';status:'running'|'built'|'refused'|'failed';reused:boolean;lines:string[];producerLine:string|null;refusals:string[];exitCode:number|null;wallMs:{clean:number|null;retarget:number|null;compile:number|null};files:FilesDiff|null;motion:MotionSummary|null;readings:RetargetLine[];build:{modelUrl:string;modelHash:string;files:Record<string,string>}|null;request:{record:RetargetRecord;recordSha256:string;configHash:string};producer:{package:string;version:string};compiler:{package:string;version:string}}
+/** `{retarget: {sequence, map, flags, configHash}}`: a declared reference id, the map by content and typed flags — no path, no flag string. */
+export interface RetargetRequestBody {retarget:{sequence:string;map:Record<string,unknown>;flags:RetargetFlags;configHash:string}}
+/** What the draft keeps and `context.applied` carries for a retarget: the record, the producer's line, the motion summary, the diff and the lines. */
+export const retargetAppliedRecord=(job:RetargetJobView):AppliedRetarget=>({schema:APPLIED_RETARGET_SCHEMA,buildId:job.id,retarget:JSON.parse(JSON.stringify(job.request.record)),recordSha256:job.request.recordSha256,configHash:job.request.configHash,producer:job.producer,compiler:job.compiler,line:job.producerLine,motion:JSON.parse(JSON.stringify(job.motion)),files:job.files,readings:job.readings.map(r=>({...r})),modelHash:job.build!.modelHash});
+/** A retarget job's status line: built (wall clocks, the new animation, the diff) or the producer's line verbatim. */
+export function retargetOutcomeLine(result:RetargetJobView|RebuildRefusal):{text:string;error:boolean} {
+ if(!('id' in result))return {text:result.producerLine??result.error,error:true};
+ if(result.status!=='built')return {text:result.producerLine??`REBUILD_FAILED: exit ${result.exitCode}`,error:true};
+ const r=result.request.record,wall=result.reused?'reused the scratch build of this exact retarget':`${r.op.clean?`clean ${seconds(result.wallMs.clean)} + `:''}retarget ${seconds(result.wallMs.retarget)} + compile ${seconds(result.wallMs.compile)}`;
+ const kept=result.motion?(result.motion.kept?'the rig\'s own animations unchanged':`changed: ${result.motion.changed.join(', ')}`):'';
+ return {text:`Retargeted "${r.flags.animation}" from ${r.sequence.reference} with ${result.producer.package} ${result.producer.version} · ${wall} · ${kept} · ${result.files?filesDiffText(result.files):'no diff'} · Reset returns to the inspected build`,error:!!result.motion&&!result.motion.kept};
+}
+export type AnyJobView=RebuildJobView|PatchJobView|DeltaJobView|RetargetJobView;
+export const isPatchJob=(job:AnyJobView):job is PatchJobView=>(job as PatchJobView).kind==='patch';
+
+export interface RebuildDeps<B=RebuildRequestBody|PatchRequestBody,J extends AnyJobView=AnyJobView> {post:(body:B)=>Promise<J|RebuildRefusal>;get:(id:string)=>Promise<J>;onLine:(line:string,index:number)=>void;sleep:(ms:number)=>Promise<void>;intervalMs?:number}
+/** One Apply: post, then poll until the job leaves `running`, handing every new line over once, in order. */
+export async function runRebuild<B,J extends AnyJobView>(body:B,deps:RebuildDeps<B,J>):Promise<J|RebuildRefusal> {
+ let job=await deps.post(body);if(job.status==='refused'&&!('id' in job))return job;
+ let seen=0;const deliver=(lines:string[])=>{for(;seen<lines.length;seen++)deps.onLine(lines[seen]!,seen);};
+ deliver((job as J).lines);
+ while(job.status==='running'){await deps.sleep(deps.intervalMs??700);job=await deps.get((job as J).id);deliver(job.lines);}
+ return job;
+}
+
+/**
+ * A patch from the config the status read: `config_sha256` is the handoff config's hash and the producer is the
+ * installed one, so an edit card only states its ops and the op. Null when Apply cannot run here.
+ */
+export function makePatch(status:Pick<RebuildStatusView,'inputs'|'producer'>,ops:PatchOp[],op:{cmd:PatchCmd;args?:string[]}={cmd:'rig'}):ConfigPatch|null {
+ if(!status.inputs||!status.producer)return null;
+ return {schema:CONFIG_PATCH_SCHEMA,config_sha256:status.inputs.configHash,ops:ops.map(o=>({...o})),producer:{name:status.producer.package,version:status.producer.version},op:{cmd:op.cmd,args:[...(op.args??[])]}};
+}
+/** What the draft keeps and `context.applied` carries for a patch: the patch, its hash, the producer's line and check's summary. */
+export const patchAppliedRecord=(job:PatchJobView):AppliedPatch=>({schema:APPLIED_PATCH_SCHEMA,buildId:job.id,patch:job.request.patch,patchSha256:job.request.patchSha256,configHash:job.request.configHash,producer:job.producer,compiler:job.compiler,line:job.producerLine,check:job.check,diff:job.diff,...(job.files?{files:job.files}:{}),modelHash:job.build!.modelHash,...(job.op?{op:job.op}:{}),...(job.remesh?{mesh:{part:job.remesh.part,before:{...job.remesh.before},after:{...job.remesh.after}}}:{}),...(job.op==='build'?{assembled:assembledRecord(job)}:{})});
+/** #115: what a build Apply records: the build's own wall clock, the recomposite figures, the parts it changed and its `seam pair` lines. */
+export function assembledRecord(job:PatchJobView):AppliedAssembled {
+ const a=job.assembled,fig=(f:Record<string,number>|null|undefined)=>f?{...f}:null;
+ return {wallMs:job.wallMs.op,recomposite:{before:fig(a?.recomposite.before as Record<string,number>|null),after:fig(a?.recomposite.after as Record<string,number>|null)},partsChanged:[...(a?.parts?.changed??[])],seamPairs:(a?.seamPairs??[]).slice(0,64)};
+}
+/** What the draft keeps and `context.applied` carries for a delta: the document and its hash, the producer's line, op "remesh", the diff and the counts. */
+export const deltaAppliedRecord=(job:DeltaJobView):AppliedDelta=>({schema:APPLIED_DELTA_SCHEMA,buildId:job.id,part:job.request.part,delta:JSON.parse(JSON.stringify(job.request.delta)),deltaSha256:job.request.deltaSha256,configHash:job.request.configHash,producer:job.producer,compiler:job.compiler,line:job.producerLine,op:'remesh',files:job.files,...(job.remesh?{mesh:{part:job.remesh.part,before:{...job.remesh.before},after:{...job.remesh.after}}}:{}),modelHash:job.build!.modelHash});
+/** A delta job's status line: built (wall clocks, counts, the per-file diff) or the producer's line verbatim. */
+export function deltaOutcomeLine(result:DeltaJobView|RebuildRefusal):{text:string;error:boolean} {
+ if(!('id' in result))return {text:result.producerLine??result.error,error:true};
+ if(result.status!=='built')return {text:result.producerLine??`REBUILD_FAILED: exit ${result.exitCode}`,error:true};
+ const ops=Array.isArray(result.request.delta.ops)?result.request.delta.ops.length:0;
+ const wall=result.reused?'reused the scratch build of this exact delta':`remesh --delta ${seconds(result.wallMs.op)} + compile ${seconds(result.wallMs.compile)}`;
+ const counts=result.remesh?` · ${result.remesh.part} v ${result.remesh.before.vertices} t ${result.remesh.before.triangles} → v ${result.remesh.after.vertices} t ${result.remesh.after.triangles}`:'';
+ return {text:`Applied mesh edit ${result.request.deltaSha256.slice(0,12)}… (${ops} op(s) on ${result.request.part}) with ${result.producer.package} ${result.producer.version} · ${wall}${counts} · ${result.files?filesDiffText(result.files):'no diff'} · Reset returns to the inspected build`,error:false};
+}
+/**
+ * What the stage draws after an Apply: the scratch build when the job built one, else what it drew before — a
+ * refusal, a failure or a busy reply leaves the stage's model (and its hash) as it was.
+ */
+export function stageModel(result:AnyJobView|RebuildRefusal,current:{url:string;hash:string}):{url:string;hash:string;id:string|null} {
+ if('id' in result&&result.status==='built'&&result.build)return {url:result.build.modelUrl,hash:result.build.modelHash,id:result.id};
+ return {...current,id:null};
+}
+const seconds=(ms:number|null)=>ms===null?'—':`${(ms/1000).toFixed(1)} s`;
+/** A patch job's status line: built (wall clocks, check's verdict, the per-file diff — #125) or the producer's line verbatim. */
+export function patchOutcomeLine(result:PatchJobView|RebuildRefusal):{text:string;error:boolean} {
+ if(!('id' in result))return {text:result.producerLine??result.error,error:true};
+ if(result.status!=='built')return {text:result.producerLine??`REBUILD_FAILED: exit ${result.exitCode}`,error:true};
+ const check=result.check?(result.check.pass===null?`check refused: ${result.check.line??`exit ${result.check.exitCode}`}`:`check ${result.check.pass?'PASS':'FAIL'}`):'check not run';
+ // #115: a build's own wall clock covers assemble, rig and check; the recorded figure is the same number.
+ const wall=result.op==='build'?`${result.reused?'reused the scratch build of this exact patch · ':''}build ${seconds(result.wallMs.op)} (assemble → rig → check) + compile ${seconds(result.wallMs.compile)}`:result.reused?'reused the scratch build of this exact patch':`${result.op??result.request.patch.op.cmd} ${seconds(result.wallMs.op)} + compile ${seconds(result.wallMs.compile)} + check ${seconds(result.wallMs.check)}`;
+ return {text:`Applied patch ${result.request.patchSha256.slice(0,12)}… (${result.request.patch.ops.length} op(s)) with ${result.producer.package} ${result.producer.version} · ${wall} · ${check} · ${result.files?filesDiffText(result.files):`rig.json differs at ${result.diff?.count??'?'} path(s)`} · Reset returns to the inspected build`,error:!!result.check&&result.check.pass!==true};
+}
+/** The status line after a job: built (with the wall clock and whether the scratch build was reused) or the producer's line verbatim. */
+export function outcomeLine(result:RebuildJobView|RebuildRefusal):{text:string;error:boolean} {
+ if(!('id' in result))return {text:result.producerLine??result.error,error:true};
+ if(result.status!=='built')return {text:result.producerLine??`REBUILD_FAILED: exit ${result.exitCode}`,error:true};
+ const wall=[result.wallMs.remesh,result.wallMs.compile].every(v=>v!==null)?` · remesh ${(result.wallMs.remesh!/1000).toFixed(1)} s + compile ${(result.wallMs.compile!/1000).toFixed(1)} s`:'';
+ return {text:`Applied ${result.request.part} with ${result.producer.package} ${result.producer.version}${result.reused?' · reused the scratch build of this exact designation':wall} · Reset returns to the inspected build`,error:false};
+}
+
+/**
+ * The editor bar's handoff line, shown before any Apply: how the config was found (declared, or discovered — and
+ * outside the opened folder when it is the `../config.json` beside an opened out/), its path and hash, then the
+ * baseline. Without a handoff it is the refusal naming where it was looked for and how to declare it.
+ */
+export function handoffText(status:Pick<RebuildStatusView,'handoff'|'baseline'|'reason'>):{text:string;error:boolean} {
+ const h=status.handoff;
+ if(!h)return {text:status.reason??'MODELING_HANDOFF_MISSING',error:true};
+ const how=h.how==='declared'?`declared (${h.via})`:h.outside?'discovered outside the opened folder':'discovered';
+ const parts=h.parts?` · parts ${h.parts==='.'?'(the opened folder)':h.parts}`:'';
+ const base=status.baseline?` · ${status.baseline.wallMs!==null&&status.baseline.status!=='running'?`${status.baseline.line} (${(status.baseline.wallMs/1000).toFixed(1)} s)`:status.baseline.line}`:' · baseline: waits for the producer';
+ return {text:`Handoff ${how}: ${h.config.path} sha256 ${h.config.sha256.slice(0,12)}…${parts}${base}`,error:!!status.baseline&&['not-reproduced','refused','failed'].includes(status.baseline.status)};
+}