windows-development-sandbox 1.0.5 → 1.4.0

package/dist/cli/menu/several.js

@@ -0,0 +1,102 @@
+// "Start several agents": projects, then agents for each, then where to attach. It only builds a command line
+// (sandbox launch --session <agent>@<folder> ...), so "repeat last" works and typing it does the same.
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertSafeWorkspace } from '../../core/safe-paths.js';
+import { errMsg, expandPath } from '../../core/util.js';
+import { readKnown } from '../../host/projects.js';
+import { isWithin } from '../../shared/projects.js';
+import { commandLine } from '../history.js';
+import { Text, Theme } from '../tui/index.js';
+/** Folders worth offering: this one, the projects started before, and the folders inside your roots. */
+export const candidateFolders = (ctx, cwd = process.cwd()) => {
+    const roots = ctx.loaded.config.projects.roots.map((r) => expandPath(r, ctx.loaded.base));
+    const inRoots = roots.flatMap((r) => { try {
+        return fs.readdirSync(r, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.isSymbolicLink() && !e.name.startsWith('.')).slice(0, 200).map((e) => path.join(r, e.name));
+    }
+    catch {
+        return [];
+    } });
+    const all = [path.resolve(cwd), ...readKnown(ctx.storageRoot).map((k) => k.host), ...inRoots];
+    return all.filter((f, i) => all.findIndex((g) => g.toLowerCase() === f.toLowerCase()) === i && fs.existsSync(f));
+};
+/** The command line for several sessions: one --session per (agent, folder), with the shared options. */
+export const severalAgentsArgv = (sessions, o) => ['launch', ...sessions.flatMap((s) => ['--session', s.harness + '@' + s.folder]), ...(o.headless ? ['--headless'] : []), ...(o.attachFirst ? ['-t'] : [])];
+const ADD = '@add';
+export class SeveralAgents {
+    app;
+    ctx;
+    path = ['Start several agents'];
+    constructor(app, ctx) {
+        this.app = app;
+        this.ctx = ctx;
+    }
+    async run() {
+        const folders = await this.folders();
+        if (!folders?.length)
+            return null;
+        const agents = Object.keys(this.ctx.loaded.config.harnesses);
+        const sessions = [];
+        for (const folder of folders) {
+            const picked = await this.app.list({
+                path: [...this.path, path.basename(folder)], intro: 'Agents for ' + folder + ' (one session each). Space ticks, Enter continues.', multi: true,
+                items: agents.map((a) => ({ value: a, label: a, checked: a === this.ctx.loaded.config.defaultHarness })),
+            });
+            if (picked.kind !== 'multi')
+                return null;
+            sessions.push(...picked.values.map((harness) => ({ harness, folder })));
+        }
+        if (!sessions.length)
+            return null;
+        const headless = await this.app.confirm({ path: this.path, question: 'Hide the sandbox window (headless)?', about: ['sandbox show brings it back.'], initial: this.ctx.loaded.config.sandbox.headless });
+        const attach = await this.app.choose(this.path, 'Attach this terminal to one of them? Each session also has a tab inside the sandbox; sandbox attach shows any of them later.', [
+            { value: -1, label: 'None' },
+            ...sessions.map((s, i) => ({ value: i, label: s.harness + ' in ' + Text.middle(s.folder, 60) })),
+        ], 0);
+        if (attach === undefined)
+            return null;
+        // The one to attach goes first: -t attaches the first session.
+        const ordered = attach >= 0 ? [sessions[attach], ...sessions.filter((_s, i) => i !== attach)] : sessions;
+        const argv = severalAgentsArgv(ordered, { headless, attachFirst: attach >= 0 });
+        const projects = [...new Set(sessions.map((s) => path.basename(s.folder)))];
+        const go = await this.app.confirm({
+            path: this.path, question: 'Start them?',
+            about: ['One sandbox with ' + sessions.length + ' session' + (sessions.length === 1 ? '' : 's') + ': ' + ordered.map((s) => s.harness + ' in ' + path.basename(s.folder)).join(', ') + '. Maps ' + projects.join(' and ') + '.', '', '$ ' + commandLine(argv)],
+        });
+        return go ? argv : null;
+    }
+    async folders() {
+        const here = path.resolve(process.cwd());
+        const candidates = candidateFolders(this.ctx);
+        const picked = await this.app.list({
+            path: this.path, intro: 'Which projects? Each gets its own sessions; all of them are mapped into one sandbox. Space ticks, Enter continues.', multi: true,
+            items: [
+                ...candidates.map((f) => ({ value: f, label: Text.middle(f, 90), hint: isWithin(f, here) && isWithin(here, f) ? Theme.muted('this folder') : undefined, checked: f.toLowerCase() === here.toLowerCase() })),
+                { value: ADD, label: '+ Another folder…' },
+            ],
+        });
+        if (picked.kind !== 'multi')
+            return null;
+        const folders = picked.values.filter((f) => f !== ADD);
+        if (picked.values.includes(ADD)) {
+            const extra = await this.app.text({
+                path: this.path, label: 'Folder to add',
+                validate: (v) => {
+                    const dir = path.resolve(v.trim());
+                    if (!v.trim() || !fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+                        return 'Not a folder: ' + dir;
+                    try {
+                        assertSafeWorkspace(dir, this.ctx.packageRoot, this.ctx.storageRoot);
+                        return true;
+                    }
+                    catch (e) {
+                        return errMsg(e);
+                    }
+                },
+            });
+            if (extra)
+                folders.push(path.resolve(extra.trim()));
+        }
+        return folders;
+    }
+}

package/dist/cli/progress.d.ts

@@ -0,0 +1,9 @@
+/** Can a line be redrawn in place? */
+export declare const canAnimate: (env: NodeJS.ProcessEnv, isTTY: boolean) => boolean;
+/** "12 s", "2 min 5 s". */
+export declare const elapsed: (ms: number) => string;
+/**
+ * Shows `message` while work runs and removes the line afterwards. The spinner only moves while the event loop is free
+ * (waiting on the sandbox); for long synchronous work (measuring folders) the static line is what you see.
+ */
+export declare const working: <T>(message: string | (() => string), work: () => Promise<T> | T, enabled?: boolean) => Promise<T>;

package/dist/cli/progress.js

@@ -0,0 +1,49 @@
+// Feedback for slow work: a spinner line on stderr (so --json and piped output stay clean). Without a terminal (pipe, CI,
+// TERM=dumb) it prints one plain line instead of animating.
+import { colorEnabled, shorten, termWidth } from './colors.js';
+const FRAMES = ['|', '/', '-', '\\'];
+/** Can a line be redrawn in place? */
+export const canAnimate = (env, isTTY) => isTTY && !env.CI && env.TERM !== 'dumb';
+/** "12 s", "2 min 5 s". */
+export const elapsed = (ms) => {
+    const s = Math.round(ms / 1000);
+    return s < 60 ? s + ' s' : Math.floor(s / 60) + ' min ' + (s % 60) + ' s';
+};
+/**
+ * Shows `message` while work runs and removes the line afterwards. The spinner only moves while the event loop is free
+ * (waiting on the sandbox); for long synchronous work (measuring folders) the static line is what you see.
+ */
+export const working = async (message, work, enabled = true) => {
+    if (!enabled)
+        return work();
+    const err = process.stderr;
+    const start = Date.now();
+    // A function: the message follows the work (e.g. the sandbox's boot step); without a terminal each new one is a line.
+    const text = () => (typeof message === 'function' ? message() : message);
+    if (!canAnimate(process.env, Boolean(err.isTTY))) {
+        let last = text();
+        err.write(last + '...\n');
+        const follow = typeof message === 'function' ? setInterval(() => { const now = text(); if (now !== last) {
+            last = now;
+            err.write(now + '\n');
+        } }, 500) : null;
+        try {
+            return await work();
+        }
+        finally {
+            if (follow)
+                clearInterval(follow);
+        }
+    }
+    let frame = 0;
+    const draw = () => { err.write('\r\x1b[2K' + (colorEnabled(process.env, true) ? '\x1b[36m' : '') + FRAMES[frame++ % FRAMES.length] + (colorEnabled(process.env, true) ? '\x1b[0m' : '') + ' ' + shorten(text(), termWidth() - 14) + (Date.now() - start > 3000 ? ' (' + elapsed(Date.now() - start) + ')' : '')); };
+    draw();
+    const timer = setInterval(draw, 120);
+    try {
+        return await work();
+    }
+    finally {
+        clearInterval(timer);
+        err.write('\r\x1b[2K');
+    }
+};

package/dist/cli/tui/app.d.ts

@@ -0,0 +1,39 @@
+import { MessageScreen, type ConfirmOptions, type TextOptions } from './dialogs.js';
+import { type FrameParts } from './frame.js';
+import { type ListOptions, type ListResult } from './list-screen.js';
+import { Terminal, type Key } from './terminal.js';
+export interface Size {
+    width: number;
+    height: number;
+}
+/** What a screen's key handler returns: `{ done: value }` ends the screen, nothing keeps it open (and redraws it). */
+export type Step<T> = {
+    done: T;
+} | undefined | void;
+export interface Screen<T> {
+    render(size: Size): FrameParts;
+    handle(key: Key): Step<T> | Promise<Step<T>>;
+}
+export declare class App {
+    readonly terminal: Terminal;
+    /** The status line for screens that do not set their own (refreshed on every draw). */
+    status: () => string;
+    constructor(terminal?: Terminal);
+    /** Shows `screen` until its handler says it is done, and returns what it returned. */
+    show<T>(screen: Screen<T>): Promise<T>;
+    list<T>(o: ListOptions<T>): Promise<ListResult<T>>;
+    text(o: TextOptions): Promise<string | undefined>;
+    confirm(o: ConfirmOptions): Promise<boolean>;
+    message(o: ConstructorParameters<typeof MessageScreen>[0]): Promise<void>;
+    /** One of a few values (undefined = back). */
+    choose<T>(path: string[], intro: string, choices: {
+        value: T;
+        label: string;
+        description?: string;
+        hint?: string;
+    }[], current?: T): Promise<T | undefined>;
+    /** Runs `work` on the normal screen (command output, interactive commands); the next show() takes the screen back. */
+    suspend<T>(work: () => Promise<T>): Promise<T>;
+    /** Leaves the alternate screen for good. */
+    close(): void;
+}

package/dist/cli/tui/app.js

@@ -0,0 +1,52 @@
+// The menu as an application: screens are shown one at a time in the frame, each until it is done. Commands that print
+// (or take over the terminal) run with the terminal handed back, and the next screen takes it again.
+import { ConfirmScreen, MessageScreen, TextScreen } from './dialogs.js';
+import { Frame } from './frame.js';
+import { ListScreen } from './list-screen.js';
+import { Terminal } from './terminal.js';
+import { Theme } from './theme.js';
+export class App {
+    terminal;
+    /** The status line for screens that do not set their own (refreshed on every draw). */
+    status = () => '';
+    constructor(terminal = new Terminal()) {
+        this.terminal = terminal;
+    }
+    /** Shows `screen` until its handler says it is done, and returns what it returned. */
+    async show(screen) {
+        this.terminal.start();
+        const draw = () => {
+            const { width, height } = this.terminal;
+            const parts = screen.render({ width, height: Frame.bodyHeight(height) });
+            this.terminal.render(Frame.render({ ...parts, status: parts.status ?? this.status() }, width, height));
+        };
+        this.terminal.onResized(draw);
+        try {
+            for (;;) {
+                draw();
+                const step = await screen.handle(await this.terminal.key());
+                if (step)
+                    return step.done;
+            }
+        }
+        finally {
+            this.terminal.onResized(null);
+        }
+    }
+    list(o) { return this.show(new ListScreen(o)); }
+    text(o) { return this.show(new TextScreen(o)); }
+    confirm(o) { return this.show(new ConfirmScreen(o)); }
+    message(o) { return this.show(new MessageScreen(o)); }
+    /** One of a few values (undefined = back). */
+    async choose(path, intro, choices, current) {
+        const picked = await this.list({ path, intro, items: choices.map((c) => ({ ...c, icon: c.value === current ? Theme.ok(Theme.glyph.on) : Theme.muted(Theme.glyph.off) })), startAt: current });
+        return picked.kind === 'pick' ? picked.value : undefined;
+    }
+    /** Runs `work` on the normal screen (command output, interactive commands); the next show() takes the screen back. */
+    async suspend(work) {
+        this.terminal.stop();
+        return work();
+    }
+    /** Leaves the alternate screen for good. */
+    close() { this.terminal.stop(); }
+}

package/dist/cli/tui/dialogs.d.ts

@@ -0,0 +1,57 @@
+import type { FrameParts } from './frame.js';
+import type { Screen, Size, Step } from './app.js';
+import type { Key } from './terminal.js';
+export interface TextOptions {
+    path: string[];
+    label: string;
+    /** Explanation above the field (plain lines). */
+    about?: string[];
+    initial?: string;
+    placeholder?: string;
+    /** true = fine, a string = what is wrong (shown under the field). */
+    validate?: (value: string) => true | string;
+    /** Allow an empty answer (otherwise Enter on an empty field cancels). */
+    allowEmpty?: boolean;
+}
+/** One line of text. Resolves to the text, or undefined when you press Esc. */
+export declare class TextScreen implements Screen<string | undefined> {
+    private readonly o;
+    private value;
+    private cursor;
+    private problem;
+    constructor(o: TextOptions);
+    render(size: Size): FrameParts;
+    handle(key: Key): Step<string | undefined>;
+    private check;
+}
+export interface ConfirmOptions {
+    path: string[];
+    question: string;
+    about?: string[];
+    yes?: string;
+    no?: string;
+    initial?: boolean;
+    danger?: boolean;
+}
+/** Yes or no. Esc answers no. */
+export declare class ConfirmScreen implements Screen<boolean> {
+    private readonly o;
+    private yes;
+    constructor(o: ConfirmOptions);
+    render(size: Size): FrameParts;
+    handle(key: Key): Step<boolean>;
+}
+/** Text to read (scrolls); any key but the arrows closes it. */
+export declare class MessageScreen implements Screen<void> {
+    private readonly o;
+    private offset;
+    private height;
+    constructor(o: {
+        path: string[];
+        title?: string;
+        lines: string[];
+        tone?: 'ok' | 'warn' | 'error';
+    });
+    render(size: Size): FrameParts;
+    handle(key: Key): Step<void>;
+}

package/dist/cli/tui/dialogs.js

@@ -0,0 +1,162 @@
+import { Text } from './text.js';
+import { Theme } from './theme.js';
+/** Plain lines are wrapped to the width; coloured ones are kept as they are (the frame cuts them). */
+const paragraphs = (lines, width) => lines.flatMap((l) => (Text.strip(l) === l ? Text.wrap(l, width - 4) : [l]).map((x) => '  ' + x));
+/** One line of text. Resolves to the text, or undefined when you press Esc. */
+export class TextScreen {
+    o;
+    value;
+    cursor;
+    problem;
+    constructor(o) {
+        this.o = o;
+        this.value = o.initial ?? '';
+        this.cursor = [...this.value].length;
+    }
+    render(size) {
+        const width = Math.min(size.width - 4, 100);
+        const chars = [...this.value];
+        // Scroll the field so the cursor stays visible.
+        const inner = width - 4;
+        const start = Math.max(0, this.cursor - inner + 1);
+        const shown = chars.slice(start, start + inner);
+        const before = shown.slice(0, this.cursor - start).join('');
+        const at = shown[this.cursor - start] ?? ' ';
+        const after = shown.slice(this.cursor - start + 1).join('');
+        const text = this.value === '' && this.o.placeholder ? Theme.muted(this.o.placeholder) : before + (Theme.colour ? '\x1b[7m' + at + '\x1b[27m' : '_') + after;
+        const body = [
+            '',
+            '  ' + Theme.bold(this.o.label),
+            ...(this.o.about?.length ? paragraphs(this.o.about, size.width).map((l) => Theme.muted(l)) : []),
+            '',
+            '  ' + Theme.accent('╭' + '─'.repeat(width - 2) + '╮'),
+            '  ' + Theme.accent('│') + ' ' + Text.fit(text, inner) + ' ' + Theme.accent('│'),
+            '  ' + Theme.accent('╰' + '─'.repeat(width - 2) + '╯'),
+            this.problem ? '  ' + Theme.error(Theme.glyph.cross + ' ' + this.problem) : '',
+        ];
+        return { path: this.o.path, body, keys: [['↵', 'save'], ['esc', 'cancel'], ['ctrl+u', 'clear'], ['←→', 'move']] };
+    }
+    handle(key) {
+        const chars = [...this.value];
+        const set = (next, cursor) => { this.value = next.join(''); this.cursor = Math.max(0, Math.min(next.length, cursor)); this.check(); };
+        if (key.name === 'escape')
+            return { done: undefined };
+        if (key.name === 'return') {
+            if (this.value === '' && !this.o.allowEmpty)
+                return { done: undefined };
+            const verdict = this.o.validate?.(this.value) ?? true;
+            if (verdict !== true) {
+                this.problem = verdict;
+                return;
+            }
+            return { done: this.value };
+        }
+        if (key.name === 'left') {
+            this.cursor = Math.max(0, this.cursor - 1);
+            return;
+        }
+        if (key.name === 'right') {
+            this.cursor = Math.min(chars.length, this.cursor + 1);
+            return;
+        }
+        if (key.name === 'home') {
+            this.cursor = 0;
+            return;
+        }
+        if (key.name === 'end') {
+            this.cursor = chars.length;
+            return;
+        }
+        if (key.name === 'backspace') {
+            if (this.cursor > 0)
+                set([...chars.slice(0, this.cursor - 1), ...chars.slice(this.cursor)], this.cursor - 1);
+            return;
+        }
+        if (key.name === 'delete') {
+            set([...chars.slice(0, this.cursor), ...chars.slice(this.cursor + 1)], this.cursor);
+            return;
+        }
+        if (key.ctrl && key.name === 'u') {
+            set([], 0);
+            return;
+        }
+        if (key.text) {
+            const add = [...key.text.replace(/[\r\n]/g, '')];
+            set([...chars.slice(0, this.cursor), ...add, ...chars.slice(this.cursor)], this.cursor + add.length);
+        }
+        return;
+    }
+    check() {
+        const verdict = this.value === '' ? true : this.o.validate?.(this.value) ?? true;
+        this.problem = verdict === true ? undefined : verdict;
+    }
+}
+/** Yes or no. Esc answers no. */
+export class ConfirmScreen {
+    o;
+    yes;
+    constructor(o) {
+        this.o = o;
+        this.yes = o.initial ?? true;
+    }
+    render(size) {
+        const button = (label, on, danger = false) => (on ? (danger ? Theme.colour ? '\x1b[48;5;160m\x1b[97m ' + label + ' \x1b[0m' : '[' + label + ']' : Theme.selected(' ' + label + ' ')) : Theme.muted(' ' + label + ' '));
+        const body = [
+            '',
+            '  ' + Theme.bold(this.o.question),
+            ...(this.o.about?.length ? ['', ...paragraphs(this.o.about, size.width)] : []),
+            '',
+            '  ' + button(this.o.yes ?? 'Yes', this.yes, this.o.danger) + '   ' + button(this.o.no ?? 'No', !this.yes),
+        ];
+        return { path: this.o.path, body, keys: [['←→', 'choose'], ['↵', 'confirm'], ['y/n', 'answer'], ['esc', 'no']] };
+    }
+    handle(key) {
+        if (key.name === 'left' || key.name === 'right' || key.name === 'tab') {
+            this.yes = !this.yes;
+            return;
+        }
+        if (key.text?.toLowerCase() === 'y')
+            return { done: true };
+        if (key.text?.toLowerCase() === 'n' || key.name === 'escape')
+            return { done: false };
+        if (key.name === 'return')
+            return { done: this.yes };
+        return;
+    }
+}
+/** Text to read (scrolls); any key but the arrows closes it. */
+export class MessageScreen {
+    o;
+    offset = 0;
+    height = 10;
+    constructor(o) {
+        this.o = o;
+    }
+    render(size) {
+        const paint = this.o.tone === 'ok' ? Theme.ok : this.o.tone === 'warn' ? Theme.warn : this.o.tone === 'error' ? Theme.error : Theme.bold;
+        const head = this.o.title ? ['', '  ' + paint(this.o.title), ''] : [''];
+        const lines = this.o.lines.flatMap((l) => (Text.width(l) > size.width - 4 && Text.strip(l) === l ? Text.wrap(l, size.width - 4) : [l])).map((l) => '  ' + l);
+        this.height = size.height - head.length;
+        this.offset = Math.max(0, Math.min(this.offset, lines.length - this.height));
+        return { path: this.o.path, body: [...head, ...lines.slice(this.offset, this.offset + this.height)], keys: lines.length > this.height ? [['↑↓', 'scroll'], ['↵', 'close']] : [['any key', 'close']] };
+    }
+    handle(key) {
+        if (key.name === 'up') {
+            this.offset--;
+            return;
+        }
+        if (key.name === 'down') {
+            this.offset++;
+            return;
+        }
+        if (key.name === 'pageup') {
+            this.offset -= this.height;
+            return;
+        }
+        if (key.name === 'pagedown') {
+            this.offset += this.height;
+            return;
+        }
+        return { done: undefined };
+    }
+}

package/dist/cli/tui/frame.d.ts

@@ -0,0 +1,18 @@
+export interface FrameParts {
+    /** Where you are, e.g. ['Settings', 'Languages and tools']. */
+    path: string[];
+    /** Short line under the title (what is running, which folder). */
+    status?: string;
+    body: string[];
+    /** [key, what it does] pairs, e.g. [['↵', 'open'], ['esc', 'back']]. */
+    keys: [string, string][];
+    /** A message for the last action (saved, invalid ...), shown above the footer. */
+    notice?: string;
+}
+export declare class Frame {
+    static title: string;
+    static version: string;
+    /** Rows the body may use on a terminal `height` rows high (title, status, two rules, notice and keys take 6). */
+    static bodyHeight(height: number): number;
+    static render(parts: FrameParts, width: number, height: number): string[];
+}

package/dist/cli/tui/frame.js

@@ -0,0 +1,27 @@
+// The frame every screen is drawn in: a title bar with where you are, a status line, the screen's own body and a footer
+// with the keys that work here.
+import { Text } from './text.js';
+import { Theme } from './theme.js';
+export class Frame {
+    static title = 'Windows Development Sandbox';
+    static version = '';
+    /** Rows the body may use on a terminal `height` rows high (title, status, two rules, notice and keys take 6). */
+    static bodyHeight(height) {
+        return Math.max(3, height - 6);
+    }
+    static render(parts, width, height) {
+        const w = width - 1;
+        const crumbs = [Frame.title, ...parts.path].map((p, i, all) => (i === all.length - 1 ? Theme.bold(p) : p)).join(Theme.dim(' › '));
+        const right = Frame.version ? 'v' + Frame.version + ' ' : '';
+        const title = Theme.bar(Text.fit(' ' + Theme.accent('◆') + ' ' + crumbs, w - Text.width(right)) + right);
+        const status = ' ' + Text.truncate(parts.status ?? '', w - 2);
+        const rule = Theme.dim(Theme.glyph.line.repeat(w));
+        const bodyRows = Frame.bodyHeight(height);
+        const body = parts.body.slice(0, bodyRows);
+        while (body.length < bodyRows)
+            body.push('');
+        const notice = parts.notice ? ' ' + Text.truncate(parts.notice, w - 2) : '';
+        const keys = ' ' + parts.keys.map(([k, what]) => Theme.key(k) + ' ' + Theme.muted(what)).join('  ');
+        return [title, status, rule, ...body, notice, rule, Text.truncate(keys, w)];
+    }
+}

package/dist/cli/tui/index.d.ts

@@ -0,0 +1,7 @@
+export { App, type Screen, type Size, type Step } from './app.js';
+export { ConfirmScreen, MessageScreen, TextScreen } from './dialogs.js';
+export { Frame } from './frame.js';
+export { ListScreen, type Category, type ListItem, type ListOptions, type ListResult, type Tab } from './list-screen.js';
+export { ExitRequested, Terminal, type Key } from './terminal.js';
+export { Text } from './text.js';
+export { Theme } from './theme.js';

package/dist/cli/tui/index.js

@@ -0,0 +1,8 @@
+// The menu's screen toolkit: a full-screen app (App) showing one screen at a time in a common frame.
+export { App } from './app.js';
+export { ConfirmScreen, MessageScreen, TextScreen } from './dialogs.js';
+export { Frame } from './frame.js';
+export { ListScreen } from './list-screen.js';
+export { ExitRequested, Terminal } from './terminal.js';
+export { Text } from './text.js';
+export { Theme } from './theme.js';

package/dist/cli/tui/list-screen.d.ts

@@ -0,0 +1,101 @@
+import type { FrameParts } from './frame.js';
+import type { Screen, Size, Step } from './app.js';
+import type { Key } from './terminal.js';
+export interface ListItem<T> {
+    value: T;
+    label: string;
+    /** Right-hand column: a setting's value, a size, a state. */
+    hint?: string;
+    description?: string;
+    /** Extra lines for the details pane (already formatted). */
+    details?: string[];
+    /** Heading the entry is listed under (entries with the same section should be next to each other). */
+    section?: string;
+    /** Sidebar category id. */
+    category?: string;
+    /** More words search should find it by. */
+    keywords?: string;
+    /** Why it cannot be picked (shown dim). */
+    disabled?: string;
+    /** Multi-select: ticked. */
+    checked?: boolean;
+    /** A glyph before the label. */
+    icon?: string;
+}
+export interface Category {
+    id: string;
+    label: string;
+    description?: string;
+}
+export interface ListAction {
+    key: string;
+    label: string;
+}
+/** Tabs above the list (e.g. which settings file): Tab switches, the screen reopens on the other one. */
+export interface Tab {
+    label: string;
+    badge: string;
+    paint: (text: string) => string;
+}
+export type ListResult<T> = {
+    kind: 'pick';
+    value: T;
+} | {
+    kind: 'back';
+} | {
+    kind: 'action';
+    key: string;
+    value: T | undefined;
+} | {
+    kind: 'multi';
+    values: T[];
+} | {
+    kind: 'tab';
+    index: number;
+};
+export interface ListOptions<T> {
+    path: string[];
+    status?: string;
+    /** A line or two above the list. */
+    intro?: string | string[];
+    items: ListItem<T>[];
+    categories?: Category[];
+    multi?: boolean;
+    /** Start on this entry (and its category). */
+    startAt?: T;
+    startCategory?: string;
+    actions?: ListAction[];
+    notice?: string;
+    empty?: string;
+    tabs?: {
+        items: Tab[];
+        active: number;
+    };
+    /** What Esc does, for the footer ("back", "quit"). */
+    escapeLabel?: string;
+}
+export declare class ListScreen<T> implements Screen<ListResult<T>> {
+    private readonly o;
+    private category;
+    private focus;
+    private cursor;
+    private offset;
+    private query;
+    private searching;
+    private notice;
+    private readonly checked;
+    constructor(o: ListOptions<T>);
+    /** Indexes of the entries shown now: all matches of the search, else the current category's, else all. */
+    private visible;
+    private rows;
+    render(size: Size): FrameParts;
+    private rowLine;
+    private sideLines;
+    private detailsLines;
+    private keys;
+    /** Programmatic notice (e.g. "Saved") shown until the next key. */
+    setNotice(text: string | undefined): void;
+    handle(key: Key): Step<ListResult<T>>;
+    private toggle;
+    private switchCategory;
+}