agent-sh 0.3.0 → 0.4.0

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
+import * as path from "node:path";
 import { Shell } from "./shell.js";
 import { createCore } from "./core.js";
 import { palette as p } from "./utils/palette.js";
@@ -10,16 +11,23 @@ import shellRecall from "./extensions/shell-recall.js";
 import shellExec from "./extensions/shell-exec.js";
 import { loadExtensions } from "./extension-loader.js";
 /**
- * Capture the user's full shell environment asynchronously.
+ * Capture the user's full shell environment.
  * This picks up env vars exported in .zshrc/.bashrc that the
- * Node.js process doesn't have.
+ * Node.js process doesn't have (e.g. when launched from an IDE).
  *
- * Uses -l (login shell) instead of -i to avoid TTY blocking issues.
+ * Uses -l (login shell) to get .zprofile/.bash_profile vars, then
+ * explicitly sources the interactive rc file (.zshrc/.bashrc) which
+ * -l alone doesn't load (that requires -i, which blocks on TTY).
  */
 async function captureShellEnvAsync(shell) {
     return new Promise((resolve) => {
         try {
-            const child = spawn(shell, ["-l", "-c", "env -0"], {
+            const shellName = path.basename(shell);
+            const isZsh = shellName.includes("zsh");
+            const sourceRc = isZsh
+                ? 'source ~/.zshrc 2>/dev/null;'
+                : '[ -f ~/.bashrc ] && source ~/.bashrc 2>/dev/null;';
+            const child = spawn(shell, ["-l", "-c", `${sourceRc} env -0`], {
                 stdio: ["ignore", "pipe", "ignore"],
                 timeout: 5000,
             });
@@ -154,7 +162,7 @@ function formatAgentInfo(agentInfo, model, thoughtLevel) {
         const label = thoughtLevel.replace(/^Thinking:\s*/i, "");
         infoStr += ` ${p.dim}[${label}]${p.reset}`;
     }
-    return `${infoStr} ${p.success}●${p.reset}`;
+    return infoStr;
 }
 async function main() {
     // Set up signal handlers before any terminal operations.
@@ -163,29 +171,26 @@ async function main() {
     // Also ignore SIGTTIN which can occur when reading from terminal while backgrounded.
     process.on("SIGTTIN", () => { });
     const config = parseArgs(process.argv.slice(2));
-    // Start with current process environment (fast, non-blocking)
-    // We'll enrich it with shell env asynchronously in the background
+    // Capture user's full shell environment (from .zshrc/.bashrc etc.)
+    // This must complete before spawning the agent so it sees all env vars.
     const baseEnv = {};
     for (const [k, v] of Object.entries(process.env)) {
         if (v !== undefined)
             baseEnv[k] = v;
     }
     config.shellEnv = baseEnv;
-    // Asynchronously capture full shell environment without blocking startup
     const shellPath = config.shell || process.env.SHELL || "/bin/bash";
-    captureShellEnvAsync(shellPath).then((shellEnv) => {
+    try {
+        const shellEnv = await captureShellEnvAsync(shellPath);
         if (Object.keys(shellEnv).length > 0) {
-            const merged = mergeShellEnv(config.shellEnv, shellEnv);
-            config.shellEnv = merged;
+            config.shellEnv = mergeShellEnv(config.shellEnv, shellEnv);
             if (process.env.DEBUG) {
-                console.error('[agent-sh] Shell environment enriched asynchronously');
+                console.error('[agent-sh] Shell environment captured');
             }
         }
-    }).catch(() => {
+    }
+    catch {
         // Ignore errors, we already have process.env as fallback
-    });
-    if (process.env.DEBUG) {
-        console.error('[agent-sh] Using current process environment (async enrichment pending)');
     }
     // ── Core (frontend-agnostic) ──────────────────────────────────
     const core = createCore(config);
@@ -232,6 +237,29 @@ async function main() {
     if (process.env.DEBUG) {
         console.error('[agent-sh] Shell created');
     }
+    // ── Input modes ──────────────────────────────────────────────
+    bus.emit("input-mode:register", {
+        id: "query",
+        trigger: "?",
+        label: "query",
+        promptIcon: "❯",
+        indicator: "❓",
+        onSubmit(query, b) {
+            b.emit("agent:submit", { query, modeLabel: "Query", modeInstruction: "[mode: query]" });
+        },
+        returnToSelf: true,
+    });
+    bus.emit("input-mode:register", {
+        id: "execute",
+        trigger: ">",
+        label: "execute",
+        promptIcon: "⟩",
+        indicator: "●",
+        onSubmit(query, b) {
+            b.emit("agent:submit", { query, modeLabel: "Execute", modeInstruction: "[mode: execute]" });
+        },
+        returnToSelf: false,
+    });
     // ── Extensions ────────────────────────────────────────────────
     if (process.env.DEBUG) {
         console.error('[agent-sh] Setting up extensions...');

package/dist/input-handler.d.ts

@@ -16,7 +16,10 @@ export interface InputContext {
 export declare class InputHandler {
     private ctx;
     private lineBuffer;
-    private agentInputMode;
+    private activeMode;
+    private pendingReturnMode;
+    private modes;
+    private modesById;
     private editor;
     private autocompleteActive;
     private autocompleteIndex;
@@ -37,22 +40,28 @@ export declare class InputHandler {
             model?: string;
         };
     });
+    private registerMode;
     private loadHistory;
     private saveHistory;
-    /** Write the agent prompt line with cursor at the correct position. */
-    private writeAgentPromptLine;
+    /** Write the mode prompt line with cursor at the correct position. */
+    private writeModePromptLine;
     handleInput(data: string): void;
-    private enterAgentInputMode;
-    private exitAgentInputMode;
+    private enterMode;
+    private exitMode;
     /** Move to the start of the prompt area and clear everything below. */
     private clearPromptArea;
     printPrompt(): void;
-    private renderAgentInput;
+    /**
+     * Called when agent processing completes. Returns true if the input
+     * handler re-entered a mode (so caller should skip shell prompt).
+     */
+    handleProcessingDone(): boolean;
+    private renderModeInput;
     private updateAutocomplete;
     private renderAutocomplete;
     private applyAutocomplete;
     private dismissAutocomplete;
     private clearAutocompleteLines;
-    private handleAgentInput;
-    private processAgentActions;
+    private handleModeInput;
+    private processModeActions;
 }

package/dist/input-handler.js

@@ -8,7 +8,10 @@ const HISTORY_FILE = path.join(CONFIG_DIR, "history");
 export class InputHandler {
     ctx;
     lineBuffer = "";
-    agentInputMode = false;
+    activeMode = null;
+    pendingReturnMode = null; // mode id to return to after processing
+    modes = new Map(); // keyed by trigger char
+    modesById = new Map(); // keyed by id
     editor = new LineEditor();
     autocompleteActive = false;
     autocompleteIndex = 0;
@@ -28,9 +31,23 @@ export class InputHandler {
         this.loadHistory();
         // Re-render prompt when config changes (e.g. thinking level cycled)
         this.bus.on("config:changed", () => {
-            if (this.agentInputMode)
-                this.writeAgentPromptLine();
+            if (this.activeMode)
+                this.writeModePromptLine();
         });
+        // Listen for mode registrations from extensions
+        this.bus.on("input-mode:register", (config) => {
+            this.registerMode(config);
+        });
+    }
+    registerMode(config) {
+        if (this.modes.has(config.trigger)) {
+            this.bus.emit("ui:error", {
+                message: `Input mode "${config.id}" cannot register trigger "${config.trigger}" — already taken by "${this.modes.get(config.trigger).id}"`,
+            });
+            return;
+        }
+        this.modes.set(config.trigger, config);
+        this.modesById.set(config.id, config);
     }
     loadHistory() {
         try {
@@ -52,8 +69,8 @@ export class InputHandler {
             // Non-critical — ignore write failures
         }
     }
-    /** Write the agent prompt line with cursor at the correct position. */
-    writeAgentPromptLine(showBuffer = true) {
+    /** Write the mode prompt line with cursor at the correct position. */
+    writeModePromptLine(showBuffer = true) {
         const termW = process.stdout.columns || 80;
         // Move cursor to the start of the prompt area (first line of wrapped content)
         if (this.promptWrappedLines > 0) {
@@ -62,9 +79,13 @@ export class InputHandler {
         // Clear from here to end of screen — removes current + all wrapped lines below
         process.stdout.write("\r\x1b[J");
         const agentInfo = this.onShowAgentInfo();
-        const infoPrefix = agentInfo.info ? `${agentInfo.info} ` : "";
-        const promptPrefix = infoPrefix + p.warning + p.bold + "❯ " + p.reset;
-        const promptVisLen = visibleLen(infoPrefix) + 2; // "❯ "
+        const indicator = this.activeMode?.indicator ?? "●";
+        const infoPrefix = agentInfo.info
+            ? `${agentInfo.info} ${p.success}${indicator}${p.reset} `
+            : `${p.success}${indicator}${p.reset} `;
+        const icon = this.activeMode?.promptIcon ?? "❯";
+        const promptPrefix = infoPrefix + p.warning + p.bold + icon + " " + p.reset;
+        const promptVisLen = visibleLen(infoPrefix) + visibleLen(icon) + 1; // icon + space
         if (!showBuffer || !this.editor.buffer.includes("\n")) {
             // Single-line: simple rendering
             const bufferText = showBuffer ? p.accent + this.editor.buffer + p.reset : "";
@@ -127,7 +148,7 @@ export class InputHandler {
             return;
         }
         // Intercept control chars for TUI (Ctrl+T, Ctrl+O) — don't pass to PTY
-        if (data.length === 1 && data.charCodeAt(0) < 32 && !this.agentInputMode) {
+        if (data.length === 1 && data.charCodeAt(0) < 32 && !this.activeMode) {
             const code = data.charCodeAt(0);
             // Keys consumed by TUI extensions
             if (code === 0x14 || code === 0x0f) { // Ctrl+T, Ctrl+O
@@ -139,9 +160,9 @@ export class InputHandler {
                 this.bus.emit("input:keypress", { key: data });
             }
         }
-        // If in agent input mode (typing a query after ">")
-        if (this.agentInputMode) {
-            this.handleAgentInput(data);
+        // If in an input mode (typing a query)
+        if (this.activeMode) {
+            this.handleModeInput(data);
             return;
         }
         for (let i = 0; i < data.length; i++) {
@@ -171,10 +192,11 @@ export class InputHandler {
                 this.ctx.writeToPty(ch);
             }
             else {
-                // Check if ">" at start of empty line → enter agent input mode
+                // Check if trigger char at start of empty line → enter that mode
                 // But not if a foreground process (ssh, vim, etc.) is running
-                if (this.lineBuffer === "" && ch === ">" && !this.ctx.isForegroundBusy()) {
-                    this.enterAgentInputMode();
+                const mode = this.modes.get(ch);
+                if (this.lineBuffer === "" && mode && !this.ctx.isForegroundBusy()) {
+                    this.enterMode(mode);
                     return; // don't process remaining chars
                 }
                 this.lineBuffer += ch;
@@ -182,17 +204,17 @@ export class InputHandler {
             }
         }
     }
-    enterAgentInputMode() {
-        this.agentInputMode = true;
+    enterMode(mode) {
+        this.activeMode = mode;
         this.editor.clear();
         // Enable kitty keyboard protocol (progressive enhancement flag 1)
         // so Shift+Enter sends \x1b[13;2u instead of plain \r
         process.stdout.write("\x1b[>1u");
-        this.writeAgentPromptLine(false);
+        this.writeModePromptLine(false);
     }
-    exitAgentInputMode() {
+    exitMode() {
         this.dismissAutocomplete();
-        this.agentInputMode = false;
+        this.activeMode = null;
         this.editor.clear();
         // Disable kitty keyboard protocol
         process.stdout.write("\x1b[<u");
@@ -210,9 +232,24 @@ export class InputHandler {
     printPrompt() {
         this.ctx.redrawPrompt();
     }
-    renderAgentInput() {
+    /**
+     * Called when agent processing completes. Returns true if the input
+     * handler re-entered a mode (so caller should skip shell prompt).
+     */
+    handleProcessingDone() {
+        if (this.pendingReturnMode) {
+            const mode = this.modesById.get(this.pendingReturnMode);
+            this.pendingReturnMode = null;
+            if (mode) {
+                this.enterMode(mode);
+                return true;
+            }
+        }
+        return false;
+    }
+    renderModeInput() {
         this.clearAutocompleteLines();
-        this.writeAgentPromptLine();
+        this.writeModePromptLine();
         this.updateAutocomplete();
     }
     updateAutocomplete() {
@@ -254,7 +291,8 @@ export class InputHandler {
         }
         const agentInfo = this.onShowAgentInfo();
         const infoLength = visibleLen(agentInfo.info);
-        const col = infoLength + 2 + this.editor.cursor;
+        const icon = this.activeMode?.promptIcon ?? "❯";
+        const col = infoLength + visibleLen(icon) + 1 + this.editor.cursor;
         process.stdout.write(`\r\x1b[${col}C`);
     }
     applyAutocomplete() {
@@ -279,7 +317,7 @@ export class InputHandler {
         this.autocompleteActive = false;
         this.autocompleteItems = [];
         this.autocompleteIndex = 0;
-        this.writeAgentPromptLine();
+        this.writeModePromptLine();
         if (isFileAc)
             this.updateAutocomplete();
     }
@@ -299,7 +337,7 @@ export class InputHandler {
         process.stdout.write("\x1b8"); // restore cursor
         this.autocompleteLines = 0;
     }
-    handleAgentInput(data) {
+    handleModeInput(data) {
         // Clear any pending escape timer — new data arrived
         if (this.escapeTimer) {
             clearTimeout(this.escapeTimer);
@@ -313,18 +351,18 @@ export class InputHandler {
                 this.escapeTimer = null;
                 const flushed = this.editor.flushPendingEscape();
                 if (flushed.length > 0)
-                    this.processAgentActions(flushed);
+                    this.processModeActions(flushed);
             }, 50);
         }
-        this.processAgentActions(actions);
+        this.processModeActions(actions);
     }
-    processAgentActions(actions) {
+    processModeActions(actions) {
         for (const act of actions) {
             switch (act.action) {
                 case "changed":
                     this.historyIndex = -1;
                     this.autocompleteIndex = 0;
-                    this.renderAgentInput();
+                    this.renderModeInput();
                     break;
                 case "submit": {
                     if (this.autocompleteActive) {
@@ -343,7 +381,8 @@ export class InputHandler {
                     this.clearAutocompleteLines();
                     this.clearPromptArea();
                     process.stdout.write("\x1b[<u"); // disable kitty keyboard protocol
-                    this.agentInputMode = false;
+                    const currentMode = this.activeMode;
+                    this.activeMode = null;
                     this.editor.clear();
                     this.dismissAutocomplete();
                     if (query && query.startsWith("/")) {
@@ -354,25 +393,26 @@ export class InputHandler {
                         this.ctx.redrawPrompt();
                     }
                     else if (query) {
-                        this.bus.emit("agent:submit", { query });
+                        this.pendingReturnMode = currentMode.returnToSelf ? currentMode.id : null;
+                        currentMode.onSubmit(query, this.bus);
                     }
                     else {
-                        this.exitAgentInputMode();
+                        this.exitMode();
                     }
                     return;
                 }
                 case "cancel":
                     if (this.autocompleteActive) {
                         this.dismissAutocomplete();
-                        this.writeAgentPromptLine();
+                        this.writeModePromptLine();
                     }
                     else {
-                        this.exitAgentInputMode();
+                        this.exitMode();
                     }
                     return;
                 case "delete-empty":
                     this.dismissAutocomplete();
-                    this.exitAgentInputMode();
+                    this.exitMode();
                     return;
                 case "tab":
                     if (this.autocompleteActive) {
@@ -389,7 +429,7 @@ export class InputHandler {
                                 ? this.autocompleteItems.length - 1
                                 : this.autocompleteIndex - 1;
                         this.clearAutocompleteLines();
-                        this.writeAgentPromptLine();
+                        this.writeModePromptLine();
                         this.renderAutocomplete();
                     }
                     else if (this.history.length > 0) {
@@ -402,7 +442,7 @@ export class InputHandler {
                         }
                         this.editor.buffer = this.history[this.historyIndex];
                         this.editor.cursor = this.editor.buffer.length;
-                        this.renderAgentInput();
+                        this.renderModeInput();
                     }
                     break;
                 case "arrow-down":
@@ -412,7 +452,7 @@ export class InputHandler {
                                 ? 0
                                 : this.autocompleteIndex + 1;
                         this.clearAutocompleteLines();
-                        this.writeAgentPromptLine();
+                        this.writeModePromptLine();
                         this.renderAutocomplete();
                     }
                     else if (this.historyIndex !== -1) {
@@ -425,7 +465,7 @@ export class InputHandler {
                             this.editor.buffer = this.savedBuffer;
                         }
                         this.editor.cursor = this.editor.buffer.length;
-                        this.renderAgentInput();
+                        this.renderModeInput();
                     }
                     break;
             }

package/dist/settings.d.ts

@@ -28,6 +28,17 @@ export interface Settings {
 declare const DEFAULTS: Required<Settings>;
 /** Load settings from disk (cached after first call). */
 export declare function getSettings(): Settings & typeof DEFAULTS;
+/**
+ * Get settings for an extension, namespaced under its key in settings.json.
+ *
+ * Example settings.json:
+ *   { "latex-images": { "dpi": 600, "fgColor": "ffffff" } }
+ *
+ * Usage in extension:
+ *   const config = getExtensionSettings("latex-images", { dpi: 300, fgColor: "d4d4d4" });
+ *   // config.dpi === 600 (overridden), config.fgColor === "ffffff" (overridden)
+ */
+export declare function getExtensionSettings<T extends Record<string, unknown>>(namespace: string, defaults: T): T;
 /** Reset cached settings (for testing or after external edit). */
 export declare function reloadSettings(): void;
 export {};

package/dist/settings.js

@@ -18,7 +18,7 @@ const DEFAULTS = {
     shellHeadLines: 5,
     shellTailLines: 5,
     recallExpandMaxLines: 100,
-    maxCommandOutputLines: 5,
+    maxCommandOutputLines: 3,
     readOutputMaxLines: 0,
     diffMaxLines: 20,
     enableMcp: true,
@@ -37,6 +37,24 @@ export function getSettings() {
     }
     return { ...DEFAULTS, ...cached };
 }
+/**
+ * Get settings for an extension, namespaced under its key in settings.json.
+ *
+ * Example settings.json:
+ *   { "latex-images": { "dpi": 600, "fgColor": "ffffff" } }
+ *
+ * Usage in extension:
+ *   const config = getExtensionSettings("latex-images", { dpi: 300, fgColor: "d4d4d4" });
+ *   // config.dpi === 600 (overridden), config.fgColor === "ffffff" (overridden)
+ */
+export function getExtensionSettings(namespace, defaults) {
+    const all = getSettings();
+    const ext = all[namespace];
+    if (ext && typeof ext === "object" && !Array.isArray(ext)) {
+        return { ...defaults, ...ext };
+    }
+    return defaults;
+}
 /** Reset cached settings (for testing or after external edit). */
 export function reloadSettings() {
     cached = null;

package/dist/shell.js

@@ -239,7 +239,9 @@ export class Shell {
             this.paused = false;
             this.agentActive = false;
             this.echoSkip = true;
-            this.freshPrompt();
+            if (!this.inputHandler.handleProcessingDone()) {
+                this.freshPrompt();
+            }
         });
         // Permission prompts need stdout unpaused so the interactive UI renders,
         // then re-paused after the decision.

package/dist/types.d.ts

@@ -2,6 +2,9 @@ import type { EventBus } from "./event-bus.js";
 import type { ContextManager } from "./context-manager.js";
 import type { AcpClient } from "./acp-client.js";
 import type { ColorPalette } from "./utils/palette.js";
+import type { BlockTransformOptions, FencedBlockTransformOptions } from "./utils/stream-transform.js";
+export type { ContentBlock } from "./event-bus.js";
+export type { BlockTransformOptions, FencedBlockTransformOptions } from "./utils/stream-transform.js";
 export interface AgentShellConfig {
     agentCommand: string;
     agentArgs: string[];
@@ -24,6 +27,31 @@ export interface ExtensionContext {
     quit: () => void;
     /** Override color palette slots for theming. */
     setPalette: (overrides: Partial<ColorPalette>) => void;
+    /** Register a delimiter-based content transform (e.g. $$...$$ → image). */
+    createBlockTransform: (opts: BlockTransformOptions) => void;
+    /** Register a fenced block transform (e.g. ```lang...``` → code-block). */
+    createFencedBlockTransform: (opts: FencedBlockTransformOptions) => void;
+    /** Read extension-namespaced settings from ~/.agent-sh/settings.json. */
+    getExtensionSettings: <T extends Record<string, unknown>>(namespace: string, defaults: T) => T;
+    /** Register a named handler. */
+    define: (name: string, fn: (...args: any[]) => any) => void;
+    /** Wrap a named handler. Receives `next` (original) + args. */
+    advise: (name: string, wrapper: (next: (...args: any[]) => any, ...args: any[]) => any) => void;
+    /** Call a named handler. */
+    call: (name: string, ...args: any[]) => any;
+}
+/**
+ * Configuration for a registered input mode.
+ * Extensions emit "input-mode:register" with this shape to add new modes.
+ */
+export interface InputModeConfig {
+    id: string;
+    trigger: string;
+    label: string;
+    promptIcon: string;
+    indicator: string;
+    onSubmit(query: string, bus: EventBus): void;
+    returnToSelf: boolean;
 }
 export interface TerminalSession {
     id: string;

package/dist/utils/box-frame.js

@@ -22,7 +22,8 @@ const BORDERS = {
  * @returns Array of terminal-ready lines with borders
  */
 export function renderBoxFrame(content, opts) {
-    const { width, borderColor = p.dim } = opts;
+    const { width: rawWidth, borderColor = p.dim } = opts;
+    const width = Math.max(6, rawWidth);
     const style = opts.style ?? "rounded";
     const b = BORDERS[style];
     const bc = borderColor;

package/dist/utils/diff-renderer.js

@@ -320,7 +320,7 @@ function renderSplit(diff, opts) {
     const lang = useSyntax ? detectLanguage(opts.filePath) : undefined;
     const totalWidth = opts.width;
     // 3 chars for " │ " separator
-    const colWidth = Math.floor((totalWidth - 3) / 2);
+    const colWidth = Math.max(1, Math.floor((totalWidth - 3) / 2));
     // Compute max line number width
     let maxNo = 0;
     for (const hunk of diff.hunks) {

package/dist/utils/frame-renderer.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Differential frame renderer.
+ *
+ * Accepts a frame (string[]) and writes only the lines that changed
+ * compared to the previous frame.  Designed for scrolling content
+ * (not full-screen ownership like pi-tui).
+ *
+ * Fast paths:
+ *   1. First render → write everything
+ *   2. Append-only → write only new lines
+ *   3. Last line changed → \r overwrite (for spinner / partial streaming)
+ *   4. General diff → cursor-up, rewrite changed region, cursor-down
+ */
+import type { OutputWriter } from "./output-writer.js";
+export declare class FrameRenderer {
+    private writer;
+    private prevLines;
+    constructor(writer: OutputWriter);
+    /**
+     * Render a new frame, writing only the diff to the output.
+     * Each line in `lines` should NOT include a trailing newline.
+     */
+    update(lines: string[]): void;
+    /** Reset state — next update will be treated as a first render. */
+    reset(): void;
+}

package/dist/utils/frame-renderer.js

@@ -0,0 +1,76 @@
+export class FrameRenderer {
+    writer;
+    prevLines = [];
+    constructor(writer) {
+        this.writer = writer;
+    }
+    /**
+     * Render a new frame, writing only the diff to the output.
+     * Each line in `lines` should NOT include a trailing newline.
+     */
+    update(lines) {
+        const prev = this.prevLines;
+        if (prev.length === 0) {
+            // Fast path 1: first render
+            for (const line of lines) {
+                this.writer.write(line + "\n");
+            }
+            this.prevLines = lines.slice();
+            return;
+        }
+        // Find first and last changed indices
+        const minLen = Math.min(prev.length, lines.length);
+        let firstChanged = -1;
+        let lastChanged = -1;
+        for (let i = 0; i < minLen; i++) {
+            if (prev[i] !== lines[i]) {
+                if (firstChanged === -1)
+                    firstChanged = i;
+                lastChanged = i;
+            }
+        }
+        // Check for appended or removed lines
+        const appended = lines.length > prev.length;
+        const truncated = lines.length < prev.length;
+        if (firstChanged === -1 && !appended && !truncated) {
+            // No changes at all
+            this.prevLines = lines.slice();
+            return;
+        }
+        if (firstChanged === -1 && appended) {
+            // Fast path 2: only new lines appended, existing unchanged
+            for (let i = prev.length; i < lines.length; i++) {
+                this.writer.write(lines[i] + "\n");
+            }
+            this.prevLines = lines.slice();
+            return;
+        }
+        // General diff: move cursor up to first changed line, rewrite
+        const linesFromBottom = prev.length - (firstChanged === -1 ? prev.length : firstChanged);
+        if (linesFromBottom > 0) {
+            this.writer.write(`\x1b[${linesFromBottom}A`); // cursor up
+        }
+        this.writer.write("\r"); // start of line
+        // Rewrite from firstChanged to end of new frame
+        const start = firstChanged === -1 ? prev.length : firstChanged;
+        for (let i = start; i < lines.length; i++) {
+            this.writer.write(`\x1b[2K${lines[i]}\n`); // clear line + write + newline
+        }
+        // If new frame is shorter, clear remaining old lines
+        if (truncated) {
+            for (let i = lines.length; i < prev.length; i++) {
+                this.writer.write("\x1b[2K\n");
+            }
+            // Move cursor back up to end of new content
+            const extra = prev.length - lines.length;
+            if (extra > 0) {
+                this.writer.write(`\x1b[${extra}A`);
+            }
+        }
+        this.prevLines = lines.slice();
+    }
+    /** Reset state — next update will be treated as a first render. */
+    reset() {
+        this.prevLines = [];
+    }
+}