@bitefoundry/retrieviewer 0.0.3 → 0.0.4

package/puppy-comfort-sprites.mjs

@@ -0,0 +1,25 @@
+import {grayFrameReader,isGrayFrameSource} from './puppy-frame-store.mjs';
+
+// A handful of authored keys, not an expanded 30fps film or a live image morph.
+// First/last keys are the exact shared seated source; all keys use one scale.
+export function comfortFrameIndex(progress,info){
+ if(!Number.isFinite(progress)||progress<0||progress>1)throw Error('Invalid comfort progress');
+ const seconds=progress*6;
+ if(seconds<.12||progress===1)return 0;
+ if(seconds<.65)return seconds<.3?1:2;
+ if(seconds>5.15)return seconds<5.45?7:seconds<5.8?8:0;
+ const loop=[3,4,3,5,3,6,3,5,3,4,3,6];
+ return loop[Math.floor((seconds-.65)/.28)%loop.length];
+}
+
+export function createComfortSpriteSampler(bytes,info){
+ if(!isGrayFrameSource(bytes)||info?.version!==1||info.width!==320||info.height!==320||info.frames!==9)throw Error('Invalid comfort sprites');
+ const frames=grayFrameReader(bytes,320,320,info.frames);let rgba=null;
+ return pose=>{
+  if(pose?.clip!=='tug')throw Error('Invalid comfort clip');
+  if(!rgba){rgba=new Uint8ClampedArray(320*320*4);for(let i=3;i<rgba.length;i+=4)rgba[i]=255;}
+  const index=comfortFrameIndex(pose.progress,info),frame=frames.getFrame(index);
+  for(let i=0,j=0;i<frame.length;i++,j+=4)rgba[j]=rgba[j+1]=rgba[j+2]=frame[i];
+  return rgba;
+ };
+}

package/puppy-companion-comfort.json

@@ -0,0 +1,77 @@
+{
+  "version": 1,
+  "width": 320,
+  "height": 320,
+  "frames": 9,
+  "clips": [
+    "tug"
+  ],
+  "gzipBytes": 103549,
+  "residentPixelBytes": 291337,
+  "sourceSheetSha256": "10fde9dacca5cb45acd68f387e7ed3bcf88cd72cf0f9c4220d31d819db91731e",
+  "neutralSha256": "19f89a8bcb5a937e528593a8f36db846a0d45a5ee398f1b0873c056e5be2fa0a",
+  "encodedSha256": "e046e214da585ffda65e8d2c1a86c589af589325b792634f128ab8b71f6dbf3a",
+  "method": "Built-in imagegen authored tug keys. One fixed scale, ground/center translation only. Exact existing Q5 seat first/last. No expanded tween film or live body deformation.",
+  "registration": {
+    "sheetSize": [
+      1774,
+      887
+    ],
+    "targetBounds": [
+      41,
+      92,
+      231,
+      301
+    ],
+    "registration": [
+      {
+        "cell": 0,
+        "scale": 0.5663956639566395,
+        "dx": 32,
+        "dy": 69
+      },
+      {
+        "cell": 1,
+        "scale": 0.5663956639566395,
+        "dx": 39,
+        "dy": 69
+      },
+      {
+        "cell": 2,
+        "scale": 0.5663956639566395,
+        "dx": 39,
+        "dy": 69
+      },
+      {
+        "cell": 3,
+        "scale": 0.5663956639566395,
+        "dx": 35,
+        "dy": 68
+      },
+      {
+        "cell": 4,
+        "scale": 0.5663956639566395,
+        "dx": 33,
+        "dy": 74
+      },
+      {
+        "cell": 5,
+        "scale": 0.5663956639566395,
+        "dx": 39,
+        "dy": 74
+      },
+      {
+        "cell": 6,
+        "scale": 0.5663956639566395,
+        "dx": 39,
+        "dy": 74
+      },
+      {
+        "cell": 7,
+        "scale": 0.5663956639566395,
+        "dx": 36,
+        "dy": 74
+      }
+    ]
+  }
+}

