@oh-my-pi/pi-tui 15.10.0 → 15.10.1

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 ## [Unreleased]
 
+## [15.10.1] - 2026-06-07
+### Breaking Changes
+
+- Removed Kitty temp-file image transmission, its startup support probe, the `PI_KITTY_IMAGE_TRANSMISSION` override, and the temp-file helper exports. Kitty/Ghostty image payloads now stay on in-band base64 before placeholder/direct placement, avoiding blank first renders from temp-file load races.
+- Renamed `RenderRequestOptions.allowUnknownViewportMutation` → `allowUnknownViewportTransientRepaint`. The option only permits a transient live-viewport repaint (autocomplete/IME/focused-editor chrome) on hosts that cannot report viewport position; it never authorizes a settled transcript commit. The old name implied any offscreen mutation was safe to push into native scrollback, which led callers to emit duplicate transcript copies.
+
+### Added
+
+- Added `TUI.addStartListener()` so feature hooks can re-enable terminal modes after temporary stop/start cycles such as external-editor handoffs.
+- Added `Editor.pasteText()` to apply terminal-style paste handling for text inserted from non-bracketed paste transports
+- Added an optional `dispose()` lifecycle method to `Component` so components can release timers and subscriptions during permanent teardown
+- Added `Container.dispose()` to propagate teardown to child components when a component tree is permanently discarded
+- Added `Loader.dispose()` to stop the loader animation timer when the component is disposed
+- Added a `ScrollView` `ellipsis` option (defaults to `Ellipsis.Unicode`) so callers that pre-wrap content to width can pass `Ellipsis.Omit` and suppress the stray per-line `…` that lands on trailing padding.
+- Added `ScrollView.handleScrollKey()` plus a `fastScrollLines` option so every scroll view gets shared navigation keys, including Shift+Arrow to scroll faster.
+- Added `OverlayOptions.fullscreen`: while the topmost visible overlay sets it, the engine borrows the terminal's alternate screen buffer for the overlay's lifetime and paints only the modal there — no ED3, no transcript re-commit — so the transcript stays untouched on the normal screen and is not scrollable behind the modal. Mouse tracking (`?1000h`/`?1006h`) is enabled for the modal's lifetime and disabled on exit, so the rest of the app keeps the terminal's native text selection.
+- Added the `submitPinsViewportToTail` terminal capability and `detectSubmitPinsViewportToTail()`: genuine local terminals where a submit keystroke scrolls the host to its tail reconcile deferred native scrollback at the prompt-submit checkpoint even when the viewport position is unprobeable (Ghostty/kitty/iTerm/WezTerm/Alacritty). Restores the pre-regression submit reconciliation without re-enabling it for Windows Terminal/ConPTY, SSH, or multiplexers, where a submit is not proof the host is at the tail.
+
+### Changed
+
+- Changed static `Loader` messages to repaint only at the spinner's 80 ms cadence; time-dependent message colorizers can opt into 16 ms redraws with `animated: true`.
+- Changed keybinding matching to precompute canonical key sets so each input sequence is parsed once per binding check instead of once per candidate key.
+- Made `Component.invalidate()` optional so leaf components without render caches no longer need no-op invalidation hooks.
+- `TERMINAL` is now a `RuntimeTerminal` whose post-construction capabilities (image protocol and the probe-driven flags) are writable, replacing the `as unknown as MutableTerminalInfo` cast pattern and the positional `withTerminalOverrides` rebuild with a prototype-preserving `clone()`.
+
+### Fixed
+
+- Fixed `Loader` text updates to skip identical messages and preserve the rendered `Text` cache instead of invalidating it every timer tick.
+
+- Fixed fullscreen overlay alt-frame rendering to reuse the current line-preparation path instead of calling removed fitting helpers.
+- Reduced TUI render-path line fitting by deferring overlay base-frame fitting until an overlay rebuild and by reusing already-fitted lines in emitters.
+- Reduced live-region pinned repaint output by diffing unchanged viewport rows when no sealed rows are being committed to native scrollback.
+- Fixed no-append live-region pinned repaints to re-anchor the hardware cursor when the logical viewport shifts.
+- Fixed keybinding matching so printable uppercase input preserves `Shift` for bindings such as `shift+a`.
+- Optimized terminal image-line detection and Thai/Lao AM normalization checks to avoid hot-path regex scans and substring allocations.
+- Fixed `Markdown.render()` cache hits returning the cache's mutable backing array, which let callers that append extra rows corrupt cached Markdown and duplicate those rows on every redraw.
+- Fixed first-paint full replays for callers that intentionally replace terminal history by allowing `TUI.start({ clearScrollback: true })`, so they do not briefly append an entire initial frame before the first clean replay.
+- Fixed ED3-risk streaming cap accounting to preserve the native scrollback high-water mark for rows that were already physically committed before transient frames were viewport-capped.
+- Fixed terminal stop and restore cleanup to disable enhanced paste mode so it does not remain enabled after shutdown
+- Removed the per-frame line-fit `Map` cache from the render timer path to avoid forcing JSC rope-string hashing during scheduled viewport repaints.
+- Fixed `visibleWidth()` so terminal column measurements for ANSI and OSC text now match the native truncation/wrapping helpers, including OSC 66 text-sizing spans being counted at their scaled payload width
+- Fixed cursor, padding, and line-fit behavior when strings contain tabs or OSC escapes by aligning `visibleWidth()` with the native text-width model
+- Fixed the transcript — or a re-appearing prior view such as the welcome screen — duplicating itself on terminals without a scroll-position oracle (Ghostty/kitty/iTerm/WezTerm) when a foreground tool completes by rewriting a partly-committed block, or when the transcript is reset. A non-destructive viewport repaint no longer re-paints rows that are byte-identical to what is already committed to native scrollback into the active grid; the repaint anchor is clamped to the committed-and-unchanged prefix (`min(firstChanged, scrollbackHighWater)`).
+
 ## [15.10.0] - 2026-06-06
 
 ### Changed

