ispyx 0.0.0-stage → 1.0.1

package/src/platform/darwin/rpc-worker.js

@@ -0,0 +1,132 @@
+// Worker thread of rpc.js: owns the socket to Ispyx.app. See rpc.js for the shared-memory layout.
+import { parentPort, workerData } from 'node:worker_threads';
+import net from 'node:net';
+import { spawnSync } from 'node:child_process';
+
+const { sab, bigPort, endpoint, autostart, waitMs, notRunningMessage } = workerData;
+const i32 = new Int32Array(sab, 0, 8);
+const bytes = new Uint8Array(sab);
+const DATA = 64; // byte offset of the payload area
+const CAP = sab.byteLength - DATA;
+// header (Int32 index): 0 state (0 waiting, 1 ready), 1 id answered, 2 byte length, 3 status, 4 id the main thread waits for
+const OK = 0, ERR = 1, BIG = 2;
+
+let sock = null;
+let connecting = null;
+let launched = false;
+let rest = '';
+const pending = new Map(); // id -> 'sync' | 'async' | 'quiet'
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function parseEndpoint(ep) {
+  const m = /^(localhost|\d{1,3}(?:\.\d{1,3}){3}):(\d+)$/.exec(ep);
+  return m ? { host: m[1], port: Number(m[2]) } : { path: ep };
+}
+
+function connectOnce() {
+  return new Promise((resolve, reject) => {
+    const s = net.connect(parseEndpoint(endpoint));
+    const onErr = (e) => { s.destroy(); reject(e); };
+    s.once('error', onErr);
+    s.once('connect', () => {
+      s.off('error', onErr);
+      s.setNoDelay(true);
+      s.setEncoding('utf8');
+      s.on('data', onData);
+      s.on('error', () => {});
+      s.on('close', () => {
+        if (sock === s) { sock = null; failAll('Ispyx closed the connection (the app quit or restarted). Try the call again.'); }
+      });
+      resolve(s);
+    });
+  });
+}
+
+async function connect() {
+  const deadline = Date.now() + waitMs;
+  let last;
+  for (;;) {
+    try {
+      return await connectOnce();
+    } catch (e) {
+      last = e;
+    }
+    if (autostart && !launched) {
+      launched = true;
+      try { spawnSync('open', ['-g', '-a', 'Ispyx', '--args', '--background'], { stdio: 'ignore', timeout: 5000 }); } catch { /* reported below */ }
+    }
+    if (Date.now() >= deadline) break;
+    await sleep(150);
+  }
+  throw new Error(`${notRunningMessage} (${last?.code ?? last?.message ?? 'cannot connect'})`);
+}
+
+function ensureConnected() {
+  if (sock) return null;
+  connecting ??= connect().then((s) => { sock = s; }).finally(() => { connecting = null; });
+  return connecting;
+}
+
+function reply(id, mode, ok, line, errText) {
+  if (mode === 'quiet') return;
+  if (mode === 'async') {
+    parentPort.postMessage(ok ? { id, line } : { id, error: errText });
+    return;
+  }
+  if (Atomics.load(i32, 4) !== id) return; // the main thread gave up on this call
+  let status = ok ? OK : ERR;
+  const payload = Buffer.from(ok ? line : errText, 'utf8');
+  if (payload.length > CAP) {
+    bigPort.postMessage({ id, status, text: payload.toString('utf8') });
+    status = BIG;
+    i32[2] = 0;
+  } else {
+    // (the shared area is only touched for the call the main thread currently waits for, checked above)
+    bytes.set(payload, DATA);
+    i32[2] = payload.length;
+  }
+  i32[1] = id;
+  i32[3] = status;
+  Atomics.store(i32, 0, 1);
+  Atomics.notify(i32, 0);
+}
+
+function failAll(text) {
+  for (const [id, mode] of pending) reply(id, mode, false, null, text);
+  pending.clear();
+}
+
+function onData(chunk) {
+  rest += chunk;
+  let nl;
+  while ((nl = rest.indexOf('\n')) >= 0) {
+    const line = rest.slice(0, nl);
+    rest = rest.slice(nl + 1);
+    if (!line.trim()) continue;
+    let msg;
+    try { msg = JSON.parse(line); } catch { continue; }
+    if (msg.event !== undefined && msg.id === undefined) {
+      parentPort.postMessage({ event: msg.event, data: msg });
+      continue;
+    }
+    const mode = pending.get(msg.id);
+    if (!mode) continue;
+    pending.delete(msg.id);
+    reply(msg.id, mode, msg.ok !== false, line, String(msg.error ?? 'Ispyx reported an error.'));
+  }
+}
+
+function send(req) {
+  pending.set(req.id, req.mode);
+  sock.write(JSON.stringify({ id: req.id, fn: req.fn, args: req.args }) + '\n');
+}
+
+parentPort.on('message', (req) => {
+  if (sock) {
+    send(req);
+    return;
+  }
+  rest = '';
+  ensureConnected().then(() => send(req), (e) => reply(req.id, req.mode, false, null, e.message));
+});

