dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/popup/src/config.js

@@ -0,0 +1,71 @@
+// Popup host configuration (task-1290). decision: keep the spike's hotkey chord and rain cadence
+// defaults, but make both configurable in a config file. The file is ~/.dexterm/popup.json (DEXTERM_HOME
+// overrides the directory, same convention as state.json / helius.key). Everything is optional; a missing
+// or malformed file degrades to the defaults and never throws — a popup must open even with a bad config.
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** The spike's global-hotkey chord (⌃⌥⌘⇧B). Accelerator syntax: `Mod+Mod+Code`, matched by the shell. */
+export const DEFAULT_HOTKEY = 'Control+Alt+Super+Shift+KeyB';
+/** task-1325: the global chord that closes every popup window (⌃⌥⌘⇧W). */
+export const DEFAULT_HOTKEY_CLOSE = 'Control+Alt+Super+Shift+KeyW';
+export const DEFAULT_DOCK = { enabled: true, width: 560, follow: true, followEvery: 0.5 };
+/** The rain cadence approved in the spike. speedScale 1 = the bubble-map default fall speed. */
+export const DEFAULT_RAIN = { enabled: true, speedScale: 1, density: 0.55 };
+export const DEFAULT_CONFIG = { hotkey: DEFAULT_HOTKEY, hotkeyClose: DEFAULT_HOTKEY_CLOSE, dock: { ...DEFAULT_DOCK }, rain: { ...DEFAULT_RAIN }, fpsCap: 60, source: 'defaults' };
+/** `DEXTERM_HOME` overrides `~/.dexterm` (tests point it at a temp dir). */
+export function dexHome(env = process.env) {
+    return env.DEXTERM_HOME && env.DEXTERM_HOME.trim() ? env.DEXTERM_HOME : join(homedir(), '.dexterm');
+}
+export function configPath(env = process.env) {
+    return join(dexHome(env), 'popup.json');
+}
+function num(v, lo, hi, dflt) {
+    const n = typeof v === 'number' ? v : NaN;
+    return Number.isFinite(n) ? Math.max(lo, Math.min(hi, n)) : dflt;
+}
+/**
+ * Validate a parsed config object into a PopupConfig, clamping every field and keeping the defaults for
+ * anything missing or out of range. The hotkey must be a short printable accelerator; an unexpected value
+ * is ignored so a bad file can never register a nonsense chord or an oversized string.
+ */
+export function normalizeConfig(raw, source = 'file') {
+    const o = (raw && typeof raw === 'object' ? raw : {});
+    const rrain = (o.rain && typeof o.rain === 'object' ? o.rain : {});
+    // empty = disabled; otherwise a short accelerator of letters/digits/+ only (no shell metacharacters)
+    const chord = (v, dflt) => {
+        if (typeof v !== 'string')
+            return dflt;
+        const h = v.trim();
+        return h === '' ? '' : (/^[A-Za-z0-9+]{1,64}$/.test(h) ? h : dflt);
+    };
+    const hotkey = chord(o.hotkey, DEFAULT_HOTKEY);
+    const rdock = (o.dock && typeof o.dock === 'object' ? o.dock : {});
+    return {
+        hotkey,
+        hotkeyClose: chord(o.hotkeyClose, DEFAULT_HOTKEY_CLOSE),
+        dock: {
+            enabled: typeof rdock.enabled === 'boolean' ? rdock.enabled : DEFAULT_DOCK.enabled,
+            width: Math.round(num(rdock.width, 360, 1600, DEFAULT_DOCK.width)),
+            follow: typeof rdock.follow === 'boolean' ? rdock.follow : DEFAULT_DOCK.follow,
+            followEvery: num(rdock.followEvery, 0.25, 5, DEFAULT_DOCK.followEvery),
+        },
+        rain: {
+            enabled: typeof rrain.enabled === 'boolean' ? rrain.enabled : DEFAULT_RAIN.enabled,
+            speedScale: num(rrain.speedScale, 0.1, 5, DEFAULT_RAIN.speedScale),
+            density: num(rrain.density, 0, 1, DEFAULT_RAIN.density),
+        },
+        fpsCap: Math.round(num(o.fpsCap, 15, 120, DEFAULT_CONFIG.fpsCap)),
+        source,
+    };
+}
+/** Load ~/.dexterm/popup.json, or the defaults when it is missing/unreadable/malformed. Never throws. */
+export function loadConfig(env = process.env) {
+    try {
+        const text = readFileSync(configPath(env), 'utf8');
+        return normalizeConfig(JSON.parse(text), 'file');
+    }
+    catch {
+        return { ...DEFAULT_CONFIG, dock: { ...DEFAULT_DOCK }, rain: { ...DEFAULT_RAIN } };
+    }
+}