package/dist/types/components/editor.d.ts

@@ -100,6 +100,8 @@ export declare class Editor implements Component, Focusable {
     setText(text: string): void;
     /** Insert text at the current cursor position */
     insertText(text: string): void;
+    /** Apply terminal paste semantics to text from non-bracketed paste transports. */
+    pasteText(text: string): void;
     isShowingAutocomplete(): boolean;
 }
 export {};

package/dist/types/components/loader.d.ts

@@ -1,13 +1,20 @@
 import type { TUI } from "../tui";
 import { Text } from "./text";
+type ColorFn = (str: string) => string;
+export type LoaderMessageColorFn = ColorFn & {
+    readonly animated?: true;
+};
 export declare class Loader extends Text {
     #private;
     private spinnerColorFn;
     private messageColorFn;
     private message;
-    constructor(ui: TUI, spinnerColorFn: (str: string) => string, messageColorFn: (str: string) => string, message?: string, spinnerFrames?: string[]);
+    constructor(ui: TUI, spinnerColorFn: ColorFn, messageColorFn: LoaderMessageColorFn, message?: string, spinnerFrames?: string[]);
     render(width: number): string[];
     start(): void;
     stop(): void;
+    /** Lifecycle teardown: stop the animation timer. Idempotent. */
+    dispose(): void;
     setMessage(message: string): void;
 }
+export {};

package/dist/types/components/scroll-view.d.ts

@@ -1,4 +1,5 @@
 import type { Component } from "../tui";
+import { Ellipsis } from "../utils";
 type ScrollbarMode = "auto" | "always" | "never";
 export interface ScrollViewTheme {
     track?: (text: string) => string;
@@ -13,6 +14,18 @@ export interface ScrollViewOptions {
     theme?: ScrollViewTheme;
     trackChar?: string;
     thumbChar?: string;
+    /**
+     * Indicator appended when a row overflows `contentWidth`. Defaults to
+     * {@link Ellipsis.Unicode}. Pass {@link Ellipsis.Omit} when callers wrap
+     * lines to width themselves and only trailing padding can overflow (e.g.
+     * the plan-review overlay), so no stray `…` lands on every padded row.
+     */
+    ellipsis?: Ellipsis;
+    /**
+     * Rows moved per keystroke when {@link ScrollView.handleScrollKey} sees a
+     * Shift+Arrow (the "scroll faster" affordance). Defaults to 5.
+     */
+    fastScrollLines?: number;
 }
 /**
  * Fixed-height viewport over pre-rendered lines, with optional right-edge scrollbar.
@@ -34,6 +47,15 @@ export declare class ScrollView implements Component {
     page(delta: number): void;
     scrollToTop(): void;
     scrollToBottom(): void;
+    /**
+     * Apply a standard navigation key to the viewport. Shift+Arrow scrolls by
+     * {@link ScrollViewOptions.fastScrollLines} (the "scroll faster" affordance);
+     * plain Arrow by one line; PageUp/PageDown by a page; Home/End to the ends.
+     * Returns true when the key was consumed, so callers can fall through to
+     * their own (e.g. vim-style) bindings. Generic on purpose: every ScrollView
+     * consumer gets the same scroll keys, including Shift-to-go-faster.
+     */
+    handleScrollKey(data: string): boolean;
     invalidate(): void;
     render(width: number): string[];
 }

