@aragon-agent/cli 0.6.31 → 0.6.32

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

@@ -64,7 +64,7 @@ function pruneEntryIds(printed, entries) {
             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, } = 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.
@@ -86,6 +86,12 @@ export function useScrollbackView(args) {
     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(() => {
@@ -227,19 +233,44 @@ export function useScrollbackView(args) {
         : 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` is read at memo time; `wanted` is what moves it.
+    // `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]);
+        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: contentCols, rows: budget.liveTailRows, thinkingVisible })
-        : [], [enabled, budget, unsettled, contentCols, thinkingVisible]);
+        ? buildLivePreview({ unsettled, cols: previewCols, rows: budget.liveTailRows, thinkingVisible })
+        : [], [enabled, budget, unsettled, previewCols, thinkingVisible]);
     const reprintExpanded = useCallback((entryId) => {
         if (!enabled || !bridge)
             return false;
@@ -259,5 +290,5 @@ export function useScrollbackView(args) {
             return;
         pendingReset.current = { kind, captured: latest.current.entries };
     }, [enabled]);
-    return { budget, liveTailLines, reprintExpanded, settleAll, notifyReset };
+    return { budget, liveTailLines, unsettledEntries: unsettled, reprintExpanded, settleAll, notifyReset };
 }

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

@@ -21,6 +21,60 @@ export declare function seedBytes(input: {
     /** 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[];
@@ -29,6 +83,20 @@ export declare function fullBytes(input: {
     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[];
@@ -57,5 +125,3 @@ export declare function clipLine(line: string, maxCols: number): {
     text: string;
     clipped: boolean;
 };
-/** Rows the previous region occupies after the terminal re-flowed it to `cols` (§4.10). */
-export declare function estimateReflowRows(lines: readonly string[], cols: number): number;

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

@@ -32,10 +32,63 @@ export function seedBytes(input) {
     const lead = input.reseed ? '\r\n' : '';
     return wrapSync(lead + '\r' + SGR0 + rows(input.statics) + rows(input.lines), input.sync);
 }
+/**
+ * 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 function skipRows(rows) {
+    return down(Math.max(0, Math.floor(Number.isFinite(rows) ? rows : 0)));
+}
+/**
+ * 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 function canvasSeedBytes(input) {
+    const lead = input.reseed ? '\r\n' : '';
+    const skip = skipRows(input.downToTop) + skipRows(input.gap);
+    return wrapSync(lead + '\r' + SGR0 + skip + rows(input.held) + rows(input.lines), input.sync);
+}
+/**
+ * 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 function canvasBytes(input) {
+    return wrapSync(up(input.eraseUp) + '\r' + SGR0 + ED0 + skipRows(input.gap) +
+        rows(input.held) + rows(input.lines), input.sync);
+}
 /** Erase exactly the previous live region, print static rows, redraw the region. */
 export function fullBytes(input) {
     return wrapSync(up(input.eraseUp) + '\r' + SGR0 + ED0 + rows(input.statics) + rows(input.lines), input.sync);
 }
+/**
+ * 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 function fillBytes(count) {
+    return '\r\n'.repeat(Math.max(0, Math.floor(count)));
+}
 /** Same height, no static rows: rewrite only the rows that changed. `''` if none did. */
 export function diffBytes(input) {
     const { lines, prev } = input;
@@ -104,11 +157,3 @@ export function clipLine(line, maxCols) {
     }
     return { text: out, clipped: false };
 }
-/** Rows the previous region occupies after the terminal re-flowed it to `cols` (§4.10). */
-export function estimateReflowRows(lines, cols) {
-    const width = Math.max(1, cols);
-    let total = 0;
-    for (const line of lines)
-        total += Math.max(1, Math.ceil(stringWidth(stripAnsi(line)) / width));
-    return total;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.6.31",
+  "version": "0.6.32",
   "description": "AragonAgent CLI — a Claude-Code / Codex-style interactive terminal UI (TUI) on top of the @aragon-agent/core engine. Installable and runnable via npm / npx.",
   "license": "MIT",
   "author": "AragonAgent contributors",
@@ -56,7 +56,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.43",
+    "@aragon-agent/core": "^0.2.44",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",
@@ -76,6 +76,6 @@
     "@types/react": "^18.3.0",
     "ink-testing-library": "^4.0.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.0"
+    "vitest": "4.1.9"
   }
 }