@bitefoundry/retrieviewer 0.0.0-stage → 0.0.2

package/integrations/windows-overlay/worker.mjs

@@ -0,0 +1,60 @@
+// Private detached worker, started only by the explicit `desktop` command.
+import {spawn} from 'node:child_process';
+import {createServer} from 'node:net';
+import {createInterface} from 'node:readline';
+import {open,unlink,readFile} from 'node:fs/promises';
+import {randomBytes,randomUUID} from 'node:crypto';
+import {prepareRoot,noLink} from './desktop.mjs';
+import {createFramePump} from './protocol.mjs';
+
+let helper,pump,timer,server,session,paths,owned=false,stopping=false,frames=0,paintedFrames=0,visible=false,selected=false,pickerVisible=false,pendingViewport=null,lastInteraction=null;
+const sendParent=message=>{if(process.connected)process.send(message);};
+async function stop(){
+ if(stopping)return;stopping=true;clearInterval(timer);pump?.dispose();
+ if(helper&&!helper.killed){try{helper.stdin.end(JSON.stringify({type:'quit'})+'\n');}catch{}}
+ if(server)server.close();
+ if(owned)try{const current=JSON.parse(await readFile(paths.session,'utf8'));if(current.token===session.token)await unlink(paths.session);}catch{}
+ // A wedged painter is our own child only, never the selected terminal.
+ const watchdog=setTimeout(()=>{helper?.kill();process.exit(0);},2500);watchdog.unref();
+ if(!helper||helper.exitCode!==null)process.exitCode=0;
+}
+process.on('SIGTERM',stop);process.on('SIGINT',stop);process.on('message',m=>{if(m?.command==='abort')stop();});
+try{
+ paths=await prepareRoot();await noLink(paths.session);
+ session={owner:'bitefoundry-retrieviewer-overlay-v1',pid:process.pid,pipe:'\\\\.\\pipe\\retrieviewer-overlay-'+randomUUID(),token:randomBytes(32).toString('hex')};
+ const record=await open(paths.session,'wx',0o600);owned=true;try{await record.writeFile(JSON.stringify(session)+'\n');}finally{await record.close();}
+ server=createServer(socket=>{
+  socket.setTimeout(1500,()=>socket.destroy());let body='';
+  socket.on('error',()=>{});socket.on('data',bytes=>{
+   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,pid:process.pid,painterPid:helper?.pid,rssBytes:process.memoryUsage().rss})+'\n');
+   if(command.command==='stop')stop();
+  });
+ });
+ await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(session.pipe,resolve);});
+ // GUI-subsystem exe: no console to hide. SW_HIDE here also hides its first UI.
+ helper=spawn(process.argv[2],process.argv[3]==='--ipc-test'?['--ipc-test']:[],{windowsHide:false,stdio:['pipe','pipe','pipe']});
+ helper.stdin.on('error',()=>stop());helper.stderr.resume();helper.once('error',error=>{sendParent({error:error.message});stop();});
+ helper.once('exit',code=>{if(!stopping)sendParent({error:'Windows painter exited ('+code+')'});stop();});
+ const write=message=>{if(!stopping&&!helper.stdin.destroyed)helper.stdin.write(JSON.stringify(message)+'\n');};
+ const reader=createInterface({input:helper.stdout});
+ reader.on('line',line=>{
+  if(line.length>100000)return stop();let m;try{m=JSON.parse(line);}catch{return stop();}
+  try{
+   if(m.type==='ready'){pickerVisible=m.pickerVisible===true;sendParent({running:true,windowPicker:pickerVisible,mode:'windows-overlay',pid:process.pid});}
+   else if(m.type==='picker')pickerVisible=m.visible===true;
+   else if(m.type==='viewport'){pendingViewport=m;visible=m.visible;selected=m.selected===true;pump?.viewport(m);}
+   else if(m.type==='ack'){frames++;if(m.painted)paintedFrames++;pump?.ack();}
+   else if(m.type==='pause')pump?.pause(m.paused);
+   else if(m.type==='interact'){const accepted=pump?.interact(m.kind)??false;lastInteraction={kind:m.kind,accepted};write({type:'interaction',kind:m.kind,accepted});}
+   else if(m.type==='quit')stop();
+  }catch(error){write({type:'error',message:error.message});stop();}
+ });
+ const {createPet}=await import('../../retrieviewer.mjs');const pet=await createPet();
+ if(stopping)pet.dispose();else{
+  pump=createFramePump({pet,send:write});if(pendingViewport)pump.viewport(pendingViewport);
+  write({type:'loaded'});timer=setInterval(()=>{try{pump.tick();}catch(error){write({type:'error',message:error.message});stop();}},1000/30);
+ }
+}catch(error){sendParent({error:error.message});await stop();}

package/locomotion-core.mjs

@@ -0,0 +1,21 @@
+import * as THREE from 'three';
+import {createAnimal} from './vendor/procedural-animals/src/index.js';
+export const LAB_OPTIONS={variant:'retriever',age:'juvenile',seed:2,quality:'low',worker:false,overrides:{colour:'yellow',stanceSoftMargin:.005}};
+export async function makeLabAnimal(extra={}){
+ return createAnimal('dog',{...LAB_OPTIONS,...extra,overrides:{...LAB_OPTIONS.overrides,...extra.overrides}});
+}
+// Never translate the mesh externally. The gait engine owns root motion + IK.
+export function makeLabController(animal){
+ let target=null,speed=animal.gears.walk;
+ return {get target(){return target;},get speed(){return speed;},setSpeed(kind){
+  if(!['walk','trot','gallop'].includes(kind))throw Error('Unknown gait');
+  speed=animal.gears[kind];if(target)animal.moveTo(target,{speed});
+ },go(x,z){
+  if(![x,z].every(Number.isFinite))throw Error('Invalid ground target');
+  target=new THREE.Vector3(Math.max(-.8,Math.min(.8,x)),0,Math.max(-1.7,Math.min(.3,z)));
+  animal.stopAction();animal.moveTo(target,{speed});
+ },stop(){target=null;animal.stop();},update(dt){
+  if(!Number.isFinite(dt)||dt<0||dt>.1)throw Error('Invalid lab step');animal.update(dt);
+  if(target&&animal.position.distanceTo(target)<.025&&animal.speed<.03){target=null;animal.stop();}
+ }};
+}

