@bitefoundry/retrieviewer 0.0.2 → 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,16 +1,19 @@
 # Install Retrieviewer
 
-Windows desktop setup (Node20+ and the Windows .NET Framework4 compiler required):
+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.
-See [desktop controls, compatibility and removal](WINDOWS-COMPANION.md).
+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.2 also includes an installer CLI and a native OpenCode TUI adapter. It does **not** claim
+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.
@@ -62,8 +65,8 @@ the new package. No automatic global install is done by the package itself.
 
 ## Commands
 
-For the separate Windows overlay (included since0.0.2),
-see [Windows companion](WINDOWS-COMPANION.md). It does not register a Codex plugin
+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

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.2.** 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,18 +11,21 @@ The complete package is not MIT-only.
 
 ## Install
 
-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.
+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:
 
-   ```powershell
+   ```sh
    npm install -g @bitefoundry/retrieviewer
    ```
 
 2. Run and choose the app window you want your puppy to live on:
 
-   ```powershell
+   ```sh
    retrieviewer desktop
    ```
 
@@ -30,13 +33,13 @@ 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.
+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
-[desktop support and removal](./WINDOWS-COMPANION.md).
+[platform support](./DESKTOP-PLATFORMS.md) and [Windows controls and removal](./WINDOWS-COMPANION.md).
 
 ## Optional: native OpenCode pane
 

package/RELEASING.md

@@ -1,6 +1,6 @@
-# Retrieviewer 0.0.2 release process
+# Retrieviewer 0.0.3 release process
 
-Target: `@bitefoundry/retrieviewer@0.0.2`, 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,9 +12,11 @@ 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 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
@@ -62,9 +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 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/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.