@rig-c/review 0.6.0 → 0.7.1

package/web/requirements-panel.ts

@@ -0,0 +1,241 @@
+/**
+ * Animate · Requirements (#113), page side: declare what the scene asks of the motion — pick a slot (its mesh
+ * attachment, its bone) on the stage or by name, an animation and a kind, then set the bar with a slider that shows the
+ * last measured value — and Check: review writes the `spine-parts-requirements/1` file and the installed producer's
+ * `rig-parts check --requirements` measures it, on the inspected rig or the latest scratch build. Each requirement gets
+ * one line with its worst frame, a button that seeks there; `REQUIREMENTS_*` refusals and `CHECK_REQUIREMENT_*` lines are
+ * shown verbatim. The file rides submitted feedback by hash and content (`context.requirements`).
+ * A kind the rig cannot offer (no mesh slot, no ik or transform constraint, fewer than two slots) is disabled with the
+ * reason. Scene targets, stage-point targets, the part exception lists and waivers (`may_fold`) are not written here.
+ */
+import {KIND_FIELDS,REQUIREMENT_KINDS,REQUIREMENT_NAME,REQUIREMENTS_CONTEXT_SCHEMA,requirementEntry,requirementsDocument,requirementsFileText,type BonePoint,type Requirement,type RequirementKind,type RequirementRow,type RequirementsBuild,type RequirementsContext} from '../src/requirements.ts';
+
+export interface RequirementsCatalogView {status:'ready'|'unavailable';reason:string|null;bones:string[];slots:string[];meshes:Record<string,string[]>;slotBones:Record<string,string>;constraints:{name:string;type:'ik'|'transform';bones:string[];drives:string[]}[];animations:{name:string;duration:number|null}[];scratch:string|null}
+export interface RequirementsJobView {id:string;status:'running'|'checked'|'refused'|'failed';build:RequirementsBuild;buildId:string|null;file:{sha256:string;size:number;text:string};producer:{package:string;version:string};exitCode:number|null;wallMs:number|null;rows:RequirementRow[];summary:string|null;checkLine:string|null;refusals:string[];problems:string[];error:string|null;lines:string[]}
+export interface RequirementsRefusal {status:'refused';error:string}
+export interface RequirementsPanelDeps {
+ /** Runs the check of this file text's requirements; the panel shows what comes back. */
+ check:(body:{fps:number;build:RequirementsBuild;requirements:Record<string,unknown>[]})=>Promise<RequirementsJobView|RequirementsRefusal|null>;
+ seek:(animation:string,frame:number,time:number|null,label:string)=>void;
+ /** The drawn animation and the slot picked on the stage. */
+ animation:()=>string;slot:()=>string|null;
+ /** The file's sha256 (hex) for the feedback context. */
+ hash:(text:string)=>Promise<string>;
+}
+export interface RequirementsPanel {
+ load(catalog:RequirementsCatalogView|null,reason:string|null):void;
+ /** Prefill the subject from the stage's selection. */
+ selectionChanged():void;
+ requirements():Requirement[];
+ add(r:Requirement):void;remove(name:string):void;setBar(name:string,field:string,value:number):void;
+ text():string|null;
+ checked(job:RequirementsJobView|RequirementsRefusal|null):void;
+ context():RequirementsContext|null;
+ shownLines():string[];
+}
+/** A kind the catalog cannot offer, and why; null when it can. */
+export function kindUnavailable(kind:RequirementKind,c:Pick<RequirementsCatalogView,'bones'|'slots'|'meshes'|'constraints'>):string|null {
+ if(kind==='stretch'&&!Object.values(c.meshes).some(list=>list.length))return 'no slot of the rig spec holds a mesh attachment';
+ if(kind==='follow'&&!c.constraints.length)return 'the rig spec declares no ik or transform constraint';
+ if(kind==='seam'&&c.slots.length<2)return 'a seam needs two slots';
+ if((kind==='contact'||kind==='aim'||kind==='range')&&!c.bones.length)return 'the rig spec declares no bone';
+ return null;
+}
+/** Each kind's bar fields and the slider's span; the span grows to hold a measured value past it. */
+export const BAR_FIELDS:Record<RequirementKind,{field:string;min:number;max:number;step:number;initial:number}[]>={
+ contact:[{field:'within_px',min:0,max:50,step:.1,initial:1}],
+ aim:[{field:'within_degrees',min:0,max:180,step:.5,initial:5}],
+ range:[{field:'lo_degrees',min:-180,max:180,step:1,initial:-45},{field:'hi_degrees',min:-180,max:180,step:1,initial:45}],
+ stretch:[{field:'within_ratio',min:1,max:3,step:.01,initial:1.3}],
+ follow:[{field:'fraction',min:-1,max:2,step:.01,initial:.5}],
+ seam:[{field:'within_px',min:0,max:20,step:.1,initial:1}],
+};
+/** A requirement name the reader takes, unique among `taken`: `KIND_SUBJECT`, then `_2`, `_3`… */
+export function requirementName(kind:RequirementKind,subject:string,taken:readonly string[]):string {
+ let base=`${kind}_${subject}`.toUpperCase().replace(/[^A-Z0-9_]+/g,'_').replace(/_+/g,'_').replace(/^_|_$/g,'');if(!/^[A-Z]/.test(base))base=`R_${base}`;
+ let name=base;for(let n=2;taken.includes(name);n++)name=`${base}_${n}`;return name;
+}
+/**
+ * A contact against its own bone and point, or an aim at its own bone, measures 0 by construction and the producer
+ * reports it as PASS (rig-c/review#142; the reader's refusal is asked in rig-c/parts#540). Refused here by name.
+ */
+export function selfTargetRefusal(r:{kind:RequirementKind;bone?:string;point?:BonePoint;target?:{bone:string;point:BonePoint}}):string|null {
+ if(!r.target||!r.bone)return null;
+ if(r.kind==='contact'&&r.target.bone===r.bone&&r.target.point===r.point)return `REQUIREMENTS_SELF_TARGET: contact of bone "${r.bone}" ${r.point} against itself measures 0 in every frame; pick another bone or point`;
+ if(r.kind==='aim'&&r.target.bone===r.bone)return `REQUIREMENTS_SELF_TARGET: aim of bone "${r.bone}" at its own ${r.target.point} has no line to measure; pick another target bone`;
+ return null;
+}
+/** The catalog the form renders from: only a ready rig spec. An unavailable one (no producer handoff) is no catalog, so picking a part with no handoff never renders fields from it (#150). */
+export function readyCatalog<C extends {status:'ready'|'unavailable'}>(next:C|null):C|null {return next&&next.status==='ready'?next:null;}
+/** The target a fresh form proposes: a bone other than the subject (the next one in rig order, else the first other one). */
+export function defaultTargetBone(bones:readonly string[],subject:string):string|null {
+ const i=bones.indexOf(subject),next=i>=0?bones.slice(i+1).find(b=>b!==subject):undefined;
+ return next??bones.find(b=>b!==subject)??null;
+}
+/** The measured figure a bar field is read against, from a row. */
+export function measuredFor(row:RequirementRow|undefined,field:string):number|null {
+ if(!row)return null;if(field==='lo_degrees')return row.least;if(field==='hi_degrees')return row.greatest;return row.measured;
+}
+
+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 options=(select:HTMLSelectElement,values:readonly string[],label=(v:string)=>v)=>{const keep=select.value;select.replaceChildren(...values.map(v=>make('option',{value:v,textContent:label(v)})));if(values.includes(keep))select.value=keep;};
+const labelled=(text:string,control:HTMLElement)=>make('label',{},text,control);
+
+export function bindRequirementsPanel(deps:RequirementsPanelDeps):RequirementsPanel {
+ const body=node('requirements-body');
+ const state=make('p',{className:'hint',id:'requirements-state',textContent:'No producer handoff loaded.'});
+ const kind=make('select',{id:'requirements-kind'}),animation=make('select',{id:'requirements-animation'});
+ const fields=make('div',{className:'requirements-fields',id:'requirements-fields'}),note=make('p',{className:'hint',id:'requirements-note'});
+ const name=make('input',{type:'text',id:'requirements-name',autocomplete:'off',placeholder:'NAME (letters, digits, _)'});
+ const add=make('button',{type:'button',id:'requirements-add',textContent:'Add requirement'});
+ const list=make('ol',{className:'requirements-list',id:'requirements-list'});
+ const build=make('select',{id:'requirements-build'}),fps=make('input',{type:'number',id:'requirements-fps',min:'1',max:'240',step:'1',value:'12'});
+ const check=make('button',{type:'button',id:'requirements-check',className:'primary',textContent:'Check',disabled:true});
+ const status=make('output',{id:'requirements-status',className:'environment-readout'}),refusals=make('ul',{className:'requirements-refusals',id:'requirements-refusals'}),summary=make('p',{className:'hint',id:'requirements-summary'});
+ options(build,['inspected','scratch'],v=>v==='inspected'?'Inspected rig':'Latest scratch build');
+ body.replaceChildren(state,make('div',{className:'row'},labelled('Kind ',kind),labelled('Animation ',animation)),fields,note,make('div',{className:'row'},name,add),list,
+  make('div',{className:'row'},labelled('Check on ',build),labelled('fps ',fps),check),status,refusals,summary);
+ let catalog:RequirementsCatalogView|null=null,declared:Requirement[]=[],job:RequirementsJobView|null=null,busy=false,shown:string[]=[];
+ let hashed:{text:string;sha256:string}|null=null;
+ const controls:Record<string,HTMLSelectElement|HTMLInputElement>={};
+
+ const sel=(id:string,values:readonly string[],label?:(v:string)=>string)=>{const s=make('select',{id:`requirements-${id}`});options(s,values,label);controls[id]=s;return s;};
+ const numberField=(id:string,value:number,min?:number)=>{const i=make('input',{type:'number',id:`requirements-${id}`,value:String(value),step:'any',...(min===undefined?{}:{min:String(min)})});controls[id]=i;return i;};
+ /** The subject inputs for the chosen kind, prefilled from the stage's slot (its bone, its mesh). */
+ function renderFields(){
+  fields.replaceChildren();for(const k of Object.keys(controls))delete controls[k];
+  if(!catalog)return;
+  const k=kind.value as RequirementKind,slot=deps.slot(),slotBone=slot?catalog.slotBones[slot]??null:null;
+  const bones=catalog.bones,points=['origin','tip'];
+  const pickBone=(id:string)=>{const s=sel(id,bones);if(slotBone&&bones.includes(slotBone))s.value=slotBone;return s;};
+  /** The subject and target selects, the target defaulting to another bone and moved off the subject when the subject changes to it. */
+  const pickPair=()=>{const subject=pickBone('bone'),target=sel('target-bone',bones);const away=()=>{const d=defaultTargetBone(bones,subject.value);if(d&&target.value===subject.value)target.value=d;};away();subject.addEventListener('change',away);return [subject,target] as const;};
+  if(k==='contact'){const [b,t]=pickPair();fields.append(make('div',{className:'row'},labelled('Bone ',b),labelled('point ',sel('point',points))),make('div',{className:'row'},labelled('Target bone ',t),labelled('point ',sel('target-point',points))));}
+  else if(k==='aim'){const [b,t]=pickPair();fields.append(make('div',{className:'row'},labelled('Bone ',b)),make('div',{className:'row'},labelled('Target bone ',t),labelled('point ',sel('target-point',points))));}
+  else if(k==='range'){fields.append(make('div',{className:'row'},labelled('Bone ',pickBone('bone'))));}
+  else if(k==='stretch'){
+   const meshSlots=catalog.slots.filter(s=>catalog!.meshes[s]?.length),slotSel=sel('slot',meshSlots);if(slot&&meshSlots.includes(slot))slotSel.value=slot;
+   const att=sel('attachment',catalog.meshes[slotSel.value]??[]);slotSel.onchange=()=>options(att as HTMLSelectElement,catalog!.meshes[slotSel.value]??[]);
+   fields.append(make('div',{className:'row'},labelled('Slot ',slotSel),labelled('mesh ',att)));
+  } else if(k==='seam'){
+   const part=sel('part',catalog.slots);if(slot&&catalog.slots.includes(slot))part.value=slot;const neighbour=sel('neighbour',catalog.slots.filter(s=>s!==part.value));
+   part.onchange=()=>options(neighbour as HTMLSelectElement,catalog!.slots.filter(s=>s!==part.value));
+   fields.append(make('div',{className:'row'},labelled('Part ',part),labelled('neighbour ',neighbour)));
+  } else {
+   const keys=catalog.constraints.map(c=>`${c.type}:${c.name}`),constraint=sel('constraint',keys,v=>v.replace(':',' '));
+   const pick=()=>catalog!.constraints[Math.max(0,keys.indexOf(constraint.value))];
+   const bone=sel('bone',pick()?.bones??[]),prop=sel('property',pick()?.drives??[]);
+   constraint.onchange=()=>{options(bone as HTMLSelectElement,pick()?.bones??[]);options(prop as HTMLSelectElement,pick()?.drives??[]);};
+   fields.append(make('div',{className:'row'},labelled('Constraint ',constraint)),make('div',{className:'row'},labelled('Bone ',bone),labelled('property ',prop)),
+    make('div',{className:'row'},labelled('tolerance ',numberField('tolerance',.05,0)),labelled('least drive ',numberField('least-drive',2,0))));
+  }
+  const why=kindUnavailable(k,catalog);note.textContent=why?`${k} is not offered here: ${why}.`:`The bar (${BAR_FIELDS[k].map(b=>b.field).join(', ')}) is set on the slider once added; the producer reads ${KIND_FIELDS[k].join(', ')}.`;note.classList.toggle('error',!!why);
+  add.disabled=!!why||busy;
+  name.placeholder=requirementName(k,subjectOf(k)??'',declared.map(r=>r.name));
+ }
+ const v=(id:string)=>controls[id]?.value??'';
+ function subjectOf(k:RequirementKind):string|null {return k==='stretch'?v('slot'):k==='seam'?`${v('part')}_${v('neighbour')}`:v('bone')||null;}
+ /** The requirement the inputs describe, with each bar at its initial value; a missing name says which. */
+ function fromInputs():Requirement|string {
+  if(!catalog)return 'REQUIREMENTS_UNAVAILABLE: no rig spec loaded';
+  const k=kind.value as RequirementKind,anim=animation.value;if(!anim)return 'an animation is required';
+  const why=kindUnavailable(k,catalog);if(why)return `${k} is not offered here: ${why}`;
+  const subject=subjectOf(k);if(!subject)return 'pick the subject';
+  const n=name.value.trim()||requirementName(k,subject,declared.map(r=>r.name));
+  if(!REQUIREMENT_NAME.test(n))return `name ${JSON.stringify(n)}: a letter, then letters, digits and underscores`;
+  if(declared.some(r=>r.name===n))return `name ${n} is declared already`;
+  const bar=Object.fromEntries(BAR_FIELDS[k].map(b=>[b.field,b.initial]));const common={name:n,animation:anim};
+  const target=()=>({bone:v('target-bone'),point:v('target-point') as BonePoint});
+  for(const id of Object.keys(controls))if(!v(id))return `${id.replace('-',' ')} is required`;
+  if(k==='contact'||k==='aim'){const self=selfTargetRefusal({kind:k,bone:v('bone'),point:v('point') as BonePoint,target:target()});if(self)return self;}
+  if(k==='contact')return {...common,kind:k,bone:v('bone'),point:v('point') as BonePoint,target:target(),within_px:bar.within_px!};
+  if(k==='aim')return {...common,kind:k,bone:v('bone'),target:target(),within_degrees:bar.within_degrees!};
+  if(k==='range')return {...common,kind:k,bone:v('bone'),lo_degrees:bar.lo_degrees!,hi_degrees:bar.hi_degrees!};
+  if(k==='stretch')return {...common,kind:k,slot:v('slot'),attachment:v('attachment'),within_ratio:bar.within_ratio!};
+  if(k==='seam')return {...common,kind:k,part:v('part'),neighbour:v('neighbour'),within_px:bar.within_px!};
+  const [type,...rest]=v('constraint').split(':'),tolerance=Number(v('tolerance')),least=Number(v('least-drive'));
+  if(!Number.isFinite(tolerance)||tolerance<0)return 'tolerance: a number 0 or more';if(!Number.isFinite(least)||least<=0)return 'least drive: a number above 0';
+  return {...common,kind:'follow',constraint:rest.join(':'),constraint_type:type as 'ik'|'transform',bone:v('bone'),property:v('property') as 'rotate'|'translate',fraction:bar.fraction!,tolerance,least_drive:least};
+ }
+ const fpsValue=()=>{const n=Number(fps.value);return Number.isFinite(n)&&n>0&&n<=240?n:null;};
+ function fileText():string|null {const f=fpsValue();return declared.length&&f!==null?requirementsFileText(requirementsDocument(f,declared.map(requirementEntry))):null;}
+ function rehash(){const text=fileText();if(text===null){hashed=null;return;}void deps.hash(text).then(sha256=>{if(fileText()===text)hashed={text,sha256};});}
+ function panelStatus(text:string,error:boolean){status.textContent=text;status.title=text;status.classList.toggle('error',error);}
+ /** One row per declared requirement: its bar slider(s) (the last measured value marked on the track), its line, a seek to its worst frame. */
+ function renderList(){
+  list.replaceChildren();shown=[];
+  const current=job&&job.file.text===fileText()?job:null;
+  for(const r of declared){
+   const row=job?.rows.find(x=>x.name===r.name),stale=!!row&&!current;
+   const item=make('li',{className:`requirements-item${row?` ${row.status==='PASS'?'pass':'fail'}`:''}`});item.dataset.name=r.name;
+   const head=make('div',{className:'row'},make('code',{textContent:`${r.name} · ${r.kind} · ${r.animation}`}));
+   const remove=make('button',{type:'button',textContent:'Remove',title:`Remove ${r.name}`});remove.onclick=()=>panel.remove(r.name);head.append(remove);item.append(head);
+   for(const b of BAR_FIELDS[r.kind]){
+    const value=(r as unknown as Record<string,number>)[b.field]!,measured=measuredFor(row,b.field);
+    const lo=Math.min(b.min,value,measured??b.min),hi=Math.max(b.max,value,measured===null?b.max:Math.ceil(measured*1.25*100)/100);
+    const slider=make('input',{type:'range',min:String(lo),max:String(hi),step:String(b.step),value:String(value)});slider.setAttribute('aria-label',`${r.name} ${b.field}`);
+    if(measured!==null){const marks=make('datalist',{id:`requirements-mark-${r.name}-${b.field}`},make('option',{value:String(measured)}));slider.setAttribute('list',marks.id);item.append(marks);}
+    const out=make('output',{textContent:`${b.field} ${value}`});
+    slider.oninput=()=>{out.textContent=`${b.field} ${slider.value}`;};slider.onchange=()=>panel.setBar(r.name,b.field,Number(slider.value));
+    item.append(make('div',{className:'row requirements-bar'},slider,out,make('span',{className:'subtle',textContent:measured===null?'not measured yet':`measured ${measured}${stale?' (before this change)':''}`})));
+   }
+   if(row){
+    const text=row.line,worst=row.worst;shown.push(text);
+    if(worst){const go=make('button',{type:'button',className:'readings-go',textContent:text,title:`Seek to ${worst.text}`});go.onclick=()=>deps.seek(row.animation||r.animation,worst.frame,worst.time,`${r.name} worst`);item.append(go);}
+    else item.append(make('code',{textContent:text,title:text}));
+   }
+   list.append(item);
+  }
+  check.disabled=busy||!declared.length||!catalog||catalog.status!=='ready';
+ }
+ function changed(){rehash();renderList();renderFields();}
+
+ kind.onchange=renderFields;
+ add.onclick=()=>{const r=fromInputs();if(typeof r==='string'){panelStatus(r,true);return;}declared.push(r);name.value='';panelStatus(`Added ${r.name}; set its bar, then Check.`,false);changed();};
+ fps.onchange=changed;
+ check.onclick=()=>{void (async()=>{
+  const f=fpsValue();if(f===null){panelStatus('fps: a number above 0, at most 240',true);return;}
+  busy=true;check.disabled=true;check.textContent='Checking…';panelStatus(`rig-parts check --requirements on the ${build.value==='inspected'?'inspected rig':'latest scratch build'}…`,false);
+  try{panel.checked(await deps.check({fps:f,build:build.value as RequirementsBuild,requirements:declared.map(requirementEntry)}));}
+  finally{busy=false;check.textContent='Check';renderList();renderFields();}
+ })();};
+
+ const panel:RequirementsPanel={
+  load(next,reason){
+   // Only a ready spec is a catalog: an unavailable one (no producer handoff, #150) leaves the form empty, so selecting a part never renders fields from it.
+   catalog=readyCatalog(next);
+   if(!next||next.status!=='ready'){state.textContent=reason??next?.reason??'REQUIREMENTS_UNAVAILABLE: no producer handoff';state.classList.add('error');kind.disabled=animation.disabled=true;add.disabled=check.disabled=true;fields.replaceChildren();return;}
+   state.textContent=`Rig spec: ${next.bones.length} bones, ${next.slots.length} slots, ${Object.keys(next.meshes).length} mesh slot(s), ${next.constraints.length} ik/transform constraint(s), ${next.animations.length} animation(s)${next.scratch?' · a scratch build exists':''}.`;state.classList.remove('error');
+   kind.disabled=animation.disabled=false;
+   options(kind,REQUIREMENT_KINDS,k=>{const why=kindUnavailable(k as RequirementKind,next);return why?`${k} — unavailable`:k;});
+   options(animation,next.animations.map(a=>a.name));const drawn=deps.animation();if(next.animations.some(a=>a.name===drawn))animation.value=drawn;
+   renderFields();renderList();
+  },
+  selectionChanged(){const drawn=deps.animation();if(catalog?.animations.some(a=>a.name===drawn))animation.value=drawn;renderFields();},
+  requirements:()=>declared.map(r=>JSON.parse(JSON.stringify(r)) as Requirement),
+  add(r){declared.push(JSON.parse(JSON.stringify(r)) as Requirement);changed();},
+  remove(n){declared=declared.filter(r=>r.name!==n);changed();},
+  setBar(n,field,value){const r=declared.find(x=>x.name===n) as unknown as Record<string,unknown>|undefined;if(!r||!(KIND_FIELDS[(r.kind as RequirementKind)]??[]).includes(field)||!Number.isFinite(value))return;r[field]=value;changed();},
+  text:fileText,
+  checked(result){
+   refusals.replaceChildren();summary.textContent='';
+   if(!result){panelStatus('REQUIREMENTS_FAILED: no answer from the check',true);return;}
+   if(!('id' in result)){panelStatus(result.error,true);return;}
+   job=result;
+   for(const line of [...result.refusals,...result.problems])refusals.append(make('li',{},make('code',{textContent:line,title:line})));
+   summary.textContent=[result.summary,result.checkLine].filter(Boolean).join(' · ');
+   if(result.status==='checked')panelStatus(`${result.producer.package} ${result.producer.version} check on the ${result.build==='inspected'?'inspected rig':'scratch build'}: ${result.rows.length} line(s)${result.wallMs===null?'':` · ${(result.wallMs/1000).toFixed(1)} s`}`,result.rows.some(r=>r.status!=='PASS'));
+   else panelStatus(result.error??`requirements check ${result.status}`,true);
+   renderList();
+  },
+  context(){
+   const text=fileText();if(text===null||!hashed||hashed.text!==text)return null;
+   const last=job&&job.file.text===text&&job.status!=='running'&&job.status!=='failed'?job:null;
+   return {schema:REQUIREMENTS_CONTEXT_SCHEMA,sha256:hashed.sha256,size:new TextEncoder().encode(text).length,text,
+    checked:last?{build:last.build,producer:{...last.producer},summary:last.summary,refusals:[...last.refusals],rows:last.rows.map(r=>({name:r.name,status:r.status,worst:r.worst?{...r.worst}:null}))}:null};
+  },
+  shownLines:()=>[...shown],
+ };
+ return panel;
+}

