@timurproko/a1 0.1.8-dev.332 → 0.1.8-dev.368

package/dist/integrations/pi/session-ui/session-viewport-controller.js

@@ -1,3 +1,4 @@
+import { samePointerSurfaces } from "../tui-runtime/index.js";
 import { TranscriptViewport, readVisibleHyperlinks, routeMouseInput, scrollForTrackPage, scrollForThumbRow, scrollbarSelectionRows, scrollbarWheelRows, } from "../../../ui/components/index.js";
 /**
  * Owns the stateful interaction policy of the bare-A1 session viewport. The
@@ -17,6 +18,10 @@ export class SessionViewportController {
         scrollbarSpeed: "normal",
     };
     #dragGrabOffset = null;
+    #inputSurface;
+    #inputSurfacePending = false;
+    #overlays = [];
+    #pointerOwner;
     // Invariant: a left-button sequence begun in dock chrome remains owned by the dock.
     #dockPointerSuppressed = false;
     // Invariant: a left-button sequence begun in non-selectable transcript tail chrome is held there.
@@ -70,7 +75,33 @@ export class SessionViewportController {
     setEditorPointerFrame(frame) {
         this.#editorPointerFrame = frame;
     }
+    /** Replacement input changed before its new bounds have been painted. */
+    invalidateInputSurface() {
+        this.#inputSurfacePending = true;
+        this.#cancelGesture();
+    }
+    setInputSurfaceFrame(surface) {
+        if (!samePointerSurfaces(this.#inputSurface === undefined ? [] : [this.#inputSurface], surface === undefined ? [] : [surface])) {
+            this.#cancelGesture();
+        }
+        this.#inputSurface = surface;
+        this.#inputSurfacePending = false;
+    }
+    setOverlaySurfaces(surfaces) {
+        if (surfaces === this.#overlays || surfaces !== null && this.#overlays !== null && samePointerSurfaces(surfaces, this.#overlays))
+            return;
+        this.#cancelGesture();
+        this.#overlays = surfaces;
+    }
+    get inputGeometryReady() {
+        return !this.#inputSurfacePending && this.#overlays !== null;
+    }
     compose(input) {
+        const previous = this.#viewport.frame;
+        if ((this.#inputSurface !== undefined || this.#overlays === null || this.#overlays.length > 0)
+            && previous !== null && (previous.rows.length !== input.height || previous.descriptor.width !== input.width
+            || previous.hits.viewportHeight !== Math.max(0, input.height - input.dockRows.length)))
+            this.#cancelGesture();
         this.#viewport.setConfig(this.#config);
         const selectionRevision = this.#viewport.selectionRevision;
         const frame = this.#viewport.compose({
@@ -132,6 +163,10 @@ export class SessionViewportController {
         this.#pointerPosition = undefined;
         this.#hoveredHyperlinkKey = undefined;
         this.#viewport.reset();
+        this.#pointerOwner = undefined;
+        this.#dragGrabOffset = null;
+        this.#dockPointerSuppressed = false;
+        this.#tailPointerSuppressed = false;
     }
     clearPointerState() {
         this.#presentationRevision += 1;
@@ -146,33 +181,51 @@ export class SessionViewportController {
         this.#stopSelectionAutoScroll();
         this.#viewport.clearSelection();
         this.#viewport.clearTransient();
+        this.#pointerOwner = undefined;
+    }
+    #cancelGesture() {
+        const held = this.#pointerOwner !== undefined || this.#viewport.selectionActive || this.#editorPointerSelecting;
+        const repaint = this.#viewport.hasSelection || held;
+        if (!repaint && this.#pointerPosition === undefined && this.#hoveredHyperlinkKey === undefined)
+            return;
+        const editorFrame = this.#editorPointerFrame;
+        this.clearPointerState();
+        this.#editorPointerFrame = editorFrame;
+        if (held)
+            this.#pointerOwner = "drain";
+        if (repaint)
+            this.#requestRender();
     }
-    handlePreInput(data, allowWheel = true, now = Date.now()) {
+    handlePreInput(data, allowWheel = true, now = Date.now(), editorActive = true) {
         if (!this.#enabled)
             return { data, consumed: false };
         // Compatibility: Pi components share one keybinding manager. Restore bare A1's aliases
         // before the focused vanilla editor handles this input.
-        this.#editor.activateKeybindings();
+        if (editorActive)
+            this.#editor.activateKeybindings();
+        // Protocol: bracketed paste is opaque input, even if its text resembles mouse reports.
+        if (data.startsWith("\u001b[200~"))
+            return { data, consumed: false };
         // Platform: handle the physical paste chord at the pre-input boundary. Windows
         // terminals vary between forwarding Ctrl+V and terminal-owned bracketed paste.
-        if (this.#editor.matchesTerminalKey(data, "ctrl+v") && this.#editor.pasteClipboard()) {
+        if (editorActive && this.#editor.matchesTerminalKey(data, "ctrl+v") && this.#editor.pasteClipboard()) {
             return { data: "", consumed: true };
         }
         // Platform: URL chip deletion must overwrite terminal link cells in the same frame.
-        if (EDITOR_LINK_DELETION_INPUTS.has(data) && this.#hasEditorLinks()) {
+        if (editorActive && EDITOR_LINK_DELETION_INPUTS.has(data) && this.#hasEditorLinks()) {
             this.#requestHyperlinkCleanup();
             this.#requestRender();
         }
         // Invariant: content shortcuts never reach the prompt, even before the first frame
         // or when scrolling is a no-op. Plain Home/End remain editor line navigation.
-        if (allowWheel && this.#editor.matchesTerminalKey(data, "ctrl+home")) {
+        if (editorActive && allowWheel && this.#editor.matchesTerminalKey(data, "ctrl+home")) {
             if (this.#viewport.scrollTo(0, now)) {
                 this.#scheduleActivityExpiry();
                 this.#requestRender();
             }
             return { data: "", consumed: true };
         }
-        if (allowWheel && this.#editor.matchesTerminalKey(data, "ctrl+end")) {
+        if (editorActive && allowWheel && this.#editor.matchesTerminalKey(data, "ctrl+end")) {
             if (!this.#viewport.followingEnd) {
                 this.#viewport.scrollToEnd(now);
                 this.#scheduleActivityExpiry();
@@ -191,7 +244,7 @@ export class SessionViewportController {
             });
         }
         if (data === "\u0003") {
-            if (this.#editor.hasSelection()) {
+            if (editorActive && this.#editor.hasSelection()) {
                 if (this.#viewport.clearSelection())
                     this.#requestRender();
             }
@@ -204,8 +257,9 @@ export class SessionViewportController {
                 }
             }
         }
-        if (allowWheel && (SHIFT_UP_INPUTS.has(data) || SHIFT_DOWN_INPUTS.has(data))) {
-            const scrolled = SHIFT_UP_INPUTS.has(data)
+        const previousPrompt = SHIFT_UP_INPUTS.has(data) || this.#editor.matchesTerminalKey(data, "alt+home");
+        if (editorActive && allowWheel && (previousPrompt || SHIFT_DOWN_INPUTS.has(data))) {
+            const scrolled = previousPrompt
                 ? this.#viewport.scrollToPreviousPrompt(now)
                 : this.#viewport.scrollToNextPrompt(now);
             if (scrolled) {
@@ -221,14 +275,44 @@ export class SessionViewportController {
         let repaint = false;
         let forceRepaint = false;
         let activity = false;
-        const routed = routeMouseInput(data, event => {
+        const routed = routeMouseInput(data, (event, report) => {
             const hits = frame.hits;
-            const overRail = hits.rail !== null
+            const overModal = this.#modalAt(event.column, event.row);
+            const wheel = event.kind === "wheel-up" || event.kind === "wheel-down";
+            // Invariant: ownership is latched for a complete gesture. Modal reports bypass the outer
+            // fullscreen selection layer without ever invoking the hidden ordinary editor.
+            if (this.#pointerOwner === "drain" || !this.inputGeometryReady) {
+                if (event.kind === "release")
+                    this.#pointerOwner = undefined;
+                else if (event.kind === "press")
+                    this.#pointerOwner = "drain";
+                return true;
+            }
+            const owner = !wheel && this.#pointerOwner !== undefined ? this.#pointerOwner : overModal;
+            if (owner !== undefined && owner !== "viewport") {
+                if (event.kind === "press")
+                    this.#pointerOwner = owner;
+                if (event.kind === "release")
+                    this.#pointerOwner = undefined;
+                if (event.kind === "press" && this.#viewport.clearSelection())
+                    repaint = true;
+                this.#viewport.setRailHovered(false);
+                this.#viewport.setStickyHovered(false);
+                this.#pointerPosition = undefined;
+                owner.component.handleInput?.(report);
+                repaint = true;
+                return true;
+            }
+            if (event.kind === "press")
+                this.#pointerOwner = "viewport";
+            if (event.kind === "release")
+                this.#pointerOwner = undefined;
+            const overRail = overModal === undefined && hits.rail !== null
                 && event.column === hits.rail.column
                 && event.row >= hits.rail.rowStart
                 && event.row < hits.rail.rowStart + hits.rail.trackHeight;
-            const overSticky = hits.sticky !== null && event.row === hits.sticky.row && event.column <= hits.sticky.width;
-            const overBottom = hits.bottom !== null && event.row === hits.bottom.row
+            const overSticky = overModal === undefined && hits.sticky !== null && event.row === hits.sticky.row && event.column <= hits.sticky.width;
+            const overBottom = overModal === undefined && hits.bottom !== null && event.row === hits.bottom.row
                 && event.column >= hits.bottom.columnStart && event.column <= hits.bottom.columnEnd;
             const previousPointer = this.#pointerPosition;
             const wasOverBottom = hits.bottom !== null && previousPointer !== undefined
@@ -251,7 +335,7 @@ export class SessionViewportController {
                 this.#viewport.setRailHovered(overRail);
                 this.#viewport.setStickyHovered(overSticky);
                 repaint = true;
-                if (this.#editor.ownsPointer() && this.#editorPointerFrame !== undefined) {
+                if (editorActive && this.#editor.ownsPointer() && this.#editorPointerFrame !== undefined) {
                     this.#editor.handlePointer({
                         kind: "motion",
                         button: event.button,
@@ -287,7 +371,7 @@ export class SessionViewportController {
                 return true;
             }
             if (event.kind === "press") {
-                const editorFrame = this.#editorPointerFrame;
+                const editorFrame = editorActive ? this.#editorPointerFrame : undefined;
                 if (event.button === 2 && editorFrame !== undefined
                     && event.row >= editorFrame.rowStart && event.row <= editorFrame.rowEnd) {
                     this.#stopSelectionAutoScroll();
@@ -362,7 +446,7 @@ export class SessionViewportController {
                 return true;
             }
             if (event.kind === "release") {
-                if (this.#editor.ownsPointer() && this.#editorPointerFrame !== undefined) {
+                if (editorActive && this.#editor.ownsPointer() && this.#editorPointerFrame !== undefined) {
                     const wasEditorSelecting = this.#editorPointerSelecting;
                     this.#editor.handlePointer({
                         kind: "release",
@@ -408,6 +492,12 @@ export class SessionViewportController {
         }
         return routed;
     }
+    #modalAt(column, row) {
+        const contains = (surface) => column >= surface.columnStart && column <= surface.columnEnd
+            && row >= surface.rowStart && row <= surface.rowEnd;
+        const overlay = this.#overlays?.findLast(contains);
+        return overlay ?? (this.#inputSurface !== undefined && contains(this.#inputSurface) ? this.#inputSurface : undefined);
+    }
     #hyperlinkKeyAt(frame, column, row) {
         if (row < 1 || row > frame.rows.length || column < 1)
             return undefined;

package/dist/integrations/pi/tui-runtime/adapter.d.ts

@@ -22,6 +22,8 @@ export declare class PiTuiRuntimeAdapter {
     setFocus(component: PiTuiComponentPort | null): void;
     showOverlay(component: PiTuiComponentPort, options?: PiTuiOverlayOptions): PiTuiOverlayHandle;
     hasOverlay(): boolean;
+    /** Keyboard capture is independent of a passive overlay's visible pointer region. */
+    hasFocusedOverlay(): boolean;
     /**
      * Writes a terminal control sequence. Used to enable and disable mouse
      * reporting while an A1-owned application is presented, and for nothing else:

package/dist/integrations/pi/tui-runtime/adapter.js

@@ -1,4 +1,6 @@
 import { HStack, ProcessTerminal, ScrollView, TuiAltScreen, TuiMainScreen, VStack, visibleWidth, } from "#pi-tui";
+import { MouseReportInput } from "./mouse-report-input.js";
+import { GeometryObservedAltScreen, OverlayGeometryTracker } from "./overlay-geometry.js";
 import { boundedCleanup, EMERGENCY_TERMINAL_RESET } from "../../../foundation/terminal-cleanup/index.js";
 import { InputPresentationCoordinator, } from "./input-presentation-coordinator.js";
 /** Identifies the Pi TUI lifecycle stage that failed while preserving the original cause. */
@@ -103,6 +105,7 @@ export class PiTuiRuntimeAdapter {
     #bridges = new WeakMap();
     #mountedComponents = new Set();
     #scrollViews = new Map();
+    #overlayGeometry;
     #overlayDisposers = new Set();
     #overlayInputCoordination = new Map();
     #inputListeners = new Map();
@@ -117,6 +120,7 @@ export class PiTuiRuntimeAdapter {
     #terminalProgress = false;
     constructor(options) {
         this.#root = options.root;
+        this.#overlayGeometry = options.onOverlayGeometry === undefined ? undefined : new OverlayGeometryTracker(options.onOverlayGeometry);
         this.#terminal = options.terminal ?? new ProcessTerminal();
         this.#inputDiagnostics = options.inputDiagnostics;
         this.#diagnosticNow = options.inputDiagnostics?.now ?? (() => performance.now());
@@ -144,8 +148,8 @@ export class PiTuiRuntimeAdapter {
                 }),
             });
         this.#tuiTerminal = this.#inputCoordinator === undefined
-            ? preInputTerminal(decoratedTerminal, data => this.#routePreInput(data))
-            : coordinatedInputTerminal(decoratedTerminal, this.#inputCoordinator, sink => { this.#inputSink = sink; });
+            ? preInputTerminal(decoratedTerminal, data => this.#routePreInput(data), this.#overlayGeometry !== undefined)
+            : coordinatedInputTerminal(decoratedTerminal, this.#inputCoordinator, sink => { this.#inputSink = sink; }, this.#overlayGeometry !== undefined);
         this.#layoutRoot = options.layoutRoot;
         this.#logDirectory = options.logDirectory;
         this.#rootBridge = new ComponentBridge(options.root, options.inputDiagnostics === undefined
@@ -256,6 +260,8 @@ export class PiTuiRuntimeAdapter {
     }
     setFocus(component) {
         this.#assertRunning("focus");
+        if (this.#overlayInputCoordination.size > 0)
+            this.#overlayGeometry?.invalidate();
         this.#tui.setFocus(this.#bridgeFor(component));
     }
     showOverlay(component, options) {
@@ -264,6 +270,7 @@ export class PiTuiRuntimeAdapter {
             throw new TypeError("Pi TUI component is already mounted");
         const bridge = new ComponentBridge(component);
         this.#bridges.set(component, bridge);
+        this.#overlayGeometry?.ports.set(bridge, component);
         let hidden = false;
         const dispose = () => {
             if (hidden)
@@ -282,6 +289,10 @@ export class PiTuiRuntimeAdapter {
     hasOverlay() {
         return this.#tui.hasOverlay();
     }
+    /** Keyboard capture is independent of a passive overlay's visible pointer region. */
+    hasFocusedOverlay() {
+        return this.#tui instanceof GeometryObservedAltScreen ? this.#tui.overlayFocused : this.#focusedOverlayInputCoordination() !== undefined;
+    }
     /**
      * Writes a terminal control sequence. Used to enable and disable mouse
      * reporting while an A1-owned application is presented, and for nothing else:
@@ -435,9 +446,13 @@ export class PiTuiRuntimeAdapter {
             throw failure;
     }
     #createTui(mode, hardwareCursor) {
-        return mode === "fullscreen"
-            ? new TuiAltScreen(this.#tuiTerminal, hardwareCursor, this.#logDirectory, this.#tuiOptions)
-            : new TuiMainScreen(this.#tuiTerminal, hardwareCursor, this.#logDirectory);
+        if (mode !== "fullscreen")
+            return new TuiMainScreen(this.#tuiTerminal, hardwareCursor, this.#logDirectory);
+        if (this.#overlayGeometry === undefined)
+            return new TuiAltScreen(this.#tuiTerminal, hardwareCursor, this.#logDirectory, this.#tuiOptions);
+        const screen = new GeometryObservedAltScreen(this.#tuiTerminal, hardwareCursor, this.#logDirectory, this.#tuiOptions);
+        screen.geometry = this.#overlayGeometry;
+        return screen;
     }
     #routePreInput(data) {
         let current = data;
@@ -600,20 +615,23 @@ export class PiTuiRuntimeAdapter {
         this.#disposeRoot();
     }
 }
-function coordinatedInputTerminal(terminal, coordinator, setSink) {
+function coordinatedInputTerminal(terminal, coordinator, setSink, frameMouse) {
+    const mouse = frameMouse ? new MouseReportInput(data => coordinator.accept(data)) : undefined;
     return {
         get columns() { return terminal.columns; },
         get rows() { return terminal.rows; },
         get kittyProtocolActive() { return terminal.kittyProtocolActive; },
         start(onInput, onResize) {
             setSink(onInput);
-            terminal.start(data => coordinator.accept(data), () => {
+            terminal.start(data => mouse === undefined ? coordinator.accept(data) : mouse.accept(data), () => {
                 coordinator.flush();
+                mouse?.reset();
                 onResize();
             });
         },
         stop() {
             coordinator.flush();
+            mouse?.reset();
             setSink(undefined);
             terminal.stop();
         },
@@ -656,19 +674,25 @@ function diagnosticTerminal(terminal, trace) {
         setProgress: active => terminal.setProgress(active),
     };
 }
-function preInputTerminal(terminal, route) {
+function preInputTerminal(terminal, route, frameMouse) {
+    let mouse;
     return {
         get columns() { return terminal.columns; },
         get rows() { return terminal.rows; },
         get kittyProtocolActive() { return terminal.kittyProtocolActive; },
         start(onInput, onResize) {
-            terminal.start(data => {
+            const deliver = (data) => {
                 const routed = route(data);
                 if (routed.length > 0)
                     onInput(routed);
-            }, onResize);
+            };
+            mouse = frameMouse ? new MouseReportInput(deliver) : undefined;
+            terminal.start(data => mouse === undefined ? deliver(data) : mouse.accept(data), () => {
+                mouse?.reset();
+                onResize();
+            });
         },
-        stop: () => terminal.stop(),
+        stop: () => { mouse?.reset(); terminal.stop(); },
         drainInput: (maxMs, idleMs) => terminal.drainInput(maxMs, idleMs),
         write: data => terminal.write(data),
         moveBy: lines => terminal.moveBy(lines),

package/dist/integrations/pi/tui-runtime/contracts.d.ts

@@ -1,4 +1,4 @@
-import type { PresentationComponentPort } from "../../../contracts/presentation/index.js";
+import type { PresentationComponentPort, PresentationPointerSurface } from "../../../contracts/presentation/index.js";
 import type { PiTuiInputCoordinationDecision, PiTuiInputCoordinationScheduler, PiTuiInputSurfaceKind } from "./input-presentation-coordinator.js";
 export type PiTuiRuntimeState = "idle" | "running" | "stopping" | "stopped" | "failed";
 export interface PiTuiViewport {
@@ -11,6 +11,7 @@ export interface PiTuiScrollState {
     readonly followingEnd: boolean;
     readonly scrollbarVisible: boolean;
 }
+export type PiTuiPointerSurface = PresentationPointerSurface;
 export interface PiTuiComponentPort extends PresentationComponentPort {
     readonly wantsKeyRelease?: boolean;
 }
@@ -112,6 +113,8 @@ export interface PiTuiInputDiagnosticsEvent {
 }
 export interface PiTuiRuntimeAdapterOptions {
     readonly root: PiTuiComponentPort;
+    /** Bare viewport only: painted overlays in back-to-front order; null while geometry is stale. */
+    readonly onOverlayGeometry?: (surfaces: readonly PiTuiPointerSurface[] | null) => void;
     readonly mode?: "regular" | "fullscreen";
     readonly layoutRoot?: PiTuiLayoutNode;
     readonly terminal?: PiTuiTerminalPort;

package/dist/integrations/pi/tui-runtime/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./contracts.js";
+export { samePointerSurfaces } from "./overlay-geometry.js";
 export * from "./damage-aware-terminal.js";
 export * from "./input-presentation-coordinator.js";
 export * from "./adapter.js";

package/dist/integrations/pi/tui-runtime/index.js

@@ -1,4 +1,5 @@
 export * from "./contracts.js";
+export { samePointerSurfaces } from "./overlay-geometry.js";
 export * from "./damage-aware-terminal.js";
 export * from "./input-presentation-coordinator.js";
 export * from "./adapter.js";

package/dist/integrations/pi/tui-runtime/mouse-report-input.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Keeps mouse reports and adjacent keyboard input in physical delivery order.
+ * ProcessTerminal already frames escape/paste sequences; this also handles hosts
+ * that batch reports or split an SGR report after its introducer. Paste payloads
+ * are opaque and never interpreted as pointer input.
+ */
+export declare class MouseReportInput {
+    #private;
+    readonly deliver: (data: string) => void;
+    constructor(deliver: (data: string) => void);
+    accept(chunk: string): void;
+    reset(): void;
+}

package/dist/integrations/pi/tui-runtime/mouse-report-input.js

@@ -0,0 +1,59 @@
+/**
+ * Keeps mouse reports and adjacent keyboard input in physical delivery order.
+ * ProcessTerminal already frames escape/paste sequences; this also handles hosts
+ * that batch reports or split an SGR report after its introducer. Paste payloads
+ * are opaque and never interpreted as pointer input.
+ */
+export class MouseReportInput {
+    deliver;
+    #pending = "";
+    #paste = false;
+    constructor(deliver) {
+        this.deliver = deliver;
+    }
+    accept(chunk) {
+        const data = this.#pending + chunk;
+        this.#pending = "";
+        if (this.#paste) {
+            const end = data.indexOf("\u001b[201~");
+            if (end < 0) {
+                this.deliver(data);
+                return;
+            }
+            this.#paste = false;
+            this.deliver(data.slice(0, end + 6));
+            if (end + 6 < data.length)
+                this.accept(data.slice(end + 6));
+            return;
+        }
+        const pattern = /\u001b\[200~|\u001b\[<\d+;\d+;\d+[Mm]/g;
+        let from = 0;
+        for (const match of data.matchAll(pattern)) {
+            if (match.index > from)
+                this.deliver(data.slice(from, match.index));
+            if (match[0] === "\u001b[200~") {
+                const end = data.indexOf("\u001b[201~", match.index + 6);
+                this.#paste = end < 0;
+                this.deliver(data.slice(match.index, end < 0 ? undefined : end + 6));
+                if (end >= 0 && end + 6 < data.length)
+                    this.accept(data.slice(end + 6));
+                return;
+            }
+            this.deliver(match[0]);
+            from = match.index + match[0].length;
+        }
+        const rest = data.slice(from);
+        const partial = /\u001b\[<[\d;]*$/.exec(rest);
+        if (partial !== null && partial[0].length <= 64) {
+            this.#pending = partial[0];
+            if (partial.index > 0)
+                this.deliver(rest.slice(0, partial.index));
+        }
+        else if (rest.length > 0)
+            this.deliver(rest);
+    }
+    reset() {
+        this.#pending = "";
+        this.#paste = false;
+    }
+}

package/dist/integrations/pi/tui-runtime/overlay-geometry.d.ts

@@ -0,0 +1,32 @@
+import { TuiAltScreen, type Component, type OverlayHandle, type OverlayOptions } from "#pi-tui";
+import type { PresentationComponentPort, PresentationPointerSurface } from "../../../contracts/presentation/index.js";
+import type { PiTuiOverlayOptions } from "./contracts.js";
+/** Observes public component renders in compositor order, without accessing renderer state. */
+export declare class OverlayGeometryTracker {
+    #private;
+    readonly publish: (surfaces: readonly PresentationPointerSurface[] | null) => void;
+    readonly ports: WeakMap<Component, PresentationComponentPort>;
+    constructor(publish: (surfaces: readonly PresentationPointerSurface[] | null) => void);
+    invalidate(): void;
+    begin(columns: number, rows: number): void;
+    record(component: PresentationComponentPort, options: PiTuiOverlayOptions | undefined, width: number, height: number): void;
+    end(): void;
+}
+/** The protected composition hook brackets the actual visible, focus-ordered overlay renders. */
+export declare class GeometryObservedAltScreen extends TuiAltScreen {
+    #private;
+    geometry: OverlayGeometryTracker | undefined;
+    get overlayFocused(): boolean;
+    setFocus(component: Component | null): void;
+    showOverlay(component: Component, options?: OverlayOptions): OverlayHandle;
+    hideOverlay(): void;
+    protected compositeOverlays(lines: string[], width: number, height: number): string[];
+}
+/** Compare only geometry and ownership, never animation content or transcript position. */
+export declare function samePointerSurfaces(a: readonly PresentationPointerSurface[], b: readonly PresentationPointerSurface[]): boolean;
+/**
+ * Resolve the pinned public overlay options against the actual render width/height.
+ * The runtime still owns layout and painting. Independent terminal-cell tests certify
+ * this option-to-hit-region projection against its compositor, including clipping.
+ */
+export declare function overlayPointerSurface(component: PresentationComponentPort, options: PiTuiOverlayOptions | undefined, width: number, renderedHeight: number, columns: number, rows: number): PresentationPointerSurface | undefined;