@timurproko/a1 0.1.8-dev.512 → 0.1.8-dev.521

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

@@ -9,12 +9,14 @@ import { assertPromptImages, ImageAttachmentError } from "../../contracts/owned-
 import { ContextualPromptSuggestionController } from "./prompt-suggestion-controller.js";
 import { MOUSE_TRACKING_OFF, MOUSE_TRACKING_ON, parseMouseInput } from "../../ui/components/mouse.js";
 import { readVisibleHyperlinks } from "../../ui/components/visible-hyperlinks.js";
-import { PINNED_PI_HIDDEN_COMMAND_NAMES, PINNED_PI_WORKFLOW_COMMAND_NAMES } from "../../integrations/pi/engine/workflows.js";
+import { PINNED_PI_HIDDEN_COMMAND_NAMES, workflowCommandNames } from "../../integrations/pi/engine/workflows.js";
 import { createPiExtensionUiBridge } from "../../integrations/pi/components/shell-extension-ui.js";
 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, createPiShellOperationLoader, createPiShellReloadBox, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionSelector, createPiShellSettingsSelector, 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, createPiShellThinkingSelector, 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";
 import { onPiThemeChange, piTheme } from "../../integrations/pi/components/upstream/theme/theme.js";
 import { DamageAwareTerminalAdapter } from "../../integrations/pi/tui-runtime/damage-aware-terminal.js";
