@timurproko/a1 0.1.8-dev.50ebb19 → 0.1.8-dev.510

package/dist/features/launch/index.d.ts

@@ -0,0 +1,12 @@
+export { resolveDevelopmentLaunchEnvironment } from "./development-launch.js";
+export type { DevelopmentLaunchEnvironment } from "./development-launch.js";
+export { PI_PROFILE_RESOURCE_DIRECTORIES, initializeProductProfile } from "./initialize-profile.js";
+export type { InitializedProfile } from "./initialize-profile.js";
+export { interactiveLaunchIntent, parseSessionSelection } from "./intent.js";
+export type { InteractiveLaunchIntent, LaunchIntent, LaunchProfileId, SessionSelection } from "./intent.js";
+export { configurationRootForProfile, resolveLaunchProfilePaths, resolvePromptHistoryDataDir } from "./profile-paths.js";
+export type { LaunchProfilePathOptions, LaunchProfilePaths } from "./profile-paths.js";
+export { prepareInteractiveLaunch } from "./prepare-launch.js";
+export type { PrepareInteractiveLaunchOptions, PreparedInteractiveLaunch } from "./prepare-launch.js";
+export { runSelectedInteractiveRuntime, selectInteractiveRuntime } from "./runtime-selection.js";
+export type { InteractiveRuntimeRunners, InteractiveRuntimeSelection, OwnedUiProfileId } from "./runtime-selection.js";

package/dist/features/launch/index.js

@@ -0,0 +1,6 @@
+export { resolveDevelopmentLaunchEnvironment } from "./development-launch.js";
+export { PI_PROFILE_RESOURCE_DIRECTORIES, initializeProductProfile } from "./initialize-profile.js";
+export { interactiveLaunchIntent, parseSessionSelection } from "./intent.js";
+export { configurationRootForProfile, resolveLaunchProfilePaths, resolvePromptHistoryDataDir } from "./profile-paths.js";
+export { prepareInteractiveLaunch } from "./prepare-launch.js";
+export { runSelectedInteractiveRuntime, selectInteractiveRuntime } from "./runtime-selection.js";

package/dist/features/launch/intent.d.ts

@@ -0,0 +1,12 @@
+import { type SessionSelection } from "../../foundation/lifecycle/index.js";
+import type { LaunchProfileId } from "../../foundation/lifecycle/index.js";
+export { parseSessionSelection } from "../../foundation/lifecycle/index.js";
+export type { SessionSelection } from "../../foundation/lifecycle/index.js";
+export type { LaunchProfileId } from "../../foundation/lifecycle/index.js";
+export interface InteractiveLaunchIntent {
+    readonly kind: "interactive";
+    readonly profileId: LaunchProfileId;
+    readonly sessionSelection?: SessionSelection;
+}
+export type LaunchIntent = InteractiveLaunchIntent;
+export declare function interactiveLaunchIntent(profileId: LaunchProfileId, sessionSelection?: SessionSelection): InteractiveLaunchIntent;

package/dist/features/launch/intent.js

@@ -0,0 +1,8 @@
+import { sessionSelectionArguments } from "../../foundation/lifecycle/index.js";
+export { parseSessionSelection } from "../../foundation/lifecycle/index.js";
+export function interactiveLaunchIntent(profileId, sessionSelection) {
+    if (sessionSelection !== undefined && profileId !== "a1")
+        throw new Error("session selection requires the normal A1 profile");
+    sessionSelectionArguments(sessionSelection);
+    return Object.freeze({ kind: "interactive", profileId, ...(sessionSelection === undefined ? {} : { sessionSelection }) });
+}

package/dist/features/launch/prepare-launch.d.ts

