@timurproko/a1 0.1.8-dev.508 → 0.1.8-dev.510

package/dist/composition/owned-ui.js

@@ -12,6 +12,8 @@ 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 { readPinnedCommandChangelog } from "../integrations/pi/engine/changelog.js";
 export async function composeOwnedUiApplication(options = {}) {
     return (await composeOwnedUi(options)).application;
 }
@@ -40,7 +42,19 @@ export async function composeOwnedUi(options = {}) {
     // dark, regardless of terminal detection or a previously stored Pi theme. The
     // comparison profile keeps Pi's configured theme behavior and settings surface.
     applyConfiguredPiTheme(ownedSurfaces ? "dark" : adapter.configuredTheme());
-    const routeHost = settings === null || !ownedSurfaces ? null : createOwnedRouteHost(settings);
+    // Rationale: the reference screens read the shell the composition is about to construct; a route
+    // cannot open before the shell exists, so the closure is settled by the time it runs.
+    const references = {
+        changelog: async (input) => {
+            const markdown = input?.document ?? await readPinnedCommandChangelog();
+            return width => renderPiShellChangelogLines(markdown, width);
+        },
+        hotkeys: async () => {
+            const presentation = shell.hotkeysPresentation();
+            return width => renderPiShellHotkeysLines(presentation, width);
+        },
+    };
+    const routeHost = settings === null || !ownedSurfaces ? null : createOwnedRouteHost(settings, references);
     const viewportSettings = settings === null || !ownedSurfaces ? null : {
         snapshot: () => viewportSettingsSnapshot(settings),
         onChange: listener => settings.onChange(() => listener(viewportSettingsSnapshot(settings))),
@@ -54,6 +68,11 @@ export async function composeOwnedUi(options = {}) {
         enabled: () => settings.value("promptSuggestions"),
         onChange: (listener) => settings.onChange(() => listener(settings.value("promptSuggestions"))),
     };
+    const skills = settings === null || !ownedSurfaces ? null : {
+        presentation: () => settings.value("skillsPresentation"),
+        // Rationale: one listener covers both the A1 presentation choice and the engine skill-command toggle.
+        onChange: (listener) => settings.onChange(() => listener()),
+    };
     const historyLimit = settings?.value("promptHistoryMaxItems");
     const historyProfileLocation = settings === null || !ownedSurfaces || !settings.value("promptHistoryEnabled")
         ? null
@@ -92,6 +111,7 @@ export async function composeOwnedUi(options = {}) {
                     paste: event => clipboardDiagnostics.paste(event),
                 } }),
             ...(promptSuggestions === null ? {} : { suggestions: promptSuggestions }),
