@bitefoundry/retrieviewer 0.0.0-stage → 0.0.1

package/retrieviewer-install.mjs

@@ -0,0 +1,157 @@
+// Safe, local native-plugin registration. Basic MCP support is NOT a renderer.
+import {homedir} from 'node:os';
+import {delimiter,join,resolve,dirname,parse as parsePath} from 'node:path';
+import {readFile,lstat,mkdir,open,rename,unlink,access} from 'node:fs/promises';
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import {fileURLToPath,pathToFileURL} from 'node:url';
+import {randomUUID} from 'node:crypto';
+import {parse,modify,applyEdits} from 'jsonc-parser';
+import {getConfigPaths,readSettings,withSettingsLock,writeAtomicJson,setAgentEnabled} from './retrieviewer-config.mjs';
+
+export const AGENTS=Object.freeze([
+ ['codex','Codex',['codex']],['claude','Claude Code',['claude']],['cursor-agent','Cursor Agent',['cursor-agent']],
+ ['grok','Grok',['grok']],['antigravity','Antigravity',['agy','antigravity']],['opencode','OpenCode',['opencode']],
+ ['pi','Pi',['pi']],['gemini','Gemini CLI',['gemini']],['copilot','GitHub Copilot CLI',['copilot']],
+ ['aider','Aider',['aider']],['goose','Goose',['goose']],['qwen','Qwen Code',['qwen']],
+ ['amp','Amp',['amp']],['droid','Droid',['droid']],['crush','Crush',['crush']],
+].map(([id,label,commands])=>Object.freeze({id,label,commands:Object.freeze(commands)})));
+const run=promisify(execFile),PLUGIN_URL=new URL('./integrations/opencode/',import.meta.url).href;
+const ADAPTER_FILE=fileURLToPath(new URL('./integrations/opencode/tui.tsx',import.meta.url));
+const definitions=new Map(AGENTS.map(a=>[a.id,a]));
+const definition=id=>{const a=definitions.get(id);if(!a)throw Error('Unknown agent: '+id);return a;};
+const processAlive=pid=>{if(!Number.isInteger(pid)||pid<=0||pid>0x7fffffff)return false;try{process.kill(pid,0);return true;}catch{return false;}};
+const exists=async path=>{try{await access(path);return true;}catch(e){if(e.code==='ENOENT')return false;throw e;}};
+async function safePath(path){
+ for(let p=resolve(path);;p=dirname(p)){
+  try{if((await lstat(p)).isSymbolicLink())throw Error('Refusing symlink/junction: '+p);}catch(e){if(e.code!=='ENOENT')throw e;}
+  if(p===parsePath(p).root)break;
+ }
+}
+async function textFile(path){await safePath(path);try{const s=await readFile(path,'utf8');if(s.length>1024*1024)throw Error('Config exceeds 1 MiB: '+path);return s;}catch(e){if(e.code==='ENOENT')return null;throw e;}}
+function documentOf(text){
+ if(text===null)return {};
+ const errors=[],data=parse(text,errors,{allowTrailingComma:true,disallowComments:false});
+ if(errors.length||!data||typeof data!=='object'||Array.isArray(data))throw Error('Malformed/non-object agent JSONC configuration; refusing to overwrite');
+ if(data.plugins!==undefined&&!Array.isArray(data.plugins))throw Error('Agent plugins must be an array; refusing to overwrite');
+ return data;
+}
+async function atomicText(path,text){
+ await safePath(path);await mkdir(dirname(path),{recursive:true});const temp=path+'.retrieviewer-'+randomUUID()+'.tmp';let owned=false;
+ try{const f=await open(temp,'wx',0o600);owned=true;try{await f.writeFile(text);await f.sync();}finally{await f.close();}await rename(temp,path);owned=false;}
+ finally{if(owned)await unlink(temp).catch(()=>{});}
+}
+
+export async function probeCommand(command,{env=process.env}={}){
+ const extensions=process.platform==='win32'?['.exe','.ps1','.cmd','']:[''];
+ for(const directory of (env.PATH??env.Path??'').split(delimiter).filter(Boolean))for(const ext of extensions){
+  const executable=join(directory,command+ext);if(!await exists(executable))continue;
+  // Never interpolate a command in a shell string. .cmd needs a shell, so prefer
+  // npm's equivalent PowerShell shim; unsupported shims are detected, not executed.
+  if(ext==='.cmd')continue;
+  try{
+   const binary=ext==='.ps1'?'pwsh.exe':executable;
+   const args=ext==='.ps1'?['-NoProfile','-NonInteractive','-File',executable,'--version']:['--version'];
+   // npm's PowerShell shims treat an open pipe as pipeline input. Close stdin so
+   // --version cannot hang waiting for EOF (spawnSync implicitly did this).
+   let pending=run(binary,args,{env,timeout:4000,maxBuffer:8192,windowsHide:true});pending.child?.stdin?.end();
+   let output;
+   try{output=await pending;}catch(error){
+    if(ext!=='.ps1'||error.code!=='ENOENT')throw error;
+    pending=run('powershell.exe',args,{env,timeout:4000,maxBuffer:8192,windowsHide:true});pending.child?.stdin?.end();output=await pending;
+   }
+   const {stdout,stderr}=output;
+   return {executable,version:(stdout+' '+stderr).match(/\d+\.\d+\.\d+/)?.[0]??'unknown'};
+  }catch{return {executable,version:'unknown'};}
+ }
+ return null;
+}
+
+export function createInstaller({home=homedir(),env=process.env,stateDir=env.RETRIEVIEWER_HOME??join(home,'.config','retrieviewer'),probe,beforeCommit}={}){
+ const options={home,env,stateDir},paths=getConfigPaths(options),probeCache=new Map();
+ const configPath=join(env.XDG_CONFIG_HOME??join(home,'.config'),'opencode','cli.json');
+ const probeOne=command=>{if(!probeCache.has(command))probeCache.set(command,Promise.resolve().then(()=>probe?probe(command):probeCommand(command,{env})));return probeCache.get(command);};
+ async function executableFor(agent){for(const cmd of agent.commands){const found=await probeOne(cmd);if(found)return found;}return null;}
+ async function inspect(id){
+  const def=definition(id),found=await executableFor(def),state=await readSettings(options),saved=state.agents[id];
+  let renderer={status:'unsupported',reason:'No native TUI renderer implemented; MCP support alone is insufficient.'};
+  if(id==='opencode')renderer=found?.version==='2.1.2'
+   ?{status:'available',reason:'Native OpenCode 2.1.2 adapter candidate; registration and runtime evidence are separate.'}
+   :{status:'version-unsupported',reason:'Native adapter currently targets OpenCode 2.1.2 exactly.'};
+  let connected=false,configError=null;
+  if(id==='opencode')try{const data=documentOf(await textFile(saved?.configPath??configPath));connected=data.plugins?.includes(PLUGIN_URL)??false;}catch(e){configError=e.message;}
+  let runtime=null;
+  try{const raw=await textFile(join(paths.root,'runtime-'+id+'.json'));if(raw)runtime=JSON.parse(raw);}catch(e){runtime={error:e.message};}
+  const age=runtime?.updatedAt?Date.now()-Date.parse(runtime.updatedAt):Infinity;
+  const recent=runtime?.version===1&&runtime?.agent===id&&runtime?.hostVersion===found?.version&&runtime?.phase==='rendering'&&age>=0&&age<15000&&Number.isFinite(runtime?.frames)&&runtime.frames>0&&processAlive(runtime?.pid);
+  return {id,label:def.label,detected:!!found,executable:found?.executable??null,version:found?.version??null,enabled:saved?.enabled===true,connected,renderer,configError,runtime,runtimeRecent:!!recent,visualApproval:false};
+ }
+ async function plan(id){
+  const row=await inspect(id);let supported=row.detected&&row.renderer.status==='available'&&!row.configError;
+  let reason=row.configError??(!row.detected?'Agent executable not found.':row.renderer.reason);
+  if(supported&&!await exists(ADAPTER_FILE)){supported=false;reason='Native adapter file is missing from the installation.';}
+  if(supported&&env.OPENCODE_CLI_CONFIG_CONTENT){supported=false;reason='An inline OpenCode CLI configuration override is active; refuse ambiguous installation.';}
+  if(id==='opencode')await safePath(configPath);
+  return {agent:id,supported,reason,pluginUrl:id==='opencode'?PLUGIN_URL:null,changes:id==='opencode'?[{path:configPath,description:'Merge the native TUI plugin URL into plugins; preserve JSONC and other entries.'},{path:paths.settings,description:'Record ownership and enabled state.'}]:[]};
+ }
+ async function backup(path,previous){
+  if(previous===null)return null;
+  const dir=join(paths.root,'backups');await safePath(dir);await mkdir(dir,{recursive:true,mode:0o700});
+  const destination=join(dir,'opencode-cli-'+randomUUID()+'.jsonc');const f=await open(destination,'wx',0o600);
+  try{await f.writeFile(previous);await f.sync();}finally{await f.close();}return destination;
+ }
+ async function transact(previous,next,state,{path=configPath}={}){
+  const backupPath=previous!==next?await backup(path,previous):null;
+  await beforeCommit?.();
+  if(await textFile(path)!==previous)throw Error('Agent configuration changed concurrently; nothing overwritten. Retry after reviewing it.');
+  let changed=false;
+  try{
+   if(previous!==next){await atomicText(path,next);changed=true;}
+   await writeAtomicJson(paths.settings,state);
+  }catch(error){
+   if(changed&&await textFile(path)===next){if(previous===null)await unlink(path);else await atomicText(path,previous);}
+   throw error;
+  }
+  return backupPath;
+ }
+ async function enable(id,{confirm=false}={}){
+  definition(id);if(!confirm)throw Error('Explicit confirmation required before changing agent configuration');
+  const proposed=await plan(id);if(!proposed.supported)throw Error(proposed.reason);
+  return withSettingsLock(async()=>{
+   const state=await readSettings(options),prior=state.agents[id],old=await textFile(configPath),data=documentOf(old),already=data.plugins?.includes(PLUGIN_URL)??false;
+   const formattingOptions={insertSpaces:true,tabSize:2,eol:old?.includes('\r\n')?'\r\n':'\n'};
+   const next=already?old:applyEdits(old??'{}\n',data.plugins
+    ?modify(old,['plugins',data.plugins.length],PLUGIN_URL,{formattingOptions,isArrayInsertion:true})
+    :modify(old??'{}\n',['plugins'],[PLUGIN_URL],{formattingOptions}));
+   // Preserve ownership only for the same exact registration; adoption is not deletion authority.
+   const addedByUs=already?!!(prior?.addedByUs&&prior.pluginUrl===PLUGIN_URL&&prior.configPath===configPath):true;
+   state.agents[id]={...prior,enabled:true,configPath,pluginUrl:PLUGIN_URL,addedByUs};
+   const backupPath=await transact(old,next,state);
+   return {agent:id,enabled:true,connected:true,rendering:false,restartRequired:true,backupPath};
+  },options);
+ }
+ async function disconnect(id,{confirm=false}={}){
+  definition(id);if(!confirm)throw Error('Explicit confirmation required before removing a registration');
+  const initial=await readSettings(options);if(!initial.agents[id])return {agent:id,connected:false,changed:false};
+  return withSettingsLock(async()=>{
+   const state=await readSettings(options),saved=state.agents[id];if(!saved)return {agent:id,changed:false};
+   // Never use a path from an editable settings file as deletion authority.
+   if(id!=='opencode'||saved.configPath!==configPath||saved.pluginUrl!==PLUGIN_URL)throw Error('Registration ownership/path does not match this installation; refusing removal.');
+   const old=await textFile(configPath),data=documentOf(old),index=data.plugins?.indexOf(PLUGIN_URL)??-1;
+   const remove=saved.addedByUs===true&&index>=0;
+   const next=remove?applyEdits(old,modify(old,['plugins',index],undefined,{formattingOptions:{insertSpaces:true,tabSize:2}})):old;
+   delete state.agents[id];const backupPath=await transact(old,next,state);
+   return {agent:id,connected:documentOf(next).plugins?.includes(PLUGIN_URL)??false,changed:true,removedOwnedEntry:remove,preservedPreexisting:index>=0&&!remove,backupPath};
+  },options);
+ }
+ return {
+  list:()=>Promise.all(AGENTS.map(a=>inspect(a.id))),plan,enable,disconnect,
+  async disable(id){definition(id);await setAgentEnabled(id,false,options);return {agent:id,enabled:false,registrationPreserved:true};},
+  status:id=>id?inspect(id):Promise.all(AGENTS.map(a=>inspect(a.id))),
+  async doctor(id){
+   const rows=id?[await inspect(id)]:await Promise.all(AGENTS.map(a=>inspect(a.id)));
+   const result=await Promise.all(rows.map(async row=>({...row,adapterFilePresent:row.id==='opencode'&&await exists(ADAPTER_FILE),checks:{executable:row.detected,compatibleVersion:row.renderer.status==='available',registration:row.connected,frameProducedRecently:row.runtimeRecent,humanVisualApproval:false},note:'A recent runtime frame receipt is not human visual verification. MCP is not required for the native OpenCode plugin.'})));
+   return id?result[0]:result;
+  },
+ };
+}

