@bitefoundry/retrieviewer 0.0.0-stage → 0.0.1

package/puppy-stable.mjs

@@ -0,0 +1,72 @@
+import {createZoomies} from './puppy-zoomies.mjs';
+import {createSpriteTween} from './puppy-continuous.mjs';
+export const STABLE_SPEC={width:320,height:320,count:42,tempo:.6,cycle:21};
+const ease=p=>{p=Math.max(0,Math.min(1,p));return p*p*p*(p*(p*6-15)+10);};
+const mix=(a,b,p)=>a+(b-a)*p;
+// Integral of a smooth velocity ramp: quick acceleration, cruise, soft stop.
+export function launchProgress(p){
+ p=Math.max(0,Math.min(1,p));const a=.10,b=.22,v=1/(1-(a+b)/2),integral=u=>u*u*u-.5*u*u*u*u;
+ if(p<a)return v*a*integral(p/a);
+ if(p>1-b)return 1-v*b*integral((1-p)/b);
+ return v*(p-a/2);
+}
+// The estimated thick-body root is ALWAYS (160,180). Stage depth/scale never comes from
+// sprite silhouette dimensions. Gait-local vertical contact correction is separate.
+export function stableAt(seconds,{mode='auto',easedTurns=false,rampRest=false,tempo=.6,quickLaunch=false,movingTurns=false}={}){
+ if(!Number.isFinite(seconds)||seconds<0||!Number.isFinite(tempo)||tempo<=0||tempo>4||!['auto','run','pant'].includes(mode))throw Error('Invalid stable animation time/mode');
+ const time=seconds*tempo,cycle=quickLaunch?20.18:21,local=time%cycle;
+ const t=quickLaunch?(local<.18?local/.18:local+.82):local;
+ const state=(kind,pair,blend,x=.58,flip=false)=>({state:kind,pair,blend,x,flip,floor:.94,scale:.72,pose:pair<=40?pair:[0,41,0,30,20,0][pair-41],z:1});
+ const pant=phase=>{const p=phase*15,i=Math.floor(p);return state('pant',20+i%10,p-i);};
+ const run=(p,from,to,start,end,flip)=>{const u=(p-start)/(end-start),progress=from===to?u:quickLaunch&&start===1?launchProgress(u):ease(u),cycles=Math.max(1,Math.round((end-start)*.9)),gait=progress*cycles*20,i=Math.floor(gait);return state('run',i%20,gait-i,mix(from,to,progress),flip);};
+ const turn=(p,x,reverse)=>{
+  const q=ease(p/1.5),direction=reverse?-1:1;
+  const position=s=>{
+   if(movingTurns){
+    // Fixed observer: the ACTOR follows a small U-shaped ground path.
+    // Same depth and scale throughout; no camera orbit or silhouette resizing.
+    s.x=x+direction*(-.04+.04*Math.cos(Math.PI*q)+.065*Math.sin(Math.PI*q));
+    s.floor+=.035*Math.sin(Math.PI*q);
+   }
+   return s;
+  };
+  if(p<.2)return position(state('turn',reverse?43:41,ease(p/.2),x));
+  if(p<1.3){const progress=(p-.2)/1.1,q=(easedTurns?ease(progress):progress)*11,index=Math.min(10,Math.floor(q)),a=q-index;return position(state('turn',reverse?40-index:30+index,reverse?1-a:a,x));}
+  return position(state('turn',reverse?44:42,ease((p-1.3)/.2),x));
+ };
+ if(mode==='pant')return pant(time);
+ if(mode==='run')return run(time,.58,.58,0,1,false);
+ if(t<1)return state('launch',45,ease(t));
+ if(t<3)return run(t,.58,.78,1,3,false);
+ if(t<4.5)return turn(t-3,.78,false);
+ if(t<47/6)return run(t,movingTurns?.70:.78,.22,4.5,47/6,true);
+ if(t<28/3)return turn(t-47/6,.22,true);
+ if(t<34/3)return run(t,movingTurns?.30:.22,.58,28/3,34/3,false);
+ if(t<37/3)return state('settle',46,ease(t-34/3));
+ const rest=t-37/3;
+ if(rampRest){
+  const duration=26/3,ramp=.5,rate=120/(duration-ramp),integral=u=>u**6-3*u**5+2.5*u**4;
+  const phase=rest<ramp?rate*ramp*integral(rest/ramp):rest>duration-ramp?120-rate*ramp*integral((duration-rest)/ramp):rate*(rest-ramp/2);
+  return pant(phase/15);
+ }
+ return pant(rest);
+}
+export function groundOffset(state,meta){
+ const [a,b]=meta.pairs[state.pair],p=state.blend;
+ const v=meta.ground_offsets;
+ if(state.pair<30){
+  const start=state.pair<20?0:20,n=start?10:20,index=a-start;
+  const before=v[start+(index+n-1)%n],after=v[start+(index+2)%n];
+  // Periodic Catmull-Rom: root velocity is continuous across pose boundaries.
+  return .5*((2*v[a])+(-before+v[b])*p+(2*before-5*v[a]+4*v[b]-after)*p*p+(-before+3*v[a]-3*v[b]+after)*p*p*p);
+ }
+ return mix(v[a],v[b],p);
+}
+export function createStableZoomies(atlas,fields,meta,width,height,{sampleState=stableAt,frameProvider,groundAt=groundOffset}={}){
+ if(meta.count!==42||meta.pairs.length!==47||meta.ground_offsets.length!==42)throw Error('Invalid stable metadata');
+ const tween=frameProvider??createSpriteTween(atlas,fields,{count:42,pairs:meta.pairs});
+ const stateAt=(seconds,options)=>{
+  const s=sampleState(seconds,options);s.floor+=groundAt(s,meta)*s.scale/320;return s;
+ };
+ return createZoomies(atlas,width,height,{spec:STABLE_SPEC,stateAt,frameProvider:tween});
+}

