@bitefoundry/retrieviewer 0.0.3 → 0.0.5

package/integrations/windows-overlay/worker.mjs

@@ -61,6 +61,6 @@ try{
  const {createPet}=await import('../../retrieviewer.mjs');const pet=await createPet();
  if(stopping)pet.dispose();else{
   pump=createFramePump({pet,send:write});if(pendingViewport)pump.viewport(pendingViewport);
-  write({type:'loaded'});timer=setInterval(()=>{try{pump.tick();}catch(error){write({type:'error',message:error.message});stop();}},1000/spec.fps);
+  write({type:'loaded',ink:process.env.RETRIEVIEWER_INK??'cream'});timer=setInterval(()=>{try{pump.tick();}catch(error){write({type:'error',message:error.message});stop();}},1000/spec.fps);
  }
 }catch(error){sendParent({error:error.message});await stop();}

package/package.json

@@ -1,10 +1,28 @@
 {
   "name": "@bitefoundry/retrieviewer",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "A fluffy Braille desktop pet for Windows and Linux X11, with experimental macOS support and an embeddable TUI engine.",
   "license": "SEE LICENSE IN LICENSE",
-  "homepage": "https://github.com/BiteFoundry",
-  "keywords": ["tui", "braille", "pet", "retriever", "opencode", "desktop-pet", "windows", "linux", "macos", "overlay"],
+  "homepage": "https://bitefoundry.github.io/retrieviewer/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BiteFoundry/retrieviewer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BiteFoundry/retrieviewer/issues"
+  },
+  "keywords": [
+    "tui",
+    "braille",
+    "pet",
+    "retriever",
+    "opencode",
+    "desktop-pet",
+    "windows",
+    "linux",
+    "macos",
+    "overlay"
+  ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
@@ -64,16 +82,17 @@
     "DESKTOP-PLATFORMS.md",
     "WINDOWS-COMPANION.md",
     "INSTALLING.md",
+    "PREREQUISITES.md",
+    "README.ko.md",
     "PLUGIN.md",
     "EMBEDDING.md",
     "PUPPY-MEMORY.md",
     "PUPPY-Q5-COMPARISON.md",
+    "COMFORT-ART.md",
     "examples/embed.mjs",
     "examples/live.mjs",
     "examples/plugin.mjs",
     "examples/bridge.py",
-    "locomotion-core.mjs",
-    "locomotion-puppy.animal",
     "braille.mjs",
     "puppy-frame-store.mjs",
     "puppy-frame-predictive.mjs",
@@ -91,6 +110,7 @@
     "puppy-companion-life.mjs",
     "puppy-companion-objects.mjs",
     "puppy-companion-sprites.mjs",
+    "puppy-comfort-sprites.mjs",
     "puppy-mouth-anchor.mjs",
     "puppy-mouth-anchor.json",
     "puppy-clean.mjs",
@@ -116,24 +136,25 @@
     "puppy-paper-actions-v9.json",
     "puppy-companion-interactions-v3-q5.bin.gz",
     "puppy-companion-interactions-v3.json",
-    "vendor/procedural-animals/src",
-    "vendor/procedural-animals/LICENSE",
-    "vendor/procedural-animals/package.json"
+    "puppy-companion-comfort-q5.bin.gz",
+    "puppy-companion-comfort.json",
+    "vendor/procedural-animals/LICENSE"
   ],
   "scripts": {
-    "start": "node server.mjs",
-    "terminal": "node terminal.mjs",
-    "pet": "node puppy-terminal.mjs",
+    "start": "node tools/preview-site.mjs",
+    "build:site": "node tools/build-site.mjs",
     "pet:companion": "node examples/live.mjs",
     "pet:desktop": "node retrieviewer-cli.mjs desktop",
     "test": "node --test \"*.test.mjs\"",
-    "test:locomotion": "node check-locomotion.mjs",
     "test:package": "node check-pet-package.mjs",
     "release:check": "node tools/check-release.mjs",
     "prepublishOnly": "npm run release:check"
   },
   "dependencies": {
-    "jsonc-parser": "3.3.1",
+    "jsonc-parser": "3.3.1"
+  },
+  "devDependencies": {
+    "playwright": "1.64.1",
     "three": "0.186.1"
   }
 }

