@bitefoundry/retrieviewer 0.0.5 → 0.0.7

package/ASSET-PROVENANCE.md

@@ -35,6 +35,13 @@ must be checked again for the final release bytes.
 
 ## Remaining limits
 
+0.0.6 re-registers only the36 watch samples of the existing behavior archive.
+The existing seated body/paws stay fixed while the authored head turns; no new
+image/photo/video reference is introduced. The offline preparation and source
+digest are in tools/prepare-watch-art.* and pet-q5-manifest.json. Butterfly wings
+are small geometric marks, using the same existing output buffer; dog poses
+reuse licensed gallop art. Existing attribution and CC BY-SA4.0 terms remain.
+
 0.0.5 extends that ninth licensed archive with four sleeping studies generated
 from the same existing puppy identity/pose references, approved by the owner in
 this conversation. COMFORT-ART.md and the comfort metadata record preparation,

package/BUTTERFLY.md

@@ -0,0 +1,30 @@
+# Rare butterfly encounter (0.0.6)
+
+No additional dog artwork, sprite archive, dependency, background process or
+timer. Existing short grounded gallops supply the bounding legs and ear motion;
+the visitor is drawn directly into the existing grayscale buffer before Braille
+conversion. Camera, stride-distance integration, contact correction and palette
+are unchanged. This is not a new up-looking/pouncing source illustration.
+
+The initial opportunity is scheduled after240–480 active simulation seconds.
+Only an awake, energetic puppy near the viewer may participate; sleep pressure
+takes priority. Subsequent opportunities are at least720 seconds apart, with
+up to480 additional random seconds. Hidden/paused time does not accumulate.
+An opportunity can be delayed by sleep or another coherent episode, rather than
+forcing a timer callback that wakes or interrupts the puppy.
+
+The puppy notices, makes three short alternating chases, watches the visitor fly
+away, returns and rests. Each target keeps the butterfly ahead of the muzzle.
+The visitor has an18-second visibility guard. Accepted ball/treat/tug clears the
+encounter and its obsolete route immediately, using normal actor recovery.
+A separate random stream leaves the existing ordinary episode/gait choices
+unchanged before the encounter.
+
+Checks: `node --test puppy-butterfly.test.mjs`, `npm test`.
+Generate a lightweight real-engine replay: `node tools/check-butterfly.mjs`.
+Its local `site-dist/butterfly-preview.html` loads prerecorded cropped Braille
+frames, not another full pet asset set. The replay is a QA artifact, not an npm
+asset or an alternate implementation. Serve only `site-dist` on a local address.
+
+Version0.0.6 includes this behavior. Existing0.0.5 registry artifacts remain
+unchanged. An already-running companion must be restarted after updating.

package/PUPPY-MEMORY.md

@@ -1,5 +1,50 @@
 # Runtime weight and performance
 