package/puppy-stride-meta.json

@@ -0,0 +1,343 @@
+{
+  "pairs": 47,
+  "samples": 17,
+  "width": 320,
+  "height": 320,
+  "channels": 1,
+  "bytes": 81817600,
+  "gzip_bytes": 27353427,
+  "sha256": "15e8ef49947cec4a1dcb3393d43a2ad48125d1bcd30f01275087c3df61627392",
+  "source_sha256": "773530ca2986c127013c5f37630701c6660c943a79f16ba1560ae2ddbda204fc",
+  "method": "RIFE v4.6, nihui/rife-ncnn-vulkan pinned release 20221029; exact original endpoints; curated single-flight gait, three new skip bridges",
+  "tool_provenance": "tools/rife-20221029/provenance.json",
+  "run_motion_costs": [
+    29.32706069946289,
+    38.92640686035156,
+    35.9362678527832,
+    26.38045883178711,
+    23.560644149780273,
+    37.207794189453125,
+    17.431142807006836,
+    31.60407257080078
+  ],
+  "run_timing": [
+    0.0,
+    2.267557382583618,
+    5.171559810638428,
+    8.922640800476074,
+    10.962368965148926,
+    12.820930480957031,
+    15.697823524475098,
+    17.556385040283203,
+    20.0
+  ],
+  "run_sequence": [
+    0,
+    1,
+    6,
+    9,
+    10,
+    11,
+    12,
+    13
+  ],
+  "pair_map": [
+    [
+      0,
+      1,
+      false,
+      false
+    ],
+    [
+      1,
+      6,
+      false,
+      false
+    ],
+    [
+      6,
+      9,
+      false,
+      false
+    ],
+    [
+      9,
+      10,
+      false,
+      false
+    ],
+    [
+      10,
+      11,
+      false,
+      false
+    ],
+    [
+      11,
+      12,
+      false,
+      false
+    ],
+    [
+      12,
+      13,
+      false,
+      false
+    ],
+    [
+      13,
+      0,
+      false,
+      false
+    ],
+    [
+      8,
+      9,
+      false,
+      false
+    ],
+    [
+      9,
+      10,
+      false,
+      false
+    ],
+    [
+      10,
+      11,
+      false,
+      false
+    ],
+    [
+      11,
+      12,
+      false,
+      false
+    ],
+    [
+      12,
+      13,
+      false,
+      false
+    ],
+    [
+      13,
+      14,
+      false,
+      false
+    ],
+    [
+      14,
+      15,
+      false,
+      false
+    ],
+    [
+      15,
+      16,
+      false,
+      false
+    ],
+    [
+      16,
+      17,
+      false,
+      false
+    ],
+    [
+      17,
+      18,
+      false,
+      false
+    ],
+    [
+      18,
+      19,
+      false,
+      false
+    ],
+    [
+      19,
+      0,
+      false,
+      false
+    ],
+    [
+      20,
+      21,
+      false,
+      false
+    ],
+    [
+      21,
+      22,
+      false,
+      false
+    ],
+    [
+      22,
+      23,
+      false,
+      false
+    ],
+    [
+      23,
+      24,
+      false,
+      false
+    ],
+    [
+      24,
+      25,
+      false,
+      false
+    ],
+    [
+      25,
+      26,
+      false,
+      false
+    ],
+    [
+      26,
+      27,
+      false,
+      false
+    ],
+    [
+      27,
+      28,
+      false,
+      false
+    ],
+    [
+      28,
+      29,
+      false,
+      false
+    ],
+    [
+      29,
+      20,
+      false,
+      false
+    ],
+    [
+      30,
+      31,
+      false,
+      false
+    ],
+    [
+      31,
+      32,
+      false,
+      false
+    ],
+    [
+      32,
+      33,
+      false,
+      false
+    ],
+    [
+      33,
+      34,
+      false,
+      false
+    ],
+    [
+      34,
+      35,
+      false,
+      false
+    ],
+    [
+      35,
+      36,
+      false,
+      false
+    ],
+    [
+      36,
+      37,
+      false,
+      false
+    ],
+    [
+      37,
+      38,
+      false,
+      false
+    ],
+    [
+      38,
+      39,
+      false,
+      false
+    ],
+    [
+      39,
+      40,
+      false,
+      false
+    ],
+    [
+      40,
+      41,
+      false,
+      false
+    ],
+    [
+      0,
+      30,
+      false,
+      false
+    ],
+    [
+      41,
+      0,
+      false,
+      true
+    ],
+    [
+      0,
+      41,
+      true,
+      false
+    ],
+    [
+      30,
+      0,
+      false,
+      false
+    ],
+    [
+      20,
+      0,
+      false,
+      false
+    ],
+    [
+      0,
+      20,
+      false,
+      false
+    ]
+  ],
+  "new_edges": [
+    [
+      1,
+      6
+    ],
+    [
+      6,
+      9
+    ],
+    [
+      13,
+      0
+    ]
+  ],
+  "previous_cache_sha256": "8d91d81cdd41629e23b0d8d6421baa0efa8d74a64a611035f3b97fd6f86fbd7d"
+}