package/puppy-comfort-sprites.mjs

@@ -0,0 +1,33 @@
+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,output){
+ if(!isGrayFrameSource(bytes)||![1,2].includes(info?.version)||info.width!==320||info.height!==320||info.frames!==(info.version===2?13:9))throw Error('Invalid comfort sprites');
+ if(output!==undefined&&(!(output instanceof Uint8ClampedArray)||output.length!==320*320*4))throw Error('Invalid comfort output');
+ const frames=grayFrameReader(bytes,320,320,info.frames);let rgba=output??null;
+ if(rgba)for(let i=3;i<rgba.length;i+=4)rgba[i]=255;
+ return pose=>{
+  if(!['tug','sleep'].includes(pose?.clip))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=pose.clip==='sleep'?info.sleep?.[pose.variant]:comfortFrameIndex(pose.progress,info);
+  if(!Number.isInteger(index))throw Error('Invalid sleep variant');
+  const frame=frames.getFrame(index),base=pose.base,blend=pose.blend??1;
+  if(!Number.isFinite(blend)||blend<0||blend>1)throw Error('Invalid sleep blend');
+  for(let i=0,j=0;i<frame.length;i++,j+=4){
+   const v=frame[pose.right?Math.floor(i/320)*320+319-i%320:i];
+   rgba[j]=rgba[j+1]=rgba[j+2]=base&&blend<1?Math.round(base[j]+(v-base[j])*blend):v;
+  }
+  return rgba;
+ };
+}

package/puppy-companion-comfort.json

@@ -0,0 +1,140 @@
+{
+  "version": 2,
+  "width": 320,
+  "height": 320,
+  "frames": 13,
+  "clips": [
+    "tug",
+    "sleep"
+  ],
+  "gzipBytes": 129148,
+  "residentPixelBytes": 341139,
+  "sourceSheetSha256": "10fde9dacca5cb45acd68f387e7ed3bcf88cd72cf0f9c4220d31d819db91731e",
+  "neutralSha256": "19f89a8bcb5a937e528593a8f36db846a0d45a5ee398f1b0873c056e5be2fa0a",
+  "encodedSha256": "35327cc103b1f7ac2ff1b09ed98658fd8ff1dcef322de9c9b18071a4358b7b87",
+  "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
+      }
+    ]
+  },
+  "sleep": {
+    "side": 9,
+    "belly": 10,
+    "curl": 11,
+    "chin": 12
+  },
+  "sleepRegistration": [
+    {
+      "key": "side",
+      "sourceBounds": [
+        26,
+        461,
+        1234,
+        873
+      ],
+      "width": 254,
+      "scale": 0.21026490066225165,
+      "ground": 300
+    },
+    {
+      "key": "belly",
+      "sourceBounds": [
+        28,
+        413,
+        1239,
+        881
+      ],
+      "width": 224,
+      "scale": 0.18497109826589594,
+      "ground": 300
+    },
+    {
+      "key": "curl",
+      "sourceBounds": [
+        44,
+        373,
+        1213,
+        992
+      ],
+      "width": 216,
+      "scale": 0.1847733105218135,
+      "ground": 300
+    },
+    {
+      "key": "chin",
+      "sourceBounds": [
+        116,
+        435,
+        1218,
+        953
+      ],
+      "width": 198,
+      "scale": 0.17967332123411978,
+      "ground": 300
+    }
+  ],
+  "sleepSourceHashes": {
+    "side": "85c567eb0958a213ee5b93d0a8592639489f5f29dded35e0d1d22e920ed1fe9f",
+    "belly": "e1967d9156a119d04e25fd6428fe5dcdbd2156c5e4eba0347217847874006109",
+    "curl": "10c9a85701af3587c48c1d8158972a07026e79a18a2375d86108538eda05aae7",
+    "chin": "e971eaa6861b597f0dba3a487403cee5f120cba0a9f9584d831b5634d096dee7"
+  }
+}

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));
@@ -37,9 +39,10 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
  if(!Number.isFinite(energy)||energy<0||energy>1)throw RangeError('energy must be within 0..1');
 
  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};
