@bitefoundry/retrieviewer 0.0.2 → 0.0.4

package/integrations/opencode/tui.tsx

@@ -43,7 +43,7 @@ export default Plugin.define({
    commands:[{
     id:'retrieviewer.pet',
     title:'Retrieviewer pet',
-    description:'enable | disable | ball | treat | status',
+    description:'enable | disable | ball | treat | tug | status',
     group:'Retrieviewer',
     palette:true,
     slash:{name:'retrieviewer',arguments:true},

package/integrations/windows-overlay/Overlay.cs

@@ -111,10 +111,10 @@ sealed class Companion : ApplicationContext {
     TargetItem target;Form pickerWindow;QuietWindow testTarget;readonly bool testMode;Rectangle canvas;int revision=0,cell=8;bool visible=false,paused=false,loaded=false,quitting=false,picking=false,announced=false;
     Label status=new Label();Mutex mutex;
     internal Companion(Mutex single,bool diagnostic){
-        mutex=single;testMode=diagnostic;bar.Text="Retrieviewer controls";bar.Size=new Size(354,40);bar.BackColor=Color.FromArgb(28,30,34);bar.ForeColor=Color.White;
+        mutex=single;testMode=diagnostic;bar.Text="Retrieviewer controls";bar.Size=new Size(404,40);bar.BackColor=Color.FromArgb(28,30,34);bar.ForeColor=Color.White;
         bar.Font=new Font("Segoe UI",9);bar.Controls.Add(MakeButton("공",8,()=>Interact("ball")));bar.Controls.Add(MakeButton("간식",52,()=>Interact("treat")));
-        bar.Controls.Add(MakeButton("창",102,ChooseTarget));bar.Controls.Add(MakeButton("쉼",146,TogglePause));bar.Controls.Add(MakeButton("종료",190,Quit));
-        status.AutoSize=false;status.Location=new Point(240,12);status.Size=new Size(110,22);status.Text="준비 중";bar.Controls.Add(status);
+        bar.Controls.Add(MakeButton("터그",102,()=>Interact("tug")));bar.Controls.Add(MakeButton("창",152,ChooseTarget));bar.Controls.Add(MakeButton("쉼",196,TogglePause));bar.Controls.Add(MakeButton("종료",240,Quit));
+        status.AutoSize=false;status.Location=new Point(290,12);status.Size=new Size(110,22);status.Text="준비 중";bar.Controls.Add(status);
         ContextMenuStrip menu=new ContextMenuStrip();menu.Items.Add("다른 창 선택",null,(s,e)=>ChooseTarget());menu.Items.Add("숨기기 / 다시 표시",null,(s,e)=>TogglePause());menu.Items.Add("종료",null,(s,e)=>Quit());
         tray.Icon=SystemIcons.Application;tray.Text="Retrieviewer · 창 선택";tray.ContextMenuStrip=menu;tray.Visible=true;tray.DoubleClick+=(s,e)=>ChooseTarget();
         // Handles are created on the UI thread before the reader can signal EOF.
@@ -127,7 +127,7 @@ sealed class Companion : ApplicationContext {
         }
     }
     Button MakeButton(string title,int x,Action action){
-        Button b=new Button();b.Text=title;b.TabStop=false;b.Size=new Size(title=="간식"?46:40,28);b.Location=new Point(x,6);b.FlatStyle=FlatStyle.Flat;b.FlatAppearance.BorderSize=0;b.BackColor=Color.FromArgb(48,51,58);b.ForeColor=Color.White;b.Click+=(s,e)=>action();return b;
+        Button b=new Button();b.Text=title;b.TabStop=false;b.Size=new Size(title=="간식"||title=="터그"?46:40,28);b.Location=new Point(x,6);b.FlatStyle=FlatStyle.Flat;b.FlatAppearance.BorderSize=0;b.BackColor=Color.FromArgb(48,51,58);b.ForeColor=Color.White;b.Click+=(s,e)=>action();return b;
     }
     void ReadInput(){
         try{

package/integrations/windows-overlay/desktop.mjs

@@ -1,4 +1,4 @@
-// Explicit Windows companion launcher. Never imports the pet on help/status/stop.
+// Explicit native companion launcher. Never imports the pet on help/status/stop.
 import {spawn,execFile} from 'node:child_process';
 import {promisify} from 'node:util';
 import {readFile,mkdir,lstat,unlink,open,rename,readdir} from 'node:fs/promises';
@@ -7,6 +7,7 @@ import {join,dirname} from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {createConnection} from 'node:net';
 import {getConfigPaths} from '../../retrieviewer-config.mjs';
+import {desktopPlatform,validControlAddress} from '../desktop/platform.mjs';
 const exec=promisify(execFile);
 const SOURCE=new URL('./Overlay.cs',import.meta.url);
 export function desktopPaths(options={}){const root=join(getConfigPaths(options).root,'desktop');return {root,session:join(root,'session.json')};}
@@ -17,7 +18,7 @@ export async function prepareRoot(options={}){
 export async function readSession(options={}){
  const {root,session}=desktopPaths(options);await noLink(dirname(root));await noLink(root);await noLink(session);
  let data;try{data=JSON.parse(await readFile(session,'utf8'));}catch(e){if(e.code==='ENOENT')return null;throw e;}
- if(data?.owner!=='bitefoundry-retrieviewer-overlay-v1'||!Number.isInteger(data.pid)||data.pid<=0||!/^\\\\\.\\pipe\\retrieviewer-overlay-[a-f0-9-]{36}$/.test(data.pipe)||!/^[a-f0-9]{64}$/.test(data.token))throw Error('Unrecognized desktop session; not modifying it');
+ if(data?.owner!=='bitefoundry-retrieviewer-overlay-v1'||!Number.isInteger(data.pid)||data.pid<=0||!validControlAddress(data.pipe)||!/^[a-f0-9]{64}$/.test(data.token))throw Error('Unrecognized desktop session; not modifying it');
  return data;
 }
 export function requestSession(session,command){
@@ -30,21 +31,37 @@ export function requestSession(session,command){
   socket.on('error',e=>finish(e));socket.on('end',()=>{if(!done)finish(Error('Desktop control closed without a response'));});
  });
 }
+async function processAlive(pid){
+ try{process.kill(pid,0);}catch(error){if(error.code==='ESRCH')return false;throw error;}
+ if(process.platform==='linux')try{
+  // A container PID1 without a reaper can retain a dead detached worker as Z.
+  // kill(pid,0) alone treats it as alive, falsely making a successful stop fail.
+  const stat=await readFile('/proc/'+pid+'/stat','utf8'),state=stat.slice(stat.lastIndexOf(')')+2).charAt(0);
+  if(state==='Z'||state==='X')return false;
+ }catch(error){if(error.code==='ENOENT')return false;throw error;}
+ return true;
+}
 export async function desktopStatus(options={}){
  const session=await readSession(options);if(!session)return {running:false};
- try{return await requestSession(session,'status');}catch(error){let alive=true;try{process.kill(session.pid,0);}catch(e){if(e.code==='ESRCH')alive=false;}
+ try{return await requestSession(session,'status');}catch(error){const alive=await processAlive(session.pid);
   return {running:alive,reachable:false,stale:!alive,pid:session.pid,reason:error.code??error.message};}
 }
 export async function stopDesktop(options={}){
  const session=await readSession(options);if(!session)return {running:false,stopped:true};
  const result=await desktopStatus(options);
- if(result.stale){await unlink(desktopPaths(options).session);return {running:false,stopped:true,staleSessionRemoved:true};}
+ if(result.stale){
+  if(session.pipe.startsWith('/tmp/')){
+   await noLink(session.pipe);
+   try{const entry=await lstat(session.pipe);if(!entry.isSocket()||(process.getuid&&entry.uid!==process.getuid()))throw Error('Refusing unowned/non-socket desktop endpoint');await unlink(session.pipe);}catch(e){if(e.code!=='ENOENT')throw e;}
+  }
+  await unlink(desktopPaths(options).session);return {running:false,stopped:true,staleSessionRemoved:true};
+ }
  if(result.reachable===false)throw Error('Desktop process is not responding; close it from its tray icon. No PID was killed.');
  await requestSession(session,'stop');
  // The stop response acknowledges the request, not native process termination.
  // Wait before advertising success so a following cleanup cannot race an in-use exe.
  for(let i=0;i<60;i++){
-  try{process.kill(session.pid,0);}catch(e){if(e.code==='ESRCH')return {running:false,stopped:true};throw e;}
+  if(!await processAlive(session.pid))return {running:false,stopped:true};
   await new Promise(resolve=>setTimeout(resolve,100));
  }
  throw Error('Desktop accepted stop but has not exited; cache preserved. Retry after it closes.');
@@ -53,7 +70,7 @@ export async function buildHelper(options={}){
  if(process.platform!=='win32')throw Error('The transparent companion currently supports Windows only');
  const {root}=await prepareRoot(options),source=await readFile(SOURCE),hash=createHash('sha256').update(source).digest('hex').slice(0,20);
  const executable=join(root,`overlay-${hash}.exe`);await noLink(executable);
- try{await lstat(executable);return executable;}catch(e){if(e.code!=='ENOENT')throw e;}
+ try{if(!(await lstat(executable)).isFile())throw Error('Desktop helper cache is not a regular file');return executable;}catch(e){if(e.code!=='ENOENT')throw e;}
  const compiler=join(process.env.SystemRoot??'C:\\Windows','Microsoft.NET','Framework64','v4.0.30319','csc.exe');
  const temporary=join(root,`build-${randomUUID()}.exe`);
  try{
@@ -62,12 +79,27 @@ export async function buildHelper(options={}){
  }catch(error){await unlink(temporary).catch(()=>{});throw Error('Windows overlay build failed: '+(error.stdout??error.message));}
  return executable;
 }
+export async function desktopHelper(options={}){
+ const platform=desktopPlatform(options);
+ if(platform.helper==='windows')return {command:await buildHelper(options),args:[],mode:platform.id,fps:platform.fps};
+ if(platform.helper==='macos')return {command:'/usr/bin/osascript',args:['-l','JavaScript',fileURLToPath(new URL('../macos-overlay/overlay.jxa',import.meta.url))],mode:platform.id,fps:platform.fps};
+ // Use an existing system Python, including AlmaLinux8's3.6 platform interpreter.
+ // No Python package, compiled addon, native bundle, compiler, or package manager.
+ const candidates=[...(process.env.RETRIEVIEWER_PYTHON?[process.env.RETRIEVIEWER_PYTHON]:[]),'python3','/usr/libexec/platform-python'];
+ for(const command of candidates)try{
+  await exec(command,['-I','-c','import sys;sys.exit(0 if sys.version_info >= (3,6) else 1)'],{windowsHide:true,timeout:5000,maxBuffer:4096});
+  return {command,args:['-I',fileURLToPath(new URL('../linux-overlay/overlay.py',import.meta.url))],mode:platform.id,fps:platform.fps};
+ }catch{}
+ throw Error('Linux desktop needs system Python3.6+ (AlmaLinux8 platform-python is supported). No packages or system settings were installed.');
+}
 export async function startDesktop(options={}){
+ // Fail before creating any cache/session on unsupported desktops (e.g. Wayland).
+ desktopPlatform(options);
  const status=await desktopStatus(options);if(status.running)return {...status,alreadyRunning:true};
  if(status.stale)await stopDesktop(options);
- const executable=await buildHelper(options);
+ const helper=await desktopHelper(options);
  return new Promise((resolve,reject)=>{
-  const child=spawn(process.execPath,[fileURLToPath(new URL('./worker.mjs',import.meta.url)),executable],{detached:true,windowsHide:true,stdio:['ignore','ignore','ignore','ipc'],env:{...process.env,RETRIEVIEWER_HOME:getConfigPaths(options).root}});
+  const child=spawn(process.execPath,[fileURLToPath(new URL('./worker.mjs',import.meta.url)),'--helper-spec',JSON.stringify(helper)],{detached:true,windowsHide:true,stdio:['ignore','ignore','ignore','ipc'],env:{...process.env,RETRIEVIEWER_HOME:getConfigPaths(options).root}});
   let settled=false;const finish=(error,message)=>{if(settled)return;settled=true;clearTimeout(timer);if(child.connected)child.disconnect();child.unref();error?reject(error):resolve(message);};
   const timer=setTimeout(()=>{if(child.connected)child.send({command:'abort'});finish(Error('Desktop startup timed out; no agent settings changed'));},20000);
   child.on('error',error=>finish(error));child.on('message',message=>message.error?finish(Error(message.error)):finish(null,message));child.on('exit',code=>finish(Error('Desktop exited during startup ('+code+')')));

package/integrations/windows-overlay/protocol.mjs

@@ -20,20 +20,24 @@ export function cropFrame(frame,revision){
 
 // Request/ack rendering: never queue obsolete frames behind a slow native painter.
 export function createFramePump({pet,send,now=()=>performance.now()}){
- let viewport=null,inFlight=false,last=null,revision=0,paused=false,disposed=false;
+ let viewport=null,inFlight=false,last=null,lastFrame=null,revision=0,paused=false,disposed=false;
  const alive=()=>{if(disposed)throw Error('Overlay pump is disposed');};
  return {
-  viewport(message){alive();const next=viewportOf(message);revision=message.revision;viewport=next;last=null;},
-  pause(value){alive();paused=!!value;last=null;},
+  viewport(message){alive();const next=viewportOf(message);revision=message.revision;viewport=next;last=null;lastFrame=null;},
+  pause(value){alive();paused=!!value;last=null;lastFrame=null;},
   ack(){alive();inFlight=false;},
   tick(){
    alive();if(inFlight||!viewport||paused)return false;
    const t=now(),dt=last===null?0:Math.max(0,(t-last)/1000);last=t;
-   pet.step(dt);const frame=pet.frame(viewport);inFlight=true;
-   try{send(cropFrame(frame,revision));}catch(error){inFlight=false;throw error;}return true;
+   pet.step(dt);const frame=cropFrame(pet.frame(viewport),revision);
+   // A held seat/down pose can be byte-identical for seconds. Advance the life
+   // clock normally but avoid JSON, IPC, bitmap allocation and native repaint.
+   if(lastFrame&&frame.x===lastFrame.x&&frame.y===lastFrame.y&&frame.columns===lastFrame.columns&&frame.rows===lastFrame.rows&&frame.text===lastFrame.text)return false;
+   inFlight=true;
+   try{send(frame);lastFrame=frame;}catch(error){inFlight=false;throw error;}return true;
   },
-  interact(kind){alive();if(!['ball','treat'].includes(kind))throw Error('Invalid overlay interaction');return pet.interact(kind);},
+  interact(kind){alive();if(!['ball','treat','tug'].includes(kind))throw Error('Invalid overlay interaction');const accepted=pet.interact(kind);if(accepted)lastFrame=null;return accepted;},
   get hidden(){return !viewport||paused;},
-  dispose(){if(!disposed){disposed=true;viewport=null;pet.dispose();}},
+  dispose(){if(!disposed){disposed=true;viewport=lastFrame=null;pet.dispose();}},
  };
 }

package/integrations/windows-overlay/worker.mjs

@@ -2,12 +2,15 @@
 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 {open,unlink,readFile,chmod} from 'node:fs/promises';
 import {randomBytes,randomUUID} from 'node:crypto';
 import {prepareRoot,noLink} from './desktop.mjs';
 import {createFramePump} from './protocol.mjs';
+import {controlAddress,parseHelperSpec} from '../desktop/platform.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;
+let nativeError=null;
+let nativeStderr='';
 const sendParent=message=>{if(process.connected)process.send(message);};
 async function stop(){
  if(stopping)return;stopping=true;clearInterval(timer);pump?.dispose();
@@ -20,8 +23,9 @@ async function stop(){
 }
 process.on('SIGTERM',stop);process.on('SIGINT',stop);process.on('message',m=>{if(m?.command==='abort')stop();});
 try{
+ const spec=parseHelperSpec(process.argv.slice(2));
  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')};
+ session={owner:'bitefoundry-retrieviewer-overlay-v1',pid:process.pid,pipe:controlAddress({uuid: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='';
@@ -34,16 +38,18 @@ try{
   });
  });
  await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(session.pipe,resolve);});
+ if(process.platform!=='win32')await chmod(session.pipe,0o600);
  // 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();});
+ helper=spawn(spec.command,spec.args,{windowsHide:false,stdio:['pipe','pipe','pipe']});
+ helper.stdin.on('error',()=>stop());helper.stderr.setEncoding('utf8');helper.stderr.on('data',s=>{nativeStderr=(nativeStderr+s).slice(-4096);});helper.once('error',error=>{sendParent({error:error.message});stop();});
+ helper.once('exit',code=>{if(!stopping)sendParent({error:nativeError??('Desktop painter exited ('+code+')'+(nativeStderr?' — '+nativeStderr.trim():''))});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});}
+   if(m.type==='ready'){pickerVisible=m.pickerVisible===true;sendParent({running:true,windowPicker:pickerVisible,mode:spec.mode,pid:process.pid});}
+   else if(m.type==='error'){nativeError=String(m.message??'Desktop painter failed');sendParent({error:nativeError});stop();}
    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();}
@@ -55,6 +61,6 @@ try{
  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);
+  write({type:'loaded'});timer=setInterval(()=>{try{pump.tick();}catch(error){write({type:'error',message:error.message});stop();}},1000/spec.fps);
  }
 }catch(error){sendParent({error:error.message});await stop();}

package/package.json

@@ -1,10 +1,28 @@
 {
   "name": "@bitefoundry/retrieviewer",
-  "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.",
+  "version": "0.0.4",
+  "description": "A fluffy Braille desktop pet for Windows and Linux X11, with experimental macOS support and an embeddable TUI engine.",
   "license": "SEE LICENSE IN LICENSE",
-  "homepage": "https://github.com/BiteFoundry",
-  "keywords": ["tui", "braille", "pet", "retriever", "opencode", "desktop-pet", "windows", "overlay"],
+  "homepage": "https://bitefoundry.github.io/retrieviewer/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BiteFoundry/retrieviewer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BiteFoundry/retrieviewer/issues"
+  },
+  "keywords": [
+    "tui",
+    "braille",
+    "pet",
+    "retriever",
+    "opencode",
+    "desktop-pet",
+    "windows",
+    "linux",
+    "macos",
+    "overlay"
+  ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
@@ -56,18 +74,25 @@
     "integrations/windows-overlay/desktop.mjs",
     "integrations/windows-overlay/worker.mjs",
     "integrations/windows-overlay/Overlay.cs",
+    "integrations/desktop/platform.mjs",
+    "integrations/linux-overlay/overlay.py",
+    "integrations/linux-overlay/README.md",
+    "integrations/macos-overlay/overlay.jxa",
+    "integrations/macos-overlay/README.md",
+    "DESKTOP-PLATFORMS.md",
     "WINDOWS-COMPANION.md",
     "INSTALLING.md",
+    "PREREQUISITES.md",
+    "README.ko.md",
     "PLUGIN.md",
     "EMBEDDING.md",
     "PUPPY-MEMORY.md",
     "PUPPY-Q5-COMPARISON.md",
+    "COMFORT-ART.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",
@@ -85,6 +110,7 @@
     "puppy-companion-life.mjs",
     "puppy-companion-objects.mjs",
     "puppy-companion-sprites.mjs",
+    "puppy-comfort-sprites.mjs",
     "puppy-mouth-anchor.mjs",
     "puppy-mouth-anchor.json",
     "puppy-clean.mjs",
@@ -110,24 +136,25 @@
     "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"
+    "puppy-companion-comfort-q5.bin.gz",
+    "puppy-companion-comfort.json",
+    "vendor/procedural-animals/LICENSE"
   ],
   "scripts": {
-    "start": "node server.mjs",
-    "terminal": "node terminal.mjs",
-    "pet": "node puppy-terminal.mjs",
+    "start": "node tools/preview-site.mjs",
+    "build:site": "node tools/build-site.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",
+    "jsonc-parser": "3.3.1"
+  },
+  "devDependencies": {
+    "playwright": "1.64.1",
     "three": "0.186.1"
   }
 }

package/puppy-comfort-sprites.mjs

@@ -0,0 +1,25 @@
+import {grayFrameReader,isGrayFrameSource} from './puppy-frame-store.mjs';
+
+// A handful of authored keys, not an expanded 30fps film or a live image morph.
+// First/last keys are the exact shared seated source; all keys use one scale.
+export function comfortFrameIndex(progress,info){
+ if(!Number.isFinite(progress)||progress<0||progress>1)throw Error('Invalid comfort progress');
+ const seconds=progress*6;
+ if(seconds<.12||progress===1)return 0;
+ if(seconds<.65)return seconds<.3?1:2;
+ if(seconds>5.15)return seconds<5.45?7:seconds<5.8?8:0;
+ const loop=[3,4,3,5,3,6,3,5,3,4,3,6];
+ return loop[Math.floor((seconds-.65)/.28)%loop.length];
+}
+
+export function createComfortSpriteSampler(bytes,info){
+ if(!isGrayFrameSource(bytes)||info?.version!==1||info.width!==320||info.height!==320||info.frames!==9)throw Error('Invalid comfort sprites');
+ const frames=grayFrameReader(bytes,320,320,info.frames);let rgba=null;
+ return pose=>{
+  if(pose?.clip!=='tug')throw Error('Invalid comfort clip');
+  if(!rgba){rgba=new Uint8ClampedArray(320*320*4);for(let i=3;i<rgba.length;i+=4)rgba[i]=255;}
+  const index=comfortFrameIndex(pose.progress,info),frame=frames.getFrame(index);
+  for(let i=0,j=0;i<frame.length;i++,j+=4)rgba[j]=rgba[j+1]=rgba[j+2]=frame[i];
+  return rgba;
+ };
+}

package/puppy-companion-comfort.json

@@ -0,0 +1,77 @@
+{
+  "version": 1,
+  "width": 320,
+  "height": 320,
+  "frames": 9,
+  "clips": [
+    "tug"
+  ],
+  "gzipBytes": 103549,
+  "residentPixelBytes": 291337,
+  "sourceSheetSha256": "10fde9dacca5cb45acd68f387e7ed3bcf88cd72cf0f9c4220d31d819db91731e",
+  "neutralSha256": "19f89a8bcb5a937e528593a8f36db846a0d45a5ee398f1b0873c056e5be2fa0a",
+  "encodedSha256": "e046e214da585ffda65e8d2c1a86c589af589325b792634f128ab8b71f6dbf3a",
+  "method": "Built-in imagegen authored tug keys. One fixed scale, ground/center translation only. Exact existing Q5 seat first/last. No expanded tween film or live body deformation.",
+  "registration": {
+    "sheetSize": [
+      1774,
+      887
+    ],
+    "targetBounds": [
+      41,
+      92,
+      231,
+      301
+    ],
+    "registration": [
+      {
+        "cell": 0,
+        "scale": 0.5663956639566395,
+        "dx": 32,
+        "dy": 69
+      },
+      {
+        "cell": 1,
+        "scale": 0.5663956639566395,
+        "dx": 39,
+        "dy": 69
+      },
+      {
+        "cell": 2,
+        "scale": 0.5663956639566395,
+        "dx": 39,
+        "dy": 69
+      },
+      {
+        "cell": 3,
+        "scale": 0.5663956639566395,
+        "dx": 35,
+        "dy": 68
+      },
+      {
+        "cell": 4,
+        "scale": 0.5663956639566395,
+        "dx": 33,
+        "dy": 74
+      },
+      {
+        "cell": 5,
+        "scale": 0.5663956639566395,
+        "dx": 39,
+        "dy": 74
+      },
+      {
+        "cell": 6,
+        "scale": 0.5663956639566395,
+        "dx": 39,
+        "dy": 74
+      },
+      {
+        "cell": 7,
+        "scale": 0.5663956639566395,
+        "dx": 36,
+        "dy": 74
+      }
+    ]
+  }
+}

package/puppy-companion-life.mjs

@@ -11,16 +11,18 @@ 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 COOLDOWN={ball:6,treat:15,tug:20};
 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:'제자리로 돌아오는 중',
+ patrol:'주변을 왕복 산책하는 중',scan:'양쪽을 번갈아 살피는 중',roll:'느긋하게 뒹구는 중',play:'신나서 한 바퀴 도는 중',checkin:'가까이 와서 함께 쉬는 중',
+ belly:'배를 보이고 발라당 쉬는 중',sleep:'새근새근 잠자는 중',tug:'장난감을 물고 당기는 중',
  fetch:'공을 쫓아가는 중',pickup:'공을 무는 중',carry:'공을 물고 돌아오는 중',drop:'공을 내려놓는 중',offer:'공을 내려놓고 기다리는 중',
  treatSit:'간식 앞에 앉는 중',chew:'간식 먹는 중'
 };
-const PENDING_LABEL={treat:'곧 간식'};
+const PENDING_LABEL={treat:'곧 간식',tug:'곧 터그놀이'};
 // 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));
@@ -38,7 +40,8 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
 
  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};
+ const cooldowns={ball:0,treat:0,tug:0};
+ const episodeCooldowns={roll:0,play:0,belly:0,sleep: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;
@@ -51,25 +54,44 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
  // 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');
+ const home=()=>cmd('go',[HOME.x,HOME.z],'home',()=>{const s=actor.sample(clock);return Math.hypot(s.x-HOME.x,s.z-HOME.z)>ARRIVE;});
+ const sit=step=>cmd('sit',[],step,()=>!seatedAnyVariant());
+ const lie=()=>cmd('lie',[],'lie',()=>actor.state!=='down');
+ const walkTo=x=>cmd('walk',()=>{const dx=x-actor.sample(clock).x;return [dx<0?'left':'right',Math.abs(dx)];},'patrol',()=>Math.abs(x-actor.sample(clock).x)>.002);
 
  // 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;})],
+  rest:()=>[lie(),wait(range(10,18),'rest'),sit('recover'),wait(range(3,6),'recover')],
+  watch:()=>[sit('sit'),cmd('look',[side()],'look'),wait(range(3,9),'watch'),fx(()=>{needs.social-=.3;needs.curiosity+=.1;})],
+  observe:()=>[sit('sit'),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;})]
+  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;})],
+  scan:()=>[sit('sit'),cmd('look',['left'],'scan'),wait(range(.5,1.5),'scan'),cmd('look',['right'],'scan'),wait(range(2,4),'observe'),fx(()=>{needs.curiosity-=.25;})],
+  patrol:()=>{const x=actor.sample(clock).x,d=range(.16,.3)*(rand()<.5?-1:1);return [walkTo(x+d),wait(range(.6,1.2),'sniff'),walkTo(x-d),wait(range(.6,1.2),'sniff'),walkTo(x),wait(range(1,3),'observe'),fx(()=>{needs.energy-=.1;needs.curiosity-=.25;})];},
+  roll:()=>[lie(),wait(range(.7,1.5),'rest'),cmd('roll',[],'roll'),wait(range(2,5),'watch'),fx(()=>{needs.energy-=.08;needs.curiosity-=.15;})],
+  checkin:()=>[home(),sit('sit'),cmd('look',[side()],'look'),wait(range(5,10),'checkin'),fx(()=>{needs.social-=.4;})],
+  play:()=>[cmd('spin',[],'play'),wait(range(1,2),'pause'),sit('sit'),wait(range(2,4),'watch'),fx(()=>{needs.energy-=.12;needs.curiosity-=.2;})],
+  belly:()=>[cmd('belly',[range(5,9)],'belly'),wait(range(2,4),'watch'),fx(()=>{needs.energy+=.08;needs.curiosity-=.15;})],
+  sleep:()=>[cmd('sleep',[range(22,38)],'sleep'),wait(range(2,4),'recover'),fx(()=>{needs.energy+=.3;})],
  };
  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};
+  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,
+   scan:.35+c*.4,patrol:e>.25?.7*c*e:0,checkin:.25+s*.7,
+   roll:episodeCooldowns.roll===0&&e>.45?.35*e:0,
+   play:episodeCooldowns.play===0&&e>.6&&typeof actor.spin==='function'?.25*e*c:0,
+   belly:episodeCooldowns.belly===0&&typeof actor.belly==='function'?.35:0,
+   sleep:episodeCooldowns.sleep===0&&typeof actor.sleep==='function'?(e<.4?3:.2):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++;
+  if(kind==='roll')episodeCooldowns.roll=90;
+  if(kind==='play')episodeCooldowns.play=120;
+  if(kind==='belly')episodeCooldowns.belly=80;
+  if(kind==='sleep')episodeCooldowns.sleep=100;
   queue=[wait(range(3,9),'pause'),...EPISODES[kind]()];
  }
 
