@bitefoundry/retrieviewer 0.0.16 → 0.0.18

package/integrations/purrviewer/vendor/retrieviewer/puppy-frame-store.mjs

@@ -0,0 +1,114 @@
+// Lossless packed grayscale frames (RVF1). Exact duplicate frames are stored
+// once and each unique frame keeps only the bounding rectangle of its nonzero
+// pixels; every other pixel is exactly zero. No quantization or resampling.
+//
+// Little-endian layout:
+//  0 'RVF1'  4 u32 width  8 u32 height  12 u32 logicalFrameCount  16 u32 uniqueCount
+//  20 u32[logicalFrameCount] logical -> unique index
+//  then uniqueCount records of u32 x,y,w,h,offset,length (offset into pixel data)
+//  then the cropped row-major pixels of every unique frame, contiguous in order.
+import {isPredictiveFrames,readPredictiveFrames} from './puppy-frame-predictive.mjs';
+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);}
+
+const fnv=(bytes,start,end)=>{let h=0x811c9dc5;for(let i=start;i<end;i++)h=Math.imul(h^bytes[i],0x01000193);return h>>>0;};
+const sameBytes=(bytes,a,b,n)=>{for(let i=0;i<n;i++)if(bytes[a+i]!==bytes[b+i])return false;return true;};
+
+// Pack a legacy concatenated raster (frameCount full width*height frames).
+export function packFrames(raw,width,height,frameCount){
+ checkShape(width,height,frameCount);
+ const n=width*height;
+ if(!(raw instanceof Uint8Array)||raw.length!==n*frameCount)throw Error('Invalid gray frames: byte length');
+ const map=new Uint32Array(frameCount),firsts=[],rects=[],buckets=new Map();let total=0;
+ for(let f=0;f<frameCount;f++){
+  const start=f*n,h=fnv(raw,start,start+n),bucket=buckets.get(h);
+  const hit=bucket?.find(u=>sameBytes(raw,firsts[u]*n,start,n));
+  if(hit!==undefined){map[f]=hit;continue;}
+  let x0=width,y0=height,x1=-1,y1=-1;
+  for(let y=0;y<height;y++){const row=start+y*width;for(let x=0;x<width;x++)if(raw[row+x]){if(x<x0)x0=x;if(x>x1)x1=x;if(y<y0)y0=y;y1=y;}}
+  const rect=x1<0?{x:0,y:0,w:0,h:0}:{x:x0,y:y0,w:x1-x0+1,h:y1-y0+1};
+  rect.offset=total;rect.length=rect.w*rect.h;total+=rect.length;
+  map[f]=firsts.length;if(bucket)bucket.push(firsts.length);else buckets.set(h,[firsts.length]);firsts.push(f);rects.push(rect);
+ }
+ const unique=firsts.length,data=HEADER+4*frameCount+RECORD*unique,out=new Uint8Array(data+total),view=new DataView(out.buffer);
+ out.set(MAGIC,0);[width,height,frameCount,unique].forEach((v,i)=>view.setUint32(4+4*i,v,true));
+ for(let f=0;f<frameCount;f++)view.setUint32(HEADER+4*f,map[f],true);
+ rects.forEach((r,u)=>{
+  const at=HEADER+4*frameCount+RECORD*u;[r.x,r.y,r.w,r.h,r.offset,r.length].forEach((v,i)=>view.setUint32(at+4*i,v,true));
+  const start=firsts[u]*n;for(let y=0;y<r.h;y++){const src=start+(r.y+y)*width+r.x;out.set(raw.subarray(src,src+r.w),data+r.offset+y*r.w);}
+ });
+ return out;
+}
+
+function checkShape(width,height,frameCount){
+ if(!Number.isInteger(width)||!Number.isInteger(height)||width<1||height<1||width>MAX_SIDE||height>MAX_SIDE)throw Error('Invalid gray frames: dimensions');
+ if(!Number.isInteger(frameCount)||frameCount<1||frameCount>0xffffffff||!Number.isSafeInteger(width*height*frameCount))throw Error('Invalid gray frames: frame count');
+}
+
+// Parse and fully validate an RVF1 store. The returned store keeps `bytes`
+// 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,options){
+ if(!(bytes instanceof Uint8Array))throw Error('Invalid packed frames: bytes');
+ 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);
+ try{checkShape(width,height,frameCount);}catch{throw Error('Invalid packed frames: header');}
+ if(unique<1||unique>frameCount)throw Error('Invalid packed frames: unique count');
+ const data=HEADER+4*frameCount+RECORD*unique,n=width*height;
+ if(bytes.length<data)throw Error('Invalid packed frames: 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)throw Error('Invalid packed frames: map');map[f]=u;used[u]=1;}
+ if(used.includes(0))throw Error('Invalid packed frames: unreferenced frame');
+ const rects=new Uint32Array(unique*6);let total=0;
+ for(let u=0;u<unique;u++){
+  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)throw Error('Invalid packed frames: rectangle');
+  if(length!==w*h||offset!==total)throw Error('Invalid packed frames: offset');
+  rects.set([x,y,w,h,offset,length],u*6);total+=length;
+ }
+ if(bytes.length!==data+total)throw Error('Invalid packed frames: pixel length');
+ const pixels=bytes.subarray(data),slots=[{unique:-1,frame:null},{unique:-1,frame:null}];let decodes=0,hits=0;
+ const store=Object.freeze({
+  width,height,frameCount,uniqueCount:unique,byteLength:n*frameCount,
+  get residentBytes(){return bytes.byteLength+map.byteLength+rects.byteLength+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)throw Error('Invalid packed frames: frame index');
+   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;}
+   const slot=slots.pop();slots.unshift(slot);decodes++;
+   const frame=slot.frame??=new Uint8Array(n),k=u*6,x=rects[k],y=rects[k+1],w=rects[k+2],h=rects[k+3],offset=rects[k+4];
+   frame.fill(0);slot.unique=u;
+   for(let r=0;r<h;r++)frame.set(pixels.subarray(offset+r*w,offset+(r+1)*w),(y+r)*width+x);
+   return frame;
+  },
+ });
+ stores.add(store);return store;
+}
+
+// Uniform frame access over a legacy concatenated Uint8Array or a packed store.
+export function grayFrameReader(source,width,height,frameCount){
+ checkShape(width,height,frameCount);
+ const n=width*height,byteLength=n*frameCount;
+ const check=index=>{if(!Number.isInteger(index)||index<0||index>=frameCount)throw Error('Invalid gray frames: frame index');};
+ if(stores.has(source)){
+  if(source.width!==width||source.height!==height||source.frameCount!==frameCount)throw Error('Invalid gray frames: store shape');
+  return{width,height,frameCount,byteLength,getFrame(index){check(index);return source.getFrame(index);}};
+ }
+ if(!(source instanceof Uint8Array))throw Error('Invalid gray frames: source');
+ if(source.length!==byteLength)throw Error('Invalid gray frames: byte length');
+ return{width,height,frameCount,byteLength,getFrame(index){check(index);return source.subarray(index*n,(index+1)*n);}};
+}