- let clock=0,decisions=0,lastEpisode=null;
+ const needs={energy,social:.5,curiosity:.5,drowsiness: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,quiet=0;
  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,47 @@ 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(65,110),['side','curl','chin','belly'][Math.floor(rand()*4)],rand()<.5],'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';
+  // Quiet-time sleep pressure is independent of energy restored by sitting.
+  // Wait for the current coherent episode to end; never yank a running puppy.
+  if(quiet>=120&&needs.drowsiness>=.35&&episodeCooldowns.sleep===0&&lastEpisode!=='sleep'&&typeof actor.sleep==='function')kind='sleep';
   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,16 +113,22 @@ 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;
+  const asleep=actor.state==='sleep';
+  needs.drowsiness+=asleep?-dt/60:dt/240;
+  quiet=active||pending||asleep?0:quiet+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 +137,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 +165,22 @@ 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;}
+  quiet=0;
+  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 +211,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,drowsiness:needs.drowsiness,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-companion-sprites.mjs

@@ -1,11 +1,13 @@
 import {grayFrameReader,isGrayFrameSource} from './puppy-frame-store.mjs';
 // Prebaked interaction samples; the original seat is the exact shared endpoint.
 // Pure sampling, no live image morph, root motion, camera or pose-size fitting.
-export function createCompanionSpriteSampler(bytes,info){
+export function createCompanionSpriteSampler(bytes,info,output){
  const n=320*320;
  if(!isGrayFrameSource(bytes)||info?.width!==320||info.height!==320||info.samples!==9||!Number.isInteger(info.pairs)||info.pairs<1||info.pairs>128||bytes.byteLength!==info.pairs*9*n)throw Error('Invalid companion sprite cache');
  for(const key of ['treat-eat','ball-pickup','ball-drop'])if(!Array.isArray(info.clips?.[key])||!info.clips[key].length||!info.clips[key].every(p=>Number.isInteger(p)&&p>=0&&p<info.pairs))throw Error('Invalid companion sprite clip');
- const frames=grayFrameReader(bytes,320,320,info.pairs*9),rgba=new Uint8ClampedArray(n*4);for(let i=3;i<rgba.length;i+=4)rgba[i]=255;
+ const frames=grayFrameReader(bytes,320,320,info.pairs*9),rgba=output??new Uint8ClampedArray(n*4);
+ if(!(rgba instanceof Uint8ClampedArray)||rgba.length!==n*4)throw Error('Invalid sprite output');
+ for(let i=3;i<rgba.length;i+=4)rgba[i]=255;
  return({clip,progress})=>{
   const list=info.clips[clip];if(!list||!Number.isFinite(progress)||progress<0||progress>1)throw Error('Invalid companion sprite pose');
   const q=progress*list.length,index=Math.min(list.length-1,Math.floor(q)),s=Math.round((q-index)*8),frame=frames.getFrame(list[index]*9+s);

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-actions.mjs

@@ -37,11 +37,13 @@ export function paperActionPose(name,progress,info){
  if(!Number.isFinite(blend))throw Error('Invalid paper action: blend');
  return{pair:list[index],blend};
 }
-export function createPaperActionSampler(bytes,info){
+export function createPaperActionSampler(bytes,info,output){
  if(!isGrayFrameSource(bytes))throw Error('Invalid action cache: bytes');
  validatePaperActionInfo(info,bytes.byteLength);
  const stride=info.width*info.height,pairs=info.pairs,frames=grayFrameReader(bytes,info.width,info.height,pairs*9);
- const out=new Uint8ClampedArray(stride*4);for(let i=3;i<out.length;i+=4)out[i]=255;
+ const out=output??new Uint8ClampedArray(stride*4);
+ if(!(out instanceof Uint8ClampedArray)||out.length!==stride*4)throw Error('Invalid action output');
+ for(let i=3;i<out.length;i+=4)out[i]=255;
  return state=>{const p=paperActionPose(state.actionName,state.actionProgress,info),sample=Math.round(p.blend*8);
   if(p.pair>=pairs||sample<0||sample>8)throw Error('Invalid paper action: sample out of range');
   const frame=frames.getFrame(p.pair*9+sample);for(let i=0,j=0;i<stride;i++,j+=4)out[j]=out[j+1]=out[j+2]=frame[i];return out;};

package/puppy-paper-behaviors.mjs

@@ -5,4 +5,4 @@ export function paperBehaviorPose(state,info){
  const q=Math.min(list.length-1e-9,progress*list.length),i=Math.floor(q),blend=Math.round((q-i)*8)/8;
  return{pair:list[i],blend};
 }
-export function createPaperBehaviorSampler(bytes,info){const sample=createRearSampler(bytes,info);return state=>{const p=paperBehaviorPose(state,info);return sample(p.pair,p.blend);};}
+export function createPaperBehaviorSampler(bytes,info,output){const sample=createRearSampler(bytes,info,output);return state=>{const p=paperBehaviorPose(state,info);return sample(p.pair,p.blend);};}

package/puppy-paper-contact.mjs

@@ -91,9 +91,11 @@ export function footSourcePoint(x,y,pins){
  return chosen?{x:x-chosen.dx*best,y:y-chosen.dy*best}:{x,y};
 }
 
-export function createRearSampler(bytes,info){
+export function createRearSampler(bytes,info,output){
  if(!isGrayFrameSource(bytes)||info.pairs!==18||info.samples!==9||bytes.byteLength!==18*9*320*320)throw Error('Invalid rear sprite cache');
- const frames=grayFrameReader(bytes,320,320,18*9),out=new Uint8ClampedArray(320*320*4);for(let i=3;i<out.length;i+=4)out[i]=255;
+ const frames=grayFrameReader(bytes,320,320,18*9),out=output??new Uint8ClampedArray(320*320*4);
+ if(!(out instanceof Uint8ClampedArray)||out.length!==320*320*4)throw Error('Invalid rear output');
+ for(let i=3;i<out.length;i+=4)out[i]=255;
  return(pair,blend)=>{
   if(!Number.isInteger(pair)||pair<0||pair>=18||!Number.isFinite(blend)||blend<0||blend>1)throw Error('Invalid rear pose');
   const frame=frames.getFrame(pair*9+Math.round(blend*8));

package/puppy-paper-seat.mjs

@@ -1,9 +1,11 @@
 import {grayFrameReader,isGrayFrameSource} from './puppy-frame-store.mjs';
 // Exact cached samples; no live crossfade. Reverse the same path to stand up.
-export function createPaperSeatSampler(bytes,info){
+export function createPaperSeatSampler(bytes,info,output){
  const stride=320*320;
  if(!isGrayFrameSource(bytes)||info.width!==320||info.height!==320||info.pairs!==3||info.samples!==17||bytes.byteLength!==3*17*stride)throw Error('Invalid paper sitting cache');
- const frames=grayFrameReader(bytes,320,320,3*17),out=new Uint8ClampedArray(stride*4);for(let i=3;i<out.length;i+=4)out[i]=255;
+ const frames=grayFrameReader(bytes,320,320,3*17),out=output??new Uint8ClampedArray(stride*4);
+ if(!(out instanceof Uint8ClampedArray)||out.length!==stride*4)throw Error('Invalid seat output');
+ for(let i=3;i<out.length;i+=4)out[i]=255;
  return progress=>{
   if(!Number.isFinite(progress)||progress<0||progress>1)throw Error('Invalid paper sitting progress');
   const q=progress*3,pair=Math.min(2,Math.floor(q)),sample=Math.round((q-pair)*16),frame=frames.getFrame(pair*17+sample);

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