tmux-ide 2.7.0 → 2.9.0-beta.5

package/packages/daemon/dist/tui/mirror/runtime/workspace-terminal-fast-lane.js

@@ -0,0 +1,498 @@
+import { createTerminalFastLane, createWorkspaceClientTerminalSource, } from "@tmux-ide/daemon-client/terminal-fast-lane";
+import { currentTuiPerformanceEventSink } from "../performance-events.js";
+const TERMINAL_RESOURCE_SAMPLE_LIMIT = 512;
+// The ProductRig idle proof reads after 10.1s. Emit just before that boundary
+// so the operation-scoped sample cannot race the proof read.
+const TERMINAL_RESOURCE_IDLE_MS = 10_000;
+const TERMINAL_RESOURCE_HEARTBEAT_MS = 16;
+const TERMINAL_RESOURCE_LOW_WATER_SAMPLES = 8;
+const TERMINAL_RESOURCE_LOW_WATER_INTERVAL_MS = 8;
+const TERMINAL_RESOURCE_IDLE_RETAINED_SAMPLES = 8;
+const TERMINAL_RESOURCE_IDLE_RETAINED_FIRST_MS = 2_000;
+const TERMINAL_RESOURCE_IDLE_RETAINED_INTERVAL_MS = 1_000;
+/**
+ * Bind one WorkspaceClient generation to one shared terminal fast lane. This
+ * adapter contains no authority state or replica state of its own.
+ */
+export function createOpenTuiWorkspaceTerminalFastLane(client, hostClientId, causalCellLedger = null) {
+    const target = client.getSnapshot().target;
+    if (target === null)
+        throw new Error("terminal fast lane requires a live workspace target");
+    const generation = target.daemon.instanceId;
+    const performanceSink = currentTuiPerformanceEventSink();
+    const lane = createTerminalFastLane({
+        address: { workspaceName: target.workspaceName, generation },
+        source: createWorkspaceClientTerminalSource(client),
+        repair: {
+            request: ({ address, reason }) => {
+                // The wire ACK is transport-admission only. A canonical reducer
+                // rejection retires this exact generation so its supervisor reconnects
+                // and obtains fresh seeds. TerminalFastLane coalesces requests until a
+                // seed arrives, preventing corrupt bursts from reconnect-storming.
+                client.requestTerminalRepair({ workspaceName: address.workspaceName, semanticPaneId: address.semanticPaneId }, address.generation, reason);
+            },
+        },
+        control: {
+            owns(authority, expectedGeneration) {
+                const snapshot = client.getSnapshot();
+                return (snapshot.target?.daemon.instanceId === expectedGeneration &&
+                    snapshot.authority?.generation === expectedGeneration &&
+                    client.ownsRuntimeAuthority?.(authority) === true);
+            },
+            async request(authority, expectedGeneration) {
+                const snapshot = client.getSnapshot();
+                if (snapshot.target?.daemon.instanceId !== expectedGeneration)
+                    return false;
+                const lease = await client.requestAuthority(authority);
+                return lease?.generation === expectedGeneration && lease.clientId === hostClientId;
+            },
+            write(address, input, performanceTraceId, causalProbe) {
+                return client.sendTerminalInput({
+                    workspaceName: address.workspaceName,
+                    semanticPaneId: address.semanticPaneId,
+                }, input, performanceTraceId, causalProbe);
+            },
+            resize(address, viewport) {
+                if (client.getSnapshot().target?.daemon.instanceId !== address.generation) {
+                    return Promise.resolve("authority-lost");
+                }
+                return client.fitViewport(viewport.cols, viewport.rows);
+            },
+        },
+        ...(performanceSink?.terminalTraceStage
+            ? {
+                onTraceStage(event) {
+                    try {
+                        performanceSink.terminalTraceStage?.({
+                            ...event,
+                            scenario: "terminal-input-to-paint",
+                            stage: "client",
+                            processId: `opentui:${process.pid}`,
+                            clockId: "opentui-performance-now",
+                            clockKind: "performance-now",
+                        });
+                    }
+                    catch {
+                        // Diagnostics cannot alter canonical delivery or input dispatch.
+                    }
+                },
+            }
+            : {}),
+    });
+    const resourceSink = performanceSink?.terminalResourceSample;
+    const resourceSampler = resourceSink
+        ? createOpenTuiTerminalResourceSampler(lane, resourceSink)
+        : null;
+    if (performanceSink?.terminalInputQueueState) {
+        try {
+            const counters = lane.counters();
+            const memory = process.memoryUsage();
+            performanceSink.terminalInputQueueState({
+                operation: "initialized",
+                processId: `opentui:${process.pid}`,
+                clockId: "opentui-performance-now",
+                clockKind: "performance-now",
+                atMicros: Math.floor(performance.now() * 1_000),
+                inputPending: counters.inputPending,
+                inputInFlight: counters.inputInFlight,
+                inputPendingBytes: counters.inputPendingBytes,
+                rssBytes: memory.rss,
+                heapUsedBytes: memory.heapUsed,
+            });
+        }
+        catch {
+            // Lifecycle diagnostics cannot prevent creation of the fresh lane.
+        }
+    }
+    return {
+        lane,
+        causalCellLedger,
+        resourceSampler,
+        dispose: () => {
+            resourceSampler?.dispose();
+            lane.dispose();
+        },
+    };
+}
+function createOpenTuiTerminalResourceSampler(lane, sink) {
+    const pending = new Set();
+    const idleSeriesTimers = new Set();
+    let idleTimer = null;
+    let heartbeatTimer = null;
+    let resourceSamplingFailureCount = 0;
+    const recordSamplingFailure = () => {
+        resourceSamplingFailureCount = Math.min(resourceSamplingFailureCount + 1, TERMINAL_RESOURCE_SAMPLE_LIMIT);
+    };
+    const readDiagnosticNow = () => {
+        try {
+            const now = performance.now();
+            if (!Number.isFinite(now) || now < 0)
+                throw new TypeError("invalid diagnostic clock");
+            return now;
+        }
+        catch {
+            recordSamplingFailure();
+            return null;
+        }
+    };
+    let heartbeatExpectedAt = (readDiagnosticNow() ?? 0) + TERMINAL_RESOURCE_HEARTBEAT_MS;
+    // Generation-lifetime maximum. An arbitrary intermediate/sibling fence must
+    // never consume the stall evidence needed by a later selected target.
+    let maxHeartbeatLatenessMs = 0;
+    let rssPeakBytes = 0;
+    let heapUsedPeakBytes = 0;
+    let inputPendingPeak = 0;
+    let inputInFlightPeak = 0;
+    let inputPendingBytesPeak = 0;
+    let eventLoopDelayPeakSource = "endpoint";
+    let latestIdentity = null;
+    let heartbeatExpectedWallMs = null;
+    let heartbeatCpu = null;
+    try {
+        heartbeatExpectedWallMs = Date.now() + TERMINAL_RESOURCE_HEARTBEAT_MS;
+        heartbeatCpu = process.cpuUsage();
+    }
+    catch {
+        // Optional attribution must never alter lane construction.
+    }
+    let heartbeatResourceUsage = (() => {
+        try {
+            return process.resourceUsage();
+        }
+        catch {
+            return null;
+        }
+    })();
+    let heartbeatPeakEpisode = null;
+    let resourceEpochIdentity = null;
+    let ordinal = 0;
+    let disposed = false;
+    const heartbeat = () => {
+        if (disposed)
+            return;
+        const now = readDiagnosticNow();
+        if (now !== null) {
+            const heartbeatLatenessMs = Math.max(now - heartbeatExpectedAt, 0);
+            let wallNow = null;
+            let cpuNow = null;
+            let resourceUsageNow = null;
+            try {
+                wallNow = Date.now();
+                cpuNow = process.cpuUsage();
+            }
+            catch {
+                // Attribution is optional evidence and never changes cap enforcement.
+            }
+            try {
+                resourceUsageNow = process.resourceUsage();
+            }
+            catch {
+                // Older/non-Node runtimes retain an explicit unavailable projection.
+            }
+            if (heartbeatLatenessMs > maxHeartbeatLatenessMs) {
+                maxHeartbeatLatenessMs = heartbeatLatenessMs;
+                eventLoopDelayPeakSource = "heartbeat";
+                heartbeatPeakEpisode = Object.freeze({
+                    expectedAtMicros: Math.max(0, Math.floor(heartbeatExpectedAt * 1_000)),
+                    actualAtMicros: Math.max(0, Math.floor(now * 1_000)),
+                    wallLatenessMicros: wallNow === null || heartbeatExpectedWallMs === null
+                        ? null
+                        : Math.max(0, Math.floor((wallNow - heartbeatExpectedWallMs) * 1_000)),
+                    cpuUserMicros: cpuNow && heartbeatCpu ? Math.max(0, cpuNow.user - heartbeatCpu.user) : null,
+                    cpuSystemMicros: cpuNow && heartbeatCpu ? Math.max(0, cpuNow.system - heartbeatCpu.system) : null,
+                    voluntaryContextSwitches: resourceUsageNow && heartbeatResourceUsage
+                        ? Math.max(0, resourceUsageNow.voluntaryContextSwitches -
+                            heartbeatResourceUsage.voluntaryContextSwitches)
+                        : null,
+                    involuntaryContextSwitches: resourceUsageNow && heartbeatResourceUsage
+                        ? Math.max(0, resourceUsageNow.involuntaryContextSwitches -
+                            heartbeatResourceUsage.involuntaryContextSwitches)
+                        : null,
+                    revision: latestIdentity?.revision ?? null,
+                    stateHash: latestIdentity?.stateHash ?? null,
+                });
+            }
+            if (cpuNow)
+                heartbeatCpu = cpuNow;
+            heartbeatResourceUsage = resourceUsageNow;
+            // Reschedule from actual time: missed ticks are summarized, never replayed.
+            heartbeatExpectedAt = now + TERMINAL_RESOURCE_HEARTBEAT_MS;
+            heartbeatExpectedWallMs = wallNow === null ? null : wallNow + TERMINAL_RESOURCE_HEARTBEAT_MS;
+        }
+        heartbeatTimer = setTimeout(heartbeat, TERMINAL_RESOURCE_HEARTBEAT_MS);
+        heartbeatTimer.unref?.();
+    };
+    heartbeatTimer = setTimeout(heartbeat, TERMINAL_RESOURCE_HEARTBEAT_MS);
+    heartbeatTimer.unref?.();
+    const emit = (operation, identity, expectedAt, sampled) => {
+        if (disposed || resourceEpochIdentity === null || ordinal >= TERMINAL_RESOURCE_SAMPLE_LIMIT)
+            return;
+        ordinal += 1;
+        const now = readDiagnosticNow();
+        if (now === null)
+            return;
+        let counters;
+        let memory;
+        try {
+            counters = sampled?.counters ?? lane.counters();
+            memory = sampled?.memory ?? process.memoryUsage();
+        }
+        catch {
+            recordSamplingFailure();
+            return;
+        }
+        const endpointLatenessMs = Math.max(now - expectedAt, 0);
+        try {
+            if (endpointLatenessMs > maxHeartbeatLatenessMs) {
+                maxHeartbeatLatenessMs = endpointLatenessMs;
+                eventLoopDelayPeakSource = "endpoint";
+                if (now === null)
+                    resourceSamplingFailureCount = 1;
+            }
+            rssPeakBytes = Math.max(rssPeakBytes, memory.rss);
+            heapUsedPeakBytes = Math.max(heapUsedPeakBytes, memory.heapUsed);
+            inputPendingPeak = Math.max(inputPendingPeak, counters.inputPending);
+            inputInFlightPeak = Math.max(inputInFlightPeak, counters.inputInFlight);
+            inputPendingBytesPeak = Math.max(inputPendingBytesPeak, counters.inputPendingBytes);
+            sink?.({
+                operation,
+                processId: `opentui:${process.pid}`,
+                clockId: "opentui-performance-now",
+                clockKind: "performance-now",
+                atMicros: Math.floor(now * 1_000),
+                ordinal,
+                resourceEpochArmed: true,
+                resourceEpochIdentity,
+                lowWaterFirstSampleOrdinal: 1,
+                lowWaterLastSampleOrdinal: sampled?.sampleCount ?? 1,
+                lowWaterSampleCount: sampled?.sampleCount ?? 1,
+                lowWaterWindowMicros: sampled?.windowMicros ?? 0,
+                semanticPaneId: identity.semanticPaneId,
+                generation: identity.generation,
+                incarnation: identity.incarnation,
+                revision: identity.revision,
+                stateHash: identity.stateHash,
+                sourceEpoch: identity.sourceEpoch,
+                rendererEpoch: identity.rendererEpoch,
+                viewportCols: identity.viewportCols,
+                viewportRows: identity.viewportRows,
+                inputPending: counters.inputPending,
+                inputInFlight: counters.inputInFlight,
+                inputPendingBytes: counters.inputPendingBytes,
+                inputPendingPeak,
+                inputInFlightPeak,
+                inputPendingBytesPeak,
+                rssBytes: memory.rss,
+                heapUsedBytes: memory.heapUsed,
+                eventLoopDelayMicros: Math.floor(endpointLatenessMs * 1_000),
+                rssPeakBytes,
+                heapUsedPeakBytes,
+                eventLoopDelayPeakMicros: Math.floor(maxHeartbeatLatenessMs * 1_000),
+                eventLoopDelayPeakSource,
+                heartbeatPeakExpectedAtMicros: heartbeatPeakEpisode?.expectedAtMicros ?? null,
+                heartbeatPeakActualAtMicros: heartbeatPeakEpisode?.actualAtMicros ?? null,
+                heartbeatPeakWallLatenessMicros: heartbeatPeakEpisode?.wallLatenessMicros ?? null,
+                heartbeatPeakCpuUserMicros: heartbeatPeakEpisode?.cpuUserMicros ?? null,
+                heartbeatPeakCpuSystemMicros: heartbeatPeakEpisode?.cpuSystemMicros ?? null,
+                heartbeatPeakVoluntaryContextSwitches: heartbeatPeakEpisode?.voluntaryContextSwitches ?? null,
+                heartbeatPeakInvoluntaryContextSwitches: heartbeatPeakEpisode?.involuntaryContextSwitches ?? null,
+                heartbeatPeakContextSwitchesAvailable: heartbeatPeakEpisode !== null &&
+                    Number.isSafeInteger(heartbeatPeakEpisode.voluntaryContextSwitches) &&
+                    Number.isSafeInteger(heartbeatPeakEpisode.involuntaryContextSwitches),
+                heartbeatPeakPhase: heartbeatPeakEpisode ? "terminal-runtime" : null,
+                heartbeatPeakRevision: heartbeatPeakEpisode?.revision ?? null,
+                heartbeatPeakStateHash: heartbeatPeakEpisode?.stateHash ?? null,
+                resourceSamplingFailureCount,
+                ...(sampled?.idleRetainedSamples
+                    ? { idleRetainedSamples: sampled.idleRetainedSamples }
+                    : {}),
+            });
+        }
+        catch {
+            // Sink/writer failures are fenced by writer health, not misclassified as
+            // resource construction failures. Diagnostics never own the lane.
+        }
+    };
+    const schedulePostFenceLowWater = (identity, expectedAt) => {
+        let remaining = TERMINAL_RESOURCE_LOW_WATER_SAMPLES;
+        let lowWaterExpectedAt = expectedAt;
+        let firstSampleAt = null;
+        let lastSampleAt = null;
+        let completedSamples = 0;
+        let lowWater;
+        const sample = () => {
+            if (disposed)
+                return;
+            try {
+                const sampledAt = readDiagnosticNow();
+                if (sampledAt !== null) {
+                    firstSampleAt ??= sampledAt;
+                    lastSampleAt = sampledAt;
+                }
+                const counters = lane.counters();
+                const memory = process.memoryUsage();
+                rssPeakBytes = Math.max(rssPeakBytes, memory.rss);
+                heapUsedPeakBytes = Math.max(heapUsedPeakBytes, memory.heapUsed);
+                inputPendingPeak = Math.max(inputPendingPeak, counters.inputPending);
+                inputInFlightPeak = Math.max(inputInFlightPeak, counters.inputInFlight);
+                inputPendingBytesPeak = Math.max(inputPendingBytesPeak, counters.inputPendingBytes);
+                if (!lowWater ||
+                    memory.heapUsed < lowWater.memory.heapUsed ||
+                    (memory.heapUsed === lowWater.memory.heapUsed && memory.rss < lowWater.memory.rss))
+                    lowWater = Object.freeze({ counters, memory });
+            }
+            catch {
+                recordSamplingFailure();
+            }
+            completedSamples += 1;
+            remaining -= 1;
+            if (remaining === 0) {
+                emit("post-fence", identity, lowWaterExpectedAt, lowWater
+                    ? Object.freeze({
+                        ...lowWater,
+                        sampleCount: completedSamples,
+                        windowMicros: firstSampleAt === null || lastSampleAt === null
+                            ? 0
+                            : Math.max(0, Math.floor((lastSampleAt - firstSampleAt) * 1_000)),
+                    })
+                    : undefined);
+                return;
+            }
+            lowWaterExpectedAt =
+                (readDiagnosticNow() ?? lowWaterExpectedAt) + TERMINAL_RESOURCE_LOW_WATER_INTERVAL_MS;
+            const timer = setTimeout(() => {
+                pending.delete(timer);
+                sample();
+            }, TERMINAL_RESOURCE_LOW_WATER_INTERVAL_MS);
+            pending.add(timer);
+            timer.unref?.();
+        };
+        sample();
+    };
+    return {
+        afterFence(identity) {
+            if (disposed || ordinal >= TERMINAL_RESOURCE_SAMPLE_LIMIT)
+                return;
+            latestIdentity = identity;
+            let now;
+            if (resourceEpochIdentity === null) {
+                resourceEpochIdentity = Object.freeze({ ...identity });
+                resourceSamplingFailureCount = 0;
+                maxHeartbeatLatenessMs = 0;
+                rssPeakBytes = 0;
+                heapUsedPeakBytes = 0;
+                inputPendingPeak = 0;
+                inputInFlightPeak = 0;
+                inputPendingBytesPeak = 0;
+                eventLoopDelayPeakSource = "endpoint";
+                heartbeatPeakEpisode = null;
+                if (heartbeatTimer)
+                    clearTimeout(heartbeatTimer);
+                // The epoch boundary precedes every diagnostic read. A clock failure
+                // at arm time therefore belongs to this epoch and remains sticky.
+                now = readDiagnosticNow();
+                heartbeatExpectedAt = (now ?? 0) + TERMINAL_RESOURCE_HEARTBEAT_MS;
+                heartbeatExpectedWallMs = null;
+                heartbeatCpu = null;
+                try {
+                    heartbeatExpectedWallMs = Date.now() + TERMINAL_RESOURCE_HEARTBEAT_MS;
+                    heartbeatCpu = process.cpuUsage();
+                    heartbeatResourceUsage = process.resourceUsage();
+                }
+                catch {
+                    heartbeatResourceUsage = null;
+                }
+                heartbeatTimer = setTimeout(heartbeat, TERMINAL_RESOURCE_HEARTBEAT_MS);
+                heartbeatTimer.unref?.();
+            }
+            else
+                now = readDiagnosticNow();
+            const expectedAt = now ?? heartbeatExpectedAt;
+            const timer = setTimeout(() => {
+                pending.delete(timer);
+                schedulePostFenceLowWater(identity, expectedAt);
+            }, 0);
+            pending.add(timer);
+            timer.unref?.();
+            if (idleTimer)
+                clearTimeout(idleTimer);
+            for (const timer of idleSeriesTimers)
+                clearTimeout(timer);
+            idleSeriesTimers.clear();
+            const idleExpectedAt = (readDiagnosticNow() ?? heartbeatExpectedAt) + TERMINAL_RESOURCE_IDLE_MS;
+            const idleRetainedSamples = [];
+            for (let index = 0; index < TERMINAL_RESOURCE_IDLE_RETAINED_SAMPLES; index += 1) {
+                const timer = setTimeout(() => {
+                    idleSeriesTimers.delete(timer);
+                    if (disposed || resourceEpochIdentity === null)
+                        return;
+                    try {
+                        const now = readDiagnosticNow();
+                        if (now === null)
+                            return;
+                        const counters = lane.counters();
+                        const memory = process.memoryUsage();
+                        rssPeakBytes = Math.max(rssPeakBytes, memory.rss);
+                        heapUsedPeakBytes = Math.max(heapUsedPeakBytes, memory.heapUsed);
+                        inputPendingPeak = Math.max(inputPendingPeak, counters.inputPending);
+                        inputInFlightPeak = Math.max(inputInFlightPeak, counters.inputInFlight);
+                        inputPendingBytesPeak = Math.max(inputPendingBytesPeak, counters.inputPendingBytes);
+                        idleRetainedSamples.push({
+                            ordinal: index + 1,
+                            atMicros: Math.floor(now * 1_000),
+                            rssBytes: memory.rss,
+                            heapUsedBytes: memory.heapUsed,
+                            inputPending: counters.inputPending,
+                            inputInFlight: counters.inputInFlight,
+                            inputPendingBytes: counters.inputPendingBytes,
+                        });
+                    }
+                    catch {
+                        recordSamplingFailure();
+                    }
+                }, TERMINAL_RESOURCE_IDLE_RETAINED_FIRST_MS +
+                    index * TERMINAL_RESOURCE_IDLE_RETAINED_INTERVAL_MS);
+                idleSeriesTimers.add(timer);
+                timer.unref?.();
+            }
+            idleTimer = setTimeout(() => {
+                idleTimer = null;
+                let counters;
+                let memory;
+                try {
+                    counters = lane.counters();
+                    memory = process.memoryUsage();
+                }
+                catch {
+                    recordSamplingFailure();
+                    return;
+                }
+                emit("idle", identity, idleExpectedAt, {
+                    counters,
+                    memory,
+                    sampleCount: 1,
+                    windowMicros: 0,
+                    idleRetainedSamples: Object.freeze(idleRetainedSamples.map((sample) => Object.freeze(sample))),
+                });
+            }, TERMINAL_RESOURCE_IDLE_MS);
+            idleTimer.unref?.();
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const timer of pending)
+                clearTimeout(timer);
+            pending.clear();
+            if (idleTimer)
+                clearTimeout(idleTimer);
+            idleTimer = null;
+            for (const timer of idleSeriesTimers)
+                clearTimeout(timer);
+            idleSeriesTimers.clear();
+            if (heartbeatTimer)
+                clearTimeout(heartbeatTimer);
+            heartbeatTimer = null;
+        },
+    };
+}

