windows-development-sandbox 1.1.0 → 1.4.0

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

package/dist/cli/tui/list-screen.js

@@ -0,0 +1,299 @@
+import { Text } from './text.js';
+import { Theme } from './theme.js';
+export class ListScreen {
+    o;
+    category = 0;
+    focus = 'list';
+    cursor = 0;
+    offset = 0;
+    query = '';
+    searching = false;
+    notice;
+    checked;
+    constructor(o) {
+        this.o = o;
+        this.notice = o.notice;
+        this.checked = new Set(o.items.flatMap((item, i) => (item.checked ? [i] : [])));
+        const start = o.startAt === undefined ? -1 : o.items.findIndex((item) => item.value === o.startAt);
+        const startCategory = start >= 0 ? o.items[start].category : o.startCategory;
+        if (o.categories && startCategory)
+            this.category = Math.max(0, o.categories.findIndex((c) => c.id === startCategory));
+        if (start >= 0)
+            this.cursor = Math.max(0, this.visible().indexOf(start));
+    }
+    /** Indexes of the entries shown now: all matches of the search, else the current category's, else all. */
+    visible() {
+        const all = this.o.items.map((_, i) => i);
+        if (this.query.trim()) {
+            const words = this.query.toLowerCase().split(/\s+/).filter(Boolean);
+            const label = (id) => this.o.categories?.find((c) => c.id === id)?.label ?? '';
+            return all.filter((i) => {
+                const it = this.o.items[i];
+                const hay = [it.label, Text.strip(it.hint ?? ''), it.description, it.keywords, it.section, label(it.category)].join(' ').toLowerCase();
+                return words.every((w) => hay.includes(w));
+            });
+        }
+        const cat = this.o.categories?.[this.category];
+        return cat ? all.filter((i) => this.o.items[i].category === cat.id) : all;
+    }
+    rows(visible) {
+        const rows = [];
+        let section;
+        const searchAll = Boolean(this.query.trim() && this.o.categories);
+        for (const index of visible) {
+            const it = this.o.items[index];
+            const heading = searchAll ? [this.o.categories?.find((c) => c.id === it.category)?.label, it.section].filter(Boolean).join(' › ') : it.section;
+            if (heading && heading !== section)
+                rows.push({ kind: 'section', text: heading });
+            section = heading;
+            rows.push({ kind: 'item', index });
+        }
+        return rows;
+    }
+    render(size) {
+        const visible = this.visible();
+        this.cursor = Math.min(this.cursor, Math.max(0, visible.length - 1));
+        const sideWidth = this.o.categories ? Math.min(32, Math.max(...this.o.categories.map((c) => Text.width(c.label))) + 7) : 0;
+        const rest = size.width - 1 - (sideWidth ? sideWidth + 3 : 0);
+        const detailsRight = rest >= 100;
+        const detailsWidth = detailsRight ? Math.min(52, Math.floor(rest * 0.38)) : rest;
+        const listWidth = detailsRight ? rest - detailsWidth - 3 : rest;
+        const top = [];
+        if (this.o.tabs)
+            top.push(' ' + this.o.tabs.items.map((tab, i) => (i === this.o.tabs.active ? tab.paint(' ' + tab.badge + ' ' + tab.label + ' ') : Theme.muted('  ' + tab.label + '  '))).join(' ') + Theme.muted('   tab switches'), '');
+        const intro = typeof this.o.intro === 'string' ? [this.o.intro] : this.o.intro ?? [];
+        for (const line of intro)
+            top.push(...Text.wrap(line, size.width - 3).map((l) => ' ' + Theme.muted(l)));
+        if (this.searching || this.query)
+            top.push(' ' + Theme.accent(Theme.glyph.search) + ' ' + this.query + (this.searching ? Theme.accent('▏') : '') + Theme.muted('   ' + visible.length + ' match' + (visible.length === 1 ? '' : 'es')));
+        if (top.length)
+            top.push('');
+        const details = this.detailsLines(visible[this.cursor], detailsWidth);
+        const bottomDetails = !detailsRight && size.height - top.length >= 14 ? details.slice(0, 6) : [];
+        const rows = this.rows(visible);
+        const room = size.height - top.length - (bottomDetails.length ? bottomDetails.length + 1 : 0);
+        // A list longer than the room keeps one row for "▲ / ▼ more".
+        const listHeight = rows.length > room ? room - 1 : room;
+        const cursorRow = rows.findIndex((r) => r.kind === 'item' && r.index === visible[this.cursor]);
+        if (cursorRow >= 0) {
+            // Keep the heading above the first entry in view, and the cursor inside the window.
+            const want = cursorRow > 0 && rows[cursorRow - 1].kind === 'section' ? cursorRow - 1 : cursorRow;
+            if (want < this.offset)
+                this.offset = want;
+            if (cursorRow >= this.offset + listHeight)
+                this.offset = cursorRow - listHeight + 1;
+        }
+        this.offset = Math.max(0, Math.min(this.offset, Math.max(0, rows.length - listHeight)));
+        const listLines = rows.slice(this.offset, this.offset + listHeight).map((row) => this.rowLine(row, visible, listWidth));
+        if (!visible.length)
+            listLines.push('', '  ' + Theme.muted(this.query ? 'Nothing matches "' + this.query + '".' : this.o.empty ?? 'Nothing here yet.'));
+        if (rows.length > listHeight) {
+            const above = this.offset;
+            const below = rows.length - this.offset - listHeight;
+            listLines.push(Theme.muted('   ' + (above > 0 ? '▲ ' + above + ' above' : '') + (above > 0 && below > 0 ? '   ' : '') + (below > 0 ? '▼ ' + below + ' more' : '')));
+        }
+        const sideLines = this.sideLines(sideWidth);
+        const body = [...top];
+        const height = Math.max(listLines.length, detailsRight ? details.length : 0, sideLines.length);
+        for (let i = 0; i < Math.min(height, size.height - top.length); i++) {
+            const side = sideWidth ? Text.fit(sideLines[i] ?? '', sideWidth) + ' ' + Theme.dim(Theme.glyph.vline) + ' ' : '';
+            const main = Text.fit(listLines[i] ?? '', listWidth);
+            const right = detailsRight ? ' ' + Theme.dim(Theme.glyph.vline) + ' ' + (details[i] ?? '') : '';
+            body.push(side + main + right);
+        }
+        if (bottomDetails.length) {
+            // The details sit at the bottom, whatever the length of the list.
+            while (body.length < size.height - bottomDetails.length - 1)
+                body.push(sideWidth ? Text.fit(sideLines[body.length - top.length] ?? '', sideWidth) + ' ' + Theme.dim(Theme.glyph.vline) : '');
+            body.push(Theme.dim(' ' + Theme.glyph.line.repeat(size.width - 3)), ...bottomDetails.map((l) => ' ' + l));
+        }
+        return { path: this.o.path, status: this.o.status, body, keys: this.keys(), notice: this.notice };
+    }
+    rowLine(row, visible, width) {
+        if (row.kind === 'section')
+            return ' ' + Theme.accentBold(row.text);
+        const it = this.o.items[row.index];
+        const selected = visible[this.cursor] === row.index;
+        const box = this.o.multi ? (this.checked.has(row.index) ? Theme.ok(Theme.glyph.checked) : Theme.muted(Theme.glyph.unchecked)) + ' ' : '';
+        const icon = it.icon ? it.icon + ' ' : '';
+        const hint = it.hint ?? '';
+        const hintWidth = Math.min(Text.width(hint), Math.floor(width * 0.5));
+        const labelWidth = width - 4 - Text.width(box) - Text.width(icon) - (hintWidth ? hintWidth + 2 : 0);
+        const label = it.disabled ? Theme.muted(it.label) : it.label;
+        const line = (selected ? Theme.glyph.pointer : ' ') + ' ' + box + icon + Text.fit(label, labelWidth) + (hintWidth ? '  ' + Text.fit(hint, hintWidth, 'right') : '') + ' ';
+        if (!selected)
+            return ' ' + line;
+        return this.focus === 'list' ? ' ' + Theme.selected(Text.strip(line)) : ' ' + Theme.accent(Text.strip(line));
+    }
+    sideLines(width) {
+        if (!this.o.categories)
+            return [];
+        return this.o.categories.map((cat, i) => {
+            const count = this.o.items.filter((it) => it.category === cat.id).length;
+            const text = ' ' + Text.fit(cat.label, width - 6) + ' ' + Text.fit(String(count), 3, 'right') + ' ';
+            if (i !== this.category)
+                return Theme.muted(text);
+            return this.focus === 'side' ? Theme.selected(text) : Theme.accentBold(text);
+        });
+    }
+    detailsLines(index, width) {
+        const w = Math.max(10, width - 1);
+        if (this.focus === 'side' && this.o.categories) {
+            const cat = this.o.categories[this.category];
+            return [Theme.bold(cat.label), ...(cat.description ? Text.wrap(cat.description, w).map((l) => Theme.muted(l)) : [])];
+        }
+        if (index === undefined)
+            return [];
+        const it = this.o.items[index];
+        return [
+            Theme.bold(Text.truncate(it.label, w)),
+            ...(it.description ? Text.wrap(it.description, w).map((l) => Theme.muted(l)) : []),
+            ...(it.details?.length ? ['', ...it.details.flatMap((d) => Text.wrap(d, w))] : []),
+            ...(it.disabled ? ['', Theme.warn(it.disabled)] : []),
+        ];
+    }
+    keys() {
+        if (this.searching)
+            return [['type', 'to search'], ['↑↓', 'move'], ['↵', this.o.multi ? 'done' : 'open'], ['esc', 'clear search']];
+        return [
+            ['↑↓', 'move'],
+            ...(this.o.tabs ? [['tab', 'switch ' + this.o.tabs.items.map((t) => t.label.toLowerCase()).join(' / ')]] : []),
+            ...(this.o.categories ? [['←→', 'categories']] : []),
+            ...(this.o.multi ? [['space', 'tick'], ['a', 'tick all shown'], ['↵', 'done']] : [['↵', 'open']]),
+            ['/', 'search'],
+            ...(this.o.actions ?? []).map((a) => [a.key, a.label]),
+            ['esc', this.o.escapeLabel ?? 'back'],
+        ];
+    }
+    /** Programmatic notice (e.g. "Saved") shown until the next key. */
+    setNotice(text) { this.notice = text; }
+    handle(key) {
+        const visible = this.visible();
+        const current = visible[this.cursor];
+        this.notice = undefined;
+        const move = (by) => { this.cursor = Math.max(0, Math.min(visible.length - 1, this.cursor + by)); };
+        if (key.name === 'up') {
+            if (this.focus === 'side')
+                this.switchCategory(-1);
+            else
+                move(-1);
+            return;
+        }
+        if (key.name === 'down') {
+            if (this.focus === 'side')
+                this.switchCategory(1);
+            else
+                move(1);
+            return;
+        }
+        if (key.name === 'pageup') {
+            move(-10);
+            return;
+        }
+        if (key.name === 'pagedown') {
+            move(10);
+            return;
+        }
+        if (key.name === 'home') {
+            this.cursor = 0;
+            return;
+        }
+        if (key.name === 'end') {
+            this.cursor = visible.length - 1;
+            return;
+        }
+        if (this.searching) {
+            if (key.name === 'escape') {
+                this.searching = false;
+                this.query = '';
+                this.cursor = 0;
+                return;
+            }
+            if (key.name === 'backspace') {
+                if (this.query)
+                    this.query = this.query.slice(0, -1);
+                else
+                    this.searching = false;
+                this.cursor = 0;
+                return;
+            }
+            // In a tick list, space always ticks (even while searching).
+            if (key.name !== 'return' && key.text && !(this.o.multi && key.name === 'space')) {
+                this.query += key.text;
+                this.cursor = 0;
+                return;
+            }
+        }
+        if (this.o.tabs && key.name === 'tab') {
+            const n = this.o.tabs.items.length;
+            return { done: { kind: 'tab', index: (this.o.tabs.active + (key.shift ? n - 1 : 1)) % n } };
+        }
+        if (this.o.categories && !this.query) {
+            if (key.name === 'left' && this.focus === 'list') {
+                this.focus = 'side';
+                return;
+            }
+            if ((key.name === 'right' || key.name === 'return') && this.focus === 'side') {
+                this.focus = 'list';
+                return;
+            }
+        }
+        if (key.name === 'escape' || (key.name === 'backspace' && !this.searching)) {
+            if (this.query) {
+                this.query = '';
+                this.cursor = 0;
+                return;
+            }
+            return { done: { kind: 'back' } };
+        }
+        if (key.text === '/' || (key.name === 'f' && key.ctrl)) {
+            this.searching = true;
+            this.focus = 'list';
+            return;
+        }
+        if (this.o.multi) {
+            if (key.name === 'space' && current !== undefined) {
+                this.toggle(current);
+                return;
+            }
+            if (key.text === 'a') {
+                const all = visible.filter((i) => !this.o.items[i].disabled);
+                const tick = all.some((i) => !this.checked.has(i));
+                all.forEach((i) => (tick ? this.checked.add(i) : this.checked.delete(i)));
+                return;
+            }
+            if (key.name === 'return')
+                return { done: { kind: 'multi', values: this.o.items.filter((_, i) => this.checked.has(i)).map((it) => it.value) } };
+        }
+        if ((key.name === 'return' || key.name === 'right' || (key.name === 'space' && !this.searching)) && current !== undefined && !this.o.multi) {
+            const it = this.o.items[current];
+            if (it.disabled) {
+                this.notice = Theme.warn(it.disabled);
+                return;
+            }
+            return { done: { kind: 'pick', value: it.value } };
+        }
+        const action = !this.searching && key.text ? this.o.actions?.find((a) => a.key === key.text) : undefined;
+        if (action)
+            return { done: { kind: 'action', key: action.key, value: current === undefined ? undefined : this.o.items[current].value } };
+        return;
+    }
+    toggle(index) {
+        if (this.o.items[index].disabled) {
+            this.notice = Theme.warn(this.o.items[index].disabled);
+            return;
+        }
+        if (this.checked.has(index))
+            this.checked.delete(index);
+        else
+            this.checked.add(index);
+    }
+    switchCategory(by) {
+        const count = this.o.categories?.length ?? 0;
+        if (!count)
+            return;
+        this.category = (this.category + by + count) % count;
+        this.cursor = 0;
+        this.offset = 0;
+    }
+}

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

