@bitefoundry/retrieviewer 0.0.16 → 0.0.18

package/integrations/purrviewer/src/world.mjs

@@ -0,0 +1,216 @@
+// Scalar travel and camera mathematics adapted from MIT Retrieviewer
+// puppy-paper-world.mjs; copyright (c) 2026 Retrieviewer contributors.
+// License text is retained in vendor/retrieviewer/LICENSE-CODE.
+// Cat values below are design choices, not measured juvenile gait data.
+import {WALK_STRIDE} from './walk-cycle.mjs';
+const gait = (stride, frequency) => Object.freeze({stride, frequency, speed: stride * frequency});
+export const CAT_GAITS = Object.freeze({
+  walk: gait(WALK_STRIDE, .27/WALK_STRIDE),
+  trot: gait(.62, 2),
+  creep: gait(WALK_STRIDE, .13/WALK_STRIDE),
+});
+
+const GRAVITY = 9.81;
+const DECELERATION = 1.8;
+const ACCELERATION = Object.freeze({walk: .65, trot: 2, creep: .3});
+const coordinate = n => Number.isFinite(n) && Math.abs(n) <= 1e6;
+function point(x, z) {
+  if (!coordinate(x) || !coordinate(z)) throw new RangeError('Invalid cat target');
+}
+function options(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('Invalid cat options');
+}
+
+// Rest-to-rest triangle/trapezoid: both the root and phase consume this integral.
+function travel(length, speed, acceleration) {
+  const peak = Math.min(speed, Math.sqrt(2 * length / (1 / acceleration + 1 / DECELERATION)));
+  const ta = peak / acceleration, td = peak / DECELERATION;
+  const da = peak * ta / 2, dd = peak * td / 2;
+  const tc = Math.max(0, length - da - dd) / peak;
+  const duration = ta + tc + td;
+  return {duration, at(t) {
+    if (t >= duration) return {distance: length, speed: 0};
+    if (t < ta) return {distance: acceleration * t * t / 2, speed: acceleration * t};
+    if (t < ta + tc) return {distance: da + peak * (t - ta), speed: peak};
+    const remaining = duration - t;
+    return {distance: length - DECELERATION * remaining * remaining / 2, speed: DECELERATION * remaining};
+  }};
+}
+
+export function createCatMotion(config = {}) {
+  options(config);
+  let {x = 0, z = 0} = config;
+  point(x, z);
+  let y = 0, speed = 0, distance = 0, phase = 0, heading = 0, currentGait = 'walk';
+  let active = null, pending = null, supportY=0, beltSpeed=0, beltDistance=0, wheelRadius=.6,wheelPhase=0;
+
+  function advance(ds) {
+    distance += ds;
+    phase += ds / CAT_GAITS[currentGait].stride;
+  }
+  function launch(command) {
+    if(command.kind==='wheel'){
+      wheelRadius=command.radius;wheelPhase=0;
+      active={...command,elapsed:0,covered:0};return;
+    }
+    const dx = command.x - x, dz = command.z - z, length = Math.hypot(dx, dz);
+    if (command.kind === 'go') currentGait = command.gait;
+    if (length > 0) heading = Math.atan2(dx, dz);
+    if (command.kind === 'go' && length === 0) return;
+    active = {
+      kind: command.kind, x, z, targetX: command.x, targetZ: command.z,
+      ux: length ? dx / length : 0, uz: length ? dz / length : 0,
+      length, elapsed: 0, covered: 0,
+      ...(command.kind === 'pounce'
+        ? (()=>{const apex=Math.max(y,command.landingY)+command.height;
+            const vy=Math.sqrt(2*GRAVITY*(apex-y));
+            return {startY:y,targetY:command.landingY,vy,
+              duration:(vy+Math.sqrt(2*GRAVITY*(apex-command.landingY)))/GRAVITY};})()
+        : {plan: travel(length, CAT_GAITS[currentGait].speed, ACCELERATION[currentGait])}),
+    };
+    if (command.kind === 'pounce') speed = length / active.duration;
+  }
+  function brake() {
+    if (!active || active.kind === 'pounce' || ['brake','wheel-brake'].includes(active.kind)) return;
+    if(active.kind==='wheel'){
+      const stride=active.stride,minDistance=beltSpeed*beltSpeed/2.4;
+      // At useful speed, finish on the supported cycle boundary; never freeze
+      // the gathered airborne drawing when an interaction brakes the wheel.
+      const distance=beltSpeed>.15?(Math.ceil(wheelPhase+minDistance/stride)-wheelPhase)*stride:minDistance;
+      const deceleration=distance>0?beltSpeed*beltSpeed/(2*distance):1.2;
+      active=beltSpeed>0?{kind:'wheel-brake',initialSpeed:beltSpeed,deceleration,
+        duration:beltSpeed/deceleration,elapsed:0,covered:0,stride}:null;return;
+    }
+    active = speed > 0 ? {
+      kind: 'brake', x, z, ux: active.ux, uz: active.uz,
+      initialSpeed: speed, duration: speed / DECELERATION, elapsed: 0, covered: 0,
+    } : null;
+  }
+  function request(command) {
+    if (active) {
+      pending = command;
+      brake();
+    }
+    if (!active) {
+      pending = null;
+      launch(command);
+    }
+  }
+  return {
+    go(targetX, targetZ, config = {}) {
+      options(config);
+      const {gait = 'walk'} = config;
+      point(targetX, targetZ);
+      if (typeof gait !== 'string' || !Object.hasOwn(CAT_GAITS, gait)) throw new RangeError('Invalid cat gait');
+      request({kind: 'go', x: targetX, z: targetZ, gait});
+    },
+    stop() {
+      pending = null;
+      brake(); // A flight must finish its one physical trajectory.
+    },
+    pounce(targetX, targetZ, config = {}) {
+      options(config);
+      const {height = .18,landingY=0} = config;
+      point(targetX, targetZ);
+      if (!Number.isFinite(height) || height <= 0 || height > 1) throw new RangeError('Invalid pounce height');
+      if(!Number.isFinite(landingY)||landingY<0||landingY>1)throw RangeError('Invalid landing support');
+      request({kind: 'pounce', x: targetX, z: targetZ, height,landingY});
+    },
+    wheel(config={}){
+      options(config);const {duration=10,speed=.65,radius=.6,stride=.32}=config;
+      if(![duration,speed,radius,stride].every(Number.isFinite)||duration<2||duration>30||speed<=0||speed>2||radius<.3||radius>1||stride<.05||stride>1)
+        throw RangeError('Invalid wheel motion');
+      request({kind:'wheel',duration,peakSpeed:speed,radius,stride});
+    },
+    step(dt) {
+      if (!Number.isFinite(dt) || dt < 0 || dt > .1) throw new RangeError('Invalid cat step');
+      let remaining = dt;
+      while (active && remaining > 0) {
+        const a = active, duration = a.plan?.duration ?? a.duration;
+        const used = Math.min(remaining, duration - a.elapsed);
+        a.elapsed = Math.min(duration, a.elapsed + used);
+        if(duration-a.elapsed<1e-10)a.elapsed=duration;
+        remaining = Math.max(0, remaining - used);
+        const done = a.elapsed >= duration;
+        let covered;
+        if(['wheel','wheel-brake'].includes(a.kind)){
+          if(a.kind==='wheel'){
+            beltSpeed=a.peakSpeed*Math.sin(Math.PI*a.elapsed/duration)**2;
+            covered=a.peakSpeed*(a.elapsed/2-duration*Math.sin(2*Math.PI*a.elapsed/duration)/(4*Math.PI));
+          }else{
+            beltSpeed=Math.max(0,a.initialSpeed-a.deceleration*a.elapsed);
+            covered=a.initialSpeed*a.elapsed-a.deceleration*a.elapsed*a.elapsed/2;
+          }
+          const ds=covered-a.covered;beltDistance+=ds;wheelPhase+=ds/a.stride;a.covered=covered;
+          if(done){beltSpeed=0;if(Math.abs(wheelPhase-Math.round(wheelPhase))<1e-9)wheelPhase=Math.round(wheelPhase);
+            active=null;if(pending){const command=pending;pending=null;launch(command);}}
+          continue;
+        }else if (a.kind === 'pounce') {
+          covered = a.length * (a.elapsed / duration);
+          speed = a.length / duration;
+          y = a.startY+a.vy*a.elapsed-GRAVITY*a.elapsed*a.elapsed/2;
+        } else if (a.kind === 'brake') {
+          covered = a.initialSpeed * a.elapsed - DECELERATION * a.elapsed * a.elapsed / 2;
+          speed = Math.max(0, a.initialSpeed - DECELERATION * a.elapsed);
+        } else {
+          const state = a.plan.at(a.elapsed);
+          covered = state.distance;
+          speed = state.speed;
+        }
+        x = a.x + a.ux * covered;
+        z = a.z + a.uz * covered;
+        advance(covered - a.covered);
+        a.covered = covered;
+        if (done) {
+          // Exact endpoint is used only when the trajectory itself has ended.
+          if (a.kind !== 'brake') { x = a.targetX; z = a.targetZ; }
+          speed = 0;
+          if(a.kind==='pounce')supportY=a.targetY;
+          y = supportY;
+          active = null;
+          if (pending) {
+            const command = pending;
+            pending = null;
+            launch(command);
+          }
+        }
+      }
+    },
+    sample() {
+      return {x, y, z, speed, distance, phase, gait: currentGait, moving: active !== null, heading,
+        supportY,airborne:active?.kind==='pounce',flightProgress:active?.kind==='pounce'?active.elapsed/active.duration:0,
+        exercising:['wheel','wheel-brake'].includes(active?.kind),beltSpeed,beltDistance,wheelPhase,wheelAngle:beltDistance/wheelRadius};
+    },
+  };
+}
+
+// Fixed assumed 32-inch 16:9 display at .70m; fit it inside any pixel rectangle.
+const diagonal = .0254 * 32;
+const screenWidth = diagonal * 16 / Math.hypot(16, 9);
+const screenHeight = diagonal * 9 / Math.hypot(16, 9);
+const pitch = 9 * Math.PI / 180, c = Math.cos(pitch), s = Math.sin(pitch);
+export function projectCat(x, y, z, config = {}) {
+  options(config);
+  const {width, height, canvasMeters = .60} = config;
+  if (![x, y, z, width, height, canvasMeters].every(Number.isFinite)
+      || width <= 0 || height <= 0 || canvasMeters <= 0) throw new RangeError('Invalid cat projection');
+  const cameraY = c * (y - .45) - s * (z - 1.65);
+  const depth = -s * (y - .45) - c * (z - 1.65);
+  if (!Number.isFinite(depth) || depth <= 0) throw new RangeError('Cat point behind camera');
+  const focal = .70 * Math.min(width / screenWidth, height / screenHeight);
+  const result = {x: width / 2 + focal * x / depth, y: height / 2 - focal * cameraY / depth,
+    size: focal * canvasMeters / depth, depth};
+  if (!Object.values(result).every(Number.isFinite)) throw new RangeError('Invalid cat projection range');
+  return result;
+}
+
+// Invert the same fixed pinhole camera at the ground plane (world y=0).
+export function unprojectCatGround(u,v,{width,height}={}){
+  if(![u,v,width,height].every(Number.isFinite)||width<=0||height<=0)throw RangeError('Invalid cat ground pixel');
+  const focal=.70*Math.min(width/screenWidth,height/screenHeight),q=(height/2-v)/focal;
+  const denominator=s-q*c;
+  if(Math.abs(denominator)<1e-10)throw RangeError('Cat ground ray at horizon');
+  const dz=-.45*(c+q*s)/denominator,depth=s*.45-c*dz;
+  if(depth<=0||!Number.isFinite(depth))throw RangeError('Cat ground behind camera');
+  return {x:(u-width/2)*depth/focal,z:dz+1.65};
+}