package/package.json

@@ -1,6 +1,133 @@
 {
   "name": "@bitefoundry/retrieviewer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "A fluffy Braille desktop companion for Windows apps, plus an embeddable TUI pet. Give it a ball or a treat.",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://github.com/BiteFoundry",
+  "keywords": ["tui", "braille", "pet", "retriever", "opencode", "desktop-pet", "windows", "overlay"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "private": false,
+  "type": "module",
+  "types": "./retrieviewer.d.mts",
+  "bin": {
+    "retrieviewer": "retrieviewer-cli.mjs",
+    "retrieviewer-stdio": "retrieviewer-stdio.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./retrieviewer.d.mts",
+      "default": "./retrieviewer.mjs"
+    },
+    "./plugin": {
+      "types": "./retrieviewer-plugin.d.mts",
+      "default": "./retrieviewer-plugin.mjs"
+    },
+    "./tui": "./integrations/opencode/tui.tsx",
+    "./opencode/tui": "./integrations/opencode/tui.tsx",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "LICENSE",
+    "LICENSE-CODE",
+    "ASSETS-LICENSE.md",
+    "ATTRIBUTION.md",
+    "ASSET-PROVENANCE.md",
+    "THIRD-PARTY-NOTICES.md",
+    "TRADEMARKS.md",
+    "RELEASING.md",
+    "retrieviewer.mjs",
+    "retrieviewer.d.mts",
+    "retrieviewer-stdio.mjs",
+    "retrieviewer-plugin.mjs",
+    "retrieviewer-plugin.d.mts",
+    "retrieviewer-cli.mjs",
+    "retrieviewer-install.mjs",
+    "retrieviewer-config.mjs",
+    "integrations/opencode/tui.tsx",
+    "integrations/opencode/runtime.mjs",
+    "integrations/windows-overlay/protocol.mjs",
+    "integrations/windows-overlay/desktop.mjs",
+    "integrations/windows-overlay/worker.mjs",
+    "integrations/windows-overlay/Overlay.cs",
+    "WINDOWS-COMPANION.md",
+    "INSTALLING.md",
+    "PLUGIN.md",
+    "EMBEDDING.md",
+    "PUPPY-MEMORY.md",
+    "PUPPY-Q5-COMPARISON.md",
+    "examples/embed.mjs",
+    "examples/live.mjs",
+    "examples/plugin.mjs",
+    "examples/bridge.py",
+    "locomotion-core.mjs",
+    "locomotion-puppy.animal",
+    "braille.mjs",
+    "puppy-frame-store.mjs",
+    "puppy-frame-predictive.mjs",
+    "pet-q5-manifest.json",
+    "puppy-paper.mjs",
+    "puppy-paper-world.mjs",
+    "puppy-paper-contact.mjs",
+    "puppy-paper-seat.mjs",
+    "puppy-paper-director.mjs",
+    "puppy-paper-behaviors.mjs",
+    "puppy-paper-area.mjs",
+    "puppy-paper-actions.mjs",
+    "puppy-paper-trick-timing.mjs",
+    "puppy-paper-paw-transport.mjs",
+    "puppy-companion-life.mjs",
+    "puppy-companion-objects.mjs",
+    "puppy-companion-sprites.mjs",
+    "puppy-mouth-anchor.mjs",
+    "puppy-mouth-anchor.json",
+    "puppy-clean.mjs",
+    "puppy-stable.mjs",
+    "puppy-face.mjs",
+    "puppy-continuous.mjs",
+    "puppy-zoomies.mjs",
+    "puppy-zoomies30.mjs",
+    "puppy-stride-tweens-q5.bin.gz",
+    "puppy-stride-meta.json",
+    "puppy-stable-meta.json",
+    "puppy-paper-rear-gallop-q5.bin.gz",
+    "puppy-paper-rear-gallop.json",
+    "puppy-paper-approach-q5.bin.gz",
+    "puppy-paper-approach.json",
+    "puppy-paper-seat-q5.bin.gz",
+    "puppy-paper-seat.json",
+    "puppy-paper-arrival-seat-q5.bin.gz",
+    "puppy-paper-arrival-seat.json",
+    "puppy-paper-behaviors-q5.bin.gz",
+    "puppy-paper-behaviors.json",
+    "puppy-paper-actions-v9-q5.bin.gz",
+    "puppy-paper-actions-v9.json",
+    "puppy-companion-interactions-v3-q5.bin.gz",
+    "puppy-companion-interactions-v3.json",
+    "vendor/procedural-animals/src",
+    "vendor/procedural-animals/LICENSE",
+    "vendor/procedural-animals/package.json"
+  ],
+  "scripts": {
+    "start": "node server.mjs",
+    "terminal": "node terminal.mjs",
+    "pet": "node puppy-terminal.mjs",
+    "pet:companion": "node examples/live.mjs",
+    "pet:desktop": "node retrieviewer-cli.mjs desktop",
+    "test": "node --test \"*.test.mjs\"",
+    "test:locomotion": "node check-locomotion.mjs",
+    "test:package": "node check-pet-package.mjs",
+    "release:check": "node tools/check-release.mjs",
+    "prepublishOnly": "npm run release:check"
+  },
+  "dependencies": {
+    "jsonc-parser": "3.3.1",
+    "three": "0.186.1"
+  }
+}