package/dist/types/kitty-graphics.d.ts

@@ -1,13 +1,26 @@
+/**
+ * Kitty graphics: Unicode placeholder placement (`U=1` + U+10EEEE), with
+ * runtime feature state and env overrides.
+ *
+ * Unicode placeholders let a transmitted image be displayed by writing ordinary
+ * text cells — the placeholder char U+10EEEE plus row/column combining
+ * diacritics — instead of a cursor-positioned `a=p` direct placement. The image
+ * then participates in the normal text grid, so it survives horizontal slicing,
+ * reflow and overlapping draws (each cell names its own row+column, so a sliced
+ * row still maps to the correct sub-region). See kitty
+ * `docs/graphics-protocol.rst` "Unicode placeholders for relative placements".
+ *
+ * This module is intentionally free of `./terminal-capabilities` imports so the
+ * dependency stays one-way (capabilities → kitty-graphics) and no import cycle
+ * forms. Protocol gating (`imageProtocol === Kitty`) lives in the caller.
+ */
 /** Kitty Unicode placeholder base character (U+10EEEE, Plane 16 PUA). */
 export declare const KITTY_PLACEHOLDER = "\uDBFB\uDEEE";
 /** Largest row/column index expressible with the diacritic table (one cell each). */
 export declare const KITTY_PLACEHOLDER_MAX_CELLS: number;
-export type KittyTransmissionMedium = "direct" | "temp-file";
 export interface KittyGraphicsFeatures {
     /** Display images via Unicode placeholders instead of direct `a=p` placement. */
     unicodePlaceholders: boolean;
-    /** How image data reaches the terminal: in-band base64 or a temp file. */
-    transmissionMedium: KittyTransmissionMedium;
 }
 /**
  * Whether the detected terminal renders Kitty Unicode placeholders (`U=1` +
@@ -29,16 +42,8 @@ export interface KittyGraphicsFeatures {
 export declare function detectKittyUnicodePlaceholdersSupport(terminalId: string, env?: NodeJS.ProcessEnv): boolean;
 export declare function getKittyGraphics(): Readonly<KittyGraphicsFeatures>;
 export declare function setKittyGraphics(partial: Partial<KittyGraphicsFeatures>): void;
-/**
- * Whether temp-file transmission may be promoted at runtime: forced via env,
- * disabled via env, otherwise auto (local sessions only — a temp file written
- * locally is not readable by a terminal on the far side of an SSH link).
- */
-export declare function kittyTempFileAllowed(): boolean;
 /** Whether a `columns`×`rows` placeholder grid fits within the diacritic table. */
 export declare function kittyPlaceholdersFit(columns: number, rows: number): boolean;
-/** True when the base64 payload is a PNG (kitty `f=100` / temp-file path only). */
-export declare function isPngBase64(base64Data: string): boolean;
 /**
  * Virtual placement APC (`a=p,U=1`): tells the terminal that placeholder cells
  * carrying image id `i` should display the transmitted image, scaled to fit the
@@ -72,23 +77,3 @@ export declare function renderKittyPlaceholderLines(opts: {
     columns: number;
     rows: number;
 }): string[];
-/**
- * Transmit a PNG via a temp file (`t=t`): decode the base64 to bytes once, write
- * them to a temp file, and send the base64-encoded file path as payload. Returns
- * the APC string, or `null` on any failure (caller falls back to direct base64).
- *
- * Synchronous filesystem writes are mandated by the synchronous render pipeline
- * (`Image.render` → `renderImage` are sync); there is no async seam here.
- */
-export declare function encodeKittyTempFileTransmit(base64Png: string, imageId: number): string | null;
-/**
- * Encode a temp-file support probe: write a tiny PNG to a temp file and ask the
- * terminal to query it (`a=q,t=t`). A conforming terminal replies
- * `ESC _ G i=<probeId>;OK ESC \`. Returns the query APC plus a `cleanup` that
- * removes the probe file (best-effort; kitty self-deletes the magic-named file).
- * Returns `null` if the temp file cannot be written.
- */
-export declare function encodeKittyTempFileProbe(probeId: number): {
-    sequence: string;
-    cleanup: () => void;
-} | null;

