@elaraai/e3-ui-cli 1.0.72 → 1.0.74

package/dist/tui/input/keymap.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The keymap — `resolve(input, key, ctx)` turns one Ink key event into a
+ * semantic {@link KeyAction} by scope: the command box while editing, a
+ * leaf editor while editing, then the view's own keys (list / tree / logs /
+ * inputs), then the keys that work everywhere. Vim aliases (`j k h l`,
+ * `gg G`, `^u ^d`) ride along.
+ *
+ * @packageDocumentation
+ */
+import type { Key } from 'ink';
+/** Where the key lands. */
+export type KeyScope = 'list' | 'tree' | 'logs' | 'none';
+/** What the keymap needs to know. */
+export interface KeyContext {
+    /** The command box mode. */
+    commandMode: 'idle' | 'edit' | 'confirm';
+    /** Whether a leaf editor is open. */
+    editingLeaf: boolean;
+    /** The view's primary scope. */
+    scope: KeyScope;
+    /** Whether the view is an editable input. */
+    editable: boolean;
+    /** Whether the view has numbered tabs. */
+    tabs: number;
+    /** A pending multi-key prefix (`g`). */
+    pendingKey: string | null;
+}
+/** A semantic key action. */
+export type KeyAction = {
+    kind: 'move';
+    op: 'up' | 'down' | 'pageUp' | 'pageDown' | 'home' | 'end';
+} | {
+    kind: 'open';
+} | {
+    kind: 'back';
+} | {
+    kind: 'quit';
+} | {
+    kind: 'help';
+} | {
+    kind: 'refresh';
+} | {
+    kind: 'tab';
+    index: number;
+} | {
+    kind: 'tab.cycle';
+    delta: 1 | -1;
+} | {
+    kind: 'prefill';
+    text: string;
+} | {
+    kind: 'type';
+    text: string;
+} | {
+    kind: 'expand';
+} | {
+    kind: 'collapse';
+} | {
+    kind: 'toggle';
+} | {
+    kind: 'collapseDeep';
+} | {
+    kind: 'save';
+} | {
+    kind: 'follow';
+} | {
+    kind: 'next';
+} | {
+    kind: 'prev';
+} | {
+    kind: 'copy';
+} | {
+    kind: 'edit';
+} | {
+    kind: 'add';
+} | {
+    kind: 'remove';
+} | {
+    kind: 'tag';
+} | {
+    kind: 'apply';
+} | {
+    kind: 'discard';
+} | {
+    kind: 'retry';
+} | {
+    kind: 'pending';
+    key: string;
+} | {
+    kind: 'paste';
+    text: string;
+    submit: boolean;
+} | {
+    kind: 'cmd.submit';
+} | {
+    kind: 'cmd.cancel';
+} | {
+    kind: 'cmd.complete';
+} | {
+    kind: 'cmd.up';
+} | {
+    kind: 'cmd.down';
+} | {
+    kind: 'cmd.left';
+} | {
+    kind: 'cmd.right';
+} | {
+    kind: 'cmd.home';
+} | {
+    kind: 'cmd.end';
+} | {
+    kind: 'cmd.backspace';
+} | {
+    kind: 'cmd.delete';
+} | {
+    kind: 'cmd.char';
+    text: string;
+} | {
+    kind: 'leaf.submit';
+} | {
+    kind: 'leaf.cancel';
+} | {
+    kind: 'leaf.left';
+} | {
+    kind: 'leaf.right';
+} | {
+    kind: 'leaf.home';
+} | {
+    kind: 'leaf.end';
+} | {
+    kind: 'leaf.backspace';
+} | {
+    kind: 'leaf.delete';
+} | {
+    kind: 'leaf.char';
+    text: string;
+} | {
+    kind: 'leaf.toggle';
+};
+/**
+ * Resolves one key event.
+ *
+ * @param input - Ink's `input` (the printable text, or `''` for special keys)
+ * @param key - Ink's `key` flags
+ * @param ctx - The context
+ * @returns The action, or null when the key means nothing here
+ */
+export declare function resolve(input: string, key: Key, ctx: KeyContext): KeyAction | null;
+//# sourceMappingURL=keymap.d.ts.map