@@ -0,0 +1,11 @@
+import { type LaunchProfilePathOptions } from "./profile-paths.js";
+import { initializeProductProfile } from "./initialize-profile.js";
+import type { InteractiveLaunchIntent } from "./intent.js";
+export interface PreparedInteractiveLaunch {
+    readonly environment: NodeJS.ProcessEnv;
+    readonly configurationRoot: string | null;
+}
+export interface PrepareInteractiveLaunchOptions extends LaunchProfilePathOptions {
+    readonly initializeProfile?: typeof initializeProductProfile;
+}
+export declare function prepareInteractiveLaunch(intent: InteractiveLaunchIntent, environment?: NodeJS.ProcessEnv, options?: PrepareInteractiveLaunchOptions): Promise<PreparedInteractiveLaunch>;

package/dist/features/launch/prepare-launch.js

@@ -0,0 +1,14 @@
+import { configurationRootForProfile, resolveLaunchProfilePaths } from "./profile-paths.js";
+import { initializeProductProfile } from "./initialize-profile.js";
+export async function prepareInteractiveLaunch(intent, environment = process.env, options = {}) {
+    const paths = resolveLaunchProfilePaths({ ...options, environment });
+    const configurationRoot = configurationRootForProfile(intent.profileId, paths);
+    if (configurationRoot !== null)
+        await (options.initializeProfile ?? initializeProductProfile)(configurationRoot);
+    const childEnvironment = { ...environment };
+    if (configurationRoot === null)
+        delete childEnvironment.PI_CODING_AGENT_DIR;
+    else
+        childEnvironment.PI_CODING_AGENT_DIR = configurationRoot;
+    return Object.freeze({ environment: childEnvironment, configurationRoot });
+}

package/dist/features/launch/profile-paths.d.ts

@@ -0,0 +1,16 @@
+import type { LaunchProfileId } from "./intent.js";
+export interface LaunchProfilePaths {
+    readonly home: string;
+    readonly managedStateRoot: string;
+    readonly agentProfile: string;
+}
+export interface LaunchProfilePathOptions {
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly home?: string;
+    readonly readHome?: () => string;
+    readonly platform?: NodeJS.Platform;
+}
+export declare function resolveLaunchProfilePaths(options?: LaunchProfilePathOptions): LaunchProfilePaths;
+/** Select history storage without relocating control state or probing former stores. */
+export declare function resolvePromptHistoryDataDir(options?: LaunchProfilePathOptions): string;
+export declare function configurationRootForProfile(profileId: LaunchProfileId, paths: LaunchProfilePaths): string | null;

package/dist/features/launch/profile-paths.js

@@ -0,0 +1,36 @@
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { resolveProductPaths } from "../../foundation/lifecycle/paths.js";
+export function resolveLaunchProfilePaths(options = {}) {
+    const environment = options.environment ?? process.env;
+    const path = options.platform === "win32" || (options.platform === undefined && process.platform === "win32") ? win32 : posix;
+    const selectedHome = options.home ?? environment[PRODUCT_IDENTITY.environment.profileHome] ?? options.readHome?.() ?? homedir();
+    const home = validateAbsolutePath(selectedHome, "effective user home", path);
+    const agentProfile = path.resolve(home, PRODUCT_IDENTITY.state.piAgentProfile);
+    return Object.freeze({
+        home,
+        managedStateRoot: path.dirname(agentProfile),
+        agentProfile,
+    });
+}
+/** Select history storage without relocating control state or probing former stores. */
+export function resolvePromptHistoryDataDir(options = {}) {
+    const environment = options.environment ?? process.env;
+    const platform = options.platform ?? process.platform;
+    if (environment[PRODUCT_IDENTITY.environment.dataDir] !== undefined) {
+        return resolveProductPaths(environment, platform).dataDir;
+    }
+    const path = platform === "win32" ? win32 : posix;
+    return path.join(resolveLaunchProfilePaths(options).managedStateRoot, "data");
+}
+export function configurationRootForProfile(profileId, paths) {
+    return profileId === "a1" ? paths.agentProfile : null;
+}
+function validateAbsolutePath(value, name, path) {
+    if (value.length === 0 || value.includes("\0"))
+        throw new TypeError(`${name} is invalid`);
+    if (!path.isAbsolute(value))
+        throw new TypeError(`${name} must be absolute`);
+    return path.resolve(value);
+}

package/dist/features/launch/runtime-selection.d.ts