package/src/platform/darwin/rpc.js

@@ -0,0 +1,146 @@
+// Client for Ispyx.app's JSON-lines socket (see PROTOCOL.md).
+//
+// The socket lives in a worker thread (rpc-worker.js). The core wants synchronous platform calls, so callSync()
+// posts the request to the worker and blocks the main thread in Atomics.wait until the worker has written the
+// response into shared memory:
+//
+//   SharedArrayBuffer: [ header: 8 x Int32 | payload area (CAPACITY bytes) ]
+//     header[0] state (0 waiting, 1 ready)   header[1] id answered   header[2] payload byte length
+//     header[3] status (0 ok = the raw response line, 1 error = message text, 2 too big for the area)
+//     header[4] id the main thread is waiting for (the worker drops answers for calls that timed out)
+//   Responses larger than CAPACITY (rare: pixels travel in files) come over a MessagePort that the main thread
+//   reads synchronously with receiveMessageOnPort().
+//
+// callAsync() is the same call answered through the worker's message port (does not block). post() sends and
+// forgets (layerPresent, overlay updates): order is preserved because everything goes through one socket.
+// Events from the app (`stop`, `permissions`) arrive through onEvent() on the main thread's event loop.
+import os from 'node:os';
+import path from 'node:path';
+import { Worker, MessageChannel, receiveMessageOnPort } from 'node:worker_threads';
+
+const CAPACITY = 4 * 1024 * 1024;
+const HEADER = 64;
+const SYNC_TIMEOUT_MS = 30000;
+
+export const defaultEndpoint = () => path.join(os.homedir(), 'Library', 'Application Support', 'Ispyx', 'helper.sock');
+export const NOT_RUNNING = 'Cannot reach Ispyx.app. Install Ispyx.app (drag it to Applications) and start it once, then try again';
+
+let worker = null;
+let i32 = null;
+let sab = null;
+let bigPort = null;
+let nextId = 1;
+let refs = 0;
+const asyncPending = new Map(); // id -> { resolve, reject }
+const listeners = new Map(); // event name -> Set<cb>
+
+function start() {
+  if (worker) return;
+  const override = process.env.ISPYX_HELPER_ENDPOINT;
+  sab = new SharedArrayBuffer(HEADER + CAPACITY);
+  i32 = new Int32Array(sab, 0, 8);
+  const ch = new MessageChannel();
+  bigPort = ch.port1;
+  worker = new Worker(new URL('./rpc-worker.js', import.meta.url), {
+    workerData: {
+      sab,
+      bigPort: ch.port2,
+      endpoint: override || defaultEndpoint(),
+      // a resident started by Ispyx.app never opens the app again: when it cannot reach the app, the app is gone
+      autostart: !override && !process.env.ISPYX_APP_PID,
+      // started by Ispyx.app: an app that does not answer is gone, so give up fast (the resident then leaves)
+      waitMs: Number(process.env.ISPYX_HELPER_WAIT_MS) || (override ? 2000 : process.env.ISPYX_APP_PID ? 1000 : 10000),
+      notRunningMessage: NOT_RUNNING,
+    },
+    transferList: [ch.port2],
+  });
+  worker.unref();
+  worker.on('message', onWorkerMessage);
+  worker.on('error', (e) => { process.stderr.write(`ispyx: helper client crashed: ${e.message}\n`); worker = null; failAsync(e.message); });
+}
+
+function ref() { if (refs++ === 0) worker?.ref(); }
+function unref() { if (--refs === 0) worker?.unref(); }
+
+function failAsync(text) {
+  for (const p of asyncPending.values()) p.reject(new Error(text));
+  asyncPending.clear();
+  refs = 0;
+}
+
+function onWorkerMessage(m) {
+  if (m.event !== undefined) {
+    for (const cb of listeners.get(m.event) ?? []) {
+      try { cb(m.data); } catch (e) { process.stderr.write(`ispyx: event handler failed: ${e.message}\n`); }
+    }
+    return;
+  }
+  const p = asyncPending.get(m.id);
+  if (!p) return;
+  asyncPending.delete(m.id);
+  unref();
+  if (m.error !== undefined) p.reject(new Error(m.error));
+  else p.resolve(JSON.parse(m.line).result);
+}
+
+/** Blocking call: returns the result or throws Error(message from the app). */
+export function callSync(fn, ...args) {
+  start();
+  const id = nextId++;
+  Atomics.store(i32, 0, 0);
+  Atomics.store(i32, 4, id);
+  worker.postMessage({ id, fn, args, mode: 'sync' });
+  for (;;) {
+    if (Atomics.wait(i32, 0, 0, SYNC_TIMEOUT_MS) === 'timed-out') {
+      Atomics.store(i32, 4, 0);
+      throw new Error(`Ispyx did not answer ${fn} within ${SYNC_TIMEOUT_MS / 1000} s. Check that Ispyx.app is running and not waiting for a permission prompt.`);
+    }
+    if (Atomics.load(i32, 1) === id) break;
+    Atomics.store(i32, 0, 0); // an answer to an older call that arrived late: keep waiting
+  }
+  let status = i32[3];
+  let text;
+  if (status === 2) { // too big for the shared area: the worker sent it through the port
+    const m = receiveMessageOnPort(bigPort)?.message;
+    if (!m) throw new Error('Internal error: a large response from Ispyx was lost.');
+    ({ status, text } = m);
+  } else {
+    text = Buffer.from(sab, HEADER, i32[2]).toString('utf8');
+  }
+  if (status === 1) throw new Error(text);
+  return JSON.parse(text).result;
+}
+
+/** Non-blocking call: Promise of the result. */
+export function callAsync(fn, ...args) {
+  start();
+  const id = nextId++;
+  return new Promise((resolve, reject) => {
+    asyncPending.set(id, { resolve, reject });
+    ref();
+    worker.postMessage({ id, fn, args, mode: 'async' });
+  });
+}
+
+/** Fire and forget: the answer (and any error) is dropped. Ordered with every other call. */
+export function post(fn, ...args) {
+  start();
+  worker.postMessage({ id: nextId++, fn, args, mode: 'quiet' });
+}
+
+/** Subscribe to an app event ('stop', 'permissions'). Returns an unsubscribe function. */
+export function onEvent(name, cb) {
+  start();
+  if (!listeners.has(name)) listeners.set(name, new Set());
+  listeners.get(name).add(cb);
+  return () => listeners.get(name)?.delete(cb);
+}
+
+/** Stop the worker (tests). */
+export async function close() {
+  if (!worker) return;
+  const w = worker;
+  worker = null;
+  failAsync('closed');
+  await w.terminate();
+}