package/retrieviewer-plugin.d.mts

@@ -0,0 +1,44 @@
+import type {FrameOptions, PetFrame, PetOptions} from './retrieviewer.mjs';
+
+/** The host owns size and output; the plugin never touches DOM, stdio or signals. */
+export interface PetPluginHost {
+  /** Called before every frame. Null or a zero-size pane means hidden: no render, no time. */
+  getSize(): FrameOptions | null;
+  /** `frame.pixels` is borrowed; copy anything kept past this call. */
+  render(frame: PetFrame): void;
+  /** Called once by dispose(). */
+  clear?(): void;
+  /** Errors from scheduled frames. The plugin is already paused (not disposed). */
+  onError?(error: unknown): void;
+}
+export interface PetPluginScheduler {
+  /** Milliseconds, monotonic. */
+  now(): number;
+  /** Must call back later, never synchronously. */
+  schedule(callback: () => void, delayMs: number): unknown;
+  cancel(handle: unknown): void;
+}
+export interface PetPluginOptions {
+  host: PetPluginHost;
+  petOptions?: PetOptions;
+  /** Scheduled frame rate, default 30. */
+  fps?: number;
+  /** Default: performance.now() with setTimeout/clearTimeout, used only after start(). */
+  scheduler?: PetPluginScheduler;
+}
+export interface PetPlugin {
+  /** Idempotent. Renders immediately, then once per 1/fps s. */
+  start(): void;
+  /** Cancels the pending frame; paused time is never caught up. */
+  pause(): void;
+  /** Renders without advancing time. False while hidden. */
+  render(): boolean;
+  /** Host-owned loop: advance seconds then render. False while hidden. Throws while running. */
+  tick(dtSeconds: number): boolean;
+  /** False when busy or cooling down. */
+  interact(kind: 'ball' | 'treat'): boolean;
+  readonly running: boolean;
+  readonly disposed: boolean;
+  dispose(): void;
+}
+export function createPetPlugin(options: PetPluginOptions): Promise<PetPlugin>;