+## Watch neck seam repair (0.0.7)
+
+The0.0.6 watch registration moved the entire head/neck8px and dissolved it into
+the seated torso across y180..210. That crossed the bandana and produced a
+second collar/jaw silhouette. Preparation now preserves the original head,
+jaw, neck and bandana through y229. The join is below them in chest fur, with
+source/target chest contours registered before blending; lower legs/paws from
+y250 stay exactly seated. Endpoints and non-watch frames remain unchanged.
+The32 turned samples' protected regions have an independent original-source
+digest regression test. All changes are baked offline: no new frame, runtime
+dependency, live compositing buffer or per-frame computation. Published0.0.6
+bytes remain unchanged; this repair ships as0.0.7.
+
+## Node compressed crops (0.0.6)
+
+Node now stores each validated Q5 crop as a small DEFLATE block, using built-in
+`node:zlib`; only the existing two-frame LRU is expanded. The original archive
+buffer is released. Browser hosts keep the portable bit-packed implementation.
+No added runtime dependency, process, timer, lower resolution or lost pose.
+
+Same Windows host, fresh processes, same450-frame ball sequence:
+
+| Metric | 0.0.5 | 0.0.6 |
+| --- | ---: | ---: |
+| Loaded ArrayBuffers, after native close callbacks + diagnostic GC | 59.7 MiB | 21.4 MiB |
+| Rendered ArrayBuffers | 67.3 MiB | 29.0 MiB |
+| Mean frame time | 3.39 ms | 3.39 ms |
+| P95 frame time | 6.11 ms | 6.27 ms |
+| Initial load | 653 ms | 910 ms |
+| Actual Windows overlay worker RSS, short owned-window checks | 130 MiB | 96–106 MiB |
+
+The450-frame output hash is unchanged. `puppy-node-cache.test.mjs` compares every
+packaged source frame in both stores, including the separately repaired watch
+art. These samples are not a RAM ceiling: V8, allocator retention, viewport and
+activity change RSS. The helper is separate. The large off-screen benchmark
+peaked at267/238 MiB; do not substitute the short96–106 MiB samples for that peak.
+Evidence: tools/benchmark-pet.mjs, local dist/006-paired-{before,after}.json and
+dist/006-native-{before,source}.log. Diagnostic GC is never enabled in the pet.
+Shrinking V8's young generation was tested but increased rendering cost, so no
+global or embedded-host V8 flags are imposed.
+
+Watch repair adds no frame count; its archive is15,422 bytes smaller. Butterfly
+chasing adds no dog images or persistent image buffer; see BUTTERFLY.md. Existing
+sleep, colors, wake-on-interaction and5fps sleeping repaint remain unchanged.
+
 ## Comfort behaviors (0.0.4)
 
 Belly-up flopping and eyes-closed sleeping reuse the existing action/rest art.

package/README.ko.md

@@ -6,6 +6,7 @@
 앱 창 위에서 혼자 걷고, 뛰고, 앉아서 쉬는 보송한 점자 도트 리트리버예요.
 옆잠, 발라당, 몸 말기, 앞발에 턱 괴기. 조용하면 양쪽으로 누워 잠들어요.
 가끔 공·간식·터그로 놀아주세요.
