dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/custom/src/themes.js

@@ -0,0 +1,176 @@
+// @dexterm/custom — user themes (task-1358 Tier 2). A theme file is `{ extends: <base>, tokens: {…} }` over
+// the app's colour tokens (SPEC §7.1 + VISUAL-V2 §2); `config.theme.overrides` patches single tokens of
+// whatever theme is active. Semantics never change (green up, red down, amber warn, coral AI): the validator
+// refuses a theme whose text / warnings would fall under a contrast floor against the panel, and one whose
+// `up` reads redder than its `down`, so a SHARED theme cannot hide a warning or make a sell look like a buy.
+// A theme that fails validation is not loaded; the app keeps the current theme and says which token failed.
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { validate, THEME_TOKENS, THEME_RAMPS, BASE_THEMES } from "./schema.js";
+export const THEME_FILE = /^[a-z][a-z0-9-]{0,39}\.json$/;
+// ---- contrast (WCAG 2.x relative luminance), a small copy of @dexterm/tui color.ts so the floor is checkable here
+function luminance(hex) {
+    const n = parseInt(hex.slice(1), 16);
+    const [r, g, b] = [(n >> 16) & 255, (n >> 8) & 255, n & 255].map((c) => { const s = c / 255; return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+export function contrast(a, b) {
+    const x = luminance(a), y = luminance(b);
+    return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05);
+}
+function hue(hex) {
+    const n = parseInt(hex.slice(1), 16);
+    const r = ((n >> 16) & 255) / 255, g = ((n >> 8) & 255) / 255, b = (n & 255) / 255;
+    const max = Math.max(r, g, b), min = Math.min(r, g, b), d = max - min;
+    if (d === 0)
+        return 0;
+    let h = max === r ? ((g - b) / d) % 6 : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
+    h *= 60;
+    return h < 0 ? h + 360 : h;
+}
+const isGreenish = (hex) => { const h = hue(hex); return h >= 60 && h <= 200; };
+const isReddish = (hex) => { const h = hue(hex); return h >= 320 || h <= 25; };
+// r5 (verifier): a hue band says nothing about a near-grey tint (#7f807f has hue 120°, #807f7f hue 0°) — up and down must
+// carry real colour and must be far apart to the eye. HSL saturation floor + CIE76 ΔE in Lab between the two.
+function saturation(hex) {
+    const n = parseInt(hex.slice(1), 16);
+    const r = ((n >> 16) & 255) / 255, g = ((n >> 8) & 255) / 255, b = (n & 255) / 255;
+    const max = Math.max(r, g, b), min = Math.min(r, g, b), d = max - min, l = (max + min) / 2;
+    return d === 0 ? 0 : d / (1 - Math.abs(2 * l - 1));
+}
+function lab(hex) {
+    const n = parseInt(hex.slice(1), 16);
+    const lin = [(n >> 16) & 255, (n >> 8) & 255, n & 255].map((c) => { const s = c / 255; return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; });
+    const [r, g, b] = lin;
+    const x = (0.4124 * r + 0.3576 * g + 0.1805 * b) / 0.95047, y = 0.2126 * r + 0.7152 * g + 0.0722 * b, z = (0.0193 * r + 0.1192 * g + 0.9505 * b) / 1.08883;
+    const f = (t) => (t > 0.008856 ? Math.cbrt(t) : 7.787 * t + 16 / 116);
+    return [116 * f(y) - 16, 500 * (f(x) - f(y)), 200 * (f(y) - f(z))];
+}
+/** CIE76 colour difference between two hex colours (0 = identical; ~2 just noticeable; built-in up/down pairs are > 80). */
+export function deltaE(a, b) {
+    const [l1, a1, b1] = lab(a), [l2, a2, b2] = lab(b);
+    return Math.hypot(l1 - l2, a1 - a2, b1 - b2);
+}
+/** The least HSL saturation `up` and `down` may have (the built-ins sit at 0.63–0.91; a grey tint is ≈ 0). */
+export const UP_DOWN_MIN_SATURATION = 0.35;
+/** The least ΔE between `up` and `down` (the built-ins are 80–120; two greys are < 3). */
+export const UP_DOWN_MIN_DELTA_E = 40;
+/** The readability floors every theme must clear (named so a failure can say which pair). */
+export const CONTRAST_FLOORS = [
+    { fg: 'text', bg: 'bg', min: 4.5 }, { fg: 'text', bg: 'panel', min: 4.5 },
+    { fg: 'muted', bg: 'panel', min: 3 },
+    { fg: 'up', bg: 'bg', min: 3 }, { fg: 'down', bg: 'bg', min: 3 }, { fg: 'warn', bg: 'bg', min: 3 },
+    { fg: 'ai', bg: 'panel', min: 3 },
+];
+/** Semantic checks on a fully merged theme: the floors and the up/down hue guard. */
+export function checkThemeSemantics(t) {
+    const errors = [];
+    const hex = (k) => (typeof t[k] === 'string' && /^#[0-9a-fA-F]{6}$/.test(t[k]) ? t[k] : null);
+    for (const f of CONTRAST_FLOORS) {
+        const a = hex(f.fg), b = hex(f.bg);
+        if (!a || !b)
+            continue;
+        const c = contrast(a, b);
+        if (c < f.min)
+            errors.push({ path: `/tokens/${f.fg}`, msg: `${f.fg} on ${f.bg} contrast ${c.toFixed(2)} is under the ${f.min} floor (a theme may not hide ${f.fg === 'warn' ? 'warnings' : f.fg === 'text' ? 'numbers' : f.fg})` });
+    }
+    // r4 (verifier): the guard used to refuse only up-reddish / down-greenish, so an amber up with an amber down (or any
+    // hue outside both bands, or up == down) passed and a SELL could look like a BUY. Now up MUST read green/cyan and down
+    // MUST read red/pink — which also forces them apart — exactly what the header of this file promises.
+    const up = hex('up'), down = hex('down');
+    if (up && !isGreenish(up))
+        errors.push({ path: '/tokens/up', msg: `up (${up}, hue ${Math.round(hue(up))}°) must read green/cyan (hue 60–200°) so a buy never looks like a sell${isReddish(up) && down && isGreenish(down) ? ' (up and down are swapped)' : ''}` });
+    if (down && !isReddish(down))
+        errors.push({ path: '/tokens/down', msg: `down (${down}, hue ${Math.round(hue(down))}°) must read red/pink (hue 320–25°) so a sell never looks like a buy` });
+    if (up && down && up.toLowerCase() === down.toLowerCase())
+        errors.push({ path: '/tokens/down', msg: `down equals up (${down}): a sell would look like a buy` });
+    // r5: the band is not enough — a grey with a green hue is still grey, and two greys read the same
+    for (const [k, v] of [['up', up], ['down', down]]) {
+        if (v && saturation(v) < UP_DOWN_MIN_SATURATION)
+            errors.push({ path: `/tokens/${k}`, msg: `${k} (${v}) is too grey (saturation ${saturation(v).toFixed(2)} < ${UP_DOWN_MIN_SATURATION}): a buy or sell must carry real colour` });
+    }
+    if (up && down && deltaE(up, down) < UP_DOWN_MIN_DELTA_E)
+        errors.push({ path: '/tokens/down', msg: `up (${up}) and down (${down}) are too alike (ΔE ${deltaE(up, down).toFixed(1)} < ${UP_DOWN_MIN_DELTA_E}): a sell would look like a buy` });
+    return errors;
+}
+/** Merge a validated user theme over its base. The result carries the user theme's name. */
+export function resolveTheme(doc, bases, overrides = {}) {
+    const schemaErrors = validate('userTheme', doc);
+    if (schemaErrors.length)
+        return { theme: null, errors: schemaErrors };
+    const base = bases[doc.extends];
+    if (!base)
+        return { theme: null, errors: [{ path: '/extends', msg: `unknown base theme ${doc.extends}` }] };
+    const merged = { ...structuredClone(base), ...sanitizeTokens(doc.tokens ?? {}), ...sanitizeTokens(overrides), name: doc.name };
+    const sem = checkThemeSemantics(merged);
+    return sem.length ? { theme: null, errors: sem } : { theme: merged, errors: [] };
+}
+/** Keep only known tokens (schema-validated callers pass clean input; this is defence in depth). */
+function sanitizeTokens(tokens) {
+    const out = {};
+    for (const [k, v] of Object.entries(tokens)) {
+        if (THEME_TOKENS.includes(k) && typeof v === 'string')
+            out[k] = v;
+        else if (THEME_RAMPS.includes(k) && Array.isArray(v) && v.length === 4)
+            out[k] = [...v];
+        else if (k === 'logo' && Array.isArray(v) && v.length === 3)
+            out[k] = [...v];
+    }
+    return out;
+}
+/** Apply `config.theme.overrides` to an already-resolved (built-in or user) theme, with the same semantic guard. */
+export function applyOverrides(theme, overrides) {
+    if (!overrides || !Object.keys(overrides).length)
+        return { theme, errors: [] };
+    const errors = validate({ type: 'object', additional: false, props: Object.fromEntries([...THEME_TOKENS.map((t) => [t, 'hex']), ...THEME_RAMPS.map((t) => [t, 'ramp'])]) }, overrides, '/theme/overrides');
+    if (errors.length)
+        return { theme, errors };
+    const merged = { ...theme, ...sanitizeTokens(overrides) };
+    const sem = checkThemeSemantics(merged);
+    return sem.length ? { theme, errors: sem.map((e) => ({ ...e, path: e.path.replace('/tokens', '/theme/overrides') })) } : { theme: merged, errors: [] };
+}
+export const themesDir = (home) => join(home, 'themes');
+/** User themes: ~/.dexterm/themes/<name>.json (file name = theme name) plus `config.theme.user`. Bad files are reported, not thrown. */
+export function listUserThemes(home, config) {
+    const out = [];
+    for (const [name, doc] of Object.entries(config?.theme?.user ?? {}))
+        out.push({ name, path: null, doc: { ...doc, name } });
+    let files = [];
+    try {
+        files = readdirSync(themesDir(home)).filter((f) => THEME_FILE.test(f)).sort();
+    }
+    catch {
+        return out;
+    }
+    for (const f of files) {
+        const path = join(themesDir(home), f);
+        const name = f.slice(0, -5);
+        try {
+            if (statSync(path).isSymbolicLink())
+                continue;
+            const raw = JSON.parse(readFileSync(path, 'utf8'));
+            if (raw && typeof raw === 'object' && raw.name !== undefined && raw.name !== name)
+                throw new Error(`"name" must be "${name}" (the file name)`);
+            const doc = { ...raw, name };
+            const errors = validate('userTheme', doc);
+            if (errors.length)
+                throw new Error(`${errors[0].path || '/'} ${errors[0].msg}`);
+            if (BASE_THEMES.includes(name))
+                throw new Error(`"${name}" is a built-in theme name`);
+            const i = out.findIndex((t) => t.name === name);
+            const entry = { name, path, doc };
+            if (i >= 0)
+                out[i] = entry;
+            else
+                out.push(entry);
+        }
+        catch (e) {
+            out.push({ name, path, doc: { name, extends: 'cyberspace' }, error: e.message });
+        }
+    }
+    return out;
+}
+/** A starter theme document a user can edit (`dexterm theme init <name>`). */
+export function starterTheme(name, base = 'cyberspace') {
+    return { name, extends: base, tokens: { accent: '#00f0ff', borderFocus: '#39ff14' } };
+}

package/dist/packages/custom/src/widget-html.js

@@ -0,0 +1,222 @@
+// @dexterm/custom — PACK WIDGET HTML (task-1358 r2): the install-time copy of the popup host's page audit, so a pack whose
+// widget page carries a loader (the `__NONCE__` token, a <script src>, a <link>, a frame, <meta http-equiv>, `@import`)
+// is refused before it lands — the host refuses the same page again at open and at ticket issue.
+//
+// MIRROR of @dexterm/popup/src/widget-html.ts (the canonical copy, with the reasoning); the two zero-dependency packages
+// do not import each other (like WIDGET_TOPICS), and packages/cli/test/widget-1358.test.ts asserts that everything from
+// the import line down is byte-identical in both files. Edit the popup copy first, then copy it here.
+import { createHash } from 'node:crypto';
+/** Most inline <script> + <style> blocks one widget page may carry (the CSP header lists one hash per block). */
+export const WIDGET_INLINE_MAX = 64;
+/** CR LF and lone CR become LF, as the HTML parser's input-stream preprocessor does before it hashes an element's text. */
+export function normalizeWidgetHtml(html) { return html.replace(/\r\n?/g, '\n'); }
+/** The CSP hash-source for one inline block's exact text. */
+export function cspHash(text) { return `'sha256-${createHash('sha256').update(text, 'utf8').digest('base64')}'`; }
+/** Elements whose whole purpose is loading another document or resource: a widget page has no use for them. */
+const LOADER_TAGS = new Set(['link', 'iframe', 'frame', 'frameset', 'embed', 'object', 'applet', 'base', 'portal', 'fencedframe']);
+const SCRIPT_SRC_ATTRS = new Set(['src', 'href', 'xlink:href']);
+/**
+ * Read one start tag at `i` (which points at `<`): tag name + attributes, honouring quoted values (a `>` inside quotes
+ * does not end the tag). Returns null when `<` does not open a tag. Mirrors the tokenizer closely enough for the audit:
+ * any disagreement makes the browser see an element we did not hash, which the CSP then refuses — never the reverse.
+ */
+function readTag(html, i) {
+    const m = /^<([a-zA-Z][a-zA-Z0-9:-]*)/.exec(html.slice(i, i + 64));
+    if (!m)
+        return null;
+    const name = m[1].toLowerCase();
+    let p = i + m[0].length;
+    const attrs = new Map();
+    let selfClosing = false;
+    for (;;) {
+        while (p < html.length && /\s/.test(html[p]))
+            p++;
+        if (p >= html.length)
+            return null;
+        if (html[p] === '>') {
+            p++;
+            break;
+        }
+        if (html[p] === '/') {
+            selfClosing = true;
+            p++;
+            continue;
+        }
+        const a = /^([^\s"'>\/=]+)/.exec(html.slice(p, p + 256));
+        if (!a) {
+            p++;
+            continue;
+        } // a stray quote or `=`: the tokenizer skips it too
+        const key = a[1].toLowerCase();
+        p += a[0].length;
+        while (p < html.length && /\s/.test(html[p]))
+            p++;
+        let value = '';
+        if (html[p] === '=') {
+            p++;
+            while (p < html.length && /\s/.test(html[p]))
+                p++;
+            const q = html[p];
+            if (q === '"' || q === "'") {
+                const j = html.indexOf(q, p + 1);
+                if (j < 0)
+                    return null;
+                value = html.slice(p + 1, j);
+                p = j + 1;
+            }
+            else {
+                const v = /^[^\s>]*/.exec(html.slice(p));
+                value = v[0];
+                p += v[0].length;
+            }
+        }
+        if (!attrs.has(key))
+            attrs.set(key, value);
+    }
+    return { name, attrs, end: p, selfClosing };
+}
+/** Index of the `</name` that closes a raw-text element (script/style), case-insensitive, or -1. */
+function rawTextEnd(html, name, from) {
+    const re = new RegExp(`</${name}[\\s/>]`, 'ig');
+    re.lastIndex = from;
+    const m = re.exec(html);
+    return m ? m.index : -1;
+}
+/**
+ * The document without its HTML comments — what the parsers actually see. Only top-level `<!-- -->` is a comment: inside
+ * <script>/<style> the same characters are raw text (the CSS parser would still honour an `@import` written there).
+ */
+function withoutComments(html) {
+    let out = '', i = 0;
+    while (i < html.length) {
+        const lt = html.indexOf('<', i);
+        if (lt < 0) {
+            out += html.slice(i);
+            break;
+        }
+        out += html.slice(i, lt);
+        if (html.startsWith('<!--', lt)) {
+            const e = html.indexOf('-->', lt + 4);
+            i = e < 0 ? html.length : e + 3;
+            continue;
+        }
+        const tag = readTag(html, lt);
+        if (!tag) {
+            out += '<';
+            i = lt + 1;
+            continue;
+        }
+        if ((tag.name === 'script' || tag.name === 'style') && !tag.selfClosing) {
+            const e = rawTextEnd(html, tag.name, tag.end);
+            const end = e < 0 ? html.length : e;
+            out += html.slice(lt, end);
+            i = end;
+            continue;
+        }
+        out += html.slice(lt, tag.end);
+        i = tag.end;
+    }
+    return out;
+}
+/** Every start tag in the document, with the raw text of script/style elements (comments are skipped). */
+function* walk(html) {
+    let i = 0;
+    while (i < html.length) {
+        const lt = html.indexOf('<', i);
+        if (lt < 0)
+            return;
+        if (html.startsWith('<!--', lt)) {
+            const e = html.indexOf('-->', lt + 4);
+            i = e < 0 ? html.length : e + 3;
+            continue;
+        }
+        const tag = readTag(html, lt);
+        if (!tag) {
+            i = lt + 1;
+            continue;
+        }
+        if ((tag.name === 'script' || tag.name === 'style') && !tag.selfClosing) {
+            const e = rawTextEnd(html, tag.name, tag.end);
+            const raw = html.slice(tag.end, e < 0 ? html.length : e);
+            yield { tag, raw };
+            i = e < 0 ? html.length : e + 1;
+        }
+        else {
+            yield { tag };
+            i = tag.end;
+        }
+    }
+}
+/**
+ * The reasons a widget page is refused (empty = acceptable). Pure over the text; the CSP header is still the enforcement
+ * for everything this does not model (inline handlers, remote images, forms, runtime injection) — this names the things
+ * whose only purpose is loading code or documents from elsewhere, so a pack that tries is refused before it lands.
+ */
+export function auditWidgetHtml(html) {
+    const out = [];
+    const text = withoutComments(html); // an author may write about these in a comment; a parser never sees one
+    if (text.includes('__NONCE__'))
+        out.push('"__NONCE__" is not substituted into a pack page (write plain <script>/<style>: each block is allow-listed by its hash)');
+    let blocks = 0;
+    const seen = new Set();
+    const push = (s) => { if (!seen.has(s)) {
+        seen.add(s);
+        out.push(s);
+    } };
+    // r4: `@import` is a CSS construct — it is refused where CSS is parsed (a <style> block, a style="" attribute), not in
+    // a script string or prose (the verifier's probe pages tripped on the literal in JS text). A runtime-built <style> has
+    // no hash and an @import inserted through CSSOM is a stylesheet fetch with no style-src source: the header holds there.
+    const css = (s, where) => {
+        if (/@import\b/i.test(s))
+            push(`@import in ${where} (a stylesheet from elsewhere) is refused`);
+        if (/@\\/.test(s))
+            push(`an escaped CSS at-rule name (@\\…) in ${where} is refused`);
+    };
+    for (const { tag, raw } of walk(html)) {
+        if (tag.name === 'script') {
+            for (const a of SCRIPT_SRC_ATTRS)
+                if (tag.attrs.has(a))
+                    push(`<script ${a}=…> (a script from elsewhere) is refused: every script is inline`);
+            if (raw !== undefined && raw.length)
+                blocks++;
+        }
+        else if (tag.name === 'style') {
+            if (raw !== undefined && raw.length) {
+                blocks++;
+                css(raw, 'a <style> block');
+            }
+        }
+        else if (LOADER_TAGS.has(tag.name))
+            push(`<${tag.name}> is refused (it loads another document or resource)`);
+        else if (tag.name === 'meta' && tag.attrs.has('http-equiv'))
+            push('<meta http-equiv> is refused (headers are the host\'s)');
+        if (tag.attrs.has('style'))
+            css(tag.attrs.get('style') ?? '', 'a style attribute');
+    }
+    if (blocks > WIDGET_INLINE_MAX)
+        out.push(`${blocks} inline script/style blocks (max ${WIDGET_INLINE_MAX})`);
+    return out;
+}
+/**
+ * The CSP hash-sources for the page's inline blocks, deduplicated, in document order. Call it on the EXACT text that is
+ * served (after normalizeWidgetHtml); a block the browser sees differently simply does not run.
+ */
+export function inlineHashes(html) {
+    const scripts = [], styles = [];
+    for (const { tag, raw } of walk(html)) {
+        if (raw === undefined || !raw.length)
+            continue;
+        // a <script src> ignores its text in the browser (and the audit refused it anyway): nothing to hash
+        if (tag.name === 'script' && !tag.attrs.has('src')) {
+            const h = cspHash(raw);
+            if (!scripts.includes(h))
+                scripts.push(h);
+        }
+        else if (tag.name === 'style') {
+            const h = cspHash(raw);
+            if (!styles.includes(h))
+                styles.push(h);
+        }
+    }
+    return { scripts, styles };
+}

package/dist/packages/custom/src/workspace.js

@@ -0,0 +1,141 @@
+// @dexterm/custom — named workspaces (task-1358 Tier 1). A workspace is a JSON document: where to land
+// (screen), the theme / intensity to use, the screener preset/filter/sort, token-panel toggles, per-screen
+// pane trees for the layout solver, and the HUD popups to open together (task-1290 windows). The shipped
+// `default` reproduces today's screens byte for byte; `morning-hud` is the north-star "show me everything".
+//
+// Workspaces hold NO keys, NO trading settings and NO code: the schema is additional:false and a pack or a
+// Jarvis proposal that tries to smuggle anything else is refused by name (schema.ts). Switching a workspace
+// is a UI action: it can navigate, re-theme and open read-only popups; it can never arm, sign or confirm.
+import { validate, POPUP_KINDS, WORKSPACE_SCREENS } from "./schema.js";
+import { breakpoint, solve, treeFor, widgetsIn, widgetSpec } from "./layout.js";
+export const DEFAULT_WORKSPACE = 'default';
+export const MORNING_HUD = 'morning-hud';
+/**
+ * The shipped layout. It carries NO `screens` trees: a workspace without trees means "the renderers' own
+ * numbers" (spotlight 44 at ≥ 140 cols, chart 46 %, analyst max(46, 34 %)), which keeps every snapshot golden
+ * byte-identical. `builtinScreens()` is the editable tree form of the same layout (`dexterm workspace init`).
+ */
+export function defaultWorkspace() {
+    return { name: DEFAULT_WORKSPACE, description: 'The shipped layout (SPEC §4)', popups: [], start: 'screener' };
+}
+/**
+ * The north-star morning HUD (ROADMAP): "yo jarvis, show me everything" → the narrative board on the
+ * terminal, with the narrative board, the social/news feeds, the order plans and the chart of the highlighted
+ * coin as HUD windows. (Popup kinds are the host's: there is no separate positions/alerts window; plans
+ * carries the PAPER plan rows, the chart carries the held position, feeds carries KOL/news + alerts-worthy posts.)
+ */
+export function morningHudWorkspace() {
+    return {
+        name: MORNING_HUD,
+        description: 'Morning HUD: narrative board + feeds + order plans + chart popups, trenches feed on the screener',
+        start: 'narrative',
+        screener: { preset: 'trench' },
+        popups: [
+            { kind: 'narrative', x: 0.62, y: 0.04, w: 0.36, h: 0.46 },
+            { kind: 'feeds', x: 0.62, y: 0.52, w: 0.36, h: 0.44 },
+            { kind: 'plans', x: 0.02, y: 0.56, w: 0.28, h: 0.4 },
+            { kind: 'chart', mint: 'selected', x: 0.32, y: 0.56, w: 0.28, h: 0.4 },
+        ],
+    };
+}
+export function builtinWorkspaces() { return [defaultWorkspace(), morningHudWorkspace()]; }
+/**
+ * Schema + semantics: every widget a tree names must exist (built-in, or a `plugin:` id present in `registry`),
+ * so a shared workspace cannot name `shell.exec` and hope a renderer picks it up.
+ */
+export function validateWorkspace(ws, registry = {}) {
+    const errors = validate('workspace', ws);
+    if (errors.length)
+        return errors;
+    const screens = ws.screens ?? {};
+    for (const [screen, layout] of Object.entries(screens)) {
+        const trees = 'kind' in layout ? [layout] : ['wide', 'standard', 'compact'].map((b) => layout[b]).filter((t) => !!t);
+        for (const t of trees)
+            for (const id of widgetsIn(t))
+                if (!widgetSpec(id, registry))
+                    errors.push({ path: `/screens/${screen}`, msg: `unknown widget "${id}"` });
+    }
+    // task-1358 Tier 5: a `widget` popup must name the pack widget; other kinds must not carry one
+    (ws.popups ?? []).forEach((p, i) => {
+        if (p.kind === 'widget' && !p.widget)
+            errors.push({ path: `/popups/${i}`, msg: 'a widget popup needs "widget": "<pack>/<widget>"' });
+        if (p.kind !== 'widget' && p.widget !== undefined)
+            errors.push({ path: `/popups/${i}/widget`, msg: `only kind "widget" takes a widget ref` });
+    });
+    return errors;
+}
+/** Parse + validate a workspace document; throws a one-line error naming the first problem. */
+export function parseWorkspace(text, source = 'workspace') {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`${source}: not valid JSON (${e.message})`);
+    }
+    const errors = validateWorkspace(raw);
+    if (errors.length)
+        throw new Error(`${source}: ${errors[0].path || '/'} ${errors[0].msg}`);
+    return raw;
+}
+/** The screen the workspace lands on (start, else the screener). */
+export function workspaceStart(ws) { return ws.start ?? 'screener'; }
+const DEFAULT_NUMBERS = (w, h) => {
+    const bp = breakpoint(w);
+    return { spotlightW: bp === 'wide' ? 44 : 0, pairSpotlightW: bp === 'wide' ? 46 : 0, chartFrac: 0.46, analystW: bp === 'compact' ? 0 : bp === 'wide' ? Math.max(46, Math.floor(w * 0.34)) : 40 };
+};
+export function solveScreen(ws, screen, rect) {
+    const tree = treeFor(ws?.screens?.[screen], breakpoint(rect.w));
+    return tree ? solve(tree, rect) : null;
+}
+/** Solve the workspace for a terminal size and read the renderer numbers off the panes (defaults when a tree is absent). */
+export function layoutNumbers(ws, w, h) {
+    const base = DEFAULT_NUMBERS(w, h);
+    if (!ws?.screens)
+        return base;
+    const body = { x: 0, y: 2, w, h: Math.max(1, h - 3) };
+    const out = { ...base };
+    const scr = solveScreen(ws, 'screener', body);
+    if (scr)
+        out.spotlightW = scr.panes.find((p) => p.widget === 'screener.spotlight')?.rect.w ?? 0;
+    const np = solveScreen(ws, 'newpairs', body);
+    if (np)
+        out.pairSpotlightW = np.panes.find((p) => p.widget === 'newpairs.spotlight')?.rect.w ?? 0;
+    const tk = solveScreen(ws, 'token', body);
+    if (tk) {
+        const chart = tk.panes.find((p) => p.widget === 'token.chart');
+        if (chart)
+            out.chartFrac = Math.max(0.2, Math.min(0.85, chart.rect.h / body.h));
+        out.analystW = tk.panes.find((p) => p.widget === 'analyst.panel')?.rect.w ?? 0;
+        // the analyst panel is a tree choice; the renderer still hides it under --no-ai (state.aiOpen === false)
+    }
+    return out;
+}
+export function captureWorkspace(name, snap) {
+    const start = WORKSPACE_SCREENS.includes(snap.screen) ? snap.screen : 'screener';
+    const ws = { name, description: `saved from the ${snap.screen} screen`, start, theme: snap.theme, intensity: snap.intensity };
+    if (snap.priceMode && snap.priceMode !== 'price')
+        ws.priceMode = snap.priceMode;
+    if (snap.screens)
+        ws.screens = structuredClone(snap.screens);
+    const sc = {};
+    if (snap.screener?.preset)
+        sc.preset = snap.screener.preset;
+    if (snap.screener?.filter)
+        sc.filter = snap.screener.filter.slice(0, 200);
+    if (snap.screener?.sort)
+        sc.sort = snap.screener.sort;
+    if (Object.keys(sc).length)
+        ws.screener = sc;
+    if (snap.token && Object.keys(snap.token).length)
+        ws.token = { ...snap.token };
+    if (snap.popups?.length || snap.widgets?.length)
+        ws.popups = [
+            ...(snap.popups ?? []).filter((k) => k !== 'widget').map((kind) => ({ kind, ...(kind === 'chart' || kind === 'bubbles' || kind === 'token' ? { mint: 'selected' } : {}) })),
+            ...(snap.widgets ?? []).map((widget) => ({ kind: 'widget', widget })),
+        ];
+    const errors = validateWorkspace(ws);
+    if (errors.length)
+        throw new Error(`${errors[0].path || '/'} ${errors[0].msg}`);
+    return ws;
+}