package/src/platform/fake/index.js

@@ -0,0 +1,162 @@
+// Fake platform: no OS access, everything in memory. Selected with ISPYX_PLATFORM=fake (tests). It exports the
+// whole surface of ../CONTRACT.md. Calls that change state are recorded in `calls`, so tests can assert on them.
+import os from 'node:os';
+import path from 'node:path';
+
+export const name = 'fake';
+export const capabilities = { elevation: true };
+export const stopLabel = 'Alt+Esc';
+
+/** Everything the core asked the fake to do: [{ fn, args }], oldest first. Tests may reset it with `calls.length = 0`. */
+export const calls = [];
+const record = (fn, ...args) => { calls.push({ fn, args }); };
+
+/** Every Layer ever created (tests inspect `present` calls and `destroyed`). */
+export const layers = [];
+
+export const init = () => {};
+export const dataDir = () => path.join(os.tmpdir(), 'ispyx-fake');
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ---- windows, monitors, pointer ----
+export const monitors = [
+  { left: 0, top: 0, width: 1920, height: 1080, primary: true },
+  { left: 1920, top: 0, width: 1920, height: 1080, primary: false },
+];
+export const windows = [
+  { hwnd: 101, title: 'Fake Notepad', className: 'FakeNotepad', pid: 1001, process: 'notepad.exe', elevated: false, minimized: false, rect: { left: 100, top: 100, width: 800, height: 600 } },
+  { hwnd: 102, title: 'Fake Browser', className: 'FakeBrowser', pid: 1002, process: 'browser.exe', elevated: false, minimized: false, rect: { left: 1000, top: 200, width: 900, height: 700 } },
+  { hwnd: 103, title: 'Fake Second Screen', className: 'FakeApp', pid: 1003, process: 'app.exe', elevated: false, minimized: false, rect: { left: 2000, top: 100, width: 700, height: 500 } },
+];
+let foreground = 101;
+let cursor = { x: 960, y: 540 };
+let clipboard = { text: null, formats: [] };
+
+const find = (id) => windows.find((x) => x.hwnd === id);
+export const describeWindow = (id) => { const x = find(id); return x ? { ...x, rect: { ...x.rect } } : null; };
+export const listWindows = ({ includeUntitled = false } = {}) => windows.filter((x) => includeUntitled || x.title).map((x) => describeWindow(x.hwnd));
+export const getRect = (id) => { const x = find(id); return x ? { ...x.rect } : null; };
+export const getTitle = (id) => find(id)?.title ?? '';
+export const getClass = (id) => find(id)?.className ?? '';
+export const getPid = (id) => find(id)?.pid ?? 0;
+export const processInfo = (pid) => { const x = windows.find((w) => w.pid === pid); return { name: x?.process ?? '', elevated: x?.elevated ?? false }; };
+export const windowExists = (id) => !!find(id);
+export const rootWindowAt = (x, y) => windows.find((w) => !w.minimized && x >= w.rect.left && x < w.rect.left + w.rect.width && y >= w.rect.top && y < w.rect.top + w.rect.height)?.hwnd ?? 0;
+export const foregroundWindow = () => foreground;
+export const bringToForeground = async (id) => { record('bringToForeground', id); if (!find(id)) return false; find(id).minimized = false; foreground = id; return true; };
+export const windowDpi = () => 96;
+export const selfIsElevated = () => false;
+export const isScreenLocked = () => false;
+export const focusIsPassword = () => false;
+export const foregroundLayout = () => 0x409;
+export const listMonitors = () => monitors.map((m) => ({ ...m }));
+export const virtualScreen = () => {
+  const x = Math.min(...monitors.map((m) => m.left)), y = Math.min(...monitors.map((m) => m.top));
+  return { x, y, width: Math.max(...monitors.map((m) => m.left + m.width)) - x, height: Math.max(...monitors.map((m) => m.top + m.height)) - y };
+};
+export const cursorPos = () => ({ ...cursor });
+
+// ---- input ----
+export const mouseMoveTo = (x, y) => { cursor = { x: Math.round(x), y: Math.round(y) }; record('mouseMoveTo', x, y); };
+export const mouseDown = (button) => record('mouseDown', button);
+export const mouseUp = (button) => record('mouseUp', button);
+export const mouseWheel = (notches) => record('mouseWheel', notches);
+export const mouseHWheel = (notches) => record('mouseHWheel', notches);
+export const typeUnicode = async (text, check = () => {}, delays = []) => {
+  const chars = [...text];
+  for (let i = 0; i < chars.length; i++) {
+    check();
+    record('typeUnicode', chars[i]);
+    const d = delays[i] ?? 0;
+    if (d > 0) await sleep(d);
+  }
+};
+export const keysDown = (codes) => record('keysDown', codes);
+export const keysUp = (codes) => record('keysUp', codes);
+export const pressVirtualKeys = (codes) => record('pressVirtualKeys', codes);
+
+const NAMED = ['ctrl', 'shift', 'alt', 'enter', 'esc', 'tab', 'space', 'backspace', 'delete', 'home', 'end', 'pageup', 'pagedown', 'left', 'up', 'right', 'down'];
+const OS_KEY = ['win', 'cmd', 'meta', 'super'];
+export function parseChord(str) {
+  return str.trim().split('+').filter(Boolean).map((k) => {
+    const key = k.trim().toLowerCase();
+    if (OS_KEY.includes(key)) return 'meta';
+    if (NAMED.includes(key) || /^f([1-9]|1\d|2[0-4])$/.test(key) || /^[a-z0-9]$/.test(key) || ',.-=/;\'[]\\`'.includes(key) && key.length === 1) return key; // codes are opaque: the key name
+    throw new Error(`Unknown key "${k}".`);
+  });
+}
+export const parseSequence = (str) => str.trim().split(/\s+/).filter(Boolean).map(parseChord);
+export const insertsContent = (codes) => (codes.includes('ctrl') && codes.includes('v')) || (codes.includes('shift') && codes.includes('insert'));
+
+// ---- screen capture ----
+function blank(rect) {
+  const width = Math.max(1, Math.round(rect.width)), height = Math.max(1, Math.round(rect.height));
+  const bits = new Uint8Array(width * height * 4);
+  for (let i = 3; i < bits.length; i += 4) bits[i] = 255; // opaque black
+  return { bits, width, height, rect: { left: rect.left, top: rect.top, width, height } };
+}
+export const captureScreenRect = (rect) => blank(rect);
+export function captureWindow(id) {
+  const r = getRect(id);
+  if (!r) throw new Error('That window no longer exists. Call list_windows again.');
+  return { ...blank(r), method: 'fake' };
+}
+
+// ---- clipboard ----
+export const getClipboardText = () => ({ text: clipboard.text, formats: [...clipboard.formats] });
+export const setClipboardText = (text) => { clipboard = { text, formats: ['text'] }; record('setClipboardText', text); };
+export const setClipboardFile = (file) => { clipboard = { text: null, formats: ['file'] }; record('setClipboardFile', file); };
+
+// ---- stop hotkey ----
+export const chordDown = () => false;
+export function installStopHotkey(onStop, lingerMs = 30000) {
+  let until = 0;
+  return { touch() { until = Date.now() + lingerMs; }, get active() { return Date.now() < until; }, stop() { until = 0; }, trigger() { onStop(stopLabel); } };
+}
+
+// ---- UI ----
+export class Overlay {
+  constructor({ enabled = true, hideAfterMs = 0, stopLabel: label = stopLabel } = {}) { this.enabled = enabled; this.hideAfterMs = hideAfterMs; this.stopLabel = label; this.active = false; this.label = ''; }
+  begin(label) { this.active = true; this.label = label; record('overlay.begin', label); }
+  done() { this.active = false; record('overlay.done'); }
+  stop(reason) { this.active = false; record('overlay.stop', reason); }
+  cancel(reason) { this.active = false; record('overlay.cancel', reason); }
+  async hiddenDuring(fn) { return await fn(); }
+}
+export const showDialog = async (opts) => { record('showDialog', opts); return { cancel: true, reason: 'closed by the user' }; };
+export const ensurePump = () => {};
+
+/** An effect window that only keeps its buffer and records what the effects did to it. */
+export class Layer {
+  constructor(width, height) {
+    this.width = width;
+    this.height = height;
+    this.px = new Uint8Array(width * height * 4);
+    this.shown = false;
+    this.destroyed = false;
+    this.everDrawn = false;
+    this.presents = []; // { x, y, alpha, height, width, srcY }
+    layers.push(this);
+  }
+
+  present(x, y, alpha, height = this.height, width = this.width, srcY = 0) {
+    if (this.destroyed) throw new Error('Layer was destroyed');
+    if (!this.everDrawn && this.px.some((b) => b !== 0)) this.everDrawn = true; // some frame had pixels
+    this.presents.push({ x, y, alpha, height, width, srcY });
+    this.shown = true;
+  }
+
+  destroy() { this.destroyed = true; }
+}
+
+/** Deterministic mask: a solid box of 0.6 x height per character with a one pixel margin. */
+export function textMask(text, heightPx = 22, weight = 600) {
+  const cw = Math.max(1, Math.round(heightPx * 0.6));
+  const width = Math.max(1, text.length * cw + 2), height = heightPx + 2;
+  const mask = new Uint8Array(width * height);
+  for (let c = 0; c < text.length; c++) {
+    if (text[c] === ' ') continue;
+    for (let y = 1; y < height - 1; y++) for (let x = 1 + c * cw; x < 1 + (c + 1) * cw - 1; x++) mask[y * width + x] = weight >= 600 ? 255 : 180;
+  }
+  return { width, height, mask };
+}

