@aragon-agent/cli 0.6.47 → 0.6.48

package/dist/ui/scrollback/scrollback-writer.js

@@ -1,648 +0,0 @@
-/**
- * ScrollbackWriter — the byte contract of native-scroll mode
- * (tui-native-terminal-scroll §4.3, extended by tui-bottom-anchored-live-region
- * and re-based on a CANVAS by tui-canvas-bottom-anchor).
- *
- * It implements `FrameDiffer`, so `stdout-frame-writer.ts::wrapStdoutForFrames`
- * binds it to a real stream exactly as it binds the full-screen differ. What it
- * does differently: the screen is NOT the app's. Settled conversation rows are
- * printed into the host terminal's own scrollback, and Ink's frame is only a small
- * LIVE REGION parked under the last printed row.
- *
- * GEOMETRY IS RELATIVE (D2/D4). A batch is `CUU(canvasRows)` to the top of the
- * previous CANVAS, erase down, skip the gap, print the content rows, print the
- * region, park on the last row. Nothing needs the terminal's absolute row count, so
- * a terminal that scrolls underneath cannot misplace anything.
- *
- * THE CANVAS (tui-canvas-bottom-anchor D1/D3). The `rows - 1` rows above the parked
- * row belong to the writer and are always laid out top-down as
- * `[gap][content][region]`. The previous feature put its blank rows between the
- * content and the region (`[content][pad][region]`), which is why a short
- * conversation left a reply floating far above the composer. The blank space now
- * lives above every visible content row, so the newest printed row always touches
- * the top row of the live region, while the composer stays on the last two rows.
- * The gap is SKIPPED with CUD and never written, so a blank row can never be pushed
- * into the scrollback (I-B3).
- *
- * THE PRICE, and it is the only one: the content rows still on the canvas can be
- * re-drawn when the layout changes (a region collapse, a longer draft), because the
- * rows that the region gives back have to move onto the canvas top. That is why the
- * writer keeps a bounded cache of them (`held`, at most `capacity - H` rows). A row
- * that leaves the canvas — pushed into the scrollback or erased at exit — is never
- * written again, so the history the user scrolls through is exactly what was
- * printed, once (I-B5). `anchor: unknown` (nothing measured: no TTY, no filter, no
- * CPR answer) keeps the pre-feature bytes exactly, which is what keeps the old byte
- * tests meaningful (I-B7).
- *
- * THE INVARIANTS THAT FAIL SILENTLY IF DROPPED:
- *  - I-S4 · every batch parks the cursor one row below the region, column 0, the
- *    same place Ink's `previousLineCount = H + 1` expects.
- *  - I-S8 · geometry in doubt (foreign write, unparseable chunk) => `prev = null`
- *    => next batch is a SEED. Never keep erasing on a stale height.
- *  - I-S14 · after `finalize` EVERY Ink write is swallowed.
- *  - I-S13 · no emitted row is wider than `cols - 1` (clipped, counted).
- *  - I-B1 · a batch ends parked on `rows - 1`, which is what the next `CUU` assumes.
- *  - I-B3 · blank rows only ever exist as SKIPPED rows, and a batch that scrolls has
- *    `gap = 0`, so the scrollback never receives an empty row from this file.
- *  - I-B5 · `held` is a contiguous suffix of the printed content, and `dropped` is
- *    exactly the number of rows this batch pushed off the top. The BYTES carry the
- *    untrimmed content: the terminal can only scroll away rows it was given.
- *  - I-B14 · a re-measurement re-derives `capacity` from `spaceBelow + canvasRows`,
- *    never from `spaceBelow` alone: the canvas itself still owns the rows above the
- *    cursor, and forgetting them makes the next batch read its own screen as an
- *    overflow and print every visible row a second time.
- *  - I-B15 · every batch starts by reconciling `top + capacity` with the live
- *    `rows - 1` (a resize event can arrive one frame late), and a column change
- *    resets before it writes.
- *  - I-B17 · a SHRINK re-pins the canvas, it never drops it. The canvas keeps
- *    `min(canvasRows, screenCapacity(rows))` rows — the screen keeps the rows nearest
- *    the parked cursor, so the survivors are its SUFFIX — and its top moves down to
- *    `capacity - kept`, which preserves LB-3. Dropping the cache instead made the next
- *    batch a SEED, and a seed assumes nothing is below the cursor
- *    (`writer-shapes.ts:60-64`); after a shrink that is false, so the batch overflowed
- *    the screen and the previous frame — status row included — went into the
- *    scrollback: the same row in two places. For the same reason a frame TALLER than
- *    the screen gives way at its TOP instead of being swallowed whole: the composer
- *    and the status line are the two rows a human is interacting with.
- *  - I-A9 · the writer never writes a probe byte; it only asks the host, which owns
- *    deferral, coalescing and the death switch.
- */
-import { parseInkFrame } from '../frame-parser.js';
-import { clampSpaceBelow, resolveCanvasLayout, screenCapacity, UNKNOWN_CANVAS, applyResizeGrowth, } from './canvas.js';
-import { SCROLLBACK_LIMITS } from './limits.js';
-import { canvasBytes, canvasSeedBytes, clipLine, diffBytes, finalizeBytes, fullBytes, seedBytes, } from './writer-shapes.js';
-/** `ansiEscapes.clearTerminal` — Ink's tall-frame write. It contains `ESC[3J`. */
-const CLEAR_TERMINAL = '\x1b[2J\x1b[3J\x1b[H';
-export function createScrollbackWriter(o) {
-    const now = o.now ?? Date.now;
-    const maxBatch = SCROLLBACK_LIMITS.maxRowsPerBatch;
-    /** Where the bottom of the screen is, as far as anything has measured it. */
-    let anchor = UNKNOWN_CANVAS;
-    /** Content rows still on the canvas, oldest first, already clipped (I-B9). */
-    let held = [];
-    /** Gap rows of the previous batch. */
-    let gapRows = 0;
-    /** Frame rows of the previous batch (`regionRows()`). */
-    let frameRows = 0;
-    /** Canvas height of the previous batch = the erase distance. */
-    let canvasRows = 0;
-    /** The canvas as it stands on screen (`''` = a skipped gap row), or null if lost. */
-    let prev = null;
-    /** The last frame BEFORE clipping, so unchanged rows are not re-measured. */
-    let prevRawFrame = null;
-    /** The last frame AFTER clipping, aligned with `prevRawFrame` (P2-3). */
-    let prevClippedFrame = null;
-    let everWritten = false;
-    let seenAnyChunk = false;
-    let finalized = false;
-    let guardTripped = false;
-    let consecutiveGuard = 0;
-    let lastResizeAt = Number.NEGATIVE_INFINITY;
-    /** Width the previous canvas was written at, for the column-change reset. */
-    let lastWriteCols;
-    /** Terminal height at the previous batch: the basis of a resize delta. */
-    let lastRows;
-    let repaintQueued = false;
-    let anchorSource = 'none';
-    /** A fresh measurement is waiting to be consumed by the next write. */
-    let anchorDirty = false;
-    let anchorReprobes = 0;
-    let scrolledRows = 0;
-    /**
-     * Rows between the cursor and the canvas top for the NEXT seed, when the canvas is
-     * shorter than the measured space below the cursor (a terminal taller than
-     * `maxCanvasRows`). Zero in every other state, because a canvas that exists has its
-     * top above the parked cursor by construction.
-     */
-    let seedDownToTop = 0;
-    const stats = {
-        framesSeed: 0, framesDiff: 0, framesFull: 0, staticRowsWritten: 0, bytesWritten: 0,
-        fallbacks: 0, guardHits: 0, guardHitsOutsideResize: 0, clippedRows: 0, elidedEntries: 0,
-        resizes: 0, repaints: 0, anchorSource: 'none', anchorCanvasRows: 0, anchorHeldRows: 0,
-        anchorGapRows: 0, anchorScrollRows: 0, anchorResets: 0, anchorReprobes: 0,
-        tallFramesTrimmed: 0,
-    };
-    const liveCols = () => {
-        const cols = o.cols();
-        return cols !== undefined && Number.isFinite(cols) && cols >= 1 ? Math.floor(cols) : undefined;
-    };
-    const liveRows = () => {
-        const rows = o.rows();
-        return rows !== undefined && Number.isFinite(rows) ? Math.floor(rows) : undefined;
-    };
-    const scheduleRepaint = () => {
-        if (!o.requestRepaint || repaintQueued || finalized)
-            return;
-        repaintQueued = true;
-        // Deferred by the host (setImmediate): this can fire from inside Ink's write.
-        o.requestRepaint();
-    };
-    /**
-     * Ask for a measurement. Never writes anything itself, and never after `finalize`
-     * (I-A9): the host owns the deferral, the coalescing and the death switch.
-     */
-    const requestProbe = () => {
-        if (finalized || anchorSource === 'none')
-            return;
-        o.requestAnchorProbe?.();
-    };
-    /** Report what the canvas looks like right now. Produces no bytes. */
-    const publishAnchorStats = () => {
-        const pinned = anchor.kind === 'pinned';
-        stats.anchorSource = anchorSource;
-        stats.anchorCanvasRows = pinned ? canvasRows : 0;
-        stats.anchorHeldRows = pinned ? held.length : 0;
-        stats.anchorGapRows = pinned ? gapRows : 0;
-        stats.anchorScrollRows = scrolledRows;
-        stats.anchorReprobes = anchorReprobes;
-    };
-    /**
-     * Drop the canvas and go back to the append path (D5, I-B8, I-A3).
-     *
-     * Shared by a column change, a shrink, `invalidate()` and a lost geometry: all
-     * four have the same safe answer, "re-measure and print nothing until then".
-     * The rows already on screen are NOT redrawn — they are not where the cache says
-     * they are, and a wrong erase both duplicates and destroys user-visible content.
-     */
-    const reset = () => {
-        prev = null;
-        prevRawFrame = null;
-        prevClippedFrame = null;
-        held = [];
-        gapRows = 0;
-        canvasRows = 0;
-        seedDownToTop = 0;
-        anchor = UNKNOWN_CANVAS;
-        anchorDirty = false;
-        stats.anchorResets += 1;
-        publishAnchorStats();
-        requestProbe();
-    };
-    /** Clip a frame row to `cols - 1`, reusing the previous result for unchanged rows. */
-    const clipFrame = (raw, cols) => {
-        if (cols === undefined)
-            return [...raw];
-        const limit = cols - 1;
-        return raw.map((line, i) => {
-            const cached = prevClippedFrame?.[i];
-            if (cached !== undefined && prevRawFrame?.[i] === line)
-                return cached;
-            const result = clipLine(line, limit);
-            if (result.clipped)
-                stats.clippedRows += 1;
-            return result.text;
-        });
-    };
-    const clipStatics = (rows, cols) => {
-        if (cols === undefined || rows.length === 0)
-            return rows;
-        return rows.map((line) => {
-            const result = clipLine(line, cols - 1);
-            if (result.clipped)
-                stats.clippedRows += 1;
-            return result.text;
-        });
-    };
-    const record = (bytes, shape, statics) => {
-        if (shape === 'seed')
-            stats.framesSeed += 1;
-        else if (shape === 'diff')
-            stats.framesDiff += 1;
-        else if (shape === 'full')
-            stats.framesFull += 1;
-        else
-            stats.repaints += 1;
-        stats.staticRowsWritten += statics;
-        stats.bytesWritten += bytes.length;
-        return bytes;
-    };
-    /**
-     * Drop from the canvas cache the rows a shorter screen no longer has (I-B17).
-     *
-     * A shrink deletes rows ABOVE the parked cursor, so what survives is the canvas's
-     * SUFFIX: the gap goes first, then the oldest content rows. Trimming the cache is
-     * what lets the next batch be a DIFF against what is really on screen. Dropping the
-     * cache (`reset()`) made it a SEED instead, and a seed assumes nothing is below the
-     * cursor (`writer-shapes.ts:60-64`) — after a shrink that is false, so the batch
-     * overflowed and the previous frame, status row included, was pushed into the
-     * scrollback instead of being erased.
-     */
-    const trimCanvasCache = (capacity) => {
-        const lost = canvasRows - capacity;
-        if (lost <= 0)
-            return;
-        const lostFromGap = Math.min(lost, gapRows);
-        gapRows -= lostFromGap;
-        held = held.slice(Math.min(lost - lostFromGap, held.length));
-        prev = prev === null ? null : prev.slice(lost);
-        canvasRows = capacity;
-        // A drastic shrink can eat into the region itself (E2). `frameRows` is the height
-        // the next diff is aligned against, so it may never claim rows that are gone.
-        frameRows = Math.min(frameRows, Math.max(0, capacity - gapRows - held.length));
-    };
-    /**
-     * Re-pin a canvas the terminal just got SHORTER, instead of dropping it (I-B17).
-     *
-     * `top` moves DOWN (`capacity - kept`) because the rows the screen lost were the ones
-     * above the cursor: the parked row is still `rows - 1`, so LB-3 holds for the same
-     * reason it always did.
-     *
-     * `capacity < 1` keeps the old answer (E3): a terminal with no row above the parked one
-     * has no canvas left to address, and re-measuring is then the only honest move. Columns
-     * are deliberately NOT handled here: a width change re-flows the rows themselves, so
-     * the cache describes nothing and still resets (D5 / E4).
-     */
-    const repinShrunk = (rows) => {
-        const room = screenCapacity(rows);
-        // Only a MEASURED canvas may be re-pinned. `unknown` means nothing ever established
-        // that the cursor sits on the last row, and the arithmetic below starts from exactly
-        // that assumption; the append path erases nothing, so it stays the honest answer and
-        // keeps its bytes exactly as they were (I-B7).
-        const capacity = anchor.kind === 'pinned' ? Math.min(canvasRows, room) : 0;
-        if (capacity < 1) {
-            reset();
-            return;
-        }
-        trimCanvasCache(capacity);
-        anchor = { kind: 'pinned', top: room - capacity, capacity };
-        seedDownToTop = 0;
-        lastRows = rows;
-        // The re-draw this answers is the host's, deferred and coalesced (P0-2 / P0-3):
-        // `anchorDirty` is what lets a `repaint()` land while the feed is idle.
-        anchorDirty = true;
-        publishAnchorStats();
-        // Re-measure anyway (I-B14). Keeping the canvas is a bet that the parked row is still
-        // `rows - 1`, and only a measurement can confirm the terminal agrees; dropping the
-        // probe here would leave a wrong geometry with nothing left to correct it. A drag
-        // that fires dozens of resize events still costs one probe: the host coalesces them
-        // (P1-3 / E6), and `anchorReprobes` counts measurements, never requests.
-        requestProbe();
-    };
-    /**
-     * Bring `top + capacity` back in line with the live `rows - 1` BEFORE the batch
-     * reads either of them (§6.11, [P0-2]).
-     *
-     * The `resize` event is dispatched a libuv turn after `stdout.rows` changed, so a
-     * frame can arrive on the new grid while the anchor still describes the old one.
-     * The pre-canvas writer healed that one batch later, by deriving `gap` from the
-     * current height; a canvas cannot, because `top` and `capacity` only ever change
-     * where they are measured — and the batch that ran on the stale grid would record
-     * the new height, leaving the late `onResize` with a delta of zero. On a terminal
-     * that never answers CPR that is a composer stuck mid-screen for the session.
-     */
-    const reconcile = (rows, cols) => {
-        if (anchor.kind !== 'pinned')
-            return;
-        if (cols !== undefined && lastWriteCols !== undefined && cols !== lastWriteCols) {
-            reset();
-            return;
-        }
-        const capacity = screenCapacity(rows);
-        const parked = anchor.top + anchor.capacity;
-        if (capacity === parked)
-            return;
-        if (capacity > parked) {
-            // The terminal grew below the cursor: the cursor did not move, so the canvas
-            // owns exactly the extra rows.
-            anchor = { kind: 'pinned', top: anchor.top, capacity: anchor.capacity + (capacity - parked) };
-            lastRows = rows;
-            return;
-        }
-        // The `resize` event can arrive a whole frame late, and on a terminal that never
-        // answers CPR it never arrives at all: this batch is then the last chance to keep
-        // the canvas instead of dropping it (I-B17, W6).
-        repinShrunk(rows);
-    };
-    const afterCanvasBatch = (layout, heldNext, frame, raw, cols, rows) => {
-        prev = [...new Array(layout.gap).fill(''), ...heldNext, ...frame];
-        prevRawFrame = [...raw];
-        prevClippedFrame = [...frame];
-        canvasRows = prev.length;
-        held = [...heldNext];
-        gapRows = layout.gap;
-        frameRows = frame.length;
-        anchor = { kind: 'pinned', top: layout.top, capacity: layout.canvasRows };
-        everWritten = true;
-        lastWriteCols = cols;
-        lastRows = rows;
-        anchorDirty = false;
-        seedDownToTop = 0;
-        scrolledRows += layout.scroll;
-        publishAnchorStats();
-        // A feed larger than one batch continues on the next tick, region still parked.
-        if (o.drain.pending() > 0) {
-            repaintQueued = false;
-            scheduleRepaint();
-        }
-    };
-    const afterLegacyBatch = (raw, frame, cols, rows) => {
-        prev = [...frame];
-        prevRawFrame = [...raw];
-        prevClippedFrame = [...frame];
-        // The region IS the erasable block on this path, which is also the number a
-        // later measurement needs in order to know how far above the cursor its top is.
-        canvasRows = frame.length;
-        gapRows = 0;
-        frameRows = frame.length;
-        held = [];
-        everWritten = true;
-        lastWriteCols = cols;
-        lastRows = rows;
-        anchorDirty = false;
-        publishAnchorStats();
-        if (o.drain.pending() > 0) {
-            repaintQueued = false;
-            scheduleRepaint();
-        }
-    };
-    /**
-     * The pre-canvas append path: static rows above a region that is never redrawn.
-     * Byte-identical to the writer before either anchor existed (I-B7): `seedBytes` /
-     * `fullBytes` / `diffBytes`, `eraseUp = canvasRows` (= the frame height).
-     */
-    const assembleLegacy = (raw, statics, frame, rows, cols, mode) => {
-        let out;
-        if (prev === null) {
-            out = record(seedBytes({ lines: frame, statics, sync: o.sync, reseed: everWritten }), 'seed', statics.length);
-        }
-        else if (mode === 'repaint') {
-            out = record(fullBytes({ lines: frame, statics, eraseUp: canvasRows, sync: o.sync }), 'repaint', statics.length);
-        }
-        else if (statics.length > 0 || frame.length !== canvasRows || o.fullEveryFrame) {
-            out = record(fullBytes({ lines: frame, statics, eraseUp: canvasRows, sync: o.sync }), 'full', statics.length);
-        }
-        else {
-            out = record(diffBytes({ lines: frame, prev, sync: o.sync }), 'diff', 0);
-        }
-        afterLegacyBatch(raw, frame, cols, rows);
-        return out;
-    };
-    /**
-     * A canvas batch repaints EVERYTHING when the layout moved, and only the rows that
-     * differ when it did not. `layout.scroll > 0` forces the full shape for a reason
-     * the other four conditions do not cover: when the canvas is already the whole
-     * screen its height cannot change, so a batch that pushes rows out would otherwise
-     * be diffed against rows it has just lost.
-     */
-    const needsCanvasShape = (layout, frame, statics, mode) => {
-        if (mode === 'repaint')
-            return true;
-        return statics > 0 || layout.scroll > 0 || layout.gap !== gapRows ||
-            layout.canvasRows !== canvasRows || frame.length !== frameRows || o.fullEveryFrame;
-    };
-    const emitCanvas = (layout, content, kept, frame, statics, mode) => {
-        if (prev === null) {
-            return record(canvasSeedBytes({
-                downToTop: seedDownToTop,
-                gap: layout.gap, held: content, lines: frame, sync: o.sync, reseed: everWritten,
-            }), 'seed', statics);
-        }
-        if (needsCanvasShape(layout, frame, statics, mode)) {
-            return record(canvasBytes({
-                eraseUp: canvasRows, gap: layout.gap, held: content, lines: frame, sync: o.sync,
-            }), mode === 'repaint' ? 'repaint' : 'full', statics);
-        }
-        const shown = [...new Array(layout.gap).fill(''), ...kept, ...frame];
-        return record(diffBytes({ lines: shown, prev, sync: o.sync }), 'diff', 0);
-    };
-    /**
-     * THE ONE PLACE THE GEOMETRY IS COMPUTED (§6.2), shared by `transform` and
-     * `repaint` so the two can never disagree about where the region goes.
-     *
-     * Order is load-bearing: reconcile, then static rows, then the layout, then the
-     * bytes. `ED0`, the gap, the content, the region — in that order, always.
-     */
-    const assemble = (raw, rows, cols, mode) => {
-        reconcile(rows, cols);
-        const statics = clipStatics(o.drain.takeUpTo(maxBatch), cols);
-        const frame = clipFrame(raw, cols);
-        if (anchor.kind === 'unknown') {
-            return assembleLegacy(raw, statics, frame, rows, cols, mode);
-        }
-        const layout = resolveCanvasLayout({
-            capacity: anchor.capacity,
-            top: anchor.top,
-            heldRows: held.length,
-            statRows: statics.length,
-            frameRows: frame.length,
-            lead: prev === null && everWritten ? 1 : 0,
-        });
-        // The bytes carry every content row; the ones that do not fit leave through the
-        // bottom, and the terminal can only scroll away rows it was given. `held` keeps
-        // the suffix that is still on screen (I-B5).
-        const content = held.concat(statics);
-        const kept = layout.dropped > 0 ? content.slice(layout.dropped) : content;
-        const out = emitCanvas(layout, content, kept, frame, statics.length, mode);
-        afterCanvasBatch(layout, kept, frame, raw, cols, rows);
-        return out;
-    };
-    const swallowTallFrame = () => {
-        stats.guardHits += 1;
-        if (now() - lastResizeAt >= SCROLLBACK_LIMITS.guardResizeGraceMs) {
-            stats.guardHitsOutsideResize += 1;
-            consecutiveGuard += 1;
-            if (consecutiveGuard >= SCROLLBACK_LIMITS.guardTripCount && !guardTripped) {
-                guardTripped = true;
-                o.onGuardTrip?.();
-            }
-        }
-        // Swallow the whole chunk: it would clear the visible screen AND scrollback.
-        return '';
-    };
-    const countFallback = (counted) => {
-        reset();
-        if (counted) {
-            stats.fallbacks += 1;
-            if (stats.fallbacks === 1)
-                o.onFirstFallback?.();
-        }
-        return null;
-    };
-    /**
-     * Ink wrote a frame we cannot address (a one-row terminal). Record only what the
-     * FRAME tells us (P2-6): a frame is not a canvas, so on the append path it is the
-     * block (`canvasRows = H`), and on the canvas path nothing survives but the fact
-     * that the geometry is lost.
-     */
-    const passThrough = (lines) => {
-        if (lines === null)
-            return;
-        prevRawFrame = lines;
-        prevClippedFrame = lines;
-        frameRows = lines.length;
-        if (anchor.kind === 'pinned') {
-            reset();
-            return;
-        }
-        prev = lines;
-        canvasRows = lines.length;
-        gapRows = 0;
-    };
-    /**
-     * Give way at the TOP of a frame taller than the screen (I-B17 / W4).
-     *
-     * Such a frame cannot be addressed as ONE block, and swallowing it left the PREVIOUS
-     * frame on screen — which is how the status row came to be printed twice. The region's
-     * last rows are the composer and the status line, the two rows a human is interacting
-     * with, so the oldest rows go first and the next (shorter) frame restores the rest.
-     *
-     * BOTH entry points that draw a frame need this: `repaint()` replays the frame it kept,
-     * and that frame can predate a shrink that has since made the screen shorter.
-     */
-    const giveWayAtTop = (lines, rows) => {
-        if (lines.length + 1 <= rows)
-            return lines;
-        stats.tallFramesTrimmed += 1;
-        return lines.slice(lines.length - (rows - 1));
-    };
-    const transform = (chunk) => {
-        if (finalized)
-            return '';
-        if (chunk.startsWith(CLEAR_TERMINAL))
-            return swallowTallFrame();
-        consecutiveGuard = 0;
-        guardTripped = false;
-        const firstChunk = !seenAnyChunk;
-        seenAnyChunk = true;
-        const rows = liveRows();
-        const lines = parseInkFrame(chunk);
-        if (rows === undefined || rows < 2) {
-            passThrough(lines);
-            return null;
-        }
-        if (lines === null)
-            return countFallback(!firstChunk);
-        return assemble(giveWayAtTop(lines, rows), rows, liveCols(), 'frame');
-    };
-    const repaint = () => {
-        repaintQueued = false;
-        if (finalized || prevClippedFrame === null || prevRawFrame === null)
-            return '';
-        // `anchorDirty` is why a probe result arriving while the feed is idle lands at
-        // all: without it, "re-pin after a resize" would write zero bytes (P0-2).
-        if (o.drain.pending() === 0 && !anchorDirty)
-            return '';
-        const rows = liveRows();
-        if (rows === undefined || rows < 2)
-            return '';
-        // The kept frame may predate a shrink, so a replay gets the same top give-way as a
-        // live frame (W4): drawing it whole would overflow the new screen and push this
-        // session's own rows into the scrollback through the repaint door.
-        return assemble(giveWayAtTop(prevRawFrame, rows), rows, liveCols(), 'repaint');
-    };
-    const finalize = (summary) => {
-        if (finalized)
-            return '';
-        finalized = true;
-        const pending = clipStatics(o.drain.takeAll(), liveCols());
-        // Unknown geometry after a foreign write: no safe erase, start on a fresh line.
-        // Otherwise erase the whole CANVAS — the gap included, or its blank rows stay
-        // behind as a dead band above the summary (I-B11).
-        const eraseUp = prev === null && everWritten ? -1 : canvasRows;
-        // ... and reprint what the erase removes. The content rows live INSIDE the canvas,
-        // so erasing it without them would delete the user's last screenful of conversation
-        // at exactly the moment they want to read it (the pre-canvas writer never had to:
-        // its static rows were already outside the erasable block).
-        const bytes = finalizeBytes({ eraseUp, statics: [...held, ...pending], summary });
-        stats.staticRowsWritten += pending.length;
-        stats.bytesWritten += bytes.length;
-        return bytes;
-    };
-    o.drain.onEnqueue = scheduleRepaint;
-    return {
-        transform,
-        repaint,
-        finalize,
-        invalidate: reset,
-        onResize() {
-            stats.resizes += 1;
-            lastResizeAt = now();
-            consecutiveGuard = 0;
-            guardTripped = false;
-            const rowsNow = liveRows();
-            const colsNow = liveCols();
-            // A column change re-flows what is already on screen: the cached rows no longer
-            // describe it, and erasing by their height would cut a line in half (D5).
-            if (colsNow !== undefined && lastWriteCols !== undefined && colsNow !== lastWriteCols) {
-                reset();
-                return;
-            }
-            if (rowsNow !== undefined && lastRows !== undefined) {
-                if (rowsNow < lastRows) {
-                    // I-B17: the screen kept the rows nearest the cursor, so re-pin the canvas onto
-                    // them instead of dropping it. A reset made the next batch a seed over a screen
-                    // that is not empty, which is what left the old status row in the scrollback.
-                    repinShrunk(rowsNow);
-                    return;
-                }
-                if (anchor.kind === 'pinned') {
-                    const capacity = screenCapacity(rowsNow);
-                    const grown = Math.min(applyResizeGrowth(anchor.capacity, lastRows, rowsNow), capacity);
-                    anchor = { kind: 'pinned', top: Math.max(0, capacity - grown), capacity: grown };
-                }
-                lastRows = rowsNow;
-            }
-            // Coalesced and deferred by the host (P0-3); `anchorReprobes` is NOT bumped
-            // here — a drag fires dozens of resize events for one probe (P1-5).
-            requestProbe();
-        },
-        cursorNeutralWrite() {
-            // OSC 52 and friends move no cell and no cursor (I-S11).
-        },
-        regionRows: () => Math.max(0, frameRows),
-        scrollbackStats: () => ({ ...stats, elidedEntries: o.drain.elided() }),
-        setAnchorSpaceBelow(spaceBelow, source) {
-            if (finalized)
-                return;
-            const rows = liveRows();
-            const capacity = screenCapacity(rows);
-            // I-B17: a measurement can arrive after the terminal got shorter without ever
-            // announcing it (`rows` is read live, the `resize` event is optional). The cache
-            // must then stop describing rows the screen has already dropped, or the reach
-            // below would hand the next batch an erase distance longer than the canvas left.
-            if (rows !== undefined)
-                trimCanvasCache(capacity);
-            // I-B14: the report is "rows BELOW the cursor", and the canvas also still owns
-            // `canvasRows` rows ABOVE it, so the reachable height is their sum. Keeping only
-            // the first term collapses the canvas onto the parked row, and the next batch
-            // then reads its own visible content as an overflow and scrolls it away twice.
-            const reach = clampSpaceBelow(spaceBelow, rows) + canvasRows;
-            // The cap bounds only a STARTING canvas: clipping a live one would make the
-            // next erase reach above its own top (see SCROLLBACK_LIMITS.maxCanvasRows).
-            const ceiling = canvasRows === 0
-                ? Math.min(capacity, SCROLLBACK_LIMITS.maxCanvasRows)
-                : capacity;
-            const usable = Math.max(0, Math.min(reach, ceiling));
-            anchor = { kind: 'pinned', top: Math.max(0, capacity - usable), capacity: usable };
-            // A capped starting canvas begins BELOW the cursor row, so the batch that seeds
-            // it has to descend first: `spaceBelow - capacity` rows. Zero whenever the cap
-            // does not bind, and zero for every canvas that already exists.
-            seedDownToTop = Math.max(0, clampSpaceBelow(spaceBelow, rows) - usable);
-            // Only measurements AFTER the first are re-probes (P1-5): `/perf` promises a
-            // re-probe count, not a measurement count, and the startup measurement is
-            // reported through `anchorSource` instead.
-            if (anchorSource !== 'none')
-                anchorReprobes += 1;
-            anchorSource = source;
-            anchorDirty = true;
-            publishAnchorStats();
-        },
-        anchorStats: () => ({
-            state: anchor.kind === 'pinned' ? 'pinned' : 'unknown',
-            source: anchorSource,
-            canvasRows: anchor.kind === 'pinned' ? canvasRows : 0,
-            heldRows: anchor.kind === 'pinned' ? held.length : 0,
-            gapRows: anchor.kind === 'pinned' ? gapRows : 0,
-            top: anchor.kind === 'pinned' ? anchor.top : 0,
-        }),
-        stats: () => ({
-            framesTotal: stats.framesSeed + stats.framesFull + stats.framesDiff,
-            framesDiffed: stats.framesDiff,
-            framesFull: stats.framesSeed + stats.framesFull,
-            linesWritten: stats.staticRowsWritten,
-            bytesWritten: stats.bytesWritten,
-            fallbacks: stats.fallbacks,
-            repaints: stats.repaints,
-        }),
-    };
-}