@bitefoundry/retrieviewer 0.0.4 → 0.0.5

package/ASSET-PROVENANCE.md

@@ -35,6 +35,11 @@ must be checked again for the final release bytes.
 
 ## Remaining limits
 
+0.0.5 extends that ninth licensed archive with four sleeping studies generated
+from the same existing puppy identity/pose references, approved by the owner in
+this conversation. COMFORT-ART.md and the comfort metadata record preparation,
+source hashes and size changes. No new downloaded photo/video input is introduced.
+
 Later source candidate: belly/sleep reuse existing licensed roll/rest frames.
 Tug adds eight built-in imagegen keys referenced only from the existing generated
 puppy sheet, not new photographs. COMFORT-ART.md records the prompt, source hash

package/COMFORT-ART.md

@@ -1,5 +1,35 @@
 # Comfort extension art record
 
+## 0.0.5 sleeping studies
+
+Four owner-approved built-in imagegen originals (side, belly, curl, chin), using
+the existing `puppy-behaviors16-sheet.png` identity and `puppy-roll16-v4-sheet.png`
+pose references, extend the same CC BY-SA4.0 comfort archive. No new external
+photo or video input. Source PNGs remain local; metadata records SHA-256 hashes.
+Preparation: `node tools/prepare-sleep-art.mjs` with the preserved local studies.
+It keeps the nine existing tug keys pixel-identical and registers four new static
+keys to ground y=300. There are no duplicated right-facing images: source sampling
+reverses x. The pose is selected once per nap, not switched during a sleeping hold.
+A short rest-to-sleep/rest recovery blend uses existing scratch; the sleeping body
+itself is held, without scale pulsing. The z cue is silent.
+
+The archive grows from103549 to129148 bytes (+25599). Packed resident pixels grow
+from291337 to341139 (+49802 bytes). The renderer's mutually exclusive authored
+samplers now share one action-sized RGBA scratch, with320px subviews for smaller
+poses, replacing their separate buffers (2457600 bytes less before tug playback).
+Sleep display is capped at5fps in the desktop pump, while simulation advances
+normally and accepted interactions invalidate the next paint immediately.
+Ink presets only change the native painter color; no RGB sprite families or
+background capture are introduced. Actual RSS depends on host and allocator.
+
+The four prompts share: one complete naturally proportioned pale fluffy retriever,
+same bandana, closed eyes, grayscale fine fur on pure black, fixed slightly elevated
+camera, no text/bed/toy/background. Pose clauses: relaxed side sleep; belly-up with
+loosely bent paws and tiny tongue; loose curl with tail near muzzle; chin resting
+on forepaws. Source prompts and PNGs are preserved locally with the approved studies.
+
+The following section records the earlier0.0.4 preparation, not the new sleep keys.
+
 Source code MIT; generated puppy art and frame data CC BY-SA4.0, retaining the
 credits in ATTRIBUTION.md. This is a development-source record, not new legal
 clearance. No external photograph, YouTube frame or downloaded rig was introduced.

package/INSTALLING.md

