@bitefoundry/retrieviewer 0.0.17 → 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.17",
+  "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",
@@ -164,7 +165,39 @@
     "vendor/procedural-animals/LICENSE",
     "puppy-frame-indexed.mjs",
     "puppy-frame-file.mjs",
-    "pet-indexed-manifest.json"
+    "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",
@@ -178,7 +211,9 @@
     "release:check": "npm run check:motion && node tools/check-release.mjs",
     "prepublishOnly": "npm run release:check",
     "bake:art-index": "node tools/index-pet-art.mjs",
-    "check:art-index": "node tools/index-pet-art.mjs --check"
+    "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/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-indexed.mjs

@@ -31,7 +31,7 @@ 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}={}){
+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);
@@ -50,7 +50,7 @@ export function createIndexedFrameStore(index,{read,expand,close=()=>{},frameInd
    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++){
+   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++){

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

package/puppy-paper.mjs

@@ -354,9 +354,9 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
  };
 }
 
-export function createPaperRenderer(cache,info,meta,width,height,{rear,approach,seat,arrivalSeat,behaviors,actions,interactions,comfort,contacts=true,pawTransport=false,motionTables=null}={}){
+export function createPaperRenderer(cache,info,meta,width,height,{rear,approach,seat,arrivalSeat,behaviors,actions,interactions,comfort,contacts=true,pawTransport=false,motionTables=null,kernel=null}={}){
  if(![width,height].every(Number.isInteger)||width<2||height<2||width*height>1_000_000)throw Error('Invalid paper grid');
- const tween=createCachedTween(cache,info),renderMeta={...meta,pairs:info.pair_map,run_sequence:info.run_sequence};
+ const tween=createCachedTween(cache,info,kernel),renderMeta={...meta,pairs:info.pair_map,run_sequence:info.run_sequence};
  const out=new Uint8ClampedArray(width*height*4),area=createPaperAreaSampler();
  // Only one authored source is drawn at a time. Small samplers borrow a view of
  // the action-sized scratch. A sleep blend reads each base pixel before writing
@@ -364,14 +364,14 @@ export function createPaperRenderer(cache,info,meta,width,height,{rear,approach,
  const actionScratch=new Uint8ClampedArray(Math.max(320*320,(actions?.info.width??320)*(actions?.info.height??320))*4);
  const spriteScratch=actionScratch.subarray(0,320*320*4);
  for(let i=3;i<actionScratch.length;i+=4)actionScratch[i]=255;
- const rearSample=rear?createRearSampler(rear.bytes,rear.info,spriteScratch):null,lock=createPaperFootLock({maxImageStretch:pawTransport?1.45:Infinity});
- const approachSample=approach?createRearSampler(approach.bytes,approach.info,spriteScratch):null;
- const seatSample=seat?createPaperSeatSampler(seat.bytes,seat.info,spriteScratch):null;
- const arrivalSeatSample=arrivalSeat?createPaperSeatSampler(arrivalSeat.bytes,arrivalSeat.info,spriteScratch):null;
- const behaviorSample=behaviors?createPaperBehaviorSampler(behaviors.bytes,behaviors.info,spriteScratch):null;
- const interactionSample=interactions?createCompanionSpriteSampler(interactions.bytes,interactions.info,spriteScratch):null;
+ const rearSample=rear?createRearSampler(rear.bytes,rear.info,spriteScratch,kernel):null,lock=createPaperFootLock({maxImageStretch:pawTransport?1.45:Infinity});
+ const approachSample=approach?createRearSampler(approach.bytes,approach.info,spriteScratch,kernel):null;
+ const seatSample=seat?createPaperSeatSampler(seat.bytes,seat.info,spriteScratch,kernel):null;
+ const arrivalSeatSample=arrivalSeat?createPaperSeatSampler(arrivalSeat.bytes,arrivalSeat.info,spriteScratch,kernel):null;
+ const behaviorSample=behaviors?createPaperBehaviorSampler(behaviors.bytes,behaviors.info,spriteScratch,kernel):null;
+ const interactionSample=interactions?createCompanionSpriteSampler(interactions.bytes,interactions.info,spriteScratch,kernel):null;
  const comfortSample=comfort?createComfortSpriteSampler(comfort.bytes,comfort.info,spriteScratch):null;
- const actionSample=actions?createPaperActionSampler(actions.bytes,actions.info,actionScratch.subarray(0,actions.info.width*actions.info.height*4),motionTables?.actionClips):null,actionArea=actions?createPaperAreaSampler(actions.info.width):null;
+ const actionSample=actions?createPaperActionSampler(actions.bytes,actions.info,actionScratch.subarray(0,actions.info.width*actions.info.height*4),motionTables?.actionClips,kernel):null,actionArea=actions?createPaperAreaSampler(actions.info.width):null;
  const episodes=(key,labels,indices,samples,options)=>motionTables?.support[key]?createBakedSupportEpisodes(motionTables.support[key]):createPaperSupportEpisodes(labels,indices,samples,options);
  const walkEpisodes=actions?episodes('walk',actions.info.feet,actions.info.clips.walk,9):null;
  const sourceEpisodes=rear?{
@@ -415,8 +415,8 @@ export function createPaperRenderer(cache,info,meta,width,height,{rear,approach,
    let sx=Math.floor(rawX);if(state.flip)sx=sourceN-1-sx;
    return image[(Math.floor(rawY)*sourceN+sx)*4]>16;
   }}):null;render.lastTransport=transport;
-  const minify=side<320||sideX<320,filter=isAction?actionArea:area;if(minify)filter.prepare(image);
-  out.fill(0);for(let i=3;i<out.length;i+=4)out[i]=255;
+  const minify=side<320||sideX<320,filter=isAction?actionArea:area;if(minify&&!(kernel?.blit&&transport))filter.prepare(image);
+  if(kernel?.clear)kernel.clear(out);else{out.fill(0);for(let i=3;i<out.length;i+=4)out[i]=255;}
   render.lastPlacement={left,top,side,sideX};
   // Measured drawn mouth of the EXACT sample above (same priority, quantization,
   // placement and mirror). Side/rear/action/interaction stay null: unsupported.
@@ -430,7 +430,7 @@ export function createPaperRenderer(cache,info,meta,width,height,{rear,approach,
   }
   const drawTop=top-originY/320*side,bottom=top+Math.max(sourceN-originY,...pins.map(p=>p.target.y+20))/320*side;
   const drawLeft=left+Math.min(-originX,...pins.map(p=>p.target.x-20))/320*sideX,drawRight=left+Math.max(sourceN-originX,...pins.map(p=>p.target.x+20))/320*sideX;
-  for(let dy=Math.max(0,minify?Math.floor(drawTop):Math.ceil(drawTop-.5));dy<Math.min(height,minify?Math.ceil(bottom):Math.ceil(bottom-.5));dy++)for(let dx=Math.max(0,minify?Math.floor(drawLeft):Math.ceil(drawLeft-.5));dx<Math.min(width,minify?Math.ceil(drawRight):Math.ceil(drawRight-.5));dx++){
+  if(kernel?.blit&&transport)kernel.blit(out,image,{width,height,sourceN,left,top,side,sideX,originX,originY,drawTop,bottom,drawLeft,drawRight,flip:state.flip,layers:transport.layers});else for(let dy=Math.max(0,minify?Math.floor(drawTop):Math.ceil(drawTop-.5));dy<Math.min(height,minify?Math.ceil(bottom):Math.ceil(bottom-.5));dy++)for(let dx=Math.max(0,minify?Math.floor(drawLeft):Math.ceil(drawLeft-.5));dx<Math.min(width,minify?Math.ceil(drawRight):Math.ceil(drawRight-.5));dx++){
    const px=(dx+.5-left)/sideX*320,py=(dy+.5-top)/side*320;
    const warped=transport?transport(px,py):footSourcePoint(px,py,pins);if(!warped)continue;
    const rawX=warped.x+originX,rawY=warped.y+originY;

package/retrieviewer-cli.mjs

@@ -13,7 +13,7 @@ Usage:
   retrieviewer doctor [--agent ID] [--json]
   retrieviewer agents [--json]
   retrieviewer preview [--original]
-  retrieviewer desktop [--ink cream|gold|dark] [--return-style auto|brake|trot|run-trot] [--watch stackbite|off] [--brain openrouter|off]
+  retrieviewer desktop [--pet dog|cat] [--engine auto|native|node] [--ink cream|gold|dark] [--return-style auto|brake|trot|run-trot] [--watch stackbite|off] [--brain openrouter|off]
   retrieviewer brain-check [--json]
   retrieviewer attention [--json]
   retrieviewer desktop-status [--json]
@@ -26,8 +26,10 @@ Non-interactive changes require --agent and --yes. Unsupported native renderers
 are refused: MCP connectivity alone is never treated as in-screen rendering.
 No command changes credentials, shell profiles or agent executables.
 Desktop is a separate native overlay, NOT a Codex plugin. Choose a window once;
-use Codex normally. Exit from its tray icon or desktop-stop. No auto-start is added.
-Windows is verified; macOS and Linux X11 adapters are experimental. Native Wayland
+use Codex normally. Exit from its controls or desktop-stop. No auto-start is added.
+Windows x64 basic mode uses one native process; Node exits after launch.
+--pet cat selects the ginger cat. Watch/brain use the Node compatibility engine.
+Windows and AlmaLinux8 X11 are verified; macOS is experimental. Native Wayland
 app tracking is not supported. Linux targets AlmaLinux8/GLIBC2.28, system Python3.6+.
 Return style defaults to auto (mix all three). Restart the companion to change it.
 Watch is OFF by default. Inside a live StackBite Seat, --watch stackbite reads only
@@ -42,7 +44,7 @@ export function parseArguments(args){
  const [command='help',...rest]=args,options={};
  for(let i=0;i<rest.length;i++){
   const token=rest[i];
-  if(token==='--agent'||token==='--ink'||token==='--return-style'||token==='--watch'||token==='--brain'){
+  if(token==='--agent'||token==='--ink'||token==='--return-style'||token==='--watch'||token==='--brain'||token==='--pet'||token==='--engine'){
    const key=token.slice(2);
    if(options[key]||!rest[i+1]||rest[i+1].startsWith('-'))throw Error(token+' requires one value');
    options[key]=rest[++i];
@@ -50,13 +52,15 @@ export function parseArguments(args){
   else throw Error('Unknown argument: '+token);
  }
  if(options.agent&&!AGENTS.some(a=>a.id===options.agent))throw Error('Unknown agent: '+options.agent);
+ if(options.pet&&!['dog','cat'].includes(options.pet))throw Error('--pet must be dog or cat');
+ if(options.engine&&!['auto','native','node'].includes(options.engine))throw Error('--engine must be auto, native or node');
  if(options.ink&&!['cream','gold','dark'].includes(options.ink))throw Error('--ink must be cream, gold or dark');
  if(options['return-style']&&!['auto','brake','trot','run-trot'].includes(options['return-style']))throw Error('--return-style must be auto, brake, trot or run-trot');
  if(options.watch&&!['off','stackbite'].includes(options.watch))throw Error('--watch must be stackbite or off');
  if(options.brain&&!['off','openrouter'].includes(options.brain))throw Error('--brain must be openrouter or off');
  if(options.brain==='openrouter'&&options.watch!=='stackbite')throw Error('--brain openrouter requires --watch stackbite');
  if(!['help','--help','-h','enable','disable','disconnect','status','doctor','agents','preview','attention','brain-check','desktop','desktop-status','desktop-stop','desktop-clean','desktop-remove'].includes(command))throw Error('Unknown command: '+command);
- const allowed={desktop:['ink','return-style','watch','brain'],attention:['json'],'brain-check':['json'],enable:['agent','yes','json','dry-run'],disconnect:['agent','yes','json','dry-run'],disable:['agent','json'],status:['agent','json'],doctor:['agent','json'],agents:['json'],preview:['original'],'desktop-status':['json'],'desktop-clean':['yes'],'desktop-remove':['yes']};
+ const allowed={desktop:['ink','return-style','watch','brain','pet','engine'],attention:['json'],'brain-check':['json'],enable:['agent','yes','json','dry-run'],disconnect:['agent','yes','json','dry-run'],disable:['agent','json'],status:['agent','json'],doctor:['agent','json'],agents:['json'],preview:['original'],'desktop-status':['json'],'desktop-clean':['yes'],'desktop-remove':['yes']};
  for(const key of Object.keys(options))if(!(allowed[command]??[]).includes(key))throw Error(`--${key} is not supported by ${command}`);
  return {command,options};
 }
@@ -82,7 +86,7 @@ export async function runCli(args,{input=process.stdin,output=process.stdout,err
   if(['desktop-clean','desktop-remove'].includes(command)&&!options.yes)throw Error('Use '+command+' --yes to remove only the companion cache.');
   const api=desktop??await import('./integrations/windows-overlay/desktop.mjs');
   const action={'desktop':'startDesktop','desktop-status':'desktopStatus','desktop-stop':'stopDesktop','desktop-clean':'cleanDesktop','desktop-remove':'removeDesktop'}[command];
-  emit(await api[action]({...options.ink?{ink:options.ink}:{},...options['return-style']?{returnStyle:options['return-style']}:{},...options.watch?{watch:options.watch}:{},...options.brain?{brain:options.brain}:{} }));return 0;
+  emit(await api[action]({...options.pet?{pet:options.pet}:{},...options.engine?{engine:options.engine}:{},...options.ink?{ink:options.ink}:{},...options['return-style']?{returnStyle:options['return-style']}:{},...options.watch?{watch:options.watch}:{},...options.brain?{brain:options.brain}:{} }));return 0;
  }
  if(command==='preview'){await import('./examples/live.mjs');return 0;}
  if(['status','doctor','agents'].includes(command)){

package/retrieviewer.mjs

@@ -123,7 +123,7 @@ async function acquireAssets(loadAsset,artProfile){
  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'}={}){
+function petOptions({loadAsset=defaultLoadAsset,seed,energy,pawTransport=true,artProfile=DEFAULT_ART_PROFILE,returnStyle='auto'}={}){
  if(typeof loadAsset!=='function')throw TypeError('loadAsset must be a function');
  if(seed===undefined)seed=globalThis.crypto?.getRandomValues?globalThis.crypto.getRandomValues(new Uint32Array(1))[0]:731;
  if(!Number.isInteger(seed)||seed<0||seed>0xffffffff)throw RangeError('seed must be a uint32');
@@ -131,7 +131,16 @@ export async function createPet({loadAsset=defaultLoadAsset,seed,energy,pawTrans
  if(typeof pawTransport!=='boolean')throw TypeError('pawTransport must be boolean');
  if(!ART_PROFILES.includes(artProfile))throw RangeError('artProfile must be original or q5');
  if(!FETCH_RETURN_STYLES.includes(returnStyle))throw RangeError('returnStyle must be auto, brake, trot or run-trot');
- let lease=await acquireAssets(loadAsset,artProfile),data=lease.data;
+ return {loadAsset,seed,energy,pawTransport,artProfile,returnStyle};
+}
+export async function createPet(options={}){
+ const normalized=petOptions(options),lease=await acquireAssets(normalized.loadAsset,normalized.artProfile);
+ return createPetFromAssets(normalized,lease);
+}
+// Shared simulation/render core for local native hosts. The provider owns I/O.
+export function createPetFromAssets(options,lease,kernel=null){
+ const {loadAsset,seed,energy,pawTransport,artProfile,returnStyle}=petOptions(options);
+ let data=lease.data;
  const release=lease.release;lease=null;
  let {cache,info,meta}=data;const assets={...data.assets};data=null;
  // Baked tables describe the bundled Q5 source only. External/optional artwork
@@ -166,14 +175,14 @@ export async function createPet({loadAsset=defaultLoadAsset,seed,energy,pawTrans
    if(typeof cellAspect!=='number'||!Number.isFinite(cellAspect)||cellAspect<=0)throw RangeError('cellAspect must be a positive number');
    if(![12,24,30].includes(poseFps))throw RangeError('poseFps must be 12, 24 or 30');
    const width=columns*2,height=rows*4,key=`${width}x${height}`;
-   if(paintKey!==key){paint=createPaperRenderer(cache,info,meta,width,height,{...assets,pawTransport,motionTables});paintKey=key;}
+   if(paintKey!==key){paint=createPaperRenderer(cache,info,meta,width,height,{...assets,pawTransport,motionTables,kernel});paintKey=key;}
    const viewportWidth=camera?.viewportWidth??columns*cellAspect,viewportHeight=camera?.viewportHeight??rows;
    const projection=createPaperProjection({viewportWidth,viewportHeight,rect:camera?.rect??{left:0,top:0,width:viewportWidth,height:viewportHeight},width,height});
    const state=actor.sample(time,{poseFps}),report=life.report;
    if(report.gesture)state.interactionPose=report.gesture;
    const placement=projection.placement(state.x,state.z,state.bodyLift??0),pixels=paint(state,{...placement,contactEnabled:!!contactEnabled});
    paintCompanionObjects(pixels,width,height,projection,report,state,paint.lastMouth);
-   const {text}=rgbaToBraille(pixels,width,height,{method:'stable',brightness:1.18,contrast:1.1});
+   const {text}=rgbaToBraille(pixels,width,height,{method:'stable',brightness:1.18,contrast:1.1,kernel});
    lastHeldFrameKey=heldFrameKey(state,report,{columns,rows,cellAspect,camera,poseFps,contactEnabled});
    return {text,columns,rows,pixels,state,report,placement,projection,artProfile,mouth:paint.lastMouth,contacts:paint.report()};
   },