@floegence/floeterm-terminal-web 0.16.3 → 0.16.5

package/dist/semantic/HistoryViewportController.js

@@ -1,49 +1,23 @@
-import { isStructuralSemanticHistoryError, SemanticHistoryError, validateHistoryViewport, } from './presentation.js';
+import { isStructuralSemanticHistoryError, SemanticHistoryError, validateHistoryWindow, validateHistoryViewport, } from './presentation.js';
 import { runSemanticHistoryRequest } from './historyRequestScheduler.js';
-const MAX_HISTORY_CACHE_BYTES = 4 * 1024 * 1024;
-const MAX_GLOBAL_HISTORY_CACHE_BYTES = 16 * 1024 * 1024;
-const globalHistoryCache = new class {
-    constructor() {
-        this.entries = new Map();
-        this.nextOwner = 0;
-    }
-    owner() {
-        this.nextOwner += 1;
-        return this.nextOwner;
-    }
-    put(entry) {
-        this.entries.set(this.entryKey(entry.owner, entry.key), entry);
-        this.enforce();
-    }
-    remove(owner, key) {
-        this.entries.delete(this.entryKey(owner, key));
-    }
-    clear(owner) {
-        for (const [key, entry] of this.entries) {
-            if (entry.owner === owner)
-                this.entries.delete(key);
-        }
-    }
-    enforce() {
-        let total = [...this.entries.values()].reduce((sum, entry) => sum + entry.bytes, 0);
-        while (total > MAX_GLOBAL_HISTORY_CACHE_BYTES) {
-            const candidate = [...this.entries.values()]
-                .filter(entry => entry.evictable())
-                .sort((left, right) => Number(right.hidden()) - Number(left.hidden()) || left.touched - right.touched)[0];
-            if (!candidate)
-                return;
-            candidate.evict();
-            total = [...this.entries.values()].reduce((sum, entry) => sum + entry.bytes, 0);
-        }
-    }
-    entryKey(owner, key) {
-        return `${owner}:${key}`;
-    }
-}();
+function emitSemanticDebugTrace(event) {
+    const target = globalThis;
+    target.__floetermSemanticTrace?.(event);
+}
+// History is owned by a single terminal session. Keep the budget local to the
+// controller so one busy session cannot evict another session's history.
+const MAX_SESSION_HISTORY_CACHE_BYTES = 4 * 1024 * 1024;
+const HISTORY_WINDOW_CACHE_TARGET_BYTES = Math.floor(MAX_SESSION_HISTORY_CACHE_BYTES * 0.85);
+const HISTORY_WINDOW_BASE_MULTIPLIER = 10;
+const HISTORY_WINDOW_FAST_MULTIPLIER = 20;
+const HISTORY_WINDOW_MAX_ROWS = 4000;
+const HISTORY_SCROLL_BURST_GAP_MS = 250;
+const HISTORY_SCROLL_BURST_DECAY_MS = 500;
+const HISTORY_SCROLL_BURST_VIEWPORTS = 2;
+const HISTORY_WINDOW_FORWARD_BIAS = 0.7;
 export class HistoryViewportController {
     constructor(options) {
         this.options = options;
-        this.cacheOwner = globalHistoryCache.owner();
         this.latest = null;
         this.visible = null;
         this.frontier = null;
@@ -51,23 +25,28 @@ export class HistoryViewportController {
         this.cacheBytes = 0;
         this.historyAnchor = null;
         this.desiredOffset = null;
-        this.prefetchOffset = null;
         this.lane = null;
         this.epoch = 0;
         this.transportGeneration = null;
         this.touch = 0;
         this.disposed = false;
-        this.viewVisible = true;
         this.error = null;
         this.wheelResidualRows = 0;
         this.wheelFrame = null;
-        this.lastDirection = 0;
+        this.handlingWheelFrame = false;
+        this.preferExactViewport = false;
+        this.scrollDirection = 0;
+        this.scrollBurstDirection = 0;
+        this.scrollBurstRows = 0;
+        this.scrollBurstAt = 0;
+        this.estimatedHistoryRowBytes = 0;
         this.requestFrame = options.requestAnimationFrame
             ?? globalThis.requestAnimationFrame?.bind(globalThis)
             ?? (callback => globalThis.setTimeout(() => callback(performance.now()), 0));
         this.cancelFrame = options.cancelAnimationFrame
             ?? globalThis.cancelAnimationFrame?.bind(globalThis)
             ?? (handle => globalThis.clearTimeout(handle));
+        this.now = options.now ?? (() => performance.now());
     }
     apply(presentation) {
         if (this.disposed)
@@ -88,9 +67,8 @@ export class HistoryViewportController {
         const rows = Math.trunc(deltaRows);
         if (rows === 0)
             return;
-        const current = this.desiredOffset ?? this.visible?.offset ?? this.latest.frame.history.screenStartOffset;
+        const current = this.currentIntentOffset();
         const target = clamp(current + rows, 0, this.latest.frame.history.screenStartOffset);
-        this.lastDirection = rows < 0 ? -1 : 1;
         this.showOffset(target);
     }
     handleWheel(delta, deltaMode) {
@@ -103,63 +81,109 @@ export class HistoryViewportController {
                 ? delta * viewportRows
                 : delta / this.options.renderer.getCellMetrics().cellHeightCssPx;
         this.wheelResidualRows += rows;
+        if (Math.abs(rows) >= viewportRows)
+            this.preferExactViewport = true;
         if (this.wheelFrame !== null)
             return;
         this.wheelFrame = this.requestFrame(() => {
             this.wheelFrame = null;
-            const wholeRows = this.wheelResidualRows < 0
-                ? Math.ceil(this.wheelResidualRows)
-                : Math.floor(this.wheelResidualRows);
-            this.wheelResidualRows -= wholeRows;
-            this.scrollByRows(wholeRows);
+            this.handlingWheelFrame = true;
+            try {
+                const wholeRows = this.wheelResidualRows < 0
+                    ? Math.ceil(this.wheelResidualRows)
+                    : Math.floor(this.wheelResidualRows);
+                this.wheelResidualRows -= wholeRows;
+                this.scrollByRows(wholeRows);
+            }
+            finally {
+                this.handlingWheelFrame = false;
+            }
         });
     }
     showStart() {
-        this.lastDirection = -1;
         this.showOffset(0);
     }
     showLatest() {
         if (!this.latest || this.disposed)
             return;
+        // Invalidate any history request that was started before returning to the
+        // live frontier. Its response must never re-enter the visible surface.
+        this.epoch += 1;
         this.desiredOffset = null;
-        this.prefetchOffset = null;
+        this.preferExactViewport = false;
         this.visible = null;
-        this.frontier = null;
-        this.clearCache();
-        this.historyAnchor = null;
         this.error = null;
-        this.options.renderer.project(null);
+        this.projectFrame(null);
+        this.evictCache();
         this.emitState();
     }
     showOffset(offset) {
         if (!this.latest || this.disposed || !Number.isFinite(offset))
             return;
         const target = clamp(Math.trunc(offset), 0, this.latest.frame.history.screenStartOffset);
+        const current = this.currentIntentOffset();
+        this.recordScrollIntent(target - current);
+        emitSemanticDebugTrace({ kind: 'history-cache-check', at: performance.now(), target,
+            frontierOffset: this.frontier?.offset ?? null, frontierRows: this.frontier?.rows ?? null,
+            cacheEntries: this.cache.size, cacheBytes: this.cacheBytes,
+            cacheExtraBytes: this.cacheExtraBytes() });
         if (target === this.latest.frame.history.screenStartOffset) {
             this.showLatest();
             return;
         }
         const cached = this.findCachedViewport(target);
-        if (cached && this.isCompatible(cached)) {
+        if (cached) {
             this.desiredOffset = null;
             this.display(cached);
             return;
         }
+        // The active frontier is the hottest window. Keep it usable even if the
+        // bounded LRU has evicted its map entry between adjacent wheel frames.
+        const frontierWindow = this.frontier;
+        if (frontierWindow && this.isReusableWindow(frontierWindow, target, this.latest.geometry.rows)) {
+            this.desiredOffset = null;
+            this.display(sliceHistoryWindow(frontierWindow, target, this.latest.geometry.rows));
+            return;
+        }
+        const window = this.findCachedWindow(target, this.latest.geometry.rows);
+        if (window) {
+            this.desiredOffset = null;
+            this.putCache(window);
+            this.display(sliceHistoryWindow(window, target, this.latest.geometry.rows));
+            return;
+        }
         this.desiredOffset = target;
         this.error = null;
         this.startLane();
         this.emitState();
     }
-    setVisible(visible) {
-        if (this.disposed || this.viewVisible === visible)
-            return;
-        this.viewVisible = visible;
-        if (!visible) {
-            this.prefetchOffset = null;
-            this.evictCache(true);
+    currentIntentOffset() {
+        if (!this.latest)
+            return 0;
+        const liveOffset = this.latest.frame.history.screenStartOffset;
+        if (this.desiredOffset !== null)
+            return clamp(this.desiredOffset, 0, liveOffset);
+        if (!this.visible)
+            return liveOffset;
+        // A bounded runtime scrollback may evict old rows while an immutable
+        // history snapshot remains visible. Its old absolute offset can then sit
+        // beyond the new live frontier. Preserve the viewport's distance from the
+        // tail before applying the next user delta; clamping the stale absolute
+        // coordinate directly would incorrectly jump the user back to live.
+        if (this.visible.screenStartOffset > liveOffset) {
+            const distanceFromLive = this.visible.screenStartOffset - this.visible.offset;
+            return clamp(liveOffset - distanceFromLive, 0, liveOffset);
         }
-        else if (this.visible)
-            this.schedulePrefetch(this.visible);
+        return clamp(this.visible.offset, 0, liveOffset);
+    }
+    setVisible(_visible) {
+        if (this.disposed)
+            return;
+        // Keep this session's bounded history cache warm while another workbench
+        // view is active. Every reuse still passes the live revision, content,
+        // geometry, and transport-generation checks; retaining the immutable
+        // window therefore removes the first-scroll cold RPC without permitting
+        // stale terminal content to be projected after returning to this view.
     }
     reset() {
         if (this.disposed)
@@ -204,7 +228,6 @@ export class HistoryViewportController {
             throw new SemanticHistoryError('snapshot_superseded', 'semantic history viewport does not match the live surface');
         }
         this.desiredOffset = null;
-        this.prefetchOffset = null;
         this.frontier = null;
         this.clearCache();
         this.historyAnchor = null;
@@ -231,7 +254,6 @@ export class HistoryViewportController {
         this.visible = null;
         this.frontier = null;
         this.desiredOffset = null;
-        this.prefetchOffset = null;
     }
     startLane() {
         if (this.lane || this.disposed)
@@ -240,38 +262,56 @@ export class HistoryViewportController {
         this.lane = this.runLane(epoch).finally(() => {
             this.lane = null;
             this.emitState();
-            if (!this.disposed && (this.desiredOffset !== null || this.prefetchOffset !== null))
+            if (!this.disposed && this.desiredOffset !== null)
                 this.startLane();
         });
     }
     async runLane(epoch) {
-        let activeWasPrefetch = false;
         try {
             while (!this.disposed && this.epoch === epoch) {
-                const target = this.desiredOffset ?? this.prefetchOffset;
-                const isPrefetch = this.desiredOffset === null && this.prefetchOffset !== null;
-                activeWasPrefetch = isPrefetch;
+                const target = this.desiredOffset;
                 if (target === null)
                     return;
-                if (isPrefetch)
-                    this.prefetchOffset = null;
                 const cached = this.findCachedViewport(target);
-                if (cached && this.isCompatible(cached)) {
-                    if (!isPrefetch && this.desiredOffset === target) {
+                if (cached) {
+                    const isCurrentTarget = this.desiredOffset === target;
+                    const desiredOffset = this.desiredOffset;
+                    if (isCurrentTarget) {
                         this.desiredOffset = null;
+                    }
+                    // A completed, validated viewport is still useful while a newer
+                    // wheel target is in flight, but only while it moves toward that
+                    // target. Never project an older response after a direction change.
+                    if (isCurrentTarget || this.shouldDisplayIntermediate(cached.offset, desiredOffset)) {
                         this.display(cached);
                     }
                     continue;
                 }
+                const cachedWindow = this.findCachedWindow(target, this.latest?.geometry.rows ?? 0);
+                if (cachedWindow && this.latest) {
+                    const isCurrentTarget = this.desiredOffset === target;
+                    const desiredOffset = this.desiredOffset;
+                    if (isCurrentTarget) {
+                        this.desiredOffset = null;
+                    }
+                    this.putCache(cachedWindow);
+                    const viewport = sliceHistoryWindow(cachedWindow, target, this.latest.geometry.rows);
+                    if (isCurrentTarget || this.shouldDisplayIntermediate(viewport.offset, desiredOffset)) {
+                        this.display(viewport);
+                    }
+                    continue;
+                }
                 const viewport = await this.fetchOffset(target);
                 if (this.disposed || this.epoch !== epoch)
                     return;
-                this.frontier = viewport;
                 this.cacheViewport(viewport);
-                if (!isPrefetch && this.desiredOffset === target) {
+                const isCurrentTarget = this.desiredOffset === target;
+                const desiredOffset = this.desiredOffset;
+                if (isCurrentTarget) {
                     this.desiredOffset = null;
+                }
+                if (isCurrentTarget || this.shouldDisplayIntermediate(viewport.offset, desiredOffset)) {
                     this.display(viewport);
-                    this.schedulePrefetch(viewport);
                 }
             }
         }
@@ -281,61 +321,231 @@ export class HistoryViewportController {
             this.error = cause instanceof Error ? cause : new Error(String(cause));
             this.frontier = null;
             this.desiredOffset = null;
-            this.prefetchOffset = null;
-            if (activeWasPrefetch)
-                this.error = null;
-            else if (isStructuralSemanticHistoryError(this.error))
+            if (isStructuralSemanticHistoryError(this.error))
                 this.resetHistory(true, this.error);
         }
     }
     async fetchOffset(target) {
+        try {
+            return await this.fetchOffsetAttempt(target);
+        }
+        catch (cause) {
+            if (!isRecoverableHistoryLineageError(cause))
+                throw cause;
+            this.frontier = null;
+            this.clearCache();
+            this.historyAnchor = null;
+            return await this.fetchOffsetAttempt(this.desiredOffset ?? target);
+        }
+    }
+    async fetchOffsetAttempt(target) {
         if (!this.latest)
             throw new Error('terminal history requires a live Presentation');
         const rows = this.latest.geometry.rows;
+        const totalRows = this.latest.frame.history.totalRows;
+        const revision = this.latest.frame.history.revision;
+        const preferExactViewport = this.preferExactViewport;
+        // A large wheel delta needs one exact target request, but must not poison
+        // the rest of the session. Subsequent small deltas should use a reusable
+        // history window again.
+        this.preferExactViewport = false;
+        const windowRows = preferExactViewport ? rows : this.adaptiveWindowRows(rows, totalRows);
+        if (windowRows <= rows)
+            return this.fetchExactFromBoundary(target, rows);
+        const cachedWindow = this.findCachedWindow(target, rows);
+        if (cachedWindow)
+            return sliceHistoryWindow(cachedWindow, target, rows);
         let frontier = this.frontier;
-        if (!frontier || !this.isCompatible(frontier)) {
-            frontier = validateHistoryViewport(await runSemanticHistoryRequest(() => this.options.request({
-                lane: 'viewport',
-                direction: target === 0 ? 'start' : 'end',
-                viewportRows: rows,
-            })));
-            this.assertTransportGeneration(frontier);
-            this.acceptLineage(frontier, true);
+        if (frontier && (frontier.revision !== revision || frontier.totalRows !== totalRows)) {
+            this.frontier = null;
+            frontier = null;
+        }
+        if (!frontier || !this.isReusableWindow(frontier, target, rows)) {
+            frontier = await this.fetchWindow(target, rows, windowRows);
+        }
+        if (frontier.window !== true)
+            return frontier;
+        return sliceHistoryWindow(frontier, target, rows);
+    }
+    async fetchExactFromBoundary(target, rows) {
+        // A boundary request already supports exact targeting in one RPC and
+        // atomically establishes its own native lineage. Reusing an old exact
+        // frontier offers no round-trip saving, but it opens a race where live
+        // output evicts the anchor after the client checks its revision and before
+        // the runtime processes the anchored request.
+        const frontier = validateHistoryViewport(await this.fetchBoundary(target === 0 ? 'start' : 'end', target, rows));
+        this.assertTransportGeneration(frontier);
+        this.acceptLineage(frontier, true);
+        this.frontier = frontier;
+        return this.fetchExactOffset(frontier, target, rows);
+    }
+    async fetchExactOffset(frontier, target, rows) {
+        if (frontier.offset === target)
+            return frontier;
+        const direction = target < frontier.offset ? 'backward' : 'forward';
+        const next = validateHistoryViewport(await runSemanticHistoryRequest(() => this.options.request({
+            lane: 'viewport',
+            direction,
+            anchor: frontier.anchor,
+            snapshotId: frontier.snapshotId,
+            offset: frontier.offset,
+            targetOffset: target,
+            viewportRows: rows,
+        })));
+        this.assertTransportGeneration(next);
+        this.acceptLineage(next);
+        this.frontier = next;
+        return next;
+    }
+    async fetchWindow(target, rows, windowRows) {
+        const windowStart = this.windowStart(target, rows, windowRows, this.scrollDirection);
+        let current = this.frontier;
+        if (current && this.isCompatibleWindow(current)
+            && current.offset === windowStart && !this.isReusableWindow(current, target, rows)) {
+            current = null;
+        }
+        if (!current || !this.isCompatibleWindow(current)) {
+            // A start/end boundary request always replaces the server-side view for
+            // this lane and therefore always establishes a new anchor. This is also
+            // how an exact viewport is upgraded to a reusable window. Clear every
+            // cache entry from the old lineage before accepting that replacement.
+            const allowLineageReplacement = true;
+            const response = await this.fetchBoundary(target === 0 ? 'start' : 'end', windowStart, windowRows, rows);
+            // Keep the old exact-viewport contract as a fallback for older runtimes
+            // while the fast-debug runtime is being rolled out.
+            if (response.window !== true) {
+                current = validateHistoryViewport(response);
+                this.assertTransportGeneration(current);
+                this.acceptLineage(current, allowLineageReplacement);
+                this.frontier = current;
+                return this.fetchExactOffset(current, this.desiredOffset ?? target, rows);
+            }
+            current = validateHistoryWindow(response);
+            this.assertTransportGeneration(current);
+            this.acceptLineage(current, allowLineageReplacement);
+            this.cacheWindow(current);
+            // This boundary response is already one validated, immutable snapshot
+            // captured for the requested target. Live output may advance `latest`
+            // while the RPC and payload chunks are in flight, so revision equality
+            // is no longer a valid reason to navigate away from this fresh window.
+            // Doing so used to synthesize a zero-distance `forward` request when the
+            // response started exactly at windowStart; the runtime correctly rejected
+            // that request as an invalid anchor and continuous agent output could make
+            // the single recovery attempt repeat the same race.
+            this.frontier = current;
+            if (this.windowCovers(current, target, rows))
+                return current;
+            // Bounded native scrollback can legitimately move past the requested
+            // absolute offset while the boundary capture is running. In that case,
+            // project the nearest viewport that is actually present in this atomic
+            // snapshot instead of issuing a directionally invalid anchored request.
+            const nearest = clamp(target, current.offset, current.offset + current.rows - rows);
+            return sliceHistoryWindow(current, nearest, rows);
         }
-        let current = frontier;
         if (!current)
-            throw new Error('terminal history frontier is unavailable');
-        const intended = this.desiredOffset ?? target;
-        if (current.offset === intended)
-            return current;
-        const direction = intended < current.offset ? 'backward' : 'forward';
-        const scrollDeltaRows = Math.abs(current.offset - intended);
-        if (scrollDeltaRows <= 0)
+            throw new Error('terminal history window is unavailable');
+        if (this.isReusableWindow(current, target, rows)) {
+            this.frontier = current;
             return current;
+        }
+        const direction = windowStart < current.offset ? 'backward' : 'forward';
         const offset = current.offset;
-        const next = validateHistoryViewport(await runSemanticHistoryRequest(() => this.options.request({
+        const next = validateHistoryWindow(await runSemanticHistoryRequest(() => this.options.request({
             lane: 'viewport',
             direction,
             anchor: current.anchor,
             snapshotId: current.snapshotId,
             offset,
-            targetOffset: intended,
-            viewportRows: rows,
+            targetOffset: windowStart,
+            viewportRows: windowRows,
+            windowRows,
         })));
         this.assertTransportGeneration(next);
         this.acceptLineage(next);
         if (next.offset === offset || (direction === 'backward' && next.offset > offset)
             || (direction === 'forward' && next.offset < offset)) {
-            throw new SemanticHistoryError('malformed_snapshot', 'semantic history request did not advance toward its target');
+            throw new SemanticHistoryError('malformed_snapshot', 'semantic history window did not advance toward its target');
         }
-        current = next;
-        return current;
+        this.frontier = next;
+        this.cacheWindow(next);
+        return next;
+    }
+    async fetchBoundary(direction, target, viewportRows, legacyViewportRows = viewportRows) {
+        try {
+            return await runSemanticHistoryRequest(() => this.options.request({
+                lane: 'viewport',
+                direction,
+                targetOffset: target,
+                viewportRows,
+                ...(viewportRows === legacyViewportRows ? {} : { windowRows: viewportRows }),
+            }));
+        }
+        catch (cause) {
+            if (!isLegacyBoundaryTargetRejection(cause))
+                throw cause;
+            return await runSemanticHistoryRequest(() => this.options.request({
+                lane: 'viewport',
+                direction,
+                viewportRows: legacyViewportRows,
+            }));
+        }
+    }
+    windowStart(target, rows, windowRows, direction) {
+        if (!this.latest)
+            return target;
+        const totalRows = this.latest.frame.history.totalRows;
+        const maximum = Math.max(0, totalRows - windowRows);
+        const bufferRows = Math.max(0, windowRows - rows);
+        const rowsBeforeTarget = direction < 0
+            ? Math.round(bufferRows * HISTORY_WINDOW_FORWARD_BIAS)
+            : direction > 0
+                ? Math.round(bufferRows * (1 - HISTORY_WINDOW_FORWARD_BIAS))
+                : Math.round(bufferRows / 2);
+        return clamp(target - rowsBeforeTarget, 0, maximum);
+    }
+    adaptiveWindowRows(rows, totalRows) {
+        if (!this.latest)
+            return rows;
+        const now = this.now();
+        const fast = this.scrollBurstDirection !== 0
+            && now - this.scrollBurstAt <= HISTORY_SCROLL_BURST_DECAY_MS
+            && this.scrollBurstRows >= rows * HISTORY_SCROLL_BURST_VIEWPORTS;
+        const multiplier = fast ? HISTORY_WINDOW_FAST_MULTIPLIER : HISTORY_WINDOW_BASE_MULTIPLIER;
+        const liveRowBytes = estimateFrameBytes(this.latest.frame) / Math.max(1, this.latest.frame.height);
+        const rowBytes = Math.max(256, this.estimatedHistoryRowBytes || liveRowBytes);
+        const cacheLimitedRows = Math.max(rows, Math.floor(HISTORY_WINDOW_CACHE_TARGET_BYTES / rowBytes));
+        const windowRows = Math.max(rows, Math.min(totalRows, HISTORY_WINDOW_MAX_ROWS, rows * multiplier, cacheLimitedRows));
+        emitSemanticDebugTrace({
+            kind: 'history-window-plan', at: now, direction: this.scrollDirection,
+            multiplier, viewportRows: rows, windowRows, cacheLimitedRows,
+            estimatedHistoryRowBytes: rowBytes, scrollBurstRows: this.scrollBurstRows,
+        });
+        return windowRows;
+    }
+    recordScrollIntent(deltaRows) {
+        if (deltaRows === 0)
+            return;
+        const direction = Math.sign(deltaRows);
+        const now = this.now();
+        if (direction === this.scrollBurstDirection
+            && now - this.scrollBurstAt <= HISTORY_SCROLL_BURST_GAP_MS) {
+            this.scrollBurstRows += Math.abs(deltaRows);
+        }
+        else {
+            this.scrollBurstDirection = direction;
+            this.scrollBurstRows = Math.abs(deltaRows);
+        }
+        this.scrollDirection = direction;
+        this.scrollBurstAt = now;
+    }
+    windowCovers(window, target, rows) {
+        return target >= window.offset && target + rows <= window.offset + window.rows;
     }
     display(viewport) {
         this.visible = viewport;
         this.error = null;
         this.putCache(viewport);
-        this.options.renderer.project(viewport.frame);
+        this.projectFrame(viewport.frame);
         this.evictCache();
         this.emitState();
     }
@@ -343,33 +553,34 @@ export class HistoryViewportController {
         this.putCache(viewport);
         this.evictCache();
     }
-    evictCache(dropHiddenExtras = false) {
-        const viewportCells = this.latest ? this.latest.geometry.cols * this.latest.geometry.rows : 0;
-        const maxExtraCells = Math.min(2 * viewportCells, 12288);
+    projectFrame(frame) {
+        if (this.handlingWheelFrame && this.options.renderer.projectInCurrentAnimationFrame) {
+            this.options.renderer.projectInCurrentAnimationFrame(frame);
+            return;
+        }
+        this.options.renderer.project(frame);
+    }
+    evictCache() {
         for (;;) {
             const candidates = [...this.cache.entries()]
                 .filter(([, item]) => item.viewport !== this.visible)
                 .sort((left, right) => left[1].touched - right[1].touched);
             const extraBytes = candidates.reduce((sum, candidate) => sum + candidate[1].bytes, 0);
-            const extraCells = candidates.reduce((sum, candidate) => sum + candidate[1].cells, 0);
-            if (!dropHiddenExtras && extraBytes <= MAX_HISTORY_CACHE_BYTES && extraCells <= maxExtraCells)
+            if (extraBytes <= MAX_SESSION_HISTORY_CACHE_BYTES)
                 break;
             const oldest = candidates[0];
             if (!oldest)
                 break;
             this.removeCacheEntry(oldest[0]);
         }
+        emitSemanticDebugTrace({ kind: 'history-cache-state', at: performance.now(),
+            cacheEntries: this.cache.size, cacheBytes: this.cacheBytes,
+            cacheExtraBytes: this.cacheExtraBytes() });
     }
-    schedulePrefetch(viewport) {
-        if (!this.viewVisible || this.lastDirection === 0)
-            return;
-        const rows = viewport.rows;
-        const target = clamp(viewport.offset + this.lastDirection * rows, 0, viewport.screenStartOffset);
-        if (target === viewport.offset || this.findCachedViewport(target))
-            return;
-        this.prefetchOffset = target;
-        if (!this.lane)
-            this.startLane();
+    cacheExtraBytes() {
+        return [...this.cache.values()]
+            .filter(item => item.viewport !== this.visible)
+            .reduce((sum, item) => sum + item.bytes, 0);
     }
     isCompatible(viewport) {
         return Boolean(this.latest
@@ -379,7 +590,32 @@ export class HistoryViewportController {
             && (viewport.lane ?? 'viewport') === 'viewport'
             && (this.historyAnchor === null || viewport.anchor === this.historyAnchor)
             && viewport.cols === this.latest.geometry.cols
-            && viewport.rows === this.latest.geometry.rows);
+            && viewport.rows === this.latest.geometry.rows
+            && viewport.window !== true);
+    }
+    isReusableViewport(viewport) {
+        return Boolean(this.latest
+            && this.isCompatible(viewport)
+            && viewport.totalRows === this.latest.frame.history.totalRows
+            && viewport.revision === this.latest.frame.history.revision);
+    }
+    isCompatibleWindow(viewport) {
+        return Boolean(this.latest
+            && viewport.window === true
+            && viewport.contentEpoch === (this.latest.state.contentEpoch ?? 0)
+            && viewport.geometryGeneration === this.latest.geometry.generation
+            && (this.transportGeneration === null || viewport.transportGeneration === this.transportGeneration)
+            && (viewport.lane ?? 'viewport') === 'viewport'
+            && (this.historyAnchor === null || viewport.anchor === this.historyAnchor)
+            && viewport.cols === this.latest.geometry.cols
+            && viewport.rows >= this.latest.geometry.rows);
+    }
+    isReusableWindow(viewport, target, rows) {
+        return Boolean(this.latest
+            && this.isCompatibleWindow(viewport)
+            && viewport.totalRows === this.latest.frame.history.totalRows
+            && this.windowCovers(viewport, target, rows)
+            && viewport.revision === this.latest.frame.history.revision);
     }
     assertTransportGeneration(viewport) {
         if (this.transportGeneration === null) {
@@ -396,20 +632,57 @@ export class HistoryViewportController {
         this.frontier = null;
         this.visible = null;
         this.desiredOffset = null;
-        this.prefetchOffset = null;
+        this.preferExactViewport = false;
+        this.scrollDirection = 0;
+        this.scrollBurstDirection = 0;
+        this.scrollBurstRows = 0;
+        this.scrollBurstAt = 0;
+        this.estimatedHistoryRowBytes = 0;
         this.historyAnchor = null;
         this.error = error;
         if (projectLatest)
             this.options.renderer.project(null);
         this.emitState();
     }
+    shouldDisplayIntermediate(target, desiredOffset) {
+        if (desiredOffset === null || this.visible === null)
+            return false;
+        const currentOffset = this.visible.offset;
+        const minimum = Math.min(currentOffset, desiredOffset);
+        const maximum = Math.max(currentOffset, desiredOffset);
+        return target >= minimum && target <= maximum
+            && Math.abs(desiredOffset - target) < Math.abs(desiredOffset - currentOffset);
+    }
     findCachedViewport(offset) {
         for (const item of this.cache.values()) {
-            if (item.viewport.offset === offset && this.isCompatible(item.viewport))
+            if (item.viewport.offset === offset && this.isReusableViewport(item.viewport))
                 return item.viewport;
         }
         return null;
     }
+    findCachedWindow(offset, rows) {
+        if (rows <= 0)
+            return null;
+        let candidate = null;
+        for (const item of this.cache.values()) {
+            if (this.isReusableWindow(item.viewport, offset, rows)
+                && (!candidate || item.touched > candidate.touched))
+                candidate = item;
+        }
+        return candidate?.viewport ?? null;
+    }
+    cacheWindow(viewport) {
+        if (viewport.window !== true)
+            return;
+        const observedRowBytes = estimateViewportBytes(viewport) / Math.max(1, viewport.rows);
+        this.estimatedHistoryRowBytes = this.estimatedHistoryRowBytes === 0
+            ? observedRowBytes
+            : observedRowBytes > this.estimatedHistoryRowBytes
+                ? observedRowBytes
+                : this.estimatedHistoryRowBytes * 0.75 + observedRowBytes * 0.25;
+        this.putCache(viewport);
+        this.evictCache();
+    }
     putCache(viewport) {
         if ((viewport.lane ?? 'viewport') !== 'viewport') {
             throw new SemanticHistoryError('malformed_snapshot', 'semantic history viewport belongs to another lane');
@@ -419,33 +692,26 @@ export class HistoryViewportController {
         }
         if (this.historyAnchor === null)
             this.historyAnchor = viewport.anchor;
-        const key = `${viewport.snapshotId}:${viewport.offset}`;
+        // Keep a sliced viewport separate from its source window. Reusing the same
+        // key would replace the reusable window as soon as it is displayed once.
+        const key = `${viewport.snapshotId}:${viewport.offset}:${viewport.window === true ? 'window' : 'viewport'}`;
+        const previous = this.cache.get(key);
+        this.touch += 1;
+        if (previous?.viewport === viewport) {
+            this.cache.set(key, { ...previous, touched: this.touch });
+            return;
+        }
         const bytes = estimateViewportBytes(viewport);
         const cells = viewport.cols * viewport.rows;
-        const previous = this.cache.get(key);
         if (previous)
             this.cacheBytes -= previous.bytes;
-        this.touch += 1;
         const item = { viewport, touched: this.touch, bytes, cells };
         this.cache.set(key, item);
         this.cacheBytes += bytes;
-        globalHistoryCache.put({
-            owner: this.cacheOwner,
-            key,
-            bytes,
-            touched: item.touched,
-            hidden: () => !this.viewVisible,
-            evictable: () => {
-                const current = this.cache.get(key)?.viewport;
-                return Boolean(current && current !== this.visible);
-            },
-            evict: () => this.removeCacheEntry(key),
-        });
     }
     clearCache() {
         this.cache.clear();
         this.cacheBytes = 0;
-        globalHistoryCache.clear(this.cacheOwner);
     }
     removeCacheEntry(key) {
         const item = this.cache.get(key);
@@ -455,7 +721,6 @@ export class HistoryViewportController {
         this.cacheBytes -= item.bytes;
         if (this.frontier === item.viewport)
             this.frontier = null;
-        globalHistoryCache.remove(this.cacheOwner, key);
     }
     acceptLineage(viewport, allowReplacement = false) {
         if ((viewport.lane ?? 'viewport') !== 'viewport') {
@@ -476,12 +741,91 @@ export class HistoryViewportController {
 function clamp(value, minimum, maximum) {
     return Math.max(minimum, Math.min(maximum, value));
 }
+function isLegacyBoundaryTargetRejection(cause) {
+    if (!(cause instanceof Error))
+        return false;
+    const code = Number(cause.code);
+    return code === 400 && cause.message.toLowerCase().includes('failed to read semantic history');
+}
+function isRecoverableHistoryLineageError(cause) {
+    if (!(cause instanceof SemanticHistoryError)
+        || (cause.kind !== 'anchor_invalid' && cause.kind !== 'snapshot_superseded'))
+        return false;
+    // The RPC adapter normally preserves the 409/412 code as `cause`, but a
+    // transport implementation is allowed to surface the typed semantic error
+    // directly. The semantic kind is the authoritative contract here; making
+    // recovery depend on an adapter-specific numeric code exposed the user to
+    // stale-anchor errors whenever that code was wrapped or omitted.
+    const rpcCause = cause.cause;
+    // A local `snapshot_superseded` means two validated responses disagreed on
+    // lineage and must remain a hard failure. Only an unwrapped anchor error is
+    // safe to recover from without an adapter code: native history can expire
+    // an anchor while the transport is still healthy.
+    if (!rpcCause)
+        return cause.kind === 'anchor_invalid';
+    const code = rpcCause instanceof Error
+        ? Number(rpcCause.code)
+        : Number.NaN;
+    return code === 409 || code === 412 || rpcCause instanceof SemanticHistoryError;
+}
 function estimateViewportBytes(viewport) {
-    let bytes = 256;
-    for (const row of viewport.frame.rows) {
+    return 256 + estimateFrameBytes(viewport.frame);
+}
+function estimateFrameBytes(frame) {
+    let bytes = 0;
+    for (const row of frame.rows) {
         for (const cell of row.cells)
             bytes += 16 + cell.text.length * 2 + (cell.hyperlink?.length ?? 0) * 2;
     }
     return bytes;
 }
+function sliceHistoryWindow(window, offset, rows) {
+    if (window.window !== true || offset < window.offset || offset + rows > window.offset + window.rows) {
+        throw new SemanticHistoryError('malformed_snapshot', 'semantic history window does not cover its target viewport');
+    }
+    const rowStart = offset - window.offset;
+    const frame = window.frame;
+    const end = rowStart + rows;
+    const screenStartOffset = window.totalRows - rows;
+    const cursorVisible = frame.cursor.visible && frame.cursor.y >= rowStart && frame.cursor.y < end;
+    const placements = frame.graphics.placements
+        .filter(placement => !placement.visible || (placement.viewportRow + placement.gridRows > rowStart && placement.viewportRow < end))
+        .map(placement => ({ ...placement, viewportRow: placement.viewportRow - rowStart }));
+    const slicedFrame = {
+        ...frame,
+        height: rows,
+        rows: frame.rows.slice(rowStart, end),
+        cursor: {
+            ...frame.cursor,
+            y: cursorVisible ? frame.cursor.y - rowStart : 0,
+            visible: cursorVisible,
+        },
+        history: {
+            revision: window.revision,
+            totalRows: window.totalRows,
+            screenStartOffset: window.totalRows - rows,
+        },
+        graphics: { ...frame.graphics, placements },
+    };
+    return validateHistoryViewport({
+        snapshotId: `${window.snapshotId}:${offset}`,
+        lane: window.lane,
+        revision: window.revision,
+        transportGeneration: window.transportGeneration,
+        contentEpoch: window.contentEpoch,
+        geometryGeneration: window.geometryGeneration,
+        cols: window.cols,
+        rows,
+        anchor: window.anchor,
+        firstAvailable: window.firstAvailable,
+        lastAvailable: window.lastAvailable,
+        screenStart: window.screenStart,
+        offset,
+        totalRows: window.totalRows,
+        screenStartOffset,
+        hasPrevious: offset > 0,
+        hasNext: offset < screenStartOffset,
+        frame: slicedFrame,
+    });
+}
 //# sourceMappingURL=HistoryViewportController.js.map