package/puppy-zoomies.mjs

@@ -0,0 +1,27 @@
+export const ZOOMIES={width:320,height:320,count:12,columns:4,rows:3};
+const ease=x=>x*x*(3-2*x);
+export function zoomiesAt(seconds,{mode='auto'}={}){
+ if(!Number.isFinite(seconds)||seconds<0||!['auto','run','pant'].includes(mode))throw Error('Invalid zoomies state');
+ const t=mode==='run'?seconds%6:seconds%16;
+ if(mode==='pant'||(mode==='auto'&&t>=8))return {state:'pant',pose:8+Math.floor(seconds*6)%4,x:.58,floor:.96,scale:.90,flip:false};
+ if(t>=6){const s=ease(Math.min(1,(t-6)/2));return {state:t<6.5?'brake':'settle',pose:t<6.5?7:8,x:.58,floor:.96,scale:.66+.24*s,flip:false};}
+ const leg=Math.floor(t/2),p=ease((t%2)/2),x=leg===0?.22+.56*p:leg===1?.78-.56*p:.22+.36*p;
+ return {state:'run',pose:Math.floor(seconds*12)%8,x,floor:.83+.045*Math.sin(t*Math.PI/3),scale:.62+.04*Math.sin(t*Math.PI/3),flip:leg===1};
+}
+export function createZoomies(atlas,width,height,{spec=ZOOMIES,stateAt=zoomiesAt,frameProvider}={}){
+ const {width:sw,height:sh,count}=spec,stride=sw*sh*4;
+ if(atlas.length!==stride*count||![width,height].every(Number.isInteger)||width<2||height<2||width*height>1_000_000)throw Error('Invalid zoomies atlas or stage');
+ const out=new Uint8ClampedArray(width*height*4);
+ return function render(seconds,options={}){
+  const state=stateAt(seconds,options),side=height*state.scale,span=side*(state.widthScale??1),left=width*state.x-span/2,top=height*state.floor-side,offset=frameProvider?0:state.pose*stride,image=frameProvider?frameProvider(state):atlas;
+  out.fill(0);for(let i=3;i<out.length;i+=4)out[i]=255;
+  for(let y=Math.max(0,Math.floor(top));y<Math.min(height,Math.ceil(top+side));y++)for(let x=Math.max(0,Math.floor(left));x<Math.min(width,Math.ceil(left+span));x++){
+   let u=(x-left)/span;if(state.flip)u=1-u;const v=(y-top)/side;
+   if(u<0||u>1||v<0||v>1)continue;
+   const sx=u*(sw-1),sy=v*(sh-1),x0=Math.floor(sx),y0=Math.floor(sy),x1=Math.min(sw-1,x0+1),y1=Math.min(sh-1,y0+1),fx=sx-x0,fy=sy-y0;
+   const a=offset+(y0*sw+x0)*4,b=offset+(y0*sw+x1)*4,c=offset+(y1*sw+x0)*4,d=offset+(y1*sw+x1)*4,j=(y*width+x)*4;
+   for(let k=0;k<3;k++)out[j+k]=(image[a+k]*(1-fx)+image[b+k]*fx)*(1-fy)+(image[c+k]*(1-fx)+image[d+k]*fx)*fy;
+  }
+  return out;
+ };
+}

