@bitefoundry/retrieviewer 0.0.0-stage → 0.0.2

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/integrations/windows-overlay/Overlay.cs

@@ -0,0 +1,259 @@
+// Native Windows painter for the existing Braille engine. No injection, keyboard
+// hooks, terminal output, screen capture, network, registry or agent config access.
+// Built locally with the Windows .NET Framework compiler; no downloaded binaries.
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Drawing;
+using System.Drawing.Imaging;
+using System.IO;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Threading;
+using System.Web.Script.Serialization;
+using System.Windows.Forms;
+
+static class Native {
+    [StructLayout(LayoutKind.Sequential)] internal struct POINT { internal int X,Y; internal POINT(int x,int y){X=x;Y=y;} }
+    [StructLayout(LayoutKind.Sequential)] internal struct SIZE { internal int Width,Height; internal SIZE(int w,int h){Width=w;Height=h;} }
+    [StructLayout(LayoutKind.Sequential)] internal struct RECT { internal int Left,Top,Right,Bottom; }
+    [StructLayout(LayoutKind.Sequential,Pack=1)] internal struct BLEND { internal byte Op,Flags,Alpha,Format; }
+    internal delegate bool EnumProc(IntPtr hwnd,IntPtr data);
+    [DllImport("user32.dll")] internal static extern bool EnumWindows(EnumProc proc,IntPtr data);
+    [DllImport("user32.dll")] internal static extern bool IsWindowVisible(IntPtr hwnd);
+    [DllImport("user32.dll")] internal static extern bool IsWindow(IntPtr hwnd);
+    [DllImport("user32.dll")] internal static extern bool IsIconic(IntPtr hwnd);
+    [DllImport("user32.dll")] internal static extern IntPtr GetForegroundWindow();
+    [DllImport("user32.dll",CharSet=CharSet.Unicode)] internal static extern int GetWindowText(IntPtr hwnd,StringBuilder text,int length);
+    [DllImport("user32.dll")] internal static extern uint GetWindowThreadProcessId(IntPtr hwnd,out uint pid);
+    [DllImport("user32.dll")] internal static extern bool GetClientRect(IntPtr hwnd,out RECT rect);
+    [DllImport("user32.dll")] internal static extern bool GetWindowRect(IntPtr hwnd,out RECT rect);
+    [DllImport("user32.dll")] internal static extern bool ClientToScreen(IntPtr hwnd,ref POINT point);
+    [DllImport("user32.dll")] internal static extern bool SetWindowPos(IntPtr hwnd,IntPtr after,int x,int y,int w,int h,uint flags);
+    [DllImport("user32.dll")] internal static extern int GetWindowLong(IntPtr hwnd,int index);
+    [DllImport("user32.dll")] internal static extern bool ShowWindow(IntPtr hwnd,int command);
+    [DllImport("user32.dll")] internal static extern bool SetProcessDPIAware();
+    [DllImport("user32.dll")] internal static extern bool SetProcessDpiAwarenessContext(IntPtr context);
+    [DllImport("user32.dll")] internal static extern IntPtr GetDC(IntPtr hwnd);
+    [DllImport("user32.dll")] internal static extern int ReleaseDC(IntPtr hwnd,IntPtr dc);
+    [DllImport("gdi32.dll")] internal static extern IntPtr CreateCompatibleDC(IntPtr dc);
+    [DllImport("gdi32.dll")] internal static extern IntPtr SelectObject(IntPtr dc,IntPtr bitmap);
+    [DllImport("gdi32.dll")] internal static extern bool DeleteDC(IntPtr dc);
+    [DllImport("gdi32.dll")] internal static extern bool DeleteObject(IntPtr obj);
+    [DllImport("user32.dll",SetLastError=true)] internal static extern bool UpdateLayeredWindow(IntPtr hwnd,IntPtr dc,ref POINT dst,ref SIZE size,IntPtr src,ref POINT point,int key,ref BLEND blend,int flags);
+    internal static Rectangle ClientBounds(IntPtr hwnd){
+        RECT r;POINT p=new POINT(0,0);
+        if(!GetClientRect(hwnd,out r)||!ClientToScreen(hwnd,ref p))return Rectangle.Empty;
+        return new Rectangle(p.X,p.Y,r.Right-r.Left,r.Bottom-r.Top);
+    }
+    internal static void Place(IntPtr hwnd,Rectangle rect){
+        SetWindowPos(hwnd,new IntPtr(-1),rect.X,rect.Y,rect.Width,rect.Height,0x10|0x40); // TOPMOST, NOACTIVATE, SHOWWINDOW
+    }
+}
+
+class QuietWindow : Form {
+    internal QuietWindow(){FormBorderStyle=FormBorderStyle.None;ShowInTaskbar=false;AutoScaleMode=AutoScaleMode.None;StartPosition=FormStartPosition.Manual;}
+    protected override bool ShowWithoutActivation {get{return true;}}
+    protected override CreateParams CreateParams {get{CreateParams p=base.CreateParams;p.ExStyle|=0x08000000|0x80;return p;}} // NOACTIVATE, TOOLWINDOW
+    protected override void WndProc(ref Message m){if(m.Msg==0x21){m.Result=new IntPtr(3);return;}base.WndProc(ref m);} // MA_NOACTIVATE
+}
+
+sealed class PetWindow : QuietWindow {
+    protected override CreateParams CreateParams {get{CreateParams p=base.CreateParams;p.ExStyle|=0x80000|0x20;return p;}} // LAYERED + TRANSPARENT
+    internal int PaintedDots;
+    internal Bitmap PaintFrame(Dictionary<string,object> m,int cell,Rectangle canvas){
+        int cols=Program.Int(m,"columns"),rows=Program.Int(m,"rows"),cx=Program.Int(m,"x"),cy=Program.Int(m,"y");
+        string text=Program.Str(m,"text");
+        if(cols==0&&rows==0&&text.Length==0){Hide();return null;}
+        if(cols<1||rows<1||cols*rows>125000||cx<0||cy<0||(cx+cols)*cell>canvas.Width||(cy+rows)*cell*2>canvas.Height)throw new Exception("Out-of-bounds overlay frame");
+        string[] lines=text.Split('\n');if(lines.Length!=rows)throw new Exception("Invalid overlay row count");
+        Bitmap image=new Bitmap(cols*cell,rows*cell*2,PixelFormat.Format32bppPArgb);
+        try{
+            using(Graphics g=Graphics.FromImage(image))using(Brush ink=new SolidBrush(Color.FromArgb(245,248,242,232))){
+                g.Clear(Color.Transparent);g.SmoothingMode=System.Drawing.Drawing2D.SmoothingMode.AntiAlias;
+                int[] dx={0,0,0,1,1,1,0,1},dy={0,1,2,0,1,2,3,3};float step=cell/2f,diameter=Math.Max(1.1f,step*.48f);PaintedDots=0;
+                for(int y=0;y<rows;y++){
+                    if(lines[y].Length!=cols)throw new Exception("Invalid overlay column count");
+                    for(int x=0;x<cols;x++){
+                        int mask=lines[y][x]-0x2800;if(mask<0||mask>255)throw new Exception("Not a Braille frame");
+                        for(int bit=0;bit<8;bit++)if((mask&(1<<bit))!=0){
+                            float px=x*cell+(dx[bit]+.5f)*step,py=y*cell*2+(dy[bit]+.5f)*step;
+                            g.FillEllipse(ink,px-diameter/2,py-diameter/2,diameter,diameter);PaintedDots++;
+                        }
+                    }
+                }
+            }
+            Rectangle destination=new Rectangle(canvas.X+cx*cell,canvas.Y+cy*cell*2,image.Width,image.Height);
+            if(!Visible){Bounds=destination;Show();}
+            IntPtr screen=Native.GetDC(IntPtr.Zero),memory=Native.CreateCompatibleDC(screen),bitmap=IntPtr.Zero,old=IntPtr.Zero;
+            try{
+                bitmap=image.GetHbitmap(Color.FromArgb(0));old=Native.SelectObject(memory,bitmap);
+                Native.POINT target=new Native.POINT(canvas.X+cx*cell,canvas.Y+cy*cell*2),source=new Native.POINT(0,0);
+                Native.SIZE size=new Native.SIZE(image.Width,image.Height);Native.BLEND blend=new Native.BLEND();blend.Alpha=255;blend.Format=1;
+                if(!Native.UpdateLayeredWindow(Handle,screen,ref target,ref size,memory,ref source,0,ref blend,2))throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error());
+                Native.Place(Handle,new Rectangle(target.X,target.Y,size.Width,size.Height));
+            }finally{if(old!=IntPtr.Zero)Native.SelectObject(memory,old);if(bitmap!=IntPtr.Zero)Native.DeleteObject(bitmap);Native.DeleteDC(memory);Native.ReleaseDC(IntPtr.Zero,screen);}
+            return image;
+        }catch{image.Dispose();throw;}
+    }
+}
+
+sealed class TargetItem {
+    internal IntPtr Window;internal uint Process;internal string Title;internal bool Terminal;
+    public override string ToString(){return Title;}
+}
+
+sealed class Companion : ApplicationContext {
+    readonly PetWindow pet=new PetWindow();readonly QuietWindow bar=new QuietWindow();
+    readonly NotifyIcon tray=new NotifyIcon();readonly System.Windows.Forms.Timer clock=new System.Windows.Forms.Timer();
+    readonly JavaScriptSerializer json=new JavaScriptSerializer();readonly object inputLock=new object();
+    readonly Queue<Dictionary<string,object>> messages=new Queue<Dictionary<string,object>>();
+    TargetItem target;Form pickerWindow;QuietWindow testTarget;readonly bool testMode;Rectangle canvas;int revision=0,cell=8;bool visible=false,paused=false,loaded=false,quitting=false,picking=false,announced=false;
+    Label status=new Label();Mutex mutex;
+    internal Companion(Mutex single,bool diagnostic){
+        mutex=single;testMode=diagnostic;bar.Text="Retrieviewer controls";bar.Size=new Size(354,40);bar.BackColor=Color.FromArgb(28,30,34);bar.ForeColor=Color.White;
+        bar.Font=new Font("Segoe UI",9);bar.Controls.Add(MakeButton("공",8,()=>Interact("ball")));bar.Controls.Add(MakeButton("간식",52,()=>Interact("treat")));
+        bar.Controls.Add(MakeButton("창",102,ChooseTarget));bar.Controls.Add(MakeButton("쉼",146,TogglePause));bar.Controls.Add(MakeButton("종료",190,Quit));
+        status.AutoSize=false;status.Location=new Point(240,12);status.Size=new Size(110,22);status.Text="준비 중";bar.Controls.Add(status);
+        ContextMenuStrip menu=new ContextMenuStrip();menu.Items.Add("다른 창 선택",null,(s,e)=>ChooseTarget());menu.Items.Add("숨기기 / 다시 표시",null,(s,e)=>TogglePause());menu.Items.Add("종료",null,(s,e)=>Quit());
+        tray.Icon=SystemIcons.Application;tray.Text="Retrieviewer · 창 선택";tray.ContextMenuStrip=menu;tray.Visible=true;tray.DoubleClick+=(s,e)=>ChooseTarget();
+        // Handles are created on the UI thread before the reader can signal EOF.
+        IntPtr unused=bar.Handle;unused=pet.Handle;
+        Thread reader=new Thread(ReadInput);reader.IsBackground=true;reader.Start();
+        clock.Interval=16;clock.Tick+=(s,e)=>Tick();clock.Start();
+        if(testMode){
+            testTarget=new QuietWindow();testTarget.Bounds=new Rectangle(-12000,-12000,1280,800);testTarget.Show();
+            target=new TargetItem{Window=testTarget.Handle,Process=(uint)Process.GetCurrentProcess().Id,Title="owned diagnostic window"};
+        }
+    }
+    Button MakeButton(string title,int x,Action action){
+        Button b=new Button();b.Text=title;b.TabStop=false;b.Size=new Size(title=="간식"?46:40,28);b.Location=new Point(x,6);b.FlatStyle=FlatStyle.Flat;b.FlatAppearance.BorderSize=0;b.BackColor=Color.FromArgb(48,51,58);b.ForeColor=Color.White;b.Click+=(s,e)=>action();return b;
+    }
+    void ReadInput(){
+        try{
+            string line;while((line=Program.Input.ReadLine())!=null){
+                if(line.Length>800000)break;
+                Dictionary<string,object> value=json.Deserialize<Dictionary<string,object>>(line);
+                lock(inputLock){if(messages.Count>4)break;messages.Enqueue(value);}
+            }
+        }catch{}
+        try{bar.BeginInvoke(new Action(Quit));}catch{}
+    }
+    void Interact(string kind){if(!loaded||paused)return;Program.Emit(new {type="interact",kind=kind});}
+    void TogglePause(){paused=!paused;Program.Emit(new {type="pause",paused=paused});Track(true);}
+    void Tick(){
+        if(quitting)return;
+        try{
+            if(!announced){announced=true;if(!testMode)ChooseTarget();Program.Emit(new {type="ready",pickerVisible=pickerWindow!=null&&pickerWindow.Visible});}
+            Track(false);
+            for(;;){Dictionary<string,object> m;lock(inputLock){if(messages.Count==0)break;m=messages.Dequeue();}
+                string type=Program.Str(m,"type");
+                if(type=="quit"){Quit();return;}
+                if(type=="loaded"){loaded=true;status.Text="함께 노는 중";if(testMode)((Button)bar.Controls[0]).PerformClick();continue;}
+                if(type=="interaction"){status.Text=Program.Bool(m,"accepted")?"좋아!":"잠깐 기다려";continue;}
+                if(type=="error"){status.Text="엔진 오류";Quit();return;}
+                if(type=="frame"){
+                    // Always acknowledge discarded frames too, otherwise resizing can deadlock the sender.
+                    bool painted=visible&&!paused&&Program.Int(m,"revision")==revision;
+                    if(painted){using(Bitmap image=pet.PaintFrame(m,cell,canvas)){} }
+                    Program.Emit(new {type="ack",painted=painted});
+                }
+            }
+        }catch(Exception error){Program.Emit(new {type="error",message=error.Message});Quit();}
+    }
+    void Track(bool force){
+        Rectangle next=Rectangle.Empty;bool show=false;uint pid;
+        if(target!=null&&(!Native.IsWindow(target.Window)||Native.GetWindowThreadProcessId(target.Window,out pid)==0||pid!=target.Process)){target=null;}
+        if(target!=null&&!Native.IsIconic(target.Window)&&Native.IsWindowVisible(target.Window)){
+            next=Native.ClientBounds(target.Window);IntPtr foreground=Native.GetForegroundWindow();show=!picking&&(testMode||foreground==target.Window||foreground==bar.Handle)&&next.Width>=160&&next.Height>=120;
+        }
+        int nextCell=8;while(next.Width/nextCell*(next.Height/(nextCell*2))>125000&&nextCell<16)nextCell+=2;
+        if(nextCell==14)nextCell=16;
+        int columns=next.Width/nextCell,rows=next.Height/(nextCell*2);
+        if(force||show!=visible||next!=canvas||nextCell!=cell){
+            visible=show;canvas=next;cell=nextCell;revision++;pet.Hide();
+            Program.Emit(new {type="viewport",revision=revision,visible=show&&!paused,selected=target!=null,columns=columns,rows=rows,cellWidth=cell,cellHeight=cell*2});
+        }
+        if(visible){
+            if(!bar.Visible)bar.Show();Native.Place(bar.Handle,new Rectangle(canvas.Right-bar.Width-10,canvas.Top+10,bar.Width,bar.Height));
+            if(paused)pet.Hide();
+        }else{pet.Hide();bar.Hide();}
+    }
+    List<TargetItem> Targets(){
+        List<TargetItem> result=new List<TargetItem>();uint mine=(uint)Process.GetCurrentProcess().Id;
+        Native.EnumWindows((hwnd,data)=>{
+            uint pid;Native.GetWindowThreadProcessId(hwnd,out pid);if(pid==mine||!Native.IsWindowVisible(hwnd))return true;
+            StringBuilder name=new StringBuilder(512);Native.GetWindowText(hwnd,name,name.Capacity);if(name.Length==0)return true;
+            string process="";try{using(Process p=Process.GetProcessById((int)pid)){process=p.ProcessName;}}catch{}
+            bool terminal=process.Equals("WindowsTerminal",StringComparison.OrdinalIgnoreCase)||process.IndexOf("wezterm",StringComparison.OrdinalIgnoreCase)>=0||process=="OpenConsole"||process=="conhost"||process=="mintty";
+            result.Add(new TargetItem{Window=hwnd,Process=pid,Title=(terminal?"[터미널] ":"")+name.ToString()+" · "+process,Terminal=terminal});return true;
+        },IntPtr.Zero);
+        result.Sort((a,b)=>a.Terminal==b.Terminal?String.Compare(a.Title,b.Title,StringComparison.CurrentCulture):a.Terminal?-1:1);return result;
+    }
+    void ChooseTarget(){
+        if(picking||quitting)return;picking=true;Track(true);
+        Form picker=new Form();pickerWindow=picker;
+        {
+            picker.Text="Retrieviewer · 함께 있을 창";picker.Size=new Size(650,230);picker.StartPosition=FormStartPosition.CenterScreen;picker.FormBorderStyle=FormBorderStyle.FixedDialog;picker.MaximizeBox=false;picker.MinimizeBox=false;picker.Font=new Font("Segoe UI",10);
+            picker.ShowInTaskbar=true;picker.TopMost=true;
+            Label hint=new Label();hint.Text="Codex를 사용하는 터미널 창을 선택하세요.\n내용을 읽지 않고 창의 위치·크기만 따라갑니다. 탭은 구별하지 않습니다.";hint.SetBounds(18,16,610,50);
+            ComboBox list=new ComboBox();list.DropDownStyle=ComboBoxStyle.DropDownList;list.SetBounds(18,76,600,28);foreach(TargetItem item in Targets())list.Items.Add(item);if(list.Items.Count>0)list.SelectedIndex=0;
+            Button refresh=new Button();refresh.Text="새로 고침";refresh.SetBounds(18,124,100,34);refresh.Click+=(s,e)=>{list.Items.Clear();foreach(TargetItem item in Targets())list.Items.Add(item);if(list.Items.Count>0)list.SelectedIndex=0;};
+            Button attach=new Button();attach.Text="이 창에 붙이기";attach.SetBounds(378,124,140,34);attach.Click+=(s,e)=>{if(list.SelectedItem!=null){target=(TargetItem)list.SelectedItem;paused=false;Program.Emit(new {type="pause",paused=false});picker.Close();}};
+            Button cancel=new Button();cancel.Text="취소";cancel.SetBounds(528,124,90,34);cancel.Click+=(s,e)=>picker.Close();
+            picker.Controls.AddRange(new Control[]{hint,list,refresh,attach,cancel});
+            picker.FormClosed+=(s,e)=>{pickerWindow=null;picking=false;Program.Emit(new {type="picker",visible=false});if(!quitting){if(target==null)status.Text="트레이에서 창 선택";tray.Text=target==null?"Retrieviewer · 창 선택":"Retrieviewer · 창에 붙어 있음";Track(true);}picker.Dispose();};
+            picker.Show();Native.ShowWindow(picker.Handle,5);Program.Emit(new {type="picker",visible=Native.IsWindowVisible(picker.Handle)});
+        }
+    }
+    void Quit(){if(quitting)return;quitting=true;clock.Stop();if(pickerWindow!=null)pickerWindow.Close();pet.Close();bar.Close();tray.Visible=false;tray.Dispose();Program.Emit(new {type="quit"});ExitThread();}
+    protected override void Dispose(bool disposing){if(disposing){clock.Dispose();pet.Dispose();bar.Dispose();tray.Dispose();if(testTarget!=null)testTarget.Dispose();if(mutex!=null){mutex.ReleaseMutex();mutex.Dispose();mutex=null;}}base.Dispose(disposing);}
+}
+
+static class Program {
+    static readonly object outputLock=new object();
+    internal static TextReader Input;static TextWriter Output;
+    internal static void Emit(object value){lock(outputLock){try{Output.WriteLine(new JavaScriptSerializer().Serialize(value));Output.Flush();}catch{Environment.Exit(0);}}}
+    internal static int Int(Dictionary<string,object> m,string key){return Convert.ToInt32(m[key]);}
+    internal static string Str(Dictionary<string,object> m,string key){return Convert.ToString(m[key]);}
+    internal static bool Bool(Dictionary<string,object> m,string key){return Convert.ToBoolean(m[key]);}
+    [STAThread] static int Main(string[] args){
+        try{
+            // GUI-subsystem processes have redirected handles but no console code
+            // page. Setting Console.*Encoding can throw before startup on Windows.
+            Input=new StreamReader(Console.OpenStandardInput(),new UTF8Encoding(false),false);
+            Output=new StreamWriter(Console.OpenStandardOutput(),new UTF8Encoding(false));
+            try{Native.SetProcessDpiAwarenessContext(new IntPtr(-4));}catch(EntryPointNotFoundException){Native.SetProcessDPIAware();}
+            Application.EnableVisualStyles();Application.SetCompatibleTextRenderingDefault(false);
+            if(args.Length==2&&args[0]=="--self-test")return SelfTest(args[1]);
+            bool ipcTest=args.Length==1&&args[0]=="--ipc-test";
+            if(args.Length!=0&&!ipcTest)throw new Exception("Unsupported native painter argument");
+            // Diagnostics own only off-screen windows and must not stop or contend
+            // with a user's running companion during a release verification.
+            string mutexName="Local\\BiteFoundry.Retrieviewer.Overlay."+System.Security.Principal.WindowsIdentity.GetCurrent().User.Value+(ipcTest?".Diagnostics."+Process.GetCurrentProcess().Id:"");
+            bool first;Mutex single=new Mutex(true,mutexName,out first);
+            if(!first){single.Dispose();Emit(new {type="error",message="A Retrieviewer companion is already running"});return 2;}
+            using(Companion context=new Companion(single,ipcTest))Application.Run(context);return 0;
+        }catch(Exception error){Emit(new {type="error",message=error.Message});return 1;}
+    }
+    static int SelfTest(string proof){
+        // Uses only our own off-screen windows. Does NOT click/type in or capture a user application.
+        IntPtr foreground=Native.GetForegroundWindow();
+        Dictionary<string,object> frame=new JavaScriptSerializer().Deserialize<Dictionary<string,object>>(Input.ReadLine());
+        using(QuietWindow target=new QuietWindow())using(PetWindow pet=new PetWindow()){
+            target.Bounds=new Rectangle(-12000,-12000,1600,1000);target.Show();Application.DoEvents();
+            Rectangle first=Native.ClientBounds(target.Handle);using(Bitmap bitmap=pet.PaintFrame(frame,8,first)){bitmap.Save(proof,ImageFormat.Png);}
+            int styles=Native.GetWindowLong(pet.Handle,-20);bool clickThrough=(styles&0x20)!=0,noActivate=(styles&0x08000000)!=0,layered=(styles&0x80000)!=0;
+            target.Bounds=new Rectangle(-11000,-11500,1800,1100);Application.DoEvents();Rectangle moved=Native.ClientBounds(target.Handle);
+            using(Bitmap bitmap=pet.PaintFrame(frame,8,moved)){}
+            Native.RECT actual;Native.GetWindowRect(pet.Handle,out actual);
+            int expectedX=moved.Left+Int(frame,"x")*8,expectedY=moved.Top+Int(frame,"y")*16;
+            bool follows=actual.Left==expectedX&&actual.Top==expectedY;
+            Native.ShowWindow(target.Handle,7);Application.DoEvents();bool minimized=Native.IsIconic(target.Handle);pet.Hide();bool hidden=!pet.Visible;
+            Native.ShowWindow(target.Handle,4);Application.DoEvents();bool restored=!Native.IsIconic(target.Handle);
+            bool focus=Native.GetForegroundWindow()==foreground;
+            bool passed=clickThrough&&noActivate&&layered&&follows&&minimized&&hidden&&restored&&focus&&pet.PaintedDots>0;
+            Emit(new {type="self-test",passed=passed,clickThroughStyle=clickThrough,noActivateStyle=noActivate,layered=layered,followGeometry=follows,expectedX=expectedX,expectedY=expectedY,actualX=actual.Left,actualY=actual.Top,minimize=minimized,hide=hidden,restore=restored,foregroundPreserved=focus,dots=pet.PaintedDots,proof=proof});return passed?0:1;
+        }
+    }
+}

