@sigrun/tui 0.4.1 → 0.5.0

package/dist/blocks/treeview.js

@@ -0,0 +1,121 @@
+/**
+ * The `tree` block (UI-blocks spec §5.3): a `nodes` binding of
+ * `{id, label, icon?, hasChildren?, children?}[]` with a cursor row,
+ * arrow-key movement, and Enter to expand/collapse or activate.
+ *
+ * A node with inline `children` toggles locally and never dispatches;
+ * a node with `hasChildren` and no inline children dispatches
+ * `onExpand` (an `edit`-shaped action carrying the handler NAME — the
+ * handler returns `DataOps` inserting the children). A leaf runs
+ * `onActivate` with `{id}`. Markers: `▸`/`▾` (ASCII `>`/`v`).
+ */
+import { bindRaw } from "./context.js";
+import { iconGlyph } from "./icons.js";
+import { truncate } from "./width.js";
+/** The markers for expandable nodes. */
+const MARKERS = { collapsed: "▸", expanded: "▾", collapsedAscii: ">", expandedAscii: "v" };
+/** Read the bound nodes, dropping malformed entries. */
+function treeNodes(block, ctx) {
+    const raw = bindRaw(block.nodes, ctx);
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const record = entry;
+        if (typeof record.id !== "string" || typeof record.label !== "string")
+            continue;
+        out.push({
+            id: record.id,
+            label: record.label,
+            icon: typeof record.icon === "string" ? record.icon : undefined,
+            hasChildren: record.hasChildren === true,
+            children: Array.isArray(record.children)
+                ? record.children
+                : undefined,
+        });
+    }
+    return out;
+}
+/** `tree`: cursor + expand/collapse + activate. */
+export class TreeComponent {
+    #block;
+    #ctx;
+    #cursor = 0;
+    #expanded = new Set();
+    constructor(block, ctx) {
+        this.#block = block;
+        this.#ctx = ctx;
+    }
+    /** The visible rows (children of expanded nodes interleave). */
+    #rows() {
+        const out = [];
+        const walk = (nodes, depth) => {
+            for (const node of nodes) {
+                out.push({ node, depth });
+                if (this.#expanded.has(node.id) && node.children !== undefined) {
+                    walk(node.children, depth + 1);
+                }
+            }
+        };
+        walk(treeNodes(this.#block, this.#ctx), 0);
+        return out;
+    }
+    render(width) {
+        const unicode = this.#ctx.unicode;
+        return this.#rows().map((row, index) => {
+            const cursor = index === this.#cursor ? "> " : "  ";
+            // Every row carries a state marker; leaves show the collapsed
+            // glyph as their bullet so icon rows align with parent rows.
+            const marker = (this.#expanded.has(row.node.id)
+                ? unicode
+                    ? MARKERS.expanded
+                    : MARKERS.expandedAscii
+                : unicode
+                    ? MARKERS.collapsed
+                    : MARKERS.collapsedAscii) + " ";
+            const icon = row.node.icon === undefined
+                ? ""
+                : `${iconGlyph(row.node.icon, !unicode)} `;
+            const indent = "  ".repeat(row.depth);
+            return truncate(`${cursor}${indent}${marker}${icon}${row.node.label}`, width);
+        });
+    }
+    handleInput(data) {
+        const rows = this.#rows();
+        if (data === "\x1b[B") {
+            this.#cursor = Math.min(rows.length - 1, this.#cursor + 1);
+            return;
+        }
+        if (data === "\x1b[A") {
+            this.#cursor = Math.max(0, this.#cursor - 1);
+            return;
+        }
+        if (data !== "\r")
+            return;
+        const row = rows[this.#cursor];
+        if (row === undefined)
+            return;
+        const node = row.node;
+        if (node.children !== undefined) {
+            // Inline children toggle locally; nothing dispatches.
+            if (this.#expanded.has(node.id))
+                this.#expanded.delete(node.id);
+            else
+                this.#expanded.add(node.id);
+            return;
+        }
+        if (node.hasChildren === true && this.#block.onExpand !== undefined) {
+            const action = { type: "edit", name: this.#block.onExpand };
+            this.#ctx.dispatch(action, { id: node.id });
+            return;
+        }
+        if (this.#block.onActivate !== undefined) {
+            this.#ctx.dispatch(this.#block.onActivate, { id: node.id });
+        }
+    }
+    invalidate() {
+        // Cursor and expansion survive re-renders.
+    }
+}

package/dist/blocks/width.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Terminal width for block rendering (UI-blocks U2 Task 1): the width
+ * classes (spec §12.1), the `s`/`m`/`l` token scale (spec §5.2), and the
+ * clamp/pad helpers every block renderer funnels through.
+ *
+ * The display-width measure is pi-tui's `visibleWidth` (grapheme-aware,
+ * wcwidth-style, ANSI-safe) — re-exported here so block code has ONE
+ * width import site and the Review-Focus-2 invariant ("every rendered
+ * line's display width ≤ the pane") is enforced in one place:
+ * {@link truncate}.
+ */
+import type { Size } from "@sigrun/shared/blocks";
+/** The container width classes (spec §12.1, TUI column). */
+export type WidthClass = "compact" | "regular" | "wide";
+/** The compact/regular/wide boundary: cells (compact < 80 ≤ regular < 140 ≤ wide). */
+export declare function widthClassOf(cells: number): WidthClass;
+/** Width tokens in cells (spec §5.2: the TUI maps s/m/l to 30/45/60). */
+export declare const SIZE_CELLS: Readonly<Record<Size, number>>;
+/**
+ * Clamp one rendered line to `width` cells with an ellipsis (Review
+ * Focus 2): ANSI-aware, wide-character-aware, never a mid-sequence cut.
+ * Empty lines pass through.
+ */
+export declare function truncate(line: string, width: number): string;
+/** Pad a line to `width` cells by its DISPLAY width (for column joins). */
+export declare function pad(line: string, width: number): string;
+/**
+ * Fit a run of source lines into `width` cells: short runs stay one
+ * line (truncated); longer word-wraps fold at spaces, each folded line
+ * truncated. Used for plain-text values (markdown wraps itself).
+ */
+export declare function wrapPlain(text: string, width: number): string[];

package/dist/blocks/width.js

@@ -0,0 +1,70 @@
+/**
+ * Terminal width for block rendering (UI-blocks U2 Task 1): the width
+ * classes (spec §12.1), the `s`/`m`/`l` token scale (spec §5.2), and the
+ * clamp/pad helpers every block renderer funnels through.
+ *
+ * The display-width measure is pi-tui's `visibleWidth` (grapheme-aware,
+ * wcwidth-style, ANSI-safe) — re-exported here so block code has ONE
+ * width import site and the Review-Focus-2 invariant ("every rendered
+ * line's display width ≤ the pane") is enforced in one place:
+ * {@link truncate}.
+ */
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+/** The compact/regular/wide boundary: cells (compact < 80 ≤ regular < 140 ≤ wide). */
+export function widthClassOf(cells) {
+    if (cells < 80)
+        return "compact";
+    if (cells < 140)
+        return "regular";
+    return "wide";
+}
+/** Width tokens in cells (spec §5.2: the TUI maps s/m/l to 30/45/60). */
+export const SIZE_CELLS = {
+    s: 30,
+    m: 45,
+    l: 60,
+};
+/**
+ * Clamp one rendered line to `width` cells with an ellipsis (Review
+ * Focus 2): ANSI-aware, wide-character-aware, never a mid-sequence cut.
+ * Empty lines pass through.
+ */
+export function truncate(line, width) {
+    if (line === "")
+        return "";
+    return truncateToWidth(line, width, "…");
+}
+/** Pad a line to `width` cells by its DISPLAY width (for column joins). */
+export function pad(line, width) {
+    const rest = width - visibleWidth(line);
+    return rest > 0 ? line + " ".repeat(rest) : line;
+}
+/**
+ * Fit a run of source lines into `width` cells: short runs stay one
+ * line (truncated); longer word-wraps fold at spaces, each folded line
+ * truncated. Used for plain-text values (markdown wraps itself).
+ */
+export function wrapPlain(text, width) {
+    if (width <= 0)
+        return [];
+    const words = text.split(/\s+/).filter((w) => w !== "");
+    if (words.length === 0)
+        return [""];
+    const lines = [];
+    let current = "";
+    for (const word of words) {
+        if (current === "") {
+            current = word;
+        }
+        else if (visibleWidth(current) + 1 + visibleWidth(word) <= width) {
+            current += ` ${word}`;
+        }
+        else {
+            lines.push(current);
+            current = word;
+        }
+    }
+    if (current !== "")
+        lines.push(current);
+    return lines.map((line) => truncate(line, width));
+}

package/dist/clipboard.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Terminal clipboard (Task C3, UI refresh): OSC 52 writes the system
+ * clipboard through the terminal emulator. Inside tmux the sequence must
+ * be DCS-wrapped with every ESC doubled, or tmux eats it.
+ *
+ * `copyToTerminal` writes the sequence to the terminal; the app flashes
+ * "Copied" in the status bar on top of this.
+ */
+/** The environment slice the tmux detection reads. */
+export interface ClipboardEnv {
+    readonly TMUX?: string;
+}
+/** The OSC 52 sequence for `text` (base64 UTF-8), tmux-wrapped when needed. */
+export declare function osc52(text: string, env?: ClipboardEnv): string;
+/** The terminal surface the copy needs (pi-tui's `Terminal.write`). */
+export interface ClipboardTerminal {
+    write(data: string): void;
+}
+/** Write `text` to the system clipboard via the terminal. */
+export declare function copyToTerminal(terminal: ClipboardTerminal, text: string, env?: ClipboardEnv): void;

package/dist/clipboard.js

@@ -0,0 +1,19 @@
+/**
+ * Terminal clipboard (Task C3, UI refresh): OSC 52 writes the system
+ * clipboard through the terminal emulator. Inside tmux the sequence must
+ * be DCS-wrapped with every ESC doubled, or tmux eats it.
+ *
+ * `copyToTerminal` writes the sequence to the terminal; the app flashes
+ * "Copied" in the status bar on top of this.
+ */
+/** The OSC 52 sequence for `text` (base64 UTF-8), tmux-wrapped when needed. */
+export function osc52(text, env = process.env) {
+    const seq = `\x1b]52;c;${Buffer.from(text, "utf8").toString("base64")}\x07`;
+    if (env.TMUX === undefined || env.TMUX === "")
+        return seq;
+    return `\x1bPtmux;\x1b${seq.replaceAll("\x1b", "\x1b\x1b")}\x1b\\`;
+}
+/** Write `text` to the system clipboard via the terminal. */
+export function copyToTerminal(terminal, text, env = process.env) {
+    terminal.write(osc52(text, env));
+}

package/dist/editor-launch.d.ts

@@ -0,0 +1,34 @@
+export declare const VIM_NAMES: readonly string[];
+/** True when the basename of the first whitespace-separated token is a vim binary. */
+export declare function isVimFamily(command: string): boolean;
+/**
+ * Resolve a vim-family editor: configured → VISUAL → EDITOR (each used only
+ * when vim-family), then nvim/vim/vi on PATH. Undefined when nothing qualifies.
+ */
+export declare function resolveVimEditor(opts: {
+    configured?: string;
+    env: NodeJS.ProcessEnv;
+    which(name: string): string | undefined;
+}): string | undefined;
+/**
+ * Edit `text` in a vim-family editor via a temp file, suspending the TUI for
+ * the duration. The temp file is always removed; on failure the draft is
+ * untouched and stop/start remain balanced.
+ */
+export declare function editInVim(opts: {
+    text: string;
+    editor: string;
+    tui: {
+        stop(): void;
+        start(): void;
+        requestRender(force?: boolean): void;
+    };
+    spawnSync?: typeof import("node:child_process").spawnSync;
+    tmpDir?: string;
+}): {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/editor-launch.js

@@ -0,0 +1,70 @@
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+export const VIM_NAMES = ["vim", "nvim", "vi"];
+/** True when the basename of the first whitespace-separated token is a vim binary. */
+export function isVimFamily(command) {
+    const first = command.trim().split(/\s+/)[0];
+    if (!first)
+        return false;
+    return VIM_NAMES.includes(basename(first));
+}
+/**
+ * Resolve a vim-family editor: configured → VISUAL → EDITOR (each used only
+ * when vim-family), then nvim/vim/vi on PATH. Undefined when nothing qualifies.
+ */
+export function resolveVimEditor(opts) {
+    for (const candidate of [opts.configured, opts.env.VISUAL, opts.env.EDITOR]) {
+        if (candidate && isVimFamily(candidate))
+            return candidate;
+    }
+    for (const name of ["nvim", "vim", "vi"]) {
+        const found = opts.which(name);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/**
+ * Edit `text` in a vim-family editor via a temp file, suspending the TUI for
+ * the duration. The temp file is always removed; on failure the draft is
+ * untouched and stop/start remain balanced.
+ */
+export function editInVim(opts) {
+    const spawn = opts.spawnSync ?? realSpawnSync;
+    const file = join(opts.tmpDir ?? tmpdir(), `sigrun-prompt-${randomBytes(8).toString("hex")}.md`);
+    writeFileSync(file, opts.text, { encoding: "utf8", mode: 0o600 });
+    // The editor string splits on whitespace — quoted paths with spaces in
+    // the command or its arguments are NOT supported (a known limitation).
+    const [command, ...args] = opts.editor.trim().split(/\s+/);
+    try {
+        opts.tui.stop();
+        const result = spawn(command, [...args, file], { stdio: "inherit" });
+        if (result.error) {
+            return { ok: false, reason: `editor failed to launch: ${result.error.message}` };
+        }
+        if (result.status !== 0) {
+            return { ok: false, reason: `editor exited with status ${result.status}` };
+        }
+        let text;
+        try {
+            text = readFileSync(file, "utf8");
+        }
+        catch {
+            return { ok: false, reason: "edited file missing or unreadable" };
+        }
+        return { ok: true, text };
+    }
+    finally {
+        opts.tui.start();
+        opts.tui.requestRender(true);
+        try {
+            unlinkSync(file);
+        }
+        catch {
+            // already gone (editor deleted it) — nothing to clean up
+        }
+    }
+}

package/dist/keymaps/emacs.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The emacs keymap (Task C5, UI refresh): modeless, chord-driven. `C-x`
+ * ("\x18") arms a 1 000 ms chord: `C-x b` conversation picker, `C-x o`
+ * focus cycle, `C-x C-c` quit, `C-x k` a consumed no-op (a mismatched
+ * follow-up is the emacs undefined-key beep — consumed, never typed).
+ * `M-x` opens the command picker; `C-s` / `C-r` search forward / backward
+ * (the app's search overlay turns them into next / previous while open);
+ * `C-g` cancels a live run, closes the search/picker (it passes through
+ * to the open overlay), or focuses the composer. `M-p` / `M-n` jump
+ * between prompts; `M-w` copy, `M-f` fork, `M-e` edit are outside-
+ * composer actions (in the composer `M-f` is the editor's word-forward —
+ * all three pass). `C-n` / `C-p` move outside the composer; `C-o`
+ * answers an interaction, `C-l` redraws, `C-h` opens the key reference.
+ * Every {@link RESERVED_KEYS} chord passes in every focus — ctrl+b is
+ * NEVER bound (no `C-x C-b` either).
+ */
+import { type Keymap } from "./types.js";
+export declare function createEmacsKeymap(): Keymap;

package/dist/keymaps/emacs.js

@@ -0,0 +1,172 @@
+/**
+ * The emacs keymap (Task C5, UI refresh): modeless, chord-driven. `C-x`
+ * ("\x18") arms a 1 000 ms chord: `C-x b` conversation picker, `C-x o`
+ * focus cycle, `C-x C-c` quit, `C-x k` a consumed no-op (a mismatched
+ * follow-up is the emacs undefined-key beep — consumed, never typed).
+ * `M-x` opens the command picker; `C-s` / `C-r` search forward / backward
+ * (the app's search overlay turns them into next / previous while open);
+ * `C-g` cancels a live run, closes the search/picker (it passes through
+ * to the open overlay), or focuses the composer. `M-p` / `M-n` jump
+ * between prompts; `M-w` copy, `M-f` fork, `M-e` edit are outside-
+ * composer actions (in the composer `M-f` is the editor's word-forward —
+ * all three pass). `C-n` / `C-p` move outside the composer; `C-o`
+ * answers an interaction, `C-l` redraws, `C-h` opens the key reference.
+ * Every {@link RESERVED_KEYS} chord passes in every focus — ctrl+b is
+ * NEVER bound (no `C-x C-b` either).
+ */
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+import { RESERVED_KEYS } from "./types.js";
+/** The C-x chord window. */
+const CHORD_MS = 1_000;
+const BINDINGS = [
+    { keys: "C-x b", action: "conversation picker" },
+    { keys: "C-x o", action: "cycle focus" },
+    { keys: "C-x C-c", action: "quit" },
+    { keys: "M-x", action: "command picker" },
+    { keys: "C-s / C-r", action: "search forward / backward" },
+    { keys: "C-g", action: "cancel run / close / focus composer" },
+    { keys: "M-p / M-n", action: "previous / next prompt" },
+    { keys: "M-w", action: "copy turn" },
+    { keys: "M-f", action: "fork here" },
+    { keys: "M-e", action: "edit here" },
+    { keys: "C-n / C-p", action: "move down / up" },
+    { keys: "enter", action: "open / fold" },
+    { keys: "C-o", action: "answer interaction" },
+    { keys: "C-l", action: "redraw" },
+    { keys: "C-h", action: "key reference" },
+    { keys: "M-m", action: "pick up (block surface)" },
+    { keys: "enter", action: "drop (block surface)" },
+    { keys: "C-g", action: "cancel move (block surface)" },
+    { keys: "space", action: "select (block surface)" },
+    { keys: ".", action: "action menu (block surface)" },
+    { keys: "x", action: "check (block surface)" },
+    { keys: "[ / ]", action: "previous / next range (calendar)" },
+    { keys: "t", action: "today (calendar)" },
+];
+/** Match `data` against any reserved chord (they always pass). */
+function isReserved(data) {
+    return RESERVED_KEYS.some((id) => matchesKey(data, id));
+}
+export function createEmacsKeymap() {
+    /** The armed C-x prefix timestamp (undefined = no chord pending). */
+    let chordAt;
+    /**
+     * Resolve the C-x chord against `data`. Returns the chord's result,
+     * "consume" when `data` ARMS the prefix, or undefined to process
+     * `data` fresh (no prefix pending, or the window expired).
+     */
+    const chord = (data) => {
+        const now = Date.now();
+        if (chordAt !== undefined) {
+            const armed = chordAt;
+            chordAt = undefined;
+            if (now - armed <= CHORD_MS) {
+                if (data === "b")
+                    return { type: "picker", kind: "conversation" };
+                if (data === "o")
+                    return { type: "focus-cycle", direction: 1 };
+                if (data === "\x03")
+                    return { type: "quit" }; // C-x C-c
+                if (data === "k")
+                    return "consume"; // C-x k: a no-op, consumed
+                return "consume"; // undefined chord: the emacs beep
+            }
+            // Expired: `data` is processed fresh below.
+        }
+        if (data === "\x18") {
+            chordAt = now;
+            return "consume";
+        }
+        return undefined;
+    };
+    /** Block-surface keys (spec §12.4; emacs picks up with M-m). C-g is
+     *  the cancel key — it cancels a move on a surface BEFORE the global
+     *  C-g (cancel-run / focus composer) below sees it. */
+    const surface = (data) => {
+        if (data === "\x1bm")
+            return { type: "blocks.pickUp" }; // M-m
+        if (matchesKey(data, Key.enter) || data === "\r")
+            return { type: "blocks.drop" };
+        if (data === "\x07")
+            return { type: "blocks.cancelMove" }; // C-g
+        if (data === " ")
+            return { type: "blocks.select" };
+        if (data === ".")
+            return { type: "blocks.actionMenu" };
+        if (data === "x")
+            return { type: "blocks.check" };
+        if (data === "[")
+            return { type: "blocks.rangePrev" };
+        if (data === "]")
+            return { type: "blocks.rangeNext" };
+        if (data === "t")
+            return { type: "blocks.today" };
+        return undefined;
+    };
+    return {
+        name: "emacs",
+        modeLabel: () => undefined,
+        handle(data, ctx) {
+            // The composer's readline chords + the tmux prefix: NEVER bound.
+            // A reserved pass-through disarms a pending C-x — otherwise
+            // `C-x C-b b` would fire the picker with the user's "b".
+            if (isReserved(data)) {
+                chordAt = undefined;
+                return "pass";
+            }
+            // A modal overlay owns the keys; C-g passes too — the picker and
+            // the search overlay close themselves on it.
+            if (ctx.overlayOpen)
+                return "pass";
+            const chorded = chord(data);
+            if (chorded !== undefined)
+                return chorded;
+            // A block surface owns the §12.4 keys (its C-g is cancel-move,
+            // which must win over the global C-g cancel-run).
+            if (ctx.focus === "surface") {
+                const surfaceResult = surface(data);
+                if (surfaceResult !== undefined)
+                    return surfaceResult;
+            }
+            if (data === "\x1bx")
+                return { type: "picker", kind: "command" };
+            if (data === "\x13")
+                return { type: "search", direction: "forward" };
+            if (data === "\x12")
+                return { type: "search", direction: "backward" };
+            if (data === "\x07") {
+                return ctx.busy
+                    ? { type: "cancel-run" }
+                    : { type: "focus", target: "composer" };
+            }
+            if (data === "\x1bp")
+                return { type: "prompt-jump", delta: -1 };
+            if (data === "\x1bn")
+                return { type: "prompt-jump", delta: 1 };
+            if (data === "\x0f")
+                return { type: "answer-interaction" };
+            if (data === "\x0c")
+                return { type: "redraw" };
+            if (data === "\x08")
+                return { type: "help" };
+            if (ctx.focus === "composer")
+                return "pass";
+            // Outside the composer: the transcript/list actions.
+            if (data === "\x1bw")
+                return { type: "copy" };
+            if (data === "\x1bf")
+                return { type: "fork-here" };
+            if (data === "\x1be")
+                return { type: "edit-here" };
+            if (data === "\x0e")
+                return { type: "move", delta: 1 };
+            if (data === "\x10")
+                return { type: "move", delta: -1 };
+            if (matchesKey(data, Key.enter) || data === "\r")
+                return { type: "open" };
+            return "pass";
+        },
+        hints: () => ["C-x b chats", "M-x commands", "C-h keys"],
+        describe: () => BINDINGS,
+    };
+}

package/dist/keymaps/standard.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The standard keymap (Task C3, UI refresh): readline-friendly globals
+ * plus vi-flavoured navigation OUTSIDE the composer. The composer owns
+ * every printable key and every {@link RESERVED_KEYS} chord — nothing
+ * here shadows a line-editing key (ctrl+d/ctrl+u included), and ctrl+b
+ * is never bound anywhere.
+ *
+ * Global (every focus): ctrl+p conversation picker, ctrl+n new
+ * conversation, ctrl+t cycle thinking, ctrl+o answer interaction,
+ * ctrl+l redraw, ctrl+c quit, tab/shift+tab focus cycle, Esc (abort a
+ * live run, else focus the composer; passes through while the
+ * composer's autocomplete is open). Outside the composer: arrows move,
+ * PgUp/PgDn page, Home/End jump, Enter open, y copy, f fork, e edit,
+ * / search, n/N next match, ? help.
+ */
+import { type Keymap } from "./types.js";
+export declare function createStandardKeymap(): Keymap;