@timurproko/a1 0.1.1-dev.6 → 0.1.1-dev.7

package/dist/src/features/owned-ui/settings-app.js

@@ -0,0 +1,631 @@
+import { GLOBAL_SCOPE, LineInput, PLAIN_THEME, ShortcutRegistry, PROMPT_GLYPH, blockJumpTarget, dialogValueColumn, numericValues, RAIL_COLUMNS, renderDialogPanel, renderEmptyState, renderGroupHeader, renderInputRow, renderStatusLine, renderListRow, renderNote, dialogRowAt, menuRowAt, regionAt, renderValueMenu, withScrollbarRail, stepperEnds, steppedValue, valueColumnFor, valueMenuFrame, promptRule, caretCell, blockRowSpan, displayWidth, faint, handleLineInputKey, humanizeLabel, humanizeTitle, indexOfKey, isThumbRow, layoutList, moveSelection, rowKey, scrollForSelection, scrollbarGeometry, selectableIndexes, } from "../../foundation/ui-components/index.js";
+export const SETTINGS_APP_ID = "settings";
+export const SETTINGS_ROUTE = "settings";
+const SCOPE = SETTINGS_APP_ID;
+/** The panel a setting with parts opens: its own keys, its own hint. */
+const DIALOG_SCOPE = `${SETTINGS_APP_ID}-parts`;
+const SCROLLBAR_TOP_INSET = 1;
+const SEARCH_PLACEHOLDER = "search settings";
+/** What a structured value offers instead of printing itself. */
+const CONFIGURE = "configure";
+export const SETTINGS_SHORTCUTS = new ShortcutRegistry();
+SETTINGS_SHORTCUTS.declare({ key: "/", scope: SCOPE, description: "Search settings", section: "Change", hint: { keys: "/", does: "to search" } }, "open-filter");
+SETTINGS_SHORTCUTS.declare({ key: "up", scope: SCOPE, description: "Previous setting", section: "Navigate", hint: { keys: "↑↓", does: "to navigate" } }, "move-up");
+SETTINGS_SHORTCUTS.declare({ key: "down", scope: SCOPE, description: "Next setting", section: "Navigate", hint: { keys: "↑↓", does: "to navigate" } }, "move-down");
+SETTINGS_SHORTCUTS.declare({ key: "shift+up", scope: SCOPE, description: "Previous section", section: "Navigate", hint: { keys: "Shift+↑↓", does: "to jump" } }, "block-up");
+SETTINGS_SHORTCUTS.declare({ key: "shift+down", scope: SCOPE, description: "Next section", section: "Navigate", hint: { keys: "Shift+↑↓", does: "to jump" } }, "block-down");
+SETTINGS_SHORTCUTS.declare({ key: "pageUp", scope: SCOPE, description: "Up a page", section: "Navigate" }, "page-up");
+SETTINGS_SHORTCUTS.declare({ key: "pageDown", scope: SCOPE, description: "Down a page", section: "Navigate" }, "page-down");
+SETTINGS_SHORTCUTS.declare({ key: "home", scope: SCOPE, description: "First setting", section: "Navigate" }, "first");
+SETTINGS_SHORTCUTS.declare({ key: "end", scope: SCOPE, description: "Last setting", section: "Navigate" }, "last");
+SETTINGS_SHORTCUTS.declare({ key: "enter", scope: SCOPE, description: "Change value", section: "Change", hint: { keys: "Enter/Space", does: "to change" } }, "activate");
+SETTINGS_SHORTCUTS.declare({ key: "space", scope: SCOPE, description: "Change value", section: "Change", hint: { keys: "Enter/Space", does: "to change" } }, "activate");
+SETTINGS_SHORTCUTS.declare({ key: "left", scope: SCOPE, description: "Previous value", section: "Change", hint: { keys: "←→", does: "to adjust" } }, "previous-value");
+SETTINGS_SHORTCUTS.declare({ key: "right", scope: SCOPE, description: "Next value", section: "Change", hint: { keys: "←→", does: "to adjust" } }, "next-value");
+SETTINGS_SHORTCUTS.declare({ key: "escape", scope: GLOBAL_SCOPE, description: "Close", section: "Screen", hint: { keys: "Esc", does: "to cancel" } }, "close");
+SETTINGS_SHORTCUTS.declare({ key: "enter", scope: DIALOG_SCOPE, description: "Change this part", section: "Parts", hint: { keys: "Enter/Space", does: "to change" } }, "part-change");
+SETTINGS_SHORTCUTS.declare({ key: "space", scope: DIALOG_SCOPE, description: "Change this part", section: "Parts", hint: { keys: "Enter/Space", does: "to change" } }, "part-change");
+SETTINGS_SHORTCUTS.declare({ key: "left", scope: DIALOG_SCOPE, description: "Change this part", section: "Parts" }, "part-change");
+SETTINGS_SHORTCUTS.declare({ key: "right", scope: DIALOG_SCOPE, description: "Change this part", section: "Parts" }, "part-change");
+SETTINGS_SHORTCUTS.declare({ key: "up", scope: DIALOG_SCOPE, description: "Previous part", section: "Parts" }, "part-previous");
+SETTINGS_SHORTCUTS.declare({ key: "down", scope: DIALOG_SCOPE, description: "Next part", section: "Parts" }, "part-next");
+const KEYS = {
+    "\u001b[A": "up",
+    "\u001b[B": "down",
+    "\u001b[1;2A": "shift+up",
+    "\u001b[1;2B": "shift+down",
+    "\u001b[D": "left",
+    "\u001b[C": "right",
+    "\u001b[5~": "pageUp",
+    "\u001b[6~": "pageDown",
+    "\u001b[H": "home",
+    "\u001b[F": "end",
+    "\u001b": "escape",
+    "\r": "enter",
+    "\n": "enter",
+    " ": "space",
+    "/": "/",
+};
+/**
+ * The settings screen. Rows, sticky headers, scrolling, and the keymap come from
+ * the shared component layer; what belongs to settings is which sections exist,
+ * how a value is shown, and where an accepted change is routed.
+ */
+export class SettingsApp {
+    id = SETTINGS_APP_ID;
+    #session;
+    #selectedKey;
+    #scroll = 0;
+    #reveal;
+    #notice = null;
+    #filter = null;
+    #menu = null;
+    #structured = null;
+    #loading = true;
+    #interruptArmed = false;
+    /** Values requested but not yet reflected by the source, keyed by entry. */
+    #pending = new Map();
+    #footerHeight = 1;
+    /** Column the dialog's values start at, so a label stays a label. */
+    #dialogValueColumn = 0;
+    /** Screen row the dialog panel starts on, for pointer hits. */
+    #panelTop = 0;
+    #panelTopForFrame = 0;
+    /** Row key under the pointer, and where each row was drawn last frame. */
+    #hoverKey = null;
+    #hoverRegion = "label";
+    #frameRows = [];
+    /** Where the value menu was drawn last frame, for hit testing. */
+    #menuFrame = null;
+    constructor(session) {
+        this.#session = session;
+    }
+    onActivate(host) {
+        void this.#session.load().then(() => {
+            this.#loading = false;
+            host.requestRender();
+        });
+    }
+    render(rect, host) {
+        const theme = host.theme ?? PLAIN_THEME;
+        this.#interruptArmed = host.interruptArmed;
+        const rows = this.#rows();
+        const footer = this.#footerLines(rect.width, theme);
+        this.#footerHeight = footer.length;
+        this.#panelTopForFrame = Math.max(0, rect.height - footer.length);
+        this.#panelTop = this.#panelTopForFrame;
+        const bodyHeight = Math.max(0, rect.height - footer.length);
+        const selected = indexOfKey(rows, this.#selectedKey);
+        this.#scroll = scrollForSelection(rows, bodyHeight, this.#scroll, selected, this.#reveal);
+        this.#reveal = undefined;
+        const layout = layoutList(rows, bodyHeight, this.#scroll);
+        const contentWidth = Math.max(0, rect.width - RAIL_COLUMNS);
+        const valueColumn = this.#valueColumn(rows);
+        const geometry = scrollbarGeometry({
+            contentLength: rows.length,
+            viewportHeight: layout.visible,
+            scroll: layout.scroll,
+            trackHeight: Math.max(0, bodyHeight - SCROLLBAR_TOP_INSET),
+        });
+        const body = [];
+        this.#frameRows = [];
+        if (rows.length === 0) {
+            const message = this.#loading ? "Loading settings…" : "No settings found.";
+            body.push(...renderEmptyState(message, "👀", bodyHeight, contentWidth, theme));
+        }
+        else {
+            if (layout.topPadding > 0)
+                body.push("");
+            if (layout.stickyHeader !== undefined)
+                body.push(this.#header(layout.stickyHeader, theme, contentWidth));
+            for (const index of layout.rowIndexes) {
+                const row = rows[index];
+                if (row !== undefined && row.kind === "element") {
+                    this.#frameRows.push({
+                        key: `${row.value.backend}:${row.value.id}`,
+                        screenRow: body.length,
+                        valueColumn,
+                        valueWidth: row.value.structured
+                            ? CONFIGURE.length
+                            : row.value.value === null ? 0 : displayWidth(displayValue(row.value.value)),
+                        stepper: isStepper(row.value),
+                    });
+                }
+                body.push(this.#renderRow(row, index === selected, contentWidth, valueColumn, theme));
+            }
+            while (body.length < bodyHeight)
+                body.push("");
+        }
+        const withRail = withScrollbarRail(body.slice(0, bodyHeight), geometry, contentWidth, theme, {
+            topInset: SCROLLBAR_TOP_INSET,
+        });
+        return this.#withMenu([...withRail, ...footer], selected, layout, valueColumn, theme, rect);
+    }
+    onInput(data, host) {
+        if (this.#structured !== null)
+            return this.#structuredKey(data);
+        if (this.#menu !== null)
+            return this.#menuKey(data);
+        if (this.#filter !== null)
+            return this.#filterKey(data);
+        const action = SETTINGS_SHORTCUTS.resolve(KEYS[data] ?? data, SCOPE);
+        if (action === null)
+            return { consumed: false };
+        const rows = this.#rows();
+        const selected = indexOfKey(rows, this.#selectedKey);
+        switch (action) {
+            case "close":
+                host.close();
+                return { consumed: true };
+            case "open-filter":
+                this.#filter = new LineInput("");
+                this.#notice = null;
+                return { consumed: true };
+            case "activate": {
+                const row = rows[selected];
+                if (row?.kind === "element" && row.value.structured)
+                    this.#openStructured(row.value);
+                else
+                    this.#cycle(rows, selected, 1);
+                return { consumed: true };
+            }
+            case "move-up":
+            case "move-down":
+                this.#select(rows, moveSelection(rows, selected, action === "move-down" ? 1 : -1));
+                return { consumed: true };
+            case "page-up":
+            case "page-down":
+                this.#select(rows, moveSelection(rows, selected, action === "page-down" ? 8 : -8));
+                return { consumed: true };
+            case "block-up":
+            case "block-down": {
+                const target = blockJumpTarget(rows, selected, action === "block-down" ? 1 : -1);
+                if (target !== undefined)
+                    this.#jump(rows, target);
+                return { consumed: true };
+            }
+            case "first":
+            case "last": {
+                // End lands on the very last setting, not on the head of its section.
+                const selectable = selectableIndexes(rows);
+                const target = action === "last" ? selectable.at(-1) : selectable[0];
+                if (target !== undefined)
+                    this.#jump(rows, target);
+                return { consumed: true };
+            }
+            case "previous-value":
+            case "next-value":
+                this.#cycle(rows, selected, action === "next-value" ? 1 : -1);
+                return { consumed: true };
+            default:
+                return { consumed: false };
+        }
+    }
+    onMouse(event, _host) {
+        const menu = this.#menu;
+        const frame = this.#menuFrame;
+        if (menu !== null && frame !== null) {
+            const overRow = menuRowAt(frame, event.row - 1, event.column);
+            const overMenu = overRow !== null;
+            if (event.kind === "motion") {
+                // While the menu is open it owns the pointer: the row under it lights up,
+                // and nothing behind it hovers.
+                const hadHover = this.#hoverKey !== null;
+                this.#hoverKey = null;
+                if (!overMenu) {
+                    const cleared = menu.index !== -1;
+                    menu.index = -1;
+                    return { consumed: true, render: hadHover || cleared };
+                }
+                if (menu.index === overRow)
+                    return { consumed: true, render: hadHover };
+                menu.index = overRow ?? -1;
+                return { consumed: true, render: true };
+            }
+            if (event.kind !== "press")
+                return { consumed: true, render: false };
+            if (overRow === null) {
+                // A press anywhere else dismisses the menu rather than acting through it.
+                this.#menu = null;
+                return { consumed: true };
+            }
+            const value = menu.choices[overRow];
+            this.#menu = null;
+            if (value !== undefined)
+                this.#apply(menu.entry, value);
+            return { consumed: true };
+        }
+        const open = this.#structured;
+        if (open !== null) {
+            // The panel owns the pointer while it is open; its flag rows are the targets.
+            // The panel's rows begin one line below its rule.
+            const panel = { firstRow: this.#panelTop + 1, rows: open.flags.length, valueColumn: this.#dialogValueColumn };
+            const row = event.row - 1 - panel.firstRow;
+            if (row < 0 || row >= panel.rows)
+                return { consumed: true, render: false };
+            if (event.kind === "motion") {
+                if (open.index === row)
+                    return { consumed: true, render: false };
+                open.index = row;
+                return { consumed: true, render: true };
+            }
+            if (event.kind === "press") {
+                open.index = row;
+                // Pointing at the label picks the row; the value is what changes it,
+                // exactly as in the list behind the dialog.
+                const key = open.flags[row] ?? "";
+                const width = displayWidth((open.record[key] ?? false) ? "true" : "false");
+                if (dialogRowAt(panel, event.row - 1, event.column, width) !== null)
+                    this.#toggleFlag(row);
+                return { consumed: true };
+            }
+            return { consumed: true, render: false };
+        }
+        const row = this.#frameRows.find(candidate => candidate.screenRow === event.row - 1);
+        const previousKey = this.#hoverKey;
+        const previousRegion = this.#hoverRegion;
+        if (row === undefined) {
+            this.#hoverKey = null;
+            this.#hoverRegion = "label";
+            return { consumed: event.kind !== "motion", render: previousKey !== null };
+        }
+        this.#hoverKey = row.key;
+        this.#hoverRegion = regionAt(row, event.column);
+        if (event.kind === "press") {
+            const rows = this.#rows();
+            const index = rows.findIndex(candidate => rowKey(candidate) === row.key);
+            if (index >= 0) {
+                // The pointer acts where it points; the arrow belongs to the keyboard.
+                this.#notice = null;
+                if (this.#hoverRegion === "minus")
+                    this.#cycle(rows, index, -1);
+                else if (this.#hoverRegion === "plus")
+                    this.#cycle(rows, index, 1);
+                else if (this.#hoverRegion === "value")
+                    this.#openMenu(rows, index);
+            }
+            return { consumed: true };
+        }
+        if (event.kind === "wheel-up" || event.kind === "wheel-down") {
+            this.#scroll = Math.max(0, this.#scroll + (event.kind === "wheel-down" ? 3 : -3));
+            return { consumed: true };
+        }
+        const changed = previousKey !== this.#hoverKey || previousRegion !== this.#hoverRegion;
+        return { consumed: event.kind !== "motion", render: changed };
+    }
+    #openMenu(rows, selected) {
+        const row = rows[selected];
+        if (row === undefined || row.kind !== "element")
+            return;
+        const entry = row.value;
+        if (entry.structured) {
+            this.#openStructured(entry);
+            return;
+        }
+        const shown = this.#shownValue(entry);
+        // A number is stepped, not picked from a list: it has its own two controls,
+        // and pointing at it is not a request for anything else.
+        if (typeof shown === "number")
+            return;
+        if (!entry.editable || entry.choices === null || entry.choices.length === 0) {
+            this.#notice = `${labelOf(entry)} cannot be changed here`;
+            return;
+        }
+        const current = shown === null ? 0 : Math.max(0, entry.choices.indexOf(shown));
+        // Nothing is highlighted until the pointer or a key picks a row, so opening
+        // the menu does not flash a highlight the reader did not ask for.
+        this.#menu = { entry, current, anchorKey: `${entry.backend}:${entry.id}`, choices: entry.choices, index: -1 };
+    }
+    /**
+     * A structured setting is a set of flags, so it opens as its own list rather
+     * than as a value menu: each row names one flag and toggles it in place.
+     */
+    #openStructured(entry) {
+        // The flags come from the declaration, not from the stored value: an unset
+        // flag still has a row, showing the default the source would apply.
+        if (entry.flags.length === 0) {
+            this.#notice = `${labelOf(entry)} has nothing to configure`;
+            return;
+        }
+        const stored = typeof entry.rawValue === "object" && entry.rawValue !== null && !Array.isArray(entry.rawValue)
+            ? entry.rawValue
+            : {};
+        const record = {};
+        for (const flag of entry.flags) {
+            const value = stored[flag.key];
+            record[flag.key] = typeof value === "boolean" ? value : flag.fallback;
+        }
+        // The dialog takes the screen: the row it was opened from stops being the
+        // thing under the pointer, so it stops looking like it.
+        this.#hoverKey = null;
+        this.#hoverRegion = "label";
+        this.#structured = { entry, flags: entry.flags.map(flag => flag.key), index: 0, record };
+    }
+    #structuredKey(data) {
+        const open = this.#structured;
+        if (open === null)
+            return { consumed: false };
+        switch (SETTINGS_SHORTCUTS.resolve(KEYS[data] ?? data, DIALOG_SCOPE)) {
+            case "close":
+                this.#structured = null;
+                return { consumed: true };
+            case "part-previous":
+                open.index = Math.max(0, open.index - 1);
+                return { consumed: true };
+            case "part-next":
+                open.index = Math.min(open.flags.length - 1, open.index + 1);
+                return { consumed: true };
+            case "part-change":
+                this.#toggleFlag(open.index);
+                return { consumed: true };
+            default:
+                return { consumed: true, render: false };
+        }
+    }
+    #toggleFlag(index) {
+        const open = this.#structured;
+        const flag = open?.flags[index];
+        if (open === null || open === undefined || flag === undefined)
+            return;
+        open.record[flag] = !(open.record[flag] ?? false);
+        const next = { ...open.record };
+        void this.#session.changeStructured(open.entry.backend, open.entry.id, next).then(outcome => {
+            this.#notice = outcome.failure === null ? null : `Could not save ${labelOf(open.entry)}: ${outcome.failure}`;
+        });
+    }
+    #menuKey(data) {
+        const menu = this.#menu;
+        if (menu === null)
+            return { consumed: false };
+        const key = KEYS[data] ?? data;
+        if (key === "escape") {
+            this.#menu = null;
+            return { consumed: true };
+        }
+        if (key === "up" || key === "down") {
+            // The keyboard starts from the value in effect rather than from the top.
+            menu.index = menu.index < 0
+                ? menu.current
+                : Math.min(menu.choices.length - 1, Math.max(0, menu.index + (key === "down" ? 1 : -1)));
+        }
+        else if (key === "enter") {
+            const value = menu.choices[menu.index];
+            this.#menu = null;
+            if (value !== undefined)
+                this.#apply(menu.entry, value);
+        }
+        return { consumed: true };
+    }
+    #filterKey(data) {
+        const input = this.#filter;
+        if (input === null)
+            return { consumed: false };
+        const key = KEYS[data];
+        if (key === "up" || key === "down" || key === "shift+up" || key === "shift+down") {
+            const rows = this.#rows();
+            // Nothing found means nothing to move through; the key is still swallowed
+            // rather than typed into the search.
+            if (selectableIndexes(rows).length === 0)
+                return { consumed: true, render: false };
+            const selected = indexOfKey(rows, this.#selectedKey);
+            const forward = key === "down" || key === "shift+down";
+            if (key === "shift+up" || key === "shift+down") {
+                const target = blockJumpTarget(rows, selected, forward ? 1 : -1);
+                if (target !== undefined)
+                    this.#jump(rows, target);
+                return { consumed: true };
+            }
+            this.#select(rows, moveSelection(rows, selected, forward ? 1 : -1));
+            return { consumed: true };
+        }
+        const outcome = handleLineInputKey(input, data);
+        if (outcome.kind === "cancelled")
+            this.#filter = null;
+        this.#scroll = 0;
+        return { consumed: true };
+    }
+    #cycle(rows, selected, delta) {
+        const row = rows[selected];
+        if (row === undefined || row.kind !== "element")
+            return;
+        const entry = row.value;
+        if (!entry.editable) {
+            this.#notice = `${labelOf(entry)} cannot be changed here`;
+            return;
+        }
+        const shown = this.#shownValue(entry);
+        if (typeof shown === "number") {
+            // At the end of the range there is nothing to say: the arrow already reads
+            // as unavailable, so a message would only repeat it.
+            const next = steppedValue(rangeOf(entry), shown, delta);
+            if (next !== null)
+                this.#apply(entry, next);
+            return;
+        }
+        const choices = entry.choices;
+        if (choices === null || choices.length === 0) {
+            this.#notice = `${labelOf(entry)} cannot be changed here`;
+            return;
+        }
+        const current = shown === null ? -1 : choices.indexOf(shown);
+        const next = choices[current < 0
+            ? (delta > 0 ? 0 : choices.length - 1)
+            : (current + delta + choices.length) % choices.length];
+        if (next !== undefined)
+            this.#apply(entry, next);
+    }
+    #apply(entry, value) {
+        const key = `${entry.backend}:${entry.id}`;
+        // Shown immediately so the row never lags a keypress, and so the next press
+        // steps from here rather than from a value the source has not caught up to.
+        this.#pending.set(key, value);
+        void this.#session.change(entry.backend, entry.id, value).then(outcome => {
+            if (outcome.failure !== null) {
+                this.#pending.delete(key);
+                this.#notice = `Could not save ${labelOf(entry)}: ${outcome.failure}`;
+                return;
+            }
+            // A later press may have moved on; only the last request clears itself.
+            if (this.#pending.get(key) === value)
+                this.#pending.delete(key);
+            this.#notice = outcome.pendingRestart ? `${labelOf(entry)} applies on the next start` : null;
+        });
+    }
+    /** What the row shows: the value asked for if one is outstanding, else the source's. */
+    #shownValue(entry) {
+        return this.#pending.get(`${entry.backend}:${entry.id}`) ?? entry.value;
+    }
+    #jump(rows, target) {
+        this.#select(rows, target);
+        this.#reveal = blockRowSpan(rows, target);
+    }
+    #select(rows, index) {
+        if (index < 0)
+            return;
+        this.#selectedKey = rowKey(rows[index]);
+        this.#notice = null;
+    }
+    #rows() {
+        const needle = this.#filter?.value.trim().toLowerCase() ?? "";
+        const matches = (entry) => needle.length === 0
+            || entry.id.toLowerCase().includes(needle)
+            || labelOf(entry).toLowerCase().includes(needle);
+        const rows = [];
+        for (const section of this.#session.sections()) {
+            // A section named by the search is what the reader asked for, so it arrives
+            // whole rather than narrowed to the entries that happen to repeat its name.
+            const named = needle.length > 0 && section.title.toLowerCase().includes(needle);
+            const entries = named ? section.entries : section.entries.filter(matches);
+            if (needle.length > 0 && entries.length === 0)
+                continue;
+            if (rows.length > 0)
+                rows.push({ kind: "spacer" });
+            rows.push({ kind: "group", group: section.id, title: section.title });
+            if (section.unavailableReason !== null) {
+                rows.push({ kind: "note", group: section.id, text: section.unavailableReason });
+                continue;
+            }
+            if (section.readOnlyReason !== null && (needle.length === 0 || named)) {
+                rows.push({ kind: "note", group: section.id, text: section.readOnlyReason });
+            }
+            // Presented in the order the source reports, which is the order the
+            // pinned engine shows and is neither declaration order nor alphabetical.
+            for (const entry of entries) {
+                rows.push({
+                    kind: "element",
+                    group: section.id,
+                    key: `${entry.backend}:${entry.id}`,
+                    selectable: entry.editable,
+                    value: entry,
+                });
+            }
+        }
+        return rows;
+    }
+    #valueColumn(rows) {
+        const shown = rows.flatMap(row => (row.kind === "element" ? [this.#viewRow(row.value)] : []));
+        return valueColumnFor(shown);
+    }
+    #header(title, theme, width) {
+        return renderGroupHeader(humanizeTitle(title), width, theme);
+    }
+    #renderRow(row, selected, width, valueColumn, theme) {
+        if (row === undefined || row.kind === "spacer")
+            return "";
+        if (row.kind === "group")
+            return this.#header(row.title, theme, width);
+        if (row.kind === "note")
+            return renderNote(row.text, width, theme);
+        const entry = row.value;
+        const key = `${entry.backend}:${entry.id}`;
+        const hovered = this.#hoverKey === key;
+        return renderListRow(this.#viewRow(entry), { selected, hovered, region: this.#hoverRegion }, valueColumn, width, theme);
+    }
+    /** What the list view needs to draw a setting: its words, and where it can go. */
+    #viewRow(entry) {
+        const shown = this.#shownValue(entry);
+        const value = entry.structured
+            ? CONFIGURE
+            : shown === null ? describeRaw(entry.rawValue) : displayValue(shown);
+        const range = rangeOf(entry);
+        return {
+            key: `${entry.backend}:${entry.id}`,
+            label: labelOf(entry),
+            value,
+            ...(entry.origin === "default" ? { suffix: "(default)" } : {}),
+            ...(typeof shown === "number" && entry.editable ? { stepper: stepperEnds(range, shown) } : {}),
+        };
+    }
+    #withMenu(lines, _selected, _layout, valueColumn, theme, rect) {
+        const menu = this.#menu;
+        const anchor = menu === null ? undefined : this.#frameRows.find(candidate => candidate.key === menu.anchorKey);
+        if (menu === null || anchor === undefined) {
+            this.#menuFrame = null;
+            return lines;
+        }
+        const state = {
+            choices: menu.choices.map(choice => displayValue(choice)),
+            current: this.#shownValue(menu.entry) === null ? null : displayValue(this.#shownValue(menu.entry)),
+            index: menu.index,
+        };
+        const frame = valueMenuFrame(state, { screenRow: anchor.screenRow, valueColumn }, {
+            bodyHeight: lines.length - this.#footerHeight,
+            surfaceWidth: rect.width,
+            reservedRight: RAIL_COLUMNS,
+        });
+        this.#menuFrame = frame;
+        return renderValueMenu(lines, state, frame, theme);
+    }
+    /** What the panel needs to present a structured setting's parts. */
+    #dialogLines(open, width, theme) {
+        const rows = open.flags.map(key => {
+            const declared = open.entry.flags.find(flag => flag.key === key);
+            return {
+                label: declared?.label ?? humanizeLabel(key),
+                // The engine writes these as the booleans they are rather than as yes/no.
+                value: (open.record[key] ?? false) ? "true" : "false",
+                ...(declared?.description === undefined ? {} : { description: declared.description }),
+            };
+        });
+        this.#dialogValueColumn = dialogValueColumn(rows);
+        this.#panelTop = this.#panelTopForFrame;
+        return renderDialogPanel({ rows, index: open.index, hint: SETTINGS_SHORTCUTS.hint(DIALOG_SCOPE) }, width, theme);
+    }
+    #footerLines(width, theme) {
+        const open = this.#structured;
+        if (open !== null)
+            return this.#dialogLines(open, width, theme);
+        // The hint is the declarations, so a key cannot be described here and bound
+        // to something else.
+        const hint = this.#interruptArmed ? "press ctrl+c again to exit A1" : SETTINGS_SHORTCUTS.hint(SCOPE);
+        const status = renderStatusLine({ hint, report: this.#notice }, width, theme);
+        const input = this.#filter;
+        if (input === null)
+            return [status];
+        return [...renderInputRow(input, width, { placeholder: SEARCH_PLACEHOLDER }).lines, status];
+    }
+}
+/** The source's own wording when it has one, otherwise the id made readable. */
+function labelOf(entry) {
+    return entry.label ?? humanizeLabel(entry.id);
+}
+function isStepper(entry, shown = entry.value) {
+    return typeof shown === "number" && entry.editable;
+}
+/** Where a setting's number may go: what the engine states, or what it offers. */
+function rangeOf(entry) {
+    return { minimum: entry.minimum, maximum: entry.maximum, values: numericValues(entry.choices) };
+}
+/** Booleans read as yes and no; everything else prints as itself. */
+function displayValue(value) {
+    if (typeof value === "boolean")
+        return value ? "yes" : "no";
+    return String(value);
+}
+function describeRaw(value) {
+    if (value === null || value === undefined)
+        return "unset";
+    if (typeof value === "object")
+        return Array.isArray(value) ? `${value.length} items` : "structured value";
+    return String(value);
+}