package/dist/tui/input/keymap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keymap.d.ts","sourceRoot":"","sources":["../../../src/tui/input/keymap.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE/B,2BAA2B;AAC3B,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzD,qCAAqC;AACrC,MAAM,WAAW,UAAU;IACvB,4BAA4B;IAC5B,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACzC,qCAAqC;IACrC,WAAW,EAAE,OAAO,CAAC;IACrB,gCAAgC;IAChC,KAAK,EAAE,QAAQ,CAAC;IAChB,6CAA6C;IAC7C,QAAQ,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,6BAA6B;AAC7B,MAAM,MAAM,SAAS,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,CAAA;CAAE,GAC5E;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAY9B;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,UAAU,GAAG,SAAS,GAAG,IAAI,CAwHlF"}

package/dist/tui/input/keymap.js

@@ -0,0 +1,206 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/** Whether an input string is printable text (one or more characters, no controls). */
+function isPrintable(input) {
+    if (input === '')
+        return false;
+    for (const ch of input) {
+        const cp = ch.codePointAt(0) ?? 0;
+        if (cp < 0x20 || (cp >= 0x7f && cp < 0xa0))
+            return false;
+    }
+    return true;
+}
+/**
+ * Resolves one key event.
+ *
+ * @param input - Ink's `input` (the printable text, or `''` for special keys)
+ * @param key - Ink's `key` flags
+ * @param ctx - The context
+ * @returns The action, or null when the key means nothing here
+ */
+export function resolve(input, key, ctx) {
+    // Ctrl-C is always quit (we own Ctrl-C: exitOnCtrlC is off so a dirty
+    // input can confirm first).
+    if (key.ctrl && input === 'c')
+        return { kind: 'quit' };
+    // A paste (or a terminal delivering several keys in one chunk) arrives
+    // as one string: it is typed into the command box, and a trailing
+    // newline submits it.
+    if (input.length > 1 && !key.ctrl && !key.meta && !ctx.editingLeaf && ctx.commandMode !== 'confirm') {
+        const submit = /[\r\n]$/.test(input);
+        const text = input.replace(/[\r\n]+$/, '');
+        if (text !== '' && isPrintable(text))
+            return { kind: 'paste', text, submit };
+    }
+    if (ctx.commandMode === 'confirm') {
+        if (key.return)
+            return { kind: 'cmd.submit' };
+        if (key.escape)
+            return { kind: 'cmd.cancel' };
+        if (input === 'y' || input === 'Y')
+            return { kind: 'cmd.submit' };
+        if (input === 'n' || input === 'N')
+            return { kind: 'cmd.cancel' };
+        return null;
+    }
+    if (ctx.commandMode === 'edit') {
+        if (key.return)
+            return { kind: 'cmd.submit' };
+        if (key.escape)
+            return { kind: 'cmd.cancel' };
+        if (key.tab)
+            return { kind: 'cmd.complete' };
+        if (key.upArrow || (key.ctrl && input === 'p'))
+            return { kind: 'cmd.up' };
+        if (key.downArrow || (key.ctrl && input === 'n'))
+            return { kind: 'cmd.down' };
+        if (key.leftArrow)
+            return { kind: 'cmd.left' };
+        if (key.rightArrow)
+            return { kind: 'cmd.right' };
+        if (key.home || (key.ctrl && input === 'a'))
+            return { kind: 'cmd.home' };
+        if (key.end || (key.ctrl && input === 'e'))
+            return { kind: 'cmd.end' };
+        if (key.backspace)
+            return { kind: 'cmd.backspace' };
+        if (key.delete)
+            return { kind: 'cmd.delete' };
+        if (key.ctrl && input === 'u')
+            return { kind: 'cmd.cancel' };
+        if (!key.ctrl && !key.meta && isPrintable(input))
+            return { kind: 'cmd.char', text: input };
+        return null;
+    }
+    if (ctx.editingLeaf) {
+        if (key.return)
+            return { kind: 'leaf.submit' };
+        if (key.escape)
+            return { kind: 'leaf.cancel' };
+        if (key.leftArrow)
+            return { kind: 'leaf.left' };
+        if (key.rightArrow)
+            return { kind: 'leaf.right' };
+        if (key.home || (key.ctrl && input === 'a'))
+            return { kind: 'leaf.home' };
+        if (key.end || (key.ctrl && input === 'e'))
+            return { kind: 'leaf.end' };
+        if (key.backspace)
+            return { kind: 'leaf.backspace' };
+        if (key.delete)
+            return { kind: 'leaf.delete' };
+        if (input === ' ')
+            return { kind: 'leaf.toggle' };
+        if (!key.ctrl && !key.meta && isPrintable(input))
+            return { kind: 'leaf.char', text: input };
+        return null;
+    }
+    // -- everywhere ---------------------------------------------------------
+    if (key.escape || key.backspace)
+        return { kind: 'back' };
+    if (input === '?')
+        return { kind: 'help' };
+    if (input === 'q')
+        return { kind: 'quit' };
+    if (input === 'R')
+        return { kind: 'refresh' };
+    if (input === '/')
+        return { kind: 'type', text: '/' };
+    if (ctx.tabs > 0) {
+        if (/^[1-9]$/.test(input) && Number(input) <= ctx.tabs)
+            return { kind: 'tab', index: Number(input) - 1 };
+        // `tab` / `⇧tab` cycle the tabs everywhere; `←` / `→` only where no content claims the
+        // arrows (the help view, a log stream) — a tree expands / collapses, a list opens on `→`.
+        if (key.tab)
+            return { kind: 'tab.cycle', delta: key.shift ? -1 : 1 };
+        if (ctx.scope === 'none' || ctx.scope === 'logs') {
+            if (key.rightArrow)
+                return { kind: 'tab.cycle', delta: 1 };
+            if (key.leftArrow)
+                return { kind: 'tab.cycle', delta: -1 };
+        }
+    }
+    // -- pending prefixes (`gg`) --------------------------------------------
+    if (ctx.pendingKey === 'g') {
+        if (input === 'g')
+            return { kind: 'move', op: 'home' };
+        return null;
+    }
+    // -- lists / trees / logs -----------------------------------------------
+    if (ctx.scope !== 'none') {
+        if (key.upArrow || input === 'k')
+            return { kind: 'move', op: 'up' };
+        if (key.downArrow || input === 'j')
+            return { kind: 'move', op: 'down' };
+        if (key.pageUp || (key.ctrl && input === 'u'))
+            return { kind: 'move', op: 'pageUp' };
+        if (key.pageDown || (key.ctrl && input === 'd'))
+            return { kind: 'move', op: 'pageDown' };
+        if (key.home)
+            return { kind: 'move', op: 'home' };
+        if (key.end || input === 'G')
+            return { kind: 'move', op: 'end' };
+        if (input === 'g')
+            return { kind: 'pending', key: 'g' };
+    }
+    if (ctx.scope === 'tree') {
+        if (key.leftArrow && key.shift)
+            return { kind: 'collapseDeep' };
+        if (key.rightArrow || input === 'l')
+            return { kind: 'expand' };
+        if (key.leftArrow || input === 'h')
+            return { kind: 'collapse' };
+        if (key.return || input === ' ')
+            return ctx.editable ? { kind: 'apply' } : { kind: 'toggle' };
+        if (input === 's')
+            return { kind: 'save' };
+        if (input === 'n')
+            return { kind: 'next' };
+        if (input === 'N')
+            return { kind: 'prev' };
+        if (ctx.editable) {
+            if (input === 'e')
+                return { kind: 'edit' };
+            if (input === 'a')
+                return { kind: 'add' };
+            if (input === 'x')
+                return { kind: 'remove' };
+            if (input === 't')
+                return { kind: 'tag' };
+        }
+    }
+    if (ctx.scope === 'logs') {
+        if (input === 'F')
+            return { kind: 'follow' };
+        if (input === 's')
+            return { kind: 'save' };
+        if (input === 'c')
+            return { kind: 'copy' };
+        if (input === 'n')
+            return { kind: 'next' };
+        if (input === 'N')
+            return { kind: 'prev' };
+    }
+    if (ctx.scope === 'list') {
+        if (key.return)
+            return { kind: 'open' };
+        if (key.rightArrow || input === 'l')
+            return { kind: 'open' };
+        if (input === 'r' && !ctx.editable)
+            return { kind: 'prefill', text: '/run ' };
+        if (input === 'x' && !ctx.editable)
+            return { kind: 'prefill', text: '/stop' };
+        if (input === 'w')
+            return { kind: 'prefill', text: '/workspaces' };
+    }
+    if (input === 'r' && ctx.scope === 'none')
+        return { kind: 'retry' };
+    // -- anything else printable starts a fuzzy jump ------------------------
+    if (!key.ctrl && !key.meta && isPrintable(input) && input !== ' ')
+        return { kind: 'type', text: input };
+    return null;
+}
+//# sourceMappingURL=keymap.js.map

