@timurproko/a1 0.1.8-dev.ece8cef → 0.2.1-dev.590

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

@@ -0,0 +1,792 @@
+import { HStack, ProcessTerminal, ScrollView, TuiAltScreen, TuiMainScreen, VStack, visibleWidth, } from "@earendil-works/pi-tui";
+import { MouseReportInput, stripSgrMouseReports } from "./mouse-report-input.js";
+import { GeometryObservedAltScreen, OverlayGeometryTracker } from "./overlay-geometry.js";
+import { boundedCleanup, EMERGENCY_TERMINAL_RESET } from "../../../foundation/terminal-cleanup/terminal-reset.js";
+import { InputPresentationCoordinator, } from "./input-presentation-coordinator.js";
+/** Identifies the Pi TUI lifecycle stage that failed while preserving the original cause. */
+export class PiTuiRuntimeError extends Error {
+    stage;
+    constructor(stage, cause) {
+        super(`Pi TUI runtime failed during ${stage}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        this.stage = stage;
+        this.name = "PiTuiRuntimeError";
+    }
+}
+class ComponentBridge {
+    #focused = false;
+    port;
+    traceComposition;
+    constructor(port, traceComposition) { this.port = port; this.traceComposition = traceComposition; }
+    get focused() {
+        return this.#focused;
+    }
+    set focused(value) {
+        this.#focused = value;
+        this.port.setFocused?.(value);
+    }
+    get wantsKeyRelease() {
+        return this.port.wantsKeyRelease ?? false;
+    }
+    render(width) {
+        this.traceComposition?.("composition-start");
+        try {
+            const lines = [...this.port.render(width)];
+            // Protocol: Kitty APC carries pixels, not columns. Still validate every ordinary cell
+            // around the payload instead of exempting the entire image-bearing row from width checks.
+            const overflow = lines.findIndex(line => visibleWidth(line.replace(/\u001b_G[^\u001b]*\u001b\\/g, "")) > width);
+            if (overflow >= 0) {
+                throw new RangeError(`Pi TUI component row ${overflow} exceeds available width ${width}`);
+            }
+            return lines;
+        }
+        finally {
+            this.traceComposition?.("composition-end");
+        }
+    }
+    handleInput(data) {
+        this.port.handleInput?.(data);
+    }
+    invalidate() {
+        this.port.invalidate();
+    }
+}
+class OverlayHandleBridge {
+    #disposed = false;
+    handle;
+    bridgeFor;
+    dispose;
+    constructor(handle, bridgeFor, dispose) { this.handle = handle; this.bridgeFor = bridgeFor; this.dispose = dispose; }
+    hide() {
+        if (this.#disposed)
+            return;
+        this.handle.hide();
+        this.#disposed = true;
+        this.dispose();
+    }
+    setHidden(hidden) {
+        if (!this.#disposed)
+            this.handle.setHidden(hidden);
+    }
+    isHidden() {
+        return this.#disposed || this.handle.isHidden();
+    }
+    getBounds() {
+        return this.#disposed ? undefined : this.handle.getBounds();
+    }
+    focus() {
+        if (!this.#disposed)
+            this.handle.focus();
+    }
+    unfocus(options) {
+        if (this.#disposed)
+            return;
+        if (options === undefined) {
+            this.handle.unfocus();
+            return;
+        }
+        this.handle.unfocus({ target: this.bridgeFor(options.target) });
+    }
+    isFocused() {
+        return !this.#disposed && this.handle.isFocused();
+    }
+}
+/** Bridges neutral presentation ports to one Pi TUI instance and owns terminal restoration on stop. */
+export class PiTuiRuntimeAdapter {
+    #terminal;
+    #tuiTerminal;
+    #tui;
+    #root;
+    #layoutRoot;
+    #tuiOptions;
+    #logDirectory;
+    #rootBridge;
+    #bridges = new WeakMap();
+    #mountedComponents = new Set();
+    #scrollViews = new Map();
+    #overlayGeometry;
+    #overlayDisposers = new Set();
+    #overlayInputCoordination = new Map();
+    #inputListeners = new Map();
+    #preInputListeners = new Set();
+    #consumeUnhandledMouse;
+    #inputCoordinator;
+    #inputDiagnostics;
+    #diagnosticNow;
+    #inputSink;
+    #state = "idle";
+    #stopPromise;
+    #rootDisposed = false;
+    #terminalProgress = false;
+    #presentationFrozen = false;
+    constructor(options) {
+        this.#root = options.root;
+        this.#overlayGeometry = options.onOverlayGeometry === undefined ? undefined : new OverlayGeometryTracker(options.onOverlayGeometry);
+        this.#terminal = options.terminal ?? new ProcessTerminal();
+        this.#consumeUnhandledMouse = options.consumeUnhandledMouse ?? false;
+        this.#inputDiagnostics = options.inputDiagnostics;
+        this.#diagnosticNow = options.inputDiagnostics?.now ?? (() => performance.now());
+        // Invariant: the pinned renderer's frames pass through this gate, while writeControl and
+        // the stop sequence reach the terminal directly. Freezing drops frames without touching
+        // the renderer, so a scheduled repaint cannot land on top of the quit outro.
+        const gatedTerminal = frozenGateTerminal(this.#terminal, () => this.#presentationFrozen);
+        const tracedTerminal = options.inputDiagnostics === undefined
+            ? gatedTerminal
+            : diagnosticTerminal(gatedTerminal, phase => this.#traceRuntimePhase(phase));
+        const decoratedTerminal = options.decorateTerminal?.(tracedTerminal) ?? tracedTerminal;
+        const coordination = options.inputCoordination ?? (options.inputDiagnostics === undefined
+            ? undefined
+            : { classify: () => "barrier" });
+        this.#inputCoordinator = coordination === undefined
+            ? undefined
+            : new InputPresentationCoordinator({
+                classify: data => coordination.classify(data, this.#focusedOverlayInputCoordination()),
+                deliver: data => {
+                    const routed = this.#routePreInput(data);
+                    if (routed.length > 0)
+                        this.#inputSink?.(routed);
+                },
+                ...(coordination.onReceipt === undefined ? {} : { onReceipt: coordination.onReceipt }),
+                ...(coordination.scheduler === undefined ? {} : { scheduler: coordination.scheduler }),
+                now: this.#diagnosticNow,
+                ...(options.inputDiagnostics === undefined ? {} : {
+                    onTrace: event => this.#traceInputCoordination(event),
+                }),
+            });
+        this.#tuiTerminal = this.#inputCoordinator === undefined
+            ? 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
+            ? undefined
+            : phase => this.#traceRuntimePhase(phase));
+        this.#bridges.set(options.root, this.#rootBridge);
+        this.#mountedComponents.add(options.root);
+        try {
+            const tuiOptions = {};
+            if (options.wheelScrollLines !== undefined)
+                tuiOptions.wheelScrollLines = options.wheelScrollLines;
+            if (options.mouse !== undefined)
+                tuiOptions.mouse = options.mouse;
+            if (options.openUrl !== undefined)
+                tuiOptions.openUrl = options.openUrl;
+            if (options.onRightClickPaste !== undefined)
+                tuiOptions.onRightClickPaste = options.onRightClickPaste;
+            this.#tuiOptions = tuiOptions;
+            this.#tui = this.#createTui(options.mode ?? "regular", options.hardwareCursor ?? false);
+            this.#mountTui(this.#tui);
+        }
+        catch (error) {
+            this.#state = "failed";
+            throw new PiTuiRuntimeError("construction", error);
+        }
+    }
+    get state() {
+        return this.#state;
+    }
+    get active() {
+        return this.#state === "running";
+    }
+    get mode() {
+        return this.#tui.mode;
+    }
+    get fullRedraws() {
+        return this.#tui.fullRedraws;
+    }
+    viewport() {
+        return {
+            columns: Math.max(1, this.#terminal.columns),
+            rows: Math.max(1, this.#terminal.rows),
+        };
+    }
+    scrollState(id) {
+        if (id === undefined) {
+            if (!(this.#tui instanceof TuiAltScreen)) {
+                throw new Error("Pi TUI application scrolling is available only in fullscreen mode");
+            }
+            return {
+                scrollTop: this.#tui.viewportTop,
+                viewportHeight: this.viewport().rows,
+                followingEnd: this.#tui.isFollowingOutput,
+                scrollbarVisible: false,
+            };
+        }
+        const scrollView = this.#requireScrollView(id);
+        return {
+            scrollTop: scrollView.scrollTop,
+            viewportHeight: scrollView.viewportHeight,
+            followingEnd: scrollView.isFollowingEnd,
+            scrollbarVisible: scrollView.isScrollbarVisible,
+        };
+    }
+    scrollBy(lines, id) {
+        this.#assertRunning("scroll");
+        if (id === undefined)
+            this.#requireFullscreen().scrollBy(lines);
+        else {
+            this.#requireScrollView(id).scrollBy(lines);
+            this.#tui.requestRender();
+        }
+    }
+    scrollToTop(id) {
+        this.#assertRunning("scroll");
+        if (id === undefined)
+            this.#requireFullscreen().scrollToTop();
+        else {
+            this.#requireScrollView(id).scrollToStart();
+            this.#tui.requestRender();
+        }
+    }
+    scrollToBottom(id) {
+        this.#assertRunning("scroll");
+        if (id === undefined)
+            this.#requireFullscreen().scrollToBottom();
+        else {
+            this.#requireScrollView(id).scrollToEnd();
+            this.#tui.requestRender();
+        }
+    }
+    start() {
+        if (this.#state === "running")
+            return;
+        if (this.#state !== "idle")
+            throw new PiTuiRuntimeError("start", new Error(`runtime cannot start from ${this.#state}`));
+        try {
+            this.#tui.setFocus(this.#rootBridge);
+            this.#tui.start();
+            this.#state = "running";
+        }
+        catch (error) {
+            this.#state = "failed";
+            this.#restoreAfterFailedStart();
+            this.#disposeRoot();
+            throw new PiTuiRuntimeError("start", error);
+        }
+    }
+    setFocus(component) {
+        this.#assertRunning("focus");
+        if (this.#overlayInputCoordination.size > 0)
+            this.#overlayGeometry?.invalidate();
+        this.#tui.setFocus(this.#bridgeFor(component));
+    }
+    showOverlay(component, options) {
+        this.#assertRunning("overlay");
+        if (this.#bridges.has(component))
+            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)
+                return;
+            hidden = true;
+            this.#overlayDisposers.delete(dispose);
+            this.#overlayInputCoordination.delete(bridge);
+            this.#bridges.delete(component);
+            component.dispose?.();
+        };
+        this.#overlayDisposers.add(dispose);
+        this.#overlayInputCoordination.set(bridge, options?.inputCoordination ?? "opaque");
+        const handle = this.#tui.showOverlay(bridge, toOverlayOptions(options));
+        return new OverlayHandleBridge(handle, target => this.#bridgeFor(target), dispose);
+    }
+    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 to paint the quit
+     * outro while presentation is frozen, and for nothing else: the transparent
+     * and pinned paths never call it.
+     */
+    writeControl(data) {
+        this.#assertRunning("control sequence");
+        this.#terminal.write(data);
+    }
+    /**
+     * Drops every pinned frame write until the runtime stops. The quit outro owns
+     * the alternate screen between the last presented frame and the leave; the
+     * renderer keeps scheduling but nothing it paints reaches the terminal.
+     */
+    freezePresentation() {
+        this.#assertRunning("presentation freeze");
+        this.#presentationFrozen = true;
+    }
+    get presentationFrozen() {
+        return this.#presentationFrozen;
+    }
+    addPreInputListener(listener) {
+        if (this.#preInputListeners.has(listener))
+            throw new TypeError("Pi TUI pre-input listener is already registered");
+        this.#preInputListeners.add(listener);
+        return () => this.#preInputListeners.delete(listener);
+    }
+    addInputListener(listener) {
+        this.#assertRunning("input listener");
+        if (this.#inputListeners.has(listener))
+            throw new TypeError("Pi TUI input listener is already registered");
+        this.#inputListeners.set(listener, this.#tui.addInputListener(data => listener(data)));
+        return () => {
+            this.#inputListeners.get(listener)?.();
+            this.#inputListeners.delete(listener);
+        };
+    }
+    switchMode(mode) {
+        this.#assertRunning("mode switch");
+        if (mode === this.#tui.mode)
+            return true;
+        if (this.#tui.hasOverlay())
+            return false;
+        const previous = this.#tui;
+        const hardwareCursor = previous.getShowHardwareCursor();
+        const clearOnShrink = previous.getClearOnShrink();
+        try {
+            for (const remove of this.#inputListeners.values())
+                remove();
+            previous.stop({ preserveScreen: true });
+            previous.setFocus(null);
+            previous.clear();
+            if (previous instanceof TuiAltScreen)
+                previous.setLayoutRoot(undefined);
+            this.#scrollViews.clear();
+            const next = this.#createTui(mode, hardwareCursor);
+            next.setClearOnShrink(clearOnShrink);
+            this.#mountTui(next);
+            this.#tui = next;
+            for (const listener of this.#inputListeners.keys()) {
+                this.#inputListeners.set(listener, next.addInputListener(data => listener(data)));
+            }
+            next.setFocus(this.#rootBridge);
+            next.start();
+            return true;
+        }
+        catch (error) {
+            this.#state = "failed";
+            this.#bestEffortTerminalRestore();
+            throw new PiTuiRuntimeError("construction", error);
+        }
+    }
+    setHardwareCursor(enabled) {
+        this.#tui.setShowHardwareCursor(enabled);
+        if (this.active)
+            this.#tui.requestRender();
+    }
+    getHardwareCursor() {
+        return this.#tui.getShowHardwareCursor();
+    }
+    setClearOnShrink(enabled) {
+        this.#tui.setClearOnShrink(enabled);
+    }
+    getClearOnShrink() {
+        return this.#tui.getClearOnShrink();
+    }
+    setTerminalProgress(active) {
+        if (this.#terminalProgress === active)
+            return;
+        this.#terminal.setProgress(active);
+        this.#terminalProgress = active;
+    }
+    setTitle(title) {
+        this.#terminal.setTitle(title);
+    }
+    /** Shows a bounded fullscreen acknowledgement without changing root layout geometry. */
+    showFlash(message, durationMs) {
+        this.#assertRunning("flash");
+        this.#requireFullscreen().flash(message, durationMs);
+    }
+    writeAfterStop(text) {
+        if (this.#state !== "stopped")
+            throw new Error("terminal output requires a stopped Pi TUI runtime");
+        this.#terminal.write(text);
+    }
+    invalidate() {
+        this.#tui.invalidate();
+        if (this.active)
+            this.#tui.requestRender();
+    }
+    requestRender(force = false) {
+        if (this.active)
+            this.#tui.requestRender(force);
+    }
+    renderNow(force = false) {
+        this.#assertRunning("render");
+        this.#tui.renderNow(force);
+    }
+    stop(options = {}) {
+        if (this.#stopPromise)
+            return this.#stopPromise;
+        if (this.#state === "idle") {
+            this.#state = "stopped";
+            this.#clearTerminalProgress();
+            this.#preInputListeners.clear();
+            this.#disposeRoot();
+            return Promise.resolve();
+        }
+        if (this.#state === "stopped")
+            return Promise.resolve();
+        this.#stopPromise = this.#stop(options);
+        return this.#stopPromise;
+    }
+    async dispose(options = {}) {
+        await this.stop(options);
+    }
+    async #stop(options) {
+        this.#state = "stopping";
+        let failure;
+        try {
+            this.#inputCoordinator?.dispose(false);
+        }
+        catch (error) {
+            failure = new PiTuiRuntimeError("restoration", error);
+        }
+        if (options.drainInput !== false) {
+            try {
+                await boundedCleanup(() => this.#terminal.drainInput(options.drainMaxMs, options.drainIdleMs));
+            }
+            catch (error) {
+                failure = new PiTuiRuntimeError("input-drain", error);
+            }
+        }
+        try {
+            const stopOptions = options.preserveScreen === undefined ? undefined : { preserveScreen: options.preserveScreen };
+            // Invariant: the gate opens only for the synchronous stop sequence, so no render
+            // scheduled during the outro can slip in before the alternate screen is left.
+            this.#presentationFrozen = false;
+            this.#tui.stop(stopOptions);
+        }
+        catch (error) {
+            failure ??= new PiTuiRuntimeError("restoration", error);
+            this.#bestEffortTerminalRestore();
+        }
+        finally {
+            this.#clearTerminalProgress();
+            this.#disposeComponents();
+        }
+        this.#state = failure === undefined ? "stopped" : "failed";
+        if (failure)
+            throw failure;
+    }
+    #createTui(mode, hardwareCursor) {
+        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;
+        for (const listener of this.#preInputListeners) {
+            if (current.length === 0)
+                break;
+            const result = listener(current);
+            if (result?.data !== undefined)
+                current = result.data;
+            else if (result?.consume === true)
+                current = "";
+        }
+        // Invariant: bare A1 owns every fullscreen pointer path. Listeners keep first
+        // refusal, then this boundary prevents Pi's reverse-video fallback selection.
+        return this.#consumeUnhandledMouse ? stripSgrMouseReports(current) : current;
+    }
+    #focusedOverlayInputCoordination() {
+        for (const [bridge, coordination] of this.#overlayInputCoordination) {
+            if (bridge.focused)
+                return coordination;
+        }
+        return undefined;
+    }
+    #traceInputCoordination(event) {
+        this.#inputDiagnostics?.onEvent(event);
+    }
+    #traceRuntimePhase(phase) {
+        if (this.#inputDiagnostics === undefined)
+            return;
+        const coordinator = this.#inputCoordinator;
+        this.#inputDiagnostics.onEvent({
+            phase,
+            revision: coordinator?.appliedRevision ?? 0,
+            atMs: this.#diagnosticNow(),
+            pendingDepth: coordinator?.pendingDepth ?? 0,
+            pendingPresentationDepth: coordinator?.pendingPresentation === true ? 1 : 0,
+            appliedRevision: coordinator?.appliedRevision ?? 0,
+        });
+    }
+    #mountTui(tui) {
+        tui.addChild(this.#rootBridge);
+        if (tui instanceof TuiAltScreen && this.#layoutRoot !== undefined) {
+            tui.setLayoutRoot(this.#buildLayout(this.#layoutRoot));
+        }
+    }
+    #bridgeFor(component) {
+        if (component === null)
+            return null;
+        const bridge = this.#bridges.get(component);
+        if (!bridge)
+            throw new TypeError("Pi TUI focus target is not mounted");
+        return bridge;
+    }
+    #mount(component) {
+        const existing = this.#bridges.get(component);
+        if (existing)
+            return existing;
+        const bridge = new ComponentBridge(component);
+        this.#bridges.set(component, bridge);
+        this.#mountedComponents.add(component);
+        return bridge;
+    }
+    #buildLayout(node) {
+        if (node.type === "component")
+            return this.#mount(node.component);
+        if (node.type === "scroll") {
+            if (this.#scrollViews.has(node.id))
+                throw new TypeError(`duplicate Pi TUI scroll layout id: ${node.id}`);
+            const options = {
+                ...(node.follow === undefined ? {} : { follow: node.follow }),
+                ...(node.primary === undefined ? {} : { primary: node.primary }),
+                ...(node.overscroll === undefined ? {} : { overscroll: node.overscroll }),
+                ...(node.scrollbar === undefined ? {} : { scrollbar: node.scrollbar }),
+                ...(node.scrollbarTrackStyle === undefined ? {} : { scrollbarTrackStyle: node.scrollbarTrackStyle }),
+                ...(node.scrollbarThumbStyle === undefined ? {} : { scrollbarThumbStyle: node.scrollbarThumbStyle }),
+                ...(node.scrollbarHideDelayMs === undefined ? {} : { scrollbarHideDelayMs: node.scrollbarHideDelayMs }),
+            };
+            const scrollView = new ScrollView(this.#buildLayout(node.child), options);
+            this.#scrollViews.set(node.id, scrollView);
+            return scrollView;
+        }
+        const children = node.children.map(entry => ({
+            component: this.#buildLayout(entry.node),
+            ...(entry.basis === undefined ? {} : { basis: entry.basis }),
+            ...(entry.grow === undefined ? {} : { grow: entry.grow }),
+            ...(entry.shrink === undefined ? {} : { shrink: entry.shrink }),
+            ...(entry.minSize === undefined ? {} : { minSize: entry.minSize }),
+            ...(entry.maxSize === undefined ? {} : { maxSize: entry.maxSize }),
+            ...(entry.visible === undefined ? {} : { visible: (viewport) => entry.visible?.({ columns: viewport.width, rows: viewport.height }) ?? true }),
+        }));
+        const options = {
+            ...(node.gap === undefined ? {} : { gap: node.gap }),
+            ...(node.align === undefined ? {} : { align: node.align }),
+        };
+        return node.direction === "vertical" ? new VStack(children, options) : new HStack(children, options);
+    }
+    #requireFullscreen() {
+        if (!(this.#tui instanceof TuiAltScreen)) {
+            throw new Error("Pi TUI application scrolling is available only in fullscreen mode");
+        }
+        return this.#tui;
+    }
+    #requireScrollView(id) {
+        this.#requireFullscreen();
+        const scrollView = this.#scrollViews.get(id);
+        if (!scrollView)
+            throw new TypeError(`unknown Pi TUI scroll layout id: ${id}`);
+        return scrollView;
+    }
+    #assertRunning(operation) {
+        if (!this.active)
+            throw new Error(`Pi TUI ${operation} requires a running runtime`);
+    }
+    #restoreAfterFailedStart() {
+        this.#presentationFrozen = false;
+        try {
+            this.#tui.stop();
+        }
+        catch {
+            this.#bestEffortTerminalRestore();
+        }
+    }
+    #clearTerminalProgress() {
+        try {
+            this.#terminal.setProgress(false);
+        }
+        catch { }
+        this.#terminalProgress = false;
+    }
+    #bestEffortTerminalRestore() {
+        this.#presentationFrozen = false;
+        this.#clearTerminalProgress();
+        try {
+            if (this.mode === "fullscreen")
+                this.#terminal.write(EMERGENCY_TERMINAL_RESET);
+        }
+        catch { }
+        try {
+            this.#terminal.showCursor();
+        }
+        catch { }
+        try {
+            this.#terminal.stop();
+        }
+        catch { }
+    }
+    #disposeRoot() {
+        if (this.#rootDisposed)
+            return;
+        this.#rootDisposed = true;
+        for (const component of this.#mountedComponents)
+            component.dispose?.();
+        this.#mountedComponents.clear();
+    }
+    #disposeComponents() {
+        this.#inputCoordinator?.dispose(false);
+        this.#inputSink = undefined;
+        for (const remove of this.#inputListeners.values())
+            remove();
+        this.#inputListeners.clear();
+        this.#preInputListeners.clear();
+        for (const dispose of [...this.#overlayDisposers])
+            dispose();
+        this.#overlayInputCoordination.clear();
+        this.#disposeRoot();
+    }
+}
+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 => mouse === undefined ? coordinator.accept(data) : mouse.accept(data), () => {
+                coordinator.flush();
+                mouse?.reset();
+                onResize();
+            });
+        },
+        stop() {
+            coordinator.flush();
+            mouse?.reset();
+            setSink(undefined);
+            terminal.stop();
+        },
+        drainInput: (maxMs, idleMs) => terminal.drainInput(maxMs, idleMs),
+        write: data => terminal.write(data),
+        moveBy: lines => terminal.moveBy(lines),
+        hideCursor: () => terminal.hideCursor(),
+        showCursor: () => terminal.showCursor(),
+        clearLine: () => terminal.clearLine(),
+        clearFromCursor: () => terminal.clearFromCursor(),
+        clearScreen: () => terminal.clearScreen(),
+        setTitle: title => terminal.setTitle(title),
+        setProgress: active => terminal.setProgress(active),
+    };
+}
+function diagnosticTerminal(terminal, trace) {
+    return {
+        get columns() { return terminal.columns; },
+        get rows() { return terminal.rows; },
+        get kittyProtocolActive() { return terminal.kittyProtocolActive; },
+        start: (onInput, onResize) => terminal.start(onInput, onResize),
+        stop: () => terminal.stop(),
+        drainInput: (maxMs, idleMs) => terminal.drainInput(maxMs, idleMs),
+        write(data) {
+            trace("write-start");
+            try {
+                terminal.write(data);
+            }
+            finally {
+                trace("write-end");
+            }
+        },
+        moveBy: lines => terminal.moveBy(lines),
+        hideCursor: () => terminal.hideCursor(),
+        showCursor: () => terminal.showCursor(),
+        clearLine: () => terminal.clearLine(),
+        clearFromCursor: () => terminal.clearFromCursor(),
+        clearScreen: () => terminal.clearScreen(),
+        setTitle: title => terminal.setTitle(title),
+        setProgress: active => terminal.setProgress(active),
+    };
+}
+function frozenGateTerminal(terminal, frozen) {
+    return {
+        get columns() { return terminal.columns; },
+        get rows() { return terminal.rows; },
+        get kittyProtocolActive() { return terminal.kittyProtocolActive; },
+        start: (onInput, onResize) => terminal.start(onInput, onResize),
+        stop: () => terminal.stop(),
+        drainInput: (maxMs, idleMs) => terminal.drainInput(maxMs, idleMs),
+        write: data => { if (!frozen())
+            terminal.write(data); },
+        moveBy: lines => { if (!frozen())
+            terminal.moveBy(lines); },
+        hideCursor: () => { if (!frozen())
+            terminal.hideCursor(); },
+        showCursor: () => { if (!frozen())
+            terminal.showCursor(); },
+        clearLine: () => { if (!frozen())
+            terminal.clearLine(); },
+        clearFromCursor: () => { if (!frozen())
+            terminal.clearFromCursor(); },
+        clearScreen: () => { if (!frozen())
+            terminal.clearScreen(); },
+        setTitle: title => terminal.setTitle(title),
+        setProgress: active => terminal.setProgress(active),
+    };
+}
+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) {
+            const deliver = (data) => {
+                const routed = route(data);
+                if (routed.length > 0)
+                    onInput(routed);
+            };
+            mouse = frameMouse ? new MouseReportInput(deliver) : undefined;
+            terminal.start(data => mouse === undefined ? deliver(data) : mouse.accept(data), () => {
+                mouse?.reset();
+                onResize();
+            });
+        },
+        stop: () => { mouse?.reset(); terminal.stop(); },
+        drainInput: (maxMs, idleMs) => terminal.drainInput(maxMs, idleMs),
+        write: data => terminal.write(data),
+        moveBy: lines => terminal.moveBy(lines),
+        hideCursor: () => terminal.hideCursor(),
+        showCursor: () => terminal.showCursor(),
+        clearLine: () => terminal.clearLine(),
+        clearFromCursor: () => terminal.clearFromCursor(),
+        clearScreen: () => terminal.clearScreen(),
+        setTitle: title => terminal.setTitle(title),
+        setProgress: active => terminal.setProgress(active),
+    };
+}
+function toOverlayOptions(options) {
+    if (options === undefined)
+        return undefined;
+    const mapped = {};
+    if (options.width !== undefined)
+        mapped.width = options.width;
+    if (options.minWidth !== undefined)
+        mapped.minWidth = options.minWidth;
+    if (options.maxHeight !== undefined)
+        mapped.maxHeight = options.maxHeight;
+    if (options.anchor !== undefined)
+        mapped.anchor = options.anchor;
+    if (options.offsetX !== undefined)
+        mapped.offsetX = options.offsetX;
+    if (options.offsetY !== undefined)
+        mapped.offsetY = options.offsetY;
+    if (options.row !== undefined)
+        mapped.row = options.row;
+    if (options.col !== undefined)
+        mapped.col = options.col;
+    if (options.margin !== undefined)
+        mapped.margin = options.margin;
+    if (options.visible !== undefined)
+        mapped.visible = options.visible;
+    if (options.nonCapturing !== undefined)
+        mapped.nonCapturing = options.nonCapturing;
+    return mapped;
+}