@@ -88,15 +110,18 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   fx(()=>{treat=true;}),cmd('sit',[],'treatSit',()=>!seatedAnyVariant()),
   play('treat-eat','chew'),fx(()=>{treat=null;needs.energy+=.25;needs.social-=.3;})
  ];
+ const TUG_STEPS=()=>[
+  cmd('sit',[],'tug',unseated),cmd('tug',[6],'tug'),wait(.5,'watch'),fx(()=>{needs.energy-=.12;needs.social-=.4;})
+ ];
 
  function startInteraction(){
   active=pending;pending=null;decisions++;hold=0;
-  queue=active==='ball'?BALL_STEPS():TREAT_STEPS();
+  queue=active==='ball'?BALL_STEPS():active==='tug'?TUG_STEPS():TREAT_STEPS();
  }
  function finishInteraction(){cooldowns[active]=COOLDOWN[active];active=null;}
 
  function drift(dt){
-  const resting=holdIntent==='rest'||holdIntent==='recover';
+  const resting=holdIntent==='rest'||holdIntent==='recover'||actor.state==='sleep'||intent==='belly';
   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);
@@ -106,6 +131,7 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   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);
+  for(const k in episodeCooldowns)episodeCooldowns[k]=Math.max(0,episodeCooldowns[k]-dt);
   drift(dt);
   const safe=SAFE.has(actor.state);
   if(waiting){
@@ -133,15 +159,21 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
    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};