package/dist/src/foundation/agent-engine-contracts/domain.d.ts

@@ -53,6 +53,32 @@ export interface AgentSettingDescriptor {
     readonly valueType: "boolean" | "number" | "string" | "enum" | "json";
     readonly writable: boolean;
     readonly choices?: readonly AgentJsonValue[];
+    /** Label the engine shows for this setting, when it has one. */
+    readonly label?: string;
+    /** One-line explanation the engine shows for this setting. */
+    readonly description?: string;
+    /**
+     * True when the values this setting offers are resolved as it is read rather
+     * than declared: what is installed, what the running session supports. The
+     * boundary resolves them; nothing above it supplies them.
+     */
+    readonly resolvedWhenRead?: boolean;
+    /** Smallest value a numeric setting accepts, when the engine states one. */
+    readonly minimum?: number;
+    /** Largest value a numeric setting accepts, when the engine states one. */
+    readonly maximum?: number;
+    /**
+     * Flags a structured setting offers. Declared by the source rather than read
+     * from the stored value, so an unset flag still has a row and a default.
+     */
+    readonly flags?: readonly AgentSettingFlag[];
+}
+export interface AgentSettingFlag {
+    readonly key: string;
+    readonly label: string;
+    readonly description: string;
+    /** Value to show when the stored object says nothing about this flag. */
+    readonly fallback: boolean;
 }
 export interface AgentResourceDescriptor {
     readonly id: string;

package/dist/src/foundation/launch-guardian/index.d.ts

@@ -0,0 +1 @@
+export * from "./main.js";

package/dist/src/foundation/launch-guardian/index.js

@@ -0,0 +1 @@
+export * from "./main.js";