@timurproko/a1 0.2.7-dev.1252 → 0.2.7-dev.1264

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

@@ -44,7 +44,6 @@ const SLOT_IDS = new Set([
     "overlay",
     "layout",
 ]);
-const OUTCOMES = new Set(["accepted", "rejected", "completed", "failed", "timed-out", "cancelled"]);
 const FOCUSED_REGIONS = new Set(["transcript", "editor", "dialog", "overlay", "status"]);
 const DIALOG_KINDS = new Set(["choice", "editor", "settings", "confirmation"]);
 const OVERLAY_PLACEMENTS = new Set(["bottom", "center"]);
@@ -94,89 +93,7 @@ export function assertOwnedUiCommand(command) {
             throw new TypeError("owned-UI command type is unknown");
     }
 }
-export function assertOwnedUiEvent(event) {
-    assertId(event.sessionId, "owned-UI event session id");
-    assertNonNegativeInteger(event.sequence, "owned-UI event sequence");
-    switch (event.type) {
-        case "session-lifecycle":
-            assertEnum(event.lifecycle, LIFECYCLES, "owned-UI lifecycle");
-            assertOptionalText(event.reason, "owned-UI lifecycle reason", MAX_MESSAGE_LENGTH);
-            return;
-        case "session-view":
-            assertOwnedUiSessionViewModel(event.view);
-            assertViewSession(event.view, event.sessionId);
-            return;
-        case "transcript-block":
-            assertOwnedUiTranscriptBlock(event.block);
-            return;
-        case "assistant-message-completed":
-            assertNonNegativeInteger(event.sessionGeneration, "owned-UI assistant response session generation");
-            assertNonNegativeInteger(event.runSequence, "owned-UI assistant response run sequence");
-            assertNonNegativeInteger(event.responseSequence, "owned-UI assistant response sequence");
-            assertNonNegativeInteger(event.assistantMessageCount, "owned-UI assistant response count");
-            if (event.model !== null)
-                assertOwnedUiModelInfo(event.model);
-            if (typeof event.successful !== "boolean")
-                throw new TypeError("owned-UI assistant response success state is invalid");
-            assertOptionalText(event.stopReason, "owned-UI assistant response stop reason", MAX_LABEL_LENGTH);
-            if (typeof event.toolContinuation !== "boolean")
-                throw new TypeError("owned-UI assistant response tool-continuation state is invalid");
-            return;
-        case "agent-run-started":
-            return;
-        case "agent-run-settled":
-            assertNonNegativeInteger(event.sessionGeneration, "owned-UI settlement session generation");
-            assertNonNegativeInteger(event.runSequence, "owned-UI settlement run sequence");
-            assertNonNegativeInteger(event.responseSequence, "owned-UI settlement response sequence");
-            assertNonNegativeInteger(event.assistantMessageCount, "owned-UI settlement assistant message count");
-            if (event.model !== null)
-                assertOwnedUiModelInfo(event.model);
-            if (typeof event.successful !== "boolean")
-                throw new TypeError("owned-UI settlement success state is invalid");
-            if (event.stopReason === undefined)
-                throw new TypeError("owned-UI settlement stop reason is missing");
-            assertOptionalText(event.stopReason, "owned-UI settlement stop reason", MAX_LABEL_LENGTH);
-            if (typeof event.toolContinuation !== "boolean")
-                throw new TypeError("owned-UI settlement tool-continuation state is invalid");
-            if (typeof event.aborted !== "boolean")
-                throw new TypeError("owned-UI settlement aborted state is invalid");
-            return;
-        case "editor-state":
-            assertOwnedUiEditorState(event.editor);
-            return;
-        case "status":
-            assertOwnedUiStatusView(event.status);
-            return;
-        case "dialog":
-            if (event.dialog !== null)
-                assertOwnedUiDialog(event.dialog);
-            return;
-        case "overlay":
-            if (event.overlay !== null)
-                assertOwnedUiOverlay(event.overlay);
-            return;
-        case "command-outcome":
-            assertId(event.correlationId, "owned-UI outcome correlation id");
-            assertEnum(event.outcome, OUTCOMES, "owned-UI command outcome");
-            assertOptionalText(event.diagnostic, "owned-UI command diagnostic", MAX_MESSAGE_LENGTH);
-            return;
-        case "customization":
-            assertCollection(event.customizations, "owned-UI customizations", MAX_CUSTOMIZATIONS);
-            assertUniqueCustomizations(event.customizations);
-            for (const customization of event.customizations)
-                assertOwnedUiCustomization(customization);
-            return;
-        case "terminal-surface":
-            assertOwnedUiTerminalSurface(event.surface);
-            return;
-        case "diagnostic":
-            assertOwnedUiDiagnostics(event.diagnostic);
-            return;
-        default:
-            throw new TypeError("owned-UI event type is unknown");
-    }
-}
-export function assertOwnedUiPromptSuggestionIdentity(identity) {
+function assertOwnedUiPromptSuggestionIdentity(identity) {
     assertId(identity.sessionId, "prompt-suggestion session id");
     assertNonNegativeInteger(identity.sessionGeneration, "prompt-suggestion session generation");
     assertNonNegativeInteger(identity.runSequence, "prompt-suggestion run sequence");
@@ -202,20 +119,7 @@ export function assertOwnedUiPromptSuggestionResult(result) {
         throw new TypeError("prompt-suggestion outcome is invalid");
     }
 }
-export function assertOwnedUiPromptSuggestionState(state) {
-    if (state.status === "idle")
-        return;
-    if (state.status !== "generating" && state.status !== "prepared" && state.status !== "available") {
-        throw new TypeError("prompt-suggestion state is invalid");
-    }
-    assertOwnedUiPromptSuggestionIdentity(state.identity);
-    if (state.status === "generating" && typeof state.settled !== "boolean") {
-        throw new TypeError("prompt-suggestion settlement state is invalid");
-    }
-    if (state.status === "prepared" || state.status === "available")
-        assertPromptSuggestionText(state.text, false);
-}
-export function assertOwnedUiSessionViewModel(view) {
+function assertOwnedUiSessionViewModel(view) {
     if (view.contractVersion !== OWNED_UI_CONTRACT_VERSION) {
         throw new TypeError("unsupported owned-UI contract version");
     }
@@ -270,7 +174,7 @@ export function assertOwnedUiSnapshot(snapshot) {
     assertViewSession(snapshot.view, snapshot.sessionId);
     assertJsonBytes(snapshot, "owned-UI snapshot", MAX_SESSION_VIEW_BYTES);
 }
-export function assertOwnedUiCustomization(customization) {
+function assertOwnedUiCustomization(customization) {
     assertId(customization.id, "owned-UI customization id");
     assertEnum(customization.slot, SLOT_IDS, "owned-UI customization slot");
     assertIntegerInRange(customization.version, 1, Number.MAX_SAFE_INTEGER, "owned-UI customization version");
@@ -278,7 +182,7 @@ export function assertOwnedUiCustomization(customization) {
     assertBoundedText(customization.label, "owned-UI customization label", MAX_LABEL_LENGTH);
     assertJsonObject(customization.payload, "owned-UI customization payload", MAX_PAYLOAD_BYTES);
 }
-export function assertOwnedUiTranscriptBlock(block) {
+function assertOwnedUiTranscriptBlock(block) {
     assertId(block.id, "owned-UI transcript block id");
     assertEnum(block.kind, BLOCK_KINDS, "owned-UI transcript block kind");
     assertEnum(block.status, BLOCK_STATUSES, "owned-UI transcript block status");
@@ -337,7 +241,7 @@ export function assertOwnedUiTranscriptBlock(block) {
         }
     }
 }
-export function assertOwnedUiEditorState(editor) {
+function assertOwnedUiEditorState(editor) {
     assertPossiblyEmptyText(editor.text, "owned-UI editor text", MAX_TEXT_BYTES);
     assertCollection(editor.queuedSubmissions, "owned-UI queued submissions", MAX_QUEUE);
     let queuedBytes = 0;
@@ -356,7 +260,7 @@ export function assertOwnedUiEditorState(editor) {
         assertIntegerInRange(editor.selection.end, editor.selection.start, editor.text.length, "owned-UI selection end");
     }
 }
-export function assertOwnedUiStatusView(status) {
+function assertOwnedUiStatusView(status) {
     assertBoundedText(status.title, "owned-UI status title", MAX_LABEL_LENGTH);
     assertOptionalText(status.workingMessage, "owned-UI working message", MAX_MESSAGE_LENGTH);
     if (status.workingProgress !== undefined && status.workingProgress !== null) {
@@ -427,14 +331,14 @@ export function assertOwnedUiStatusView(status) {
         }
     }
 }
-export function assertOwnedUiTerminalSurface(surface) {
+function assertOwnedUiTerminalSurface(surface) {
     assertIntegerInRange(surface.columns, 20, 500, "owned-UI terminal columns");
     assertIntegerInRange(surface.rows, 8, 300, "owned-UI terminal rows");
     assertEnum(surface.focusedRegion, FOCUSED_REGIONS, "owned-UI focused region");
     if (typeof surface.hardwareCursor !== "boolean")
         throw new TypeError("owned-UI hardware-cursor state is invalid");
 }
-export function assertOwnedUiDiagnostics(diagnostic) {
+function assertOwnedUiDiagnostics(diagnostic) {
     assertNonNegativeInteger(diagnostic.sequence, "owned-UI diagnostic sequence");
     assertId(diagnostic.code, "owned-UI diagnostic code");
     assertEnum(diagnostic.severity, SEVERITIES, "owned-UI diagnostic severity");

package/dist/contracts/presentation/component.d.ts

@@ -0,0 +1,17 @@
+export interface PresentationComponentPort {
+    render(width: number): readonly string[];
+    invalidate(): void;
+    handleInput?(data: string): void;
+    setFocused?(focused: boolean): void;
+    dispose?(): void;
+}
+/** A painted input surface in terminal coordinates (one-based, inclusive bounds). */
+export interface PresentationPointerSurface {
+    readonly component: PresentationComponentPort;
+    readonly columnStart: number;
+    readonly columnEnd: number;
+    readonly rowStart: number;
+    readonly rowEnd: number;
+}
+/** Compares only geometry and ownership, never animation content or transcript position. */
+export declare function samePointerSurfaces(a: readonly PresentationPointerSurface[], b: readonly PresentationPointerSurface[]): boolean;

package/dist/contracts/presentation/component.js

@@ -0,0 +1,8 @@
+/** Compares only geometry and ownership, never animation content or transcript position. */
+export function samePointerSurfaces(a, b) {
+    return a.length === b.length && a.every((surface, index) => {
+        const other = b[index];
+        return surface.component === other.component && surface.columnStart === other.columnStart
+            && surface.columnEnd === other.columnEnd && surface.rowStart === other.rowStart && surface.rowEnd === other.rowEnd;
+    });
+}

package/dist/contracts/presentation/index.d.ts

@@ -1,3 +1,9 @@
+import type { PresentationComponentPort } from "./component.js";
+export type { PresentationComponentPort, PresentationPointerSurface } from "./component.js";
+export { samePointerSurfaces } from "./component.js";
+export type { CanvasBackgroundStyle, ShellPresentationPorts, ThemeSource, UiTheme, UiThemeBackground, UiThemeToken } from "./theme.js";
+export type { TerminalComponentPort, TerminalDamageDecision, TerminalDamageDecisionReason, TerminalDamageFrameDescriptor, TerminalDamageFrameSafety, TerminalDamageOptions, TerminalDamagePort, TerminalHyperlinkInspection, TerminalInputCoordinationDecision, TerminalInputCoordinationScheduler, TerminalInputDiagnosticsEvent, TerminalInputDiagnosticsPhase, TerminalInputListener, TerminalInputListenerResult, TerminalInputSurfaceKind, TerminalLayoutEntry, TerminalLayoutNode, TerminalOverlayAnchor, TerminalOverlayHandle, TerminalOverlayMargin, TerminalOverlayOptions, TerminalOverlayUnfocusOptions, TerminalPointerSurface, TerminalPort, TerminalPreInputListener, TerminalProgramStatus, TerminalRuntimeFactory, TerminalRuntimeOptions, TerminalRuntimePort, TerminalRuntimeState, TerminalSizeValue, TerminalStopOptions, TerminalViewport, TerminalWheelScrollLines, } from "./terminal.js";
+export { SHARED_PROGRESS_ACCENT_ANSI, SHARED_PROGRESS_PALETTE } from "./progress-palette.generated.js";
 export type PresentationRuntimeState = "idle" | "running" | "stopping" | "stopped" | "failed";
 export interface SemanticShortcutHint {
     readonly key?: string;
@@ -33,21 +39,6 @@ export interface ShortcutHintRoles {
 export declare function displayShortcutKeyLabel(label: string): string;
 /** Renders the canonical semantic shortcut row independently of either presentation framework. */
 export declare function renderSemanticShortcutHints(entries: readonly SemanticShortcutHint[], roles: ShortcutHintRoles, indent?: number, separator?: string): string;
-export interface PresentationComponentPort {
-    render(width: number): readonly string[];
-    invalidate(): void;
-    handleInput?(data: string): void;
-    setFocused?(focused: boolean): void;
-    dispose?(): void;
-}
-/** A painted input surface in terminal coordinates (one-based, inclusive bounds). */
-export interface PresentationPointerSurface {
-    readonly component: PresentationComponentPort;
-    readonly columnStart: number;
-    readonly columnEnd: number;
-    readonly rowStart: number;
-    readonly rowEnd: number;
-}
 export interface PresentationEditorPort extends PresentationComponentPort {
     getText(): string;
     setText(text: string): void;

package/dist/contracts/presentation/index.js

@@ -1,3 +1,5 @@
+export { samePointerSurfaces } from "./component.js";
+export { SHARED_PROGRESS_ACCENT_ANSI, SHARED_PROGRESS_PALETTE } from "./progress-palette.generated.js";
 /** Canonical dismissal guidance for every A1-rendered dialog surface. */
 export const DIALOG_CLOSE_SHORTCUT_HINT = Object.freeze({ key: "esc", action: "close" });
 /** Canonical return guidance for a nested step within a dialog surface. */

package/dist/contracts/presentation/terminal.d.ts

@@ -0,0 +1,284 @@
+import type { PresentationComponentPort, PresentationPointerSurface } from "./component.js";
+/** A program-status report for terminals that show one (OSC 9;4 style); `clear` removes it. */
+export interface TerminalProgramStatus {
+    state: "idle" | "working" | "blocked" | "done" | "error" | "clear";
+    app?: string;
+    kind?: "permission" | "question" | "auth";
+}
+/** Lines one wheel notch scrolls, or `auto` to follow wheel velocity. */
+export type TerminalWheelScrollLines = number | "auto";
+/** Whether queued input may be applied immediately or must wait for the current presentation. */
+export type TerminalInputCoordinationDecision = "safe" | "barrier";
+/** What kind of surface owns the keyboard when input arrives. */
+export type TerminalInputSurfaceKind = "editor" | "owned" | "opaque";
+export interface TerminalInputCoordinationScheduler {
+    scheduleImmediate(callback: () => void): ReturnType<typeof setImmediate>;
+    cancelImmediate(handle: ReturnType<typeof setImmediate>): void;
+}
+export type TerminalRuntimeState = "idle" | "running" | "stopping" | "stopped" | "failed";
+export interface TerminalViewport {
+    readonly columns: number;
+    readonly rows: number;
+}
+export type TerminalPointerSurface = PresentationPointerSurface;
+export interface TerminalComponentPort extends PresentationComponentPort {
+    readonly wantsKeyRelease?: boolean;
+}
+export interface TerminalPort {
+    start(onInput: (data: string) => void, onResize: () => void): void;
+    stop(): void;
+    drainInput(maxMs?: number, idleMs?: number): Promise<void>;
+    write(data: string): void;
+    readonly columns: number;
+    readonly rows: number;
+    readonly kittyProtocolActive: boolean;
+    moveBy(lines: number): void;
+    hideCursor(): void;
+    showCursor(): void;
+    clearLine(): void;
+    clearFromCursor(): void;
+    clearScreen(): void;
+    setTitle(title: string): void;
+    setProgress(active: boolean): void;
+    /** Optional for neutral test/decorator ports; the vendor adapter always supplies it. */
+    setProgramStatus?(status: TerminalProgramStatus): void;
+    /**
+     * Optional synchronous last-resort mode restore that the runtime invokes from a process `exit` handler when
+     * `stop()` did not run; the runtime adapter binds it to the undecorated terminal, so decorators need not forward it.
+     */
+    restoreOnExit?(before: string, after: string): void;
+}
+export type TerminalSizeValue = number | `${number}%`;
+export type TerminalOverlayAnchor = "center" | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-center" | "bottom-center" | "left-center" | "right-center";
+export interface TerminalOverlayMargin {
+    readonly top?: number;
+    readonly right?: number;
+    readonly bottom?: number;
+    readonly left?: number;
+}
+export interface TerminalOverlayOptions {
+    readonly width?: TerminalSizeValue;
+    readonly minWidth?: number;
+    readonly maxHeight?: TerminalSizeValue;
+    readonly anchor?: TerminalOverlayAnchor;
+    readonly offsetX?: number;
+    readonly offsetY?: number;
+    readonly row?: TerminalSizeValue;
+    readonly col?: TerminalSizeValue;
+    readonly margin?: TerminalOverlayMargin | number;
+    readonly visible?: (columns: number, rows: number) => boolean;
+    readonly nonCapturing?: boolean;
+    /** A1-owned input scheduling declaration; omitted extension overlays fail closed. */
+    readonly inputCoordination?: Exclude<TerminalInputSurfaceKind, "editor">;
+}
+export interface TerminalOverlayUnfocusOptions {
+    readonly target: TerminalComponentPort | null;
+}
+export interface TerminalOverlayHandle {
+    hide(): void;
+    setHidden(hidden: boolean): void;
+    isHidden(): boolean;
+    focus(): void;
+    unfocus(options?: TerminalOverlayUnfocusOptions): void;
+    isFocused(): boolean;
+    /** The most recently rendered terminal-relative rectangle of a visible overlay. */
+    getBounds(): {
+        readonly row: number;
+        readonly col: number;
+        readonly width: number;
+        readonly height: number;
+    } | undefined;
+}
+export interface TerminalInputListenerResult {
+    readonly consume?: boolean;
+    readonly data?: string;
+}
+export type TerminalInputListener = (data: string) => TerminalInputListenerResult | undefined;
+/** Runs at the terminal bridge before the runtime receives physical input. */
+export type TerminalPreInputListener = TerminalInputListener;
+export interface TerminalLayoutEntry {
+    readonly node: TerminalLayoutNode;
+    readonly basis?: number | "auto";
+    readonly grow?: number;
+    readonly shrink?: number;
+    readonly minSize?: number;
+    readonly maxSize?: number;
+    readonly visible?: (viewport: TerminalViewport) => boolean;
+}
+export type TerminalLayoutNode = {
+    readonly type: "component";
+    readonly component: TerminalComponentPort;
+} | {
+    readonly type: "stack";
+    readonly direction: "vertical" | "horizontal";
+    readonly children: readonly TerminalLayoutEntry[];
+    readonly gap?: number;
+    readonly align?: "stretch" | "start" | "center" | "end";
+} | {
+    readonly type: "scroll";
+    readonly id: string;
+    readonly child: TerminalLayoutNode;
+    readonly follow?: "none" | "end";
+    readonly primary?: boolean;
+    readonly overscroll?: "chain" | "contain";
+    readonly scrollbar?: "hidden" | "auto" | "always";
+    /** Styles the scrollbar track; the pinned runtime draws it as foreground text. */
+    readonly scrollbarTrackStyle?: (text: string) => string;
+    /** Styles the scrollbar thumb; the pinned runtime draws it as foreground text. */
+    readonly scrollbarThumbStyle?: (text: string) => string;
+    readonly scrollbarHideDelayMs?: number;
+};
+export type TerminalInputDiagnosticsPhase = "receipt" | "semantic-start" | "semantic-end" | "composition-start" | "composition-end" | "write-start" | "write-end";
+export interface TerminalInputDiagnosticsEvent {
+    readonly phase: TerminalInputDiagnosticsPhase;
+    readonly revision: number;
+    readonly atMs: number;
+    readonly pendingDepth: number;
+    readonly pendingPresentationDepth: 0 | 1;
+    readonly appliedRevision: number;
+}
+export interface TerminalRuntimeOptions {
+    readonly root: TerminalComponentPort;
+    /** Bare viewport only: painted overlays in back-to-front order; null while geometry is stale. */
+    readonly onOverlayGeometry?: (surfaces: readonly TerminalPointerSurface[] | null) => void;
+    readonly mode?: "regular" | "fullscreen";
+    readonly layoutRoot?: TerminalLayoutNode;
+    readonly terminal?: TerminalPort;
+    /** A1-owned public-boundary decorator; comparison paths omit it. */
+    readonly decorateTerminal?: (terminal: TerminalPort) => TerminalPort;
+    /** Bare-custom-viewport scheduling policy; comparison paths omit it. */
+    readonly inputCoordination?: {
+        readonly classify: (data: string, focusedOverlay?: Exclude<TerminalInputSurfaceKind, "editor">) => TerminalInputCoordinationDecision;
+        readonly onReceipt?: () => void;
+        readonly scheduler?: TerminalInputCoordinationScheduler;
+    };
+    /** Optional bounded evidence hook. Production composition omits it. */
+    readonly inputDiagnostics?: {
+        readonly onEvent: (event: TerminalInputDiagnosticsEvent) => void;
+        readonly now?: () => number;
+    };
+    readonly hardwareCursor?: boolean;
+    readonly mouse?: boolean;
+    /** Consume residual SGR mouse reports after every pre-input listener has run. */
+    readonly consumeUnhandledMouse?: boolean;
+    readonly wheelScrollLines?: TerminalWheelScrollLines;
+    readonly openUrl?: (url: string) => void;
+    readonly onRightClickPaste?: () => void;
+    readonly logDirectory?: string;
+}
+export interface TerminalStopOptions {
+    readonly preserveScreen?: boolean;
+    readonly drainInput?: boolean;
+    readonly drainMaxMs?: number;
+    readonly drainIdleMs?: number;
+}
+export interface TerminalDamageFrameDescriptor {
+    /**
+     * Frame ids are compared only within one presentation epoch; absent means the current epoch. A
+     * presenter switch starts a new epoch, because each presenter numbers its own frames.
+     */
+    readonly epoch?: number;
+    readonly frameId: number;
+    readonly width: number;
+    readonly height: number;
+    readonly transcript: {
+        readonly rowStart: number;
+        readonly rowEnd: number;
+    } | null;
+    readonly dock: {
+        readonly rowStart: number;
+        readonly rowEnd: number;
+    } | null;
+    /**
+     * Visible rows owned by the block that is currently streaming. A live block repaints
+     * every row it owns when it reflows, so the allowed damage follows the declared tail
+     * instead of assuming a one-row tail.
+     */
+    readonly liveTailRows?: number;
+    readonly verticalShiftRows: number;
+    readonly safeVerticalShift: boolean;
+    readonly cause: string;
+}
+export interface TerminalDamageFrameSafety {
+    readonly overlayActive: boolean;
+    readonly selectionActive: boolean;
+    readonly replacementSurfaceActive: boolean;
+}
+export type TerminalDamageDecisionReason = "transformed" | "suppressed-redundant-clear" | "hyperlink-cleanup" | "pending-hyperlink-cleanup" | "not-armed" | "unsafe-frame" | "stale-frame" | "unsupported-region-scroll" | "geometry-mismatch" | "grammar-mismatch" | "unsafe-terminal-content" | "incomplete-prior-frame" | "excessive-real-damage";
+export interface TerminalDamageDecision {
+    readonly frameId: number | null;
+    readonly transformed: boolean;
+    readonly reason: TerminalDamageDecisionReason;
+    readonly shiftRows: number;
+    readonly paintedRows: readonly number[];
+}
+/** What the shell's hyperlink analysis reports for one visible row. */
+export interface TerminalHyperlinkInspection {
+    readonly ranges: readonly unknown[];
+    readonly hasExplicitLink: boolean;
+    readonly signature: string;
+    readonly replaySafe: boolean;
+    readonly width: number;
+}
+export interface TerminalDamageOptions {
+    readonly regionalScroll: boolean;
+    /** The shell supplies visible-row analysis; the terminal layer owns no UI parser. */
+    readonly inspectHyperlinks: (content: string) => TerminalHyperlinkInspection;
+    readonly onResize?: () => void;
+    readonly onHyperlinkCleanupRequired?: () => void;
+}
+/** A terminal decorator that repaints only the rows a frame declares changed. */
+export interface TerminalDamagePort extends TerminalPort {
+    readonly lastDecision: TerminalDamageDecision;
+    readonly canvasBackgroundAnsi: string | null;
+    readonly presentationEpoch: number;
+    invalidatePresentation(): void;
+    /** Returns true when the background changed and a full repaint is needed. */
+    setCanvasBackground(ansi: string | null): boolean;
+    presentedRows(): readonly string[];
+    requestHyperlinkCleanup(rows?: readonly number[]): void;
+    arm(descriptor: TerminalDamageFrameDescriptor, safety: TerminalDamageFrameSafety): void;
+}
+/** The terminal runtime the shell drives: one root, overlays, input listeners, and modes. */
+export interface TerminalRuntimePort {
+    readonly state: TerminalRuntimeState;
+    readonly active: boolean;
+    readonly mode: "regular" | "fullscreen";
+    /** Full repaints since start, for rendering evidence. */
+    readonly fullRedraws: number;
+    readonly presentationHeld: boolean;
+    viewport(): TerminalViewport;
+    start(): void;
+    showOverlay(component: TerminalComponentPort, options?: TerminalOverlayOptions): TerminalOverlayHandle;
+    hasOverlay(): boolean;
+    hasFocusedOverlay(): boolean;
+    writeControl(data: string): void;
+    freezePresentation(): void;
+    beginPresentationHold(): () => void;
+    addPreInputListener(listener: TerminalPreInputListener): () => void;
+    addInputListener(listener: TerminalInputListener): () => void;
+    switchMode(mode: "regular" | "fullscreen"): boolean;
+    setHardwareCursor(enabled: boolean): void;
+    setClearOnShrink(enabled: boolean): void;
+    setWheelScrollLines(lines: TerminalWheelScrollLines): void;
+    setTerminalProgress(active: boolean): void;
+    setProgramStatus(status: TerminalProgramStatus): void;
+    setTitle(title: string): void;
+    writeAfterStop(text: string): void;
+    invalidate(): void;
+    requestRender(force?: boolean): void;
+    renderNow(force?: boolean): void;
+    stop(options?: TerminalStopOptions): Promise<void>;
+    dispose(options?: TerminalStopOptions): Promise<void>;
+}
+/** Builds the terminal runtime and its helpers; the vendor TUI adapter implements it. */
+export interface TerminalRuntimeFactory {
+    createRuntime(options: TerminalRuntimeOptions): TerminalRuntimePort;
+    createDamageTerminal(terminal: TerminalPort, options: TerminalDamageOptions): TerminalDamagePort;
+    /** Whether input on a surface may be applied before the current presentation completes. */
+    classifyInput(data: string, surface: TerminalInputSurfaceKind): TerminalInputCoordinationDecision;
+    /** Decodes an enhanced-keyboard sequence to the legacy byte form, or "" for a key release. */
+    legacyKeyInput(data: string): string;
+    /** Rebases a painted row's default background onto the given background sequence. */
+    rebaseDefaultBackground(content: string, backgroundAnsi: string): string;
+}

package/dist/contracts/presentation/terminal.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/presentation/theme.d.ts

@@ -0,0 +1,46 @@
+/** Foreground roles a vendor-neutral surface paints with. */
+export type UiThemeToken = "accent" | "mdHeading" | "mdLink" | "text" | "muted" | "dim" | "border" | "error" | "success" | "scrollbarTrack" | "scrollbarThumb";
+/** Background roles for a selected row and for a row whose work is still pending. */
+export type UiThemeBackground = "selectedBg" | "toolPendingBg";
+export interface UiTheme {
+    fg(token: UiThemeToken, text: string): string;
+    bold(text: string): string;
+    /**
+     * The terminal's own foreground, left unpainted. What a list's own text is:
+     * a theme built for a light background would otherwise write near-black rows
+     * into a dark terminal, which is how the engine leaves its lists too.
+     */
+    plain(text: string): string;
+    /** Optional palette preview used by controls that choose the active accent. */
+    accentPreview?(color: string, text: string): string | null;
+    /** Selection background for an active list item or floating-surface row. */
+    highlight(text: string): string;
+    /** A control that is present but cannot act: quieter than quiet text. */
+    disabled(text: string): string;
+    /** Background for a floating surface, so it reads as above the content. */
+    panel(text: string): string;
+    /** Paints a declared background role behind already painted text. */
+    background(token: UiThemeBackground, text: string): string;
+}
+/**
+ * The active theme and its change notifications. The vendor adapter supplies it, so a surface paints
+ * from the live theme without importing the vendor's theme module.
+ */
+export interface ThemeSource {
+    /** The live theme; its painters read the current palette on every call. */
+    current(): UiTheme;
+    /** Calls `listener` after the active theme changes; returns the unsubscribe function. */
+    onChange(listener: () => void): () => void;
+}
+import type { TerminalRuntimeFactory } from "./terminal.js";
+/** How the full-screen canvas behind the session is painted. */
+export type CanvasBackgroundStyle = "transparent" | "accent" | "dark";
+/** What the application shell receives from the vendor presentation adapter. */
+export interface ShellPresentationPorts {
+    readonly theme: ThemeSource;
+    /** The terminal background sequence for a canvas style in the active theme, or null to leave the terminal's own. */
+    canvasBackground(style: CanvasBackgroundStyle): string | null;
+    /** Columns the pinned comparison layout pads command output with. */
+    readonly pinnedOutputPad: 0 | 1;
+    readonly terminalRuntime: TerminalRuntimeFactory;
+}

package/dist/contracts/presentation/theme.js

@@ -0,0 +1 @@
+export {};

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

@@ -19,7 +19,7 @@ export function resolveDevelopmentLaunchEnvironment(canonicalPackageRoot, releas
         ? join(developmentRoot, "config")
         : join(checkoutRoot, "config");
     const dataDir = resolve(source[PRODUCT_IDENTITY.environment.dataDir] ?? join(developmentRoot, "data"));
-    // Rationale: solo processes keep isolated control state but must see the same history
+    // Rationale: development processes keep isolated control state but must see the same history
     // after selecting Shared; use a checkout-wide root across rebuilds unless overridden.
     const historyDataDir = resolve(source[PRODUCT_IDENTITY.environment.developmentHistoryDataDir]
         ?? source[PRODUCT_IDENTITY.environment.dataDir]

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

@@ -7,10 +7,10 @@ export type OwnedUiProfileId = LaunchProfileId;
 export interface InteractiveRuntimeSelection {
     readonly kind: "owned-ui";
     readonly profileId: OwnedUiProfileId;
-    readonly ownedSurfaces: "on" | "off";
+    readonly productMode: "bare" | "comparison";
 }
 export interface InteractiveRuntimeRunners {
-    readonly ownedUi: (profileId: OwnedUiProfileId, ownedSurfaces: "on" | "off") => Promise<number>;
+    readonly ownedUi: (profileId: OwnedUiProfileId, productMode: "bare" | "comparison") => 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

@@ -4,10 +4,10 @@ export function selectInteractiveRuntime(profileId) {
     return Object.freeze({
         kind: "owned-ui",
         profileId,
-        ownedSurfaces: profileId === "a1" ? "on" : "off",
+        productMode: profileId === "a1" ? "bare" : "comparison",
     });
 }
 export async function runSelectedInteractiveRuntime(profileId, runners) {
     const selection = selectInteractiveRuntime(profileId);
-    return await runners.ownedUi(selection.profileId, selection.ownedSurfaces);
+    return await runners.ownedUi(selection.profileId, selection.productMode);
 }

package/dist/features/owned-ui/project-trust-prompt.d.ts

@@ -1,5 +1,5 @@
 import type { Readable, Writable } from "node:stream";
-export type OwnedProjectTrustChoiceId = "trust" | "trust-parent" | "trust-session" | "deny" | "deny-session";
+type OwnedProjectTrustChoiceId = "trust" | "trust-parent" | "trust-session" | "deny" | "deny-session";
 export interface OwnedProjectTrustPromptRequest {
     readonly cwd: string;
     readonly defaultDecision: "ask" | "always" | "never";
@@ -21,7 +21,7 @@ export interface ConsoleProjectTrustPromptOptions {
         readonly columns?: number;
         readonly rows?: number;
     };
-    readonly presentation?: "bare" | "comparison";
+    readonly productMode?: "bare" | "comparison";
     readonly environment?: NodeJS.ProcessEnv;
 }
 /** Fixed pre-resource selector; no project resource is available. */

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

@@ -34,7 +34,7 @@ export function createConsoleProjectTrustPrompt(options = {}) {
         }
         if (choices.length === 0)
             throw new Error("project trust choices are unavailable");
-        const comparison = options.presentation === "comparison";
+        const comparison = options.productMode === "comparison";
         const renderBareDialog = comparison ? undefined : (await import("./project-trust-dialog.js")).renderProjectTrustDialog;
         const palette = comparison ? null : trustPaletteOptions(options.environment ?? process.env);
         const wasRaw = input.isRaw === true;

package/dist/features/owned-ui/release-note-state.d.ts

@@ -3,7 +3,7 @@ export interface ReleaseNoteClaim {
     acknowledge(): Promise<void>;
     release(): Promise<void>;
 }
-export interface ReleaseNoteStateOptions {
+interface ReleaseNoteStateOptions {
     readonly configDir: string;
     readonly profileId: string;
     readonly version: string;
@@ -11,3 +11,4 @@ export interface ReleaseNoteStateOptions {
 }
 /** Claims one stable note across concurrent sessions and acknowledges it only after presentation closes. */
 export declare function claimReleaseNote(options: ReleaseNoteStateOptions): Promise<ReleaseNoteClaim | null>;
+export {};