@bitefoundry/retrieviewer 0.0.1 → 0.0.3

package/DESKTOP-PLATFORMS.md

@@ -0,0 +1,70 @@
+# Native desktop adapters — 0.0.3
+
+Version0.0.3 includes Windows, Linux X11 and experimental macOS adapters. Windows
+and the AlmaLinux8 X11 baseline have live verification; macOS has no runtime verification.
+Installation takes two steps: `npm install -g @bitefoundry/retrieviewer`,
+then `retrieviewer desktop`. No app patch, wrapper, shell profile or auto-start entry.
+
+## Design and status
+
+| Platform | Adapter | Current verification boundary |
+| --- | --- | --- |
+| Windows10/11 | .NET Framework/Win32 layered window | Live verified; shared-adapter regression checks passed on this host |
+| macOS | Built-in osascript/JXA AppKit, no Python/Xcode/browser runtime | Experimental; no macOS runtime available on this Windows host |
+| Linux X11 | Python3.6+ stdlib ctypes + X11/Xrender/Xext | AlmaLinux8 GLIBC2.28/Python3.6.8/Node22.23.4 live checks passed on owned Xvfb + Openbox + xcompmgr |
+| Linux native Wayland | No arbitrary-window tracking adapter | Refused, including sessions exposing an Xwayland DISPLAY; no insecure compositor workaround |
+
+Linux needs a running Xorg/X11 desktop with an ARGB visual, SHAPE input extension
+and a compositing window manager. A headless/server-only AlmaLinux installation
+cannot display desktop windows. System Python3.6+ is used; AlmaLinux8's
+`/usr/libexec/platform-python` is a fallback. No pip packages, GTK, Qt, Electron,
+native npm addons or on-machine C/C++ compilation are required on Linux. Missing
+capabilities cause a clear error rather than silently installing packages or
+changing a login/session/privacy setting. The source must not require a newer
+GLIBC just because the development workstation has one.
+
+AlmaLinux8 users should use an officially maintained Node22 build compatible
+with their GLIBC2.28 system. The package's Node>=20 range is not a promise that
+every future upstream Node binary will run on an old OS. The baseline test uses
+official Node22.23.4 linux-x64, SHA256
+`1805bcd35e6815559bd2eb97db438d3fdb0eb3a5e6a977b7c1badca76337e9ce`.
+
+## Low-resource behavior
+
+Linux/macOS worker loops default to15fps, Windows retains30fps. Real elapsed time
+drives the existing fixed-step animation: fewer drawn frames do not deliberately
+speed the dog up. There is at most one frame in flight. Only the cropped, nonblank
+Braille rectangle crosses the pipe and is painted. Hidden/inactive/minimized
+time is paused and never replayed on reveal. Native adapters should default to
+coarser cells/bounded grids on large displays instead of rendering a4K framebuffer.
+This is a design target, not a claim of zero CPU use or a measured memory minimum.
+
+In the owned1280×800 Alma8 test the Node engine RSS was about179MiB, plus the
+Python helper. This is not a minimum-memory requirement or proof of4K performance.
+
+All adapters reuse the same Q5 art and behavior engine. POSIX control sockets use
+short `/tmp/retrieviewer-overlay-<uid>-<uuid>.sock` addresses with0600 permissions,
+an independently random token in the0600 session record, and conservative cleanup.
+Windows named pipes remain compatible with the previous launcher. No token is
+printed in status or sent over a network. Same-user hostile software remains
+outside the security boundary. Stop/remove must not kill or modify the target app.
+
+## Evidence
+
+Keep actual checks, failures, skips and the tested OS separate. Static macOS source
+tests cannot establish AppKit/JXA behavior or privacy permissions. An Ubuntu test
+with a newer libc is not AlmaLinux8/GLIBC2.28 certification. A fake window manager
+is not proof of composited visual quality. Test containers may install their own
+QA tools, but product launch never installs OS packages or changes the user's OS.
+
+Recorded Linux checks: real ARGB painting, empty input shape, moved target geometry,
+stale-frame discard, hide on unmap, target disappearance, foreground retention,
+actual Node-to-Python worker painting, accepted ball interaction,0600 UNIX socket,
+rejected wrong token, clean worker/helper exit, and remove lifecycle. This covers
+an isolated desktop, not every GNOME/KDE theme, compositor or physical monitor.
+Evidence: `dist/alma8-qa/posix-worker.json` and source QA script output.
+
+- [Node build platform requirements](https://github.com/nodejs/node/blob/v22.23.4/BUILDING.md)
+- [X11 Shape protocol](https://xorg.freedesktop.org/archive/X11R7.7/doc/xextproto/shape.html)
+- [Wayland client surface isolation](https://wayland.pages.freedesktop.org/wayland.freedesktop.org/docs/book/Protocol.html)
+- [Apple NSWindow](https://developer.apple.com/documentation/appkit/nswindow)

package/INSTALLING.md

@@ -1,6 +1,19 @@
-# Enable Retrieviewer in an agent TUI
+# Install Retrieviewer
 
-0.0.1 includes an installer CLI and a native OpenCode TUI adapter. It does **not** claim
+Desktop setup (Node20+; [OS requirements and verification](DESKTOP-PLATFORMS.md)):
+
+1. `npm install -g @bitefoundry/retrieviewer`
+2. `retrieviewer desktop` — select the app window in the picker.
+
+No agent configuration is needed for this separate transparent companion.
+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
+Framework4 compiler. See [Windows controls and removal](WINDOWS-COMPANION.md).
+
+## Optional native OpenCode integration
+
+0.0.3 also includes an installer CLI and a native OpenCode TUI adapter. It does **not** claim
 that every MCP client can display animated UI. Native OpenCode rendering uses its
 official TUI plugin slot, not another terminal, a wrapper, or a modified binary.
 Other agent IDs are discoverable but refused until an adapter is implemented.
@@ -12,7 +25,7 @@ agent are required. Source code is MIT; bundled puppy artwork is CC BY-SA 4.0.
 Keep the included ATTRIBUTION.md and asset license when redistributing artwork.
 
 ```sh
-npm install -g @bitefoundry/retrieviewer@0.0.1
+npm install -g @bitefoundry/retrieviewer
 retrieviewer enable
 ```
 
@@ -31,9 +44,7 @@ version is **not automatically certified**. Existing project configuration can
 override global settings; doctor checks registration, not arbitrary host precedence.
 Do not put API keys in Retrieviewer settings. No credentials are needed by the pet.
 
-After a future public release, the install command will instead be
-`npm install -g @bitefoundry/retrieviewer@0.0.1`. Do not run that registry command
-before publication. The package also exports `./tui` for npm-aware OpenCode plugin
+The package also exports `./tui` for npm-aware OpenCode plugin
 loaders; package-name discovery has not yet been live-tested against npm.
 The verified installer continues using its local directory URL, not that new path.
 
@@ -54,6 +65,17 @@ the new package. No automatic global install is done by the package itself.
 
 ## Commands
 
+For the separate native overlay (Windows since0.0.2; Linux X11 and experimental macOS since0.0.3),
+see [desktop platforms](DESKTOP-PLATFORMS.md). It does not register a Codex plugin
+or change the way an agent is launched:
+
+```powershell
+retrieviewer desktop
+retrieviewer desktop-status --json
+retrieviewer desktop-stop
+retrieviewer desktop-remove --yes
+```
+
 ```sh
 retrieviewer agents --json
 retrieviewer status --agent opencode

package/README.md

@@ -1,9 +1,9 @@
 # Retrieviewer
 
-An autonomous, fluffy Braille retriever that lives in a pane of your terminal UI.
+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.
 
-**Version 0.0.1.** Source code is MIT; puppy artwork is CC BY-SA 4.0, including
+**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).
@@ -11,11 +11,39 @@ The complete package is not MIT-only.
 
 ## Install
 
-Node.js >=20 and a terminal font supporting Unicode Braille are required.
+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).
+
+1. Install:
+
+   ```sh
+   npm install -g @bitefoundry/retrieviewer
+   ```
+
+2. Run and choose the app window you want your puppy to live on:
+
+   ```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.
+
+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).
+
+## Optional: native OpenCode pane
 
 ```sh
-npm install -g @bitefoundry/retrieviewer@0.0.1
-retrieviewer enable --agent opencode --dry-run
 retrieviewer enable --agent opencode --yes
 opencode
 ```

package/RELEASING.md

@@ -1,6 +1,6 @@
-# Retrieviewer 0.0.1 release process
+# Retrieviewer 0.0.3 release process
 
-Target: `@bitefoundry/retrieviewer@0.0.1`, public npm registry, `latest` tag.
+Target: `@bitefoundry/retrieviewer@0.0.3`, public npm registry, `latest` tag.
 The npm organization `bitefoundry` uses the free public-packages plan; account
 `shinick` owns the organization.
 
@@ -12,6 +12,12 @@ 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.
+
 `release-policy.json` has four independent approval gates and the CC artwork
 license identifier. The guard still refuses false/missing approvals, private
 packages, missing attribution/notices, install scripts and known leaked paths.
@@ -29,7 +35,7 @@ npm publish --dry-run --access public --registry=https://registry.npmjs.org/
 The package test packs the exact candidate, installs it in a fresh offline
 consumer, byte-compares all installed files and checks exports, frames,
 interactions, lifecycle, examples, JSONL and isolated installer settings.
-Its report is `dist/package-check.json`; it does not publish or edit live
+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,
@@ -37,7 +43,7 @@ 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.
 
-## First publish
+## Publish the tested tarball
 
 Confirm `npm whoami` is the intended account. Publish only the tested candidate
 with explicit public access; complete any npm browser/2FA verification through
@@ -58,4 +64,9 @@ 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 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/WINDOWS-COMPANION.md

@@ -0,0 +1,113 @@
+# Windows companion — 0.0.2
+
+This is a separate transparent desktop window, not a Codex plugin or a terminal
+wrapper. Version0.0.2 includes it; version0.0.1 does not. Setup is two steps:
+
+1. `npm install -g @bitefoundry/retrieviewer`
+2. `retrieviewer desktop` — choose the app window in the picker.
+
+Choose a supported ordinary Windows app window (including a terminal containing
+Codex). Then use your app normally, without a
+wrapper, shell alias, patched binary, changed credentials, or agent configuration.
+The helper uses native Windows/.NET Framework facilities and the existing Node
+pet engine. No Electron, Chromium, downloaded helper binary or new npm dependency.
+Windows10/11 x64 with Node20+ and the .NET Framework4 compiler is required. Other
+desktop platforms and exclusive fullscreen/security surfaces are not certified.
+Launch reports
+that the picker is ready, **not** that the user has selected a window or visually
+approved the pet.
+
+## Interaction and window scope
+
+- The original Q5 Braille artwork/behavior engine is reused without new sprites.
+- The pet is click-through and non-activating. It does not read keyboard input.
+- A small separate, non-activating control strip offers ball, treat, choose window,
+  pause and exit. These buttons consume their own clicks, not terminal typing.
+- Ball/treat use the existing engine interactions, including busy/cooldown rules.
+  Ball currently uses its existing preset destination, **not free mouse aiming**.
+- The overlay follows the selected window's client rectangle. It hides and stops
+  simulation when another app is foreground, the target is minimized, or paused.
+  The control strip remains available while paused in the selected window.
+- It binds a whole top-level window, **not a terminal tab/pane**. Switching tabs
+  inside that window does not automatically rebind or identify the running agent.
+- Selection is per launch. There is no process scanning to infer Codex sessions,
+  screen scraping/OCR, chat capture, global keyboard hook or input injection.
+  The picker locally reads window titles/process names; tracking reads window
+  geometry, foreground state, visibility and owning process ID.
+- No automatic startup, background scheduled task, registry entry or MCP is added.
+  Exit stops both the painter and engine. If either process closes, its counterpart
+  exits too. Losing the target hides the pet; tray selection can attach another.
+
+## Stop, remove, and recover
+
+```powershell
+retrieviewer desktop-status --json
+retrieviewer desktop-stop
+retrieviewer desktop-clean --yes
+```
+
+One-command companion removal (stop, wait for exit, remove only its cache):
+
+```powershell
+retrieviewer desktop-remove --yes
+```
+
+The tray icon also provides window selection, hide/resume and exit. `desktop-stop`
+asks the companion to exit through an authenticated local named pipe; it never
+kills a PID from a stale file. The worker may terminate only its own stuck child
+painter after a graceful timeout. Cache cleanup refuses a live/unreachable worker,
+symlinks/junctions and unrecognized session records. It removes only recognized
+helper cache filenames; unrelated files and agent/pet settings remain untouched.
+
+Own files are under `~/.config/retrieviewer/desktop` (or RETRIEVIEWER_HOME/desktop):
+one hash-named compiled helper and a transient local session capability record.
+The token is not printed by status and is never sent over a network. Same-user
+local software is not treated as an adversarial security boundary. No screenshot,
+terminal content or window title is persisted by this companion.
+
+For a globally installed copy, stop/remove the companion before
+`npm uninstall -g @bitefoundry/retrieviewer`. Other native OpenCode registrations,
+if any, must first be disconnected with the existing explicit disconnect command.
+This companion does not change or remove a pre-existing Codex `/pets` pack.
+
+## Rendering and bounded work
+
+Native pixels are dots decoded from the engine's existing Braille cells, on an
+alpha-transparent bitmap. Every frame starts clear, avoiding previous-frame paw
+trails. Only the nonblank bounding rectangle crosses IPC and is painted; the
+native window does not allocate a full-screen transparent bitmap. A request/ack
+bridge permits only one frame in flight. Viewport revisions discard frames from
+an old size/position; discarded frames are acknowledged to avoid deadlock. Hidden
+time is not replayed when the pet becomes visible. The engine targets30fps, but
+the actual frame rate depends on CPU, window resolution and Windows scheduling.
+
+## Search-first decision and evidence
+
+Reused `createPet` and its side-effect-free host API. A small native Win32 painter
+was selected for Windows instead of adding an Electron runtime or a PTY wrapper.
+The former adds another browser runtime; the latter changes how Codex is launched
+and was explicitly rejected. This is not a claim of cross-platform support or a
+benchmarked memory advantage; measurements belong to the local validation.
+
+- [Layered windows and mouse passthrough](https://learn.microsoft.com/en-us/windows/win32/winmsg/window-features#layered-windows)
+- [UpdateLayeredWindow](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-updatelayeredwindow)
+- [No-activate extended window style](https://learn.microsoft.com/en-us/windows/win32/winmsg/extended-window-styles)
+- [SetWindowPos without activation](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-setwindowpos)
+- [Electron alternative](https://www.electronjs.org/docs/latest/tutorial/custom-window-interactions)
+
+`node --test retrieviewer-desktop.test.mjs` covers transport/cropping/backpressure,
+hidden-time resets, CLI isolation, authenticated control transport and conservative
+cleanup. Native validation must additionally test layered window rendering, focus,
+geometry, minimize/restore, controls and lifecycle on an actual Windows desktop.
+Do not equate style checks or a rendered PNG with end-user visual approval.
+
+Local validation on2026-10-23:281 automated tests passed, real packaged offline
+consumer passed, and the real native worker painted frames with the actual pet
+engine. The native ball button reached the engine and was accepted; an incorrect
+control token was rejected. Owned off-screen native-window checks passed position
+tracking, minimize/restore, passthrough/no-activate styles and foreground retention.
+The worker and painter both exited. Node RSS was about157MiB in that small-window
+check (not total app memory or a4K performance claim). A Windows GUI startup bug
+was fixed by building a GUI-subsystem helper and not applying SW_HIDE to it; the
+real user picker was verified in Windows' visible main-window list. User visual
+approval after selecting a terminal remains separate.

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.