@aragon-agent/cli 0.5.4 → 0.5.8

package/dist/ui/layout/rail.js

@@ -0,0 +1,68 @@
+/**
+ * Rail geometry (todo-plan-execution §3.9) — the ONE place that says how wide
+ * and how tall the todo rail is allowed to be.
+ *
+ * Pure and React-free, mirroring `budget.ts`, so `todo-rail.test.ts` can pin the
+ * arithmetic without mounting anything. Deliberately NOT part of `budget.ts`:
+ * that module answers "how many ROWS does the viewport get" and stays a function
+ * of `rows` alone; the rail spends COLUMNS.
+ *
+ * NAMED FOR ITS POSITION, NOT ITS CONTENT, like `AppShellProps.rail` (D-18):
+ * this is a layout primitive and `viewportRows` is its neighbour, not
+ * `TodoPanel`.
+ */
+import { TODO_LIMITS } from '../../todo/limits.js';
+/** R-e, literally: the rail asks for a fifth of the terminal. */
+const RAIL_FRACTION = 0.2;
+/** Below this the marker + a two-word title do not fit and the column is noise. */
+export const TODO_RAIL_MIN_COLS = 18;
+/**
+ * Above this, 20% is being spent on whitespace: at 36 columns a step title
+ * already fits on one line, and the transcript is the surface that benefits from
+ * a 200-column terminal. A deliberate, revertible deviation from a literal
+ * reading of R-e; it only binds above 180 columns.
+ */
+export const TODO_RAIL_MAX_COLS = 36;
+/** Under 80 columns the transcript needs every column; no rail at all. */
+export const TODO_RAIL_MIN_TOTAL_COLS = 80;
+/** Below this rail width the 2-column index prefix is dropped for content. */
+export const TODO_RAIL_INDEX_MIN_COLS = 22;
+/**
+ * Two properties are pinned by tests, for the reason `budget.ts` records about
+ * the viewport being non-monotonic before anyone measured it:
+ *
+ *  - NON-DECREASING in `cols` across [40, 300]. A user dragging a window wider
+ *    must never see the rail get narrower.
+ *  - `cols - todoRailWidth(cols) >= 62` for every `cols >= 80`. Every existing
+ *    width heuristic inside the viewport (`TERSE_HINT_COLS` 42,
+ *    `MIN_INDICATOR_COLS` 50, the status bar's 60/72 steps) sits below that
+ *    floor, so no existing behaviour changes because a rail appeared (R-3).
+ */
+export function todoRailWidth(cols) {
+    if (!Number.isFinite(cols) || cols < TODO_RAIL_MIN_TOTAL_COLS)
+        return 0;
+    return Math.min(TODO_RAIL_MAX_COLS, Math.max(TODO_RAIL_MIN_COLS, Math.round(cols * RAIL_FRACTION)));
+}
+/**
+ * How many rows the rail may actually draw.
+ *
+ * IT IS NOT `viewportBudget`, AND THE DIFFERENCE IS NOT COSMETIC (P1-3 / D-23).
+ * `viewportRows()` subtracts the STATIC chrome only, and says so; the live team
+ * roster is mounted inside `AppShell`'s measured bottom box, where it costs a
+ * header row, up to `TEAM_LIMITS.panelMaxRows` child rows, a `+N more` row and a
+ * mail row that `viewportBudget` knows nothing about. `ScrollViewport` is immune
+ * because it MEASURES itself; the rail does not measure - a second
+ * measure -> setState -> measure loop is exactly what §1.2 refuses - so it has
+ * to subtract.
+ *
+ * Ink clips overflow from the BOTTOM, so an over-request does not error: it
+ * silently eats the last row, which is the `+N below` marker - the one row whose
+ * absence is indistinguishable from "the list is short". That is why this is
+ * arithmetic rather than a shrug at `overflow: hidden`.
+ */
+export function todoRailRows(viewportBudget, teamActive) {
+    if (!Number.isFinite(viewportBudget))
+        return 0;
+    const reserved = teamActive ? TODO_LIMITS.railReservedRows : 0;
+    return Math.max(0, viewportBudget - reserved);
+}

