@sayknow-cli/tui 0.4.6 → 0.5.0

package/README.md

@@ -56,6 +56,14 @@ tui.requestRender(); // Request a re-render
 tui.onDebug = () => console.log("Debug triggered");
 ```
 
+### Manual viewport and pinned suffix
+
+`setBottomPinnedComponent(component)` marks a direct-child boundary. During manual viewport ownership, that child and all later direct children remain fixed at the bottom while rows before it form the scrollable lane; this does not require an output source. `scrollViewportPages()` moves by the lane height minus one; `scrollViewportBy()` supports smaller row steps and rejects non-finite deltas.
+
+`setViewportOutputSource({ identity, revision })` reports semantic output changes without coupling the TUI to message types. A same-identity revision advance while manually scrolled displays the exact notice `New output — type to follow`; following live or changing/removing the identity clears it, while a stale same-identity revision rollback does not.
+
+Pinned rows and the notice are excluded from transcript mouse-selection coordinates. When the terminal is too short, the focused direct-child suffix component is retained before decorative or lower-priority suffix rows.
+
 ### Component Interface
 
 All components implement:

package/dist/types/components/sayknow-pet.d.ts

@@ -124,10 +124,5 @@ export declare function buildSayknowPixelFrames(options: {
     kittyImageId?: number;
     /** Color skin for the sprite palette (default "red"). */
     skin?: PetSkinId;
-    /**
-     * Optional wrapper applied to each encoded sixel frame (e.g. tmux DCS
-     * passthrough). Identity when omitted. Never applied to kitty frames.
-     */
-    wrapSixel?: (frame: string) => string;
 }): SayknowPixelFrames;
 export {};

package/dist/types/components/select-list.d.ts

@@ -45,6 +45,7 @@ export declare class SelectList implements Component {
     constructor(items: ReadonlyArray<SelectItem>, maxVisible: number, theme: SelectListTheme, layout?: SelectListLayoutOptions);
     setFilter(filter: string): void;
     setSelectedIndex(index: number): void;
+    handleNavigation(action: "tui.select.up" | "tui.select.down" | "tui.select.pageUp" | "tui.select.pageDown"): void;
     invalidate(): void;
     render(width: number): string[];
     handleInput(keyData: string): void;

package/dist/types/keys.d.ts

@@ -41,11 +41,11 @@ export declare function setKittyProtocolActive(active: boolean): void;
 export declare function isKittyProtocolActive(): boolean;
 type Letter = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
 type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
-type SymbolKey = "`" | "-" | "=" | "[" | "]" | "\\" | ";" | "'" | "," | "." | "/" | "!" | "@" | "#" | "$" | "%" | "^" | "&" | "*" | "(" | ")" | "_" | "+" | "|" | "~" | "{" | "}" | ":" | "<" | ">" | "?";
+type SymbolKey = "`" | "-" | "=" | "[" | "]" | "\\" | ";" | "'" | '"' | "," | "." | "/" | "!" | "@" | "#" | "$" | "%" | "^" | "&" | "*" | "(" | ")" | "_" | "+" | "|" | "~" | "{" | "}" | ":" | "<" | ">" | "?";
 type SpecialKey = "escape" | "esc" | "enter" | "return" | "tab" | "space" | "backspace" | "delete" | "insert" | "clear" | "home" | "end" | "pageUp" | "pageDown" | "up" | "down" | "left" | "right" | "f1" | "f2" | "f3" | "f4" | "f5" | "f6" | "f7" | "f8" | "f9" | "f10" | "f11" | "f12";
