windows-development-sandbox 1.7.0 → 1.9.0

package/dist/cli/menu/settings/index.d.ts

@@ -1,4 +1,2 @@
-export { CATEGORIES, categoryOf, nameOf, SETTINGS_ELSEWHERE } from './categories.js';
-export { ConfigFile, editConfigText, fileValue, type SettingChange, type SettingsTarget } from './config-file.js';
 export { Draft, type DraftResult } from './draft.js';
-export { SchemaNode } from './schema-node.js';
+export { diffText, exportSettings, planImport, skippedLine, type DiffLine, type ImportPlan, type Pruned, type Skipped, } from './share.js';

package/dist/cli/menu/settings/index.js

@@ -1,4 +1,4 @@
-export { CATEGORIES, categoryOf, nameOf, SETTINGS_ELSEWHERE } from './categories.js';
-export { ConfigFile, editConfigText, fileValue } from './config-file.js';
+// The menu's settings editing: staged changes (Ctrl+S saves them), sharing settings, and the editors for each kind of
+// value. What the settings are, their files and rows live in the settings feature (src/app/features/settings).
 export { Draft } from './draft.js';
-export { SchemaNode } from './schema-node.js';
+export { diffText, exportSettings, planImport, skippedLine, } from './share.js';

package/dist/cli/menu/settings/object-editor.d.ts

@@ -1,5 +1,5 @@
 import { type App } from '../../tui/index.js';
