@code-yeongyu/senpi-tui 2026.9.12 → 2026.9.13-2

package/dist/tui.js

@@ -60,6 +60,41 @@ function extractKittyImageRows(line) {
 function isTermuxSession() {
     return Boolean(process.env.TERMUX_VERSION);
 }
+/**
+ * Dispatch an event to a component and retain the exact target and coordinate
+ * transform. Containers use this when forwarding events to nested children.
+ */
+export function dispatchMouseEvent(component, event) {
+    const result = component.handleMouse?.(event);
+    if (!result)
+        return undefined;
+    if ("target" in result)
+        return result;
+    if (!result.handled && !result.capture && !result.focus)
+        return undefined;
+    return {
+        ...result,
+        handled: true,
+        ...(result.focus ? { focusTarget: component } : {}),
+        target: {
+            component,
+            originX: event.screenX - event.x,
+            originY: event.screenY - event.y,
+            width: event.width,
+            height: event.height,
+        },
+    };
+}
+/** Recreate local coordinates for a previously dispatched mouse target. */
+export function retargetMouseEvent(event, target) {
+    return {
+        ...event,
+        x: event.screenX - target.originX,
+        y: event.screenY - target.originY,
+        width: target.width,
+        height: target.height,
+    };
+}
 /** Type guard to check if a component implements Focusable */
 export function isFocusable(component) {
     return component !== null && "focused" in component;
@@ -250,8 +285,31 @@ export class Container {
             child.invalidate?.();
         }
     }
+    handleMouse(event) {
+        if (event.y < 0 || event.y >= event.height)
+            return undefined;
+        const mouseChildren = this.mouseLayout?.width === event.width
+            ? this.mouseLayout.children
+            : this.children.map((component) => ({ component, height: component.render(event.width).length }));
+        let childY = 0;
+        for (const { component: child, height: childHeight } of mouseChildren) {
+            if (event.y >= childY && event.y < childY + childHeight) {
+                const result = dispatchMouseEvent(child, {
+                    ...event,
+                    y: event.y - childY,
+                    height: childHeight,
+                });
+                if (result?.focus && this.handleInput)
+                    return { ...result, focusTarget: this };
+                return result;
+            }
+            childY += childHeight;
+        }
+        return undefined;
+    }
     render(width) {
         const lines = [];
+        const mouseChildren = [];
         for (const child of this.children) {
             let childLines;
             try {
@@ -263,10 +321,12 @@ export class Container {
                 // Focus ownership stays unchanged; render containment must not steal or clear focus implicitly.
                 childLines = [`[render error: ${componentName}]`];
             }
+            mouseChildren.push({ component: child, height: childLines.length });
             for (const line of childLines) {
                 lines.push(line);
             }
         }
+        this.mouseLayout = { width, children: mouseChildren };
         return lines;
     }
 }
@@ -352,7 +412,15 @@ export class TuiBase extends Container {
         // Overlay stack for modal components rendered on top of base content
         this.focusOrderCounter = 0;
         this.overlayStack = [];
+        this.renderedOverlayLayouts = [];
         this.overlayFocusRestore = { status: "inactive" };
+        this.mouseLeases = new Map();
+        this.mouseBlockers = new Set();
+        this.placementEpoch = 0;
+        this.anchor = { kind: "unknown", epoch: 0, rows: 0, columns: 0 };
+        this.mouseCommittedLineCount = 0;
+        this.mouseAnchorPending = false;
+        this.mouseExternalWritePending = false;
         this.terminal = terminal;
         // Preserve existing positional boolean callers while allowing explicit render-policy overrides.
         const normalizedOptions = typeof options === "boolean" ? { showHardwareCursor: options } : (options ?? {});
@@ -362,6 +430,152 @@ export class TuiBase extends Container {
             this.showHardwareCursor = normalizedOptions.showHardwareCursor;
         }
     }
+    /** Host-owned intent. A replacement renderer starts with no leases. */
+    acquireMouseCapture(reason) {
+        const token = Symbol(reason);
+        const first = this.mouseLeases.size === 0;
+        this.mouseLeases.set(token, reason);
+        if (first) {
+            this.mouseWriteUnsubscribe ??= this.terminal.observeExternalWrites?.(() => {
+                this.placementEpoch++;
+                this.mouseExternalWritePending = true;
+            });
+            this.applyMouseTracking(this.mouseCaptureEnabled);
+            this.calibrateMouseAnchor();
+        }
+        return () => {
+            if (!this.mouseLeases.delete(token))
+                return;
+            if (this.mouseLeases.size === 0)
+                this.applyMouseTracking(false);
+        };
+    }
+    resetMouseCaptureState() {
+        this.mouseLeases.clear();
+        this.mouseBlockers.clear();
+        this.mouseWriteUnsubscribe?.();
+        this.mouseWriteUnsubscribe = undefined;
+        this.placementEpoch++;
+    }
+    get mouseCaptureEnabled() {
+        return this.mouseLeases.size > 0 && this.mouseBlockers.size === 0;
+    }
+    applyMouseTracking(_enabled) { }
+    getMouseLayoutRoots() {
+        return [...this.getMountedRoots(), ...this.renderedOverlayLayouts.map((layout) => layout.entry.component)];
+    }
+    setMouseBlocker(name, on) {
+        if (this.mouseBlockers.has(name) === on)
+            return;
+        if (on)
+            this.mouseBlockers.add(name);
+        else
+            this.mouseBlockers.delete(name);
+        this.placementEpoch++;
+        this.applyMouseTracking(this.mouseCaptureEnabled);
+    }
+    noteFullRender(clear) {
+        this.placementEpoch++;
+        this.anchor = {
+            kind: clear ? "cleared" : "unknown",
+            frameTopScreenRow: clear ? 0 : undefined,
+            epoch: this.placementEpoch,
+            rows: this.terminal.rows,
+            columns: this.terminal.columns,
+        };
+        this.mouseCommittedLineCount = this.previousLines.length;
+        this.noteCommittedMouseFrame();
+        this.calibrateMouseAnchor();
+    }
+    /** Called only after the renderer has published its geometry and bytes. */
+    noteCommittedMouseFrame() {
+        if (this.mouseCommittedLineCount !== this.previousLines.length)
+            this.placementEpoch++;
+        this.mouseCommittedLineCount = this.previousLines.length;
+        if (this.previousLines.some(isImageLine)) {
+            this.placementEpoch++;
+            this.anchor.kind = "unknown";
+            return;
+        }
+        if (this.previousLines.length >= this.terminal.rows) {
+            this.anchor = {
+                kind: "viewport",
+                epoch: this.placementEpoch,
+                rows: this.terminal.rows,
+                columns: this.terminal.columns,
+            };
+        }
+        else if (this.anchor.epoch !== this.placementEpoch ||
+            this.anchor.rows !== this.terminal.rows ||
+            this.anchor.columns !== this.terminal.columns) {
+            this.anchor = {
+                kind: "unknown",
+                epoch: this.placementEpoch,
+                rows: this.terminal.rows,
+                columns: this.terminal.columns,
+            };
+        }
+    }
+    /** Never block a frame on terminal protocol negotiation or a missing reply. */
+    calibrateMouseAnchor() {
+        if (!this.mouseCaptureEnabled ||
+            this.stopped ||
+            this.mouseAnchorPending ||
+            this.mouseExternalWritePending ||
+            !this.terminal.queryCursorPosition ||
+            this.previousLines.length === 0 ||
+            this.previousLines.some(isImageLine))
+            return;
+        if (this.anchor.kind !== "unknown" &&
+            this.anchor.epoch === this.placementEpoch &&
+            this.anchor.rows === this.terminal.rows &&
+            this.anchor.columns === this.terminal.columns)
+            return;
+        const epoch = this.placementEpoch;
+        const rows = this.terminal.rows;
+        const columns = this.terminal.columns;
+        const hardwareCursorRow = this.hardwareCursorRow;
+        const lineCount = this.previousLines.length;
+        this.mouseAnchorPending = true;
+        void this.terminal.queryCursorPosition().then((position) => {
+            this.mouseAnchorPending = false;
+            if (!position ||
+                this.stopped ||
+                !this.mouseCaptureEnabled ||
+                epoch !== this.placementEpoch ||
+                rows !== this.terminal.rows ||
+                columns !== this.terminal.columns ||
+                hardwareCursorRow !== this.hardwareCursorRow ||
+                lineCount !== this.previousLines.length)
+                return;
+            const top = position.row - 1 - hardwareCursorRow;
+            if (!Number.isSafeInteger(top) ||
+                top < 0 ||
+                top + lineCount > rows ||
+                !Number.isSafeInteger(position.column) ||
+                position.column < 1 ||
+                // Some emulators report the pending-wrap cell just past the right edge.
+                position.column > columns + 1 ||
+                (position.page !== undefined && position.page !== 1))
+                return;
+            this.anchor = { kind: "cpr", frameTopScreenRow: top, epoch, rows, columns };
+        });
+    }
+    /** Input rows are one-based; the returned committed frame line is zero-based. */
+    resolveFrameLine(screenRow) {
+        const anchor = this.anchor;
+        if (anchor.kind === "unknown" ||
+            anchor.epoch !== this.placementEpoch ||
+            anchor.rows !== this.terminal.rows ||
+            anchor.columns !== this.terminal.columns ||
+            screenRow < 1 ||
+            screenRow > anchor.rows)
+            return undefined;
+        const line = anchor.kind === "viewport"
+            ? this.previousViewportTop + screenRow - 1
+            : screenRow - 1 - (anchor.frameTopScreenRow ?? 0);
+        return line >= 0 && line < this.previousLines.length ? line : undefined;
+    }
     resetRenderState() { }
     beforeTerminalStart() { }
     afterTerminalStart() { }
@@ -387,8 +601,8 @@ export class TuiBase extends Container {
     }
     /**
      * Set whether to trigger full re-render when content shrinks.
-     * When true (default), empty rows are cleared when content shrinks.
-     * When false, empty rows remain (reduces redraws on slower terminals).
+     * When true, empty rows are cleared when content shrinks.
+     * When false (default), empty rows remain (reduces redraws on slower terminals).
      */
     setClearOnShrink(enabled) {
         this.clearOnShrink = enabled;
@@ -608,6 +822,11 @@ export class TuiBase extends Container {
                 this.requestRender();
             },
             isFocused: () => this.focusedComponent === component,
+            getBounds: () => {
+                if (!this.overlayStack.includes(entry) || !this.isOverlayVisible(entry) || !entry.bounds)
+                    return undefined;
+                return { ...entry.bounds };
+            },
         };
     }
     /** Hide the topmost overlay and restore previous focus. */