package/puppy-zoomies30.mjs

@@ -0,0 +1,12 @@
+import {createZoomies,zoomiesAt} from './puppy-zoomies.mjs';
+export const ZOOMIES30={width:320,height:320,count:30,runCount:20,pantCount:10,fps:30,tempo:.6};
+export function zoomies30At(seconds,options={}){
+ // Slow the shared behavior/pose clock, not the display refresh rate.
+ const time=seconds*ZOOMIES30.tempo,state=zoomiesAt(time,options);
+ if(state.state==='run')state.pose=Math.floor(time*30)%20;
+ else if(state.state==='brake')state.pose=19;
+ else if(state.state==='settle')state.pose=20;
+ else state.pose=20+Math.floor(time*15)%10;
+ return state;
+}
+export function createZoomies30(atlas,width,height){return createZoomies(atlas,width,height,{spec:ZOOMIES30,stateAt:zoomies30At});}

package/retrieviewer-cli.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// Installer entrypoint. Never imports art for help/status/doctor or config planning.
+import {createInstaller,AGENTS} from './retrieviewer-install.mjs';
+import {createInterface} from 'node:readline/promises';
+
+const HELP=`Retrieviewer — autonomous Braille companion
+
+Usage:
+  retrieviewer enable [--agent ID] [--yes] [--dry-run]
+  retrieviewer disable --agent ID
+  retrieviewer disconnect --agent ID [--yes] [--dry-run]
+  retrieviewer status [--agent ID] [--json]
+  retrieviewer doctor [--agent ID] [--json]
+  retrieviewer agents [--json]
+  retrieviewer preview [--original]
+
+Enable opens a first-run selection/confirmation wizard on a real terminal.
+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.
+`;
+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'){
+   if(options.agent||!rest[i+1]||rest[i+1].startsWith('-'))throw Error('--agent requires one ID');
+   options.agent=rest[++i];
+  }else if(['--yes','--json','--dry-run','--original'].includes(token))options[token.slice(2)]=true;
+  else throw Error('Unknown argument: '+token);
+ }
+ if(options.agent&&!AGENTS.some(a=>a.id===options.agent))throw Error('Unknown agent: '+options.agent);
+ if(!['help','--help','-h','enable','disable','disconnect','status','doctor','agents','preview'].includes(command))throw Error('Unknown command: '+command);
+ const allowed={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']};
+ for(const key of Object.keys(options))if(!(allowed[command]??[]).includes(key))throw Error(`--${key} is not supported by ${command}`);
+ return {command,options};
+}
+export async function runCli(args,{input=process.stdin,output=process.stdout,error=process.stderr,installer=createInstaller()}={}){
+ const {command,options}=parseArguments(args),emit=value=>output.write(JSON.stringify(value,null,2)+'\n');
+ if(['help','--help','-h'].includes(command)){output.write(HELP);return 0;}
+ if(command==='preview'){await import('./examples/live.mjs');return 0;}
+ if(['status','doctor','agents'].includes(command)){
+  const result=command==='agents'?await installer.list():await installer[command](options.agent);
+  if(options.json||command==='doctor')emit(result);
+  else for(const row of Array.isArray(result)?result:[result])output.write(`${row.id}: ${row.detected?'detected '+(row.version??'unknown version'):'not installed'} | ${row.enabled?'enabled':'disabled'} | ${row.connected?'registered':'not registered'} | renderer ${row.renderer?.status??'unknown'}${row.renderer?.reason?' — '+row.renderer.reason:''}\n`);
+  return 0;
+ }
+ let agent=options.agent,rl;
+ const interactive=!!input.isTTY&&!!output.isTTY;
+ try{
+  if(!agent){
+   if(!interactive)throw Error('Specify --agent ID. Run retrieviewer agents to list targets.');
+   if(command!=='enable')throw Error('--agent is required');
+   const list=await installer.list();
+   output.write('Choose an agent (unavailable renderers cannot be enabled):\n');
+   list.forEach((row,i)=>output.write(`  ${i+1}. ${row.label} — ${row.detected?'detected':'not installed'} / ${row.renderer.status}\n`));
+   rl=createInterface({input,output});const selected=await rl.question('Number or agent ID (Enter cancels): ');
+   if(!selected.trim()){output.write('Cancelled; no settings changed.\n');return 0;}
+   agent=list[Number(selected)-1]?.id??selected.trim();
+   if(!list.some(row=>row.id===agent))throw Error('Unknown selection');
+  }
+  if(command==='disable'){emit(await installer.disable(agent));return 0;}
+  const plan=await installer.plan(agent);
+  if(command==='enable'&&!plan.supported){emit(plan);error.write('Native in-screen renderer is not available for this target; nothing changed.\n');return 2;}
+  output.write(`${command==='enable'?'Enable':'Disconnect'} Retrieviewer for ${agent}\n`);
+  for(const change of plan.changes??[])output.write(`  ${change.path}: ${command==='disconnect'?'remove only the Retrieviewer-owned registration; preserve other settings':change.description}\n`);
+  if(options['dry-run']){emit({...plan,dryRun:true,operation:command});return 0;}
+  let confirmed=options.yes===true;
+  if(!confirmed&&interactive){rl??=createInterface({input,output});confirmed=/^y(?:es)?$/i.test((await rl.question('Back up and apply these changes? [y/N] ')).trim());}
+  if(!confirmed){if(!interactive)throw Error('No settings changed. Review --dry-run, then use --yes to confirm.');output.write('Cancelled; no settings changed.\n');return 0;}
+  emit(await installer[command](agent,{confirm:true}));
+  if(command==='enable')output.write('Registration complete; restart the agent. Rendering is checked separately by doctor.\n');
+  return 0;
+ }finally{rl?.close();}
+}
+
+// CLI is deliberately a separate module from the side-effect-free library.
+import {pathToFileURL} from 'node:url';
+if(process.argv[1]&&import.meta.url===pathToFileURL(process.argv[1]).href){
+ try{process.exitCode=await runCli(process.argv.slice(2));}catch(e){process.stderr.write('Retrieviewer: '+e.message+'\n');process.exitCode=1;}
+}

