@linxiraos/pi-tui 1.2.1 → 1.3.0

package/src/prompt/custom-editor.ts

@@ -39,6 +39,7 @@ import {
 	skillToken,
 } from "./composer-attachments";
 import { type MacOSSpellingFeatures, MacOSSpellingProvider } from "./macos-spelling";
+import { TypingWordTracker } from "./typing-word";
 import { hasMagicKeyword, highlightMagicKeywords, magicKeywordRanges } from "./magic-keywords";
 import type { TspEditorDecoration, TspText } from "@linxiraos/pi-wire";
 import { isNativeRendering } from "../native/state";
@@ -64,6 +65,8 @@ export interface ComposerNativeState {
 	readonly rate?: number;
 	/** A turn is running: the send keycap becomes a Stop button. */
 	readonly running: boolean;
+	/** Native dictation control; undefined hides it for hosts without speech-to-text. */
+	readonly dictation?: "idle" | "starting" | "recording" | "transcribing";
 	/** The viewed subagent's lineage, outermost first and the viewed agent last; undefined on the main session. */
 	readonly viewing?: readonly string[];
 	/** The session's title, quoted in italics as the TSP placeholder; undefined until it has one. */
@@ -75,12 +78,18 @@ const FOCUS_ACTION = "focus:";
 
 const IDLE_COMPOSER: ComposerNativeState = { running: false };
 
+/** Recording and transcription still write into the draft, so sending it then would split the dictation. */
+function dictationHoldsDraft(dictation: ComposerNativeState["dictation"]): boolean {
+	return dictation === "recording" || dictation === "transcribing";
+}
+
 /** The composer's controls around the input, rebuilt when what they show changes; the bar adds the rate and facts. */
 interface ComposerControls {
 	readonly focus: NativeNode | undefined;
 	readonly mode: NativeNode | undefined;
 	readonly model: NativeNode | undefined;
 	readonly effort: NativeNode | undefined;
+	readonly dictation: NativeNode | undefined;
 	readonly submit: NativeNode;
 }
 
@@ -453,6 +462,8 @@ export type ComposerChipDescriptor =
  */
 export class CustomEditor extends Editor {
 	#spelling = new MacOSSpellingProvider();
+	/** The word being typed: its typo mark waits until the caret leaves it. */
+	#typing = new TypingWordTracker();
 	#wordCompletion = new WordCompletionProvider();
 	imageLinks?: readonly (string | undefined)[];
 
@@ -857,6 +868,9 @@ export class CustomEditor extends Editor {
 		}
 		// One string instance per revision: whole-buffer memos downstream hit on identity.
 		const editorText = this.#decorationText;
+		const caret = this.getCursor();
+		this.#typing.update(this.textRevision, this.#decorationLines, caret.line, caret.col, this.focused);
+		const typing = this.#typing.word;
 		const animated = this.focused && this.#shimmerEnabled() && hasMagicKeyword(editorText);
 		const phase = animated ? (Date.now() % CustomEditor.SHIMMER_PERIOD_MS) / CustomEditor.SHIMMER_PERIOD_MS : 0;
 		if (animated) this.#scheduleShimmerFrame();
@@ -879,6 +893,7 @@ export class CustomEditor extends Editor {
 							lines: this.#decorationLines,
 							line: context.line,
 							startCol: context.startCol + sourceOffset,
+							typing,
 						},
 						span => highlightMagicKeywords(span, undefined, phase),
 					);
@@ -926,6 +941,15 @@ export class CustomEditor extends Editor {
 		);
 	};
 