package/integrations/windows-overlay/desktop.mjs

@@ -93,6 +93,8 @@ export async function desktopHelper(options={}){
  throw Error('Linux desktop needs system Python3.6+ (AlmaLinux8 platform-python is supported). No packages or system settings were installed.');
 }
 export async function startDesktop(options={}){
+ const pet=options.pet??'dog';if(!['dog','cat'].includes(pet))throw Error('Invalid desktop pet');
+ const engine=options.engine??'auto';if(!['auto','native','node'].includes(engine))throw Error('Invalid desktop engine');
  const watch=options.watch??'off';if(!['off','stackbite'].includes(watch))throw Error('Invalid desktop watch source');
  const brain=options.brain??'off';if(!['off','openrouter'].includes(brain))throw Error('Invalid desktop brain');
  if(brain==='openrouter'){
@@ -100,14 +102,20 @@ export async function startDesktop(options={}){
   const {createOpenRouterBrain}=await import('../openrouter/brain.mjs');createOpenRouterBrain().dispose();
  }
  if(watch==='stackbite'){const {stackBiteBinding}=await import('../stackbite/attention.mjs');stackBiteBinding();}
- const ink=options.ink??'cream';if(!['cream','gold','dark'].includes(ink))throw Error('Invalid desktop ink');
+ const ink=options.ink??(pet==='cat'?'gold':'cream');if(!['cream','gold','dark'].includes(ink))throw Error('Invalid desktop ink');
  const returnStyle=options.returnStyle??'auto';if(!['auto','brake','trot','run-trot'].includes(returnStyle))throw Error('Invalid return style');
  // Fail before creating any cache/session on unsupported desktops (e.g. Wayland).
  desktopPlatform(options);
- const status=await desktopStatus(options);if(status.running)return {...status,alreadyRunning:true,...status.returnStyle!==returnStyle?{requestedReturnStyle:returnStyle,restartRequired:true}:{},...(status.watch?.source??'off')!==watch?{requestedWatch:watch,restartRequired:true}:{},...(status.brain?.provider??'off')!==brain?{requestedBrain:brain,restartRequired:true}:{}};
+ const native=process.platform==='win32'&&process.arch==='x64'&&engine!=='node'&&watch==='off'&&brain==='off';
+ if(engine==='native'&&!native)throw Error('Native mode requires Windows x64 with watch/brain off; use --engine node for compatibility features');
+ const status=await desktopStatus(options);if(status.running){
+  if(native&&status.engine==='quickjs-native'&&status.pet!==pet){const {switchNativePet}=await import('../native-windows/desktop.mjs');return switchNativePet(options,await readSession(options),pet);}
+  return {...status,alreadyRunning:true,...(status.pet??'dog')!==pet?{requestedPet:pet,restartRequired:true}:{},...status.returnStyle!==returnStyle?{requestedReturnStyle:returnStyle,restartRequired:true}:{},...(status.watch?.source??'off')!==watch?{requestedWatch:watch,restartRequired:true}:{},...(status.brain?.provider??'off')!==brain?{requestedBrain:brain,restartRequired:true}:{}};
+ }
  if(status.stale)await stopDesktop(options);
+ if(native){const {startNativeDesktop}=await import('../native-windows/desktop.mjs');return startNativeDesktop(options);}
  const helper=await desktopHelper(options);
- const workerEnv={...process.env,RETRIEVIEWER_HOME:getConfigPaths(options).root,RETRIEVIEWER_INK:ink,RETRIEVIEWER_RETURN_STYLE:returnStyle,RETRIEVIEWER_WATCH:watch,RETRIEVIEWER_BRAIN:brain};
+ const workerEnv={...process.env,RETRIEVIEWER_HOME:getConfigPaths(options).root,RETRIEVIEWER_PET:pet,RETRIEVIEWER_INK:ink,RETRIEVIEWER_RETURN_STYLE:returnStyle,RETRIEVIEWER_WATCH:watch,RETRIEVIEWER_BRAIN:brain};
  if(brain==='off')delete workerEnv.OPENROUTER_API_KEY;
  return new Promise((resolve,reject)=>{
   const child=spawn(process.execPath,[fileURLToPath(new URL('./worker.mjs',import.meta.url)),'--helper-spec',JSON.stringify(helper)],{detached:true,windowsHide:true,stdio:['ignore','ignore','ignore','ipc'],env:workerEnv});

package/integrations/windows-overlay/worker.mjs

@@ -14,6 +14,7 @@ let attention=null,brain=null,attentionLabel=null;
 const returnStyle=process.env.RETRIEVIEWER_RETURN_STYLE??'auto';
 const watchSource=process.env.RETRIEVIEWER_WATCH??'off';
 const brainSource=process.env.RETRIEVIEWER_BRAIN??'off';
+const petKind=process.env.RETRIEVIEWER_PET??'dog';
 let nativeStderr='';
 const sendParent=message=>{if(process.connected)try{process.send(message,error=>{if(error&&!detached)stop();});}catch{if(!detached)stop();}};
 const starting=()=>{if(stopping||(!process.connected&&!detached))throw Error('Desktop launcher closed during startup');};
@@ -44,7 +45,7 @@ try{
    body+=bytes.toString('utf8');if(body.length>2048)return socket.destroy();if(!body.includes('\n'))return;
    let command;try{command=JSON.parse(body.split('\n')[0]);}catch{return socket.destroy();}
    if(command.token!==session.token||!['status','stop'].includes(command.command))return socket.destroy();
-   socket.end(JSON.stringify(command.command==='stop'?{stopped:true}:{running:true,reachable:true,selected,visible,pickerVisible,frames,paintedFrames,lastInteraction,returnStyle,attentionLabel,watch:{source:watchSource,...attention?.status??{state:'off',pendingCount:0}},brain:brain?.status??{provider:'off',state:'off'},pid:process.pid,painterPid:helper?.pid,rssBytes:process.memoryUsage().rss})+'\n');
+   socket.end(JSON.stringify(command.command==='stop'?{stopped:true}:{running:true,reachable:true,pet:petKind,engine:"node-compat",selected,visible,pickerVisible,frames,paintedFrames,lastInteraction,returnStyle,attentionLabel,watch:{source:watchSource,...attention?.status??{state:'off',pendingCount:0}},brain:brain?.status??{provider:'off',state:'off'},pid:process.pid,painterPid:helper?.pid,rssBytes:process.memoryUsage().rss})+'\n');
    if(command.command==='stop')stop();
   });
  });
@@ -72,7 +73,13 @@ try{
    else if(m.type==='quit')stop();
   }catch(error){write({type:'error',message:error.message});stop();}
  });
