@bitefoundry/retrieviewer 0.0.3 → 0.0.5

package/README.md

@@ -1,90 +1,152 @@
-# Retrieviewer
+<p align="center">
+  <a href="https://bitefoundry.github.io/retrieviewer/"><img src="https://raw.githubusercontent.com/BiteFoundry/retrieviewer/main/docs/assets/preview.png" alt="Retrieviewer — a fluffy retriever drawn with tiny monochrome Braille dots" width="960"></a>
+</p>
 
-An autonomous, fluffy Braille retriever that lives above your app window or in a TUI pane.
-Give it a ball or a treat; otherwise it wanders and plays on its own. By BiteFoundry.
+<h1 align="center">Retrieviewer</h1>
+<p align="center">A little company for your screen.</p>
+<p align="center">
+  <a href="https://bitefoundry.github.io/retrieviewer/">Meet your retriever</a> ·
+  <a href="./README.ko.md">한국어</a> ·
+  <a href="https://www.npmjs.com/package/@bitefoundry/retrieviewer">npm</a> ·
+  <a href="https://github.com/BiteFoundry/retrieviewer/issues">Feedback</a>
+</p>
 
-**Version 0.0.3.** Source code is MIT; puppy artwork is CC BY-SA 4.0, including
-commercial use and adaptations under its attribution/ShareAlike conditions.
-See [licensing](./LICENSE), [artwork terms](./ASSETS-LICENSE.md),
-[credits](./ATTRIBUTION.md) and [brand notice](./TRADEMARKS.md).
-The complete package is not MIT-only.
+A fluffy, autonomous Braille-art retriever that hangs out above an app window.
+It wanders, runs, flops belly-up and naps. Toss a ball, offer a treat or play tug.
+Get back to your thing.
 
