dexterm-cli 0.0.0-stage → 0.1.1

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 },
+    };
+}