dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/cli/src/screens/overlay.js

@@ -0,0 +1,257 @@
+// dexterm — modal overlays (task-1305): the first-run WELCOME card (shown once, then reachable with
+// `?`) and the `?` HELP card that lists every key for the screen underneath it. Both are drawn last,
+// after the effects pass, so the card is crisp and no rain/scanline crosses it. Any key closes the
+// overlay; `?` toggles help.
+import { Canvas, DEFAULT_KEYMAP, mix } from '../../../tui/src/index.js';
+/** Pretty single-key display for a keymap id ('enter' → '⏎', 'pagedown' → 'PgDn', 'ctrl+f' → '^F'). */
+function prettyKey(id) {
+    switch (id) {
+        case 'enter': return '⏎';
+        case 'esc': return 'esc';
+        case 'tab': return 'tab';
+        case 'space': return 'spc';
+        case 'up': return '↑';
+        case 'down': return '↓';
+        case 'left': return '←';
+        case 'right': return '→';
+        case 'home': return 'home';
+        case 'end': return 'end';
+        case 'pageup': return 'PgUp';
+        case 'pagedown': return 'PgDn';
+        case 'backspace': return '⌫';
+    }
+    // task-1358 chords: "ctrl+w s" → "^W s"
+    if (id.includes(' '))
+        return id.split(' ').map(prettyKey).join(' ');
+    if (id.startsWith('ctrl+'))
+        return '^' + id.slice(5).toUpperCase();
+    if (id.startsWith('alt+'))
+        return '⌥' + id.slice(4);
+    return id;
+}
+/** Collapse a binding's key list to a compact display, dropping synonyms that render the same. */
+function keysDisplay(b) {
+    const seen = new Set();
+    const parts = [];
+    for (const k of b.keys) {
+        const p = prettyKey(k);
+        if (seen.has(p))
+            continue;
+        seen.add(p);
+        parts.push(p);
+    }
+    return parts.join('/');
+}
+/**
+ * Extra behaviours handled directly in the interactive loop (not in the keymap), surfaced in help so
+ * the overlay really does list every key. `fixtures` adds the demo-event keys that only fire on
+ * `--fixtures`.
+ */
+export function OVERLAY_HINTS(screen, fixtures) {
+    const rows = [
+        { keys: 'c', label: 'calm mode (effects off)' },
+        { keys: '?', label: 'this help' },
+    ];
+    if (screen === 'analyst')
+        rows.unshift({ keys: 'type', label: 'ask a follow-up · ⏎ send · esc clear/back' });
+    if (fixtures)
+        rows.push({ keys: 'n/u/d/x', label: 'demo: new pair · pump · dump · rug' });
+    return rows;
+}
+/** The help rows for a screen: the keymap bindings that apply there, plus the loop-handled extras.
+ *  A global key shadowed by a screen-specific binding (e.g. `1` = timeframe on the token screen, not
+ *  "screener") is attributed to the screen binding, mirroring Keymap.resolve's precedence. */
+export function helpRows(screen, fixtures, keymap = DEFAULT_KEYMAP, overridden = new Set()) {
+    const bindings = keymap.forScreen(screen);
+    const screenKeys = new Set();
+    for (const b of bindings)
+        if (b.screen === screen)
+            for (const k of b.keys)
+                screenKeys.add(k);
+    const order = [];
+    const rowFor = new Map();
+    for (const b of bindings) {
+        if (!b.label)
+            continue;
+        for (const k of b.keys) {
+            if (!b.screen && screenKeys.has(k))
+                continue; // this global key is overridden on this screen
+            let r = rowFor.get(b.action);
+            if (!r) {
+                r = { label: b.label, keys: [] };
+                rowFor.set(b.action, r);
+                order.push(b.action);
+            }
+            r.keys.push(k);
+        }
+    }
+    const rows = [];
+    for (const action of order) {
+        const r = rowFor.get(action);
+        if (!r.keys.length)
+            continue;
+        // task-1358: a `·` marks a binding the user changed in config.keymap
+        const mark = overridden.has(`|${action}`) || overridden.has(`${screen}|${action}`) ? ' ·' : '';
+        rows.push({ keys: keysDisplay({ keys: r.keys, action }), label: r.label + mark });
+    }
+    return [...rows, ...OVERLAY_HINTS(screen, fixtures)];
+}
+const SCREEN_TITLE = {
+    screener: 'Screener', token: 'Token detail', newpairs: 'New pairs', watchlist: 'Watchlist', analyst: 'Analyst', boot: 'Screener',
+    ticket: 'Paper trade ticket', positions: 'Paper positions',
+    trending: 'Trending in the space', kol: 'KOL lists', bubbles: 'Bubble map', narrative: 'Narrative board',
+    plans: 'Order plans & mandates', follows: 'Followed wallets', rules: 'Rules (alerts + proposals only)',
+};
+/** Draw a centered modal card and return its inner rect, or null when the terminal is too small. */
+function card(c, want, title, caption) {
+    const w = Math.min(want.w, c.w - 2);
+    const h = Math.min(want.h, c.h - 2);
+    if (w < 24 || h < 6)
+        return null;
+    const x = Math.max(0, Math.floor((c.w - w) / 2));
+    const y = Math.max(0, Math.floor((c.h - h) / 2));
+    c.noRain(x, y, w, h);
+    const box = c.box(x, y, w, h, { title, caption, focus: true, bg: c.theme.panelAlt });
+    return box;
+}
+function renderWelcome(c, state) {
+    const t = c.theme;
+    const box = card(c, { w: 72, h: 22 }, 'WELCOME TO DEXTERM', 'press any key to start');
+    if (!box)
+        return;
+    const bg = box.bg;
+    let y = box.y;
+    const line = (s, st = { fg: t.text, bg }) => { c.text(box.x + 2, y, s, st, box.w - 4); y += 1; };
+    const gap = () => { y += 1; };
+    line('A terminal dex screener for Solana — live, keyless, read-only.', { fg: t.muted, bg });
+    line('Browse tokens, open a token for safety & holders, ask a local', { fg: t.muted, bg });
+    line('Claude to scan the trenches. No wallet, no keys, no trades.', { fg: t.muted, bg });
+    gap();
+    c.text(box.x + 2, y, 'GET AROUND', { fg: t.accent, bg, b: true });
+    y += 1;
+    const hints = [
+        ['1-4', 'switch screens (screener · new pairs · watchlist · analyst)'],
+        ['j/k', 'move · ⏎ open a token · esc go back'],
+        ['/', 'filter · s sort · [ ] change the feed'],
+        ['a', 'ask Claude about what you are looking at'],
+        ['?', 'show every key for the current screen, anytime'],
+        ['q', 'quit (your terminal is always restored)'],
+    ];
+    for (const [k, what] of hints) {
+        c.text(box.x + 3, y, k.padEnd(5), { fg: t.borderFocus, bg, b: true });
+        c.text(box.x + 9, y, what, { fg: t.text, bg }, box.w - 11);
+        y += 1;
+    }
+    gap();
+    c.hline(box.x, y, box.w, { fg: mix(t.border, t.warn, 0.4), bg, soft: true });
+    y += 1;
+    line('Safety: dexterm never signs, holds keys, or sends funds. Trading is PAPER (simulated).', { fg: t.warn, bg });
+    line('Nothing here is financial advice — do your own research.', { fg: t.warn, bg });
+}
+function renderHelp(c, state) {
+    const t = c.theme;
+    const screen = state.screen === 'boot' ? 'screener' : state.screen;
+    const fixtures = state.screener.source === 'fixtures';
+    const ov = new Set((state.custom?.keymapResult.overridden ?? []).map((o) => `${o.screen ?? ''}|${o.action}`));
+    const rows = helpRows(screen, fixtures, state.custom?.keymap ?? DEFAULT_KEYMAP, ov);
+    // task-1330: the global key table outgrew a 40-row terminal (T trending, K KOL lists); when one column
+    // cannot show every row the card goes two columns wide (110) so the last rows (the fixture demo keys) are never cut.
+    const maxRows = c.h - 2 - 7;
+    const columns = rows.length > maxRows && c.w >= 112 ? 2 : 1;
+    const perCol = columns === 2 ? Math.ceil(rows.length / 2) : rows.length;
+    const want = { w: columns === 2 ? 110 : 64, h: perCol + 7 };
+    const box = card(c, want, `KEYS — ${SCREEN_TITLE[screen]}`, 'esc or ? to close');
+    if (!box)
+        return;
+    const bg = box.bg;
+    const keyW = Math.min(12, Math.max(...rows.map((r) => r.keys.length)) + 1);
+    const colW = Math.floor((box.w - 2) / columns);
+    rows.forEach((r, i) => {
+        const col = Math.floor(i / perCol);
+        const y = box.y + (i % perCol);
+        if (y >= box.y + box.h - 2)
+            return;
+        const x = box.x + 2 + col * colW;
+        c.text(x, y, r.keys.padEnd(keyW), { fg: t.borderFocus, bg, b: true });
+        c.text(x + keyW + 1, y, r.label, { fg: t.text, bg }, colW - keyW - 3);
+    });
+    const fy = box.y + box.h - 1;
+    c.hline(box.x, fy - 1, box.w, { fg: mix(t.border, t.warn, 0.4), bg, soft: true });
+    c.text(box.x + 2, fy, 'read-only · no keys · no trades · not financial advice', { fg: t.warn, bg, i: true }, box.w - 4);
+}
+/** task-1358: the WORKSPACES card — 1-9 pick, j/k move + ⏎, esc close. Built-ins first, then ~/.dexterm/workspaces/*.json. */
+function renderWorkspaces(c, state) {
+    const t = c.theme;
+    const ui = state.custom;
+    const items = ui?.workspaces ?? [];
+    const box = card(c, { w: 76, h: Math.min(c.h - 2, items.length + 7) }, 'WORKSPACES', '1-9 pick · j/k + ⏎ · ^W s save current · esc close');
+    if (!box)
+        return;
+    const bg = box.bg;
+    if (!items.length) {
+        c.text(box.x + 2, box.y, 'no workspaces loaded (config not read on this run)', { fg: t.muted, bg }, box.w - 4);
+        return;
+    }
+    const cursor = Math.max(0, Math.min(items.length - 1, ui?.listCursor ?? 0));
+    let slot = 0;
+    items.forEach((w, i) => {
+        const y = box.y + i;
+        if (y >= box.y + box.h - 2)
+            return;
+        const active = ui?.active === w.name;
+        const picked = i === cursor;
+        const n = w.error ? ' ' : slot < 9 ? String(++slot) : ' ';
+        c.text(box.x + 2, y, `${picked ? '›' : ' '} ${n} `, { fg: picked ? t.accent : t.dim, bg, b: picked });
+        c.text(box.x + 7, y, w.name.padEnd(22), { fg: w.error ? t.down : active ? t.borderFocus : t.text, bg, b: active });
+        const what = w.error ? `⚠ ${w.error}` : `${w.builtin ? 'built-in' : 'file'} · ${w.workspace.description ?? (w.workspace.start ? `starts on ${w.workspace.start}` : '')}${w.workspace.popups?.length ? ` · ${w.workspace.popups.length} popup${w.workspace.popups.length > 1 ? 's' : ''}` : ''}`;
+        c.text(box.x + 30, y, what, { fg: w.error ? t.down : t.muted, bg }, box.w - 32);
+    });
+    const fy = box.y + box.h - 1;
+    c.hline(box.x, fy - 1, box.w, { fg: mix(t.border, t.warn, 0.4), bg, soft: true });
+    c.text(box.x + 2, fy, `active: ${ui?.active ?? 'default'} · a workspace only navigates, re-themes and opens read-only popups`, { fg: t.warn, bg, i: true }, box.w - 4);
+}
+/**
+ * task-1388: the GO-TO prompt — a one-line "paste a contract address (or a dexscreener / pump.fun / solscan
+ * URL) to open any coin" input, opened with `g`. Read-only: ⏎ opens the coin's live token screen, esc cancels.
+ * Drawn as a centered card so it works the same on every screen that offers it.
+ */
+export function renderGotoPrompt(c, state) {
+    const g = state.goto;
+    if (!g)
+        return;
+    const t = c.theme;
+    const box = card(c, { w: 68, h: 7 }, 'GO TO COIN', '⏎ open · esc cancel');
+    if (!box)
+        return;
+    const bg = box.bg;
+    c.text(box.x + 2, box.y, 'paste or type a contract address (or a coin URL):', { fg: t.muted, bg }, box.w - 4);
+    const shown = g.input.length > box.w - 6 ? '…' + g.input.slice(-(box.w - 7)) : g.input;
+    c.text(box.x + 2, box.y + 2, '› ', { fg: t.accent, bg, b: true });
+    c.text(box.x + 4, box.y + 2, shown, { fg: t.text, bg, b: true }, box.w - 7);
+    c.text(box.x + 4 + shown.length, box.y + 2, '▏', { fg: t.borderFocus, bg });
+    const fy = box.y + box.h - 1;
+    c.hline(box.x, fy - 1, box.w, { fg: mix(t.border, t.warn, 0.4), bg, soft: true });
+    c.text(box.x + 2, fy, g.notice ?? 'read-only — opens the token screen, never trades or signs', { fg: g.notice ? t.down : t.warn, bg, i: true }, box.w - 4);
+}
+/** Draw the active overlay (welcome or help). Called by renderFrame after the effects pass. */
+export function renderOverlay(c, state) {
+    if (state.overlay === 'welcome')
+        renderWelcome(c, state);
+    else if (state.overlay === 'help')
+        renderHelp(c, state);
+    else if (state.overlay === 'workspaces')
+        renderWorkspaces(c, state);
+    else if (state.overlay === 'links' && state.linkMenu) {
+        const menu = state.linkMenu;
+        const box = card(c, { w: 100, h: Math.min(24, menu.items.length * 2 + 6) }, 'ADVERTISED LINKS (UNTRUSTED)', 'j/k select · enter open · esc close');
+        if (!box)
+            return;
+        const count = Math.max(1, Math.floor((box.h - 2) / 2));
+        const start = Math.max(0, menu.selected - count + 1);
+        menu.items.slice(start, start + count).forEach((item, i) => {
+            const selected = start + i === menu.selected;
+            c.text(box.x + 1, box.y + i * 2, `${selected ? '›' : ' '} ${item.kind}`, { fg: selected ? c.theme.accent : c.theme.muted, bg: box.bg }, box.w - 2);
+            c.text(box.x + 3, box.y + i * 2 + 1, item.url.replace(/[\p{Cc}\p{Cf}]/gu, ''), { fg: c.theme.text, bg: box.bg }, box.w - 4);
+        });
+    }
+}