package/retrieviewer-plugin.mjs

@@ -0,0 +1,97 @@
+import {createPet} from './retrieviewer.mjs';
+
+// Portable pet plugin: the host supplies size and output, the plugin owns only its
+// own clock. Importing or creating it starts no timer, renders nothing and touches
+// no DOM, stdin/stdout, signals or global listeners; start() or tick() does the work.
+const fn=(value,name)=>{if(typeof value!=='function')throw TypeError(`${name} must be a function`);};
+const defaultScheduler=()=>({now:()=>performance.now(),schedule:(callback,delayMs)=>setTimeout(callback,delayMs),cancel:handle=>clearTimeout(handle)});
+
+export async function createPetPlugin({host,petOptions,fps=30,scheduler}={}){
+ if(!host||typeof host!=='object')throw TypeError('host must be an object');
+ fn(host.getSize,'host.getSize');fn(host.render,'host.render');
+ if(host.clear!==undefined)fn(host.clear,'host.clear');
+ if(host.onError!==undefined)fn(host.onError,'host.onError');
+ if(typeof fps!=='number'||!Number.isFinite(fps)||fps<=0||fps>120)throw RangeError('fps must be within (0, 120]');
+ if(scheduler!==undefined){
+  if(!scheduler||typeof scheduler!=='object')throw TypeError('scheduler must be an object');
+  fn(scheduler.now,'scheduler.now');fn(scheduler.schedule,'scheduler.schedule');fn(scheduler.cancel,'scheduler.cancel');
+ }
+ const clock=scheduler??defaultScheduler(),delay=1000/fps;
+ let pet=await createPet(petOptions);
+ // One pending callback at most; `token` makes a late or uncancelled callback inert.
+ let running=false,disposed=false,busy=false,armed=false,handle=null,token=0,baseline=null;
+ const alive=()=>{if(disposed)throw Error('Pet plugin is disposed');};
+ const idle=()=>{if(busy)throw Error('Pet plugin cannot render or tick from inside host.render');};
+ const cancel=()=>{if(!armed)return;const h=handle;armed=false;handle=null;token++;clock.cancel(h);};
+ const halt=()=>{running=false;baseline=null;cancel();};
+
+ // Fresh size every frame, so resizes need no listener. Null or zero-size panes are
+ // hidden: no render and no simulated time. Other invalid sizes throw from frame().
+ function draw(dt){
+  busy=true;
+  try{
+   const size=host.getSize();
+   if(size===null||size===undefined)return false;
+   if(typeof size!=='object')throw TypeError('host.getSize() must return FrameOptions or null');
+   const {columns,rows}=size;
+   if((columns===0&&Number.isInteger(rows)&&rows>=0)||(rows===0&&Number.isInteger(columns)&&columns>=0))return false;
+   if(dt>0)pet.step(dt);
+   host.render(pet.frame(size));
+   return true;
+  }finally{busy=false;}
+ }
+ // Scheduled frames advance by real elapsed time since the last visible frame. A
+ // resume or a reveal after hiding starts a new baseline, so nothing is caught up.
+ function frameAt(now){
+  const dt=baseline===null?0:Math.max(0,(now-baseline)/1000);
+  const shown=draw(dt);
+  if(running)baseline=shown?now:null;
+ }
+ function arm(){
+  if(!running||disposed||armed)return;
+  const mine=++token;armed=true;
+  handle=clock.schedule(()=>{if(mine!==token)return;armed=false;handle=null;token++;run();},delay);
+ }
+ // Asynchronous failures have no caller to throw to: the plugin pauses (it is not
+ // disposed) and hands the error to host.onError, or stays paused silently without
+ // one. If onError itself throws, that error escapes this callback and the plugin
+ // stays paused; it is never rescheduled.
+ function run(){
+  if(!running||disposed)return;
+  try{frameAt(clock.now());arm();}
+  catch(error){halt();if(!disposed&&host.onError)host.onError(error);}
+ }
+
+ return {
+  // Idempotent. Renders the first frame immediately (no time advance), then once
+  // per 1/fps s. Errors from that first frame stop the plugin and propagate.
+  start(){
+   alive();idle();if(running)return;
+   running=true;baseline=null;
+   try{frameAt(clock.now());arm();}catch(error){halt();throw error;}
+  },
+  // Cancels the pending callback; time while paused is never simulated.
+  pause(){if(!disposed)halt();},
+  // Draws the current state without advancing time. False while hidden.
+  render(){alive();idle();try{return draw(0);}catch(error){halt();throw error;}},
+  // Host-owned loop: advance by explicit seconds, then render. False while hidden
+  // (time does not advance). Use instead of start(), not alongside it.
+  tick(dtSeconds){
+   alive();idle();
+   if(running)throw Error('tick() is for host-owned loops; pause() the scheduled loop first');
+   if(typeof dtSeconds!=='number'||!Number.isFinite(dtSeconds)||dtSeconds<0)throw RangeError('dtSeconds must be finite non-negative seconds');
+   try{return draw(dtSeconds);}catch(error){halt();throw error;}
+  },
+  // 'ball' | 'treat'. False when busy or cooling down; shows on the next frame.
+  interact(kind){alive();return pet.interact(kind);},
+  get running(){return running;},
+  get disposed(){return disposed;},
+  // Idempotent: stops the clock, disposes the pet and calls host.clear once, even
+  // if pet disposal throws. A throwing clear() propagates once; disposal still holds.
+  dispose(){
+   if(disposed)return;disposed=true;halt();
+   const core=pet;pet=null;
+   try{core.dispose();}finally{host.clear?.();}
+  },
+ };
+}

