@timurproko/a1 0.1.8-dev.528 → 0.1.8-dev.544

package/bin/update-recovery.js

@@ -5,7 +5,7 @@
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { chmod, lstat, mkdir, open, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const SCHEMA = "a1-update-recovery-v1";
@@ -200,9 +200,15 @@ async function readCapsule(path) {
   const packageRoot = await realpath(value.packageRoot).catch(() => resolve(value.packageRoot));
   const expectedPackage = resolve(globalRoot, ...value.packageName.split("/"));
   if (!samePath(packageRoot, expectedPackage) || !containedBy(globalRoot, packageRoot)) throw new Error("A1 update recovery package root escapes npm global root");
-  const expectedNpmArguments = ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${value.packageName}@${value.targetVersion}`];
-  if (JSON.stringify(value.npmArguments) !== JSON.stringify(expectedNpmArguments)) throw new Error("A1 update recovery npm arguments are invalid");
+  const prefix = npmPrefixForGlobalRoot(globalRoot);
+  const expectedNpmArguments = ["install", "--global", "--prefix", prefix, "--loglevel=error", "--no-fund", "--no-audit", `${value.packageName}@${value.targetVersion}`];
+  const legacyNpmArguments = ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${value.packageName}@${value.targetVersion}`];
+  if (![expectedNpmArguments, legacyNpmArguments].some(arguments_ => sameArguments(value.npmArguments, arguments_))) {
+    throw new Error("A1 update recovery npm arguments are invalid");
+  }
   const launcherRoot = resolve(value.launcherRoot);
+  const expectedLauncherRoot = process.platform === "win32" ? prefix : resolve(prefix, "bin");
+  if (!samePath(launcherRoot, expectedLauncherRoot)) throw new Error("A1 update recovery launcher root is invalid");
   const expectedLaunchers = process.platform === "win32"
     ? [resolve(launcherRoot, "a1"), resolve(launcherRoot, "a1.cmd"), resolve(launcherRoot, "a1.ps1")]
     : [resolve(launcherRoot, "a1")];
@@ -306,6 +312,22 @@ async function writeJson(path, value) {
   await rename(temporary, path);
 }
 
+/** @param {string} globalRoot */
+function npmPrefixForGlobalRoot(globalRoot) {
+  const root = resolve(globalRoot);
+  const nodeModules = process.platform === "win32" ? basename(root).toLowerCase() === "node_modules" : basename(root) === "node_modules";
+  if (!nodeModules) throw new Error("A1 update recovery npm global root layout is invalid");
+  if (process.platform === "win32") return dirname(root);
+  const libraryRoot = dirname(root);
+  if (basename(libraryRoot) !== "lib") throw new Error("A1 update recovery npm global root layout is invalid");
+  return dirname(libraryRoot);
+}
+
+/** @param {string[]} left @param {string[]} right */
+function sameArguments(left, right) {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
 /**
  * @param {string} left
  * @param {string} right

package/dist/app/session-shell/session-shell-root.d.ts

@@ -265,6 +265,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         readonly dockOnly: number;
     };
     transcriptRenderCount(): number;
+    setFooterLevel(visible: boolean): void;
     setInputSurface(component: PiShellComponentPort | null, disposePrevious?: boolean, coordination?: Exclude<PiTuiInputSurfaceKind, "editor">): void;
     handleInput(data: string): void;
     invalidate(): void;

package/dist/app/session-shell/session-shell-root.js

@@ -51,6 +51,7 @@ export class OwnedUiSessionShellRoot {
     #componentRuntime;
     #toolsExpanded = false;
     #thinkingVisible = true;
+    #footerLevel = true;
     #mermaidRenderingMode = "off";
     #showImages = true;
     #imageWidthCells = 80;
@@ -107,7 +108,7 @@ export class OwnedUiSessionShellRoot {
         this.resources = createPiShellLoadedResources(startup.resources ?? [], startup.expanded ?? false);
         this.#status = createPiShellStatus(view, progressStatusText, handlers);
         this.#status.setProgressPresentation(this.#customViewport ? "custom-viewport" : "pinned");
-        this.#footer = createPiShellFooter(this.#viewWithExtensionStatuses(view), cwd, this.#customViewport ? "a1" : "pi");
+        this.#footer = createPiShellFooter(this.#viewWithExtensionStatuses(view), cwd, this.#customViewport ? "a1" : "pi", () => this.#footerLevel);
         this.#queued = createPiQueuedInputStatus(view.editor.queuedSubmissions, this.#customViewport ? "custom-viewport" : "pinned");
         this.editor = createPiShellEditor({
             ...handlers,
@@ -970,6 +971,7 @@ export class OwnedUiSessionShellRoot {
     transcriptRenderCount() {
         return this.#transcriptBlockRenders;
     }
+    setFooterLevel(visible) { this.#footerLevel = visible; }
     setInputSurface(component, disposePrevious = true, coordination = "owned") {
         const next = component ?? this.editor;
         const nextCoordination = next === this.editor ? "editor" : coordination;

package/dist/app/session-shell/session-shell.d.ts

@@ -36,7 +36,7 @@ export declare class OwnedUiSessionShell {
     queueFollowUp(): Promise<AdapterCommandResult>;
     restoreQueuedInput(): void;
     showSelector(title: string, options: readonly PiShellSelectorOption[], onSelect: (id: string) => void, onCancel?: () => void): PiTuiOverlayHandle;
-    showThinkingSelector(): void;
+    showThinkingSelector(): Promise<void>;
     /** The Skills dialog: a replacement input like the model selector, applying the chosen skill through the prompt path. */
     showSkillsSelector(skills?: readonly PiShellSkillSummary[]): void;
     showModelSelector(initialSearchInput?: string): void;

package/dist/app/session-shell/session-shell.js

@@ -14,7 +14,7 @@ import { createPiExtensionUiBridge } from "../../integrations/pi/components/shel
 import { createPiShellEditor } from "../../integrations/pi/components/shell-editor-autocomplete.js";
 import { SKILLS_COMMAND_NAME, findSkillByArgument, rewriteSkillsTunnelSubmission, skillPrompt, skillsFromCommands, } from "../../integrations/pi/components/skills-command.js";
 import { createPiQueuedInputStatus, createPiShellFooter, createPiShellHeader, createPiShellLoadedResources, createPiShellStatus, } from "../../integrations/pi/components/shell-footer-status.js";
-import { createPiShellArmin, createPiShellAuthProviderSelector, createPiShellDaxnuts, createPiShellDialog, createPiShellEarendilAnnouncement, createPiShellExtensionSelector, createPiShellLoginDialog, createPiShellModelSelector, createPiShellModelsDialog, createPiShellOperationLoader, createPiShellReloadBox, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionSelector, createPiShellSettingsSelector, createPiShellSkillsSelector, createPiShellThinkingSelector, createPiShellTreeSelector, createPiShellTrustSelector, createPiShellUserMessageSelector, } from "../../integrations/pi/components/shell-selectors-dialogs.js";
+import { createPiShellArmin, createPiShellAuthProviderSelector, createPiShellDaxnuts, createPiShellDialog, createPiShellEarendilAnnouncement, createPiShellExtensionSelector, createPiShellLoginDialog, createPiShellModelSelector, createPiShellModelsDialog, createPiShellOperationLoader, createPiShellReloadBox, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionSelector, createPiShellSettingsSelector, createPiShellSkillsSelector, createPiShellTreeSelector, createPiShellTrustSelector, createPiShellUserMessageSelector, } from "../../integrations/pi/components/shell-selectors-dialogs.js";
 import { createPiShellChangelog, createPiShellHotkeys, createPiShellSessionInfo, renderPiShellStatusText, } from "../../integrations/pi/components/shell-presenters-info.js";
 import { CHANGELOG_ROUTE } from "../../features/owned-ui/reference-routes.js";
 import { createPiShellTranscriptComponent, renderPiShellPackageUpdateNotice, renderPiShellStartupDiagnostic, renderPiShellTranscriptBlock, } from "../../integrations/pi/components/shell-presenters-transcript.js";
@@ -839,9 +839,10 @@ export class OwnedUiSessionShell {
         this.#dialogHandle = handle;
         return handle;
     }
-    showThinkingSelector() {
+    async showThinkingSelector() {
         const snapshot = this.backend.pinnedSettingsSnapshot();
         const close = () => {
+            this.root.setFooterLevel(true);
             this.root.setInputSurface(null);
             this.runtime.requestRender();
         };
@@ -849,7 +850,12 @@ export class OwnedUiSessionShell {
             close();
             void this.runWorkflow({ command: "thinking", argument: "", selection: level, ...(persist ? { persist: true } : {}) });
         };
-        const component = createPiShellThinkingSelector(snapshot.thinkingLevel, snapshot.availableThinkingLevels, level => select(level, false), close, level => select(level, true), snapshot.defaultThinkingLevel);
+        const { createPiShellThinkingSelector } = await import("../../integrations/pi/components/thinking-selector-dialog.js");
+        const component = createPiShellThinkingSelector(snapshot.thinkingLevel, snapshot.availableThinkingLevels, level => select(level, false), close, level => select(level, true), snapshot.defaultThinkingLevel, this.#customViewport ? {
+            profile: "bare",
+            cycleBinding: this.root.editor.keybindingConfig()["app.thinking.cycle"] ?? [],
+        } : undefined);
+        this.root.setFooterLevel(false);
         this.root.setInputSurface(component);
         this.runtime.requestRender();
     }
@@ -1188,7 +1194,7 @@ export class OwnedUiSessionShell {
             return { outcome: "completed", diagnostic: null };
         }
         if (request.command === "thinking" && request.selection === undefined && request.argument.trim().length === 0) {
-            this.showThinkingSelector();
+            await this.showThinkingSelector();
             return { outcome: "completed", diagnostic: null };
         }
         if (request.command === "trust" && request.selection === undefined && request.confirmed === undefined) {

package/dist/composition/owned-ui.js

@@ -12,7 +12,7 @@ import { OwnedUiSessionShell } from "../app/session-shell/session-shell.js";
 import { OwnedSettingsManager } from "../ui/settings/manager.js";
 import { createPiTerminalBridge } from "../integrations/pi/tui-runtime/presentation-adapter.js";
 import { createOwnedRouteHost } from "./settings-route-host.js";
-import { renderPiShellChangelogLines, renderPiShellHotkeysLines } from "../integrations/pi/components/shell-presenters-info.js";
+import { renderPiShellChangelogLines } from "../integrations/pi/components/shell-presenters-info.js";
 import { readPinnedCommandChangelog } from "../integrations/pi/engine/changelog.js";
 export async function composeOwnedUiApplication(options = {}) {
     return (await composeOwnedUi(options)).application;
@@ -47,11 +47,12 @@ export async function composeOwnedUi(options = {}) {
     const references = {
         changelog: async (input) => {
             const markdown = input?.document ?? await readPinnedCommandChangelog();
-            return width => renderPiShellChangelogLines(markdown, width);
+            return { rows: width => renderPiShellChangelogLines(markdown, width) };
         },
         hotkeys: async () => {
             const presentation = shell.hotkeysPresentation();
-            return width => renderPiShellHotkeysLines(presentation, width);
+            const { renderPiShellHotkeySections } = await import("../integrations/pi/components/shell-hotkey-sections.js");
+            return { sections: width => renderPiShellHotkeySections(presentation, width) };
         },
     };
     const routeHost = settings === null || !ownedSurfaces ? null : createOwnedRouteHost(settings, references);

package/dist/composition/settings-route-host.d.ts

@@ -1,16 +1,12 @@
+import type { ReferenceDocumentProvider } from "../features/owned-ui/reference-screen-app.js";
 import type { OwnedSettingsManager } from "../ui/settings/manager.js";
 import type { UiRouteHost, UiRouteInput } from "../ui/apps/contracts.js";
 /** Styled document rows for one content width. */
-export type OwnedReferenceRows = (width: number) => readonly string[];
-/**
- * The documents the reference routes present, supplied by the composition so the
- * route host never reads the changelog or the shell's keybindings itself.
- */
+export type OwnedReferenceRows = NonNullable<ReferenceDocumentProvider["rows"]>;
+/** Documents supplied by composition so the route host never reads shell data itself. */
 export interface OwnedReferenceProviders {
-    /** The complete pinned changelog, or the supplied document when the route input carries one. */
-    changelog(input?: UiRouteInput): Promise<OwnedReferenceRows>;
-    /** The shell's keyboard shortcuts as they stand when the screen opens. */
-    hotkeys(): Promise<OwnedReferenceRows>;
+    changelog(input?: UiRouteInput): Promise<ReferenceDocumentProvider>;
+    hotkeys(): Promise<ReferenceDocumentProvider>;
 }
 /**
  * Declares the A1-owned settings route, and the changelog and hotkeys reference

package/dist/composition/settings-route-host.js

@@ -72,11 +72,11 @@ async function loadSettingsSurface(settings) {
 async function loadReferenceSurface(settings, id, route, title, document) {
     // Rationale: the app module and the document load together, so a document that fails
     // to render is reported by the placeholder rather than by a screen that never fills.
-    const [{ ReferenceScreenApp }, rows] = await Promise.all([import("../features/owned-ui/reference-screen-app.js"), document]);
+    const [{ ReferenceScreenApp }, content] = await Promise.all([import("../features/owned-ui/reference-screen-app.js"), document]);
     return hostApp(id, route, () => new ReferenceScreenApp({
         id,
         title,
-        document: { rows },
+        document: content,
         scrollSettings: () => ({
             scrollbarAppearance: settings.value("scrollbarAppearance"),
             scrollbarStyle: settings.value("scrollbarStyle"),

package/dist/contracts/owned-ui/model.d.ts

@@ -115,6 +115,10 @@ export interface OwnedUiUsageView {
 }
 export interface OwnedUiFooterView {
     readonly branch: string | null;
+    readonly pullRequest?: {
+        readonly number: number;
+        readonly url: string;
+    } | null;
     readonly sessionName: string | null;
     readonly availableProviderCount: number;
     readonly extensionStatuses: readonly (readonly [string, string])[];

package/dist/contracts/owned-ui/validation.js

@@ -396,6 +396,13 @@ export function assertOwnedUiStatusView(status) {
     }
     if (status.footer !== undefined) {
         assertOptionalText(status.footer.branch, "owned-UI footer branch", MAX_LABEL_LENGTH);
+        if (status.footer.pullRequest !== undefined && status.footer.pullRequest !== null) {
+            const pullRequest = status.footer.pullRequest;
+            assertIntegerInRange(pullRequest.number, 1, Number.MAX_SAFE_INTEGER, "owned-UI footer pull request number");
+            if (!isCanonicalGitHubPullRequestUrl(pullRequest.url, pullRequest.number)) {
+                throw new TypeError("owned-UI footer pull request URL is invalid");
+            }
+        }
         assertOptionalText(status.footer.sessionName, "owned-UI footer session name", MAX_LABEL_LENGTH);
         assertIntegerInRange(status.footer.availableProviderCount, 0, 1_000, "owned-UI footer provider count");
         assertCollection(status.footer.extensionStatuses, "owned-UI footer extension statuses", MAX_BADGES);
@@ -422,6 +429,24 @@ export function assertOwnedUiDiagnostics(diagnostic) {
     if (typeof diagnostic.recoverable !== "boolean")
         throw new TypeError("owned-UI diagnostic recoverability is invalid");
 }
+function isCanonicalGitHubPullRequestUrl(value, number) {
+    if (typeof value !== "string" || value.length > MAX_LABEL_LENGTH)
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:"
+            && url.hostname.toLowerCase() === "github.com"
+            && url.username === ""
+            && url.password === ""
+            && url.port === ""
+            && url.search === ""
+            && url.hash === ""
+            && new RegExp(`^/[^/]+/[^/]+/pull/${number}/?$`, "u").test(url.pathname);
+    }
+    catch {
+        return false;
+    }
+}
 function assertOwnedUiModelInfo(model) {
     assertId(model.providerId, "owned-UI provider id");
     assertId(model.modelId, "owned-UI model id");

package/dist/features/owned-ui/index.d.ts

@@ -5,5 +5,5 @@ export type { ConsoleProjectTrustPromptOptions, OwnedProjectTrustPrompt, OwnedPr
 export { createConsoleSessionForkPrompt } from "./session-fork-prompt.js";
 export { SETTINGS_APP_ID, SETTINGS_ROUTE, SETTINGS_SHORTCUTS, SettingsApp } from "./settings-app.js";
 export { REFERENCE_SCREEN_SHORTCUTS, ReferenceScreenApp } from "./reference-screen-app.js";
-export type { ReferenceDocumentProvider, ReferenceScreenOptions } from "./reference-screen-app.js";
+export type { ReferenceDocumentProvider, ReferenceDocumentSection, ReferenceScreenOptions } from "./reference-screen-app.js";
 export { CHANGELOG_APP_ID, CHANGELOG_ROUTE, CHANGELOG_TITLE, HOTKEYS_APP_ID, HOTKEYS_ROUTE, HOTKEYS_TITLE, } from "./reference-routes.js";

package/dist/features/owned-ui/reference-screen-app.d.ts

@@ -4,10 +4,16 @@ import { ShortcutRegistry, type PaneInputResult, type PaneMouseEvent, type PaneR
 type Action = "up" | "down" | "page-up" | "page-down" | "first" | "last" | "close";
 export declare const REFERENCE_SCREEN_SHORTCUTS: ShortcutRegistry<Action>;
 /** Rows of a document already styled and wrapped for one content width. */
+export interface ReferenceDocumentSection {
+    readonly title: string;
+    readonly rows: readonly string[];
+}
 export interface ReferenceDocumentProvider {
-    /** The rows for this width, or null while the document is not available yet. */
-    rows(width: number): readonly string[] | null;
-    /** Settles once `rows` answers; absent when the document is available at once. */
+    /** Flat rows for this width, or null while the document is not available yet. */
+    readonly rows?: (width: number) => readonly string[] | null;
+    /** Structured groups opt into shared Settings-style headers and pinning. */
+    readonly sections?: (width: number) => readonly ReferenceDocumentSection[] | null;
+    /** Settles once the selected content provider answers; absent when available at once. */
     readonly ready?: Promise<void>;
 }
 export interface ReferenceScreenOptions {

package/dist/features/owned-ui/reference-screen-app.js

@@ -1,4 +1,4 @@
-import { GLOBAL_SCOPE, PLAIN_THEME, RAIL_COLUMNS, ShortcutRegistry, ScrollbarRails, assertNoShortcutConflicts, displayWidth, padToWidth, scrollForTrackPage, scrollbarGeometry, scrollbarPresentation, scrollbarWheelRows, truncateToWidth, withScrollbarRail, } from "../../ui/components/index.js";
+import { GLOBAL_SCOPE, PLAIN_THEME, RAIL_COLUMNS, ShortcutRegistry, ScrollbarRails, assertNoShortcutConflicts, displayWidth, layoutList, padToWidth, renderGroupHeader, scrollForTrackPage, scrollbarGeometry, scrollbarPresentation, scrollbarWheelRows, truncateToWidth, withScrollbarRail, } from "../../ui/components/index.js";
 const SCOPE = "reference-screen";
 /** Rows above the document: the top rule. */
 const HEADER_ROWS = 1;
@@ -91,16 +91,38 @@ export class ReferenceScreenApp {
         const contentWidth = reservesRail ? Math.max(0, rect.width - RAIL_COLUMNS) : rect.width;
         const bodyHeight = Math.max(0, rect.height - HEADER_ROWS - FOOTER_ROWS);
         this.#bodyHeight = bodyHeight;
-        const rows = this.#rows(contentWidth, theme);
-        const maxScroll = Math.max(0, rows.length - bodyHeight);
-        this.#scroll = Math.min(Math.max(0, this.#scroll), maxScroll);
+        const content = this.#content(contentWidth, theme);
+        const body = [];
+        let contentLength;
+        let viewportLength = bodyHeight;
+        if (content.kind === "sections") {
+            const layout = layoutList(content.rows, bodyHeight, this.#scroll, { topPadding: false });
+            this.#scroll = layout.scroll;
+            contentLength = content.rows.length;
+            viewportLength = layout.visible;
+            if (layout.stickyHeader !== undefined)
+                body.push(renderGroupHeader(layout.stickyHeader, contentWidth, theme));
+            for (const index of layout.rowIndexes)
+                body.push(this.#renderSectionRow(content.rows[index], contentWidth, theme));
+        }
+        else {
+            contentLength = content.rows.length;
+            const maxScroll = Math.max(0, content.rows.length - bodyHeight);
+            this.#scroll = Math.min(Math.max(0, this.#scroll), maxScroll);
+            for (let index = this.#scroll; index < this.#scroll + bodyHeight; index++) {
+                const row = content.rows[index] ?? "";
+                body.push(displayWidth(row) > contentWidth ? truncateToWidth(row, contentWidth) : row);
+            }
+        }
+        while (body.length < bodyHeight)
+            body.push("");
         const now = Date.now();
         // Rationale: every way of scrolling ends in this frame, so a moved document is noticed here
         // once rather than at each wheel, drag, and key branch.
         if (this.#renderedScroll !== undefined && this.#renderedScroll !== this.#scroll)
             this.#noteScrollActivity(host, now);
         this.#renderedScroll = this.#scroll;
-        const geometry = scrollbarGeometry({ contentLength: rows.length, viewportHeight: bodyHeight, scroll: this.#scroll, trackHeight: bodyHeight });
+        const geometry = scrollbarGeometry({ contentLength, viewportHeight: viewportLength, scroll: this.#scroll, trackHeight: bodyHeight });
         const presentation = scrollbarPresentation({
             geometry,
             appearance: settings.scrollbarAppearance,
@@ -111,14 +133,9 @@ export class ReferenceScreenApp {
             now,
         });
         this.#railFrame = reservesRail && geometry !== null
-            ? { rail: { key: this.id, column: rect.width, rowStart: HEADER_ROWS, trackHeight: geometry.trackHeight }, geometry, page: bodyHeight }
+            ? { rail: { key: this.id, column: rect.width, rowStart: HEADER_ROWS, trackHeight: geometry.trackHeight }, geometry, page: viewportLength }
             : null;
-        const body = [];
-        for (let index = this.#scroll; index < this.#scroll + bodyHeight; index++) {
-            const row = rows[index] ?? "";
-            body.push(displayWidth(row) > contentWidth ? truncateToWidth(row, contentWidth) : row);
-        }
-        const withRail = withScrollbarRail(body, geometry, contentWidth, theme, { presentation });
+        const withRail = withScrollbarRail(body.slice(0, bodyHeight), geometry, contentWidth, theme, { presentation });
         const hint = this.#interruptArmed ? "press ctrl+c again to exit a1" : REFERENCE_SCREEN_SHORTCUTS.hint(SCOPE, HINT_SEPARATOR);
         // Compatibility: the v2 reference screen frames its document between two border-coloured rules.
         const rule = theme.fg("border", "─".repeat(rect.width));
@@ -197,19 +214,50 @@ export class ReferenceScreenApp {
         return { owned: true, changed: true };
     }
     // Invariant: the title is the first document row, as in v2, so it scrolls with the document.
-    #rows(width, theme) {
+    #content(width, theme) {
         // Compatibility: one leading space, so the title lines up with the padded Markdown rows as in v2.
         const title = ` ${theme.bold(theme.fg("accent", this.#title))}`;
         if (this.#failure !== null)
-            return [title, "", this.#failure];
+            return { kind: "flat", rows: [title, "", this.#failure] };
         const cached = this.#cached;
         if (cached !== null && cached.width === width)
-            return [title, ...cached.rows];
-        const rows = this.#document.rows(width);
-        if (rows === null)
-            return [title, "", LOADING_NOTICE];
-        this.#cached = { width, rows };
-        return [title, ...rows];
+            return this.#withTitle(cached.content, title);
+        const sections = this.#document.sections?.(width);
+        if (sections === null)
+            return { kind: "flat", rows: [title, "", LOADING_NOTICE] };
+        if (sections !== undefined) {
+            const rows = [];
+            sections.forEach((section, sectionIndex) => {
+                if (sectionIndex > 0)
+                    rows.push({ kind: "spacer" });
+                const group = `section-${sectionIndex}`;
+                rows.push({ kind: "group", group, title: section.title });
+                for (const row of section.rows)
+                    rows.push({ kind: "note", group, text: row });
+            });
+            const content = { kind: "sections", rows };
+            this.#cached = { width, content };
+            return this.#withTitle(content, title);
+        }
+        const flat = this.#document.rows?.(width);
+        if (flat === null)
+            return { kind: "flat", rows: [title, "", LOADING_NOTICE] };
+        const content = { kind: "flat", rows: flat ?? [] };
+        this.#cached = { width, content };
+        return this.#withTitle(content, title);
+    }
+    #withTitle(content, title) {
+        if (content.kind === "flat")
+            return { kind: "flat", rows: [title, ...content.rows] };
+        return { kind: "sections", rows: [{ kind: "note", group: "", text: title }, { kind: "spacer" }, ...content.rows] };
+    }
+    #renderSectionRow(row, width, theme) {
+        if (row === undefined || row.kind === "spacer")
+            return "";
+        if (row.kind === "group")
+            return renderGroupHeader(row.title, width, theme);
+        const text = row.kind === "note" ? row.text : row.value;
+        return displayWidth(text) > width ? truncateToWidth(text, width) : text;
     }
     #scrollBy(distance) {
         // Invariant: the upper clamp happens at render, where the body height and row count are known.

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

@@ -1,10 +1,16 @@
-import { GLOBAL_SCOPE, LineInput, PLAIN_THEME, ShortcutRegistry, assertNoShortcutConflicts, blockJumpTarget, dialogValueColumn, numericValues, RAIL_COLUMNS, renderDialogPanel, renderEmptyState, renderGroupHeader, renderInputRow, renderListRow, renderNote, renderStatusLine, dialogRowAt, menuRowAt, regionAt, renderValueMenu, withScrollbarRail, stepperEnds, steppedValue, valueColumnFor, valueMenuFrame, blockRowSpan, displayWidth, handleLineInputKey, humanizeLabel, humanizeTitle, indexOfKey, isThumbRow, layoutList, moveSelection, rowKey, scrollForSelection, scrollForTrackPage, scrollbarGeometry, scrollbarPresentation, ScrollbarRails, scrollbarWheelRows, selectableIndexes, } from "../../ui/components/index.js";
+import { GLOBAL_SCOPE, LineInput, PLAIN_THEME, ShortcutRegistry, assertNoShortcutConflicts, blockJumpTarget, dialogValueColumn, numericValues, RAIL_COLUMNS, renderDialogPanel, renderEmptyState, renderGroupHeader, renderInputRow, renderListRow, renderNote, statusText, dialogRowAt, menuRowAt, regionAt, renderValueMenu, withScrollbarRail, stepperEnds, steppedValue, truncateToWidth, valueColumnFor, valueMenuFrame, blockRowSpan, displayWidth, handleLineInputKey, humanizeLabel, humanizeTitle, indexOfKey, isThumbRow, layoutList, moveSelection, rowKey, scrollForSelection, scrollForTrackPage, scrollbarGeometry, scrollbarPresentation, ScrollbarRails, scrollbarWheelRows, selectableIndexes, } from "../../ui/components/index.js";
 import { SETTINGS_APP_ID, SETTINGS_ROUTE } from "./settings-route.js";
 export { SETTINGS_APP_ID, SETTINGS_ROUTE } from "./settings-route.js";
 const SCOPE = SETTINGS_APP_ID;
+const SETTINGS_TOP_RULE_ROWS = 1;
+const SETTINGS_TITLE_ROWS = 1;
+const SETTINGS_FOOTER_DIVIDER_ROWS = 1;
+const SETTINGS_SEARCH_INPUT_ROWS = 3;
+const SETTINGS_STATUS_ROWS = 1;
+const SETTINGS_CONTENT_INSET = 1;
 /** 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 SCROLLBAR_TOP_INSET = 0;
 /** Identity of the settings list rail in the shared rail state. */
 const RAIL_KEY = "settings";
 // Compatibility: the transcript rail stays lit this long after a scroll, and repaints just after.
@@ -72,13 +78,15 @@ export class SettingsApp {
     #reveal;
     #notice = null;
     #filter = null;
+    #scrollBeforeFilter = null;
     #menu = null;
     #structured = null;
     #interruptArmed = false;
     // Invariant: pending values remain visible until the source reflects them.
     #pending = new Map();
-    #footerHeight = 1;
     #dialogValueColumn = 0;
+    #bodyTopForFrame = SETTINGS_TOP_RULE_ROWS + SETTINGS_TITLE_ROWS;
+    #bodyHeightForFrame = 0;
     #panelTop = 0;
     #panelTopForFrame = 0;
     #hoverKey = null;
@@ -109,16 +117,30 @@ export class SettingsApp {
         const rows = this.#rows();
         const selected = indexOfKey(rows, this.#selectedKey);
         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);
-        if (this.#selectionNeedsReveal) {
+        const dividerRows = this.#filter === null ? SETTINGS_FOOTER_DIVIDER_ROWS : 0;
+        const topRows = Math.min(SETTINGS_TOP_RULE_ROWS, rect.height);
+        const contentHeight = Math.max(0, rect.height - topRows - dividerRows - footer.length);
+        let titleRows = this.#scroll <= 0 ? Math.min(SETTINGS_TITLE_ROWS, contentHeight) : 0;
+        let bodyHeight = contentHeight - titleRows;
+        if (this.#selectionNeedsReveal && bodyHeight > 0) {
             this.#scroll = scrollForSelection(rows, bodyHeight, this.#scroll, selected, this.#reveal);
             this.#selectionNeedsReveal = false;
+            this.#reveal = undefined;
+        }
+        if (this.#scroll > 0 && titleRows > 0) {
+            titleRows = 0;
+            bodyHeight = contentHeight;
         }
-        this.#reveal = undefined;
-        const layout = layoutList(rows, bodyHeight, this.#scroll);
+        let layout = layoutList(rows, bodyHeight, this.#scroll);
+        if (layout.scroll === 0 && titleRows === 0) {
+            titleRows = Math.min(SETTINGS_TITLE_ROWS, contentHeight);
+            bodyHeight = contentHeight - titleRows;
+            layout = layoutList(rows, bodyHeight, 0);
+        }
+        this.#bodyTopForFrame = topRows + titleRows;
+        this.#bodyHeightForFrame = bodyHeight;
+        this.#panelTopForFrame = topRows + contentHeight + dividerRows;
+        this.#panelTop = this.#panelTopForFrame;
         this.#scroll = layout.scroll;
         const now = Date.now();
         // Rationale: every way of scrolling ends in this frame, so a moved list is noticed here
@@ -136,7 +158,7 @@ export class SettingsApp {
             contentLength: rows.length,
             viewportHeight: layout.visible,
             scroll: layout.scroll,
-            trackHeight: Math.max(0, bodyHeight - SCROLLBAR_TOP_INSET),
+            trackHeight: Math.max(0, titleRows + bodyHeight - SCROLLBAR_TOP_INSET),
         });
         const presentation = scrollbarPresentation({
             geometry,
@@ -149,7 +171,7 @@ export class SettingsApp {
         });
         this.#railFrame = reservesRail && geometry !== null
             ? {
-                rail: { key: RAIL_KEY, column: rect.width, rowStart: SCROLLBAR_TOP_INSET, trackHeight: geometry.trackHeight },
+                rail: { key: RAIL_KEY, column: rect.width, rowStart: topRows + SCROLLBAR_TOP_INSET, trackHeight: geometry.trackHeight },
                 geometry,
                 page: layout.visible,
             }
@@ -170,8 +192,8 @@ export class SettingsApp {
                     const view = this.#viewRow(row.value);
                     this.#frameRows.push({
                         key: view.key,
-                        screenRow: body.length,
-                        valueColumn,
+                        screenRow: this.#bodyTopForFrame + body.length,
+                        valueColumn: valueColumn + Math.min(SETTINGS_CONTENT_INSET, contentWidth),
                         valueWidth: displayWidth(view.value),
                         stepper: view.stepper !== undefined,
                     });
@@ -181,11 +203,15 @@ export class SettingsApp {
             while (body.length < bodyHeight)
                 body.push("");
         }
-        const withRail = withScrollbarRail(body.slice(0, bodyHeight), geometry, contentWidth, theme, {
+        const title = truncateToWidth(` ${theme.bold(theme.fg("accent", "Settings"))}`, contentWidth);
+        const scrollingFrame = [...(titleRows === 0 ? [] : [title]), ...body.slice(0, bodyHeight)];
+        const withRail = withScrollbarRail(scrollingFrame, geometry, contentWidth, theme, {
             topInset: SCROLLBAR_TOP_INSET,
             presentation,
         });
-        return this.#withMenu([...withRail, ...footer], selected, layout, valueColumn, theme, rect, reservesRail ? RAIL_COLUMNS : 0);
+        const rule = theme.fg("border", "─".repeat(Math.max(0, rect.width)));
+        const frame = this.#withMenu([rule, ...withRail, ...(dividerRows === 0 ? [] : [rule]), ...footer], selected, layout, valueColumn, theme, rect, reservesRail ? RAIL_COLUMNS : 0);
+        return frame.slice(0, rect.height).concat(Array(Math.max(0, rect.height - frame.length)).fill(""));
     }
     onInput(data, host) {
         if (this.#structured !== null)
@@ -205,6 +231,7 @@ export class SettingsApp {
                 host.close();
                 return { consumed: true };
             case "open-filter":
+                this.#scrollBeforeFilter = this.#scroll;
                 this.#filter = new LineInput("");
                 this.#notice = null;
                 return { consumed: true };
@@ -316,9 +343,15 @@ export class SettingsApp {
         if (event.kind === "wheel-up" || event.kind === "wheel-down") {
             // Invariant: the whole list pane owns wheel scrolling, including blank space beside
             // short labels. It must not depend on finding an item under the pointer.
-            if (event.row < 1 || event.row > this.#panelTopForFrame)
+            const screenRow = event.row - 1;
+            const wheelBottom = this.#filter === null
+                ? this.#bodyTopForFrame + this.#bodyHeightForFrame
+                : this.#panelTopForFrame + SETTINGS_SEARCH_INPUT_ROWS + SETTINGS_STATUS_ROWS;
+            if (screenRow < 0 || screenRow >= wheelBottom)
                 return { consumed: false };
             const distance = scrollbarWheelRows(this.#scrollbarSpeed());
+            if (this.#filter !== null)
+                this.#scrollBeforeFilter = null;
             this.#scroll = Math.max(0, this.#scroll + (event.kind === "wheel-down" ? distance : -distance));
             return { consumed: true };
         }
@@ -520,6 +553,7 @@ export class SettingsApp {
         // Rationale: the boundary chords jump through the results; plain Home and End stay with
         // the search cursor, which the shared line input moves below.
         if (key === "ctrl+home" || key === "ctrl+end") {
+            this.#scrollBeforeFilter = null;
             const rows = this.#rows();
             const selectable = selectableIndexes(rows);
             const target = key === "ctrl+end" ? selectable.at(-1) : selectable[0];
@@ -531,6 +565,7 @@ export class SettingsApp {
             return { consumed: true };
         }
         if (key === "up" || key === "down" || key === "shift+up" || key === "shift+down") {
+            this.#scrollBeforeFilter = null;
             const rows = this.#rows();
             // Rationale: nothing found means nothing to move through; the key is still swallowed
             // rather than typed into the search.
@@ -548,9 +583,16 @@ export class SettingsApp {
             return { consumed: true };
         }
         const outcome = handleLineInputKey(input, data);
-        if (outcome.kind === "cancelled")
+        if (outcome.kind === "cancelled") {
             this.#filter = null;
-        this.#scroll = 0;
+            if (this.#scrollBeforeFilter !== null)
+                this.#scroll = this.#scrollBeforeFilter;
+            this.#scrollBeforeFilter = null;
+        }
+        else {
+            this.#scrollBeforeFilter = null;
+            this.#scroll = 0;
+        }
         return { consumed: true };
     }
     #cycle(rows, selected, delta) {
@@ -684,16 +726,17 @@ export class SettingsApp {
         return renderGroupHeader(humanizeTitle(title), width, theme);
     }
     #renderRow(row, selected, width, valueColumn, theme) {
-        if (row === undefined || row.kind === "spacer")
+        if (row === undefined || row.kind === "spacer" || width < SETTINGS_CONTENT_INSET)
             return "";
         if (row.kind === "group")
             return this.#header(row.title, theme, width);
+        const innerWidth = width - SETTINGS_CONTENT_INSET;
         if (row.kind === "note")
-            return renderNote(row.text, width, theme);
+            return ` ${renderNote(row.text, innerWidth, 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);
+        return ` ${renderListRow(this.#viewRow(entry), { selected, hovered, region: this.#hoverRegion }, valueColumn, innerWidth, theme)}`;
     }
     #viewRow(entry) {
         const shown = this.#shownValue(entry);
@@ -723,7 +766,8 @@ export class SettingsApp {
             index: menu.index,
         };
         const frame = valueMenuFrame(state, { screenRow: anchor.screenRow, valueColumn }, {
-            bodyHeight: lines.length - this.#footerHeight,
+            bodyTop: this.#bodyTopForFrame,
+            bodyHeight: this.#bodyHeightForFrame,
             surfaceWidth: rect.width,
             reservedRight,
         });
@@ -749,7 +793,8 @@ export class SettingsApp {
         if (open !== null)
             return this.#dialogLines(open, width, theme);
         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 report = statusText({ hint, report: this.#notice });
+        const status = truncateToWidth(`${width > 0 ? " " : ""}${theme.fg("dim", report)}`, width);
         const input = this.#filter;
         if (input === null)
             return [status];