@bitefoundry/retrieviewer 0.0.2 → 0.0.4

package/puppy-frame-predictive.mjs

@@ -80,7 +80,7 @@ function unfilterRow(type,src,at,cur,prev,w){
 
 // Validate and unfilter. Only the returned typed arrays survive; `bytes` is
 // not referenced by the store built from them.
-function decode(bytes){
+function decode(bytes,{frameIndices}={}){
  if(!(bytes instanceof Uint8Array))fail('bytes');
  if(!isPredictiveFrames(bytes)||bytes.length<HEADER)fail('magic');
  const view=new DataView(bytes.buffer,bytes.byteOffset,bytes.byteLength),u32=at=>view.getUint32(at,true);
@@ -89,8 +89,13 @@ function decode(bytes){
  if(unique<1||unique>frameCount)fail('unique count');
  const data=HEADER+4*frameCount+RECORD*unique;
  if(bytes.length<data)fail('truncated');
- const map=new Uint32Array(frameCount),used=new Uint8Array(unique);
- for(let f=0;f<frameCount;f++){const u=u32(HEADER+4*f);if(u>=unique)fail('map');map[f]=u;used[u]=1;}
+ const retained=frameIndices===undefined?null:new Uint8Array(frameCount);
+ if(retained){
+  if(!Array.isArray(frameIndices)||!frameIndices.length)fail('retained frames');
+  for(const f of frameIndices){if(!Number.isInteger(f)||f<0||f>=frameCount)fail('retained frame index');retained[f]=1;}
+ }
+ const map=new Uint32Array(frameCount),used=new Uint8Array(unique),needed=retained?new Uint8Array(unique):null;
+ for(let f=0;f<frameCount;f++){const u=u32(HEADER+4*f);if(u>=unique)fail('map');map[f]=u;used[u]=1;if(retained?.[f])needed[u]=1;}
  if(used.includes(0))fail('unreferenced frame');
  // x,y,w,h,first pixel index in the packed stream
  const rects=new Float64Array(unique*5);let total=0,pixels=0;
@@ -98,7 +103,7 @@ function decode(bytes){
   const at=HEADER+4*frameCount+RECORD*u,x=u32(at),y=u32(at+4),w=u32(at+8),h=u32(at+12),offset=u32(at+16),length=u32(at+20);
   if((w===0)!==(h===0)||(w===0&&(x||y))||x+w>width||y+h>height)fail('rectangle');
   if(length!==h*(w+1)||offset!==total)fail('offset');
-  rects.set([x,y,w,h,pixels],u*5);total+=length;pixels+=w*h;
+  rects.set([x,y,w,h,pixels],u*5);total+=length;if(!needed||needed[u])pixels+=w*h;
  }
  if(bytes.length!==data+total)fail('pixel length');
  if(pixels*BITS>0xffffffff)fail('pixel count');
@@ -109,23 +114,24 @@ function decode(bytes){
   for(let y=0;y<h;y++){
    unfilterRow(bytes[at],bytes,at+1,cur,prev,w);at+=w+1;
    for(let x=0;x<w;x++){
-    const q=cur[x];if(q>31)fail('quantized value');
+    const q=cur[x];if(q>31)fail('quantized value');if(needed&&!needed[u])continue;
     const i=pos>>>3,s=pos&7;packed[i]|=(q<<s)&255;if(s>3)packed[i+1]|=q>>(8-s);pos+=BITS;
    }
    const t=prev;prev=cur;cur=t;
   }
  }
- return{width,height,frameCount,unique,map,rects,packed};
+ return{width,height,frameCount,unique,map,rects,packed,retained};
 }
 
-function createStore({width,height,frameCount,unique,map,rects,packed}){
+function createStore({width,height,frameCount,unique,map,rects,packed,retained}){
  const n=width*height,slots=[{unique:-1,frame:null},{unique:-1,frame:null}];let decodes=0,hits=0;
  return Object.freeze({
   width,height,frameCount,uniqueCount:unique,byteLength:n*frameCount,residentPixelBytes:packed.byteLength,
-  get residentBytes(){return packed.byteLength+map.byteLength+rects.byteLength+slots.reduce((s,e)=>s+(e.frame?.byteLength??0),0);},
+  get residentBytes(){return packed.byteLength+map.byteLength+rects.byteLength+(retained?.byteLength??0)+slots.reduce((s,e)=>s+(e.frame?.byteLength??0),0);},
   stats(){return{decodes,hits,cachedFrames:slots.filter(e=>e.frame).length};},
   getFrame(index){
    if(!Number.isInteger(index)||index<0||index>=frameCount)fail('frame index');
+   if(retained&&!retained[index])fail('frame was not retained');
    const u=map[index];
    if(slots[0].unique===u){hits++;return slots[0].frame;}
    if(slots[1].unique===u){hits++;slots.reverse();return slots[0].frame;}
@@ -144,4 +150,4 @@ function createStore({width,height,frameCount,unique,map,rects,packed}){
 
 // Parse, validate and unpack an RVQ5 store. A returned frame is valid until two
 // other unique frames have been requested.
-export function readPredictiveFrames(bytes){return createStore(decode(bytes));}
+export function readPredictiveFrames(bytes,options){return createStore(decode(bytes,options));}

package/puppy-frame-store.mjs

@@ -52,9 +52,9 @@ function checkShape(width,height,frameCount){
 // resident (crops only) and reconstructs at most two full frames at a time.
 // A returned frame is valid until two other unique frames have been requested.
 // An 'RVQ5' store (lossy 32-level comparison codec) is delegated and branded.
-export function readPackedFrames(bytes){
+export function readPackedFrames(bytes,options){
  if(!(bytes instanceof Uint8Array))throw Error('Invalid packed frames: bytes');
- if(isPredictiveFrames(bytes)){const store=readPredictiveFrames(bytes);stores.add(store);return store;}
+ if(isPredictiveFrames(bytes)){const store=readPredictiveFrames(bytes,options);stores.add(store);return store;}
  if(bytes.length<HEADER||MAGIC.some((v,i)=>bytes[i]!==v))throw Error('Invalid packed frames: magic');
  const view=new DataView(bytes.buffer,bytes.byteOffset,bytes.byteLength),u32=at=>view.getUint32(at,true);
  const width=u32(4),height=u32(8),frameCount=u32(12),unique=u32(16);

package/puppy-paper-world.mjs

@@ -1,6 +1,20 @@
 // Design calibration, not a measurement of the user's current head position.
 // Sources: OpenCV pinhole model; PsychoPy viewtools physical-screen frustums.
 const diagonal=.0254*32;
+// The paper actor already integrates its own calibrated travel profile and foot
+// contacts. Its old 3D Animal.follow() merely copied that root's x/z, then also
+// updated an invisible skinned mesh, IK, fur and materials. Keep just the follow
+// contract here; speed/stride/projection remain owned by the existing planner.
+export function createPaperBody(){
+ const position={x:0,y:0,z:0};let target=null,disposed=false;
+ const alive=()=>{if(disposed)throw Error('Paper body is disposed');};
+ return{
+  position,
+  follow(point){alive();if(!point||![point.x,point.y,point.z].every(Number.isFinite))throw Error('Invalid paper body position');target={x:point.x,y:point.y,z:point.z};},
+  update(dt){alive();if(!Number.isFinite(dt)||dt<0||dt>.1)throw Error('Invalid paper body step');if(target){position.x=target.x;position.z=target.z;}},
+  dispose(){disposed=true;target=null;},
+ };
+}
 export const PAPER_SCREEN=Object.freeze({widthMeters:diagonal*16/Math.hypot(16,9),heightMeters:diagonal*9/Math.hypot(16,9),viewDistance:.70});
 const eyeHeight=.45,eyeZ=1.65,pitch=9*Math.PI/180;
 export const PAPER_CAMERA=Object.freeze({fov:2*Math.atan(PAPER_SCREEN.heightMeters/(2*PAPER_SCREEN.viewDistance))*180/Math.PI,aspect:16/9,position:Object.freeze([0,eyeHeight,eyeZ]),target:Object.freeze([0,.12,eyeZ-(eyeHeight-.12)/Math.tan(pitch)]),canvasMeters:.64});

package/puppy-paper.mjs

@@ -8,13 +8,31 @@ import {createPaperAreaSampler} from './puppy-paper-area.mjs';
 import {PAPER_ACTION_DURATIONS,createPaperActionSampler,paperActionPose} from './puppy-paper-actions.mjs';
 import {createPawTransport} from './puppy-paper-paw-transport.mjs';
 import {createCompanionSpriteSampler} from './puppy-companion-sprites.mjs';
+import {createComfortSpriteSampler} from './puppy-comfort-sprites.mjs';
 import {mouthSourceFrame,mouthAnchor,projectMouth} from './puppy-mouth-anchor.mjs';
+import {trickClipEdges} from './puppy-paper-trick-timing.mjs';
 
 // Fixed viewer: slightly closer/wider lens gives depth without changing the art.
 export {PAPER_CAMERA} from './puppy-paper-world.mjs';
 
+// Comfort poses reuse existing clips only. Belly holds the calibrated roll-down
+// source exactly at the start of the edge leaving `key` (paws-up belly), easing
+// in/out with zero speed at the hold. `hold` defaults to the v9 keyOrder/edge
+// boundary of roll7; createPaperComfortTimings re-derives it from action info.
+export const PAPER_COMFORT_LIMITS=Object.freeze({belly:30,sleep:120,tug:30});
+export const PAPER_COMFORT_TIMINGS=Object.freeze({belly:Object.freeze({key:'roll7',hold:.4449823183425605,enter:1.3,exit:1.7}),tugExit:.35});
+export function createPaperComfortTimings(actionInfo,{key=PAPER_COMFORT_TIMINGS.belly.key}={}){
+ const {keys,bounds}=trickClipEdges('roll-down',actionInfo),i=keys.findIndex(k=>k[0]===key);
+ if(i<=0)throw Error(`Invalid comfort timing: no roll-down edge leaves ${key}`);
+ return Object.freeze({...PAPER_COMFORT_TIMINGS,belly:Object.freeze({...PAPER_COMFORT_TIMINGS.belly,key,hold:bounds[i]})});
+}
+const comfortDuration=(name,seconds)=>{if(typeof seconds!=='number'||!Number.isFinite(seconds)||seconds<=0||seconds>PAPER_COMFORT_LIMITS[name])throw Error(`Invalid ${name} duration`);};
+const comfortEase=u=>u<=0?0:u>=1?1:u*u*(3-2*u);
+
 // Original artwork only. Physics supplies ground travel; no procedural dog is drawn.
-export function createPaperActor(animal,info,{manualTricks=false,trickTimings=null,walkTransitions=false}={}){
+export function createPaperActor(animal,info,{manualTricks=false,trickTimings=null,walkTransitions=false,comfortTimings=PAPER_COMFORT_TIMINGS}={}){
+ const bellyTiming=comfortTimings?.belly;
+ if(!bellyTiming||![bellyTiming.hold,bellyTiming.enter,bellyTiming.exit,comfortTimings.tugExit].every(Number.isFinite)||bellyTiming.hold<=0||bellyTiming.hold>=1||bellyTiming.enter<=0||bellyTiming.exit<=0||comfortTimings.tugExit<=0)throw Error('Invalid comfort timing');
  let state='idle',age=0,phase=0,flip=false,nextFlip=false,target=null,route=false,routeIndex=0,view='front',nextView='front',turnView='front',turnFlip=false;
  let held=null,waypoints=[];
  let preparationRate=1;
@@ -22,6 +40,7 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
  let straight=false,seatProgress=0,seatVariant='default',travel=null,approachPlan=null,travelAge=0,travelDistance=0,motionSpeed=0,motionStage='rest',completed=false;
  let watchSide='left',restProgress=0,idleHold=2.5;
  let pendingAction=null,activeAction=null,actionDone=null,deferred=null,movementMode='run',stayDown=false,manualDown=false,spinReady=false;
+ let comfort=null,comfortSeconds=0;
  const director=createPaperDirector();
  const points=[[.12,PAPER_GROUND.away]];
  const enter=s=>{state=s;age=0;};
@@ -33,13 +52,31 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
  const turnSeconds=()=>snappyPreparation()?.22:.85;
  const launchSeconds=()=>snappyPreparation()?.10:.25;
  const dispatch=(fn,{keepDown=false}={})=>{
-  if(activeAction||(movementMode==='walk'&&state==='run')){route=false;deferred=()=>dispatch(fn,{keepDown});return true;}
+  if(activeAction||state==='tug'||(movementMode==='walk'&&state==='run')){route=false;deferred=()=>dispatch(fn,{keepDown});hurryComfort();return true;}
   // The calibrated trick down pose has its own byte-shared recovery; never
   // jump back into the older/larger rest illustration on another command.
   if(manualDown&&!keepDown){route=false;deferred=fn;playAction('lie-up',()=>{manualDown=false;view='approach';seatProgress=1;seatVariant='default';enter('idle');drain();},.55);return true;}
   return fn();
  };
  const drain=()=>{const fn=deferred;deferred=null;if(fn){fn();return true;}return false;};
+ // Belly: 0 -> hold eased to rest, held exact source sample, eased hold -> 1.
+ // Queued commands cut the remaining hold only; the roll always finishes at seat.
+ const bellyAction=seconds=>{
+  const {hold:H,enter:a,exit:b}=bellyTiming,t={comfort:'belly',hold:[a,a+seconds],duration:a+seconds+b};
+  t.progressAt=age=>{if(!Number.isFinite(age))throw Error('Invalid comfort age');return age<t.hold[0]?H*comfortEase(age/a):age<t.hold[1]?H:H+(1-H)*comfortEase((age-t.hold[1])/b);};
+  return t;
+ };
+ const startBelly=seconds=>{
+  manualDown=false;stayDown=false;restProgress=0;comfort=null;
+  const timing=bellyAction(seconds);activeAction={name:'roll-down',duration:timing.duration,timing,comfort:'belly'};actionDone=()=>finishTrick('roll');stop();enter('action');
+  if(deferred)hurryComfort();
+ };
+ const tugProgress=()=>{if(!comfort||comfort.kind!=='tug')return 0;const h=comfort.hurry;return h?(h.length>0?Math.min(1,h.progress+(1-h.progress)*(age-h.age)/h.length):1):Math.min(1,age/comfort.seconds);};
+ function hurryComfort(){
+  const t=activeAction?.timing;
+  if(t?.comfort==='belly'&&age<t.hold[1]){t.hold[1]=Math.max(t.hold[0],age);t.duration=activeAction.duration=t.hold[1]+bellyTiming.exit;}
+  else if(state==='tug'&&comfort&&!comfort.hurry){const progress=tugProgress();comfort.hurry={progress,age,length:Math.min(comfortTimings.tugExit,(1-progress)*comfort.seconds)};}
+ }
  const playAction=(name,done,duration=PAPER_ACTION_DURATIONS[name])=>{const timing=trickTimings?.[name];duration=timing?.duration??duration;if(!Number.isFinite(duration)||duration<=0)throw Error('Invalid paper action duration');activeAction={name,duration,timing};actionDone=done;stop();enter('action');};
  const finishTrick=name=>{if(name!=='spin'){view='approach';flip=false;seatProgress=1;seatVariant='default';enter('idle');}else{view='front';flip=false;seatProgress=0;enter('settle');}drain();};
  const issue=(skipEntry=false)=>{
@@ -61,6 +98,9 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
   if(walkTransitions&&name==='spin'&&!spinReady){spinReady=true;enter('launch');return;}
   pendingAction=null;
   if(name==='sit'){enter('idle');return;}
+  if(name==='belly'){const seconds=comfortSeconds;playAction('lie-down',()=>startBelly(seconds),.65);return;}
+  if(name==='sleep'){stayDown=false;comfort={kind:'sleep',seconds:comfortSeconds};enter('recline');return;}
+  if(name==='tug'){stop();comfort={kind:'tug',seconds:comfortSeconds};enter('tug');return;}
   if(name==='lie'){
    if(manualTricks){playAction('lie-down',()=>{manualDown=true;enter('down');drain();},.65);}
    else{stayDown=true;enter('recline');}
@@ -73,7 +113,9 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
   preparationRate=1;
   if(name==='roll'&&manualDown&&state==='down'){route=false;target=null;waypoints=[];pendingAction=null;stayDown=false;manualDown=false;restProgress=0;playAction('roll-down',()=>finishTrick('roll'));return true;}
   if(name==='roll'&&state==='down'&&restProgress===.25){route=false;target=null;waypoints=[];pendingAction=null;stayDown=false;restProgress=0;playAction('roll-down',()=>finishTrick('roll'));return true;}
-  route=false;target=null;waypoints=[];pendingAction=name;spinReady=false;completed=false;stayDown=false;movementMode='run';stop();
+  if(name==='belly'&&state==='down'&&(manualDown||restProgress===.25)){route=false;target=null;waypoints=[];pendingAction=null;startBelly(comfortSeconds);return true;}
+  if(name==='sleep'&&state==='sleep'&&comfort?.kind==='sleep'){comfort.seconds=age+comfortSeconds;return true;}
+  comfort=null;route=false;target=null;waypoints=[];pendingAction=name;spinReady=false;completed=false;stayDown=false;movementMode='run';stop();
   if(restProgress>0||state==='recline'||state==='wake')enter('wake');
   else if(['watch','view-turn','turn','arrival-exit'].includes(state)){/* reach a shared endpoint */}
   else if(['run','finish','launch','settle'].includes(state))enter('finish');
@@ -87,7 +129,7 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
   if(![x,z].every(Number.isFinite))throw Error('Invalid paper target');
   preparationRate=urgent?3:1;
   target=paperGroundTarget(x,z);
-  pendingAction=null;stayDown=false;movementMode=walking?'walk':'run';
+  pendingAction=null;stayDown=false;comfort=null;movementMode=walking?'walk':'run';
   const dz=target[1]-animal.position.z,dx=target[0]-animal.position.x;
   waypoints=[];
   // Do not drag a straight rear/front drawing diagonally across the floor.
@@ -116,10 +158,14 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
   walk(side,distance=1.05){if(!['left','right'].includes(side)||!Number.isFinite(distance)||distance<=0)throw Error('Invalid walk command');return dispatch(()=>{const [x,z]=paperWalkTarget(animal.position.x,animal.position.z,side==='left'?-1:1,distance);if(Math.abs(x-animal.position.x)<1e-6)return false;route=false;go(x,z,{walking:true});return true;});},
   look(side='left'){if(state!=='idle'||seatProgress!==1)return false;route=false;watchSide=side==='right'?'right':'left';enter('watch');return true;},
   lie(){const name=manualDown||activeAction?.name==='lie-down'||restProgress>0?'sit':'lie';return dispatch(()=>requestAction(name));},
-  rest(){return dispatch(()=>{route=false;target=null;waypoints=[];pendingAction=null;stayDown=false;stop();if(restProgress>0){enter('wake');}else if(state==='watch'||state==='arrival-exit'){/* finish shared return */}else if(seatProgress>0||state==='rise'||state==='sit-down')enter('sit-down');else if(!['idle','view-turn','turn'].includes(state))enter('finish');});},
+  // Comfort poses: bounded finite seconds; same dispatch safety as tricks.
+  belly(seconds=6){comfortDuration('belly',seconds);return dispatch(()=>{comfortSeconds=seconds;return requestAction('belly');},{keepDown:true});},
+  sleep(seconds=25){comfortDuration('sleep',seconds);return dispatch(()=>{comfortSeconds=seconds;return requestAction('sleep');});},
+  tug(seconds=6){comfortDuration('tug',seconds);return dispatch(()=>{comfortSeconds=seconds;return requestAction('tug');});},
+  rest(){return dispatch(()=>{route=false;target=null;waypoints=[];pendingAction=null;stayDown=false;comfort=null;stop();if(restProgress>0){enter('wake');}else if(state==='watch'||state==='arrival-exit'){/* finish shared return */}else if(seatProgress>0||state==='rise'||state==='sit-down')enter('sit-down');else if(!['idle','view-turn','turn'].includes(state))enter('finish');});},
   update(dt){
    if(!Number.isFinite(dt)||dt<0||dt>.1)throw Error('Invalid paper step');
-   const before=animal.position.clone();
+   const beforeX=animal.position.x,beforeZ=animal.position.z;
    if(state==='run'&&travel&&target){
     travelAge+=dt;const p=travel.plan.at(travelAge),ratio=travel.plan.distance?p.distance/travel.plan.distance:1;
     travelDistance=p.distance;motionSpeed=p.speed;motionStage=p.stage;
@@ -130,7 +176,7 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
    animal.update(dt);
    const prepareDt=dt*preparationRate;
    age+=['view-turn','turn','rise','watch','arrival-exit','launch','wake'].includes(state)?prepareDt:dt;
-   const distance=Math.hypot(animal.position.x-before.x,animal.position.z-before.z);
+   const distance=Math.hypot(animal.position.x-beforeX,animal.position.z-beforeZ);
    director.update(dt,state==='run',distance);
    if(state==='run'){
     phase+=distance/travel.stride;
@@ -151,7 +197,9 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
    else if(state==='rise'){seatProgress=Math.max(0,seatProgress-prepareDt/(snappyPreparation()?.28:.65));if(seatProgress===0){if(seatVariant==='arrival')enter('arrival-exit');else prepareDirection();}}
    else if(state==='arrival-exit'&&age>=.22){seatVariant='default';prepareDirection();}
    else if(state==='watch'&&age>=1.4){if(pendingAction)prepareDirection();else if(target)enter('rise');else enter('idle');}
-   else if(state==='recline'){const end=stayDown?.25:1;restProgress=Math.min(end,restProgress+dt/1.8);if(restProgress===end)enter(stayDown?'down':'nap');}
+   else if(state==='recline'){const end=stayDown?.25:1;restProgress=Math.min(end,restProgress+dt/1.8);if(restProgress===end)enter(stayDown?'down':comfort?.kind==='sleep'?'sleep':'nap');}
+   else if(state==='sleep'&&age>=comfort.seconds){comfort=null;enter('wake');}
+   else if(state==='tug'&&tugProgress()>=1){comfort=null;enter('idle');drain();}
    else if(state==='nap'&&age>=5&&!stayDown){enter('wake');}
    else if(state==='wake'){restProgress=Math.max(0,restProgress-prepareDt/1.2);if(restProgress===0){if(pendingAction)prepareDirection();else if(target)enter('rise');else enter('idle');}}
    else if(state==='idle'&&route&&age>=idleHold)nextRoute();
@@ -161,7 +209,8 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
    if(![12,24,30].includes(poseFps))throw Error('Invalid pose cadence');
    let pair=20,blend=0,kind=state,rearPair=null,approachPair=null;
    let seat=state==='sit-down'||state==='rise'||seatProgress>0?Math.round(seatProgress*48)/48:null;
-   let behavior=null,behaviorProgress=0;
+   let behavior=null,behaviorProgress=0,comfortPose=state==='tug'?{clip:'tug',progress:tugProgress()}:null;
+   if(activeAction?.comfort)kind=activeAction.comfort;
    let actionName=activeAction?.name??(state==='run'&&movementMode==='walk'?'walk':null),actionProgress=activeAction?(activeAction.timing?activeAction.timing.progressAt(age):Math.min(1,age/activeAction.duration)):phase;
    if(manualDown&&state==='down'){actionName='lie-down';actionProgress=1;}
    if(walkTransitions&&state==='view-turn'&&turnView==='front'){
@@ -192,13 +241,13 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
    // Deliberate held source poses: no live frame blending or face/body deformation.
    blend=Math.round(blend*16)/16;
    const key=`${state}/${actionName}/${view}/${turnView}/${poseFps}/${Math.floor(clock*poseFps)}`;
-   if(held?.key===key){pair=held.pair;blend=held.blend;rearPair=held.rearPair;approachPair=held.approachPair;seat=held.seat;behavior=held.behavior;behaviorProgress=held.behaviorProgress;actionName=held.actionName;actionProgress=held.actionProgress;}else held={key,pair,blend,rearPair,approachPair,seat,behavior,behaviorProgress,actionName,actionProgress,posePhase:phase};
-   return{state:state==='run'||state==='finish'?'run':kind,pair,blend,rearPair,approachPair,seatProgress:seat,seatVariant,behavior,behaviorProgress,actionName,actionProgress,queued:!!deferred,view,straight,flip:state==='turn'&&!walkTransitions?false:flip,phase,posePhase:held.posePhase,stride:travel?.stride??PAPER_GAITS.front.stride,heading:travel?.heading??0,speed:motionSpeed,motionStage,travelDistance,energy:director.report.energy,x:animal.position.x,z:animal.position.z};
+   if(held?.key===key){pair=held.pair;blend=held.blend;rearPair=held.rearPair;approachPair=held.approachPair;seat=held.seat;behavior=held.behavior;behaviorProgress=held.behaviorProgress;actionName=held.actionName;actionProgress=held.actionProgress;comfortPose=held.comfortPose;}else held={key,pair,blend,rearPair,approachPair,seat,behavior,behaviorProgress,actionName,actionProgress,comfortPose,posePhase:phase};
+   return{state:state==='run'||state==='finish'?'run':kind,pair,blend,rearPair,approachPair,seatProgress:seat,seatVariant,behavior,behaviorProgress,actionName,actionProgress,queued:!!deferred,view,straight,flip:state==='turn'&&!walkTransitions?false:flip,phase,posePhase:held.posePhase,stride:travel?.stride??PAPER_GAITS.front.stride,heading:travel?.heading??0,speed:motionSpeed,motionStage,travelDistance,energy:director.report.energy,x:animal.position.x,z:animal.position.z,...(comfortPose?{comfortPose:{...comfortPose}}:{})};
   },get state(){return state;}
  };
 }
 
-export function createPaperRenderer(cache,info,meta,width,height,{rear,approach,seat,arrivalSeat,behaviors,actions,interactions,contacts=true,pawTransport=false}={}){
+export function createPaperRenderer(cache,info,meta,width,height,{rear,approach,seat,arrivalSeat,behaviors,actions,interactions,comfort,contacts=true,pawTransport=false}={}){
  if(![width,height].every(Number.isInteger)||width<2||height<2||width*height>1_000_000)throw Error('Invalid paper grid');
  const tween=createCachedTween(cache,info),renderMeta={...meta,pairs:info.pair_map,run_sequence:info.run_sequence};
  const out=new Uint8ClampedArray(width*height*4),area=createPaperAreaSampler();
@@ -208,6 +257,7 @@ export function createPaperRenderer(cache,info,meta,width,height,{rear,approach,
  const arrivalSeatSample=arrivalSeat?createPaperSeatSampler(arrivalSeat.bytes,arrivalSeat.info):null;
  const behaviorSample=behaviors?createPaperBehaviorSampler(behaviors.bytes,behaviors.info):null;
  const interactionSample=interactions?createCompanionSpriteSampler(interactions.bytes,interactions.info):null;
+ const comfortSample=comfort?createComfortSpriteSampler(comfort.bytes,comfort.info):null;
  const actionSample=actions?createPaperActionSampler(actions.bytes,actions.info):null,actionArea=actions?createPaperAreaSampler(actions.info.width):null;
  const walkEpisodes=actions?createPaperSupportEpisodes(actions.info.feet,actions.info.clips.walk,9):null;
  const sourceEpisodes=rear?{
@@ -222,10 +272,11 @@ export function createPaperRenderer(cache,info,meta,width,height,{rear,approach,
   const isApproach=state.approachPair!==null&&state.approachPair!==undefined&&approachSample;
   const isSeat=state.seatProgress!==null&&state.seatProgress!==undefined&&seatSample;
   if(!Number.isFinite(pixelAspect)||pixelAspect<.1||pixelAspect>10)throw Error('Invalid dot pixel aspect');
-  const isInteraction=state.interactionPose&&interactionSample;
+  const isComfort=state.comfortPose&&comfortSample;
+  const isInteraction=isComfort||state.interactionPose&&interactionSample;
   const isBehavior=!isInteraction&&state.behavior&&behaviorSample;
   const isAction=!isInteraction&&state.actionName&&actionSample,sourceN=isAction?actions.info.width:320,originX=(sourceN-320)/2,originY=(sourceN/320-1)*300;
-  const image=isInteraction?interactionSample(state.interactionPose):isAction?actionSample(state):isBehavior?behaviorSample(state):isSeat?(state.seatVariant==='arrival'&&arrivalSeatSample?arrivalSeatSample:seatSample)(state.seatProgress):isApproach?approachSample(state.approachPair,state.blend):isRear?rearSample(state.rearPair,state.blend):tween(state),side=height*size,sideX=side/pixelAspect;
+  const image=isComfort?comfortSample(state.comfortPose):isInteraction?interactionSample(state.interactionPose):isAction?actionSample(state):isBehavior?behaviorSample(state):isSeat?(state.seatVariant==='arrival'&&arrivalSeatSample?arrivalSeatSample:seatSample)(state.seatProgress):isApproach?approachSample(state.approachPair,state.blend):isRear?rearSample(state.rearPair,state.blend):tween(state),side=height*size,sideX=side/pixelAspect;
   // Quantize source lookup only, never the projected rectangle. Rounding side,
   // left and top first introduced whole-body scale/position jumps at thresholds.
   const left=width*x-sideX/2,floor=isInteraction||isAction||isBehavior||isSeat||isRear||isApproach?0:cleanGroundOffset(state,renderMeta),top=height*y-(300-floor)/320*side;

package/retrieviewer-cli.mjs

@@ -23,8 +23,10 @@ Enable opens a first-run selection/confirmation wizard on a real terminal.
 Non-interactive changes require --agent and --yes. Unsupported native renderers
 are refused: MCP connectivity alone is never treated as in-screen rendering.
 No command changes credentials, shell profiles or agent executables.
-Desktop is a separate Windows overlay, NOT a Codex plugin. Choose a window once;
+Desktop is a separate native overlay, NOT a Codex plugin. Choose a window once;
 use Codex normally. Exit from its tray icon or desktop-stop. No auto-start is added.
+Windows is verified; macOS and Linux X11 adapters are experimental. Native Wayland
+app tracking is not supported. Linux targets AlmaLinux8/GLIBC2.28, system Python3.6+.
 `;
 export function parseArguments(args){
  const [command='help',...rest]=args,options={};
@@ -88,7 +90,12 @@ export async function runCli(args,{input=process.stdin,output=process.stdout,err
 }
 
 // CLI is deliberately a separate module from the side-effect-free library.
-import {pathToFileURL} from 'node:url';
-if(process.argv[1]&&import.meta.url===pathToFileURL(process.argv[1]).href){
+import {fileURLToPath} from 'node:url';
+import {realpathSync} from 'node:fs';
+// npm global bins are symlinks on Unix. import.meta resolves the real module,
+// whereas argv[1] keeps the bin link; comparing those raw URLs silently did nothing.
+let main=false;
+try{main=!!process.argv[1]&&realpathSync(process.argv[1])===realpathSync(fileURLToPath(import.meta.url));}catch{}
+if(main){
  try{process.exitCode=await runCli(process.argv.slice(2));}catch(e){process.stderr.write('Retrieviewer: '+e.message+'\n');process.exitCode=1;}
 }

package/retrieviewer-plugin.d.mts

@@ -36,7 +36,7 @@ export interface PetPlugin {
   /** Host-owned loop: advance seconds then render. False while hidden. Throws while running. */
   tick(dtSeconds: number): boolean;
   /** False when busy or cooling down. */
-  interact(kind: 'ball' | 'treat'): boolean;
+  interact(kind: 'ball' | 'treat' | 'tug'): boolean;
   readonly running: boolean;
   readonly disposed: boolean;
   dispose(): void;

package/retrieviewer-plugin.mjs

@@ -82,7 +82,7 @@ export async function createPetPlugin({host,petOptions,fps=30,scheduler}={}){
    if(typeof dtSeconds!=='number'||!Number.isFinite(dtSeconds)||dtSeconds<0)throw RangeError('dtSeconds must be finite non-negative seconds');
    try{return draw(dtSeconds);}catch(error){halt();throw error;}
   },
-  // 'ball' | 'treat'. False when busy or cooling down; shows on the next frame.
+  // 'ball' | 'treat' | 'tug'. False when busy or cooling down; shows on the next frame.
   interact(kind){alive();return pet.interact(kind);},
   get running(){return running;},
   get disposed(){return disposed;},

package/retrieviewer.d.mts

@@ -35,16 +35,22 @@ export interface PetState {
   [key: string]: unknown;
 }
 export interface LifeReport {
+  /** Last selected autonomous episode; null before the first decision. */
+  episode: string | null;
   intent: string;
   label: string;
-  interaction: 'ball' | 'treat' | null;
+  interaction: 'ball' | 'treat' | 'tug' | null;
   busy: boolean;
   energy: number;
   decisions: number;
-  cooldowns: {ball: number; treat: number};
+  cooldowns: {ball: number; treat: number; tug: number};
   gesture: {clip: string; progress: number} | null;
   ball: {x: number; z: number; height: number; carried: boolean} | null;
   treat: {x: number; z: number; height: number} | null;
+  /** Tug-of-war state while a tug interaction is active. */
+  tug: {progress: number; grip: number} | null;
+  /** Silent rising sleep cue, normalized cycle progress; no audio process. */
+  snore: number | null;
 }
 export interface PetFrame {
   artProfile: 'original' | 'q5';
@@ -70,7 +76,7 @@ export interface Pet {
   step(dt: number): number;
   frame(options: FrameOptions): PetFrame;
   /** False when busy or cooling down. */
-  interact(kind: 'ball' | 'treat'): boolean;
+  interact(kind: 'ball' | 'treat' | 'tug'): boolean;
   readonly disposed: boolean;
   dispose(): void;
 }
@@ -78,7 +84,7 @@ export function createPet(options?: PetOptions): Promise<Pet>;
 export function defaultLoadAsset(name: string): Promise<ArrayBuffer | Uint8Array>;
 export const STEP_SECONDS: number;
 export const MAX_CATCH_UP_SECONDS: number;
-export const INTERACTIONS: readonly ['ball', 'treat'];
+export const INTERACTIONS: readonly ['ball', 'treat', 'tug'];
 export const ART_PROFILES: readonly ['original', 'q5'];
 export const DEFAULT_ART_PROFILE: 'q5';
 export function getPetAssetFiles(artProfile?: 'original' | 'q5'): readonly string[];

package/retrieviewer.mjs

@@ -1,6 +1,5 @@
-import {makeLabAnimal} from './locomotion-core.mjs';
-import {createPaperActor,createPaperRenderer} from './puppy-paper.mjs';
-import {createPaperProjection} from './puppy-paper-world.mjs';
+import {createPaperActor,createPaperRenderer,createPaperComfortTimings} from './puppy-paper.mjs';
+import {createPaperProjection,createPaperBody} from './puppy-paper-world.mjs';
 import {rgbaToBraille} from './braille.mjs';
 import {createSnappyTrickTimings} from './puppy-paper-trick-timing.mjs';
 import {createCompanionLife} from './puppy-companion-life.mjs';
@@ -11,24 +10,25 @@ import {readPackedFrames} from './puppy-frame-store.mjs';
 // or listener side effects: the host owns the loop and calls step() then frame().
 export const STEP_SECONDS=1/60;
 export const MAX_CATCH_UP_SECONDS=.1;
-export const INTERACTIONS=Object.freeze(['ball','treat']);
+export const INTERACTIONS=Object.freeze(['ball','treat','tug']);
 // Approved 32-level art ships by default; preserved original art is optional.
 export const DEFAULT_ART_PROFILE='q5';
 export const ART_PROFILES=Object.freeze(['original','q5']);
 // Current companion runtime: v9 tricks + interactions-v3, same as puppy-paper.html.
 export const PET_ASSETS=Object.freeze({
+ // Kept as a legacy identifier only; createPet/getPetAssetFiles no longer load it.
  animal:'locomotion-puppy.animal',
  stride:'puppy-stride-tweens-q5.bin.gz',strideInfo:'puppy-stride-meta.json',stableInfo:'puppy-stable-meta.json',
  rear:'puppy-paper-rear-gallop',approach:'puppy-paper-approach',seat:'puppy-paper-seat',arrivalSeat:'puppy-paper-arrival-seat',
- behaviors:'puppy-paper-behaviors',actions:'puppy-paper-actions-v9',interactions:'puppy-companion-interactions-v3',
+ behaviors:'puppy-paper-behaviors',actions:'puppy-paper-actions-v9',interactions:'puppy-companion-interactions-v3',comfort:'puppy-companion-comfort',
 });
-const BUNDLES=['rear','approach','seat','arrivalSeat','behaviors','actions','interactions'];
+const BUNDLES=['rear','approach','seat','arrivalSeat','behaviors','actions','interactions','comfort'];
 const frameFile=(base,profile)=>base+(profile==='q5'?'-q5.bin.gz':'-compact.bin.gz');
 /** Exact files a host/bundler must copy, including metadata. Never loads assets. */
 export function getPetAssetFiles(artProfile=DEFAULT_ART_PROFILE){
  if(!ART_PROFILES.includes(artProfile))throw RangeError('artProfile must be original or q5');
  return Object.freeze([PET_ASSETS.strideInfo,PET_ASSETS.stableInfo,frameFile('puppy-stride-tweens',artProfile),
-  ...BUNDLES.flatMap(key=>[PET_ASSETS[key]+'.json',frameFile(PET_ASSETS[key],artProfile)]),PET_ASSETS.animal]);
+  ...BUNDLES.flatMap(key=>[PET_ASSETS[key]+'.json',frameFile(PET_ASSETS[key],artProfile)])]);
 }
 
 // Relative to this module, never the process cwd: file: URLs in Node, HTTP in browsers.
@@ -62,13 +62,19 @@ const sharedAssets=new Map();
 async function loadPetAssets(loadAsset,artProfile){
  const load=async name=>bytesOf(name,await loadAsset(name));
  const json=async name=>JSON.parse(new TextDecoder().decode(await load(name)));
- const frames=async name=>readPackedFrames(await gunzip(await load(name)));
+ const frames=async (name,options)=>readPackedFrames(await gunzip(await load(name)),options);
  // One family at a time: never inflate all eight legacy-sized buffers together.
  const data={assets:{}};
  data.info=await json(PET_ASSETS.strideInfo);data.meta=await json(PET_ASSETS.stableInfo);
  data.cache=await frames(frameFile('puppy-stride-tweens',artProfile));
- for(const key of BUNDLES){const base=PET_ASSETS[key];data.assets[key]={info:await json(base+'.json'),bytes:await frames(frameFile(base,artProfile))};}
- data.baked=await load(PET_ASSETS.animal);
+ for(const key of BUNDLES){
+  const base=PET_ASSETS[key],info=await json(base+'.json');
+  // Old interaction sheets include preparation frames no runtime clip can reach.
+  // Keep exact active samples only, leaving room for small new gestures without
+  // keeping another multi-megabyte art family resident. Original RVF1 unchanged.
+  const options=key==='interactions'&&artProfile==='q5'?{frameIndices:[...new Set(Object.values(info.clips).flatMap(list=>list.flatMap(p=>Array.from({length:info.samples},(_,s)=>p*info.samples+s))))]}:undefined;
+  data.assets[key]={info,bytes:await frames(frameFile(base,artProfile),options)};
+ }
  return data;
 }
 async function acquireAssets(loadAsset,artProfile){
@@ -90,12 +96,12 @@ export async function createPet({loadAsset=defaultLoadAsset,seed,energy,pawTrans
  if(!ART_PROFILES.includes(artProfile))throw RangeError('artProfile must be original or q5');
  let lease=await acquireAssets(loadAsset,artProfile),data=lease.data;
  const release=lease.release;lease=null;
- let {cache,info,meta,baked}=data;const assets={...data.assets};data=null;
+ let {cache,info,meta}=data;const assets={...data.assets};data=null;
  let animal,actor,life;
  try{
   if(!assets.actions.info.clips?.['lie-down']||!assets.actions.info.clips?.['lie-up'])throw Error('v9 action cache lacks lie-down/lie-up clips');
-  animal=await makeLabAnimal({baked:baked.buffer.slice(baked.byteOffset,baked.byteOffset+baked.byteLength)});baked=null;
-  actor=createPaperActor(animal,info,{manualTricks:true,trickTimings:createSnappyTrickTimings(assets.actions.info),walkTransitions:true});
+  animal=createPaperBody();
+  actor=createPaperActor(animal,info,{manualTricks:true,trickTimings:createSnappyTrickTimings(assets.actions.info),comfortTimings:createPaperComfortTimings(assets.actions.info),walkTransitions:true});
   life=createCompanionLife(actor,{seed,...energy===undefined?{}:{energy}});
  }catch(e){animal?.dispose?.();release();throw e;}
  let paint=null,paintKey='',time=0,acc=0,disposed=false;
@@ -127,7 +133,7 @@ export async function createPet({loadAsset=defaultLoadAsset,seed,energy,pawTrans
    const {text}=rgbaToBraille(pixels,width,height,{method:'stable',brightness:1.18,contrast:1.1});
    return {text,columns,rows,pixels,state,report,placement,projection,artProfile,mouth:paint.lastMouth,contacts:paint.report()};
   },
-  // 'ball' | 'treat'. False when busy or cooling down; unknown kinds throw.
+  // 'ball' | 'treat' | 'tug'. False when busy or cooling down; unknown kinds throw.
   interact(kind){alive();if(!INTERACTIONS.includes(kind))throw TypeError(`Unknown interaction: ${kind}`);return life.interact(kind);},
   get disposed(){return disposed;},
   dispose(){

package/locomotion-core.mjs

@@ -1,21 +0,0 @@
-import * as THREE from 'three';
-import {createAnimal} from './vendor/procedural-animals/src/index.js';
-export const LAB_OPTIONS={variant:'retriever',age:'juvenile',seed:2,quality:'low',worker:false,overrides:{colour:'yellow',stanceSoftMargin:.005}};
-export async function makeLabAnimal(extra={}){
- return createAnimal('dog',{...LAB_OPTIONS,...extra,overrides:{...LAB_OPTIONS.overrides,...extra.overrides}});
-}
-// Never translate the mesh externally. The gait engine owns root motion + IK.
-export function makeLabController(animal){
- let target=null,speed=animal.gears.walk;
- return {get target(){return target;},get speed(){return speed;},setSpeed(kind){
-  if(!['walk','trot','gallop'].includes(kind))throw Error('Unknown gait');
-  speed=animal.gears[kind];if(target)animal.moveTo(target,{speed});
- },go(x,z){
-  if(![x,z].every(Number.isFinite))throw Error('Invalid ground target');
-  target=new THREE.Vector3(Math.max(-.8,Math.min(.8,x)),0,Math.max(-1.7,Math.min(.3,z)));
-  animal.stopAction();animal.moveTo(target,{speed});
- },stop(){target=null;animal.stop();},update(dt){
-  if(!Number.isFinite(dt)||dt<0||dt>.1)throw Error('Invalid lab step');animal.update(dt);
-  if(target&&animal.position.distanceTo(target)<.025&&animal.speed<.03){target=null;animal.stop();}
- }};
-}

package/vendor/procedural-animals/package.json

@@ -1,40 +0,0 @@
-{
-  "name": "procedural-animals",
-  "version": "0.1.0",
-  "description": "24 fully procedural animals for three.js: SDF-sculpted bodies, dual-quaternion skinning, GPU fur, feathers and scales, IK locomotion and actions. No models, no textures, no downloads.",
-  "license": "MIT",
-  "author": "Majid Manzarpour",
-  "homepage": "https://majidmanzarpour.github.io/threejs-procedural-animals/",
-  "repository": { "type": "git", "url": "git+https://github.com/majidmanzarpour/threejs-procedural-animals.git" },
-  "bugs": { "url": "https://github.com/majidmanzarpour/threejs-procedural-animals/issues" },
-  "type": "module",
-  "main": "./src/index.js",
-  "module": "./src/index.js",
-  "types": "./src/index.d.ts",
-  "exports": {
-    ".": { "types": "./src/index.d.ts", "default": "./src/index.js" },
-    "./species/*": "./src/species/*/index.js",
-    "./worker": "./src/worker.js",
-    "./bake": "./src/bake.js",
-    "./package.json": "./package.json"
-  },
-  "bin": { "procedural-animals-bake": "./tools/bake.mjs" },
-  "sideEffects": ["./src/worker.js"],
-  "files": [
-    "src/**/*.js",
-    "src/index.d.ts",
-    "tools/bake.mjs",
-    "README.md",
-    "LICENSE",
-    "llms.txt"
-  ],
-  "engines": { "node": ">=18" },
-  "peerDependencies": { "three": ">=0.160.0" },
-  "devDependencies": { "esbuild": "^0.28.2", "playwright-core": "1.56", "three": "^0.186.0" },
-  "scripts": {
-    "build:showcase": "node showcase/build.mjs",
-    "build:pages": "node showcase/build.mjs --pages",
-    "test": "node tools/test.mjs"
-  },
-  "keywords": ["three", "threejs", "procedural", "animals", "animation", "ik", "fur", "sdf", "creatures", "gamedev", "webgl"]
-}