package/dist/ui/layout/viewport-geometry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Viewport geometry, published downward (tui-render-performance L3).
+ *
+ * `ScrollViewport`'s header records (P1-7) why it — and not its parent — owns
+ * the metrics and the scroll offset: holding the offset in two places creates a
+ * measure -> setState -> re-render -> measure loop whose convergence is provable
+ * but whose frame count is not.
+ *
+ * Virtualisation needs those same three numbers one level DOWN, in
+ * `TranscriptList`. So the viewport PUBLISHES rather than lifting: a `useMemo`d
+ * context value, no new state, no second owner, no extra layout pass.
+ */
+export interface ViewportGeometry {
+    /** Visible height of the clipping box, in rows. `0` before the first measure. */
+    viewportRows: number;
+    /** Rows hidden BELOW the viewport (`layout/scroll.ts` semantics; V-4). */
+    offset: number;
+    /** Natural (unclipped) height of the content, in rows. */
+    contentRows: number;
+}
+/**
+ * The default is the UNMEASURED geometry, and consumers must treat it as such:
+ * a `TranscriptList` rendered outside a `ScrollViewport` (inline mode, and every
+ * test that mounts it bare) sees `viewportRows: 0`, which `selectWindow` reads
+ * as "first frame" and answers by pinning the live tail.
+ */
+export declare const ViewportGeometryContext: import("react").Context<ViewportGeometry>;
+export declare function useViewportGeometry(): ViewportGeometry;

package/dist/ui/layout/viewport-geometry.js

@@ -0,0 +1,27 @@
+/**
+ * Viewport geometry, published downward (tui-render-performance L3).
+ *
+ * `ScrollViewport`'s header records (P1-7) why it — and not its parent — owns
+ * the metrics and the scroll offset: holding the offset in two places creates a
+ * measure -> setState -> re-render -> measure loop whose convergence is provable
+ * but whose frame count is not.
+ *
+ * Virtualisation needs those same three numbers one level DOWN, in
+ * `TranscriptList`. So the viewport PUBLISHES rather than lifting: a `useMemo`d
+ * context value, no new state, no second owner, no extra layout pass.
+ */
+import { createContext, useContext } from 'react';
+/**
+ * The default is the UNMEASURED geometry, and consumers must treat it as such:
+ * a `TranscriptList` rendered outside a `ScrollViewport` (inline mode, and every
+ * test that mounts it bare) sees `viewportRows: 0`, which `selectWindow` reads
+ * as "first frame" and answers by pinning the live tail.
+ */
+export const ViewportGeometryContext = createContext({
+    viewportRows: 0,
+    offset: 0,
+    contentRows: 0,
+});
+export function useViewportGeometry() {
+    return useContext(ViewportGeometryContext);
+}