package/retrieviewer-stdio.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// Explicit language-neutral host bridge. Stdout is JSONL only; no autonomous
+// timers or terminal ownership. Close stdin or send dispose to release the pet.
+import {createPet} from './retrieviewer.mjs';
+import {createInterface} from 'node:readline';
+import {once} from 'node:events';
+
+let pet,lines;
+const stop=()=>lines?.close();
+const send=async value=>{if(!process.stdout.write(JSON.stringify(value)+'\n'))await once(process.stdout,'drain');};
+try{
+ pet=await createPet();
+ lines=createInterface({input:process.stdin,crlfDelay:Infinity});
+ process.on('SIGINT',stop);process.on('SIGTERM',stop);
+ await send({event:'ready',protocol:1});
+ for await(const line of lines){
+  if(!line.trim())continue;
+  let id=null;
+  try{
+   const request=JSON.parse(line);
+   if(!request||typeof request!=='object'||Array.isArray(request))throw TypeError('Expected a request object');
+   if(request.id!==undefined&&request.id!==null&&typeof request.id!=='string'&&typeof request.id!=='number')throw TypeError('id must be a string, number or null');
+   id=request.id??null;
+   if(request.op==='frame'||request.op==='tick'){
+    // One round trip per host frame; existing step + frame stays compatible.
+    if(request.op==='tick')pet.step(request.dt);
+    const {text,columns,rows,report,artProfile}=pet.frame(request);
+    await send({id,ok:true,text,columns,rows,report,artProfile});
+   }else if(request.op==='step')await send({id,ok:true,steps:pet.step(request.dt)});
+   else if(request.op==='interact')await send({id,ok:true,accepted:pet.interact(request.kind)});
+   else if(request.op==='dispose'){pet.dispose();await send({id,ok:true});break;}
+   else throw TypeError('Unknown op: use frame, tick, step, interact or dispose');
+  }catch(error){await send({id,ok:false,error:error.message});}
+ }
+}catch(error){process.stderr.write('Retrieviewer bridge: '+error.message+'\n');process.exitCode=1;}
+finally{
+ lines?.close();pet?.dispose();process.off('SIGINT',stop);process.off('SIGTERM',stop);
+}