package/web/retarget-panel.ts

@@ -0,0 +1,203 @@
+/**
+ * Animate · Retarget (#114), page side: a `rig-pose-map/1` editor — per chain, include it and pick the rig bone that
+ * carries each segment (and its bend), the translated bone and its scale points — the clean and retarget flags as typed
+ * controls, the declared pose sequence to read, then Apply · Retarget. The server runs the installed `rig-pose clean`,
+ * `rig-pose retarget` and the compile into scratch; this draws what came back: the producer's lines (every refusal
+ * verbatim) and the run's FEET / STANCE / FLIP / SHORT / END-ON / LEG-SCALE / REACH lines, each a button that seeks to
+ * its frame. The map starts from a loaded `rig-pose-map/1` file (read in the page, sent by content) or the body-18
+ * chains with no bone picked. Review authors no keys: the motion is the producer's.
+ */
+import {DEFAULT_CLEAN,DEFAULT_FLAGS,POSE_MAP_SCHEMA,type RetargetFlags,type RetargetLine} from '../src/retarget.ts';
+import type {RetargetJobView,RetargetStatusView,RebuildRefusal} from './rebuild-client.ts';
+
+type Chain={name:string;bones:string[];joints:string[];bend?:string;[key:string]:unknown};
+export type PoseMap={spec:typeof POSE_MAP_SCHEMA;chains:Chain[];translate?:{bone:string;joint:string;scale?:{pose:[string,string];rig:[string,string]}};[key:string]:unknown};
+/** The body-18 chains a front-facing figure maps (README, "The map"), no bone picked: the editor's start without a map file. */
+export function templateMap():PoseMap {
+ return {spec:POSE_MAP_SCHEMA,chains:[
+  {name:'trunk',bones:[''],joints:['mid_hip','neck'],aim:['neck']},
+  {name:'arm_r',bones:['',''],joints:['r_shoulder','r_elbow','r_wrist'],bend:'free'},
+  {name:'arm_l',bones:['',''],joints:['l_shoulder','l_elbow','l_wrist'],bend:'free'},
+  {name:'leg_r',bones:['',''],joints:['r_hip','r_knee','r_ankle'],bend:'free'},
+  {name:'leg_l',bones:['',''],joints:['l_hip','l_knee','l_ankle'],bend:'free'},
+ ],translate:{bone:'',joint:'mid_hip',scale:{pose:['mid_hip','neck'],rig:['','']}}};
+}
+/** A bone not yet picked, refused before anything is sent; whether a picked bone is the rig's is the producer's to say. */
+export function mapPrecheck(map:PoseMap):string|null {
+ if(!map.chains.length)return 'RETARGET_MAP_INCOMPLETE: no chain is included';
+ for(const c of map.chains){const i=c.bones.findIndex(b=>!b);if(i>=0)return `RETARGET_MAP_INCOMPLETE: chain "${c.name}" bone ${i+1} (${c.joints[i]} → ${c.joints[i+1]??'?'}) is not picked`;}
+ if(map.translate&&!map.translate.bone)return 'RETARGET_MAP_INCOMPLETE: the translated bone is not picked';
+ if(map.translate?.scale&&map.translate.scale.rig.some(b=>!b))return 'RETARGET_MAP_INCOMPLETE: the translate scale\'s rig points are not picked';
+ return null;
+}
+/** A document read from a file or the JSON field: a `rig-pose-map/1` with chains, else the line saying why not. */
+export function readMap(text:string):{map:PoseMap}|{error:string} {
+ let value:unknown;try{value=JSON.parse(text);}catch(error){return {error:`RETARGET_MAP_INVALID: ${error instanceof Error?error.message:String(error)}`};}
+ const v=value as PoseMap;
+ if(!v||typeof v!=='object'||v.spec!==POSE_MAP_SCHEMA||!Array.isArray(v.chains)||!v.chains.every(c=>c&&typeof c.name==='string'&&Array.isArray(c.bones)&&Array.isArray(c.joints)))return {error:`RETARGET_MAP_INVALID: expected a ${POSE_MAP_SCHEMA} document with chains of {name, bones, joints}`};
+ return {map:JSON.parse(JSON.stringify(v)) as PoseMap};
+}
+
+export interface RetargetPanelDeps {
+ apply:(body:{sequence:string;map:PoseMap;flags:RetargetFlags})=>Promise<RetargetJobView|RebuildRefusal|null>;
+ reset:()=>void;
+ seek:(animation:string,frame:number,time:number|null,label:string)=>void;
+}
+export interface RetargetPanel {
+ load(status:RetargetStatusView|null,reason:string|null):void;
+ map():PoseMap;setMap(map:PoseMap):void;
+ /** Include or leave out a chain by name. */
+ include(chain:string,on:boolean):void;
+ pick(chain:string,index:number,bone:string):void;
+ flags():RetargetFlags|{error:string};setFlags(flags:Partial<RetargetFlags>):void;
+ sequence():string;
+ busy(value:boolean):void;
+ status(text:string,error:boolean):void;
+ line(text:string):void;
+ result(job:RetargetJobView|RebuildRefusal|null):void;
+ shownLines():string[];
+}
+
+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;};
+// A checkbox reads after its box; a field after its name.
+const labelled=(text:string,control:HTMLElement)=>control instanceof HTMLInputElement&&control.type==='checkbox'?make('label',{},control,text):make('label',{},text,control);
+const numberInput=(id:string,value:number,step:string,label:string)=>{const n=make('input',{id,type:'number',step,value:String(value)});n.setAttribute('aria-label',label);return n;};
+const checkbox=(id:string,checked=false)=>make('input',{id,type:'checkbox',checked});
+
+export function bindRetargetPanel(deps:RetargetPanelDeps):RetargetPanel {
+ const body=node('retarget-body');
+ let status:RetargetStatusView|null=null,entries:{chain:Chain;on:boolean}[]=[],rest:Omit<PoseMap,'chains'>={spec:POSE_MAP_SCHEMA},shown:string[]=[],isBusy=false;
+ const log:string[]=[];
+ // Controls.
+ const sequence=make('select',{id:'retarget-sequence'});sequence.setAttribute('aria-label','Pose sequence');
+ const person=make('select',{id:'retarget-person'});person.setAttribute('aria-label','Person');
+ const template=make('button',{type:'button',textContent:'Body-18 chains'}),file=make('input',{id:'retarget-map-file',type:'file',accept:'.json,application/json'});file.setAttribute('aria-label','Load a rig-pose-map/1 file');
+ const chains=make('div',{id:'retarget-chains',className:'retarget-chains'}),translate=make('div',{id:'retarget-translate',className:'row retarget-translate'});
+ const json=make('textarea',{id:'retarget-map-json',rows:8,spellcheck:false}),useJson=make('button',{type:'button',textContent:'Use this JSON'});json.setAttribute('aria-label','Map JSON');
+ const clean=checkbox('retarget-clean',true),loop=checkbox('retarget-loop'),legs=numberInput('retarget-legs',DEFAULT_CLEAN.legs,'2','clean legs window'),restWin=numberInput('retarget-rest',DEFAULT_CLEAN.rest,'2','clean rest window'),hold=checkbox('retarget-hold',true),hips=checkbox('retarget-hips-inferred');
+ const animation=make('input',{id:'retarget-animation',type:'text',value:DEFAULT_FLAGS.animation,autocomplete:'off'});animation.setAttribute('aria-label','New animation name');
+ const opt=(id:string,value:number,step:string,label:string)=>({on:checkbox(`${id}-on`),value:numberInput(id,value,step,label)});
+ const minScore=opt('retarget-min-score',0.3,'0.05','min score'),flip=opt('retarget-flip',90,'1','flip degrees'),short=opt('retarget-short',0.35,'0.05','short fraction'),tolerance=opt('retarget-bend-tolerance',0,'1','bend tolerance degrees'),stance=opt('retarget-stance',0.07,'0.01','stance leg lengths');
+ const bends=make('select',{id:'retarget-bends'},make('option',{value:'refuse',textContent:'refuse'}),make('option',{value:'clamp',textContent:'clamp'}));bends.setAttribute('aria-label','Wrong-way bends');
+ const legScale={on:checkbox('retarget-leg-scale-on'),min:numberInput('retarget-leg-scale-min',0.8,'0.01','leg scale min'),max:numberInput('retarget-leg-scale-max',1.05,'0.01','leg scale max')};
+ const plant=checkbox('retarget-plant-feet'),raised=checkbox('retarget-raised-by-head'),carry=checkbox('retarget-carry-idle');
+ const apply=make('button',{id:'retarget-apply',type:'button',className:'primary',textContent:'Apply · Retarget',disabled:true}),reset=make('button',{id:'retarget-reset',type:'button',textContent:'Reset'});
+ const statusLine=make('p',{id:'retarget-status',className:'hint'});statusLine.setAttribute('aria-live','polite');
+ const logView=make('pre',{id:'retarget-log',className:'retarget-log',hidden:true}),refusals=make('ul',{id:'retarget-refusals',className:'requirements-refusals'}),readings=make('ul',{id:'retarget-lines',className:'readings-worst'});readings.setAttribute('aria-label','Retarget lines');
+ body.append(
+  make('div',{className:'row'},labelled('Sequence',sequence),labelled('Person',person)),
+  make('div',{className:'row'},make('span',{className:'eyebrow',textContent:'MAP · rig-pose-map/1'}),template,file),
+  chains,translate,
+  make('details',{className:'retarget-json'},make('summary',{textContent:'Map JSON (aims, ranges, alternates…)'}),json,make('div',{className:'row'},useJson)),
+  make('div',{className:'row'},make('span',{className:'eyebrow',textContent:'CLEAN'}),labelled('clean first',clean),labelled('loop',loop),labelled('legs',legs),labelled('rest',restWin),labelled('hold',hold),labelled('hips inferred',hips)),
+  make('div',{className:'row'},make('span',{className:'eyebrow',textContent:'RETARGET'}),labelled('as',animation)),
+  make('div',{className:'row'},labelled('flip °',flip.on),flip.value,labelled('short',short.on),short.value,labelled('min score',minScore.on),minScore.value),
+  make('div',{className:'row'},labelled('bends',bends),labelled('tolerance °',tolerance.on),tolerance.value,labelled('leg scale',legScale.on),legScale.min,legScale.max),
+  make('div',{className:'row'},labelled('plant feet',plant),labelled('stance',stance.on),stance.value,labelled('raised by head',raised),labelled('carry idle',carry)),
+  make('div',{className:'row'},apply,reset),statusLine,refusals,logView,readings,
+ );
+
+ const bonesOf=()=>status?.bones??[];
+ const boneSelect=(value:string,label:string,change:(v:string)=>void)=>{
+  const s=make('select');s.setAttribute('aria-label',label);
+  const names=bonesOf(),options=[make('option',{value:'',textContent:'— pick a bone —'}),...names.map(n=>make('option',{value:n,textContent:n}))];
+  // A bone the map names that the rig lacks stays visible: Apply sends it and the producer refuses it by name.
+  if(value&&!names.includes(value))options.push(make('option',{value,textContent:`${value} (not in the rig)`}));
+  s.append(...options);s.value=value;s.onchange=()=>change(s.value);return s;
+ };
+ const map=():PoseMap=>({...JSON.parse(JSON.stringify(rest)),chains:entries.filter(e=>e.on).map(e=>JSON.parse(JSON.stringify(e.chain)))}) as PoseMap;
+ function render(){
+  chains.replaceChildren(...entries.map((e,ci)=>{
+   const on=checkbox(`retarget-chain-${ci}`,e.on);on.onchange=()=>{e.on=on.checked;render();};
+   const row=make('div',{className:`retarget-chain${e.on?'':' off'}`},labelled(e.chain.name,on));
+   e.chain.bones.forEach((bone,bi)=>{row.append(make('code',{textContent:`${e.chain.joints[bi]??'?'}→${e.chain.joints[bi+1]??'?'}`}),boneSelect(bone,`${e.chain.name} bone ${bi+1}`,v=>{e.chain.bones[bi]=v;render();}));});
+   const bend=make('select',{},...['','rest','free','ccw','cw'].map(v=>make('option',{value:v,textContent:v||'bend: rest (default)'})));bend.setAttribute('aria-label',`${e.chain.name} bend`);bend.value=typeof e.chain.bend==='string'?e.chain.bend:'';bend.onchange=()=>{if(bend.value)e.chain.bend=bend.value;else delete e.chain.bend;render();};
+   row.append(bend);return row;
+  }));
+  translate.replaceChildren();
+  const t=rest.translate as PoseMap['translate'];
+  if(t){
+   translate.append(make('span',{textContent:`translate ${t.joint} →`}),boneSelect(t.bone,'translated bone',v=>{t.bone=v;render();}));
+   if(t.scale){translate.append(make('span',{textContent:`scale ${t.scale.pose.join('→')} =`}));t.scale.rig.forEach((b,i)=>translate.append(boneSelect(b,`scale rig point ${i+1}`,v=>{t.scale!.rig[i]=v;render();})));}
+  }
+  if(document.activeElement!==json)json.value=JSON.stringify(map(),null,1);
+  syncApply();
+ }
+ function setMap(next:PoseMap){const {chains:list,...others}=JSON.parse(JSON.stringify(next)) as PoseMap;rest=others;entries=list.map(chain=>({chain,on:true}));render();}
+ function syncApply(){apply.disabled=isBusy||!status?.available||!sequence.value;}
+ function people(){const s=status?.sequences.find(x=>x.id===sequence.value);person.replaceChildren(make('option',{value:'',textContent:s&&s.people.length>1?'— pick —':'(the one person)'}),...(s?.people??[]).map(p=>make('option',{value:p,textContent:p})));}
+ const say=(text:string,error:boolean)=>{statusLine.textContent=text;statusLine.title=text;statusLine.classList.toggle('error',error);};
+
+ template.onclick=()=>setMap(templateMap());
+ file.onchange=()=>{const f=file.files?.[0];if(!f)return;void f.text().then(text=>{const read=readMap(text);if('error' in read)say(read.error,true);else{setMap(read.map);say(`Map loaded from ${f.name} (by content; nothing is sent until Apply).`,false);}file.value='';});};
+ useJson.onclick=()=>{const read=readMap(json.value);if('error' in read)say(read.error,true);else{setMap(read.map);say('Map taken from the JSON field.',false);}};
+ sequence.onchange=()=>{people();syncApply();};
+ reset.onclick=()=>deps.reset();
+
+ function flags():RetargetFlags|{error:string}{
+  const n=(input:HTMLInputElement,what:string)=>{const v=Number(input.value);return input.value.trim()&&Number.isFinite(v)?v:null;};
+  const optional=(o:{on:HTMLInputElement;value:HTMLInputElement},what:string):number|null|{error:string}=>{if(!o.on.checked)return null;const v=n(o.value,what);return v===null?{error:`RETARGET_FLAG_INCOMPLETE: ${what}`}:v;};
+  const name=animation.value.trim();if(!name)return {error:'RETARGET_FLAG_INCOMPLETE: name the new animation'};
+  const values:Record<string,number|null>={};
+  for(const [key,o,what] of [['minScore',minScore,'min score'],['flip',flip,'flip degrees'],['short',short,'short fraction'],['bendTolerance',tolerance,'bend tolerance'],['stance',stance,'stance']] as const){const v=optional(o,what);if(v&&typeof v==='object')return v;values[key]=v;}
+  const lmin=n(legScale.min,'leg scale min'),lmax=n(legScale.max,'leg scale max');
+  if(legScale.on.checked&&(lmin===null||lmax===null))return {error:'RETARGET_FLAG_INCOMPLETE: leg scale min and max'};
+  const l=n(legs,'legs'),r=n(restWin,'rest');if(clean.checked&&(l===null||r===null))return {error:'RETARGET_FLAG_INCOMPLETE: clean windows'};
+  return {animation:name,person:person.value||null,clean:clean.checked?{loop:loop.checked,legs:l!,rest:r!,hold:hold.checked,hipsInferred:hips.checked}:null,
+   minScore:values.minScore??null,flip:values.flip??null,short:values.short??null,bends:bends.value as 'refuse'|'clamp',bendTolerance:values.bendTolerance??null,
+   legScale:legScale.on.checked?[lmin!,lmax!]:null,plantFeet:plant.checked,stance:values.stance??null,raisedByHead:raised.checked,carryIdle:carry.checked};
+ }
+ function setFlags(f:Partial<RetargetFlags>){
+  if(f.animation!==undefined)animation.value=f.animation;
+  if(f.person!==undefined)person.value=f.person??'';
+  if(f.clean!==undefined){clean.checked=!!f.clean;if(f.clean){loop.checked=f.clean.loop;legs.value=String(f.clean.legs);restWin.value=String(f.clean.rest);hold.checked=f.clean.hold;hips.checked=f.clean.hipsInferred;}}
+  for(const [key,o] of [['minScore',minScore],['flip',flip],['short',short],['bendTolerance',tolerance],['stance',stance]] as const){const v=f[key];if(v===undefined)continue;o.on.checked=v!==null;if(v!==null)o.value.value=String(v);}
+  if(f.bends)bends.value=f.bends;
+  if(f.legScale!==undefined){legScale.on.checked=!!f.legScale;if(f.legScale){legScale.min.value=String(f.legScale[0]);legScale.max.value=String(f.legScale[1]);}}
+  if(f.plantFeet!==undefined)plant.checked=f.plantFeet;if(f.raisedByHead!==undefined)raised.checked=f.raisedByHead;if(f.carryIdle!==undefined)carry.checked=f.carryIdle;
+ }
+
+ apply.onclick=()=>{
+  const m=map(),problem=mapPrecheck(m);if(problem){say(`${problem} (review pre-check; nothing sent)`,true);return;}
+  const f=flags();if('error' in f){say(`${f.error} (review pre-check; nothing sent)`,true);return;}
+  log.length=0;logView.textContent='';logView.hidden=true;
+  void deps.apply({sequence:sequence.value,map:m,flags:f});
+ };
+
+ function lineItem(r:RetargetLine,animationName:string){
+  const item=make('li',{className:'readings-line scratch'}),swatch=make('span',{className:'tick-swatch scratch'});swatch.setAttribute('aria-hidden','true');
+  if(r.frame!==null){const go=make('button',{type:'button',className:'readings-go',textContent:r.line,title:r.line});go.onclick=()=>deps.seek(animationName,r.frame!,r.time,`${r.code} F${r.frame}`);item.append(swatch,go);}
+  else item.append(swatch,make('code',{textContent:r.line,title:r.line}));
+  return item;
+ }
+ return {
+  load(next,reason){
+   status=next;const prior=sequence.value;
+   sequence.replaceChildren(...(next?.sequences??[]).map(s=>make('option',{value:s.id,textContent:`${s.label} · ${s.frames} frame(s) · ${s.cleaned?'cleaned':'raw'}`})));
+   if(prior&&next?.sequences.some(s=>s.id===prior))sequence.value=prior;
+   const s=next?.sequences.find(x=>x.id===sequence.value);if(s?.cleaned&&!prior)clean.checked=false;
+   people();if(!entries.length)setMap(templateMap());else render();
+   say(next?.available?`${next.producer?.package} ${next.producer?.version} with ${next.compiler?.package} ${next.compiler?.version} on the handoff rig${next.rig?` (${next.rig})`:''} · ${next.bones.length} bone(s), animations ${next.animations.join(', ')||'none'}`:(next?.reason??reason??'RETARGET_UNAVAILABLE'),!next?.available);
+   syncApply();
+  },
+  map,setMap,
+  include(name,on){const e=entries.find(x=>x.chain.name===name);if(e){e.on=on;render();}},
+  pick(name,index,bone){const e=entries.find(x=>x.chain.name===name);if(e&&index>=0&&index<e.chain.bones.length){e.chain.bones[index]=bone;render();}},
+  flags,setFlags,sequence:()=>sequence.value,
+  busy(value){isBusy=value;apply.textContent=value?'Retargeting…':'Apply · Retarget';syncApply();},
+  status:say,
+  line(text){log.push(text);logView.hidden=false;logView.textContent=log.slice(-12).join('\n');},
+  result(job){
+   refusals.replaceChildren();readings.replaceChildren();shown=[];
+   if(!job)return;
+   if(!('id' in job)){refusals.append(make('li',{},make('code',{textContent:job.producerLine??job.error})));return;}
+   for(const line of job.refusals??[])refusals.append(make('li',{},make('code',{textContent:line})));
+   if(job.status!=='built')return;
+   const name=job.request.record.flags.animation;
+   for(const r of job.readings){readings.append(lineItem(r,name));shown.push(r.line);}
+   if(!job.readings.length)readings.append(make('li',{className:'hint',textContent:'No FEET / STANCE / FLIP / SHORT / END-ON / LEG-SCALE / REACH line in this run (FEET needs both legs mapped; FLIP and SHORT their flags).'}));
+  },
+  shownLines:()=>[...shown],
+ };
+}