package/dist/ui/layout/virtual-window.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Viewport virtualisation maths (tui-render-performance L3 / R1). Pure,
+ * React-free, unit-tested.
+ *
+ * THE STRUCTURAL FIX. Ink's `renderNodeToOutput` has no early-out for clipped
+ * subtrees: for every `ink-text` node it runs `squashTextNodes`, `widestLine`
+ * and possibly `wrapText` — all O(chars) — and `Output.get()` then evaluates
+ * `widestLine` a SECOND time before it is allowed to skip an out-of-clip
+ * operation. A clipped 50 000-character entry therefore costs two full string
+ * scans per frame and buys nothing. Bounding the ENTRY COUNT (`transcriptWindow`)
+ * never bounded that, because one entry can be fifty thousand lines.
+ *
+ * So entries outside the visible band are not mounted at all. They are replaced
+ * by two spacer boxes whose heights come from a height cache, which makes the
+ * per-frame cost O(visible rows) instead of O(characters ever produced).
+ *
+ * V-4 — `offset` counts rows FROM THE BOTTOM (`layout/scroll.ts:1-13`), and that
+ * is what makes virtualisation safe here for free: a height correction on an
+ * entry ABOVE the viewport changes the content height and therefore
+ * `overflowLines`, while `offset` — and hence what the user is looking at — is
+ * unchanged. No scroll-anchoring compensation pass is required. Do NOT
+ * "simplify" `offset` to count from the top.
+ */
+import type { Entry } from '../../agent/reducer.js';
+import type { DensityMode } from '../density.js';
+export declare const VIRTUAL_LIMITS: {
+    /**
+     * Entries kept mounted on each side of the visible band.
+     *
+     * V-2 — must stay `>= 2`, so a one-row scroll can never expose an entry whose
+     * height has never been measured at the very edge of the viewport.
+     */
+    readonly overscan: 2;
+    /** Height-cache ceiling (LRU). Four thousand numbers, not four thousand strings. */
+    readonly heightEntries: 4096;
+};
+export type HeightKey = string;
+/**
+ * A cheap content version: it changes exactly when the rendered content does.
+ *
+ * DERIVED, NEVER HASHED. Hashing a 256 KiB string once per entry per frame would
+ * recreate the very cost this module exists to remove, so every field below is
+ * an O(1) read of a length or a scalar.
+ *
+ * I-L3-1 — this must change whenever the rendered output changes. The only lossy
+ * case is a same-LENGTH text replacement, which the reducer cannot produce: all
+ * text fields are append-only (`appendBounded` only ever elides the middle,
+ * which changes the length). A future NON-APPEND mutation MUST extend the
+ * revision, or the entry freezes at a stale height AND a stale rendered subtree
+ * with nothing anywhere reporting it. `virtual-window.test.ts` enumerates every
+ * kind against every mutating action.
+ */
+export declare function entryRevision(entry: Entry): string;
+/**
+ * The height-cache key.
+ *
+ * V-5 — `cols` is part of the key, so a resize invalidates every entry. The
+ * frame after a resize renders from estimates and re-measures lazily: one
+ * reflow, no crash, no stale layout.
+ *
+ * `flags` carries the render-affecting switches that are neither per-entry nor
+ * part of `density` — today only `thinkingVisible` (Ctrl+T). It is a parameter
+ * rather than a fifth positional scalar so a future switch costs one character
+ * at the call site instead of a signature change at four.
+ */
+export declare function heightKey(entry: Entry, cols: number, expanded: boolean, density: DensityMode, flags?: string): HeightKey;
+/**
+ * Pure UPPER-BOUND estimate of an entry's height, used until a real measurement
+ * exists.
+ *
+ * Upper bound rather than best guess, and deliberately so: an over-estimate
+ * makes the scroll position slightly conservative and self-corrects the frame
+ * after the entry is measured, while an under-estimate can put the newest output
+ * off the bottom of a viewport the user believes is pinned.
+ */
+export declare function estimateEntryRows(entry: Entry, cols: number, density: DensityMode, expanded: boolean): number;
+export interface WindowSelection {
+    /** First mounted entry, inclusive. */
+    startIndex: number;
+    /** One past the last mounted entry. */
+    endIndex: number;
+    /** Spacer rows above the mounted slice. */
+    leadingRows: number;
+    /** Spacer rows below the mounted slice. */
+    trailingRows: number;
+    /** Sum of every entry height, measured or estimated. */
+    totalRows: number;
+}
+export interface SelectWindowInput {
+    entries: readonly Entry[];
+    /** Measured, else estimated; never 0 for a real entry. */
+    heightOf: (index: number) => number;
+    viewportRows: number;
+    /** Rows hidden BELOW the viewport — the existing `scroll.ts` semantic (V-4). */
+    offset: number;
+    /** `>= 2` (V-2). Lower values are raised rather than honoured. */
+    overscan: number;
+}
+/** Choose which entries to mount, and how tall the two spacers must be. */
+export declare function selectWindow(input: SelectWindowInput): WindowSelection;