- starting();const {createPet}=await import('../../retrieviewer.mjs');starting();const pet=await createPet({returnStyle});
+ starting();let pet;
+ if(petKind==='cat'){
+  const {createCat}=await import('../purrviewer/src/purrviewer.mjs');starting();const cat=await createCat();
+  pet={step:dt=>cat.step(dt),frame:o=>cat.frame(o),dispose:()=>cat.dispose(),
+   interact:kind=>cat.interact(({ball:'toy',tug:'company'})[kind]??kind),
+   notify:()=>cat.interact('greet'),clearNotice:()=>{}};
+ }else {const {createPet}=await import('../../retrieviewer.mjs');starting();pet=await createPet({returnStyle});}
  if(stopping)pet.dispose();else{
   pump=createFramePump({pet,send:write});if(pendingViewport)pump.viewport(pendingViewport);
   if(!['off','stackbite'].includes(watchSource))throw Error('Invalid desktop watch source');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitefoundry/retrieviewer",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "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/",
@@ -57,7 +57,8 @@
     },
     "./tui": "./integrations/opencode/tui.tsx",
     "./opencode/tui": "./integrations/opencode/tui.tsx",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./cat": "./integrations/purrviewer/src/purrviewer.mjs"
   },
   "files": [
     "LICENSE",
@@ -142,26 +143,61 @@
     "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",
+    "integrations/native-windows/desktop.mjs",
+    "integrations/native-windows/runtime.mjs",
+    "integrations/native-windows/runtime.bundle.mjs",
+    "integrations/native-windows/manifest.json",
+    "integrations/native-windows/bin/win32-x64/retrieviewer-native.exe",
+    "integrations/native-windows/host.cpp",
+    "integrations/native-windows/native-window.hpp",
+    "integrations/native-windows/native-control.hpp",
+    "integrations/native-windows/CMakeLists.txt",
+    "integrations/native-windows/sources.json",
+    "integrations/native-windows/THIRD-PARTY-LICENSES.txt",
+    "NATIVE-RUNTIME.md",
+    "integrations/purrviewer/ART.md",
+    "integrations/purrviewer/ASSETS-LICENSE.md",
+    "integrations/purrviewer/LICENSE",
+    "integrations/purrviewer/art/ginger.bin.gz",
+    "integrations/purrviewer/art/ginger.json",
+    "integrations/purrviewer/art/ginger.rvz",
+    "integrations/purrviewer/src/contact.mjs",
+    "integrations/purrviewer/src/habitat.mjs",
+    "integrations/purrviewer/src/life.mjs",
+    "integrations/purrviewer/src/purrviewer-core.mjs",
+    "integrations/purrviewer/src/purrviewer.mjs",
+    "integrations/purrviewer/src/walk-cycle.mjs",
+    "integrations/purrviewer/src/world.mjs",
+    "integrations/purrviewer/vendor/retrieviewer/braille.mjs",
+    "integrations/purrviewer/vendor/retrieviewer/LICENSE-CODE",
+    "integrations/purrviewer/vendor/retrieviewer/puppy-frame-predictive.mjs",
+    "integrations/purrviewer/vendor/retrieviewer/puppy-frame-store.mjs",
+    "integrations/purrviewer/vendor/retrieviewer/puppy-frame-file.mjs",
+    "integrations/purrviewer/vendor/retrieviewer/puppy-frame-indexed.mjs",
+    "integrations/native-windows/application.manifest"
   ],
   "scripts": {
     "bake:motion": "node tools/bake-pet-motion.mjs",
@@ -173,7 +209,11 @@
     "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",
+    "build:native": "node tools/build-native-windows.mjs",
+    "check:native-pixels": "node tools/check-native-pixels.mjs"
   },
   "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-clean.mjs