package/integrations/windows-overlay/desktop.mjs

@@ -0,0 +1,87 @@
+// Explicit Windows companion launcher. Never imports the pet on help/status/stop.
+import {spawn,execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import {readFile,mkdir,lstat,unlink,open,rename,readdir} from 'node:fs/promises';
+import {createHash,randomUUID} from 'node:crypto';
+import {join,dirname} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {createConnection} from 'node:net';
+import {getConfigPaths} from '../../retrieviewer-config.mjs';
+const exec=promisify(execFile);
+const SOURCE=new URL('./Overlay.cs',import.meta.url);
+export function desktopPaths(options={}){const root=join(getConfigPaths(options).root,'desktop');return {root,session:join(root,'session.json')};}
+export async function noLink(path){try{if((await lstat(path)).isSymbolicLink())throw Error('Refusing desktop symlink: '+path);}catch(e){if(e.code!=='ENOENT')throw e;}}
+export async function prepareRoot(options={}){
+ const parent=getConfigPaths(options).root,{root}=desktopPaths(options);await noLink(dirname(parent));await noLink(parent);await noLink(root);await mkdir(root,{recursive:true,mode:0o700});return desktopPaths(options);
+}
+export async function readSession(options={}){
+ const {root,session}=desktopPaths(options);await noLink(dirname(root));await noLink(root);await noLink(session);
+ let data;try{data=JSON.parse(await readFile(session,'utf8'));}catch(e){if(e.code==='ENOENT')return null;throw e;}
+ if(data?.owner!=='bitefoundry-retrieviewer-overlay-v1'||!Number.isInteger(data.pid)||data.pid<=0||!/^\\\\\.\\pipe\\retrieviewer-overlay-[a-f0-9-]{36}$/.test(data.pipe)||!/^[a-f0-9]{64}$/.test(data.token))throw Error('Unrecognized desktop session; not modifying it');
+ return data;
+}
+export function requestSession(session,command){
+ return new Promise((resolve,reject)=>{
+  const socket=createConnection(session.pipe);let text='',done=false;
+  const finish=(error,value)=>{if(done)return;done=true;socket.destroy();error?reject(error):resolve(value);};
+  socket.setTimeout(1800,()=>finish(Error('Desktop control timed out')));
+  socket.on('connect',()=>socket.write(JSON.stringify({token:session.token,command})+'\n'));
+  socket.on('data',bytes=>{text+=bytes.toString('utf8');if(text.length>65536)return finish(Error('Oversized desktop response'));if(text.includes('\n'))try{finish(null,JSON.parse(text.split('\n')[0]));}catch(e){finish(e);}});
+  socket.on('error',e=>finish(e));socket.on('end',()=>{if(!done)finish(Error('Desktop control closed without a response'));});
+ });
+}
+export async function desktopStatus(options={}){
+ const session=await readSession(options);if(!session)return {running:false};
+ try{return await requestSession(session,'status');}catch(error){let alive=true;try{process.kill(session.pid,0);}catch(e){if(e.code==='ESRCH')alive=false;}
+  return {running:alive,reachable:false,stale:!alive,pid:session.pid,reason:error.code??error.message};}
+}
+export async function stopDesktop(options={}){
+ const session=await readSession(options);if(!session)return {running:false,stopped:true};
+ const result=await desktopStatus(options);
+ if(result.stale){await unlink(desktopPaths(options).session);return {running:false,stopped:true,staleSessionRemoved:true};}
+ if(result.reachable===false)throw Error('Desktop process is not responding; close it from its tray icon. No PID was killed.');
+ await requestSession(session,'stop');
+ // The stop response acknowledges the request, not native process termination.
+ // Wait before advertising success so a following cleanup cannot race an in-use exe.
+ for(let i=0;i<60;i++){
+  try{process.kill(session.pid,0);}catch(e){if(e.code==='ESRCH')return {running:false,stopped:true};throw e;}
+  await new Promise(resolve=>setTimeout(resolve,100));
+ }
+ throw Error('Desktop accepted stop but has not exited; cache preserved. Retry after it closes.');
+}
+export async function buildHelper(options={}){
+ if(process.platform!=='win32')throw Error('The transparent companion currently supports Windows only');
+ const {root}=await prepareRoot(options),source=await readFile(SOURCE),hash=createHash('sha256').update(source).digest('hex').slice(0,20);
+ const executable=join(root,`overlay-${hash}.exe`);await noLink(executable);
+ try{await lstat(executable);return executable;}catch(e){if(e.code!=='ENOENT')throw e;}
+ const compiler=join(process.env.SystemRoot??'C:\\Windows','Microsoft.NET','Framework64','v4.0.30319','csc.exe');
+ const temporary=join(root,`build-${randomUUID()}.exe`);
+ try{
+  await exec(compiler,['/nologo','/target:winexe','/platform:anycpu','/optimize+','/codepage:65001','/reference:System.Windows.Forms.dll','/reference:System.Drawing.dll','/reference:System.Web.Extensions.dll','/out:'+temporary,fileURLToPath(SOURCE)],{windowsHide:true,timeout:30000,maxBuffer:1024*1024});
+  await rename(temporary,executable);
+ }catch(error){await unlink(temporary).catch(()=>{});throw Error('Windows overlay build failed: '+(error.stdout??error.message));}
+ return executable;
+}
+export async function startDesktop(options={}){
+ const status=await desktopStatus(options);if(status.running)return {...status,alreadyRunning:true};
+ if(status.stale)await stopDesktop(options);
+ const executable=await buildHelper(options);
+ return new Promise((resolve,reject)=>{
+  const child=spawn(process.execPath,[fileURLToPath(new URL('./worker.mjs',import.meta.url)),executable],{detached:true,windowsHide:true,stdio:['ignore','ignore','ignore','ipc'],env:{...process.env,RETRIEVIEWER_HOME:getConfigPaths(options).root}});
+  let settled=false;const finish=(error,message)=>{if(settled)return;settled=true;clearTimeout(timer);if(child.connected)child.disconnect();child.unref();error?reject(error):resolve(message);};
+  const timer=setTimeout(()=>{if(child.connected)child.send({command:'abort'});finish(Error('Desktop startup timed out; no agent settings changed'));},20000);
+  child.on('error',error=>finish(error));child.on('message',message=>message.error?finish(Error(message.error)):finish(null,message));child.on('exit',code=>finish(Error('Desktop exited during startup ('+code+')')));
+ });
+}
+export async function cleanDesktop(options={}){
+ const status=await desktopStatus(options);if(status.running)throw Error('Stop the desktop companion before removing its cache');
+ const {root,session}=desktopPaths(options);if(status.stale)await unlink(session);
+ let files;try{await noLink(root);files=await readdir(root);}catch(e){if(e.code==='ENOENT')return {removed:[]};throw e;}
+ const removed=[];
+ for(const name of files)if(/^overlay-[a-f0-9]{20}\.exe$/.test(name)||/^build-[a-f0-9-]{36}\.exe$/.test(name)){
+  const path=join(root,name);await noLink(path);if(!(await lstat(path)).isFile())throw Error('Refusing non-file desktop cache entry');await unlink(path);removed.push(name);
+ }
+ // Unknown files and all other Retrieviewer/agent settings are deliberately kept.
+ return {removed,preservedOtherFiles:true};
+}
+export async function removeDesktop(options={}){await stopDesktop(options);return {stopped:true,...await cleanDesktop(options)};}

package/integrations/windows-overlay/protocol.mjs

@@ -0,0 +1,39 @@
+// Pure transport helpers: no art, timers, processes or I/O on import.
+export function viewportOf(message){
+ if(message?.type!=='viewport'||!Number.isSafeInteger(message.revision)||message.revision<1||typeof message.visible!=='boolean')throw Error('Invalid overlay viewport');
+ if(!message.visible)return null;
+ const {columns,rows,cellWidth,cellHeight}=message;
+ if(!Number.isInteger(columns)||!Number.isInteger(rows)||columns<1||rows<1||columns*rows>125000||![6,8,10,12,16].includes(cellWidth)||cellHeight!==cellWidth*2)throw Error('Invalid overlay grid');
+ return {columns,rows,cellAspect:.5,revision:message.revision,cellWidth,cellHeight};
+}
+export function cropFrame(frame,revision){
+ const lines=frame.text.split('\n');
+ if(lines.length!==frame.rows||lines.some(s=>s.length!==frame.columns))throw Error('Invalid frame dimensions');
+ let left=frame.columns,top=frame.rows,right=-1,bottom=-1;
+ for(let y=0;y<lines.length;y++)for(let x=0;x<lines[y].length;x++){
+  const c=lines[y].charCodeAt(x);if(c<0x2800||c>0x28ff)throw Error('Only Braille cells may cross the overlay bridge');
+  if(c!==0x2800){left=Math.min(left,x);right=Math.max(right,x);top=Math.min(top,y);bottom=Math.max(bottom,y);}
+ }
+ return {type:'frame',revision,x:right<0?0:left,y:right<0?0:top,columns:right<0?0:right-left+1,rows:right<0?0:bottom-top+1,
+  text:right<0?'':lines.slice(top,bottom+1).map(s=>s.slice(left,right+1)).join('\n')};
+}
+
+// Request/ack rendering: never queue obsolete frames behind a slow native painter.
+export function createFramePump({pet,send,now=()=>performance.now()}){
+ let viewport=null,inFlight=false,last=null,revision=0,paused=false,disposed=false;
+ const alive=()=>{if(disposed)throw Error('Overlay pump is disposed');};
+ return {
+  viewport(message){alive();const next=viewportOf(message);revision=message.revision;viewport=next;last=null;},
+  pause(value){alive();paused=!!value;last=null;},
+  ack(){alive();inFlight=false;},
+  tick(){
+   alive();if(inFlight||!viewport||paused)return false;
+   const t=now(),dt=last===null?0:Math.max(0,(t-last)/1000);last=t;
+   pet.step(dt);const frame=pet.frame(viewport);inFlight=true;
+   try{send(cropFrame(frame,revision));}catch(error){inFlight=false;throw error;}return true;
+  },
+  interact(kind){alive();if(!['ball','treat'].includes(kind))throw Error('Invalid overlay interaction');return pet.interact(kind);},
+  get hidden(){return !viewport||paused;},
+  dispose(){if(!disposed){disposed=true;viewport=null;pet.dispose();}},
+ };
+}