dexterm-cli 0.0.0-stage → 0.1.1

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%; }

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

@@ -0,0 +1,36 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="dexterm-ws" content="__WS_TOKEN__">
+<meta name="dexterm-popup" content="__POPUP_ID__">
+<meta name="dexterm-port" content="__PORT__">
+<title>dexterm · bubble map</title>
+<style nonce="__NONCE__">/*__CSS__*/</style>
+</head>
+<body>
+<div id="hud" class="hud bubbles">
+  <div id="drag" class="drag">
+    <span class="mark">✦</span>
+    <span id="coin-img-slot" class="coin-img-slot" hidden></span>
+    <span id="title" class="title">dexterm · BUBBLE MAP</span>
+    <span id="depth" class="depth"></span>
+    <span id="status" class="status">connecting…</span>
+    <button id="close" class="close" type="button" aria-label="close">✕</button>
+  </div>
+  <div id="banner" class="banner" hidden></div>
+  <div class="stage">
+    <canvas id="rain"></canvas>
+    <canvas id="map"></canvas>
+    <div id="tip" class="tip" hidden></div>
+  </div>
+  <div id="insights" class="insights"></div>
+  <div id="why" class="why"></div>
+  <div id="legend" class="legend"></div>
+  <div id="foot" class="foot"><span>hover  rule</span><span>click  select</span><span>m  treemap</span><span>z  zoom cluster</span><span>esc  close</span><span id="fps" class="fps">— fps</span></div>
+</div>
+<script nonce="__NONCE__">/*__COMMON_JS__*/</script>
+<script nonce="__NONCE__">/*__LIB_JS__*/</script>
+<script nonce="__NONCE__">/*__JS__*/</script>
+</body>
+</html>

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