+	/** Catch the typed word up with the caret first: its leaving the word (or a blur) re-describes the typo marks. */
+	override describe(cx: DescribeContext): NativeNode {
+		const caret = this.getCursor();
+		if (this.#typing.update(this.textRevision, this.getLines(), caret.line, caret.col, this.focused)) {
+			this.invalidate();
+		}
+		return super.describe(cx);
+	}
+
 	/**
 	 * TSP decorations: magic keywords shimmer (terminal-clocked) in the accent
 	 * color, chips and markers take their token colors, misspellings are marked,
@@ -966,6 +990,7 @@ export class CustomEditor extends Editor {
 
 		const queueBody = parseQueueShorthand(text);
 		const queueList = queueBody !== undefined && isQueuedMessageList(queueBody);
+		const typing = this.#typing.word;
 		let lineStart = 0;
 		for (let line = 0; line < lines.length; line++) {
 			const value = lines[line] ?? "";
@@ -979,7 +1004,8 @@ export class CustomEditor extends Editor {
 					decor.push({ from: lineStart + indent, to: lineStart + marker[0].length, s: "accent" });
 				}
 			}
-			for (const typo of this.#spelling.typoRanges(value, { editorText: text, lines, line, startCol: 0 })) {
+			const context = { editorText: text, lines, line, startCol: 0, typing };
+			for (const typo of this.#spelling.typoRanges(value, context)) {
 				decor.push({ from: lineStart + typo.start, to: lineStart + typo.start + typo.length, s: "typo" });
 			}
 			lineStart += value.length + 1;
@@ -1034,9 +1060,10 @@ export class CustomEditor extends Editor {
 		}, CustomEditor.SHIMMER_FRAME_MS);
 		this.#shimmerTimer.unref?.();
 	}
-	/** Editing is available during bootstrap; atomic sends wait until submission is wired and enabled. */
+	/** Editing is available during bootstrap; atomic sends wait until submission is wired and enabled
+	 *  and no dictation is still writing into the draft. */
 	protected override get nativeSendable(): boolean {
-		return this.onSubmit !== undefined && !this.disableSubmit;
+		return this.onSubmit !== undefined && !this.disableSubmit && !dictationHoldsDraft(this.composerState().dictation);
 	}
 	/** The quoted-title placeholder, kept while the title stands so the editor node stays reused. */
 	#titlePlaceholder: { title: string; text: TspText } | undefined;