package/pet-q5-manifest.json

@@ -0,0 +1,118 @@
+{
+ "version": 1,
+ "levels": 32,
+ "entries": {
+  "puppy-stride-tweens": {
+   "file": "puppy-stride-tweens-q5.bin.gz",
+   "width": 320,
+   "height": 320,
+   "frames": 799,
+   "uniqueFrames": 683,
+   "sourceSha256": "15e8ef49947cec4a1dcb3393d43a2ad48125d1bcd30f01275087c3df61627392",
+   "sourcePackedSha256": "439c8d235492ebb1e11cdb2f4cb1078b7840f14c0586c15544cb984d06d1047b",
+   "encodedBytes": 44585401,
+   "gzipBytes": 7564304,
+   "residentPixelBytes": 27752723,
+   "encodedSha256": "eecf92fd402843bef43aa4b154db6eba999959dd16cd8e34c54e42c88eaade10",
+   "quantizedSha256": "a74614dc210b245e5f8a4dba6a8cfb9b11b8da8dba9e2537fab53458ba27f02c"
+  },
+  "puppy-paper-rear-gallop": {
+   "file": "puppy-paper-rear-gallop-q5.bin.gz",
+   "width": 320,
+   "height": 320,
+   "frames": 162,
+   "uniqueFrames": 143,
+   "sourceSha256": "75972598be42314b92e64487106e3103ad477f897705dda869fc0b10cf68e256",
+   "sourcePackedSha256": "0c2d70643ef5807f1fa3e489abd65e0e9871041a8b45ea1027f94439601a3677",
+   "encodedBytes": 8770545,
+   "gzipBytes": 1468318,
+   "residentPixelBytes": 5456694,
+   "encodedSha256": "fe96e31d30348cc7d1fc674f40778d2312c9d1b40c57e634dcc397a35cc5ccf4",
+   "quantizedSha256": "a072f3a3f729f96556767b93d4921f76e32bc517aa06fb50f87fcb27fd05396c"
+  },
+  "puppy-paper-approach": {
+   "file": "puppy-paper-approach-q5.bin.gz",
+   "width": 320,
+   "height": 320,
+   "frames": 162,
+   "uniqueFrames": 139,
+   "sourceSha256": "f5558c57d5a445d396e06c060f9f8d64e6ce0ff5b9b92fa6d77ef9bb2984a2fe",
+   "sourcePackedSha256": "53bd77c5d06012b9b99884d2b38c499f0bcb9a42007736ef3d1cfffaba3c6ebf",
+   "encodedBytes": 7089140,
+   "gzipBytes": 1442754,
+   "residentPixelBytes": 4407560,
+   "encodedSha256": "6f57a5f506eabea41c00f02738c8124a4ae8e05471bdcd76e0a6e9ed739ca1a3",
+   "quantizedSha256": "c6e12fc09a7c314e65f7a115afb1e9cb865069cdd321c6f5483a92aa69517024"
+  },
+  "puppy-paper-seat": {
+   "file": "puppy-paper-seat-q5.bin.gz",
+   "width": 320,
+   "height": 320,
+   "frames": 51,
+   "uniqueFrames": 49,
+   "sourceSha256": "613dbeeeaec11804e80db0216922c8f62294745514ee6283bdce61a6d784dd5e",
+   "sourcePackedSha256": "2c34d1a34323e48e4ec73f60613ddacab9ff3814851275663fe573b00469e485",
+   "encodedBytes": 3326771,
+   "gzipBytes": 478093,
+   "residentPixelBytes": 2070312,
+   "encodedSha256": "b21aa11039b314ed3dec96818e571d54b6102bd0bc1f76e0a99ceb6d2b5ae097",
+   "quantizedSha256": "be0876275d124005ecb758b953f3a553a7f2748f5e3fd522612059f6fd81149a"
+  },
+  "puppy-paper-arrival-seat": {
+   "file": "puppy-paper-arrival-seat-q5.bin.gz",
+   "width": 320,
+   "height": 320,
+   "frames": 51,
+   "uniqueFrames": 49,
+   "sourceSha256": "13acb62fd573ff7ef97bcf59be80757897fe9d1784f187ab278990ff94a643b9",
+   "sourcePackedSha256": "014ee6e77802de49e9bcb77666867619b03688fd1a57040701904385a35dcd16",
+   "encodedBytes": 3332894,
+   "gzipBytes": 489164,
+   "residentPixelBytes": 2074316,
+   "encodedSha256": "3b2ef9e322e625340c42a549f17165492cc14f724f4593bf298f67195677bb6e",
+   "quantizedSha256": "77eb55a8922fda7f9a39c2b247eeb7098a3bacbf4c38d4652e7686650d9396aa"
+  },
+  "puppy-paper-behaviors": {
+   "file": "puppy-paper-behaviors-q5.bin.gz",
+   "width": 320,
+   "height": 320,
+   "frames": 162,
+   "uniqueFrames": 142,
+   "sourceSha256": "7918261fb64c57a91739729841fd84c6dd53891196c7fb76ee9c27712ab6ef5d",
+   "sourcePackedSha256": "7785ef65b8a2a5bf6f7ce600fe9957a60d9af82066ff49275bba061eac5392d1",
+   "encodedBytes": 7031343,
+   "gzipBytes": 1450156,
+   "residentPixelBytes": 4373034,
+   "encodedSha256": "38cfdfcee9c857c56a14f0a9734cb3301b4a04cb8e1ae3fb2e2b2ffe3666240f",
+   "quantizedSha256": "3c8f40416d2fff1c1031d3ad8917ea885998a786126d5973dfee4102893a0a53"
+  },
+  "puppy-paper-actions-v9": {
+   "file": "puppy-paper-actions-v9-q5.bin.gz",
+   "width": 480,
+   "height": 480,
+   "frames": 594,
+   "uniqueFrames": 474,
+   "sourceSha256": "1e0db7138d087292a3e70c246a1d56af590b3fb50928687a026e7080d7657c38",
+   "sourcePackedSha256": "ce5426d2fb9b2bb5d20b4f206215252954f9cc20d830d309a2d74ed441e37f02",
+   "encodedBytes": 24733003,
+   "gzipBytes": 4614142,
+   "residentPixelBytes": 15388998,
+   "encodedSha256": "615fb04961a38e592a661a20ad50fad45e1e4205e34198fa87a155ace966ea77",
+   "quantizedSha256": "fd1f23fe5dbd79bcf3cb9e060b9adfa0948cd4423e4b19e5810671e42ee952be"
+  },
+  "puppy-companion-interactions-v3": {
+   "file": "puppy-companion-interactions-v3-q5.bin.gz",
+   "width": 320,
+   "height": 320,
+   "frames": 360,
+   "uniqueFrames": 124,
+   "sourceSha256": "8438ee6cfc52b28f8e327bf37453c8e5ad7d568b2569cd4c5ed1e051d7026905",
+   "sourcePackedSha256": "deb8a3618451087fdae102f16ef7528c79c91b249844db1bfa9f9399c5355051",
+   "encodedBytes": 8023311,
+   "gzipBytes": 1150175,
+   "residentPixelBytes": 4992197,
+   "encodedSha256": "5ebfc58c9cfeaf349d30bc65be2e4663f7a3b8be9f35ca5d6da323172624de7a",
+   "quantizedSha256": "ebf86e2671234feb46a0933bb9c6d367c353d1b38a5bbf01e07c7b7f6183c1ea"
+  }
+ }
+}

