dexterm-cli 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,375 @@
+// dexterm doctor (task-1305): a pre-flight the user runs before anything else. It answers one
+// question — "will dexterm work on this machine, and if not, exactly what do I fix?" — as a plain
+// pass/warn/fail list with a copy-pasteable fix on every line that is not a pass.
+//
+// Everything that touches the outside world (the claude binary, the network) is injected so the
+// checks stay deterministic in tests and never hang: each probe carries its own timeout and any
+// failure is turned into a `fail`/`warn` line, never an exception. The doctor NEVER prints the
+// Helius key or any URL that could carry it — it reports the provider name only.
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { shellBinaryPath } from '../../popup/src/index.js';
+import { detectColorDepth, protocolFromEnv } from '../../tui/src/index.js';
+import { resolveRpcUrl, defaultDbPath } from '../../data/src/index.js';
+import { XTokenStore } from '../../data/src/index.js';
+import { SayTts, voiceDoctor, resolveVoice, WHISPER_MODEL, resolvePiperBin, pickPlayer, PIPER_MODEL } from '../../voice/src/index.js';
+import { loadConfig, dextermHome } from '../../custom/src/index.js';
+import { kbStore, skillStore } from "./kb-skill-cmd.js";
+/** The minimum Node that runs dexterm (type-stripping of the .ts entry needs 22.18). */
+export const MIN_NODE = [22, 18, 0];
+/** Cheap PATH lookup (no spawn) for the voice probe. */
+function onPath(bin) {
+    for (const p of (process.env.PATH ?? '').split(':'))
+        if (p && existsSync(join(p, bin)))
+            return true;
+    return false;
+}
+/**
+ * Default voice probe. Deliberately cheap and non-blocking: it never compiles the Swift helper (that
+ * is left to the first real `v` press), so resolvedStt is inferred from swiftc / whisper presence.
+ */
+export async function defaultVoiceProbe(platform = process.platform, configuredVoice) {
+    const say = new SayTts();
+    const sayAvailable = platform === 'darwin' ? await say.available() : false;
+    const voices = sayAvailable ? await say.listVoicesDetailed() : [];
+    const swiftcPresent = platform === 'darwin' && onPath('swiftc');
+    const whisperBinPresent = onPath('whisper-cli');
+    const whisperModelPresent = existsSync(WHISPER_MODEL);
+    const micToolPresent = onPath('sox') || onPath('rec') || onPath('ffmpeg') || onPath('arecord');
+    // Apple Speech is macOS-only; everywhere else whisper.cpp is the default voice-in (task-1393 Part 2).
+    const resolvedStt = swiftcPresent ? 'apple' : (whisperBinPresent && whisperModelPresent && micToolPresent) ? 'whisper' : null;
+    // espeak-ng is the baseline portable speech-out engine off macOS.
+    const espeakPresent = platform !== 'darwin' && (onPath('espeak-ng') || onPath('espeak'));
+    // Piper is the preferred neural speech-out engine off macOS (task-1408): binary + voice model + a player.
+    const piperPresent = platform !== 'darwin' && resolvePiperBin() !== null;
+    const piperVoicePresent = platform !== 'darwin' && existsSync(PIPER_MODEL);
+    const playerName = platform !== 'darwin' ? pickPlayer() : null;
+    // task-1393: show which voice will actually speak, and why — never a silent system/novelty voice.
+    const r = sayAvailable ? resolveVoice({ configured: configuredVoice, installed: voices }) : { voice: null, reason: '' };
+    return {
+        platform, sayAvailable, voiceCount: voices.length, swiftcPresent, whisperBinPresent, whisperModelPresent, micToolPresent, resolvedStt,
+        espeakPresent, piperPresent, piperVoicePresent, playerName,
+        resolvedVoice: sayAvailable ? r.voice : undefined, resolvedVoiceReason: r.reason,
+    };
+}
+/** The keyless data sources the live app depends on, with a cheap reachability URL for each. */
+export const DATA_SOURCES = [
+    { name: 'DexScreener', url: 'https://api.dexscreener.com/latest/dex/search?q=SOL' },
+    { name: 'Jupiter', url: 'https://lite-api.jup.ag/price/v3?ids=So11111111111111111111111111111111111111112' },
+    { name: 'GeckoTerminal', url: 'https://api.geckoterminal.com/api/v2/networks' },
+    { name: 'RugCheck', url: 'https://api.rugcheck.xyz/v1/stats/new_tokens' },
+    { name: 'GoPlus', url: 'https://api.gopluslabs.io/api/v1/supported_chains' },
+    { name: 'Solana RPC', url: 'https://api.mainnet-beta.solana.com' },
+    // PumpPortal is a websocket; a plain GET to the host proves the network path (new pairs is a soft dep).
+    { name: 'PumpPortal', url: 'https://pumpportal.fun/', soft: true },
+];
+function parseVersion(v) {
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(v);
+    if (!m)
+        return [0, 0, 0];
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+/** Compare two semver triples: -1 / 0 / 1. */
+export function cmpVersion(a, b) {
+    for (let i = 0; i < 3; i++) {
+        const d = (a[i] ?? 0) - (b[i] ?? 0);
+        if (d)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/** Default live probe: a GET with a hard timeout. Any HTTP answer = reachable; only transport errors fail. */
+export async function livingProbe(url, timeoutMs = 4000) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    const t0 = Date.now();
+    try {
+        const res = await fetch(url, { method: 'GET', signal: ctl.signal, headers: { 'user-agent': 'dexterm-doctor' } });
+        // Drain a little so sockets close cleanly; we do not care about the body.
+        try {
+            await res.arrayBuffer();
+        }
+        catch { /* ignore */ }
+        return { reachable: true, status: res.status, ms: Date.now() - t0 };
+    }
+    catch (e) {
+        const err = e.name === 'AbortError' ? `timeout after ${timeoutMs}ms` : e.message;
+        return { reachable: false, error: err, ms: Date.now() - t0 };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Default claude probe: spawn `claude --version` with a timeout. Presence only (login is not asserted here). */
+export async function claudeProbe(timeoutMs = 4000) {
+    const { execFile } = await import('node:child_process');
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (r) => { if (!done) {
+            done = true;
+            resolve(r);
+        } };
+        try {
+            const child = execFile('claude', ['--version'], { timeout: timeoutMs }, (err) => {
+                if (err && err.code === 'ENOENT')
+                    finish('missing');
+                else if (err)
+                    finish('present'); // on PATH but the probe errored/timed out: do not block on it
+                else
+                    finish('present');
+            });
+            child.on('error', () => finish('missing'));
+        }
+        catch {
+            finish('missing');
+        }
+    });
+}
+/** Default writable check: create the directory, write and remove a temp file. Returns an error message or null. */
+export function writableProbe(dir) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        const tmp = mkdtempSync(join(dir, '.dexterm-doctor-'));
+        const f = join(tmp, 'probe');
+        writeFileSync(f, 'ok');
+        rmSync(tmp, { recursive: true, force: true });
+        return null;
+    }
+    catch (e) {
+        return e.message;
+    }
+}
+export function defaultDeps(env = process.env, isTTY = process.stdout.isTTY === true) {
+    return {
+        env,
+        isTTY,
+        nodeVersion: process.versions.node,
+        platform: process.platform,
+        claude: () => claudeProbe(),
+        probe: (url) => livingProbe(url),
+        checkWritable: writableProbe,
+        offline: env.DEXTERM_OFFLINE === '1' || env.DEXTERM_OFFLINE === 'true',
+        popupShell: () => {
+            const path = shellBinaryPath(env);
+            const cargo = spawnSync('cargo', ['--version'], { stdio: 'ignore', timeout: 3000 }).status === 0;
+            return { path, built: existsSync(path), cargo };
+        },
+        voiceProbe: () => defaultVoiceProbe(process.platform, loadConfig(dextermHome(env)).config.voice?.name ?? null),
+        content: () => ({ kb: kbStore(env).get(), skills: skillStore(env).get() }),
+    };
+}
+/** Run every check. Never throws; network and claude probes are the injected ones. */
+export async function runDoctor(deps) {
+    const checks = [];
+    // 1. Node version
+    const node = parseVersion(deps.nodeVersion);
+    if (cmpVersion(node, MIN_NODE) >= 0) {
+        checks.push({ name: 'Node', status: 'pass', detail: `v${deps.nodeVersion} (need ${MIN_NODE.join('.')}+)` });
+    }
+    else {
+        checks.push({
+            name: 'Node', status: 'fail',
+            detail: `v${deps.nodeVersion} is too old (need ${MIN_NODE.join('.')}+ for the TypeScript entry)`,
+            fix: 'Install Node 22.18+ : `nvm install 22` (nvm) or `brew install node` (Homebrew), then re-run.',
+        });
+    }
+    // 2. Terminal colour
+    const depth = detectColorDepth(deps.env, deps.isTTY);
+    const term = deps.env.TERM_PROGRAM || deps.env.TERM || 'unknown';
+    if (!deps.isTTY) {
+        checks.push({
+            name: 'Terminal', status: 'warn',
+            detail: 'not a TTY (output is being piped); the interactive UI needs a real terminal',
+            fix: 'Run dexterm directly in a terminal window, not through a pipe or a non-interactive shell.',
+        });
+    }
+    else if (depth === 'truecolor') {
+        checks.push({ name: 'Terminal colour', status: 'pass', detail: `24-bit truecolor (${term})` });
+    }
+    else if (depth === '256') {
+        checks.push({
+            name: 'Terminal colour', status: 'warn',
+            detail: `256-colour only (${term}); dexterm runs but the neon look is flattened`,
+            fix: 'Use a truecolor terminal (iTerm2, WezTerm, Ghostty, Kitty, Alacritty, Windows Terminal) or set COLORTERM=truecolor.',
+        });
+    }
+    else {
+        checks.push({
+            name: 'Terminal colour', status: 'warn',
+            detail: `no colour (${term}${deps.env.NO_COLOR ? ', NO_COLOR set' : ''}); dexterm falls back to monochrome`,
+            fix: 'Unset NO_COLOR and use a colour terminal for the full look; dexterm still works without it.',
+        });
+    }
+    // 2b. Coin images (task-1326): the protocol this terminal gets, judged from the environment alone (the
+    // interactive run also asks the tty). Apple Terminal.app is the one known no-images terminal → warn + fix.
+    {
+        const p = protocolFromEnv(deps.env);
+        const label = p.protocol === 'kitty' ? 'real pixels (kitty graphics)' : p.protocol === 'iterm' ? 'real pixels (iTerm2 inline images)' : p.protocol === 'sixel' ? 'real pixels (sixel)' : 'half-block art';
+        if (p.protocol === 'blocks' && /apple terminal/i.test(p.reason)) {
+            checks.push({ name: 'Coin images', status: 'warn', detail: `${label}: ${p.reason}`, fix: 'For real coin pictures use Ghostty (`brew install --cask ghostty`) or iTerm2 (`brew install --cask iterm2`); the block-art fallback still shows every coin here.' });
+        }
+        else {
+            checks.push({ name: 'Coin images', status: 'pass', detail: `${label} (${p.reason})${p.protocol === 'blocks' ? '; --no-images turns them off' : ''}` });
+        }
+    }
+    // 3. Claude CLI (the analyst). Not required to browse; required for the `a` analyst.
+    const claude = await deps.claude();
+    if (claude === 'missing') {
+        checks.push({
+            name: 'Claude CLI', status: 'warn',
+            detail: 'not found on PATH; the analyst (a) is disabled, the rest of dexterm works',
+            fix: 'Install Claude Code (https://claude.com/claude-code) and run `claude` once to log in.',
+        });
+    }
+    else {
+        checks.push({
+            name: 'Claude CLI', status: 'pass',
+            detail: 'found on PATH (the analyst runs your local `claude`; log in once with `claude` if the analyst errors)',
+        });
+    }
+    // 4b. Login with X (optional, task-1357): the user's own X app + login unlock X posts in the SOCIAL panel / TRENDING.
+    {
+        const xs = new XTokenStore({ env: deps.env });
+        const meta = xs.meta();
+        const modes = xs.modes();
+        const clientId = xs.clientId(deps.env);
+        if (meta.loggedIn) {
+            const loose = (modes.tokens !== null && modes.tokens !== 0o600) || (modes.dir !== null && modes.dir !== 0o700);
+            checks.push({ name: 'Login with X', status: loose ? 'warn' : 'pass', detail: `logged in${meta.user ? ` as @${meta.user.username}` : ''} · scopes ${meta.scopes.join(' ') || '?'} · refresh ${meta.hasRefresh ? 'yes' : 'no'}${loose ? ' · token file permissions are looser than 0600' : ''}`, ...(loose ? { fix: `chmod 700 ${xs.dir} && chmod 600 ${xs.tokensPath}` } : {}) });
+        }
+        else if (clientId) {
+            checks.push({ name: 'Login with X', status: 'warn', detail: 'client id stored, not logged in — X posts stay off (keyless venues, news and on-chain rows still work)', fix: 'dexterm x login' });
+        }
+        else {
+            checks.push({ name: 'Login with X', status: 'pass', detail: 'not set up (optional) — X posts need your own X app: free Native App + `dexterm x set-client-id` + `dexterm x login`; see docs › Login with X' });
+        }
+    }
+    // 4. Helius key (optional; the app is live and keyless without it, just with fewer holders/safety fields).
+    const rpc = resolveRpcUrl({ env: deps.env, home: deps.env.HOME || undefined });
+    if (rpc.provider === 'helius') {
+        checks.push({ name: 'Helius RPC', status: 'pass', detail: `key configured (${rpc.basis}) — holders & safety enriched` });
+    }
+    else if (rpc.provider === 'custom') {
+        checks.push({ name: 'RPC', status: 'pass', detail: 'custom endpoint via DEXTERM_RPC_URL' });
+    }
+    else {
+        checks.push({
+            name: 'Helius RPC', status: 'warn',
+            detail: 'no key — dexterm uses the public RPC (holders & some safety fields will show as "needs key")',
+            fix: 'Free tier: make a key at https://dashboard.helius.dev, then `mkdir -p ~/.dexterm && printf %s "YOUR_KEY" > ~/.dexterm/helius.key && chmod 600 ~/.dexterm/helius.key`',
+        });
+    }
+    // 5. Network + each data source
+    if (deps.offline) {
+        checks.push({
+            name: 'Network', status: 'warn',
+            detail: 'DEXTERM_OFFLINE is set; skipped the live source probes (use --fixtures / --replay for offline data)',
+        });
+    }
+    else {
+        const results = await Promise.all(DATA_SOURCES.map(async (s) => ({ s, r: await deps.probe(s.url) })));
+        const down = results.filter((x) => !x.r.reachable);
+        const hardDown = down.filter((x) => !x.s.soft);
+        if (down.length === 0) {
+            const slow = results.filter((x) => (x.r.ms ?? 0) > 2500).map((x) => x.s.name);
+            checks.push({
+                name: 'Data sources', status: 'pass',
+                detail: `all ${results.length} reachable${slow.length ? ` (slow: ${slow.join(', ')})` : ''}`,
+            });
+        }
+        else {
+            checks.push({
+                name: 'Data sources', status: hardDown.length ? 'fail' : 'warn',
+                detail: `unreachable: ${down.map((x) => `${x.s.name} (${x.r.error ?? 'error'})`).join(', ')}`,
+                fix: hardDown.length
+                    ? 'Check your internet connection / VPN / firewall. If only some hosts fail, they may be regionally blocked — try again or use a different network.'
+                    : 'New pairs (PumpPortal) is unreachable; the rest of dexterm works. Check back later or your network may block its host.',
+            });
+        }
+    }
+    // 5b. task-1325: the native chart window (docked beside the terminal) vs the browser fallback
+    if (deps.popupShell) {
+        const sh = deps.popupShell();
+        if (sh.built)
+            checks.push({ name: 'Chart window', status: 'pass', detail: `native window ready (${sh.path}); C on a token opens it docked beside this terminal` });
+        else
+            checks.push({
+                name: 'Chart window', status: 'warn',
+                detail: `native window not built — C opens the chart in your browser instead`,
+                fix: sh.cargo ? 'Run `npm run build:shell` in packages/popup (about a minute the first time).' : 'Install Rust (https://rustup.rs), then run `npm run build:shell` in packages/popup.',
+            });
+    }
+    // 6. Writable DB path
+    const dbPath = defaultDbPath(deps.env);
+    const dbDir = dirname(dbPath);
+    const werr = deps.checkWritable(dbDir);
+    if (!werr) {
+        checks.push({ name: 'Data directory', status: 'pass', detail: `${dbDir} is writable (cache, watchlist, credit meter)` });
+    }
+    else {
+        checks.push({
+            name: 'Data directory', status: 'fail',
+            detail: `cannot write ${dbDir}: ${werr}`,
+            fix: `Fix the permissions (\`mkdir -p ${dbDir} && chmod u+rwx ${dbDir}\`) or run with \`--db :memory:\` for a throwaway session.`,
+        });
+    }
+    // 6b. task-1377: the user's KB / skill overlay. Warn-only: a bad user file is skipped and the bundled one stays in effect.
+    if (deps.content) {
+        try {
+            const { kb, skills } = deps.content();
+            const part = (label, m) => `${label} ${m.bundled} bundled · ${m.user} user (${m.overridden} overridden, ${m.added} new)${m.skipped.length ? ` · ${m.skipped.length} skipped` : ''}`;
+            const detail = `${part('KB', kb)} · ${part('skills', skills)}`;
+            const skipped = [...kb.skipped.map((s) => `kb ${s.id}: ${s.reason}`), ...skills.skipped.map((s) => `skill ${s.id}: ${s.reason}`)];
+            if (skipped.length) {
+                checks.push({ name: 'KB + skills', status: 'warn', detail: `${detail}; skipped ${skipped.slice(0, 3).join('; ')}`, fix: `Run \`dexterm kb check\` / \`dexterm skill check\` and fix the file, or \`dexterm kb|skill reset <id>\` to go back to the bundled one.` });
+            }
+            else {
+                checks.push({ name: 'KB + skills', status: 'pass', detail: `${detail} (yours: ${kb.dir}, ${skills.dir}; \`dexterm kb|skill list\`)` });
+            }
+        }
+        catch { /* an overlay problem must not break the doctor */ }
+    }
+    // 7. Voice mode (task-1282). Warn-only — voice always degrades to text, so it never fails the doctor.
+    if (deps.voiceProbe) {
+        try {
+            const vc = voiceDoctor(await deps.voiceProbe());
+            for (const c of vc)
+                checks.push(c);
+        }
+        catch { /* a voice probe failure must not break the doctor */ }
+    }
+    const ok = !checks.some((c) => c.status === 'fail');
+    return { checks, ok };
+}
+const GLYPH = { pass: '✓', warn: '!', fail: '✗' };
+const ANSI = { pass: '\x1b[32m', warn: '\x1b[33m', fail: '\x1b[31m' };
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+/** Render the result as a plain pass/fail list. `color` adds ANSI; off for pipes / NO_COLOR. */
+export function renderDoctor(result, opts = {}) {
+    const color = opts.color ?? false;
+    const paint = (s, code) => (color ? code + s + RESET : s);
+    const lines = [];
+    lines.push(paint('dexterm doctor', color ? BOLD : ''));
+    lines.push('');
+    const nameW = Math.max(...result.checks.map((c) => c.name.length));
+    for (const c of result.checks) {
+        const g = paint(GLYPH[c.status], color ? ANSI[c.status] : '');
+        lines.push(`  ${g}  ${c.name.padEnd(nameW)}  ${c.detail}`);
+        if (c.fix)
+            lines.push(`     ${' '.repeat(nameW)}  ${paint('→ ' + c.fix, color ? DIM : '')}`);
+    }
+    lines.push('');
+    const fails = result.checks.filter((c) => c.status === 'fail').length;
+    const warns = result.checks.filter((c) => c.status === 'warn').length;
+    if (result.ok && warns === 0)
+        lines.push(paint('All checks passed — run `dexterm` to start.', color ? ANSI.pass : ''));
+    else if (result.ok)
+        lines.push(paint(`Ready to run (${warns} warning${warns === 1 ? '' : 's'} above are optional).`, color ? ANSI.warn : ''));
+    else
+        lines.push(paint(`${fails} check${fails === 1 ? '' : 's'} failed — fix the ✗ lines above, then re-run \`dexterm doctor\`.`, color ? ANSI.fail : ''));
+    return lines.join('\n');
+}

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

