ispyx 0.0.0-stage → 1.0.0

package/src/platform/win32/dialog.js

@@ -0,0 +1,41 @@
+// Native password window for the auth gate (Windows: PowerShell + WinForms).
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const DIALOG = path.join(HERE, 'auth-dialog.ps1');
+
+/**
+ * Real password window. Resolves to the dialog's JSON, or
+ * { cancel: true, reason } where reason says why: 'timed out', 'closed by the user', or 'dialog failed: ...'.
+ */
+export function showDialog(opts, ms) {
+  return new Promise((resolve) => {
+    const args = ['-NoProfile', '-STA', '-ExecutionPolicy', 'Bypass', '-File', DIALOG,
+      '-Mode', opts.mode,
+      '-Message', ` ${opts.message || ''}`, // leading space: a bare "-" would be read as a parameter name
+      '-Seconds', String(Math.max(1, Math.ceil(ms / 1000))),
+      '-Value', String(opts.value), '-Unit', opts.unit];
+    const p = spawn('powershell.exe', args, { windowsHide: false, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '';
+    let err = '';
+    let killed = false;
+    p.stdout.on('data', (d) => { out += d; });
+    p.stderr.on('data', (d) => { err += d; });
+    const kill = setTimeout(() => { killed = true; try { p.kill(); } catch { /* gone */ } }, ms + 1500);
+    const finish = (code) => {
+      clearTimeout(kill);
+      try {
+        const r = JSON.parse(out.trim().split('\n').pop());
+        if (r.cancel) r.reason = r.reason === 'timeout' ? 'timed out' : 'closed by the user';
+        resolve(r);
+      } catch {
+        const why = killed ? 'timed out' : `dialog failed (exit ${code}): ${(err.trim().split('\n')[0] || 'no output').slice(0, 120)}`;
+        resolve({ cancel: true, reason: why });
+      }
+    };
+    p.on('close', finish);
+    p.on('error', (e) => { clearTimeout(kill); resolve({ cancel: true, reason: `dialog failed to start: ${e.message}` }); });
+  });
+}

package/src/platform/win32/hotkey.js

@@ -0,0 +1,77 @@
+// Emergency stop hotkey: Alt+Esc pressed by the person (not by this server).
+// Primary path is a low-level keyboard hook, which can tell real keystrokes from injected ones and swallows
+// the Esc, so Windows does not also cycle windows. A polling fallback in the guard covers moments when the
+// hook is not serviced (long synchronous work).
+import koffi from 'koffi';
+import * as w from './win32.js';
+import { ensurePump } from './pump.js';
+
+const user32 = koffi.load('user32.dll');
+const HookProc = koffi.proto('intptr_t StopHookProc(int code, uintptr_t wp, intptr_t lp)');
+const SetWindowsHookExW = user32.func('intptr_t SetWindowsHookExW(int id, StopHookProc *proc, intptr_t mod, uint32 tid)');
+const UnhookWindowsHookEx = user32.func('bool UnhookWindowsHookEx(intptr_t h)');
+const CallNextHookEx = user32.func('intptr_t CallNextHookEx(intptr_t h, int code, uintptr_t wp, intptr_t lp)');
+const GetAsyncKeyState = user32.func('int16_t GetAsyncKeyState(int vk)');
+
+const VK_ESCAPE = 0x1b;
+const LLKHF_INJECTED = 0x10;
+const LLKHF_ALTDOWN = 0x20;
+
+/** True while every key of the chord is down right now (used as a fallback; injected keys also count). */
+export const chordDown = (vks) => vks.every((vk) => (GetAsyncKeyState(vk) & 0x8000) !== 0);
+
+export const HOOK_LINGER_MS = 30000;
+
+/**
+ * Alt+Esc hook that exists only while the server is working: touch() installs it (if absent) and pushes the
+ * removal back HOOK_LINGER_MS, so idle time and the user's own typing never go through this process.
+ */
+export function installStopHotkey(onStop, lingerMs = HOOK_LINGER_MS) {
+  let hook = 0;
+  let swallowUp = false;
+  let timer = null;
+  const proc = koffi.register((code, wp, lp) => {
+    try {
+      if (code === 0) {
+        const buf = Buffer.alloc(24);
+        w._raw.CopyFromMem(buf, lp, 24);
+        const vk = buf.readUInt32LE(0);
+        const flags = buf.readUInt32LE(8);
+        if (vk === VK_ESCAPE && !(flags & LLKHF_INJECTED)) {
+          const down = wp === 0x100 || wp === 0x104;
+          if (down && flags & LLKHF_ALTDOWN) {
+            if (!swallowUp) { // key auto-repeat while held counts as one press
+              swallowUp = true;
+              setImmediate(() => onStop('Alt+Esc'));
+            }
+            return 1; // swallowed: no window cycling
+          }
+          if (!down && swallowUp) {
+            swallowUp = false;
+            return 1;
+          }
+        }
+      }
+    } catch { /* never let a hook error break the keyboard */ }
+    return CallNextHookEx(hook, code, wp, lp);
+  }, koffi.pointer(HookProc));
+  const remove = () => {
+    timer = null;
+    if (hook) UnhookWindowsHookEx(hook);
+    hook = 0;
+  };
+  return {
+    touch() {
+      ensurePump(lingerMs + 2000); // the hook must be serviced quickly or the user's own typing lags
+      if (!hook) {
+        hook = SetWindowsHookExW(13, proc, 0, 0); // WH_KEYBOARD_LL
+        if (!hook) process.stderr.write('ispyx: stop hotkey hook not installed; using polling only\n');
+      }
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(remove, lingerMs);
+      timer.unref();
+    },
+    active: () => !!hook,
+    stop: remove,
+  };
+}

package/src/platform/win32/index.js

@@ -0,0 +1,31 @@
+// Windows platform layer: the API every platform exports (see ../CONTRACT.md).
+import path from 'node:path';
+
+export * from './win32.js';
+export { chordDown, installStopHotkey, HOOK_LINGER_MS } from './hotkey.js';
+export { Overlay } from './overlay.js';
+export { parseChord, parseSequence, insertsContent } from './keys.js';
+export { showDialog } from './dialog.js';
+export { ensurePump, pumpOnce } from './pump.js';
+
+export const name = 'win32';
+export const capabilities = { elevation: true };
+export const stopLabel = 'Alt+Esc';
+
+/** Where the password hash and other per-user state live. */
+export const dataDir = () => {
+  const roaming = process.env.APPDATA || path.join(process.env.USERPROFILE || '.', 'AppData', 'Roaming');
+  const fs = process.getBuiltinModule('node:fs');
+  const dir = path.join(roaming, 'ispyx');
+  const old = path.join(roaming, 'win-input-mcp');
+  try { // one-time migration from the old name: copy auth.json, leave the old folder alone
+    if (!fs.existsSync(dir) && fs.existsSync(path.join(old, 'auth.json'))) {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.copyFileSync(path.join(old, 'auth.json'), path.join(dir, 'auth.json'));
+    }
+  } catch { /* best effort: a fresh folder just asks for a new password */ }
+  return dir;
+};
+export { Layer, textMask } from './layer.js';
+export { Tray } from './tray.js';
+export { autostart } from './autostart.js';

package/src/platform/win32/keys.js

@@ -0,0 +1,31 @@
+// "ctrl+shift+t" style chords -> Windows virtual-key codes.
+const NAMED = {
+  win: 0x5b, windows: 0x5b, meta: 0x5b, cmd: 0x5b, super: 0x5b, lwin: 0x5b, rwin: 0x5c,
+  ctrl: 0x11, control: 0x11, shift: 0x10, alt: 0x12, menu: 0x12,
+  enter: 0x0d, return: 0x0d, esc: 0x1b, escape: 0x1b, tab: 0x09, space: 0x20,
+  backspace: 0x08, delete: 0x2e, del: 0x2e, insert: 0x2d, ins: 0x2d,
+  home: 0x24, end: 0x23, pageup: 0x21, pgup: 0x21, pagedown: 0x22, pgdn: 0x22,
+  left: 0x25, up: 0x26, right: 0x27, down: 0x28,
+  ',': 0xbc, '.': 0xbe, '-': 0xbd, '=': 0xbb, '/': 0xbf, ';': 0xba, "'": 0xde,
+  '[': 0xdb, ']': 0xdd, '\\': 0xdc, '`': 0xc0,
+};
+
+export function parseChord(chord) {
+  const parts = chord.trim().toLowerCase().split('+').map((s) => s.trim()).filter(Boolean);
+  if (!parts.length) throw new Error('Empty key chord.');
+  return parts.map((p) => {
+    if (NAMED[p] !== undefined) return NAMED[p];
+    if (/^f([1-9]|1\d|2[0-4])$/.test(p)) return 0x70 + Number(p.slice(1)) - 1;
+    if (/^[a-z0-9]$/.test(p)) return p.toUpperCase().charCodeAt(0);
+    throw new Error(`Unknown key "${p}". Use names like ctrl, shift, alt, enter, tab, esc, f5, a-z, 0-9.`);
+  });
+}
+
+/** "ctrl+a ctrl+c" -> two chords. */
+export const parseSequence = (s) => s.trim().split(/\s+/).filter(Boolean).map(parseChord);
+
+/** Chords that would insert clipboard/other content, which must not go into a password field. */
+export function insertsContent(vks) {
+  const has = (k) => vks.includes(k);
+  return (has(0x11) && has(0x56)) || (has(0x10) && has(0x2d));
+}

package/src/platform/win32/layer.js

@@ -0,0 +1,120 @@
+// Windows effect window: a layered, click-through window backed by a DIB section, plus GDI text masks.
+// Pixels are drawn in software (src/effects) into `layer.px`; nothing here depends on GDI+.
+import koffi from 'koffi';
+
+const user32 = koffi.load('user32.dll');
+const gdi32 = koffi.load('gdi32.dll');
+const kernel32 = koffi.load('kernel32.dll');
+
+const POINT = koffi.struct('SC_POINT', { x: 'int32', y: 'int32' });
+const SIZE = koffi.struct('SC_SIZE', { cx: 'int32', cy: 'int32' });
+const BLEND = koffi.struct('SC_BLEND', { op: 'uint8', flags: 'uint8', alpha: 'uint8', format: 'uint8' });
+const BITMAPINFO = koffi.struct('SC_BITMAPINFO', {
+  biSize: 'uint32', biWidth: 'int32', biHeight: 'int32', biPlanes: 'uint16', biBitCount: 'uint16', biCompression: 'uint32',
+  biSizeImage: 'uint32', biXPels: 'int32', biYPels: 'int32', biClrUsed: 'uint32', biClrImportant: 'uint32', bmiColors: 'uint32',
+});
+const WndProc = koffi.proto('intptr_t ScWndProc(intptr_t h, uint32 msg, uintptr_t wp, intptr_t lp)');
+const WNDCLASSEXW = koffi.struct('SC_WNDCLASSEXW', {
+  cbSize: 'uint32', style: 'uint32', lpfnWndProc: koffi.pointer(WndProc), cbClsExtra: 'int32', cbWndExtra: 'int32',
+  hInstance: 'intptr_t', hIcon: 'intptr_t', hCursor: 'intptr_t', hbrBackground: 'intptr_t',
+  lpszMenuName: 'str16', lpszClassName: 'str16', hIconSm: 'intptr_t',
+});
+
+const f = {
+  RegisterClassExW: user32.func('uint16 RegisterClassExW(SC_WNDCLASSEXW *c)'),
+  CreateWindowExW: user32.func('intptr_t CreateWindowExW(uint32 ex, str16 cls, str16 title, uint32 style, int x, int y, int w, int h, intptr_t parent, intptr_t menu, intptr_t inst, intptr_t param)'),
+  DefWindowProcW: user32.func('intptr_t DefWindowProcW(intptr_t h, uint32 msg, uintptr_t wp, intptr_t lp)'),
+  DestroyWindow: user32.func('bool DestroyWindow(intptr_t h)'),
+  ShowWindow: user32.func('bool ShowWindow(intptr_t h, int cmd)'),
+  UpdateLayeredWindow: user32.func('bool UpdateLayeredWindow(intptr_t h, intptr_t dst, SC_POINT *pos, SC_SIZE *size, intptr_t src, SC_POINT *from, uint32 key, SC_BLEND *blend, uint32 flags)'),
+  GetDC: user32.func('intptr_t GetDC(intptr_t h)'),
+  ReleaseDC: user32.func('int ReleaseDC(intptr_t h, intptr_t dc)'),
+  CreateCompatibleDC: gdi32.func('intptr_t CreateCompatibleDC(intptr_t dc)'),
+  DeleteDC: gdi32.func('bool DeleteDC(intptr_t dc)'),
+  CreateDIBSection: gdi32.func('intptr_t CreateDIBSection(intptr_t dc, SC_BITMAPINFO *bi, uint32 usage, _Out_ void **bits, intptr_t section, uint32 offset)'),
+  SelectObject: gdi32.func('intptr_t SelectObject(intptr_t dc, intptr_t o)'),
+  DeleteObject: gdi32.func('bool DeleteObject(intptr_t o)'),
+  GetModuleHandleW: kernel32.func('intptr_t GetModuleHandleW(str16 n)'),
+  CreateFontW: gdi32.func('intptr_t CreateFontW(int h, int w, int esc, int ori, int weight, uint32 it, uint32 ul, uint32 so, uint32 cs, uint32 op, uint32 clip, uint32 q, uint32 pf, str16 face)'),
+  TextOutW: gdi32.func('bool TextOutW(intptr_t dc, int x, int y, str16 text, int n)'),
+  GetTextExtentPoint32W: gdi32.func('bool GetTextExtentPoint32W(intptr_t dc, str16 text, int n, _Out_ SC_SIZE *size)'),
+  SetBkMode: gdi32.func('int SetBkMode(intptr_t dc, int m)'),
+  SetTextColor: gdi32.func('uint32 SetTextColor(intptr_t dc, uint32 c)'),
+};
+
+const CLASS = 'WinInputMcpScan';
+let proc = null;
+function registerClass() {
+  if (proc) return;
+  proc = koffi.register((h, msg, wp, lp) => (msg === 0x84 ? -1 : f.DefWindowProcW(h, msg, wp, lp)), koffi.pointer(WndProc));
+  f.RegisterClassExW({
+    cbSize: koffi.sizeof(WNDCLASSEXW), style: 0, lpfnWndProc: proc, cbClsExtra: 0, cbWndExtra: 0, hInstance: f.GetModuleHandleW(null),
+    hIcon: 0, hCursor: 0, hbrBackground: 0, lpszMenuName: null, lpszClassName: CLASS, hIconSm: 0,
+  });
+}
+
+/** One layered window with a premultiplied-BGRA pixel buffer. */
+export class Layer {
+  constructor(width, height) {
+    registerClass();
+    this.width = width;
+    this.height = height;
+    // TOPMOST | TOOLWINDOW | LAYERED | TRANSPARENT (click-through) | NOACTIVATE ; WS_POPUP
+    this.hwnd = f.CreateWindowExW(0x08 | 0x80 | 0x80000 | 0x20 | 0x08000000, CLASS, '', 0x80000000, 0, 0, width, height, 0, 0, f.GetModuleHandleW(null), 0);
+    if (!this.hwnd) throw new Error('CreateWindowEx failed');
+    const screen = f.GetDC(0);
+    this.dc = f.CreateCompatibleDC(screen);
+    const out = [null];
+    this.bmp = f.CreateDIBSection(screen, { biSize: 40, biWidth: width, biHeight: -height, biPlanes: 1, biBitCount: 32, biCompression: 0, biSizeImage: 0, biXPels: 0, biYPels: 0, biClrUsed: 0, biClrImportant: 0, bmiColors: 0 }, 0, out, 0, 0);
+    f.ReleaseDC(0, screen);
+    if (!this.bmp || !out[0]) throw new Error('CreateDIBSection failed');
+    this.old = f.SelectObject(this.dc, this.bmp);
+    this.px = new Uint8Array(koffi.view(out[0], width * height * 4));
+    this.shown = false;
+  }
+
+  /** Shows the `width` x `height` part of the buffer starting at row `srcY` at (x, y) with constant opacity `alpha` (0-255). */
+  present(x, y, alpha, height = this.height, width = this.width, srcY = 0) {
+    f.UpdateLayeredWindow(this.hwnd, 0, { x: Math.round(x), y: Math.round(y) }, { cx: Math.max(1, Math.min(this.width, Math.round(width))), cy: Math.max(1, Math.min(this.height, Math.round(height))) }, this.dc, { x: 0, y: Math.max(0, Math.round(srcY)) }, 0,
+      { op: 0, flags: 0, alpha: Math.max(0, Math.min(255, Math.round(alpha))), format: 1 }, 2); // ULW_ALPHA, AC_SRC_ALPHA
+    if (!this.shown) {
+      f.ShowWindow(this.hwnd, 4); // SW_SHOWNOACTIVATE
+      this.shown = true;
+    }
+  }
+
+  destroy() {
+    try {
+      f.ShowWindow(this.hwnd, 0);
+      f.SelectObject(this.dc, this.old);
+      f.DeleteObject(this.bmp);
+      f.DeleteDC(this.dc);
+      f.DestroyWindow(this.hwnd);
+    } catch { /* already gone */ }
+  }
+}
+
+/** Anti-aliased text as a coverage mask (0-255 per pixel), drawn by GDI white on black and read back. */
+export function textMask(text, heightPx = 22, weight = 600) {
+  const screen = f.GetDC(0);
+  const dc = f.CreateCompatibleDC(screen);
+  const font = f.CreateFontW(-heightPx, 0, 0, 0, weight, 0, 0, 0, 1, 0, 0, 4, 0, 'Segoe UI'); // ANTIALIASED_QUALITY
+  const oldFont = f.SelectObject(dc, font);
+  const size = {};
+  f.GetTextExtentPoint32W(dc, text, text.length, size);
+  const width = Math.max(1, size.cx + 2), height = Math.max(1, size.cy + 2);
+  const out = [null];
+  const bmp = f.CreateDIBSection(screen, { biSize: 40, biWidth: width, biHeight: -height, biPlanes: 1, biBitCount: 32, biCompression: 0, biSizeImage: 0, biXPels: 0, biYPels: 0, biClrUsed: 0, biClrImportant: 0, bmiColors: 0 }, 0, out, 0, 0);
+  const old = f.SelectObject(dc, bmp);
+  const px = new Uint8Array(koffi.view(out[0], width * height * 4));
+  px.fill(0);
+  f.SetBkMode(dc, 1);
+  f.SetTextColor(dc, 0xffffff);
+  f.TextOutW(dc, 1, 1, text, text.length);
+  const mask = new Uint8Array(width * height);
+  for (let i = 0; i < mask.length; i++) mask[i] = Math.max(px[i * 4], px[i * 4 + 1], px[i * 4 + 2]);
+  f.SelectObject(dc, old); f.DeleteObject(bmp);
+  f.SelectObject(dc, oldFont); f.DeleteObject(font);
+  f.DeleteDC(dc); f.ReleaseDC(0, screen);
+  return { width, height, mask };
+}

package/src/platform/win32/overlay.js

@@ -0,0 +1,265 @@
+// A small always-on-top pill that shows while the server works, drawn like the macOS one: dark body with a tint of the
+// accent colour (green working, amber cancelled, red stopped), accent outline and dot, white text. It is click-through
+// (mouse input goes to whatever is underneath), never takes focus, and has no title so list_windows skips it.
+// Rendered into a per-pixel-alpha bitmap so the rounded edge is smooth.
+import koffi from 'koffi';
+import * as w from './win32.js';
+import { ensurePump, pumpOnce } from './pump.js';
+
+const user32 = koffi.load('user32.dll');
+const gdi32 = koffi.load('gdi32.dll');
+const kernel32 = koffi.load('kernel32.dll');
+
+const WndProc = koffi.proto('intptr_t OvWndProc(intptr_t h, uint32 msg, uintptr_t wp, intptr_t lp)');
+const WNDCLASSEXW = koffi.struct('OV_WNDCLASSEXW', {
+  cbSize: 'uint32', style: 'uint32', lpfnWndProc: koffi.pointer(WndProc), cbClsExtra: 'int32', cbWndExtra: 'int32',
+  hInstance: 'intptr_t', hIcon: 'intptr_t', hCursor: 'intptr_t', hbrBackground: 'intptr_t',
+  lpszMenuName: 'str16', lpszClassName: 'str16', hIconSm: 'intptr_t',
+});
+const POINT = koffi.struct('OV_POINT', { x: 'int32', y: 'int32' });
+const SIZE = koffi.struct('OV_SIZE', { cx: 'int32', cy: 'int32' });
+const RECT = koffi.struct('OV_RECT', { left: 'int32', top: 'int32', right: 'int32', bottom: 'int32' });
+const BLEND = koffi.struct('OV_BLEND', { op: 'uint8', flags: 'uint8', alpha: 'uint8', format: 'uint8' });
+const BITMAPINFO = koffi.struct('OV_BITMAPINFO', {
+  size: 'uint32', width: 'int32', height: 'int32', planes: 'uint16', bitCount: 'uint16', compression: 'uint32',
+  sizeImage: 'uint32', xPels: 'int32', yPels: 'int32', clrUsed: 'uint32', clrImportant: 'uint32',
+});
+
+const f = {
+  RegisterClassExW: user32.func('uint16 RegisterClassExW(OV_WNDCLASSEXW *c)'),
+  CreateWindowExW: user32.func('intptr_t CreateWindowExW(uint32 ex, str16 cls, str16 title, uint32 style, int x, int y, int w, int h, intptr_t parent, intptr_t menu, intptr_t inst, intptr_t param)'),
+  DefWindowProcW: user32.func('intptr_t DefWindowProcW(intptr_t h, uint32 msg, uintptr_t wp, intptr_t lp)'),
+  ShowWindow: user32.func('bool ShowWindow(intptr_t h, int cmd)'),
+  SetWindowPos: user32.func('bool SetWindowPos(intptr_t h, intptr_t after, int x, int y, int cx, int cy, uint32 flags)'),
+  GetDC: user32.func('intptr_t GetDC(intptr_t h)'),
+  ReleaseDC: user32.func('int ReleaseDC(intptr_t h, intptr_t dc)'),
+  DrawTextW: user32.func('int DrawTextW(intptr_t dc, str16 text, int n, OV_RECT *r, uint32 flags)'),
+  UpdateLayeredWindow: user32.func('bool UpdateLayeredWindow(intptr_t h, intptr_t dst, OV_POINT *pos, OV_SIZE *size, intptr_t src, OV_POINT *srcPos, uint32 key, OV_BLEND *blend, uint32 flags)'),
+  CreateCompatibleDC: gdi32.func('intptr_t CreateCompatibleDC(intptr_t dc)'),
+  DeleteDC: gdi32.func('bool DeleteDC(intptr_t dc)'),
+  CreateDIBSection: gdi32.func('intptr_t CreateDIBSection(intptr_t dc, OV_BITMAPINFO *bi, uint32 usage, _Out_ void **bits, intptr_t section, uint32 offset)'),
+  CreateFontW: gdi32.func('intptr_t CreateFontW(int h, int w, int esc, int ori, int weight, uint32 it, uint32 ul, uint32 so, uint32 cs, uint32 op, uint32 clip, uint32 q, uint32 pf, str16 face)'),
+  DeleteObject: gdi32.func('bool DeleteObject(intptr_t o)'),
+  SelectObject: gdi32.func('intptr_t SelectObject(intptr_t dc, intptr_t o)'),
+  SetBkMode: gdi32.func('int SetBkMode(intptr_t dc, int m)'),
+  SetTextColor: gdi32.func('uint32 SetTextColor(intptr_t dc, uint32 c)'),
+  GetTextExtentPoint32W: gdi32.func('bool GetTextExtentPoint32W(intptr_t dc, str16 text, int n, _Out_ OV_SIZE *size)'),
+  GetModuleHandleW: kernel32.func('intptr_t GetModuleHandleW(str16 n)'),
+};
+
+export const OVERLAY_CLASS = 'WinInputMcpOverlay';
+const HEIGHT = 40;
+const LEFT_PAD = 38;
+const RIGHT_PAD = 22;
+const MIN_WIDTH = 300;
+const SS = 3; // text is drawn SS times larger and averaged down: smooth grayscale edges like the macOS banner
+const BODY_ALPHA = 0.92;
+const BASE = [20, 23, 36]; // dark navy body (r, g, b)
+const ACCENTS = { working: [51, 204, 107], cancelled: [250, 184, 38], stopped: [237, 66, 66] };
+
+const clamp01 = (v) => (v < 0 ? 0 : v > 1 ? 1 : v);
+
+export class Overlay {
+  constructor({ enabled = true, hideAfterMs = 1500, stopLabel = 'Alt+Esc' } = {}) {
+    this.stopLabel = stopLabel;
+    this.enabled = enabled;
+    this.hideAfterMs = hideAfterMs;
+    this.active = 0;
+    this.hwnd = 0;
+    this.timer = null;
+    this.bitmap = 0;
+  }
+
+  _create() {
+    if (this.hwnd || !this.enabled) return;
+    try {
+      this.font = f.CreateFontW(-18 * SS, 0, 0, 0, 700, 0, 0, 0, 1, 0, 0, 4, 0, 'Segoe UI');
+      this.proc = koffi.register((h, msg, wp, lp) => (msg === 0x84 ? -1 : f.DefWindowProcW(h, msg, wp, lp)), koffi.pointer(WndProc)); // WM_NCHITTEST -> HTTRANSPARENT
+      const inst = f.GetModuleHandleW(null);
+      f.RegisterClassExW({
+        cbSize: koffi.sizeof(WNDCLASSEXW), style: 0, lpfnWndProc: this.proc, cbClsExtra: 0, cbWndExtra: 0, hInstance: inst,
+        hIcon: 0, hCursor: 0, hbrBackground: 0, lpszMenuName: null, lpszClassName: OVERLAY_CLASS, hIconSm: 0,
+      });
+      // WS_EX_TOPMOST | TOOLWINDOW | LAYERED | TRANSPARENT (click-through) | NOACTIVATE ; WS_POPUP
+      this.hwnd = f.CreateWindowExW(0x08 | 0x80 | 0x80000 | 0x20 | 0x08000000, OVERLAY_CLASS, '', 0x80000000,
+        0, 0, MIN_WIDTH, HEIGHT, 0, 0, inst, 0);
+      if (!this.hwnd) throw new Error('CreateWindowEx failed');
+      // Windows only delivers hit-test messages while someone pumps; do it here, on this thread.
+      ensurePump();
+    } catch (e) {
+      process.stderr.write(`ispyx: overlay disabled (${e.message})\n`);
+      this.enabled = false;
+      this.hwnd = 0;
+    }
+  }
+
+  /** Draw the pill into a bitmap and hand it to the layered window. */
+  _paint(text, kind) {
+    const screenDc = f.GetDC(0);
+    const dc = f.CreateCompatibleDC(screenDc);
+    const oldFont = f.SelectObject(dc, this.font);
+    const ext = {};
+    f.GetTextExtentPoint32W(dc, text, text.length, ext);
+    ext.cx = Math.ceil(ext.cx / SS);
+    const mon = w.listMonitors().find((m) => m.primary) ?? { left: 0, top: 0, width: 1280 };
+    const W = Math.round(Math.min(Math.max(MIN_WIDTH, ext.cx + LEFT_PAD + RIGHT_PAD), Math.min(1400, mon.width - 40)));
+    const H = HEIGHT;
+
+    const bits = [null];
+    const bmp = f.CreateDIBSection(dc, { size: 40, width: W, height: -H, planes: 1, bitCount: 32, compression: 0, sizeImage: 0, xPels: 0, yPels: 0, clrUsed: 0, clrImportant: 0 }, 0, bits, 0, 0);
+    if (!bmp || !bits[0]) {
+      f.SelectObject(dc, oldFont); f.DeleteDC(dc); f.ReleaseDC(0, screenDc);
+      throw new Error('CreateDIBSection failed');
+    }
+    const old = f.SelectObject(dc, bmp);
+    const px = new Uint8Array(koffi.view(bits[0], W * H * 4));
+    const mask = new Float32Array(W * H);
+    const accent = ACCENTS[kind] ?? ACCENTS.working;
+
+    // Same geometry as the macOS banner: a capsule, outline 1.5 wide centred 1.5 in from the edge, dot at x=18..28.
+    const cy = H / 2;
+    const outer = H / 2 - 0.75;
+    const inner = H / 2 - 2.25;
+    const x0 = outer + 0.75;
+    const x1 = W - outer - 0.75;
+    const body = BASE.map((c, i) => c * 0.84 + accent[i] * 0.16);
+    const line = BASE.map((c, i) => c * 0.15 + accent[i] * 0.85);
+    for (let y = 0; y < H; y++) {
+      for (let x = 0; x < W; x++) {
+        const qx = x + 0.5;
+        const qy = y + 0.5;
+        const d = Math.hypot(qx - Math.min(Math.max(qx, x0), x1), qy - cy);
+        const fill = clamp01(outer - d + 0.5);
+        const core = clamp01(inner - d + 0.5); // 1 inside the outline, 0 on it
+        const dot = clamp01(5 - Math.hypot(qx - 23, qy - cy) + 0.5);
+        const i = (y * W + x) * 4;
+        mask[y * W + x] = fill * BODY_ALPHA;
+        for (let k = 0; k < 3; k++) {
+          const base = line[k] * (1 - core) + body[k] * core;
+          px[i + (2 - k)] = Math.round(base * (1 - dot) + accent[k] * dot); // BGRA
+        }
+        px[i + 3] = 255;
+      }
+    }
+
+    // Text: white on black at SS x size, then each SS x SS block becomes one coverage value.
+    const tw = (W - LEFT_PAD - RIGHT_PAD) * SS;
+    const th = H * SS;
+    const tb = [null];
+    const tbmp = f.CreateDIBSection(dc, { size: 40, width: tw, height: -th, planes: 1, bitCount: 32, compression: 0, sizeImage: 0, xPels: 0, yPels: 0, clrUsed: 0, clrImportant: 0 }, 0, tb, 0, 0);
+    if (tbmp && tb[0]) {
+      const tdc = f.CreateCompatibleDC(screenDc);
+      const told = f.SelectObject(tdc, tbmp);
+      const tf = f.SelectObject(tdc, this.font);
+      const big = new Uint8Array(koffi.view(tb[0], tw * th * 4));
+      big.fill(0);
+      f.SetBkMode(tdc, 1);
+      f.SetTextColor(tdc, 0xffffff);
+      f.DrawTextW(tdc, text, -1, { left: 0, top: 0, right: tw, bottom: th }, 0x4 | 0x20 | 0x8000); // VCENTER | SINGLELINE | END_ELLIPSIS
+      for (let y = 0; y < H; y++) {
+        for (let x = 0; x < W - LEFT_PAD - RIGHT_PAD; x++) {
+          let sum = 0;
+          for (let dy = 0; dy < SS; dy++) for (let dx = 0; dx < SS; dx++) sum += big[(((y * SS + dy) * tw) + x * SS + dx) * 4 + 1];
+          const c = sum / (255 * SS * SS);
+          if (c <= 0) continue;
+          const i = (y * W + x + LEFT_PAD) * 4;
+          for (let k = 0; k < 3; k++) px[i + k] = Math.round(px[i + k] * (1 - c) + 255 * c);
+        }
+      }
+      f.SelectObject(tdc, tf); f.SelectObject(tdc, told); f.DeleteObject(tbmp); f.DeleteDC(tdc);
+    }
+
+    // Premultiply by the capsule coverage.
+    for (let p = 0; p < W * H; p++) {
+      const a = mask[p];
+      const i = p * 4;
+      px[i] = Math.round(px[i] * a);
+      px[i + 1] = Math.round(px[i + 1] * a);
+      px[i + 2] = Math.round(px[i + 2] * a);
+      px[i + 3] = Math.round(a * 255);
+    }
+
+    const x = mon.left + Math.round((mon.width - W) / 2);
+    const ok = f.UpdateLayeredWindow(this.hwnd, screenDc, { x, y: mon.top + 6 }, { cx: W, cy: H }, dc, { x: 0, y: 0 }, 0,
+      { op: 0, flags: 0, alpha: 255, format: 1 }, 2); // AC_SRC_OVER, AC_SRC_ALPHA ; ULW_ALPHA
+
+    f.SelectObject(dc, old);
+    f.SelectObject(dc, oldFont);
+    f.DeleteObject(bmp);
+    f.DeleteDC(dc);
+    f.ReleaseDC(0, screenDc);
+    if (!ok) throw new Error('UpdateLayeredWindow failed');
+  }
+
+  _show(text, kind = 'working') {
+    this._create();
+    if (!this.hwnd) return;
+    try {
+      this._paint(text, kind);
+    } catch (e) {
+      process.stderr.write(`ispyx: overlay disabled (${e.message})\n`);
+      this.enabled = false;
+      return;
+    }
+    f.SetWindowPos(this.hwnd, -1, 0, 0, 0, 0, 0x1 | 0x2 | 0x10); // HWND_TOPMOST, NOSIZE|NOMOVE|NOACTIVATE
+    f.ShowWindow(this.hwnd, 4); // SW_SHOWNOACTIVATE
+  }
+
+  _hide() {
+    if (this.hwnd) f.ShowWindow(this.hwnd, 0);
+  }
+
+  /** A tool started: show the banner. Call done() when it ends. */
+  begin(label) {
+    if (!this.enabled) return;
+    this.active++;
+    clearTimeout(this.timer);
+    this._show(`ispyx is working: ${label}   |   To stop press ${this.stopLabel}`, 'working');
+  }
+
+  done() {
+    if (!this.enabled) return;
+    this.active = Math.max(0, this.active - 1);
+    if (this.active === 0) {
+      clearTimeout(this.timer);
+      this.timer = setTimeout(() => this._hide(), this.hideAfterMs);
+      this.timer.unref();
+    }
+  }
+
+  /** The user stopped the server: turn the banner red and keep it for a few seconds. */
+  stop(reason) {
+    if (!this.enabled) return;
+    clearTimeout(this.timer);
+    this._show(`ispyx STOPPED (${reason})`, 'stopped');
+    this.timer = setTimeout(() => this._hide(), 5000);
+    this.timer.unref();
+  }
+
+  /** First stop press: the running tool was cancelled; a second press within the window shuts the server down. */
+  cancel(reason, windowMs) {
+    if (!this.enabled) return;
+    this.active = 0;
+    clearTimeout(this.timer);
+    this._show(`ispyx CANCELLED (${reason})   |   press again to shut down`, 'cancelled');
+    this.timer = setTimeout(() => this._hide(), windowMs);
+    this.timer.unref();
+  }
+
+  /** Hide the banner while the agent takes a screenshot, so it never covers what the agent needs to see. */
+  async hiddenDuring(fn) {
+    const visible = this.hwnd && this.enabled && w._raw.IsWindowVisible(this.hwnd);
+    if (visible) {
+      this._hide();
+      await w.sleep(60); // let the compositor drop it
+    }
+    try {
+      return await fn();
+    } finally {
+      if (visible) {
+        f.ShowWindow(this.hwnd, 4);
+        pumpOnce();
+      }
+    }
+  }
+}

package/src/platform/win32/pump.js

@@ -0,0 +1,37 @@
+// Windows only calls window procedures and low-level hooks while the owning thread pumps messages.
+// Node has no message loop of its own, so a timer does it, but only while something needs it: the keyboard hook
+// or an effect window. Anything that installs a hook must hold the pump for as long as the hook exists (a
+// low-level hook that is not serviced makes the user's own typing lag). When nothing holds it, polling stops.
+// The tray icon does not use this: it has its own thread (tray-worker.js).
+import koffi from 'koffi';
+
+const user32 = koffi.load('user32.dll');
+const MSG = koffi.struct('PUMP_MSG', {
+  hwnd: 'intptr_t', message: 'uint32', wParam: 'uintptr_t', lParam: 'intptr_t', time: 'uint32', ptx: 'int32', pty: 'int32', lPrivate: 'uint32',
+});
+const PeekMessageW = user32.func('bool PeekMessageW(_Out_ PUMP_MSG *m, intptr_t h, uint32 min, uint32 max, uint32 remove)');
+const DispatchMessageW = user32.func('intptr_t DispatchMessageW(PUMP_MSG *m)');
+
+const PUMP_MS = 10;
+const DEFAULT_HOLD_MS = 10000;
+
+let timer = null;
+let until = 0;
+
+export function pumpOnce() {
+  const m = {};
+  for (let i = 0; i < 50 && PeekMessageW(m, 0, 0, 0, 1); i++) DispatchMessageW(m);
+}
+
+function tick() {
+  pumpOnce();
+  if (Date.now() >= until) { timer = null; return; }
+  timer = setTimeout(tick, PUMP_MS);
+  timer.unref();
+}
+
+/** Run the pump for at least holdMs from now (default 10 s); every call extends it. */
+export function ensurePump(holdMs = DEFAULT_HOLD_MS) {
+  until = Math.max(until, Date.now() + holdMs);
+  if (!timer) tick();
+}