-import { type SchemaNode } from './schema-node.js';
+import type { SchemaNode } from '../../../app/kernel/index.js';
 import type { ValueEditor, Edited } from './value-editor.js';
 /** One object as a form: each field with its value, Enter to change it, r to clear an optional one. */
 export declare class ObjectEditor {

package/dist/cli/menu/settings/share.d.ts

@@ -0,0 +1,36 @@
+import type { Config } from '../../../core/types.js';
+import type { SettingChange } from '../../../app/features/settings/index.js';
+/** Why something was left out. */
+export interface Skipped {
+    readonly key: string;
+    readonly why: 'secret' | 'path' | 'machine';
+}
+export interface Pruned {
+    readonly data: Record<string, unknown>;
+    readonly skipped: Skipped[];
+}
+/** One line for a skipped setting. */
+export declare function skippedLine(s: Skipped): string;
+/** Your settings as a shareable object: only what differs from the defaults, without secrets or (by default) paths. */
+export declare function exportSettings(config: Config, withPaths: boolean): Pruned;
+/** One changed setting in a diff: old -> new. */
+export interface DiffLine {
+    readonly key: string[];
+    readonly from: unknown;
+    readonly to: unknown;
+}
+export interface ImportPlan {
+    /** What would change (empty: nothing). */
+    readonly changes: SettingChange[];
+    readonly lines: DiffLine[];
+    readonly skipped: Skipped[];
+    /** Why the file cannot be imported at all (not JSON, not settings). */
+    readonly problems: string[];
+}
+/**
+ * Reads a shared settings file and works out what importing it would do to `current` (your settings with defaults).
+ * Pure: nothing is written.
+ */
+export declare function planImport(text: string, current: Config): ImportPlan;
+/** The diff as plain lines: `key: old -> new`. */
+export declare function diffText(lines: readonly DiffLine[]): string[];

package/dist/cli/menu/settings/share.js

@@ -0,0 +1,131 @@
+// Sharing your settings: the part of them that differs from the defaults, as a .json a team can pass around, and the
+// reverse (read a file, show what it would change, apply the rest). Secrets (anything the schema marks), the data
+// folder and folders or files of this PC never go into a file and are never taken from one.
+import { parse } from 'jsonc-parser';
+import _ from 'lodash';
+import { DEFAULTS, mergeConfig } from '../../../core/config/index.js';
+import { ConfigSchema, describeIssues, secretPaths } from '../../../core/schema/index.js';
+import { pathKindOf } from '../../../app/kernel/index.js';
+/** Settings that are about this PC and never travel (the data folder). */
+const MACHINE_ONLY = ['storage.root'];
+/** A folder or file of this PC: a drive path, a network path, a rooted path or a %VARIABLE% path. */
+const ABSOLUTE = /^([a-zA-Z]:[\\/]|\\\\|\/|%)/;
+const WHY_TEXT = {
+    secret: 'a secret, never shared',
+    path: 'a folder or file of this PC',
+    machine: 'this PC only',
+};
+/** One line for a skipped setting. */
+export function skippedLine(s) {
+    return s.key + ' (' + WHY_TEXT[s.why] + ')';
+}
+const isSecret = (trail) => secretPaths().some((p) => p.length === trail.length && p.every((part, i) => part === '*' || part === trail[i]));
+/**
+ * `value` without secrets, machine-only settings and (unless `withPaths`) folders and files of this PC. A list item
+ * that holds such a path is dropped whole. `trail` is the key path, with * for a list item.
+ */
+function prune(value, trail, withPaths, skipped) {
+    const name = () => trail.join('.').replace(/\.\*/g, '[]');
+    if (isSecret(trail)) {
+        skipped.push({ key: name(), why: 'secret' });
+        return undefined;
+    }
+    if (MACHINE_ONLY.includes(trail.join('.'))) {
+        skipped.push({ key: name(), why: 'machine' });
+        return undefined;
+    }
+    const isPath = !withPaths && pathKindOf(trail.filter((p) => p !== '*')) !== undefined;
+    if (typeof value === 'string') {
+        if (isPath && ABSOLUTE.test(value)) {
+            skipped.push({ key: name(), why: 'path' });
+            return undefined;
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        const kept = [];
+        for (const item of value) {
+            const before = skipped.length;
+            const out = prune(item, [...trail, '*'], withPaths, skipped);
+            // A list item that lost a path (a folder entry without its folder) means nothing any more.
+            const lostPath = skipped.slice(before).some((x) => x.why !== 'secret');
+            if (out !== undefined && !lostPath)
+                kept.push(out);
+        }
+        return kept.length || value.length === 0 ? kept : undefined;
+    }
+    if (_.isPlainObject(value)) {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            const next = prune(v, [...trail, k], withPaths, skipped);
+            if (next !== undefined)
+                out[k] = next;
+        }
+        return _.isEmpty(out) && !_.isEmpty(value) ? undefined : out;
+    }
+    return value;
+}
+/** What `value` has that `base` does not (undefined when nothing). Lists and plain values are compared whole. */
+function differences(value, base) {
+    if (_.isPlainObject(value) && _.isPlainObject(base)) {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            const d = differences(v, base[k]);
+            if (d !== undefined)
+                out[k] = d;
+        }
+        return _.isEmpty(out) ? undefined : out;
+    }
+    return _.isEqual(value, base) ? undefined : value;
+}
+/** Your settings as a shareable object: only what differs from the defaults, without secrets or (by default) paths. */
+export function exportSettings(config, withPaths) {
+    const skipped = [];
+    const diff = differences(config, DEFAULTS) ?? {};
+    const data = (prune(diff, [], withPaths, skipped) ?? {});
+    return { data, skipped };
+}
+/** The leaves of an object as key paths; lists and plain values are leaves. */
+function leaves(value, key = []) {
+    if (_.isPlainObject(value) && !_.isEmpty(value))
+        return Object.entries(value).flatMap(([k, v]) => leaves(v, [...key, k]));
+    return key.length ? [{ key, value }] : [];
+}
+/**
+ * Reads a shared settings file and works out what importing it would do to `current` (your settings with defaults).
+ * Pure: nothing is written.
+ */
+export function planImport(text, current) {
+    const none = { changes: [], lines: [], skipped: [] };
+    const errors = [];
+    const parsed = parse(text, errors, { allowTrailingComma: true });
+    if (errors.length || !_.isPlainObject(parsed))
+        return { ...none, problems: ['The file is not a settings file (a JSON object is expected).'] };
+    const raw = _.omit(parsed, '$schema');
+    const skipped = [];
+    const safe = (prune(raw, [], false, skipped) ?? {});
+    const checked = ConfigSchema.safeParse(mergeConfig(DEFAULTS, safe));
+    if (!checked.success)
+        return { ...none, skipped, problems: describeIssues(checked.error) };
+    const changes = [];
+    const lines = [];
+    for (const { key, value } of leaves(safe)) {
+        const from = _.get(current, key);
+        if (_.isEqual(from, value))
+            continue;
+        changes.push({ key, value });
+        lines.push({ key, from, to: value });
+    }
+    return { changes, lines, skipped, problems: [] };
+}
+/** A value as one short piece of text for a diff. */
+function show(value) {
+    if (value === undefined)
+        return '(not set)';
+    const text = JSON.stringify(value);
+    return text.length > 60 ? text.slice(0, 57) + '...' : text;
+}
+/** The diff as plain lines: `key: old -> new`. */
+export function diffText(lines) {
+    return lines.map((l) => l.key.join('.') + ': ' + show(l.from) + ' -> ' + show(l.to));
+}