+            ...(skills === null ? {} : { skills }),
             ...(promptHistory === null ? {} : { history: {
                     ...promptHistory,
                     editor: await import("../integrations/pi/components/history-editor-loader.js").then(module => module.loadHistoryEditor()),
@@ -123,8 +143,6 @@ export async function composeOwnedUi(options = {}) {
 function quitOutroSettingsSnapshot(settings) {
     return {
         enabled: settings.value("quitAnimation"),
-        effect: settings.value("quitEffect"),
-        durationMs: settings.value("quitEffectDurationMs"),
     };
 }
 function viewportSettingsSnapshot(settings) {

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

@@ -1,7 +1,20 @@
 import type { OwnedSettingsManager } from "../ui/settings/manager.js";
-import type { UiRouteHost } from "../ui/apps/contracts.js";
+import type { UiRouteHost, UiRouteInput } from "../ui/apps/contracts.js";
+/** Styled document rows for one content width. */
+export type OwnedReferenceRows = (width: number) => readonly string[];
 /**
- * Declares the A1-owned settings route without evaluating its presentation graph
- * during startup. Opening the route retains input while the optional module loads.
+ * 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 declare function createOwnedRouteHost(settings: OwnedSettingsManager): UiRouteHost;
+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>;
+}
+/**
+ * Declares the A1-owned settings route, and the changelog and hotkeys reference
+ * routes when their documents are supplied, without evaluating their presentation
+ * graphs during startup. Opening a route retains input while the optional module loads.
+ */
+export declare function createOwnedRouteHost(settings: OwnedSettingsManager, references?: OwnedReferenceProviders): UiRouteHost;

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

@@ -1,24 +1,38 @@
+import { CHANGELOG_APP_ID, CHANGELOG_ROUTE, CHANGELOG_TITLE, HOTKEYS_APP_ID, HOTKEYS_ROUTE, HOTKEYS_TITLE, } from "../features/owned-ui/reference-routes.js";
 import { SETTINGS_APP_ID, SETTINGS_ROUTE } from "../features/owned-ui/settings-route.js";
 import { piTheme } from "../integrations/pi/components/upstream/theme/theme.js";
 import { faint } from "../ui/components/text.js";
 /**
- * Declares the A1-owned settings route without evaluating its presentation graph
- * during startup. Opening the route retains input while the optional module loads.
+ * Declares the A1-owned settings route, and the changelog and hotkeys reference
+ * routes when their documents are supplied, without evaluating their presentation
+ * graphs during startup. Opening a route retains input while the optional module loads.
  */
-export function createOwnedRouteHost(settings) {
+export function createOwnedRouteHost(settings, references) {
+    const routes = new Set([SETTINGS_ROUTE, ...(references === undefined ? [] : [CHANGELOG_ROUTE, HOTKEYS_ROUTE])]);
     return {
-        claims: route => route === SETTINGS_ROUTE,
-        open: route => route === SETTINGS_ROUTE ? deferredSettingsSurface(settings) : null,
+        claims: route => routes.has(route),
+        open: (route, input) => {
+            if (!routes.has(route))
+                return null;
+            if (route === SETTINGS_ROUTE) {
+                return deferredSurface(SETTINGS_APP_ID, "settings", () => loadSettingsSurface(settings));
+            }
+            const changelog = route === CHANGELOG_ROUTE;
+            const id = changelog ? CHANGELOG_APP_ID : HOTKEYS_APP_ID;
+            const title = changelog ? CHANGELOG_TITLE : HOTKEYS_TITLE;
+            const document = changelog ? references.changelog(input) : references.hotkeys();
+            return deferredSurface(id, title, () => loadReferenceSurface(settings, id, route, title, document));
+        },
     };
 }
-function deferredSettingsSurface(settings) {
+function deferredSurface(id, label, load) {
     let delegate = null;
     let closed = false;
     let failure = null;
     let onRender = () => undefined;
     let onExit = () => undefined;
     const pending = [];
-    void loadSettingsSurface(settings).then(surface => {
+    void load().then(surface => {
         if (closed) {
             surface.close();
             return;
@@ -30,7 +44,7 @@ function deferredSettingsSurface(settings) {
             action(surface);
         onRender();
     }).catch(error => {
-        failure = `Could not load settings: ${error instanceof Error ? error.message : String(error)}`;
+        failure = `Could not load ${label}: ${error instanceof Error ? error.message : String(error)}`;
         onRender();
     });
     const defer = (action) => {
@@ -40,10 +54,9 @@ function deferredSettingsSurface(settings) {
             pending.push(action);
     };
     return {
-        id: SETTINGS_APP_ID,
+        id,
         render: (width, height) => delegate?.render(width, height)
-            ?? [...(height > 0 ? [failure ?? "Loading settings…"] : []), ...Array(Math.max(0, height - 1)).fill("")]
-                .map(line => line.slice(0, Math.max(0, width))),
+            ?? Array.from({ length: Math.max(0, height) }, (_, row) => row === 0 && failure !== null ? failure.slice(0, Math.max(0, width)) : ""),
         handleInput: data => { defer(surface => surface.handleInput(data)); return true; },
         handleMouse: event => { defer(surface => surface.handleMouse(event)); return true; },
         isClosed: () => closed || delegate?.isClosed() === true,
@@ -53,13 +66,31 @@ function deferredSettingsSurface(settings) {
     };
 }
 async function loadSettingsSurface(settings) {
-    const [{ SettingsApp }, { UiAppHost }, { UiAppRegistry }] = await Promise.all([
-        import("../features/owned-ui/settings-app.js"),
+    const { SettingsApp } = await import("../features/owned-ui/settings-app.js");
+    return hostApp(SETTINGS_APP_ID, SETTINGS_ROUTE, () => new SettingsApp(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]);
+    return hostApp(id, route, () => new ReferenceScreenApp({
+        id,
+        title,
+        document: { rows },
+        scrollSettings: () => ({
+            scrollbarAppearance: settings.value("scrollbarAppearance"),
+            scrollbarStyle: settings.value("scrollbarStyle"),
+            scrollbarSpeed: settings.value("scrollbarSpeed"),
+        }),
+    }));
+}
+async function hostApp(id, route, create) {
+    const [{ UiAppHost }, { UiAppRegistry }] = await Promise.all([
         import("../ui/apps/host.js"),
         import("../ui/apps/registry.js"),
     ]);
     const registry = new UiAppRegistry();
-    registry.register({ id: SETTINGS_APP_ID, route: SETTINGS_ROUTE, create: () => new SettingsApp(settings) });
+    registry.register({ id, route, create });
     let size = { width: 80, height: 24 };
     let frame = [];
     let closed = false;
@@ -81,9 +112,9 @@ async function loadSettingsSurface(settings) {
             },
         },
     });
-    host.open(SETTINGS_APP_ID);
+    host.open(id);
     return {
-        id: SETTINGS_APP_ID,
+        id,
         render: (width, height) => {
             size = { width, height };
             host.render();

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

@@ -1,7 +1,7 @@
 export { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, assertOwnedUiExtensionUiPort, } from "./extension-ui.js";
 export type { OwnedUiExtensionAutocompleteItem, OwnedUiExtensionAutocompleteProvider, OwnedUiExtensionAutocompleteProviderFactory, OwnedUiExtensionAutocompleteSuggestions, OwnedUiExtensionComponent, OwnedUiExtensionComponentFactory, OwnedUiExtensionComponentFactoryContext, OwnedUiExtensionCustomFactory, OwnedUiExtensionCustomOptions, OwnedUiExtensionDialogOptions, OwnedUiExtensionEditorComponent, OwnedUiExtensionEditorFactory, OwnedUiExtensionEditorThemePort, OwnedUiExtensionEntryRenderInput, OwnedUiExtensionFooterDataPort, OwnedUiExtensionFooterFactory, OwnedUiExtensionInputListener, OwnedUiExtensionKeybindingsPort, OwnedUiExtensionMessageRenderInput, OwnedUiExtensionNotificationSeverity, OwnedUiExtensionOverlayAnchor, OwnedUiExtensionOverlayHandle, OwnedUiExtensionOverlayMargin, OwnedUiExtensionOverlayOptions, OwnedUiExtensionRenderCallback, OwnedUiExtensionRendererPort, OwnedUiExtensionRuntimePort, OwnedUiExtensionSelectListThemePort, OwnedUiExtensionSizeValue, OwnedUiExtensionTerminalPort, OwnedUiExtensionThemeBackground, OwnedUiExtensionThemeColor, OwnedUiExtensionThemeInfo, OwnedUiExtensionThemePort, OwnedUiExtensionToolRenderContext, OwnedUiExtensionUiCallback, OwnedUiExtensionUiPort, OwnedUiExtensionUiProperty, OwnedUiExtensionWidgetOptions, OwnedUiExtensionWidgetPlacement, OwnedUiExtensionWorkingIndicatorOptions, } from "./extension-ui.js";
 export { OWNED_UI_CONTRACT_VERSION } from "./model.js";
-export type { OwnedUiBlockStatus, OwnedUiCommand, OwnedUiCommandOutcome, OwnedUiCorrelationId, OwnedUiCustomization, OwnedUiDiagnostics, OwnedUiDialog, OwnedUiEditorState, OwnedUiEntityId, OwnedUiEvent, OwnedUiFooterView, OwnedUiImageAttachment, OwnedUiLifecycle, OwnedUiModelInfo, OwnedUiOverlay, OwnedUiPromptSuggestionGeneratorPort, OwnedUiPromptSuggestionIdentity, OwnedUiPromptSuggestionReasoning, OwnedUiPromptSuggestionRequest, OwnedUiPromptSuggestionResult, OwnedUiPromptSuggestionState, OwnedUiQuitEffect, OwnedUiQuitOutroSettings, OwnedUiQuitOutroSettingsPort, OwnedUiSessionId, OwnedUiSessionViewModel, OwnedUiSeverity, OwnedUiSlotId, OwnedUiSnapshot, OwnedUiStatusView, OwnedUiTerminalSurface, OwnedUiThinkingLevel, OwnedUiToolRendering, OwnedUiToolResultPart, OwnedUiToolState, OwnedUiTranscriptBlock, OwnedUiTranscriptBlockKind, OwnedUiTranscriptImageReference, OwnedUiUsageView, OwnedUiViewportSettings, OwnedUiViewportSettingsPort, } from "./model.js";
+export type { OwnedUiBlockStatus, OwnedUiCommand, OwnedUiCommandOutcome, OwnedUiCorrelationId, OwnedUiCustomization, OwnedUiDiagnostics, OwnedUiDialog, OwnedUiEditorState, OwnedUiEntityId, OwnedUiEvent, OwnedUiFooterView, OwnedUiImageAttachment, OwnedUiLifecycle, OwnedUiModelInfo, OwnedUiOverlay, OwnedUiPromptSuggestionGeneratorPort, OwnedUiPromptSuggestionIdentity, OwnedUiPromptSuggestionReasoning, OwnedUiPromptSuggestionRequest, OwnedUiPromptSuggestionResult, OwnedUiPromptSuggestionState, OwnedUiQuitOutroSettings, OwnedUiQuitOutroSettingsPort, OwnedUiSessionId, OwnedUiSessionViewModel, OwnedUiSeverity, OwnedUiSlotId, OwnedUiSnapshot, OwnedUiStatusView, OwnedUiTerminalSurface, OwnedUiThinkingLevel, OwnedUiToolRendering, OwnedUiToolResultPart, OwnedUiToolState, OwnedUiTranscriptBlock, OwnedUiTranscriptBlockKind, OwnedUiTranscriptImageReference, OwnedUiUsageView, OwnedUiViewportSettings, OwnedUiViewportSettingsPort, } from "./model.js";
 export { acceptsTranscriptUpdate, transcriptToolState } from "./transcript-lifecycle.js";
 export { ImageAttachmentError, MAX_CLIPBOARD_TEXT_BYTES, MAX_IMAGE_DATA_BYTES, MAX_PROMPT_IMAGES, assertImageEncodedSize, assertPromptImages, } from "./image-attachments.js";
 export { CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION, normalizePromptSuggestionCandidate } from "./prompt-suggestions.js";

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

@@ -64,14 +64,10 @@ export interface OwnedUiViewportSettingsPort {
     snapshot(): OwnedUiViewportSettings;
     onChange(listener: (settings: OwnedUiViewportSettings) => void): () => void;
 }
-export type OwnedUiQuitEffect = "fall" | "dissolve" | "starburst" | "waves";
 /** Profile-local quit outro choice, read at the moment bare A1 quits. */
 export interface OwnedUiQuitOutroSettings {
-    /** False leaves the terminal immediately; the effect and duration are then ignored. */
+    /** False leaves the terminal immediately; true plays the shell's fixed effect. */
     readonly enabled: boolean;
-    readonly effect: OwnedUiQuitEffect;
-    /** Requested playback length; the player clamps it to its supported range. */
-    readonly durationMs: number;
 }
 export interface OwnedUiQuitOutroSettingsPort {
     snapshot(): OwnedUiQuitOutroSettings;

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

@@ -4,3 +4,6 @@ export { createConsoleProjectTrustPrompt } from "./project-trust-prompt.js";
 export type { ConsoleProjectTrustPromptOptions, OwnedProjectTrustPrompt, OwnedProjectTrustPromptRequest } from "./project-trust-prompt.js";
 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 { CHANGELOG_APP_ID, CHANGELOG_ROUTE, CHANGELOG_TITLE, HOTKEYS_APP_ID, HOTKEYS_ROUTE, HOTKEYS_TITLE, } from "./reference-routes.js";

package/dist/features/owned-ui/index.js

@@ -2,3 +2,5 @@ export { runOwnedUi, terminateOwnedUiProcess } from "./run.js";
 export { createConsoleProjectTrustPrompt } from "./project-trust-prompt.js";
 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 { CHANGELOG_APP_ID, CHANGELOG_ROUTE, CHANGELOG_TITLE, HOTKEYS_APP_ID, HOTKEYS_ROUTE, HOTKEYS_TITLE, } from "./reference-routes.js";

package/dist/features/owned-ui/reference-routes.d.ts

@@ -0,0 +1,6 @@
+export declare const CHANGELOG_APP_ID = "changelog";
+export declare const CHANGELOG_ROUTE = "changelog";
+export declare const CHANGELOG_TITLE = "What's New";
+export declare const HOTKEYS_APP_ID = "hotkeys";
+export declare const HOTKEYS_ROUTE = "hotkeys";
+export declare const HOTKEYS_TITLE = "Keyboard Shortcuts";

package/dist/features/owned-ui/reference-routes.js

@@ -0,0 +1,6 @@
+export const CHANGELOG_APP_ID = "changelog";
+export const CHANGELOG_ROUTE = "changelog";
+export const CHANGELOG_TITLE = "What's New";
+export const HOTKEYS_APP_ID = "hotkeys";
+export const HOTKEYS_ROUTE = "hotkeys";
+export const HOTKEYS_TITLE = "Keyboard Shortcuts";

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

@@ -0,0 +1,37 @@
+import type { OwnedUiViewportSettings } from "../../contracts/owned-ui/index.js";
+import type { AppHostServices, UiApp } from "../../ui/apps/index.js";
+import { ShortcutRegistry, type PaneInputResult, type PaneMouseEvent, type PaneRect } from "../../ui/components/index.js";
+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 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. */
+    readonly ready?: Promise<void>;
+}
+export interface ReferenceScreenOptions {
+    readonly id: string;
+    readonly title: string;
+    readonly document: ReferenceDocumentProvider;
+    /** The reader's scroll settings, read on every frame so a live change is honored. */
+    readonly scrollSettings: () => OwnedUiViewportSettings;
+}
+/**
+ * Presents one read-only document full screen between two accent rules: the bold
+ * title leads the scrolled rows, the shared scrollbar rail runs beside them, and
+ * the hint line closes the frame. Rows come from a provider per content width and
+ * are cached until the width changes; the screen closes on Escape and leaves the
+ * interrupt chord to its host.
+ */
+export declare class ReferenceScreenApp implements UiApp {
+    #private;
+    readonly id: string;
+    constructor(options: ReferenceScreenOptions);
+    onActivate(host: AppHostServices): void;
+    onClose(_host: AppHostServices): void;
+    render(rect: PaneRect, host: AppHostServices): readonly string[];
+    onInput(data: string, host: AppHostServices): PaneInputResult;
+    onMouse(event: PaneMouseEvent, _host: AppHostServices): PaneInputResult;
+}
+export {};

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

@@ -0,0 +1,232 @@
+import { GLOBAL_SCOPE, PLAIN_THEME, RAIL_COLUMNS, ShortcutRegistry, ScrollbarRails, assertNoShortcutConflicts, displayWidth, padToWidth, 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;
+/** Rows below the document: the bottom rule and the hint line. */
+const FOOTER_ROWS = 2;
+// Compatibility: the transcript rail stays lit this long after a scroll, and repaints just after.
+const SCROLL_LINGER_MS = 900;
+const SCROLL_LINGER_REPAINT_MS = 925;
+const LOADING_NOTICE = "Loading…";
+export const REFERENCE_SCREEN_SHORTCUTS = new ShortcutRegistry();
+// Compatibility: the footer reads as v2's `esc/ctrl+c close • ↑↓ scroll`, without ctrl+c, which is
+// the A1 interrupt chord here rather than a close key.
+REFERENCE_SCREEN_SHORTCUTS.declare({ key: "escape", scope: GLOBAL_SCOPE, description: "Close", section: "Screen", hint: { keys: "esc", does: "close" } }, "close");
+REFERENCE_SCREEN_SHORTCUTS.declare({ key: "up", scope: SCOPE, description: "Scroll up", section: "Navigate", hint: { keys: "↑↓", does: "scroll" } }, "up");
+REFERENCE_SCREEN_SHORTCUTS.declare({ key: "down", scope: SCOPE, description: "Scroll down", section: "Navigate", hint: { keys: "↑↓", does: "scroll" } }, "down");
+REFERENCE_SCREEN_SHORTCUTS.declare({ key: "pageUp", scope: SCOPE, description: "Up a page", section: "Navigate" }, "page-up");
+REFERENCE_SCREEN_SHORTCUTS.declare({ key: "pageDown", scope: SCOPE, description: "Down a page", section: "Navigate" }, "page-down");
+REFERENCE_SCREEN_SHORTCUTS.declare({ key: "home", scope: SCOPE, description: "First row", section: "Navigate" }, "first");
+REFERENCE_SCREEN_SHORTCUTS.declare({ key: "end", scope: SCOPE, description: "Last row", section: "Navigate" }, "last");
+/** The separator v2's footer puts between its hints. */
+const HINT_SEPARATOR = " • ";
+assertNoShortcutConflicts(REFERENCE_SCREEN_SHORTCUTS.assemble());
+const KEYS = {
+    "\u001b[A": "up",
+    "\u001b[B": "down",
+    "\u001b[5~": "pageUp",
+    "\u001b[6~": "pageDown",
+    // Protocol: xterm, VT220, and rxvt forms of the same two chords.
+    "\u001b[H": "home",
+    "\u001b[1~": "home",
+    "\u001b[7~": "home",
+    "\u001b[F": "end",
+    "\u001b[4~": "end",
+    "\u001b[8~": "end",
+    "\u001b": "escape",
+};
+/**
+ * Presents one read-only document full screen between two accent rules: the bold
+ * title leads the scrolled rows, the shared scrollbar rail runs beside them, and
+ * the hint line closes the frame. Rows come from a provider per content width and
+ * are cached until the width changes; the screen closes on Escape and leaves the
+ * interrupt chord to its host.
+ */
+export class ReferenceScreenApp {
+    id;
+    #title;
+    #document;
+    #scrollSettings;
+    #scroll = 0;
+    #interruptArmed = false;
+    #failure = null;
+    // Performance: the provider wraps Markdown; wheel and drag frames must not repeat that work.
+    #cached = null;
+    // Invariant: rail hover and drag live in the shared keyed state, as the transcript's do.
+    #rails = new ScrollbarRails();
+    // Rationale: the rail as drawn in the last frame, or null when nothing can be pointed at.
+    #railFrame = null;
+    #bodyHeight = 0;
+    // Invariant: a scroll lights the rail until this time; the timer repaints once it has passed.
+    #activeUntil = 0;
+    #activityTimer;
+    #renderedScroll;
+    constructor(options) {
+        this.id = options.id;
+        this.#title = options.title;
+        this.#document = options.document;
+        this.#scrollSettings = options.scrollSettings;
+    }
+    onActivate(host) {
+        const ready = this.#document.ready;
+        if (ready === undefined)
+            return;
+        void ready.then(() => {
+            this.#cached = null;
+            host.requestRender();
+        }, (error) => {
+            this.#failure = `Could not load ${this.#title}: ${error instanceof Error ? error.message : String(error)}`;
+            host.requestRender();
+        });
+    }
+    onClose(_host) {
+        this.#clearActivityTimer();
+        this.#rails.clear();
+    }
+    render(rect, host) {
+        const theme = host.theme ?? PLAIN_THEME;
+        this.#interruptArmed = host.interruptArmed;
+        const settings = this.#scrollSettings();
+        const reservesRail = settings.scrollbarAppearance !== "hidden";
+        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 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 presentation = scrollbarPresentation({
+            geometry,
+            appearance: settings.scrollbarAppearance,
+            style: settings.scrollbarStyle,
+            hovered: this.#rails.isHovered(this.id),
+            dragging: this.#rails.isDragging(this.id),
+            activeUntil: this.#activeUntil,
+            now,
+        });
+        this.#railFrame = reservesRail && geometry !== null
+            ? { rail: { key: this.id, column: rect.width, rowStart: HEADER_ROWS, trackHeight: geometry.trackHeight }, geometry, page: bodyHeight }
+            : 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 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));
+        // Compatibility: v2 sets its footer against the left edge, unlike the settings status line.
+        const frame = [rule, ...withRail, rule, padToWidth(theme.fg("dim", hint), rect.width)];
+        // Invariant: a rectangle too small for the chrome still gets exactly its rows, top first.
+        return frame.slice(0, rect.height).concat(Array(Math.max(0, rect.height - frame.length)).fill(""));
+    }
+    onInput(data, host) {
+        const action = REFERENCE_SCREEN_SHORTCUTS.resolve(KEYS[data] ?? data, SCOPE);
+        if (action === null)
+            return { consumed: false };
+        switch (action) {
+            case "close":
+                host.close();
+                return { consumed: true };
+            case "up":
+                this.#scrollBy(-1);
+                return { consumed: true };
+            case "down":
+                this.#scrollBy(1);
+                return { consumed: true };
+            case "page-up":
+                this.#scrollBy(-Math.max(1, this.#bodyHeight));
+                return { consumed: true };
+            case "page-down":
+                this.#scrollBy(Math.max(1, this.#bodyHeight));
+                return { consumed: true };
+            case "first":
+                this.#scroll = 0;
+                return { consumed: true };
+            case "last":
+                this.#scroll = Number.MAX_SAFE_INTEGER;
+                return { consumed: true };
+        }
+    }
+    onMouse(event, _host) {
+        if (event.kind === "wheel-up" || event.kind === "wheel-down") {
+            // Invariant: the whole screen owns wheel scrolling; it must not depend on the pointer's row.
+            const distance = scrollbarWheelRows(this.#scrollSettings().scrollbarSpeed);
+            this.#scrollBy(event.kind === "wheel-down" ? distance : -distance);
+            return { consumed: true };
+        }
+        const rail = this.#railPointer(event);
+        if (rail.owned)
+            return { consumed: true };
+        return { consumed: event.kind !== "motion", render: rail.changed };
+    }
+    // Rationale: the rail takes its share of a pointer report first: hover, a thumb drag, or a
+    // track page. Owned means the document must not see the report; changed means the rail looks different.
+    #railPointer(event) {
+        const frame = this.#railFrame;
+        const wasHovered = this.#rails.isHovered(this.id);
+        if (frame === null) {
+            this.#rails.clear();
+            return { owned: false, changed: wasHovered };
+        }
+        const pointer = { column: event.column, row: event.row - 1 };
+        if (this.#rails.isDragging(this.id)) {
+            // Invariant: a drag keeps the pointer wherever it goes until the button comes up.
+            if (event.kind === "release")
+                this.#rails.endDrag();
+            else {
+                const target = this.#rails.dragTo(frame.rail, frame.geometry, pointer);
+                if (target !== null)
+                    this.#scroll = target;
+            }
+            return { owned: true, changed: true };
+        }
+        const over = this.#rails.notePointer([frame.rail], pointer) !== null;
+        if (!over)
+            return { owned: false, changed: wasHovered };
+        if (event.kind === "press" && !this.#rails.beginDrag(frame.rail, frame.geometry, pointer)) {
+            this.#scroll = scrollForTrackPage(frame.geometry, pointer.row - frame.rail.rowStart, this.#scroll, frame.page);
+        }
+        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) {
+        // 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];
+        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];
+    }
+    #scrollBy(distance) {
+        // Invariant: the upper clamp happens at render, where the body height and row count are known.
+        this.#scroll = Math.max(0, this.#scroll + distance);
+    }
+    #noteScrollActivity(host, now) {
+        this.#activeUntil = Math.max(this.#activeUntil, now + SCROLL_LINGER_MS);
+        this.#clearActivityTimer();
+        this.#activityTimer = setTimeout(() => {
+            this.#activityTimer = undefined;
+            host.requestRender();
+        }, SCROLL_LINGER_REPAINT_MS);
+        this.#activityTimer.unref?.();
+    }
+    #clearActivityTimer() {
+        if (this.#activityTimer !== undefined)
+            clearTimeout(this.#activityTimer);
+        this.#activityTimer = undefined;
+    }
+}

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

@@ -74,7 +74,6 @@ export class SettingsApp {
     #filter = null;
     #menu = null;
     #structured = null;
-    #loading = true;
     #interruptArmed = false;
     // Invariant: pending values remain visible until the source reflects them.
     #pending = new Map();
@@ -98,10 +97,7 @@ export class SettingsApp {
         this.#session = session;
     }
     onActivate(host) {
-        void this.#session.load().then(() => {
-            this.#loading = false;
-            host.requestRender();
-        });
+        void this.#session.load().then(() => host.requestRender());
     }
     onClose(_host) {
         this.#clearActivityTimer();
@@ -161,8 +157,7 @@ export class SettingsApp {
         const body = [];
         this.#frameRows = [];
         if (rows.length === 0) {
-            const message = this.#loading ? "Loading settings…" : "No settings found.";
-            body.push(...renderEmptyState(message, "👀", bodyHeight, contentWidth, theme));
+            body.push(...renderEmptyState("No settings found.", "👀", bodyHeight, contentWidth, theme));
         }
         else {
             if (layout.topPadding > 0)

package/dist/foundation/release/index.d.ts

@@ -22,6 +22,8 @@ export { STABLE_RELEASE_SCHEMA, createStableReleaseEvidence, verifyStableRegistr
 export type { StableRegistryState, StableRegistryVerificationOptions, StableReleaseEvidence, StableReleaseEvidenceInput } from "./stable-release.js";
 export { PRODUCT_PACKAGE, assertUpdatePerformanceBudget, createNpmProcessRunner, createUpdateLifecycleCoordinator, planUpdateOwnership, renderUpdateProgressBar, runSelfUpdate, } from "./update.js";
 export type { ProcessRequest, ProcessResult, SelfUpdateOptions, UpdateActivationPhase, UpdateChannel, UpdateFileSystem, UpdateLifecycleCoordinator, UpdateMaterializationProgress, UpdateMeasuredPhase, UpdateOutput, UpdateOwnershipAction, UpdatePackageReplacementInput, UpdatePerformanceEvidence, UpdatePhaseTimingEvent, UpdateProcessRunner, UpdateTransactionJournal, } from "./update.js";
+export { UPDATE_ACTIVATION_CONTRACT, UPDATE_ACTIVATION_ENTRY, UPDATE_ACTIVATION_MANIFEST_FIELD, activateInstalledRelease, delegateActivation, readActivationContracts, runActivationEntry, } from "./update-activation.js";
+export type { UpdateActivationCallbacks, UpdateActivationEvent, UpdateActivationRequest } from "./update-activation.js";
 export { selectSupervisorLaunchReleaseId, selectUpdateLaunchRelease } from "./update-launch.js";
 export { UPDATE_RECOVERY_SCHEMA, cleanupUpdateRecoveryCapsules, inspectUpdateLauncherSet, prepareUpdateRecoveryCapsule, readUpdateRecoveryCapsule, removeUpdateRecoveryCapsule, runProtectedPackageReplacement, updateLauncherPaths, } from "./update-recovery.js";
 export type { ProtectedPackageReplacementOptions, ProtectedPackageReplacementResult, UpdateRecoveryCapsule, UpdateRecoveryResult } from "./update-recovery.js";

package/dist/foundation/release/index.js

@@ -10,6 +10,7 @@ export { RELEASE_MANIFEST_FILENAME, assertImmutableExecutionRoot, consumeMateria
 export { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDocument, restartSealDigest } from "./restart-certification.js";
 export { STABLE_RELEASE_SCHEMA, createStableReleaseEvidence, verifyStableRegistry } from "./stable-release.js";
 export { PRODUCT_PACKAGE, assertUpdatePerformanceBudget, createNpmProcessRunner, createUpdateLifecycleCoordinator, planUpdateOwnership, renderUpdateProgressBar, runSelfUpdate, } from "./update.js";
+export { UPDATE_ACTIVATION_CONTRACT, UPDATE_ACTIVATION_ENTRY, UPDATE_ACTIVATION_MANIFEST_FIELD, activateInstalledRelease, delegateActivation, readActivationContracts, runActivationEntry, } from "./update-activation.js";
 export { selectSupervisorLaunchReleaseId, selectUpdateLaunchRelease } from "./update-launch.js";
 export { UPDATE_RECOVERY_SCHEMA, cleanupUpdateRecoveryCapsules, inspectUpdateLauncherSet, prepareUpdateRecoveryCapsule, readUpdateRecoveryCapsule, removeUpdateRecoveryCapsule, runProtectedPackageReplacement, updateLauncherPaths, } from "./update-recovery.js";
 export { UPDATE_JOURNAL_SCHEMA, UpdateTransactionStore } from "./update-transaction.js";