@bitefoundry/retrieviewer 0.0.1 → 0.0.3

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,119 @@
+// Explicit native 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';
+import {desktopPlatform,validControlAddress} from '../desktop/platform.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||!validControlAddress(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'));});
+ });
+}
+async function processAlive(pid){
+ try{process.kill(pid,0);}catch(error){if(error.code==='ESRCH')return false;throw error;}
+ if(process.platform==='linux')try{
+  // A container PID1 without a reaper can retain a dead detached worker as Z.
+  // kill(pid,0) alone treats it as alive, falsely making a successful stop fail.
+  const stat=await readFile('/proc/'+pid+'/stat','utf8'),state=stat.slice(stat.lastIndexOf(')')+2).charAt(0);
+  if(state==='Z'||state==='X')return false;
+ }catch(error){if(error.code==='ENOENT')return false;throw error;}
+ return true;
+}
+export async function desktopStatus(options={}){
+ const session=await readSession(options);if(!session)return {running:false};
+ try{return await requestSession(session,'status');}catch(error){const alive=await processAlive(session.pid);
+  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){
+  if(session.pipe.startsWith('/tmp/')){
+   await noLink(session.pipe);
+   try{const entry=await lstat(session.pipe);if(!entry.isSocket()||(process.getuid&&entry.uid!==process.getuid()))throw Error('Refusing unowned/non-socket desktop endpoint');await unlink(session.pipe);}catch(e){if(e.code!=='ENOENT')throw e;}
+  }
+  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++){
+  if(!await processAlive(session.pid))return {running:false,stopped:true};
+  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{if(!(await lstat(executable)).isFile())throw Error('Desktop helper cache is not a regular file');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 desktopHelper(options={}){
+ const platform=desktopPlatform(options);
+ if(platform.helper==='windows')return {command:await buildHelper(options),args:[],mode:platform.id,fps:platform.fps};
+ if(platform.helper==='macos')return {command:'/usr/bin/osascript',args:['-l','JavaScript',fileURLToPath(new URL('../macos-overlay/overlay.jxa',import.meta.url))],mode:platform.id,fps:platform.fps};
+ // Use an existing system Python, including AlmaLinux8's3.6 platform interpreter.
+ // No Python package, compiled addon, native bundle, compiler, or package manager.
+ const candidates=[...(process.env.RETRIEVIEWER_PYTHON?[process.env.RETRIEVIEWER_PYTHON]:[]),'python3','/usr/libexec/platform-python'];
+ for(const command of candidates)try{
+  await exec(command,['-I','-c','import sys;sys.exit(0 if sys.version_info >= (3,6) else 1)'],{windowsHide:true,timeout:5000,maxBuffer:4096});
+  return {command,args:['-I',fileURLToPath(new URL('../linux-overlay/overlay.py',import.meta.url))],mode:platform.id,fps:platform.fps};
+ }catch{}
+ throw Error('Linux desktop needs system Python3.6+ (AlmaLinux8 platform-python is supported). No packages or system settings were installed.');
+}
+export async function startDesktop(options={}){
+ // Fail before creating any cache/session on unsupported desktops (e.g. Wayland).
+ desktopPlatform(options);
+ const status=await desktopStatus(options);if(status.running)return {...status,alreadyRunning:true};
+ if(status.stale)await stopDesktop(options);
+ const helper=await desktopHelper(options);
+ return new Promise((resolve,reject)=>{
+  const child=spawn(process.execPath,[fileURLToPath(new URL('./worker.mjs',import.meta.url)),'--helper-spec',JSON.stringify(helper)],{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();}},
+ };
+}

package/integrations/windows-overlay/worker.mjs

@@ -0,0 +1,66 @@
+// Private detached worker, started only by the explicit `desktop` command.
+import {spawn} from 'node:child_process';
+import {createServer} from 'node:net';
+import {createInterface} from 'node:readline';
+import {open,unlink,readFile,chmod} from 'node:fs/promises';
+import {randomBytes,randomUUID} from 'node:crypto';
+import {prepareRoot,noLink} from './desktop.mjs';
+import {createFramePump} from './protocol.mjs';
+import {controlAddress,parseHelperSpec} from '../desktop/platform.mjs';
+
+let helper,pump,timer,server,session,paths,owned=false,stopping=false,frames=0,paintedFrames=0,visible=false,selected=false,pickerVisible=false,pendingViewport=null,lastInteraction=null;
+let nativeError=null;
+let nativeStderr='';
+const sendParent=message=>{if(process.connected)process.send(message);};
+async function stop(){
+ if(stopping)return;stopping=true;clearInterval(timer);pump?.dispose();
+ if(helper&&!helper.killed){try{helper.stdin.end(JSON.stringify({type:'quit'})+'\n');}catch{}}
+ if(server)server.close();
+ if(owned)try{const current=JSON.parse(await readFile(paths.session,'utf8'));if(current.token===session.token)await unlink(paths.session);}catch{}
+ // A wedged painter is our own child only, never the selected terminal.
+ const watchdog=setTimeout(()=>{helper?.kill();process.exit(0);},2500);watchdog.unref();
+ if(!helper||helper.exitCode!==null)process.exitCode=0;
+}
+process.on('SIGTERM',stop);process.on('SIGINT',stop);process.on('message',m=>{if(m?.command==='abort')stop();});
+try{
+ const spec=parseHelperSpec(process.argv.slice(2));
+ paths=await prepareRoot();await noLink(paths.session);
+ session={owner:'bitefoundry-retrieviewer-overlay-v1',pid:process.pid,pipe:controlAddress({uuid:randomUUID()}),token:randomBytes(32).toString('hex')};
+ const record=await open(paths.session,'wx',0o600);owned=true;try{await record.writeFile(JSON.stringify(session)+'\n');}finally{await record.close();}
+ server=createServer(socket=>{
+  socket.setTimeout(1500,()=>socket.destroy());let body='';
+  socket.on('error',()=>{});socket.on('data',bytes=>{
+   body+=bytes.toString('utf8');if(body.length>2048)return socket.destroy();if(!body.includes('\n'))return;
+   let command;try{command=JSON.parse(body.split('\n')[0]);}catch{return socket.destroy();}
+   if(command.token!==session.token||!['status','stop'].includes(command.command))return socket.destroy();
+   socket.end(JSON.stringify(command.command==='stop'?{stopped:true}:{running:true,reachable:true,selected,visible,pickerVisible,frames,paintedFrames,lastInteraction,pid:process.pid,painterPid:helper?.pid,rssBytes:process.memoryUsage().rss})+'\n');
+   if(command.command==='stop')stop();
+  });
+ });
+ await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(session.pipe,resolve);});
+ if(process.platform!=='win32')await chmod(session.pipe,0o600);
+ // GUI-subsystem exe: no console to hide. SW_HIDE here also hides its first UI.
+ helper=spawn(spec.command,spec.args,{windowsHide:false,stdio:['pipe','pipe','pipe']});
+ helper.stdin.on('error',()=>stop());helper.stderr.setEncoding('utf8');helper.stderr.on('data',s=>{nativeStderr=(nativeStderr+s).slice(-4096);});helper.once('error',error=>{sendParent({error:error.message});stop();});
+ helper.once('exit',code=>{if(!stopping)sendParent({error:nativeError??('Desktop painter exited ('+code+')'+(nativeStderr?' — '+nativeStderr.trim():''))});stop();});
+ const write=message=>{if(!stopping&&!helper.stdin.destroyed)helper.stdin.write(JSON.stringify(message)+'\n');};
+ const reader=createInterface({input:helper.stdout});
+ reader.on('line',line=>{
+  if(line.length>100000)return stop();let m;try{m=JSON.parse(line);}catch{return stop();}
+  try{
+   if(m.type==='ready'){pickerVisible=m.pickerVisible===true;sendParent({running:true,windowPicker:pickerVisible,mode:spec.mode,pid:process.pid});}
+   else if(m.type==='error'){nativeError=String(m.message??'Desktop painter failed');sendParent({error:nativeError});stop();}
+   else if(m.type==='picker')pickerVisible=m.visible===true;
+   else if(m.type==='viewport'){pendingViewport=m;visible=m.visible;selected=m.selected===true;pump?.viewport(m);}
+   else if(m.type==='ack'){frames++;if(m.painted)paintedFrames++;pump?.ack();}
+   else if(m.type==='pause')pump?.pause(m.paused);
+   else if(m.type==='interact'){const accepted=pump?.interact(m.kind)??false;lastInteraction={kind:m.kind,accepted};write({type:'interaction',kind:m.kind,accepted});}
+   else if(m.type==='quit')stop();
+  }catch(error){write({type:'error',message:error.message});stop();}
+ });
+ const {createPet}=await import('../../retrieviewer.mjs');const pet=await createPet();
+ if(stopping)pet.dispose();else{
+  pump=createFramePump({pet,send:write});if(pendingViewport)pump.viewport(pendingViewport);
+  write({type:'loaded'});timer=setInterval(()=>{try{pump.tick();}catch(error){write({type:'error',message:error.message});stop();}},1000/spec.fps);
+ }
+}catch(error){sendParent({error:error.message});await stop();}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@bitefoundry/retrieviewer",
-  "version": "0.0.1",
-  "description": "Embeddable autonomous Braille retriever for TUI panes; Q5 art included, host-owned input and screen.",
+  "version": "0.0.3",
+  "description": "A fluffy Braille desktop pet for Windows and Linux X11, with experimental macOS support and an embeddable TUI engine.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/BiteFoundry",
-  "keywords": ["tui", "braille", "pet", "retriever", "opencode"],
+  "keywords": ["tui", "braille", "pet", "retriever", "opencode", "desktop-pet", "windows", "linux", "macos", "overlay"],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
@@ -52,6 +52,17 @@
     "retrieviewer-config.mjs",
     "integrations/opencode/tui.tsx",
     "integrations/opencode/runtime.mjs",
+    "integrations/windows-overlay/protocol.mjs",
+    "integrations/windows-overlay/desktop.mjs",
+    "integrations/windows-overlay/worker.mjs",
+    "integrations/windows-overlay/Overlay.cs",
+    "integrations/desktop/platform.mjs",
+    "integrations/linux-overlay/overlay.py",
+    "integrations/linux-overlay/README.md",
+    "integrations/macos-overlay/overlay.jxa",
+    "integrations/macos-overlay/README.md",
+    "DESKTOP-PLATFORMS.md",
+    "WINDOWS-COMPANION.md",
     "INSTALLING.md",
     "PLUGIN.md",
     "EMBEDDING.md",
@@ -114,6 +125,7 @@
     "terminal": "node terminal.mjs",
     "pet": "node puppy-terminal.mjs",
     "pet:companion": "node examples/live.mjs",
+    "pet:desktop": "node retrieviewer-cli.mjs desktop",
     "test": "node --test \"*.test.mjs\"",
     "test:locomotion": "node check-locomotion.mjs",
     "test:package": "node check-pet-package.mjs",

package/retrieviewer-cli.mjs

@@ -13,11 +13,20 @@ Usage:
   retrieviewer doctor [--agent ID] [--json]
   retrieviewer agents [--json]
   retrieviewer preview [--original]
+  retrieviewer desktop
+  retrieviewer desktop-status [--json]
+  retrieviewer desktop-stop
+  retrieviewer desktop-clean --yes
+  retrieviewer desktop-remove --yes
 
 Enable opens a first-run selection/confirmation wizard on a real terminal.
 Non-interactive changes require --agent and --yes. Unsupported native renderers
 are refused: MCP connectivity alone is never treated as in-screen rendering.
 No command changes credentials, shell profiles or agent executables.
+Desktop is a separate native overlay, NOT a Codex plugin. Choose a window once;
+use Codex normally. Exit from its tray icon or desktop-stop. No auto-start is added.
+Windows is verified; macOS and Linux X11 adapters are experimental. Native Wayland
+app tracking is not supported. Linux targets AlmaLinux8/GLIBC2.28, system Python3.6+.
 `;
 export function parseArguments(args){
  const [command='help',...rest]=args,options={};
@@ -30,14 +39,20 @@ export function parseArguments(args){
   else throw Error('Unknown argument: '+token);
  }
  if(options.agent&&!AGENTS.some(a=>a.id===options.agent))throw Error('Unknown agent: '+options.agent);
- if(!['help','--help','-h','enable','disable','disconnect','status','doctor','agents','preview'].includes(command))throw Error('Unknown command: '+command);
- const allowed={enable:['agent','yes','json','dry-run'],disconnect:['agent','yes','json','dry-run'],disable:['agent','json'],status:['agent','json'],doctor:['agent','json'],agents:['json'],preview:['original']};
+ if(!['help','--help','-h','enable','disable','disconnect','status','doctor','agents','preview','desktop','desktop-status','desktop-stop','desktop-clean','desktop-remove'].includes(command))throw Error('Unknown command: '+command);
+ const allowed={enable:['agent','yes','json','dry-run'],disconnect:['agent','yes','json','dry-run'],disable:['agent','json'],status:['agent','json'],doctor:['agent','json'],agents:['json'],preview:['original'],'desktop-status':['json'],'desktop-clean':['yes'],'desktop-remove':['yes']};
  for(const key of Object.keys(options))if(!(allowed[command]??[]).includes(key))throw Error(`--${key} is not supported by ${command}`);
  return {command,options};
 }
-export async function runCli(args,{input=process.stdin,output=process.stdout,error=process.stderr,installer=createInstaller()}={}){
+export async function runCli(args,{input=process.stdin,output=process.stdout,error=process.stderr,installer=createInstaller(),desktop}={}){
  const {command,options}=parseArguments(args),emit=value=>output.write(JSON.stringify(value,null,2)+'\n');
  if(['help','--help','-h'].includes(command)){output.write(HELP);return 0;}
+ if(command.startsWith('desktop')){
+  if(['desktop-clean','desktop-remove'].includes(command)&&!options.yes)throw Error('Use '+command+' --yes to remove only the companion cache.');
+  const api=desktop??await import('./integrations/windows-overlay/desktop.mjs');
+  const action={'desktop':'startDesktop','desktop-status':'desktopStatus','desktop-stop':'stopDesktop','desktop-clean':'cleanDesktop','desktop-remove':'removeDesktop'}[command];
+  emit(await api[action]());return 0;
+ }
  if(command==='preview'){await import('./examples/live.mjs');return 0;}
  if(['status','doctor','agents'].includes(command)){
   const result=command==='agents'?await installer.list():await installer[command](options.agent);
@@ -75,7 +90,12 @@ export async function runCli(args,{input=process.stdin,output=process.stdout,err
 }
 
 // CLI is deliberately a separate module from the side-effect-free library.
-import {pathToFileURL} from 'node:url';
-if(process.argv[1]&&import.meta.url===pathToFileURL(process.argv[1]).href){
+import {fileURLToPath} from 'node:url';
+import {realpathSync} from 'node:fs';
+// npm global bins are symlinks on Unix. import.meta resolves the real module,
+// whereas argv[1] keeps the bin link; comparing those raw URLs silently did nothing.
+let main=false;
+try{main=!!process.argv[1]&&realpathSync(process.argv[1])===realpathSync(fileURLToPath(import.meta.url));}catch{}
+if(main){
  try{process.exitCode=await runCli(process.argv.slice(2));}catch(e){process.stderr.write('Retrieviewer: '+e.message+'\n');process.exitCode=1;}
 }