@bitefoundry/retrieviewer 0.0.2 → 0.0.4

package/README.md

@@ -1,87 +1,148 @@
-# 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 in a pane of your terminal UI.
-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.2.** 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.
 
-Windows10/11 x64, Node.js >=20, and the Windows .NET Framework4 compiler are required
-for the desktop companion. The helper builds automatically on first launch.
+## 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.
 
-   ```powershell
-   npm install -g @bitefoundry/retrieviewer
+1. Install (or update):
+
+   ```sh
+   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:
 
-   ```powershell
+   ```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
-Windows window, **not a widget injected into another app**. macOS/Linux desktop
-overlays, 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.
+
+> **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
-[desktop support 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.
+
+## Put it inside your own TUI
 
-const puppy = await createPetPlugin({host: {
-  getSize: () => ({columns: pane.width, rows: pane.height}),
-  render: ({text}) => pane.setContent(text),
-  onError: error => logToYourApp(error),
-}});
+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,6 @@
-# Retrieviewer 0.0.2 release process
+# Retrieviewer 0.0.4 release process
 
-Target: `@bitefoundry/retrieviewer@0.0.2`, public npm registry, `latest` tag.
+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,9 +12,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 also explicitly authorized publishing0.0.2 with the Windows companion
-and the two-step npm install/desktop launch guide. No new art license or Codex
-modification is part of this release. Do not replace the0.0.1 registry artifact.
+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
@@ -36,10 +42,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
 
@@ -56,15 +68,16 @@ 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.
 See INSTALLING.md for support and removal.
 
-The separate Windows transparent companion uses native layered windows plus the
-same pet engine. Test its real installed copy with an isolated state directory and
-owned off-screen diagnostic windows; do not stop the user's live companion merely
-to run QA. Source/native diagnostic evidence is not a cross-platform certification.
+The separate transparent companion uses platform-native windows plus the same pet
+engine. Test real installed copies with isolated state and owned diagnostic windows;
+do not stop the user's live companion merely to run QA. See DESKTOP-PLATFORMS.md
+for verified checks, experimental macOS status and unsupported environments.
 
 Historical research notes remain local and are not current support promises.

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/desktop/platform.mjs

@@ -0,0 +1,27 @@
+// Dependency-free platform selection. Importing performs no probing or I/O.
+import {posix} from 'node:path';
+export function desktopPlatform({platform=process.platform,env=process.env,glibc}={}){
+ if(platform==='win32')return {id:'windows-overlay',fps:30,helper:'windows',experimental:false};
+ if(platform==='darwin')return {id:'macos-overlay',fps:15,helper:'macos',experimental:true};
+ if(platform==='linux'){
+  if(env.XDG_SESSION_TYPE?.trim().toLowerCase()==='wayland'||env.WAYLAND_DISPLAY)throw Error('Native Wayland cannot safely track arbitrary app windows. Log in to an Xorg/X11 session; no compositor or privacy settings will be changed.');
+  if(!env.DISPLAY)throw Error('Linux desktop requires an X11 DISPLAY and a compositing window manager. Headless/SSH sessions are not a desktop.');
+  if(glibc!==undefined){const parts=String(glibc).split('.').map(Number);if(!/^\d+\.\d+(?:\.\d+)?$/.test(String(glibc))||parts[0]<2||(parts[0]===2&&parts[1]<28))throw Error('Linux desktop requires GLIBC2.28 or later (AlmaLinux8 baseline).');}
+  return {id:'linux-x11-overlay',fps:15,helper:'linux',experimental:true};
+ }
+ throw Error('Desktop companion supports Windows, macOS and Linux X11 only');
+}
+export function controlAddress({platform=process.platform,uuid,uid=process.getuid?.()??0}={}){
+ if(!/^[a-f0-9-]{36}$/.test(uuid))throw Error('Invalid desktop control UUID');
+ if(platform==='win32')return '\\\\.\\pipe\\retrieviewer-overlay-'+uuid;
+ if(!Number.isSafeInteger(uid)||uid<0)throw Error('Invalid desktop user ID');
+ // Short enough for macOS's104-byte sockaddr_un, regardless of HOME/TMPDIR length.
+ return posix.join('/tmp',`retrieviewer-overlay-${uid}-${uuid}.sock`);
+}
+export function validControlAddress(value){return typeof value==='string'&&(/^\\\\\.\\pipe\\retrieviewer-overlay-[a-f0-9-]{36}$/.test(value)||/^\/tmp\/retrieviewer-overlay-\d+-[a-f0-9-]{36}\.sock$/.test(value));}
+export function parseHelperSpec(argv){
+ if(argv[0]!=='--helper-spec')return {command:argv[0],args:argv[1]==='--ipc-test'?['--ipc-test']:[],mode:'windows-overlay',fps:30};
+ const value=JSON.parse(argv[1]);
+ if(!value||typeof value.command!=='string'||!value.command||value.command.includes('\0')||!Array.isArray(value.args)||value.args.some(a=>typeof a!=='string'||a.includes('\0'))||!['windows-overlay','macos-overlay','linux-x11-overlay'].includes(value.mode)||!Number.isInteger(value.fps)||value.fps<5||value.fps>30)throw Error('Invalid desktop helper descriptor');
+ return value;
+}

package/integrations/linux-overlay/README.md

@@ -0,0 +1,83 @@
+# Linux X11 companion painter (implementation-ready, not release-certified)
+
+`overlay.py` is the Linux counterpart of `../windows-overlay/Overlay.cs`: a
+native transparent painter driven over the same NDJSON stdin/stdout bridge by the
+Node pet engine. It draws only the Braille frames it receives; it adds no art.
+
+## Why Python + ctypes
+
+- Python 3.6+ **standard library only**. `ctypes` binds the X client libraries
+  the desktop already ships: `libX11.so.6`, `libXrender.so.1`, `libXext.so.6`.
+- No compiler, PyPI package, GTK/Qt/gi/Tk, Electron or npm native addon, so there
+  is no GLIBC/Node ABI coupling. Target baseline: AlmaLinux 8 (GLIBC 2.28,
+  platform Python 3.6) on old hardware.
+- Struct layouts and constants were checked against the official X.org headers
+  (libX11 1.8.13, libXrender 0.9.12, libXext 1.3.4, xorgproto 2025.1) with a
+  compiled `offsetof`/`sizeof` probe on x86_64. 32-bit layouts were not
+  compiled; every field uses `c_long`/`c_ulong`/pointers so they follow the C ABI.
+
+## Requirements and refusals (fail closed, one JSON `error` line, exit 2)
+
+| Condition | Result |
+|---|---|
+| `WAYLAND_DISPLAY` set or `XDG_SESSION_TYPE=wayland` (even with `DISPLAY`/XWayland) | Refused: log in to an Xorg session. Wayland cannot safely follow/stack over another app. |
+| `DISPLAY` unset / display cannot be opened | Refused with the display name. |
+| No SHAPE ≥ 1.1 (input shapes), no RENDER, no XRender ARGB32 32-bit visual | Refused. |
+| No compositing manager (`_NET_WM_CM_Sn` unowned) | Refused instead of painting an opaque black box. |
+| WM without EWMH `_NET_CLIENT_LIST` / `_NET_ACTIVE_WINDOW` | Refused. |
+| Missing X client library | Refused; it never installs packages. |
+
+## Bridge (same as Windows)
+
+stdin: `frame{revision,x,y,columns,rows,text}`, `loaded`, `interaction`, `error`, `quit`.
+stdout: `ready{pickerVisible}`, `picker{visible}`,
+`viewport{revision,visible,selected,columns,rows,cellWidth,cellHeight=2*cellWidth}`,
+`ack{painted}`, `interact{kind:ball|treat}`, `pause{paused}`, `quit`.
+
+- One outstanding frame; discarded, hidden and stale-revision frames are still ACKed.
+- Only U+2800..U+28FF cells; ≤ 125000 cells per frame. Default cell is 16 px and the
+  viewport grid is capped at 20000 cells (`--cell 6|8|10|12|16` to change the cell).
+- Only the cropped bounding box is rasterized; the pet window is resized to it and
+  fully overwritten, and is unmapped on every viewport change, so no stale trails.
+- stdin EOF quits; every owned window, GC and colormap is released and the display
+  connection closed. The single-instance lock is an abstract Unix socket (no file).
+
+## Window behavior
+
+- Explicit picker lists EWMH client windows (title and `/proc/PID/comm` only,
+  terminals first). Titles are drawn ASCII-only (`?` for other characters).
+  The picker sets `WM_HINTS.input=False` so the WM should not move keyboard focus.
+- Tracking is read-only polling (~30 Hz) of the target's attributes, root-relative
+  position, `_NET_WM_STATE_HIDDEN`, `_NET_WM_PID` and `_NET_ACTIVE_WINDOW`. The pet
+  shows only while the target is the active window, viewable, not minimized and at
+  least 160×120. A vanished target (BadWindow is trapped) or reused PID hides it.
+- Pet: override-redirect ARGB32 window with an **empty ShapeInput region**, so all
+  pointer input passes through; no keyboard selection, grabs or hotkeys.
+- Controls: a separate override-redirect strip (Ball, Treat, Window, Pause, Quit)
+  consumes only its own clicks and is never focused.
+- Target windows and global focus are never modified. No capture, injection,
+  network, root access or Wayland compositor changes.
+
+## Commands
+
+```sh
+python3 overlay.py                  # bridge mode (spawned by the Node worker)
+python3 overlay.py --ipc-test       # bridge mode with an owned off-screen stand-in target
+python3 overlay.py --check-json     # environment diagnostics, creates no windows
+python3 overlay.py --self-test :99  # owned windows on an explicitly named isolated display (e.g. Xvfb)
+```
+
+`--self-test` refuses an implicit display; it does not require a compositor and
+checks painting, input-shape emptiness, geometry following, stale-frame discard,
+hide on unmap, target loss, focus preservation and teardown on owned windows only.
+
+## Known limits
+
+- Parent verification after the worker report: AlmaLinux8/GLIBC2.28, Python3.6.8,
+  Node22.23.4, owned Xvfb + Openbox + xcompmgr passed native painting, empty input
+  shape, focus/geometry/hide/stale-frame checks and real Node worker ball/exit
+  lifecycle. This is not certification of every physical desktop/compositor.
+- Compositors may draw a shadow around override-redirect windows; the pet window
+  declares `_NET_WM_WINDOW_TYPE_DND`, which most compositors leave unshadowed.
+- The overlay is raised every 250 ms while visible because a WM restacks the active
+  target above override-redirect windows when it is clicked.