@bitefoundry/retrieviewer 0.0.3 → 0.0.5

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,sleepLook=null,nextSleepLook={variant:'side',right:false};
  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;sleepLook={...nextSleepLook};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,variant='side',right=false){comfortDuration('sleep',seconds);if(!['side','belly','curl','chin'].includes(variant)||typeof right!=='boolean')throw Error('Invalid sleep pose');return dispatch(()=>{comfortSeconds=seconds;nextSleepLook={variant,right};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,9 @@ 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;
+   if(restProgress===0&&state!=='recline')sleepLook=null;
+   let behavior=null,behaviorProgress=0,comfortPose=state==='tug'?{clip:'tug',progress:tugProgress()}:sleepLook&&restProgress>.72?{clip:'sleep',...sleepLook,blend:comfortEase((restProgress-.72)/.28)}: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,23 +242,30 @@ 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();
- const rearSample=rear?createRearSampler(rear.bytes,rear.info):null,lock=createPaperFootLock({maxImageStretch:pawTransport?1.45:Infinity});
- const approachSample=approach?createRearSampler(approach.bytes,approach.info):null;
- const seatSample=seat?createPaperSeatSampler(seat.bytes,seat.info):null;
- 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 actionSample=actions?createPaperActionSampler(actions.bytes,actions.info):null,actionArea=actions?createPaperAreaSampler(actions.info.width):null;
+ // Only one authored source is drawn at a time. Small samplers borrow a view of
+ // the action-sized scratch. A sleep blend reads each base pixel before writing
+ // that same pixel, so it needs no second image or per-frame temporary buffer.
+ const actionScratch=new Uint8ClampedArray(Math.max(320*320,(actions?.info.width??320)*(actions?.info.height??320))*4);
+ const spriteScratch=actionScratch.subarray(0,320*320*4);
+ for(let i=3;i<actionScratch.length;i+=4)actionScratch[i]=255;
+ const rearSample=rear?createRearSampler(rear.bytes,rear.info,spriteScratch):null,lock=createPaperFootLock({maxImageStretch:pawTransport?1.45:Infinity});
+ const approachSample=approach?createRearSampler(approach.bytes,approach.info,spriteScratch):null;
+ const seatSample=seat?createPaperSeatSampler(seat.bytes,seat.info,spriteScratch):null;
+ const arrivalSeatSample=arrivalSeat?createPaperSeatSampler(arrivalSeat.bytes,arrivalSeat.info,spriteScratch):null;
+ const behaviorSample=behaviors?createPaperBehaviorSampler(behaviors.bytes,behaviors.info,spriteScratch):null;
+ const interactionSample=interactions?createCompanionSpriteSampler(interactions.bytes,interactions.info,spriteScratch):null;
+ const comfortSample=comfort?createComfortSpriteSampler(comfort.bytes,comfort.info,spriteScratch):null;
+ const actionSample=actions?createPaperActionSampler(actions.bytes,actions.info,actionScratch.subarray(0,actions.info.width*actions.info.height*4)):null,actionArea=actions?createPaperAreaSampler(actions.info.width):null;
  const walkEpisodes=actions?createPaperSupportEpisodes(actions.info.feet,actions.info.clips.walk,9):null;
  const sourceEpisodes=rear?{
   front:createPaperSupportEpisodes(rear.info.frontFeet,[0,1,2,3,4,5,6,7],17),
@@ -222,10 +279,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,...state.comfortPose.clip==='sleep'&&state.comfortPose.blend<1&&behaviorSample?{base:behaviorSample({behavior:'rest',behaviorProgress:state.behaviorProgress})}:{}}):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

@@ -13,7 +13,7 @@ Usage:
   retrieviewer doctor [--agent ID] [--json]
   retrieviewer agents [--json]
   retrieviewer preview [--original]
-  retrieviewer desktop
+  retrieviewer desktop [--ink cream|gold|dark]
   retrieviewer desktop-status [--json]
   retrieviewer desktop-stop
   retrieviewer desktop-clean --yes
@@ -32,15 +32,17 @@ export function parseArguments(args){
  const [command='help',...rest]=args,options={};
  for(let i=0;i<rest.length;i++){
   const token=rest[i];
-  if(token==='--agent'){
-   if(options.agent||!rest[i+1]||rest[i+1].startsWith('-'))throw Error('--agent requires one ID');
-   options.agent=rest[++i];
+  if(token==='--agent'||token==='--ink'){
+   const key=token.slice(2);
+   if(options[key]||!rest[i+1]||rest[i+1].startsWith('-'))throw Error(token+' requires one value');
+   options[key]=rest[++i];
   }else if(['--yes','--json','--dry-run','--original'].includes(token))options[token.slice(2)]=true;
   else throw Error('Unknown argument: '+token);
  }
  if(options.agent&&!AGENTS.some(a=>a.id===options.agent))throw Error('Unknown agent: '+options.agent);
+ if(options.ink&&!['cream','gold','dark'].includes(options.ink))throw Error('--ink must be cream, gold or dark');
  if(!['help','--help','-h','enable','disable','disconnect','status','doctor','agents','preview','desktop','desktop-status','desktop-stop','desktop-clean','desktop-remove'].includes(command))throw Error('Unknown command: '+command);
- const allowed={enable:['agent','yes','json','dry-run'],disconnect:['agent','yes','json','dry-run'],disable:['agent','json'],status:['agent','json'],doctor:['agent','json'],agents:['json'],preview:['original'],'desktop-status':['json'],'desktop-clean':['yes'],'desktop-remove':['yes']};
+ const allowed={desktop:['ink'],enable:['agent','yes','json','dry-run'],disconnect:['agent','yes','json','dry-run'],disable:['agent','json'],status:['agent','json'],doctor:['agent','json'],agents:['json'],preview:['original'],'desktop-status':['json'],'desktop-clean':['yes'],'desktop-remove':['yes']};
  for(const key of Object.keys(options))if(!(allowed[command]??[]).includes(key))throw Error(`--${key} is not supported by ${command}`);
  return {command,options};
 }
@@ -51,7 +53,7 @@ export async function runCli(args,{input=process.stdin,output=process.stdout,err
   if(['desktop-clean','desktop-remove'].includes(command)&&!options.yes)throw Error('Use '+command+' --yes to remove only the companion cache.');
   const api=desktop??await import('./integrations/windows-overlay/desktop.mjs');
   const action={'desktop':'startDesktop','desktop-status':'desktopStatus','desktop-stop':'stopDesktop','desktop-clean':'cleanDesktop','desktop-remove':'removeDesktop'}[command];
-  emit(await api[action]());return 0;
+  emit(await api[action](options.ink?{ink:options.ink}:{}));return 0;
  }
  if(command==='preview'){await import('./examples/live.mjs');return 0;}
  if(['status','doctor','agents'].includes(command)){

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,24 @@ 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;
+  /** Awake-time sleep pressure; ordinary sitting does not erase it. */
+  drowsiness: 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 +78,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 +86,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"]
-}

package/vendor/procedural-animals/src/animal.js

@@ -1,146 +0,0 @@
-// The public Animal: build data + render object + motion engine behind a small game-facing API.
-import * as THREE from 'three';
-import { createAnimalObject } from './core/render/animalObject.js';
-import { createMotion } from './core/motion/index.js';
-
-const _v = new THREE.Vector3();
-
-export class Animal {
-  constructor(species, data, opts = {}) {
-    this.species = species;
-    this.id = species.id;
-    this.data = data;
-    this.seed = data.seed;
-    this.params = data.params;
-    this.quality = opts.quality || data.quality;
-    const ground = opts.ground || (() => 0);
-    this.ground = ground;
-    this.water = opts.water || null;
-    this.render = createAnimalObject(data, species, { quality: this.quality, castShadow: opts.castShadow, receiveShadow: opts.receiveShadow });
-    /** Add this to your scene. Keep its own transform at identity: the animal moves by itself. */
-    this.object = this.render.group;
-    this.object.userData.animal = this;
-    this._listeners = new Map();
-    this.motion = createMotion(species.plan, {
-      species, data, skeleton: this.render.skeleton, ground, water: this.water, perches: opts.perches,
-      position: opts.position, heading: opts.heading ?? 0,
-      emit: (type, payload) => this._emit(type, payload),
-    });
-    this.attachments = {};
-    this._attachDefs = [];
-    for (const [name, def] of Object.entries(this.motion.attachmentPoints || {})) {
-      const o = new THREE.Object3D();
-      o.name = name;
-      o.matrixAutoUpdate = false;
-      this.object.add(o);
-      this.attachments[name] = o;
-      this._attachDefs.push({ o, ...def });
-    }
-    this.stats = { vertices: data.nV, triangles: data.index.length / 3, bones: data.bones.length, buildMs: data.stats?.buildMs || 0, updateMs: 0 };
-    this.time = 0;
-    this._lastDt = 1 / 60;
-    this.update(0);
-  }
-
-  // ---------------------------------------------------------------- control
-  /** Locomotion: the animal moves itself. speed in m/s, heading in radians (0 = +Z). */
-  move({ speed = 0, heading, climb = 0, gait } = {}) {
-    const inp = this.motion.input;
-    inp.follow = null;
-    inp.target = null;
-    inp.speed = Math.max(0, speed);
-    if (heading !== undefined) inp.heading = heading;
-    inp.climb = climb;
-    inp.gait = gait || null;
-    return this;
-  }
-  stop() { return this.move({ speed: 0 }); }
-  /** Walk / run to a point and stop there. */
-  moveTo(point, { speed = 3 } = {}) {
-    const inp = this.motion.input;
-    inp.follow = null;
-    inp.target = point ? new THREE.Vector3().copy(point) : null;
-    inp.targetSpeed = speed;
-    return this;
-  }
-  /** Match your own physics body: the animal is placed at `position` and animates for `velocity`. */
-  follow(position, velocity, { heading } = {}) {
-    const inp = this.motion.input;
-    inp.follow = inp.follow || { position: new THREE.Vector3(), velocity: new THREE.Vector3(), heading: null };
-    inp.follow.position.copy(position);
-    inp.follow.velocity.copy(velocity || _v.set(0, 0, 0));
-    inp.follow.heading = heading ?? null;
-    return this;
-  }
-  /** Look at a world point (Vector3) or stop looking (null). The animal keeps tracking the point you pass. */
-  lookAt(target) {
-    this.motion.input.look = target ? (target.isVector3 ? target : new THREE.Vector3().copy(target)) : null;
-    return this;
-  }
-  /**
-   * Play an action ('jump', 'sit', 'lie', 'sleep', 'eat', 'drink', 'attack', 'hit', 'death', 'stand', ...).
-   * A new one-shot interrupts the running one; postures cross-fade.
-   * Resolves with 'done' | 'interrupted' | 'stopped' | 'refused'.
-   */
-  play(name, opts = {}) { return this.motion.play(name, opts); }
-  /** End an action (a posture: stand up), or every action but death when no name is given. */
-  stopAction(name) { this.motion.stop(name); return this; }
-  get actions() { return this.motion.actions; }
-  get gaits() { return this.motion.gaits; }
-  /** Named speeds for UIs ({ walk, trot, ... } in m/s, scaled to this individual's size). */
-  get gears() { return this.motion.gears || {}; }
-
-  // ---------------------------------------------------------------- events
-  on(type, fn) {
-    if (!this._listeners.has(type)) this._listeners.set(type, new Set());
-    this._listeners.get(type).add(fn);
-    return () => this.off(type, fn);
-  }
-  off(type, fn) { this._listeners.get(type)?.delete(fn); return this; }
-  _emit(type, payload) {
-    const set = this._listeners.get(type);
-    if (set) for (const fn of set) fn({ type, animal: this, ...payload });
-  }
-
-  // ---------------------------------------------------------------- state
-  get position() { return this.motion.state.position; }
-  get heading() { return this.motion.state.heading; }
-  get speed() { return this.motion.state.speed; }
-  get velocity() { return this.motion.state.velocity; }
-  get state() { return this.motion.state; }
-
-  // ---------------------------------------------------------------- frame
-  /** Call once per frame with the frame time in seconds. */
-  update(dt) {
-    const t0 = now();
-    if (!(dt >= 0) || !Number.isFinite(dt)) dt = 0;
-    dt = Math.min(dt, 0.1);
-    this.time += dt;
-    this.motion.update(dt);
-    this.render.update({ dt, time: this.time, motion: this.motion });
-    for (const a of this._attachDefs) {
-      const b = this.render.skeleton.byName[a.bone];
-      if (!b) continue;
-      a.o.matrix.multiplyMatrices(b.matrixWorld, a.local);
-      a.o.matrixWorld.multiplyMatrices(this.object.matrixWorld, a.o.matrix);
-      a.o.matrixWorldNeedsUpdate = false;
-    }
-    this.stats.updateMs = this.stats.updateMs * 0.9 + (now() - t0) * 0.1;
-    return this;
-  }
-
-  setQuality(q) { this.render.setQuality?.(q); this.quality = q; return this; }
-  /** Motion level of detail: 0 full, 1 reduced secondary motion, 2 crowd (half-rate IK). */
-  setLod(level) { this.motion.setLod?.(level); this.lod = level; return this; }
-  setDebug(mode, on) { this.render.setDebug?.(mode, on); return this; }
-  /** Show or hide the coverings (fur shells and silhouette fins); the base still reads as fur. */
-  setCoverings(on) { this.render.setCoverings?.(on); return this; }
-
-  dispose() {
-    this.render.dispose();
-    this.motion.dispose?.();
-    this._listeners.clear();
-  }
-}
-
-const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());