@bitefoundry/retrieviewer 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,62 @@
-# 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.1.** 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
+
+Node.js >=20 and a terminal font supporting Unicode Braille are required.
+
+```sh
+npm install -g @bitefoundry/retrieviewer@0.0.1
+retrieviewer enable --agent opencode --dry-run
+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,61 @@
+# Retrieviewer 0.0.1 release process
+
+Target: `@bitefoundry/retrieviewer@0.0.1`, 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.
+
+`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 `dist/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.
+
+## First publish
+
+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.
+
+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/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
+}

package/integrations/opencode/runtime.mjs

@@ -0,0 +1,195 @@
+// Host-neutral controller behind the OpenCode TUI widget. One pet core is shared by
+// every mounted slot view; the most recently attached view receives frames. Import
+// and creation start no timer and load no art or settings: the first attach() starts
+// a <=1 Hz settings poll, and only an enabled, visible view loads the pet. It never
+// touches stdin/stdout, the alternate screen, processes, windows or the network.
+
+export const AGENT='opencode';
+export const DEFAULT_FPS=30;
+export const POLL_MS=1000;
+export const HEARTBEAT_MS=5000;
+// Bounded so the host prompt stays usable: at most 64x12 cells, hidden when the
+// terminal is too small for a legible pet.
+export const LIMITS=Object.freeze({maxColumns:64,maxRows:12,minColumns:20,minRows:5,sideMargin:4,reservedRows:14});
+export const COMMANDS=Object.freeze(['enable','disable','ball','treat','status']);
+
+const fn=(value,name)=>{if(typeof value!=='function')throw TypeError(`${name} must be a function`);};
+const defaultScheduler=()=>({now:()=>performance.now(),schedule:(callback,delayMs)=>setTimeout(callback,delayMs),cancel:handle=>clearTimeout(handle)});
+const defaultLoadPlugin=async()=>(await import('../../retrieviewer-plugin.mjs')).createPetPlugin;
+const defaultLoadSettings=()=>import('../../retrieviewer-config.mjs');
+
+// Terminal viewport (cells) -> pet pane, or null when hidden/too small.
+export function petViewport(viewport){
+ if(!viewport||typeof viewport!=='object')return null;
+ const {width,height}=viewport;
+ if(!Number.isFinite(width)||!Number.isFinite(height))return null;
+ const columns=Math.min(LIMITS.maxColumns,Math.floor(width)-LIMITS.sideMargin);
+ const rows=Math.min(LIMITS.maxRows,Math.floor((Math.floor(height)-LIMITS.reservedRows)/2));
+ return columns<LIMITS.minColumns||rows<LIMITS.minRows?null:{columns,rows};
+}
+
+export function createOpenCodePetController({hostVersion='unknown',scheduler,fps=DEFAULT_FPS,petOptions,loadPlugin=defaultLoadPlugin,loadSettings=defaultLoadSettings,onError}={}){
+ if(scheduler!==undefined){fn(scheduler?.now,'scheduler.now');fn(scheduler.schedule,'scheduler.schedule');fn(scheduler.cancel,'scheduler.cancel');}
+ fn(loadPlugin,'loadPlugin');fn(loadSettings,'loadSettings');
+ if(onError!==undefined)fn(onError,'onError');
+ const clock=scheduler??defaultScheduler();
+ const views=new Set();
+ let active=null,shown=null,enabled=false,disposed=false;
+ let plugin=null,loading=false,gen=0;
+ let settings=null,pollHandle=null,polling=false,epoch=0,hiddenCheck=null,pollError=null;
+ let receipt=null,writes=Promise.resolve();
+ const report=error=>{try{onError?.(error);}catch{}};
+ const settingsModule=()=>settings??=Promise.resolve().then(loadSettings);
+
+ // Receipts carry our own state only, serialized so phases never reorder.
+ function writeReceipt(phase){
+  if(!receipt)return;
+  const body={hostVersion:String(hostVersion),phase,firstFrameAt:receipt.firstFrameAt,columns:receipt.columns,rows:receipt.rows,frames:receipt.frames};
+  writes=writes.then(async()=>{const m=await settingsModule();await m.writeRuntimeReceipt(AGENT,body);}).catch(report);
+ }
+ function show(view,text){if(!view)return;view.render(text);shown=text?view:(shown===view?null:shown);}
+ function clearShown(){if(shown){const v=shown;shown=null;v.render('');}}
+
+ const host={
+  getSize(){
+   const box=active?petViewport(active.getViewport()):null;
+   if(!box&&!hiddenCheck)hiddenCheck=clock.schedule(()=>{hiddenCheck=null;reconcile();},0);
+   return box;
+  },
+  render(frame){
+   if(!active)return;
+   if(shown&&shown!==active)clearShown();
+   show(active,frame.text);
+   const now=clock.now();
+   if(!receipt){receipt={firstFrameAt:new Date().toISOString(),frames:1,beat:now,columns:frame.columns,rows:frame.rows};writeReceipt('rendering');return;}
+   receipt.frames++;receipt.columns=frame.columns;receipt.rows=frame.rows;
+   if(now-receipt.beat>=HEARTBEAT_MS){receipt.beat=now;writeReceipt('rendering');}
+  },
+  clear:clearShown,
+  onError(error){stopPet();report(error);},
+ };
+
+ function stopPet(){
+  gen++;loading=false;
+  if(hiddenCheck){clock.cancel(hiddenCheck);hiddenCheck=null;}
+  const p=plugin;plugin=null;
+  try{p?.dispose();}catch(error){report(error);}
+  clearShown();
+  if(receipt){writeReceipt('stopped');receipt=null;}
+ }
+ const wanted=()=>!disposed&&enabled&&views.size>0;
+
+ async function load(){
+  const mine=++gen;loading=true;
+  try{
+   const create=await loadPlugin();
+   if(mine!==gen||!wanted())return;
+   const p=await create({host,fps,petOptions,scheduler:clock});
+   // Disabled, unmounted or reloaded while the art loaded: release it unseen.
+   if(mine!==gen||!wanted()){p.dispose();return;}
+   plugin=p;
+  }catch(error){if(mine===gen)report(error);return;}
+  finally{if(mine===gen)loading=false;}
+  reconcile();
+ }
+
+ function reconcile(redraw=false){
+  if(!wanted()){if(plugin||loading||receipt)stopPet();return;}
+  if(!plugin){if(!loading)load();return;}
+  const box=active?petViewport(active.getViewport()):null;
+  // Hidden: no timer and no simulated time until a refresh reveals the pane.
+  if(!box){plugin.pause();clearShown();return;}
+  try{if(!plugin.running)plugin.start();else if(redraw)plugin.render();}
+  catch(error){stopPet();report(error);}
+ }
+
+ function schedulePoll(){
+  if(disposed||views.size===0||pollHandle!==null)return;
+  pollHandle=clock.schedule(()=>{pollHandle=null;poll();},POLL_MS);
+ }
+ async function poll(){
+  if(disposed||views.size===0||polling)return;
+  polling=true;const seen=epoch;
+  try{
+   const m=await settingsModule();
+   const s=await m.readAgentSettings(AGENT);
+   pollError=null;
+   if(seen===epoch&&!disposed){enabled=s?.enabled===true;reconcile();}
+  }catch(error){
+   // A persistent failure (e.g. missing settings module) is reported once, not per poll.
+   const key=String(error?.message??error);
+   if(key!==pollError){pollError=key;report(error);}
+  }
+  finally{polling=false;schedulePoll();}
+ }
+ function stopPolling(){if(pollHandle!==null){clock.cancel(pollHandle);pollHandle=null;}}
+
+ async function setEnabled(value){
+  if(typeof value!=='boolean')throw TypeError('enabled must be boolean');
+  const m=await settingsModule();
+  await m.setAgentEnabled(AGENT,value);
+  epoch++;
+  if(disposed)return;
+  enabled=value;reconcile();
+ }
+ function interact(kind){
+  if(kind!=='ball'&&kind!=='treat')throw TypeError("kind must be 'ball' or 'treat'");
+  return plugin?plugin.interact(kind):false;
+ }
+ function status(){
+  return {enabled,mounted:views.size,loading,running:!!plugin?.running,frames:receipt?.frames??0,columns:receipt?.columns??null,rows:receipt?.rows??null,firstFrameAt:receipt?.firstFrameAt??null};
+ }
+
+ return {
+  // view: {getViewport(): {width,height}|null, render(text: string): void}. Text is
+  // plain Braille (rows lines); '' means show nothing.
+  attach(view){
+   if(disposed)throw Error('OpenCode pet controller is disposed');
+   if(!view||typeof view!=='object')throw TypeError('view must be an object');
+   fn(view.getViewport,'view.getViewport');fn(view.render,'view.render');
+   const record={getViewport:view.getViewport,render:view.render};
+   views.add(record);active=record;
+   if(views.size===1)poll();
+   reconcile(true);
+   let attached=true;
+   return {
+    // Call on resize or visibility change; re-derives the pane from the viewport.
+    refresh(){if(attached&&!disposed)reconcile(true);},
+    detach(){
+     if(!attached)return;attached=false;
+     views.delete(record);
+     if(shown===record)clearShown();
+     if(active===record)active=[...views].at(-1)??null;
+     if(views.size===0)stopPolling();
+     if(!disposed)reconcile(true);
+    },
+   };
+  },
+  setEnabled,
+  interact,
+  status,
+  // Slash handler: '/retrieviewer <enable|disable|ball|treat|status>'.
+  async command(argument){
+   const word=String(argument??'').trim().toLowerCase()||'status';
+   if(word==='enable'||word==='disable'){await setEnabled(word==='enable');return word==='enable'?'Retrieviewer enabled':'Retrieviewer disabled';}
+   if(word==='ball'||word==='treat'){
+    if(!plugin)return enabled?'Retrieviewer is still loading':'Retrieviewer is disabled; run /retrieviewer enable';
+    return interact(word)?`Retrieviewer: ${word} accepted`:`Retrieviewer is busy; ${word} not accepted`;
+   }
+   if(word==='status'){
+    const s=status();
+    return `Retrieviewer ${s.enabled?'enabled':'disabled'}, ${s.running?`rendering ${s.columns}x${s.rows}, ${s.frames} frames`:s.loading?'loading':'idle'}, ${s.mounted} view(s)`;
+   }
+   return `Usage: /retrieviewer ${COMMANDS.join('|')}`;
+  },
+  // Resolves once queued receipt writes have finished (for clean shutdown/tests).
+  settled(){return writes;},
+  get disposed(){return disposed;},
+  dispose(){
+   if(disposed)return writes;
+   disposed=true;stopPolling();stopPet();
+   views.clear();active=null;
+   return writes;
+  },
+ };
+}

package/integrations/opencode/tui.tsx

@@ -0,0 +1,59 @@
+/** @jsxImportSource @opentui/solid */
+// OpenCode v2 TUI plugin: the Retrieviewer pet drawn inside OpenCode's own UI (home
+// footer and session composer slots). The host resolves @opencode/plugin/tui,
+// @opentui/solid and solid-js and compiles this file; no production dependency here.
+// All lifecycle lives in ./runtime.mjs, which loads nothing until a view mounts.
+import {Plugin} from '@opencode/plugin/tui';
+import {useTerminalDimensions} from '@opentui/solid';
+import {createEffect, createSignal, onCleanup, Show} from 'solid-js';
+import {createOpenCodePetController} from './runtime.mjs';
+
+export default Plugin.define({
+ id:'retrieviewer.pet',
+ setup(context){
+  const toast=(message,variant='info')=>context.ui.toast.show({title:'Retrieviewer',message,variant});
+  const pet=createOpenCodePetController({
+   hostVersion:context.app?.version??'unknown',
+   onError:error=>toast(String(error?.message??error),'error'),
+  });
+
+  // One view per mounted slot; all share the single pet core in the controller.
+  function PetView(){
+   const dimensions=useTerminalDimensions();
+   const [text,setText]=createSignal('');
+   const view=pet.attach({
+    getViewport:()=>{const {width,height}=dimensions();return {width,height};},
+    render:value=>setText(value),
+   });
+   createEffect(()=>{dimensions();view.refresh();});
+   onCleanup(()=>view.detach());
+   return (
+    <Show when={text()}>
+     <box flexShrink={0} paddingLeft={2}>
+      <text wrapMode="none" fg={context.theme.text.base}>{text()}</text>
+     </box>
+    </Show>
+   );
+  }
+
+  context.ui.slot({append:'home.footer',render:()=><PetView/>});
+  context.ui.slot({append:'session.composer.top',render:()=><PetView/>});
+  context.keymap.layer(()=>({
+   mode:'global',
+   commands:[{
+    id:'retrieviewer.pet',
+    title:'Retrieviewer pet',
+    description:'enable | disable | ball | treat | status',
+    group:'Retrieviewer',
+    palette:true,
+    slash:{name:'retrieviewer',arguments:true},
+    async run(argument){
+     try{toast(await pet.command(argument));}
+     catch(error){toast(String(error?.message??error),'error');}
+    },
+   }],
+  }));
+
+  return ()=>pet.dispose();
+ },
+});

package/locomotion-core.mjs

@@ -0,0 +1,21 @@
+import * as THREE from 'three';
+import {createAnimal} from './vendor/procedural-animals/src/index.js';
+export const LAB_OPTIONS={variant:'retriever',age:'juvenile',seed:2,quality:'low',worker:false,overrides:{colour:'yellow',stanceSoftMargin:.005}};
+export async function makeLabAnimal(extra={}){
+ return createAnimal('dog',{...LAB_OPTIONS,...extra,overrides:{...LAB_OPTIONS.overrides,...extra.overrides}});
+}
+// Never translate the mesh externally. The gait engine owns root motion + IK.
+export function makeLabController(animal){
+ let target=null,speed=animal.gears.walk;
+ return {get target(){return target;},get speed(){return speed;},setSpeed(kind){
+  if(!['walk','trot','gallop'].includes(kind))throw Error('Unknown gait');
+  speed=animal.gears[kind];if(target)animal.moveTo(target,{speed});
+ },go(x,z){
+  if(![x,z].every(Number.isFinite))throw Error('Invalid ground target');
+  target=new THREE.Vector3(Math.max(-.8,Math.min(.8,x)),0,Math.max(-1.7,Math.min(.3,z)));
+  animal.stopAction();animal.moveTo(target,{speed});
+ },stop(){target=null;animal.stop();},update(dt){
+  if(!Number.isFinite(dt)||dt<0||dt>.1)throw Error('Invalid lab step');animal.update(dt);
+  if(target&&animal.position.distanceTo(target)<.025&&animal.speed<.03){target=null;animal.stop();}
+ }};
+}