package/puppy-companion-life.mjs

@@ -11,16 +11,18 @@ const BALL_TARGET={x:0,z:-4};
 const OFFER={x:0,z:.3};
 // Hand-fed treat marker, relative to the puppy's current root (no travel for treats).
 const TREAT_OFFSET={z:.08,height:.25};
-const COOLDOWN={ball:6,treat:15};
+const COOLDOWN={ball:6,treat:15,tug:20};
 const FLIGHT=.65,BALL_PEAK=.75,CARRY_HEIGHT=.19,SETTLE_FALLBACK=.6,MAX_DT=.25,ARRIVE=.05;
 const LABEL={
  start:'기다리는 중',pause:'잠시 느긋하게 둘러보는 중',lie:'엎드리는 중',rest:'엎드려 쉬는 중',recover:'앉아서 기운 차리는 중',
  sit:'앉는 중',watch:'앉아서 지켜보는 중',look:'고개를 돌려 살피는 중',observe:'가만히 주변 관찰 중',
  stroll:'옆으로 살짝 걸어가는 중',sniff:'잠깐 멈춰 주변을 살피는 중',dash:'저 멀리 달려가는 중',far:'멀리서 둘러보는 중',home:'제자리로 돌아오는 중',
+ patrol:'주변을 왕복 산책하는 중',scan:'양쪽을 번갈아 살피는 중',roll:'느긋하게 뒹구는 중',play:'신나서 한 바퀴 도는 중',checkin:'가까이 와서 함께 쉬는 중',
+ belly:'배를 보이고 발라당 쉬는 중',sleep:'새근새근 잠자는 중',tug:'장난감을 물고 당기는 중',
  fetch:'공을 쫓아가는 중',pickup:'공을 무는 중',carry:'공을 물고 돌아오는 중',drop:'공을 내려놓는 중',offer:'공을 내려놓고 기다리는 중',
  treatSit:'간식 앞에 앉는 중',chew:'간식 먹는 중'
 };
-const PENDING_LABEL={treat:'곧 간식'};
+const PENDING_LABEL={treat:'곧 간식',tug:'곧 터그놀이'};
 // Baked interaction clips, played only while holding at the shared seated endpoint.
 const GESTURE={'ball-pickup':1.4,'ball-drop':1.2,'treat-eat':2.4};
 const clamp=(v,a,b)=>Math.min(b,Math.max(a,v));
@@ -38,7 +40,8 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
 
  const rand=mulberry32(seed),range=(a,b)=>a+(b-a)*rand(),side=()=>rand()<.5?'left':'right';
  const needs={energy,social:.5,curiosity:.5};
- const cooldowns={ball:0,treat:0};
+ const cooldowns={ball:0,treat:0,tug:0};
+ const episodeCooldowns={roll:0,play:0,belly:0,sleep:0};
  let clock=0,decisions=0,lastEpisode=null;
  let queue=[],hold=0,holdIntent=null,waiting=null,gesture=null;
  let intent='start',label=LABEL.start,pending=null,active=null,ball=null,treat=null;
@@ -51,25 +54,44 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
  // Treats accept any seat variant at the front-seated endpoint: the hand comes to the puppy.
  const seatedAnyVariant=()=>{const s=actor.sample(clock);return actor.state==='idle'&&s.seatProgress===1&&s.view==='approach';};
  const fx=fn=>({fx:fn});