+   if(actor[step.cmd](...(typeof step.args==='function'?step.args():step.args))!==false)waiting={age:0,left:false};
    return;
   }
  }
 
  function interact(kind){
-  if(kind!=='ball'&&kind!=='treat')return false;
+  if(!['ball','treat','tug'].includes(kind))return false;
+  if(kind==='tug'&&typeof actor.tug!=='function')return false;
   if(pending||active||cooldowns[kind]>0)return false;
-  if(kind==='treat'){pending=kind;return true;}
+  if(kind==='treat'||kind==='tug'){
+   pending=kind;
+   // The pet wakes through its authored recovery, not after a long sleep timer.
+   if(['sleep','belly'].includes(actor.sample(clock).state))actor.sit();
+   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;
@@ -172,8 +204,9 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   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},
+    intent,label:pending?`${label} · ${PENDING_LABEL[pending]}`:label,episode:lastEpisode,interaction,busy:interaction!==null,
+    ball:ballReport(),treat:treatReport(),tug:actor.state==='tug'?{progress:actor.sample(clock).comfortPose?.progress??0,grip:1}:null,
+    snore:actor.state==='sleep'?((clock%3.6)/3.6):null,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

@@ -7,6 +7,18 @@ export function paintCompanionObjects(pixels,width,height,projection,report,stat
  // 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;
+ // A quiet, tiny rising "z" suggests snoring. The sleeping dog itself remains
+ // the original eyes-closed source pose: no chest/body zoom or squashing.
+ if(Number.isFinite(report.snore)&&state.state==='sleep'){
+  const placement=projection.placement(state.x,state.z),side=height*placement.size,sideX=side/placement.pixelAspect;
+  const left=width*placement.x-sideX/2,top=height*placement.y-300/320*side;
+  const cycle=report.snore,tone=Math.round(140*Math.sin(Math.PI*cycle)),unit=Math.max(1,Math.round(side/160));
+  const cx=Math.round(left+220/320*sideX),cy=Math.round(top+(210-16*cycle)/320*side);
+  if(tone>12)for(const [gx,gy] of [[0,0],[1,0],[2,0],[1,1],[0,2],[1,2],[2,2]])for(let dy=0;dy<unit;dy++)for(let dx=0;dx<unit;dx++){
+   const x=cx+gx*unit+dx,y=cy+gy*unit+dy;if(x<0||x>=width||y<0||y>=height)continue;
+   const j=(y*width+x)*4;pixels[j]=pixels[j+1]=pixels[j+2]=Math.max(pixels[j],tone);
+  }
+ }
  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'});