@aragon-agent/cli 0.6.31 → 0.6.33

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

@@ -1,32 +1,64 @@
 /**
  * ScrollbackWriter — the byte contract of native-scroll mode
- * (tui-native-terminal-scroll §4.3).
+ * (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 directly under the last printed row.
+ * LIVE REGION parked under the last printed row.
  *
- * GEOMETRY IS RELATIVE (D2). A batch is `CUU(H0)` to the top of the previous
- * region, erase down, print static rows, print the new region, park one row below
- * it. Nothing in that sequence depends on the terminal's absolute row count, so a
- * terminal that scrolls underneath it cannot misplace anything.
+ * 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 at (regionBottom + 1, column 0), the same
- *    place Ink's `previousLineCount = H + 1` expects, so falling back to a raw Ink
- *    write is still correct.
+ *  - 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 `H0`.
- *  - I-S14 · after `finalize` EVERY Ink write is swallowed. Ink's unmount renders
- *    once more (and a 32 ms trailing throttle call can follow); passed through,
- *    its `eraseLines(H + 1)` would erase the summary and the end of the
- *    conversation. With an unknown or sub-2-row terminal the frame is still
- *    parsed so `prev`/`H0` track Ink's own `previousLineCount`.
+ *    => 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-A9 · the writer never writes a probe byte; it only asks the host, which owns
+ *    deferral, coalescing and the death switch.
  */
 import type { FrameDiffer } from '../frame-differ.js';
+import { type AnchorSource } from './canvas.js';
 import type { ScrollbackDrain } from './drain.js';
 export interface ScrollbackWriterOptions {
     rows: () => number | undefined;
@@ -45,6 +77,17 @@ export interface ScrollbackWriterOptions {
      * arrive without a new Ink frame, and to flush the rest of an oversized feed.
      */
     requestRepaint?: () => void;
+    /**
+     * Ask the host for one more cursor measurement (resize settled, geometry lost).
+     *
+     * CONTRACT (P0-3), and the writer does NOT implement any of it: the call can
+     * arrive from inside Ink's `stdout.write` (`invalidate` is called by
+     * `transform`), so the host MUST defer it with `setImmediate`, MUST coalesce
+     * everything inside the window into one `ESC[6n`, and MUST drop it after
+     * `finalize`/`dispose`/`exit` — a probe written at a terminal already handed
+     * back to the shell leaks `^[[12;1R` onto the user's prompt (I-A9).
+     */
+    requestAnchorProbe?: () => void;
     /** Injected clock for the resize grace window. */
     now?: () => number;
 }
@@ -63,12 +106,57 @@ export interface ScrollbackWriterStats {
     elidedEntries: number;
     resizes: number;
     repaints: number;
+    /** Where the anchor came from: `probe`, one-off `fill`, or never measured. */
+    anchorSource: AnchorSource;
+    /** Canvas height of the most recent batch — the next erase distance (0 = unknown). */
+    anchorCanvasRows: number;
+    /** Content rows inside that canvas. */
+    anchorHeldRows: number;
+    /** Blank rows above the content in that canvas. */
+    anchorGapRows: number;
+    /** Rows this session pushed into the scrollback (the "is it scrolling" signal). */
+    anchorScrollRows: number;
+    /** Times the geometry was dropped on purpose (column change, shrink, gap lost). */
+    anchorResets: number;
+    /** Measurements accepted AFTER the first one — the re-probe count (not resize events). */
+    anchorReprobes: number;
+}
+export interface CanvasStats {
+    /** `'pinned'` = measured, drawing a canvas; `'unknown'` = legacy append path. */
+    state: 'pinned' | 'unknown';
+    /** Probe / fill origin; `'none'` = never measured. */
+    source: AnchorSource;
+    /** Rows of the most recent canvas (0 while unknown). */
+    canvasRows: number;
+    /** Content rows inside it. */
+    heldRows: number;
+    /** Blank rows above the content. */
+    gapRows: number;
+    /** Canvas top row (0 = the canvas starts at the first screen row). */
+    top: number;
 }
 export interface ScrollbackWriter extends FrameDiffer {
     /** Idempotent. Returns the exit bytes; afterwards every Ink write is swallowed. */
     finalize(summary: readonly string[]): string;
-    /** Rows of the live region as last parked. */
+    /**
+     * Rows of the LIVE REGION as last parked — the frame height `H`, NOT the canvas
+     * (P1-4). `/perf` prints this as "scrollback region N rows", and it has to keep
+     * meaning the same number; the canvas height is `anchorStats().canvasRows`.
+     */
     regionRows(): number;
     scrollbackStats(): ScrollbackWriterStats;
+    /**
+     * The host measured how many blank rows are left below the parked cursor
+     * (`0` = already on the last row). Writes no bytes; the next batch — or the
+     * `repaint()` the host schedules right after — consumes it.
+     *
+     * Idempotent and overwritable: the post-resize re-probe calls it again, and it
+     * must then arrive at the SAME capacity the resize delta did (I-B14). Side
+     * effect: sets `anchorDirty`, which is what lets `repaint()` redraw while the
+     * feed is idle (P0-2).
+     */
+    setAnchorSpaceBelow(spaceBelow: number, source: AnchorSource): void;
+    /** For `/perf` and tests. Produces no bytes. */
+    anchorStats(): CanvasStats;
 }
 export declare function createScrollbackWriter(o: ScrollbackWriterOptions): ScrollbackWriter;