- const home=()=>cmd('go',[HOME.x,HOME.z],'home');
+ const home=()=>cmd('go',[HOME.x,HOME.z],'home',()=>{const s=actor.sample(clock);return Math.hypot(s.x-HOME.x,s.z-HOME.z)>ARRIVE;});
+ const sit=step=>cmd('sit',[],step,()=>!seatedAnyVariant());
+ const lie=()=>cmd('lie',[],'lie',()=>actor.state!=='down');
+ const walkTo=x=>cmd('walk',()=>{const dx=x-actor.sample(clock).x;return [dx<0?'left':'right',Math.abs(dx)];},'patrol',()=>Math.abs(x-actor.sample(clock).x)>.002);
 
  // Each episode is a short coherent plan; a pause always leads in so autonomy never stalls.
  const EPISODES={
-  rest:()=>[cmd('lie',[],'lie'),wait(range(10,18),'rest'),cmd('sit',[],'recover'),wait(range(3,6),'recover')],
-  watch:()=>[cmd('sit',[],'sit'),cmd('look',[side()],'look'),wait(range(3,9),'watch'),fx(()=>{needs.social-=.3;needs.curiosity+=.1;})],
-  observe:()=>[cmd('look',[side()],'look'),wait(range(3,9),'observe'),fx(()=>{needs.curiosity-=.15;})],
+  rest:()=>[lie(),wait(range(10,18),'rest'),sit('recover'),wait(range(3,6),'recover')],
+  watch:()=>[sit('sit'),cmd('look',[side()],'look'),wait(range(3,9),'watch'),fx(()=>{needs.social-=.3;needs.curiosity+=.1;})],
+  observe:()=>[sit('sit'),cmd('look',[side()],'look'),wait(range(3,9),'observe'),fx(()=>{needs.curiosity-=.15;})],
   stroll:()=>[cmd('walk',[side(),range(.08,.18)],'stroll'),wait(range(2,4),'sniff'),home(),fx(()=>{needs.energy-=.08;needs.curiosity-=.2;})],
-  dash:()=>[cmd('go',[(rand()*2-1)*.18,-range(3,8)],'dash'),wait(range(1.5,3),'far'),home(),fx(()=>{needs.energy-=.3;needs.curiosity-=.4;})]
+  dash:()=>[cmd('go',[(rand()*2-1)*.18,-range(3,8)],'dash'),wait(range(1.5,3),'far'),home(),fx(()=>{needs.energy-=.3;needs.curiosity-=.4;})],
+  scan:()=>[sit('sit'),cmd('look',['left'],'scan'),wait(range(.5,1.5),'scan'),cmd('look',['right'],'scan'),wait(range(2,4),'observe'),fx(()=>{needs.curiosity-=.25;})],
+  patrol:()=>{const x=actor.sample(clock).x,d=range(.16,.3)*(rand()<.5?-1:1);return [walkTo(x+d),wait(range(.6,1.2),'sniff'),walkTo(x-d),wait(range(.6,1.2),'sniff'),walkTo(x),wait(range(1,3),'observe'),fx(()=>{needs.energy-=.1;needs.curiosity-=.25;})];},
+  roll:()=>[lie(),wait(range(.7,1.5),'rest'),cmd('roll',[],'roll'),wait(range(2,5),'watch'),fx(()=>{needs.energy-=.08;needs.curiosity-=.15;})],
+  checkin:()=>[home(),sit('sit'),cmd('look',[side()],'look'),wait(range(5,10),'checkin'),fx(()=>{needs.social-=.4;})],
+  play:()=>[cmd('spin',[],'play'),wait(range(1,2),'pause'),sit('sit'),wait(range(2,4),'watch'),fx(()=>{needs.energy-=.12;needs.curiosity-=.2;})],
+  belly:()=>[cmd('belly',[range(5,9)],'belly'),wait(range(2,4),'watch'),fx(()=>{needs.energy+=.08;needs.curiosity-=.15;})],
+  sleep:()=>[cmd('sleep',[range(22,38)],'sleep'),wait(range(2,4),'recover'),fx(()=>{needs.energy+=.3;})],
  };
  const weights=()=>{
   const {energy:e,social:s,curiosity:c}=needs;
-  return {rest:e<.35?6:(1-e)*1.2,watch:.8+s,observe:.6+c*.6,stroll:1.2*c*e,dash:e>.55?1.2*e*c:0};
+  return {rest:e<.35?6:(1-e)*1.2,watch:.8+s,observe:.6+c*.6,stroll:1.2*c*e,dash:e>.55?1.2*e*c:0,
+   scan:.35+c*.4,patrol:e>.25?.7*c*e:0,checkin:.25+s*.7,
+   roll:episodeCooldowns.roll===0&&e>.45?.35*e:0,
+   play:episodeCooldowns.play===0&&e>.6&&typeof actor.spin==='function'?.25*e*c:0,
+   belly:episodeCooldowns.belly===0&&typeof actor.belly==='function'?.35:0,
+   sleep:episodeCooldowns.sleep===0&&typeof actor.sleep==='function'?(e<.4?3:.2):0};
  };
  function decide(){
   const w=weights();if(lastEpisode)w[lastEpisode]=0;
   const kinds=Object.keys(w),total=kinds.reduce((sum,k)=>sum+w[k],0);
   let pick=rand()*total,kind=kinds.find(k=>(pick-=w[k])<0)??'observe';
   lastEpisode=kind;decisions++;
+  if(kind==='roll')episodeCooldowns.roll=90;
+  if(kind==='play')episodeCooldowns.play=120;
+  if(kind==='belly')episodeCooldowns.belly=80;
+  if(kind==='sleep')episodeCooldowns.sleep=100;
   queue=[wait(range(3,9),'pause'),...EPISODES[kind]()];
  }
 