package/src/platform/index.js

@@ -0,0 +1,13 @@
+// Picks the platform layer for this OS. Every platform folder exports the same API (see CONTRACT.md); the rest
+// of the code imports this module and never a platform folder directly.
+const IMPLEMENTATIONS = {
+  win32: './win32/index.js',
+  darwin: './darwin/index.js',
+  linux: './linux/index.js',
+};
+
+const target = process.env.ISPYX_PLATFORM || process.platform; // ISPYX_PLATFORM=fake runs the core without a desktop (tests)
+const path = target === 'fake' ? './fake/index.js' : IMPLEMENTATIONS[target];
+if (!path) throw new Error(`ispyx does not support ${process.platform} yet.`);
+
+export default await import(path);

package/src/platform/win32/auth-dialog.ps1

@@ -0,0 +1,140 @@
+# Password prompt for ispyx. Prints one JSON line on stdout and exits.
+#   {"password":"..","confirm":"..","value":24,"unit":"saat","makeDefault":false}   or   {"cancel":true}
+# Control names double as UI Automation ids, so tests can drive the dialog.
+param(
+  [string]$Mode = 'unlock',   # unlock | setup
+  [string]$Message = '',
+  [int]$Seconds = 30,
+  [int]$Value = 24,
+  [string]$Unit = 'hours'
+)
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+[System.Windows.Forms.Application]::EnableVisualStyles()
+
+$setup = $Mode -eq 'setup'
+$form = New-Object System.Windows.Forms.Form
+$form.Text = 'ispyx'
+$form.Name = 'authForm'
+$form.StartPosition = 'CenterScreen'
+$form.FormBorderStyle = 'FixedDialog'
+$form.MaximizeBox = $false
+$form.MinimizeBox = $false
+$form.TopMost = $true
+$form.ShowInTaskbar = $true
+$form.ClientSize = New-Object System.Drawing.Size(380, $(if ($setup) { 250 } else { 215 }))
+$font = New-Object System.Drawing.Font('Segoe UI', 9)
+$form.Font = $font
+
+function Add-Label($text, $x, $y, $w = 340, $h = 20, $name = '') {
+  $l = New-Object System.Windows.Forms.Label
+  $l.Text = $text; $l.Location = New-Object System.Drawing.Point($x, $y); $l.Size = New-Object System.Drawing.Size($w, $h)
+  if ($name) { $l.Name = $name }
+  $form.Controls.Add($l); return $l
+}
+
+$y = 12
+$title = if ($setup) { 'First setup: choose a password. The tools will not run without it.' } else { 'A tool call came in. Enter the password to continue.' }
+$null = Add-Label $title 20 $y 340 34 'title'
+$y += 38
+$msg = Add-Label $Message.Trim() 20 $y 340 18 'message'
+$msg.ForeColor = [System.Drawing.Color]::Firebrick
+$y += 22
+
+$null = Add-Label 'Password' 20 $y 80 20
+$pw = New-Object System.Windows.Forms.TextBox
+$pw.Name = 'password'; $pw.UseSystemPasswordChar = $true
+$pw.Location = New-Object System.Drawing.Point(110, ($y - 3)); $pw.Size = New-Object System.Drawing.Size(250, 24)
+$form.Controls.Add($pw)
+$y += 34
+
+$cf = $null
+if ($setup) {
+  $null = Add-Label 'Repeat' 20 $y 80 20
+  $cf = New-Object System.Windows.Forms.TextBox
+  $cf.Name = 'confirm'; $cf.UseSystemPasswordChar = $true
+  $cf.Location = New-Object System.Drawing.Point(110, ($y - 3)); $cf.Size = New-Object System.Drawing.Size(250, 24)
+  $form.Controls.Add($cf)
+  $y += 34
+}
+
+$null = Add-Label 'Stay unlocked for' 20 $y 130 20
+$num = New-Object System.Windows.Forms.NumericUpDown
+$num.Name = 'duration'; $num.Minimum = 1; $num.Maximum = 100000; $num.Value = [Math]::Max(1, $Value)
+$num.Location = New-Object System.Drawing.Point(155, ($y - 3)); $num.Size = New-Object System.Drawing.Size(70, 24)
+$form.Controls.Add($num)
+$unitBox = New-Object System.Windows.Forms.ComboBox
+$unitBox.Name = 'unit'; $unitBox.DropDownStyle = 'DropDownList'
+$null = $unitBox.Items.AddRange(@('minutes', 'hours', 'days'))
+$unitBox.SelectedItem = $Unit; if ($unitBox.SelectedIndex -lt 0) { $unitBox.SelectedItem = 'hours' }
+$unitBox.Location = New-Object System.Drawing.Point(232, ($y - 3)); $unitBox.Size = New-Object System.Drawing.Size(80, 24)
+$form.Controls.Add($unitBox)
+$y += 30
+
+$chk = New-Object System.Windows.Forms.CheckBox
+$chk.Name = 'makeDefault'; $chk.Text = 'Make this the new default'
+$chk.Location = New-Object System.Drawing.Point(20, $y); $chk.Size = New-Object System.Drawing.Size(340, 22)
+$form.Controls.Add($chk)
+$y += 30
+
+$left = $Seconds
+$count = Add-Label '' 20 ($y + 4) 170 20 'countdown'
+$count.ForeColor = [System.Drawing.Color]::DimGray
+$ok = New-Object System.Windows.Forms.Button
+$ok.Name = 'ok'; $ok.Text = 'OK'; $ok.Location = New-Object System.Drawing.Point(200, $y); $ok.Size = New-Object System.Drawing.Size(75, 26)
+$ok.DialogResult = 'OK'; $form.AcceptButton = $ok; $form.Controls.Add($ok)
+$cancel = New-Object System.Windows.Forms.Button
+$cancel.Name = 'cancel'; $cancel.Text = 'Cancel'; $cancel.Location = New-Object System.Drawing.Point(285, $y); $cancel.Size = New-Object System.Drawing.Size(75, 26)
+$cancel.DialogResult = 'Cancel'; $form.CancelButton = $cancel; $form.Controls.Add($cancel)
+
+$timer = New-Object System.Windows.Forms.Timer
+$timer.Interval = 1000
+$timer.Add_Tick({
+  try {
+    $script:left--
+    $count.Text = "Closes in $($script:left) s"
+    if ($script:left -le 0) { $script:timedOut = $true; $form.DialogResult = 'Cancel'; $form.Close() }
+  } catch { [Console]::Error.WriteLine("tick failed: $($_.Exception.Message)") }
+})
+$count.Text = "Closes in $left s"
+$timer.Start()
+# A background process may not take the foreground (foreground lock): attaching to the foreground thread's input lifts it.
+Add-Type -Namespace Native -Name Fg -MemberDefinition @'
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool SetForegroundWindow(System.IntPtr h);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern void keybd_event(byte vk, byte scan, int flags, System.UIntPtr extra);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern System.IntPtr GetForegroundWindow();
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(System.IntPtr h, out uint pid);
+[System.Runtime.InteropServices.DllImport("user32.dll")] public static extern bool AttachThreadInput(uint a, uint b, bool attach);
+[System.Runtime.InteropServices.DllImport("kernel32.dll")] public static extern uint GetCurrentThreadId();
+'@
+$script:timedOut = $false
+function Bring-ToFront {
+  $fg = [Native.Fg]::GetForegroundWindow()
+  $pid0 = [uint32]0
+  $fgThread = [Native.Fg]::GetWindowThreadProcessId($fg, [ref]$pid0)
+  $me = [Native.Fg]::GetCurrentThreadId()
+  # (no Alt tap here: an Alt press/release on our own window starts the window-menu mode, which freezes the buttons)
+  $att = $fgThread -ne 0 -and $fgThread -ne $me -and [Native.Fg]::AttachThreadInput($me, $fgThread, $true)
+  [void][Native.Fg]::SetForegroundWindow($form.Handle)
+  if ($att) { [void][Native.Fg]::AttachThreadInput($me, $fgThread, $false) }
+  $form.Activate(); $pw.Focus()
+}
+$form.Add_Shown({
+  try { Bring-ToFront } catch { [Console]::Error.WriteLine("bring-to-front failed: $($_.Exception.Message)") } # never let this block the dialog
+})
+
+$res = $form.ShowDialog()
+$timer.Stop()
+if ($res -eq 'OK') {
+  $num.ValidateEditText() # commit text typed into the number box
+  $out = [ordered]@{
+    password = $pw.Text
+    confirm = $(if ($cf) { $cf.Text } else { '' })
+    value = [int]$num.Value
+    unit = [string]$unitBox.SelectedItem
+    makeDefault = [bool]$chk.Checked
+  }
+} else {
+  $out = [ordered]@{ cancel = $true; reason = $(if ($script:timedOut) { 'timeout' } else { 'closed' }) }
+}
+[Console]::Out.WriteLine(($out | ConvertTo-Json -Compress))