package/puppy-clean.mjs

@@ -0,0 +1,51 @@
+import {stableAt,groundOffset,createStableZoomies} from './puppy-stable.mjs';
+import {createFaceMotion} from './puppy-face.mjs';
+import {grayFrameReader,isGrayFrameSource} from './puppy-frame-store.mjs';
+export const CLEAN_BYTES=47*17*320*320;
+export const STRIDE_TEMPO=.72;
+export function retimeRun(phase,knots){
+ if(!knots)return phase;
+ const count=knots.length-1;
+ if(count<2||count>20||knots[0]!==0||knots[count]!==20||knots.some((x,i)=>!Number.isFinite(x)||(i&&x<=knots[i-1])))throw Error('Invalid gait timing');
+ const tangent=i=>{i%=count;const before=i?knots[i]-knots[i-1]:20-knots[count-1],after=knots[i+1]-knots[i],w1=2*after+before,w2=after+2*before;return (w1+w2)/(w1*before+w2*after);};
+ let index=0;while(index<count-1&&phase>knots[index+1])index++;
+ const h=knots[index+1]-knots[index],p=Math.max(0,Math.min(1,(phase-knots[index])/h)),p2=p*p,p3=p2*p;
+ return (2*p3-3*p2+1)*index+(p3-2*p2+p)*h*tangent(index)+(-2*p3+3*p2)*(index+1)+(p3-p2)*h*tangent(index+1);
+}
+export function cleanAt(seconds,options={}){
+ const state=stableAt(seconds,{...options,tempo:options.tempo??(options.sequence?STRIDE_TEMPO:.6),quickLaunch:options.quickLaunch??!!options.sequence,easedTurns:true,rampRest:true});
+ if(state.state==='run'){
+  const phase=retimeRun(state.pair+state.blend,options.timing),index=Math.floor(phase),count=options.sequence?.length??20;
+  state.pair=index%count;state.pose=options.sequence?.[state.pair]??state.pair;state.blend=phase-index;
+ }
+ return state;
+}
+export function cleanGroundOffset(state,meta){
+ if(state.state==='run'&&meta.run_sequence){
+  const seq=meta.run_sequence,n=seq.length,i=state.pair,p=state.blend,v=meta.ground_offsets;
+  const a=v[seq[(i+n-1)%n]],b=v[seq[i]],c=v[seq[(i+1)%n]],d=v[seq[(i+2)%n]];
+  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);
+ }
+ if(state.pair<30||state.pair>40)return groundOffset(state,meta);
+ const i=state.pair,p=state.blend,v=meta.ground_offsets;
+ 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){
+ 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;
+ return state=>{
+  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;}
+  return output;
+ };
+}
+export function createCleanZoomies(atlas,cache,meta,cacheInfo,width,height,{secondaryMotion=true,quickLaunch=!!cacheInfo.run_sequence,sampleState=cleanAt,frameTransform,groundAt=cleanGroundOffset}={}){
+ const renderMeta=cacheInfo.pair_map?{...meta,pairs:cacheInfo.pair_map,run_sequence:cacheInfo.run_sequence}:meta;
+ if(cacheInfo.run_sequence){const seq=cacheInfo.run_sequence;if(seq.some((v,i)=>!Number.isInteger(v)||v<0||v>=20||renderMeta.pairs[i][0]!==v||renderMeta.pairs[i][1]!==seq[(i+1)%seq.length]))throw Error('Invalid curated gait');}
+ const tween=createCachedTween(cache,cacheInfo),face=secondaryMotion&&cacheInfo.run_sequence?createFaceMotion():null;
+ return createStableZoomies(atlas,null,renderMeta,width,height,{sampleState:(s,o)=>sampleState(s,{...o,quickLaunch,timing:cacheInfo.run_timing,sequence:cacheInfo.run_sequence}),frameProvider:state=>{const image=tween(state),moved=face?face(image,state):image;return frameTransform?frameTransform(moved,state):moved;},groundAt});
+}