package/retrieviewer.d.mts

@@ -0,0 +1,85 @@
+/** A headless pet: the host owns input, time and terminal rendering. */
+export interface PetOptions {
+  /** Asset names are relative; return original file bytes (keep .gz files compressed). */
+  loadAsset?: (name: string) => Promise<ArrayBuffer | ArrayBufferView>;
+  seed?: number;
+  energy?: number;
+  /** Keep true for the current paw correction; false selects the legacy comparison. */
+  pawTransport?: boolean;
+  /** Default q5 (32 levels). Original requires separately supplied original assets. */
+  artProfile?: 'original' | 'q5';
+}
+export interface FrameOptions {
+  columns: number;
+  rows: number;
+  /** Character width / line height. Default .5; measure your terminal font if needed. */
+  cellAspect?: number;
+  poseFps?: 12 | 24 | 30;
+  contactEnabled?: boolean;
+  camera?: {
+    viewportWidth: number;
+    viewportHeight: number;
+    rect: {left: number; top: number; width: number; height: number};
+  };
+}
+export interface PetState {
+  state: string;
+  x: number;
+  z: number;
+  speed: number;
+  view: string;
+  flip: boolean;
+  seatProgress: number | null;
+  behavior: string | null;
+  actionName: string | null;
+  [key: string]: unknown;
+}
+export interface LifeReport {
+  intent: string;
+  label: string;
+  interaction: 'ball' | 'treat' | null;
+  busy: boolean;
+  energy: number;
+  decisions: number;
+  cooldowns: {ball: number; treat: number};
+  gesture: {clip: string; progress: number} | null;
+  ball: {x: number; z: number; height: number; carried: boolean} | null;
+  treat: {x: number; z: number; height: number} | null;
+}
+export interface PetFrame {
+  artProfile: 'original' | 'q5';
+  /** Plain Unicode Braille: rows lines of exactly columns cells, no ANSI. */
+  text: string;
+  columns: number;
+  rows: number;
+  /** Borrowed RGBA buffer; copy it before retaining across frame() calls. */
+  pixels: Uint8ClampedArray;
+  state: PetState;
+  report: LifeReport;
+  mouth: {x: number; y: number; rx: number; ry: number; family: string; frame: number} | null;
+  placement: {x: number; y: number; size: number; pixelAspect: number; depth: number};
+  projection: {
+    project(x: number, y: number, z: number): {x: number; y: number; depth: number};
+    ground(u: number, v: number): {x: number; z: number} | null;
+    focalPixels: number;
+  };
+  contacts: {samples: number; max: number; limited: number; releaseEvents: number; releasedMax: number};
+}
+export interface Pet {
+  /** Seconds. Fixed 60 Hz simulation, at most .1 s catch-up per call. */
+  step(dt: number): number;
+  frame(options: FrameOptions): PetFrame;
+  /** False when busy or cooling down. */
+  interact(kind: 'ball' | 'treat'): boolean;
+  readonly disposed: boolean;
+  dispose(): void;
+}
+export function createPet(options?: PetOptions): Promise<Pet>;
+export function defaultLoadAsset(name: string): Promise<ArrayBuffer | Uint8Array>;
+export const STEP_SECONDS: number;
+export const MAX_CATCH_UP_SECONDS: number;
+export const INTERACTIONS: readonly ['ball', 'treat'];
+export const ART_PROFILES: readonly ['original', 'q5'];
+export const DEFAULT_ART_PROFILE: 'q5';
+export function getPetAssetFiles(artProfile?: 'original' | 'q5'): readonly string[];
+export const PET_ASSETS: Readonly<Record<string, string>>;