package/dist/tui/input/keymap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keymap.js","sourceRoot":"","sources":["../../../src/tui/input/keymap.ts"],"names":[],"mappings":"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"}

package/dist/tui/input/mouse.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * SGR mouse reporting — the sequences (`ESC [ < b ; x ; y M|m`) Ink hands
+ * `useInput` intact (with the leading ESC stripped) once
+ * `?1000;1002;1006h` is on: presses, releases, drags, wheel ticks and the
+ * modifiers. `--no-mouse`, `TERM=dumb` and a non-TTY stdout keep the
+ * enable sequence unwritten; every exit path writes the disable one.
+ *
+ * @packageDocumentation
+ */
+/** One mouse event, 0-based cells. */
+export interface MouseEvent {
+    kind: 'press' | 'release' | 'drag' | 'move' | 'wheelUp' | 'wheelDown';
+    button: 'left' | 'middle' | 'right' | 'none';
+    x: number;
+    y: number;
+    shift: boolean;
+    alt: boolean;
+    ctrl: boolean;
+}
+/** Turns SGR reporting on (buttons, drags, SGR encoding). */
+export declare const MOUSE_ON = "\u001B[?1000h\u001B[?1002h\u001B[?1006h";
+/** Turns SGR reporting off (the reverse order). */
+export declare const MOUSE_OFF = "\u001B[?1006l\u001B[?1002l\u001B[?1000l";
+/**
+ * Whether an input chunk is one or more SGR mouse reports.
+ *
+ * @param input - Ink's `input`
+ * @returns `true` for mouse reports only
+ */
+export declare function isMouseInput(input: string): boolean;
+/**
+ * Parses the SGR mouse reports in an input chunk.
+ *
+ * @param input - Ink's `input` (one or more reports, ESC optional)
+ * @returns The events, in order
+ */
+export declare function parseSgr(input: string): MouseEvent[];
+/**
+ * Whether mouse reporting can be turned on for this terminal.
+ *
+ * @param env - The environment (`TERM`)
+ * @param stdout - The output stream
+ * @returns `true` for a TTY that is not `dumb`
+ */
+export declare function mouseSupported(env: NodeJS.ProcessEnv, stdout: {
+    isTTY?: boolean | undefined;
+}): boolean;
+//# sourceMappingURL=mouse.d.ts.map