-type BaseKey = Letter | Digit | SymbolKey | SpecialKey;
-type ModifierName = "ctrl" | "shift" | "alt" | "super";
-type ModifiedKeyId<Key extends string, RemainingModifiers extends ModifierName = ModifierName> = {
+export type BaseKey = Letter | Digit | SymbolKey | SpecialKey;
+export type KeyModifier = "ctrl" | "shift" | "alt" | "super";
+type ModifiedKeyId<Key extends string, RemainingModifiers extends KeyModifier = KeyModifier> = {
     [M in RemainingModifiers]: `${M}+${Key}` | `${M}+${ModifiedKeyId<Key, Exclude<RemainingModifiers, M>>}`;
 }[RemainingModifiers];
 /**
@@ -53,6 +53,19 @@ type ModifiedKeyId<Key extends string, RemainingModifiers extends ModifierName =
  * Provides autocomplete and catches typos at compile time.
  */
 export type KeyId = BaseKey | ModifiedKeyId<BaseKey>;
+export interface ParsedKeyId {
+    keyId: KeyId;
+    modifiers: KeyModifier[];
+    baseKey: BaseKey;
+}
+/**
+ * Parse a case-insensitive key identifier into normalized dispatch parts.
+ * The legacy `plus` base-key alias normalizes to `+`; the trailing `+` in
+ * values such as `ctrl++` is the literal plus base.
+ */
+export declare function parseKeyId(value: string): ParsedKeyId | undefined;
+/** Whether a value is a valid canonical key identifier. */
+export declare function isKeyId(value: string): value is KeyId;
 /**
  * Typed helper for constructing key identifiers with autocomplete.
  *

package/dist/types/metrics.d.ts

@@ -48,6 +48,7 @@ export interface RenderMetricsSnapshot {
     timerGauges: Record<string, number>;
     helperStats: Record<string, HelperStat>;
     lineCounts: Record<string, LineCountGauge>;
+    structuralCounters: Record<string, number>;
 }
 export declare class RenderMetrics {
     #private;
@@ -73,6 +74,8 @@ export declare class RenderMetrics {
     recordHelper(name: string, durationMs: number): void;
     /** Record a per-render line-count gauge (e.g. "rendered", "normalized", "diffed"). */
     recordLineCount(name: string, value: number): void;
+    /** Accumulate deterministic structural render work without retaining frame data. */
+    recordStructuralCounter(name: string, value?: number): void;
     /**
      * Force a GC when the runtime exposes one and sample RSS as the post-run
      * "return" value used by the memory-leak gate. Callers should drop large

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

@@ -78,6 +78,9 @@ export declare function isUnderTmux(env?: NodeJS.ProcessEnv): boolean;
  * tmux, so non-multiplexed, screen, and zellij paths are untouched.
  */
 export declare function wrapTmuxPassthrough(payload: string, env?: NodeJS.ProcessEnv): string;
+export declare function tmuxOwnsSixel(env?: NodeJS.ProcessEnv): boolean;
+/** Testing seam: drop the cached tmux sixel-ownership answer. */
+export declare function resetTmuxSixelOwnershipCache(): void;
 /**
  * Returns true when running in Windows Terminal with known SIXEL support.
  *

package/dist/types/tui.d.ts

@@ -1,5 +1,7 @@
 import type { Terminal } from "./terminal";
 import { visibleWidth } from "./utils";
+/** Discrete mouse-wheel notch size in terminal rows (xterm/less-style). */
+export declare const DEFAULT_WHEEL_LINES = 3;
 type InputListenerResult = {
     consume?: boolean;
     data?: string;
@@ -9,7 +11,7 @@ type InputListener = (data: string) => InputListenerResult;
  * Component interface - all components must implement this
  */
 export type MouseEvent = {
-    kind: "wheel" | "click";
+    kind: "wheel" | "click" | "drag" | "release";
     direction?: -1 | 1;
     button?: 0;
     /** Terminal cell coordinates, one-based. */
@@ -27,7 +29,7 @@ type OverlayMouseBounds = {
     termWidth: number;
     termHeight: number;
 };
-/** Parse xterm SGR mouse reports. Drag and button-release reports are ignored. */
+/** Parse xterm SGR mouse reports for wheel, left-click, drag, and release events. */
 export declare function parseSgrMouseEvent(data: string): MouseEvent | undefined;
 export interface Component {
     /**
@@ -99,6 +101,11 @@ export interface ViewportAnchorProvider extends Component {
 export interface ViewportAnchorSource {
     id: ViewportAnchorId;
 }
+/** Identity and monotonic revision of the logical output producer. */
+export type ViewportOutputSource = {
+    identity: string;
+    revision: bigint;
+};
 export interface ViewportAnchorSourceRenderer extends Component {
     renderWithViewportAnchorSource(width: number, source: ViewportAnchorSource): ViewportAnchorRender;
 }
@@ -125,10 +132,11 @@ export type SizeValue = number | `${number}%`;
  * Startup sixel capability probe policy (pure; exported for tests):
  * - Never probe when PI_FORCE_IMAGE_PROTOCOL is set — an explicit
  *   configuration (including "off") is authoritative.
- * - Under tmux, probe when the sixel-multiplexer path is enabled (default): the
- *   query is DCS-passthrough wrapped so the OUTER terminal answers, not tmux's
- *   unreliable compile-time DA1, making a positive reply genuine end-to-end
- *   evidence. screen/zellij have no passthrough envelope, so graphics stay off.
+ * - Never probe inside a terminal multiplexer: tmux advertises DA1 ";4"
+ *   whenever it was compiled with sixel support, regardless of whether the
+ *   attached client terminal can render sixel, so a positive reply is not
+ *   end-to-end evidence. Graphics under a multiplexer are strictly opt-in
+ *   via PI_FORCE_IMAGE_PROTOCOL=sixel.
  * - Probe Windows Terminal (>=1.22 renders sixel but exposes no env marker).
  */
 export declare function shouldProbeSixelCapability(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
@@ -229,6 +237,14 @@ export declare class TUI extends Container {
     }[];
     constructor(terminal: Terminal, showHardwareCursor?: boolean, options?: {
         enableMouse?: boolean;
+        copySelection?: (text: string) => void | Promise<void>;
+        /**
+         * Trailing debounce for the settled width repair, in ms. `0` disables the
+         * settled repair (deterministic harnesses need this — a wall-clock-timed
+         * full replay lands at nondeterministic logical positions). Defaults to
+         * `SKC_TUI_WIDTH_SETTLE_MS` / `PI_TUI_WIDTH_SETTLE_MS`, then 1000.
+         */
+        widthSettleMs?: number;
     });
     dispose(): void;
     get fullRedraws(): number;
@@ -242,7 +258,11 @@ export declare class TUI extends Container {
      */
     setClearOnShrink(enabled: boolean): void;
     setFocus(component: Component | null): void;
+    removeChild(component: Component): void;
+    clear(): void;
     setBottomPinnedComponent(component: Component | null): void;
+    /** Report the logical output producer revision without coupling TUI to message types. */
+    setViewportOutputSource(source: ViewportOutputSource | null): void;
     /** Register the direct child whose rows are eligible for semantic viewport anchoring. */
     setViewportAnchorComponent(component: Component | null): void;
     /** Clear manual viewport ownership before replacing the transcript identity namespace. */
@@ -251,6 +271,10 @@ export declare class TUI extends Container {
     prepareViewportAnchorForTranscriptRebuild(): void;
     /** Reveal a semantic viewport anchor without changing the rendered content width. */
     revealViewportAnchor(id: ViewportAnchorId, alignment: "top" | "center" | "bottom"): boolean;
+    scrollViewportBy(deltaRows: number, options?: {
+        /** edge: PageUp/PageDown pin; stable: preserve/center pin for fine wheel motion */
+        pin?: "edge" | "stable";
+    }): boolean;
     scrollViewportPages(direction: -1 | 1): boolean;
     followLiveViewport(): boolean;
     /**
@@ -264,6 +288,15 @@ export declare class TUI extends Container {
     hasOverlay(): boolean;
     invalidate(): void;
     start(): void;
+    /**
+     * Wait for a specific render request generation to be written successfully.
+     *
+     * Render requests are coalesced, so committing a newer generation also commits
+     * every older generation represented by that frame. A stopped or unavailable
+     * terminal resolves waiters false so UI callers can fail open instead of
+     * holding a session operation behind a dead renderer.
+     */
+    waitForRenderCommit(generation: number, timeoutMs?: number): Promise<boolean>;
     get terminalAvailable(): boolean;
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;
@@ -280,9 +313,19 @@ export declare class TUI extends Container {
      * the transcript top during streaming redraws, so viewport-repaint sessions
      * keep force off and let `#doRender` repaint only the live viewport. Set
      * `PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER=1` to restore the legacy tmux redraw.
+     *
+     * Spurious resize events (SIGWINCH with unchanged dimensions — iTerm2 tab
+     * switches and window focus changes, the self-sent SIGWINCH after resume)
+     * must not force either: on hosts still using the `fullRender` path (legacy
+     * multiplexer opt-in, non-process terminals) the forced redraw clears
+     * scrollback (`2J`/`H`/`3J`) and replays the whole transcript, which can
+     * park the native viewport at the transcript top. Only force when the grid
+     * size actually changed since the last committed frame; a plain diff render
+     * is a no-op otherwise.
      */
     requestResizeRender(): void;
     requestRender(force?: boolean, source?: string): void;
+    requestRenderWithGeneration(force?: boolean, source?: string): number;
     getLineRenderCacheStats(): {
         normalizationSize: number;
         truncationSize: number;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.4.6",
+	"version": "0.5.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -38,8 +38,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.4.6",
-		"@sayknow-cli/utils": "0.4.6",
+		"@sayknow-cli/natives": "0.5.0",
+		"@sayknow-cli/utils": "0.5.0",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/components/sayknow-pet.ts

@@ -392,11 +392,6 @@ export function buildSayknowPixelFrames(options: {
 	kittyImageId?: number;
 	/** Color skin for the sprite palette (default "red"). */
 	skin?: PetSkinId;
-	/**
-	 * Optional wrapper applied to each encoded sixel frame (e.g. tmux DCS
-	 * passthrough). Identity when omitted. Never applied to kitty frames.
-	 */
-	wrapSixel?: (frame: string) => string;
 }): SayknowPixelFrames {
 	const targetRows = options.targetRows ?? 2;
 	const gridSize = 16;
@@ -421,7 +416,7 @@ export function buildSayknowPixelFrames(options: {
 	for (const name of Object.keys(PIXEL_GRIDS) as SayknowPixelFrameName[]) {
 		frames[name] =
 			options.protocol === "sixel"
-				? (options.wrapSixel ?? (frame => frame))(encodeGridSixel(PIXEL_GRIDS[name], scale, topPaddingPx, palette))
+				? encodeGridSixel(PIXEL_GRIDS[name], scale, topPaddingPx, palette)
 				: encodeGridKitty(
 						PIXEL_GRIDS[name],
 						scale,

package/src/components/select-list.ts

@@ -92,6 +92,22 @@ export class SelectList implements Component {
 			this.#findEnabledIndex(clamped, 1, false) ?? this.#findEnabledIndex(clamped, -1, false) ?? -1;
 		this.#syncViewportToIndex(this.#selectedIndex >= 0 ? this.#selectedIndex : clamped);
 	}
+	handleNavigation(action: "tui.select.up" | "tui.select.down" | "tui.select.pageUp" | "tui.select.pageDown"): void {
+		switch (action) {
+			case "tui.select.up":
+				this.#moveSelection(-1);
+				break;
+			case "tui.select.down":
+				this.#moveSelection(1);
+				break;
+			case "tui.select.pageUp":
+				this.#movePage(-1);
+				break;
+			case "tui.select.pageDown":
+				this.#movePage(1);
+				break;
+		}
+	}
 
 	invalidate(): void {
 		// No cached state to invalidate currently

package/src/keybindings.ts

@@ -170,7 +170,16 @@ const SHIFTED_SYMBOL_KEYS = new Set<string>([
 	"~",
 ]);
 
-const normalizeKeyId = (key: KeyId): KeyId => key.toLowerCase() as KeyId;
+const normalizeKeyId = (key: KeyId): KeyId => {
+	const normalized = key.toLowerCase();
+	if (normalized.endsWith("pageup")) {
+		return `${normalized.slice(0, -6)}pageUp` as KeyId;
+	}
+	if (normalized.endsWith("pagedown")) {
+		return `${normalized.slice(0, -8)}pageDown` as KeyId;
+	}
+	return normalized as KeyId;
+};
 
 function normalizeKeys(keys: KeyId | KeyId[] | undefined): KeyId[] {
 	if (keys === undefined) return [];

package/src/keys.ts

@@ -117,6 +117,7 @@ type SymbolKey =
 	| "\\"
 	| ";"
 	| "'"
+	| '"'
 	| ","
 	| "."
 	| "/"
@@ -173,10 +174,10 @@ type SpecialKey =
 	| "f11"
 	| "f12";
 
-type BaseKey = Letter | Digit | SymbolKey | SpecialKey;
-type ModifierName = "ctrl" | "shift" | "alt" | "super";
+export type BaseKey = Letter | Digit | SymbolKey | SpecialKey;
+export type KeyModifier = "ctrl" | "shift" | "alt" | "super";
 
-type ModifiedKeyId<Key extends string, RemainingModifiers extends ModifierName = ModifierName> = {
+type ModifiedKeyId<Key extends string, RemainingModifiers extends KeyModifier = KeyModifier> = {
 	[M in RemainingModifiers]: `${M}+${Key}` | `${M}+${ModifiedKeyId<Key, Exclude<RemainingModifiers, M>>}`;
 }[RemainingModifiers];
 
@@ -186,6 +187,123 @@ type ModifiedKeyId<Key extends string, RemainingModifiers extends ModifierName =
  */
 export type KeyId = BaseKey | ModifiedKeyId<BaseKey>;
 
+export interface ParsedKeyId {
+	keyId: KeyId;
+	modifiers: KeyModifier[];
+	baseKey: BaseKey;
+}
+
+const BASE_KEYS = new Set<string>([
+	..."abcdefghijklmnopqrstuvwxyz",
+	..."0123456789",
+	"`",
+	"-",
+	"=",
+	"[",
+	"]",
+	"\\",
+	";",
+	"'",
+	'"',
+	",",
+	".",
+	"/",
+	"!",
+	"@",
+	"#",
+	"$",
+	"%",
+	"^",
+	"&",
+	"*",
+	"(",
+	")",
+	"_",
+	"+",
+	"|",
+	"~",
+	"{",
+	"}",
+	":",
+	"<",
+	">",
+	"?",
+	"escape",
+	"esc",
+	"enter",
+	"return",
+	"tab",
+	"space",
+	"backspace",
+	"delete",
+	"insert",
+	"clear",
+	"home",
+	"end",
+	"pageup",
+	"pagedown",
+	"up",
+	"down",
+	"left",
+	"right",
+	"f1",
+	"f2",
+	"f3",
+	"f4",
+	"f5",
+	"f6",
+	"f7",
+	"f8",
+	"f9",
+	"f10",
+	"f11",
+	"f12",
+]);
+
+const KEY_MODIFIERS: readonly KeyModifier[] = ["ctrl", "alt", "shift", "super"];
+
+/**
+ * Parse a case-insensitive key identifier into normalized dispatch parts.
+ * The legacy `plus` base-key alias normalizes to `+`; the trailing `+` in
+ * values such as `ctrl++` is the literal plus base.
+ */
+export function parseKeyId(value: string): ParsedKeyId | undefined {
+	if (hasControlChars(value) || value.length === 0) return undefined;
+
+	const lowerCaseValue = value
+		.trim()
+		.toLowerCase()
+		.replace(/\s*\+\s*/g, "+");
+	const normalized = lowerCaseValue === "plus" ? "+" : lowerCaseValue.replace(/\+plus$/, "++");
+	const baseKey = normalized.endsWith("+") ? "+" : normalized.split("+").pop();
+	if (!baseKey || !BASE_KEYS.has(baseKey)) return undefined;
+
+	const modifierSource = normalized.slice(0, normalized.length - baseKey.length);
+	const modifierParts =
+		modifierSource.length === 0
+			? []
+			: modifierSource
+					.slice(0, -1)
+					.split("+")
+					.map(part => part.trim());
+	if (modifierParts.some(part => !KEY_MODIFIERS.includes(part as KeyModifier))) return undefined;
+
+	const modifiers = modifierParts as KeyModifier[];
+	if (new Set(modifiers).size !== modifiers.length) return undefined;
+
+	const canonicalBase = baseKey === "pageup" ? "pageUp" : baseKey === "pagedown" ? "pageDown" : baseKey;
+	return {
+		keyId: [...modifiers, canonicalBase].join("+") as KeyId,
+		modifiers,
+		baseKey: canonicalBase as BaseKey,
+	};
+}
+
+/** Whether a value is a valid canonical key identifier. */
+export function isKeyId(value: string): value is KeyId {
+	return parseKeyId(value)?.keyId === value;
+}
+
 /**
  * Typed helper for constructing key identifiers with autocomplete.
  *

package/src/metrics.ts

@@ -124,6 +124,7 @@ export interface RenderMetricsSnapshot {
 	timerGauges: Record<string, number>;
 	helperStats: Record<string, HelperStat>;
 	lineCounts: Record<string, LineCountGauge>;
+	structuralCounters: Record<string, number>;
 }
 
 function emptyDurationStats(): DurationStats {
@@ -160,6 +161,7 @@ export class RenderMetrics {
 	#timerGauges = new Map<string, number>();
 	#helpers = new Map<string, { count: number; totalMs: number }>();
 	#lineGauges = new Map<string, LineCountGauge>();
+	#structuralCounters = new Map<string, number>();
 	#rssReturn: number | null = null;
 	#heapBaseline: number | null = null;
 	#heapReturn: number | null = null;
@@ -200,6 +202,7 @@ export class RenderMetrics {
 		this.#timerGauges.clear();
 		this.#helpers.clear();
 		this.#lineGauges.clear();
+		this.#structuralCounters.clear();
 		this.#rssReturn = null;
 		this.#heapBaseline = null;
 		this.#heapReturn = null;
@@ -296,6 +299,13 @@ export class RenderMetrics {
 		this.#lineGauges.set(retained, cur);
 	}
 
+	/** Accumulate deterministic structural render work without retaining frame data. */
+	recordStructuralCounter(name: string, value = 1): void {
+		if (!this.#enabled) return;
+		const retained = retainedLabel(this.#structuralCounters, name);
+		this.#structuralCounters.set(retained, (this.#structuralCounters.get(retained) ?? 0) + value);
+	}
+
 	/**
 	 * Force a GC when the runtime exposes one and sample RSS as the post-run
 	 * "return" value used by the memory-leak gate. Callers should drop large
@@ -345,6 +355,10 @@ export class RenderMetrics {
 		return out;
 	}
 
+	#structuralCounterStats(): Record<string, number> {
+		return Object.fromEntries(this.#structuralCounters);
+	}
+
 	snapshot(): RenderMetricsSnapshot {
 		return {
 			enabled: this.#enabled,
@@ -374,6 +388,7 @@ export class RenderMetrics {
 			timerGauges: Object.fromEntries(this.#timerGauges),
 			helperStats: this.#helperStats(),
 			lineCounts: this.#lineCountStats(),
+			structuralCounters: this.#structuralCounterStats(),
 		};
 	}
 }

package/src/terminal-capabilities.ts

@@ -1,5 +1,5 @@
 import { encodeSixel } from "@sayknow-cli/natives";
-import { $env } from "@sayknow-cli/utils";
+import { $env, $pickenv } from "@sayknow-cli/utils";
 
 export enum ImageProtocol {
 	Kitty = "\x1b_G",
@@ -125,7 +125,7 @@ export function isCursorNeutralImagePermittedInFallback(): boolean {
 }
 
 function getForcedImageProtocol(): ImageProtocol | null | undefined {
-	const raw = $env.PI_FORCE_IMAGE_PROTOCOL?.trim().toLowerCase();
+	const raw = $pickenv("SKC_FORCE_IMAGE_PROTOCOL", "PI_FORCE_IMAGE_PROTOCOL")?.trim().toLowerCase();
 	if (!raw) return undefined;
 	if (raw === "kitty") return ImageProtocol.Kitty;
 	if (raw === "iterm2" || raw === "iterm") return ImageProtocol.Iterm2;
@@ -182,6 +182,46 @@ export function wrapTmuxPassthrough(payload: string, env: NodeJS.ProcessEnv = Bu
 	return `\x1bPtmux;${payload.replaceAll("\x1b", "\x1b\x1b")}\x1b\\`;
 }
 
+/**
+ * Returns whether tmux itself claims the sixel capability for the attached client.
+ *
+ * This is the difference between tmux *owning* the graphic and tmux *not knowing it
+ * exists*. tmux 3.4+ parses sixel into its own screen model (`screen_write_sixelimage`)
+ * and re-renders it via `tty_cmd_sixelimage`, so scrolling, clearing, resizing, and
+ * copy-mode all behave. It only does that when `terminal-features` advertises `sixel`
+ * for the client's terminal.
+ *
+ * Without the feature the graphic must be smuggled past tmux with DCS passthrough —
+ * and then tmux can never erase what it never recorded, which is exactly how the pet
+ * leaves sixel residue behind: the erase (`ECH`) reaches tmux's cell buffer while the
+ * pixels live in the outer terminal's image plane.
+ *
+ * The answer is cached: it is a per-client property that cannot change without a
+ * re-attach, and the probe shells out to tmux.
+ */
+let tmuxSixelOwnershipCache: boolean | undefined;
+export function tmuxOwnsSixel(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	if (!isUnderTmux(env)) return false;
+	if (tmuxSixelOwnershipCache !== undefined) return tmuxSixelOwnershipCache;
+	try {
+		const probe = Bun.spawnSync({
+			cmd: [env.SKC_TMUX_COMMAND?.trim() || "tmux", "display", "-p", "#{client_termfeatures}"],
+			stdout: "pipe",
+			stderr: "ignore",
+		});
+		const features = probe.success ? new TextDecoder().decode(probe.stdout).trim().split(",") : [];
+		tmuxSixelOwnershipCache = features.includes("sixel");
+	} catch {
+		tmuxSixelOwnershipCache = false;
+	}
+	return tmuxSixelOwnershipCache;
+}
+
+/** Testing seam: drop the cached tmux sixel-ownership answer. */
+export function resetTmuxSixelOwnershipCache(): void {
+	tmuxSixelOwnershipCache = undefined;
+}
+
 function parseMajorMinorVersion(versionRaw?: string): { major: number; minor: number } | null {
 	if (!versionRaw) return null;
 	const match = /^(\d+)\.(\d+)/u.exec(versionRaw.trim());

package/src/terminal.ts

@@ -1,9 +1,8 @@
 import { dlopen, FFIType, ptr } from "bun:ffi";
 import * as fs from "node:fs";
-import { $env, $flag } from "@sayknow-cli/utils";
+import { $env, $flag, $pickenv } from "@sayknow-cli/utils";
 import { setKittyProtocolActive } from "./keys";
 import { StdinBuffer } from "./stdin-buffer";
-import { isUnderTerminalMultiplexer } from "./terminal-capabilities";
 
 const TERMINAL_PROGRESS_KEEPALIVE_MS = 1000;
 const TERMINAL_PROGRESS_ACTIVE_SEQUENCE = "\x1b]9;4;3\x07";
@@ -92,6 +91,7 @@ export function emergencyTerminalRestore(): void {
 			process.stdout.write(
 				"\x1b[?2004l" + // Disable bracketed paste
 					"\x1b[?1000l" + // Disable normal mouse reporting
+					"\x1b[?1002l" + // Disable button-event mouse reporting
 					"\x1b[?1006l" + // Disable SGR extended mouse reporting
 					"\x1b[?2031l" + // Disable Mode 2031 appearance notifications
 					"\x1b[<u" + // Pop kitty keyboard protocol
@@ -249,7 +249,7 @@ export class ProcessTerminal implements Terminal {
 	#stdinBuffer?: StdinBuffer;
 	#stdinDataHandler?: (data: string | Buffer) => void;
 	#dead = false;
-	#writeLogPath = $env.PI_TUI_WRITE_LOG || "";
+	#writeLogPath = $pickenv("SKC_TUI_WRITE_LOG", "PI_TUI_WRITE_LOG") || "";
 	#detachLogPath = $env.PI_TUI_TERMINAL_DETACH_LOG || "";
 	#windowsVTInputRestore?: () => void;
 	#stdoutErrorHandler?: (err: Error) => void;
@@ -284,8 +284,11 @@ export class ProcessTerminal implements Terminal {
 	}
 
 	setMouseEnabled(enabled: boolean): void {
-		this.#mouseEnabled = enabled && !isUnderTerminalMultiplexer(Bun.env);
-		if (this.#started) this.#safeWrite(this.#mouseEnabled ? "\x1b[?1000h\x1b[?1006h" : "\x1b[?1000l\x1b[?1006l");
+		this.#mouseEnabled = enabled;
+		if (this.#started)
+			this.#safeWrite(
+				this.#mouseEnabled ? "\x1b[?1000l\x1b[?1002h\x1b[?1006h" : "\x1b[?1000l\x1b[?1002l\x1b[?1006l",
+			);
 	}
 
 	start(onInput: (data: string) => void, onResize: () => void): void {
@@ -315,8 +318,9 @@ export class ProcessTerminal implements Terminal {
 
 		// Enable bracketed paste mode - terminal will wrap pastes in \x1b[200~ ... \x1b[201~
 		this.#safeWrite("\x1b[?2004h");
-		// SGR mouse reporting is opt-in and never enabled inside tmux or screen.
-		if (this.#mouseEnabled) this.#safeWrite("\x1b[?1000h\x1b[?1006h");
+		// Button-event reporting preserves wheel input while also letting the TUI implement drag selection.
+		// Clear both tracking variants first so stale modes from another application cannot leak across startup.
+		this.#safeWrite(this.#mouseEnabled ? "\x1b[?1000l\x1b[?1002h\x1b[?1006h" : "\x1b[?1000l\x1b[?1002l\x1b[?1006l");
 
 		// Set up resize handler immediately
 		process.stdout.on("resize", this.#resizeHandler);
@@ -752,6 +756,7 @@ export class ProcessTerminal implements Terminal {
 		this.#mouseEnabled = false;
 		this.#safeWrite("\x1b[?2004l");
 		this.#safeWrite("\x1b[?1000l");
+		this.#safeWrite("\x1b[?1002l");
 		this.#safeWrite("\x1b[?1006l");
 
 		// Disable Mode 2031 appearance change notifications