@@ -0,0 +1,37 @@
+/** One key press: `name` for special keys (up, return, escape, f1 ...), `text` for something typed. */
+export interface Key {
+    name: string;
+    text: string;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+}
+/** Ctrl+C: leave the menu at once (callers let it propagate to the top). */
+export declare class ExitRequested extends Error {
+    constructor();
+}
+export declare class Terminal {
+    private readonly stdin;
+    private readonly stdout;
+    private active;
+    private frame;
+    private queue;
+    private waiting;
+    private resizeHandler;
+    private readonly onKeypress;
+    private readonly onResize;
+    constructor(stdin?: NodeJS.ReadStream, stdout?: NodeJS.WriteStream);
+    get width(): number;
+    get height(): number;
+    /** Called after the window was resized (the screen draws itself again). */
+    onResized(handler: (() => void) | null): void;
+    start(): void;
+    /** Gives the terminal back exactly as it was (also on errors: callers use try/finally). */
+    stop(): void;
+    get running(): boolean;
+    /** Draws a whole screen: `lines` are cut to the width and padded to the height; unchanged rows are not rewritten. */
+    render(lines: string[]): void;
+    /** The next key press. Ctrl+C rejects with ExitRequested. */
+    key(): Promise<Key>;
+    private push;
+}

package/dist/cli/tui/terminal.js

