@aragon-agent/cli 0.5.9 → 0.5.11

package/dist/ui/PromptInput.js

@@ -8,13 +8,24 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
  * The buffer/cursor transforms (`applyEdit`, `moveVertical`) and the suggestion
  * computations (`slashSuggestions`, `fileTokenAt`) are pure module functions,
  * exported for `input.test.ts`, so the component itself stays thin.
+ *
+ * THE EDITOR'S FIVE PIECES OF STATE LIVE IN ONE REDUCER, and every branch of the
+ * input handler performs AT MOST ONE `dispatch` (tui-input-flicker-fix §3.4).
+ * Ink mounts a LEGACY React root, where `setState` outside a React event handler
+ * is not batched — and `useInput` runs from a stdin `'data'` listener, which is
+ * outside React entirely. The five `setState` calls one keystroke used to make
+ * were five commits, five whole-tree Yoga layouts and, through Ink's 32 ms
+ * leading+trailing throttle, two full-frame repaints per character. `fileMatches`
+ * stays a plain `useState` because it is written from the debounced glob effect
+ * rather than from a key.
  */
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useReducer, useRef, useState } from 'react';
 import { Box, Text, useInput } from 'ink';
 import { glob as tinyGlob } from 'tinyglobby';
 import { pickGlyphs } from './glyphs.js';
 import { recognize } from '../input/keymap.js';
 import { AutocompletePopup } from './AutocompletePopup.js';
+import { editorReducer, INITIAL_EDITOR_STATE } from './editor-reducer.js';
 // ---------------------------------------------------------------------------
 // Pure editing helpers (unit-tested in input.test.ts)
 // ---------------------------------------------------------------------------
@@ -128,11 +139,8 @@ function isControlSeq(input) {
 // Component
 // ---------------------------------------------------------------------------
 export function PromptInput({ isActive, running, history, commands, cwd, theme, caps, popupMaxRows, agentMode, onSubmit, onHelp, bordered, onDraftChange, }) {
-    const [buffer, setBuffer] = useState('');
-    const [cursor, setCursor] = useState(0);
-    const [historyIndex, setHistoryIndex] = useState(null);
-    const [dismissed, setDismissed] = useState(false);
-    const [sel, setSel] = useState(0);
+    const [editor, dispatch] = useReducer(editorReducer, INITIAL_EDITOR_STATE);
+    const { buffer, cursor, historyIndex, dismissed, sel } = editor;
     const [fileMatches, setFileMatches] = useState([]);
     // --- Derived suggestion state (shared by render + input handler). --------
     const slashSug = dismissed ? null : slashSuggestions(buffer, commands);
@@ -189,46 +197,36 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
         onDraftChange(hasDraft);
     }, [hasDraft, onDraftChange]);
     // --- Mutators. -----------------------------------------------------------