package/integrations/purrviewer/vendor/retrieviewer/LICENSE-CODE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Retrieviewer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/integrations/purrviewer/vendor/retrieviewer/braille.mjs

@@ -0,0 +1,73 @@
+// Unicode 2x4 cells, the same dot numbering used by AuraDeck's Braille canvas.
+export const BRAILLE_BITS=[[1,8],[2,16],[4,32],[64,128]];
+const BAYER=[[0,8,2,10],[12,4,14,6],[3,11,1,9],[15,7,13,5]];
+const clamp=v=>Math.max(0,Math.min(1,v));
+const GLYPHS=Array.from({length:256},(_,i)=>String.fromCharCode(0x2800+i));
+let grayTable=null,grayBrightness=0,grayContrast=0;
+function stableBraille(rgba,width,height,brightness,contrast){
+  if(grayBrightness!==brightness||grayContrast!==contrast){
+    grayTable=Float32Array.from({length:256},(_,v)=>{
+      const luma=(.2126*v+.7152*v+.0722*v)/255;
+      return luma===0?0:clamp((Math.pow(luma,.9)*brightness-.5)*contrast+.5);
+    });
+    grayBrightness=brightness;grayContrast=contrast;
+  }
+  const table=grayTable,bytePixels=rgba instanceof Uint8Array||rgba instanceof Uint8ClampedArray,columns=Math.ceil(width/2),rows=Math.ceil(height/4),masks=new Uint8Array(columns*rows);
+  let dots=0;
+  // Stable dithering has no error diffusion: background pixels cannot affect a
+  // neighbor. Skip them before luma/hash work, and write straight to cell masks.
+  // Float32 rounding matches the original intermediate values array exactly.
+  for(let y=0;y<height;y++)for(let x=0,p=y*width*4;x<width;x++,p+=4){
+    const r=rgba[p],g=rgba[p+1],b=rgba[p+2],a=rgba[p+3];
+    if(a===0||(r===0&&g===0&&b===0))continue;
+    let value;
+    if(bytePixels&&a===255&&r===g&&g===b)value=table[r];
+    else{
+      const luma=(.2126*r+.7152*g+.0722*b)/255*(a/255);
+      value=Math.fround(luma===0?0:clamp((Math.pow(luma,.9)*brightness-.5)*contrast+.5));
+    }
+    if(value<=0)continue;
+    let n=Math.imul(x+1,0x1f123bb5)^Math.imul(y+1,0x5f356495);
+    n=Math.imul(n^(n>>>16),0x45d9f3b);n=Math.imul(n^(n>>>16),0x45d9f3b);n=(n^(n>>>16))>>>0;
+    if(value>(n+.5)/4294967296){masks[(y>>2)*columns+(x>>1)]|=BRAILLE_BITS[y&3][x&1];dots++;}
+  }
+  // Reuse one row of glyph references. Per-cell string concatenation retained
+  // thousands of rope nodes until the final join on large desktop grids.
+  const lines=new Array(rows),cells=new Array(columns);
+  for(let y=0;y<rows;y++){for(let x=0;x<columns;x++)cells[x]=GLYPHS[masks[y*columns+x]];lines[y]=cells.join('');}
+  return{text:lines.join('\n'),columns,rows,dots};
+}
+export function rgbaToBraille(rgba,width,height,{brightness=1,contrast=1,method='floyd'}={}){
+  if(!Number.isInteger(width)||!Number.isInteger(height)||width<1||height<1||width*height>1_000_000||rgba.length!==width*height*4)throw Error('Invalid RGBA image');
+  if(!Number.isFinite(brightness)||brightness<=0||brightness>4||!Number.isFinite(contrast)||contrast<=0||contrast>4||!['floyd','bayer','stable'].includes(method))throw Error('Invalid dithering options');
+  if(method==='stable')return stableBraille(rgba,width,height,brightness,contrast);
+  const values=new Float32Array(width*height),bits=new Uint8Array(width*height);
+  for(let i=0;i<values.length;i++){
+    const p=i*4,luma=(.2126*rgba[p]+.7152*rgba[p+1]+.0722*rgba[p+2])/255*(rgba[p+3]/255);
+    values[i]=luma===0?0:clamp((Math.pow(luma,.9)*brightness-.5)*contrast+.5);
+  }
+  if(method==='bayer'){
+    for(let y=0;y<height;y++)for(let x=0;x<width;x++)bits[y*width+x]=values[y*width+x]>(BAYER[y%4][x%4]+.5)/16?1:0;
+  }else{
+    const add=(x,y,error,weight)=>{if(x>=0&&x<width&&y<height)values[y*width+x]+=error*weight/16;};
+    for(let y=0;y<height;y++){
+      const direction=y%2?-1:1;
+      for(let k=0;k<width;k++){
+        const x=direction===1?k:width-1-k,i=y*width+x,old=values[i],value=old>=.5?1:0,error=old-value;
+        bits[i]=value;add(x+direction,y,error,7);add(x-direction,y+1,error,3);add(x,y+1,error,5);add(x+direction,y+1,error,1);
+      }
+    }
+  }
+  const columns=Math.ceil(width/2),rows=Math.ceil(height/4),lines=[];
+  for(let cy=0;cy<rows;cy++){
+    let line='';
+    for(let cx=0;cx<columns;cx++){
+      let mask=0;for(let dy=0;dy<4;dy++)for(let dx=0;dx<2;dx++){
+        const x=cx*2+dx,y=cy*4+dy;if(x<width&&y<height&&bits[y*width+x])mask|=BRAILLE_BITS[dy][dx];
+      }
+      line+=String.fromCodePoint(0x2800+mask);
+    }
+    lines.push(line);
+  }
+  return {text:lines.join('\n'),columns,rows,dots:bits.reduce((a,b)=>a+b,0)};
+}