@@ -6,6 +6,10 @@ Desktop setup (Node20+; [OS requirements and verification](DESKTOP-PLATFORMS.md)
 2. `retrieviewer desktop` — select the app window in the picker.
 
 No agent configuration is needed for this separate transparent companion.
+Choose the dot ink at launch: `retrieviewer desktop --ink gold`, or
+`retrieviewer desktop --ink dark` on light backgrounds. Default: `cream`.
+Exit an existing companion before changing ink. Presets reuse the same Braille
+mask and native painter, without new color sprites or screen capture.
 Windows and AlmaLinux8/GLIBC2.28 X11 have live test evidence. macOS support is
 experimental and not runtime verified; native Wayland is unsupported. Linux needs
 system Python3.6+, X11/Xrender/Xext and a compositor; Windows needs the .NET

package/README.ko.md

@@ -4,7 +4,8 @@
 <p align="center"><a href="https://bitefoundry.github.io/retrieviewer/?lang=ko">직접 만나 보기</a> · <a href="README.md">English</a> · <a href="https://www.npmjs.com/package/@bitefoundry/retrieviewer">npm</a> · <a href="https://github.com/BiteFoundry/retrieviewer/issues">피드백</a></p>
 
 앱 창 위에서 혼자 걷고, 뛰고, 앉아서 쉬는 보송한 점자 도트 리트리버예요.
-발라당 누워 쉬거나 눈을 감고 잠들기도 해요. 가끔 공·간식·터그로 놀아주세요.
+옆잠, 발라당, 몸 말기, 앞발에 턱 괴기. 조용하면 양쪽으로 누워 잠들어요.
+가끔 공·간식·터그로 놀아주세요.
 나머지 시간에는 각자의 일을 하면 돼요.
 [BiteFoundry](https://github.com/BiteFoundry)가 만듭니다.
 런타임에는 계정, 모델 API, 텔레메트리가 필요하지 않아요.
@@ -31,6 +32,11 @@ Node.js/npm이 없다면 [먼저 설치](PREREQUISITES.md)해 주세요.
 통과시킵니다. 앱 창 단위로 동작하고, 대상 창이 비활성화·최소화되면 숨습니다.
 자동 시작이나 셸 래퍼는 등록하지 않아요.
 
+도트 색은 실행할 때 고를 수 있어요. 기본은 크림색이고, 골드색은
+`retrieviewer desktop --ink gold`, 밝은 배경에는
+`retrieviewer desktop --ink dark`를 쓰세요. 실행 중이라면 먼저 종료하고 다시
+실행하세요. 배경을 캡처하지 않고, 같은 도트에 색만 바꿉니다.
+
 > **Cursor / VS Code Remote SSH 사용자:** 원격 서버의 터미널이 아닌,
 > Cursor 화면이 떠 있는 **로컬 PC의 PowerShell/터미널**에 설치하세요.
 > 서버의 `DISPLAY=:1`은 서버 쪽 X11 화면을 뜻합니다. VNC로 그 화면을 보고

package/README.md

@@ -40,6 +40,10 @@ click-through native overlay—not a patched app, shell wrapper or injected MCP
 widget. It follows a whole app window, not a tab, and hides when that window is
 inactive or minimized. No automatic startup entry is installed.
 
+Choose the dot color at launch: `retrieviewer desktop --ink gold`, or
+`retrieviewer desktop --ink dark` for light backgrounds. Default: `cream`.
+Quit a running companion first. Colors reuse the same artwork; no screen capture.
+
 > **Cursor / VS Code Remote SSH:** run those commands in your **local** computer's
 > terminal, not the remote server's terminal. The puppy belongs where the window
 > is displayed. A server's `DISPLAY=:1` refers to that server's X11 display, which

package/RELEASING.md

@@ -1,4 +1,13 @@
-# Retrieviewer 0.0.4 release process
+# Retrieviewer 0.0.5 release process
+
+Current target: `@bitefoundry/retrieviewer@0.0.5`, public `latest`. The owner
+explicitly requested npm publication and homepage update of the approved sleep
+studies and mirrored side on2026-10-23. This also includes manual ink presets,
+sleep pressure independent of energy, shared gesture scratch and5fps sleep paint.
+Preserve0.0.4 registry bytes; never republish them. Run all checks below and publish
+only the exact tested0.0.5 tarball. Four new approved keys stay under the existing
+CC BY-SA4.0 artwork terms; see COMFORT-ART.md. The historical scope below describes
+0.0.4, not current verification results.
 
 Target: `@bitefoundry/retrieviewer@0.0.4`, public npm registry, `latest` tag.
 The npm organization `bitefoundry` uses the free public-packages plan; account

package/integrations/linux-overlay/overlay.py

@@ -180,6 +180,12 @@ class Companion(object):
         if kind == 'quit':
             self.quit()
         elif kind == 'loaded':
+            palette = {'cream': (248, 242, 232), 'gold': (231, 184, 103), 'dark': (67, 48, 24)}
+            ink = message.get('ink', 'cream')
+            if ink not in palette:
+                raise OverlayError('Invalid ink')
+            self.tiles.ink = palette[ink]
+            self.tiles.cache.clear()
             self.loaded = True
             self.set_status('playing')
             if self.test_mode:

package/integrations/macos-overlay/overlay.jxa

@@ -238,7 +238,7 @@ function createCore(io, options) {
     if (s.quitting) return;
     if (!m || typeof m !== 'object') throw new Error('Invalid overlay message');
     if (m.type === 'quit') { quit(); return; }
-    if (m.type === 'loaded') { s.loaded = true; io.status(TEXT.playing); io.loaded(); return; }
+    if (m.type === 'loaded') { var palette = {cream:[248,242,232,245],gold:[231,184,103,245],dark:[67,48,24,245]}; var ink = m.ink || 'cream'; if (!Object.prototype.hasOwnProperty.call(palette,ink)) throw new Error('Invalid ink'); INK=palette[ink]; s.loaded = true; io.status(TEXT.playing); io.loaded(); return; }
     if (m.type === 'interaction') { io.status(m.accepted === true ? TEXT.accepted : TEXT.busy); return; }
     if (m.type === 'error') { io.status(TEXT.engineError); quit(); return; }
     if (m.type === 'frame') {

package/integrations/windows-overlay/Overlay.cs

@@ -61,6 +61,7 @@ class QuietWindow : Form {
 sealed class PetWindow : QuietWindow {
     protected override CreateParams CreateParams {get{CreateParams p=base.CreateParams;p.ExStyle|=0x80000|0x20;return p;}} // LAYERED + TRANSPARENT
     internal int PaintedDots;
+    internal Color Ink=Color.FromArgb(245,248,242,232);
     internal Bitmap PaintFrame(Dictionary<string,object> m,int cell,Rectangle canvas){
         int cols=Program.Int(m,"columns"),rows=Program.Int(m,"rows"),cx=Program.Int(m,"x"),cy=Program.Int(m,"y");
         string text=Program.Str(m,"text");
@@ -69,7 +70,7 @@ sealed class PetWindow : QuietWindow {
         string[] lines=text.Split('\n');if(lines.Length!=rows)throw new Exception("Invalid overlay row count");
         Bitmap image=new Bitmap(cols*cell,rows*cell*2,PixelFormat.Format32bppPArgb);
         try{
-            using(Graphics g=Graphics.FromImage(image))using(Brush ink=new SolidBrush(Color.FromArgb(245,248,242,232))){
+            using(Graphics g=Graphics.FromImage(image))using(Brush ink=new SolidBrush(Ink)){
                 g.Clear(Color.Transparent);g.SmoothingMode=System.Drawing.Drawing2D.SmoothingMode.AntiAlias;
                 int[] dx={0,0,0,1,1,1,0,1},dy={0,1,2,0,1,2,3,3};float step=cell/2f,diameter=Math.Max(1.1f,step*.48f);PaintedDots=0;
                 for(int y=0;y<rows;y++){
@@ -149,7 +150,7 @@ sealed class Companion : ApplicationContext {
             for(;;){Dictionary<string,object> m;lock(inputLock){if(messages.Count==0)break;m=messages.Dequeue();}
                 string type=Program.Str(m,"type");
                 if(type=="quit"){Quit();return;}
-                if(type=="loaded"){loaded=true;status.Text="함께 노는 중";if(testMode)((Button)bar.Controls[0]).PerformClick();continue;}
+                if(type=="loaded"){string ink=m.ContainsKey("ink")?Program.Str(m,"ink"):"cream";if(ink!="cream"&&ink!="gold"&&ink!="dark")throw new Exception("Invalid ink");pet.Ink=ink=="gold"?Color.FromArgb(245,231,184,103):ink=="dark"?Color.FromArgb(245,67,48,24):Color.FromArgb(245,248,242,232);loaded=true;status.Text="함께 노는 중";if(testMode)((Button)bar.Controls[0]).PerformClick();continue;}
                 if(type=="interaction"){status.Text=Program.Bool(m,"accepted")?"좋아!":"잠깐 기다려";continue;}
                 if(type=="error"){status.Text="엔진 오류";Quit();return;}
                 if(type=="frame"){

package/integrations/windows-overlay/desktop.mjs

@@ -93,13 +93,14 @@ export async function desktopHelper(options={}){
  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={}){
+ const ink=options.ink??'cream';if(!['cream','gold','dark'].includes(ink))throw Error('Invalid desktop ink');
  // 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 helper=await desktopHelper(options);
  return new Promise((resolve,reject)=>{
-  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}});
+  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,RETRIEVIEWER_INK:ink}});
   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,23 +20,25 @@ 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,lastFrame=null,revision=0,paused=false,disposed=false;
+ let viewport=null,inFlight=false,last=null,lastFrame=null,revision=0,paused=false,disposed=false,nextPaint=0;
  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;lastFrame=null;},
-  pause(value){alive();paused=!!value;last=null;lastFrame=null;},
+  viewport(message){alive();const next=viewportOf(message);revision=message.revision;viewport=next;last=null;lastFrame=null;nextPaint=0;},
+  pause(value){alive();paused=!!value;last=null;lastFrame=null;nextPaint=0;},
   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=cropFrame(pet.frame(viewport),revision);
+   pet.step(dt);if(t<nextPaint)return false;
+   const source=pet.frame(viewport),frame=cropFrame(source,revision);
+   nextPaint=source.state?.state==='sleep'?t+200:0;
    // 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','tug'].includes(kind))throw Error('Invalid overlay interaction');const accepted=pet.interact(kind);if(accepted)lastFrame=null;return accepted;},
+  interact(kind){alive();if(!['ball','treat','tug'].includes(kind))throw Error('Invalid overlay interaction');const accepted=pet.interact(kind);if(accepted){lastFrame=null;nextPaint=0;}return accepted;},
   get hidden(){return !viewport||paused;},
   dispose(){if(!disposed){disposed=true;viewport=lastFrame=null;pet.dispose();}},
  };

package/integrations/windows-overlay/worker.mjs

@@ -61,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/spec.fps);
+  write({type:'loaded',ink:process.env.RETRIEVIEWER_INK??'cream'});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,6 +1,6 @@
 {
   "name": "@bitefoundry/retrieviewer",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "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://bitefoundry.github.io/retrieviewer/",

package/puppy-comfort-sprites.mjs

@@ -12,14 +12,22 @@ export function comfortFrameIndex(progress,info){
  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;
+export function createComfortSpriteSampler(bytes,info,output){
+ if(!isGrayFrameSource(bytes)||![1,2].includes(info?.version)||info.width!==320||info.height!==320||info.frames!==(info.version===2?13:9))throw Error('Invalid comfort sprites');
+ if(output!==undefined&&(!(output instanceof Uint8ClampedArray)||output.length!==320*320*4))throw Error('Invalid comfort output');
+ const frames=grayFrameReader(bytes,320,320,info.frames);let rgba=output??null;
+ if(rgba)for(let i=3;i<rgba.length;i+=4)rgba[i]=255;
  return pose=>{
-  if(pose?.clip!=='tug')throw Error('Invalid comfort clip');
+  if(!['tug','sleep'].includes(pose?.clip))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];
+  const index=pose.clip==='sleep'?info.sleep?.[pose.variant]:comfortFrameIndex(pose.progress,info);
+  if(!Number.isInteger(index))throw Error('Invalid sleep variant');
+  const frame=frames.getFrame(index),base=pose.base,blend=pose.blend??1;
+  if(!Number.isFinite(blend)||blend<0||blend>1)throw Error('Invalid sleep blend');
+  for(let i=0,j=0;i<frame.length;i++,j+=4){
+   const v=frame[pose.right?Math.floor(i/320)*320+319-i%320:i];
+   rgba[j]=rgba[j+1]=rgba[j+2]=base&&blend<1?Math.round(base[j]+(v-base[j])*blend):v;
+  }
   return rgba;
  };
 }

package/puppy-companion-comfort.json

@@ -1,16 +1,17 @@
 {
-  "version": 1,
+  "version": 2,
   "width": 320,
   "height": 320,
-  "frames": 9,
+  "frames": 13,
   "clips": [
-    "tug"
+    "tug",
+    "sleep"
   ],
-  "gzipBytes": 103549,
-  "residentPixelBytes": 291337,
+  "gzipBytes": 129148,
+  "residentPixelBytes": 341139,
   "sourceSheetSha256": "10fde9dacca5cb45acd68f387e7ed3bcf88cd72cf0f9c4220d31d819db91731e",
   "neutralSha256": "19f89a8bcb5a937e528593a8f36db846a0d45a5ee398f1b0873c056e5be2fa0a",
-  "encodedSha256": "e046e214da585ffda65e8d2c1a86c589af589325b792634f128ab8b71f6dbf3a",
+  "encodedSha256": "35327cc103b1f7ac2ff1b09ed98658fd8ff1dcef322de9c9b18071a4358b7b87",
   "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": [
@@ -73,5 +74,67 @@
         "dy": 74
       }
     ]
+  },
+  "sleep": {
+    "side": 9,
+    "belly": 10,
+    "curl": 11,
+    "chin": 12
+  },
+  "sleepRegistration": [
+    {
+      "key": "side",
+      "sourceBounds": [
+        26,
+        461,
+        1234,
+        873
+      ],
+      "width": 254,
+      "scale": 0.21026490066225165,
+      "ground": 300
+    },
+    {
+      "key": "belly",
+      "sourceBounds": [
+        28,
+        413,
+        1239,
+        881
+      ],
+      "width": 224,
+      "scale": 0.18497109826589594,
+      "ground": 300
+    },
+    {
+      "key": "curl",
+      "sourceBounds": [
+        44,
+        373,
+        1213,
+        992
+      ],
+      "width": 216,
+      "scale": 0.1847733105218135,
+      "ground": 300
+    },
+    {
+      "key": "chin",
+      "sourceBounds": [
+        116,
+        435,
+        1218,
+        953
+      ],
+      "width": 198,
+      "scale": 0.17967332123411978,
+      "ground": 300
+    }
+  ],
+  "sleepSourceHashes": {
+    "side": "85c567eb0958a213ee5b93d0a8592639489f5f29dded35e0d1d22e920ed1fe9f",
+    "belly": "e1967d9156a119d04e25fd6428fe5dcdbd2156c5e4eba0347217847874006109",
+    "curl": "10c9a85701af3587c48c1d8158972a07026e79a18a2375d86108538eda05aae7",
+    "chin": "e971eaa6861b597f0dba3a487403cee5f120cba0a9f9584d831b5634d096dee7"
   }
 }

package/puppy-companion-life.mjs

@@ -39,10 +39,10 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
  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 needs={energy,social:.5,curiosity:.5,drowsiness: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 clock=0,decisions=0,lastEpisode=null,quiet=0;
  let queue=[],hold=0,holdIntent=null,waiting=null,gesture=null;
  let intent='start',label=LABEL.start,pending=null,active=null,ball=null,treat=null;
 
@@ -72,7 +72,7 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   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;})],
+  sleep:()=>[cmd('sleep',[range(65,110),['side','curl','chin','belly'][Math.floor(rand()*4)],rand()<.5],'sleep'),wait(range(2,4),'recover'),fx(()=>{needs.energy+=.3;})],
  };
  const weights=()=>{
   const {energy:e,social:s,curiosity:c}=needs;
@@ -87,6 +87,9 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   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';
+  // Quiet-time sleep pressure is independent of energy restored by sitting.
+  // Wait for the current coherent episode to end; never yank a running puppy.
+  if(quiet>=120&&needs.drowsiness>=.35&&episodeCooldowns.sleep===0&&lastEpisode!=='sleep'&&typeof actor.sleep==='function')kind='sleep';
   lastEpisode=kind;decisions++;
   if(kind==='roll')episodeCooldowns.roll=90;
   if(kind==='play')episodeCooldowns.play=120;
@@ -123,6 +126,9 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
  function drift(dt){
   const resting=holdIntent==='rest'||holdIntent==='recover'||actor.state==='sleep'||intent==='belly';
   needs.energy+=resting?.04*dt:-.004*dt;
+  const asleep=actor.state==='sleep';
+  needs.drowsiness+=asleep?-dt/60:dt/240;
+  quiet=active||pending||asleep?0:quiet+dt;
   if(!active){needs.curiosity+=.01*dt;needs.social+=.008*dt;}
   for(const k in needs)needs[k]=clamp(needs[k],0,1);
  }
@@ -168,6 +174,7 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   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;
+  quiet=0;
   if(kind==='treat'||kind==='tug'){
    pending=kind;
    // The pet wakes through its authored recovery, not after a long sleep timer.
@@ -206,7 +213,7 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
    return {
     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},
+    snore:actor.state==='sleep'?((clock%3.6)/3.6):null,energy:needs.energy,drowsiness:needs.drowsiness,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-sprites.mjs

@@ -1,11 +1,13 @@
 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){
+export function createCompanionSpriteSampler(bytes,info,output){
  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;
+ const frames=grayFrameReader(bytes,320,320,info.pairs*9),rgba=output??new Uint8ClampedArray(n*4);
+ if(!(rgba instanceof Uint8ClampedArray)||rgba.length!==n*4)throw Error('Invalid sprite output');
+ 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);

package/puppy-paper-actions.mjs

@@ -37,11 +37,13 @@ export function paperActionPose(name,progress,info){
  if(!Number.isFinite(blend))throw Error('Invalid paper action: blend');
  return{pair:list[index],blend};
 }
-export function createPaperActionSampler(bytes,info){
+export function createPaperActionSampler(bytes,info,output){
  if(!isGrayFrameSource(bytes))throw Error('Invalid action cache: bytes');
  validatePaperActionInfo(info,bytes.byteLength);
  const stride=info.width*info.height,pairs=info.pairs,frames=grayFrameReader(bytes,info.width,info.height,pairs*9);
- const out=new Uint8ClampedArray(stride*4);for(let i=3;i<out.length;i+=4)out[i]=255;
+ const out=output??new Uint8ClampedArray(stride*4);
+ if(!(out instanceof Uint8ClampedArray)||out.length!==stride*4)throw Error('Invalid action output');
+ for(let i=3;i<out.length;i+=4)out[i]=255;
  return state=>{const p=paperActionPose(state.actionName,state.actionProgress,info),sample=Math.round(p.blend*8);
   if(p.pair>=pairs||sample<0||sample>8)throw Error('Invalid paper action: sample out of range');
   const frame=frames.getFrame(p.pair*9+sample);for(let i=0,j=0;i<stride;i++,j+=4)out[j]=out[j+1]=out[j+2]=frame[i];return out;};

package/puppy-paper-behaviors.mjs

@@ -5,4 +5,4 @@ export function paperBehaviorPose(state,info){
  const q=Math.min(list.length-1e-9,progress*list.length),i=Math.floor(q),blend=Math.round((q-i)*8)/8;
  return{pair:list[i],blend};
 }
-export function createPaperBehaviorSampler(bytes,info){const sample=createRearSampler(bytes,info);return state=>{const p=paperBehaviorPose(state,info);return sample(p.pair,p.blend);};}
+export function createPaperBehaviorSampler(bytes,info,output){const sample=createRearSampler(bytes,info,output);return state=>{const p=paperBehaviorPose(state,info);return sample(p.pair,p.blend);};}

package/puppy-paper-contact.mjs

@@ -91,9 +91,11 @@ export function footSourcePoint(x,y,pins){
  return chosen?{x:x-chosen.dx*best,y:y-chosen.dy*best}:{x,y};
 }
 
-export function createRearSampler(bytes,info){
+export function createRearSampler(bytes,info,output){
  if(!isGrayFrameSource(bytes)||info.pairs!==18||info.samples!==9||bytes.byteLength!==18*9*320*320)throw Error('Invalid rear sprite cache');
- const frames=grayFrameReader(bytes,320,320,18*9),out=new Uint8ClampedArray(320*320*4);for(let i=3;i<out.length;i+=4)out[i]=255;
+ const frames=grayFrameReader(bytes,320,320,18*9),out=output??new Uint8ClampedArray(320*320*4);
+ if(!(out instanceof Uint8ClampedArray)||out.length!==320*320*4)throw Error('Invalid rear output');
+ for(let i=3;i<out.length;i+=4)out[i]=255;
  return(pair,blend)=>{
   if(!Number.isInteger(pair)||pair<0||pair>=18||!Number.isFinite(blend)||blend<0||blend>1)throw Error('Invalid rear pose');
   const frame=frames.getFrame(pair*9+Math.round(blend*8));

package/puppy-paper-seat.mjs

@@ -1,9 +1,11 @@
 import {grayFrameReader,isGrayFrameSource} from './puppy-frame-store.mjs';
 // Exact cached samples; no live crossfade. Reverse the same path to stand up.
-export function createPaperSeatSampler(bytes,info){
+export function createPaperSeatSampler(bytes,info,output){
  const stride=320*320;
  if(!isGrayFrameSource(bytes)||info.width!==320||info.height!==320||info.pairs!==3||info.samples!==17||bytes.byteLength!==3*17*stride)throw Error('Invalid paper sitting cache');
- const frames=grayFrameReader(bytes,320,320,3*17),out=new Uint8ClampedArray(stride*4);for(let i=3;i<out.length;i+=4)out[i]=255;
+ const frames=grayFrameReader(bytes,320,320,3*17),out=output??new Uint8ClampedArray(stride*4);
+ if(!(out instanceof Uint8ClampedArray)||out.length!==stride*4)throw Error('Invalid seat output');
+ for(let i=3;i<out.length;i+=4)out[i]=255;
  return progress=>{
   if(!Number.isFinite(progress)||progress<0||progress>1)throw Error('Invalid paper sitting progress');
   const q=progress*3,pair=Math.min(2,Math.floor(q)),sample=Math.round((q-pair)*16),frame=frames.getFrame(pair*17+sample);

package/puppy-paper.mjs

@@ -40,7 +40,7 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
  let straight=false,seatProgress=0,seatVariant='default',travel=null,approachPlan=null,travelAge=0,travelDistance=0,motionSpeed=0,motionStage='rest',completed=false;
  let watchSide='left',restProgress=0,idleHold=2.5;
  let pendingAction=null,activeAction=null,actionDone=null,deferred=null,movementMode='run',stayDown=false,manualDown=false,spinReady=false;
- let comfort=null,comfortSeconds=0;
+ let comfort=null,comfortSeconds=0,sleepLook=null,nextSleepLook={variant:'side',right:false};
  const director=createPaperDirector();
  const points=[[.12,PAPER_GROUND.away]];
  const enter=s=>{state=s;age=0;};
@@ -99,7 +99,7 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
   pendingAction=null;
   if(name==='sit'){enter('idle');return;}
   if(name==='belly'){const seconds=comfortSeconds;playAction('lie-down',()=>startBelly(seconds),.65);return;}
-  if(name==='sleep'){stayDown=false;comfort={kind:'sleep',seconds:comfortSeconds};enter('recline');return;}
+  if(name==='sleep'){stayDown=false;sleepLook={...nextSleepLook};comfort={kind:'sleep',seconds:comfortSeconds};enter('recline');return;}
   if(name==='tug'){stop();comfort={kind:'tug',seconds:comfortSeconds};enter('tug');return;}
   if(name==='lie'){
    if(manualTricks){playAction('lie-down',()=>{manualDown=true;enter('down');drain();},.65);}
@@ -160,7 +160,7 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
   lie(){const name=manualDown||activeAction?.name==='lie-down'||restProgress>0?'sit':'lie';return dispatch(()=>requestAction(name));},
   // Comfort poses: bounded finite seconds; same dispatch safety as tricks.
   belly(seconds=6){comfortDuration('belly',seconds);return dispatch(()=>{comfortSeconds=seconds;return requestAction('belly');},{keepDown:true});},
-  sleep(seconds=25){comfortDuration('sleep',seconds);return dispatch(()=>{comfortSeconds=seconds;return requestAction('sleep');});},
+  sleep(seconds=25,variant='side',right=false){comfortDuration('sleep',seconds);if(!['side','belly','curl','chin'].includes(variant)||typeof right!=='boolean')throw Error('Invalid sleep pose');return dispatch(()=>{comfortSeconds=seconds;nextSleepLook={variant,right};return requestAction('sleep');});},
   tug(seconds=6){comfortDuration('tug',seconds);return dispatch(()=>{comfortSeconds=seconds;return requestAction('tug');});},
   rest(){return dispatch(()=>{route=false;target=null;waypoints=[];pendingAction=null;stayDown=false;comfort=null;stop();if(restProgress>0){enter('wake');}else if(state==='watch'||state==='arrival-exit'){/* finish shared return */}else if(seatProgress>0||state==='rise'||state==='sit-down')enter('sit-down');else if(!['idle','view-turn','turn'].includes(state))enter('finish');});},
   update(dt){
@@ -209,7 +209,8 @@ export function createPaperActor(animal,info,{manualTricks=false,trickTimings=nu
    if(![12,24,30].includes(poseFps))throw Error('Invalid pose cadence');
    let pair=20,blend=0,kind=state,rearPair=null,approachPair=null;
    let seat=state==='sit-down'||state==='rise'||seatProgress>0?Math.round(seatProgress*48)/48:null;
-   let behavior=null,behaviorProgress=0,comfortPose=state==='tug'?{clip:'tug',progress:tugProgress()}:null;
+   if(restProgress===0&&state!=='recline')sleepLook=null;
+   let behavior=null,behaviorProgress=0,comfortPose=state==='tug'?{clip:'tug',progress:tugProgress()}:sleepLook&&restProgress>.72?{clip:'sleep',...sleepLook,blend:comfortEase((restProgress-.72)/.28)}:null;
    if(activeAction?.comfort)kind=activeAction.comfort;
    let actionName=activeAction?.name??(state==='run'&&movementMode==='walk'?'walk':null),actionProgress=activeAction?(activeAction.timing?activeAction.timing.progressAt(age):Math.min(1,age/activeAction.duration)):phase;
    if(manualDown&&state==='down'){actionName='lie-down';actionProgress=1;}
@@ -251,14 +252,20 @@ export function createPaperRenderer(cache,info,meta,width,height,{rear,approach,
  if(![width,height].every(Number.isInteger)||width<2||height<2||width*height>1_000_000)throw Error('Invalid paper grid');
  const tween=createCachedTween(cache,info),renderMeta={...meta,pairs:info.pair_map,run_sequence:info.run_sequence};
  const out=new Uint8ClampedArray(width*height*4),area=createPaperAreaSampler();
- const rearSample=rear?createRearSampler(rear.bytes,rear.info):null,lock=createPaperFootLock({maxImageStretch:pawTransport?1.45:Infinity});
- const approachSample=approach?createRearSampler(approach.bytes,approach.info):null;
- const seatSample=seat?createPaperSeatSampler(seat.bytes,seat.info):null;
- const arrivalSeatSample=arrivalSeat?createPaperSeatSampler(arrivalSeat.bytes,arrivalSeat.info):null;
- const behaviorSample=behaviors?createPaperBehaviorSampler(behaviors.bytes,behaviors.info):null;
- const interactionSample=interactions?createCompanionSpriteSampler(interactions.bytes,interactions.info):null;
- const comfortSample=comfort?createComfortSpriteSampler(comfort.bytes,comfort.info):null;
- const actionSample=actions?createPaperActionSampler(actions.bytes,actions.info):null,actionArea=actions?createPaperAreaSampler(actions.info.width):null;
+ // Only one authored source is drawn at a time. Small samplers borrow a view of
+ // the action-sized scratch. A sleep blend reads each base pixel before writing
+ // that same pixel, so it needs no second image or per-frame temporary buffer.
+ const actionScratch=new Uint8ClampedArray(Math.max(320*320,(actions?.info.width??320)*(actions?.info.height??320))*4);
+ const spriteScratch=actionScratch.subarray(0,320*320*4);
+ for(let i=3;i<actionScratch.length;i+=4)actionScratch[i]=255;
+ const rearSample=rear?createRearSampler(rear.bytes,rear.info,spriteScratch):null,lock=createPaperFootLock({maxImageStretch:pawTransport?1.45:Infinity});
+ const approachSample=approach?createRearSampler(approach.bytes,approach.info,spriteScratch):null;
+ const seatSample=seat?createPaperSeatSampler(seat.bytes,seat.info,spriteScratch):null;
+ const arrivalSeatSample=arrivalSeat?createPaperSeatSampler(arrivalSeat.bytes,arrivalSeat.info,spriteScratch):null;
+ const behaviorSample=behaviors?createPaperBehaviorSampler(behaviors.bytes,behaviors.info,spriteScratch):null;
+ const interactionSample=interactions?createCompanionSpriteSampler(interactions.bytes,interactions.info,spriteScratch):null;
+ const comfortSample=comfort?createComfortSpriteSampler(comfort.bytes,comfort.info,spriteScratch):null;
+ const actionSample=actions?createPaperActionSampler(actions.bytes,actions.info,actionScratch.subarray(0,actions.info.width*actions.info.height*4)):null,actionArea=actions?createPaperAreaSampler(actions.info.width):null;
  const walkEpisodes=actions?createPaperSupportEpisodes(actions.info.feet,actions.info.clips.walk,9):null;
  const sourceEpisodes=rear?{
   front:createPaperSupportEpisodes(rear.info.frontFeet,[0,1,2,3,4,5,6,7],17),
@@ -276,7 +283,7 @@ export function createPaperRenderer(cache,info,meta,width,height,{rear,approach,
   const isInteraction=isComfort||state.interactionPose&&interactionSample;
   const isBehavior=!isInteraction&&state.behavior&&behaviorSample;
   const isAction=!isInteraction&&state.actionName&&actionSample,sourceN=isAction?actions.info.width:320,originX=(sourceN-320)/2,originY=(sourceN/320-1)*300;
-  const image=isComfort?comfortSample(state.comfortPose):isInteraction?interactionSample(state.interactionPose):isAction?actionSample(state):isBehavior?behaviorSample(state):isSeat?(state.seatVariant==='arrival'&&arrivalSeatSample?arrivalSeatSample:seatSample)(state.seatProgress):isApproach?approachSample(state.approachPair,state.blend):isRear?rearSample(state.rearPair,state.blend):tween(state),side=height*size,sideX=side/pixelAspect;
+  const image=isComfort?comfortSample({...state.comfortPose,...state.comfortPose.clip==='sleep'&&state.comfortPose.blend<1&&behaviorSample?{base:behaviorSample({behavior:'rest',behaviorProgress:state.behaviorProgress})}:{}}):isInteraction?interactionSample(state.interactionPose):isAction?actionSample(state):isBehavior?behaviorSample(state):isSeat?(state.seatVariant==='arrival'&&arrivalSeatSample?arrivalSeatSample:seatSample)(state.seatProgress):isApproach?approachSample(state.approachPair,state.blend):isRear?rearSample(state.rearPair,state.blend):tween(state),side=height*size,sideX=side/pixelAspect;
   // Quantize source lookup only, never the projected rectangle. Rounding side,
   // left and top first introduced whole-body scale/position jumps at thresholds.
   const left=width*x-sideX/2,floor=isInteraction||isAction||isBehavior||isSeat||isRear||isApproach?0:cleanGroundOffset(state,renderMeta),top=height*y-(300-floor)/320*side;

package/retrieviewer-cli.mjs

@@ -13,7 +13,7 @@ Usage:
   retrieviewer doctor [--agent ID] [--json]
   retrieviewer agents [--json]
   retrieviewer preview [--original]
-  retrieviewer desktop
+  retrieviewer desktop [--ink cream|gold|dark]
   retrieviewer desktop-status [--json]
   retrieviewer desktop-stop
   retrieviewer desktop-clean --yes
@@ -32,15 +32,17 @@ 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];
+  if(token==='--agent'||token==='--ink'){
+   const key=token.slice(2);
+   if(options[key]||!rest[i+1]||rest[i+1].startsWith('-'))throw Error(token+' requires one value');
+   options[key]=rest[++i];
   }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(options.ink&&!['cream','gold','dark'].includes(options.ink))throw Error('--ink must be cream, gold or dark');
  if(!['help','--help','-h','enable','disable','disconnect','status','doctor','agents','preview','desktop','desktop-status','desktop-stop','desktop-clean','desktop-remove'].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'],'desktop-status':['json'],'desktop-clean':['yes'],'desktop-remove':['yes']};
+ const allowed={desktop:['ink'],enable:['agent','yes','json','dry-run'],disconnect:['agent','yes','json','dry-run'],disable:['agent','json'],status:['agent','json'],doctor:['agent','json'],agents:['json'],preview:['original'],'desktop-status':['json'],'desktop-clean':['yes'],'desktop-remove':['yes']};
  for(const key of Object.keys(options))if(!(allowed[command]??[]).includes(key))throw Error(`--${key} is not supported by ${command}`);
  return {command,options};
 }
@@ -51,7 +53,7 @@ export async function runCli(args,{input=process.stdin,output=process.stdout,err
   if(['desktop-clean','desktop-remove'].includes(command)&&!options.yes)throw Error('Use '+command+' --yes to remove only the companion cache.');
   const api=desktop??await import('./integrations/windows-overlay/desktop.mjs');
   const action={'desktop':'startDesktop','desktop-status':'desktopStatus','desktop-stop':'stopDesktop','desktop-clean':'cleanDesktop','desktop-remove':'removeDesktop'}[command];
-  emit(await api[action]());return 0;
+  emit(await api[action](options.ink?{ink:options.ink}:{}));return 0;
  }
  if(command==='preview'){await import('./examples/live.mjs');return 0;}
  if(['status','doctor','agents'].includes(command)){

package/retrieviewer.d.mts

@@ -42,6 +42,8 @@ export interface LifeReport {
   interaction: 'ball' | 'treat' | 'tug' | null;
   busy: boolean;
   energy: number;
+  /** Awake-time sleep pressure; ordinary sitting does not erase it. */
+  drowsiness: number;
   decisions: number;
   cooldowns: {ball: number; treat: number; tug: number};
   gesture: {clip: string; progress: number} | null;