@@ -635,6 +854,42 @@ export class TuiBase extends Container {
     isOverlayFocused() {
         return this.overlayStack.some((entry) => entry.component === this.focusedComponent && this.isOverlayVisible(entry));
     }
+    /** Keep overlay containers as keyboard focus owners when a nested control is clicked. */
+    resolveMouseFocusTarget(component) {
+        for (let index = this.overlayStack.length - 1; index >= 0; index--) {
+            const overlay = this.overlayStack[index];
+            if (this.isOverlayVisible(overlay) && this.containsComponent(overlay.component, component)) {
+                return overlay.component;
+            }
+        }
+        return component;
+    }
+    /** Dispatch to the visually topmost overlay under the pointer. */
+    dispatchMouseToOverlay(event) {
+        for (let index = this.renderedOverlayLayouts.length - 1; index >= 0; index--) {
+            const layout = this.renderedOverlayLayouts[index];
+            if (event.screenX < layout.col ||
+                event.screenX >= layout.col + layout.width ||
+                event.screenY < layout.row ||
+                event.screenY >= layout.row + layout.height) {
+                continue;
+            }
+            const result = dispatchMouseEvent(layout.entry.component, {
+                ...event,
+                x: event.screenX - layout.col,
+                y: event.screenY - layout.row,
+                width: layout.width,
+                height: layout.height,
+            });
+            return result
+                ? {
+                    hit: true,
+                    result: result.focus ? { ...result, focusTarget: layout.entry.component } : result,
+                }
+                : { hit: true };
+        }
+        return { hit: false };
+    }
     /** Check if an overlay entry is currently visible */
     isOverlayVisible(entry) {
         if (entry.hidden)
@@ -721,6 +976,7 @@ export class TuiBase extends Container {
             this.terminal.write("\x1b[?2031l");
         }
         this.beforeTerminalStop(options);
+        this.resetMouseCaptureState();
         // Move cursor to the end of the content to prevent overwriting/artifacts on exit.
         // Skipped when the screen is preserved for another renderer taking over this terminal.
         if (!options.preserveScreen && this.previousLines.length > 0) {
@@ -1129,9 +1385,13 @@ export class TuiBase extends Container {
     }
     /** Composite all overlays into content lines (sorted by focusOrder, higher = on top). */
     compositeOverlays(lines, termWidth, termHeight) {
-        if (this.overlayStack.length === 0)
+        if (this.overlayStack.length === 0) {
+            this.renderedOverlayLayouts = [];
             return lines;
+        }
         const result = [...lines];
+        for (const entry of this.overlayStack)
+            entry.bounds = undefined;
         // Pre-render all visible overlays and calculate positions
         const rendered = [];
         let minLinesNeeded = result.length;
@@ -1150,9 +1410,17 @@ export class TuiBase extends Container {
             }
             // Get final row/col with actual overlay height
             const { row, col } = this.resolveOverlayLayout(options, overlayLines.length, termWidth, termHeight);
-            rendered.push({ overlayLines, row, col, w: width });
+            entry.bounds = { row, col, width, height: overlayLines.length };
+            rendered.push({ entry, overlayLines, row, col, w: width });
             minLinesNeeded = Math.max(minLinesNeeded, row + overlayLines.length);
         }
+        this.renderedOverlayLayouts = rendered.map(({ entry, row, col, w, overlayLines }) => ({
+            entry,
+            row,
+            col,
+            width: w,
+            height: overlayLines.length,
+        }));
         // Pad to at least terminal height so overlays have screen-relative positions.
         // Excludes maxLinesRendered: the historical high-water mark caused self-reinforcing
         // inflation that pushed content into scrollback on terminal widen.
@@ -1435,6 +1703,7 @@ export class TuiBase extends Container {
         this.previousKittyImageIds = this.collectKittyImageIds(newLines);
         this.previousWidth = width;
         this.previousHeight = height;
+        this.placementEpoch++;
     }
     renderScrollbackReplay(newLines, rawLines, cursorPos, width, height, prevViewportTop, hardwareCursorRow) {
         let buffer = TUI.FRAME_BEGIN;
@@ -1462,6 +1731,7 @@ export class TuiBase extends Container {
         this.previousKittyImageIds = this.collectKittyImageIds(newLines);
         this.previousWidth = width;
         this.previousHeight = height;
+        this.placementEpoch++;
     }
     renderMuxViewportRepaint(newLines, rawLines, cursorPos, width, height, viewportTop = Math.max(0, newLines.length - height)) {
         const previousVisible = this.getViewportRows(this.previousLines, this.previousViewportTop, height);
@@ -1491,6 +1761,7 @@ export class TuiBase extends Container {
         this.previousKittyImageIds = this.collectKittyImageIds(newLines);
         this.previousWidth = width;
         this.previousHeight = height;
+        this.placementEpoch++;
         return true;
     }
     /** Splice overlay content into a base line at a specific column. Single-pass optimized. */
@@ -1581,6 +1852,8 @@ export class TuiBase extends Container {
         const height = this.terminal.rows;
         const widthChanged = this.previousWidth !== 0 && this.previousWidth !== width;
         const heightChanged = this.previousHeight !== 0 && this.previousHeight !== height;
+        if (widthChanged || heightChanged)
+            this.placementEpoch++;
         const previousBufferLength = this.previousHeight > 0 ? this.previousViewportTop + this.previousHeight : height;
         let prevViewportTop = heightChanged ? Math.max(0, previousBufferLength - height) : this.previousViewportTop;
         let viewportTop = prevViewportTop;
@@ -1651,6 +1924,7 @@ export class TuiBase extends Container {
             this.previousKittyImageIds = this.collectKittyImageIds(newLines);
             this.previousWidth = width;
             this.previousHeight = height;
+            this.noteFullRender(clear);
         };
         const debugRedraw = process.env.PI_DEBUG_REDRAW === "1";
         const logRedraw = (reason) => {