package/dist/packages/popup/src/dock.js

@@ -0,0 +1,271 @@
+// dexterm popup — dock the chart window beside the terminal (task-1325).
+//
+// macOS only (elsewhere every function degrades to "no docking": the shell's default geometry is used).
+//
+//   * Which terminal: TERM_PROGRAM (Apple_Terminal | iTerm.app), else LC_TERMINAL=iTerm2 (survives tmux/ssh).
+//   * Which WINDOW: the one whose tab (Terminal.app) / session (iTerm2) has OUR controlling tty, found once and
+//     then addressed by window id; the front window if no tty matches (e.g. inside tmux).
+//   * One `osascript -l JavaScript` process does the work. It prints the screens first (AppKit, no Apple Events,
+//     no permission), then the terminal window's bounds (Apple Events to the terminal app: from inside that
+//     terminal this is the app talking to itself). With follow on it stays alive, re-checks every ~0.5 s, prints
+//     only when something changed, and exits by itself when its parent (the TUI) is gone.
+//   * Placement: right edge of the terminal, same top and height; left edge when the right side has no room;
+//     overlapping the screen's right edge (always-on-top) when neither side has room; and for an unknown
+//     terminal, the right edge of the main screen (always-on-top), full visible height.
+//
+// Nothing here reads keys, URLs or tickets: the script only carries our tty name and the terminal kind.
+import { spawn, spawnSync } from 'node:child_process';
+/** The terminal app we run in, from the environment it sets. */
+export function detectTerminal(env = process.env) {
+    const tp = env.TERM_PROGRAM ?? '';
+    if (tp === 'Apple_Terminal')
+        return 'terminal';
+    if (tp === 'iTerm.app' || env.LC_TERMINAL === 'iTerm2')
+        return 'iterm';
+    return 'unknown';
+}
+/** Our controlling tty as the terminal apps report it (`/dev/ttys003`), or null. */
+export function controllingTty(pid = process.pid, run = spawnSync) {
+    try {
+        const r = run('ps', ['-o', 'tty=', '-p', String(pid)], { encoding: 'utf8', timeout: 1500 });
+        const t = String(r.stdout ?? '').trim();
+        return /^ttys?\d+$/.test(t) ? `/dev/${t}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The JXA probe. `tty`/`kind` are JSON-encoded into the script (never interpolated raw). */
+export function dockScript(kind, tty, follow, everyS = 0.5) {
+    const every = Math.max(0.25, Math.min(5, Number.isFinite(everyS) ? everyS : 0.5));
+    return `ObjC.import('AppKit');
+ObjC.bindFunction('getppid', ['int', []]);
+var KIND = ${JSON.stringify(kind)}, TTY = ${JSON.stringify(tty)}, FOLLOW = ${follow ? 'true' : 'false'}, EVERY = ${every};
+var PARENT = $.getppid(), winId = null;
+function rect(b) {
+  if (!b) return null;
+  if (Array.isArray(b) && b.length === 4) return [b[0], b[1], b[2] - b[0], b[3] - b[1]];
+  if (typeof b.width === 'number') return [b.x, b.y, b.width, b.height];
+  return null;
+}
+function screens() {
+  var out = [], all = $.NSScreen.screens, mainH = all.objectAtIndex(0).frame.size.height;
+  for (var i = 0; i < all.count; i++) {
+    var s = all.objectAtIndex(i), f = s.frame, v = s.visibleFrame;
+    out.push({ frame: [f.origin.x, mainH - f.origin.y - f.size.height, f.size.width, f.size.height],
+               visible: [v.origin.x, mainH - v.origin.y - v.size.height, v.size.width, v.size.height], scale: s.backingScaleFactor });
+  }
+  return out;
+}
+function find(app, tabsOf) {
+  if (!app.running()) return null;
+  if (winId !== null) { try { return rect(app.windows.byId(winId).bounds()); } catch (e) { winId = null; } }
+  var ws = app.windows();
+  for (var i = 0; i < ws.length; i++) { if (TTY && tabsOf(ws[i])) { winId = ws[i].id(); return rect(ws[i].bounds()); } }
+  return ws.length ? rect(ws[0].bounds()) : null;
+}
+function term() {
+  try {
+    if (KIND === 'terminal') return find(Application('com.apple.Terminal'), function (w) {
+      var t = w.tabs(); for (var j = 0; j < t.length; j++) if (t[j].tty() === TTY) return true; return false; });
+    if (KIND === 'iterm') return find(Application('com.googlecode.iterm2'), function (w) {
+      var t = w.tabs(); for (var j = 0; j < t.length; j++) { var s = t[j].sessions(); for (var k = 0; k < s.length; k++) if (s[k].tty() === TTY) return true; } return false; });
+  } catch (e) { return null; }
+  return null;
+}
+function out(s) { $.NSFileHandle.fileHandleWithStandardOutput.writeData($(s + '\\n').dataUsingEncoding($.NSUTF8StringEncoding)); }
+function run() {
+  var sc = screens(), last = '';
+  out(JSON.stringify({ screens: sc, term: null, pending: KIND !== 'unknown' }));
+  for (;;) {
+    var s = JSON.stringify({ screens: screens(), term: term(), pending: false });
+    if (s !== last) { out(s); last = s; }
+    if (!FOLLOW) return '';
+    var pp = $.getppid(); if (pp !== PARENT || pp === 1) return '';
+    delay(EVERY);
+  }
+}
+`;
+}
+const finite = (n) => typeof n === 'number' && Number.isFinite(n);
+const toRect = (a) => Array.isArray(a) && a.length === 4 && a.every(finite) && a[2] > 0 && a[3] > 0 ? { x: a[0], y: a[1], w: a[2], h: a[3] } : null;
+/** Validate one probe line. Anything malformed → null (the caller keeps its last placement). */
+export function parseDockProbe(line) {
+    let o;
+    try {
+        o = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (!o || typeof o !== 'object')
+        return null;
+    const r = o;
+    if (!Array.isArray(r.screens) || r.screens.length === 0 || r.screens.length > 16)
+        return null;
+    const screens = [];
+    for (const s of r.screens) {
+        const so = (s ?? {});
+        const frame = toRect(so.frame), visible = toRect(so.visible);
+        if (!frame || !visible)
+            return null;
+        screens.push({ frame, visible, scale: finite(so.scale) ? so.scale : 1 });
+    }
+    return { screens, term: toRect(r.term), pending: r.pending === true };
+}
+const contains = (r, x, y) => x >= r.x && x < r.x + r.w && y >= r.y && y < r.y + r.h;
+/**
+ * Where the popup goes. Pure: unit-tested with synthetic screens/terminals.
+ *   right   — the terminal's right edge, same top + height (a narrower window if 360–width pt fit)
+ *   left    — mirrored, when the right side has no room
+ *   overlap — neither side fits: the screen's right edge, always-on-top, over part of the terminal
+ *   screen-right — unknown terminal: the main screen's right edge, full visible height, always-on-top
+ */
+export function dockRect(term, screens, kind, opts = {}) {
+    const want = Math.max(360, Math.round(opts.width ?? 560));
+    const gap = Math.max(0, Math.round(opts.gap ?? 4));
+    const main = screens[0]?.visible ?? { x: 0, y: 25, w: 1440, h: 875 };
+    if (!term) {
+        const w = Math.min(want, Math.round(main.w * 0.5));
+        return { rect: { x: main.x + main.w - w, y: main.y, w, h: main.h }, mode: 'screen-right', ontop: true, kind };
+    }
+    const cx = term.x + term.w / 2, cy = term.y + Math.min(term.h / 2, 40);
+    const V = (screens.find((s) => contains(s.frame, cx, cy)) ?? screens[0])?.visible ?? main;
+    const h = Math.max(200, Math.min(term.h, V.h));
+    const y = Math.max(V.y, Math.min(term.y, V.y + V.h - h));
+    const right = V.x + V.w - (term.x + term.w) - gap;
+    const left = term.x - V.x - gap;
+    if (right >= want)
+        return { rect: { x: term.x + term.w + gap, y, w: want, h }, mode: 'right', ontop: false, kind };
+    if (right >= 360)
+        return { rect: { x: term.x + term.w + gap, y, w: right, h }, mode: 'right', ontop: false, kind };
+    if (left >= want)
+        return { rect: { x: term.x - gap - want, y, w: want, h }, mode: 'left', ontop: false, kind };
+    const w = Math.min(want, V.w);
+    return { rect: { x: V.x + V.w - w, y, w, h }, mode: 'overlap', ontop: true, kind };
+}
+const same = (a, b) => !!a && a.mode === b.mode && Math.abs(a.rect.x - b.rect.x) < 1 && Math.abs(a.rect.y - b.rect.y) < 1 && Math.abs(a.rect.w - b.rect.w) < 1 && Math.abs(a.rect.h - b.rect.h) < 1;
+/** Probes and follows the terminal window. Every failure degrades to "no docking"; it never throws. */
+export class TerminalDock {
+    kind;
+    enabled;
+    tty;
+    opts;
+    child = null;
+    last = null;
+    onExit = () => this.stop();
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.kind = detectTerminal(opts.env ?? process.env);
+        this.enabled = (opts.platform ?? process.platform) === 'darwin';
+        this.tty = opts.tty !== undefined ? opts.tty : (this.enabled && this.kind !== 'unknown' ? controllingTty() : null);
+    }
+    get following() { return this.child !== null; }
+    run(follow) {
+        const args = ['-l', 'JavaScript', '-e', dockScript(this.kind, this.tty, follow, this.opts.followEvery)];
+        return this.opts.spawnImpl ? this.opts.spawnImpl('osascript', args) : spawn('osascript', args, { stdio: ['ignore', 'pipe', 'ignore'] });
+    }
+    place1(p) {
+        return dockRect(p.term, p.screens, p.term ? this.kind : (this.kind === 'unknown' ? 'unknown' : this.kind), { width: this.opts.width, gap: this.opts.gap });
+    }
+    /**
+     * One probe, at most `timeoutMs`. Resolves with the terminal-docked placement, or — when the terminal did
+     * not answer in time (first-run Automation prompt, app busy) — the screen-right placement from the screens
+     * line, or null off macOS / when even that failed.
+     */
+    place(timeoutMs = 1500) {
+        if (!this.enabled)
+            return Promise.resolve(null);
+        return new Promise((resolve) => {
+            let best = null, buf = '', done = false;
+            let child;
+            try {
+                child = this.run(false);
+            }
+            catch {
+                resolve(null);
+                return;
+            }
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(t);
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* gone */ }
+                const p = best ? this.place1(best) : null;
+                if (p)
+                    this.last = p;
+                resolve(p);
+            };
+            const t = setTimeout(finish, timeoutMs);
+            child.on('error', finish);
+            child.on('exit', finish);
+            child.stdout?.on('data', (d) => {
+                buf += d.toString();
+                let i;
+                while ((i = buf.indexOf('\n')) >= 0) {
+                    const p = parseDockProbe(buf.slice(0, i));
+                    buf = buf.slice(i + 1);
+                    if (p) {
+                        best = p;
+                        if (!p.pending)
+                            finish();
+                    }
+                }
+            });
+        });
+    }
+    /** Follow the terminal: `onPlace` fires on every changed placement. Idempotent; stop() ends it. */
+    follow(onPlace) {
+        if (!this.enabled || this.child || this.kind === 'unknown')
+            return;
+        let buf = '';
+        try {
+            this.child = this.run(true);
+        }
+        catch {
+            this.child = null;
+            return;
+        }
+        const child = this.child;
+        child.on('error', () => { if (this.child === child)
+            this.child = null; });
+        child.on('exit', () => { if (this.child === child)
+            this.child = null; });
+        child.stdout?.on('data', (d) => {
+            buf += d.toString();
+            let i;
+            while ((i = buf.indexOf('\n')) >= 0) {
+                const p = parseDockProbe(buf.slice(0, i));
+                buf = buf.slice(i + 1);
+                if (!p || p.pending || !p.term)
+                    continue; // never jump to screen-right while following
+                const pl = this.place1(p);
+                if (!same(this.last, pl)) {
+                    this.last = pl;
+                    try {
+                        onPlace(pl);
+                    }
+                    catch { /* the window may be gone */ }
+                }
+            }
+        });
+        process.once('exit', this.onExit);
+    }
+    stop() {
+        const c = this.child;
+        this.child = null;
+        process.removeListener('exit', this.onExit);
+        if (c) {
+            try {
+                c.kill('SIGTERM');
+            }
+            catch { /* gone */ }
+        }
+    }
+    /** The child's pid while following (for the CPU measurement). */
+    get pid() { return this.child?.pid; }
+}

package/dist/packages/popup/src/host.js

@@ -0,0 +1,210 @@
+// dexterm popup host — the window layer behind the PopupHost interface (task-1290).
+//
+// Two implementations, chosen at runtime:
+//   * ShellPopupHost  — spawns the frameless wry shell (shell/wry) and speaks the stdio control protocol.
+//                       Opens chromeless, transparent, always-on-top HUD windows. native = true.
+//   * BrowserPopupHost — graceful fallback when the shell binary or a display is unavailable: opens the
+//                       same loopback URL in the OS default browser (`open` / `xdg-open`). native = false.
+//
+// The popup URL (which carries a single-use ticket) is handed to the shell over STDIN, never argv, so `ps`
+// from another local user cannot read it. The browser fallback necessarily passes it as an argument — that
+// tradeoff is documented in the README threat notes; the ticket is single-use and loopback-only.
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { DEFAULT_HOTKEY, DEFAULT_HOTKEY_CLOSE } from "./config.js";
+import { isLoopbackUrl } from "./loopback.js";
+const here = path.dirname(fileURLToPath(import.meta.url));
+/** The built wry shell binary. `DEXTERM_POPUP_SHELL` overrides (e.g. a packaged location). */
+export function shellBinaryPath(env = process.env) {
+    if (env.DEXTERM_POPUP_SHELL && env.DEXTERM_POPUP_SHELL.trim())
+        return env.DEXTERM_POPUP_SHELL;
+    return path.join(here, '..', 'shell', 'wry', 'target', 'release', 'dexterm-shell-wry');
+}
+/** Whether a GUI display is reachable (a frameless window can be created). Browser fallback otherwise. */
+export function displayAvailable(env = process.env, platform = process.platform) {
+    if (platform === 'darwin')
+        return true; // macOS GUI session (a locked screen still has a display)
+    if (platform === 'win32')
+        return true;
+    return !!(env.DISPLAY || env.WAYLAND_DISPLAY); // X11 / Wayland on Linux; empty in a headless/CI box
+}
+/** Whether `createPopupHost` would pick the native shell (binary present + display), without starting anything. */
+export function nativeShellAvailable(env = process.env, platform = process.platform) {
+    return existsSync(shellBinaryPath(env)) && displayAvailable(env, platform);
+}
+/**
+ * Decide and construct the host without starting it. The shell is chosen only when its binary exists AND a
+ * display is available AND the browser was not forced; otherwise the browser fallback is returned with a
+ * reason the caller can show the user ("wry shell not built", "no display", ...).
+ */
+export function createPopupHost(opts = {}) {
+    const env = opts.env ?? process.env;
+    const platform = opts.platform ?? process.platform;
+    if (opts.forceBrowser)
+        return { host: new BrowserPopupHost(platform, opts.port), native: false, reason: 'browser requested' };
+    const bin = shellBinaryPath(env);
+    if (!existsSync(bin))
+        return { host: new BrowserPopupHost(platform, opts.port), native: false, reason: `wry shell not built (${bin}); run \`npm run build:shell\` in @dexterm/popup` };
+    if (!displayAvailable(env, platform))
+        return { host: new BrowserPopupHost(platform, opts.port), native: false, reason: 'no display available' };
+    return { host: new ShellPopupHost({ bin, hotkey: opts.hotkey ?? DEFAULT_HOTKEY, hotkeyClose: opts.hotkeyClose ?? DEFAULT_HOTKEY_CLOSE, env, ...(opts.proxyPort ? { proxyPort: opts.proxyPort } : {}) }), native: true, reason: 'wry shell' };
+}
+export class ShellPopupHost extends EventEmitter {
+    native = true;
+    proc = null;
+    spawnedAt = 0;
+    bin;
+    hotkey;
+    env;
+    hotkeyClose;
+    proxyPort;
+    /** Set from shell.ready (task-1325). */
+    hotkeyCloseRegistered = false;
+    /** task-1358 r4: the sink proxy the shell confirmed in shell.ready (`127.0.0.1:<port>`), or null. */
+    sinkProxy = null;
+    constructor(deps) { super(); this.bin = deps.bin; this.hotkey = deps.hotkey; this.env = deps.env; this.hotkeyClose = deps.hotkeyClose ?? DEFAULT_HOTKEY_CLOSE; this.proxyPort = deps.proxyPort; }
+    async start() {
+        if (this.proc)
+            return { hotkeyRegistered: false, spawnToReadyMs: 0, sinkProxy: this.sinkProxy };
+        this.spawnedAt = performance.now();
+        // The hotkey chord (and, r4, the sink proxy address) reach the shell via the environment, never a
+        // shell-interpolated command line.
+        const env = { ...this.env, DEXTERM_POPUP_HOTKEY: this.hotkey, DEXTERM_POPUP_HOTKEY_CLOSE: this.hotkeyClose, ...(this.proxyPort ? { DEXTERM_POPUP_PROXY: `127.0.0.1:${this.proxyPort}` } : {}) };
+        this.proc = spawn(this.bin, [], { stdio: ['pipe', 'pipe', 'pipe'], env });
+        let buf = '';
+        this.proc.stdout.on('data', (d) => {
+            buf += d.toString();
+            let i;
+            while ((i = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, i);
+                buf = buf.slice(i + 1);
+                if (!line.trim())
+                    continue;
+                let ev;
+                try {
+                    ev = JSON.parse(line);
+                }
+                catch {
+                    this.emit('stderr', line);
+                    continue;
+                }
+                this.emit('shell', ev);
+                if (ev.ev)
+                    this.emit(ev.ev, ev);
+            }
+        });
+        this.proc.stderr.on('data', (d) => this.emit('stderr', d.toString().trimEnd()));
+        this.proc.on('exit', (code, sig) => { this.proc = null; this.emit('exit', { code, sig }); });
+        this.proc.on('error', (err) => this.emit('error', err));
+        const ready = await this.waitFor('shell.ready', 20_000);
+        this.hotkeyCloseRegistered = !!ready.hotkey_close_registered;
+        this.sinkProxy = typeof ready.sink_proxy === 'string' ? ready.sink_proxy : null;
+        return { hotkeyRegistered: !!ready.hotkey_registered, spawnToReadyMs: +(performance.now() - this.spawnedAt).toFixed(1), sinkProxy: this.sinkProxy };
+    }
+    sendOp(op) { if (!this.proc)
+        throw new Error('shell not running'); this.proc.stdin.write(JSON.stringify(op) + '\n'); }
+    open(id, url, geom = {}) {
+        // The URL reaching here is already pinned to our server origin (assertLoopbackUrl / a server ticket).
+        // The shell pins every later navigation of this window to the same origin; `port` tells it which.
+        let port;
+        try {
+            const u = new URL(url);
+            port = Number(u.port || '80');
+        }
+        catch {
+            port = undefined;
+        }
+        this.sendOp({ op: 'open', id, url, port, x: geom.x ?? 80, y: geom.y ?? 80, w: geom.w ?? 960, h: geom.h ?? 640, ontop: geom.ontop ?? true, focus: geom.focus ?? false });
+    }
+    close(id) { this.sendOp({ op: 'close', id }); }
+    show(id) { this.sendOp({ op: 'show', id }); }
+    hide(id) { this.sendOp({ op: 'hide', id }); }
+    focus(id) { this.sendOp({ op: 'focus', id }); }
+    alwaysOnTop(id, on) { this.sendOp({ op: 'ontop', id, on }); }
+    clickThrough(id, on) { this.sendOp({ op: 'clickthrough', id, on }); }
+    move(id, x, y) { this.sendOp({ op: 'move', id, x, y }); }
+    setBounds(id, r) { this.sendOp({ op: 'bounds', id, x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.w), h: Math.round(r.h) }); }
+    snapshot(id, file) { this.sendOp({ op: 'snapshot', id, path: file }); }
+    quit() {
+        if (!this.proc)
+            return;
+        try {
+            this.sendOp({ op: 'quit' });
+        }
+        catch { /* already gone */ }
+        const p = this.proc;
+        setTimeout(() => { try {
+            p.kill('SIGKILL');
+        }
+        catch { /* ignore */ } }, 1500).unref();
+    }
+    get pid() { return this.proc?.pid; }
+    waitFor(ev, timeoutMs = 10_000, pred = () => true) {
+        return new Promise((resolve, reject) => {
+            const t = setTimeout(() => { this.off(ev, h); reject(new Error(`timeout waiting for ${ev}`)); }, timeoutMs);
+            const h = (e) => { if (!pred(e))
+                return; clearTimeout(t); this.off(ev, h); resolve(e); };
+            this.on(ev, h);
+        });
+    }
+}
+// ------------------------------------------------------------------ browser fallback host
+/**
+ * Opens popups as plain tabs/windows in the OS default browser. Everything else is a no-op: a browser tab
+ * cannot be made always-on-top / click-through / frameless, and closing it is the user's job. The loopback
+ * URL and its single-use ticket are identical to the shell path, so the security model is unchanged.
+ */
+export class BrowserPopupHost extends EventEmitter {
+    native = false;
+    platform;
+    port;
+    opened = new Set();
+    /** `port`: when known, only http://127.0.0.1:<port> URLs are ever launched (the manager passes the server's). */
+    constructor(platform = process.platform, port) { super(); this.platform = platform; this.port = port; }
+    start() { return Promise.resolve(null); }
+    open(id, url) {
+        if (!openInBrowser(url, this.platform, this.port)) {
+            this.emit('error', new Error(`refused to open ${url} in a browser on ${this.platform} (not our loopback origin, or no launcher)`));
+            return;
+        }
+        this.opened.add(id);
+        this.emit('window.created', { ev: 'window.created', id, t_ms: 0, create_ms: 0 });
+    }
+    close(id) { this.opened.delete(id); /* a browser tab cannot be closed from here */ }
+    show(_id) { }
+    hide(_id) { }
+    focus(_id) { }
+    alwaysOnTop(_id, _on) { }
+    clickThrough(_id, _on) { }
+    move(_id, _x, _y) { }
+    setBounds(_id, _r) { }
+    quit() { this.opened.clear(); }
+}
+/**
+ * Launch a URL in the OS browser: `open` (macOS) or `xdg-open` (Linux); `cmd /c start "" <url>` on Windows.
+ * Only http://127.0.0.1 URLs are ever launched — enforced here by a parsed comparison (see loopback.ts),
+ * not just assumed: https, remote hosts, userinfo (`http://127.0.0.1:1@evil.example/`), `localhost`,
+ * `[::1]` and non-http schemes are refused so a remote page can never be opened via the fallback (ROADMAP
+ * "no remote content"); with `port` given, any other loopback port is refused too. The URL is a single
+ * argument — no shell interpolation. Returns false when refused or when no launcher is available.
+ */
+export function openInBrowser(url, platform = process.platform, port) {
+    if (!isLoopbackUrl(url, port))
+        return false;
+    const href = new URL(url).toString();
+    const cmd = platform === 'darwin' ? ['open', href]
+        : platform === 'win32' ? ['cmd', '/c', 'start', '', href]
+            : ['xdg-open', href];
+    try {
+        const p = spawn(cmd[0], cmd.slice(1), { stdio: 'ignore' });
+        p.on('error', () => { });
+        p.unref?.();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/packages/popup/src/index.js

@@ -0,0 +1,12 @@
+// @dexterm/popup — loopback popup host: a frameless HUD-window layer (wry) with a graceful OS-browser
+// fallback, driven by a loopback-only server and a typed protocol (task-1290). The terminal is the hub;
+// heavy views (chart, token detail, feeds) open as chromeless always-on-top windows over the same data.
+export * from "./protocol.js";
+export { createPopupServer, POPUP_EVENTS, IMAGE_ROUTE_RE, IMAGE_ROUTE_PREFIX } from "./server.js";
+export { auditWidgetHtml, inlineHashes, normalizeWidgetHtml, cspHash, WIDGET_INLINE_MAX } from "./widget-html.js";
+export { createPopupHost, ShellPopupHost, BrowserPopupHost, openInBrowser, shellBinaryPath, displayAvailable, nativeShellAvailable } from "./host.js";
+export { createPopupManager, assertLoopbackUrl } from "./open.js";
+export { loopbackUrlProblem, isLoopbackUrl } from "./loopback.js";
+export { loadConfig, normalizeConfig, configPath, dexHome, DEFAULT_CONFIG, DEFAULT_HOTKEY, DEFAULT_HOTKEY_CLOSE, DEFAULT_DOCK, DEFAULT_RAIN } from "./config.js";
+export { detectTerminal, controllingTty, dockScript, parseDockProbe, dockRect, TerminalDock } from "./dock.js";
+export { runSelfTest, renderSelfTest, fixtureChartVM, fixtureRosterVM } from "./selftest.js";

package/dist/packages/popup/src/loopback.js

@@ -0,0 +1,53 @@
+// The one URL pin every popup path goes through (task-1290 follow-up): a popup may only load, navigate to,
+// or be launched in a browser at OUR loopback server origin, http://127.0.0.1:<port>/… — never a remote
+// page (ROADMAP "no remote content"), never another local service.
+//
+// This is a parsed comparison, not a string prefix: `http://127.0.0.1:1@evil.example/` has host
+// evil.example (the "127.0.0.1:1" is userinfo), so a prefix match on "http://127.0.0.1:" passes it and a
+// parsed one refuses it. Any userinfo is refused outright, even to our own host, so the launched URL can
+// never carry a credential-shaped prefix. The hostname must be exactly 127.0.0.1 after WHATWG
+// normalisation (so `0x7f.1`, `2130706433`, `127.0.0.%31` and `HTTP://` all resolve to our host and
+// pass — they ARE 127.0.0.1 — while `localhost`, `[::1]`, `127.0.0.1.evil.example` and `evil.example`
+// are refused: the server only answers `Host: 127.0.0.1:<port>`). The port must equal the server's
+// (an http:// URL with no explicit port means 80).
+//
+// The wry shell applies the same rule in Rust (shell/wry/src/main.rs `nav_allowed`) as defence in depth.
+/** Why `raw` is not an allowed popup URL for the server on `port`, or null when it is allowed. */
+export function loopbackUrlProblem(raw, port) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        return `popup url is not a valid URL: ${raw}`;
+    }
+    if (u.protocol !== 'http:')
+        return `popup url must be an http:// loopback url, got ${u.protocol}//`;
+    if (u.username !== '' || u.password !== '')
+        return 'popup url must not carry userinfo (user:pass@)';
+    if (u.hostname !== '127.0.0.1')
+        return `popup url host must be 127.0.0.1, got ${u.hostname || '(empty)'}`;
+    if ((u.port || '80') !== String(port))
+        return `popup url port must be the popup server's (${port}), got ${u.port || '(default)'}`;
+    return null;
+}
+/** The normalised URL when allowed (see loopbackUrlProblem); throws otherwise. */
+export function assertLoopbackUrl(raw, port) {
+    const problem = loopbackUrlProblem(raw, port);
+    if (problem)
+        throw new Error(problem);
+    return new URL(raw).toString();
+}
+/** True when `raw` is an http:// URL at exactly 127.0.0.1 with no userinfo (and on `port`, when given). */
+export function isLoopbackUrl(raw, port) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (u.protocol !== 'http:' || u.username !== '' || u.password !== '' || u.hostname !== '127.0.0.1')
+        return false;
+    return port === undefined || (u.port || '80') === String(port);
+}