package/puppy-companion-interactions-v3.json

@@ -0,0 +1 @@
+{"version":3,"width":320,"height":320,"samples":9,"pairs":40,"bytes":36864000,"sha256":"8438ee6cfc52b28f8e327bf37453c8e5ad7d568b2569cd4c5ed1e051d7026905","clips":{"treat-eat":[30,31,32,33,34,35,36,37,38,39],"ball-pickup":[13,14,15,16,17,18,19,20,21,22],"ball-drop":[23,24,25,26,27,28,29]},"edges":[[0,2],[2,3],[3,4],[4,5],[5,4],[5,6],[6,0],[0,7],[7,8],[8,9],[9,10],[10,11],[11,0],[0,1],[1,2],[2,3],[3,4],[4,5],[5,6],[6,7],[7,8],[8,9],[9,10],[10,11],[11,12],[12,13],[13,14],[14,15],[15,16],[16,0]],"ballSourceKeys":{"13":[0,1],"14":[1,2],"15":[2,3],"16":[3,4],"17":[4,5],"18":[5,6],"19":[6,7],"20":[7,8],"21":[8,9],"22":[9,10],"23":[10,11],"24":[11,12],"25":[12,13],"26":[13,14],"27":[14,15],"28":[15,16],"29":[16,0]},"sourceSequences":{"ball-pickup":[0,1,2,3,4,5,6,7,8,9,10],"ball-drop":[10,11,12,13,14,15,16,0]},"scale":0.7870722433460076,"registration":[{"cell":0,"matrix":[[0.7870722433460076,0.0,13.04942965779469],[0.0,0.7870722433460076,75.68441064638785]]},{"cell":1,"matrix":[[0.7870722433460076,0.0,-232.12357414448667],[0.0,0.7870722433460076,75.68441064638785]]},{"cell":2,"matrix":[[0.7870722433460076,0.0,-475.32889733840295],[0.0,0.7870722433460076,75.68441064638785]]},{"cell":3,"matrix":[[0.7870722433460076,0.0,-718.5342205323193],[0.0,0.7870722433460076,74.89733840304183]]},{"cell":4,"matrix":[[0.7870722433460076,0.0,10.688212927756666],[0.0,0.7870722433460076,-162.01140684410643]]},{"cell":5,"matrix":[[0.7870722433460076,0.0,-232.12357414448667],[0.0,0.7870722433460076,-162.01140684410643]]},{"cell":6,"matrix":[[0.7870722433460076,0.0,-476.115969581749],[0.0,0.7870722433460076,-162.01140684410643]]},{"cell":7,"matrix":[[0.7870722433460076,0.0,-718.9277566539923],[0.0,0.7870722433460076,-162.01140684410643]]},{"cell":8,"matrix":[[0.7870722433460076,0.0,12.655893536121681],[0.0,0.7870722433460076,-407.57794676806077]]},{"cell":9,"matrix":[[0.7870722433460076,0.0,-231.7300380228137],[0.0,0.7870722433460076,-407.57794676806077]]},{"cell":10,"matrix":[[0.7870722433460076,0.0,-474.93536121673003],[0.0,0.7870722433460076,-407.57794676806077]]},{"cell":11,"matrix":[[0.7870722433460076,0.0,-718.5342205323193],[0.0,0.7870722433460076,-407.57794676806077]]},{"cell":12,"matrix":[[0.7870722433460076,0.0,12.262357414448672],[0.0,0.7870722433460076,-647.6349809885932]]},{"cell":13,"matrix":[[0.7870722433460076,0.0,-232.12357414448667],[0.0,0.7870722433460076,-646.8479087452471]]},{"cell":14,"matrix":[[0.7870722433460076,0.0,-474.14828897338396],[0.0,0.7870722433460076,-647.6349809885932]]},{"cell":15,"matrix":[[0.7870722433460076,0.0,-718.9277566539923],[0.0,0.7870722433460076,-647.6349809885932]]}],"neutralSha256":"0b0584bd032ddf41d62f02c5064547d667e84eea9b8a74e3ff2d7043abb5eb78","sourceHashes":{"puppy-companion-interactions-v2.bin.gz":"75d682c0eaab31dd01038f36fd6da425eaee6cb92afc8857e06e3013e3307724","puppy-interactions12-v1-sheet.png":"e3931afbd935355734f9448f12495edb269547cadba30dcd36265ea9e4cf7afd","puppy-paper-seat.bin.gz":"a863225bef502fa3d60fe97c85007a9e85b818d53e5c3b5490fddd80b0c100d9","prepare-companion-interactions-v3.py":"d0d195683d2869f9bf5a94e8c8195d00cb5caf3caa4099c49cc20e384592da73"},"method":"v2 ball sprites byte-exact; treat is full original generated sprite, one source scale, no head/torso mask and no ghost-frame morph","treatSourceKeys":{"30":[0,1],"31":[1,2],"32":[2,3],"33":[3,4],"34":[4,5],"35":[5,4],"36":[4,5],"37":[5,6],"38":[6,1],"39":[1,0]},"treatKeyHashes":["0b0584bd032ddf41d62f02c5064547d667e84eea9b8a74e3ff2d7043abb5eb78","0870c83bbd95da39680c4297fb2a7c08fafb296578f7e872de31ace3736e303d","fe95b5930e429cb1e42ca5c6c06e500c4c30446164ece075fd580d85f8a014e0","2533e5d855f56867c2d0650da1644a175e414145c03a29e43281996094e14e67","a75805e1a40004160a07275db03cc74310950bb8200ca6ca71566706e6a8d776","51b81c3433ba2ee74127a39386bf725d654c72bffbf6cfcbe475107cf1d13cdb","d11f159c000b2e432a77dd3d922d7f51435db5f2a9799f55290d3dedc9c88636"],"treatScale":0.6124260355029586,"treatRegistration":[{"cell":0,"matrix":[[0.6124260355029586,0.0,36.39497041420118],[0.0,0.6124260355029586,57.47928994082841]]},{"cell":1,"matrix":[[0.6124260355029586,0.0,-149.47633136094674],[0.0,0.6124260355029586,56.25443786982248]]},{"cell":2,"matrix":[[0.6124260355029586,0.0,-335.3476331360947],[0.0,0.6124260355029586,56.86686390532543]]},{"cell":3,"matrix":[[0.6124260355029586,0.0,-521.8313609467456],[0.0,0.6124260355029586,56.25443786982248]]},{"cell":4,"matrix":[[0.6124260355029586,0.0,37.00739644970413],[0.0,0.6124260355029586,-181.36686390532543]]},{"cell":5,"matrix":[[0.6124260355029586,0.0,-148.8639053254438],[0.0,0.6124260355029586,-181.36686390532543]]}]}