package/src/platform/win32/autostart.js

@@ -0,0 +1,54 @@
+// "Open at Windows start": a per-user Run entry (HKCU, no admin).
+//
+// Design choice: the Run value does not start node.exe directly, because node.exe is a console-subsystem
+// program and Windows would flash a console window at every logon. Instead the value is
+//     "<SystemRoot>\System32\wscript.exe" "%APPDATA%\ispyx\start.vbs"
+// and start.vbs runs `"<node.exe>" "<src/server.js>"` with window style 0 (hidden, not waited for). Started with no
+// arguments, server.js turns into the detached hidden resident process by itself (the launcher semantics), so
+// nothing visible appears. The registry is written through reg.exe (always present, per-user, no native glue).
+//
+// Tests can redirect everything with ISPYX_AUTOSTART_VALUE (value name; also names the .vbs), so the real entry is
+// never touched.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const RUN_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run';
+const valueName = () => process.env.ISPYX_AUTOSTART_VALUE || 'Ispyx';
+const roaming = () => process.env.APPDATA || path.join(process.env.USERPROFILE || '.', 'AppData', 'Roaming');
+const vbsPath = () => path.join(roaming(), 'ispyx', valueName() === 'Ispyx' ? 'start.vbs' : `start-${valueName()}.vbs`);
+const serverJs = () => path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'server.js');
+
+const reg = (args) => execFileSync('reg.exe', args, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
+
+export const autostart = {
+  /** The command line stored in the Run value. */
+  command() {
+    const wscript = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'wscript.exe');
+    return `"${wscript}" "${vbsPath()}"`;
+  },
+
+  /** Whether the Run value exists. */
+  get() {
+    try {
+      return reg(['query', RUN_KEY, '/v', valueName()]).includes('REG_');
+    } catch { return false; }
+  },
+
+  /** Turns the entry on or off; returns the resulting state. Throws if the registry cannot be written. */
+  set(on) {
+    if (on) {
+      const vbs = vbsPath();
+      fs.mkdirSync(path.dirname(vbs), { recursive: true });
+      const q = (s) => `"${s.replace(/"/g, '""')}"`; // VBScript string literal
+      const cmd = `"${process.execPath}" "${serverJs()}"`;
+      fs.writeFileSync(vbs, `CreateObject("WScript.Shell").Run ${q(cmd)}, 0, False\r\n`, 'utf8');
+      reg(['add', RUN_KEY, '/v', valueName(), '/t', 'REG_SZ', '/d', this.command(), '/f']);
+    } else {
+      try { reg(['delete', RUN_KEY, '/v', valueName(), '/f']); } catch { /* not there */ }
+      try { fs.rmSync(vbsPath(), { force: true }); } catch { /* best effort */ }
+    }
+    return this.get();
+  },
+};