@@ -88,15 +110,18 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   fx(()=>{treat=true;}),cmd('sit',[],'treatSit',()=>!seatedAnyVariant()),
   play('treat-eat','chew'),fx(()=>{treat=null;needs.energy+=.25;needs.social-=.3;})
  ];
+ const TUG_STEPS=()=>[
+  cmd('sit',[],'tug',unseated),cmd('tug',[6],'tug'),wait(.5,'watch'),fx(()=>{needs.energy-=.12;needs.social-=.4;})
+ ];
 
  function startInteraction(){
   active=pending;pending=null;decisions++;hold=0;
-  queue=active==='ball'?BALL_STEPS():TREAT_STEPS();
+  queue=active==='ball'?BALL_STEPS():active==='tug'?TUG_STEPS():TREAT_STEPS();
  }
  function finishInteraction(){cooldowns[active]=COOLDOWN[active];active=null;}
 
  function drift(dt){
-  const resting=holdIntent==='rest'||holdIntent==='recover';
+  const resting=holdIntent==='rest'||holdIntent==='recover'||actor.state==='sleep'||intent==='belly';
   needs.energy+=resting?.04*dt:-.004*dt;
   if(!active){needs.curiosity+=.01*dt;needs.social+=.008*dt;}
   for(const k in needs)needs[k]=clamp(needs[k],0,1);
@@ -106,6 +131,7 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   if(typeof dt!=='number'||!Number.isFinite(dt)||dt<0)throw RangeError('dt must be a finite non-negative number');
   dt=Math.min(dt,MAX_DT);clock+=dt;
   for(const k in cooldowns)cooldowns[k]=Math.max(0,cooldowns[k]-dt);
+  for(const k in episodeCooldowns)episodeCooldowns[k]=Math.max(0,episodeCooldowns[k]-dt);
   drift(dt);
   const safe=SAFE.has(actor.state);
   if(waiting){
@@ -133,15 +159,21 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
    if(step.when&&!step.when())continue;
    intent=step.intent;label=step.label;
    if(step.hold!==undefined){hold=step.hold;holdIntent=step.intent;if(step.gesture)gesture={clip:step.gesture,duration:step.hold,elapsed:0};return;}
-   if(actor[step.cmd](...step.args)!==false)waiting={age:0,left:false};
+   if(actor[step.cmd](...(typeof step.args==='function'?step.args():step.args))!==false)waiting={age:0,left:false};
    return;
   }
  }
 
  function interact(kind){
-  if(kind!=='ball'&&kind!=='treat')return false;
+  if(!['ball','treat','tug'].includes(kind))return false;
+  if(kind==='tug'&&typeof actor.tug!=='function')return false;
   if(pending||active||cooldowns[kind]>0)return false;
-  if(kind==='treat'){pending=kind;return true;}
+  if(kind==='treat'||kind==='tug'){
+   pending=kind;
+   // The pet wakes through its authored recovery, not after a long sleep timer.
+   if(['sleep','belly'].includes(actor.sample(clock).state))actor.sit();
+   return true;
+  }
   // Ball: launch now and drop obsolete controller plans; the actor's own state is left to chase.
   active='ball';decisions++;ball={mode:'flight',start:clock};
   queue=BALL_STEPS();hold=0;holdIntent=null;gesture=null;waiting=null;
@@ -172,8 +204,9 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   get report(){
    const interaction=active??pending;
    return {
-    intent,label:pending?`${label} · ${PENDING_LABEL[pending]}`:label,interaction,busy:interaction!==null,
-    ball:ballReport(),treat:treatReport(),energy:needs.energy,decisions,cooldowns:{...cooldowns},
+    intent,label:pending?`${label} · ${PENDING_LABEL[pending]}`:label,episode:lastEpisode,interaction,busy:interaction!==null,
+    ball:ballReport(),treat:treatReport(),tug:actor.state==='tug'?{progress:actor.sample(clock).comfortPose?.progress??0,grip:1}:null,
+    snore:actor.state==='sleep'?((clock%3.6)/3.6):null,energy:needs.energy,decisions,cooldowns:{...cooldowns},
     // Local hold clock only: progress freezes between updates; null outside the stationary hold.
     gesture:gesture&&SAFE.has(actor.state)?{clip:gesture.clip,progress:clamp(gesture.elapsed/gesture.duration,0,1)}:null
    };

package/puppy-companion-objects.mjs

@@ -7,6 +7,18 @@ export function paintCompanionObjects(pixels,width,height,projection,report,stat
  // Interaction drawings already include the toy/food. Never paint a second
  // floating ball over the baked mouth, or a biscuit through the puppy's chest.
  if(report.gesture)return pixels;
+ // A quiet, tiny rising "z" suggests snoring. The sleeping dog itself remains
+ // the original eyes-closed source pose: no chest/body zoom or squashing.
+ if(Number.isFinite(report.snore)&&state.state==='sleep'){
+  const placement=projection.placement(state.x,state.z),side=height*placement.size,sideX=side/placement.pixelAspect;
+  const left=width*placement.x-sideX/2,top=height*placement.y-300/320*side;
+  const cycle=report.snore,tone=Math.round(140*Math.sin(Math.PI*cycle)),unit=Math.max(1,Math.round(side/160));
+  const cx=Math.round(left+220/320*sideX),cy=Math.round(top+(210-16*cycle)/320*side);
+  if(tone>12)for(const [gx,gy] of [[0,0],[1,0],[2,0],[1,1],[0,2],[1,2],[2,2]])for(let dy=0;dy<unit;dy++)for(let dx=0;dx<unit;dx++){
+   const x=cx+gx*unit+dx,y=cy+gy*unit+dy;if(x<0||x>=width||y<0||y>=height)continue;
+   const j=(y*width+x)*4;pixels[j]=pixels[j+1]=pixels[j+2]=Math.max(pixels[j],tone);
+  }
+ }
  if(report.ball?.carried){if(mouth&&[mouth.x,mouth.y,mouth.rx,mouth.ry].every(Number.isFinite)&&mouth.rx>0&&mouth.ry>0)objects.push({kind:'ball',screen:mouth});}
  else if(report.ball)objects.push({...report.ball,radius:.035,kind:'ball'});
  if(report.treat)objects.push({...report.treat,height:report.treat.height??.018,radius:.022,kind:'treat'});

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