package/dist/cli/menu/settings/value-editor.d.ts

@@ -1,5 +1,5 @@
 import { type App } from '../../tui/index.js';
-import { type SchemaNode } from './schema-node.js';
+import { type SchemaNode } from '../../../app/kernel/index.js';
 /** What is wrong with the text typed for a number setting (true = fine), in words that name the allowed range. */
 export declare function numberProblem(node: SchemaNode, text: string): true | string;
 /** The new value, or undefined when you backed out without changing anything. */
@@ -15,6 +15,10 @@ export declare class ValueEditor {
     private readonly hints;
     constructor(app: App, hints?: EditorHints);
     edit(path: string[], key: string[], node: SchemaNode, current: unknown): Promise<Edited>;
+    /** A choice with "Custom…" for a value of your own (a number or a text besides the fixed values). */
+    private custom;
+    /** A list: ticks for fixed values, a form per entry for objects, otherwise text (or paths) one per entry. */
+    private list;
     private number;
     /** A folder or file on this PC: the path picker (typing a path still works). */
     private folderOrFile;

package/dist/cli/menu/settings/value-editor.js

@@ -1,15 +1,16 @@
-// Editing one value with the screen that fits it: on/off flips, choices are picked from a list, numbers and text are
-// typed and checked as you type, lists and maps get an editor of their own (add, change, remove), and objects (a
-// mapped folder, an agent) open as a small form. JSON is only the last resort for shapes none of these fit.
+// Editing one value with the screen that fits its Field (app/kernel/fields.ts, the same descriptor the web's inputs
+// read): on/off flips, choices are picked from a list, numbers and text are typed and checked as you type, lists and
+// maps get an editor of their own (add, change, remove), and objects (a mapped folder, an agent) open as a small form.
+// JSON is only the last resort for shapes none of these fit.
 import _ from 'lodash';
 import { Text } from '../../tui/index.js';
-import { choiceLabel } from './format.js';
+import { choiceLabel, fieldOf, pathLiterals } from '../../../app/kernel/index.js';
 import { StringListEditor } from './collections/string-list-editor.js';
 import { MapEditor } from './collections/map-editor.js';
 import { ObjectListEditor } from './collections/object-list-editor.js';
 import { ObjectMapEditor } from './collections/object-map-editor.js';
 import { ObjectEditor } from './object-editor.js';
-import { askPath, pathKindOf, pathLiterals } from './path-kind.js';
+import { askPath } from './ask-path.js';
 /** What is wrong with the text typed for a number setting (true = fine), in words that name the allowed range. */
 export function numberProblem(node, text) {
     const n = Number(text);
@@ -31,77 +32,79 @@ export class ValueEditor {
         this.hints = hints;
     }
     async edit(path, key, node, current) {
-        const about = node.description ? [node.description] : [];
+        const field = fieldOf(node, key);
         const suggestions = this.hints.suggestions?.(key);
         if (suggestions?.length && node.type === 'string')
             return this.suggest(path, key, node, current, suggestions);
-        switch (node.editor) {
+        switch (field.kind) {
             case 'boolean':
                 return { value: !(current ?? false) };
-            case 'choice':
-                return this.pick(path, node, current, node.choiceValues);
-            case 'union': {
-                const open = node.openOption;
-                const custom = '@custom';
-                const picked = await this.app.choose(path, node.description ?? '', [
-                    ...node.choiceValues.map((v) => ({ value: v, label: choiceLabel(v) })),
-                    ...(open
-                        ? [
-                            {
-                                value: custom,
-                                label: 'Custom ' + open.type + '…',
-                                description: 'Type a ' + open.type + ' of your own.',
-                            },
-                        ]
-                        : []),
-                ], node.choiceValues.includes(current) ? current : open && current !== undefined ? custom : undefined);
-                if (picked === undefined)
-                    return undefined;
-                return picked === custom && open
-                    ? this.edit(path, key, open, node.choiceValues.includes(current) ? undefined : current)
-                    : { value: picked };
-            }
+            case 'enum':
+                return field.open ? this.custom(path, key, node, current) : this.pick(path, node, current, node.choiceValues);
             case 'number':
                 return this.number(path, key, node, current);
-            case 'string': {
-                const kind = pathKindOf(key);
-                if (kind)
-                    return this.folderOrFile(path, key, node, current, kind);
+            case 'path':
+                return this.folderOrFile(path, key, node, current, field.pathKind ?? 'dir');
+            case 'text':
+            case 'secret': {
                 const typed = await this.app.text({
                     path,
                     label: Text.humanize(key[key.length - 1]),
-                    about,
+                    about: field.help ? [field.help] : [],
                     initial: typeof current === 'string' ? current : '',
                     allowEmpty: node.check('') === true,
-                    masked: node.secret,
+                    masked: field.kind === 'secret',
                     validate: (v) => node.check(v),
                 });
                 return typed === undefined ? undefined : { value: typed };
             }
-            case 'choice-list': {
-                const ticked = Array.isArray(current) ? current : [];
-                const picked = await this.app.list({
-                    path,
-                    intro: node.description,
-                    multi: true,
-                    items: node.element.choices.map((v) => ({ value: v, label: String(v), checked: ticked.includes(v) })),
-                });
-                return picked.kind === 'multi' ? { value: picked.values } : undefined;
-            }
-            case 'string-list':
-                return new StringListEditor(this.app, path, node, this, key, pathKindOf(key)).run(Array.isArray(current) ? current : []);
-            case 'string-map':
-                return new MapEditor(this.app, path, node, this, key).run(_.isPlainObject(current) ? current : {});
-            case 'object-list':
-                return new ObjectListEditor(this.app, path, node, this, key).run(Array.isArray(current) ? current : []);
-            case 'object-map':
-                return new ObjectMapEditor(this.app, path, node, this, key).run(_.isPlainObject(current) ? current : {});
+            case 'list':
+                return this.list(path, key, node, field, current);
+            case 'map':
+                return field.element?.kind === 'object'
+                    ? new ObjectMapEditor(this.app, path, node, this, key).run(_.isPlainObject(current) ? current : {})
+                    : new MapEditor(this.app, path, node, this, key).run(_.isPlainObject(current) ? current : {});
             case 'object':
                 return new ObjectEditor(this.app, path, node, this, key).run(_.isPlainObject(current) ? current : node.initial());
             default:
                 return this.json(path, key, node, current);
         }
     }
+    /** A choice with "Custom…" for a value of your own (a number or a text besides the fixed values). */
+    async custom(path, key, node, current) {
+        const open = node.openOption;
+        const custom = '@custom';
+        const picked = await this.app.choose(path, node.description ?? '', [
+            ...node.choiceValues.map((v) => ({ value: v, label: choiceLabel(v) })),
+            {
+                value: custom,
+                label: 'Custom ' + open.type + '…',
+                description: 'Type a ' + open.type + ' of your own.',
+            },
+        ], node.choiceValues.includes(current) ? current : current !== undefined ? custom : undefined);
+        if (picked === undefined)
+            return undefined;
+        return picked === custom
+            ? this.edit(path, key, open, node.choiceValues.includes(current) ? undefined : current)
+            : { value: picked };
+    }
+    /** A list: ticks for fixed values, a form per entry for objects, otherwise text (or paths) one per entry. */
+    async list(path, key, node, field, current) {
+        const kind = field.element?.kind;
+        if (kind === 'enum') {
+            const ticked = Array.isArray(current) ? current : [];
+            const picked = await this.app.list({
+                path,
+                intro: node.description,
+                multi: true,
+                items: node.element.choices.map((v) => ({ value: v, label: String(v), checked: ticked.includes(v) })),
+            });
+            return picked.kind === 'multi' ? { value: picked.values } : undefined;
+        }
+        if (kind === 'object')
+            return new ObjectListEditor(this.app, path, node, this, key).run(Array.isArray(current) ? current : []);
+        return new StringListEditor(this.app, path, node, this, key, field.element?.pathKind).run(Array.isArray(current) ? current : []);
+    }
     async number(path, key, node, current) {
         const range = node.rangeText();
         const typed = await this.app.text({

package/dist/cli/menu/several.js

@@ -8,7 +8,7 @@ import { KnownProjects } from '../../host/projects/index.js';
 import { isWithin } from '../../shared/paths/index.js';
 import { commandLine } from '../history.js';
 import { Text, Theme } from '../tui/index.js';
-import { askPath } from './settings/path-kind.js';
+import { askPath } from './settings/ask-path.js';
 /** Folders worth offering: this one, the projects started before, and the folders inside your roots. */
 export function candidateFolders(ctx, cwd = process.cwd()) {
     const roots = ctx.loaded.config.projects.roots.map((r) => expandPath(r, ctx.loaded.base));

package/dist/cli/menu/share-settings.d.ts

@@ -0,0 +1,21 @@
+import type { Context } from '../commands/context.js';
+import { type App } from '../tui/index.js';
+/** The rows' ids in the settings list. */
+export declare const EXPORT_SETTINGS = "@export-settings";
+export declare const IMPORT_SETTINGS = "@import-settings";
+export declare function shareSettingsRows(): {
+    value: string;
+    label: string;
+    hint: string;
+    description: string;
+}[];
+export declare class ShareSettingsFlow {
+    private readonly app;
+    private readonly ctx;
+    constructor(app: App, ctx: Context);
+    /** Your settings as they are on disk now (the menu may have saved changes since it started). */
+    private fresh;
+    /** Returns the notice to show (undefined when cancelled). */
+    export(): Promise<string | undefined>;
+    import(): Promise<string | undefined>;
+}

package/dist/cli/menu/share-settings.js

@@ -0,0 +1,112 @@
+// The "Export settings…" and "Import settings…" rows in Settings > General: pick a file, then (for an import) read the
+// diff of what would change and say yes once. Same rules as sandbox config export / import.
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig } from '../../core/config/index.js';
+import { errMsg } from '../../core/util/index.js';
+import { applyImport, DEFAULT_EXPORT, readImport, writeExport } from '../commands/maintenance/config-share.js';
+import { Theme } from '../tui/index.js';
+import { askPath } from './settings/ask-path.js';
+import { diffText, skippedLine } from './settings/index.js';
+/** The rows' ids in the settings list. */
+export const EXPORT_SETTINGS = '@export-settings';
+export const IMPORT_SETTINGS = '@import-settings';
+export function shareSettingsRows() {
+    return [
+        {
+            value: EXPORT_SETTINGS,
+            label: 'Export settings…',
+            hint: '.json',
+            description: 'Write the settings you changed to a .json file you can share with a team. Secrets, the data folder and folders or files of this PC are left out.',
+        },
+        {
+            value: IMPORT_SETTINGS,
+            label: 'Import settings…',
+            hint: '.json',
+            description: 'Read a settings file someone shared, see what it would change, and apply it once you say yes. Secrets, the data folder and paths in it are never taken.',
+        },
+    ];
+}
+export class ShareSettingsFlow {
+    app;
+    ctx;
+    constructor(app, ctx) {
+        this.app = app;
+        this.ctx = ctx;
+    }
+    /** Your settings as they are on disk now (the menu may have saved changes since it started). */
+    fresh() {
+        return { ...this.ctx, loaded: loadConfig(this.ctx.loaded.configPath ?? undefined) };
+    }
+    /** Returns the notice to show (undefined when cancelled). */
+    async export() {
+        const where = ['Settings', 'Export settings'];
+        try {
+            const file = await askPath(this.app, {
+                path: where,
+                title: 'Where to write the settings file',
+                about: ['Only what differs from the defaults is written; secrets and paths of this PC are left out.'],
+                initial: path.resolve(DEFAULT_EXPORT),
+                kind: 'file',
+                validate: (p) => (p.toLowerCase().endsWith('.json') ? true : 'The file name should end in .json.'),
+            });
+            if (!file)
+                return undefined;
+            const exists = path.resolve(file);
+            const replace = fs.existsSync(exists);
+            if (replace &&
+                !(await this.app.confirm({ path: where, question: exists + ' exists. Replace it?', initial: false })))
+                return undefined;
+            const skipped = writeExport(this.fresh(), file, false, replace);
+            return (Theme.ok(Theme.glyph.ok + ' Wrote ' + exists + '.') +
+                (skipped.length ? Theme.muted(' Left out: ' + skipped.join(', ') + '.') : ''));
+        }
+        catch (e) {
+            return Theme.error(Theme.glyph.cross + ' ' + errMsg(e));
+        }
+    }
+    async import() {
+        const where = ['Settings', 'Import settings'];
+        try {
+            const file = await askPath(this.app, {
+                path: where,
+                title: 'Which settings file',
+                about: ['A file made by Export settings (or sandbox config export).'],
+                kind: 'file',
+            });
+            if (!file)
+                return undefined;
+            const ctx = this.fresh();
+            const plan = readImport(ctx, file);
+            const lines = [
+                ...(plan.changes.length
+                    ? [
+                        plan.changes.length + ' setting' + (plan.changes.length === 1 ? '' : 's') + ' would change:',
+                        '',
+                        ...diffText(plan.lines),
+                    ]
+                    : ['Nothing to change: your settings already match the file.']),
+                ...(plan.skipped.length
+                    ? ['', 'Not imported (never taken from a file):', ...plan.skipped.map((s) => skippedLine(s))]
+                    : []),
+            ];
+            if (!plan.changes.length) {
+                await this.app.message({ path: where, lines });
+                return Theme.muted('Nothing changed.');
+            }
+            const yes = await this.app.confirm({
+                path: where,
+                question: 'Change your settings like this?',
+                about: lines,
+                initial: false,
+            });
+            if (!yes)
+                return Theme.muted('Nothing changed.');
+            const n = applyImport(ctx, plan);
+            return Theme.ok(Theme.glyph.ok + ' Imported ' + n + ' setting' + (n === 1 ? '' : 's') + '.');
+        }
+        catch (e) {
+            return Theme.error(Theme.glyph.cross + ' ' + errMsg(e));
+        }
+    }
+}

package/dist/cli/menu/shell.d.ts

@@ -14,10 +14,15 @@ export type ShellExit = {
     kind: 'view';
     file: string;
 };
-/** Which section and category the menu shows. */
+/** Where one section was left: its open category and its search. */
+export interface ScreenView {
+    readonly category?: string;
+    readonly search?: string;
+}
+/** Which section the menu shows, and where each section was left (by section name). */
 export interface MenuView {
     readonly section: number;
-    readonly category: string | undefined;
+    readonly screens: Readonly<Record<string, ScreenView>>;
 }
 /** One section of the menu. */
 export interface Page {
@@ -30,6 +35,12 @@ export interface Page {
     categories(): readonly Category[];
     /** The id of the open category. */
     readonly category: string | undefined;
+    /** The data is still loading: its categories are not known yet (a category asked for opens when they are). */
+    readonly loading?: boolean;
+    /** The search typed in the list ('' or missing: none). */
+    readonly search?: string;
+    /** Types a search into the list (the menu opens on the one it was left on). */
+    restoreSearch?(text: string): void;
     /** Opens a category (the navigation moved onto it). */
     selectCategory(id: string): Promise<void>;
     /** Whether the list has the keyboard (its highlight is softer while the navigation has it). */
@@ -51,6 +62,9 @@ export declare class Shell implements Screen<ShellExit> {
     private active;
     private focus;
     private notice;
+    /** Where each section was left, by name; a section takes its entry the first time it opens in this shell. */
+    private readonly screens;
+    private readonly restored;
     constructor(app: App, pages: readonly Page[], draft: Draft, 
     /** Told after a save (the menu applies settings that act on this PC) and returns a note to add. */
     afterSave?: (result: DraftResult) => string | undefined);
@@ -58,11 +72,13 @@ export declare class Shell implements Screen<ShellExit> {
     /** Which pane has the keyboard. */
     get focused(): 'nav' | 'list';
     nav(): NavState;
-    /** The section and category that are open (the menu opens on them again later in the same run). */
+    /** Notes where the open section is (its category and search). */
+    private remember;
+    /** The section that is open and where every section was left (the menu opens there again, also in a later run). */
     view(): MenuView;
-    /** Opens the section and category a view names (a category that is gone is ignored). */
+    /** Opens the section a view names and puts each section back where it was (what is gone is ignored). */
     restore(view: MenuView): Promise<void>;
-    /** Opens a section by index (loads its data). */
+    /** Opens a section by index (loads its data); the first time, it goes back to the category and search it had. */
     openTab(index: number): Promise<void>;
     /** Puts the keyboard in the navigation or in the list. */
     setFocus(focus: 'nav' | 'list'): void;

package/dist/cli/menu/shell.js

@@ -16,6 +16,9 @@ export class Shell {
     active = 0;
     focus = 'list';
     notice;
+    /** Where each section was left, by name; a section takes its entry the first time it opens in this shell. */
+    screens = new Map();
+    restored = new Set();
     constructor(app, pages, draft, 
     /** Told after a save (the menu applies settings that act on this PC) and returns a note to add. */
     afterSave = () => undefined) {
@@ -45,21 +48,43 @@ export class Shell {
             focused: this.focus === 'nav',
         };
     }
-    /** The section and category that are open (the menu opens on them again later in the same run). */
+    /** Notes where the open section is (its category and search). */
+    remember() {
+        // A section that was never opened here keeps what the last run knew about it.
+        if (!this.restored.has(this.active))
+            return;
+        const { category, search } = this.page;
+        if (category || search)
+            this.screens.set(this.page.label, { category, search: search || undefined });
+        else
+            this.screens.delete(this.page.label);
+    }
+    /** The section that is open and where every section was left (the menu opens there again, also in a later run). */
     view() {
-        return { section: this.active, category: this.page.category };
+        this.remember();
+        return { section: this.active, screens: Object.fromEntries(this.screens) };
     }
-    /** Opens the section and category a view names (a category that is gone is ignored). */
+    /** Opens the section a view names and puts each section back where it was (what is gone is ignored). */
     async restore(view) {
+        this.restored.clear();
+        for (const [label, screen] of Object.entries(view.screens))
+            this.screens.set(label, screen);
         await this.openTab(view.section);
-        if (view.category && this.page.categories().some((c) => c.id === view.category))
-            await this.page.selectCategory(view.category);
     }
-    /** Opens a section by index (loads its data). */
+    /** Opens a section by index (loads its data); the first time, it goes back to the category and search it had. */
     async openTab(index) {
+        this.remember();
         this.active = Math.max(0, Math.min(this.pages.length - 1, index));
         this.page.setFocus(this.focus === 'list');
         await this.page.open();
+        if (this.restored.has(this.active))
+            return;
+        this.restored.add(this.active);
+        const wanted = this.screens.get(this.page.label);
+        if (wanted?.category && (this.page.loading || this.page.categories().some((c) => c.id === wanted.category)))
+            await this.page.selectCategory(wanted.category);
+        if (wanted?.search)
+            this.page.restoreSearch?.(wanted.search);
     }
     /** Puts the keyboard in the navigation or in the list. */
     setFocus(focus) {

package/dist/cli/menu/views.d.ts

@@ -0,0 +1,7 @@
+import type { AnyView } from '../../app/kernel/index.js';
+import type { SECTION_LABELS } from './shell.js';
+export interface MenuViewPlace {
+    readonly view: AnyView;
+    readonly section: (typeof SECTION_LABELS)[number];
+}
+export declare const MENU_VIEWS: readonly MenuViewPlace[];

package/dist/cli/menu/views.js

@@ -0,0 +1,11 @@
+// The shared core's views the menu shows, and in which section (the parity self-test reads this list: an operation or
+// query is reachable in the menu when a view here offers it). Settings is drawn by its own page over the same rows,
+// because the menu stages changes until Ctrl+S.
+import { sandboxView } from '../../app/features/sandbox/index.js';
+import { sessionsView } from '../../app/features/sessions/index.js';
+import { settingsView } from '../../app/features/settings/index.js';
+export const MENU_VIEWS = [
+    { view: sessionsView, section: 'Sessions' },
+    { view: sandboxView, section: 'Sandbox' },
+    { view: settingsView, section: 'Settings' },
+];