package/puppy-companion-life.mjs

@@ -0,0 +1,182 @@
+// Autonomous companion "life" controller layered over a paper puppy actor.
+// The parent calls actor.update(dt) THEN life.update(dt). Commands are only issued
+// while the actor rests at a shared safe endpoint (idle/down); everything else waits.
+// Exception: an accepted ball throw reacts at once via actor.chase (the actor owns safe
+// interruption); actors without chase fall back to go at the next safe endpoint.
+// Parameters are authored for feel, not canine science.
+
+const SAFE=new Set(['idle','down']);
+const HOME={x:0,z:.2};
+const BALL_TARGET={x:0,z:-4};
+const OFFER={x:0,z:.3};
+// Hand-fed treat marker, relative to the puppy's current root (no travel for treats).
+const TREAT_OFFSET={z:.08,height:.25};
+const COOLDOWN={ball:6,treat:15};
+const FLIGHT=.65,BALL_PEAK=.75,CARRY_HEIGHT=.19,SETTLE_FALLBACK=.6,MAX_DT=.25,ARRIVE=.05;
+const LABEL={
+ start:'기다리는 중',pause:'잠시 느긋하게 둘러보는 중',lie:'엎드리는 중',rest:'엎드려 쉬는 중',recover:'앉아서 기운 차리는 중',
+ sit:'앉는 중',watch:'앉아서 지켜보는 중',look:'고개를 돌려 살피는 중',observe:'가만히 주변 관찰 중',
+ stroll:'옆으로 살짝 걸어가는 중',sniff:'잠깐 멈춰 주변을 살피는 중',dash:'저 멀리 달려가는 중',far:'멀리서 둘러보는 중',home:'제자리로 돌아오는 중',
+ fetch:'공을 쫓아가는 중',pickup:'공을 무는 중',carry:'공을 물고 돌아오는 중',drop:'공을 내려놓는 중',offer:'공을 내려놓고 기다리는 중',
+ treatSit:'간식 앞에 앉는 중',chew:'간식 먹는 중'
+};
+const PENDING_LABEL={treat:'곧 간식'};
+// Baked interaction clips, played only while holding at the shared seated endpoint.
+const GESTURE={'ball-pickup':1.4,'ball-drop':1.2,'treat-eat':2.4};
+const clamp=(v,a,b)=>Math.min(b,Math.max(a,v));
+
+function mulberry32(seed){
+ let a=seed>>>0;
+ return()=>{a=a+0x6d2b79f5>>>0;let t=a;t=Math.imul(t^t>>>15,t|1);t^=t+Math.imul(t^t>>>7,t|61);return((t^t>>>14)>>>0)/4294967296;};
+}
+
+export function createCompanionLife(actor,{seed=731,energy=.8}={}){
+ for(const name of ['update','sample','go','come','sit','lie','look','walk','roll','rest'])
+  if(!actor||typeof actor[name]!=='function')throw TypeError(`actor.${name} must be a function`);
+ if(!Number.isInteger(seed))throw TypeError('seed must be an integer');
+ if(!Number.isFinite(energy)||energy<0||energy>1)throw RangeError('energy must be within 0..1');
+
+ const rand=mulberry32(seed),range=(a,b)=>a+(b-a)*rand(),side=()=>rand()<.5?'left':'right';
+ const needs={energy,social:.5,curiosity:.5};
+ const cooldowns={ball:0,treat:0};
+ let clock=0,decisions=0,lastEpisode=null;
+ let queue=[],hold=0,holdIntent=null,waiting=null,gesture=null;
+ let intent='start',label=LABEL.start,pending=null,active=null,ball=null,treat=null;
+
+ const cmd=(name,args,step,when)=>({cmd:name,args,intent:step,label:LABEL[step],when});
+ const wait=(seconds,step)=>({hold:seconds,intent:step,label:LABEL[step]});
+ const play=(clip,step)=>({hold:GESTURE[clip],gesture:clip,intent:step,label:LABEL[step]});
+ // Skip sit() when the actor already rests in the canonical front-seated endpoint.
+ const unseated=()=>{const s=actor.sample(clock);return !(actor.state==='idle'&&s.seatProgress===1&&s.view==='approach'&&(s.seatVariant??'default')==='default');};
+ // Treats accept any seat variant at the front-seated endpoint: the hand comes to the puppy.
+ const seatedAnyVariant=()=>{const s=actor.sample(clock);return actor.state==='idle'&&s.seatProgress===1&&s.view==='approach';};
+ const fx=fn=>({fx:fn});
+ const home=()=>cmd('go',[HOME.x,HOME.z],'home');
+
+ // Each episode is a short coherent plan; a pause always leads in so autonomy never stalls.
+ const EPISODES={
+  rest:()=>[cmd('lie',[],'lie'),wait(range(10,18),'rest'),cmd('sit',[],'recover'),wait(range(3,6),'recover')],
+  watch:()=>[cmd('sit',[],'sit'),cmd('look',[side()],'look'),wait(range(3,9),'watch'),fx(()=>{needs.social-=.3;needs.curiosity+=.1;})],
+  observe:()=>[cmd('look',[side()],'look'),wait(range(3,9),'observe'),fx(()=>{needs.curiosity-=.15;})],
+  stroll:()=>[cmd('walk',[side(),range(.08,.18)],'stroll'),wait(range(2,4),'sniff'),home(),fx(()=>{needs.energy-=.08;needs.curiosity-=.2;})],
+  dash:()=>[cmd('go',[(rand()*2-1)*.18,-range(3,8)],'dash'),wait(range(1.5,3),'far'),home(),fx(()=>{needs.energy-=.3;needs.curiosity-=.4;})]
+ };
+ const weights=()=>{
+  const {energy:e,social:s,curiosity:c}=needs;
+  return {rest:e<.35?6:(1-e)*1.2,watch:.8+s,observe:.6+c*.6,stroll:1.2*c*e,dash:e>.55?1.2*e*c:0};
+ };
+ function decide(){
+  const w=weights();if(lastEpisode)w[lastEpisode]=0;
+  const kinds=Object.keys(w),total=kinds.reduce((sum,k)=>sum+w[k],0);
+  let pick=rand()*total,kind=kinds.find(k=>(pick-=w[k])<0)??'observe';
+  lastEpisode=kind;decisions++;
+  queue=[wait(range(3,9),'pause'),...EPISODES[kind]()];
+ }
+
+ const landed=()=>ball?.mode==='flight'&&clock-ball.start>=FLIGHT;
+ const arrived=()=>{const s=actor.sample(clock);return SAFE.has(actor.state)&&Math.hypot(s.x-BALL_TARGET.x,s.z-BALL_TARGET.z)<ARRIVE;};
+ // The leading go is dropped when interact() already dispatched the chase; pickup waits for both arrival and landing.
+ const BALL_STEPS=()=>[
+  cmd('go',[BALL_TARGET.x,BALL_TARGET.z],'fetch'),{until:()=>landed()&&arrived()},
+  fx(()=>{ball={mode:'ground',x:BALL_TARGET.x,z:BALL_TARGET.z};}),
+  cmd('sit',[],'pickup'),play('ball-pickup','pickup'),fx(()=>{ball={mode:'carried'};}),cmd('go',[HOME.x,HOME.z],'carry'),
+  cmd('sit',[],'drop',unseated),play('ball-drop','drop'),
+  fx(()=>{ball={mode:'ground',x:OFFER.x,z:OFFER.z};needs.social-=.4;}),wait(3,'offer'),fx(()=>{ball=null;})
+ ];
+ // Hand-feed where the puppy already is: sit only if not front-seated, never go/walk/chase/come.
+ const TREAT_STEPS=()=>[
+  fx(()=>{treat=true;}),cmd('sit',[],'treatSit',()=>!seatedAnyVariant()),
+  play('treat-eat','chew'),fx(()=>{treat=null;needs.energy+=.25;needs.social-=.3;})
+ ];
+
+ function startInteraction(){
+  active=pending;pending=null;decisions++;hold=0;
+  queue=active==='ball'?BALL_STEPS():TREAT_STEPS();
+ }
+ function finishInteraction(){cooldowns[active]=COOLDOWN[active];active=null;}
+
+ function drift(dt){
+  const resting=holdIntent==='rest'||holdIntent==='recover';
+  needs.energy+=resting?.04*dt:-.004*dt;
+  if(!active){needs.curiosity+=.01*dt;needs.social+=.008*dt;}
+  for(const k in needs)needs[k]=clamp(needs[k],0,1);
+ }
+
+ function update(dt){
+  if(typeof dt!=='number'||!Number.isFinite(dt)||dt<0)throw RangeError('dt must be a finite non-negative number');
+  dt=Math.min(dt,MAX_DT);clock+=dt;
+  for(const k in cooldowns)cooldowns[k]=Math.max(0,cooldowns[k]-dt);
+  drift(dt);
+  const safe=SAFE.has(actor.state);
+  if(waiting){
+   waiting.age+=dt;if(!safe)waiting.left=true;
+   if(!safe||(!waiting.left&&waiting.age<SETTLE_FALLBACK))return;
+   waiting=null;
+  }
+  if(hold>0){
+   hold-=dt;if(gesture)gesture.elapsed+=dt;
+   if(pending&&!active&&safe)hold=0;
+   if(hold>0)return;
+  }
+  holdIntent=null;gesture=null;
+  if(!safe)return;
+  if(pending&&!active)startInteraction();
+  // Run instant effects; stop at the first hold or issued command (at most one command per update).
+  for(;;){
+   if(!queue.length){
+    if(active){finishInteraction();if(pending)startInteraction();else decide();}
+    else decide();
+   }
+   const step=queue.shift();
+   if(step.fx){step.fx();for(const k in needs)needs[k]=clamp(needs[k],0,1);continue;}
+   if(step.until){if(step.until())continue;queue.unshift(step);return;}
+   if(step.when&&!step.when())continue;
+   intent=step.intent;label=step.label;
+   if(step.hold!==undefined){hold=step.hold;holdIntent=step.intent;if(step.gesture)gesture={clip:step.gesture,duration:step.hold,elapsed:0};return;}
+   if(actor[step.cmd](...step.args)!==false)waiting={age:0,left:false};
+   return;
+  }
+ }
+
+ function interact(kind){
+  if(kind!=='ball'&&kind!=='treat')return false;
+  if(pending||active||cooldowns[kind]>0)return false;
+  if(kind==='treat'){pending=kind;return true;}
+  // Ball: launch now and drop obsolete controller plans; the actor's own state is left to chase.
+  active='ball';decisions++;ball={mode:'flight',start:clock};
+  queue=BALL_STEPS();hold=0;holdIntent=null;gesture=null;waiting=null;
+  intent='fetch';label=LABEL.fetch;
+  const urgent=typeof actor.chase==='function';
+  if((urgent||SAFE.has(actor.state))&&actor[urgent?'chase':'go'](BALL_TARGET.x,BALL_TARGET.z)!==false)queue.shift();
+  return true;
+ }
+
+ // Recomputed from the live pose so the marker stays truthful before and after sitting.
+ function treatReport(){
+  if(!treat)return null;
+  const s=actor.sample(clock);return {x:s.x,z:s.z+TREAT_OFFSET.z,height:TREAT_OFFSET.height};
+ }
+ function ballReport(){
+  if(!ball)return null;
+  if(ball.mode==='flight'){
+   const p=clamp((clock-ball.start)/FLIGHT,0,1);
+   if(p===1)return {x:BALL_TARGET.x,z:BALL_TARGET.z,height:0,carried:false};
+   return {x:HOME.x+(BALL_TARGET.x-HOME.x)*p,z:HOME.z+(BALL_TARGET.z-HOME.z)*p,height:4*BALL_PEAK*p*(1-p),carried:false};
+  }
+  if(ball.mode==='carried'){const s=actor.sample(clock);return {x:s.x,z:s.z,height:CARRY_HEIGHT,carried:true};}
+  return {x:ball.x,z:ball.z,height:0,carried:false};
+ }
+
+ return {
+  update,interact,
+  get report(){
+   const interaction=active??pending;
+   return {
+    intent,label:pending?`${label} · ${PENDING_LABEL[pending]}`:label,interaction,busy:interaction!==null,
+    ball:ballReport(),treat:treatReport(),energy:needs.energy,decisions,cooldowns:{...cooldowns},
+    // Local hold clock only: progress freezes between updates; null outside the stationary hold.
+    gesture:gesture&&SAFE.has(actor.state)?{clip:gesture.clip,progress:clamp(gesture.elapsed/gesture.duration,0,1)}:null
+   };
+  }
+ };
+}