package/dist/ui/layout/virtual-window.js

@@ -0,0 +1,204 @@
+/**
+ * Viewport virtualisation maths (tui-render-performance L3 / R1). Pure,
+ * React-free, unit-tested.
+ *
+ * THE STRUCTURAL FIX. Ink's `renderNodeToOutput` has no early-out for clipped
+ * subtrees: for every `ink-text` node it runs `squashTextNodes`, `widestLine`
+ * and possibly `wrapText` — all O(chars) — and `Output.get()` then evaluates
+ * `widestLine` a SECOND time before it is allowed to skip an out-of-clip
+ * operation. A clipped 50 000-character entry therefore costs two full string
+ * scans per frame and buys nothing. Bounding the ENTRY COUNT (`transcriptWindow`)
+ * never bounded that, because one entry can be fifty thousand lines.
+ *
+ * So entries outside the visible band are not mounted at all. They are replaced
+ * by two spacer boxes whose heights come from a height cache, which makes the
+ * per-frame cost O(visible rows) instead of O(characters ever produced).
+ *
+ * V-4 — `offset` counts rows FROM THE BOTTOM (`layout/scroll.ts:1-13`), and that
+ * is what makes virtualisation safe here for free: a height correction on an
+ * entry ABOVE the viewport changes the content height and therefore
+ * `overflowLines`, while `offset` — and hence what the user is looking at — is
+ * unchanged. No scroll-anchoring compensation pass is required. Do NOT
+ * "simplify" `offset` to count from the top.
+ */
+import { GUTTER_WIDTH } from './Gutter.js';
+export const VIRTUAL_LIMITS = {
+    /**
+     * Entries kept mounted on each side of the visible band.
+     *
+     * V-2 — must stay `>= 2`, so a one-row scroll can never expose an entry whose
+     * height has never been measured at the very edge of the viewport.
+     */
+    overscan: 2,
+    /** Height-cache ceiling (LRU). Four thousand numbers, not four thousand strings. */
+    heightEntries: 4096,
+};
+/**
+ * A cheap content version: it changes exactly when the rendered content does.
+ *
+ * DERIVED, NEVER HASHED. Hashing a 256 KiB string once per entry per frame would
+ * recreate the very cost this module exists to remove, so every field below is
+ * an O(1) read of a length or a scalar.
+ *
+ * I-L3-1 — this must change whenever the rendered output changes. The only lossy
+ * case is a same-LENGTH text replacement, which the reducer cannot produce: all
+ * text fields are append-only (`appendBounded` only ever elides the middle,
+ * which changes the length). A future NON-APPEND mutation MUST extend the
+ * revision, or the entry freezes at a stale height AND a stale rendered subtree
+ * with nothing anywhere reporting it. `virtual-window.test.ts` enumerates every
+ * kind against every mutating action.
+ */
+export function entryRevision(entry) {
+    switch (entry.kind) {
+        case 'user':
+            return 'u';
+        case 'notice':
+            return 'n';
+        case 'assistant':
+            return `a${entry.text.length}.${entry.thinking?.length ?? 0}.${entry.streaming ? 1 : 0}.${entry.aborted ? 1 : 0}`;
+        case 'tool':
+            return `t${entry.status}.${entry.argsRaw.length}.${entry.preview?.length ?? 0}.${entry.durationMs ?? -1}`;
+        case 'team':
+            return `m${entry.active ? 1 : 0}.${entry.runs.length}.${entry.runs
+                .map((r) => r.phase[0])
+                .join('')}.${entry.runs.reduce((acc, r) => acc + r.toolCalls, 0)}`;
+        case 'todo':
+            return `d${entry.live ? 1 : 0}.${entry.doneCount}.${entry.total}.${entry.items.length}`;
+        default:
+            return 'x';
+    }
+}
+/**
+ * The height-cache key.
+ *
+ * V-5 — `cols` is part of the key, so a resize invalidates every entry. The
+ * frame after a resize renders from estimates and re-measures lazily: one
+ * reflow, no crash, no stale layout.
+ *
+ * `flags` carries the render-affecting switches that are neither per-entry nor
+ * part of `density` — today only `thinkingVisible` (Ctrl+T). It is a parameter
+ * rather than a fifth positional scalar so a future switch costs one character
+ * at the call site instead of a signature change at four.
+ */
+export function heightKey(entry, cols, expanded, density, flags = '') {
+    return `${entry.id}|${entryRevision(entry)}|${cols}|${expanded ? 1 : 0}|${density}|${flags}`;
+}
+/** Rows a string occupies at `usable` columns, wrapping included. At least 1. */
+function wrappedRows(text, usable) {
+    const width = Math.max(1, usable);
+    let rows = 0;
+    let lineLen = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10) {
+            rows += Math.max(1, Math.ceil(lineLen / width));
+            lineLen = 0;
+        }
+        else {
+            lineLen += 1;
+        }
+    }
+    return rows + Math.max(1, Math.ceil(lineLen / width));
+}
+/** Collapsed preview rows in `ToolCard`; duplicated as a NUMBER, not imported. */
+const TOOL_COLLAPSED_LINES = 8;
+/**
+ * Pure UPPER-BOUND estimate of an entry's height, used until a real measurement
+ * exists.
+ *
+ * Upper bound rather than best guess, and deliberately so: an over-estimate
+ * makes the scroll position slightly conservative and self-corrects the frame
+ * after the entry is measured, while an under-estimate can put the newest output
+ * off the bottom of a viewport the user believes is pinned.
+ */
+export function estimateEntryRows(entry, cols, density, expanded) {
+    const usable = Math.max(1, cols - GUTTER_WIDTH);
+    // `separationRows` needs the PRECEDING entry, which a per-entry estimate does
+    // not have. One row is its maximum, so charging it unconditionally keeps this
+    // an upper bound (`compact` never spends it at all).
+    const separation = density === 'comfortable' ? 1 : 0;
+    switch (entry.kind) {
+        case 'user':
+            return separation + wrappedRows(entry.text, usable);
+        case 'notice':
+            return separation + wrappedRows(entry.text, usable);
+        case 'assistant': {
+            const thinking = entry.thinking ? 1 + wrappedRows(entry.thinking, usable) : 0;
+            const body = entry.text.length > 0 ? wrappedRows(entry.text, usable) : 1;
+            return separation + thinking + body + (entry.aborted ? 1 : 0);
+        }
+        case 'tool': {
+            if (!entry.preview || (entry.status !== 'done' && entry.status !== 'error')) {
+                return separation + 1;
+            }
+            const lines = wrappedRows(entry.preview, usable);
+            const shown = expanded ? lines : Math.min(lines, TOOL_COLLAPSED_LINES);
+            // header + body + the `+N lines (Ctrl+O)` / `(Ctrl+O to collapse)` footer
+            return separation + 1 + shown + 1;
+        }
+        case 'team':
+            return separation + 1 + entry.runs.length + (expanded ? entry.runs.length * 3 + 1 : 1);
+        case 'todo':
+            return separation + 1 + entry.items.length;
+        default:
+            return separation + 1;
+    }
+}
+/** Choose which entries to mount, and how tall the two spacers must be. */
+export function selectWindow(input) {
+    const { entries, heightOf } = input;
+    const n = entries.length;
+    if (n === 0) {
+        return { startIndex: 0, endIndex: 0, leadingRows: 0, trailingRows: 0, totalRows: 0 };
+    }
+    const heights = new Array(n);
+    let totalRows = 0;
+    for (let i = 0; i < n; i += 1) {
+        const h = heightOf(i);
+        const rows = Number.isFinite(h) && h > 0 ? Math.floor(h) : 1;
+        heights[i] = rows;
+        totalRows += rows;
+    }
+    // A viewport of 0 is the FIRST FRAME, before `measureElement` has run. Falling
+    // back to 1 keeps the live tail mounted through it, so the first paint is real
+    // content rather than a blank rectangle that only fills in on the second.
+    const viewport = Math.max(1, Math.floor(input.viewportRows) || 0);
+    const offset = Math.max(0, Math.floor(input.offset) || 0);
+    const overscan = Math.max(VIRTUAL_LIMITS.overscan, Math.floor(input.overscan) || 0);
+    const bottom = totalRows - offset;
+    const top = bottom - viewport;
+    let start = n - 1;
+    let acc = 0;
+    for (let i = 0; i < n; i += 1) {
+        const next = acc + heights[i];
+        if (next > top) {
+            start = i;
+            break;
+        }
+        acc = next;
+    }
+    let end = n;
+    acc = 0;
+    for (let i = 0; i < n; i += 1) {
+        if (acc >= bottom) {
+            end = i;
+            break;
+        }
+        acc += heights[i];
+    }
+    start = Math.max(0, start - overscan);
+    end = Math.min(n, end + overscan);
+    // V-3 — while pinned, the LAST entry is always inside the window, whatever its
+    // height. The live tail must be real content and never a spacer, or a
+    // streaming answer renders as a growing blank rectangle.
+    if (offset <= 0)
+        end = n;
+    if (end <= start)
+        end = Math.min(n, start + 1);
+    let leadingRows = 0;
+    for (let i = 0; i < start; i += 1)
+        leadingRows += heights[i];
+    let trailingRows = 0;
+    for (let i = end; i < n; i += 1)
+        trailingRows += heights[i];
+    return { startIndex: start, endIndex: end, leadingRows, trailingRows, totalRows };
+}