-    const resetDraftFlags = () => {
-        setHistoryIndex(null);
-        setDismissed(false);
-        setSel(0);
-    };
+    // ONE DISPATCH EACH, and that is the rule §3.4 asks a reviewer to check line
+    // by line. Two dispatches from one key would put the legacy root back to two
+    // commits and undo the whole of F3 for that branch.
     const insert = (text) => {
-        setBuffer(buffer.slice(0, cursor) + text + buffer.slice(cursor));
-        setCursor(cursor + text.length);
-        resetDraftFlags();
+        dispatch({ type: 'insert', text });
     };
     const submit = (text) => {
         onSubmit(text);
-        setBuffer('');
-        setCursor(0);
-        resetDraftFlags();
+        dispatch({ type: 'clear' });
     };
     const recallUp = () => {
         if (history.length === 0)
             return;
         const idx = historyIndex === null ? history.length - 1 : Math.max(0, historyIndex - 1);
         const value = history[idx] ?? '';
-        setHistoryIndex(idx);
-        setBuffer(value);
-        setCursor(value.length);
+        dispatch({ type: 'recall', buffer: value, cursor: value.length, historyIndex: idx });
     };
     const recallDown = () => {
         if (historyIndex === null)
             return;
         const idx = historyIndex + 1;
+        // Past the newest entry the walk ends and the draft goes back to empty —
+        // `historyIndex: null` is what tells `verticalOrHistory` the user is editing
+        // again rather than still stepping.
         if (idx >= history.length) {
-            setHistoryIndex(null);
-            setBuffer('');
-            setCursor(0);
-        }
-        else {
-            const value = history[idx] ?? '';
-            setHistoryIndex(idx);
-            setBuffer(value);
-            setCursor(value.length);
+            dispatch({ type: 'recall', buffer: '', cursor: 0, historyIndex: null });
+            return;
         }
+        const value = history[idx] ?? '';
+        dispatch({ type: 'recall', buffer: value, cursor: value.length, historyIndex: idx });
     };
     const completeSelection = () => {
         const chosen = popupItems[clampedSel];
@@ -236,20 +234,17 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
             return;
         if (popupKind === 'slash') {
             const next = `${chosen.label} `;
-            setBuffer(next);
-            setCursor(next.length);
+            dispatch({ type: 'replace', buffer: next, cursor: next.length });
         }
         else if (popupKind === 'file' && fileTok) {
             const next = buffer.slice(0, fileTok.start) + chosen.label + buffer.slice(fileTok.end);
-            setBuffer(next);
-            setCursor(fileTok.start + chosen.label.length);
+            dispatch({ type: 'replace', buffer: next, cursor: fileTok.start + chosen.label.length });
         }
-        resetDraftFlags();
     };
     const verticalOrHistory = (dir) => {
         const moved = moveVertical(buffer, cursor, dir);
         if (moved) {
-            setCursor(moved.cursor);
+            dispatch({ type: 'moveCursor', cursor: moved.cursor });
             return;
         }
         // At an edge: recall history only from an empty buffer or while already
@@ -274,11 +269,11 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
         // Popup navigation owns Up/Down/Tab/→/Enter/Esc while it is open.
         if (popupItems.length > 0) {
             if (key.upArrow) {
-                setSel(Math.max(0, clampedSel - 1));
+                dispatch({ type: 'select', sel: Math.max(0, clampedSel - 1) });
                 return;
             }
             if (key.downArrow) {
-                setSel(Math.min(popupItems.length - 1, clampedSel + 1));
+                dispatch({ type: 'select', sel: Math.min(popupItems.length - 1, clampedSel + 1) });
                 return;
             }
             if (key.tab || (key.rightArrow && cursor >= buffer.length)) {
@@ -292,7 +287,7 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
                 return;
             }
             if (key.escape) {
-                setDismissed(true);
+                dispatch({ type: 'dismiss' });
                 return;
             }
             // Any other key falls through so typing keeps filtering the popup.
@@ -303,9 +298,7 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
         const intent = recognize(input, key);
         if (intent) {
             const next = applyEdit(buffer, cursor, intent);
-            setBuffer(next.buffer);
-            setCursor(next.cursor);
-            resetDraftFlags();
+            dispatch({ type: 'replace', buffer: next.buffer, cursor: next.cursor });
             return;
         }
         if (key.ctrl)
@@ -321,19 +314,19 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
             return;
         }
         if (key.backspace || key.delete) {
-            if (cursor > 0) {
-                setBuffer(buffer.slice(0, cursor - 1) + buffer.slice(cursor));
-                setCursor(cursor - 1);
-                resetDraftFlags();
-            }
+            // The `cursor > 0` guard lives in the reducer now, so this branch is one
+            // unconditional dispatch and a no-op at the left edge returns the same
+            // state object — which React bails out on, exactly as the old
+            // `if (cursor > 0)` skipped the `setState`s.
+            dispatch({ type: 'backspace' });
             return;
         }
         if (key.leftArrow) {
-            setCursor(Math.max(0, cursor - 1));
+            dispatch({ type: 'moveCursor', cursor: Math.max(0, cursor - 1) });
             return;
         }
         if (key.rightArrow) {
-            setCursor(Math.min(buffer.length, cursor + 1));
+            dispatch({ type: 'moveCursor', cursor: Math.min(buffer.length, cursor + 1) });
             return;
         }
         // `!key.shift` is load-bearing: Shift+↑/↓ is the viewport's line-scroll

package/dist/ui/UpdateLine.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The update line (cli-auto-update section 6.2) - the THIRD occupant of the
+ * already-budgeted bottom row, after the toast stack and the activity line.
+ *
+ * ONE ROW, ALWAYS, AND NEVER `null` (C-15 / P0-1 / D-19). The return type is
+ * `React.ReactElement` rather than `React.ReactElement | null`, so the compiler
+ * refuses the shortcut: `BottomStatusRow` decides presence with `if (update)`,
+ * which tests a REACT ELEMENT, and an element whose render returns `null` is
+ * still truthy. Taking that branch would emit a box of ZERO rows - the frame
+ * keeps its fixed height, Yoga hands the row to the transcript, and
+ * `viewportRows()` goes on reporting the old number to `ScrollViewport`,
+ * `selectWindow`, `overlayMaxRows`, `popupMaxRows` and `todoRailRows`. The
+ * transcript would gain a row while the updater is idle and lose it the moment
+ * it has news. Presence is the CALLER's decision, through
+ * `shouldRenderUpdateLine`, exactly as `App.tsx` already decides the activity
+ * line's with `running && !overlayNode`.
+ *
+ * PURE: a function of `snapshot + compact + theme + caps`. No state, no timer,
+ * no clock. `<Text wrap="truncate">` so a narrow terminal degrades by truncation
+ * rather than by wrapping into a second row the fixed frame cannot afford.
+ *
+ * ASCII ONLY, and every user-visible character comes from `pickGlyphs(caps)`
+ * (C-3). No literal `...`, `+` or `~` may be spelled inline - `ActivityLine`'s
+ * routing of even the ellipsis through `pickGlyphs` is the precedent.
+ *
+ * `compact` RATHER THAN `cols` (IF-1). Section 6.2 describes the width tiers in
+ * terms of `cols`, but resolving them here would mean importing
+ * `UPDATE_LIMITS.statusCompactCols` - a VALUE - from `update/`, and section 3.1
+ * rule 1 requires this module's only edge into that tree to be erasable by tsc.
+ * The caller owns `UPDATE_LIMITS` already (it computes presence from it), so it
+ * resolves the threshold too. Same rule as presence: the call site decides.
+ */
+import React from 'react';
+import type { Theme } from './theme.js';
+import type { TermCapabilities } from './capabilities.js';
+import type { UpdateSnapshot } from '../update/types.js';
+export interface UpdateLineProps {
+    snapshot: UpdateSnapshot;
+    /** `cols < UPDATE_LIMITS.statusCompactCols`, resolved by the caller. */
+    compact: boolean;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+export declare function UpdateLine({ snapshot, compact, theme, caps }: UpdateLineProps): React.ReactElement;

package/dist/ui/UpdateLine.js

@@ -0,0 +1,129 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { pickGlyphs } from './glyphs.js';
+export function UpdateLine({ snapshot, compact, theme, caps }) {
+    const glyphs = pickGlyphs(caps);
+    const version = snapshot.latestVersion ?? snapshot.currentVersion;
+    const advice = snapshot.advice ?? '';
+    const dot = glyphs.midDot;
+    const line = (() => {
+        if (snapshot.phase === 'installing') {
+            return {
+                glyph: glyphs.arrowUp,
+                text: compact
+                    ? `${version}${glyphs.ellipsis}`
+                    : `updating to ${version}${glyphs.ellipsis}`,
+                color: theme.muted,
+            };
+        }
+        if (snapshot.phase === 'ready') {
+            return {
+                glyph: glyphs.check,
+                text: compact ? `${version} ready` : `${version} installed ${dot} restart aragon to apply`,
+                color: theme.toast.success,
+            };
+        }
+        if (snapshot.phase === 'failed') {
+            // H2's three classified failures (cli-auto-update-hardening section 8).
+            // Each names the REAL obstacle rather than the generic one, because each
+            // is allowed to break the three-strike silence and a notice that breaks
+            // silence must be worth the interruption.
+            if (snapshot.reason === 'blocked-by-os') {
+                // `npm i -g` FROM THE SAME SHELL HITS THE SAME HANDLE. On Windows the
+                // shim that launched us is being read by the `cmd.exe` running it for
+                // as long as our process lives, and npm's install rewrites that shim -
+                // so the generic advice is not merely unhelpful here, it is a wrong
+                // instruction (R-3 / section 5.3.1).
+                return {
+                    glyph: glyphs.warn,
+                    text: compact || !advice
+                        ? 'update blocked'
+                        : `update blocked ${dot} close other aragon windows, then: ${advice}`,
+                    color: theme.noticeWarn,
+                };
+            }
+            if (snapshot.reason === 'no-space') {
+                return {
+                    glyph: glyphs.warn,
+                    text: compact ? 'no disk space' : `update failed ${dot} no disk space`,
+                    color: theme.noticeWarn,
+                };
+            }
+            if (snapshot.reason === 'not-writable') {
+                return {
+                    glyph: glyphs.warn,
+                    text: compact || !advice
+                        ? 'update blocked'
+                        : `update needs write access ${dot} ${advice}`,
+                    color: theme.noticeWarn,
+                };
+            }
+            return {
+                glyph: glyphs.warn,
+                text: compact || !advice ? 'update failed' : `update failed ${dot} ${advice}`,
+                color: theme.noticeWarn,
+            };
+        }
+        if (snapshot.phase === 'available') {
+            if (snapshot.reason === 'node-too-old') {
+                // Both numbers or neither: "needs a newer Node" without saying which is
+                // a notice the user cannot act on.
+                const detail = snapshot.requiredNode && snapshot.runningNode
+                    ? `${version} needs Node ${snapshot.requiredNode} (running ${snapshot.runningNode})`
+                    : `${version} needs a newer Node`;
+                return {
+                    glyph: glyphs.warn,
+                    text: compact ? 'needs newer Node' : detail,
+                    color: theme.noticeWarn,
+                };
+            }
+            if (snapshot.reason === 'install-ineffective') {
+                return {
+                    glyph: glyphs.warn,
+                    text: compact
+                        ? 'check npm prefix'
+                        : `${version} installed elsewhere${advice ? ` ${dot} ${advice}` : ''}`,
+                    color: theme.noticeWarn,
+                };
+            }
+            return {
+                glyph: glyphs.arrowUp,
+                text: compact
+                    ? version
+                    : `${version} available${advice ? ` ${dot} ${advice}` : ''}`,
+                color: theme.muted,
+            };
+        }
+        // H1's rollback notice, and it goes HERE rather than in a phase branch
+        // (cli-auto-update-hardening section 8 / P0-1). It is true for a whole
+        // SESSION rather than for a phase, so `shouldRenderUpdateLine` decides its
+        // presence from `snapshot.rolledBackFrom` outside `phase` entirely - and the
+        // phases that leaves are exactly `idle` / `checking`, which is this
+        // fallthrough. An earlier draft put it in the `failed` / `available`
+        // branches and keyed it on phase `idle`, a phase neither branch handles;
+        // three independent suppressions, so the one line telling a user their CLI
+        // had been silently downgraded could never have appeared.
+        //
+        // NOT `version` ABOVE: that is `latestVersion ?? currentVersion`, and after
+        // a rollback `latestVersion` may well be the BAD release we just escaped.
+        if (snapshot.rolledBackFrom) {
+            const to = snapshot.rolledBackTo ?? snapshot.currentVersion;
+            return {
+                glyph: glyphs.warn,
+                text: compact
+                    ? 'rolled back'
+                    : `rolled back to ${to} after ${snapshot.rolledBackFrom} failed to start`,
+                color: theme.noticeWarn,
+            };
+        }
+        // `idle` / `checking`, and a `failed` below the notice threshold. The CALLER
+        // never mounts us here (`shouldRenderUpdateLine` is false), but the row must
+        // still be exactly one row if it ever is - the same blank-row discipline
+        // `ToastStack` applies to its own budgeted row.
+        return null;
+    })();
+    if (!line) {
+        return (_jsx(Box, { flexShrink: 0, children: _jsx(Text, { children: " " }) }));
+    }
+    return (_jsx(Box, { flexShrink: 0, children: _jsxs(Text, { wrap: "truncate", color: line.color, children: [' ', line.glyph, " ", line.text] }) }));
+}

package/dist/ui/editor-reducer.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Composer editor state — F3 of tui-input-flicker-fix (§3.4).
+ *
+ * Ink creates its container with tag `0` — a LEGACY React root
+ * (`ink/build/ink.js:59-61`). In a legacy root, `setState` called outside a
+ * React event handler is NOT batched: each call schedules and immediately
+ * flushes a synchronous render. `useInput`'s callback runs from a stdin
+ * `'data'` listener, which is outside React entirely, so `PromptInput.insert`'s
+ * five `setState` calls became five commits, five whole-tree Yoga layouts, and
+ * — through Ink's 32 ms leading+trailing throttle — TWO full-frame repaints per
+ * printable character (§2 R3). The flicker got worse the faster the user typed,
+ * which is exactly what the report described.
+ *
+ * Collapsing the five always-together pieces of state into one reducer makes a
+ * keystroke cost one commit. `fileMatches` deliberately stays a separate
+ * `useState` in the component: it is written from the debounced async glob
+ * effect, not from the key handler, so folding it in here would couple two
+ * unrelated update sources.
+ *
+ * THE RULE A REVIEWER SHOULD CHECK LINE BY LINE: every branch of the `useInput`
+ * callback performs at most ONE `dispatch` and then returns.
+ *
+ * Extracted from the component so it is unit-testable without mounting Ink.
+ */
+export interface EditorState {
+    buffer: string;
+    cursor: number;
+    historyIndex: number | null;
+    dismissed: boolean;
+    sel: number;
+}
+/**
+ * A `type` and not an `interface` because it is a discriminated union — the one
+ * documented exception to this package's interface-first convention.
+ */
+export type EditorAction = {
+    type: 'insert';
+    text: string;
+} | {
+    type: 'replace';
+    buffer: string;
+    cursor: number;
+} | {
+    type: 'backspace';
+} | {
+    type: 'moveCursor';
+    cursor: number;
+} | {
+    type: 'recall';
+    buffer: string;
+    cursor: number;
+    historyIndex: number | null;
+} | {
+    type: 'select';
+    sel: number;
+} | {
+    type: 'dismiss';
+} | {
+    type: 'clear';
+};
+export declare const INITIAL_EDITOR_STATE: EditorState;
+export declare function editorReducer(state: EditorState, action: EditorAction): EditorState;

package/dist/ui/editor-reducer.js

@@ -0,0 +1,90 @@
+/**
+ * Composer editor state — F3 of tui-input-flicker-fix (§3.4).
+ *
+ * Ink creates its container with tag `0` — a LEGACY React root
+ * (`ink/build/ink.js:59-61`). In a legacy root, `setState` called outside a
+ * React event handler is NOT batched: each call schedules and immediately
+ * flushes a synchronous render. `useInput`'s callback runs from a stdin
+ * `'data'` listener, which is outside React entirely, so `PromptInput.insert`'s
+ * five `setState` calls became five commits, five whole-tree Yoga layouts, and
+ * — through Ink's 32 ms leading+trailing throttle — TWO full-frame repaints per
+ * printable character (§2 R3). The flicker got worse the faster the user typed,
+ * which is exactly what the report described.
+ *
+ * Collapsing the five always-together pieces of state into one reducer makes a
+ * keystroke cost one commit. `fileMatches` deliberately stays a separate
+ * `useState` in the component: it is written from the debounced async glob
+ * effect, not from the key handler, so folding it in here would couple two
+ * unrelated update sources.
+ *
+ * THE RULE A REVIEWER SHOULD CHECK LINE BY LINE: every branch of the `useInput`
+ * callback performs at most ONE `dispatch` and then returns.
+ *
+ * Extracted from the component so it is unit-testable without mounting Ink.
+ */
+export const INITIAL_EDITOR_STATE = {
+    buffer: '',
+    cursor: 0,
+    historyIndex: null,
+    dismissed: false,
+    sel: 0,
+};
+/**
+ * The three flags `resetDraftFlags()` used to clear with three separate
+ * `setState` calls.
+ *
+ * Every action that CHANGES THE BUFFER resets them, and that is the pre-existing
+ * semantics rather than a new rule: an edit invalidates the history cursor (the
+ * draft is no longer the recalled entry), un-dismisses the popup (the user is
+ * typing again, so suggestions should come back), and re-homes the selection
+ * (the candidate list is about to be recomputed).
+ */
+const DRAFT_FLAGS = { historyIndex: null, dismissed: false, sel: 0 };
+export function editorReducer(state, action) {
+    switch (action.type) {
+        case 'insert':
+            return {
+                ...state,
+                ...DRAFT_FLAGS,
+                buffer: state.buffer.slice(0, state.cursor) + action.text + state.buffer.slice(state.cursor),
+                cursor: state.cursor + action.text.length,
+            };
+        case 'replace':
+            return { ...state, ...DRAFT_FLAGS, buffer: action.buffer, cursor: action.cursor };
+        case 'backspace': {
+            if (state.cursor <= 0)
+                return state;
+            return {
+                ...state,
+                ...DRAFT_FLAGS,
+                buffer: state.buffer.slice(0, state.cursor - 1) + state.buffer.slice(state.cursor),
+                cursor: state.cursor - 1,
+            };
+        }
+        case 'moveCursor':
+            // NO DRAFT-FLAG RESET. Moving the caret is not an edit: clearing
+            // `historyIndex` here would end a history walk the moment the user pressed
+            // ← to look at what they recalled.
+            return state.cursor === action.cursor ? state : { ...state, cursor: action.cursor };
+        case 'recall':
+            // `historyIndex` is SET, not reset, which is why recall cannot reuse
+            // `replace` — the two differ in exactly the field that keeps the walk
+            // alive. `dismissed` and `sel` are LEFT ALONE, which is not an oversight:
+            // the three `setState` calls this replaces did not touch them either, and
+            // an Esc-dismissed popup that reopened when the user stepped through their
+            // history would be a behaviour change smuggled in by a refactor whose whole
+            // claim is that input semantics are identical (K-7).
+            return {
+                ...state,
+                buffer: action.buffer,
+                cursor: action.cursor,
+                historyIndex: action.historyIndex,
+            };
+        case 'select':
+            return state.sel === action.sel ? state : { ...state, sel: action.sel };
+        case 'dismiss':
+            return state.dismissed ? state : { ...state, dismissed: true };
+        case 'clear':
+            return INITIAL_EDITOR_STATE;
+    }
+}

package/dist/ui/frame-differ.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Frame differ — F1 of tui-input-flicker-fix (§3.2).
+ *
+ * Ink 5.2.1 has exactly one repaint strategy: on every commit it serialises the
+ * WHOLE frame and hands it to `log-update`, which writes
+ * `eraseLines(previousLineCount) + frame` in a single `stdout.write`
+ * (`ink/build/log-update.js:17`). `ansiEscapes.eraseLines` walks BOTTOM-UP, so
+ * the composer — the last row of the frame — is erased near the start of every
+ * repaint and rewritten at the very end of it. During a run that happens 15–30
+ * times a second with the composer's bytes unchanged, and the user sees the
+ * bottom of their screen flicker while they type (§2 R1/R2).
+ *
+ * This module recognises that write shape, diffs the new frame against the
+ * previous one line by line, and emits only the rows that actually changed, each
+ * addressed absolutely. It is PURE: no I/O, no Node globals, no event emitter —
+ * `stdout-frame-writer.ts` is what binds it to a real stream. That is what keeps
+ * it unit-testable with plain string literals and no TTY.
+ *
+ * THREE INVARIANTS LIVE HERE AND EACH ONE FAILS SILENTLY IF DROPPED:
+ *
+ *  - I-4 · An emitted line is `CUP · SGR0 · text · SGR0 · CSI K`, IN THAT ORDER,
+ *    and it never contains `CSI 2K`. Erasing first would blank the row and refill
+ *    it, which is R1's defect at 1/H the scale but on the one row the user is
+ *    watching. Overwriting in place means no cell is ever presentably empty; the
+ *    trailing `CSI K` removes only the residue a longer previous line left, and
+ *    the trailing SGR reset before it stops a BCE terminal painting that residue
+ *    in whatever background colour the line ended inside.
+ *  - I-5 · Every emitted batch ends parked on row `H+1`. Ink's own
+ *    `previousLineCount` is computed from the string IT produced and is
+ *    unaffected by what we actually wrote, so a later pass-through's
+ *    `eraseLines(H+1)` must find the cursor exactly where log-update left it last
+ *    time. Drop this and one fallback shifts the frame up a row for the rest of
+ *    the session.
+ *  - I-6 · Any unrecognised write invalidates the cache. Absolute addressing is
+ *    valid only while nothing else writes to stdout. Full-screen mode already
+ *    forbids that, but "forbidden" is not "impossible", and the failure mode of
+ *    the guard being absent is a permanently misaligned screen while the failure
+ *    mode of it firing spuriously is one extra full repaint.
+ */
+/**
+ * Rebuild `ansiEscapes.eraseLines(count)` byte for byte.
+ *
+ * Exported for the upgrade tripwire (`frame-differ-ink-shape.test.ts`), which
+ * drives the real `ink/build/log-update.js` and asserts this reconstruction is
+ * byte-equal to what it produced. If a future Ink changes the shape, that test
+ * fails loudly instead of this module silently degrading to pass-through for the
+ * rest of the package's life (K-2).
+ */
+export declare function eraseLinesPrefix(count: number): string;
+export interface FrameDifferOptions {
+    /** Emit the DEC 2026 envelope around each batch. */
+    sync: boolean;
+    /**
+     * Live terminal height. Read on every `transform`, NEVER cached: it is the
+     * only input to the I-9 geometry guard and it changes under the differ's feet
+     * on resize. `undefined` ⇒ stand down and pass through.
+     */
+    rows: () => number | undefined;
+    /** Raised once, on the 0→1 edge of `fallbacks` (§5.6). */
+    onFirstFallback?: () => void;
+}
+export interface FrameWriterStats {
+    /** Frames the differ EMITTED — `framesDiffed + framesFull`, never pass-throughs. */
+    framesTotal: number;
+    framesDiffed: number;
+    framesFull: number;
+    linesWritten: number;
+    bytesWritten: number;
+    /**
+     * Pass-throughs caused by a write the differ did not understand.
+     *
+     * NOT INVALIDATIONS (AC-11 / K-14). A resize legitimately invalidates and shows
+     * up as `framesFull`; counting invalidations here would put AC-7 and AC-11 in
+     * direct contradiction and one of them would end up quietly relaxed. It also
+     * excludes the two pass-throughs this module inflicts on ITSELF and already
+     * knows are benign — the session's seed write and the degenerate-geometry
+     * stand-down — because `fallbacks > 0` is documented to mean "something wrote
+     * to stdout behind Ink's back" and is what raises the §5.6 notice.
+     */
+    fallbacks: number;
+}
+export interface FrameDiffer {
+    /**
+     * Bytes to write instead of `chunk`; `''` = write nothing; `null` = write
+     * `chunk`. The parameter is `string` and only `string` (P1-4): decoding, and
+     * the decision about what is even diffable, belong to the writer — the only
+     * place untyped input arrives.
+     */
+    transform(chunk: string): string | null;
+    /** Force the next frame to be a full repaint. */
+    invalidate(): void;
+    /** Single owner of the counters (P2-2); the writer re-exports this. */
+    stats(): FrameWriterStats;
+}
+export declare function createFrameDiffer(options: FrameDifferOptions): FrameDiffer;