@@ -0,0 +1,89 @@
+// The terminal while the menu owns it: the alternate screen (your scrollback stays as it was), raw keys, a cursor that
+// is hidden, and redraws that only rewrite the rows that changed (no flicker). suspend() hands the terminal back for
+// a command's own output; resume() takes it again.
+import readline from 'node:readline';
+import { Text } from './text.js';
+/** Ctrl+C: leave the menu at once (callers let it propagate to the top). */
+export class ExitRequested extends Error {
+    constructor() { super('Ctrl+C'); this.name = 'ExitPromptError'; }
+}
+export class Terminal {
+    stdin;
+    stdout;
+    active = false;
+    frame = [];
+    queue = [];
+    waiting = null;
+    resizeHandler = null;
+    onKeypress = (str, key) => this.push(str, key);
+    onResize = () => { this.frame = []; this.resizeHandler?.(); };
+    constructor(stdin = process.stdin, stdout = process.stdout) {
+        this.stdin = stdin;
+        this.stdout = stdout;
+    }
+    get width() { return Math.max(40, this.stdout.columns ?? 80); }
+    get height() { return Math.max(12, this.stdout.rows ?? 30); }
+    /** Called after the window was resized (the screen draws itself again). */
+    onResized(handler) { this.resizeHandler = handler; }
+    start() {
+        if (this.active)
+            return;
+        this.active = true;
+        this.frame = [];
+        readline.emitKeypressEvents(this.stdin);
+        if (this.stdin.isTTY)
+            this.stdin.setRawMode(true);
+        this.stdin.on('keypress', this.onKeypress);
+        this.stdin.resume();
+        this.stdout.on('resize', this.onResize);
+        this.stdout.write('\x1b[?1049h\x1b[?25l\x1b[H\x1b[2J');
+    }
+    /** Gives the terminal back exactly as it was (also on errors: callers use try/finally). */
+    stop() {
+        if (!this.active)
+            return;
+        this.active = false;
+        this.stdin.off('keypress', this.onKeypress);
+        this.stdout.off('resize', this.onResize);
+        if (this.stdin.isTTY)
+            this.stdin.setRawMode(false);
+        this.stdin.pause();
+        this.queue = [];
+        this.stdout.write('\x1b[0m\x1b[?25h\x1b[?1049l');
+    }
+    get running() { return this.active; }
+    /** Draws a whole screen: `lines` are cut to the width and padded to the height; unchanged rows are not rewritten. */
+    render(lines) {
+        const { width, height } = this;
+        // One column is left free: writing the last column can scroll older consoles.
+        const rows = Array.from({ length: height }, (_, i) => Text.fit(lines[i] ?? '', width - 1));
+        let out = '';
+        rows.forEach((row, i) => { if (this.frame[i] !== row)
+            out += '\x1b[' + (i + 1) + ';1H' + row + '\x1b[0m'; });
+        if (this.frame.length !== rows.length)
+            out = '\x1b[H\x1b[2J' + rows.map((r, i) => '\x1b[' + (i + 1) + ';1H' + r + '\x1b[0m').join('');
+        this.frame = rows;
+        if (out)
+            this.stdout.write(out);
+    }
+    /** The next key press. Ctrl+C rejects with ExitRequested. */
+    key() {
+        const next = this.queue.shift();
+        if (next)
+            return next.ctrl && next.name === 'c' ? Promise.reject(new ExitRequested()) : Promise.resolve(next);
+        return new Promise((resolve, reject) => { this.waiting = { resolve, reject }; });
+    }
+    push(str, key) {
+        const event = { name: key?.name ?? '', text: str && !key?.ctrl && !key?.meta && str.length >= 1 && str >= ' ' && str !== '\x7f' ? str : '', ctrl: Boolean(key?.ctrl), meta: Boolean(key?.meta), shift: Boolean(key?.shift) };
+        const waiting = this.waiting;
+        if (!waiting) {
+            this.queue.push(event);
+            return;
+        }
+        this.waiting = null;
+        if (event.ctrl && event.name === 'c')
+            waiting.reject(new ExitRequested());
+        else
+            waiting.resolve(event);
+    }
+}

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