@@ -31,7 +31,7 @@ export function cleanGroundOffset(state,meta){
  const a=v[Math.max(30,i-1)],b=v[i],c=v[i+1],d=v[Math.min(41,i+2)];
  return .5*(2*b+(-a+c)*p+(2*a-5*b+4*c-d)*p*p+(-a+3*b-3*c+d)*p*p*p);
 }
-export function createCachedTween(cache,info){
+export function createCachedTween(cache,info,kernel=null){
  if(!isGrayFrameSource(cache)||cache.byteLength!==CLEAN_BYTES||info.pairs!==47||info.samples!==17||info.width!==320||info.height!==320||info.channels!==1||info.bytes!==CLEAN_BYTES)throw Error('Invalid baked tween cache');
  const frames=grayFrameReader(cache,320,320,47*17),output=new Uint8ClampedArray(320*320*4),stride=320*320;
  for(let i=3;i<output.length;i+=4)output[i]=255;
@@ -39,7 +39,7 @@ export function createCachedTween(cache,info){
   if(!Number.isInteger(state.pair)||state.pair<0||state.pair>=47||!Number.isFinite(state.blend))throw Error('Invalid baked tween state');
   const phase=Math.max(0,Math.min(1,state.blend))*16,index=Math.min(15,Math.floor(phase)),alpha=phase-index;
   const a=frames.getFrame(state.pair*17+index),b=frames.getFrame(state.pair*17+index+1);
-  for(let i=0,j=0;i<stride;i++,j+=4){const value=a[i]*(1-alpha)+b[i]*alpha;output[j]=output[j+1]=output[j+2]=value;}
+  if(kernel?.blendGray)kernel.blendGray(output,a,b,alpha);else for(let i=0,j=0;i<stride;i++,j+=4){const value=a[i]*(1-alpha)+b[i]*alpha;output[j]=output[j+1]=output[j+2]=value;}
   return output;
  };
 }

package/puppy-companion-sprites.mjs

@@ -1,7 +1,7 @@
 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,output){
+export function createCompanionSpriteSampler(bytes,info,output,kernel=null){
  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');
@@ -11,6 +11,6 @@ export function createCompanionSpriteSampler(bytes,info,output){
  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);
-  for(let i=0,j=0;i<n;i++,j+=4)rgba[j]=rgba[j+1]=rgba[j+2]=frame[i];return rgba;
+  if(kernel?.copyGray)kernel.copyGray(rgba,frame);else for(let i=0,j=0;i<n;i++,j+=4)rgba[j]=rgba[j+1]=rgba[j+2]=frame[i];return rgba;
  };
 }

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,kernel=null}={}){
+ 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);
+   if(kernel?.decodeRows)kernel.decodeRows(frame,rows,x,y,w,h,width);else 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/puppy-paper-actions.mjs