@@ -1078,9 +1105,9 @@ export class CustomEditor extends Editor {
 	 * subagent is focused, the attachment chips, a `line` row of the
 	 * shell-mode chip and the input, and the `bar`: model chip, effort chip
 	 * (or the effort glyph as the model chip's icon), the generation rate,
-	 * the other status facts, usage, then send (Stop while a turn runs).
-	 * Clicks come back as `status.model`, `thinking.cycle`, `submit`,
-	 * `interrupt` and `focus:<id>` actions.
+	 * the other status facts, usage, dictation, then send (Stop while a turn runs).
+	 * Clicks come back as `status.model`, `thinking.cycle`, `dictation.toggle`,
+	 * `submit`, `interrupt` and `focus:<id>` actions.
 	 */
 	override describeLayout = (input: NativeNode, cx: DescribeContext): NativeEditorLayout => {
 		const effortGlyph = cx.supports("effort");
@@ -1095,6 +1122,7 @@ export class CustomEditor extends Editor {
 			shell?.excluded,
 			state.thinking,
 			state.running,
+			state.dictation,
 			thinkingKey,
 			modelKey,
 			interruptKey,
@@ -1138,6 +1166,7 @@ export class CustomEditor extends Editor {
 								// The status facts are the bar's flexible space; without them a spacer keeps send at the end.
 								facts?.extras ?? node("row", { grow: 1 }, [], "gap"),
 								facts?.usage,
+								controls.dictation,
 								controls.submit,
 							]),
 							{ role: "zeta.composer.bar", gap: "sm", align: "center" },
@@ -1289,6 +1318,38 @@ export class CustomEditor extends Editor {
 						"effort",
 					)
 				: undefined;
+		const recording = state.dictation === "recording";
+		const starting = state.dictation === "starting";
+		const transcribing = state.dictation === "transcribing";
+		const dictation =
+			state.dictation === undefined
+				? undefined
+				: node(
+						"row",
+						{
+							role: "zeta.composer.dictation",
+							gap: "xs",
+							align: "center",
+							tone: recording ? "error" : starting || transcribing ? "pending" : undefined,
+							title: recording
+								? "Stop recording and transcribe"
+								: starting
+									? "Cancel dictation"
+									: transcribing
+										? "Transcribing dictation"
+										: "Start dictation",
+							// The model can take a while to load on first use, so a start stays cancellable.
+							actions: transcribing ? undefined : { click: "dictation.toggle" },
+						},
+						starting || transcribing
+							? [node("spinner", { label: starting ? "Starting…" : "Transcribing…" }, undefined, "pending")]
+							: compact([
+									node("icon", { name: recording ? "stop" : "mic" }, undefined, "icon"),
+									recording && node("text", { text: "Recording · Stop", wrap: "none" }, undefined, "label"),
+								]),
+						"dictation",
+					);
+		const dictating = dictationHoldsDraft(state.dictation);
 		const submit = state.running
 			? node(
 					"text",
@@ -1307,13 +1368,14 @@ export class CustomEditor extends Editor {
 					{
 						role: "zeta.composer.send",
 						keys: ["enter"],
-						title: `Send  ${formatTooltipKey("enter")}`,
-						actions: { click: "submit" },
+						title: dictating ? "Finish dictation before sending" : `Send  ${formatTooltipKey("enter")}`,
+						tone: dictating ? "muted" : undefined,
+						actions: dictating ? undefined : { click: "submit" },
 					},
 					undefined,
 					"send",
 				);
-		if (!shell) return { focus, mode: undefined, model, effort, submit };
+		if (!shell) return { focus, mode: undefined, model, effort, dictation, submit };
 		const runs = shell.kind === "bash" ? "Runs in your shell" : "Runs in Python";
 		const mode = keyed(
 			row(
@@ -1336,15 +1398,15 @@ export class CustomEditor extends Editor {
 			),
 			"mode",
 		);
-		return { focus, mode, model, effort, submit };
+		return { focus, mode, model, effort, dictation, submit };
 	}
 
 	/**
-	 * Clicks on the composer's controls take the same paths as their keys: ⇧⇥,
-	 * ⏎ and Esc; the viewing header's links (`focus:<id>`) go to the host,
-	 * the status facts' clicks (`status.*`) to their source. Selection edits
-	 * go to the buffer; `send` submits its own prompt after saving the old draft
-	 * for recall and waiting for in-flight clipboard work.
+	 * Dictation clicks go directly to the host, independent of keybindings.
+	 * Other controls take the same paths as their keys; the viewing header's
+	 * links (`focus:<id>`) go to the host, the status facts' clicks to their source.
+	 * Selection edits go to the buffer; `send` submits its own prompt after
+	 * saving the old draft for recall and waiting for in-flight clipboard work.
 	 */
 	override handleNativeEvent(event: NativeUiEvent): void {
 		if (event.type === "send") {
@@ -1368,8 +1430,13 @@ export class CustomEditor extends Editor {
 			case "thinking.cycle":
 				this.onCycleThinkingLevel?.();
 				return;
+			case "dictation.toggle": {
+				const { dictation } = this.composerState();
+				if (dictation !== undefined && dictation !== "transcribing") this.onToggleDictation?.();
+				return;
+			}
 			case "submit":
-				this.submit();
+				if (this.nativeSendable) this.submit();
 				return;
 			case "interrupt":
 				this.onEscape?.();
@@ -1404,6 +1471,8 @@ export class CustomEditor extends Editor {
 	onRetry?: () => void;
 	/** Called when Caps Lock is pressed. */
 	onCapsLock?: () => void;
+	/** Called directly by the native microphone/stop control, without synthesizing a keypress. */
+	onToggleDictation?: () => void;
 	/** Called when left-arrow is pressed while the editor is empty (cursor necessarily at start). */
 	onLeftAtStart?: () => void;
 	/** Called when the viewing header asks to view agent `id` ({@link MAIN_AGENT_ID}: the main session). */
@@ -1436,8 +1505,9 @@ export class CustomEditor extends Editor {
 	 *  `pendingImages` (Codex PR #3602 review). */
 	#pasteInFlight = 0;
 	/** Input chunks and explicit prompts deferred behind an in-flight paste,
-	 *  drained in FIFO order once the paste count returns to zero. */
-	#pendingInput: (string | Extract<NativeUiEvent, { type: "send" }>)[] = [];
+	 *  drained in FIFO order once the paste count returns to zero. A `draft` chunk
+	 *  arrived through {@link handleDraftEdit} and drains back through it. */
+	#pendingInput: (string | { draft: string } | Extract<NativeUiEvent, { type: "send" }>)[] = [];
 	#actionKeys = new Map<ConfigurableEditorAction, KeyId[]>(
 		Object.entries(DEFAULT_ACTION_KEYS).map(([action, keys]) => [action as ConfigurableEditorAction, [...keys]]),
 	);
@@ -1516,6 +1586,7 @@ export class CustomEditor extends Editor {
 		const drained = this.#pendingInput.splice(0);
 		for (const input of drained) {
 			if (typeof input === "string") this.handleInput(input);
+			else if ("draft" in input) this.handleDraftEdit(input.draft);
 			else this.handleNativeEvent(input);
 		}
 	}
@@ -1530,6 +1601,11 @@ export class CustomEditor extends Editor {
 		void promise.then(this.#onPasteSettled, this.#onPasteSettled);
 	}
 
+	/** True while a clipboard-image or image-path paste is still landing; later keys queue behind it. */
+	get pasteInFlight(): boolean {
+		return this.#pasteInFlight > 0;
+	}
+
 	capturesInput(data: string): boolean {
 		return this.spaceHold.shouldRoute(data);
 	}
@@ -1550,56 +1626,21 @@ export class CustomEditor extends Editor {
 			this.onCapsLock();
 			return;
 		}
-
-		// Bracketed-paste assembly. Some terminals fragment the start marker,
-		// the payload, and the end marker across separate stdin chunks
-		// (Windows Terminal under heavy load, certain SSH muxes, …); the
-		// inherited handler then sees a zero-length payload and silently
-		// drops it through the normal text-insert path. Running our own
-		// `BracketedPasteHandler` ahead of `super.handleInput` lets us route
-		// the assembled content regardless of chunk boundaries:
-		//  - empty payload → `onPasteImage` (#3601: `Cmd+V`/`Ctrl+V` on an
-		//    image-only macOS pasteboard the terminal stripped to `""` first);
-		//  - explicit image-file paths → `onPasteImagePath` (#3506);
-		//  - anything else → the base editor's `pasteText` so `[Paste #N]`
-		//    markers, autocomplete, and undo state stay intact.
-		const paste = this.#pasteHandler.process(data);
-		if (paste.handled) {
-			if (paste.pasteContent === undefined) return; // still buffering — wait for end marker
-			const content = paste.pasteContent;
-			const remaining = paste.remaining;
-			// Queue any trailing bytes from the same read (typically a follow-up keystroke such as
-			// Enter that the user pressed right after Cmd+V) so they only fire *after* the paste
-			// completes — fixes the race where submit runs against an empty `pendingImages`.
-			if (remaining.length > 0) this.#pendingInput.push(remaining);
-			if (content.length === 0 && this.onPasteImage) {
-				this.#trackAsyncPaste(Promise.resolve(this.onPasteImage()));
-				return;
-			}
-			const attachmentPaths = extractImagePastePathsFromText(content);
-			if (attachmentPaths && this.onPasteImagePath) {
-				this.#trackAsyncPaste(
-					(async () => {
-						for (const p of attachmentPaths) await this.onPasteImagePath?.(p);
-					})(),
-				);
-				return;
-			}
-			// A submit key that shared the read (see `StdinBuffer`'s paste event) is
-			// about to be drained below, so a large-paste host must stage the paste
-			// synchronously instead of opening a menu the submit would land in.
-			if (this.#isSubmitKey(remaining)) this.pasteText(content, { submitAfterPaste: true });
-			else this.pasteText(content);
-			this.#collapseSkillTokens();
-			this.#collapseModelMentions();
-			// No async paste was started; drain the queued trailing bytes ourselves.
-			this.#drainPendingInput();
-			return;
-		}
+		if (this.#routeBracketedPaste(data, false)) return;
 
 		const parsedKey = parseKey(data);
 		const canonical = parsedKey !== undefined ? canonicalKeyId(parsedKey) : undefined;
 
+		// Enter matches the disabled Send button while dictation still writes into the draft;
+		// dictation's own submit trigger goes through submit(), not this key path.
+		if (
+			canonical !== undefined &&
+			getKeybindings().matchesCanonical(canonical, "tui.input.submit") &&
+			dictationHoldsDraft(this.composerState().dictation)
+		) {
+			return;
+		}
+
 		// Space-hold push-to-talk runs before editor shortcuts so a reserved binding can never
 		// delete, move, submit, or invoke an app action while the gesture is enabled.
 		const spaceHoldText = getSpaceHoldText(data, canonical);
@@ -1828,6 +1869,57 @@ export class CustomEditor extends Editor {
 		this.#normalizeQueuePrefix(hadBareQueuePrefix);
 	}
 
+	/**
+	 * Bracketed-paste assembly. Some terminals fragment the start marker,
+	 * the payload, and the end marker across separate stdin chunks
+	 * (Windows Terminal under heavy load, certain SSH muxes, …); the
+	 * inherited handler then sees a zero-length payload and silently
+	 * drops it through the normal text-insert path. Running our own
+	 * `BracketedPasteHandler` ahead of `super.handleInput` lets us route
+	 * the assembled content regardless of chunk boundaries:
+	 *  - empty payload → `onPasteImage` (#3601: `Cmd+V`/`Ctrl+V` on an
+	 *    image-only macOS pasteboard the terminal stripped to `""` first);
+	 *  - explicit image-file paths → `onPasteImagePath` (#3506);
+	 *  - anything else → the base editor's `pasteText` so `[Paste #N]`
+	 *    markers, autocomplete, and undo state stay intact.
+	 * True when `data` was consumed. `draft` queues trailing bytes back through
+	 * {@link handleDraftEdit} instead of {@link handleInput}.
+	 */
+	#routeBracketedPaste(data: string, draft: boolean): boolean {
+		const paste = this.#pasteHandler.process(data);
+		if (!paste.handled) return false;
+		if (paste.pasteContent === undefined) return true; // still buffering — wait for end marker
+		const content = paste.pasteContent;
+		const remaining = paste.remaining;
+		// Queue any trailing bytes from the same read (typically a follow-up keystroke such as
+		// Enter that the user pressed right after Cmd+V) so they only fire *after* the paste
+		// completes — fixes the race where submit runs against an empty `pendingImages`.
+		if (remaining.length > 0) this.#pendingInput.push(draft ? { draft: remaining } : remaining);
+		if (content.length === 0 && this.onPasteImage) {
+			this.#trackAsyncPaste(Promise.resolve(this.onPasteImage()));
+			return true;
+		}
+		const attachmentPaths = extractImagePastePathsFromText(content);
+		if (attachmentPaths && this.onPasteImagePath) {
+			this.#trackAsyncPaste(
+				(async () => {
+					for (const p of attachmentPaths) await this.onPasteImagePath?.(p);
+				})(),
+			);
+			return true;
+		}
+		// A submit key that shared the read (see `StdinBuffer`'s paste event) is
+		// about to be drained below, so a large-paste host must stage the paste
+		// synchronously instead of opening a menu the submit would land in.
+		if (this.#isSubmitKey(remaining)) this.pasteText(content, { submitAfterPaste: true });
+		else this.pasteText(content);
+		this.#collapseSkillTokens();
+		this.#collapseModelMentions();
+		// No async paste was started; drain the queued trailing bytes ourselves.
+		this.#drainPendingInput();
+		return true;
+	}
+
 	/** Promote a newly formed bare `->` / `=>` prefix to a reserved header line by opening the
 	 *  queue body beneath it. `hadBareQueuePrefix` is the pre-edit state: a prompt that was
 	 *  already just the prefix is left alone so the user can keep editing it. */
@@ -1846,9 +1938,16 @@ export class CustomEditor extends Editor {
 	 * an Ask dialog opened over a non-empty prompt — so finishing or submitting
 	 * the draft cannot fire an editor-slot shortcut that clears
 	 * `editorContainer` and orphans the overlay. Only text editing, cursor
-	 * movement, submission, and the clear action reach the buffer.
+	 * movement, submission, the clear action, and pastes (clipboard images and
+	 * image paths attach as on the composer) reach the buffer.
 	 */
 	handleDraftEdit(data: string): void {
+		// Same serialization as handleInput: keys typed behind an image paste wait for it.
+		if (this.#pasteInFlight > 0) {
+			this.#pendingInput.push({ draft: data });
+			return;
+		}
+		if (this.#routeBracketedPaste(data, true)) return;
 		// The base editor reserves Ctrl+C for parent handling and returns without
 		// touching the buffer, so the configured clear action must be dispatched
 		// explicitly here — otherwise the guard's "finish or clear the prompt"
@@ -1862,6 +1961,10 @@ export class CustomEditor extends Editor {
 			else this.setText("");
 			return;
 		}
+		if (canonical !== undefined && this.#matchesAction(canonical, "app.clipboard.pasteImage") && this.onPasteImage) {
+			this.#trackAsyncPaste(Promise.resolve(this.onPasteImage()));
+			return;
+		}
 		this.#forwardInput(data);
 	}
 

package/src/prompt/image-references.d.ts

@@ -1,4 +1,5 @@
 import type { ImageContent } from "@linxiraos/pi-ai";
+import type { TspSpan } from "@linxiraos/pi-wire";
 /** Materialized image destination returned by the host blob writer. */
 interface ImageBlobResult {
     displayPath: string;
@@ -23,4 +24,25 @@ type ImageBlobWriterSync = (data: Buffer, options?: {
 export declare function imageReferenceHyperlink(label: string, index: number, imageLinks: readonly (string | undefined)[] | undefined, renderLabel: (text: string) => string): string;
 export declare function materializeImageReferenceLinks(images: readonly ImageContent[] | undefined, putBlob: ImageBlobWriter): Promise<(string | undefined)[] | undefined>;
 export declare function materializeImageReferenceLinksSync(images: readonly ImageContent[] | undefined, putBlob: ImageBlobWriterSync): (string | undefined)[] | undefined;
+/**
+ * Register the host's blob writer that backs links for images without a file of their
+ * own. Returns a disposer that unregisters it unless another writer replaced it since.
+ */
+export declare function setImageBlobWriter(next: ImageBlobWriterSync): () => void;
+/**
+ * Whether transcript images carry links under the current `tui.hyperlinks` policy: a
+ * native surface honours only an explicit `off`, text mode the resolved OSC 8 support.
+ * Renderers caching a linked image key their cache on it.
+ */
+export declare function imageLinksEnabled(): boolean;
+/**
+ * The file a transcript image opens: `sourcePath` when it was read from one, else a
+ * blob copy of its bytes written through the host. Undefined when links are disabled
+ * or no file exists, so a disabled policy never writes blobs.
+ */
+export declare function transcriptImageLink(image: Pick<ImageContent, "data" | "mimeType">, sourcePath?: string): string | undefined;
+/** `text` (an image's placeholder) as an OSC 8 link to the image's file; plain when hyperlinks are off or no file exists. */
+export declare function linkedImageText(text: string, image: Pick<ImageContent, "data" | "mimeType">, sourcePath?: string): string;
+/** Native counterpart of {@link linkedImageText}: a span linking to the image's file when one exists. */
+export declare function linkedImageSpan(text: string, image: Pick<ImageContent, "data" | "mimeType">, sourcePath: string | undefined, s?: string): TspSpan;
 export {};

package/src/prompt/image-references.ts

@@ -1,13 +1,15 @@
 import type { ImageContent } from "@linxiraos/pi-ai";
 import { logger } from "@linxiraos/pi-utils";
+import type { TspSpan } from "@linxiraos/pi-wire";
+import { span } from "../native/describe";
+import { isNativeRendering } from "../native/state";
+import { fileHyperlink, fileLinkSpan, isHyperlinkEnabled, isNativeLinkEnabled } from "../render/hyperlink";
 import { blobExtensionForImageMimeType } from "./image-format";
 
 /** Materialized image destination returned by the host blob writer. */
 interface ImageBlobResult {
 	displayPath: string;
 }
-import { fileHyperlink } from "../render/hyperlink";
-
 /** Probed pixel dimensions riding on the draft image object itself; `null` records a failed
  *  probe so the chips band never re-decodes a corrupt header every frame. */
 const kImageDims = Symbol("zeta.imageDimensions");
@@ -100,3 +102,78 @@ export function materializeImageReferenceLinksSync(
 	const links = images.map((image, index) => materializeImageReferenceLink(image, index + 1, putBlob));
 	return links.some(link => link !== undefined) ? links : undefined;
 }
+
+let hostBlobWriter: ImageBlobWriterSync | undefined;
+/** Blob paths already written for an image payload, keyed by mime type and content hash. */
+const blobLinks = new Map<string, string>();
+const BLOB_LINK_CACHE_LIMIT = 256;
+
+/**
+ * Register the host's blob writer that backs links for images without a file of their
+ * own. Returns a disposer that unregisters it unless another writer replaced it since.
+ */
+export function setImageBlobWriter(next: ImageBlobWriterSync): () => void {
+	hostBlobWriter = next;
+	blobLinks.clear();
+	return () => {
+		if (hostBlobWriter !== next) return;
+		hostBlobWriter = undefined;
+		blobLinks.clear();
+	};
+}
+
+/**
+ * Whether transcript images carry links under the current `tui.hyperlinks` policy: a
+ * native surface honours only an explicit `off`, text mode the resolved OSC 8 support.
+ * Renderers caching a linked image key their cache on it.
+ */
+export function imageLinksEnabled(): boolean {
+	return isNativeRendering() ? isNativeLinkEnabled() : isHyperlinkEnabled();
+}
+
+/**
+ * The file a transcript image opens: `sourcePath` when it was read from one, else a
+ * blob copy of its bytes written through the host. Undefined when links are disabled
+ * or no file exists, so a disabled policy never writes blobs.
+ */
+export function transcriptImageLink(
+	image: Pick<ImageContent, "data" | "mimeType">,
+	sourcePath?: string,
+): string | undefined {
+	if (!imageLinksEnabled()) return undefined;
+	if (sourcePath) return sourcePath;
+	if (!hostBlobWriter || !image.data) return undefined;
+	const key = `${image.mimeType}:${Bun.hash(image.data)}`;
+	const cached = blobLinks.get(key);
+	if (cached) return cached;
+	const link = materializeImageReferenceLink({ type: "image", ...image }, 1, hostBlobWriter);
+	if (!link) return undefined;
+	if (blobLinks.size >= BLOB_LINK_CACHE_LIMIT) {
+		const oldest = blobLinks.keys().next();
+		if (!oldest.done) blobLinks.delete(oldest.value);
+	}
+	blobLinks.set(key, link);
+	return link;
+}
+
+/** `text` (an image's placeholder) as an OSC 8 link to the image's file; plain when hyperlinks are off or no file exists. */
+export function linkedImageText(
+	text: string,
+	image: Pick<ImageContent, "data" | "mimeType">,
+	sourcePath?: string,
+): string {
+	if (!isHyperlinkEnabled()) return text;
+	const target = transcriptImageLink(image, sourcePath);
+	return target ? fileHyperlink(target, text) : text;
+}
+
+/** Native counterpart of {@link linkedImageText}: a span linking to the image's file when one exists. */
+export function linkedImageSpan(
+	text: string,
+	image: Pick<ImageContent, "data" | "mimeType">,
+	sourcePath: string | undefined,
+	s?: string,
+): TspSpan {
+	const target = transcriptImageLink(image, sourcePath);
+	return target ? fileLinkSpan(target, text, s) : span(text, s);
+}

package/src/prompt/internal-url-autocomplete.ts

@@ -76,6 +76,7 @@ export interface InternalUrlCallerContext {
 	cwd?: string;
 	sessionFile?: string;
 	sessionId?: string;
+	seanceSourceArtifactsDir?: string;
 }
 
 /**

package/src/prompt/macos-spelling.ts

@@ -1,7 +1,7 @@
 import * as native from "@linxiraos/pi-natives";
 import { TERMINAL } from "../index";
 import type { EditorInlineReplacement, EditorTextAssistProvider, EditorWordReplacements } from "../components/editor";
-import { logger } from "@linxiraos/pi-utils";
+import { logger, withTimeout } from "@linxiraos/pi-utils";
 import { isMagicKeyword } from "./magic-keywords";
 import { maskNonProse } from "./markdown-prose";
 import { isProseWord, lineContext, ProseSource, type SpellingDecorationContext } from "./prose-gate";
@@ -45,6 +45,12 @@ const NATIVE_BACKEND: SpellingBackend = {
 	spellingGuesses: (text, start, length) => native.macOSSpellingGuesses(text, start, length),
 };
 
+/**
+ * The native side awaits a `flume::bounded(1)` reply with no timeout, so a stuck call
+ * stays pending and never reaches the `catch` that disables the provider.
+ */
+const BACKEND_TIMEOUT_MS = 2_000;
+
 /**
  * Bridges Apple's spelling service into the editor's typo and autocorrection
  * paths. Word completion is the cross-platform `WordCompletionProvider`
@@ -113,7 +119,8 @@ export class MacOSSpellingProvider implements EditorTextAssistProvider {
 
 	/**
 	 * Misspelled prose ranges in `text` (offsets into it), in order and
-	 * non-overlapping. Schedules the verification check for uncached text; its
+	 * non-overlapping, except ones touching `context.typing` (the word still
+	 * being typed). Schedules the verification check for uncached text; its
 	 * result arrives through {@link onUpdate}.
 	 */
 	typoRanges(text: string, context: SpellingDecorationContext): readonly native.SpellingRange[] {
@@ -131,9 +138,13 @@ export class MacOSSpellingProvider implements EditorTextAssistProvider {
 		const ranges = cached ?? this.#projectTypoRanges(text);
 		if (!ranges || ranges.length === 0) return [];
 		const kept: native.SpellingRange[] = [];
+		const typing = context.typing?.line === context.line ? context.typing : undefined;
 		let cursor = 0;
 		for (const range of ranges) {
 			const end = range.start + range.length;
+			if (typing && context.startCol + range.start <= typing.end && typing.start <= context.startCol + end) {
+				continue;
+			}
 			// Overlapping or out-of-bounds ranges (stale native data, edit projection)
 			// must never re-emit already-rendered text: that doubles it on screen and
 			// desyncs the rendered width from the measured width (cursor drift).
@@ -167,7 +178,11 @@ export class MacOSSpellingProvider implements EditorTextAssistProvider {
 		const context = lineContext(lines, cursorLine);
 		if (!this.#prose.isProse(context, start, start + word.length)) return null;
 		try {
-			const correction = await this.backend.autocorrectWord(textBeforeCursor, start, word.length);
+			const correction = await withTimeout(
+				this.backend.autocorrectWord(textBeforeCursor, start, word.length),
+				BACKEND_TIMEOUT_MS,
+				`macOS spelling service did not respond within ${BACKEND_TIMEOUT_MS}ms`,
+			);
 			if (!correction || correction === word) return null;
 			return { replaceLen: word.length + boundary.length, insert: correction + boundary };
 		} catch (error) {
@@ -200,7 +215,11 @@ export class MacOSSpellingProvider implements EditorTextAssistProvider {
 		try {
 			const seen = new Set<string>();
 			const items: string[] = [];
-			for (const guess of await this.backend.spellingGuesses(line, range.start, range.length)) {
+			for (const guess of await withTimeout(
+				this.backend.spellingGuesses(line, range.start, range.length),
+				BACKEND_TIMEOUT_MS,
+				`macOS spelling service did not respond within ${BACKEND_TIMEOUT_MS}ms`,
+			)) {
 				if (!guess || seen.has(guess)) continue;
 				seen.add(guess);
 				items.push(guess);
@@ -305,7 +324,11 @@ export class MacOSSpellingProvider implements EditorTextAssistProvider {
 	async #fetchTypoRanges(text: string, generation: number): Promise<readonly native.SpellingRange[]> {
 		let checked: readonly native.SpellingRange[];
 		try {
-			checked = await this.backend.checkSpelling(text);
+			checked = await withTimeout(
+				this.backend.checkSpelling(text),
+				BACKEND_TIMEOUT_MS,
+				`macOS spelling service did not respond within ${BACKEND_TIMEOUT_MS}ms`,
+			);
 		} catch (error) {
 			this.#disable(error);
 			return [];

package/src/prompt/prose-gate.ts

@@ -1,4 +1,5 @@
 import { maskNonProse } from "./markdown-prose";
+import type { TypingWord } from "./typing-word";
 
 /**
  * Client-side gates shared by the prose assistants (macOS typo/autocorrect and
@@ -19,6 +20,8 @@ export interface SpellingDecorationContext {
 	lines: readonly string[];
 	line: number;
 	startCol: number;
+	/** The word being typed: typo marks touching it wait until the caret leaves it. */
+	typing?: TypingWord | undefined;
 }
 
 function tokenAt(text: string, start: number, end: number): string {