package/dist/packages/cli/src/screens/plans.js

@@ -0,0 +1,126 @@
+// dexterm — ORDER PLANS & STANDING MANDATES screen (key O, task-1355; SPEC §6.13). Lists the conditional
+// order plans and standing mandates held in the signer trust domain, and lets the user arm (hold-to-confirm,
+// physical keypress only), cancel/revoke, and panic. The screen NEVER signs, holds a key, raises a cap, or
+// arms by anything but a captured physical keypress — voice and agents can only PROPOSE, never reach here.
+// Default runs are PAPER (no key, no wallet, no mainnet); the on-disk journal is the audit log + recovery.
+import { Canvas, header, footer, breakpoint, fmtUsd } from '../../../tui/src/index.js';
+import { headerModel } from "../state.js";
+import { planStatusLabel } from '../../../data/src/trade/plans/index.js';
+import { planLevels, priceModeOf } from "../display.js";
+function fmtTtl(expiresAt, now) {
+    const ms = expiresAt - now;
+    if (ms <= 0)
+        return 'expired';
+    const h = Math.floor(ms / 3600_000);
+    const m = Math.floor((ms % 3600_000) / 60_000);
+    return h > 0 ? `${h}h${m}m` : `${m}m`;
+}
+export function renderPlans(c, state) {
+    const t = c.theme;
+    const bp = breakpoint(c.w);
+    header(c, headerModel(state));
+    const ui = state.plansUi ?? null;
+    const svc = state.plansSvc ?? null;
+    const tab = ui?.tab ?? 'plans';
+    const plans = svc ? svc.listPlans() : [];
+    const mandates = svc ? svc.listMandates() : [];
+    const top = 2, bottom = c.h - 1;
+    const risk = svc ? svc.riskStatus() : { gateOff: false, acceptedAt: null, expiresAt: null, active: false };
+    const gateLabel = risk.active ? 'HANDS-FREE' : 'GATE ON';
+    // task-1363: the fire path. Anything not provably paper renders LIVE (fail-safe).
+    const liveFire = svc ? svc.mode() === 'live' : false;
+    const fireLabel = liveFire ? '◉ LIVE · DEVNET · FAST WALLET' : 'PAPER';
+    const title = `ORDER PLANS & MANDATES · ${tab === 'plans' ? `${plans.length} plans` : `${mandates.length} mandates`} · ${fireLabel} · ${gateLabel}`;
+    const caption = bp === 'compact' ? undefined : 'voice/agents PROPOSE only · arming needs a physical keypress hold · caps are signer-side · panic revokes all';
+    const box = c.box(0, top, c.w, bottom - top, { title, caption, focus: true });
+    const bg = box.bg;
+    const now = state.now.getTime();
+    // Tab strip
+    let cy = box.y;
+    const tabPlans = `PLANS (${plans.length})`;
+    const tabMand = `MANDATES (${mandates.length})`;
+    c.text(box.x + 1, cy, tabPlans, { fg: tab === 'plans' ? t.accent : t.dim, bg, b: tab === 'plans' });
+    c.text(box.x + 2 + tabPlans.length + 2, cy, tabMand, { fg: tab === 'mandates' ? t.accent : t.dim, bg, b: tab === 'mandates' });
+    cy += 1;
+    c.hline(box.x, cy, box.w, { fg: t.border, bg });
+    cy += 1;
+    const rows = tab === 'plans' ? plans : mandates;
+    if (!rows.length) {
+        c.textC(box.x, box.y + 3, box.w, tab === 'plans' ? 'no order plans — propose one with `dexterm plan propose`, or by voice ("buy this if it dips to 300k")' : 'no standing mandates — draft one with `dexterm mandate draft`', { fg: t.muted, bg, i: true });
+        c.textC(box.x, box.y + 5, box.w, 'a proposal is INERT until you arm it here with a physical keypress hold; nothing arms by voice or agent', { fg: t.dim, bg });
+        footer(c, [['tab', 'plans/mandates'], ['esc', 'back'], ['q', 'quit']], t.name);
+        return;
+    }
+    const sel = Math.max(0, Math.min(rows.length - 1, ui?.selected ?? 0));
+    const scroll = Math.max(0, sel - (box.h - 6));
+    for (let i = scroll; i < rows.length; i++) {
+        if (cy >= box.y + box.h - 2)
+            break;
+        const selected = i === sel;
+        const rb = selected ? t.selBg : bg;
+        c.fill(box.x, cy, box.w, 1, ' ', { bg: rb });
+        if (selected)
+            c.put(box.x, cy, '▎', { fg: t.accent, bg: rb, soft: true });
+        if (tab === 'plans') {
+            const r = rows[i];
+            // status colour: armed=up, proposed=muted, terminal/refused=down
+            const armed = r.status === 'armed' || r.status.startsWith('filled');
+            const dead = r.status === 'cancelled' || r.status === 'failed' || r.status === 'expired' || r.status === 'done';
+            const sfg = r.paused ? t.down : armed ? t.up : dead ? t.dim : t.muted;
+            c.text(box.x + 1, cy, r.id, { fg: selected ? t.borderFocus : t.text, bg: rb }, 20);
+            c.text(box.x + 22, cy, planStatusLabel(r), { fg: sfg, bg: rb }, box.w - 24);
+        }
+        else {
+            const r = rows[i];
+            const armed = r.status === 'armed';
+            const sfg = armed ? t.up : r.status === 'revoked' || r.status === 'expired' ? t.dim : t.muted;
+            c.text(box.x + 1, cy, r.id, { fg: selected ? t.borderFocus : t.text, bg: rb }, 22);
+            c.text(box.x + 24, cy, r.status.toUpperCase(), { fg: sfg, bg: rb }, 8);
+            const detail = `${fmtUsd(r.totalUsd)} tot · ${fmtUsd(r.reservedUsd)} rsv · ${fmtUsd(r.spentUsd)} spent · ${r.maxTier} · ${fmtTtl(r.expiresAt, now)}`;
+            c.text(box.x + 33, cy, detail, { fg: t.muted, bg: rb }, box.w - 35);
+        }
+        cy += 1;
+    }
+    // The hold-to-arm modal (captured by the loop; this just paints the prompt).
+    if (ui?.arming) {
+        const a = ui.arming;
+        const mw = Math.min(box.w - 4, 72), mh = 7;
+        const mx = box.x + Math.floor((box.w - mw) / 2), my = box.y + Math.floor((box.h - mh) / 2);
+        const mbox = c.box(mx, my, mw, mh, { title: '⚠ ARM — physical keypress', focus: true });
+        const label = a.kind === 'plan' ? `Arm plan ${a.id} into ${a.mandateId}?` : `Arm standing mandate ${a.id}?`;
+        c.textC(mbox.x, mbox.y, mbox.w, label, { fg: t.text, bg: mbox.bg, b: true });
+        c.textC(mbox.x, mbox.y + 1, mbox.w, a.kind === 'mandate' ? 'armed plans can fire at machine speed from the capped fast wallet' : 'the signer re-checks caps on every fill; voice/agents can never arm', { fg: t.muted, bg: mbox.bg });
+        c.textC(mbox.x, mbox.y + 3, mbox.w, 'Hold and release [enter] or [y] to confirm · [esc] cancels · a pipe/agent cannot arm', { fg: t.accent, bg: mbox.bg });
+    }
+    // The "less safe" hands-free opt-in modal (Tier 4): keypress-only, journaled, auto-expires 24h, reversible.
+    if (ui?.riskModal) {
+        const mw = Math.min(box.w - 4, 74), mh = 8;
+        const mx = box.x + Math.floor((box.w - mw) / 2), my = box.y + Math.floor((box.h - mh) / 2);
+        const mbox = c.box(mx, my, mw, mh, { title: '⚠ LESS SAFE — turn OFF the keypress gate', focus: true });
+        c.textC(mbox.x, mbox.y, mbox.w, risk.active ? 'Hands-free is ON. Restore the keypress gate?' : 'Allow hands-free (spoken) confirmation without a keypress?', { fg: t.text, bg: mbox.bg, b: true });
+        c.textC(mbox.x, mbox.y + 2, mbox.w, risk.active ? 'armed plans could then confirm by voice alone — restoring the gate is always safe' : 'armed plans could then fire from a spoken phrase, with NO physical keypress', { fg: risk.active ? t.muted : t.down, bg: mbox.bg });
+        c.textC(mbox.x, mbox.y + 3, mbox.w, 'signer caps, allow-lists and panic still apply · this auto-expires in 24h · logged to the journal', { fg: t.muted, bg: mbox.bg });
+        c.textC(mbox.x, mbox.y + 5, mbox.w, risk.active ? 'Hold+release [enter]/[y] to restore the gate · [esc] cancels' : 'Hold+release [enter]/[y] to accept (keypress only) · [esc] cancels · a pipe/agent cannot', { fg: t.accent, bg: mbox.bg });
+    }
+    // task-1363: the FIRE PATH modal (paper ⇄ live). Switched by a captured keypress in the loop; this paints the prompt.
+    if (ui?.liveModal) {
+        const mw = Math.min(box.w - 4, 78), mh = 9;
+        const mx = box.x + Math.floor((box.w - mw) / 2), my = box.y + Math.floor((box.h - mh) / 2);
+        const mbox = c.box(mx, my, mw, mh, { title: liveFire ? 'FIRE PATH — back to PAPER' : '⚠ FIRE PATH — go LIVE on DEVNET', focus: true });
+        c.textC(mbox.x, mbox.y, mbox.w, liveFire ? 'Switch plan fills back to the paper executor?' : 'Fire armed plans through the SIGNER from the capped fast wallet (devnet)?', { fg: t.text, bg: mbox.bg, b: true });
+        c.textC(mbox.x, mbox.y + 2, mbox.w, liveFire ? 'fills are then simulated again at the tick price; nothing on chain' : 'real devnet lamports move (fees of a wrap-and-unwrap sized to the plan); the token leg is modelled — Jupiter has no devnet', { fg: liveFire ? t.muted : t.down, bg: mbox.bg });
+        c.textC(mbox.x, mbox.y + 3, mbox.w, 'the signer re-checks policy, simulation, USD per-trade/daily caps and the 0.05 SOL per-fill ceiling on every fill', { fg: t.muted, bg: mbox.bg });
+        c.textC(mbox.x, mbox.y + 4, mbox.w, 'needs: a live run with the signer, `dexterm wallet fast create`, no armed/filled plans · never mainnet · journaled', { fg: t.muted, bg: mbox.bg });
+        c.textC(mbox.x, mbox.y + 6, mbox.w, 'Hold+release [enter]/[y] to switch (keypress only) · [esc] cancels · a pipe/agent/voice cannot', { fg: t.accent, bg: mbox.bg });
+    }
+    // task-1366: the selected plan's levels with BOTH market cap and price (display only; mc first in mcap mode)
+    if (tab === 'plans' && svc && !ui?.notice) {
+        const r = rows[sel];
+        const plan = r ? svc.engine.plan(r.id) : null;
+        if (plan)
+            c.text(box.x + 1, box.y + box.h - 1, planLevels(plan, priceModeOf(state)), { fg: t.muted, bg }, box.w - 2);
+    }
+    if (ui?.notice)
+        c.text(box.x + 1, box.y + box.h - 1, ui.notice, { fg: t.accent, bg });
+    footer(c, [['↑↓', 'move'], ['tab', 'plans/mandates'], ['a', 'arm (hold)'], tab === 'plans' ? ['c', 'cancel'] : ['r', 'revoke'], ['L', liveFire ? 'paper' : 'live (devnet)'], ['G', risk.active ? 'gate on' : 'hands-free'], ['!', 'PANIC'], ['esc', 'back'], ['q', 'quit']], t.name);
+}

