@aragon-agent/cli 0.6.29 → 0.6.32

package/dist/ui/scrollback/settled-boundary.js

@@ -0,0 +1,106 @@
+/**
+ * Settled boundary — which transcript entries may be PRINTED
+ * (tui-native-terminal-scroll §4.4).
+ *
+ * Printed rows live in the host terminal's scrollback and can never be rewritten
+ * ("printed is forever"). So the only entries that may be printed are the ones the
+ * reducer will NEVER write to again. This module derives that from the reducer's
+ * real write set, one exhaustive `switch` per entry kind. Adding an `Entry` kind is
+ * a compile error here (`never`), which is the whole point; widening the write set
+ * of an EXISTING kind is not caught by the compiler, so `agent/reducer.ts` carries
+ * a pointer comment beside the `Entry` union and the unit tests pin each row.
+ *
+ * Three rules that are easy to "simplify" wrongly:
+ *  - A tool is stable only when `done` or `error`. `pending` is NOT stable: the
+ *    card is created at `pending` and `toolCallDelta` keeps rewriting `argsRaw`
+ *    while the model streams its arguments (RV-1).
+ *  - A trailing `Context length exceeded` error notice is NOT stable while a run is
+ *    active: `compactionStart` rewrites it in place into an info notice (RV-4).
+ *  - A non-terminal `service` card is neither printed nor a wall (RV-3). It is
+ *    rewritten for the whole session; the one-row `terminal: true` record the
+ *    reducer appends at the end is an ordinary stable entry and carries the news.
+ */
+import { CONTEXT_OVERFLOW_NOTICE_PREFIX } from '../../agent/reducer.js';
+/** Kinds the reducer may still rewrite while a run is active, so a tail one is held. */
+const MUTABLE_TAIL_KINDS = new Set([
+    'assistant', 'tool', 'compaction', 'todo', 'team', 'fast', 'retry', 'queued',
+]);
+/** Never printed and never a wall: rewritten for the whole session (RV-3). */
+export function isExcluded(entry) {
+    return entry.kind === 'service' && entry.terminal !== true;
+}
+/** True when the reducer will never write to `entry` again. */
+export function isEntryStable(entry, runActive, isTail) {
+    switch (entry.kind) {
+        case 'user':
+            return true;
+        case 'notice':
+            return !(runActive &&
+                isTail &&
+                entry.level === 'error' &&
+                entry.text.startsWith(CONTEXT_OVERFLOW_NOTICE_PREFIX));
+        case 'assistant':
+            return !entry.streaming;
+        case 'tool':
+            return entry.status === 'done' || entry.status === 'error';
+        case 'compaction':
+            return entry.live !== true;
+        case 'todo':
+            return entry.live === false;
+        case 'team':
+            return entry.active === false;
+        case 'fast':
+            return entry.live === false;
+        case 'retry':
+            return (entry.phase === 'recovered' ||
+                entry.phase === 'exhausted' ||
+                entry.phase === 'interrupted');
+        case 'queued':
+            // Rewritten in place into a `user` entry by the matching receipt.
+            return false;
+        case 'service':
+            // Only the terminal record is ever a candidate; `isExcluded` filters the rest.
+            return entry.terminal === true;
+        default: {
+            const exhaustive = entry;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * Length of the printable PREFIX of `entries`.
+ *
+ * The first unstable (non-excluded) entry is a wall: everything before it may
+ * print, nothing after it may, which keeps scrollback order equal to conversation
+ * order (I-S3). Excluded entries are skipped, so a long-lived service card never
+ * blocks the conversation behind it.
+ */
+export function settledCount(entries, runActive) {
+    const last = entries.length - 1;
+    let count = entries.length;
+    for (let i = 0; i < entries.length; i += 1) {
+        const entry = entries[i];
+        if (isExcluded(entry))
+            continue;
+        if (!isEntryStable(entry, runActive, i === last)) {
+            count = i;
+            break;
+        }
+    }
+    // Hold a mutable TAIL while a run is active, but only a mutable one: a `user` or
+    // `notice` at the tail prints immediately (a submitted message must appear at once).
+    if (runActive && count === entries.length && count > 0) {
+        const tail = entries[last];
+        if (!isExcluded(tail) && MUTABLE_TAIL_KINDS.has(tail.kind))
+            return last;
+    }
+    return count;
+}
+/**
+ * Everything printable at shutdown: all entries except those that never settle
+ * (`queued`, non-terminal services). The last answer must not be lost to a
+ * boundary that was waiting for a frame that will never come.
+ */
+export function settleAllEntries(entries) {
+    return entries.filter((entry) => entry.kind !== 'queued' && !isExcluded(entry));
+}

package/dist/ui/scrollback/use-scrollback-view.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `useScrollbackView` — the promotion pipeline of native-scroll mode
+ * (tui-native-terminal-scroll §4.4 / §6.2).
+ *
+ * `App` calls it ALWAYS (hooks cannot be conditional); `enabled: false` makes every
+ * effect a no-op and keeps `scrollMode: 'app'` byte-identical to the pre-feature
+ * build (I-S9).
+ *
+ * What it does when enabled:
+ *  1. Prints the session header (and the opener for an empty session) once.
+ *  2. On every entries change, promotes each newly SETTLED entry: renders it once
+ *     through the offscreen renderer and enqueues the rows for the writer.
+ *  3. Computes the live-region budget and the streaming preview rows for the shell.
+ *
+ * THE PROMOTION RUNS IN A MICROTASK, NOT IN THE EFFECT. The offscreen renderer is a
+ * second Ink instance, and both instances share one React reconciler. A `rerender`
+ * issued from inside the main tree's commit (a layout effect) is deferred until that
+ * commit finishes, so its frame would not exist when the effect reads it. A
+ * microtask runs after the commit has unwound, where the offscreen render is
+ * synchronous again. Everything the pass needs is read from refs for that reason.
+ *
+ * `printedIds` is the ONLY authority on "already printed" (RV-7). The cursor is just
+ * a hint for where to resume scanning: entries leave the list by retain-ring
+ * trimming AND by reducer deletion (empty settled assistants, abandoned tool
+ * cards), so an id-keyed cursor can dangle, and then the only correct answer is to
+ * rescan and let `printedIds` skip.
+ */
+import React from 'react';
+import type { Entry } from '../../agent/reducer.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { DensityMode } from '../density.js';
+import type { Theme } from '../theme.js';
+import { type ScrollbackBudget } from './budget.js';
+import type { ScrollbackDrain } from './drain.js';
+import type { ScrollbackWriter } from './scrollback-writer.js';
+/** The channel between `cli.tsx` (which owns the stream) and the React tree. */
+export interface ScrollbackBridge {
+    writer: ScrollbackWriter;
+    drain: ScrollbackDrain;
+    /** Installed by `cli.tsx`: schedule `writer.repaint()` soon. */
+    requestFlush: () => void;
+    /**
+     * Installed by the hook on mount (reads the latest entries through a ref).
+     * `restore()` calls it on every exit path; it is idempotent through `printedIds`
+     * and it releases the offscreen renderer when done.
+     */
+    settleAllNow: () => void;
+    /** Installed by `App`; at most `exitSummaryMaxRows` rows. Wrapped in try/catch by the caller. */
+    getSummaryRows: () => readonly string[];
+    /** Installed by `App`: the writer swallowed repeated tall frames (degrade to the placeholder). */
+    onGuardTrip: (() => void) | null;
+}
+export declare function createScrollbackBridge(parts: Pick<ScrollbackBridge, 'writer' | 'drain'> & {
+    requestFlush?: () => void;
+}): ScrollbackBridge;
+export type ScrollbackResetKind = 'clear' | 'restore';
+export interface UseScrollbackViewArgs {
+    /** `scrollMode === 'native'`. */
+    enabled: boolean;
+    bridge: ScrollbackBridge | undefined;
+    entries: readonly Entry[];
+    runActive: boolean;
+    theme: Theme;
+    caps: TermCapabilities;
+    density: DensityMode;
+    thinkingVisible: boolean;
+    reducedMotion: boolean;
+    /** Terminal size. */
+    rows: number;
+    cols: number;
+    /** Printed first, once. */
+    headerNode: React.ReactNode;
+    /** Printed after the header for an empty session. */
+    openerNode: React.ReactNode | null;
+    overlayOpen: boolean;
+    draftRows: number;
+    popupRows: number;
+    statusExpanded: boolean;
+    /** Degrade the region to the placeholder (the writer's tall-frame guard tripped). */
+    forceInactive?: boolean;
+    /** `state.todos.items.length` - 0 means there is no plan, so the rail has no work to show. */
+    itemCount: number;
+    /** `cfg.todo.panel`: the user can switch the rail off entirely. */
+    panelEnabled: boolean;
+    /** `buildTeamPanelLayout().rowCount`; 0 when nothing is dispatched. */
+    teamRowsNatural: number;
+}
+export interface ScrollbackView {
+    budget: ScrollbackBudget | null;
+    liveTailLines: string[];
+    /**
+     * The exact list `liveTailLines` was built from, so the real-component tail
+     * (`LiveTail`) and the plain-text fallback can never disagree about their input.
+     */
+    unsettledEntries: readonly Entry[];
+    /** Print a fresh EXPANDED copy of an entry; false when it cannot be found / rendered. */
+    reprintExpanded(entryId: string): boolean;
+    /** Promote everything printable now (shutdown). */
+    settleAll(): void;
+    /** Called by `App`'s dispatch wrapper BEFORE a reset action reaches the reducer. */
+    notifyReset(kind: ScrollbackResetKind): void;
+}
+export declare function useScrollbackView(args: UseScrollbackViewArgs): ScrollbackView;

package/dist/ui/scrollback/use-scrollback-view.js

@@ -0,0 +1,294 @@
+/**
+ * `useScrollbackView` — the promotion pipeline of native-scroll mode
+ * (tui-native-terminal-scroll §4.4 / §6.2).
+ *
+ * `App` calls it ALWAYS (hooks cannot be conditional); `enabled: false` makes every
+ * effect a no-op and keeps `scrollMode: 'app'` byte-identical to the pre-feature
+ * build (I-S9).
+ *
+ * What it does when enabled:
+ *  1. Prints the session header (and the opener for an empty session) once.
+ *  2. On every entries change, promotes each newly SETTLED entry: renders it once
+ *     through the offscreen renderer and enqueues the rows for the writer.
+ *  3. Computes the live-region budget and the streaming preview rows for the shell.
+ *
+ * THE PROMOTION RUNS IN A MICROTASK, NOT IN THE EFFECT. The offscreen renderer is a
+ * second Ink instance, and both instances share one React reconciler. A `rerender`
+ * issued from inside the main tree's commit (a layout effect) is deferred until that
+ * commit finishes, so its frame would not exist when the effect reads it. A
+ * microtask runs after the commit has unwound, where the offscreen render is
+ * synchronous again. Everything the pass needs is read from refs for that reason.
+ *
+ * `printedIds` is the ONLY authority on "already printed" (RV-7). The cursor is just
+ * a hint for where to resume scanning: entries leave the list by retain-ring
+ * trimming AND by reducer deletion (empty settled assistants, abandoned tool
+ * cards), so an id-keyed cursor can dangle, and then the only correct answer is to
+ * rescan and let `printedIds` skip.
+ */
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import { buildScrollbackBudget } from './budget.js';
+import { buildLivePreview } from './live-preview.js';
+import { SCROLLBACK_LIMITS } from './limits.js';
+import { createEntryRenderer } from './renderer.js';
+import { isExcluded, settleAllEntries, settledCount } from './settled-boundary.js';
+export function createScrollbackBridge(parts) {
+    return {
+        writer: parts.writer,
+        drain: parts.drain,
+        requestFlush: parts.requestFlush ?? (() => undefined),
+        settleAllNow: () => undefined,
+        getSummaryRows: () => [],
+        onGuardTrip: null,
+    };
+}
+const CLEARED_ROW = '---- conversation cleared ----';
+const RESTORED_ROW = '---- session restored ----';
+function printableBefore(entries, index) {
+    for (let i = index - 1; i >= 0; i -= 1) {
+        if (!isExcluded(entries[i]))
+            return entries[i];
+    }
+    return undefined;
+}
+/**
+ * Ids leave `entries` by retain-ring trimming and never come back (ids are unique
+ * per session), so `printedIds` is trimmed to the live list once it grows well past
+ * it. Only ids still present can be re-evaluated, so dropping the rest is lossless.
+ */
+function pruneEntryIds(printed, entries) {
+    if (printed.size <= Math.max(2000, entries.length * 3))
+        return;
+    const live = new Set(entries.map((entry) => entry.id));
+    for (const id of printed)
+        if (!live.has(id))
+            printed.delete(id);
+}
+export function useScrollbackView(args) {
+    const { enabled, bridge, entries, runActive, theme, caps, density, thinkingVisible, reducedMotion, rows, cols, headerNode, openerNode, overlayOpen, draftRows, popupRows, statusExpanded, forceInactive = false, itemCount, panelEnabled, teamRowsNatural, } = args;
+    const contentCols = Math.max(1, cols - 1);
+    const startedRef = useRef(false);
+    // Everything the asynchronous pass reads travels here, refreshed on every render.
+    const latest = useRef({
+        entries, runActive, contentCols, headerNode, openerNode,
+        options: { theme, caps, density, thinkingVisible, reducedMotion },
+    });
+    latest.current = {
+        entries, runActive, contentCols,
+        // The banner nodes only matter until the banner is printed; afterwards keep the
+        // old references so a changing element identity is not mistaken for new input.
+        headerNode: startedRef.current ? latest.current.headerNode : headerNode,
+        openerNode: startedRef.current ? latest.current.openerNode : openerNode,
+        options: { theme, caps, density, thinkingVisible, reducedMotion },
+    };
+    const rendererRef = useRef(null);
+    const printedIds = useRef(new Set());
+    /** A resume hint only (RV-7): the id of the last entry the previous pass covered. */
+    const cursorRef = useRef(null);
+    const pendingReset = useRef(null);
+    const heldTailRows = useRef(0);
+    // Band hysteresis (release-gate-and-native-panels §6.7). Same lifecycle and same
+    // reason as `heldTailRows`: the writer re-lays out the canvas on every batch, so a
+    // band that shrank for two frames would make everything above the composer jump.
+    const heldRailRows = useRef(0);
+    const heldTeamRows = useRef(0);
+    const heldGeometry = useRef({ rows, cols });
+    const pumpQueued = useRef(false);
+    const mountedRef = useRef(true);
+    const ensureRenderer = useCallback(() => {
+        if (!rendererRef.current)
+            rendererRef.current = createEntryRenderer(latest.current.options);
+        rendererRef.current.setOptions(latest.current.options);
+        return rendererRef.current;
+    }, []);
+    const enqueue = useCallback((rowsToPrint, id, kind) => {
+        if (rowsToPrint.length === 0 || !bridge)
+            return;
+        bridge.drain.enqueue(rowsToPrint, { id, kind });
+    }, [bridge]);
+    /** Promote `list[start..end)`; returns true when it stopped early because the feed is full. */
+    const promote = useCallback((list, end, limit) => {
+        const renderer = ensureRenderer();
+        let start = 0;
+        const cursor = cursorRef.current;
+        if (cursor && list[cursor.index]?.id === cursor.id)
+            start = cursor.index + 1;
+        let promoted = 0;
+        let lastIndex = start - 1;
+        const remember = () => {
+            cursorRef.current = lastIndex >= 0 ? { id: list[lastIndex].id, index: lastIndex } : null;
+        };
+        for (let i = start; i < end; i += 1) {
+            const entry = list[i];
+            if (isExcluded(entry) || printedIds.current.has(entry.id)) {
+                lastIndex = i;
+                continue;
+            }
+            if (promoted >= limit) {
+                remember();
+                return true;
+            }
+            const rowsToPrint = renderer.renderEntry(entry, printableBefore(list, i), latest.current.contentCols);
+            enqueue(rowsToPrint, entry.id, entry.kind);
+            // A rendered-to-nothing entry is registered too, or it would be retried forever.
+            printedIds.current.add(entry.id);
+            promoted += 1;
+            lastIndex = i;
+        }
+        remember();
+        return false;
+    }, [ensureRenderer, enqueue]);
+    const printBanner = useCallback(() => {
+        if (startedRef.current)
+            return;
+        startedRef.current = true;
+        const renderer = ensureRenderer();
+        const { headerNode: header, openerNode: opener, contentCols: width } = latest.current;
+        enqueue(renderer.renderNode(header, width), 'startup:header', 'header');
+        if (opener)
+            enqueue(renderer.renderNode(opener, width), 'startup:opener', 'opener');
+    }, [ensureRenderer, enqueue]);
+    const applyPendingReset = useCallback(() => {
+        const reset = pendingReset.current;
+        if (!reset || latest.current.entries === reset.captured)
+            return;
+        pendingReset.current = null;
+        printedIds.current = new Set();
+        cursorRef.current = null;
+        enqueue([reset.kind === 'clear' ? CLEARED_ROW : RESTORED_ROW], `reset:${Date.now()}`, 'notice');
+    }, [enqueue]);
+    const pumpRef = useRef(() => undefined);
+    const schedulePump = useCallback(() => {
+        if (pumpQueued.current)
+            return;
+        pumpQueued.current = true;
+        queueMicrotask(() => pumpRef.current());
+    }, []);
+    /** The promotion pass. Runs in a microtask (see the file header). */
+    pumpRef.current = () => {
+        pumpQueued.current = false;
+        if (!mountedRef.current || !bridge)
+            return;
+        printBanner();
+        applyPendingReset();
+        const { entries: list, runActive: active } = latest.current;
+        const limit = Math.max(1, SCROLLBACK_LIMITS.feedCapacity - bridge.drain.pendingEntries() - 1);
+        const more = promote(list, settledCount(list, active), limit);
+        pruneEntryIds(printedIds.current, list);
+        if (more) {
+            // Continue once the writer has consumed what is queued (a restored transcript
+            // longer than the feed is promoted in waves rather than folded into a marker).
+            bridge.drain.onDrained = () => {
+                bridge.drain.onDrained = null;
+                schedulePump();
+            };
+            bridge.requestFlush();
+        }
+    };
+    useLayoutEffect(() => {
+        if (enabled && bridge)
+            schedulePump();
+    }, [enabled, bridge, entries, runActive, schedulePump]);
+    const settleAll = useCallback(() => {
+        if (!bridge)
+            return;
+        const list = latest.current.entries;
+        const renderer = ensureRenderer();
+        printBanner();
+        // Shutdown must not leave anything behind, so no per-pass limit.
+        for (const entry of settleAllEntries(list)) {
+            if (printedIds.current.has(entry.id))
+                continue;
+            enqueue(renderer.renderEntry(entry, printableBefore(list, list.indexOf(entry)), latest.current.contentCols), entry.id, entry.kind);
+            printedIds.current.add(entry.id);
+        }
+    }, [bridge, ensureRenderer, printBanner, enqueue]);
+    // Shutdown hook for the exit paths. `restore()` runs it AFTER the tree is gone
+    // (normal exit) or while it is alive (signal), so it renders synchronously and then
+    // releases the offscreen instance. The unmount cleanup deliberately renders nothing:
+    // it runs inside the main tree's commit, where an offscreen render is deferred.
+    const settleAllRef = useRef(settleAll);
+    settleAllRef.current = settleAll;
+    useEffect(() => {
+        mountedRef.current = true;
+        if (!enabled || !bridge)
+            return undefined;
+        bridge.settleAllNow = () => {
+            try {
+                settleAllRef.current();
+            }
+            finally {
+                rendererRef.current?.dispose();
+                rendererRef.current = null;
+            }
+        };
+        return () => { mountedRef.current = false; };
+    }, [enabled, bridge]);
+    // --- Live region budget and streaming preview. ---------------------------
+    const boundary = useMemo(() => settledCount(entries, runActive), [entries, runActive]);
+    const unsettled = useMemo(() => entries.slice(boundary).filter((entry) => !isExcluded(entry)), [entries, boundary]);
+    const wanted = enabled
+        ? buildLivePreview({
+            unsettled, cols: contentCols, rows: SCROLLBACK_LIMITS.maxLiveTailRows, thinkingVisible,
+        }).length
+        : 0;
+    // D11 · the preview height only grows while anything is unsettled, then resets.
+    heldTailRows.current = unsettled.length === 0 ? 0 : Math.max(heldTailRows.current, wanted);
+    // The band's hysteresis has exactly THREE reset points and no others: the plan
+    // emptied, the dispatch finished, or the geometry changed (a new size is a new
+    // measurement - the same treatment `App` gives `guardTripped`).
+    if (heldGeometry.current.rows !== rows || heldGeometry.current.cols !== cols) {
+        heldGeometry.current = { rows, cols };
+        heldRailRows.current = 0;
+        heldTeamRows.current = 0;
+    }
+    if (itemCount === 0)
+        heldRailRows.current = 0;
+    if (teamRowsNatural === 0)
+        heldTeamRows.current = 0;
+    const budget = useMemo(() => enabled
+        ? buildScrollbackBudget({
+            rows, cols, draftRows, popupRows, statusExpanded, overlayOpen,
+            liveTailWanted: heldTailRows.current, forceInactive,
+            band: {
+                itemCount, panelEnabled, teamRowsNatural,
+                heldRailRows: heldRailRows.current, heldTeamRows: heldTeamRows.current,
+            },
+        })
+        : null, 
+    // `heldTailRows.current` and the two band refs are read at memo time; `wanted`,
+    // `itemCount` and `teamRowsNatural` are what move them. ONE memo, deliberately:
+    // a second one depending on the first would render the previous frame's band.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [enabled, rows, cols, draftRows, popupRows, statusExpanded, overlayOpen, wanted,
+        unsettled.length, forceInactive, itemCount, panelEnabled, teamRowsNatural]);
+    if (budget) {
+        // Monotone memory, fed back into the memo above on the next frame.
+        heldRailRows.current = budget.band.heldRailRows;
+        heldTeamRows.current = budget.band.heldTeamRows;
+    }
+    // Print keeps `contentCols`; only the live preview gives up the rail's columns (I-5).
+    const previewCols = budget ? budget.previewCols : contentCols;
+    const liveTailLines = useMemo(() => enabled && budget && budget.liveTailRows > 0
+        ? buildLivePreview({ unsettled, cols: previewCols, rows: budget.liveTailRows, thinkingVisible })
+        : [], [enabled, budget, unsettled, previewCols, thinkingVisible]);
+    const reprintExpanded = useCallback((entryId) => {
+        if (!enabled || !bridge)
+            return false;
+        const list = latest.current.entries;
+        const index = list.findIndex((entry) => entry.id === entryId);
+        if (index < 0)
+            return false;
+        const entry = list[index];
+        const body = ensureRenderer().renderEntry(entry, undefined, latest.current.contentCols, true);
+        if (body.length === 0)
+            return false;
+        enqueue([`-- expanded: ${entry.kind === 'tool' ? entry.name : entry.kind} --`, ...body], `expanded:${entryId}:${Date.now()}`, entry.kind);
+        return true;
+    }, [enabled, bridge, ensureRenderer, enqueue]);
+    const notifyReset = useCallback((kind) => {
+        if (!enabled)
+            return;
+        pendingReset.current = { kind, captured: latest.current.entries };
+    }, [enabled]);
+    return { budget, liveTailLines, unsettledEntries: unsettled, reprintExpanded, settleAll, notifyReset };
+}

package/dist/ui/scrollback/writer-shapes.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Byte shapes of the native-scroll writer (tui-native-terminal-scroll §4.3 /
+ * Appendix A). Stateless string assembly only — the state machine that decides
+ * WHICH shape to emit lives in `scrollback-writer.ts`.
+ *
+ * THE WHITELIST (I-S5 / I-S6). Every byte produced here is drawn from: SGR, CUU,
+ * CUD, CR, CRLF, ED0, EL0, DEC 2026 and DECTCEM. There is no absolute CUP, no
+ * scroll region, no `CSI S/T`, no `ED2/ED3`. Relative addressing is what makes the
+ * geometry independent of the terminal scrolling underneath it (spec appendix B).
+ *
+ * Each row is `SGR0 · text · SGR0`: the leading reset stops one row's style leaking
+ * into the next, and the trailing one stops a background-colour-erase terminal from
+ * painting the following ED0/EL0 in the row's last colour.
+ */
+export declare const SGR0 = "\u001B[0m";
+/** First write of a session: the cursor is already on a fresh line at column 0. */
+export declare function seedBytes(input: {
+    lines: readonly string[];
+    statics: readonly string[];
+    sync: boolean;
+    /** After a foreign write the cursor may sit mid-line; start on a new one (RV-11). */
+    reseed: boolean;
+}): string;
+/**
+ * CUD(n): move down n rows WITHOUT writing a single cell.
+ *
+ * This is how the canvas spends its `gap` (D3). A blank row that is never written
+ * cannot be pushed into the scrollback by a later overflow, which is the whole
+ * reason the gap is not a run of `\r\n` (I-B3). The sequence is already whitelisted
+ * (`diffBytes` uses it to step between changed rows); this is the same CUD used to
+ * skip empty space instead.
+ */
+export declare function skipRows(rows: number): string;
+/**
+ * First canvas batch (or the first one after a reset): the screen below the cursor
+ * is assumed empty, so there is nothing to erase — only `[gap][content][region]` to
+ * write, ending with the cursor parked on the last row.
+ */
+export declare function canvasSeedBytes(input: {
+    /**
+     * Rows to descend from the cursor to the canvas top, when the canvas is shorter
+     * than the space measured below the cursor.
+     *
+     * Non-zero only on a terminal taller than the start-of-canvas cap: the canvas then
+     * begins BELOW the cursor, and a seed that started writing at the cursor would park
+     * the region low and leave the top of the canvas empty for the whole session.
+     */
+    downToTop: number;
+    /** Blank rows to skip before the first content row. */
+    gap: number;
+    /** Content rows, already clipped, oldest first. */
+    held: readonly string[];
+    /** The live region. */
+    lines: readonly string[];
+    sync: boolean;
+    /** After a foreign write the cursor may sit mid-line; start on a new one. */
+    reseed: boolean;
+}): string;
+/**
+ * Redraw the whole canvas: erase the previous one, then write `[gap][content][region]`.
+ *
+ * ORDER IS SEMANTICS: `ED0`, then the gap, then the content, then the region. Moving
+ * the gap after the content puts the blank space back between the reply and the
+ * composer, which is the exact defect this feature fixes (M1 in the spec).
+ *
+ * `held` is the FULL content sequence, not the part that will still be on screen: the
+ * rows that do not fit are supposed to leave through the bottom, and the terminal can
+ * only scroll away what it was given.
+ */
+export declare function canvasBytes(input: {
+    /** Previous canvas height: the erase distance. */
+    eraseUp: number;
+    gap: number;
+    held: readonly string[];
+    lines: readonly string[];
+    sync: boolean;
+}): string;
+/** Erase exactly the previous live region, print static rows, redraw the region. */
+export declare function fullBytes(input: {
+    lines: readonly string[];
+    statics: readonly string[];
+    /** Rows between the region top and the parked cursor. */
+    eraseUp: number;
+    sync: boolean;
+}): string;
+/**
+ * Fill the screen down to the LAST row before the first batch (D4 rung 2 / §4.3).
+ *
+ * This is the fallback for a terminal that never answers `ESC[6n`: from any row, a
+ * run of `rows - 1` line feeds is guaranteed to leave the cursor on the bottom row
+ * (extra feeds only scroll, which is why the count is the caller's business). It is
+ * written ONCE, before anything else, so the rows it scrolls away are the host's old
+ * output — which is still in the scrollback — and never this session's content.
+ *
+ * The argument is the NUMBER OF LINE FEEDS, not the terminal height: `cli.tsx` passes
+ * `rows - 1`. Naming it after the height instead made the caller subtract twice and
+ * left the cursor one row short of the bottom.
+ */
+export declare function fillBytes(count: number): string;
+/** Same height, no static rows: rewrite only the rows that changed. `''` if none did. */
+export declare function diffBytes(input: {
+    lines: readonly string[];
+    prev: readonly string[];
+    sync: boolean;
+}): string;
+/**
+ * Exit: erase the live region, flush leftover static rows, print the summary.
+ * `eraseUp < 0` means the geometry is unknown (a foreign write intervened), in
+ * which case the only safe move is to start on a fresh line and erase nothing.
+ */
+export declare function finalizeBytes(input: {
+    eraseUp: number;
+    statics: readonly string[];
+    summary: readonly string[];
+}): string;
+/**
+ * Cut a row to `maxCols` DISPLAY columns (I-S13), keeping SGR / OSC 8 intact.
+ *
+ * Returns the input unchanged (same reference) when it already fits, which is the
+ * overwhelmingly common case. Width is measured the way Ink measures it
+ * (`string-width` over the ANSI-stripped text): that is the number Ink used to
+ * wrap, so a disagreement with the terminal is the only way a row can exceed it.
+ */
+export declare function clipLine(line: string, maxCols: number): {
+    text: string;
+    clipped: boolean;
+};