@@ -35,6 +37,9 @@ export class OwnedUiSessionShell {
     #unsubscribe;
     #unsubscribePromptSuggestions;
     #promptSuggestions;
+    #skills;
+    #unsubscribeSkills;
+    #installedCommandSignature = "";
     #promptHistory = null;
     #promptHistoryImageSidecar;
     #extensionBridge;
@@ -51,6 +56,8 @@ export class OwnedUiSessionShell {
     #shutdownPromise;
     #disposePromise;
     #pointerReporting = false;
+    // Invariant: the startup release notes open at most once per shell, whatever the view does later.
+    #startupChangelogHandled = false;
     #customViewport;
     #responseCopy;
     // Rationale: only an executor this shell created owns a spare copy helper worth warming and disposing.
@@ -96,6 +103,8 @@ export class OwnedUiSessionShell {
         let streamPresentation;
         let pendingClipboardWrite = Promise.resolve();
         let promptSuggestionController = null;
+        // Invariant: the collapsed skills presentation is a bare-A1 replacement; comparison profiles keep the pinned list.
+        this.#skills = this.#customViewport ? options.skills ?? null : null;
         const terminalCopy = terminal !== undefined || hasAsyncClipboardOutput();
         this.#responseCopy = this.#customViewport ? new ResponseCopyCoordinator({
             execute: responseCopy?.execute ?? (this.#copyExecutor = createResponseCopyExecutor({
@@ -160,7 +169,7 @@ export class OwnedUiSessionShell {
             onInterrupt: () => { void this.interrupt(); },
             onClear: () => { void this.clearOrExit(); },
             onExit: () => { void this.shutdown(); },
-            onModelSelect: () => this.showModelSelector(),
+            onModelSelect: () => this.#customViewport ? this.showModelsDialog() : this.showModelSelector(),
             onModelCycle: direction => { void this.cycleModel(direction); },
             onThinkingCycle: () => { void this.cycleThinkingLevel(); },
             onThinkingToggle: () => {
@@ -170,7 +179,7 @@ export class OwnedUiSessionShell {
             onMessageCopy: () => { void this.runWorkflow({ command: "copy", argument: "" }); },
             onFollowUp: () => { void this.queueFollowUp().catch(() => this.#reportSubmissionError()); },
             onDequeue: () => this.restoreQueuedInput(),
-            onEditorChange: () => { this.#editorRevision++; promptSuggestionController?.invalidate(); },
+            onEditorChange: () => { this.#editorRevision++; promptSuggestionController?.abortPending(); },
             onPromptSuggestionAccepted: () => promptSuggestionController?.accept(),
             onInputSurfaceChanged: () => {
                 promptSuggestionController?.invalidate();
@@ -207,6 +216,7 @@ export class OwnedUiSessionShell {
             },
             ...(pasteDiagnostics === undefined ? {} : { pasteDiagnostics: pasteDiagnostics }),
             ...(pastePreparation === undefined ? {} : { pastePreparation }),
+            skillsPresentation: () => this.#skills?.presentation() ?? "expand",
         }, {
             ...startup,
             resources: startup?.resources ?? shellResourceEntries(this.backend),
@@ -287,6 +297,15 @@ export class OwnedUiSessionShell {
         this.#unsubscribePromptSuggestions = promptSuggestionOptions === undefined
             ? () => { }
             : promptSuggestionOptions.onChange(enabled => this.#promptSuggestions?.setEnabled(enabled));
+        // Rationale: the same listener refreshes the menu for the A1 presentation choice and for the engine's
+        // skill-command registration, both of which the owned settings manager reports through one change.
+        this.#unsubscribeSkills = this.#skills === null ? () => { } : this.#skills.onChange(() => {
+            // Invariant: reinstalling drops extension provider wrappers, so an unrelated setting change leaves the list alone.
+            if (this.#disposed || this.#commandListSignature() === this.#installedCommandSignature)
+                return;
+            this.#installAutocompleteCommands();
+            this.runtime.requestRender();
+        });
         const initialPiSettings = this.backend.pinnedSettingsSnapshot();
         this.runtime.setHardwareCursor(initialPiSettings.showHardwareCursor);
         this.runtime.setClearOnShrink(initialPiSettings.clearOnShrink);
@@ -453,7 +472,7 @@ export class OwnedUiSessionShell {
             },
             finishLogin: () => this.#finishWorkflowLogin(),
         });
-        this.root.editor.setAutocompleteCommands(this.backend.workflowAutocompleteCommands());
+        this.#installAutocompleteCommands();
         this.#unsubscribe = this.backend.onEvent(event => {
             // Performance: a streamed chunk names one block, and touching only that block is what keeps the
             // cost of a chunk the same in a long session as in a new one. Everything else
@@ -669,7 +688,7 @@ export class OwnedUiSessionShell {
         }, displayInput);
     }
     async clearOrExit(now = Date.now()) {
-        this.#promptSuggestions?.invalidate();
+        this.#promptSuggestions?.abortPending();
         if (now - this.#lastClearTime < 500)
             return this.shutdown();
         this.root.editor.setText("");
@@ -834,6 +853,23 @@ export class OwnedUiSessionShell {
         this.root.setInputSurface(component);
         this.runtime.requestRender();
     }
+    /** The Skills dialog: a replacement input like the model selector, applying the chosen skill through the prompt path. */
+    showSkillsSelector(skills = this.#skillSummaries()) {
+        const close = () => {
+            this.root.setInputSurface(null);
+            this.runtime.requestRender();
+        };
+        const component = createPiShellSkillsSelector({
+            skills,
+            onSelect: name => {
+                close();
+                void this.#submitSkillPrompt(skillPrompt(name), skillPrompt(name)).catch(() => this.#reportSubmissionError());
+            },
+            onCancel: close,
+        });
+        this.root.setInputSurface(component);
+        this.runtime.requestRender();
+    }
     showModelSelector(initialSearchInput) {
         const context = this.backend.pinnedModelSelectorContext();
         const close = () => {
@@ -1139,6 +1175,10 @@ export class OwnedUiSessionShell {
             this.showScopedModelsSelector();
             return { outcome: "completed", diagnostic: null };
         }
+        if (request.command === "models" && request.selection === undefined) {
+            this.showModelsDialog(request.argument.trim() || undefined);
+            return { outcome: "completed", diagnostic: null };
+        }
         if (request.command === "model" && request.selection === undefined && request.confirmed === undefined && request.argument.trim().length === 0) {
             this.showModelSelector();
             return { outcome: "completed", diagnostic: null };
@@ -1247,10 +1287,10 @@ export class OwnedUiSessionShell {
         if (request.command === "reload" && result.outcome === "completed") {
             this.root.resetWorkflowPresentation();
             this.root.editor.reloadKeybindings();
-            this.root.editor.setAutocompleteCommands(this.backend.workflowAutocompleteCommands());
+            this.#installAutocompleteCommands();
         }
         this.root.appendWorkflowResult(result);
-        if (request.command === "model" && result.outcome === "completed")
+        if ((request.command === "model" || request.command === "models") && result.outcome === "completed")
             this.#showDaxnutsForActiveModel();
         this.runtime.requestRender();
         return workflowAdapterResult(result);
@@ -1357,6 +1397,90 @@ export class OwnedUiSessionShell {
             this.runtime.requestRender();
         }).finally(() => clearTimeout(timeout));
     }
+    // Invariant: bare A1 routes `models`; the comparison profile keeps the pinned `model`/`scoped-models` pair. Hidden routes are shared.
+    #isWorkflowRoute(value) {
+        return workflowCommandNames(this.#customViewport ? "bare" : "comparison").includes(value)
+            || PINNED_PI_HIDDEN_COMMAND_NAMES.includes(value);
+    }
+    /** The bare-A1 unified Models dialog: switch on Enter, scope on Space, persist on Ctrl+S, all through the engine. */
+    showModelsDialog(initialQuery) {
+        const context = this.backend.modelsContext();
+        const available = new Set(context.models.map(model => `${model.provider}/${model.id}`));
+        const savedScopeIds = context.persistedScopeIds.filter(id => available.has(id));
+        // Invariant: an explicit session scope wins; otherwise the dialog starts from what is persisted, never from "all rows scoped".
+        const scopeIds = context.sessionScopeIds.length > 0 ? context.sessionScopeIds : savedScopeIds;
+        let disposed = false;
+        let timedOut = false;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, 15_000);
+        const close = () => {
+            disposed = true;
+            clearTimeout(timeout);
+            controller.abort();
+            this.root.setInputSurface(null);
+            this.runtime.requestRender();
+        };
+        const dialog = createPiShellModelsDialog({
+            models: context.models,
+            activeModelId: context.activeModelId,
+            scopeIds,
+            savedScopeIds,
+            ...(initialQuery === undefined ? {} : { initialQuery }),
+            refreshStatus: "Refreshing model catalogs…",
+            requestRender: () => this.runtime.requestRender(),
+            onSelect: modelId => {
+                void this.runWorkflow({ command: "models", argument: "", selection: modelId }).then(result => {
+                    if (!disposed && result.outcome === "completed")
+                        close();
+                });
+            },
+            onScopeChange: ids => {
+                this.backend.setSessionModelScope(ids);
+                this.runtime.requestRender();
+            },
+            onSave: ids => {
+                try {
+                    this.backend.persistModelScope(ids);
+                }
+                catch (error) {
+                    this.root.appendWorkflowResult({ command: "models", outcome: "failed", message: error instanceof Error ? error.message : String(error) });
+                    this.runtime.requestRender();
+                    throw error;
+                }
+                this.root.appendWorkflowStatus("Model selection saved to settings");
+                this.runtime.requestRender();
+            },
+            onCancel: close,
+        });
+        const component = {
+            ...dialog,
+            dispose: () => {
+                disposed = true;
+                clearTimeout(timeout);
+                controller.abort();
+                dialog.dispose?.();
+            },
+        };
+        this.root.setInputSurface(component);
+        this.runtime.requestRender();
+        void this.backend.refreshModels(controller.signal).then(refreshed => {
+            if (disposed)
+                return;
+            component.updateModels(refreshed.models);
+            component.setRefreshStatus(timedOut ? "Model refresh timed out; showing cached models." : refreshed.status, timedOut ? "warning" : refreshed.statusKind);
+            this.runtime.requestRender();
+        }).catch(error => {
+            if (disposed)
+                return;
+            component.setRefreshStatus(timedOut
+                ? "Model refresh timed out; showing cached models."
+                : `Could not refresh model catalogs: ${error instanceof Error ? error.message : String(error)}`, "warning");
+            this.runtime.requestRender();
+        }).finally(() => clearTimeout(timeout));
+    }
     #showDaxnutsForActiveModel() {
         const model = this.view().activeModel;
         if (model?.providerId === "opencode" && model.modelId.toLowerCase().includes("kimi-k2.5")) {
@@ -1409,6 +1533,7 @@ export class OwnedUiSessionShell {
         attempt(() => this.#streamPresentation.dispose());
         attempt(() => this.#promptSuggestions?.dispose());
         attempt(() => this.#unsubscribePromptSuggestions());
+        attempt(() => this.#unsubscribeSkills());
         attempt(() => this.#unsubscribeSettings());
         let fullscreenExitText = "";
         attempt(() => {
@@ -1453,11 +1578,13 @@ export class OwnedUiSessionShell {
         if (!this.runtime.active || this.runtime.mode !== "fullscreen")
             return null;
         try {
-            const { enabled, effect, durationMs } = outro.snapshot();
-            if (!enabled)
+            if (!outro.snapshot().enabled)
                 return null;
             const viewport = this.runtime.viewport();
-            return { rows: this.#damageTerminal.presentedRows(), columns: viewport.columns, height: viewport.rows, settings: { effect, durationMs } };
+            return {
+                rows: this.#damageTerminal.presentedRows(), columns: viewport.columns, height: viewport.rows,
+                settings: { effect: QUIT_OUTRO_EFFECT, durationMs: QUIT_OUTRO_DURATION_MS },
+            };
         }
         catch {
             return null;
@@ -1550,13 +1677,31 @@ export class OwnedUiSessionShell {
         }
         this.root.update(view);
         this.#syncDialog(view.dialog);
+        this.#presentStartupChangelog(view);
         this.runtime.requestRender();
         for (const listener of this.#listeners)
             listener(view);
         return view;
     }
-    #openOwnedRoute(route) {
-        const surface = this.#routeHost?.open(route) ?? null;
+    // Rationale: the engine has already stored the current version when the diagnostic arrives, so the
+    // entries newer than the last acknowledged one exist only in its message; the screen shows exactly those.
+    #presentStartupChangelog(view) {
+        if (this.#startupChangelogHandled || !this.#customViewport || this.#routeHost === null)
+            return;
+        const diagnostic = view.diagnostics.find(candidate => candidate.code === "changelog-expanded");
+        // Invariant: a view synchronized before the runtime starts is not the moment of arrival; start() replays it.
+        if (diagnostic === undefined || !this.runtime.active)
+            return;
+        this.#startupChangelogHandled = true;
+        // Invariant: a dialog, selector, or owned screen already up keeps the screen; the hint stays in the feed.
+        if (this.#dialogHandle !== undefined || !this.root.usesDefaultInputSurface())
+            return;
+        if (!this.#routeHost.claims(CHANGELOG_ROUTE))
+            return;
+        this.#openOwnedRoute(CHANGELOG_ROUTE, { document: diagnostic.message });
+    }
+    #openOwnedRoute(route, input) {
+        const surface = this.#routeHost?.open(route, input) ?? null;
         if (surface === null)
             return { outcome: "failed", diagnostic: `route is unavailable: ${route}` };
         if (!this.runtime.active)
@@ -1683,6 +1828,9 @@ export class OwnedUiSessionShell {
         });
         this.#dialogId = dialog.id;
     }
+    hotkeysPresentation() {
+        return this.root.hotkeysPresentation();
+    }
     async #slashCommand(text) {
         const body = text.slice(1).trim();
         const separator = body.search(/\s/);
@@ -1690,8 +1838,15 @@ export class OwnedUiSessionShell {
         const argument = separator < 0 ? "" : body.slice(separator + 1).trimStart();
         if (this.#routeHost?.claims(name))
             return this.#openOwnedRoute(name);
-        if (isWorkflowRoute(name))
+        if (this.#isWorkflowRoute(name))
             return this.runWorkflow({ command: name, argument });
+        if (this.#skillsCollapsed()) {
+            if (name === SKILLS_COMMAND_NAME)
+                return this.#runSkillsCommand(text, argument);
+            const rewritten = rewriteSkillsTunnelSubmission(text);
+            if (rewritten !== text)
+                return this.#submitSkillPrompt(rewritten, text);
+        }
         // Compatibility: unknown slash input, prompt templates, skills, and extension commands remain Pi prompt input.
         this.#rememberInput(text, "slash");
         this.root.resumeViewportFollowing();
@@ -1702,6 +1857,51 @@ export class OwnedUiSessionShell {
             text,
         });
     }
+    #installAutocompleteCommands() {
+        this.root.editor.setAutocompleteCommands(this.backend.workflowAutocompleteCommands());
+        this.#installedCommandSignature = this.#commandListSignature();
+    }
+    #commandListSignature() {
+        return JSON.stringify([this.#skills?.presentation() ?? "expand", this.backend.disposed ? [] : this.backend.workflowAutocompleteCommands().map(command => command.name)]);
+    }
+    // Invariant: collapse applies only while the engine registers skill commands; otherwise there is nothing to collapse.
+    #skillsCollapsed() {
+        return this.#skills !== null && this.#skills.presentation() === "collapse"
+            && !this.backend.disposed && this.backend.pinnedSettingsSnapshot().enableSkillCommands;
+    }
+    #skillSummaries() {
+        return skillsFromCommands(this.backend.workflowAutocompleteCommands());
+    }
+    // Protocol: bare "/skills" opens the dialog, "/skills <name> [args]" applies directly, and an unknown name is a command outcome.
+    async #runSkillsCommand(text, argument) {
+        const skills = this.#skillSummaries();
+        const trimmed = argument.trim();
+        if (trimmed.length === 0) {
+            this.showSkillsSelector(skills);
+            return { outcome: "completed", diagnostic: null };
+        }
+        const separator = trimmed.search(/\s/u);
+        const token = separator < 0 ? trimmed : trimmed.slice(0, separator);
+        const skill = findSkillByArgument(skills, token);
+        if (skill === undefined) {
+            const message = "Unknown skill: " + token;
+            this.root.appendWorkflowMessage({ kind: "error", message });
+            this.runtime.requestRender();
+            return { outcome: "failed", diagnostic: message };
+        }
+        return this.#submitSkillPrompt(skillPrompt(skill.name, separator < 0 ? "" : trimmed.slice(separator + 1)), text);
+    }
+    // Rationale: the engine expands "/skill:<name> args" itself; history keeps the form the user typed so recall restores the invocation.
+    #submitSkillPrompt(prompt, typed) {
+        this.#rememberInput(typed, "slash");
+        this.root.resumeViewportFollowing();
+        return this.#execute({
+            type: this.view().lifecycle === "busy" ? "steer" : "prompt",
+            correlationId: this.#correlation("prompt-command"),
+            sessionId: this.backend.sessionId,
+            text: prompt,
+        });
+    }
     async #completeTreeSelection(entryId, skipSummaryPrompt) {
         let summarize = false;
         let customInstructions;
@@ -1911,7 +2111,6 @@ function workflowAdapterResult(result) {
 const INTERRUPT = "\u0003";
 const INTERRUPT_CHORD_MS = 1_500;
 const RELOAD_SURFACE_MIN_VISIBLE_MS = 400;
-function isWorkflowRoute(value) {
-    return PINNED_PI_WORKFLOW_COMMAND_NAMES.includes(value)
-        || PINNED_PI_HIDDEN_COMMAND_NAMES.includes(value);
-}
+// Rationale: the outro is not configurable; the switch only decides whether this plan plays.
+const QUIT_OUTRO_EFFECT = "fall";
+const QUIT_OUTRO_DURATION_MS = 800;

package/dist/composition/index.d.ts

@@ -1,2 +1,2 @@
 export { composeOwnedUi, composeOwnedUiApplication, type OwnedUiComposition, type OwnedUiCompositionOptions, } from "./owned-ui.js";
-export { createOwnedRouteHost } from "./settings-route-host.js";
+export { createOwnedRouteHost, type OwnedReferenceProviders, type OwnedReferenceRows } from "./settings-route-host.js";

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";