dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/cli/src/state.js

@@ -0,0 +1,463 @@
+// dexterm — app state consumed by the screens. Screens are pure render(canvas, state) functions;
+// renderFrame() draws the screen, the toast, then runs the effects post-pass (VISUAL-V2 §3).
+import { Canvas, THEMES, applyFx, toast, makeVfx, setSources, marketActivity, candleActivity, isCalm, } from '../../tui/src/index.js';
+import { makeFixtures } from "./fixtures.js";
+import { fromFixture } from "./screener/rows.js";
+import { makeScreenerState, screenerView } from "./screener/view.js";
+import { renderScreener } from "./screens/screener.js";
+import { renderToken } from "./screens/token.js";
+import { renderNewPairs } from "./screens/newpairs.js";
+import { renderWatchlist } from "./screens/watchlist.js";
+import { renderAnalyst } from "./screens/analyst.js";
+import { renderBoot } from "./screens/boot.js";
+import { renderOverlay, renderGotoPrompt } from "./screens/overlay.js";
+import { renderTicket } from "./screens/ticket.js";
+import { renderPositions } from "./screens/positions.js";
+import { renderTrending } from "./screens/trending.js";
+import { renderKol } from "./screens/kol.js";
+import { renderBubbles } from "./screens/bubbles.js";
+import { renderNarrative } from "./screens/narrative.js";
+import { renderPlans } from "./screens/plans.js";
+import { renderFollows } from "./screens/follows.js";
+import { renderRules } from "./screens/rules.js";
+import { CopyLive } from "./live/copy.js";
+import { CopyAuto, defaultCopyJournalPath, leaderSoldSince } from '../../data/src/trade/copy/index.js';
+import { computeBoard, loadDefaultLexicon, recentNarrativeRows } from '../../packs/src/index.js';
+import { PlanService, defaultPlansJournalPath } from '../../data/src/trade/plans/index.js';
+import { openTicket } from "./trade.js";
+import { computeFill } from '../../data/src/index.js';
+import { renderScanTicker, scanIndicator } from "./scan/ui.js";
+import { renderVoiceHud } from "./voice-hud.js";
+import { workspaceBadge } from "./custom.js";
+/** Map key for the Analyst-tab's own conversation (not tied to a single token). */
+export const ANALYST_TAB_KEY = '__analyst_tab__';
+/**
+ * The conversation key for whatever is on screen: the token's mint on the token screen, the shared
+ * Analyst-tab key on the analyst screen, else null (no chat surface). Drives `state.analystByMint`.
+ */
+export function analystKey(s) {
+    if (s.screen === 'token')
+        return s.live?.token?.view.mint ?? s.token?.mint ?? null;
+    if (s.screen === 'analyst')
+        return ANALYST_TAB_KEY;
+    return null;
+}
+/** Point `state.analyst` at the saved conversation for the current screen (task-1311, QA M5). */
+export function syncAnalyst(s) {
+    const k = analystKey(s);
+    if (!k || !s.analystByMint)
+        return;
+    s.analyst = s.analystByMint.get(k) ?? null;
+}
+/**
+ * Keep the New pairs highlight on the coin the cursor picked, not on a row index (task-1311, QA M8):
+ * remap `state.selected` to the current position of `state.selectedMint`. Called after the list
+ * changes. When the pinned mint has scrolled off, the selection is clamped in place.
+ */
+export function pinNewpairsSelection(s) {
+    const live = s.live;
+    if (!live || s.screen !== 'newpairs' || !s.selectedMint)
+        return;
+    const list = live.newpairs.list();
+    const i = list.findIndex((r) => r.mint === s.selectedMint);
+    if (i >= 0)
+        s.selected = i;
+    else if (list.length)
+        s.selected = Math.max(0, Math.min(list.length - 1, s.selected || 0));
+}
+/** Map the screener's visible rows to narrative rows (the fallback source when there is no recorder DB). */
+export function narrativeRowsFromScreener(rows) {
+    return rows.filter((r) => r.mint && !r.skeleton).map((r) => ({
+        mint: r.mint, symbol: r.symbol, name: r.name,
+        vol_h1: r.vol1h, vol_h24: r.vol24, chg_h1: r.chg.h1, chg_h24: r.chg.h24,
+        holder_count: r.holders, liquidity_usd: r.liq, mcap: r.mcap,
+        age_sec: r.ageMin == null ? null : Math.round(r.ageMin * 60), feeds: [], t: r.fetchedAt,
+    }));
+}
+/**
+ * Recompute the narrative board for the current state: from the history recorder when its DB is reachable
+ * (the design's recorded-history source), else from the visible screener rows so the board is always
+ * populated in fixtures / replay / live-without-recorder.
+ */
+export function computeNarrativeView(state, window, now = Date.now()) {
+    const lex = loadDefaultLexicon();
+    try {
+        const db = state.live?.recorder?.database ?? null;
+        if (db) {
+            const rows = recentNarrativeRows(db, { now });
+            if (rows.length)
+                return { board: computeBoard(rows, lex, { window, now }), window, computedAt: now, source: 'recorded', selected: 0 };
+        }
+        const rows = narrativeRowsFromScreener(state.screener.rows);
+        if (rows.length)
+            return { board: computeBoard(rows, lex, { window, now }), window, computedAt: now, source: 'screen', selected: 0 };
+        return { board: null, window, computedAt: now, source: 'none', selected: 0 };
+    }
+    catch (e) {
+        return { board: null, window, computedAt: now, source: 'none', selected: 0, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+export function newPlansUi() { return { tab: 'plans', selected: 0, notice: null, arming: null, riskModal: false, liveModal: false }; }
+/**
+ * task-1363: how old a board price may be and still fire a plan. The terminal feeds the plan engine from its
+ * screener/watchlist refresh (about every 10 s) and the token screen, so the engine's 3 s default would never
+ * see two consecutive fresh ticks; 15 s keeps the two-tick debounce meaningful at that cadence.
+ */
+export const PLANS_TICK_MAX_AGE_MS = 15_000;
+/**
+ * The plan service for this run, created on first open and recovered from its journal. Held on AppState so
+ * the screen works in fixtures/replay/live alike; a test can inject one via `state.plansSvc`.
+ */
+export function plansService(state, env = process.env) {
+    if (!state.plansSvc)
+        state.plansSvc = new PlanService({ journalPath: defaultPlansJournalPath(env), priceMaxAgeMs: PLANS_TICK_MAX_AGE_MS });
+    return state.plansSvc;
+}
+/** The rows the plans screen shows for the active tab (plans or mandates). */
+export function plansRows(state) {
+    const svc = state.plansSvc;
+    if (!svc)
+        return [];
+    return state.plansUi?.tab === 'mandates' ? svc.listMandates() : svc.listPlans();
+}
+export function newFollowsUi() { return { selected: 0, input: null, notice: null, mirror: null, autoModal: null }; }
+/**
+ * Tier 3: the auto-mirror service for this run, attached to the copy binding on first use. It sits on the plan
+ * service (the signer trust domain) and the copy binding's market resolver; its journal is ~/.dexterm/copy.journal.
+ * Auto is OFF after every start; enabling is a keypress on the follows screen.
+ */
+export function copyAutoService(state, env = process.env) {
+    const copy = copyService(state, env);
+    if (!copy.auto) {
+        const plans = plansService(state, env);
+        const live = state.live ?? null;
+        copy.auto = new CopyAuto({
+            plans, journalPath: defaultCopyJournalPath(env),
+            market: (mint) => copy.mirrorMarket(mint, {}),
+            trades: (wallet) => copy.trades(wallet),
+            isFollowed: (wallet) => copy.store.has(wallet),
+            leaderIntel: (mint, wallet) => {
+                const res = live?.intel.entry(mint)?.result;
+                if (!res || res.state !== 'ok')
+                    return null;
+                const h = res.analysis.holders.find((x) => x.owner === wallet);
+                return { inDevCluster: res.analysis.clusters.some((c) => c.kind === 'dev-linked' && c.members.includes(wallet)) || !!h?.labels.some((l) => l.label === 'dev'), holdsPct: h ? h.pct : null };
+            },
+        });
+    }
+    return copy.auto;
+}
+export { leaderSoldSince };
+/** The user's own cap for ONE mirror ticket (USD). The mandate's per-trade cap still applies at arming. */
+export const MIRROR_DEFAULT_CAP_USD = 20;
+/**
+ * The copy-trading binding for this run: the live context's (polling Helius history) when there is one, else a
+ * store-only binding whose tracker says "unavailable" (fixtures / one-shot). A test injects `state.copy`.
+ */
+export function copyService(state, env = process.env) {
+    if (!state.copy)
+        state.copy = state.live?.copy ?? new CopyLive(null, { env });
+    return state.copy;
+}
+export const RENDERERS = {
+    screener: renderScreener,
+    token: renderToken,
+    newpairs: renderNewPairs,
+    watchlist: renderWatchlist,
+    analyst: renderAnalyst,
+    boot: renderBoot,
+    ticket: renderTicket,
+    positions: renderPositions,
+    trending: renderTrending,
+    kol: renderKol,
+    bubbles: renderBubbles,
+    narrative: renderNarrative,
+    plans: renderPlans,
+    follows: renderFollows,
+    rules: renderRules,
+};
+export const SCREEN_NAMES = Object.keys(RENDERERS);
+export function isScreenKey(s) {
+    return SCREEN_NAMES.includes(s);
+}
+/** Screens that render fixtures while the app runs on real data (the analyst until the Claude lane; any live screen without its binding). */
+export function isDemoScreen(s) {
+    if (s.screener.source === 'fixtures')
+        return false;
+    if (s.screen === 'screener')
+        return false;
+    if (s.screen === 'token')
+        return !s.live?.token;
+    if (s.screen === 'newpairs' || s.screen === 'watchlist')
+        return !s.live;
+    // PAPER trade screens carry their own banner; the header shows a PAPER status, not "demo data".
+    if (s.screen === 'ticket' || s.screen === 'positions')
+        return false;
+    // task-1330: the social screens read real keyless venues/news in live mode (fixtures mode is demo like the rest).
+    if (s.screen === 'trending' || s.screen === 'kol')
+        return false;
+    // task-1340: the bubble map reads the live scan (its own screen says loading / unavailable when it has nothing)
+    if (s.screen === 'bubbles')
+        return false;
+    // task-1360: the follows screen shows the user's own list + the tracker's real state (unavailable when keyless).
+    if (s.screen === 'follows')
+        return false;
+    // analyst screen: a live Claude session (even mid-run or failed) is real output, not demo data
+    return !s.analyst;
+}
+/** The header's view of the state. Screens still on fixtures say so when the app runs on real data. */
+export function headerModel(s) {
+    const demo = isDemoScreen(s);
+    let status = s.screener.headerStatus;
+    let feedLabel = s.feedLabel;
+    if (s.live && !demo) {
+        if (s.screen === 'newpairs') {
+            const st = s.live.newpairs.status();
+            status = st.headerStatus ?? status;
+            feedLabel = st.caption;
+        }
+        else if (s.screen === 'watchlist') {
+            status = s.live.watch.status().headerStatus ?? status;
+            feedLabel = 'dexscreener · jup · sqlite watchlist';
+        }
+        else if (s.screen === 'token')
+            feedLabel = `${s.live.rpc.provider === 'helius' ? 'helius · ' : ''}gecko · rugcheck · goplus · dexscreener · jup`;
+        status = s.live.creditsStatus() ?? status;
+    }
+    if (s.screen === 'ticket' || s.screen === 'positions') {
+        status = '◈ PAPER · simulation';
+        feedLabel = 'jupiter keyless quote · paper wallet';
+    }
+    if (s.screen === 'trending' && s.live)
+        feedLabel = 'jupiter · gecko · boosts · coingecko · rss · keyless';
+    if (s.screen === 'kol')
+        feedLabel = 'kol lists · sqlite';
+    // task-1355: the plans screen is the signer trust domain; it is paper by default and says so.
+    // task-1363: once the fire path is LIVE (devnet fast wallet, keypress opt-in) the header says so; anything not
+    // provably paper renders LIVE (fail-safe).
+    if (s.screen === 'plans') {
+        const paper = s.plansSvc ? s.plansSvc.mode() === 'paper' : true;
+        status = paper ? '◈ PAPER · plans journal' : '◉ LIVE · DEVNET · fast wallet';
+        feedLabel = paper ? 'order plans · standing mandates · hash-chained journal' : 'order plans · signer process · fast wallet · devnet';
+    }
+    // task-1360: the follows screen reads public history for the user's own list; it never trades.
+    if (s.screen === 'follows')
+        feedLabel = `${s.live?.rpc.provider === 'helius' ? 'helius history · ' : ''}your follow list (local) · alerts`;
+    // task-1358: the rules screen evaluates the screener rows locally; rules only alert or PROPOSE.
+    if (s.screen === 'rules')
+        feedLabel = 'rules · config.json · alerts + proposals only · nothing arms';
+    if (s.screen === 'bubbles')
+        feedLabel = `${s.live?.rpc.provider === 'helius' ? 'helius history · ' : ''}rpc holders · rules · sqlite`;
+    // task-1328: a LIVE ticket says so in the header, with the SIGNER's network (never a UI flag).
+    if (s.screen === 'ticket' && s.live?.ticket?.ticket.mode === 'live') {
+        const net = s.live.ticket.view().live?.signer?.network ?? null;
+        status = net === 'mainnet' ? '⚠ LIVE · MAINNET · real funds' : net === 'devnet' ? '◉ LIVE · DEVNET' : '◉ LIVE · signer unreachable';
+        feedLabel = 'signer process · jupiter · phantom';
+    }
+    // task-1324: while AI scan mode is on the header ALWAYS says so (state + the scan's analyst meter +
+    // any Helius credit warning), on every screen — the running indicator wins over every other status.
+    let scanStatus = null;
+    if (s.scan?.engine.on)
+        scanStatus = s.live?.meterStatus(scanIndicator(s.scan)) ?? scanIndicator(s.scan);
+    return {
+        screen: s.screen, paused: s.paused,
+        // live mode never shows the fixture SOL quote; it shows the real one when the feed carried it, else nothing
+        sol: s.screener.source === 'fixtures' ? s.fx.sol : (s.sol ?? null),
+        now: s.now, timeZone: s.timeZone, feedLabel,
+        status: scanStatus ?? (demo ? '◌ demo data' : status),
+        calm: isCalm(s.vfx),
+    };
+}
+/** Wrapped SOL mint: when it is among the enriched rows the header can quote it for free. */
+export const SOL_MINT = 'So11111111111111111111111111111111111111112';
+/** The prototype's frozen clock: 2026-10-05 23:04:11 UTC (19:04:11 in New York). */
+export const FIXTURE_NOW = new Date(Date.UTC(2026, 9, 5, 23, 4, 11));
+export function makeFixtureState(opts = {}) {
+    const seed = opts.seed ?? 7;
+    const fx = makeFixtures(seed);
+    const screen = opts.screen ?? 'screener';
+    const selected = opts.selected ?? 0;
+    const vfx = makeVfx({ seed, intensity: opts.intensity, calm: opts.calm, ascii: opts.asciiRain });
+    vfx.frame = opts.frame ?? 0;
+    const state = {
+        fx,
+        screen,
+        theme: opts.theme ?? THEMES.cyberspace,
+        selected,
+        token: screen === 'token' ? fx.tokens[selected] ?? fx.tokens[0] : null,
+        aiOpen: opts.aiOpen ?? true,
+        paused: false,
+        now: new Date(FIXTURE_NOW.getTime()),
+        timeZone: opts.timeZone === null ? undefined : (opts.timeZone ?? 'America/New_York'),
+        refreshedAgo: '2s',
+        screener: makeScreenerState('fixtures', fx.tokens.map(fromFixture)),
+        vfx,
+        boot: { t: 1 },
+        ai: null,
+        analystByMint: new Map(),
+        larpByMint: new Map(),
+        colorDepth: opts.colorDepth ?? 'truecolor',
+    };
+    refreshVfx(state);
+    if (screen === 'ticket' || screen === 'positions')
+        seedDemoTrade(state);
+    return state;
+}
+/**
+ * Seed a demo PAPER ticket / positions view for one-shot fixture frames (`--screen ticket/positions
+ * --fixtures`) so the screens render without a live binding. The real data comes from the live
+ * bindings (live/trade.ts); this is only the fixtures/evidence path.
+ */
+export function seedDemoTrade(state) {
+    const mint = 'FTREEabc1111111111111111111111111111111111x';
+    const decimals = 6;
+    if (state.screen === 'ticket') {
+        const ticket = openTicket({ mint, symbol: 'FTREE', decimals, side: 'buy' });
+        ticket.sizeInput = '0.5';
+        const quote = {
+            inputMint: SOL_MINT, outputMint: mint, inAmount: 500000000n, outAmount: 1250000000n,
+            otherAmountThreshold: 1243750000n, mode: 'ExactIn', slippageBps: 50, priceImpactPct: 0.42,
+            route: ['Meteora', 'Whirlpool'], platformFeeBps: null, platformFeeAmount: null, usdValue: 75,
+            contextSlot: 1, source: 'jupiter-swap', fetchedAt: FIXTURE_NOW.getTime(),
+        };
+        const order = { mint, symbol: 'FTREE', side: 'buy', decimals, amountRaw: 500000000n, slippageBps: 50 };
+        state.ticket = {
+            ticket, balanceSol: 10, positionTokens: 0, positionValueSol: null, quote,
+            preview: computeFill(order, quote, FIXTURE_NOW.getTime()), quoteAgeMs: 2000, loading: false, error: null, receipt: null, rateLimited: false,
+        };
+    }
+    else {
+        state.positions = {
+            balanceSol: 8.5, startSol: 10, equitySol: 10.42, totalUnrealizedSol: 0.42, totalRealizedSol: 0.12, totalPct: 0.042,
+            solPriceUsd: 150,
+            rows: [{ mint, symbol: 'FTREE', tokens: 1250, costSol: 1.5, avgEntrySol: 0.0012, priceSol: 0.00154, valueSol: 1.92, unrealizedSol: 0.42, unrealizedPct: 0.28, realizedSol: 0.12 }],
+            history: [
+                { id: 2, t: FIXTURE_NOW.getTime() - 30_000, mint, symbol: 'FTREE', side: 'sell', decimals, solDelta: 300000000n, tokenDelta: -200000000n, grossLamports: 300005000n, feeLamports: 5000n, priceSol: 0.0015, priceUsd: 0.225, priceImpactPct: 0.3, slippageBps: 50, route: ['Meteora'], realizedLamports: 60000000n, paper: true },
+                { id: 1, t: FIXTURE_NOW.getTime() - 120_000, mint, symbol: 'FTREE', side: 'buy', decimals, solDelta: -1500005000n, tokenDelta: 1250000000n, grossLamports: 1500000000n, feeLamports: 5000n, priceSol: 0.0012, priceUsd: 0.18, priceImpactPct: 0.42, slippageBps: 50, route: ['Meteora', 'Whirlpool'], realizedLamports: 0n, paper: true },
+            ],
+            loading: false,
+        };
+    }
+}
+/**
+ * State over a data-store feed (live or replayed recording). The fixtures still back the screens
+ * that have not been ported (token detail D-05, new pairs D-10, watchlist D-11); the header marks
+ * them as demo data. Call syncFeed() after every refresh.
+ */
+export function makeFeedState(feed, source, opts = {}) {
+    const state = makeFixtureState(opts);
+    state.feed = feed;
+    state.screener = makeScreenerState(source, [], { presets: feed.presets(), gates: feed.gates() });
+    state.screener.preset = feed.preset;
+    syncFeed(state);
+    return state;
+}
+/** Copy the feed's rows, gates, health status and clock into the state, then rebuild the rain sources and activity. */
+export function syncFeed(state) {
+    const feed = state.feed;
+    if (!feed)
+        return;
+    const sc = state.screener;
+    sc.rows = feed.rows;
+    sc.gates = feed.gates();
+    sc.presets = feed.presets();
+    sc.preset = feed.preset;
+    sc.pool = feed.pool;
+    sc.slowing = feed.slowing;
+    const st = feed.status();
+    sc.headerStatus = st.headerStatus;
+    sc.errors = st.errors;
+    state.feedLabel = st.feedLabel;
+    const sol = feed.rows.find((r) => r.mint === SOL_MINT);
+    if (sol && sol.price !== null)
+        state.sol = { price: sol.price, chg24: sol.chg.h24 ?? 0 };
+    state.refreshedAgo = feed.refreshedAgo();
+    state.now = new Date(feed.now());
+    refreshVfx(state);
+}
+/** Rain columns are the user's own data: watchlist + screener tickers, mint prefixes, trade address tails (VISUAL-V2 §7). */
+export function rainSources(state) {
+    const s = [];
+    const fx = state.fx;
+    for (const w of fx.watch)
+        s.push(w.token.symbol);
+    const live = state.screener.source !== 'fixtures' ? state.screener.rows : [];
+    if (live.length) {
+        for (const r of live.slice(0, 16))
+            s.push(r.symbol.toUpperCase());
+        for (const r of live.slice(0, 10))
+            s.push(r.mint.slice(0, 10).toUpperCase());
+    }
+    else {
+        for (const t of fx.tokens.slice(0, 12))
+            s.push(t.symbol);
+        for (const t of fx.tokens.slice(0, 8))
+            s.push(t.mint.slice(0, 10).toUpperCase());
+    }
+    for (const t of fx.tokens.slice(0, 4))
+        for (const tr of t.trades.slice(0, 3))
+            s.push(tr.addr.slice(-8).toUpperCase());
+    return s;
+}
+/**
+ * Market activity for the rain (VISUAL-V2 §3, §7): on the token screen the selected token's own
+ * candles drive colour and speed; elsewhere the cross-section of the rows on screen does (live
+ * rows when the feed has them, fixtures otherwise), with volume velocity when the source reports it.
+ */
+export function activityFor(state) {
+    if (state.screen === 'token') {
+        const tk = state.token || state.fx.tokens[state.selected || 0];
+        if (tk)
+            return candleActivity(tk.candles, tk.chg.m5);
+    }
+    const live = state.screener.source !== 'fixtures' ? state.screener.rows : [];
+    if (live.length) {
+        const rows = state.screen === 'screener' ? screenerView(state.screener) : live;
+        const use = rows.length ? rows : live;
+        return marketActivity(use.map((r) => r.chg.m5), use.map((r) => (r.vol5m !== null && r.vol24 !== null && r.vol24 > 0 ? (r.vol5m * 288) / r.vol24 : null)));
+    }
+    const all = [...state.fx.tokens, ...state.fx.newPairs];
+    return marketActivity(all.map((t) => t.chg.m5));
+}
+/** Rebuild rain sources and set activity/mood directly from the data (one-shot renders and feed syncs). */
+export function refreshVfx(state) {
+    setSources(state.vfx, rainSources(state));
+    const act = activityFor(state);
+    state.vfx.activity = act.activity;
+    state.vfx.mood = act.mood;
+}
+/** Render one frame of the current screen into a fresh canvas: screen → toast → effects. */
+export function renderFrame(state, w, h) {
+    const c = new Canvas(w, h, state.theme);
+    c.fill(0, 0, w, h, ' ', { bg: state.theme.bg });
+    c.imageMode = state.images && state.imageProtocol && state.imageProtocol !== 'blocks' ? 'pixels' : 'cells';
+    (RENDERERS[state.screen] || renderScreener)(c, state);
+    // task-1324: the SCANNING ticker on row 1 (the blank band under the header) of every list screen; the
+    // live token screen draws its own WHY IT TRIGGERED strip there (token-live.ts).
+    if (state.scan?.engine.on && state.screen !== 'boot' && state.screen !== 'token')
+        renderScanTicker(c, state.scan, state.live?.scanMeterLabel() ?? '');
+    if (state.screen !== 'boot')
+        toast(c, state.vfx.toast);
+    applyFx(c, state.vfx, { scan: state.screen !== 'boot' });
+    // The voice indicator (task-1282) draws after the effects so the mic-live badge is always crisp and
+    // unmistakable. Suppressed on the boot screen, where row 1 is part of the boot art.
+    if (state.voice?.enabled && state.screen !== 'boot')
+        renderVoiceHud(c, state.voice, state.theme);
+    // task-1358: the workspace badge (non-default name, a pending ctrl+w chord, the save-as input) on the band
+    // under the header, right-aligned, drawn after the effects so it is always legible. Nothing on `default`.
+    const badge = state.screen !== 'boot' ? workspaceBadge(state.custom, state.now.getTime()) : null;
+    if (badge) {
+        const t = state.theme;
+        const text = badge.text.slice(0, Math.max(0, w - 2));
+        const x = Math.max(0, w - text.length - 1);
+        c.noRain(x, 1, text.length, 1);
+        c.text(x, 1, text, badge.kind === 'input' ? { fg: t.text, bg: t.accentSoft, b: true } : badge.kind === 'chord' ? { fg: t.warn, bg: t.warnSoft, b: true } : { fg: t.accent, bg: t.headBg, b: true });
+    }
+    // Overlays (task-1305) draw last, over the effects, so the welcome/help card is always crisp.
+    if (state.overlay)
+        renderOverlay(c, state);
+    // task-1388: the GO-TO prompt draws on top of everything (but is mutually exclusive with an overlay).
+    if (state.goto)
+        renderGotoPrompt(c, state);
+    return c;
+}

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

@@ -0,0 +1,126 @@
+// `dexterm theme <list|show|init|check> …` and `dexterm keymap [screen]` (task-1358 Tier 2). No network, no
+// model, never touches a key file.
+//   theme list              built-ins + ~/.dexterm/themes/*.json + config.theme.user, with errors for bad ones
+//   theme show <name>       the resolved tokens (user theme merged over its base, overrides applied)
+//   theme init <name> [--extends cyberspace|midnight|ember|paper]   write a starter theme file to edit
+//   theme check <file>      validate a theme file (schema, contrast floor, up/down hue) without installing it
+//   keymap [screen]         the effective bindings (defaults + config.keymap), user overrides marked with ·
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { THEMES, THEME_NAMES, DEFAULT_KEYMAP } from '../../tui/src/index.js';
+import { dextermHome, loadConfig, listUserThemes, resolveTheme, applyOverrides, starterTheme, themesDir, validate, applyKeymapConfig, renderKeymap, BASE_THEMES } from '../../custom/src/index.js';
+export const THEME_USAGE = `usage: dexterm theme list | show <name> | init <name> [--extends ${BASE_THEMES.join('|')}] | check <file>
+  files: ~/.dexterm/themes/<name>.json = { "extends": "<built-in>", "tokens": { "<token>": "#rrggbb", "<ramp>": [4 × "#rrggbb"] } }
+  guard: text/warn/up/down must keep a contrast floor against bg/panel; up stays green/cyan, down stays red/pink`;
+const bases = THEMES;
+export async function themeCommand(argv, io) {
+    const home = dextermHome(io.env);
+    const [cmd, name] = argv;
+    const bad = (s) => { io.stderr.write(`dexterm theme: ${s}\n${THEME_USAGE}\n`); return 2; };
+    const cfg = loadConfig(home);
+    switch (cmd) {
+        case undefined:
+        case 'list': {
+            io.stdout.write(`${themesDir(home)}\n`);
+            for (const n of THEME_NAMES)
+                io.stdout.write(`  ${n.padEnd(24)} built-in\n`);
+            for (const t of listUserThemes(home, cfg.config)) {
+                if (t.error) {
+                    io.stdout.write(`  ${t.name.padEnd(24)} ⚠ ${t.error}\n`);
+                    continue;
+                }
+                const r = resolveTheme(t.doc, bases);
+                io.stdout.write(`  ${t.name.padEnd(24)} ${t.path ? 'file' : 'config'} · extends ${t.doc.extends} · ${Object.keys(t.doc.tokens ?? {}).length} token(s)${r.theme ? '' : ` · ⚠ ${r.errors[0].path} ${r.errors[0].msg}`}\n`);
+            }
+            const ov = cfg.config.theme?.overrides ?? {};
+            if (Object.keys(ov).length)
+                io.stdout.write(`  overrides (config.theme.overrides): ${Object.keys(ov).join(', ')}\n`);
+            return 0;
+        }
+        case 'show': {
+            if (!name)
+                return bad('show needs a name');
+            let doc = bases[name] ?? null;
+            if (!doc) {
+                const t = listUserThemes(home, cfg.config).find((x) => x.name === name);
+                if (!t) {
+                    io.stderr.write(`dexterm theme: no theme "${name}"\n`);
+                    return 1;
+                }
+                if (t.error) {
+                    io.stderr.write(`dexterm theme: ${name}: ${t.error}\n`);
+                    return 1;
+                }
+                const r = resolveTheme(t.doc, bases);
+                if (!r.theme) {
+                    io.stderr.write(`dexterm theme: ${name} refused: ${r.errors.map((e) => `${e.path} ${e.msg}`).join('; ')}\n`);
+                    return 1;
+                }
+                doc = r.theme;
+            }
+            const o = applyOverrides(doc, cfg.config.theme?.overrides);
+            for (const e of o.errors)
+                io.stderr.write(`dexterm theme: override ignored: ${e.path} ${e.msg}\n`);
+            io.stdout.write(JSON.stringify(o.theme, null, 2) + '\n');
+            return 0;
+        }
+        case 'init': {
+            if (!name)
+                return bad('init needs a name');
+            if (!/^[a-z][a-z0-9-]{0,39}$/.test(name))
+                return bad('name: lowercase letters, digits and dashes');
+            if (BASE_THEMES.includes(name))
+                return bad(`"${name}" is a built-in theme`);
+            const ei = argv.indexOf('--extends');
+            const base = ei >= 0 ? argv[ei + 1] : 'cyberspace';
+            if (!BASE_THEMES.includes(base))
+                return bad(`--extends expects ${BASE_THEMES.join('|')}`);
+            mkdirSync(themesDir(home), { recursive: true, mode: 0o700 });
+            const path = join(themesDir(home), `${name}.json`);
+            if (existsSync(path)) {
+                io.stdout.write(`${path} already exists\n`);
+                return 0;
+            }
+            const { name: _n, ...body } = starterTheme(name, base);
+            void _n;
+            writeFileSync(path, JSON.stringify(body, null, 2) + '\n', { mode: 0o600 });
+            io.stdout.write(`wrote ${path}\n  edit the tokens, then: dexterm --theme ${name}  (or t in the app cycles to it)\n`);
+            return 0;
+        }
+        case 'check': {
+            if (!name)
+                return bad('check needs a file');
+            let raw;
+            try {
+                raw = JSON.parse(readFileSync(name, 'utf8'));
+            }
+            catch (e) {
+                io.stderr.write(`dexterm theme: ${name}: ${e.message}\n`);
+                return 1;
+            }
+            const doc = { name: 'check', ...raw };
+            const errors = validate('userTheme', doc);
+            const r = errors.length ? { theme: null, errors } : resolveTheme(doc, bases);
+            if (r.theme) {
+                io.stdout.write(`ok: ${name} extends ${doc.extends} (${Object.keys(doc.tokens ?? {}).length} token(s)); contrast floor and the up/down guard (hue, saturation, distance) pass\n`);
+                return 0;
+            }
+            for (const e of r.errors)
+                io.stdout.write(`✗ ${e.path || '/'} ${e.msg}\n`);
+            return 1;
+        }
+        default: return bad(`unknown subcommand "${cmd}"`);
+    }
+}
+export async function keymapCommand(argv, io) {
+    const home = dextermHome(io.env);
+    const cfg = loadConfig(home);
+    for (const e of cfg.errors)
+        io.stderr.write(`dexterm keymap: config: ${e}\n`);
+    const r = applyKeymapConfig(DEFAULT_KEYMAP.bindings, cfg.config.keymap);
+    const screen = argv[0] && /^[a-z]+$/.test(argv[0]) ? argv[0] : undefined;
+    io.stdout.write(`${cfg.path}${cfg.missing ? ' (no config: defaults)' : ''} · config.keymap.global[action] = ["key", …] · config.keymap.screens[screen][action] = [...]\n`);
+    io.stdout.write(`reserved keys: ctrl+c esc enter y Y ! · reserved actions keep their keys: quit back alert.confirm alert.dismiss plans.arm plans.panic plans.gate\n`);
+    io.stdout.write(renderKeymap(r, screen) + '\n');
+    return r.errors.length ? 1 : 0;
+}