@voidlabs.gg/voidshift 0.0.0-stage → 0.4.0

package/dist/tui/screens.js

@@ -0,0 +1,172 @@
+// The screen registry and the contract every screen follows.
+//
+// ADDING A SCREEN (one import plus one registry line)
+//   1. Write your screen in its own file, e.g. src/tui/screens/runs.ts, and
+//      export a Screen: `export const runsScreen: Screen = { id: 'agents.runs', ... }`.
+//   2. Import it below and add its name to `registry`, after the placeholders.
+//      A later entry with the same id replaces the placeholder.
+//
+// A SCREEN
+//   id         unique, e.g. "agents.log". Ids below are fixed so Home can open them.
+//   title      breadcrumb crumb(s) for the header, a string, string[] or a
+//              function of the route params: (p) => ['Workflows', `Edit ${p.name}`].
+//              Screens under the top one contribute only their first crumb.
+//   component  a function component taking { params }. Everything else comes
+//              from hooks, never from props.
+//   hints      (props) => Hint[]: the default footer key hints. Use the
+//              useHints() hook instead when they depend on component state.
+//              End every list with { key: 'esc', label: 'back' }.
+//
+// WHAT A SCREEN GETS (all from ./context.ts, call them inside the component)
+//   useScreen()      the ScreenContext:
+//     params         the object passed to nav.push(id, params)
+//     nav            push(id, params) / pop() / replace(id, params)
+//     actions        run(spec): confirm dialog, then `vsf <args>` as a child
+//                    process, toast, store refresh. confirm(opts). detach(args,
+//                    logFile) for long runs. terminal(args) for commands that
+//                    need the real terminal. NEVER do a write or a blocking
+//                    command in-process; add --yes to args only for commands
+//                    that take it (clean, workflow rm, project rm).
+//     toast(text, kind)   'ok' | 'error' | 'info'
+//     columns, rows  terminal size
+//   useData()        (./data.ts) the live store: state.agents, state.runs,
+//                    state.workflows, state.projects, state.homes, state.awake,
+//                    state.memory, state.checks, state.steps (the hidden
+//                    `vsf agents steps` catalog), state.errors[source],
+//                    readConfig(tool), refresh(). Polled every 2 seconds.
+//   useKeys(fn)      key handler, silent while a dialog or the palette is open
+//                    and while a text field has focus.
+//   useHints(list)   dynamic footer hints.
+//   useEquivalent(args)   the "= vsf ..." command shown bottom right for forms
+//                    and actions, e.g. useEquivalent(['agents', 'cancel', card]).
+//   useCapture(on)   TextInput and Select call this for you. While a field has
+//                    focus the app ignores q : ? and Esc, so a form must handle
+//                    Esc itself with useKeys(fn, { whileCapturing: true }).
+//   useBackGuard(fn) Esc asks this first when no field has focus; return true
+//                    if you used the key (e.g. to clear a filter).
+//
+// WIDGETS (./widgets.ts): Panel, KeyHints, Table, SubTabs, ProgressSteps,
+// Badge, Confirm, TextInput, Select, Lines/SplitRow for coloured text.
+//
+// SUB-TABS. "agents" is a shell: a tab bar over the screens agents.runs,
+// agents.workflows, agents.projects, agents.homes and settings. Left and right
+// switch tabs. A tab is an ordinary screen; it is rendered inside the shell and
+// receives the shell's params plus (for settings) { tool: 'agents' }. Push
+// "agents.log" { card, step? } for a run's log, "agents.workflow.form" { name? }
+// (no name means new) and "agents.project.form" { name? } on top of the shell.
+import React from 'react';
+import { Box, Text, useInput } from 'ink';
+import { ScreenCtx, useScreen } from "./context.js";
+import { homeScreen } from "./home.js";
+import { agentsScreen as agentsShellScreen } from "./screens/agents.js";
+import { runsScreen } from "./screens/runs.js";
+import { logScreen } from "./screens/log.js";
+import { settingsScreen } from "./screens/settings.js";
+import { awakeScreen } from "./screens/awake.js";
+import { memoryScreen } from "./screens/memory.js";
+import { checksScreen } from "./screens/checks.js";
+import { workflowsScreen } from "./screens/workflows.js";
+import { workflowFormScreen } from "./screens/workflow-form.js";
+import { projectsScreen } from "./screens/projects.js";
+import { projectFormScreen } from "./screens/project-form.js";
+import { homesScreen } from "./screens/homes.js";
+import { SubTabs } from "./widgets.js";
+import { theme } from "./theme.js";
+const h = React.createElement;
+const BACK = { key: 'esc', label: 'back' };
+// ---- placeholders ---------------------------------------------------------
+function placeholder(id, title, extra = {}) {
+    return {
+        id,
+        title,
+        component: (props) => h(Box, { flexDirection: 'column', paddingX: 1 }, h(Text, { bold: true, color: theme.bold }, titleOf({ title }, props.params).join(' › ')), h(Text, { color: theme.dim }, 'Coming in this release.')),
+        hints: () => [BACK],
+        ...extra,
+    };
+}
+export const AGENT_TABS = [
+    { id: 'agents.runs', label: 'Runs' },
+    { id: 'agents.workflows', label: 'Workflows' },
+    { id: 'agents.projects', label: 'Projects' },
+    { id: 'agents.homes', label: 'Homes' },
+    { id: 'settings', label: 'Settings', params: { tool: 'agents' } },
+];
+const TAB_HINT = { key: '←→', label: 'tab' };
+export const activeTab = (params) => AGENT_TABS.find((t) => t.id === params.tab) ?? AGENT_TABS[0];
+// Renders another registered screen inside the current one with its own
+// params. Hints it sets get `extra` appended.
+export function ScreenHost(props) {
+    const parent = useScreen();
+    const screen = screens[props.id];
+    if (!screen)
+        return h(Text, { color: theme.red }, `Unknown screen ${props.id}`);
+    const ctx = {
+        ...parent,
+        id: props.id,
+        params: props.params,
+        setHints: (hints) => parent.setHints(hints && props.extraHints ? [...hints, ...props.extraHints] : hints),
+    };
+    return h(ScreenCtx.Provider, { value: ctx }, h(screen.component, { params: props.params }));
+}
+function AgentsShell(props) {
+    const ctx = useScreen();
+    const tab = activeTab(props.params);
+    useInput((_input, key) => {
+        const i = AGENT_TABS.indexOf(tab);
+        const next = key.rightArrow ? AGENT_TABS[(i + 1) % AGENT_TABS.length] : key.leftArrow ? AGENT_TABS[(i + AGENT_TABS.length - 1) % AGENT_TABS.length] : undefined;
+        if (next)
+            ctx.nav.replace('agents', { ...props.params, tab: next.id });
+    }, { isActive: !ctx.modalOpen && !ctx.capturing });
+    return h(Box, { flexDirection: 'column' }, h(SubTabs, { tabs: AGENT_TABS.map((t) => ({ id: t.id, label: t.label })), active: tab.id }), h(Text, null, ' '), h(ScreenHost, { key: tab.id, id: tab.id, params: { ...props.params, ...tab.params }, extraHints: [TAB_HINT] }));
+}
+const agentsScreen = {
+    id: 'agents',
+    title: (p) => ['Agents', activeTab(p).label],
+    component: AgentsShell,
+    hints: (p) => {
+        const tab = activeTab(p);
+        const inner = screens[tab.id];
+        return [...(inner ? inner.hints({ params: { ...p, ...tab.params } }) : [BACK]), TAB_HINT];
+    },
+};
+// ---- the registry ---------------------------------------------------------
+// Add screens here. Later entries replace earlier ones with the same id.
+const registry = [
+    homeScreen,
+    agentsScreen,
+    placeholder('agents.runs', 'Runs'),
+    placeholder('agents.workflows', 'Workflows'),
+    placeholder('agents.projects', 'Projects'),
+    placeholder('agents.homes', 'Homes'),
+    placeholder('settings', 'Settings'),
+    placeholder('agents.log', 'Log'),
+    placeholder('agents.workflow.form', 'Workflow'),
+    placeholder('agents.project.form', 'Project'),
+    placeholder('awake', 'Awake'),
+    placeholder('memory', 'Memory'),
+    placeholder('checks', 'Checks'),
+    agentsShellScreen,
+    runsScreen,
+    logScreen,
+    settingsScreen,
+    awakeScreen,
+    memoryScreen,
+    checksScreen,
+    workflowsScreen,
+    workflowFormScreen,
+    projectsScreen,
+    projectFormScreen,
+    homesScreen,
+];
+export const screens = Object.fromEntries(registry.map((s) => [s.id, s]));
+export function titleOf(screen, params) {
+    const t = typeof screen.title === 'function' ? screen.title(params) : screen.title;
+    return Array.isArray(t) ? t : [t];
+}
+export function hintsOf(id, params) {
+    return screens[id]?.hints({ params }) ?? [BACK];
+}
+export function crumbsOf(id, params) {
+    const s = screens[id];
+    return s ? titleOf(s, params) : [id];
+}

