@aragon-agent/cli 0.6.32 → 0.6.34

package/dist/ui/scrollback/tail-window.js

@@ -0,0 +1,74 @@
+/**
+ * The TAIL WINDOW of the native-scroll live region
+ * (tui-full-height-live-region D6 / D7, I-F8 / I-F9).
+ *
+ * WHAT CHANGED AND WHY. The region used to show only the entries the reducer had not
+ * finished writing (`entries.slice(settledCount)`), and everything settled was printed
+ * into the terminal's scrollback the moment it settled. Once the region is the WHOLE
+ * screen (`liveRows = rows - 1`), a printed row is pushed off the top by the very next
+ * frame, so "print on settle" would leave the user staring at a screen of blanks with
+ * only the unfinished cards on it. So the region now shows the last `K` PRINTABLE
+ * entries - settled or not - and an entry is printed when it LEAVES that window.
+ *
+ * The window is defined by ENTRY COUNT, never by measured height; what a single entry
+ * taller than the region used to do is the whole subject of
+ * `overflow-print.ts` (tui-final-reply-truncated-unscrollable). The box still clips it
+ * from the top with `justifyContent="flex-end"`, but the rows it hides are now PRINTED
+ * into the terminal's scrollback, where the wheel already reaches, instead of waiting for
+ * `K` further entries (README, known limitation 2 - rewritten by that fix).
+ *
+ * PURE: no Ink, no I/O, no clock. `promote()` (the writer's only feeder) takes
+ * `printBoundary`'s result and keeps its own `printed` authority, so "printed is
+ * forward-only" (RV-7) is unchanged.
+ *
+ * PRINTABILITY != VISIBILITY. `isExcluded` entries (a non-terminal `service` card) never
+ * print and never take a slot in the window; an entry that is in the window may still be
+ * scrolled out of sight by a taller neighbour. That second gap is what the row-level plan
+ * closes, and `/perf`'s `window=<start>/<n> head=<rows>` is how it stays observable.
+ */
+import { isExcluded, settledCount } from './settled-boundary.js';
+/**
+ * The index of the first entry that is still on screen: count backwards up to
+ * `maxEntries` PRINTABLE entries. Everything before it has left the region and is the
+ * writer's business.
+ *
+ * `maxEntries <= 0` returns `entries.length` - an empty window, which is the old
+ * behaviour ("everything printable may print") and the reason the guard is written as
+ * an early return rather than as a loop bound.
+ */
+export function tailWindowStart(entries, maxEntries) {
+    const limit = Number.isFinite(maxEntries) ? Math.floor(maxEntries) : 0;
+    if (limit <= 0)
+        return entries.length;
+    let seen = 0;
+    for (let i = entries.length - 1; i >= 0; i -= 1) {
+        if (isExcluded(entries[i]))
+            continue;
+        seen += 1;
+        if (seen === limit)
+            return i;
+    }
+    // Fewer printable entries than the window holds: the whole conversation is on screen.
+    return 0;
+}
+/** `entries.slice(start)` with the entries that never print dropped. */
+export function selectTailWindow(entries, maxEntries) {
+    const start = tailWindowStart(entries, maxEntries);
+    return { start, entries: entries.slice(start).filter((entry) => !isExcluded(entry)) };
+}
+/**
+ * The print boundary: never print what the region is still showing.
+ *
+ * THIS IS THE ONLY PLACE THAT COMBINES "settled" WITH "in the window" (RV-P2-13), which
+ * is why the composition lives here instead of at the pump: `promote()` must keep
+ * receiving one number, and the two authorities it is derived from - `settledCount`
+ * (what may print at all) and `tailWindowStart` (what is still visible) - then cannot
+ * drift apart in a future edit.
+ *
+ * `settleAllEntries` is the OTHER authority, not a duplicate: it answers "what must be
+ * printed when the conversation is being torn down", while this answers "how far may
+ * this frame print".
+ */
+export function printBoundary(entries, runActive, maxEntries) {
+    return Math.min(settledCount(entries, runActive), tailWindowStart(entries, maxEntries));
+}

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