package/packages/daemon/dist/tui/mirror/scrollbar-model.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pure scrollbar geometry (M19.5) — shared by the editor viewport, the diff
+ * pane, and any scrolled mirror pane.
+ *
+ * A 1-col track at the right edge of an always-present container; the thumb's
+ * position and size are pure functions of (viewportTop, contentLen, viewH).
+ * Both the RENDER (draws the track cells) and the ROUTER (classifies a press as
+ * thumb vs track, maps a thumb drag to an absolute scroll top, pages a track
+ * click) read the SAME math from here — the surface-bar discipline applied to a
+ * vertical strip. Deliberately opentui-free so it unit-tests under Node.
+ */
+export interface ScrollThumb {
+    /** Whether the content overflows the viewport (nothing to scroll → hidden). */
+    overflow: boolean;
+    /** First track row (0-based, within [0, viewH)) the thumb occupies. */
+    start: number;
+    /** Thumb height in rows (≥1, ≤viewH). */
+    size: number;
+}
+/** The thumb geometry for a scroll position. `viewportTop` is the first visible
+ *  content line; `contentLen` the total lines; `viewH` the visible rows. When
+ *  the content fits, `overflow` is false and the caller draws no track. */
+export declare function scrollThumb(viewportTop: number, contentLen: number, viewH: number): ScrollThumb;
+/** Where a track row falls relative to the thumb — the fourth drag-origin's
+ *  press classifier and the page-click direction source. */
+export type TrackZone = "above" | "thumb" | "below";
+export declare function trackZone(row: number, thumb: ScrollThumb): TrackZone;
+/** Page the viewport toward a click at track `row` (above the thumb → up one
+ *  viewport, below → down one; on the thumb → unchanged), clamped to range. */
+export declare function pageTop(row: number, viewportTop: number, contentLen: number, viewH: number): number;
+/** Map a dragged thumb to an absolute scroll top. `trackRow` is the current
+ *  pointer row within the track; `grabOffset` is the row within the thumb where
+ *  the drag began (so the thumb doesn't jump under the cursor). Returns the new
+ *  first-visible line, clamped. */
+export declare function dragTop(trackRow: number, grabOffset: number, contentLen: number, viewH: number): number;