@@ -38,7 +38,7 @@ export function paperActionPose(name,progress,info,compiledClips){
  if(!Number.isFinite(blend))throw Error('Invalid paper action: blend');
  return{pair:list[index],blend};
 }
-export function createPaperActionSampler(bytes,info,output,compiledClips){
+export function createPaperActionSampler(bytes,info,output,compiledClips,kernel=null){
  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);
@@ -47,5 +47,5 @@ export function createPaperActionSampler(bytes,info,output,compiledClips){
  for(let i=3;i<out.length;i+=4)out[i]=255;
  return state=>{const p=paperActionPose(state.actionName,state.actionProgress,info,compiledClips),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;};
+  const frame=frames.getFrame(p.pair*9+sample);if(kernel?.copyGray)kernel.copyGray(out,frame);else 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,output){const sample=createRearSampler(bytes,info,output);return state=>{const p=paperBehaviorPose(state,info);return sample(p.pair,p.blend);};}
+export function createPaperBehaviorSampler(bytes,info,output,kernel=null){const sample=createRearSampler(bytes,info,output,kernel);return state=>{const p=paperBehaviorPose(state,info);return sample(p.pair,p.blend);};}

package/puppy-paper-contact.mjs

@@ -101,7 +101,7 @@ 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,output){
+export function createRearSampler(bytes,info,output,kernel=null){
  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=output??new Uint8ClampedArray(320*320*4);
  if(!(out instanceof Uint8ClampedArray)||out.length!==320*320*4)throw Error('Invalid rear output');
@@ -109,7 +109,7 @@ export function createRearSampler(bytes,info,output){
  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));
-  for(let j=0,i=0;i<320*320;i++,j+=4)out[j]=out[j+1]=out[j+2]=frame[i];
+  if(kernel?.copyGray)kernel.copyGray(out,frame);else for(let j=0,i=0;i<320*320;i++,j+=4)out[j]=out[j+1]=out[j+2]=frame[i];
   return out;
  };
 }

package/puppy-paper-seat.mjs

@@ -1,6 +1,6 @@
 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,output){
+export function createPaperSeatSampler(bytes,info,output,kernel=null){
  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=output??new Uint8ClampedArray(stride*4);
@@ -9,7 +9,7 @@ export function createPaperSeatSampler(bytes,info,output){
  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);
-  for(let i=0,j=0;i<stride;i++,j+=4)out[j]=out[j+1]=out[j+2]=frame[i];
+  if(kernel?.copyGray)kernel.copyGray(out,frame);else for(let i=0,j=0;i<stride;i++,j+=4)out[j]=out[j+1]=out[j+2]=frame[i];
   return out;
  };
 }