package/dist/tui/input/mouse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mouse.d.ts","sourceRoot":"","sources":["../../../src/tui/input/mouse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AAEH,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACvB,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,CAAC;IACtE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IAC7C,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACjB;AAED,6DAA6D;AAC7D,eAAO,MAAM,QAAQ,4CAAsC,CAAC;AAC5D,mDAAmD;AACnD,eAAO,MAAM,SAAS,4CAAsC,CAAC;AAK7D;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE,CAkBpD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAAE,GAAG,OAAO,CAEvG"}

package/dist/tui/input/mouse.js

@@ -0,0 +1,55 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/** Turns SGR reporting on (buttons, drags, SGR encoding). */
+export const MOUSE_ON = '\x1b[?1000h\x1b[?1002h\x1b[?1006h';
+/** Turns SGR reporting off (the reverse order). */
+export const MOUSE_OFF = '\x1b[?1006l\x1b[?1002l\x1b[?1000l';
+const ONE = /\x1b?\[<(\d+);(\d+);(\d+)([mM])/g;
+const ALL = /^(?:\x1b?\[<\d+;\d+;\d+[mM])+$/;
+/**
+ * Whether an input chunk is one or more SGR mouse reports.
+ *
+ * @param input - Ink's `input`
+ * @returns `true` for mouse reports only
+ */
+export function isMouseInput(input) {
+    return ALL.test(input);
+}
+/**
+ * Parses the SGR mouse reports in an input chunk.
+ *
+ * @param input - Ink's `input` (one or more reports, ESC optional)
+ * @returns The events, in order
+ */
+export function parseSgr(input) {
+    const out = [];
+    for (const m of input.matchAll(ONE)) {
+        const code = Number(m[1]);
+        const x = Number(m[2]) - 1;
+        const y = Number(m[3]) - 1;
+        const release = m[4] === 'm';
+        const wheel = (code & 64) !== 0;
+        const motion = (code & 32) !== 0;
+        const low = code & 3;
+        const button = wheel ? 'none' : low === 0 ? 'left' : low === 1 ? 'middle' : low === 2 ? 'right' : 'none';
+        const kind = wheel ? (low === 0 ? 'wheelUp' : 'wheelDown')
+            : release ? 'release'
+                : motion ? (button === 'none' ? 'move' : 'drag')
+                    : 'press';
+        out.push({ kind, button, x: Math.max(0, x), y: Math.max(0, y), shift: (code & 4) !== 0, alt: (code & 8) !== 0, ctrl: (code & 16) !== 0 });
+    }
+    return out;
+}
+/**
+ * Whether mouse reporting can be turned on for this terminal.
+ *
+ * @param env - The environment (`TERM`)
+ * @param stdout - The output stream
+ * @returns `true` for a TTY that is not `dumb`
+ */
+export function mouseSupported(env, stdout) {
+    return stdout.isTTY === true && env['TERM'] !== 'dumb';
+}
+//# sourceMappingURL=mouse.js.map

package/dist/tui/input/mouse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mouse.js","sourceRoot":"","sources":["../../../src/tui/input/mouse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuBH,6DAA6D;AAC7D,MAAM,CAAC,MAAM,QAAQ,GAAG,mCAAmC,CAAC;AAC5D,mDAAmD;AACnD,MAAM,CAAC,MAAM,SAAS,GAAG,mCAAmC,CAAC;AAE7D,MAAM,GAAG,GAAG,kCAAkC,CAAC;AAC/C,MAAM,GAAG,GAAG,gCAAgC,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACtC,OAAO,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa;IAClC,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1B,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;QAC7B,MAAM,KAAK,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,MAAM,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;QACjC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC;QACrB,MAAM,MAAM,GAAyB,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;QAC/H,MAAM,IAAI,GAAuB,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC;YAC1E,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;gBACrB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;oBAChD,CAAC,CAAC,OAAO,CAAC;QACd,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC9I,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,GAAsB,EAAE,MAAuC;IAC1F,OAAO,MAAM,CAAC,KAAK,KAAK,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC;AAC3D,CAAC"}

package/dist/tui/lifecycle.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/** The exit code for an unexpected failure (EX_SOFTWARE). */
+export declare const EXIT_SOFTWARE = 70;
+/** A line logger. */
+export type Logger = (line: string) => void;
+/**
+ * The debug logger: appends to `$XDG_STATE_HOME/e3-ui/debug.log` (beside
+ * the state file) when `E3_UI_DEBUG=1`, else a no-op.
+ *
+ * @param env - The environment
+ * @returns The logger and the log path (null when disabled)
+ */
+export declare function createDebugLogger(env: NodeJS.ProcessEnv): {
+    log: Logger;
+    file: string | null;
+};
+/** What the handlers call. */
+export interface LifecycleHooks {
+    /** A termination signal arrived: unmount and stop. */
+    onSignal: (signal: NodeJS.Signals) => void;
+    /** An unexpected error: the terminal is restored by the caller, then this reports it. */
+    onFatal: (error: unknown) => void;
+}
+/**
+ * Installs the process handlers.
+ *
+ * @param hooks - The callbacks
+ * @returns A function that removes them
+ */
+export declare function installLifecycle(hooks: LifecycleHooks): () => void;
+/**
+ * The stack (or message) of an unexpected error, for stderr after the
+ * terminal is restored.
+ *
+ * @param error - The error
+ * @returns The text
+ */
+export declare function fatalText(error: unknown): string;
+/**
+ * A one-line terminal description for the about view
+ * (`kitty 0.36 · 120×36 · truecolor · mouse ● · kitty keyboard ○`).
+ *
+ * @param env - The environment
+ * @param size - The terminal size
+ * @param colorLevel - The colour level
+ * @param mouse - Whether mouse reporting is on
+ * @param glyphs - The glyphs for the dots
+ * @returns The description
+ */
+export declare function describeTerminal(env: NodeJS.ProcessEnv, size: {
+    columns: number;
+    rows: number;
+}, colorLevel: number, mouse: boolean, glyphs: {
+    dot: string;
+    empty: string;
+    sep: string;
+}): string;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/tui/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/tui/lifecycle.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAkBH,6DAA6D;AAC7D,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,qBAAqB;AACrB,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAE5C;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAgB9F;AAED,8BAA8B;AAC9B,MAAM,WAAW,cAAc;IAC3B,sDAAsD;IACtD,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC;IAC3C,yFAAyF;IACzF,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,IAAI,CAalE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGhD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC5B,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACvC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACpD,MAAM,CAMR"}

package/dist/tui/lifecycle.js

@@ -0,0 +1,99 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Lifecycle — the process-level handlers the terminal UI installs:
+ * SIGINT / SIGTERM / SIGHUP unmount cleanly (Ctrl-C is a key while the
+ * UI runs, so SIGINT only arrives from outside), `uncaughtException` /
+ * `unhandledRejection` restore the terminal first, then print the stack
+ * and exit 70; and the `E3_UI_DEBUG=1` file logger, which never writes to
+ * stdout or stderr while the UI owns the screen.
+ *
+ * @packageDocumentation
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { statePath } from './state/persist.js';
+/** The exit code for an unexpected failure (EX_SOFTWARE). */
+export const EXIT_SOFTWARE = 70;
+/**
+ * The debug logger: appends to `$XDG_STATE_HOME/e3-ui/debug.log` (beside
+ * the state file) when `E3_UI_DEBUG=1`, else a no-op.
+ *
+ * @param env - The environment
+ * @returns The logger and the log path (null when disabled)
+ */
+export function createDebugLogger(env) {
+    if (env['E3_UI_DEBUG'] !== '1')
+        return { log: () => undefined, file: null };
+    const file = path.join(path.dirname(statePath(env, process.platform, os.homedir())), 'debug.log');
+    let ready = false;
+    const log = (line) => {
+        try {
+            if (!ready) {
+                fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+                ready = true;
+            }
+            fs.appendFileSync(file, `${new Date().toISOString()} ${line}\n`, { mode: 0o600 });
+        }
+        catch {
+            // The log must never take the UI down.
+        }
+    };
+    return { log, file };
+}
+/**
+ * Installs the process handlers.
+ *
+ * @param hooks - The callbacks
+ * @returns A function that removes them
+ */
+export function installLifecycle(hooks) {
+    const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+    const onSignal = (signal) => hooks.onSignal(signal);
+    const onException = (error) => hooks.onFatal(error);
+    const onRejection = (reason) => hooks.onFatal(reason);
+    for (const signal of signals)
+        process.on(signal, onSignal);
+    process.on('uncaughtException', onException);
+    process.on('unhandledRejection', onRejection);
+    return () => {
+        for (const signal of signals)
+            process.off(signal, onSignal);
+        process.off('uncaughtException', onException);
+        process.off('unhandledRejection', onRejection);
+    };
+}
+/**
+ * The stack (or message) of an unexpected error, for stderr after the
+ * terminal is restored.
+ *
+ * @param error - The error
+ * @returns The text
+ */
+export function fatalText(error) {
+    if (error instanceof Error)
+        return error.stack ?? `${error.name}: ${error.message}`;
+    return String(error);
+}
+/**
+ * A one-line terminal description for the about view
+ * (`kitty 0.36 · 120×36 · truecolor · mouse ● · kitty keyboard ○`).
+ *
+ * @param env - The environment
+ * @param size - The terminal size
+ * @param colorLevel - The colour level
+ * @param mouse - Whether mouse reporting is on
+ * @param glyphs - The glyphs for the dots
+ * @returns The description
+ */
+export function describeTerminal(env, size, colorLevel, mouse, glyphs) {
+    const program = env['TERM_PROGRAM'] ?? env['TERMINAL_EMULATOR'] ?? (env['TERM'] === 'xterm-kitty' ? 'kitty' : env['TERM'] ?? 'terminal');
+    const version = env['TERM_PROGRAM_VERSION'] !== undefined ? ` ${env['TERM_PROGRAM_VERSION']}` : '';
+    const colour = colorLevel >= 3 ? 'truecolor' : colorLevel === 2 ? '256 colours' : colorLevel === 1 ? '16 colours' : 'no colour';
+    const on = (flag) => (flag ? glyphs.dot : glyphs.empty);
+    return `${program}${version} ${glyphs.sep} ${size.columns}×${size.rows} ${glyphs.sep} ${colour} ${glyphs.sep} mouse ${on(mouse)}`;
+}
+//# sourceMappingURL=lifecycle.js.map