dexterm-cli 0.0.0-stage → 0.1.2

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);
+}

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

@@ -0,0 +1,183 @@
+// dexterm popup host — the small, lane-reusable facade (task-1290 scope item 3).
+//
+//   const mgr = createPopupManager({ theme, onEvent });
+//   const h = await mgr.open({ kind: 'chart', title: 'WIF', data: chartVm });   // opens a frameless HUD window
+//   mgr.setData(h.id, nextChartVm);                                             // the popup follows the open coin
+//   h.close();                                                                  // closing never touches the TUI
+//
+// The same `open({ kind, url|route, title })` is what Jarvis will call ("show me the bubble map for X") and
+// what the trading lane's wallet bridge can call to render its loopback page in a chromeless window instead
+// of the default browser — pass `url` for a custom loopback page, or `route` for one of the built-in kinds.
+import { EventEmitter } from 'node:events';
+import { randomBytes } from 'node:crypto';
+import os from 'node:os';
+import { createPopupServer } from "./server.js";
+import { createPopupHost } from "./host.js";
+import { createSinkProxy } from "./sinkproxy.js";
+import { DEFAULT_HOTKEY, DEFAULT_RAIN } from "./config.js";
+/** macOS major (Darwin kernel major − 9): WKWebsiteDataStore.proxyConfigurations needs macOS 14 = Darwin 23. */
+const darwinMajor = () => Number(os.release().split('.')[0]) || 0;
+// A custom popup URL may only point at our own loopback server origin (http://127.0.0.1:<server-port>/…).
+// This enforces the ROADMAP "no remote content" rule in code, not just in the doc comment: https, any
+// other host, any other port, userinfo and non-http schemes are all rejected before a window or browser
+// tab opens. The rule itself lives in ./loopback.ts (shared with the browser fallback); re-exported here.
+import { assertLoopbackUrl } from "./loopback.js";
+export { assertLoopbackUrl, loopbackUrlProblem } from "./loopback.js";
+export function createPopupManager(opts = {}) {
+    const emitter = new EventEmitter();
+    if (opts.onEvent)
+        emitter.on('event', opts.onEvent);
+    let server = null;
+    let host = null;
+    let native = false;
+    let reason = 'not started';
+    let hotkeyRegistered = false;
+    let hostDead = false;
+    let startPromise = null;
+    const openIds = new Set();
+    // task-1358 r4: the sink proxy + the widget gate (see PopupManager.widgetsAllowed)
+    let sinkProxy = null;
+    let widgetsOk = false;
+    let widgetReason = 'popups not started';
+    const warn = (m) => { opts.onWarn?.(m); };
+    const noWidgets = (why) => { widgetsOk = false; widgetReason = why; };
+    /** Swap a crashed native shell for the browser fallback so the next open() degrades instead of throwing. */
+    async function switchToBrowser(why) {
+        hostDead = false;
+        native = false;
+        hotkeyRegistered = false;
+        reason = `${why}; using browser`;
+        noWidgets(`browser fallback (${reason})`);
+        const fb = createPopupHost({ forceBrowser: true, env: opts.env, platform: opts.platform, port: server?.port });
+        host = fb.host;
+        await host.start();
+        warn(`popups open in your browser: ${reason}`);
+    }
+    async function ensureStarted() {
+        if (startPromise)
+            return startPromise;
+        startPromise = (async () => {
+            server = await createPopupServer({
+                theme: opts.theme,
+                rain: opts.rain ?? { ...DEFAULT_RAIN },
+                onEvent: (ev) => emitter.emit('event', ev),
+                ...(opts.imageProvider ? { imageProvider: opts.imageProvider } : {}),
+            });
+            const hostOpts = { hotkey: opts.hotkey ?? DEFAULT_HOTKEY, hotkeyClose: opts.hotkeyClose, forceBrowser: opts.forceBrowser, env: opts.env, platform: opts.platform, port: server.port };
+            let decision = createPopupHost(hostOpts);
+            if (decision.native) {
+                // r4: the shell gets a loopback sink proxy that tunnels to the popup server and nowhere else; every
+                // connection a WebView makes — page loads, the socket, a runtime <link rel=preconnect> — goes through it.
+                const srvPort = server.port;
+                sinkProxy = await createSinkProxy({ targetPort: srvPort, onRefused: (r) => emitter.emit('event', { ev: 'proxy.refused', ...r }) });
+                decision = createPopupHost({ ...hostOpts, proxyPort: sinkProxy.port });
+            }
+            host = decision.host;
+            native = decision.native;
+            reason = decision.reason;
+            if (!native) {
+                warn(`popups open in your browser: ${reason}`);
+                noWidgets(`browser fallback (${reason})`);
+            }
+            else {
+                // If the native window shell dies (crash/kill), mark it dead so the next open() re-starts via the
+                // browser fallback instead of letting a later close/open throw "shell not running" into the TUI.
+                const nativeHost = host;
+                nativeHost.once?.('exit', () => { hostDead = true; noWidgets('the popup shell exited'); });
+            }
+            try {
+                const info = await host.start();
+                if (info)
+                    hotkeyRegistered = info.hotkeyRegistered;
+                if (native) {
+                    const confirmed = info?.sinkProxy ?? null;
+                    if ((opts.platform ?? process.platform) === 'darwin' && darwinMajor() < 23)
+                        noWidgets('the sink proxy needs macOS 14 or newer');
+                    else if (!sinkProxy || confirmed !== sinkProxy.address)
+                        noWidgets(`the popup shell did not confirm the sink proxy (${confirmed ?? 'none'})`);
+                    else {
+                        widgetsOk = true;
+                        widgetReason = `native shell behind the sink proxy ${sinkProxy.address}`;
+                    }
+                }
+            }
+            catch (err) {
+                // The shell was present but would not start (missing libs, no GUI session, crash): degrade to the
+                // browser so a popup still opens, and tell the user why.
+                reason = `shell failed to start (${err.message}); using browser`;
+                native = false;
+                hotkeyRegistered = false;
+                noWidgets(`browser fallback (${reason})`);
+                warn(`popups open in your browser: ${reason}`);
+                const fb = createPopupHost({ forceBrowser: true, env: opts.env, platform: opts.platform, port: server.port });
+                host = fb.host;
+                await host.start();
+            }
+        })();
+        return startPromise;
+    }
+    function handleFor(id, kind) {
+        return {
+            id, kind, native,
+            setData: (data) => server?.setData(id, data),
+            sendData: (topic, payload) => server?.sendData(id, topic, payload),
+            close: () => { server?.closePopup(id); host?.close(id); openIds.delete(id); },
+            show: () => host?.show(id),
+            hide: () => host?.hide(id),
+            focus: () => host?.focus(id),
+            alwaysOnTop: (on) => host?.alwaysOnTop(id, on),
+            setBounds: (r) => { if (native && !hostDead)
+                host?.setBounds?.(id, r); },
+        };
+    }
+    return {
+        async open(req) {
+            await ensureStarted();
+            if (hostDead)
+                await switchToBrowser('popup window shell exited');
+            if (!server || !host)
+                throw new Error('popup host failed to start');
+            const id = `p_${randomBytes(6).toString('hex')}`;
+            const kind = req.route ?? req.kind;
+            // r4: a pack widget never opens in an engine the host does not route through its sink proxy
+            if ((kind === 'widget' || req.widget) && !widgetsOk)
+                throw new Error(`pack widgets open only in the native popup shell behind its sink proxy — ${widgetReason}`);
+            // A custom loopback URL (e.g. the wallet bridge's own page) is pinned to our own loopback origin —
+            // never a remote page; a built-in kind gets a single-use ticket URL from our server with the initial
+            // view model attached. assertLoopbackUrl throws on https/other-host/other-port before anything opens.
+            const url = req.url !== undefined
+                ? assertLoopbackUrl(req.url, server.port)
+                : server.issueTicket(kind, id, { ...(req.data ? { data: req.data } : {}), ...(req.widget ? { widget: req.widget } : {}), ...(native ? {} : { fallback: reason }) });
+            host.open(id, url, req.geom);
+            openIds.add(id);
+            return handleFor(id, kind);
+        },
+        setData: (id, data) => server?.setData(id, data),
+        close: (id) => { server?.closePopup(id); host?.close(id); openIds.delete(id); },
+        get native() { return native; },
+        get reason() { return reason; },
+        get hotkeyRegistered() { return hotkeyRegistered; },
+        get port() { return server?.port ?? null; },
+        get widgetsAllowed() { return widgetsOk; },
+        get widgetReason() { return widgetReason; },
+        get sinkProxyPort() { return sinkProxy?.port ?? null; },
+        get sinkProxyStats() { return sinkProxy ? { forwarded: sinkProxy.forwarded, refused: sinkProxy.refused } : null; },
+        async shutdown() {
+            try {
+                host?.quit();
+            }
+            catch { /* ignore */ }
+            if (sinkProxy) {
+                await sinkProxy.close();
+                sinkProxy = null;
+            }
+            noWidgets('popups shut down');
+            if (server)
+                await server.close();
+            server = null;
+            host = null;
+            startPromise = null;
+            openIds.clear();
+        },
+    };
+}