-## Install
+Made by [BiteFoundry](https://github.com/BiteFoundry). No model API, account or
+telemetry is needed by the runtime.
 
-Node.js >=20 is required. Windows10/11 x64 uses the Windows .NET Framework4
-compiler (automatic helper build on first launch). Linux needs X11, a compositor,
-system Python3.6+ and X11/Xrender/Xext; AlmaLinux8/GLIBC2.28 has been tested.
-macOS uses built-in osascript/AppKit and is **experimental, not runtime verified**.
-Native Wayland is not supported. See [platform requirements](./DESKTOP-PLATFORMS.md).
+## Bring one home
 
-1. Install:
+Install **on the computer displaying the app**, in a terminal. Node.js is required;
+[install Node/npm first](./PREREQUISITES.md) if you do not have them.
+
+1. Install (or update):
 
    ```sh
-   npm install -g @bitefoundry/retrieviewer
+   npm install -g @bitefoundry/retrieviewer@latest
    ```
 
-2. Run and choose the app window you want your puppy to live on:
+2. Run, then choose an app in the window picker:
 
    ```sh
    retrieviewer desktop
    ```
 
-That's it. Use your app normally. Ball/treat controls sit above the selected
-window; the pet lets ordinary clicks through. No Codex patch, wrapper, MCP setup,
-administrator access, or automatic startup registration. It follows a whole window,
-not individual tabs, and hides when you switch away. It is a separate transparent
-native window, **not a widget injected into another app**. macOS is experimental;
-exclusive fullscreen apps and privileged/security surfaces are not certified.
+Next time, just run `retrieviewer desktop`. This is a separate transparent,
+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
+> you may be viewing through VNC; it is not automatically your local Cursor window.
 
-Exit from the tray icon or `retrieviewer desktop-stop`. To remove the companion's
-own cache, run `retrieviewer desktop-remove --yes`; then
-`npm uninstall -g @bitefoundry/retrieviewer` removes the package. See
-[platform support](./DESKTOP-PLATFORMS.md) and [Windows controls and removal](./WINDOWS-COMPANION.md).
+<details>
+<summary>Try once with npx / command not found / Node is missing</summary>
 
-## Optional: native OpenCode pane
+With Node/npm installed, try without a global installation:
 
 ```sh
-retrieviewer enable --agent opencode --yes
-opencode
+npx --yes --package @bitefoundry/retrieviewer@latest retrieviewer desktop
 ```
 
-Without `--agent` / `--yes`, interactive `retrieviewer enable` offers agent
-selection and a preview before changing configuration. The native adapter is
-currently verified only with OpenCode 2.1.2 on Windows. Codex, Claude Code, Cursor
-Agent, Grok and Antigravity native panes are not implemented. MCP connectivity
-alone does not create a pet inside their screens.
+`npx` does **not** permanently add `retrieviewer` to PATH. Use the global install
+above for future short commands. If that still says command not found, see
+[PATH fixes for bash, csh/tcsh and Windows](./PREREQUISITES.md#command-not-found).
+Do not use `sudo npm install -g` as a blanket workaround.
 
-Inside OpenCode use `/retrieviewer ball`, `/retrieviewer treat`, or
-`/retrieviewer disable`. See [installation and removal](./INSTALLING.md).
+</details>
 
-## Embed in your own TUI
+## Where it can live
 
-Install `@bitefoundry/retrieviewer` in your app, without `-g`, then use the host callbacks:
+| Desktop | Status / requirements |
+| --- | --- |
+| Windows 10/11 x64 | Live tested. Node + Windows .NET Framework 4 compiler; helper builds on first launch. |
+| Linux X11 | AlmaLinux 8 / GLIBC 2.28 / Python 3.6.8 / Node 22.23.4 tested in an isolated composited X11 desktop. Requires system Python 3.6+, X11/Xrender/Xext and a compositor. |
+| macOS | **Experimental; no Mac runtime verification yet.** Uses built-in osascript/AppKit. |
+| Native Wayland / headless SSH | Not supported by the desktop overlay. No session/privacy workaround is installed. |
 
-```js
-import {createPetPlugin} from '@bitefoundry/retrieviewer/plugin';
+Linux currently favors lower load: 16px cells / 15fps versus the Windows default
+8px cells / 30fps, so its dots look coarser. The Q5 artwork is identical.
+This is not a zero-resource widget: the npm tarball is about 19 MB. An earlier
+0.0.3 AlmaLinux test used roughly 180 MiB of Node RSS, plus the Python helper;
+that is not a memory budget or a new Linux GUI check for 0.0.4.
+See [platform details and verification boundaries](./DESKTOP-PLATFORMS.md).
+
+## Easy to leave, too
+
+Quit through the controls, or run `retrieviewer desktop-stop`.
+To remove the companion's own cache and the package:
+
+```sh
+retrieviewer desktop-remove --yes
+npm uninstall -g @bitefoundry/retrieviewer
+```
+
+The desktop companion does not edit agent credentials, app binaries or shell
+profiles. [Optional OpenCode registration](./INSTALLING.md) is separate; disconnect
+that registration before uninstalling if you explicitly enabled it.
 
-const puppy = await createPetPlugin({host: {
-  getSize: () => ({columns: pane.width, rows: pane.height}),
-  render: ({text}) => pane.setContent(text),
-  onError: error => logToYourApp(error),
-}});
+## Put it inside your own TUI
+
+The core is host-driven. Your app owns the pane, input and clock; the puppy does
+not take over stdin/stdout.
+
+```js
+import { createPetPlugin } from '@bitefoundry/retrieviewer/plugin';
+
+const puppy = await createPetPlugin({
+  host: {
+    getSize: () => ({ columns: pane.width, rows: pane.height }),
+    render: ({ text }) => pane.setContent(text),
+    onError: error => logToYourApp(error),
+  },
+});
 puppy.start();
-// Optional interaction: puppy.interact('ball') / puppy.interact('treat')
+// puppy.interact('ball') / puppy.interact('treat') / puppy.interact('tug')
 // On unmount: puppy.dispose()
 ```
 
-`pane` and `logToYourApp` are supplied by your app. The pet does not take over
-stdin, stdout or the screen. Q5 (32-level) artwork is bundled; no model API,
-account or telemetry is needed by the runtime. npm dependencies require an
-initial download or a populated cache. This is not a tiny icon: the complete
-tarball is about 21 MB and a previous Windows sample used about 172 MB RSS.
+`pane` and `logToYourApp` come from your app.
+[Plugin lifecycle](./PLUGIN.md) · [Core / JSONL bridge](./EMBEDDING.md) ·
+[Optional OpenCode adapter](./INSTALLING.md).
+The native OpenCode pane has Windows/OpenCode 2.1.2 host evidence; Codex, Claude,
+Cursor, Grok and Antigravity **in-terminal** renderers are not implemented.
+An MCP connection alone cannot insert a persistent picture into those clients.
+
+## Build, contribute, be kind
+
+```sh
+npm ci
+npm test
+npm run build:site
+npm start
+```
+
+The public tree contains the shipped runtime, Q5 art, focused runtime/adapter
+tests and reproducible site build. Historical art experiments, original reference
+photos and private worker/QA logs are intentionally absent.
+See [contributing](./CONTRIBUTING.md) and [source scope](./SOURCE-SCOPE.md).
+Compatibility reports are welcome—especially real Mac testing and X11 desktops.
+
+## Code and coat have different licenses
+
+**Code: MIT. Artwork: CC BY-SA 4.0.** Commercial reuse is permitted under the
+respective terms. Keep artwork credits and ShareAlike conditions when applicable;
+the complete package is **not MIT-only**.
 
-- [Plugin lifecycle](./PLUGIN.md) — host callbacks, clocks and embedding.
-- [Core and JSONL bridge](./EMBEDDING.md) — JS and non-JS TUI integration.
-- [Release process](./RELEASING.md) — checks and support boundaries.
-- [Third-party notices](./THIRD-PARTY-NOTICES.md).
+[Code license](./LICENSE-CODE) · [Artwork terms](./ASSETS-LICENSE.md) ·
+[Required credits](./ATTRIBUTION.md) · [Third-party notices](./THIRD-PARTY-NOTICES.md) ·
+[Brand notice](./TRADEMARKS.md).
 
-The runtime has no install scripts and never edits agent settings automatically.
-Only an explicit `retrieviewer enable` changes settings, after a preview/approval
-or an explicit `--yes`. Unsupported hosts are refused.
+The puppy artwork was developed with AI-generated imagery and programmatic pose,
+grounding and frame processing. It is authored animation, not motion capture or
+a claim of sentience.

package/RELEASING.md

@@ -1,6 +1,15 @@
-# Retrieviewer 0.0.3 release process
-
-Target: `@bitefoundry/retrieviewer@0.0.3`, public npm registry, `latest` tag.
+# 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
 `shinick` owns the organization.
 
@@ -12,11 +21,15 @@ artwork draft is superseded. ATTRIBUTION.md retains the photographic references
 and original license links. ASSET-PROVENANCE.md records the bounded review and
 remaining limits; this is not comprehensive legal clearance.
 
-The owner explicitly authorized publishing0.0.3 with the cross-platform companion
-and the two-step npm install/desktop launch guide. Windows and the AlmaLinux8
-GLIBC2.28 X11 baseline have live test evidence; macOS ships as experimental and
-not runtime verified. Native Wayland is unsupported. No new art license or Codex
-modification is part of this release. Preserve all earlier registry artifacts.
+The owner explicitly authorized GitHub push and npm publication of the reviewed
+comfort extension and runtime optimizations on2026-10-23. Version0.0.4 removes
+unused Three.js runtime work, retains only reachable interaction samples, and
+adds belly-up/sleep behavior plus a tiny tug sprite family. Code/art licenses stay
+MIT/CC BY-SA4.0, including the new covered archive. No Codex modification is made.
+Windows live, installed-consumer and browser checks cover this release. Linux
+retains the earlier AlmaLinux8/GLIBC2.28 X11 adapter baseline; new controls have
+grammar/protocol checks, not a new Linux GUI test. macOS remains experimental.
+Native Wayland is unsupported. Preserve all earlier registry artifacts.
 
 `release-policy.json` has four independent approval gates and the CC artwork
 license identifier. The guard still refuses false/missing approvals, private
@@ -38,10 +51,16 @@ interactions, lifecycle, examples, JSONL and isolated installer settings.
 Its report is in a fresh `dist/package-check-*/package-check.json`; it does not publish or edit live
 agent configuration. Keep the final tarball hash and file inventory.
 
-The product workspace is not a Git repository. No public source repository,
-Actions pipeline or npm trusted publisher is implied by this npm release.
-Do not upload this experimental workspace wholesale: original photos, source
-image sheets, workers, QA receipts, credentials and local settings stay local.
+The original art playground was not a Git repository. The owner separately
+authorized a curated public source tree at BiteFoundry/retrieviewer and its
+GitHub Pages workflow. This is not an upload of the experimental workspace:
+original photos, source image sheets, workers, QA receipts, credentials and local
+settings remain local. See SOURCE-SCOPE.md. There is no npm trusted publisher or
+automatic npm release workflow; the site workflow deploys the site only.
+
+Immutable npm0.0.3 was already published and verified. Do not republish different
+bytes as0.0.3. This release uses0.0.4 with fresh authorization, version/lock/test/
+policy updates, exact-tarball checks and registry-install verification.
 
 ## Publish the tested tarball
 
@@ -58,7 +77,8 @@ https://docs.npmjs.com/trusted-publishers/
 
 ## Support boundaries
 
-The default Q5 art and runtime are unchanged by this release. The OpenCode
+The approved existing Q5 frames are unchanged; the new tiny tug family uses the
+same32-level pipeline. Belly/sleep reuse existing source frames. The OpenCode
 2.1.2 Windows directory-based adapter has local host proof; npm `./tui`
 discovery alone is not live-host certification. Other agent-native renderers
 remain unimplemented. MCP alone cannot inject a pet into arbitrary agent UIs.

package/THIRD-PARTY-NOTICES.md

@@ -1,11 +1,13 @@
 # Third-party notices
 
 - **procedural-animals 0.1.0** — MIT, Copyright (c) 2026 Majid Manzarpour and
-  procedural-animals contributors. Source is vendored under
-  `vendor/procedural-animals/src`; the full notice is retained at
+  procedural-animals contributors. The original development source is retained
+  under `vendor/procedural-animals/src` for motion parity tests; it is no longer
+  executed or shipped in the dot-art runtime. The full notice is retained at
   `vendor/procedural-animals/LICENSE`.
   Upstream: https://github.com/majidmanzarpour/threejs-procedural-animals
-- **three 0.186.1** — MIT; installed as a pinned npm dependency. Its distribution
+- **three 0.186.1** — MIT; development-only dependency for original 3D parity
+  tests. Not installed by the production package. Its development distribution
   includes its own `LICENSE`. https://github.com/mrdoob/three.js
 - **jsonc-parser 3.3.1** — MIT; installed as a pinned npm dependency. Its
   distribution includes `LICENSE.md`. https://github.com/microsoft/node-jsonc-parser

package/braille.mjs

@@ -2,23 +2,49 @@
 export const BRAILLE_BITS=[[1,8],[2,16],[4,32],[64,128]];
 const BAYER=[[0,8,2,10],[12,4,14,6],[3,11,1,9],[15,7,13,5]];
 const clamp=v=>Math.max(0,Math.min(1,v));
+const GLYPHS=Array.from({length:256},(_,i)=>String.fromCharCode(0x2800+i));
+let grayTable=null,grayBrightness=0,grayContrast=0;
+function stableBraille(rgba,width,height,brightness,contrast){
+  if(grayBrightness!==brightness||grayContrast!==contrast){
+    grayTable=Float32Array.from({length:256},(_,v)=>{
+      const luma=(.2126*v+.7152*v+.0722*v)/255;
+      return luma===0?0:clamp((Math.pow(luma,.9)*brightness-.5)*contrast+.5);
+    });
+    grayBrightness=brightness;grayContrast=contrast;
+  }
+  const table=grayTable,bytePixels=rgba instanceof Uint8Array||rgba instanceof Uint8ClampedArray,columns=Math.ceil(width/2),rows=Math.ceil(height/4),masks=new Uint8Array(columns*rows);
+  let dots=0;
+  // Stable dithering has no error diffusion: background pixels cannot affect a
+  // neighbor. Skip them before luma/hash work, and write straight to cell masks.
+  // Float32 rounding matches the original intermediate values array exactly.
+  for(let y=0;y<height;y++)for(let x=0,p=y*width*4;x<width;x++,p+=4){
+    const r=rgba[p],g=rgba[p+1],b=rgba[p+2],a=rgba[p+3];
+    if(a===0||(r===0&&g===0&&b===0))continue;
+    let value;
+    if(bytePixels&&a===255&&r===g&&g===b)value=table[r];
+    else{
+      const luma=(.2126*r+.7152*g+.0722*b)/255*(a/255);
+      value=Math.fround(luma===0?0:clamp((Math.pow(luma,.9)*brightness-.5)*contrast+.5));
+    }
+    if(value<=0)continue;
+    let n=Math.imul(x+1,0x1f123bb5)^Math.imul(y+1,0x5f356495);
+    n=Math.imul(n^(n>>>16),0x45d9f3b);n=Math.imul(n^(n>>>16),0x45d9f3b);n=(n^(n>>>16))>>>0;
+    if(value>(n+.5)/4294967296){masks[(y>>2)*columns+(x>>1)]|=BRAILLE_BITS[y&3][x&1];dots++;}
+  }
+  const lines=[];
+  for(let y=0;y<rows;y++){let line='';for(let x=0;x<columns;x++)line+=GLYPHS[masks[y*columns+x]];lines.push(line);}
+  return{text:lines.join('\n'),columns,rows,dots};
+}
 export function rgbaToBraille(rgba,width,height,{brightness=1,contrast=1,method='floyd'}={}){
   if(!Number.isInteger(width)||!Number.isInteger(height)||width<1||height<1||width*height>1_000_000||rgba.length!==width*height*4)throw Error('Invalid RGBA image');
   if(!Number.isFinite(brightness)||brightness<=0||brightness>4||!Number.isFinite(contrast)||contrast<=0||contrast>4||!['floyd','bayer','stable'].includes(method))throw Error('Invalid dithering options');
+  if(method==='stable')return stableBraille(rgba,width,height,brightness,contrast);
   const values=new Float32Array(width*height),bits=new Uint8Array(width*height);
   for(let i=0;i<values.length;i++){
     const p=i*4,luma=(.2126*rgba[p]+.7152*rgba[p+1]+.0722*rgba[p+2])/255*(rgba[p+3]/255);
     values[i]=luma===0?0:clamp((Math.pow(luma,.9)*brightness-.5)*contrast+.5);
   }
-  if(method==='stable'){
-    // Fixed per-pixel threshold, not fresh random noise on every animation tick.
-    // Unlike the 4x4 Bayer matrix this avoids a repeating cross-hatch on fur.
-    for(let y=0;y<height;y++)for(let x=0;x<width;x++){
-      let n=Math.imul(x+1,0x1f123bb5)^Math.imul(y+1,0x5f356495);
-      n=Math.imul(n^(n>>>16),0x45d9f3b);n=Math.imul(n^(n>>>16),0x45d9f3b);n=(n^(n>>>16))>>>0;
-      bits[y*width+x]=values[y*width+x]>(n+.5)/4294967296?1:0;
-    }
-  }else if(method==='bayer'){
+  if(method==='bayer'){
     for(let y=0;y<height;y++)for(let x=0;x<width;x++)bits[y*width+x]=values[y*width+x]>(BAYER[y%4][x%4]+.5)/16?1:0;
   }else{
     const add=(x,y,error,weight)=>{if(x>=0&&x<width&&y<height)values[y*width+x]+=error*weight/16;};

package/examples/live.mjs

@@ -13,7 +13,7 @@ if(!out.isTTY||!input.isTTY){
  const data=bytes=>{for(const c of bytes.toString()){
   if(c==='q'||c==='\x03')stop();
   if(c===' ')paused=!paused;
-  if(c==='b'||c==='t'){if(pet.interact(c==='b'?'ball':'treat'))paused=false;}
+  if(c==='b'||c==='t'||c==='g'){if(pet.interact(c==='b'?'ball':c==='t'?'treat':'tug'))paused=false;}
  }};
  process.on('SIGINT',stop);process.on('SIGTERM',stop);
  input.setRawMode(true);input.resume();input.on('data',data);
@@ -28,7 +28,7 @@ if(!out.isTTY||!input.isTTY){
    const frame=pet.frame({columns,rows}),lines=frame.text.split('\n');let batch='';
    for(let y=0;y<rows;y++)if(lines[y]!==previous[y])batch+=`\x1b[${y+1};1H${lines[y]}`;
    previous=lines;
-   const status=`${paused?'Paused':frame.report.intent} | B ball  T treat  Space pause  Q quit`.slice(0,columns);
+   const status=`${paused?'Paused':frame.report.intent} | B ball  T treat  G tug  Space pause  Q quit`.slice(0,columns);
    batch+=`\x1b[${rows+1};1H\x1b[2K${status}`;
    if(!out.write(batch))await once(out,'drain');
    await new Promise(resolve=>setTimeout(resolve,Math.max(1,1000/30-(performance.now()-start))));

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:
@@ -213,7 +219,7 @@ class Companion(object):
     def press(self, name):
         if self.quitting:
             return
-        if name in ('ball', 'treat'):
+        if name in ('ball', 'treat', 'tug'):
             if self.loaded and not self.paused:
                 self.emit({'type': 'interact', 'kind': name})
         elif name == 'pause':
@@ -460,7 +466,7 @@ def ascii_label(text, limit):
 
 class XDisplay(object):
     """Owned X11 resources: one ARGB pet window, one control strip, one picker."""
-    BAR_BUTTONS = (('ball', 'Ball'), ('treat', 'Treat'), ('window', 'Window'), ('pause', 'Pause'), ('quit', 'Quit'))
+    BAR_BUTTONS = (('ball', 'Ball'), ('treat', 'Treat'), ('tug', 'Tug'), ('window', 'Window'), ('pause', 'Pause'), ('quit', 'Quit'))
 
     def __init__(self, display_name=None, require_compositor=True, x=None):
         self.x = x or load_libraries()

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') {
@@ -265,7 +265,7 @@ var STYLE_BORDERLESS = 0, STYLE_TITLED = 1, STYLE_CLOSABLE = 2, STYLE_NONACTIVAT
 var BACKING_BUFFERED = 2, FLOATING_LEVEL = 3, ACTIVATION_ACCESSORY = 1, ANIMATION_NONE = 2;
 // canJoinAllSpaces | stationary | ignoresCycle | fullScreenAuxiliary
 var OVERLAY_SPACES = 1 | 16 | 64 | 256;
-var BAR_WIDTH = 354, BAR_HEIGHT = 40;
+var BAR_WIDTH = 404, BAR_HEIGHT = 40;
 
 var shell = null;
 
@@ -379,7 +379,7 @@ function registerClasses() {
     name: 'RetrieviewerController', superclass: 'NSObject',
     methods: {
       'onInput:': guarded('onInput'), 'onTick:': guarded('onTick'),
-      'onBall:': guarded('onBall'), 'onTreat:': guarded('onTreat'), 'onPick:': guarded('onPick'),
+      'onBall:': guarded('onBall'), 'onTreat:': guarded('onTreat'), 'onTug:': guarded('onTug'), 'onPick:': guarded('onPick'),
       'onPause:': guarded('onPause'), 'onQuit:': guarded('onQuit'),
       'onRefresh:': guarded('onRefresh'), 'onAttach:': guarded('onAttach'), 'onCancel:': guarded('onCancel'),
       'windowWillClose:': guarded('onWindowWillClose')
@@ -412,10 +412,11 @@ function startCompanion(testMode) {
   ballButton = makeButton('\uACF5', { x: 8, y: 6, width: 40, height: 28 }, 'onBall:');
   content.addSubview(ballButton);
   content.addSubview(makeButton('\uAC04\uC2DD', { x: 52, y: 6, width: 46, height: 28 }, 'onTreat:'));
-  content.addSubview(makeButton('\uCC3D', { x: 102, y: 6, width: 40, height: 28 }, 'onPick:'));
-  content.addSubview(makeButton('\uC27C', { x: 146, y: 6, width: 40, height: 28 }, 'onPause:'));
-  content.addSubview(makeButton('\uC885\uB8CC', { x: 190, y: 6, width: 46, height: 28 }, 'onQuit:'));
-  statusLabel = makeLabel(TEXT.preparing, { x: 242, y: 10, width: 108, height: 20 }, $.NSColor.whiteColor);
+  content.addSubview(makeButton('\uD130\uADF8', { x: 102, y: 6, width: 46, height: 28 }, 'onTug:'));
+  content.addSubview(makeButton('\uCC3D', { x: 152, y: 6, width: 40, height: 28 }, 'onPick:'));
+  content.addSubview(makeButton('\uC27C', { x: 196, y: 6, width: 40, height: 28 }, 'onPause:'));
+  content.addSubview(makeButton('\uC885\uB8CC', { x: 240, y: 6, width: 46, height: 28 }, 'onQuit:'));
+  statusLabel = makeLabel(TEXT.preparing, { x: 292, y: 10, width: 108, height: 20 }, $.NSColor.whiteColor);
   content.addSubview(statusLabel);
 
   // Menu bar item: the macOS counterpart of the Windows tray icon.
@@ -535,6 +536,7 @@ function startCompanion(testMode) {
   };
   shell.onBall = function () { core.interact('ball'); };
   shell.onTreat = function () { core.interact('treat'); };
+  shell.onTug = function () { core.interact('tug'); };
   shell.onPick = function () { choose(); };
   shell.onPause = function () { core.togglePause(); };
   shell.onQuit = function () { core.quit(); };

package/integrations/opencode/runtime.mjs

@@ -11,7 +11,7 @@ export const HEARTBEAT_MS=5000;
 // Bounded so the host prompt stays usable: at most 64x12 cells, hidden when the
 // terminal is too small for a legible pet.
 export const LIMITS=Object.freeze({maxColumns:64,maxRows:12,minColumns:20,minRows:5,sideMargin:4,reservedRows:14});
-export const COMMANDS=Object.freeze(['enable','disable','ball','treat','status']);
+export const COMMANDS=Object.freeze(['enable','disable','ball','treat','tug','status']);
 
 const fn=(value,name)=>{if(typeof value!=='function')throw TypeError(`${name} must be a function`);};
 const defaultScheduler=()=>({now:()=>performance.now(),schedule:(callback,delayMs)=>setTimeout(callback,delayMs),cancel:handle=>clearTimeout(handle)});
@@ -133,7 +133,7 @@ export function createOpenCodePetController({hostVersion='unknown',scheduler,fps
   enabled=value;reconcile();
  }
  function interact(kind){
-  if(kind!=='ball'&&kind!=='treat')throw TypeError("kind must be 'ball' or 'treat'");
+  if(!['ball','treat','tug'].includes(kind))throw TypeError("kind must be 'ball', 'treat' or 'tug'");
   return plugin?plugin.interact(kind):false;
  }
  function status(){
@@ -168,11 +168,11 @@ export function createOpenCodePetController({hostVersion='unknown',scheduler,fps
   setEnabled,
   interact,
   status,
-  // Slash handler: '/retrieviewer <enable|disable|ball|treat|status>'.
+  // Slash handler: '/retrieviewer <enable|disable|ball|treat|tug|status>'.
   async command(argument){
    const word=String(argument??'').trim().toLowerCase()||'status';
    if(word==='enable'||word==='disable'){await setEnabled(word==='enable');return word==='enable'?'Retrieviewer enabled':'Retrieviewer disabled';}
-   if(word==='ball'||word==='treat'){
+   if(word==='ball'||word==='treat'||word==='tug'){
     if(!plugin)return enabled?'Retrieviewer is still loading':'Retrieviewer is disabled; run /retrieviewer enable';
     return interact(word)?`Retrieviewer: ${word} accepted`:`Retrieviewer is busy; ${word} not accepted`;
    }

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

@@ -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++){
@@ -111,10 +112,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 +128,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{
@@ -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,20 +20,26 @@ 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,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;},
-  pause(value){alive();paused=!!value;last=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=pet.frame(viewport);inFlight=true;
-   try{send(cropFrame(frame,revision));}catch(error){inFlight=false;throw error;}return true;
+   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'].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;nextPaint=0;}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();}},
  };
 }