package/dist/ui/live-clamp.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Live-region clamp for INLINE render mode (tui-render-performance L5 / R6).
+ *
+ * Inline mode has no fixed frame, so nothing kept its live (non-`<Static>`)
+ * region shorter than the terminal. When one live entry grew taller than
+ * `stdout.rows`, Ink took the branch at `ink.js:118-123`:
+ *
+ *     if (outputHeight >= this.options.stdout.rows) {
+ *       stdout.write(clearTerminal + this.fullStaticOutput + output);
+ *     }
+ *
+ * `fullStaticOutput` accumulates EVERY `<Static>` frame of the whole session and
+ * is never trimmed, so once that branch is taken it is taken on every subsequent
+ * frame — bypassing both the `output !== lastOutput` dedupe and `throttledLog` —
+ * and the terminal receives the entire session history thirty times a second.
+ * That is a genuine hard freeze, and it is reachable today by any inline user
+ * (`--no-fullscreen`, `TERM=dumb`, CI, a short or narrow terminal) whose model
+ * writes a long answer.
+ *
+ * I-L5-1 — keeping the live region strictly below `stdout.rows` makes that
+ * branch UNREACHABLE, which is the inline analogue of `frame.ts`'s
+ * `frameHeight(r) < r` and deserves the same standing. We cannot bound Ink's
+ * `fullStaticOutput` growth (it is private and append-only); preventing the
+ * branch that WRITES it is the entire mitigation, and nothing about the memory
+ * it holds is fixed by this module.
+ *
+ * Nothing is lost, only deferred: when the entry settles it moves into
+ * `<Static>` and is printed in full.
+ */
+export interface LiveClamp {
+    text: string;
+    /** Rows dropped off the FRONT. `0` means the text was returned untouched. */
+    hiddenRows: number;
+}
+/**
+ * Keep the LAST `maxRows` rows of `text`; report how many were dropped.
+ *
+ * Rows, not wrapped display lines: this runs per frame on a streaming entry, and
+ * a wrap-aware count would need the column width and a second full scan of a
+ * string this function exists to avoid scanning twice.
+ */
+export declare function clampLiveText(text: string, maxRows: number): LiveClamp;