@@ -0,0 +1,235 @@
+// dexterm — EXPORT / SHARE (task-1401). One key (`E`) renders the current view to a PNG plus a plain-text report in
+// ~/.dexterm/exports (DEXTERM_HOME overrides). Nothing is uploaded, posted or copied anywhere else.
+//
+// The renderer is reusable on purpose (task-1407 PNL cards build on it): give `renderExportPng` / `renderExportText`
+// / `writeExport` an ExportView — any rendered Canvas plus its title, the data label (live / sample / replay) and the
+// data ages — and it frames the view with a header band (title, the label, the export time) and a footer band (every
+// data age, "nothing was uploaded"). The label is never optional: a sample-data frame always says SAMPLE DATA.
+//
+// The frame is rendered CALM (no rain, glitch or scanlines) with no toast, help card or prompt on top, so the PNG
+// is the data, not an effect. PNGs are pure TypeScript (@dexterm/tui rasterize + @dexterm/data encodePng).
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Canvas, rasterizeCanvas, fmtUsd, fmtPrice, fmtPct } from '../../tui/src/index.js';
+import { encodePng } from '../../data/src/index.js';
+import { dextermHome } from "./boot-state.js";
+import { cleanText } from "./screener/rows.js";
+import { rugP, fmtRugP, RUG_MODEL_LABEL } from "./screener/rug.js";
+import { renderFrame } from "./state.js";
+export const LABEL_TEXT = {
+    live: '● LIVE DATA',
+    sample: '◌ SAMPLE DATA · not real prices',
+    replay: '◌ REPLAY · recorded data',
+};
+/** `4s` / `3m` / `2h` / `5d`; `—` when unknown. */
+export function fmtAge(sec) {
+    if (sec === null || !Number.isFinite(sec))
+        return '—';
+    const s = Math.max(0, Math.round(sec));
+    return s < 60 ? `${s}s` : s < 3600 ? `${Math.floor(s / 60)}m` : s < 86_400 ? `${Math.floor(s / 3600)}h` : `${Math.floor(s / 86_400)}d`;
+}
+const ageText = (a) => (a.ageSec !== null ? `${a.name} ${fmtAge(a.ageSec)}` : `${a.name} ${a.state || 'n/a'}`);
+/** Local timestamp `2026-10-16 01:23:45` (the machine's own clock; the report also carries the ISO time). */
+function localStamp(now) {
+    const d = new Date(now);
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+/** Wrap `parts` joined by ` · ` into lines of at most `w` columns. */
+function wrapParts(prefix, parts, w) {
+    const out = [];
+    let line = prefix;
+    for (const p of parts) {
+        const add = line === prefix ? p : ` · ${p}`;
+        if (line.length + add.length > w && line !== prefix) {
+            out.push(line);
+            line = ' '.repeat(prefix.length) + p;
+        }
+        else
+            line += add;
+    }
+    out.push(line);
+    return out;
+}
+/**
+ * Frame a rendered view: a header band (title, label, export time), the view itself, and a footer band (every data
+ * age, local-only note). Returns a new canvas; the view canvas is not changed.
+ */
+export function composeExportCanvas(v, now) {
+    const src = v.canvas;
+    const w = Math.max(src.w, 60);
+    const t = src.theme;
+    const footer = [
+        ...(v.mint ? [` contract ${v.mint}`] : []),
+        ...wrapParts(v.label === 'replay' ? ' data ages (replay clock): ' : ' data ages: ', v.ages.length ? v.ages.map(ageText) : ['none reported for this view'], w - 1),
+        ` exported locally by dexterm ${localStamp(now)} · nothing was uploaded · not financial advice`,
+    ];
+    const c = new Canvas(w, src.h + 2 + footer.length, t);
+    c.fill(0, 0, w, c.h, ' ', { bg: t.bg });
+    // header band
+    c.fill(0, 0, w, 1, ' ', { bg: t.headBg });
+    const label = ` ${LABEL_TEXT[v.label]} `;
+    const labelFg = v.label === 'live' ? t.up : t.warn;
+    c.text(1, 0, `dexterm export · ${v.title}`, { fg: t.text, bg: t.headBg, b: true }, Math.max(0, w - label.length - 3));
+    c.textR(0, 0, w - 1, label, { fg: labelFg, bg: t.headBg, b: true });
+    // the view
+    for (let y = 0; y < src.h; y++)
+        for (let x = 0; x < src.w; x++) {
+            const i = src.idx(x, y), j = c.idx(x, y + 1);
+            c.ch[j] = src.ch[i];
+            c.fg[j] = src.fg[i];
+            c.bg[j] = src.bg[i];
+            c.at[j] = src.at[i];
+            c.hard[j] = src.hard[i];
+        }
+    for (const s of src.images)
+        c.images.push({ ...s, y: s.y + 1 });
+    c.imageMode = src.imageMode;
+    // footer band
+    const fy = src.h + 1;
+    c.fill(0, fy, w, c.h - fy, ' ', { bg: t.headBg });
+    footer.forEach((line, k) => c.text(0, fy + 1 + k, line, { fg: k === footer.length - 1 ? t.muted : t.text, bg: t.headBg }, w));
+    c.text(0, fy, ` ${LABEL_TEXT[v.label]}`, { fg: labelFg, bg: t.headBg, b: true }, w);
+    return c;
+}
+/** The PNG bytes of a framed view. */
+export function renderExportPng(v, now, opts = {}) {
+    const px = rasterizeCanvas(composeExportCanvas(v, now), opts);
+    return encodePng({ w: px.w, h: px.h, rgba: px.rgba });
+}
+/** The plain-text report: header, label, ages, the view's own lines, the local-only note. */
+export function renderExportText(v, now) {
+    const L = [];
+    L.push(`dexterm export · ${v.title}`);
+    if (v.mint)
+        L.push(`contract    ${v.mint}`);
+    L.push(`data        ${LABEL_TEXT[v.label]}`);
+    L.push(`exported    ${localStamp(now)} (local time) · ${new Date(now).toISOString()}`);
+    L.push(`data ages${v.label === 'replay' ? ' (on the replay clock)' : ''}`);
+    if (!v.ages.length)
+        L.push('  none reported for this view');
+    for (const a of v.ages)
+        L.push(`  ${a.name.padEnd(12)} ${(a.ageSec !== null ? fmtAge(a.ageSec) : a.state || 'n/a').padEnd(14)} ${a.source ?? ''}`.trimEnd());
+    L.push('');
+    L.push(...v.report);
+    L.push('');
+    L.push('Exported locally by dexterm. Nothing was uploaded. Model outputs are labelled as such. Not financial advice.');
+    return L.join('\n') + '\n';
+}
+/** ~/.dexterm/exports (DEXTERM_HOME overrides). */
+export function exportsDir(env = process.env) {
+    return join(dextermHome(env), 'exports');
+}
+const slug = (s) => s.replace(/[^A-Za-z0-9_-]+/g, '').slice(0, 16) || 'view';
+/** Write `<dir>/dexterm-<kind>-<subject>-<stamp>.png` and `.txt` (dir 0700, files 0600). */
+export function writeExport(v, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const dir = opts.dir ?? exportsDir(opts.env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const stamp = localStamp(now).replace(/[-: ]/g, '').replace(/^(\d{8})(\d{6})$/, '$1-$2');
+    const base = join(dir, `dexterm-${slug(v.kind)}-${slug(opts.subject ?? v.mint?.slice(0, 6) ?? '')}-${stamp}`);
+    const png = renderExportPng(v, now, opts.raster);
+    writeFileSync(`${base}.png`, png, { mode: 0o600 });
+    writeFileSync(`${base}.txt`, renderExportText(v, now), { mode: 0o600 });
+    return { png: `${base}.png`, txt: `${base}.txt`, bytes: png.length };
+}
+// ------------------------------------------------------------------------------------------ view builders
+const PANEL_NAMES = { market: 'market', candles: 'candles', authorities: 'authorities', holders: 'holders', rugcheck: 'rugcheck', goplus: 'goplus', trades: 'trades' };
+/** Data ages of a live token view, one per panel, from each panel's own fetch time. */
+export function tokenAges(v, now) {
+    return Object.keys(PANEL_NAMES).map((p) => {
+        const s = v.panels[p];
+        const ok = s.fetchedAt !== null && (s.state === 'ok' || s.stale);
+        return {
+            name: PANEL_NAMES[p], source: s.via,
+            ageSec: ok ? (now - s.fetchedAt) / 1000 : null,
+            state: ok ? (s.stale ? 'stale' : null) : s.state === 'needs-key' ? 'needs key' : s.state === 'error' ? `unavailable${s.reason ? ` (${s.reason})` : ''}` : s.state,
+        };
+    });
+}
+const yesNo = (b) => (b === null ? 'unknown' : b ? 'ENABLED' : 'revoked');
+/** The text report body for a live token view: the numbers on screen, each from its panel. */
+export function tokenReport(state, v, now) {
+    const L = [];
+    L.push(`coin        $${cleanText(v.symbol, 16)}${v.name ? ` · ${cleanText(v.name, 40)}` : ''} · ${v.launchpad}`);
+    L.push(`price       ${fmtPrice(v.price)}   5m ${fmtPct(v.chg.m5)}   1h ${fmtPct(v.chg.h1)}   6h ${fmtPct(v.chg.h6)}   24h ${fmtPct(v.chg.h24)}`);
+    L.push(`market cap  ${fmtUsd(v.mcap)}${v.mcapFlagged ? ' (flagged)' : ''}   liquidity ${fmtUsd(v.liq)}   vol 24h ${fmtUsd(v.vol24)}`);
+    L.push(`holders     ${v.holders ?? '—'}   top-10 ${v.top10 === null ? '—' : `${v.top10.toFixed(1)}%`}   dev ${v.dev === null ? '—' : `${v.dev.toFixed(1)}%`}${v.holdersSample ? `   (${v.holdersSample})` : ''}`);
+    L.push(`age         ${v.ageMin === null ? '—' : fmtAge(v.ageMin * 60)}`);
+    L.push(`authorities mint ${yesNo(v.mintAuth)} · freeze ${yesNo(v.freezeAuth)}${v.riskyExtensions.length ? ` · risky extensions: ${v.riskyExtensions.join(', ')}` : ''}`);
+    if (v.rug)
+        L.push(`rugcheck    score ${v.rug.score ?? '—'} · ${v.rug.risks.length} risk${v.rug.risks.length === 1 ? '' : 's'}${v.rug.risks.length ? `: ${v.rug.risks.slice(0, 4).map((r) => cleanText(r.name, 40)).join('; ')}` : ''}${v.rug.lpLockedPct !== null ? ` · LP locked ${v.rug.lpLockedPct.toFixed(0)}%` : ''}`);
+    if (v.flags.length)
+        L.push(`flags       ${v.flags.join(', ')}`);
+    const row = state.screener.rows.find((r) => r.mint === v.mint);
+    const p = row ? rugP(row) : null;
+    if (p !== null)
+        L.push(`p(rug)      ${fmtRugP(p)} · model output: ${RUG_MODEL_LABEL} (a ranking, not a probability; see dexterm backtest)`);
+    const larp = state.larpByMint?.get(v.mint);
+    if (larp)
+        L.push(`LARP check  ${larp.verdict}${larp.confidence !== null ? ` · confidence ${larp.confidence.toFixed(2)}` : ''} · model output, ${fmtAge((now - larp.at) / 1000)} old · a risk flag, not a certificate`);
+    const links = [v.socialLinks.web, v.socialLinks.x, v.socialLinks.tg].filter((x) => !!x).map((u) => cleanText(u, 120));
+    if (links.length)
+        L.push(`links       ${links.join('  ')}  (advertised by the coin; unverified)`);
+    return L;
+}
+/** Plain text of every row of a canvas (the generic report body for screens without a dedicated builder). */
+export function canvasText(c) {
+    const out = [];
+    for (let y = 0; y < c.h; y++)
+        out.push(c.ch.slice(y * c.w, (y + 1) * c.w).join('').trimEnd());
+    while (out.length && out[out.length - 1] === '')
+        out.pop();
+    return out;
+}
+/**
+ * Render the current screen for export: CALM (no rain / glitch / scanlines), and without the toast, help card or
+ * GO-TO prompt on top. The state is restored afterwards, so the live loop is unaffected.
+ */
+export function renderCalmFrame(state, w, h) {
+    const v = state.vfx;
+    const saved = { intensity: v.intensity, toast: v.toast, overlay: state.overlay, goto: state.goto };
+    try {
+        v.intensity = 'off';
+        v.toast = null;
+        state.overlay = null;
+        state.goto = null;
+        return renderFrame(state, w, h);
+    }
+    finally {
+        v.intensity = saved.intensity;
+        v.toast = saved.toast;
+        state.overlay = saved.overlay;
+        state.goto = saved.goto;
+    }
+}
+/** The data label of what is on screen: seeded fixtures are SAMPLE, a `--replay` file is REPLAY, else LIVE. */
+export function dataLabelOf(state) {
+    return state.screener.source === 'fixtures' ? 'sample' : state.screener.source === 'replay' ? 'replay' : 'live';
+}
+/** Build the ExportView for whatever screen is showing (the token screen gets the full per-panel report). */
+export function exportViewFor(state, w, h, now) {
+    const canvas = renderCalmFrame(state, w, h);
+    const label = dataLabelOf(state);
+    const tv = state.screen === 'token' && label !== 'sample' ? state.live?.token?.view ?? null : null;
+    if (tv) {
+        return {
+            kind: 'token', title: `TOKEN · $${cleanText(tv.symbol, 16)}${tv.name ? ` · ${cleanText(tv.name, 32)}` : ''}`, mint: tv.mint,
+            label, canvas, ages: tokenAges(tv, now), report: tokenReport(state, tv, now),
+        };
+    }
+    const sample = label === 'sample' ? [{ name: 'all panels', source: 'seeded fixtures', ageSec: null, state: 'sample data' }] : [];
+    if (state.screen === 'token') {
+        const tk = state.token || state.fx.tokens[state.selected || 0];
+        return { kind: 'token', title: `TOKEN · $${cleanText(tk?.symbol ?? '?', 16)}`, mint: tk?.mint ?? null, label, canvas, ages: sample, report: canvasText(canvas) };
+    }
+    const ages = [...sample];
+    if (label !== 'sample' && state.screener.rows.length) {
+        const ts = state.screener.rows.map((r) => r.fetchedAt).filter((t) => typeof t === 'number' && Number.isFinite(t));
+        if (ts.length) {
+            ages.push({ name: 'rows newest', source: 'screener feed', ageSec: (now - Math.max(...ts)) / 1000 });
+            ages.push({ name: 'rows oldest', source: 'screener feed', ageSec: (now - Math.min(...ts)) / 1000 });
+        }
+    }
+    return { kind: state.screen, title: state.screen.toUpperCase(), mint: null, label, canvas, ages, report: canvasText(canvas) };
+}