package/packages/daemon/dist/tui/mirror/scrollbar-model.js

@@ -0,0 +1,64 @@
+/**
+ * Pure scrollbar geometry (M19.5) — shared by the editor viewport, the diff
+ * pane, and any scrolled mirror pane.
+ *
+ * A 1-col track at the right edge of an always-present container; the thumb's
+ * position and size are pure functions of (viewportTop, contentLen, viewH).
+ * Both the RENDER (draws the track cells) and the ROUTER (classifies a press as
+ * thumb vs track, maps a thumb drag to an absolute scroll top, pages a track
+ * click) read the SAME math from here — the surface-bar discipline applied to a
+ * vertical strip. Deliberately opentui-free so it unit-tests under Node.
+ */
+/** The thumb size for a content/viewport pair — a viewport-fraction of the
+ *  track, floored at one cell so a thumb always exists. Shared by every
+ *  function below so their maths never drift. */
+function thumbSize(contentLen, viewH) {
+    return Math.max(1, Math.min(viewH, Math.round((viewH * viewH) / contentLen)));
+}
+/** The thumb geometry for a scroll position. `viewportTop` is the first visible
+ *  content line; `contentLen` the total lines; `viewH` the visible rows. When
+ *  the content fits, `overflow` is false and the caller draws no track. */
+export function scrollThumb(viewportTop, contentLen, viewH) {
+    if (viewH <= 0 || contentLen <= viewH) {
+        return { overflow: false, start: 0, size: Math.max(1, viewH) };
+    }
+    const size = thumbSize(contentLen, viewH);
+    const maxTop = contentLen - viewH;
+    const maxStart = viewH - size;
+    const top = Math.max(0, Math.min(maxTop, viewportTop));
+    const start = maxStart <= 0 ? 0 : Math.round((top / maxTop) * maxStart);
+    return { overflow: true, start: Math.max(0, Math.min(maxStart, start)), size };
+}
+export function trackZone(row, thumb) {
+    if (row < thumb.start)
+        return "above";
+    if (row >= thumb.start + thumb.size)
+        return "below";
+    return "thumb";
+}
+/** Page the viewport toward a click at track `row` (above the thumb → up one
+ *  viewport, below → down one; on the thumb → unchanged), clamped to range. */
+export function pageTop(row, viewportTop, contentLen, viewH) {
+    const thumb = scrollThumb(viewportTop, contentLen, viewH);
+    if (!thumb.overflow)
+        return viewportTop;
+    const maxTop = contentLen - viewH;
+    const zone = trackZone(row, thumb);
+    const next = zone === "above" ? viewportTop - viewH : zone === "below" ? viewportTop + viewH : viewportTop;
+    return Math.max(0, Math.min(maxTop, next));
+}
+/** Map a dragged thumb to an absolute scroll top. `trackRow` is the current
+ *  pointer row within the track; `grabOffset` is the row within the thumb where
+ *  the drag began (so the thumb doesn't jump under the cursor). Returns the new
+ *  first-visible line, clamped. */
+export function dragTop(trackRow, grabOffset, contentLen, viewH) {
+    if (viewH <= 0 || contentLen <= viewH)
+        return 0;
+    const size = thumbSize(contentLen, viewH);
+    const maxStart = viewH - size;
+    const maxTop = contentLen - viewH;
+    if (maxStart <= 0)
+        return 0;
+    const start = Math.max(0, Math.min(maxStart, trackRow - grabOffset));
+    return Math.round((start / maxStart) * maxTop);
+}