@@ -0,0 +1,16 @@
+import { type LaunchProfileId } from "../../foundation/lifecycle/model.js";
+/**
+ * Both interactive commands use the owned composition. Bare A1 enables product
+ * surfaces; the Pi comparison command withholds them and reads Pi's own profile.
+ */
+export type OwnedUiProfileId = LaunchProfileId;
+export interface InteractiveRuntimeSelection {
+    readonly kind: "owned-ui";
+    readonly profileId: OwnedUiProfileId;
+    readonly ownedSurfaces: "on" | "off";
+}
+export interface InteractiveRuntimeRunners {
+    readonly ownedUi: (profileId: OwnedUiProfileId, ownedSurfaces: "on" | "off") => Promise<number>;
+}
+export declare function selectInteractiveRuntime(profileId: string): InteractiveRuntimeSelection;
+export declare function runSelectedInteractiveRuntime(profileId: string, runners: InteractiveRuntimeRunners): Promise<number>;

package/dist/features/launch/runtime-selection.js

@@ -0,0 +1,13 @@
+import { assertLaunchProfileId } from "../../foundation/lifecycle/model.js";
+export function selectInteractiveRuntime(profileId) {
+    assertLaunchProfileId(profileId);
+    return Object.freeze({
+        kind: "owned-ui",
+        profileId,
+        ownedSurfaces: profileId === "a1" ? "on" : "off",
+    });
+}
+export async function runSelectedInteractiveRuntime(profileId, runners) {
+    const selection = selectInteractiveRuntime(profileId);
+    return await runners.ownedUi(selection.profileId, selection.ownedSurfaces);
+}

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

@@ -0,0 +1,9 @@
+export { runOwnedUi, terminateOwnedUiProcess } from "./run.js";
+export type { OwnedUiRunOptions } from "./run.js";
+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

@@ -0,0 +1,6 @@
+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/project-trust-prompt.d.ts

@@ -0,0 +1,25 @@
+import type { Readable, Writable } from "node:stream";
+export interface OwnedProjectTrustPromptRequest {
+    readonly cwd: string;
+    readonly defaultDecision: "ask" | "always" | "never";
+}
+export type OwnedProjectTrustPrompt = (request: OwnedProjectTrustPromptRequest) => Promise<boolean | null>;
+interface RawTtyInput extends Readable {
+    readonly isTTY?: boolean;
+    readonly isRaw?: boolean;
+    setRawMode?(enabled: boolean): this;
+}
+export interface ConsoleProjectTrustPromptOptions {
+    readonly input?: RawTtyInput;
+    readonly output?: Writable & {
+        readonly isTTY?: boolean;
+        readonly columns?: number;
+    };
+}
+/**
+ * Pre-resource startup selector. It uses only fixed product wording and terminal
+ * controls: no project setting, theme, extension, prompt, package, or skill is
+ * consulted before the trust result exists.
+ */
+export declare function createConsoleProjectTrustPrompt(options?: ConsoleProjectTrustPromptOptions): OwnedProjectTrustPrompt;
+export {};

package/dist/features/owned-ui/project-trust-prompt.js