package/dist/tui/theme.d.ts

@@ -0,0 +1,14 @@
+export declare const theme: {
+    readonly dim: "#6b7280";
+    readonly accent: "#7aa2f7";
+    readonly green: "#9ece6a";
+    readonly yellow: "#e0af68";
+    readonly red: "#f7768e";
+    readonly text: "#d7dae0";
+    readonly bold: "#ffffff";
+    readonly selected: "#1f2335";
+    readonly keycap: "#565f89";
+    readonly keycapText: "#0f1117";
+    readonly onAccent: "#0f1117";
+};
+export type Colour = string;

package/dist/tui/theme.js

@@ -0,0 +1,18 @@
+// Colours for the dashboard. Hex values work on every modern terminal and
+// match the approved mockup: dim grey, one blue accent, and three signals.
+export const theme = {
+    dim: '#6b7280',
+    accent: '#7aa2f7',
+    green: '#9ece6a',
+    yellow: '#e0af68',
+    red: '#f7768e',
+    text: '#d7dae0',
+    bold: '#ffffff',
+    // Background of the selected row.
+    selected: '#1f2335',
+    // Background of a key cap in the hints footer.
+    keycap: '#565f89',
+    keycapText: '#0f1117',
+    // Text on an accent background (the active tab, the chosen button).
+    onAccent: '#0f1117',
+};