package/retrieviewer.mjs

@@ -0,0 +1,142 @@
+import {makeLabAnimal} from './locomotion-core.mjs';
+import {createPaperActor,createPaperRenderer} from './puppy-paper.mjs';
+import {createPaperProjection} from './puppy-paper-world.mjs';
+import {rgbaToBraille} from './braille.mjs';
+import {createSnappyTrickTimings} from './puppy-paper-trick-timing.mjs';
+import {createCompanionLife} from './puppy-companion-life.mjs';
+import {paintCompanionObjects} from './puppy-companion-objects.mjs';
+import {readPackedFrames} from './puppy-frame-store.mjs';
+
+// Embeddable autonomous puppy. Importing or creating has no DOM, timer, stdin/stdout
+// or listener side effects: the host owns the loop and calls step() then frame().
+export const STEP_SECONDS=1/60;
+export const MAX_CATCH_UP_SECONDS=.1;
+export const INTERACTIONS=Object.freeze(['ball','treat']);
+// Approved 32-level art ships by default; preserved original art is optional.
+export const DEFAULT_ART_PROFILE='q5';
+export const ART_PROFILES=Object.freeze(['original','q5']);
+// Current companion runtime: v9 tricks + interactions-v3, same as puppy-paper.html.
+export const PET_ASSETS=Object.freeze({
+ animal:'locomotion-puppy.animal',
+ stride:'puppy-stride-tweens-q5.bin.gz',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',
+});
+const BUNDLES=['rear','approach','seat','arrivalSeat','behaviors','actions','interactions'];
+const frameFile=(base,profile)=>base+(profile==='q5'?'-q5.bin.gz':'-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');
+ return Object.freeze([PET_ASSETS.strideInfo,PET_ASSETS.stableInfo,frameFile('puppy-stride-tweens',artProfile),
+  ...BUNDLES.flatMap(key=>[PET_ASSETS[key]+'.json',frameFile(PET_ASSETS[key],artProfile)]),PET_ASSETS.animal]);
+}
+
+// Relative to this module, never the process cwd: file: URLs in Node, HTTP in browsers.
+export async function defaultLoadAsset(name){
+ const url=new URL(name,import.meta.url);
+ if(url.protocol==='file:'){
+  const {readFile}=await import('node:fs/promises');
+  try{return await readFile(url);}catch(error){
+   if(error.code==='ENOENT'&&name.endsWith('-compact.bin.gz'))throw Error('Original art is optional and not bundled. Supply the preserved original assets with loadAsset, or use the default q5 profile.',{cause:error});
+   throw error;
+  }
+ }
+ const r=await fetch(url);if(!r.ok)throw Error(`${name} HTTP ${r.status}`);return r.arrayBuffer();
+}
+
+const bytesOf=(name,value)=>{
+ if(value instanceof ArrayBuffer)return new Uint8Array(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){
+ // 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 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');
+}
+
+// Only immutable art/metadata is shared. Each pet still owns its animal, actor,
+// life, renderer and output. Last dispose drops the shared lease, not other pets.
+const sharedAssets=new Map();
+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=>readPackedFrames(await gunzip(await load(name)));
+ // One family at a time: never inflate all eight legacy-sized buffers together.
+ const data={assets:{}};
+ 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){const base=PET_ASSETS[key];data.assets[key]={info:await json(base+'.json'),bytes:await frames(frameFile(base,artProfile))};}
+ data.baked=await load(PET_ASSETS.animal);
+ return data;
+}
+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;}
+}
+
+export async function createPet({loadAsset=defaultLoadAsset,seed,energy,pawTransport=true,artProfile=DEFAULT_ART_PROFILE}={}){
+ 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');
+ if(energy!==undefined&&(!Number.isFinite(energy)||energy<0||energy>1))throw RangeError('energy must be within 0..1');
+ if(typeof pawTransport!=='boolean')throw TypeError('pawTransport must be boolean');
+ if(!ART_PROFILES.includes(artProfile))throw RangeError('artProfile must be original or q5');
+ let lease=await acquireAssets(loadAsset,artProfile),data=lease.data;
+ const release=lease.release;lease=null;
+ let {cache,info,meta,baked}=data;const assets={...data.assets};data=null;
+ let animal,actor,life;
+ try{
+  if(!assets.actions.info.clips?.['lie-down']||!assets.actions.info.clips?.['lie-up'])throw Error('v9 action cache lacks lie-down/lie-up clips');
+  animal=await makeLabAnimal({baked:baked.buffer.slice(baked.byteOffset,baked.byteOffset+baked.byteLength)});baked=null;
+  actor=createPaperActor(animal,info,{manualTricks:true,trickTimings:createSnappyTrickTimings(assets.actions.info),walkTransitions:true});
+  life=createCompanionLife(actor,{seed,...energy===undefined?{}:{energy}});
+ }catch(e){animal?.dispose?.();release();throw e;}
+ let paint=null,paintKey='',time=0,acc=0,disposed=false;
+ const alive=()=>{if(disposed)throw Error('Pet is disposed');};
+ return {
+  // Fixed 1/60 s simulation; host deltas are clamped to 0.1 s so a stalled host
+  // catches up at most six steps. Returns the number of fixed steps taken.
+  step(dt){
+   alive();if(typeof dt!=='number'||!Number.isFinite(dt)||dt<0)throw RangeError('dt must be finite non-negative seconds');
+   acc+=Math.min(dt,MAX_CATCH_UP_SECONDS);let n=0;
+   while(acc>=STEP_SECONDS-1e-9){actor.update(STEP_SECONDS);life.update(STEP_SECONDS);time+=STEP_SECONDS;acc=Math.max(0,acc-STEP_SECONDS);n++;}
+   return n;
+  },
+  // Plain Braille text sized exactly columns x rows (2x4 dots per cell). `pixels`
+  // is the renderer's buffer, valid only until the next frame()/dispose().
+  frame({columns,rows,cellAspect=.5,camera,poseFps=24,contactEnabled=true}={}){
+   alive();
+   if(!Number.isInteger(columns)||!Number.isInteger(rows)||columns<1||rows<1||columns*rows*8>1_000_000)throw RangeError('columns/rows must be positive integers within 125000 cells');
+   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});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),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});
+   return {text,columns,rows,pixels,state,report,placement,projection,artProfile,mouth:paint.lastMouth,contacts:paint.report()};
+  },
+  // 'ball' | 'treat'. False when busy or cooling down; unknown kinds throw.
+  interact(kind){alive();if(!INTERACTIONS.includes(kind))throw TypeError(`Unknown interaction: ${kind}`);return life.interact(kind);},
+  get disposed(){return disposed;},
+  dispose(){
+   if(disposed)return;disposed=true;
+   try{animal.dispose?.();}finally{
+    animal=actor=life=paint=cache=info=meta=null;paintKey='';
+    for(const k of BUNDLES)assets[k]=null;
+    release();
+   }
+  },
+ };
+}