package/retrieviewer-config.mjs

@@ -0,0 +1,49 @@
+// Tiny runtime settings API. No art, processes, timers or I/O on import.
+import {homedir} from 'node:os';
+import {join,resolve} from 'node:path';
+import {readFile,mkdir,lstat,open,rename,unlink} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+
+export function getConfigPaths({home=homedir(),env=process.env,stateDir}={}){
+ const root=resolve(stateDir??env.RETRIEVIEWER_HOME??join(home,'.config','retrieviewer'));
+ return {root,settings:join(root,'settings.json'),lock:join(root,'settings.lock')};
+}
+const agentId=id=>{if(typeof id!=='string'||!/^[a-z][a-z0-9-]{0,47}$/.test(id))throw TypeError('Invalid agent ID');return id;};
+async function noLink(path){try{if((await lstat(path)).isSymbolicLink())throw Error('Refusing symlink: '+path);}catch(e){if(e.code!=='ENOENT')throw e;}}
+export async function readSettings(options={}){
+ const {root,settings}=getConfigPaths(options);await noLink(root);await noLink(settings);
+ let bytes;try{bytes=await readFile(settings,'utf8');}catch(e){if(e.code==='ENOENT')return {version:1,agents:{}};throw e;}
+ if(bytes.length>1024*1024)throw Error('Retrieviewer settings exceed 1 MiB');
+ const data=JSON.parse(bytes);
+ if(!data||data.version!==1||!data.agents||typeof data.agents!=='object'||Array.isArray(data.agents))throw Error('Unsupported Retrieviewer settings format');
+ return data;
+}
+export async function readAgentSettings(agent,options={}){
+ agentId(agent);const data=await readSettings(options);
+ return Object.hasOwn(data.agents,agent)?{...data.agents[agent],enabled:data.agents[agent]?.enabled===true}:{enabled:false};
+}
+export async function writeAtomicJson(path,value){
+ await noLink(path);const temp=path+'.'+randomUUID()+'.tmp';let owned=false;
+ try{const file=await open(temp,'wx',0o600);owned=true;try{await file.writeFile(JSON.stringify(value,null,2)+'\n');await file.sync();}finally{await file.close();}await rename(temp,path);owned=false;}
+ finally{if(owned)await unlink(temp).catch(()=>{});}
+}
+export async function withSettingsLock(fn,options={}){
+ const paths=getConfigPaths(options);await noLink(paths.root);await mkdir(paths.root,{recursive:true,mode:0o700});
+ await noLink(paths.lock);let handle;
+ try{handle=await open(paths.lock,'wx',0o600);}catch(e){if(e.code==='EEXIST')throw Error('Retrieviewer settings are locked by another operation; retry when it finishes.');throw e;}
+ try{return await fn(paths);}finally{await handle.close();await unlink(paths.lock);}
+}
+export async function setAgentEnabled(agent,enabled,options={}){
+ agentId(agent);if(typeof enabled!=='boolean')throw TypeError('enabled must be boolean');
+ await withSettingsLock(async({settings})=>{
+  const data=await readSettings(options);
+  if(!Object.hasOwn(data.agents,agent))throw Error('Agent is not connected. Run retrieviewer enable --agent '+agent+' first.');
+  data.agents[agent]={...data.agents[agent],enabled};await writeAtomicJson(settings,data);
+ },options);
+}
+export async function writeRuntimeReceipt(agent,receipt,options={}){
+ agentId(agent);const {root}=getConfigPaths(options);await noLink(root);await mkdir(root,{recursive:true,mode:0o700});
+ const {hostVersion,phase,firstFrameAt,columns,rows,frames}=receipt;
+ if(!['rendering','stopped'].includes(phase))throw TypeError('Invalid renderer receipt phase');
+ await writeAtomicJson(join(root,'runtime-'+agent+'.json'),{version:1,agent,hostVersion,phase,firstFrameAt,columns,rows,frames,pid:process.pid,updatedAt:new Date().toISOString()});
+}