package/dist/tui/widgets.d.ts

@@ -0,0 +1,122 @@
+import React from 'react';
+import { type Key } from 'ink';
+import { type Hint } from './context.ts';
+export interface PanelProps {
+    title: string;
+    focused?: boolean;
+    colour?: string;
+    width?: number | string;
+    height?: number;
+    flexGrow?: number;
+    subtitle?: string;
+    children?: React.ReactNode;
+}
+export declare function Panel(props: PanelProps): React.ReactElement;
+export interface Seg {
+    text: string;
+    colour?: string;
+    bold?: boolean;
+    dim?: boolean;
+    bg?: string;
+}
+export type Line = Seg[];
+export declare const seg: (text: string, colour?: string, extra?: Partial<Seg>) => Seg;
+export declare function Lines(props: {
+    lines: Line[];
+}): React.ReactElement;
+export declare function SplitRow(props: {
+    left: Line;
+    right?: Line;
+}): React.ReactElement;
+export interface FooterLayout {
+    rows: Hint[][];
+    command: string | null;
+    inline: boolean;
+}
+export declare function layoutFooter(hints: Hint[], command: string | undefined, width: number): FooterLayout;
+export declare function KeyHints(props: {
+    hints: Hint[];
+    right?: string;
+    width?: number;
+}): React.ReactElement;
+export type Cell = string | {
+    text: string;
+    colour?: string;
+    bold?: boolean;
+};
+export interface Column {
+    title: string;
+    width?: number;
+}
+export declare function fitCell(text: string, width: number): string;
+export declare function fitColumn(text: string, width: number): string;
+export declare function Table(props: {
+    columns: Column[];
+    rows: Cell[][];
+    selected?: number;
+    empty?: string;
+    marker?: boolean;
+}): React.ReactElement;
+export declare function SubTabs(props: {
+    tabs: {
+        id: string;
+        label: string;
+    }[];
+    active: string;
+}): React.ReactElement;
+export type StepState = 'done' | 'running' | 'pending' | 'failed';
+export interface StepProgress {
+    label: string;
+    state: StepState;
+    fraction?: number;
+}
+export declare function barParts(state: StepState, fraction: number, width: number): {
+    filled: string;
+    head: string;
+    rest: string;
+};
+export declare function ProgressSteps(props: {
+    steps: StepProgress[];
+    barWidth?: number;
+}): React.ReactElement;
+export declare function outcomeColour(outcome: string): string;
+export declare function Badge(props: {
+    outcome: string;
+    label?: string;
+}): React.ReactElement;
+export interface ConfirmProps {
+    title: string;
+    body?: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    onConfirm(): void;
+    onCancel(): void;
+}
+export declare function Confirm(props: ConfirmProps): React.ReactElement;
+export interface EditResult {
+    value: string;
+    cursor: number;
+}
+export declare function editText(value: string, cursor: number, input: string, key: Partial<Key>): EditResult;
+export interface TextInputProps {
+    value: string;
+    onChange(value: string): void;
+    focus?: boolean;
+    placeholder?: string;
+    mask?: boolean;
+    onSubmit?(value: string): void;
+}
+export declare function TextInput(props: TextInputProps): React.ReactElement;
+export interface Option {
+    value: string;
+    label: string;
+    hint?: string;
+}
+export declare function cycle(count: number, index: number, delta: number): number;
+export interface SelectProps {
+    options: Option[];
+    value: string;
+    onChange(value: string): void;
+    focus?: boolean;
+}
+export declare function Select(props: SelectProps): React.ReactElement;