package/puppy-companion-objects.mjs

@@ -0,0 +1,30 @@
+// Small physical toys in the SAME fixed camera as the puppy, before Braille
+// conversion. No minimum thumbnail size, DOM overlay, sprite zoom or new dog art.
+// mouth: renderer.lastMouth for the frame just painted. A carried ball sits on that
+// measured drawn mouth only; without one (side/rear/unmeasured pose) it is hidden.
+export function paintCompanionObjects(pixels,width,height,projection,report,state,mouth=null){
+ const objects=[];
+ // Interaction drawings already include the toy/food. Never paint a second
+ // floating ball over the baked mouth, or a biscuit through the puppy's chest.
+ if(report.gesture)return pixels;
+ if(report.ball?.carried){if(mouth&&[mouth.x,mouth.y,mouth.rx,mouth.ry].every(Number.isFinite)&&mouth.rx>0&&mouth.ry>0)objects.push({kind:'ball',screen:mouth});}
+ else if(report.ball)objects.push({...report.ball,radius:.035,kind:'ball'});
+ if(report.treat)objects.push({...report.treat,height:report.treat.height??.018,radius:.022,kind:'treat'});
+ for(const o of objects){
+  let cx,cy,rx,ry;
+  if(o.screen)({x:cx,y:cy,rx,ry}=o.screen);
+  else{
+   const p=projection.project(o.x,o.height??0,o.z),edge=projection.project(o.x+o.radius,o.height??0,o.z);
+   cx=p.x*width;cy=p.y*height;rx=Math.abs(edge.x-p.x)*width;
+   const up=projection.project(o.x,(o.height??0)+o.radius,o.z);ry=Math.abs(up.y-p.y)*height;
+  }
+  if(![cx,cy,rx,ry].every(Number.isFinite)||rx<=0||ry<=0)continue;
+  for(let y=Math.max(0,Math.floor(cy-ry));y<Math.min(height,Math.ceil(cy+ry));y++)
+   for(let x=Math.max(0,Math.floor(cx-rx));x<Math.min(width,Math.ceil(cx+rx));x++){
+    const u=(x+.5-cx)/rx,v=(y+.5-cy)/ry;if(u*u+v*v>1)continue;
+    const tone=o.kind==='treat'?((x+y)%3?190:85):Math.abs(v+.25*u)<.18?85:225;
+    const j=(y*width+x)*4;pixels[j]=pixels[j+1]=pixels[j+2]=tone;
+   }
+ }
+ return pixels;
+}

package/puppy-companion-sprites.mjs

@@ -0,0 +1,14 @@
+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){
+ 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');
+ const frames=grayFrameReader(bytes,320,320,info.pairs*9),rgba=new Uint8ClampedArray(n*4);for(let i=3;i<rgba.length;i+=4)rgba[i]=255;
+ 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;
+ };
+}