@@ -0,0 +1,214 @@
+// dexterm popup — BUBBLE MAP HUD (task-1340, wallet intel W5). The same engine output as the terminal's bubble
+// screen, drawn as real circles on a canvas: area ∝ share, colour = rule, dotted ring + tag per linked cluster,
+// hover shows the rule text behind a colour, click selects (the terminal hears `holder.selected`), `m` treemap,
+// `z` zooms the selected cluster. Inlined after common.js + bubbles-lib.js under a CSP nonce. No remote content,
+// no innerHTML: every untrusted string (addresses, rule text, symbol) goes through textContent / fillText.
+// Data is a BubbleVM over the WS; an `unavailable` VM draws a banner and nothing else — never a fake map.
+(() => {
+  'use strict';
+  const DT = window.DT; DT.page = 'bubbles'; DT.rainEvery = 2;
+  const B = window.DTBubbles;
+  const $ = (id) => document.getElementById(id);
+  const titleEl = $('title'), depthEl = $('depth'), bannerEl = $('banner'), tipEl = $('tip'), insightsEl = $('insights'), whyEl = $('why'), legendEl = $('legend');
+  const cv = $('map'); const ctx = cv.getContext('2d');
+  const rain = DT.mountRain('rain');
+  let vm = null, lay = null, view = 'bubbles', focus = null, hover = -1, selected = null, W = 0, H = 0, DPR = 1, dirty = true;
+
+  function clear(el) { while (el.firstChild) el.removeChild(el.firstChild); }
+  function el(tag, cls, text) { const e = document.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; }
+
+  function resize() {
+    const r = cv.parentElement.getBoundingClientRect();
+    W = Math.max(1, Math.floor(r.width)); H = Math.max(1, Math.floor(r.height)); DPR = Math.min(2, window.devicePixelRatio || 1);
+    cv.width = W * DPR; cv.height = H * DPR; cv.style.width = W + 'px'; cv.style.height = H + 'px';
+    ctx.setTransform(DPR, 0, 0, DPR, 0, 0);
+    if (rain) rain.resize(W, H);
+    lay = null; dirty = true;
+  }
+  window.addEventListener('resize', resize);
+  // the insights / WHY panels change height with the data and the hover, which resizes the stage: re-fit the canvas
+  if (typeof ResizeObserver !== 'undefined') new ResizeObserver(() => { const r = cv.parentElement.getBoundingClientRect(); if (Math.floor(r.width) !== W || Math.floor(r.height) !== H) resize(); }).observe(cv.parentElement);
+
+  function relayout() {
+    if (!vm || vm.state !== 'ok') { lay = null; return; }
+    lay = B.layout(vm.holders, vm.clusters, W - 16, H - 16, { focus });
+  }
+
+  // ---- legend (glyph + word, colour-blind second encoding)
+  function renderLegend() {
+    clear(legendEl);
+    const t = DT.theme;
+    for (const [kind, word] of B.LEGEND) {
+      const s = el('span'); const dot = el('i'); dot.style.background = B.kindColor(t, kind); if (kind === 'plain') dot.style.opacity = '.6';
+      s.appendChild(dot); s.appendChild(document.createTextNode(word)); legendEl.appendChild(s);
+    }
+  }
+
+  // ---- insights strip (sample-captioned)
+  function renderInsights() {
+    clear(insightsEl);
+    if (!vm || vm.state !== 'ok' || !vm.insights) return;
+    const I = vm.insights;
+    const pct = (v) => (v == null ? 'n/a' : `${Number(v).toFixed(1)}%`);
+    const cells = [
+      ['top10 raw', pct(I.top10Raw), 'by token acct'],
+      I.top10ExPool != null ? ['top10 ex-pool', pct(I.top10ExPool), `adj ${pct(I.top10Adjusted)} · -${I.exPoolDropped || 0} venue`] : ['top10 adj', pct(I.top10Adjusted), `excl ${I.excludedCount} labelled`],
+      ['snipers', I.snipers ? String(I.snipers.count) : 'n/a', I.snipers && I.snipers.count ? `${pct(I.snipers.launchSharePct)} at launch` : 'first 3 slots'],
+      ['bundled', pct(I.bundlePct), `${I.cohorts == null ? '—' : I.cohorts} cohorts`],
+      ['dev', I.devPct != null ? pct(I.devPct) : I.devUpperBoundPct != null ? `≤${pct(I.devUpperBoundPct)}` : 'n/a', I.devPct == null ? 'not in sample' : 'now'],
+      ['fresh', pct(I.freshPct), `of ${pct(I.freshMeasuredPct)} meas.`],
+    ];
+    for (const [l, v, s] of cells) { const c = el('div', 'cell'); c.appendChild(el('div', 'l', l)); c.appendChild(el('div', 'v', v)); c.appendChild(el('div', 's', s)); insightsEl.appendChild(c); }
+    if (I.bigHolder) { const r = el('div', 'sample', `⚠ main risk: ${I.bigHolder.tag} ${B.shortAddr(I.bigHolder.owner, 4)} holds ${pct(I.bigHolder.pct)} of supply`); r.style.color = DT.theme.down; r.style.fontWeight = 'bold'; insightsEl.appendChild(r); }
+    insightsEl.appendChild(el('div', 'sample', I.sample));
+  }
+
+  // ---- WHY THIS LABEL panel for the selected (or hovered) holder
+  function renderWhy() {
+    clear(whyEl);
+    if (!vm || vm.state !== 'ok') return;
+    const idx = hover >= 0 ? hover : selected;
+    const h = idx != null && idx >= 0 ? vm.holders[idx] : null;
+    if (!h) { whyEl.appendChild(el('div', 'muted', 'hover or click a bubble to see the rules behind its colour')); return; }
+    const cluster = h.cluster ? vm.clusters.find((c) => c.name === h.cluster) : null;
+    for (const ln of B.whyLines(h, cluster)) {
+      if (ln.kind === 'label') { const row = el('div', 'label'); const left = el('span', null, ln.text); left.style.color = B.kindColor(DT.theme, ln.label === 'LP' || ln.label === 'contract' ? 'pool' : ln.label === 'multi-token-top20' ? 'whale' : ln.label); row.appendChild(left); row.appendChild(el('span', 'conf', ln.right)); whyEl.appendChild(row); }
+      else whyEl.appendChild(el('div', ln.kind, ln.text));
+    }
+  }
+
+  function banner(text, bad) { if (!text) { bannerEl.hidden = true; return; } bannerEl.hidden = false; bannerEl.textContent = text; bannerEl.className = 'banner' + (bad ? ' bad' : ''); }
+
+  // ---- drawing
+  function rgba(hex, a) { return DT.rgba(hex, a); }
+  function draw() {
+    ctx.clearRect(0, 0, W, H);
+    if (!vm) return;
+    const t = DT.theme;
+    if (vm.state !== 'ok') { ctx.font = '13px ui-monospace, Menlo, monospace'; ctx.fillStyle = t.muted; ctx.textAlign = 'center'; ctx.fillText(vm.state === 'loading' ? 'scanning holders…' : 'bubble map unavailable', W / 2, H / 2); return; }
+    if (!lay) relayout();
+    if (!lay) return;
+    const ox = 8, oy = 8;
+    if (view === 'treemap') return drawTreemap(ox, oy, W - 16, H - 16);
+    ctx.font = '11px ui-monospace, Menlo, monospace'; ctx.textAlign = 'center'; ctx.textBaseline = 'middle';
+    // rings + tags
+    for (const cl of lay.clusters) {
+      if (!cl.multi) continue;
+      const col = B.kindColor(t, cl.kind);
+      ctx.save(); ctx.setLineDash([3, 4]); ctx.strokeStyle = rgba(col, 0.55); ctx.lineWidth = 1; ctx.beginPath(); ctx.arc(ox + cl.cx, oy + cl.cy, cl.R + 2, 0, Math.PI * 2); ctx.stroke(); ctx.restore();
+      ctx.fillStyle = col; ctx.font = 'bold 11px ui-monospace, Menlo, monospace';
+      ctx.fillText(`${B.KIND_LETTER[cl.kind] || '·'}·${cl.name} ${cl.members.length}w ${cl.pct.toFixed(1)}%`, ox + cl.cx, Math.max(8, oy + cl.cy - cl.R - 9));
+    }
+    // dotted edges from the selected holder to its mates
+    const sel = selected != null ? lay.bubbles.find((b) => b.idx === selected) : null;
+    if (sel) {
+      const cl = lay.clusters.find((c) => c.members.includes(selected));
+      if (cl && cl.multi) { ctx.save(); ctx.setLineDash([2, 4]); ctx.strokeStyle = rgba(t.accent, 0.7); for (const m of cl.members) { if (m === selected) continue; const mb = lay.bubbles.find((b) => b.idx === m); ctx.beginPath(); ctx.moveTo(ox + sel.cx, oy + sel.cy); ctx.lineTo(ox + mb.cx, oy + mb.cy); ctx.stroke(); } ctx.restore(); }
+    }
+    // discs
+    for (const b of lay.bubbles) {
+      const h = vm.holders[b.idx];
+      const isSel = b.idx === selected, isHover = b.idx === hover;
+      const col = isSel ? t.borderFocus : B.kindColor(t, h.kind);
+      const g = ctx.createRadialGradient(ox + b.cx - b.r * 0.3, oy + b.cy - b.r * 0.3, b.r * 0.1, ox + b.cx, oy + b.cy, b.r);
+      g.addColorStop(0, rgba(col, h.kind === 'plain' && !isSel ? 0.55 : 0.95)); g.addColorStop(1, rgba(col, h.kind === 'plain' && !isSel ? 0.3 : 0.7));
+      ctx.fillStyle = g; ctx.beginPath(); ctx.arc(ox + b.cx, oy + b.cy, b.r, 0, Math.PI * 2); ctx.fill();
+      if (isHover || isSel) { ctx.strokeStyle = isSel ? t.borderFocus : t.text; ctx.lineWidth = isSel ? 2 : 1.5; ctx.stroke(); }
+      if (b.r >= 14) {
+        ctx.fillStyle = '#031008'; ctx.font = `${isSel ? 'bold ' : ''}${b.r >= 30 ? 12 : 10}px ui-monospace, Menlo, monospace`;
+        const addr = B.shortAddr(h.owner, 4), pct = B.pctText(h.pct);
+        if (b.r >= 24) { ctx.fillText(addr, ox + b.cx, oy + b.cy - 7); ctx.fillText(pct, ox + b.cx, oy + b.cy + 6); if (b.r >= 36 && h.kind !== 'plain') ctx.fillText(h.kind.toUpperCase(), ox + b.cx, oy + b.cy + 19); }
+        else ctx.fillText(pct, ox + b.cx, oy + b.cy);
+      }
+    }
+    if (lay.overflow) { ctx.fillStyle = t.warn; ctx.font = '11px ui-monospace, Menlo, monospace'; ctx.textAlign = 'left'; ctx.fillText('window too small to pack the map: grid view', ox + 4, oy + 10); }
+  }
+
+  function drawTreemap(x, y, w, h) {
+    const t = DT.theme;
+    const items = vm.clusters.slice().sort((a, b) => b.pct - a.pct).map((cl) => ({ cl, v: Math.max(0.05, cl.pct) }));
+    const total = items.reduce((s, it) => s + it.v, 0) || 1;
+    // simple slice-and-dice rows (the terminal keeps the squarified version; this view is the share reading)
+    let cy = y, remain = h;
+    let i = 0;
+    while (i < items.length && remain > 2) {
+      let rowV = 0, j = i;
+      const target = Math.max(items[i].v, total * (remain / h) * 0.28);
+      while (j < items.length && rowV < target) rowV += items[j++].v;
+      const rh = Math.max(14, Math.round((rowV / total) * h));
+      let cx = x;
+      for (let k = i; k < j; k++) {
+        const cl = items[k].cl;
+        const rw = Math.round((items[k].v / rowV) * w);
+        const col = selected != null && cl.members.includes(vm.holders[selected] && vm.holders[selected].owner) ? t.borderFocus : B.kindColor(t, cl.kind);
+        ctx.fillStyle = rgba(col, 0.22); ctx.fillRect(cx, cy, rw - 1, rh - 1);
+        ctx.fillStyle = col; ctx.fillRect(cx, cy, 2, rh - 1);
+        if (rw > 44) { ctx.fillStyle = col; ctx.font = 'bold 11px ui-monospace, Menlo, monospace'; ctx.textAlign = 'left'; ctx.textBaseline = 'top'; ctx.fillText(cl.members.length > 1 ? `${B.KIND_LETTER[cl.kind] || '·'}·${cl.name}` : B.shortAddr(cl.members[0], 3), cx + 6, cy + 3); ctx.fillStyle = t.text; ctx.font = '11px ui-monospace, Menlo, monospace'; if (rh > 28) ctx.fillText(`${cl.pct.toFixed(1)}%${cl.members.length > 1 ? ` ${cl.members.length}w` : ''}`, cx + 6, cy + 16); }
+        cx += rw;
+      }
+      cy += rh; remain -= rh; i = j;
+    }
+  }
+
+  // ---- hover / click
+  function hitAt(e) {
+    if (!lay || view !== 'bubbles') return -1;
+    const r = cv.getBoundingClientRect();
+    return B.hit(lay, e.clientX - r.left - 8, e.clientY - r.top - 8);
+  }
+  cv.addEventListener('mousemove', (e) => {
+    const idx = hitAt(e);
+    if (idx !== hover) { hover = idx; dirty = true; renderWhy(); }
+    if (idx >= 0) {
+      const h = vm.holders[idx];
+      clear(tipEl);
+      tipEl.appendChild(el('div', 'k', `${B.shortAddr(h.owner, 6)} · ${B.pctText(h.pct)} · ${h.kind}${h.cluster ? ` · ${h.cluster}` : ''}`));
+      const first = h.labels && h.labels[0];
+      const cl0 = h.cluster ? (vm.clusters || []).find((c) => c.name === h.cluster) : null;
+      const ev0 = cl0 ? (cl0.evidence || []).find((e) => e.linked !== false && (e.a === h.owner || e.b === h.owner)) : null;
+      tipEl.appendChild(el('div', null, first ? `${first.label}: ${first.rule}` : ev0 ? `linked: ${ev0.rule}` : 'no rule matched · unlinked wallet'));
+      tipEl.hidden = false;
+      const r = cv.getBoundingClientRect();
+      const tx = Math.min(e.clientX - r.left + 14, W - 370), ty = Math.min(e.clientY - r.top + 14, H - 60);
+      tipEl.style.left = `${Math.max(4, tx)}px`; tipEl.style.top = `${Math.max(4, ty)}px`;
+    } else tipEl.hidden = true;
+  });
+  cv.addEventListener('mouseleave', () => { hover = -1; tipEl.hidden = true; dirty = true; renderWhy(); });
+  cv.addEventListener('click', (e) => {
+    const idx = hitAt(e);
+    if (idx < 0) return;
+    selected = idx; dirty = true; renderWhy();
+    const owner = vm.holders[idx] && vm.holders[idx].owner;
+    if (owner && /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(owner)) DT.send({ type: 'event', name: 'holder.selected', payload: { address: owner } });
+  });
+  window.addEventListener('keydown', (e) => {
+    if (e.key === 'm') { view = view === 'treemap' ? 'bubbles' : 'treemap'; dirty = true; }
+    else if (e.key === 'z') { if (focus) focus = null; else if (selected != null && vm && vm.holders[selected] && vm.holders[selected].cluster) focus = vm.holders[selected].cluster; lay = null; dirty = true; }
+    else return;
+    e.preventDefault();
+  });
+
+  function setData(a) {
+    vm = a;
+    const sym = String(vm.symbol || '?').replace(/^\$/, '');
+    titleEl.textContent = `dexterm · $${sym} · BUBBLE MAP`;
+    document.title = `dexterm · ${sym} bubbles`;
+    depthEl.textContent = vm.state === 'ok' ? `${vm.depth || 'light'} scan${vm.via ? ` · ${vm.via}` : ''}` : '';
+    if (vm.state === 'unavailable') banner(`bubble map unavailable: ${vm.reason || 'no holder source answered'}${vm.fix ? ` — ${vm.fix}` : ''}`, true);
+    else if (vm.state === 'loading') banner('scanning holders…', false);
+    else banner(vm.degraded ? `partial: ${vm.degraded}` : null, false);
+    if (vm.selected != null && vm.selected !== selected) selected = vm.selected;
+    if (focus && !(vm.clusters || []).some((c) => c.name === focus)) focus = null;
+    if (rain) rain.setSources([sym, String(vm.mint || '').slice(0, 6), ...((vm.holders || []).slice(0, 6).map((h) => String(h.owner).slice(-6)))]);
+    DT.status(vm.state === 'ok' ? `${vm.holders.length} holders` : vm.state, vm.state === 'ok' ? 'up' : vm.state === 'loading' ? 'warn' : 'down');
+    renderInsights(); renderWhy();
+    resize(); // the panels just changed height; fit the canvas to what is left before laying out
+  }
+
+  DT.onData(setData);
+  DT.onTheme(() => { renderLegend(); renderWhy(); dirty = true; });
+  DT.wireChrome();
+  resize(); renderLegend(); renderWhy();
+  DT.connect();
+  DT.loop(() => { if (dirty) { dirty = false; draw(); } });
+})();