package/dist/packages/popup/src/pages/bubbles-lib.js

@@ -0,0 +1,160 @@
+// dexterm popup — bubble map pure helpers (task-1340). No DOM, no network, no globals besides the export.
+// The SAME layout algorithm as @dexterm/tui bubbles.ts (packed circles per cluster, members radial around their
+// hub, area ∝ share with a per-bubble cap), in plain JS so the page can inline it under its CSP nonce and
+// test/bubbles-lib.test.ts can load it through node:vm. Pixel space here is real pixels (W × H), not half-rows.
+(function (root) {
+  'use strict';
+  const KIND_LETTER = { 'dev-linked': 'D', dev: 'D', bundle: 'B', funder: 'F', transfer: 'T', sniper: 'S', pool: 'P', cex: 'X', whale: 'W', plain: '·' };
+  const LEGEND = [['dev', 'dev'], ['bundle', 'bundle'], ['funder', 'linked'], ['sniper', 'sniper'], ['pool', 'pool/LP'], ['cex', 'exchange'], ['plain', 'unlinked']];
+
+  /** Colour = rule; `t` is the popup theme tokens. */
+  function kindColor(t, kind) {
+    switch (kind) {
+      case 'dev': case 'dev-linked': return t.warn;
+      case 'bundle': return t.pump || t.accent;
+      case 'funder': return t.up;
+      case 'transfer': return t.dbc || t.warn;
+      case 'sniper': return t.down;
+      case 'pool': return t.accent;
+      case 'cex': case 'whale': return t.muted;
+      default: return t.dim;
+    }
+  }
+
+  function placeCluster(members) {
+    const hub = members[0];
+    const out = [{ i: hub.i, r: hub.r, dx: 0, dy: 0 }];
+    if (members.length === 1) return { items: out, R: hub.r + 1.5 };
+    let ringR = hub.r, k = 1, maxReach = hub.r;
+    while (k < members.length) {
+      const ring = [];
+      const d0 = ringR + 2;
+      let angleUsed = 0, biggest = 0;
+      while (k < members.length) {
+        const m = members[k];
+        const d = d0 + m.r;
+        const need = 2 * Math.asin(Math.min(1, (m.r + 1) / d));
+        if (ring.length && angleUsed + need > 2 * Math.PI) break;
+        ring.push({ m, d, need });
+        angleUsed += need; biggest = Math.max(biggest, m.r); k++;
+      }
+      const slack = Math.max(0, 2 * Math.PI - angleUsed) / ring.length;
+      let a = -Math.PI / 2 + (ring.length % 2 ? 0 : slack / 2) + out.length * 0.37;
+      for (const { m, d, need } of ring) {
+        a += need / 2 + slack / 2;
+        out.push({ i: m.i, r: m.r, dx: Math.cos(a) * d, dy: Math.sin(a) * d });
+        maxReach = Math.max(maxReach, d + m.r);
+        a += need / 2 + slack / 2;
+      }
+      ringR = d0 + 2 * biggest;
+    }
+    return { items: out, R: maxReach + 1.5 };
+  }
+
+  function packClusters(cls, W, H, gap) {
+    const placed = [];
+    const cx0 = W / 2, cy0 = H / 2;
+    const inside = (x, y, R) => x - R >= 0 && x + R <= W && y - R >= 0 && y + R <= H;
+    const free = (x, y, R) => placed.every((p) => Math.hypot(p.x - x, p.y - y) >= p.R + R + gap - 1e-6);
+    for (const c of cls) {
+      if (!placed.length) { if (!inside(cx0, cy0, c.R)) return null; placed.push(Object.assign({}, c, { x: cx0, y: cy0 })); continue; }
+      let best = null, bestD = Infinity;
+      for (const p of placed) {
+        for (let s = 0; s < 48; s++) {
+          const th = (s / 48) * 2 * Math.PI;
+          const d = p.R + c.R + gap;
+          const x = p.x + Math.cos(th) * d, y = p.y + Math.sin(th) * d;
+          if (!inside(x, y, c.R) || !free(x, y, c.R)) continue;
+          const dd = (x - cx0) ** 2 + ((y - cy0) * 1.15) ** 2;
+          if (dd < bestD) { bestD = dd; best = { x, y }; }
+        }
+      }
+      if (!best) return null;
+      placed.push(Object.assign({}, c, { x: best.x, y: best.y }));
+    }
+    return placed;
+  }
+
+  /**
+   * Lay out holders in a W×H pixel area. Returns { bubbles:[{idx,cx,cy,r}], clusters:[{name,kind,pct,cx,cy,R,members,multi}], k }.
+   * `focus` = a cluster name → only that cluster (zoom). Deterministic. Never throws (grid fallback).
+   */
+  function layout(holders, clusters, W, H, opts) {
+    opts = opts || {};
+    const idxs = holders.map((_, i) => i).filter((i) => !opts.focus || holders[i].cluster === opts.focus);
+    if (!idxs.length || W < 20 || H < 20) return { bubbles: [], clusters: [], k: 0, W, H };
+    const total = idxs.reduce((s, i) => s + Math.max(0.01, holders[i].pct), 0);
+    const fill = opts.fill != null ? opts.fill : opts.focus ? 0.6 : 0.5;
+    let k = Math.sqrt((fill * W * H) / (Math.PI * total));
+    const rMax = Math.min(W / 5.2, H / 2.6);
+    const gap = Math.max(2, Math.min(W, H) * 0.01);
+    for (let iter = 0; iter < 14; iter++) {
+      const byCluster = new Map();
+      for (const i of idxs) {
+        const h = holders[i];
+        const r = Math.max(3, Math.min(rMax, k * Math.sqrt(Math.max(0.01, h.pct))));
+        const key = h.cluster || `single:${i}`;
+        const arr = byCluster.get(key) || []; arr.push({ i, r }); byCluster.set(key, arr);
+      }
+      const cls = [];
+      for (const [key, members] of byCluster) {
+        members.sort((a, b) => b.r - a.r);
+        const pc = placeCluster(members);
+        const c = clusters.find((x) => x.name === key) || null;
+        cls.push({ key, name: c ? c.name : null, kind: c ? c.kind : holders[members[0].i].kind, pct: c ? c.pct : holders[members[0].i].pct, items: pc.items, R: pc.R, multi: members.length > 1 });
+      }
+      cls.sort((a, b) => b.R - a.R);
+      const placed = packClusters(cls, W, H, gap);
+      if (placed) {
+        const bubbles = [], out = [];
+        for (const p of placed) {
+          for (const it of p.items) bubbles.push({ idx: it.i, cx: p.x + it.dx, cy: p.y + it.dy, r: it.r });
+          out.push({ name: p.name, kind: p.kind, pct: p.pct, cx: p.x, cy: p.y, R: p.R, members: p.items.map((it) => it.i), multi: p.multi });
+        }
+        return { bubbles, clusters: out, k, W, H };
+      }
+      k *= 0.86;
+    }
+    const cols = Math.max(1, Math.floor(W / 24));
+    return { bubbles: idxs.map((i, n) => ({ idx: i, cx: 12 + (n % cols) * 24, cy: 12 + Math.floor(n / cols) * 24, r: 8 })), clusters: [], k, W, H, overflow: true };
+  }
+
+  /** Holder index under a point, or -1. */
+  function hit(lay, x, y) {
+    let best = -1, bestD = Infinity;
+    for (const b of lay.bubbles) { const d = Math.hypot(b.cx - x, b.cy - y); if (d <= b.r && d < bestD) { bestD = d; best = b.idx; } }
+    return best;
+  }
+
+  const shortAddr = (s, n) => { n = n || 4; s = String(s || ''); return s.length > 2 * n + 1 ? `${s.slice(0, n)}…${s.slice(-n)}` : s; };
+  const pctText = (p) => `${p.toFixed(p >= 10 ? 1 : 2)}%`;
+  const fmtNum = (n) => (n == null ? '—' : n >= 1e9 ? `${(n / 1e9).toFixed(2)}B` : n >= 1e6 ? `${(n / 1e6).toFixed(2)}M` : n >= 1e3 ? `${(n / 1e3).toFixed(1)}K` : String(Math.round(n)));
+
+  /** The rule panel lines for one holder: label · confidence, then the rule text, then up to 3 evidence lines. */
+  function whyLines(h, cluster) {
+    const lines = [];
+    if (!h) return lines;
+    lines.push({ kind: 'head', text: `${shortAddr(h.owner, 6)}  ${pctText(h.pct)}  ${h.kind.toUpperCase()}${h.cluster ? `  ${h.cluster}` : ''}` });
+    // task-1367: the holder class + its on-chain reason (absent from older terminals)
+    if (h.cls) {
+      lines.push({ kind: 'label', text: `■ ${h.cls.tag}`, right: 'on-chain', label: h.cls.tag === 'UNLABELLED' ? 'plain' : h.cls.tag === 'DEV' ? 'dev' : h.cls.tag === 'LINKED' ? 'dev-linked' : h.cls.tag === 'CEX' ? 'cex' : 'pool' });
+      lines.push({ kind: 'rule', text: h.cls.reason });
+      if (h.cls.lock) lines.push({ kind: 'muted', text: `${h.cls.lock.program} escrow ${shortAddr(h.cls.lock.escrow, 4)} · ${h.cls.lock.unlock || h.cls.lock.note}` });
+    }
+    if (h.funder) lines.push({ kind: 'muted', text: `funded by ${shortAddr(h.funder.address, 4)}${h.funder.label ? ` (${h.funder.label})` : ''}${h.funder.blockTime ? ` · ${new Date(h.funder.blockTime * 1000).toISOString().slice(0, 10)}` : ''}` });
+    else if (h.walletFirstSeen) lines.push({ kind: 'muted', text: `first seen ${new Date(h.walletFirstSeen * 1000).toISOString().slice(0, 10)} · funder not found in first txs` });
+    else lines.push({ kind: 'muted', text: 'funding not looked up (outside the funded sample)' });
+    const linked = cluster && cluster.members && cluster.members.length > 1;
+    const rules = h.labels && h.labels.length ? h.labels : linked
+      ? [{ label: `linked · ${cluster.kind}`, rule: `no label of its own; linked into ${cluster.name} (${cluster.members.length} wallets, ${Number(cluster.pct).toFixed(1)}%) by the evidence below`, confidence: 'on-chain' }]
+      : [{ label: 'unlinked', rule: 'no rule matched: no shared funder, same-slot buy, transfer or creator link found in the sample', confidence: 'n/a' }];
+    for (const r of rules) { lines.push({ kind: 'label', text: `● ${r.label}`, right: r.confidence || '', label: r.label }); lines.push({ kind: 'rule', text: r.rule }); }
+    const ev = cluster ? cluster.evidence.filter((e) => e.linked !== false && (e.a === h.owner || e.b === h.owner)).slice(0, 3) : [];
+    for (const e of ev) lines.push({ kind: 'evidence', text: `↳ ${shortAddr(e.a, 4)} ↔ ${shortAddr(e.b, 4)}: ${e.rule}` });
+    lines.push({ kind: 'foot', text: 'labels are heuristics (rule + evidence) · never asserted as fact' });
+    return lines;
+  }
+
+  const api = { KIND_LETTER, LEGEND, kindColor, layout, hit, shortAddr, pctText, fmtNum, whyLines };
+  root.DTBubbles = Object.freeze(api);
+})(typeof window !== 'undefined' ? window : globalThis);