package/vendor/procedural-animals/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Majid Manzarpour and procedural-animals 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/vendor/procedural-animals/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "procedural-animals",
+  "version": "0.1.0",
+  "description": "24 fully procedural animals for three.js: SDF-sculpted bodies, dual-quaternion skinning, GPU fur, feathers and scales, IK locomotion and actions. No models, no textures, no downloads.",
+  "license": "MIT",
+  "author": "Majid Manzarpour",
+  "homepage": "https://majidmanzarpour.github.io/threejs-procedural-animals/",
+  "repository": { "type": "git", "url": "git+https://github.com/majidmanzarpour/threejs-procedural-animals.git" },
+  "bugs": { "url": "https://github.com/majidmanzarpour/threejs-procedural-animals/issues" },
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": { "types": "./src/index.d.ts", "default": "./src/index.js" },
+    "./species/*": "./src/species/*/index.js",
+    "./worker": "./src/worker.js",
+    "./bake": "./src/bake.js",
+    "./package.json": "./package.json"
+  },
+  "bin": { "procedural-animals-bake": "./tools/bake.mjs" },
+  "sideEffects": ["./src/worker.js"],
+  "files": [
+    "src/**/*.js",
+    "src/index.d.ts",
+    "tools/bake.mjs",
+    "README.md",
+    "LICENSE",
+    "llms.txt"
+  ],
+  "engines": { "node": ">=18" },
+  "peerDependencies": { "three": ">=0.160.0" },
+  "devDependencies": { "esbuild": "^0.28.2", "playwright-core": "1.56", "three": "^0.186.0" },
+  "scripts": {
+    "build:showcase": "node showcase/build.mjs",
+    "build:pages": "node showcase/build.mjs --pages",
+    "test": "node tools/test.mjs"
+  },
+  "keywords": ["three", "threejs", "procedural", "animals", "animation", "ik", "fur", "sdf", "creatures", "gamedev", "webgl"]
+}