package/dist/ui/live-clamp.js

@@ -0,0 +1,74 @@
+/**
+ * Live-region clamp for INLINE render mode (tui-render-performance L5 / R6).
+ *
+ * Inline mode has no fixed frame, so nothing kept its live (non-`<Static>`)
+ * region shorter than the terminal. When one live entry grew taller than
+ * `stdout.rows`, Ink took the branch at `ink.js:118-123`:
+ *
+ *     if (outputHeight >= this.options.stdout.rows) {
+ *       stdout.write(clearTerminal + this.fullStaticOutput + output);
+ *     }
+ *
+ * `fullStaticOutput` accumulates EVERY `<Static>` frame of the whole session and
+ * is never trimmed, so once that branch is taken it is taken on every subsequent
+ * frame — bypassing both the `output !== lastOutput` dedupe and `throttledLog` —
+ * and the terminal receives the entire session history thirty times a second.
+ * That is a genuine hard freeze, and it is reachable today by any inline user
+ * (`--no-fullscreen`, `TERM=dumb`, CI, a short or narrow terminal) whose model
+ * writes a long answer.
+ *
+ * I-L5-1 — keeping the live region strictly below `stdout.rows` makes that
+ * branch UNREACHABLE, which is the inline analogue of `frame.ts`'s
+ * `frameHeight(r) < r` and deserves the same standing. We cannot bound Ink's
+ * `fullStaticOutput` growth (it is private and append-only); preventing the
+ * branch that WRITES it is the entire mitigation, and nothing about the memory
+ * it holds is fixed by this module.
+ *
+ * Nothing is lost, only deferred: when the entry settles it moves into
+ * `<Static>` and is printed in full.
+ */
+/**
+ * Keep the LAST `maxRows` rows of `text`; report how many were dropped.
+ *
+ * Rows, not wrapped display lines: this runs per frame on a streaming entry, and
+ * a wrap-aware count would need the column width and a second full scan of a
+ * string this function exists to avoid scanning twice.
+ */
+export function clampLiveText(text, maxRows) {
+    if (!Number.isFinite(maxRows) || maxRows <= 0)
+        return { text: '', hiddenRows: rowCount(text) };
+    const keep = Math.floor(maxRows);
+    // Cheap reject: a string with fewer than `keep` newlines cannot have more than
+    // `keep` rows, and this is the path every ordinary entry takes.
+    let newlines = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10)
+            newlines += 1;
+    }
+    if (newlines + 1 <= keep)
+        return { text, hiddenRows: 0 };
+    // Walk back from the end to the `keep`-th newline rather than splitting the
+    // whole string: the point of the clamp is to stop touching the head at all.
+    let cut = text.length;
+    let seen = 0;
+    for (let i = text.length - 1; i >= 0; i -= 1) {
+        if (text.charCodeAt(i) === 10) {
+            seen += 1;
+            if (seen === keep) {
+                cut = i + 1;
+                break;
+            }
+        }
+    }
+    return { text: text.slice(cut), hiddenRows: newlines + 1 - keep };
+}
+function rowCount(text) {
+    if (text.length === 0)
+        return 0;
+    let n = 1;
+    for (let i = 0; i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10)
+            n += 1;
+    }
+    return n;
+}

