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

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 ## [Unreleased]
 
+## [15.10.2] - 2026-06-08
+### Added
+
+- Added exported `canonicalKeyId` and `addKeyAliases` keybinding helpers so consumers can share the same canonical shortcut matching semantics as `KeybindingsManager`.
+- Added `super` modifier support to native key parsing/matching and bound `super+alt+backspace` / `super+alt+delete` (and `super+alt+d`) into the word-delete defaults so Ghostty's default macOS Option+Backspace wire (`ESC [127;11u` — kitty modifier 11 = super|alt) deletes a word instead of falling through to single-char delete ([#2064](https://github.com/can1357/oh-my-pi/issues/2064)).
+
+### Fixed
+
+- Fixed focus-changing in-place menus leaving stale Working/menu rows and parking the hardware cursor in the old menu viewport on terminals without a scroll-position oracle.
+- Fixed redundant terminal cursor updates so repeated renders that do not change the cursor row, column, or visibility no longer emit ANSI move/hide sequences
+- Fixed repeated cursor updates during no-op re-renders by reusing the last known cursor state, preventing unnecessary cursor position changes and hide/show sequences
+- Fixed the kitty keyboard progressive-enhancement probe to honor the `CSI ? <flags> u` reply even when the terminal answers the DA1 sentinel first. Previously the kitty reply was discarded once the DA1-driven `modifyOtherKeys` fallback engaged, so terminals like Superset/xterm-on-Electron stayed on the fallback and delivered Shift+Enter as a bare `\r` ([#2042](https://github.com/can1357/oh-my-pi/issues/2042)).
+- Bounded TUI line fitting for oversized raw rows so ANSI-heavy subagent output and zero-width-heavy text cannot grow render buffers independently of the viewport or hide visible suffix text ([#2045](https://github.com/can1357/oh-my-pi/issues/2045)).
+- Fixed tmux offscreen-shrink frames to skip repainting when the visible tail is unchanged, avoiding intermittent blank/refresh flashes in pane terminals ([#2046](https://github.com/can1357/oh-my-pi/issues/2046)).
+- Fixed Windows ConPTY hosts (Windows Terminal, Tabby, Hyper, VS Code) parking the viewport at the top of a full paint after a `/resume` or any long-session repaint. `ProcessTerminal#safeWrite` now splits oversized writes into ≤ 8 KiB pieces at line boundaries on `win32` and inside WSL (where stdout still crosses ConPTY at the `wslhost` boundary) so each underlying `WriteFile` stays below the ~32 KiB threshold where ConPTY stops tracking the cursor; the data was always delivered, but the host UI's scroll position would not follow until any focus event forced a re-query. ([#2034](https://github.com/can1357/oh-my-pi/issues/2034))
+
+## [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/components/text.d.ts

@@ -6,7 +6,7 @@ export declare class Text implements Component {
     #private;
     constructor(text?: string, paddingX?: number, paddingY?: number, customBgFn?: (text: string) => string);
     getText(): string;
-    setText(text: string): void;
+    setText(text: string): boolean;
     setCustomBgFn(customBgFn?: (text: string) => string): void;
     invalidate(): void;
     render(width: number): string[];

package/dist/types/keybindings.d.ts

@@ -102,11 +102,11 @@ export declare const TUI_KEYBINDINGS: {
         readonly description: "Delete character forward";
     };
     readonly "tui.editor.deleteWordBackward": {
-        readonly defaultKeys: ["ctrl+w", "alt+backspace", "ctrl+backspace"];
+        readonly defaultKeys: ["ctrl+w", "alt+backspace", "ctrl+backspace", "super+alt+backspace"];
         readonly description: "Delete word backward";
     };
     readonly "tui.editor.deleteWordForward": {
-        readonly defaultKeys: ["alt+delete", "alt+d"];
+        readonly defaultKeys: ["alt+delete", "alt+d", "super+alt+delete", "super+alt+d"];
         readonly description: "Delete word forward";
     };
     readonly "tui.editor.deleteToLineStart": {
@@ -174,6 +174,8 @@ export interface KeybindingConflict {
     key: KeyId;
     keybindings: string[];
 }
+export declare function canonicalKeyId(key: string): string;
+export declare function addKeyAliases(keys: Set<string>, key: KeyId): void;
 export declare class KeybindingsManager {
     #private;
     constructor(definitions: KeybindingDefinitions, userBindings?: KeybindingsConfig);

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/terminal.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Split `data` into chunks no larger than `maxChunkSize`, preferring a line
+ * boundary (`\n`) as the cut point so escape sequences (which never contain
+ * `\n`) stay intact. The TUI's full-paint buffers are line-structured
+ * (`buffer += "\r\n"` between rows), so a newline almost always exists within
+ * the window. The fallback for a buffer with no newline in range is a hard
+ * cut at `maxChunkSize`: the ConPTY viewport bug from a single oversized
+ * write is strictly worse than a one-frame escape-sequence glitch on a buffer
+ * the renderer effectively never produces.
+ *
+ * Exported for unit testing of the chunking contract; `#safeWrite` is the
+ * sole production caller.
+ */
+export declare function chunkForConPTY(data: string, maxChunkSize?: number): string[];
 /**
  * Emergency terminal restore - call this from signal/crash handlers
  * Resets terminal state without requiring access to the ProcessTerminal instance

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.2",
 	"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.2",
+		"@oh-my-pi/pi-utils": "15.10.2",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.4"
 	},

package/src/components/editor.ts

@@ -1109,12 +1109,18 @@ export class Editor implements Component, Focusable {
 		else if (matchesKey(data, "ctrl+w")) {
 			this.#deleteWordBackwards();
 		}
-		// Option/Alt+Backspace - Delete word backwards
-		else if (matchesKey(data, "alt+backspace")) {
+		// Option/Alt+Backspace - Delete word backwards.
+		// Ghostty on macOS reports Option+Backspace as super+alt (kitty mod 11) — see #2064.
+		else if (matchesKey(data, "alt+backspace") || matchesKey(data, "super+alt+backspace")) {
 			this.#deleteWordBackwards();
 		}
-		// Option/Alt+D - Delete word forwards
-		else if (matchesKey(data, "alt+d") || matchesKey(data, "alt+delete")) {
+		// Option/Alt+D and Option+Delete - Delete word forwards. Same Ghostty quirk applies.
+		else if (
+			matchesKey(data, "alt+d") ||
+			matchesKey(data, "alt+delete") ||
+			matchesKey(data, "super+alt+d") ||
+			matchesKey(data, "super+alt+delete")
+		) {
 			this.#deleteWordForwards();
 		}
 		// Ctrl+Y - Yank from kill ring
@@ -1495,6 +1501,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,15 +73,23 @@ 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();
 	}
 
 	#updateDisplay() {
 		const frame = this.#frames[this.#currentFrame];
-		this.setText(`${this.spinnerColorFn(frame)} ${this.messageColorFn(this.message)}`);
-		if (this.#ui) {
+		const text = `${this.spinnerColorFn(frame)} ${this.messageColorFn(this.message)}`;
+		if (this.setText(text) && this.#ui) {
 			this.#ui.requestRender();
 		}
 	}