@bitefoundry/retrieviewer 0.0.16 → 0.0.18

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.d.mts

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

package/retrieviewer.mjs

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