+가끔 찾아오는 나비를 쫓기도 해요.
 나머지 시간에는 각자의 일을 하면 돼요.
 [BiteFoundry](https://github.com/BiteFoundry)가 만듭니다.
 런타임에는 계정, 모델 API, 텔레메트리가 필요하지 않아요.

package/README.md

@@ -12,7 +12,8 @@
 </p>
 
 A fluffy, autonomous Braille-art retriever that hangs out above an app window.
-It wanders, runs, flops belly-up and naps. Toss a ball, offer a treat or play tug.
+It wanders, runs, flops belly-up and naps. Occasionally it chases a butterfly.
+Toss a ball, offer a treat or play tug.
 Get back to your thing.
 
 Made by [BiteFoundry](https://github.com/BiteFoundry). No model API, account or

package/RELEASING.md

@@ -1,13 +1,13 @@
-# Retrieviewer 0.0.5 release process
-
-Current target: `@bitefoundry/retrieviewer@0.0.5`, public `latest`. The owner
-explicitly requested npm publication and homepage update of the approved sleep
-studies and mirrored side on2026-10-23. This also includes manual ink presets,
-sleep pressure independent of energy, shared gesture scratch and5fps sleep paint.
-Preserve0.0.4 registry bytes; never republish them. Run all checks below and publish
-only the exact tested0.0.5 tarball. Four new approved keys stay under the existing
-CC BY-SA4.0 artwork terms; see COMFORT-ART.md. The historical scope below describes
-0.0.4, not current verification results.
+# Retrieviewer 0.0.7 release process
+
+Current target: `@bitefoundry/retrieviewer@0.0.7`, public `latest`. The owner
+explicitly requested npm publication of the watch neck seam repair on2026-10-23.
+The authored head/jaw/neck/bandana remain together; chest contours are registered
+offline before joining the seated lower body. No new frames, runtime buffers,
+dependencies or per-frame work. Node crop compression and butterfly behavior
+from0.0.6 remain. MIT/CC BY-SA4.0 unchanged. Preserve0.0.6 and all earlier registry
+bytes; publish only the exact tested0.0.7 tarball. The historical scope below is
+not current verification evidence.
 
 Target: `@bitefoundry/retrieviewer@0.0.4`, public npm registry, `latest` tag.
 The npm organization `bitefoundry` uses the free public-packages plan; account

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitefoundry/retrieviewer",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "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://bitefoundry.github.io/retrieviewer/",
@@ -89,6 +89,7 @@
     "PUPPY-MEMORY.md",
     "PUPPY-Q5-COMPARISON.md",
     "COMFORT-ART.md",
+    "BUTTERFLY.md",
     "examples/embed.mjs",
     "examples/live.mjs",
     "examples/plugin.mjs",

package/pet-q5-manifest.json

@@ -80,11 +80,22 @@
    "uniqueFrames": 142,
    "sourceSha256": "7918261fb64c57a91739729841fd84c6dd53891196c7fb76ee9c27712ab6ef5d",
    "sourcePackedSha256": "7785ef65b8a2a5bf6f7ce600fe9957a60d9af82066ff49275bba061eac5392d1",
-   "encodedBytes": 7031343,
-   "gzipBytes": 1450156,
-   "residentPixelBytes": 4373034,
-   "encodedSha256": "38cfdfcee9c857c56a14f0a9734cb3301b4a04cb8e1ae3fb2e2b2ffe3666240f",
-   "quantizedSha256": "3c8f40416d2fff1c1031d3ad8917ea885998a786126d5973dfee4102893a0a53"
+   "encodedBytes": 6209085,
+   "gzipBytes": 1438571,
+   "residentPixelBytes": 3860054,
+   "encodedSha256": "93c98cb49ad26a84390adb76f443ab3cf231cf3d1203c3da4059e463283d5f51",
+   "quantizedSha256": "5c3c9d0dbe29db4b482fcc6b04562e46cf0d9352c95ad6c273b849a3f30b8d75",
+   "watchRegistration": {
+    "sourceVersion": "0.0.5",
+    "sourceEncodedSha256": "38cfdfcee9c857c56a14f0a9734cb3301b4a04cb8e1ae3fb2e2b2ffe3666240f",
+    "canonicalSeat": 50,
+    "bodyFromY": 250,
+    "chestBlendFromY": 230,
+    "chestContourRegistered": true,
+    "headTranslateY": 0,
+    "neckUnmodified": true,
+    "unchangedOtherFrames": true
+   }
   },
   "puppy-paper-actions-v9": {
    "file": "puppy-paper-actions-v9-q5.bin.gz",

package/puppy-companion-life.mjs

@@ -13,12 +13,15 @@ const OFFER={x:0,z:.3};
 const TREAT_OFFSET={z:.08,height:.25};
 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;
+// Active simulation seconds, never a wall-clock timer that wakes a hidden pet.
+export const BUTTERFLY_RULES=Object.freeze({firstMin:240,firstSpread:240,cooldownMin:720,cooldownSpread:480,maxVisible:18});
 const LABEL={
  start:'기다리는 중',pause:'잠시 느긋하게 둘러보는 중',lie:'엎드리는 중',rest:'엎드려 쉬는 중',recover:'앉아서 기운 차리는 중',
  sit:'앉는 중',watch:'앉아서 지켜보는 중',look:'고개를 돌려 살피는 중',observe:'가만히 주변 관찰 중',
  stroll:'옆으로 살짝 걸어가는 중',sniff:'잠깐 멈춰 주변을 살피는 중',dash:'저 멀리 달려가는 중',far:'멀리서 둘러보는 중',home:'제자리로 돌아오는 중',
  patrol:'주변을 왕복 산책하는 중',scan:'양쪽을 번갈아 살피는 중',roll:'느긋하게 뒹구는 중',play:'신나서 한 바퀴 도는 중',checkin:'가까이 와서 함께 쉬는 중',
  belly:'배를 보이고 발라당 쉬는 중',sleep:'새근새근 잠자는 중',tug:'장난감을 물고 당기는 중',
+ butterflyNotice:'나비를 발견하고 귀를 쫑긋하는 중',butterfly:'나비를 폴짝폴짝 쫓는 중',butterflyBye:'날아가는 나비를 바라보는 중',
  fetch:'공을 쫓아가는 중',pickup:'공을 무는 중',carry:'공을 물고 돌아오는 중',drop:'공을 내려놓는 중',offer:'공을 내려놓고 기다리는 중',
  treatSit:'간식 앞에 앉는 중',chew:'간식 먹는 중'
 };
@@ -39,6 +42,9 @@ 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';
+ // Separate stream: the rare encounter does not perturb ordinary episodes/gaits.
+ const encounterRand=mulberry32(seed^0x4bf17a93),encounterRange=(a,b)=>a+(b-a)*encounterRand();
+ let nextButterfly=BUTTERFLY_RULES.firstMin+encounterRange(0,BUTTERFLY_RULES.firstSpread),butterfly=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};
@@ -58,6 +64,32 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
  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);
