@bitefoundry/retrieviewer 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# Retrieviewer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+**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.
+
+## 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.
+
+1. Install:
+
+   ```powershell
+   npm install -g @bitefoundry/retrieviewer
+   ```
+
+2. Run and choose the app window you want your puppy to live on:
+
+   ```powershell
+   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.
+
+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).
+
+## Optional: native OpenCode pane
+
+```sh
+retrieviewer enable --agent opencode --yes
+opencode
+```
+
+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.
+
+Inside OpenCode use `/retrieviewer ball`, `/retrieviewer treat`, or
+`/retrieviewer disable`. See [installation and removal](./INSTALLING.md).
+
+## Embed in your own TUI
+
+Install `@bitefoundry/retrieviewer` in your app, without `-g`, then use the host callbacks:
+
+```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')
+// 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.
+
+- [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).
+
+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.

package/RELEASING.md

@@ -0,0 +1,70 @@
+# Retrieviewer 0.0.2 release process
+
+Target: `@bitefoundry/retrieviewer@0.0.2`, public npm registry, `latest` tag.
+The npm organization `bitefoundry` uses the free public-packages plan; account
+`shinick` owns the organization.
+
+## Approval and licensing
+
+The project owner explicitly authorized first publication on 2026-10-23 and
+selected MIT code + CC BY-SA 4.0 artwork. The earlier unpublished restrictive
+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.
+
+`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.
+Passing tests does not itself provide a new publication authorization.
+
+## Checks before publication
+
+```sh
+npm test
+npm run test:package
+npm run release:check
+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 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.
+
+## 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
+the user's own verification flow. Never put credentials in files or chat.
+After publication, verify registry name/version/license/integrity and exercise
+a fresh registry installation. A prepared or uploaded candidate is not the same
+as a verified live package.
+
+For later CI releases, consider GitHub Actions OIDC trusted publishing after an
+audited source repository and exact workflow exist:
+https://docs.npmjs.com/trusted-publishers/
+
+## Support boundaries
+
+The default Q5 art and runtime are unchanged by this release. 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.
+
+Historical research notes remain local and are not current support promises.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,17 @@
+# 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
+  `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
+  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
+
+The generated puppy artwork is separately CC BY-SA 4.0, not MIT. Its reference
+photographers (Scott, CC BY 2.0; Stefan Bauer, CC BY-SA 2.5) and adaptation history
+are credited in ATTRIBUTION.md. Original photographs are not bundled. See LICENSE,
+LICENSE-CODE, ASSETS-LICENSE.md and the bounded ASSET-PROVENANCE.md review. No
+comprehensive legal-clearance or exclusive AI-output ownership claim is made.

package/TRADEMARKS.md

@@ -0,0 +1,21 @@
+# Names and origin
+
+BiteFoundry and Retrieviewer are the project's brand and product names. No claim
+is made here that either is a registered trademark or has passed legal clearance.
+Owning a GitHub/npm namespace is not equivalent to obtaining trademark rights.
+
+Neither the MIT code license nor the CC artwork license grants a general
+right to market a different product as an official BiteFoundry/Retrieviewer
+release. Accurate descriptive references and required attribution are allowed.
+Clearly identify modified distributions and unaffiliated integrations; do not
+falsely imply endorsement. Do not use the registered trademark symbol (R) unless
+and until the relevant registration and scope justify it.
+
+This notice does not limit lawful referential uses, statutory exceptions or
+the MIT permissions for code or the CC permissions for artwork. It does not
+require separate permission for lawful commercial reuse of the CC artwork, and
+does not claim exclusive rights over generic
+retriever imagery, dog behavior, the Braille rendering technique or ideas.
+
+Domestic word-mark research is being conducted separately. No application,
+registration, paid service engagement or fee payment is authorized by this file.

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/braille.mjs

@@ -0,0 +1,45 @@
+// Unicode 2x4 cells, the same dot numbering used by AuraDeck's Braille canvas.
+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));
+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');
+  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'){
+    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;};
+    for(let y=0;y<height;y++){
+      const direction=y%2?-1:1;
+      for(let k=0;k<width;k++){
+        const x=direction===1?k:width-1-k,i=y*width+x,old=values[i],value=old>=.5?1:0,error=old-value;
+        bits[i]=value;add(x+direction,y,error,7);add(x-direction,y+1,error,3);add(x,y+1,error,5);add(x+direction,y+1,error,1);
+      }
+    }
+  }
+  const columns=Math.ceil(width/2),rows=Math.ceil(height/4),lines=[];
+  for(let cy=0;cy<rows;cy++){
+    let line='';
+    for(let cx=0;cx<columns;cx++){
+      let mask=0;for(let dy=0;dy<4;dy++)for(let dx=0;dx<2;dx++){
+        const x=cx*2+dx,y=cy*4+dy;if(x<width&&y<height&&bits[y*width+x])mask|=BRAILLE_BITS[dy][dx];
+      }
+      line+=String.fromCodePoint(0x2800+mask);
+    }
+    lines.push(line);
+  }
+  return {text:lines.join('\n'),columns,rows,dots:bits.reduce((a,b)=>a+b,0)};
+}

package/examples/bridge.py

@@ -0,0 +1,62 @@
+"""Minimal non-JS host: one plain frame, no terminal/input ownership.
+
+python examples/bridge.py [--bridge /installed/path/retrieviewer-stdio.mjs]
+Use request(op='tick', dt=elapsed_seconds, columns=..., rows=...) in your TUI loop.
+Node >=20 is required. Only Python's standard library is used.
+"""
+import argparse
+import json
+from pathlib import Path
+import subprocess
+import sys
+
+
+class PetBridge:
+    def __init__(self, bridge):
+        self.process = subprocess.Popen(
+            ["node", str(bridge)], stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+            text=True, encoding="utf-8", bufsize=1,
+        )
+        self.serial = 0
+        try:
+            ready = json.loads(self.process.stdout.readline())
+            if ready != {"event": "ready", "protocol": 1}:
+                raise RuntimeError("Unsupported pet protocol")
+        except BaseException:
+            self.close()
+            raise
+
+    def request(self, **request):
+        self.serial += 1
+        request["id"] = self.serial
+        self.process.stdin.write(json.dumps(request) + "\n")
+        self.process.stdin.flush()
+        response = json.loads(self.process.stdout.readline())
+        if response.get("id") != self.serial or not response.get("ok"):
+            raise RuntimeError(response.get("error", "Pet protocol mismatch"))
+        return response
+
+    def close(self):
+        if self.process.stdin and not self.process.stdin.closed:
+            self.process.stdin.close()  # EOF releases pet even after host errors.
+        try:
+            self.process.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            self.process.terminate()
+            self.process.wait(timeout=5)
+        finally:
+            self.process.stdout.close()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--bridge", type=Path,
+                        default=Path(__file__).resolve().parents[1] / "retrieviewer-stdio.mjs")
+    args = parser.parse_args()
+    pet = PetBridge(args.bridge)
+    try:
+        frame = pet.request(op="tick", dt=1 / 30, columns=48, rows=14)
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stdout.write(frame["text"] + "\n")
+    finally:
+        pet.close()

package/examples/embed.mjs

@@ -0,0 +1,15 @@
+// Minimal embed: print one plain Braille frame and exit. No fullscreen, no ANSI.
+// Run from anywhere: node examples/embed.mjs [columns] [rows]
+import {createPet} from '../retrieviewer.mjs';
+
+const columns=Number(process.argv[2]??48),rows=Number(process.argv[3]??14);
+const pet=await createPet();
+try{
+ // A real TUI calls step(elapsedSeconds) from ITS OWN loop (timer, render tick,
+ // input poll), then frame() with the current pane size. Here we fake 3 s of life.
+ for(let i=0;i<90;i++)pet.step(1/30);
+ const {text}=pet.frame({columns,rows});
+ process.stdout.write(text+'\n');
+}finally{
+ pet.dispose(); // release caches/renderer when the pane closes
+}

package/examples/live.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// Opt-in terminal host. The imported pet itself never touches terminal I/O.
+import {createPet} from '../retrieviewer.mjs';
+import {once} from 'node:events';
+
+const pet=await createPet({artProfile:process.argv.includes('--original')?'original':'q5'}),out=process.stdout,input=process.stdin;
+if(!out.isTTY||!input.isTTY){
+ try{out.write(pet.frame({columns:80,rows:24}).text+'\n');}finally{pet.dispose();}
+}else{
+ let stopped=false,paused=false,last=performance.now(),previous=[],key='';
+ const wasRaw=!!input.isRaw;
+ const stop=()=>{stopped=true;};
+ 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;}
+ }};
+ process.on('SIGINT',stop);process.on('SIGTERM',stop);
+ input.setRawMode(true);input.resume();input.on('data',data);
+ out.write('\x1b[?1049h\x1b[?25l\x1b[2J');
+ try{
+  while(!stopped){
+   const start=performance.now();if(!paused)pet.step((start-last)/1000);last=start;
+   const columns=Math.max(1,(out.columns??80)-1),available=Math.max(1,(out.rows??24)-2);
+   const rows=Math.min(available,Math.max(1,Math.floor(125000/columns)));
+   const nextKey=`${columns}/${rows}`;
+   if(key!==nextKey){key=nextKey;previous=[];out.write('\x1b[2J');}
+   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);
+   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))));
+  }
+ }finally{
+  process.off('SIGINT',stop);process.off('SIGTERM',stop);input.off('data',data);
+  input.setRawMode(wasRaw);input.pause();out.write('\x1b[0m\x1b[?25h\x1b[?1049l');pet.dispose();
+ }
+}

package/examples/plugin.mjs

@@ -0,0 +1,21 @@
+// Plugin embed with a host-owned loop: the host supplies the pane size, receives
+// frames and drives time with tick(). No timers, raw mode or escape codes here.
+// Run from an installed package: node examples/plugin.mjs [columns] [rows]
+import {createPetPlugin} from '@bitefoundry/retrieviewer/plugin';
+
+const columns=Number(process.argv[2]??48),rows=Number(process.argv[3]??14);
+let latest='';
+const plugin=await createPetPlugin({host:{
+ getSize:()=>({columns,rows}),   // return null while the pane is hidden
+ render:frame=>{latest=frame.text;}, // copy what you keep; pixels are borrowed
+ clear:()=>{latest='';},
+}});
+try{
+ // A real TUI calls tick(elapsedSeconds) from ITS OWN render loop. Here: 3 s of life.
+ for(let i=0;i<90;i++)plugin.tick(1/30);
+ const lines=latest.split('\n');
+ if(lines.length!==rows||lines.some(l=>[...l].length!==columns||!/^[⠀-⣿]*$/u.test(l)))throw Error('frame is not exact plain Braille');
+ process.stdout.write(latest+'\n');
+}finally{
+ plugin.dispose(); // stops the pet and calls clear() once
+}