@timurproko/a1 0.1.8-dev.de7821a → 0.2.0

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

@@ -0,0 +1,43 @@
+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 ReferenceDocumentSection {
+    readonly title: string;
+    readonly rows: readonly string[];
+}
+export interface ReferenceDocumentProvider {
+    /** Flat rows for this width, or null while the document is not available yet. */
+    readonly rows?: (width: number) => readonly string[] | null;
+    /** Structured groups opt into shared Settings-style headers and pinning. */
+    readonly sections?: (width: number) => readonly ReferenceDocumentSection[] | null;
+    /** Settles once the selected content provider answers; absent when available at once. */
+    readonly ready?: Promise<void>;
+}
+export interface ReferenceScreenOptions {
+    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,279 @@
+import { GLOBAL_SCOPE, PLAIN_THEME, RAIL_COLUMNS, ShortcutRegistry, ScrollbarRails, assertNoShortcutConflicts, displayWidth, layoutList, padToWidth, renderGroupHeader, renderShortcutHints, 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: Ctrl+C remains 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");
+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 content = this.#content(contentWidth, theme);
+        const body = [];
+        let contentLength;
+        let viewportLength = bodyHeight;
+        if (content.kind === "sections") {
+            const layout = layoutList(content.rows, bodyHeight, this.#scroll, { topPadding: false });
+            this.#scroll = layout.scroll;
+            contentLength = content.rows.length;
+            viewportLength = layout.visible;
+            if (layout.stickyHeader !== undefined)
+                body.push(renderGroupHeader(layout.stickyHeader, contentWidth, theme));
+            for (const index of layout.rowIndexes)
+                body.push(this.#renderSectionRow(content.rows[index], contentWidth, theme));
+        }
+        else {
+            contentLength = content.rows.length;
+            const maxScroll = Math.max(0, content.rows.length - bodyHeight);
+            this.#scroll = Math.min(Math.max(0, this.#scroll), maxScroll);
+            for (let index = this.#scroll; index < this.#scroll + bodyHeight; index++) {
+                const row = content.rows[index] ?? "";
+                body.push(displayWidth(row) > contentWidth ? truncateToWidth(row, contentWidth) : row);
+            }
+        }
+        while (body.length < bodyHeight)
+            body.push("");
+        const now = Date.now();
+        // Rationale: every way of scrolling ends in this frame, so a moved document is noticed here
+        // once rather than at each wheel, drag, and key branch.
+        if (this.#renderedScroll !== undefined && this.#renderedScroll !== this.#scroll)
+            this.#noteScrollActivity(host, now);
+        this.#renderedScroll = this.#scroll;
+        const geometry = scrollbarGeometry({ contentLength, viewportHeight: viewportLength, 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: viewportLength }
+            : null;
+        const withRail = withScrollbarRail(body.slice(0, bodyHeight), geometry, contentWidth, theme, { presentation });
+        const hint = this.#interruptArmed
+            ? theme.fg("dim", " press ctrl+c again to exit a1")
+            : renderShortcutHints(REFERENCE_SCREEN_SHORTCUTS.hintEntries(SCOPE), theme, 1);
+        // Compatibility: the v2 reference screen frames its document between two border-coloured rules.
+        const rule = theme.fg("border", "─".repeat(rect.width));
+        // Invariant: dialog chrome shares the title's one-cell inset; document content keeps its own layout.
+        const frame = [rule, ...withRail, rule, padToWidth(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.
+    #content(width, theme) {
+        // Compatibility: one leading space, so the title lines up with the padded Markdown rows as in v2.
+        const title = ` ${theme.bold(theme.fg("accent", this.#title))}`;
+        if (this.#failure !== null)
+            return { kind: "flat", rows: [title, "", this.#failure] };
+        const cached = this.#cached;
+        if (cached !== null && cached.width === width)
+            return this.#withTitle(cached.content, title);
+        const sections = this.#document.sections?.(width);
+        if (sections === null)
+            return { kind: "flat", rows: [title, "", LOADING_NOTICE] };
+        if (sections !== undefined) {
+            const rows = [];
+            sections.forEach((section, sectionIndex) => {
+                if (sectionIndex > 0)
+                    rows.push({ kind: "spacer" });
+                const group = `section-${sectionIndex}`;
+                rows.push({ kind: "group", group, title: section.title });
+                for (const row of section.rows)
+                    rows.push({ kind: "note", group, text: row });
+            });
+            const content = { kind: "sections", rows };
+            this.#cached = { width, content };
+            return this.#withTitle(content, title);
+        }
+        const flat = this.#document.rows?.(width);
+        if (flat === null)
+            return { kind: "flat", rows: [title, "", LOADING_NOTICE] };
+        const content = { kind: "flat", rows: flat ?? [] };
+        this.#cached = { width, content };
+        return this.#withTitle(content, title);
+    }
+    #withTitle(content, title) {
+        if (content.kind === "flat")
+            return { kind: "flat", rows: [title, ...content.rows] };
+        return { kind: "sections", rows: [{ kind: "note", group: "", text: title }, { kind: "spacer" }, ...content.rows] };
+    }
+    #renderSectionRow(row, width, theme) {
+        if (row === undefined || row.kind === "spacer")
+            return "";
+        if (row.kind === "group")
+            return renderGroupHeader(row.title, width, theme);
+        const text = row.kind === "note" ? row.text : row.value;
+        return displayWidth(text) > width ? truncateToWidth(text, width) : text;
+    }
+    #scrollBy(distance) {
+        // Invariant: the upper clamp happens at render, where the body height and row count are known.
+        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/run.d.ts

@@ -0,0 +1,17 @@
+import type { OwnedUiApplicationPort } from "../../contracts/presentation/index.js";
+import type { OwnedSettingsManager } from "../../ui/settings/index.js";
+export interface OwnedUiRunOptions {
+    readonly application: OwnedUiApplicationPort;
+    /**
+     * Resolved once before the application starts, so every surface reads the same
+     * values for the life of the session. Omitted when the caller runs without settings.
+     */
+    readonly settings?: OwnedSettingsManager;
+}
+/**
+ * Completes the interactive executable only after runOwnedUi has restored its terminal.
+ * Extensions are untrusted process guests and can retain servers or timers after session
+ * shutdown, so assigning exitCode alone cannot guarantee return to the invoking shell.
+ */
+export declare function terminateOwnedUiProcess(code: number): Promise<never>;
+export declare function runOwnedUi(options: OwnedUiRunOptions): Promise<number>;

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

@@ -0,0 +1,64 @@
+import { markStartupPhase } from "../../foundation/startup/startup-runtime.js";
+import { boundedCleanup } from "../../foundation/terminal-cleanup/terminal-reset.js";
+const PROCESS_OUTPUT_FLUSH_TIMEOUT_MS = 250;
+/**
+ * Completes the interactive executable only after runOwnedUi has restored its terminal.
+ * Extensions are untrusted process guests and can retain servers or timers after session
+ * shutdown, so assigning exitCode alone cannot guarantee return to the invoking shell.
+ */
+export async function terminateOwnedUiProcess(code) {
+    process.exitCode = code;
+    await Promise.all([flushProcessOutput(process.stdout), flushProcessOutput(process.stderr)]);
+    return process.exit(code);
+}
+export async function runOwnedUi(options) {
+    const { application, settings } = options;
+    let failed = false;
+    let originalFailure;
+    try {
+        if (settings)
+            await settings.load();
+        application.start();
+        await application.flush();
+        await markStartupPhase(process.env, "first-input-ready-render");
+        if (!application.disposed)
+            await application.waitUntilStopped();
+        return 0;
+    }
+    catch (error) {
+        failed = true;
+        originalFailure = error;
+        throw error;
+    }
+    finally {
+        try {
+            await boundedCleanup(() => application.dispose(), 2500);
+        }
+        catch (error) {
+            if (failed)
+                throw new AggregateError([originalFailure, error], "Owned UI run and cleanup failed", { cause: originalFailure });
+            throw error;
+        }
+    }
+}
+async function flushProcessOutput(stream) {
+    if (stream.destroyed || !stream.writable)
+        return;
+    await new Promise(resolve => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            resolve();
+        };
+        const timeout = setTimeout(finish, PROCESS_OUTPUT_FLUSH_TIMEOUT_MS);
+        try {
+            stream.write("", finish);
+        }
+        catch {
+            finish();
+        }
+    });
+}

package/dist/features/owned-ui/session-fork-prompt.d.ts

@@ -0,0 +1,8 @@
+import type { Readable, Writable } from "node:stream";
+/** Pre-resource, line-mode confirmation matching Pi's cross-project CLI fork decision. */
+export declare function createConsoleSessionForkPrompt(options?: {
+    readonly input?: Readable;
+    readonly output?: Writable;
+}): (request: {
+    readonly sourceCwd: string;
+}) => Promise<boolean>;

package/dist/features/owned-ui/session-fork-prompt.js

@@ -0,0 +1,34 @@
+import { createInterface } from "node:readline";
+/** Pre-resource, line-mode confirmation matching Pi's cross-project CLI fork decision. */
+export function createConsoleSessionForkPrompt(options = {}) {
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    return async ({ sourceCwd }) => {
+        output.write(`Session found in different project: ${sourceCwd}\n`);
+        const wasFlowing = input.readableFlowing;
+        const readline = createInterface({ input, output });
+        try {
+            return await new Promise((resolve, reject) => {
+                const finish = (accepted) => { cleanup(); resolve(accepted); };
+                const cancel = () => finish(false);
+                const fail = (error) => { cleanup(); reject(error); };
+                const cleanup = () => {
+                    readline.off("close", cancel);
+                    readline.off("SIGINT", cancel);
+                    input.off("error", fail);
+                };
+                readline.once("close", cancel);
+                readline.once("SIGINT", cancel);
+                input.once("error", fail);
+                readline.question("Fork this session into current directory? [y/N] ", answer => {
+                    finish(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
+                });
+            });
+        }
+        finally {
+            readline.close();
+            if (wasFlowing !== true)
+                input.pause();
+        }
+    };
+}

package/dist/features/owned-ui/settings-app.d.ts

@@ -0,0 +1,21 @@
+import type { AppHostServices, UiApp } from "../../ui/apps/index.js";
+import { ShortcutRegistry, type PaneInputResult, type PaneMouseEvent, type PaneRect } from "../../ui/components/index.js";
+import type { OwnedSettingsManager } from "../../ui/settings/index.js";
+export { SETTINGS_APP_ID, SETTINGS_ROUTE } from "./settings-route.js";
+type Action = "move-up" | "move-down" | "block-up" | "block-down" | "first" | "last" | "page-up" | "page-down" | "previous-value" | "next-value" | "activate" | "open-filter" | "close" | "part-previous" | "part-next" | "part-change";
+export declare const SETTINGS_SHORTCUTS: ShortcutRegistry<Action>;
+/**
+ * The settings screen. Rows, sticky headers, scrolling, and the keymap come from
+ * the shared component layer; what belongs to settings is which sections exist,
+ * how a value is shown, and where an accepted change is routed.
+ */
+export declare class SettingsApp implements UiApp {
+    #private;
+    readonly id = "settings";
+    constructor(session: OwnedSettingsManager);
+    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;
+}