@@ -0,0 +1,149 @@
+const ENTER_ALTERNATE_SCREEN = "\u001b[?1049h";
+const LEAVE_ALTERNATE_SCREEN = "\u001b[?1049l";
+const HIDE_CURSOR = "\u001b[?25l";
+const SHOW_CURSOR = "\u001b[?25h";
+const CLEAR_HOME = "\u001b[2J\u001b[H";
+const ACCENT = "\u001b[38;2;138;190;183m";
+const MUTED = "\u001b[38;2;128;128;128m";
+const DIM = "\u001b[38;2;102;102;102m";
+const RESET_FG = "\u001b[39m";
+const BOLD = "\u001b[1m";
+const RESET_BOLD = "\u001b[22m";
+/**
+ * Pre-resource startup selector. It uses only fixed product wording and terminal
+ * controls: no project setting, theme, extension, prompt, package, or skill is
+ * consulted before the trust result exists.
+ */
+export function createConsoleProjectTrustPrompt(options = {}) {
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    return async ({ cwd }) => {
+        if (input.isTTY !== true || output.isTTY !== true) {
+            throw new Error("an interactive terminal is unavailable");
+        }
+        const wasRaw = input.isRaw === true;
+        let selected = 0;
+        let restored = false;
+        const restore = () => {
+            if (restored)
+                return;
+            restored = true;
+            input.setRawMode?.(wasRaw);
+            output.write(`${CLEAR_HOME}${SHOW_CURSOR}${LEAVE_ALTERNATE_SCREEN}`);
+        };
+        const render = () => {
+            const width = Math.max(20, output.columns ?? 80);
+            const lines = [
+                `${BOLD}${ACCENT}Trust project folder?${RESET_FG}${RESET_BOLD}`,
+                cwd,
+                "",
+                "This allows a1 to load project settings and resources, install missing project packages, and execute project extensions.",
+                "",
+                optionRow("Trust", selected === 0),
+                optionRow("Do not trust", selected === 1),
+                "",
+                `${DIM}  ↑/↓ to navigate · Enter to select · Esc to cancel${RESET_FG}`,
+            ];
+            output.write(`${CLEAR_HOME}${lines.map(line => clipAnsiSafe(line, width)).join("\n")}`);
+        };
+        try {
+            output.write(`${ENTER_ALTERNATE_SCREEN}${HIDE_CURSOR}`);
+            input.setRawMode?.(true);
+            render();
+            return await new Promise((resolve, reject) => {
+                let settled = false;
+                const finish = (value) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    restore();
+                    resolve(value);
+                };
+                const fail = (error) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    restore();
+                    reject(error);
+                };
+                const onData = (chunk) => {
+                    const data = chunk.toString();
+                    for (let index = 0; index < data.length;) {
+                        if (data.startsWith("\u001b[A", index)) {
+                            selected = 0;
+                            index += 3;
+                            render();
+                            continue;
+                        }
+                        if (data.startsWith("\u001b[B", index) || data[index] === "\t") {
+                            selected = selected === 0 ? 1 : 0;
+                            index += data[index] === "\t" ? 1 : 3;
+                            render();
+                            continue;
+                        }
+                        const key = data[index] ?? "";
+                        index += 1;
+                        if (key === "\r" || key === "\n") {
+                            finish(selected === 0);
+                            return;
+                        }
+                        if (key === "\u001b" || key === "\u0003") {
+                            finish(null);
+                            return;
+                        }
+                        // Compatibility: retain y/n aliases for terminals or automation that cannot send
+                        // navigation keys; the visible interaction remains selector-first.
+                        if (key === "y" || key === "Y") {
+                            finish(true);
+                            return;
+                        }
+                        if (key === "n" || key === "N") {
+                            finish(false);
+                            return;
+                        }
+                    }
+                };
+                const onEnd = () => finish(null);
+                const onError = (error) => fail(error);
+                const cleanup = () => {
+                    input.off("data", onData);
+                    input.off("end", onEnd);
+                    input.off("error", onError);
+                };
+                input.on("data", onData);
+                input.once("end", onEnd);
+                input.once("error", onError);
+                input.resume();
+            });
+        }
+        finally {
+            restore();
+        }
+    };
+}
+function optionRow(label, selected) {
+    return selected
+        ? `${ACCENT}→ ${label}${RESET_FG}`
+        : `  ${label}`;
+}
+/** Avoid replaying or manufacturing control payloads while keeping fixed SGR. */
+function clipAnsiSafe(line, width) {
+    let visible = 0;
+    let output = "";
+    for (let index = 0; index < line.length && visible < width;) {
+        if (line[index] === "\u001b") {
+            const match = line.slice(index).match(/^\u001b\[[0-9;:]*m/);
+            if (match !== null) {
+                output += match[0];
+                index += match[0].length;
+                continue;
+            }
+        }
+        output += line[index];
+        index += 1;
+        visible += 1;
+    }
+    return `${output}${RESET_FG}${RESET_BOLD}`;
+}

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;
+    }
+}