package/integrations/purrviewer/vendor/retrieviewer/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/integrations/purrviewer/vendor/retrieviewer/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/integrations/purrviewer/vendor/retrieviewer/puppy-frame-predictive.mjs

@@ -0,0 +1,170 @@
+// 32-level predictive grayscale frames (RVQ5), a lossy VISUAL COMPARISON codec
+// built from a lossless RVF1 store. Every pixel v becomes q=round(v*31/255) and
+// is shown as round(q*255/31) (max error 4; 0 and 255 stay exact). The RVF1
+// dedup map and crop rectangles are kept unchanged. Each cropped row stores a
+// PNG filter type (0 None, 1 Sub, 2 Up, 3 Average, 4 Paeth; 1 byte per pixel)
+// followed by w residual bytes (q - prediction) mod 256.
+//
+// Little-endian layout:
+//  0 'RVQ5'  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 (length = h*(w+1))
+//  then the filtered rows of every unique crop, contiguous in order.
+// 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);
+export const expand5=q=>Math.round(q*255/31);
+const QUANT=Uint8Array.from({length:256},(_,v)=>quantize5(v)),DISPLAY=Uint8Array.from({length:32},(_,q)=>expand5(q));
+export const quantizedGray=Uint8Array.from({length:256},(_,v)=>DISPLAY[QUANT[v]]);
+export const isPredictiveFrames=bytes=>bytes instanceof Uint8Array&&bytes.length>=4&&MAGIC.every((v,i)=>bytes[i]===v);
+
+const fail=what=>{throw Error(`Invalid predictive frames: ${what}`);};
+const paeth=(a,b,c)=>{const p=a+b-c,pa=Math.abs(p-a),pb=Math.abs(p-b),pc=Math.abs(p-c);return pa<=pb&&pa<=pc?a:pb<=pc?b:c;};
+export function predict(type,a,b,c){
+ switch(type){case 0:return 0;case 1:return a;case 2:return b;case 3:return (a+b)>>1;case 4:return paeth(a,b,c);}
+ return fail('filter');
+}
+
+function checkShape(width,height,frameCount){
+ if(!Number.isInteger(width)||!Number.isInteger(height)||width<1||height<1||width>MAX_SIDE||height>MAX_SIDE)fail('header');
+ if(!Number.isInteger(frameCount)||frameCount<1||frameCount>0xffffffff||!Number.isSafeInteger(width*height*frameCount))fail('header');
+}
+
+// Encode an RVF1 byte store (see puppy-frame-store.mjs). Rows pick the filter
+// with the smallest sum of |signed residual|, lowest type on ties; `filter`
+// forces one type for every row (tests). Deterministic.
+export function encodePredictiveFrames(rvf1,{filter}={}){
+ if(!(rvf1 instanceof Uint8Array)||rvf1.length<HEADER||RVF1.some((v,i)=>rvf1[i]!==v))throw Error('Invalid packed frames: magic');
+ if(filter!==undefined&&!(Number.isInteger(filter)&&filter>=0&&filter<=4))fail('filter');
+ const view=new DataView(rvf1.buffer,rvf1.byteOffset,rvf1.byteLength),u32=at=>view.getUint32(at,true);
+ const width=u32(4),height=u32(8),frameCount=u32(12),unique=u32(16),records=HEADER+4*frameCount,data=records+RECORD*unique;
+ checkShape(width,height,frameCount);
+ if(rvf1.length<data)throw Error('Invalid packed frames: truncated');
+ let total=0;
+ for(let u=0;u<unique;u++)total+=u32(records+RECORD*u+12)*(u32(records+RECORD*u+8)+1);
+ const out=new Uint8Array(data+total),ov=new DataView(out.buffer);
+ out.set(rvf1.subarray(0,data));out.set(MAGIC,0);
+ const rows=Array.from({length:5},()=>new Uint8Array(width)),cur=new Uint8Array(width),prev=new Uint8Array(width);let at=data,offset=0;
+ for(let u=0;u<unique;u++){
+  const rec=records+RECORD*u,w=u32(rec+8),h=u32(rec+12),src=data+u32(rec+16);
+  if(u32(rec+20)!==w*h||src+w*h>rvf1.length)throw Error('Invalid packed frames: offset');
+  ov.setUint32(rec+16,offset,true);ov.setUint32(rec+20,h*(w+1),true);offset+=h*(w+1);
+  prev.fill(0);
+  for(let y=0;y<h;y++){
+   for(let x=0;x<w;x++)cur[x]=QUANT[rvf1[src+y*w+x]];
+   let best=filter??-1,bestCost=Infinity;
+   for(let t=filter??0;t<=(filter??4);t++){
+    const r=rows[t];let cost=0;
+    for(let x=0;x<w;x++){const v=(cur[x]-predict(t,x?cur[x-1]:0,prev[x],x?prev[x-1]:0))&255;r[x]=v;cost+=v>127?256-v:v;}
+    if(cost<bestCost){bestCost=cost;best=t;}
+   }
+   out[at++]=best;out.set(rows[best].subarray(0,w),at);at+=w;prev.set(cur.subarray(0,w));
+  }
+ }
+ return out;
+}
+
+// Exact PNG inverse filter of one row into `cur` (bpp 1, integer arithmetic).
+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;
+  case 2:for(let x=0;x<w;x++)cur[x]=(src[at+x]+prev[x])&255;return;
+  case 3:for(let x=0;x<w;x++)cur[x]=(src[at+x]+(((x?cur[x-1]:0)+prev[x])>>1))&255;return;
+  case 4:for(let x=0;x<w;x++)cur[x]=(src[at+x]+paeth(x?cur[x-1]:0,prev[x],x?prev[x-1]:0))&255;return;
+ }
+ fail('filter');
+}
+
+// Validate and unfilter. Only the returned typed arrays survive; `bytes` is
+// not referenced by the store built from them.
+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);
+ const width=u32(4),height=u32(8),frameCount=u32(12),unique=u32(16);
+ checkShape(width,height,frameCount);
+ if(unique<1||unique>frameCount)fail('unique count');
+ const data=HEADER+4*frameCount+RECORD*unique;
+ if(bytes.length<data)fail('truncated');
+ const retained=frameIndices===undefined?null:new Uint8Array(frameCount);
+ if(retained){
+  if(!Array.isArray(frameIndices)||!frameIndices.length)fail('retained frames');
+  for(const f of frameIndices){if(!Number.isInteger(f)||f<0||f>=frameCount)fail('retained frame index');retained[f]=1;}
+ }
+ const map=new Uint32Array(frameCount),used=new Uint8Array(unique),needed=retained?new Uint8Array(unique):null;
+ for(let f=0;f<frameCount;f++){const u=u32(HEADER+4*f);if(u>=unique)fail('map');map[f]=u;used[u]=1;if(retained?.[f])needed[u]=1;}
+ if(used.includes(0))fail('unreferenced frame');
+ // x,y,w,h,first pixel index in the packed stream
+ const rects=new Float64Array(unique*5);let total=0,pixels=0;
+ 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)fail('rectangle');
+  if(length!==h*(w+1)||offset!==total)fail('offset');
+  rects.set([x,y,w,h,pixels],u*5);total+=length;if(!needed||needed[u])pixels+=w*h;
+ }
+ if(bytes.length!==data+total)fail('pixel length');
+ if(pixels*BITS>0xffffffff)fail('pixel count');
+ 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],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(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,chunks,codec};
+}
+
+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: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');
+   if(retained&&!retained[index])fail('frame was not retained');
+   const u=map[index];
+   if(slots[0].unique===u){hits++;return slots[0].frame;}
+   if(slots[1].unique===u){hits++;slots.reverse();return slots[0].frame;}
+   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;
+    for(let c=0;c<w;c++){const i=pos>>>3,s=pos&7;let v=packed[i]>>s;if(s>3)v|=packed[i+1]<<(8-s);frame[row+c]=DISPLAY[v&31];pos+=BITS;}
+   }
+   return frame;
+  },
+ });
+}
+
+// Parse, validate and unpack an RVQ5 store. A returned frame is valid until two
+// other unique frames have been requested.
+export function readPredictiveFrames(bytes,options){return createStore(decode(bytes,options));}