package/dist/ui/markdown-blocks.d.ts

@@ -15,11 +15,13 @@ export interface HeadingBlock {
 export interface RuleBlock {
     kind: 'rule';
 }
+/** Column alignment carried by a table's `|---|:--:|` divider row. */
+export type Align = 'left' | 'right' | 'center';
 export interface TableBlock {
     kind: 'table';
     /** Already column-aligned; render as plain monospace rows. */
     rows: string[][];
-    align: ('left' | 'right' | 'center')[];
+    align: Align[];
 }
 export declare function parseHeading(line: string): HeadingBlock | null;
 export declare function isRule(line: string): boolean;
@@ -34,6 +36,28 @@ export declare function tableAlignments(dividerLine: string): TableBlock['align'
  * on any realistic terminal.
  */
 export declare function formatTable(rows: string[][], align: TableBlock['align']): string[];
+/**
+ * One parsed top-level block.
+ *
+ * `line` is deliberately UNPARSED: heading / rule / quote / bullet detection is
+ * a handful of regexes over one short string and is done at render time, where
+ * the theme and the glyph set live. Caching a themed element instead would make
+ * `/theme` a no-op until the cache evicted (K-5).
+ */
+export type MdBlock = {
+    kind: 'code';
+    code: string;
+    lang: string;
+} | {
+    kind: 'table';
+    rows: string[][];
+    align: Align[];
+} | {
+    kind: 'line';
+    text: string;
+};
+/** Split a document into fenced code, pipe tables, and everything else. */
+export declare function parseMarkdownBlocks(text: string): MdBlock[];
 export type InlineSpan = {
     kind: 'text';
     text: string;

package/dist/ui/markdown-blocks.js

@@ -73,6 +73,49 @@ export function formatTable(rows, align) {
         .join('  ')
         .trimEnd());
 }
+/** A fence line: ```` ```lang ```` or a bare ```` ``` ````. */
+const FENCE_RE = /^```(\w*)\s*$/;
+/** Split a document into fenced code, pipe tables, and everything else. */
+export function parseMarkdownBlocks(text) {
+    const lines = text.split('\n');
+    const blocks = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i] ?? '';
+        const fence = FENCE_RE.exec(line.trim());
+        if (fence) {
+            const lang = fence[1] || '';
+            const codeLines = [];
+            i += 1;
+            while (i < lines.length && !FENCE_RE.test((lines[i] ?? '').trim())) {
+                codeLines.push(lines[i] ?? '');
+                i += 1;
+            }
+            i += 1; // skip the closing fence
+            blocks.push({ kind: 'code', code: codeLines.join('\n'), lang });
+            continue;
+        }
+        // A pipe row followed by a divider row starts a table; consume the run.
+        const headerCells = parseTableRow(line);
+        if (headerCells && i + 1 < lines.length && isTableDivider(lines[i + 1] ?? '')) {
+            const align = tableAlignments(lines[i + 1] ?? '');
+            const rows = [headerCells];
+            i += 2;
+            while (i < lines.length) {
+                const cells = parseTableRow(lines[i] ?? '');
+                if (!cells)
+                    break;
+                rows.push(cells);
+                i += 1;
+            }
+            blocks.push({ kind: 'table', rows, align });
+            continue;
+        }
+        blocks.push({ kind: 'line', text: line });
+        i += 1;
+    }
+    return blocks;
+}
 const CODE_RE = /`[^`]+`/g;
 const EMPHASIS_RE = /(\*\*[^*]+\*\*|~~[^~]+~~|\*[^*]+\*)/g;
 /**

package/dist/ui/overlays/HelpOverlay.js

@@ -27,6 +27,10 @@ const COMMANDS = [
     ['/thinking <level>', 'Set thinking level'],
     ['/max-tokens [n|auto]', 'Output token cap; no argument reports the effective one'],
     ['/team [on|off|max n]', 'Team subagents: status, switch, fan-out width'],
+    [
+        '/todo [on|off|panel|follow|clear|continue]',
+        'Todo planning: status, switches, the rail, follow-through',
+    ],
     ['/tools', 'List active tools'],
     ['/clear', 'Clear the visible transcript'],
     ['/reset', 'New conversation'],