package/dist/packages/cli/src/screens/positions.js

@@ -0,0 +1,176 @@
+// dexterm — PAPER positions screen (task-1310 T0, SPEC §6.1 "book"). The simulated wallet: balance,
+// equity, open positions with live PnL (marked from the keyless price feed) and the trade history.
+// Labelled PAPER on every frame; nothing here signs, holds a key or sends anything.
+import { Canvas, header, footer, breakpoint, mix, isCalm, fmtPriceBare, fmtMcap, fmtNum, fmtPct, fmtAgeSec, shortAddr, } from '../../../tui/src/index.js';
+import { lamportsToSol, rawToTokens, positionPnl } from '../../../data/src/index.js';
+import { headerModel } from "../state.js";
+import { priceModeOf, supplyRatio, FALLBACK_MARK } from "../display.js";
+export function sol(n, digits = 4) {
+    return `${n >= 0 ? '' : '-'}${Math.abs(n).toFixed(digits)}`;
+}
+export function signedSol(n, digits = 4) {
+    return `${n >= 0 ? '+' : '-'}${Math.abs(n).toFixed(digits)}`;
+}
+/**
+ * USD for position-sized amounts (task-1323): cents below $1K (`$192.50`), compact above (`$12.3K`).
+ * `fmtUsd` rounds small values to whole dollars, which hides a paper PnL of a few dollars.
+ */
+export function fmtUsdFine(n) {
+    const a = Math.abs(n);
+    const sign = n < 0 ? '-' : '';
+    if (a >= 1e9)
+        return `${sign}$${(a / 1e9).toFixed(2)}B`;
+    if (a >= 1e6)
+        return `${sign}$${(a / 1e6).toFixed(2)}M`;
+    if (a >= 1e3)
+        return `${sign}$${(a / 1e3).toFixed(a >= 1e4 ? 1 : 2)}K`;
+    return `${sign}$${a.toFixed(2)}`;
+}
+/** Signed USD: `+$42.00` / `-$3.10` (zero reads `+$0.00`). */
+export function signedUsd(n) {
+    return `${n >= 0 ? '+' : '-'}${fmtUsdFine(Math.abs(n))}`;
+}
+/** Signed percent of a fraction: 0.28 → `+28.0%`, -0.082 → `-8.2%`. */
+export function signedPctOf(frac, digits = 1) {
+    const p = frac * 100;
+    const a = Math.abs(p);
+    return `${p >= 0 ? '+' : '-'}${a.toFixed(a >= 1000 ? 0 : digits)}%`;
+}
+export function renderPositions(c, state) {
+    const t = c.theme;
+    header(c, headerModel(state));
+    const bp = breakpoint(c.w);
+    const v = (state.live ? state.live.positions.view() : state.positions) ?? null;
+    const top = 2;
+    c.fill(0, top, c.w, 1, ' ', { bg: mix(t.bg, t.warn, 0.16) });
+    c.text(2, top, ' ◈ PAPER PORTFOLIO — simulated wallet · no real funds, keys or signing ', { fg: t.warn, bg: mix(t.bg, t.warn, 0.16), b: true });
+    const linked = state.live?.linkedWallet;
+    if (linked)
+        c.textR(2, top, c.w - 3, `linked: ${linked.publicKey.slice(0, 4)}…${linked.publicKey.slice(-4)} `, { fg: t.muted, bg: mix(t.bg, t.warn, 0.16) });
+    c.noRain(0, top, c.w, 1);
+    if (!v) {
+        c.text(2, 4, 'No paper wallet in this mode. Run live to paper-trade (B/S on a token).', { fg: t.muted, bg: t.bg });
+        footer(c, [['esc', 'back'], ['q', 'quit']], t.name, isCalm(state.vfx));
+        return;
+    }
+    // summary strip
+    let y = 4;
+    const totalColor = v.totalPct === null ? t.muted : v.totalPct >= 0 ? t.up : t.down;
+    let x = c.text(2, y, 'Equity', { fg: t.dim, bg: t.bg });
+    x = c.text(x + 1, y, `${sol(v.equitySol)} SOL`, { fg: t.text, bg: t.bg, b: true });
+    x = c.text(x + 3, y, 'Cash', { fg: t.dim, bg: t.bg });
+    x = c.text(x + 1, y, `${sol(v.balanceSol)} SOL`, { fg: t.muted, bg: t.bg });
+    x = c.text(x + 3, y, 'Start', { fg: t.dim, bg: t.bg });
+    x = c.text(x + 1, y, `${sol(v.startSol)} SOL`, { fg: t.muted, bg: t.bg });
+    x = c.text(x + 3, y, 'Total PnL', { fg: t.dim, bg: t.bg });
+    x = c.text(x + 1, y, `${signedSol(v.equitySol - v.startSol)} SOL${v.totalPct !== null ? ` (${fmtPct(v.totalPct * 100)})` : ''}`, { fg: totalColor, bg: t.bg, b: true });
+    if (v.solPriceUsd)
+        c.textR(2, y, c.w - 3, `SOL $${v.solPriceUsd.toFixed(2)}${v.loading ? ' · marking…' : ''}`, { fg: t.dim, bg: t.bg });
+    y += 1;
+    c.text(2, y, `realized ${signedSol(v.totalRealizedSol)} · unrealized ${signedSol(v.totalUnrealizedSol)} SOL`, { fg: t.dim, bg: t.bg });
+    y += 2;
+    // positions table
+    const bottom = c.h - 1;
+    const half = Math.max(8, Math.floor((bottom - y) * 0.5));
+    // task-1366: mcap mode reads AVG / PRICE as market cap = SOL price × SOL/USD × the token's CURRENT supply (from the
+    // screener rows); a token without a supply (or no SOL/USD yet) keeps its SOL price, marked ᵖ. PnL stays SOL.
+    const mode = priceModeOf(state);
+    const supplyOf = (mint) => { const row = state.screener.rows.find((x) => x.mint === mint); return row ? supplyRatio(row.price, row.mcap) : null; };
+    const mcCell = (pSol, mint) => {
+        if (pSol === null)
+            return '—';
+        if (mode !== 'mcap')
+            return fmtPriceBare(pSol);
+        const s = supplyOf(mint);
+        return s !== null && v.solPriceUsd ? fmtMcap(pSol * v.solPriceUsd * s) : fmtPriceBare(pSol) + FALLBACK_MARK;
+    };
+    const pb = c.box(0, y, c.w, half, { title: 'POSITIONS', caption: mode === 'mcap' ? 'marked from keyless price feed · mcap at current supply' : 'marked from keyless price feed' });
+    let py = pb.y;
+    const cols = bp === 'compact'
+        ? [['TOKEN', 16], ['AMOUNT', 16], ['VALUE', 14], ['uPnL', 16]]
+        : [['TOKEN', 20], ['AMOUNT', 18], [mode === 'mcap' ? 'AVG MC' : 'AVG', 14], [mode === 'mcap' ? 'MCAP' : 'PRICE', 14], ['VALUE', 14], ['uPnL SOL', 18], ['REALIZED', 14]];
+    let hx = pb.x + 1;
+    for (const [label, wdt] of cols) {
+        c.text(hx, py, label, { fg: t.dim, bg: pb.bg }, wdt);
+        hx += wdt;
+    }
+    py += 1;
+    const open = v.rows.filter((r) => r.tokens > 0);
+    if (open.length === 0) {
+        c.text(pb.x + 1, py, 'no open positions — B paper-buy on a token', { fg: t.dim, bg: pb.bg });
+    }
+    for (const r of open) {
+        if (py >= pb.y + pb.h - 1)
+            break;
+        const uColor = r.unrealizedSol === null ? t.muted : r.unrealizedSol >= 0 ? t.up : t.down;
+        let cx = pb.x + 1;
+        cx = c.text(cx, py, `$${r.symbol}`, { fg: t.text, bg: pb.bg, b: true }, cols[0][1]);
+        cx = pb.x + 1 + cols[0][1];
+        c.text(cx, py, fmtNum(r.tokens), { fg: t.muted, bg: pb.bg }, cols[1][1] - 1);
+        cx += cols[1][1];
+        if (!bp || bp !== 'compact') {
+            c.text(cx, py, mcCell(r.avgEntrySol, r.mint), { fg: t.dim, bg: pb.bg }, cols[2][1] - 1);
+            cx += cols[2][1];
+            c.text(cx, py, mcCell(r.priceSol, r.mint), { fg: t.muted, bg: pb.bg }, cols[3][1] - 1);
+            cx += cols[3][1];
+            c.text(cx, py, r.valueSol !== null ? sol(r.valueSol) : '—', { fg: t.text, bg: pb.bg }, cols[4][1] - 1);
+            cx += cols[4][1];
+            c.text(cx, py, r.unrealizedSol !== null ? `${signedSol(r.unrealizedSol)}${r.unrealizedPct !== null ? ` ${fmtPct(r.unrealizedPct * 100)}` : ''}` : '—', { fg: uColor, bg: pb.bg, b: true }, cols[5][1] - 1);
+            cx += cols[5][1];
+            c.text(cx, py, signedSol(r.realizedSol), { fg: r.realizedSol >= 0 ? t.muted : t.down, bg: pb.bg }, cols[6][1] - 1);
+        }
+        else {
+            c.text(cx, py, r.valueSol !== null ? sol(r.valueSol) : '—', { fg: t.text, bg: pb.bg }, cols[2][1] - 1);
+            cx += cols[2][1];
+            c.text(cx, py, r.unrealizedSol !== null ? signedSol(r.unrealizedSol) : '—', { fg: uColor, bg: pb.bg, b: true }, cols[3][1] - 1);
+        }
+        py += 1;
+    }
+    // task-1328: LIVE positions (the signer's ledger file, read-only), only when there are any.
+    const liveSrc = state.live?.livePositions ?? null;
+    const livePos = liveSrc ? liveSrc.positions().filter((p) => p.tokensRaw > 0n) : [];
+    y += half;
+    if (livePos.length > 0) {
+        const lh = Math.min(livePos.length + 3, Math.max(5, Math.floor((bottom - y) * 0.4)));
+        const lb = c.box(0, y, c.w, lh, { title: '◉ LIVE POSITIONS', titleFg: t.up, caption: 'confirmed on-chain fills · signer ledger' });
+        let ly = lb.y;
+        for (const p of livePos) {
+            if (ly >= lb.y + lb.h)
+                break;
+            const mark = liveSrc?.held(p.mint)?.markSol ?? null;
+            const pnl = positionPnl(p, mark);
+            let cx = c.text(lb.x + 1, ly, `$${p.symbol}`, { fg: t.text, bg: lb.bg, b: true });
+            cx = c.text(cx + 2, ly, fmtNum(rawToTokens(p.tokensRaw, p.decimals)), { fg: t.muted, bg: lb.bg });
+            cx = c.text(cx + 2, ly, `cost ${sol(pnl.costSol)} SOL`, { fg: t.dim, bg: lb.bg });
+            if (pnl.avgEntrySol !== null)
+                cx = c.text(cx + 2, ly, `avg ${fmtPriceBare(pnl.avgEntrySol)}`, { fg: t.dim, bg: lb.bg });
+            if (pnl.unrealizedSol !== null)
+                c.text(cx + 2, ly, `uPnL ${signedSol(pnl.unrealizedSol)} SOL${pnl.unrealizedPct !== null ? ` ${fmtPct(pnl.unrealizedPct * 100)}` : ''}`, { fg: pnl.unrealizedSol >= 0 ? t.up : t.down, bg: lb.bg, b: true });
+            c.textR(lb.x + 1, ly, lb.w - 2, `${shortAddr(p.mint, 4)} · LIVE`, { fg: t.up, bg: lb.bg });
+            ly += 1;
+        }
+        y += lh;
+    }
+    // history
+    const hb = c.box(0, y, c.w, bottom - y, { title: 'TRADE HISTORY', caption: `${v.history.length} paper fills${liveSrc ? ` · ${liveSrc.records(50).length} live` : ''}` });
+    let yy = hb.y;
+    for (const h of v.history) {
+        if (yy >= hb.y + hb.h)
+            break;
+        const sideColor = h.side === 'buy' ? t.up : t.down;
+        const gotTokens = h.side === 'buy' ? rawToTokens(h.tokenDelta, h.decimals) : rawToTokens(-h.tokenDelta, h.decimals);
+        const solAmt = lamportsToSol(h.solDelta);
+        let cx = c.text(hb.x + 1, yy, fmtAgeSec(Math.max(0, Math.round((state.now.getTime() - h.t) / 1000))).padStart(4), { fg: t.dim, bg: hb.bg });
+        cx = c.text(cx + 1, yy, h.side === 'buy' ? '▲ BUY ' : '▼ SELL', { fg: sideColor, bg: hb.bg, b: true });
+        cx = c.text(cx + 1, yy, `$${h.symbol}`, { fg: t.text, bg: hb.bg, b: true });
+        cx = c.text(cx + 1, yy, `${fmtNum(gotTokens)} @ ${fmtPriceBare(h.priceSol)} SOL`, { fg: t.muted, bg: hb.bg });
+        cx = c.text(cx + 2, yy, `${signedSol(solAmt)} SOL`, { fg: solAmt >= 0 ? t.up : t.muted, bg: hb.bg });
+        if (h.side === 'sell')
+            c.text(cx + 2, yy, `pnl ${signedSol(lamportsToSol(h.realizedLamports))}`, { fg: h.realizedLamports >= 0n ? t.up : t.down, bg: hb.bg });
+        c.textR(hb.x + 1, yy, hb.w - 2, `${shortAddr(h.mint, 4)} · PAPER`, { fg: t.dim, bg: hb.bg });
+        yy += 1;
+    }
+    if (v.history.length === 0)
+        c.text(hb.x + 1, hb.y, 'no paper trades yet', { fg: t.dim, bg: hb.bg });
+    footer(c, [['esc', 'back'], ['r', 'refresh'], ['1-4', 'screens'], ['q', 'quit']], t.name, isCalm(state.vfx));
+}