dexterm-cli 0.1.1 → 0.1.3

package/dist/packages/cli/src/mcp-cmd.js

@@ -0,0 +1,321 @@
+// `dexterm mcp …` — the read-only MCP server plus one-command setup for any agent (task-1405).
+//
+//   dexterm mcp                         run the read-only MCP server on stdio (what the analyst uses and
+//                                       what `claude mcp add dexterm -- dexterm mcp` wires up)
+//   dexterm mcp install <client>        write/print the MCP config for a client (claude-code, claude-desktop,
+//                                       cursor, codex, generic). Shows the exact change, asks first,
+//                                       is idempotent, and backs the file up before editing.
+//   dexterm mcp doctor                  spawn the server over stdio, do the MCP handshake, and list the tools,
+//                                       prompts and resources the agent sees — proof the connection works.
+//
+// install writes nothing without consent: it prints the target file and the exact snippet, then (unless
+// --yes) asks on a TTY; a non-TTY run without --yes prints the plan and stops. --print never writes. The
+// config dir is resolved from the environment; --config FILE overrides it (tests point this at a temp dir),
+// so this command NEVER has to touch the real ~/.claude, Cursor or Claude Desktop config to be exercised.
+import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+function flag(rest, name) { const i = rest.indexOf(name); return i >= 0 ? rest[i + 1] : undefined; }
+function has(rest, name) { return rest.includes(name); }
+export function defaultCommand(env, useNode) {
+    if (!useNode)
+        return { command: 'dexterm', args: ['mcp'] };
+    // Fallback for when dexterm is not on PATH: run this repo's server bin with the current node.
+    return { command: process.execPath, args: [mcpBinPath(), 'mcp'] };
+}
+/** Where this repo's standalone MCP server bin lives (used by the --node command and by `doctor`). */
+export function mcpBinPath() {
+    const here = dirname(fileURLToPath(import.meta.url)); // packages/cli/src
+    return resolve(here, '..', '..', 'mcp', 'bin', 'dexterm-mcp.mjs');
+}
+function home(env) { return env.HOME || env.USERPROFILE || homedir(); }
+function appSupport(env, platform, app) {
+    if (platform === 'darwin')
+        return join(home(env), 'Library', 'Application Support', app);
+    if (platform === 'win32')
+        return join(env.APPDATA || join(home(env), 'AppData', 'Roaming'), app);
+    return join(env.XDG_CONFIG_HOME || join(home(env), '.config'), app);
+}
+export const CLIENTS = [
+    {
+        id: 'claude-code', label: 'Claude Code', format: 'json', keyPath: 'mcpServers',
+        path: (env) => join(env.DEXTERM_CWD || process.cwd(), '.mcp.json'),
+        note: 'project-scoped .mcp.json in the current directory; or run `claude mcp add dexterm -- dexterm mcp`.',
+    },
+    {
+        id: 'claude-desktop', label: 'Claude Desktop', format: 'json', keyPath: 'mcpServers',
+        path: (env, platform) => join(appSupport(env, platform, 'Claude'), 'claude_desktop_config.json'),
+        note: 'restart Claude Desktop after editing so it re-reads the config.',
+    },
+    {
+        id: 'cursor', label: 'Cursor', format: 'json', keyPath: 'mcpServers',
+        path: (env) => join(home(env), '.cursor', 'mcp.json'),
+        note: 'global Cursor MCP config (~/.cursor/mcp.json); a project .cursor/mcp.json works too.',
+    },
+    {
+        id: 'codex', label: 'Codex CLI', format: 'toml', keyPath: 'mcp_servers',
+        path: (env) => join(env.CODEX_HOME || join(home(env), '.codex'), 'config.toml'),
+        note: 'Codex reads MCP servers from the [mcp_servers.*] tables in ~/.codex/config.toml.',
+    },
+    {
+        id: 'generic', label: 'Generic (print the snippet)', format: 'print', keyPath: 'mcpServers',
+        path: () => null,
+        note: 'the standard stdio mcpServers entry most agents take; paste it where your agent reads MCP servers, or pass --config FILE to write a JSON file.',
+    },
+];
+export function clientById(id) { return CLIENTS.find((c) => c.id === id); }
+/** The JSON object a json-format client expects under its server map, for `dexterm`. */
+export function serverEntryJson(cmd) {
+    return { command: cmd.command, args: cmd.args };
+}
+/** The TOML block a codex-style client expects. */
+export function serverEntryToml(cmd) {
+    const args = cmd.args.map((a) => JSON.stringify(a)).join(', ');
+    return `[mcp_servers.dexterm]\ncommand = ${JSON.stringify(cmd.command)}\nargs = [${args}]\n`;
+}
+/** Plan a JSON merge: returns the new file text and whether anything changes. Preserves every other key. */
+export function planJson(existingText, keyPath, entry) {
+    let obj = {};
+    if (existingText && existingText.trim()) {
+        try {
+            const parsed = JSON.parse(existingText);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                obj = parsed;
+        }
+        catch {
+            throw new Error('the existing config is not valid JSON — fix or move it, then re-run');
+        }
+    }
+    const map = (obj[keyPath] && typeof obj[keyPath] === 'object' && !Array.isArray(obj[keyPath])) ? obj[keyPath] : {};
+    const prev = map.dexterm;
+    const was = prev === undefined ? 'absent' : JSON.stringify(prev) === JSON.stringify(entry) ? 'same' : 'different';
+    const next = { ...obj, [keyPath]: { ...map, dexterm: entry } };
+    return { text: JSON.stringify(next, null, 2) + '\n', changed: was !== 'same', was };
+}
+/** Plan a TOML merge: append the dexterm block when there is no [mcp_servers.dexterm] yet; never clobber. */
+export function planToml(existingText, block) {
+    const cur = existingText ?? '';
+    if (cur.includes(block.trim()))
+        return { text: cur, changed: false, was: 'same', conflict: false };
+    if (/\[mcp_servers\.dexterm\]/.test(cur))
+        return { text: cur, changed: false, was: 'different', conflict: true };
+    const sep = cur.length && !cur.endsWith('\n\n') ? (cur.endsWith('\n') ? '\n' : '\n\n') : '';
+    return { text: cur + sep + block, changed: true, was: 'absent', conflict: false };
+}
+function readLineYesNo(io, prompt) {
+    const stdin = io.stdin;
+    if (!stdin || !stdin.isTTY)
+        return Promise.resolve(false);
+    return new Promise((res) => {
+        const rl = readline.createInterface({ input: stdin, output: io.stdout });
+        rl.question(prompt, (ans) => { rl.close(); res(/^y(es)?$/i.test(ans.trim())); });
+    });
+}
+function backupPath(file) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return `${file}.bak-${stamp}`;
+}
+async function install(rest, io) {
+    const out = (s) => io.stdout.write(s + '\n');
+    const errOut = (s) => io.stderr.write(s + '\n');
+    const id = rest.find((a) => !a.startsWith('-'));
+    const spec = id ? clientById(id) : undefined;
+    if (!spec) {
+        errOut(`usage: dexterm mcp install <${CLIENTS.map((c) => c.id).join('|')}> [--config FILE] [--print] [--node] [--yes]`);
+        if (id)
+            errOut(`unknown client "${id}". known: ${CLIENTS.map((c) => c.id).join(', ')}`);
+        return 2;
+    }
+    const printOnly = has(rest, '--print');
+    const useNode = has(rest, '--node');
+    const yes = has(rest, '--yes') || has(rest, '-y');
+    const cmd = defaultCommand(io.env, useNode);
+    const override = flag(rest, '--config');
+    const target = override ? resolve(override) : spec.path(io.env, process.platform);
+    const forcePrint = spec.format === 'print' && !override;
+    // The snippet we would add, always shown.
+    const snippet = spec.format === 'toml' ? serverEntryToml(cmd) : JSON.stringify({ [spec.keyPath]: { dexterm: serverEntryJson(cmd) } }, null, 2);
+    out(`dexterm MCP server for ${spec.label}:`);
+    out('');
+    out(indent(snippet));
+    out('');
+    if (spec.note)
+        out(`note: ${spec.note}`);
+    if (printOnly || forcePrint) {
+        if (forcePrint && !printOnly)
+            out('(this client has no single well-known config file — paste the snippet above, or pass --config FILE to write it.)');
+        return 0;
+    }
+    if (!target) {
+        out('pass --config FILE to write this to a specific file.');
+        return 0;
+    }
+    const existed = existsSync(target);
+    const existingText = existed ? readFileSync(target, 'utf8') : null;
+    let plan;
+    try {
+        plan = spec.format === 'toml'
+            ? planToml(existingText, serverEntryToml(cmd))
+            : planJson(existingText, spec.keyPath, serverEntryJson(cmd));
+    }
+    catch (e) {
+        errOut(`dexterm mcp install: ${e.message} (${target})`);
+        return 1;
+    }
+    out('');
+    out(`target: ${target}${existed ? '' : ' (new file)'}`);
+    if (plan.conflict) {
+        out('a [mcp_servers.dexterm] section already exists and differs; not modifying it. Review it by hand, or edit it to match the snippet above.');
+        return 0;
+    }
+    if (!plan.changed) {
+        out('already configured — nothing to change (idempotent).');
+        return 0;
+    }
+    out(plan.was === 'different' ? 'this UPDATES the existing dexterm entry.' : existed ? 'this ADDS a dexterm entry (your other servers are preserved).' : 'this CREATES the config file with a dexterm entry.');
+    if (!yes) {
+        const ok = await readLineYesNo(io, 'write this change? [y/N] ');
+        if (!ok) {
+            out(io.stdin?.isTTY ? 'cancelled; nothing was written.' : 'not a TTY and --yes was not given; nothing written. Re-run with --yes to write, or --print to just print.');
+            return io.stdin?.isTTY ? 0 : 0;
+        }
+    }
+    try {
+        mkdirSync(dirname(target), { recursive: true });
+        if (existed) {
+            const bak = backupPath(target);
+            copyFileSync(target, bak);
+            out(`backed up: ${bak}`);
+        }
+        writeFileSync(target, plan.text, { mode: 0o600 });
+        out(`wrote ${target}.`);
+        out(`verify it: dexterm mcp doctor`);
+        return 0;
+    }
+    catch (e) {
+        errOut(`dexterm mcp install: could not write ${target}: ${e.message}`);
+        return 1;
+    }
+}
+function indent(s) { return s.split('\n').map((l) => '  ' + l).join('\n'); }
+async function doctor(rest, io) {
+    const out = (s) => io.stdout.write(s + '\n');
+    const errOut = (s) => io.stderr.write(s + '\n');
+    // Prefer the command install writes (`dexterm mcp`); fall back to this repo's node bin when dexterm is
+    // not on PATH (e.g. a dev checkout). Either way this is a real stdio child, not an in-process shortcut.
+    const useNode = has(rest, '--node');
+    const cmd = useNode ? defaultCommand(io.env, true) : { command: 'dexterm', args: ['mcp'] };
+    out(`dexterm mcp doctor — spawning: ${cmd.command} ${cmd.args.join(' ')}`);
+    const result = await probe(cmd, io.env).catch((e) => ({ error: e.message }));
+    if ('error' in result && !useNode && /ENOENT|not found|spawn/i.test(result.error)) {
+        // dexterm not on PATH: retry with the bundled node bin so doctor still verifies the server.
+        out(`(dexterm not on PATH; retrying with this checkout's server)`);
+        const fallback = defaultCommand(io.env, true);
+        out(`dexterm mcp doctor — spawning: ${fallback.command} ${fallback.args.join(' ')}`);
+        const r2 = await probe(fallback, io.env).catch((e) => ({ error: e.message }));
+        return report(r2, out, errOut);
+    }
+    return report(result, out, errOut);
+}
+function report(r, out, errOut) {
+    if ('error' in r) {
+        errOut(`✗ could not reach the MCP server: ${r.error}`);
+        return 1;
+    }
+    const info = r.serverInfo;
+    out(`✓ connected to ${info?.name ?? 'dexterm'} ${info?.version ?? ''} over stdio (MCP initialize ok)`);
+    out(`tools (${r.tools.length}): ${r.tools.join(', ')}`);
+    out(`prompts/skills (${r.prompts.length}): ${r.prompts.join(', ') || '(none)'}`);
+    out(`resources: ${r.resources}`);
+    out('the connection works; add it to your agent with `dexterm mcp install <client>`.');
+    return 0;
+}
+function probe(cmd, env) {
+    return new Promise((res, rej) => {
+        const child = spawn(cmd.command, cmd.args, { stdio: ['pipe', 'pipe', 'pipe'], env: { ...env, DEXTERM_OFFLINE: '1', NO_COLOR: '1' } });
+        const timer = setTimeout(() => { try {
+            child.kill();
+        }
+        catch { /* ignore */ } rej(new Error('timed out waiting for the server (10s)')); }, 10_000);
+        let stderr = '';
+        child.on('error', (e) => { clearTimeout(timer); rej(e); });
+        child.stderr.on('data', (d) => { stderr += String(d); });
+        const rl = readline.createInterface({ input: child.stdout });
+        const pending = new Map();
+        let seq = 0;
+        const send = (method, params) => {
+            const id = ++seq;
+            const msg = { jsonrpc: '2.0', id, method, ...(params ? { params } : {}) };
+            return new Promise((r) => { pending.set(id, r); child.stdin.write(JSON.stringify(msg) + '\n'); });
+        };
+        rl.on('line', (line) => {
+            if (!line.trim())
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (typeof msg.id === 'number' && pending.has(msg.id)) {
+                const r = pending.get(msg.id);
+                pending.delete(msg.id);
+                r(msg.result ?? {});
+            }
+        });
+        (async () => {
+            try {
+                const init = await send('initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'dexterm-doctor', version: '1' } });
+                const toolsRes = await send('tools/list');
+                const promptsRes = await send('prompts/list');
+                const resRes = await send('resources/list');
+                clearTimeout(timer);
+                try {
+                    child.stdin.end();
+                }
+                catch { /* ignore */ }
+                try {
+                    child.kill();
+                }
+                catch { /* ignore */ }
+                const tools = Array.isArray(toolsRes.tools) ? toolsRes.tools.map((t) => String(t.name)) : [];
+                const prompts = Array.isArray(promptsRes.prompts) ? promptsRes.prompts.map((p) => String(p.name)) : [];
+                const resources = Array.isArray(resRes.resources) ? resRes.resources.length : 0;
+                res({ serverInfo: init.serverInfo ?? {}, tools, prompts, resources });
+            }
+            catch (e) {
+                clearTimeout(timer);
+                rej(new Error(`${e.message}${stderr ? ` · server stderr: ${stderr.slice(0, 200)}` : ''}`));
+            }
+        })();
+    });
+}
+const USAGE = `dexterm mcp [<command>]
+  (no command)              run the read-only MCP server on stdio (claude mcp add dexterm -- dexterm mcp)
+  install <client>          write/print the MCP config for a client and verify what changes
+                            clients: ${CLIENTS.map((c) => c.id).join(', ')}
+                            --config FILE  write to a specific file (instead of the client's default)
+                            --print        only print the snippet, never write
+                            --node         emit a "node <path> mcp" command (when dexterm is not on PATH)
+                            --yes          write without the confirmation prompt
+  doctor                    spawn the server, do the MCP handshake, and list the tools/prompts/resources`;
+/** `dexterm mcp …`. With no subcommand (or an arg the server consumes, e.g. --replay) it runs the server. */
+export async function runMcp(rest, io) {
+    const sub = rest[0];
+    if (sub === 'install')
+        return install(rest.slice(1), io);
+    if (sub === 'doctor')
+        return doctor(rest.slice(1), io);
+    if (sub === 'help' || sub === '--help' || sub === '-h') {
+        io.stdout.write(USAGE + '\n');
+        return 0;
+    }
+    // Anything else (no args, or server flags like --replay) → the stdio server, unchanged.
+    const { runStdioServer } = await import('../../mcp/src/index.js');
+    await runStdioServer({ argv: rest });
+    return 0;
+}

package/dist/packages/cli/src/pnl-app.js

@@ -0,0 +1,221 @@
+// dexterm — PNL CARD glue for the app (task-1407). `H` on the token, positions and followed-wallets screens opens a
+// preview of the coin's PnL card built from dexterm's own records:
+//   token      → that coin: LIVE when the signer's ledger has fills for it, else PAPER
+//   positions  → every coin with fills (newest activity first; ← → cycle), LIVE or PAPER as above
+//   follows    → the selected followed wallet's coins (TRACKED), newest first
+// In the preview: x share to X · t copy as text · s save only · a show/hide wallet · z exact size/band ·
+// f 16:9 ⇄ 1:1 · ← → other coin · esc close. Share = save + clipboard image + X compose intent in the user's own
+// browser (pnl-card.ts shareCard); dexterm posts nothing. Nothing here trades, signs or edits a number.
+import { mix } from '../../tui/src/index.js';
+import { computeCard, renderCard, previewCanvas, cardText, paperCardInput, liveCardInput, trackedCardInput, CardError, } from "./pnl-card.js";
+const MARK_VIA = 'dexscreener';
+function coinMeta(state, mint) {
+    const tv = state.live?.token?.view;
+    if (tv && tv.mint === mint)
+        return { symbol: tv.symbol, name: tv.name, image: tv.image };
+    const row = state.screener.rows.find((r) => r.mint === mint);
+    return { symbol: row?.symbol ?? null, name: row?.name ?? null, image: row?.image ?? null };
+}
+function imageOf(state, url) {
+    if (!url || !state.images)
+        return null;
+    const st = state.images.get(url, 2);
+    return st.state === 'ready' ? st.img : null;
+}
+/** The newest price mark for a mint: the positions mark pass, else the open token's market panel ÷ SOL/USD. */
+export function markFor(state, mint) {
+    const pos = state.live?.positions;
+    const p = pos?.markOf(mint) ?? null, at = pos?.markAt(mint) ?? null;
+    if (p !== null && at !== null)
+        return { priceSol: p, at, via: MARK_VIA };
+    const tv = state.live?.token?.view;
+    const solUsd = pos?.solUsd() ?? null;
+    const m = tv?.panels.market;
+    if (tv && tv.mint === mint && tv.price && solUsd && m?.fetchedAt)
+        return { priceSol: tv.price / solUsd, at: m.fetchedAt, via: `${m.via ?? 'market'} ÷ SOL/USD` };
+    return null;
+}
+/** Coins with paper or live fills, newest activity first. */
+function tradedCoins(state) {
+    const live = state.live;
+    if (!live)
+        return [];
+    const last = new Map();
+    const see = (mint, t, symbol) => { const e = last.get(mint); if (!e || t > e.t)
+        last.set(mint, { t, symbol }); };
+    for (const r of live.wallet.trades(1000))
+        see(r.mint, r.t, r.symbol);
+    for (const r of live.livePositions?.records(1000) ?? [])
+        see(r.mint, r.t, r.symbol);
+    return [...last.entries()].sort((a, b) => b[1].t - a[1].t).map(([mint, v]) => ({ mint, symbol: v.symbol }));
+}
+/** Open the preview for the current screen. Returns a reason when there is nothing to card. */
+export function openPnl(state) {
+    if (!state.live)
+        return 'PnL cards are made from recorded fills: run dexterm live (not --fixtures / --replay)';
+    const base = { idx: 0, stats: null, error: null, busy: false, notice: null, opts: { aspect: 'wide', showWallet: false, exactSize: false } };
+    if (state.screen === 'follows') {
+        const follows = state.copy?.follows() ?? [];
+        const f = follows[Math.max(0, Math.min(follows.length - 1, state.copyUi?.selected ?? 0))];
+        if (!f)
+            return 'follow a wallet first (i), then H cards its coins';
+        const seen = new Set();
+        const choices = [];
+        for (const tr of [...(state.copy?.trades(f.addr) ?? [])].sort((a, b) => b.t - a.t)) {
+            if (seen.has(tr.mint) || tr.side === 'transfer')
+                continue;
+            seen.add(tr.mint);
+            choices.push({ mint: tr.mint, symbol: coinMeta(state, tr.mint).symbol ?? tr.mint.slice(0, 4) });
+        }
+        if (!choices.length)
+            return 'no decoded swaps for this wallet yet (r polls now)';
+        state.pnl = { origin: 'follows', choices, wallet: f.addr, ...base };
+    }
+    else if (state.screen === 'token') {
+        const mint = state.live.token?.view?.mint ?? state.token?.mint ?? null;
+        if (!mint)
+            return 'open a coin first';
+        const has = (state.live.livePositions?.records(1, mint).length ?? 0) > 0 || state.live.wallet.trades(1000).some((r) => r.mint === mint);
+        if (!has)
+            return 'no paper or live fills for this coin yet: PnL cards come from your own recorded trades';
+        state.pnl = { origin: 'token', choices: [{ mint, symbol: coinMeta(state, mint).symbol ?? mint.slice(0, 4) }], wallet: null, ...base };
+    }
+    else if (state.screen === 'positions') {
+        const choices = tradedCoins(state);
+        if (!choices.length)
+            return 'no paper or live fills yet: B / S on a token to trade, then H here';
+        state.pnl = { origin: 'positions', choices, wallet: null, ...base };
+    }
+    else
+        return 'PnL cards open from the token, positions (P) or followed wallets (U) screens';
+    state.overlay = 'pnl';
+    return null;
+}
+/** The card input for the current choice, from the right ledger. Async only for a tracked coin that needs decimals / a price. */
+export async function pnlInput(state, ui) {
+    const live = state.live;
+    if (!live)
+        throw new CardError('no live context');
+    const ch = ui.choices[ui.idx];
+    const meta = coinMeta(state, ch.mint);
+    const image = imageOf(state, meta.image);
+    if (ui.origin === 'follows' && ui.wallet && state.copy) {
+        const copy = state.copy;
+        const st = copy.status();
+        const stats = copy.stats(ui.wallet);
+        let mark = markFor(state, ch.mint);
+        let decimals = null;
+        // decimals + a price for a public mint: the same keyless reads the mirror checks make (no wallet, no user data)
+        const m = await copy.mirrorMarket(ch.mint, { symbol: meta.symbol });
+        decimals = m.decimals;
+        const solUsd = live.positions.solUsd();
+        if (!mark && m.priceUsd && m.priceAt && solUsd)
+            mark = { priceSol: m.priceUsd / solUsd, at: m.priceAt, via: `${MARK_VIA} ÷ SOL/USD` };
+        return trackedCardInput(copy.trades(ui.wallet), {
+            wallet: ui.wallet, mint: ch.mint, symbol: meta.symbol ?? m.symbol ?? ch.symbol, name: meta.name, decimals, mark,
+            historyAt: st.lastPollAt, complete: stats.sample.complete, image,
+        });
+    }
+    const liveRows = live.livePositions?.fills(ch.mint) ?? [];
+    if (liveRows.length) {
+        return liveCardInput(liveRows, { mint: ch.mint, symbol: meta.symbol ?? undefined, name: meta.name, wallet: live.linkedWallet?.publicKey ?? null, mark: markFor(state, ch.mint), image });
+    }
+    return paperCardInput(live.wallet.trades(1000), { mint: ch.mint, symbol: meta.symbol ?? undefined, name: meta.name, mark: markFor(state, ch.mint), image });
+}
+/** (Re)build the card for the current choice; on refusal the preview shows the reason instead of a card. */
+export async function loadPnl(state, now = Date.now()) {
+    const ui = state.pnl;
+    if (!ui)
+        return;
+    try {
+        ui.stats = computeCard(await pnlInput(state, ui), now);
+        ui.error = null;
+    }
+    catch (e) {
+        ui.stats = null;
+        ui.error = e instanceof Error ? e.message : String(e);
+    }
+}
+/** Keys while the preview is open. Pure: the loop performs reload / share. */
+export function pnlKey(ui, key) {
+    if (key.name === 'esc' || (key.name === 'char' && key.ch === 'q'))
+        return { kind: 'close' };
+    if (ui.busy)
+        return { kind: 'none' };
+    const ch = key.name === 'char' && !key.ctrl ? key.ch : undefined;
+    if (key.name === 'right' || ch === ']' || ch === 'l') {
+        if (ui.choices.length > 1) {
+            ui.idx = (ui.idx + 1) % ui.choices.length;
+            return { kind: 'reload' };
+        }
+        return { kind: 'none' };
+    }
+    if (key.name === 'left' || ch === '[' || ch === 'h') {
+        if (ui.choices.length > 1) {
+            ui.idx = (ui.idx - 1 + ui.choices.length) % ui.choices.length;
+            return { kind: 'reload' };
+        }
+        return { kind: 'none' };
+    }
+    if (ch === 'a') {
+        ui.opts.showWallet = !ui.opts.showWallet;
+        ui.notice = ui.opts.showWallet ? 'wallet + tx signatures SHOWN on the card' : 'wallet hidden';
+        return { kind: 'none' };
+    }
+    if (ch === 'z') {
+        ui.opts.exactSize = !ui.opts.exactSize;
+        ui.notice = ui.opts.exactSize ? 'exact SOL size SHOWN on the card' : 'size shown as a band';
+        return { kind: 'none' };
+    }
+    if (ch === 'f') {
+        ui.opts.aspect = ui.opts.aspect === 'wide' ? 'square' : 'wide';
+        return { kind: 'none' };
+    }
+    if (!ui.stats)
+        return { kind: 'none' };
+    if (ch === 'x')
+        return { kind: 'share', action: 'x' };
+    if (ch === 't')
+        return { kind: 'share', action: 'text' };
+    if (ch === 's')
+        return { kind: 'share', action: 'save' };
+    return { kind: 'none' };
+}
+const HINTS = 'x share to X · t copy text · s save · a wallet · z size · f 16:9/1:1 · ←→ coin · esc';
+/** The preview overlay: the card itself at cell size when the terminal fits it, else its text; then the keys. */
+export function renderPnlOverlay(c, state) {
+    const ui = state.pnl;
+    if (!ui)
+        return;
+    const t = c.theme;
+    c.noRain(0, 0, c.w, c.h);
+    c.fill(0, 0, c.w, c.h, ' ', { bg: mix(t.bg, '#000000', 0.5) });
+    const ch = ui.choices[ui.idx];
+    const head = `PnL CARD · $${ch?.symbol ?? '?'}${ui.choices.length > 1 ? ` (${ui.idx + 1}/${ui.choices.length})` : ''} · ${ui.opts.aspect === 'wide' ? '16:9' : '1:1'} · wallet ${ui.opts.showWallet ? 'SHOWN' : 'hidden'} · size ${ui.opts.exactSize ? 'EXACT' : 'band'}`;
+    c.text(1, 0, head, { fg: t.text, bg: t.headBg, b: true }, c.w - 2);
+    c.fill(0, c.h - 1, c.w, 1, ' ', { bg: t.headBg });
+    c.text(1, c.h - 1, ui.busy ? 'working… (esc closes)' : (ui.notice ?? HINTS), { fg: ui.notice ? t.warn : t.muted, bg: t.headBg }, c.w - 2);
+    const area = { x: 0, y: 1, w: c.w, h: c.h - 2 };
+    if (!ui.stats) {
+        c.text(2, 3, ui.error ? `no card: ${ui.error}` : 'building the card…', { fg: ui.error ? t.warn : t.muted, bg: c.bg[c.idx(2, 3)] }, c.w - 4);
+        return;
+    }
+    const r = renderCard(ui.stats, ui.opts);
+    const pv = previewCanvas(r);
+    if (pv.w <= area.w && pv.h <= area.h) {
+        const ox = area.x + Math.floor((area.w - pv.w) / 2), oy = area.y + Math.floor((area.h - pv.h) / 2);
+        for (let y = 0; y < pv.h; y++)
+            for (let x = 0; x < pv.w; x++) {
+                const i = pv.idx(x, y), j = c.idx(ox + x, oy + y);
+                c.ch[j] = pv.ch[i];
+                c.fg[j] = pv.fg[i];
+                c.bg[j] = pv.bg[i];
+                c.at[j] = pv.at[i];
+            }
+        return;
+    }
+    // too small for the card grid: the same facts as text (the PNG is still full size)
+    const lines = cardText(ui.stats, ui.opts).trimEnd().split('\n');
+    lines.forEach((l, k) => { if (2 + k < c.h - 1)
+        c.text(2, 2 + k, l, { fg: k === 0 ? t.warn : t.text, bg: c.bg[c.idx(2, 2 + k)] }, c.w - 4); });
+}