package/packages/daemon/dist/tui/mirror/search-model.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure, io-free math for scrollback search (M20.3) — the copy-mode `/` finder,
+ * app-native. app.tsx owns the search-session state machine + the io (reading a
+ * pane's `bufferLines`, driving scrollOffset); this module owns the arithmetic,
+ * unit-tested without a terminal exactly like selection.ts / diff-model.ts.
+ *
+ * A match is a (line, col) into the pane's full buffer (0 = oldest scrollback
+ * line). The render maps a match line to a visible row and inverse/accent-tints
+ * its [col, col+len) span; a jump converts a match line to a scrollOffset.
+ */
+/** One substring hit: `line` is the absolute buffer line, `col` the 0-based
+ *  character column of the match start on that line. */
+export interface SearchMatch {
+    line: number;
+    col: number;
+}
+/**
+ * Every case-insensitive substring occurrence of `query` across `lines`, in
+ * buffer order (top→bottom, left→right), one entry per occurrence (multiple per
+ * line allowed; non-overlapping — the scan advances past each hit). An empty
+ * query yields no matches.
+ */
+export declare function findMatches(lines: readonly string[], query: string): SearchMatch[];
+/**
+ * Matches in VISIT order — bottom-up (nearest the live viewport first), the
+ * order `/`-then-Enter lands on and n/N cycle through. So visit index 0 is the
+ * bottom-most match (shown as "1/N"), and `n` walks upward through the buffer.
+ * A fresh copy (does not mutate the input).
+ */
+export declare function visitOrder(matches: readonly SearchMatch[]): SearchMatch[];
+/** Cycle a match index by `dir` (+1 next / -1 prev) with wraparound; -1 stays
+ *  -1 when there are no matches. */
+export declare function stepMatch(current: number, dir: number, total: number): number;
+/**
+ * The scrollOffset (lines above the live viewport) that brings buffer `line`
+ * into view, positioned roughly at the middle of a `viewH`-row viewport, clamped
+ * to [0, depth]. `depth` is the scrollback budget (lines above the live top);
+ * the pane snapshot renders visible row `r` from buffer line `depth - offset + r`,
+ * so putting `line` at row `target` needs `offset = depth + target - line`.
+ */
+export declare function offsetForMatch(line: number, depth: number, viewH: number): number;