@oh-my-pi/pi-tui 17.2.1 → 17.2.2

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [17.2.2] - 2026-07-31
+
+### Added
+
+- Added request tokens to explicit OSC 11 appearance refreshes to allow consumers to correlate responses across queued and coalesced terminal probes.
+
+### Fixed
+
+- Fixed the event-loop watchdog incorrectly reporting system sleep or suspension as a synchronous ui.loop-blocked stall.
+- Fixed terminal copies of fenced-code blocks retaining margins from components, lists, or blockquotes in assistant messages (#7055 by @GratefulDave).
+
 ## [17.2.0] - 2026-07-30
 
 ### Added

package/dist/types/loop-watchdog.d.ts

@@ -3,6 +3,8 @@ export interface LoopWatchdogOptions {
     intervalMs?: number;
     /** A tick later than this past its deadline counts as a block. Default 250. */
     thresholdMs?: number;
+    /** Overshoot beyond this likely includes system sleep, so it is suppressed. Default 60_000. */
+    sleepMs?: number;
     /** Monotonic clock source; injectable for tests. Default `performance.now`. */
     now?: () => number;
     /** Timer source; injectable for tests. Default `setTimeout`. */
@@ -28,7 +30,10 @@ interface LoopWatchdogTimer {
  * The handle is `unref`'d so the probe never keeps the process alive, and stop()
  * cancels the armed timer when the handle exposes `cancel` (the default
  * `setTimeout` handle does, via `clearTimeout`). The `#generation` guard remains
- * as a fallback for injected handles that cannot cancel.
+ * as a fallback for injected handles that cannot cancel. An overshoot beyond
+ * `sleepMs` is treated as system sleep rather than a synchronous stall: the
+ * process could not have run JS during the missed interval, and one resume
+ * should not produce a multi-minute `ui.loop-blocked` record.
  */
 export declare class LoopWatchdog {
     #private;

package/dist/types/terminal.d.ts

@@ -58,6 +58,8 @@ export declare function setAltScreenActive(active: boolean): void;
 export declare function emergencyTerminalRestore(): void;
 /** Terminal-reported appearance (dark/light mode). */
 export type TerminalAppearance = "dark" | "light";
+/** Identity of an accepted explicit terminal appearance refresh request. */
+export type TerminalAppearanceRequestToken = number;
 export interface Terminal {
     start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void): void;
     stop(): void;
@@ -90,24 +92,28 @@ export interface Terminal {
      * Subscribers registered after detection are invoked immediately with the
      * already-detected appearance so late subscribers never miss it.
      */
-    onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
+    onAppearanceChange(callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void): void;
     /**
      * Register a callback fired for every valid OSC 11 appearance report,
      * including reports whose classification matches the current appearance.
      * Unlike onAppearanceChange, this does not replay an earlier report.
      * Optional so custom Terminals built against older pi-tui versions keep working.
      */
-    onAppearanceReport?(callback: (appearance: TerminalAppearance) => void): (() => void) | void;
+    onAppearanceReport?(callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void): (() => void) | void;
     /**
      * Issue a single OSC 11 background-color re-query, driving the appearance
      * callbacks through the same parse/dedup pipeline used at startup and on Mode
      * 2031 notifications. Bounded: one probe per call, no timers. Invoked on the
-     * user's explicit display-reset gesture (Ctrl+L) so terminals that cannot
+     * user's explicit display-reset gesture so terminals that cannot
      * deliver end-to-end Mode 2031 notifications still pick up a light/dark switch
-     * without a restart. Optional so custom Terminals built against older pi-tui
-     * versions keep working.
+     * without a restart.
+     *
+     * A caller-provided token must be propagated unchanged to callbacks and
+     * returned when the request is accepted. This lets callers establish ownership
+     * before implementations synchronously dispatch a cached response. Optional so
+     * custom Terminals built against older pi-tui versions keep working.
      */
-    refreshAppearance?(): void;
+    refreshAppearance?(requestToken?: TerminalAppearanceRequestToken): TerminalAppearanceRequestToken | void;
     /** The last detected terminal appearance, or undefined if not yet known. */
     get appearance(): TerminalAppearance | undefined;
     /**
@@ -137,8 +143,8 @@ export declare class ProcessTerminal implements Terminal {
     get keyboardEnhancementEnterSequence(): string | null;
     get keyboardEnhancementExitSequence(): string | null;
     get appearance(): TerminalAppearance | undefined;
-    onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
-    onAppearanceReport(callback: (appearance: TerminalAppearance) => void): () => void;
+    onAppearanceChange(callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void): void;
+    onAppearanceReport(callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void): () => void;
     /**
      * Re-query the terminal background via a single OSC 11 probe. Reuses the
      * startup DA1-sentinel FIFO, pending/queued gating, parsing, dedup, and
@@ -148,7 +154,7 @@ export declare class ProcessTerminal implements Terminal {
      * armed. Suppressed while inactive, headless, or after the terminal is torn
      * down.
      */
-    refreshAppearance(): void;
+    refreshAppearance(requestToken?: TerminalAppearanceRequestToken): TerminalAppearanceRequestToken | void;
     onPrivateModeReport(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void;
     start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void): void;
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "17.2.1",
+	"version": "17.2.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": "17.2.1",
-		"@oh-my-pi/pi-utils": "17.2.1",
+		"@oh-my-pi/pi-natives": "17.2.2",
+		"@oh-my-pi/pi-utils": "17.2.2",
 		"lru-cache": "11.5.2",
 		"marked": "^18.0.6"
 	},

package/src/components/markdown.ts

@@ -837,6 +837,19 @@ const RENDER_CACHE_MAX_SIZE = 4 * 1024 * 1024;
 const RENDER_CACHE_MAX_ENTRY_SIZE = 256 * 1024;
 const EMPTY_RENDER_LINES: readonly string[] = [];
 
+interface RenderedLine {
+	text: string;
+	literalCode?: true;
+}
+
+interface RenderedListItemLine extends RenderedLine {
+	nested: boolean;
+}
+
+function renderedLine(text: string, literalCode?: boolean): RenderedLine {
+	return literalCode ? { text, literalCode: true } : { text };
+}
+
 interface RenderCacheEntry {
 	lines: readonly string[];
 	tables: readonly RenderedTableLayout[];
@@ -1858,7 +1871,7 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 		rowOffset: number,
 		startingSourceOffset: number,
 	): string[] {
-		const wrappedLines: string[] = [];
+		const wrappedLines: RenderedLine[] = [];
 		let sourceOffset = startingSourceOffset;
 		for (let i = start; i < end; i++) {
 			const token = tokens[i];
@@ -1874,14 +1887,21 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 				`offset:${sourceOffset}`,
 			);
 			const tokenLineOffsets = [0];
-			for (const line of renderedTokenLines) {
+			for (const renderedRow of renderedTokenLines) {
 				// Lists wrap while their structural prefixes are still available, so
 				// continuation rows retain the correct hanging indent. Re-wrapping the
 				// flattened rows here would discard that structure.
-				if (token.type === "list" || TERMINAL.isImageLine(line) || isOsc66Line(line)) {
-					wrappedLines.push(line);
+				if (token.type === "list" || TERMINAL.isImageLine(renderedRow.text) || isOsc66Line(renderedRow.text)) {
+					wrappedLines.push(renderedRow);
 				} else {
-					wrappedLines.push(...wrapTextWithAnsi(line, contentWidth));
+					const wrappedRows = wrapTextWithAnsi(renderedRow.text, contentWidth);
+					if (wrappedRows.length === 1 && wrappedRows[0] === renderedRow.text) {
+						wrappedLines.push(renderedRow);
+					} else {
+						for (const wrappedLine of wrappedRows) {
+							wrappedLines.push(renderedLine(wrappedLine, renderedRow.literalCode));
+						}
+					}
 				}
 				tokenLineOffsets.push(wrappedLines.length - tokenWrappedRowStart);
 			}
@@ -1914,8 +1934,9 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 		const bgFn = this.#defaultTextStyle?.bgColor;
 		const contentLines: string[] = [];
 		let previousLineWasOsc66 = false;
-
-		for (const line of wrappedLines) {
+		for (const renderedLine of wrappedLines) {
+			const literalCodeRow = renderedLine.literalCode === true;
+			const line = renderedLine.text;
 			// The first empty row after a scale>1 OSC 66 heading is structural:
 			// it reserves the lower cells occupied by the multicell glyphs. Do
 			// not pad or background-fill it, because real spaces on that row can
@@ -1935,6 +1956,10 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 			}
 
 			previousLineWasOsc66 = false;
+			if (literalCodeRow) {
+				contentLines.push(line);
+				continue;
+			}
 			const lineWithMargins = leftMargin + line + rightMargin;
 
 			if (bgFn) {
@@ -1965,8 +1990,9 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 		return layouts;
 	}
 
-	#renderCodeBodyLines(token: Token, codeIndent: string): string[] {
-		const bodyLines: string[] = [];
+	#renderCodeBodyLines(token: Token, codeIndent: string): RenderedLine[] {
+		const literalCode = this.#codeBlockIndent === 0;
+		const bodyLines: RenderedLine[] = [];
 		const tokenText = "text" in token && typeof token.text === "string" ? token.text : "";
 		const lang = "lang" in token && typeof token.lang === "string" ? token.lang : undefined;
 		const normalizedLang = lang?.toLowerCase();
@@ -1975,11 +2001,14 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 			!this.#renderingFrozenPrefix &&
 			this.#theme.highlightCode &&
 			(normalizedLang === "diff" || normalizedLang === "patch" || normalizedLang === "udiff");
+		const addBodyLine = (line: string): void => {
+			bodyLines.push(renderedLine(literalCode ? line : codeIndent + line, literalCode));
+		};
 
 		if (this.#theme.highlightCode && (!this.transientRenderCache || this.#renderingFrozenPrefix)) {
 			const highlightedLines = this.#theme.highlightCode(tokenText, lang);
 			for (const hlLine of highlightedLines) {
-				bodyLines.push(`${codeIndent}${hlLine}`);
+				addBodyLine(hlLine);
 			}
 			return bodyLines;
 		}
@@ -1990,11 +2019,11 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 			if (closedFence || lineEnd >= 0) {
 				const completedText = closedFence ? tokenText : tokenText.slice(0, lineEnd);
 				for (const hlLine of this.#highlightStreamingDiffLines(completedText, lang)) {
-					bodyLines.push(`${codeIndent}${hlLine}`);
+					addBodyLine(hlLine);
 				}
 				if (!closedFence) {
 					for (const codeLine of tokenText.slice(lineEnd + 1).split("\n")) {
-						bodyLines.push(`${codeIndent}${this.#theme.codeBlock(codeLine)}`);
+						addBodyLine(this.#theme.codeBlock(codeLine));
 					}
 				}
 				return bodyLines;
@@ -2002,7 +2031,7 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 		}
 
 		for (const codeLine of tokenText.split("\n")) {
-			bodyLines.push(`${codeIndent}${this.#theme.codeBlock(codeLine)}`);
+			addBodyLine(this.#theme.codeBlock(codeLine));
 		}
 		return bodyLines;
 	}
@@ -2181,14 +2210,14 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 		nextTokenType?: string,
 		styleContext?: InlineStyleContext,
 		tokenKey = "root",
-	): string[] {
-		const lines: string[] = [];
+	): RenderedLine[] {
+		const lines: RenderedLine[] = [];
 
 		// Display math block (own-line `$$…$$` / `\[…\]`): stack `\frac` vertically
 		// and keep `\\` row breaks, so fractions and matrices span multiple lines.
 		if (isMathToken(token)) {
-			for (const mathLine of latexToBlock(token.text)) lines.push(this.#applyDefaultStyle(mathLine));
-			if (nextTokenType && nextTokenType !== "space") lines.push("");
+			for (const mathLine of latexToBlock(token.text)) lines.push(renderedLine(this.#applyDefaultStyle(mathLine)));
+			if (nextTokenType && nextTokenType !== "space") lines.push(renderedLine(""));
 			return lines;
 		}
 
@@ -2203,10 +2232,10 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 					const plainWidth = visibleWidth(headingPlainText);
 					if (plainWidth > 0 && 2 * plainWidth <= width) {
 						const sizedHeading = encodeTextSizedHeading(headingPlainText, 2);
-						lines.push(this.#theme.heading(this.#theme.bold(this.#theme.underline(sizedHeading))));
-						lines.push(""); // reserve the heading's second visual row
+						lines.push(renderedLine(this.#theme.heading(this.#theme.bold(this.#theme.underline(sizedHeading)))));
+						lines.push(renderedLine("")); // reserve the heading's second visual row
 						if (nextTokenType && nextTokenType !== "space") {
-							lines.push(""); // Add spacing after headings (unless space token follows)
+							lines.push(renderedLine("")); // Add spacing after headings (unless space token follows)
 						}
 						break;
 					}
@@ -2218,9 +2247,9 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 				} else {
 					styledHeading = this.#theme.heading(this.#theme.bold(headingPrefix + headingText));
 				}
-				lines.push(styledHeading);
+				lines.push(renderedLine(styledHeading));
 				if (nextTokenType && nextTokenType !== "space") {
-					lines.push(""); // Add spacing after headings (unless space token follows)
+					lines.push(renderedLine("")); // Add spacing after headings (unless space token follows)
 				}
 				break;
 			}
@@ -2228,15 +2257,18 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 			case "paragraph": {
 				const displayMath = soleDisplayMath(token.tokens);
 				if (displayMath) {
-					for (const mathLine of latexToBlock(displayMath.text)) lines.push(this.#applyDefaultStyle(mathLine));
-					if (nextTokenType && nextTokenType !== "list" && nextTokenType !== "space") lines.push("");
+					for (const mathLine of latexToBlock(displayMath.text))
+						lines.push(renderedLine(this.#applyDefaultStyle(mathLine)));
+					if (nextTokenType && nextTokenType !== "list" && nextTokenType !== "space") lines.push(renderedLine(""));
 					break;
 				}
 				const paragraphText = this.#renderInlineTokens(token.tokens || [], styleContext);
-				lines.push(...(hangWrapTreeGuideLines(paragraphText, width) ?? [paragraphText]));
+				for (const paragraphLine of hangWrapTreeGuideLines(paragraphText, width) ?? [paragraphText]) {
+					lines.push(renderedLine(paragraphLine));
+				}
 				// Don't add spacing if next token is space or list
 				if (nextTokenType && nextTokenType !== "list" && nextTokenType !== "space") {
-					lines.push("");
+					lines.push(renderedLine(""));
 				}
 				break;
 			}
@@ -2252,24 +2284,28 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 					if (ascii) {
 						for (const asciiLine of ascii.split("\n")) {
 							lines.push(
-								visibleWidth(asciiLine) > width ? truncateToWidth(asciiLine, width, Ellipsis.Omit) : asciiLine,
+								renderedLine(
+									visibleWidth(asciiLine) > width
+										? truncateToWidth(asciiLine, width, Ellipsis.Omit)
+										: asciiLine,
+								),
 							);
 						}
 						if (nextTokenType && nextTokenType !== "space") {
-							lines.push("");
+							lines.push(renderedLine(""));
 						}
 						break;
 					}
 				}
 
 				const codeIndent = padding(this.#codeBlockIndent);
-				lines.push(this.#theme.codeBlockBorder(`\`\`\`${token.lang || ""}`));
+				lines.push(renderedLine(this.#theme.codeBlockBorder(`\`\`\`${token.lang || ""}`)));
 				for (const bodyLine of this.#renderCodeBodyLines(token, codeIndent)) {
 					lines.push(bodyLine);
 				}
-				lines.push(this.#theme.codeBlockBorder("```"));
+				lines.push(renderedLine(this.#theme.codeBlockBorder("```")));
 				if (nextTokenType && nextTokenType !== "space") {
-					lines.push(""); // Add spacing after code blocks (unless space token follows)
+					lines.push(renderedLine("")); // Add spacing after code blocks (unless space token follows)
 				}
 				break;
 			}
@@ -2284,7 +2320,7 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 
 			case "table": {
 				const tableLines = this.#renderTable(token as TableToken, width, nextTokenType, styleContext, tokenKey);
-				lines.push(...tableLines);
+				for (const tableLine of tableLines) lines.push(renderedLine(tableLine));
 				break;
 			}
 
@@ -2295,7 +2331,7 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 				};
 				const quoteContentWidth = Math.max(1, width - 2);
 				const quoteTokens = token.tokens || [];
-				const renderedQuoteLines: string[] = [];
+				const renderedQuoteLines: RenderedLine[] = [];
 				const blockquoteSpecStart = this.#activeTableRenderSpecs?.length ?? 0;
 
 				for (let i = 0; i < quoteTokens.length; i++) {
@@ -2331,7 +2367,7 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 					}
 				}
 
-				while (renderedQuoteLines.length > 0 && renderedQuoteLines[renderedQuoteLines.length - 1] === "") {
+				while (renderedQuoteLines.length > 0 && renderedQuoteLines[renderedQuoteLines.length - 1]!.text === "") {
 					renderedQuoteLines.pop();
 				}
 
@@ -2350,16 +2386,16 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 				}
 				lines.push(...borderedQuoteLines);
 				if (nextTokenType && nextTokenType !== "space") {
-					lines.push(""); // Add spacing after blockquotes (unless space token follows)
+					lines.push(renderedLine("")); // Add spacing after blockquotes (unless space token follows)
 				}
 				break;
 			}
 
 			case "hr": {
 				const raw = "raw" in token && typeof token.raw === "string" ? token.raw.trim() : "";
-				lines.push(this.#renderHrLine(width, raw[0] || ""));
+				lines.push(renderedLine(this.#renderHrLine(width, raw[0] || "")));
 				if (nextTokenType && nextTokenType !== "space") {
-					lines.push(""); // Add spacing after horizontal rules (unless space token follows)
+					lines.push(renderedLine("")); // Add spacing after horizontal rules (unless space token follows)
 				}
 				break;
 			}
@@ -2372,13 +2408,13 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 
 			case "space":
 				// Space tokens represent blank lines in markdown
-				lines.push("");
+				lines.push(renderedLine(""));
 				break;
 
 			default:
 				// Handle any other token types as plain text
 				if ("text" in token && typeof token.text === "string") {
-					lines.push(token.text);
+					lines.push(renderedLine(token.text));
 				}
 		}
 
@@ -2395,7 +2431,7 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 	 * Wrap already-rendered lines in the blockquote border and quote styling.
 	 * `width` is the full content width; the border reserves two cells.
 	 */
-	#applyQuoteBorder(renderedLines: string[], width: number, sourceRowOffsets?: number[]): string[] {
+	#applyQuoteBorder(renderedLines: RenderedLine[], width: number, sourceRowOffsets?: number[]): RenderedLine[] {
 		const quoteStyle = (text: string) => this.#theme.quote(this.#theme.italic(text));
 		const quoteStylePrefix = this.#getStylePrefix(quoteStyle);
 		const applyQuoteStyle = (line: string): string => {
@@ -2406,12 +2442,23 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 			return quoteStyle(lineWithReappliedStyle);
 		};
 		const quoteContentWidth = Math.max(1, width - 2);
-		const lines: string[] = [];
+		const lines: RenderedLine[] = [];
 		sourceRowOffsets?.push(0);
 		for (const quoteLine of renderedLines) {
-			const styledLine = applyQuoteStyle(quoteLine);
-			for (const wrappedLine of wrapTextWithAnsi(styledLine, quoteContentWidth)) {
-				lines.push(this.#theme.quoteBorder(`${this.#theme.symbols.quoteBorder} `) + wrappedLine);
+			if (quoteLine.literalCode) {
+				const wrappedLiteralRows = wrapTextWithAnsi(quoteLine.text, quoteContentWidth);
+				if (wrappedLiteralRows.length === 0) {
+					lines.push(renderedLine("", true));
+				} else {
+					for (const wrappedLine of wrappedLiteralRows) {
+						lines.push(renderedLine(wrappedLine, true));
+					}
+				}
+			} else {
+				const styledLine = applyQuoteStyle(quoteLine.text);
+				for (const wrappedLine of wrapTextWithAnsi(styledLine, quoteContentWidth)) {
+					lines.push(renderedLine(this.#theme.quoteBorder(`${this.#theme.symbols.quoteBorder} `) + wrappedLine));
+				}
 			}
 			sourceRowOffsets?.push(lines.length);
 		}
@@ -2424,8 +2471,8 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 	 * quote styling; the remaining markup is normalized to terminal text (entities
 	 * decoded, `<code>` themed, lists/`<br>`/`<p>` laid out).
 	 */
-	#renderHtmlBlock(raw: string, width: number): string[] {
-		const lines: string[] = [];
+	#renderHtmlBlock(raw: string, width: number): RenderedLine[] {
+		const lines: RenderedLine[] = [];
 		const state = createHtmlNormalizationState();
 		const codeHook = (text: string): string => this.#theme.code(text) + this.#getDefaultStylePrefix();
 		const flushText = (chunk: string): void => {
@@ -2433,7 +2480,7 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 			if (cleaned.trim() === "") return;
 			for (const line of splitTerminalLines(cleaned)) {
 				const trimmed = line.trimEnd();
-				lines.push(trimmed.trim() === "" ? "" : this.#applyDefaultStyle(trimmed));
+				lines.push(renderedLine(trimmed.trim() === "" ? "" : this.#applyDefaultStyle(trimmed)));
 			}
 		};
 		let lastIndex = 0;
@@ -2444,7 +2491,7 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 			if (match[1] !== undefined) {
 				lines.push(...this.#renderHtmlBlockquote(match[1], width));
 			} else {
-				lines.push(this.#renderHrLine(width));
+				lines.push(renderedLine(this.#renderHrLine(width)));
 			}
 		}
 		flushText(raw.slice(lastIndex));
@@ -2452,10 +2499,10 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 	}
 
 	/** Render the inner content of an HTML `<blockquote>` with quote styling. */
-	#renderHtmlBlockquote(inner: string, width: number): string[] {
+	#renderHtmlBlockquote(inner: string, width: number): RenderedLine[] {
 		const cleaned = normalizeHtmlForTerminal(inner, createHtmlNormalizationState(), text => this.#theme.code(text));
-		const innerLines = splitTerminalLines(cleaned).map(line => line.trimEnd());
-		while (innerLines.length > 0 && innerLines[innerLines.length - 1] === "") innerLines.pop();
+		const innerLines = splitTerminalLines(cleaned).map(line => renderedLine(line.trimEnd()));
+		while (innerLines.length > 0 && innerLines[innerLines.length - 1].text === "") innerLines.pop();
 		return this.#applyQuoteBorder(innerLines, width);
 	}
 
@@ -2591,27 +2638,41 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 	/**
 	 * Render a list with proper nesting support
 	 */
-	#renderList(token: ListToken, depth: number, width: number, styleContext?: InlineStyleContext): string[] {
-		const lines: string[] = [];
+	#renderList(token: ListToken, depth: number, width: number, styleContext?: InlineStyleContext): RenderedLine[] {
+		const lines: RenderedLine[] = [];
 		const indent = "  ".repeat(depth);
 		// Use the list's start property (defaults to 1 for ordered lists)
 		const startNumber = token.start ?? 1;
-		const pushWrapped = (text: string, firstPrefix: string, continuationPrefix: string): void => {
+		const pushWrapped = (line: RenderedLine, firstPrefix: string, continuationPrefix: string): void => {
+			if (line.literalCode) {
+				const wrappedLiteralRows = wrapTextWithAnsi(line.text, Math.max(1, width));
+				if (wrappedLiteralRows.length === 0) {
+					lines.push(renderedLine("", true));
+				} else {
+					for (const wrappedLine of wrappedLiteralRows) {
+						lines.push(renderedLine(wrappedLine, true));
+					}
+				}
+				return;
+			}
+
 			const prefixWidth = visibleWidth(firstPrefix);
 			if (prefixWidth >= width) {
-				lines.push(truncateToWidth(firstPrefix, width, Ellipsis.Omit));
-				lines.push(...wrapTextWithAnsi(text, Math.max(1, width)));
+				lines.push(renderedLine(truncateToWidth(firstPrefix, width, Ellipsis.Omit)));
+				for (const wrappedLine of wrapTextWithAnsi(line.text, Math.max(1, width))) {
+					lines.push(renderedLine(wrappedLine));
+				}
 				return;
 			}
 			const bodyWidth = width - prefixWidth;
-			const wrapped = wrapTextWithAnsi(text, bodyWidth);
+			const wrapped = wrapTextWithAnsi(line.text, bodyWidth);
 			if (wrapped.length === 0) {
-				lines.push(firstPrefix);
+				lines.push(renderedLine(firstPrefix));
 				return;
 			}
-			lines.push(firstPrefix + wrapped[0]);
+			lines.push(renderedLine(firstPrefix + wrapped[0]));
 			for (let lineIndex = 1; lineIndex < wrapped.length; lineIndex++) {
-				lines.push(continuationPrefix + wrapped[lineIndex]);
+				lines.push(renderedLine(continuationPrefix + wrapped[lineIndex]));
 			}
 		};
 
@@ -2630,21 +2691,21 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 			if (itemLines.length > 0) {
 				const firstLine = itemLines[0]!;
 				if (firstLine.nested) {
-					lines.push(firstLine.text);
+					lines.push(firstLine);
 				} else {
-					pushWrapped(firstLine.text, firstPrefix, continuationIndent);
+					pushWrapped(firstLine, firstPrefix, continuationIndent);
 				}
 
 				for (let j = 1; j < itemLines.length; j++) {
 					const line = itemLines[j]!;
 					if (line.nested) {
-						lines.push(line.text);
+						lines.push(line);
 					} else {
-						pushWrapped(line.text, continuationIndent, continuationIndent);
+						pushWrapped(line, continuationIndent, continuationIndent);
 					}
 				}
 			} else {
-				lines.push(firstPrefix);
+				lines.push(renderedLine(firstPrefix));
 			}
 		}
 
@@ -2662,8 +2723,8 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 		parentDepth: number,
 		width: number,
 		styleContext?: InlineStyleContext,
-	): Array<{ text: string; nested: boolean }> {
-		const lines: Array<{ text: string; nested: boolean }> = [];
+	): RenderedListItemLine[] {
+		const lines: RenderedListItemLine[] = [];
 
 		for (const token of tokens) {
 			if (token.type === "list") {
@@ -2671,7 +2732,7 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 				// These lines carry their own indent, so tag them for pass-through
 				const nestedLines = this.#renderList(token as ListToken, parentDepth + 1, width, styleContext);
 				for (const nestedLine of nestedLines) {
-					lines.push({ text: nestedLine, nested: true });
+					lines.push({ ...nestedLine, nested: true });
 				}
 			} else if (token.type === "text") {
 				// Text content (may have inline tokens, or a sole display-math token)
@@ -2702,7 +2763,7 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 				const codeIndent = padding(this.#codeBlockIndent);
 				lines.push({ text: this.#theme.codeBlockBorder(`\`\`\`${token.lang || ""}`), nested: false });
 				for (const bodyLine of this.#renderCodeBodyLines(token, codeIndent)) {
-					lines.push({ text: bodyLine, nested: false });
+					lines.push({ ...bodyLine, nested: false });
 				}
 				lines.push({ text: this.#theme.codeBlockBorder("```"), nested: false });
 			} else if (isMathToken(token)) {

package/src/loop-watchdog.ts

@@ -6,6 +6,8 @@ export interface LoopWatchdogOptions {
 	intervalMs?: number;
 	/** A tick later than this past its deadline counts as a block. Default 250. */
 	thresholdMs?: number;
+	/** Overshoot beyond this likely includes system sleep, so it is suppressed. Default 60_000. */
+	sleepMs?: number;
 	/** Monotonic clock source; injectable for tests. Default `performance.now`. */
 	now?: () => number;
 	/** Timer source; injectable for tests. Default `setTimeout`. */
@@ -33,11 +35,15 @@ interface LoopWatchdogTimer {
  * The handle is `unref`'d so the probe never keeps the process alive, and stop()
  * cancels the armed timer when the handle exposes `cancel` (the default
  * `setTimeout` handle does, via `clearTimeout`). The `#generation` guard remains
- * as a fallback for injected handles that cannot cancel.
+ * as a fallback for injected handles that cannot cancel. An overshoot beyond
+ * `sleepMs` is treated as system sleep rather than a synchronous stall: the
+ * process could not have run JS during the missed interval, and one resume
+ * should not produce a multi-minute `ui.loop-blocked` record.
  */
 export class LoopWatchdog {
 	#intervalMs: number;
 	#thresholdMs: number;
+	#sleepMs: number;
 	#now: () => number;
 	#schedule: (cb: () => void, ms: number) => LoopWatchdogTimer;
 	#expected = 0;
@@ -52,6 +58,7 @@ export class LoopWatchdog {
 	constructor(options: LoopWatchdogOptions = {}) {
 		this.#intervalMs = options.intervalMs ?? 250;
 		this.#thresholdMs = options.thresholdMs ?? 250;
+		this.#sleepMs = options.sleepMs ?? 60_000;
 		this.#now = options.now ?? (() => performance.now());
 		this.#schedule =
 			options.schedule ??
@@ -91,7 +98,9 @@ export class LoopWatchdog {
 		// forward to a later, phase-less block.
 		const phase = takeRecentLoopPhase();
 		if (blockedMs > this.#thresholdMs) {
-			if (!this.#wasBlocked) {
+			if (blockedMs > this.#sleepMs) {
+				this.#wasBlocked = false;
+			} else if (!this.#wasBlocked) {
 				this.#wasBlocked = true;
 				logger.warn("ui.loop-blocked", {
 					blockedMs: Math.round(blockedMs),

package/src/terminal.ts

@@ -377,6 +377,8 @@ export function emergencyTerminalRestore(): void {
 }
 /** Terminal-reported appearance (dark/light mode). */
 export type TerminalAppearance = "dark" | "light";
+/** Identity of an accepted explicit terminal appearance refresh request. */
+export type TerminalAppearanceRequestToken = number;
 export interface Terminal {
 	// Start the terminal with input, resize, and host-disconnect handlers.
 	start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void): void;
@@ -444,24 +446,32 @@ export interface Terminal {
 	 * Subscribers registered after detection are invoked immediately with the
 	 * already-detected appearance so late subscribers never miss it.
 	 */
-	onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
+	onAppearanceChange(
+		callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void,
+	): void;
 	/**
 	 * Register a callback fired for every valid OSC 11 appearance report,
 	 * including reports whose classification matches the current appearance.
 	 * Unlike onAppearanceChange, this does not replay an earlier report.
 	 * Optional so custom Terminals built against older pi-tui versions keep working.
 	 */
-	onAppearanceReport?(callback: (appearance: TerminalAppearance) => void): (() => void) | void;
+	onAppearanceReport?(
+		callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void,
+	): (() => void) | void;
 	/**
 	 * Issue a single OSC 11 background-color re-query, driving the appearance
 	 * callbacks through the same parse/dedup pipeline used at startup and on Mode
 	 * 2031 notifications. Bounded: one probe per call, no timers. Invoked on the
-	 * user's explicit display-reset gesture (Ctrl+L) so terminals that cannot
+	 * user's explicit display-reset gesture so terminals that cannot
 	 * deliver end-to-end Mode 2031 notifications still pick up a light/dark switch
-	 * without a restart. Optional so custom Terminals built against older pi-tui
-	 * versions keep working.
+	 * without a restart.
+	 *
+	 * A caller-provided token must be propagated unchanged to callbacks and
+	 * returned when the request is accepted. This lets callers establish ownership
+	 * before implementations synchronously dispatch a cached response. Optional so
+	 * custom Terminals built against older pi-tui versions keep working.
 	 */
-	refreshAppearance?(): void;
+	refreshAppearance?(requestToken?: TerminalAppearanceRequestToken): TerminalAppearanceRequestToken | void;
 	/** The last detected terminal appearance, or undefined if not yet known. */
 	get appearance(): TerminalAppearance | undefined;
 	/**
@@ -574,11 +584,17 @@ export class ProcessTerminal implements Terminal {
 
 	#windowsVTInputRestore?: () => void;
 	#xtermScrollToBottomRestoreModes = new Set<number>();
-	#appearanceCallbacks: Array<(appearance: TerminalAppearance) => void> = [];
-	#appearanceReportCallbacks: Array<(appearance: TerminalAppearance) => void> = [];
+	#appearanceCallbacks: Array<
+		(appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void
+	> = [];
+	#appearanceReportCallbacks: Array<
+		(appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void
+	> = [];
 	#appearance: TerminalAppearance | undefined;
 	#osc11Pending = false;
-	#osc11QueuedRoute?: Osc11QueryRoute;
+	#osc11ActiveToken?: TerminalAppearanceRequestToken;
+	#osc11QueuedQuery?: { route: Osc11QueryRoute; token?: TerminalAppearanceRequestToken };
+	#nextAppearanceRequestToken = 1;
 	#osc11ResponseBuffer = "";
 	#osc99PendingId: string | undefined;
 	#osc99ResponseBuffer = "";
@@ -624,7 +640,9 @@ export class ProcessTerminal implements Terminal {
 		return this.#appearance;
 	}
 
-	onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void {
+	onAppearanceChange(
+		callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void,
+	): void {
 		this.#appearanceCallbacks.push(callback);
 		// Replay an already-detected appearance: the startup OSC 11 response can
 		// arrive before consumers (e.g. the theme bridge) subscribe, and the
@@ -639,7 +657,9 @@ export class ProcessTerminal implements Terminal {
 		}
 	}
 
-	onAppearanceReport(callback: (appearance: TerminalAppearance) => void): () => void {
+	onAppearanceReport(
+		callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void,
+	): () => void {
 		this.#appearanceReportCallbacks.push(callback);
 		let subscribed = true;
 		return () => {
@@ -659,9 +679,14 @@ export class ProcessTerminal implements Terminal {
 	 * armed. Suppressed while inactive, headless, or after the terminal is torn
 	 * down.
 	 */
-	refreshAppearance(): void {
+	refreshAppearance(requestToken?: TerminalAppearanceRequestToken): TerminalAppearanceRequestToken | void {
 		if (!this.#active || this.#headless || this.#dead) return;
-		this.#queryBackgroundColor(isInsideTmux() ? "tmux" : "direct");
+		const token = requestToken ?? this.#nextAppearanceRequestToken++;
+		if (token >= this.#nextAppearanceRequestToken) {
+			this.#nextAppearanceRequestToken = token + 1;
+		}
+		this.#queryBackgroundColor(isInsideTmux() ? "tmux" : "direct", token);
+		return token;
 	}
 
 	onPrivateModeReport(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void {
@@ -1011,18 +1036,19 @@ export class ProcessTerminal implements Terminal {
 						if (this.#osc11Pending) {
 							// DA1 arrived before the OSC 11 reply: terminal does not support OSC 11.
 							this.#osc11Pending = false;
+							this.#osc11ActiveToken = undefined;
 							this.#osc11ResponseBuffer = "";
 						}
 						// Start a queued OSC 11 query once the prior cycle is fully drained.
 						if (
-							this.#osc11QueuedRoute !== undefined &&
+							this.#osc11QueuedQuery !== undefined &&
 							!this.#osc11Pending &&
 							!this.#da1SentinelOwners.some(o => o.kind === "osc11") &&
 							!this.#dead
 						) {
-							const route = this.#osc11QueuedRoute;
-							this.#osc11QueuedRoute = undefined;
-							this.#startOsc11Query(route);
+							const query = this.#osc11QueuedQuery;
+							this.#osc11QueuedQuery = undefined;
+							this.#startOsc11Query(query.route, query.token);
 						}
 						break;
 					}
@@ -1103,8 +1129,10 @@ export class ProcessTerminal implements Terminal {
 					if (!osc11Match) return;
 					const [, rHex, gHex, bHex] = osc11Match;
 					this.#osc11Pending = false;
+					const requestToken = this.#osc11ActiveToken;
+					this.#osc11ActiveToken = undefined;
 					this.#osc11ResponseBuffer = "";
-					this.#handleOsc11Response(rHex!, gHex!, bHex!);
+					this.#handleOsc11Response(rHex!, gHex!, bHex!, requestToken);
 					return;
 				}
 			}
@@ -1157,22 +1185,28 @@ export class ProcessTerminal implements Terminal {
 	 * DA1 avoids indefinite hangs: if DA1 response arrives before OSC 11,
 	 * the terminal does not support OSC 11.
 	 */
-	#queryBackgroundColor(route: Osc11QueryRoute = "direct"): void {
+	#queryBackgroundColor(route: Osc11QueryRoute = "direct", token?: TerminalAppearanceRequestToken): void {
 		if (this.#dead) return;
 		// Queue if an OSC 11 query is in flight or its DA1 sentinel hasn't been
 		// consumed yet. Starting a new query while a DA1 is outstanding would
 		// increment the sentinel counter, and the old DA1 arrival would then
 		// prematurely clear the new query's pending state. Preserve a requested
-		// tmux passthrough route when coalescing direct and explicit queries.
+		// tmux passthrough route when coalescing direct and explicit queries, and
+		// retain the latest explicit request identity across automatic queries.
 		if (this.#osc11Pending || this.#da1SentinelOwners.some(o => o.kind === "osc11")) {
-			if (this.#osc11QueuedRoute !== "tmux") this.#osc11QueuedRoute = route;
+			const queued = this.#osc11QueuedQuery;
+			this.#osc11QueuedQuery = {
+				route: queued?.route === "tmux" || route === "tmux" ? "tmux" : "direct",
+				token: token ?? queued?.token,
+			};
 			return;
 		}
-		this.#startOsc11Query(route);
+		this.#startOsc11Query(route, token);
 	}
 
-	#startOsc11Query(route: Osc11QueryRoute): void {
+	#startOsc11Query(route: Osc11QueryRoute, token?: TerminalAppearanceRequestToken): void {
 		this.#osc11Pending = true;
+		this.#osc11ActiveToken = token;
 		this.#osc11ResponseBuffer = "";
 		this.#da1SentinelOwners.push({ kind: "osc11" });
 		if (route === "tmux") {
@@ -1237,7 +1271,7 @@ export class ProcessTerminal implements Terminal {
 	 * Parse an OSC 11 background color response and compute BT.601 luminance.
 	 * Handles 1-, 2-, 3-, and 4-digit XParseColor hex components.
 	 */
-	#handleOsc11Response(rHex: string, gHex: string, bHex: string): void {
+	#handleOsc11Response(rHex: string, gHex: string, bHex: string, requestToken?: TerminalAppearanceRequestToken): void {
 		const normalize = (hex: string): number => {
 			const value = parseInt(hex, 16);
 			if (Number.isNaN(value)) return 0;
@@ -1250,7 +1284,7 @@ export class ProcessTerminal implements Terminal {
 		this.#appearance = mode;
 		for (const cb of [...this.#appearanceReportCallbacks]) {
 			try {
-				cb(mode);
+				cb(mode, requestToken);
 			} catch {
 				/* ignore callback errors */
 			}
@@ -1258,7 +1292,7 @@ export class ProcessTerminal implements Terminal {
 		if (!changed) return;
 		for (const cb of this.#appearanceCallbacks) {
 			try {
-				cb(mode);
+				cb(mode, requestToken);
 			} catch {
 				/* ignore callback errors */
 			}
@@ -1516,9 +1550,11 @@ export class ProcessTerminal implements Terminal {
 			this.#mode2031DebounceTimer = undefined;
 		}
 		this.#appearanceCallbacks = [];
+		this.#appearanceReportCallbacks = [];
 		this.#osc11Pending = false;
+		this.#osc11ActiveToken = undefined;
 		this.#clearWindowsTerminalAppearancePoll();
-		this.#osc11QueuedRoute = undefined;
+		this.#osc11QueuedQuery = undefined;
 		this.#osc11ResponseBuffer = "";
 		this.#osc99PendingId = undefined;
 		this.#osc99ResponseBuffer = "";