@@ -1,31 +1,55 @@
 /**
  * `useScrollbackView` — the promotion pipeline of native-scroll mode
- * (tui-native-terminal-scroll §4.4 / §6.2).
+ * (tui-native-terminal-scroll §4.4 / §6.2, tui-full-height-live-region D3/D4/D7/D8,
+ * tui-final-reply-truncated-unscrollable A-prime).
  *
  * `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).
+ * build (I-S9 / I-F10).
  *
  * 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.
+ *  1. On every entries change, promotes each entry that has LEFT THE TAIL WINDOW:
+ *     renders it once through the offscreen renderer and enqueues the rows for the
+ *     writer. Entries still on screen are never printed - at `H = rows - 1` a printed
+ *     row is pushed back off the top by the next frame, and a second copy in the
+ *     scrollback would be a duplicate the user meets by scrolling up (I-F8).
+ *  2. Gives way at the TOP (tui-final-reply-truncated-unscrollable). The window is still
+ *     counted in ENTRIES, so a settled answer taller than the box used to sit inside the
+ *     window forever, clipped by `justifyContent="flex-end"`, in a mode whose wheel only
+ *     scrolls the terminal's scrollback: the clipped rows existed nowhere the user could
+ *     reach. The rows the box hides are now measured (`overflow-print.ts`) and printed, so
+ *     `scrollback + screen` covers every row exactly once. Screen unchanged, reachability
+ *     fixed.
+ *  3. Computes the live-region budget, the window and the tail rows for the shell.
+ *  4. Flushes the window before either reset path (`/clear`, `--resume`) and on exit,
+ *     so "on screen but not printed yet" can never become "lost" (D8 / I-F12).
+ *
+ * THE HEADER AND THE OPENER ARE NOT PRINTED HERE ANY MORE (D3/D4). They are slots of
+ * `ScrollbackShell` now, rendered inside the region: `H = rows - 1` means any printed
+ * row is immediately scrolled off the screen, so printing the banner would be the same
+ * as not drawing it. Their `renderNode` path, the `startedRef` latch that kept their
+ * element identities stable, and the `printBanner()` call in `settleAll()` are gone.
  *
  * 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.
+ * 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.
+ *
+ * THE PASS READS THE COMMITTED FRAME, NOT THE LATEST RENDER. `latest` is refreshed during
+ * render, so it can be a frame ahead of the screen; `committed` is written by a layout
+ * effect and therefore describes exactly the frame the user is looking at. With
+ * entry-granular bookkeeping the difference was harmless (printing was idempotent per
+ * entry); with ROW-granular bookkeeping it would slice this frame's picture with another
+ * frame's row numbers, and the result is a duplicate or a hole.
  *
- * `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.
+ * `printed` is the ONLY authority on "already printed" (RV-7): a `Map` from entry id to
+ * the leading rows already handed to the writer, and the width they were measured at. 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
+ * `printed` skip.
  */
-import React from 'react';
 import type { Entry } from '../../agent/reducer.js';
 import type { TermCapabilities } from '../capabilities.js';
 import type { DensityMode } from '../density.js';
@@ -41,7 +65,7 @@ export interface ScrollbackBridge {
     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`
+     * `restore()` calls it on every exit path; it is idempotent through `printed`
      * and it releases the offscreen renderer when done.
      */
     settleAllNow: () => void;
@@ -68,10 +92,6 @@ export interface UseScrollbackViewArgs {
     /** 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;
@@ -84,18 +104,34 @@ export interface UseScrollbackViewArgs {
     panelEnabled: boolean;
     /** `buildTeamPanelLayout().rowCount`; 0 when nothing is dispatched. */
     teamRowsNatural: number;
+    /**
+     * `state.expandedToolIds` - REQUIRED, because the height of a window entry depends on it
+     * and a forgotten value would measure an expansion the region is not drawing.
+     */
+    expandedToolIds: Record<string, true>;
 }
 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.
+     * The entries the region is showing, in order (excluded kinds already dropped).
+     * `windowStart` is their index in the full list - together they are what `/perf`
+     * reports as `window=<start>/<n>`, the number that makes the "visible vs printable"
+     * gap observable instead of a guess (known limitation 5).
+     */
+    tailEntries: readonly Entry[];
+    windowStart: number;
+    /**
+     * Measured height of `tailEntries`, once every one of them is stable AND measured at the
+     * current geometry; `undefined` otherwise. `LiveTail` prefers it over the estimate - see
+     * `tail-anchor.ts::resolveTailAnchor` for why the measured answer has to win.
      */
-    unsettledEntries: readonly Entry[];
+    measuredTailRows: number | undefined;
+    /** Rows the top give-way has printed this session; `/perf`'s `head=`. */
+    headRows: number;
     /** Print a fresh EXPANDED copy of an entry; false when it cannot be found / rendered. */
     reprintExpanded(entryId: string): boolean;
-    /** Promote everything printable now (shutdown). */
+    /** Promote everything still unprinted (shutdown) - `flushUnprinted(latest entries)`. */
     settleAll(): void;
     /** Called by `App`'s dispatch wrapper BEFORE a reset action reaches the reducer. */
     notifyReset(kind: ScrollbackResetKind): void;