@bitefoundry/retrieviewer 0.0.16 → 0.0.17

package/EMBEDDING.md

@@ -52,10 +52,16 @@ Redirected stdout prints one plain frame and exits.
 ## Assets / original option
 
 Default files resolve against the module URL, never cwd (lazy Node fs or browser
-HTTP fetch). getPetAssetFiles(profile?) returns exactly18 filenames:8 compressed
-bundles plus metadata and animal. Copy these without transforming bytes for
-bundlers. Loader returns ArrayBuffer/typed bytes; .gz must remain compressed,
-not transparently decompressed by HTTP Content-Encoding.
+HTTP fetch). getPetAssetFiles(profile?) returns 19 filenames: nine art archives
+plus ten metadata files. Copy these unchanged for bundlers. The default Q5 files
+use `.rvz`, an index followed by individually gzip-compressed crops. A custom
+loader returns the original ArrayBuffer/typed bytes, without unpacking the archive.
+
+Local Node hosts using the default loader read only the indices at creation and
+read/decode requested crops synchronously into a two-frame cache per family.
+There is no background loader or extra process. The final pet's `dispose()` closes
+the shared files. Custom loaders and browsers use the portable memory-backed
+store; they do not receive the local file-backed memory reduction.
 
 ```js
 import {createPet,getPetAssetFiles} from '@bitefoundry/retrieviewer';
@@ -74,11 +80,11 @@ They are **not bundled** in the small distribution. For external original art,
 copy getPetAssetFiles('original') from the workspace and supply loadAsset. Missing
 originals fail clearly, never silently fall back.
 
-Q5 is lossy quantization (max source-pixel error4/255), not lossless compression.
-Art gzip18.7MB versus54.2MB original; resident packed pixels66.5MB.
-One Windows Node sample:172MB RSS after rendering, startup737ms, mean frame2.61ms
-at160×50. Samples, not guarantees. Node/Three remain runtime costs.
-See [PUPPY-Q5-COMPARISON.md](./PUPPY-Q5-COMPARISON.md).
+Q5 is lossy quantization (max original-source pixel error 4/255). The indexed
+repack is lossless relative to the approved Q5 art: all 2,401 logical frames and
+their timing remain unchanged. The nine indexed archives total 19,326,068 bytes;
+their indices total 54,040 bytes. No Three.js dependency runs in the pet core.
+See [PUPPY-MEMORY.md](./PUPPY-MEMORY.md) for measured costs and host limitations.
 
 ## JSONL bridge (Python/Rust/other process hosts)
 

package/PUPPY-MEMORY.md

@@ -1,5 +1,64 @@
 # Runtime weight and performance
 
+## Indexed local art (local candidate, 2026-10-25)
+
+The default local Node loader opens nine RVZ5 files and reads only 54,040 bytes
+of indices (plus 20-byte header probes). Each file contains the exact approved
+RVQ5 filtered rows, individually gzip-compressed offline at level 9. Frame access
+reads and inflates one requested crop into the existing two-frame-per-family
+cache. No artwork family is decompressed/recompressed during startup; no loader
+thread, process, dependency, polling timer or persistent user cache is added.
+Shared pets hold one set of file descriptors. Last disposal closes all nine;
+partial startup failure closes previously opened files. Repeated disposal is safe.
+
+All 2,401 logical source frames are pixel-identical, including duplicates and
+random seeks. The indexed repack round-trips to byte-identical RVQ5 archives.
+The 450-frame fetch replay retains the same trajectory and visible SHA256
+`76d5ec6c58622f4330a277852e0d6cb16f4bf2f9fd118688d9ec97b35f80f6a8`.
+Timing, contacts, physics, palettes, art resolution and behavior are unchanged.
+
+Fresh-process Windows Node 24 samples, seed 731, 480x135 cells, the existing
+`tools/benchmark-pet.mjs` workload. ArrayBuffers/RSS samples below use diagnostic
+GC after native zlib-close callbacks; these are not desktop memory guarantees.
+
+| Metric | Previous | Indexed |
+|---|---:|---:|
+| Initial load | 1,481ms | 17ms |
+| Loaded ArrayBuffers | 21,122,810B | 206,439B |
+| Rendered ArrayBuffers | 27,658,258B | 6,741,887B |
+| Loaded process RSS | 92,504,064B | 66,420,736B |
+| Rendered process RSS | 166,457,344B | 148,267,008B |
+| Peak benchmark process RSS | 207,421,440B | 158,302,208B |
+| Mean frame time | 4.04ms | 4.09ms |
+| P95 frame time | 6.44ms | 6.80ms |
+
+This is a RAM/startup tradeoff, not a smaller download: art bytes increase from
+19,095,012 to 19,326,068 (about 1.2%) to allow independent crop reads. The npm
+candidate is about 19.5MB versus 19.3MB; it contains only indexed Q5 art, not
+duplicate legacy archives. Legacy source archives remain for authoring and exact
+regression comparisons. `pet-indexed-manifest.json` describes the shipped format;
+the older `pet-q5-manifest.json` describes its legacy source inputs.
+
+Random-access storage adds synchronous small reads during rendering. The local
+sample used OS-cached files; cold disks, network filesystems, antivirus and other
+platforms can have different latency. Frame access validates gzip length/CRC and
+filtered pixels on demand; headers, maps, crop bounds and offsets are validated
+at opening. This differs from the old eager whole-archive pixel validation.
+
+Browser/custom-loader compatibility is retained by restoring each indexed family
+into the existing portable store during async creation. Those hosts do not get
+the local file-backed RAM reduction. Actual Aside browser loading, Braille output
+and a ball interaction were checked; no Node file module was requested there.
+An isolated npm-installed Windows native check painted real frames, accepted the
+native ball button and exited worker/painter cleanly. Its short Node sample was
+73MiB RSS, with native-helper memory separate; it is not a peak or long-run budget.
+No live Linux/macOS check was performed for this storage change.
+
+Evidence: local `dist/indexed-art-{before,after}.json`,
+`dist/indexed-art-tests.txt`, `dist/package-check-*/package-check.json` and
+`dist/windows-overlay-qa/`. Rebuild/check deterministic archives with
+`npm run bake:art-index` / `npm run check:art-index` in the source checkout.
+
 ## Held-pose invalidation (local candidate, 2026-10-24)
 
 The desktop pump now asks `pet.needsFrame(viewport)` before rasterization. Only

package/README.ko.md

@@ -108,6 +108,9 @@ npm uninstall -g @bitefoundry/retrieviewer
 
 ## StackBite 알림
 
+0.0.17은 기존 그림과 움직임을 유지하고, 기본 로컬 Node 실행에서 필요한 그림만
+파일에서 읽어요. [메모리 측정 기록](PUPPY-MEMORY.md)을 참고하세요.
+
 0.0.16은 앞발로 살살 부르기와 두 발로 서서 벽 박박 긁기를 번갈아 보여줘요.
 홈페이지에서도 두 동작을 눌러볼 수 있어요. Windows의 npm 설치형 StackBite도
 감시할 수 있게 했어요. 작업 완료 체크표시는 아직 알림 대상이 아니에요.

package/README.md

@@ -141,6 +141,9 @@ Version 0.0.15 alerts without waiting for the model, shows the Seat name and
 pending kind locally on Windows, and lets the puppy approach before looking
 toward the sidebar. It reuses existing artwork; names never enter model input.
 
+Version 0.0.17 keeps the same artwork and motion while loading only requested
+frames from disk in the default local Node host. See [memory measurements](PUPPY-MEMORY.md).
+
 Version 0.0.16 adds two approved attention gestures: a gentle seated paw and a
 standing two-paw glass scrabble. They alternate for new alerts; both are playable
 in the website demo. Windows watching also supports npm's PowerShell launcher.

package/RELEASING.md

@@ -1,4 +1,20 @@
-# Retrieviewer 0.0.16 release process
+# Retrieviewer 0.0.17 release process
+
+Current target: `@bitefoundry/retrieviewer@0.0.17`, public `latest`.
+On 2026-10-25 the owner authorized publication of the indexed local-art update
+and measurement of actual operating memory. Local Node hosts read only the art
+indices at startup, then reconstruct requested crops from file-backed archives.
+All 2,401 approved Q5 frames, timing and behavior remain unchanged. The browser
+and custom-loader paths retain the compatible memory-backed representation.
+No new dependency, background loader, process or persistent user cache is added.
+
+Publish one fresh installed/native-tested tarball after Windows/Linux CI and
+verify its registry integrity and a fresh registry consumer. Keep existing pets
+running; measure only owned diagnostic windows and report Node and native-helper
+working sets separately. No real approval, paid inference or user-window change
+is needed for the measurement. Preserve all existing registry releases.
+
+## Previous 0.0.16 scope (historical)
 
 Current target: `@bitefoundry/retrieviewer@0.0.16`, public `latest`.
 On2026-10-24 the owner accepted the gentle-paw and standing-wall gestures and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitefoundry/retrieviewer",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "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/",
@@ -142,26 +142,29 @@
     "puppy-continuous.mjs",
     "puppy-zoomies.mjs",
     "puppy-zoomies30.mjs",
-    "puppy-stride-tweens-q5.bin.gz",
+    "puppy-stride-tweens-q5.rvz",
     "puppy-stride-meta.json",
     "puppy-stable-meta.json",
-    "puppy-paper-rear-gallop-q5.bin.gz",
+    "puppy-paper-rear-gallop-q5.rvz",
     "puppy-paper-rear-gallop.json",
-    "puppy-paper-approach-q5.bin.gz",
+    "puppy-paper-approach-q5.rvz",
     "puppy-paper-approach.json",
-    "puppy-paper-seat-q5.bin.gz",
+    "puppy-paper-seat-q5.rvz",
     "puppy-paper-seat.json",
-    "puppy-paper-arrival-seat-q5.bin.gz",
+    "puppy-paper-arrival-seat-q5.rvz",
     "puppy-paper-arrival-seat.json",
-    "puppy-paper-behaviors-q5.bin.gz",
+    "puppy-paper-behaviors-q5.rvz",
     "puppy-paper-behaviors.json",
-    "puppy-paper-actions-v9-q5.bin.gz",
+    "puppy-paper-actions-v9-q5.rvz",
     "puppy-paper-actions-v9.json",
-    "puppy-companion-interactions-v3-q5.bin.gz",
+    "puppy-companion-interactions-v3-q5.rvz",
     "puppy-companion-interactions-v3.json",
-    "puppy-companion-comfort-q5.bin.gz",
+    "puppy-companion-comfort-q5.rvz",
     "puppy-companion-comfort.json",
-    "vendor/procedural-animals/LICENSE"
+    "vendor/procedural-animals/LICENSE",
+    "puppy-frame-indexed.mjs",
+    "puppy-frame-file.mjs",
+    "pet-indexed-manifest.json"
   ],
   "scripts": {
     "bake:motion": "node tools/bake-pet-motion.mjs",
@@ -173,7 +176,9 @@
     "test": "node --test",
     "test:package": "node check-pet-package.mjs",
     "release:check": "npm run check:motion && node tools/check-release.mjs",
-    "prepublishOnly": "npm run release:check"
+    "prepublishOnly": "npm run release:check",
+    "bake:art-index": "node tools/index-pet-art.mjs",
+    "check:art-index": "node tools/index-pet-art.mjs --check"
   },
   "dependencies": {
     "jsonc-parser": "3.3.1"

package/pet-indexed-manifest.json

@@ -0,0 +1,106 @@
+{
+  "version": 1,
+  "format": "RVZ5",
+  "pixels": "Exact approved RVQ5 rows; no quantization, frame removal or resampling",
+  "entries": [
+    {
+      "file": "puppy-stride-tweens-q5.rvz",
+      "bytes": 7643027,
+      "indexBytes": 19608,
+      "frames": 799,
+      "uniqueFrames": 683,
+      "sha256": "e049a3e5dbf2332620d881b8b484b1828dcc7aa3c9e636bf14358b3146458fd9",
+      "source": "puppy-stride-tweens-q5.bin.gz",
+      "sourceSha256": "abcc6f1825f09655f23e977c56e6790d27edd054c4c24be852c097fb575d6a4f",
+      "restoredRvq5Sha256": "eecf92fd402843bef43aa4b154db6eba999959dd16cd8e34c54e42c88eaade10"
+    },
+    {
+      "file": "puppy-paper-rear-gallop-q5.rvz",
+      "bytes": 1481295,
+      "indexBytes": 4100,
+      "frames": 162,
+      "uniqueFrames": 143,
+      "sha256": "fefa5949317e5afde1f5872f8ac43da95206a844cec1d90b27b2f31f32655ddd",
+      "source": "puppy-paper-rear-gallop-q5.bin.gz",
+      "sourceSha256": "ca731e1979a37ec2e005a80365e3b58358f640b8b26e7036b0e931940a7b1264",
+      "restoredRvq5Sha256": "fe96e31d30348cc7d1fc674f40778d2312c9d1b40c57e634dcc397a35cc5ccf4"
+    },
+    {
+      "file": "puppy-paper-approach-q5.rvz",
+      "bytes": 1462216,
+      "indexBytes": 4004,
+      "frames": 162,
+      "uniqueFrames": 139,
+      "sha256": "5f14d0c8f4b2a5a6f59be653cd6a9f3c0450260e0ae4e79074a0da5dc9f66821",
+      "source": "puppy-paper-approach-q5.bin.gz",
+      "sourceSha256": "17179d3ace7748f66ed3c5a61b5246d24ecd3570b350535bd2edc8cbf58304e6",
+      "restoredRvq5Sha256": "6f57a5f506eabea41c00f02738c8124a4ae8e05471bdcd76e0a6e9ed739ca1a3"
+    },
+    {
+      "file": "puppy-paper-seat-q5.rvz",
+      "bytes": 481353,
+      "indexBytes": 1400,
+      "frames": 51,
+      "uniqueFrames": 49,
+      "sha256": "569e943321eaad920f6915c4bd7c60f70571737c57a9407f3268ae7283565c4f",
+      "source": "puppy-paper-seat-q5.bin.gz",
+      "sourceSha256": "5480c994de0d034d70eff6ea86095f3722cf87bde72f364dd369b94b1ad66f84",
+      "restoredRvq5Sha256": "b21aa11039b314ed3dec96818e571d54b6102bd0bc1f76e0a99ceb6d2b5ae097"
+    },
+    {
+      "file": "puppy-paper-arrival-seat-q5.rvz",
+      "bytes": 492675,
+      "indexBytes": 1400,
+      "frames": 51,
+      "uniqueFrames": 49,
+      "sha256": "d69c7d59c99b6f12cebab4e92ec2aa137ba68efb56bb5d37cb52ea1b91d217a2",
+      "source": "puppy-paper-arrival-seat-q5.bin.gz",
+      "sourceSha256": "7effa0a2150e8ef9ed37d5b6cb10089672e0ce32599c06db21ad4769144bf246",
+      "restoredRvq5Sha256": "3b2ef9e322e625340c42a549f17165492cc14f724f4593bf298f67195677bb6e"
+    },
+    {
+      "file": "puppy-paper-behaviors-q5.rvz",
+      "bytes": 1288500,
+      "indexBytes": 3692,
+      "frames": 162,
+      "uniqueFrames": 126,
+      "sha256": "fac739a813a00bfd63294b3926b2463b60a2ab1a1b063b4ae02a053d2f925e8d",
+      "source": "puppy-paper-behaviors-q5.bin.gz",
+      "sourceSha256": "e4b79387aca974ceec74a02dc3f02780eb53d38af6ec9ebd69994de744b39716",
+      "restoredRvq5Sha256": "cb045558ca490436c5d6703f6468daba26f20ed76bc886e829787889253ccbb9"
+    },
+    {
+      "file": "puppy-paper-actions-v9-q5.rvz",
+      "bytes": 4691230,
+      "indexBytes": 13772,
+      "frames": 594,
+      "uniqueFrames": 474,
+      "sha256": "80621dbbdbd5272e9f4a40ac237f1d1f784a01456cdef48f2c10fdd45095f600",
+      "source": "puppy-paper-actions-v9-q5.bin.gz",
+      "sourceSha256": "abb4677468206c62937c0247dc4c5823e0a7c4a3a197da40194a08dd594aeef9",
+      "restoredRvq5Sha256": "615fb04961a38e592a661a20ad50fad45e1e4205e34198fa87a155ace966ea77"
+    },
+    {
+      "file": "puppy-companion-interactions-v3-q5.rvz",
+      "bytes": 1160887,
+      "indexBytes": 4436,
+      "frames": 360,
+      "uniqueFrames": 124,
+      "sha256": "237089d60d0350f08c4570c3379d44a6947d610b59c50856ed5f050d1debf420",
+      "source": "puppy-companion-interactions-v3-q5.bin.gz",
+      "sourceSha256": "8c7d24254f3f1e9fb85bff5ed1c7904fb4f111b0e47b57eee22dc094c18f3bf3",
+      "restoredRvq5Sha256": "5ebfc58c9cfeaf349d30bc65be2e4663f7a3b8be9f35ca5d6da323172624de7a"
+    },
+    {
+      "file": "puppy-companion-comfort-q5.rvz",
+      "bytes": 624885,
+      "indexBytes": 1628,
+      "frames": 60,
+      "uniqueFrames": 57,
+      "sha256": "9df13e0e4c5cd854e42aee595ee675eea716293e392d6e587145ffbaa74c5870",
+      "source": "puppy-companion-comfort-q5.bin.gz",
+      "sourceSha256": "57942c55e9c467d973a08f1e23804b0f756eaed46dddfe3aba7e7c3621996236",
+      "restoredRvq5Sha256": "5f598c2ba15212a73e88c02f0d189b20a74e46f2346f7dfbc3bca8c2d26fc66b"
+    }
+  ]
+}

package/puppy-frame-file.mjs

@@ -0,0 +1,15 @@
+// Loaded only by the default local Node host; browsers never import node:fs.
+import {openSync,readSync,fstatSync,closeSync} from 'node:fs';
+import {gunzipSync} from 'node:zlib';
+import {indexedIndexLength,readIndexedIndex,createIndexedFrameStore} from './puppy-frame-indexed.mjs';
+import {registerFrameStore} from './puppy-frame-store.mjs';
+
+export function openFrameFile(url,options){
+ const fd=openSync(url,'r');let owned=true;
+ try{
+  const stat=fstatSync(fd);if(!stat.isFile())throw Error('Invalid frame file');
+  const read=(offset,size)=>{const out=new Uint8Array(size);let at=0;while(at<size){const n=readSync(fd,out,at,size-at,offset+at);if(!n)throw Error('Truncated frame file');at+=n;}return out;};
+  const header=read(0,20),length=indexedIndexLength(header),index=readIndexedIndex(read(0,length),stat.size);
+  const store=registerFrameStore(createIndexedFrameStore(index,{...options,read,expand:(b,n)=>gunzipSync(b,{maxOutputLength:Math.max(1,n)}),close:()=>closeSync(fd)}));owned=false;return store;
+ }finally{if(owned)closeSync(fd);}
+}

package/puppy-frame-indexed.mjs

@@ -0,0 +1,78 @@
+// RVZ5: the approved RVQ5 rows, independently gzip-compressed for random access.
+// Header/map match RVQ5; each 24-byte crop record stores x,y,w,h,offset,gzipLength.
+// Offsets are relative to the end of the index. No new quantization or resampling.
+import {unfilterRow} from './puppy-frame-predictive.mjs';
+const HEADER=20,RECORD=24,MAX_PIXELS=16_777_216,MAX_INDEX=64*1024*1024,MAX_EXPANDED=512*1024*1024;
+const fail=why=>{throw Error('Invalid indexed frames: '+why);};
+const viewOf=b=>new DataView(b.buffer,b.byteOffset,b.byteLength);
+export function indexedIndexLength(header){
+ if(!(header instanceof Uint8Array)||header.length<HEADER||String.fromCharCode(...header.subarray(0,4))!=='RVZ5')fail('header');
+ const v=viewOf(header),width=v.getUint32(4,true),height=v.getUint32(8,true),frames=v.getUint32(12,true),unique=v.getUint32(16,true);
+ if(!width||!height||width>16384||height>16384||width*height>MAX_PIXELS||!frames||!unique||unique>frames)fail('shape');
+ const length=HEADER+4*frames+RECORD*unique;
+ if(length>MAX_INDEX)fail('index size');return length;
+}
+export function readIndexedIndex(bytes,fileSize=bytes.length){
+ const length=indexedIndexLength(bytes);if(bytes.length<length||!Number.isSafeInteger(fileSize)||fileSize<length)fail('truncated index');
+ const v=viewOf(bytes),width=v.getUint32(4,true),height=v.getUint32(8,true),frameCount=v.getUint32(12,true),uniqueCount=v.getUint32(16,true);
+ const map=new Uint32Array(frameCount),used=new Uint8Array(uniqueCount),rects=new Uint32Array(uniqueCount*6);let payload=0,expanded=0;
+ for(let i=0;i<frameCount;i++){const u=v.getUint32(HEADER+i*4,true);if(u>=uniqueCount)fail('map');map[i]=u;used[u]=1;}
+ if(used.includes(0))fail('unreferenced frame');
+ for(let u=0;u<uniqueCount;u++){
+  const at=HEADER+frameCount*4+u*RECORD,r=Array.from({length:6},(_,i)=>v.getUint32(at+i*4,true)),[x,y,w,h,offset,size]=r;
+  if((w===0)!==(h===0)||(!w&&(x||y))||x+w>width||y+h>height)fail('rectangle');
+  if(offset!==payload||size<20)fail('offset');payload+=size;expanded+=h*(w+1);
+  if(expanded>MAX_EXPANDED)fail('expanded size');rects.set(r,u*6);
+ }
+ if(length+payload!==fileSize)fail('file size');
+ return {width,height,frameCount,uniqueCount,map,rects,indexBytes:length,expandedBytes:expanded,fileSize};
+}
+const display=Uint8Array.from({length:32},(_,q)=>Math.round(q*255/31));
+
+// The host provides bounded positional reads and a synchronous gzip decoder.
+// Only two reconstructed frames survive; compressed art stays on disk.
+export function createIndexedFrameStore(index,{read,expand,close=()=>{},frameIndices}={}){
+ if(typeof read!=='function'||typeof expand!=='function')fail('reader');
+ const {width,height,frameCount,uniqueCount,map,rects,indexBytes}=index,n=width*height;
+ const retained=frameIndices===undefined?null:new Uint8Array(frameCount);
+ if(retained){if(!Array.isArray(frameIndices)||!frameIndices.length)fail('retained frames');for(const i of frameIndices){if(!Number.isInteger(i)||i<0||i>=frameCount)fail('retained frame index');retained[i]=1;}}
+ const slots=[{unique:-1,frame:null},{unique:-1,frame:null}],cur=new Uint8Array(width),prev=new Uint8Array(width);
+ let closed=false,decodes=0,hits=0,diskBytes=0;
+ return Object.freeze({width,height,frameCount,uniqueCount,byteLength:n*frameCount,residentPixelBytes:0,
+  get residentBytes(){return closed?0:map.byteLength+rects.byteLength+cur.byteLength+prev.byteLength+(retained?.byteLength??0)+slots.reduce((s,e)=>s+(e.frame?.byteLength??0),0);},
+  stats(){return {decodes,hits,cachedFrames:slots.filter(s=>s.frame).length,diskReads:decodes,diskBytes,closed};},
+  getFrame(i){
+   if(closed)throw Error('Frame store is disposed');
+   if(!Number.isInteger(i)||i<0||i>=frameCount)fail('frame index');if(retained&&!retained[i])fail('frame was not retained');
+   const u=map[i];if(slots[0].unique===u){hits++;return slots[0].frame;}if(slots[1].unique===u){hits++;slots.reverse();return slots[0].frame;}
+   const k=u*6,x=rects[k],y=rects[k+1],w=rects[k+2],h=rects[k+3],offset=rects[k+4],size=rects[k+5],expected=h*(w+1);
+   const compressed=read(indexBytes+offset,size);if(!(compressed instanceof Uint8Array)||compressed.length!==size)fail('short read');
+   const rows=expand(compressed,expected);if(!(rows instanceof Uint8Array)||rows.length!==expected)fail('expanded length');
+   // Mark the evicted slot invalid before parsing: a failed decode is never a hit.
+   const slot=slots.pop();slots.unshift(slot);slot.unique=-1;const frame=slot.frame??=new Uint8Array(n);frame.fill(0);prev.fill(0);
+   for(let r=0,at=0;r<h;r++){
+    const type=rows[at++];if(type>4)fail('filter');
+    unfilterRow(type,rows,at,cur,prev,w);at+=w;
+    for(let c=0;c<w;c++){
+     const q=cur[c];if(q>31)fail('quantized value');frame[(y+r)*width+x+c]=display[q];
+    }
+    prev.set(cur.subarray(0,w));
+   }
+   slot.unique=u;decodes++;diskBytes+=size;return frame;
+  },
+  dispose(){if(closed)return;closed=true;for(const slot of slots){slot.frame=null;slot.unique=-1;}close();},
+ });
+}
+
+// Portable/custom loaders retain the existing in-memory Q5 representation.
+// The default local Node loader instead reads only the index and requested crops.
+export async function expandIndexedArchive(bytes,expand){
+ const index=readIndexedIndex(bytes),{frameCount,uniqueCount,rects,indexBytes,expandedBytes}=index;
+ const out=new Uint8Array(indexBytes+expandedBytes);out.set(bytes.subarray(0,indexBytes));out.set([82,86,81,53]);const v=viewOf(out);let offset=0;
+ for(let u=0;u<uniqueCount;u++){
+  const k=u*6,size=rects[k+3]*(rects[k+2]+1),start=indexBytes+rects[k+4],rows=await expand(bytes.subarray(start,start+rects[k+5]),size);
+  if(!(rows instanceof Uint8Array)||rows.length!==size)fail('expanded length');
+  const at=HEADER+frameCount*4+u*RECORD;v.setUint32(at+16,offset,true);v.setUint32(at+20,size,true);out.set(rows,indexBytes+offset);offset+=size;
+ }
+ return out;
+}

package/puppy-frame-predictive.mjs

@@ -68,7 +68,7 @@ export function encodePredictiveFrames(rvf1,{filter}={}){
 }
 
 // Exact PNG inverse filter of one row into `cur` (bpp 1, integer arithmetic).
-function unfilterRow(type,src,at,cur,prev,w){
+export function unfilterRow(type,src,at,cur,prev,w){
  switch(type){
   case 0:for(let x=0;x<w;x++)cur[x]=src[at+x];return;
   case 1:for(let x=0;x<w;x++)cur[x]=(src[at+x]+(x?cur[x-1]:0))&255;return;

package/puppy-frame-store.mjs

@@ -11,6 +11,12 @@ import {isPredictiveFrames,readPredictiveFrames} from './puppy-frame-predictive.
 const MAGIC=[0x52,0x56,0x46,0x31],HEADER=20,RECORD=24,MAX_SIDE=16384;
 const stores=new WeakSet();
 
+// Indexed local files obey the same borrowed two-frame contract as memory stores.
+export function registerFrameStore(store){
+ if(!store||typeof store.getFrame!=='function'||typeof store.stats!=='function'||!Number.isInteger(store.width)||!Number.isInteger(store.height)||!Number.isInteger(store.frameCount))throw Error('Invalid frame store');
+ stores.add(store);return store;
+}
+
 export function isPackedFrames(value){return stores.has(value);}
 export function isGrayFrameSource(value){return value instanceof Uint8Array||stores.has(value);}
 

package/retrieviewer.d.mts

@@ -1,7 +1,7 @@
 /** A headless pet: the host owns input, time and terminal rendering. */
 export type FetchReturnStyle = 'auto' | 'brake' | 'trot' | 'run-trot';
 export interface PetOptions {
-  /** Asset names are relative; return original file bytes (keep .gz files compressed). */
+  /** Relative names; return unchanged .rvz/.gz file bytes. Custom loaders use memory-backed art. */
   loadAsset?: (name: string) => Promise<ArrayBuffer | ArrayBufferView>;
   seed?: number;
   energy?: number;

package/retrieviewer.mjs

@@ -5,6 +5,7 @@ import {createSnappyTrickTimings} from './puppy-paper-trick-timing.mjs';
 import {createCompanionLife,FETCH_RETURN_STYLES} from './puppy-companion-life.mjs';
 import {paintCompanionObjects} from './puppy-companion-objects.mjs';
 import {readPackedFrames} from './puppy-frame-store.mjs';
+import {expandIndexedArchive} from './puppy-frame-indexed.mjs';
 import {BAKED_MOTION} from './puppy-motion-tables.generated.mjs';
 
 // Embeddable autonomous puppy. Importing or creating has no DOM, timer, stdin/stdout
@@ -19,12 +20,12 @@ export const ART_PROFILES=Object.freeze(['original','q5']);
 export const PET_ASSETS=Object.freeze({
  // Kept as a legacy identifier only; createPet/getPetAssetFiles no longer load it.
  animal:'locomotion-puppy.animal',
- stride:'puppy-stride-tweens-q5.bin.gz',strideInfo:'puppy-stride-meta.json',stableInfo:'puppy-stable-meta.json',
+ stride:'puppy-stride-tweens-q5.rvz',strideInfo:'puppy-stride-meta.json',stableInfo:'puppy-stable-meta.json',
  rear:'puppy-paper-rear-gallop',approach:'puppy-paper-approach',seat:'puppy-paper-seat',arrivalSeat:'puppy-paper-arrival-seat',
  behaviors:'puppy-paper-behaviors',actions:'puppy-paper-actions-v9',interactions:'puppy-companion-interactions-v3',comfort:'puppy-companion-comfort',
 });
 const BUNDLES=['rear','approach','seat','arrivalSeat','behaviors','actions','interactions','comfort'];
-const frameFile=(base,profile)=>base+(profile==='q5'?'-q5.bin.gz':'-compact.bin.gz');
+const frameFile=(base,profile)=>base+(profile==='q5'?'-q5.rvz':'-compact.bin.gz');
 /** Exact files a host/bundler must copy, including metadata. Never loads assets. */
 export function getPetAssetFiles(artProfile=DEFAULT_ART_PROFILE){
  if(!ART_PROFILES.includes(artProfile))throw RangeError('artProfile must be original or q5');
@@ -50,9 +51,9 @@ const bytesOf=(name,value)=>{
  if(ArrayBuffer.isView(value))return new Uint8Array(value.buffer,value.byteOffset,value.byteLength);
  throw TypeError(`loadAsset(${name}) must return an ArrayBuffer or typed bytes`);
 };
-async function gunzip(bytes){
+async function gunzip(bytes,size){
  // Native Node gzip avoids Blob/Response/stream copies of every large cache.
- if(typeof process!=='undefined'&&process.versions?.node){const {gunzipSync}=await import('node:zlib');return gunzipSync(bytes);}
+ if(typeof process!=='undefined'&&process.versions?.node){const {gunzipSync}=await import('node:zlib');return gunzipSync(bytes,size===undefined?undefined:{maxOutputLength:Math.max(1,size)});}
  if(typeof DecompressionStream!=='undefined')return new Uint8Array(await new Response(new Blob([bytes]).stream().pipeThrough(new DecompressionStream('gzip'))).arrayBuffer());
  throw Error('This browser needs DecompressionStream for pet assets');
 }
@@ -75,8 +76,8 @@ function heldFrameKey(state,report,{columns,rows,cellAspect=.5,camera,poseFps=24
   report.ball,report.treat]);
 }
 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.
+ // Default local Node hosts keep art on disk and reconstruct two frames per
+ // family. Custom/browser loaders retain the compatible memory-backed store.
  let codec;
  if(typeof process!=='undefined'&&process.versions?.node){
   const {deflateRawSync,inflateRawSync}=await import('node:zlib');
@@ -86,9 +87,18 @@ async function loadPetAssets(loadAsset,artProfile){
  }
  const load=async name=>bytesOf(name,await loadAsset(name));
  const json=async name=>JSON.parse(new TextDecoder().decode(await load(name)));
- const frames=async (name,options)=>readPackedFrames(await gunzip(await load(name)),{...options,codec});
- // One family at a time: never inflate all eight legacy-sized buffers together.
+ let openFrameFile;
+ if(artProfile==='q5'&&loadAsset===defaultLoadAsset&&new URL('.',import.meta.url).protocol==='file:'&&typeof process!=='undefined'&&process.versions?.node)({openFrameFile}=await import('./puppy-frame-file.mjs'));
+ const frames=async (name,options)=>{
+  if(name.endsWith('.rvz')){
+   if(openFrameFile)return openFrameFile(new URL(name,import.meta.url),options);
+   return readPackedFrames(await expandIndexedArchive(await load(name),gunzip),{...options,codec});
+  }
+  return readPackedFrames(await gunzip(await load(name)),{...options,codec});
+ };
+ // Read small indices locally; expand portable archives one family at a time.
  const data={assets:{}};
+ try{
  data.info=await json(PET_ASSETS.strideInfo);data.meta=await json(PET_ASSETS.stableInfo);
  data.cache=await frames(frameFile('puppy-stride-tweens',artProfile));
  for(const key of BUNDLES){
@@ -100,15 +110,17 @@ async function loadPetAssets(loadAsset,artProfile){
   data.assets[key]={info,bytes:await frames(frameFile(base,artProfile),options)};
  }
  return data;
+ }catch(error){disposeAssets(data);throw error;}
 }
+function disposeAssets(data){data?.cache?.dispose?.();for(const family of Object.values(data?.assets??{}))family.bytes?.dispose?.();}
 async function acquireAssets(loadAsset,artProfile){
  let entry;
  if(loadAsset===defaultLoadAsset){entry=sharedAssets.get(artProfile);if(!entry){entry={users:0,promise:loadPetAssets(loadAsset,artProfile)};sharedAssets.set(artProfile,entry);}}
  else entry={users:0,promise:loadPetAssets(loadAsset,artProfile)};
  entry.users++;
  let released=false;
- const release=()=>{if(released)return;released=true;const previous=entry;entry=null;if(--previous.users===0&&sharedAssets.get(artProfile)===previous)sharedAssets.delete(artProfile);};
- try{return{data:await entry.promise,release};}catch(error){release();throw error;}
+ const release=()=>{if(released)return;released=true;const previous=entry;entry=null;if(--previous.users===0){if(sharedAssets.get(artProfile)===previous)sharedAssets.delete(artProfile);disposeAssets(previous.data);}};
+ try{const data=await entry.promise;entry.data=data;return{data,release};}catch(error){release();throw error;}
 }
 
 export async function createPet({loadAsset=defaultLoadAsset,seed,energy,pawTransport=true,artProfile=DEFAULT_ART_PROFILE,returnStyle='auto'}={}){