@@ -0,0 +1,20 @@
+export declare class Text {
+    /** Removes colour and cursor codes. */
+    static strip(text: string): string;
+    /** Columns one character takes: 2 for East Asian wide characters and most emoji, 0 for combining marks. */
+    static charWidth(code: number): number;
+    /** Columns `text` takes on screen. */
+    static width(text: string): number;
+    /**
+     * The first `max` columns of `text`, keeping colour codes (and closing them), with an ellipsis when something was cut.
+     */
+    static truncate(text: string, max: number, ellipsis?: string): string;
+    /** `text` cut or padded with spaces to exactly `width` columns. */
+    static fit(text: string, width: number, align?: 'left' | 'right'): string;
+    /** Cuts the middle out of a long path so both ends stay readable (plain text). */
+    static middle(text: string, max: number): string;
+    /** Word-wraps plain text to `width` columns (long words are split); keeps the text's own line breaks. */
+    static wrap(text: string, width: number): string[];
+    /** "memoryMb" -> "Memory MB", "vGpu" -> "V GPU": a readable label from a setting's key. */
+    static humanize(key: string): string;
+}

package/dist/cli/tui/text.js

@@ -0,0 +1,105 @@
+// Measuring and laying out terminal text that may hold colour codes: visible width, padding, cutting and wrapping.
+// Pure (tested), so every screen lines up the same way.
+const ANSI = /\x1b\[[0-9;?]*[A-Za-z]/g;
+export class Text {
+    /** Removes colour and cursor codes. */
+    static strip(text) {
+        return text.replace(ANSI, '');
+    }
+    /** Columns one character takes: 2 for East Asian wide characters and most emoji, 0 for combining marks. */
+    static charWidth(code) {
+        if (code < 32 || (code >= 0x7f && code < 0xa0))
+            return 0;
+        if ((code >= 0x300 && code <= 0x36f) || (code >= 0x200b && code <= 0x200f) || code === 0xfe0f)
+            return 0;
+        const wide = (code >= 0x1100 && code <= 0x115f) || (code >= 0x2e80 && code <= 0xa4cf) || (code >= 0xac00 && code <= 0xd7a3)
+            || (code >= 0xf900 && code <= 0xfaff) || (code >= 0xfe30 && code <= 0xfe4f) || (code >= 0xff00 && code <= 0xff60)
+            || (code >= 0xffe0 && code <= 0xffe6) || (code >= 0x1f300 && code <= 0x1faff) || (code >= 0x20000 && code <= 0x3fffd);
+        return wide ? 2 : 1;
+    }
+    /** Columns `text` takes on screen. */
+    static width(text) {
+        let width = 0;
+        for (const ch of Text.strip(text))
+            width += Text.charWidth(ch.codePointAt(0));
+        return width;
+    }
+    /**
+     * The first `max` columns of `text`, keeping colour codes (and closing them), with an ellipsis when something was cut.
+     */
+    static truncate(text, max, ellipsis = '…') {
+        if (max <= 0)
+            return '';
+        if (Text.width(text) <= max)
+            return text;
+        const room = max - Text.width(ellipsis);
+        let out = '';
+        let used = 0;
+        let coloured = false;
+        for (let i = 0; i < text.length;) {
+            const code = /^\x1b\[[0-9;?]*[A-Za-z]/.exec(text.slice(i));
+            if (code) {
+                out += code[0];
+                coloured = code[0] !== '\x1b[0m';
+                i += code[0].length;
+                continue;
+            }
+            const ch = String.fromCodePoint(text.codePointAt(i));
+            const w = Text.charWidth(ch.codePointAt(0));
+            if (used + w > room)
+                break;
+            out += ch;
+            used += w;
+            i += ch.length;
+        }
+        return out + (coloured ? '\x1b[0m' : '') + ellipsis;
+    }
+    /** `text` cut or padded with spaces to exactly `width` columns. */
+    static fit(text, width, align = 'left') {
+        const cut = Text.truncate(text, width);
+        const gap = ' '.repeat(Math.max(0, width - Text.width(cut)));
+        return align === 'left' ? cut + gap : gap + cut;
+    }
+    /** Cuts the middle out of a long path so both ends stay readable (plain text). */
+    static middle(text, max) {
+        if (max < 5 || text.length <= max)
+            return text;
+        const keep = max - 1;
+        const head = Math.ceil(keep / 2);
+        return text.slice(0, head) + '…' + text.slice(text.length - (keep - head));
+    }
+    /** Word-wraps plain text to `width` columns (long words are split); keeps the text's own line breaks. */
+    static wrap(text, width) {
+        const lines = [];
+        for (const paragraph of text.split(/\r?\n/)) {
+            let line = '';
+            for (const word of paragraph.split(/ +/)) {
+                let rest = word;
+                while (Text.width(rest) > width) {
+                    if (line) {
+                        lines.push(line);
+                        line = '';
+                    }
+                    lines.push(rest.slice(0, width));
+                    rest = rest.slice(width);
+                }
+                if (!line)
+                    line = rest;
+                else if (Text.width(line) + 1 + Text.width(rest) <= width)
+                    line += ' ' + rest;
+                else {
+                    lines.push(line);
+                    line = rest;
+                }
+            }
+            lines.push(line);
+        }
+        return lines;
+    }
+    /** "memoryMb" -> "Memory MB", "vGpu" -> "V GPU": a readable label from a setting's key. */
+    static humanize(key) {
+        const words = key.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ').split(' ').filter(Boolean);
+        const upper = new Set(['mb', 'gb', 'cpu', 'gpu', 'jdk', 'sdk', 'id', 'url', 'ui', 'npm', 'msvc', 'uv', 'api', 'ssh', 'vm', 'io']);
+        return words.map((w, i) => (upper.has(w.toLowerCase()) ? w.toUpperCase() : i === 0 ? w[0].toUpperCase() + w.slice(1) : w.toLowerCase())).join(' ');
+    }
+}