+ const butterflyPoint=()=>{
+  if(!butterfly)return null;
+  const elapsed=clock-butterfly.since,p=clamp(elapsed/.65,0,1),ease=p*p*(3-2*p);
+  const leaving=butterfly.leaving?clamp((clock-butterfly.leaving)/1.1,0,1):0;
+  return {x:butterfly.from.x+(butterfly.to.x-butterfly.from.x)*ease+.025*Math.sin(elapsed*5)+leaving*.2*butterfly.side,
+   z:butterfly.from.z+(butterfly.to.z-butterfly.from.z)*ease,
+   height:.45+.045*Math.sin((clock-butterfly.start)*6)+leaving*.35,
+   phase:((clock-butterfly.start)*5)%1,opacity:1-leaving};
+ };
+ const butterflyEpisode=()=>{
+  const s=actor.sample(clock),direction=encounterRand()<.5?-1:1;
+  const targets=[clamp(s.x+direction*.36,-.5,.5),clamp(s.x-direction*.38,-.5,.5),clamp(s.x+direction*.24,-.5,.5)];
+  const z=s.z;
+  const moveFly=x=>fx(()=>{
+   const from=butterflyPoint()??{x:s.x-direction*.28,z};
+   const heading=x<actor.sample(clock).x?-1:1;
+   // The dog root is its body center, NOT its nose. Keep the visitor ahead of
+   // the muzzle on each leg, rather than hovering behind the running face.
+   butterfly={start:butterfly?.start??clock,since:clock,from:{x:from.x,z:from.z},to:{x:x+heading*.23,z},side:heading,leaving:0};
+  });
+  // Look names are dog-relative: its left is the viewer's right.
+  return [sit('butterflyNotice'),moveFly(targets[0]),cmd('look',[direction<0?'right':'left'],'butterflyNotice'),wait(.8,'butterflyNotice'),
+   ...targets.flatMap((x,i)=>[...(i?[moveFly(x)]:[]),cmd(typeof actor.chase==='function'?'chase':'go',[x,z],'butterfly'),wait(.3,'butterfly')]),
+   fx(()=>{if(butterfly)butterfly.leaving=clock;}),wait(1.1,'butterflyBye'),fx(()=>{butterfly=null;needs.energy-=.12;needs.curiosity-=.25;}),
+   home(),sit('recover'),wait(range(3,6),'recover')];
+ };
 
  // Each episode is a short coherent plan; a pause always leads in so autonomy never stalls.
  const EPISODES={
@@ -73,6 +105,7 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   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;})],
+  butterfly:butterflyEpisode,
  };
  const weights=()=>{
   const {energy:e,social:s,curiosity:c}=needs;
@@ -90,6 +123,10 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   // 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';
+  const position=actor.sample(clock);
+  if(kind!=='sleep'&&clock>=nextButterfly&&quiet>=15&&needs.energy>.6&&needs.drowsiness<.35&&position.z> -1.2){
+   kind='butterfly';nextButterfly=clock+BUTTERFLY_RULES.cooldownMin+encounterRange(0,BUTTERFLY_RULES.cooldownSpread);
+  }
   lastEpisode=kind;decisions++;
   if(kind==='roll')episodeCooldowns.roll=90;
   if(kind==='play')episodeCooldowns.play=120;
@@ -139,6 +176,10 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   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);
+  // A stalled or externally substituted actor must not leave a permanent insect.
+  if(butterfly&&clock-butterfly.start>BUTTERFLY_RULES.maxVisible){
+   butterfly=null;queue=[sit('recover'),wait(3,'recover')];hold=0;holdIntent=null;gesture=null;waiting=null;actor.rest();
+  }
   const safe=SAFE.has(actor.state);
   if(waiting){
    waiting.age+=dt;if(!safe)waiting.left=true;
@@ -175,6 +216,10 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   if(kind==='tug'&&typeof actor.tug!=='function')return false;
   if(pending||active||cooldowns[kind]>0)return false;
   quiet=0;
+  if(butterfly||lastEpisode==='butterfly'){
+   butterfly=null;queue=[];hold=0;holdIntent=null;gesture=null;waiting=null;
+   if(kind!=='ball')actor.sit();
+  }
   if(kind==='treat'||kind==='tug'){
    pending=kind;
    // The pet wakes through its authored recovery, not after a long sleep timer.
@@ -212,7 +257,7 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
    const interaction=active??pending;
    return {
     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,
+    ball:ballReport(),treat:treatReport(),butterfly:butterflyPoint(),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,22 @@ 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;
+ // Tiny procedural butterfly: two paired wings and a body. World-space size,
+ // same fixed camera and palette as the pet; no image/cache or extra render pass.
+ if(report.butterfly){
+  const b=report.butterfly,p=projection.project(b.x,b.height,b.z);
+  const edge=projection.project(b.x+.04,b.height,b.z),up=projection.project(b.x,b.height+.035,b.z);
+  const cx=p.x*width,cy=p.y*height,rx=Math.abs(edge.x-p.x)*width,ry=Math.abs(up.y-p.y)*height;
+  const opening=.22+.78*Math.abs(Math.sin(b.phase*Math.PI)),tone=Math.round(235*b.opacity);
+  if([cx,cy,rx,ry,opening,tone].every(Number.isFinite)&&rx>0&&ry>0&&tone>0)
+   for(let y=Math.max(0,Math.floor(cy-ry));y<Math.min(height,Math.ceil(cy+ry));y++)
+    for(let x=Math.max(0,Math.floor(cx-rx));x<Math.min(width,Math.ceil(cx+rx));x++){
+     const u=(x+.5-cx)/rx,v=(y+.5-cy)/ry,a=Math.abs(u)/opening;
+     const wing=((a-.5)/.44)**2+((v+.28)/.56)**2<1||((a-.36)/.29)**2+((v-.43)/.37)**2<1;
+     const body=Math.abs(u)<.1&&Math.abs(v)<.7;
+     if(wing||body){const j=(y*width+x)*4;pixels[j]=pixels[j+1]=pixels[j+2]=Math.max(pixels[j],body?tone:Math.round(tone*(.65+.35*a)));}
+    }
+ }
  // 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'){

package/puppy-frame-predictive.mjs

@@ -10,8 +10,9 @@
 //  20 u32[logicalFrameCount] logical -> unique index
 //  then uniqueCount records of u32 x,y,w,h,offset,length (length = h*(w+1))
 //  then the filtered rows of every unique crop, contiguous in order.
-// At load every crop is unfiltered once and kept as 5-bit packed indices; the
-// filtered input is not retained. Full frames are rebuilt on demand (LRU of 2).
+// At load every crop is validated. The portable store keeps 5-bit packed indices;
+// an optional host codec compresses each filtered crop instead (Node zlib).
+// Neither retains the input archive. Full frames rebuild on demand (LRU of 2).
 const MAGIC=[0x52,0x56,0x51,0x35],RVF1=[0x52,0x56,0x46,0x31],HEADER=20,RECORD=24,MAX_SIDE=16384,BITS=5;
 
 export const quantize5=v=>Math.round(v*31/255);
@@ -80,7 +81,8 @@ 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,{frameIndices}={}){
+function decode(bytes,{frameIndices,codec}={}){
+ if(codec&&(typeof codec.compress!=='function'||typeof codec.expand!=='function'))fail('codec');
  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);
@@ -107,27 +109,30 @@ function decode(bytes,{frameIndices}={}){
  }
  if(bytes.length!==data+total)fail('pixel length');
  if(pixels*BITS>0xffffffff)fail('pixel count');
- const packed=new Uint8Array(Math.ceil(pixels*BITS/8));
+ const packed=codec?null:new Uint8Array(Math.ceil(pixels*BITS/8)),chunks=codec?new Array(unique):null;
  let cur=new Uint8Array(width),prev=new Uint8Array(width),at=data,pos=0;
  for(let u=0;u<unique;u++){
-  const w=rects[u*5+2],h=rects[u*5+3];prev.fill(0);
+  const w=rects[u*5+2],h=rects[u*5+3],start=at;prev.fill(0);
   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');if(needed&&!needed[u])continue;
+    const q=cur[x];if(q>31)fail('quantized value');if(codec||(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;
   }
+  if(codec&&h&&(!needed||needed[u]))chunks[u]=Uint8Array.from(codec.compress(bytes.subarray(start,at)));
  }
- return{width,height,frameCount,unique,map,rects,packed,retained};
+ return{width,height,frameCount,unique,map,rects,packed,retained,chunks,codec};
 }
 
-function createStore({width,height,frameCount,unique,map,rects,packed,retained}){
+function createStore({width,height,frameCount,unique,map,rects,packed,retained,chunks,codec}){
  const n=width*height,slots=[{unique:-1,frame:null},{unique:-1,frame:null}];let decodes=0,hits=0;
+ const pixelBytes=packed?.byteLength??chunks.reduce((sum,c)=>sum+(c?.byteLength??0),0);
+ const cur=codec?new Uint8Array(width):null,prev=codec?new Uint8Array(width):null;
  return Object.freeze({
-  width,height,frameCount,uniqueCount:unique,byteLength:n*frameCount,residentPixelBytes:packed.byteLength,
-  get residentBytes(){return packed.byteLength+map.byteLength+rects.byteLength+(retained?.byteLength??0)+slots.reduce((s,e)=>s+(e.frame?.byteLength??0),0);},
+  width,height,frameCount,uniqueCount:unique,byteLength:n*frameCount,residentPixelBytes:pixelBytes,
+  get residentBytes(){return pixelBytes+map.byteLength+rects.byteLength+(cur?.byteLength??0)+(prev?.byteLength??0)+(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');
@@ -138,6 +143,18 @@ function createStore({width,height,frameCount,unique,map,rects,packed,retained})
    const slot=slots.pop();slots.unshift(slot);decodes++;
    const frame=slot.frame??=new Uint8Array(n),k=u*5,x=rects[k],y=rects[k+1],w=rects[k+2],h=rects[k+3];
    frame.fill(0);slot.unique=u;
+   if(codec){
+    if(!h)return frame;
+    const rows=codec.expand(chunks[u],h*(w+1));
+    if(rows.length!==h*(w+1))fail('expanded length');
+    prev.fill(0);
+    for(let r=0,at=0;r<h;r++,at+=w+1){
+     unfilterRow(rows[at],rows,at+1,cur,prev,w);
+     for(let c=0;c<w;c++)frame[(y+r)*width+x+c]=DISPLAY[cur[c]];
+     prev.set(cur.subarray(0,w));
+    }
+    return frame;
+   }
    let pos=rects[k+4]*BITS;
    for(let r=0;r<h;r++){
     const row=(y+r)*width+x;

package/puppy-paper.mjs

@@ -28,6 +28,13 @@ export function createPaperComfortTimings(actionInfo,{key=PAPER_COMFORT_TIMINGS.
 }
 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);
+// Turn, hold the gaze, then return. Progress addresses the two authored edges;
+// the paws and torso are registered to the same seated source in both edges.
+export const PAPER_WATCH_TIMING=Object.freeze({turn:.6,hold:.65,back:.65,total:1.9});
+export function paperWatchProgress(age){
+ const {turn,hold,back}=PAPER_WATCH_TIMING;
+ return age<turn?.5*comfortEase(age/turn):age<turn+hold?.5:.5+.5*comfortEase((age-turn-hold)/back);
+}
 
 // Original artwork only. Physics supplies ground travel; no procedural dog is drawn.
 export function createPaperActor(animal,info,{manualTricks=false,trickTimings=null,walkTransitions=false,comfortTimings=PAPER_COMFORT_TIMINGS}={}){
@@ -196,7 +203,7 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
    else if(state==='sit-down'){seatProgress=Math.min(1,seatProgress+dt/(snappyPreparation()?.35:.95));if(seatProgress===1){seatVariant='default';enter('idle');if(pendingAction)prepareDirection();}}
    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==='watch'&&age>=PAPER_WATCH_TIMING.total){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':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();}
@@ -222,7 +229,7 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
    if(walkTransitions&&state==='turn'){actionName='walk-turn';actionProgress=Math.min(1,age/turnSeconds());}
    if(view==='approach'&&approachPlan&&(state==='run'||(state==='finish'&&completed))){const p=approachPlan.at(travelDistance);if(state==='finish'){behavior='brake';behaviorProgress=1;}else if(p.clip!=='run'){behavior=p.clip;behaviorProgress=p.progress;}}
    if(state==='arrival-exit'){behavior='finish';behaviorProgress=Math.min(1,age/.22);}
-   if(state==='watch'){behavior=`watch-${watchSide}`;behaviorProgress=Math.min(1,age/1.4);}
+   if(state==='watch'){behavior=`watch-${watchSide}`;behaviorProgress=paperWatchProgress(age);}
    if(restProgress>0||state==='recline'||state==='wake'||state==='nap'){behavior='rest';behaviorProgress=restProgress;}
    if(state==='run'||state==='finish'){
     const p=state==='finish'?phase+(Math.ceil(phase)-phase)*Math.min(1,age/.22):phase;

package/retrieviewer.d.mts

@@ -48,6 +48,8 @@ export interface LifeReport {
   cooldowns: {ball: number; treat: number; tug: number};
   gesture: {clip: string; progress: number} | null;
   ball: {x: number; z: number; height: number; carried: boolean} | null;
+  /** Rare autonomous visitor; absent during direct user interactions. */
+  butterfly: {x: number; z: number; height: number; phase: number; opacity: number} | 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;

package/retrieviewer.mjs

@@ -60,9 +60,16 @@ async function gunzip(bytes){
 // life, renderer and output. Last dispose drops the shared lease, not other pets.
 const sharedAssets=new Map();
 async function loadPetAssets(loadAsset,artProfile){
+ // Node keeps filtered crops compressed; only the existing two-frame LRU is
+ // expanded. Browser bundles retain the portable bit-packed implementation.
+ let codec;
+ if(typeof process!=='undefined'&&process.versions?.node){
+  const {deflateRawSync,inflateRawSync}=await import('node:zlib');
+  codec={compress:bytes=>deflateRawSync(bytes,{level:1}),expand:(bytes,size)=>inflateRawSync(bytes,{maxOutputLength:size})};
+ }
  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,options)=>readPackedFrames(await gunzip(await load(name)),options);
+ const frames=async (name,options)=>readPackedFrames(await gunzip(await load(name)),{...options,codec});
  // 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);