package/dist/types/terminal-capabilities.d.ts

@@ -24,6 +24,21 @@ export declare class TerminalInfo {
     constructor(id: TerminalId, imageProtocol: ImageProtocol | null, trueColor: boolean, hyperlinks: boolean, notifyProtocol?: NotifyProtocol, eagerEraseScrollbackRisk?: boolean, deccara?: boolean, supportsScreenToScrollback?: boolean, 
     /** Renders the Kitty OSC 66 text-sizing protocol (scaled spans). Kitty only. */
     textSizing?: boolean);
+    /**
+     * Whether a prompt-submit keystroke scrolls this host to its tail, so the
+     * native-scrollback reconciliation checkpoint may ED3-rebuild even when the
+     * viewport position is unprobeable. Assigned by the TERMINAL builder from
+     * {@link detectSubmitPinsViewportToTail}; readonly but tests opt in via the
+     * {@link setTerminalSubmitPinsViewportToTail} mutable-cast setter.
+     */
+    readonly submitPinsViewportToTail: boolean;
+    /**
+     * Mutable clone for the {@link TERMINAL} singleton: copies every field and
+     * keeps the prototype methods, so the builder and runtime setters flip
+     * runtime-resolved {@link RuntimeTerminal} capabilities in place instead of
+     * reconstructing positional constructor args.
+     */
+    clone(): RuntimeTerminal;
     isImageLine(line: string): boolean;
     formatNotification(message: string | TerminalNotification): string;
     sendNotification(message: string | TerminalNotification): void;
@@ -51,6 +66,20 @@ export declare function isWindowsTerminalPreviewSixelSupported(env?: NodeJS.Proc
  * outer host fronting WSL, where the same ED3 yank applies. See #1610/#1682/#1799.
  */
 export declare function detectTerminalEagerEraseScrollbackRisk(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/**
+ * Whether a prompt-submit keystroke scrolls this terminal to its tail, making the
+ * native-scrollback reconciliation checkpoint (`refreshNativeScrollbackIfDirty`)
+ * safe to ED3-rebuild even when the viewport position cannot be probed.
+ *
+ * True only for recognized genuine *local* terminals where typing into the prompt
+ * brings the host viewport to the bottom. False — the checkpoint keeps deferring
+ * until a positive at-tail probe — for hosts whose scrollback a keystroke does not
+ * move: Windows consoles/ConPTY, Windows Terminal (incl. WSL), SSH, multiplexers,
+ * and unrecognized profiles. This is the per-terminal counterpart to the blanket
+ * block from #1610/#1682/#1746: those hosts genuinely cannot treat a submit as
+ * proof of at-tail, but genuine local terminals can.
+ */
+export declare function detectSubmitPinsViewportToTail(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
 /**
  * Resolve an explicit user override for DEC 2026 synchronized output. Returns
  * `false` for an opt-out, `true` for a force-on, or `null` when the user has
@@ -96,7 +125,22 @@ export declare function shouldEnableSynchronizedOutputByDefault(env?: NodeJS.Pro
  */
 export declare function detectRectangularSgrSupport(terminalId: TerminalId, env?: NodeJS.ProcessEnv): boolean;
 export declare const TERMINAL_ID: TerminalId;
-export declare const TERMINAL: TerminalInfo;
+/**
+ * The process-wide {@link TERMINAL} singleton: a {@link TerminalInfo} whose
+ * post-construction capabilities — the image protocol and the probe-driven
+ * flags — are writable, so the runtime setters and tests mutate them directly
+ * instead of through an unsound cast. Every other field stays readonly.
+ */
+export interface RuntimeTerminal extends TerminalInfo {
+    imageProtocol: ImageProtocol | null;
+    hyperlinks: boolean;
+    eagerEraseScrollbackRisk: boolean;
+    deccara: boolean;
+    supportsScreenToScrollback: boolean;
+    textSizing: boolean;
+    submitPinsViewportToTail: boolean;
+}
+export declare const TERMINAL: RuntimeTerminal;
 /**
  * Override terminal image protocol at runtime after capability probes complete.
  */
@@ -109,6 +153,8 @@ export declare function setTerminalImageProtocol(imageProtocol: ImageProtocol |
 export declare function setTerminalDeccara(enabled: boolean): void;
 /** Override screen-to-scrollback clear support for targeted renderer tests. */
 export declare function setTerminalScreenToScrollback(enabled: boolean): void;
+/** Override submit-pins-viewport-to-tail for checkpoint reconciliation tests. */
+export declare function setTerminalSubmitPinsViewportToTail(enabled: boolean): void;
 /**
  * Enable/disable OSC 66 text-sizing at runtime. The coding-agent calls this from
  * the `tui.textSizing` setting (gated on the terminal's static `textSizing`

package/dist/types/tui.d.ts

@@ -6,6 +6,7 @@ type InputListenerResult = {
     data?: string;
 } | undefined;
 type InputListener = (data: string) => InputListenerResult;
+type StartListener = () => void;
 export interface RenderTimer {
     cancel(): void;
 }
@@ -17,6 +18,10 @@ export interface RenderScheduler {
 export interface TUIOptions {
     renderScheduler?: RenderScheduler;
 }
+export interface TUIStartOptions {
+    /** Clear saved native scrollback before the first paint. */
+    clearScrollback?: boolean;
+}
 /**
  * Component interface - all components must implement this
  */
@@ -37,10 +42,17 @@ export interface Component {
      */
     wantsKeyRelease?: boolean;
     /**
-     * Invalidate any cached rendering state.
+     * Optional hook to invalidate any cached rendering state.
      * Called when theme changes or when component needs to re-render from scratch.
      */
-    invalidate(): void;
+    invalidate?(): void;
+    /**
+     * Optional teardown. Called when the component is permanently removed from
+     * the live tree (e.g. a transcript reset). Release timers, intervals, and
+     * subscriptions here. Must be idempotent. Containers propagate dispose to
+     * their children; leaf components without resources may omit it.
+     */
+    dispose?(): void;
 }
 /**
  * Optional component seam for native-scrollback pinning. A component that
@@ -86,15 +98,14 @@ export interface RenderRequestOptions {
     /** Clear terminal scrollback for intentional transcript replacement. */
     clearScrollback?: boolean;
     /**
-     * Bypass the unknown-Windows-viewport deferral for this render so the
-     * caller's intentional live UI mutation reaches the terminal even when
-     * `Terminal#isNativeViewportAtBottom()` cannot answer.
+     * Allow a transient live-viewport repaint when the terminal cannot report
+     * whether its native viewport is at the tail.
      *
-     * Use only for renders driven by direct user interaction (autocomplete
-     * updates, IME, etc.). Any background/offscreen transcript change that
-     * coalesces into the same frame WILL also bypass the deferral and reach
-     * native scrollback — that is the trade-off, and the reason ordinary
-     * `requestRender()` calls must continue to omit this flag.
+     * This is **not** a settled transcript commit and must not be used for tool
+     * completion, session replay, or other background/offscreen rewrites. On
+     * ED3-risk terminals it may deliberately choose a viewport repaint/deferred
+     * shrink without clearing native scrollback so autocomplete, IME, and focused
+     * editor chrome stay responsive without yanking a scrolled reader.
      */
     allowUnknownViewportMutation?: boolean;
 }
@@ -156,6 +167,15 @@ export interface OverlayOptions {
      * Called each render cycle with current terminal dimensions.
      */
     visible?: (termWidth: number, termHeight: number) => boolean;
+    /**
+     * Borrow the terminal's alternate screen buffer for this overlay's lifetime
+     * (vim/less idiom). While the topmost visible overlay sets this, the engine
+     * paints only the modal on the alt screen and emits no ED3 / scrollback
+     * bytes, so the transcript on the normal screen stays untouched and is not
+     * scrollable behind the modal. Defaults off — all other overlays are
+     * unchanged and still draw over the transcript on the normal screen.
+     */
+    fullscreen?: boolean;
 }
 /**
  * Handle returned by showOverlay for controlling the overlay
@@ -177,6 +197,12 @@ export declare class Container implements Component {
     removeChild(component: Component): void;
     clear(): void;
     invalidate(): void;
+    /**
+     * Propagate teardown to children. Call when the container's children are
+     * being permanently discarded (not when they are detached for reuse — use
+     * {@link clear} for that). Idempotent per child via each child's own dispose.
+     */
+    dispose(): void;
     render(width: number): string[];
 }
 /**
@@ -255,7 +281,8 @@ export declare class TUI extends Container {
     /** Check if there are any visible overlays */
     hasOverlay(): boolean;
     invalidate(): void;
-    start(): void;
+    start(options?: TUIStartOptions): void;
+    addStartListener(listener: StartListener): () => void;
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;
     stop(): void;

package/dist/types/utils.d.ts

@@ -33,9 +33,12 @@ export declare function padding(n: number): string;
  * Get the shared grapheme segmenter instance.
  */
 export declare function getSegmenter(): Intl.Segmenter;
-export declare function visibleWidthRaw(str: string): number;
 /**
- * Calculate the visible width of a string in terminal columns.
+ * Visible width of a string in terminal columns, excluding ANSI/OSC escapes.
+ *
+ * `Bun.stringWidth` does the heavy lifting (UAX#11 width tables + ANSI/OSC
+ * stripping); this adds the two corrections it omits — tabs (expanded to
+ * `tabWidth` cells) and OSC 66 text-sizing payloads (scaled by `s=`).
  */
 export declare function visibleWidth(str: string): number;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "15.10.0",
+	"version": "15.10.1",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "15.10.0",
-		"@oh-my-pi/pi-utils": "15.10.0",
+		"@oh-my-pi/pi-natives": "15.10.1",
+		"@oh-my-pi/pi-utils": "15.10.1",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.4"
 	},

package/src/components/editor.ts

@@ -1495,6 +1495,11 @@ export class Editor implements Component, Focusable {
 		this.#insertTextAtCursor(text);
 	}
 
+	/** Apply terminal paste semantics to text from non-bracketed paste transports. */
+	pasteText(text: string): void {
+		this.#handlePaste(text);
+	}
+
 	// All the editor methods from before...
 	#insertCharacter(char: string): void {
 		this.#exitHistoryForEditing();

package/src/components/loader.ts

@@ -3,21 +3,20 @@ import { sliceByColumn, visibleWidth } from "../utils";
 import { Text } from "./text";
 
 /**
- * Loader component that drives display refresh at ~60fps so callers whose
- * message colorizer is time-dependent (e.g. shimmer/KITT) animate smoothly.
+ * Loader component. Spinner frames advance at `SPINNER_ADVANCE_MS`.
  *
- * Two cadences are interleaved on a single timer:
- *   - **Render tick** (every `RENDER_INTERVAL_MS`) → asks the TUI to redraw.
- *     The TUI already throttles at 16ms (`MIN_RENDER_INTERVAL_MS`), so this
- *     is the natural upper bound; static messageColorFns produce identical
- *     output and the differ drops the no-op redraw at ~zero cost.
- *   - **Spinner advance** (every `SPINNER_ADVANCE_MS`) → bumps the spinner
- *     frame index. Decoupled from the render cadence so the spinner keeps
- *     its classic ~12.5fps step pace regardless of shimmer state.
+ * Message colorizers that are time-dependent can opt into 30fps redraws by
+ * setting `animated` to `true` on the function object.
  */
-const RENDER_INTERVAL_MS = 16;
+const RENDER_INTERVAL_MS = 1000 / 30;
 const SPINNER_ADVANCE_MS = 80;
 
+type ColorFn = (str: string) => string;
+
+export type LoaderMessageColorFn = ColorFn & {
+	readonly animated?: true;
+};
+
 export class Loader extends Text {
 	#frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 	#currentFrame = 0;
@@ -27,8 +26,8 @@ export class Loader extends Text {
 
 	constructor(
 		ui: TUI,
-		private spinnerColorFn: (str: string) => string,
-		private messageColorFn: (str: string) => string,
+		private spinnerColorFn: ColorFn,
+		private messageColorFn: LoaderMessageColorFn,
 		private message: string = "Loading...",
 		spinnerFrames?: string[],
 	) {
@@ -54,14 +53,17 @@ export class Loader extends Text {
 	start() {
 		this.#lastSpinnerTick = performance.now();
 		this.#updateDisplay();
+		const intervalMs = this.messageColorFn.animated === true ? RENDER_INTERVAL_MS : SPINNER_ADVANCE_MS;
 		this.#intervalId = setInterval(() => {
 			const now = performance.now();
-			if (now - this.#lastSpinnerTick >= SPINNER_ADVANCE_MS) {
-				this.#currentFrame = (this.#currentFrame + 1) % this.#frames.length;
-				this.#lastSpinnerTick = now;
+			const elapsed = now - this.#lastSpinnerTick;
+			if (elapsed >= SPINNER_ADVANCE_MS) {
+				const steps = Math.floor(elapsed / SPINNER_ADVANCE_MS);
+				this.#currentFrame = (this.#currentFrame + steps) % this.#frames.length;
+				this.#lastSpinnerTick += steps * SPINNER_ADVANCE_MS;
 			}
 			this.#updateDisplay();
-		}, RENDER_INTERVAL_MS);
+		}, intervalMs);
 	}
 
 	stop() {
@@ -71,7 +73,15 @@ export class Loader extends Text {
 		}
 	}
 
+	/** Lifecycle teardown: stop the animation timer. Idempotent. */
+	dispose() {
+		this.stop();
+	}
+
 	setMessage(message: string) {
+		if (message === this.message) {
+			return;
+		}
 		this.message = message;
 		this.#updateDisplay();
 	}

package/src/components/markdown.ts

@@ -58,7 +58,8 @@ markdownParser.setOptions({
 // (Rust FFI) work for content/layout combinations already seen this session.
 
 const RENDER_CACHE_MAX = 256; // sane cap: ~256 distinct message × width combos
-const renderCache = new LRUCache<string, string[]>({ max: RENDER_CACHE_MAX });
+const EMPTY_RENDER_LINES: readonly string[] = [];
+const renderCache = new LRUCache<string, readonly string[]>({ max: RENDER_CACHE_MAX });
 
 /** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */
 export function clearRenderCache(): void {
@@ -288,10 +289,11 @@ export class Markdown implements Component {
 	/** Number of spaces used to indent code block content. */
 	#codeBlockIndent: number;
 
-	// Cache for rendered output
+	// Cache for rendered output. Cached arrays are internal snapshots; render()
+	// returns caller-owned arrays because several renderers append surrounding rows.
 	#cachedText?: string;
 	#cachedWidth?: number;
-	#cachedLines?: string[];
+	#cachedLines?: readonly string[];
 
 	constructor(
 		text: string,
@@ -324,7 +326,7 @@ export class Markdown implements Component {
 		// L1: per-instance cache — fastest path for repeated renders of the same
 		// instance at the same width (e.g. resize debounce, repeated redraws).
 		if (this.#cachedLines && this.#cachedText === this.#text && this.#cachedWidth === width) {
-			return this.#cachedLines;
+			return this.#cachedLines.slice();
 		}
 
 		// Calculate available width for content (subtract horizontal padding)
@@ -332,12 +334,10 @@ export class Markdown implements Component {
 
 		// Don't render anything if there's no actual text
 		if (!this.#text || this.#text.trim() === "") {
-			const result: string[] = [];
-			// Update per-instance cache
 			this.#cachedText = this.#text;
 			this.#cachedWidth = width;
-			this.#cachedLines = result;
-			return result;
+			this.#cachedLines = EMPTY_RENDER_LINES;
+			return [];
 		}
 
 		// Replace tabs with 3 spaces for consistent rendering
@@ -364,7 +364,7 @@ export class Markdown implements Component {
 			this.#cachedText = this.#text;
 			this.#cachedWidth = width;
 			this.#cachedLines = cached;
-			return cached;
+			return cached.slice();
 		}
 
 		// Parse markdown to HTML-like tokens
@@ -445,14 +445,16 @@ export class Markdown implements Component {
 		const rawResult = [...emptyLines, ...contentLines, ...emptyLines];
 		const result = rawResult.length > 0 ? rawResult : [""];
 
-		// Update L1 per-instance cache
+		// Update caches with a private snapshot. The returned array remains owned by
+		// the caller, so push/splice by tool renderers cannot poison future redraws.
+		const cachedLines = result.slice();
 		this.#cachedText = this.#text;
 		this.#cachedWidth = width;
-		this.#cachedLines = result;
+		this.#cachedLines = cachedLines;
 
 		// Update L2 module-level LRU so future instances with the same key skip
 		// the marked.lexer + highlightCode (Rust FFI) work entirely.
-		renderCache.set(cacheKey, result);
+		renderCache.set(cacheKey, cachedLines);
 
 		return result;
 	}