dexterm-cli 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,213 @@
+// @dexterm/custom — the config loader (task-1358 Tier 1). ~/.dexterm/config.json is the canonical,
+// machine-written config (0600, `version: 4`); workspaces are one JSON file each in ~/.dexterm/workspaces/,
+// user themes in ~/.dexterm/themes/. THIS MODULE NEVER READS A KEY FILE: `<name>.key` files are the data
+// layer's business, and the only thing the loader does with a key is move one OUT of an old config.
+//
+// Failure model: a missing config is the defaults (nothing is written until the user saves something); an
+// unreadable or invalid config keeps the defaults and reports the error so the app can show a toast and
+// `dexterm doctor` can name the file. Nothing here throws on I/O except `saveConfig` / `writeWorkspace`.
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, renameSync, unlinkSync, statSync, appendFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { CONFIG_VERSION, defaultConfig, migrate, validateConfig } from "./schema.js";
+import { applyOps } from "./schema.js";
+import { builtinWorkspaces, parseWorkspace, validateWorkspace } from "./workspace.js";
+/** `DEXTERM_HOME` overrides `~/.dexterm` (tests point it at a temp dir). Same rule as the CLI's boot-state. */
+export function dextermHome(env = process.env) {
+    return env.DEXTERM_HOME && env.DEXTERM_HOME.trim() ? env.DEXTERM_HOME : join(homedir(), '.dexterm');
+}
+export const configPath = (home) => join(home, 'config.json');
+export const journalPath = (home) => join(home, 'config.journal.jsonl');
+export const workspacesDir = (home) => join(home, 'workspaces');
+export const packsDir = (home) => join(home, 'packs');
+const sha = (s) => createHash('sha256').update(s).digest('hex');
+/** Load (and migrate if needed) ~/.dexterm/config.json. Never throws. */
+export function loadConfig(home) {
+    const path = configPath(home);
+    const base = { config: defaultConfig(), path, missing: false, ok: true, errors: [], notes: [], extractedKeyFiles: [], hash: sha('') };
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { ...base, missing: true };
+        return { ...base, ok: false, errors: [`${path}: ${e.message}`] };
+    }
+    base.hash = sha(text);
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        return { ...base, ok: false, errors: [`${path}: not valid JSON (${e.message}); keeping defaults`] };
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return { ...base, ok: false, errors: [`${path}: expected an object; keeping defaults`] };
+    const version = Number(raw.version ?? 1);
+    if (version === CONFIG_VERSION) {
+        const errors = validateConfig(raw);
+        if (errors.length)
+            return { ...base, ok: false, errors: errors.slice(0, 5).map((e) => `${path}: ${e.path || '/'} ${e.msg}`) };
+        return { ...base, config: raw };
+    }
+    // older (or newer) config: migrate, back up, write the new one, write extracted keys to <name>.key (0600)
+    let m;
+    try {
+        m = migrate(raw);
+    }
+    catch (e) {
+        return { ...base, ok: false, errors: [`${path}: ${e.message}`] };
+    }
+    if (m.errors.length)
+        return { ...base, ok: false, errors: m.errors.slice(0, 5).map((e) => `${path}: after migration ${e.path || '/'} ${e.msg}`) };
+    const out = { ...base, config: m.config, notes: [...m.notes] };
+    try {
+        writeFileSync(`${path}.bak-v${m.from}`, text, { mode: 0o600 });
+        for (const [name, value] of Object.entries(m.extractedKeys)) {
+            const kf = join(home, `${name}.key`);
+            if (!existsSync(kf)) {
+                writeFileSync(kf, value + '\n', { mode: 0o600 });
+                out.extractedKeyFiles.push(`${name}.key`);
+            }
+            else
+                out.notes.push(`${name}.key already exists; the key in config.json was dropped, not copied`);
+        }
+        saveConfig(home, m.config);
+        out.notes.push(`migrated config.json v${m.from} → v${CONFIG_VERSION} (backup: config.json.bak-v${m.from})`);
+        out.hash = sha(readFileSync(path, 'utf8'));
+    }
+    catch (e) {
+        out.ok = false;
+        out.errors.push(`${path}: migration could not be written (${e.message}); using the migrated config for this run only`);
+    }
+    return out;
+}
+/** Validate + write config.json atomically (0600, directory 0700). Throws on a schema error or I/O failure. */
+export function saveConfig(home, config) {
+    const errors = validateConfig(config);
+    if (errors.length)
+        throw new Error(`config invalid: ${errors[0].path || '/'} ${errors[0].msg}`);
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    const path = configPath(home);
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, path);
+}
+export function readJournal(home) {
+    try {
+        return readFileSync(journalPath(home), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}
+/** Apply ops to the stored config, journal them with the inverse, and save. Throws (and writes nothing) on a bad op or schema error. */
+export function applyAndJournal(home, ops, meta) {
+    const loaded = loadConfig(home);
+    if (!loaded.ok)
+        throw new Error(loaded.errors[0]);
+    const { doc, inverse } = applyOps(loaded.config, ops);
+    const errors = validateConfig(doc);
+    if (errors.length)
+        throw new Error(`refused: ${errors[0].path || '/'} ${errors[0].msg}`);
+    saveConfig(home, doc);
+    const after = sha(readFileSync(configPath(home), 'utf8'));
+    const seq = (readJournal(home).at(-1)?.seq ?? 0) + 1;
+    const entry = { seq, at: meta.now ?? Date.now(), kind: meta.kind ?? 'apply', actor: meta.actor, why: meta.why, ops, inverse, hashBefore: loaded.hash, hashAfter: after };
+    appendFileSync(journalPath(home), JSON.stringify(entry) + '\n', { mode: 0o600 });
+    return { config: doc, entry };
+}
+/** Undo the last applied/redone change if the config has not been edited by hand since. */
+export function undoLast(home, now = Date.now()) {
+    const j = readJournal(home);
+    // the last entry that can be undone: walk back skipping already-undone applies
+    let depth = 0;
+    for (let i = j.length - 1; i >= 0; i--) {
+        const e = j[i];
+        if (e.kind === 'undo') {
+            depth++;
+            continue;
+        }
+        if (depth > 0) {
+            depth--;
+            continue;
+        }
+        const current = loadConfig(home);
+        if (current.hash !== e.hashAfter)
+            return { ok: false, reason: 'cannot undo: config.json changed since (edited by hand?)' };
+        try {
+            const { entry } = applyAndJournal(home, e.inverse, { actor: 'user', why: `undo #${e.seq}`, kind: 'undo', now });
+            return { ok: true, entry };
+        }
+        catch (err) {
+            return { ok: false, reason: `cannot undo: ${err.message}` };
+        }
+    }
+    return { ok: false, reason: 'nothing to undo' };
+}
+// ------------------------------------------------------------------ workspaces on disk
+export const WS_FILE = /^[a-z][a-z0-9-]{0,39}\.json$/;
+/** Built-ins first (default, morning-hud), then the user's files; a user file with a built-in's name REPLACES it. Bad files are listed with their error. */
+export function listWorkspaces(home) {
+    const out = builtinWorkspaces().map((w) => ({ name: w.name, path: null, workspace: w, builtin: true }));
+    const dir = workspacesDir(home);
+    let files = [];
+    try {
+        files = readdirSync(dir).filter((f) => WS_FILE.test(f)).sort();
+    }
+    catch {
+        return out;
+    }
+    for (const f of files) {
+        const path = join(dir, f);
+        const name = f.slice(0, -5);
+        try {
+            if (statSync(path).isSymbolicLink())
+                continue;
+            const ws = parseWorkspace(readFileSync(path, 'utf8'), f);
+            if (ws.name !== name)
+                throw new Error(`${f}: "name" must be "${name}" (the file name)`);
+            const i = out.findIndex((w) => w.name === name);
+            const entry = { name, path, workspace: ws, builtin: false };
+            if (i >= 0)
+                out[i] = entry;
+            else
+                out.push(entry);
+        }
+        catch (e) {
+            out.push({ name, path, workspace: { name }, builtin: false, error: e.message });
+        }
+    }
+    return out;
+}
+export function readWorkspace(home, name) {
+    return listWorkspaces(home).find((w) => w.name === name && !w.error)?.workspace ?? null;
+}
+/** Write a workspace file (validated, 0600). Throws on a bad document or name. */
+export function writeWorkspace(home, ws) {
+    const errors = validateWorkspace(ws);
+    if (errors.length)
+        throw new Error(`workspace invalid: ${errors[0].path || '/'} ${errors[0].msg}`);
+    if (ws.name.includes('/'))
+        throw new Error('a user workspace name cannot contain "/" (reserved for packs)');
+    mkdirSync(workspacesDir(home), { recursive: true, mode: 0o700 });
+    const path = join(workspacesDir(home), `${ws.name}.json`);
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(ws, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, path);
+    return path;
+}
+export function removeWorkspace(home, name) {
+    if (!/^[a-z][a-z0-9-]{0,39}$/.test(name))
+        return false;
+    const path = join(workspacesDir(home), `${name}.json`);
+    try {
+        unlinkSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,10 @@
+// @dexterm/custom — public surface (task-1358).
+export * from "./schema.js";
+export * from "./layout.js";
+export * from "./workspace.js";
+export * from "./config.js";
+export * from "./themes.js";
+export * from "./keymap.js";
+export * from "./rules.js";
+export * from "./packs.js";
+export * from "./widget-html.js";

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

@@ -0,0 +1,107 @@
+// @dexterm/custom — keymap overrides (task-1358 Tier 2). `config.keymap.global[action] = keys[]` and
+// `config.keymap.screens[screen][action] = keys[]` re-bind the app's actions (the AppAction ids of
+// @dexterm/tui) over the shipped defaults. Validation refuses what a shared config must never do:
+//   * RESERVED KEYS cannot be assigned to anything: ctrl+c (quit), esc, enter, y / Y (confirm), ! (panic);
+//   * RESERVED ACTIONS keep their default keys: quit, back, alert.confirm / alert.dismiss, plans.arm,
+//     plans.panic, plans.gate (the money-adjacent confirms and the panic key);
+//   * no two actions on the same key within one scope (global, or one screen); a global key may still be
+//     shadowed by a screen binding, as the defaults already do;
+//   * a chord prefix (the first key of "ctrl+w s") cannot also be bound on its own;
+//   * at most 4 keys per action, every key a valid id (the KEY pattern in schema.ts).
+// Pure: takes the default binding table, returns a new one plus the errors. Nothing here reads a file.
+import { validate } from "./schema.js";
+export const RESERVED_KEYS = new Set(['ctrl+c', 'esc', 'enter', 'y', 'Y', '!']);
+export const RESERVED_ACTIONS = new Set(['quit', 'back', 'alert.confirm', 'alert.dismiss', 'plans.arm', 'plans.panic', 'plans.gate']);
+/**
+ * Layer `cfg` over `defaults`. On ANY error the defaults are returned untouched (a half-applied keymap is worse
+ * than none) with every problem listed, so the user fixes the file once.
+ */
+export function applyKeymapConfig(defaults, cfg) {
+    const errors = cfg ? validate('keymap', cfg, '/keymap') : [];
+    const overridden = [];
+    if (!cfg || errors.length)
+        return { bindings: defaults.map((b) => ({ ...b, keys: [...b.keys] })), errors, overridden };
+    const bindings = defaults.map((b) => ({ ...b, keys: [...b.keys] }));
+    const known = new Set(defaults.map((b) => b.action));
+    const globalLabel = new Map();
+    for (const b of defaults)
+        if (!b.screen)
+            globalLabel.set(b.action, b.label);
+    const apply = (screen, action, keys) => {
+        const where = screen ? `/keymap/screens/${screen}/${action}` : `/keymap/global/${action}`;
+        if (!known.has(action)) {
+            errors.push({ path: where, msg: `unknown action "${action}"` });
+            return;
+        }
+        if (RESERVED_ACTIONS.has(action)) {
+            errors.push({ path: where, msg: `"${action}" keeps its default keys (reserved: confirm / dismiss / panic / quit / back)` });
+            return;
+        }
+        for (const k of keys) {
+            const parts = k.split(' ');
+            if (parts.some((p) => RESERVED_KEYS.has(p)) && !(parts.length === 2 && !RESERVED_KEYS.has(parts[0]))) {
+                errors.push({ path: where, msg: `"${k}" is reserved (${[...RESERVED_KEYS].join(' ')})` });
+                return;
+            }
+        }
+        const i = bindings.findIndex((b) => b.action === action && (screen ? b.screen === screen : !b.screen));
+        if (i >= 0)
+            bindings[i] = { ...bindings[i], keys: [...keys] };
+        else
+            bindings.push({ keys: [...keys], action: action, label: globalLabel.get(action) ?? defaults.find((b) => b.action === action)?.label, screen: screen ?? undefined });
+        overridden.push({ action: action, screen, keys: [...keys] });
+    };
+    for (const [action, keys] of Object.entries(cfg.global ?? {}))
+        apply(null, action, keys);
+    for (const [screen, table] of Object.entries(cfg.screens ?? {})) {
+        if (!/^[a-z]+$/.test(screen)) {
+            errors.push({ path: `/keymap/screens/${screen}`, msg: 'bad screen name' });
+            continue;
+        }
+        for (const [action, keys] of Object.entries(table))
+            apply(screen, action, keys);
+    }
+    if (!errors.length)
+        errors.push(...collisions(bindings));
+    if (errors.length)
+        return { bindings: defaults.map((b) => ({ ...b, keys: [...b.keys] })), errors, overridden: [] };
+    return { bindings, errors: [], overridden };
+}
+/** Two actions on one key within the same scope, or a chord prefix bound on its own. */
+export function collisions(bindings) {
+    const errors = [];
+    const byScope = new Map();
+    const prefixes = new Set();
+    for (const b of bindings)
+        for (const k of b.keys) {
+            const sp = k.indexOf(' ');
+            if (sp > 0)
+                prefixes.add(k.slice(0, sp));
+        }
+    for (const b of bindings) {
+        const scope = b.screen ?? '';
+        let m = byScope.get(scope);
+        if (!m) {
+            m = new Map();
+            byScope.set(scope, m);
+        }
+        for (const k of b.keys) {
+            const other = m.get(k);
+            if (other && other !== b.action)
+                errors.push({ path: scope ? `/keymap/screens/${scope}` : '/keymap/global', msg: `"${k}" is bound to both ${other} and ${b.action}` });
+            m.set(k, b.action);
+            if (prefixes.has(k))
+                errors.push({ path: scope ? `/keymap/screens/${scope}` : '/keymap/global', msg: `"${k}" starts a chord and cannot also be bound alone (${b.action})` });
+        }
+    }
+    return errors;
+}
+/** `dexterm keymap`: one line per binding, user overrides marked with `·`. */
+export function renderKeymap(r, screen) {
+    const ov = new Set(r.overridden.map((o) => `${o.screen ?? ''}|${o.action}`));
+    const rows = r.bindings.filter((b) => !screen || !b.screen || b.screen === screen);
+    const lines = rows.map((b) => `${ov.has(`${b.screen ?? ''}|${b.action}`) ? '·' : ' '} ${(b.screen ?? 'global').padEnd(10)} ${b.action.padEnd(22)} ${b.keys.join(' / ').padEnd(24)} ${b.label ?? ''}`);
+    if (r.errors.length)
+        lines.unshift(...r.errors.map((e) => `✗ ${e.path} ${e.msg}`), '  (keymap config refused: the defaults are in use)');
+    return lines.join('\n');
+}

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

@@ -0,0 +1,235 @@
+// @dexterm/custom — layout engine (task-1358, from the task-1288 design): a pane tree (splits + widget panes)
+// solved into integer rects for a screen size and breakpoint. Deterministic, pure, no canvas dependency.
+//
+// Rules (they mirror the SPEC §7.4 column-drop rule so users get one mental model):
+//   * breakpoints: compact < 100 cols, standard < 140, wide ≥ 140 (same as @dexterm/tui);
+//   * a pane with collapseBelow: 'wide' is dropped at standard/compact, etc.;
+//   * every widget has a minimum size; when a split cannot give every child its minimum, the LEAF with the
+//     highest priority number among the overflowing children is dropped and the split re-solved (priority 0
+//     never drops: it is solved anyway and the renderer clips);
+//   * fixed sizes come first, the remainder is shared by weight with largest-remainder rounding so the
+//     rects tile exactly (no 1-cell seams); an optional 1-cell gutter between children rains.
+import { BUILTIN_WIDGETS } from "./schema.js";
+export function breakpoint(w) { return w < 100 ? 'compact' : w < 140 ? 'standard' : 'wide'; }
+const BP_RANK = { compact: 0, standard: 1, wide: 2 };
+export function widgetSpec(id, registry = {}) {
+    return BUILTIN_WIDGETS[id] ?? registry[id] ?? null;
+}
+/** Pick the tree for this breakpoint: per-breakpoint object (nearest smaller defined, else larger) or the single tree. */
+export function treeFor(layout, bp) {
+    if (!layout)
+        return null;
+    if ('kind' in layout)
+        return layout;
+    const order = ['wide', 'standard', 'compact'];
+    const start = order.indexOf(bp);
+    for (let i = start; i < order.length; i++) {
+        const t = layout[order[i]];
+        if (t)
+            return t;
+    }
+    for (let i = start - 1; i >= 0; i--) {
+        const t = layout[order[i]];
+        if (t)
+            return t;
+    }
+    return null;
+}
+function visible(node, bp) {
+    if (node.kind === 'pane')
+        return !node.collapseBelow || BP_RANK[bp] >= BP_RANK[node.collapseBelow];
+    return node.children.some((c) => visible(c.node, bp));
+}
+/** Minimum size a node needs (sum along its axis, max across), ignoring collapsed children. */
+function minSize(node, bp, registry) {
+    if (node.kind === 'pane') {
+        const spec = widgetSpec(node.widget, registry);
+        return spec ? { ...spec.min } : { w: 10, h: 3 };
+    }
+    const kids = node.children.filter((c) => visible(c.node, bp));
+    const g = node.gutter ? Math.max(0, kids.length - 1) : 0;
+    let along = g, across = 0;
+    for (const c of kids) {
+        const m = minSize(c.node, bp, registry);
+        if (node.dir === 'row') {
+            along += c.fixed ?? m.w;
+            across = Math.max(across, m.h);
+        }
+        else {
+            along += c.fixed ?? m.h;
+            across = Math.max(across, m.w);
+        }
+    }
+    return node.dir === 'row' ? { w: along, h: across } : { w: across, h: along };
+}
+/** Largest-remainder share of `total` by weights after fixed sizes; integer sizes that sum to total. */
+function share(children, total) {
+    const fixedSum = children.reduce((s, c) => s + (c.fixed ?? 0), 0);
+    const flex = children.filter((c) => c.fixed === undefined);
+    const wsum = flex.reduce((s, c) => s + (c.weight ?? 1), 0) || 1;
+    const remain = Math.max(0, total - fixedSum);
+    const sizes = children.map((c) => (c.fixed !== undefined ? Math.min(c.fixed, total) : 0));
+    const raw = flex.map((c) => (remain * (c.weight ?? 1)) / wsum);
+    const floors = raw.map(Math.floor);
+    let left = remain - floors.reduce((a, b) => a + b, 0);
+    const order = raw.map((r, i) => [r - floors[i], i]).sort((a, b) => b[0] - a[0]);
+    for (const [, i] of order) {
+        if (left <= 0)
+            break;
+        floors[i] += 1;
+        left -= 1;
+    }
+    let fi = 0;
+    for (let i = 0; i < children.length; i++)
+        if (children[i].fixed === undefined)
+            sizes[i] = floors[fi++];
+    // if fixed sizes overflow, trim from the last fixed child
+    let over = sizes.reduce((a, b) => a + b, 0) - total;
+    for (let i = children.length - 1; i >= 0 && over > 0; i--) {
+        const cut = Math.min(over, sizes[i]);
+        sizes[i] -= cut;
+        over -= cut;
+    }
+    return sizes;
+}
+/** Solve a tree into panes for `rect`. */
+export function solve(tree, rect, opts = {}) {
+    const bp = opts.breakpoint ?? breakpoint(rect.w);
+    const registry = opts.registry ?? {};
+    const out = { panes: [], dropped: [], gutters: [], breakpoint: bp };
+    solveNode(tree, rect, bp, registry, out);
+    return out;
+}
+function solveNode(node, rect, bp, registry, out) {
+    if (!visible(node, bp)) {
+        collect(node, (p) => out.dropped.push({ widget: p.widget, reason: `collapsed below ${p.collapseBelow}` }));
+        return;
+    }
+    if (node.kind === 'pane') {
+        const m = minSize(node, bp, registry);
+        if (rect.w < m.w || rect.h < m.h) {
+            if ((node.priority ?? 1) === 0)
+                out.panes.push({ widget: node.widget, rect, node, clipped: true });
+            else
+                out.dropped.push({ widget: node.widget, reason: `needs ${m.w}×${m.h}, has ${rect.w}×${rect.h}` });
+            return;
+        }
+        out.panes.push({ widget: node.widget, rect, node });
+        return;
+    }
+    for (const c of node.children)
+        if (!visible(c.node, bp))
+            collect(c.node, (p) => out.dropped.push({ widget: p.widget, reason: `collapsed below ${p.collapseBelow}` }));
+    let kids = node.children.filter((c) => visible(c.node, bp));
+    // Drop the highest-priority LEAF among the children that actually overflow (never an innocent sibling)
+    // until the minimums fit. Across-axis overflow (a child too tall for a row) is resolved inside that child;
+    // along-axis overflow (the sum too wide) may take a leaf from any child.
+    for (;;) {
+        const need = minSize({ ...node, children: kids }, bp, registry);
+        const fits = need.w <= rect.w && need.h <= rect.h;
+        if (fits || kids.length === 0)
+            break;
+        const across = node.dir === 'row' ? 'h' : 'w';
+        const over = kids.filter((c) => minSize(c.node, bp, registry)[across] > rect[across]);
+        const victim = highestLeaf({ ...node, children: over.length ? over : kids });
+        if (!victim || (victim.priority ?? 1) === 0)
+            break;
+        out.dropped.push({ widget: victim.widget, reason: `no room at ${rect.w}×${rect.h} (priority ${victim.priority ?? 1})` });
+        kids = kids.map((c) => ({ ...c, node: removeLeaf(c.node, victim) })).filter((c) => c.node !== null);
+    }
+    if (!kids.length)
+        return;
+    const g = node.gutter ? 1 : 0;
+    const along = node.dir === 'row' ? rect.w : rect.h;
+    const sizes = share(kids, along - g * (kids.length - 1));
+    let pos = node.dir === 'row' ? rect.x : rect.y;
+    kids.forEach((c, i) => {
+        const r = node.dir === 'row' ? { x: pos, y: rect.y, w: sizes[i], h: rect.h } : { x: rect.x, y: pos, w: rect.w, h: sizes[i] };
+        if (r.w > 0 && r.h > 0)
+            solveNode(c.node, r, bp, registry, out);
+        pos += sizes[i];
+        if (g && i < kids.length - 1) {
+            out.gutters.push(node.dir === 'row' ? { x: pos, y: rect.y, w: 1, h: rect.h } : { x: rect.x, y: pos, w: rect.w, h: 1 });
+            pos += 1;
+        }
+    });
+}
+/** The pane with the highest priority number in a subtree (ties: the later one in document order). */
+function highestLeaf(node) {
+    let best = null;
+    collect(node, (p) => { if (!best || (p.priority ?? 1) >= (best.priority ?? 1))
+        best = p; });
+    return best;
+}
+/** Remove one pane (by identity) from a subtree; splits left with no children collapse to null. */
+function removeLeaf(node, leaf) {
+    if (node.kind === 'pane')
+        return node === leaf ? null : node;
+    const children = node.children.map((c) => ({ ...c, node: removeLeaf(c.node, leaf) })).filter((c) => c.node !== null);
+    return children.length ? { ...node, children } : null;
+}
+function collect(node, fn) { if (node.kind === 'pane')
+    fn(node);
+else
+    node.children.forEach((c) => collect(c.node, fn)); }
+/** Every widget id a tree references (for validation against the registry). */
+export function widgetsIn(node) { const ids = []; collect(node, (p) => ids.push(p.widget)); return ids; }
+// ------------------------------------------------------------------ plain-text render (previews, tests, proposal cards)
+export function renderPlain(solved, w, h, opts = {}) {
+    const grid = Array.from({ length: h }, () => Array(w).fill(' '));
+    const put = (x, y, s) => { for (let i = 0; i < s.length; i++)
+        if (x + i >= 0 && x + i < w && y >= 0 && y < h)
+            grid[y][x + i] = s[i]; };
+    for (const gt of solved.gutters)
+        for (let y = gt.y; y < gt.y + gt.h; y++)
+            for (let x = gt.x; x < gt.x + gt.w; x++)
+                if (x < w && y < h)
+                    grid[y][x] = '·';
+    for (const p of solved.panes) {
+        const { x, y, w: pw, h: ph } = p.rect;
+        if (pw < 2 || ph < 2)
+            continue;
+        put(x, y, '╭' + '─'.repeat(pw - 2) + '╮');
+        for (let yy = y + 1; yy < y + ph - 1; yy++) {
+            put(x, yy, '│');
+            put(x + pw - 1, yy, '│');
+        }
+        put(x, y + ph - 1, '╰' + '─'.repeat(pw - 2) + '╯');
+        const spec = widgetSpec(p.widget, opts.registry ?? {});
+        const title = ` ${(p.node.title ?? spec?.title ?? p.widget).toUpperCase()} `;
+        if (title.trim())
+            put(x + 2, y, title.slice(0, Math.max(0, pw - 4)));
+        const info = `${p.widget} ${pw}×${ph}${p.clipped ? ' (clipped)' : ''}`;
+        put(x + 2, y + 1, info.slice(0, Math.max(0, pw - 4)));
+    }
+    return grid.map((r) => r.join('')).join('\n');
+}
+/** The app's shipped screens expressed as trees (so "default" is a workspace too, and the numbers are the renderers'). */
+export function builtinScreens() {
+    return {
+        screener: { kind: 'split', dir: 'row', gutter: true, children: [
+                { node: { kind: 'pane', widget: 'screener.table', priority: 0 } },
+                { node: { kind: 'pane', widget: 'screener.spotlight', priority: 2, collapseBelow: 'wide' }, fixed: 44 },
+            ] },
+        token: { kind: 'split', dir: 'row', children: [
+                { node: { kind: 'split', dir: 'col', children: [
+                            { node: { kind: 'pane', widget: 'token.chart', priority: 0 }, weight: 46 },
+                            { node: { kind: 'split', dir: 'row', children: [
+                                        { node: { kind: 'pane', widget: 'token.onchain', priority: 1 }, weight: 40 },
+                                        { node: { kind: 'pane', widget: 'token.flow', priority: 2 }, weight: 60 },
+                                    ] }, weight: 54 },
+                        ] } },
+                { node: { kind: 'pane', widget: 'analyst.panel', priority: 3, collapseBelow: 'standard' }, fixed: 46 },
+            ] },
+        newpairs: { kind: 'split', dir: 'row', gutter: true, children: [
+                { node: { kind: 'pane', widget: 'newpairs.table', priority: 0 } },
+                { node: { kind: 'pane', widget: 'newpairs.spotlight', priority: 2, collapseBelow: 'wide' }, fixed: 46 },
+            ] },
+        watchlist: { kind: 'pane', widget: 'watchlist.table', priority: 0 },
+        analyst: { kind: 'split', dir: 'row', children: [
+                { node: { kind: 'pane', widget: 'analyst.panel', priority: 0 } },
+                { node: { kind: 'pane', widget: 'analyst.context', priority: 2, collapseBelow: 'wide' }, fixed: 36 },
+            ] },
+        positions: { kind: 'pane', widget: 'positions.table', priority: 0 },
+    };
+}