package/dist/tui/widgets.js

@@ -0,0 +1,264 @@
+// Reusable pieces for every screen: a titled box, the key hints footer, a
+// table, step progress, outcome badges, a confirm dialog, and the two form
+// fields (TextInput and Select). Elements are built with React.createElement
+// because Node's type stripping does not run JSX.
+import React, { useEffect, useState } from 'react';
+import { Box, Text, useInput, useWindowSize } from 'ink';
+import { useCapture, useScreen } from "./context.js";
+import { theme } from "./theme.js";
+const h = React.createElement;
+export function Panel(props) {
+    const colour = props.colour ?? (props.focused ? theme.accent : theme.dim);
+    const top = h(Box, { flexDirection: 'row', flexShrink: 0, height: 1 }, h(Box, { flexShrink: 0 }, h(Text, { wrap: 'truncate-end' }, h(Text, { color: colour }, '╭─ '), h(Text, { bold: true, color: theme.bold }, props.title), props.subtitle ? h(Text, { color: theme.dim }, ` ${props.subtitle}`) : null, h(Text, { color: colour }, ' '))), 
+    // A rule far longer than any terminal, clipped to whatever width is left.
+    h(Box, { flexGrow: 1, flexBasis: 0, height: 1, overflow: 'hidden' }, h(Text, { color: colour }, '─'.repeat(400))), h(Box, { flexShrink: 0 }, h(Text, { color: colour }, '╮')));
+    const body = h(Box, { flexDirection: 'column', borderStyle: 'round', borderTop: false, borderColor: colour, paddingX: 1, flexGrow: 1 }, props.children);
+    return h(Box, { flexDirection: 'column', width: props.width, height: props.height, flexGrow: props.flexGrow }, top, body);
+}
+export const seg = (text, colour, extra = {}) => ({ text, colour, ...extra });
+const segNodes = (line) => line.map((s, j) => h(Text, { key: j, color: s.colour, bold: s.bold, dimColor: s.dim, backgroundColor: s.bg }, s.text));
+export function Lines(props) {
+    return h(Box, { flexDirection: 'column' }, ...props.lines.map((line, i) => h(Text, { key: i, wrap: 'truncate-end' }, ...(line.length ? segNodes(line) : [' ']))));
+}
+// A row with text on the left and text pushed to the right edge.
+export function SplitRow(props) {
+    return h(Box, { flexDirection: 'row' }, h(Box, { flexShrink: 1, flexGrow: 1 }, h(Text, { wrap: 'truncate-end' }, ...segNodes(props.left))), props.right?.length ? h(Box, { flexShrink: 0, marginLeft: 2 }, h(Text, null, ...segNodes(props.right))) : null);
+}
+// ---- KeyHints footer -----------------------------------------------------
+// Width of one hint as drawn: " key " + " label  ".
+const hintWidth = (hint) => hint.key.length + hint.label.length + 5;
+// Lays out the footer for `width` columns (inside the padding). Hints and the
+// command share one line when they fit. Otherwise the hints wrap onto as many
+// lines as they need and the command gets its own line below, cut with an
+// ellipsis only if it is longer than the width. Hints are never cut.
+export function layoutFooter(hints, command, width) {
+    const w = Math.max(10, width);
+    const total = hints.reduce((n, hint) => n + hintWidth(hint), 0) - 2;
+    if (!command && total + 2 <= w)
+        return { rows: [hints], command: null, inline: false };
+    if (command && total + 2 + command.length <= w)
+        return { rows: [hints], command, inline: true };
+    const rows = [];
+    let row = [];
+    let used = 0;
+    for (const hint of hints) {
+        const hw = hintWidth(hint);
+        if (row.length && used + hw > w) {
+            rows.push(row);
+            row = [];
+            used = 0;
+        }
+        row.push(hint);
+        used += hw;
+    }
+    if (row.length)
+        rows.push(row);
+    if (!command)
+        return { rows, command: null, inline: false };
+    return { rows, command: command.length > w ? command.slice(0, w - 1) + '…' : command, inline: false };
+}
+export function KeyHints(props) {
+    const win = useWindowSize();
+    const layout = layoutFooter(props.hints, props.right, (props.width ?? win.columns) - 2);
+    const rowNode = (row, r) => h(Text, { key: r, wrap: 'truncate-end' }, ...row.flatMap((hint, i) => [
+        h(Text, { key: `k${i}`, backgroundColor: theme.keycap, color: theme.keycapText }, ` ${hint.key} `),
+        h(Text, { key: `l${i}`, color: theme.text }, ` ${hint.label}  `),
+    ]));
+    if (layout.inline) {
+        return h(Box, { flexDirection: 'row', paddingX: 1 }, h(Box, { flexGrow: 1, flexShrink: 1 }, rowNode(layout.rows[0], 0)), h(Box, { flexShrink: 0, marginLeft: 2 }, h(Text, { color: theme.dim }, layout.command)));
+    }
+    return h(Box, { flexDirection: 'column', paddingX: 1 }, ...layout.rows.map(rowNode), layout.command ? h(Text, { key: 'cmd', color: theme.dim, wrap: 'truncate-end' }, layout.command) : null);
+}
+const cellText = (c) => (typeof c === 'string' ? c : c.text);
+const cellColour = (c) => (typeof c === 'string' ? undefined : c.colour);
+// Cuts or pads a cell to exactly `width` characters.
+export function fitCell(text, width) {
+    const t = text.length > width ? text.slice(0, Math.max(0, width - 1)) + '…' : text;
+    return t.padEnd(width);
+}
+// A table cell in a column `width` wide: the text is cut so at least two spaces
+// are left before the next column, then padded to the full width.
+export function fitColumn(text, width) {
+    return fitCell(text, Math.max(1, width - 2)).padEnd(width);
+}
+export function Table(props) {
+    const marker = props.marker !== false;
+    const line = (cells, i, isHead) => {
+        const sel = !isHead && i === props.selected;
+        const bg = sel ? theme.selected : undefined;
+        return h(Box, { key: isHead ? 'head' : i, flexDirection: 'row' }, h(Text, { color: theme.accent, backgroundColor: bg }, marker ? (sel ? '▶ ' : '  ') : ''), ...props.columns.map((col, j) => {
+            const cell = cells[j] ?? '';
+            const text = col.width ? fitColumn(cellText(cell), col.width) : cellText(cell);
+            const bold = sel || (typeof cell !== 'string' && cell.bold);
+            const node = h(Text, { wrap: 'truncate-end', color: isHead ? theme.dim : cellColour(cell), bold, backgroundColor: bg }, text);
+            return col.width ? h(Box, { key: j, width: col.width, flexShrink: 0 }, node) : h(Box, { key: j, flexGrow: 1, flexShrink: 1 }, node);
+        }));
+    };
+    return h(Box, { flexDirection: 'column' }, line(props.columns.map((c) => c.title), -1, true), ...props.rows.map((r, i) => line(r, i, false)), props.rows.length === 0 && props.empty ? h(Text, { color: theme.dim }, props.empty) : null);
+}
+// ---- Sub-tabs -------------------------------------------------------------
+export function SubTabs(props) {
+    const parts = [];
+    props.tabs.forEach((t, i) => {
+        const on = t.id === props.active;
+        parts.push(on
+            ? h(Text, { key: i, backgroundColor: theme.accent, color: theme.onAccent }, ` ${t.label} `)
+            : h(Text, { key: i, color: theme.text }, ` ${t.label} `));
+        parts.push(h(Text, { key: `s${i}` }, '  '));
+    });
+    return h(Box, { paddingLeft: 1 }, h(Text, null, ...parts));
+}
+// The three parts of a bar: filled, the head, the rest. Done is all filled.
+export function barParts(state, fraction, width) {
+    if (state === 'done' || state === 'failed')
+        return { filled: '━'.repeat(width), head: '', rest: '' };
+    if (state === 'pending')
+        return { filled: '', head: '', rest: '─'.repeat(width) };
+    const n = Math.max(0, Math.min(width - 1, Math.round(Math.max(0, Math.min(1, fraction)) * (width - 1))));
+    return { filled: '━'.repeat(n), head: '╸', rest: '─'.repeat(width - n - 1) };
+}
+// "Dev ━━━━━━━━━━━━ ✓   QA ━━━━━━╸──────"
+export function ProgressSteps(props) {
+    const width = props.barWidth ?? 12;
+    const nodes = [];
+    props.steps.forEach((s, i) => {
+        const colour = s.state === 'done' ? theme.green : s.state === 'failed' ? theme.red : s.state === 'running' ? theme.accent : theme.dim;
+        const bar = barParts(s.state, s.fraction ?? 0.5, width);
+        nodes.push(h(Text, { key: i }, h(Text, { color: colour }, `${s.label} ${bar.filled}${bar.head}`), h(Text, { color: theme.dim }, bar.rest), s.state === 'done' ? h(Text, { color: theme.green }, ' ✓') : s.state === 'failed' ? h(Text, { color: theme.red }, ' ✗') : null, i < props.steps.length - 1 ? h(Text, null, '   ') : null));
+    });
+    return h(Text, null, ...nodes);
+}
+// ---- Badge ---------------------------------------------------------------
+export function outcomeColour(outcome) {
+    switch (outcome) {
+        case 'verified':
+            return theme.green;
+        case 'parked':
+        case 'changes':
+            return theme.yellow;
+        case 'cancelled':
+            return theme.red;
+        case 'running':
+            return theme.accent;
+        default:
+            return theme.dim;
+    }
+}
+export function Badge(props) {
+    return h(Text, { color: outcomeColour(props.outcome) }, props.label ?? props.outcome);
+}
+// Left and right choose, enter confirms, esc cancels, y and n are shortcuts.
+export function Confirm(props) {
+    const [yes, setYes] = useState(true);
+    useInput((input, key) => {
+        if (key.leftArrow || key.rightArrow || key.tab)
+            setYes((v) => !v);
+        else if (key.return)
+            (yes ? props.onConfirm : props.onCancel)();
+        else if (key.escape || input === 'n')
+            props.onCancel();
+        else if (input === 'y')
+            props.onConfirm();
+    });
+    const button = (label, on) => on ? h(Text, { backgroundColor: theme.accent, color: theme.onAccent }, ` ${label} `) : h(Text, { color: theme.text }, ` ${label} `);
+    return h(Box, { justifyContent: 'center', marginTop: 2 }, h(Box, { flexDirection: 'column', borderStyle: 'round', borderColor: theme.accent, paddingX: 2, width: 66 }, h(Text, { bold: true, color: theme.bold }, props.title), props.body ? h(Box, { marginTop: 1 }, h(Text, null, props.body)) : null, h(Box, { marginTop: 1, justifyContent: 'center', gap: 3 }, button(props.confirmLabel ?? 'Yes', yes), button(props.cancelLabel ?? 'No', !yes))));
+}
+// Applies one keypress to a single-line text value. Pure. Keys it does not
+// own (enter, tab, esc, up, down) leave the value unchanged for the form to use.
+export function editText(value, cursor, input, key) {
+    const at = Math.max(0, Math.min(cursor, value.length));
+    if (key.leftArrow)
+        return { value, cursor: Math.max(0, at - 1) };
+    if (key.rightArrow)
+        return { value, cursor: Math.min(value.length, at + 1) };
+    if (key.home || (key.ctrl && input === 'a'))
+        return { value, cursor: 0 };
+    if (key.end || (key.ctrl && input === 'e'))
+        return { value, cursor: value.length };
+    if (key.backspace || key.delete) {
+        if (at === 0)
+            return { value, cursor: at };
+        return { value: value.slice(0, at - 1) + value.slice(at), cursor: at - 1 };
+    }
+    if (key.ctrl && input === 'u')
+        return { value: value.slice(at), cursor: 0 };
+    if (key.ctrl && input === 'w') {
+        const head = value.slice(0, at).replace(/\S+\s*$/, '');
+        return { value: head + value.slice(at), cursor: head.length };
+    }
+    if (key.ctrl || key.meta || key.escape || key.return || key.tab || key.upArrow || key.downArrow || !input)
+        return { value, cursor: at };
+    // Pasted text arrives as one chunk; drop control characters and newlines.
+    const clean = input.replace(/[\u0000-\u001f\u007f]/g, '');
+    return { value: value.slice(0, at) + clean + value.slice(at), cursor: at + clean.length };
+}
+export function TextInput(props) {
+    const ctx = useScreen();
+    const [cursor, setCursor] = useState(props.value.length);
+    const focus = props.focus !== false;
+    useCapture(focus);
+    useInput((input, key) => {
+        if (key.return) {
+            props.onSubmit?.(props.value);
+            return;
+        }
+        const r = editText(props.value, cursor, input, key);
+        if (r.value !== props.value)
+            props.onChange(r.value);
+        setCursor(r.cursor);
+    }, { isActive: focus && !ctx.modalOpen });
+    const shown = props.mask ? '•'.repeat(props.value.length) : props.value;
+    const at = Math.min(cursor, shown.length);
+    if (!focus)
+        return h(Text, { color: shown ? undefined : theme.dim }, shown || props.placeholder || ' ');
+    const on = { backgroundColor: theme.accent, color: theme.onAccent };
+    return h(Text, { wrap: 'truncate-start' }, h(Text, on, ` ${shown.slice(0, at)}`), h(Text, { inverse: true }, shown[at] ?? ' '), h(Text, on, `${shown.slice(at + 1)} `));
+}
+// Next option index when moving by `delta`, wrapping around.
+export function cycle(count, index, delta) {
+    return count === 0 ? 0 : (((index + delta) % count) + count) % count;
+}
+// Closed: "label ▾". Left and right change the value; enter opens the list,
+// up and down move, enter picks, esc closes.
+export function Select(props) {
+    const ctx = useScreen();
+    const [open, setOpen] = useState(false);
+    const idx = Math.max(0, props.options.findIndex((o) => o.value === props.value));
+    const [hover, setHover] = useState(idx);
+    const focus = props.focus !== false;
+    useCapture(open);
+    useEffect(() => {
+        if (!focus)
+            setOpen(false);
+    }, [focus]);
+    useInput((_input, key) => {
+        if (open) {
+            if (key.upArrow)
+                setHover((i) => cycle(props.options.length, i, -1));
+            else if (key.downArrow)
+                setHover((i) => cycle(props.options.length, i, 1));
+            else if (key.return) {
+                const o = props.options[hover];
+                if (o)
+                    props.onChange(o.value);
+                setOpen(false);
+            }
+            else if (key.escape)
+                setOpen(false);
+            return;
+        }
+        if (key.return) {
+            setHover(idx);
+            setOpen(true);
+        }
+        else if (key.leftArrow)
+            props.onChange(props.options[cycle(props.options.length, idx, -1)]?.value ?? props.value);
+        else if (key.rightArrow)
+            props.onChange(props.options[cycle(props.options.length, idx, 1)]?.value ?? props.value);
+    }, { isActive: focus && !ctx.modalOpen });
+    const current = props.options[idx];
+    const head = h(Text, null, h(Text, { backgroundColor: focus ? theme.accent : undefined, color: focus ? theme.onAccent : undefined }, ` ${current?.label ?? props.value} `), current?.hint ? h(Text, { color: theme.dim }, `  ${current.hint}`) : null, h(Text, { color: theme.dim }, '  ▾'));
+    if (!open)
+        return head;
+    return h(Box, { flexDirection: 'column' }, head, ...props.options.map((o, i) => h(Text, { key: o.value, backgroundColor: i === hover ? theme.selected : undefined, color: i === hover ? theme.bold : theme.text }, `${i === hover ? '▶ ' : '  '}${o.label}`, o.hint ? h(Text, { color: theme.dim }, `  ${o.hint}`) : null)));
+}

package/dist/ui.d.ts

@@ -0,0 +1,5 @@
+import type { Ui } from './tool.ts';
+export declare class Cancelled extends Error {
+}
+export declare const ui: Ui;
+export declare const defaultsUi: Ui;