package/dist/packages/popup/src/pages/bubbles.css

@@ -0,0 +1,23 @@
+/* dexterm popup — bubble map page (task-1340). Same HUD chrome as the chart; the map is a canvas, the panels are text. */
+.hud.bubbles .stage { min-height: 260px; }
+.hud.bubbles #map { z-index: 1; cursor: crosshair; }
+.hud.bubbles .depth { font-size: 11px; color: var(--dim); white-space: nowrap; }
+.hud.bubbles .banner { padding: 6px 12px; font-size: 12px; color: var(--warn); border-bottom: 1px solid var(--border); background: rgba(245,255,45,.05); }
+.hud.bubbles .banner.bad { color: var(--down); background: rgba(255,59,107,.06); }
+.hud.bubbles .tip { position: absolute; z-index: 2; max-width: 360px; padding: 6px 9px; font-size: 11px; line-height: 1.35; color: var(--text);
+  background: rgba(3,9,12,.94); border: 1px solid var(--border); border-radius: 8px; pointer-events: none; white-space: pre-wrap; word-break: break-word; }
+.hud.bubbles .tip .k { color: var(--muted); }
+.hud.bubbles .insights { display: grid; grid-template-columns: repeat(6, minmax(0, 1fr)); gap: 0 10px; padding: 5px 10px 3px; border-top: 1px solid var(--border); font-size: 11px; }
+.hud.bubbles .insights .cell .l { color: var(--dim); text-transform: uppercase; letter-spacing: .04em; font-size: 10px; }
+.hud.bubbles .insights .cell .v { color: var(--text); font-weight: 700; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.hud.bubbles .insights .cell .s { color: var(--muted); font-size: 10px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.hud.bubbles .insights .sample { grid-column: 1 / -1; color: var(--dim); font-size: 10px; padding-top: 2px; }
+.hud.bubbles .why { padding: 4px 10px 6px; border-top: 1px solid var(--border); font-size: 11px; line-height: 1.35; max-height: 118px; overflow: auto; }
+.hud.bubbles .why .head { color: var(--borderFocus); font-weight: 700; }
+.hud.bubbles .why .label { display: flex; justify-content: space-between; color: var(--text); font-weight: 700; margin-top: 3px; }
+.hud.bubbles .why .label .conf { color: var(--dim); font-weight: 400; }
+.hud.bubbles .why .rule { color: var(--muted); padding-left: 12px; }
+.hud.bubbles .why .evidence { color: var(--dim); font-style: italic; padding-left: 8px; }
+.hud.bubbles .why .foot, .hud.bubbles .why .muted { color: var(--dim); }
+.hud.bubbles .legend span { display: inline-flex; align-items: center; gap: 5px; }
+.hud.bubbles .legend i { display: inline-block; width: 9px; height: 9px; border-radius: 50%; }