@linxiraos/pi-tui 1.2.0 → 1.3.0

package/src/components/image.ts

@@ -4,13 +4,15 @@ import {
 	encodeSixelNow,
 	getCellDimensions,
 	getImageDimensions,
+	getTerminalBackgroundColor,
 	type ImageDimensions,
 	ImageProtocol,
 	imageFallback,
 	renderImage,
 	TERMINAL,
 } from "../terminal-capabilities";
-import { nativeImageNode } from "../native/blobs";
+import { nativeImageNode, openableImageProps } from "../native/blobs";
+import { imageLinksEnabled, linkedImageText, transcriptImageLink } from "../prompt/image-references";
 import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 
@@ -22,6 +24,8 @@ export interface ImageOptions {
 	maxWidthCells?: number;
 	maxHeightCells?: number;
 	filename?: string;
+	/** File the image was read from; its link target. Images without one link to a blob copy of their bytes. */
+	sourcePath?: string;
 	/** Shared budget that caps how many inline images render as live graphics. */
 	budget?: ImageBudget;
 	/**
@@ -38,6 +42,13 @@ export interface ImageOptions {
 	requestRender?: () => void;
 }
 
+interface SixelEncode {
+	widthPx: number;
+	heightPx: number;
+	backgroundRgb: number;
+	sequence?: string | null;
+}
+
 /** Renders in progress whose rows are bound for native scrollback. */
 let scrollbackRenderDepth = 0;
 
@@ -652,14 +663,17 @@ export class Image implements Component {
 	#cachedImageProtocol: typeof TERMINAL.imageProtocol = null;
 	#cachedCellWidthPx = 0;
 	#cachedCellHeightPx = 0;
+	#cachedSixelBackground: number | undefined;
 	#cachedKittyUnicodePlaceholders = false;
+	#cachedLinked = false;
 	// Tallest graphic placement this image has rendered. The text fallback
 	// pads itself to this height so a budget demotion never shrinks the block
 	// (its rows may already be committed to native scrollback).
 	#renderedGraphicRows = 0;
-	#native?: NativeNode;
-	/** Newest SIXEL encode: its target size and, once settled, the sequence (`null` on failure). */
-	#sixel?: { widthPx: number; heightPx: number; sequence?: string | null };
+	/** Described node and the link policy it was built under (an `off` switch drops its `href`). */
+	#native?: { linked: boolean; node: NativeNode };
+	/** Newest SIXEL encode: target size, compositing background, and settled sequence. */
+	#sixel?: SixelEncode;
 
 	constructor(
 		base64Data: string,
@@ -699,33 +713,38 @@ export class Image implements Component {
 	}
 
 	/**
-	 * SIXEL sequence for a target size. A new size starts the encode off the JS
+	 * SIXEL sequence for a target size and background. A change starts the encode off the JS
 	 * thread and answers `undefined` until it settles; the settled encode
 	 * invalidates the cached lines and requests a repaint. A render bound for
 	 * scrollback cannot wait, so it encodes synchronously.
 	 */
-	#sixelSequence(widthPx: number, heightPx: number): string | null | undefined {
+	#sixelSequence(widthPx: number, heightPx: number, backgroundRgb: number): string | null | undefined {
 		const current = this.#sixel;
-		const sameSize = current !== undefined && current.widthPx === widthPx && current.heightPx === heightPx;
-		if (sameSize && current.sequence !== undefined) return current.sequence;
+		const sameInput =
+			current !== undefined &&
+			current.widthPx === widthPx &&
+			current.heightPx === heightPx &&
+			current.backgroundRgb === backgroundRgb;
+		if (sameInput && current.sequence !== undefined) return current.sequence;
 		if (scrollbackRenderDepth > 0) {
 			// Replacing the entry makes a still-pending async encode settle as stale.
-			const sequence = encodeSixelNow(this.#base64Data, widthPx, heightPx);
-			this.#sixel = { widthPx, heightPx, sequence };
+			const sequence = encodeSixelNow(this.#base64Data, widthPx, heightPx, backgroundRgb);
+			this.#sixel = { widthPx, heightPx, backgroundRgb, sequence };
 			return sequence;
 		}
-		if (sameSize) return undefined;
-		const request: { widthPx: number; heightPx: number; sequence?: string | null } = { widthPx, heightPx };
+		if (sameInput) return undefined;
+		const request: SixelEncode = { widthPx, heightPx, backgroundRgb };
 		this.#sixel = request;
 		const settle = (sequence: string | null): void => {
 			request.sequence = sequence;
-			if (this.#sixel !== request) return;
+			if (this.#sixel !== request || getTerminalBackgroundColor() !== backgroundRgb) return;
 			this.invalidate();
 			if (this.#options.requestRender) this.#options.requestRender();
 			else this.#budget?.requestRender();
 		};
-		encodeSixelAsync(new Uint8Array(Buffer.from(this.#base64Data, "base64")), widthPx, heightPx).then(settle, () =>
-			settle(null),
+		encodeSixelAsync(new Uint8Array(Buffer.from(this.#base64Data, "base64")), widthPx, heightPx, backgroundRgb).then(
+			settle,
+			() => settle(null),
 		);
 		return undefined;
 	}
@@ -736,10 +755,12 @@ export class Image implements Component {
 	 * graphics protocols do not apply.
 	 */
 	describe(_cx: DescribeContext): NativeNode {
-		if (this.#native) return this.#native;
+		const linked = imageLinksEnabled();
+		if (this.#native?.linked === linked) return this.#native.node;
 		const maxW = this.#options.maxWidthCells;
 		const maxH = this.#options.maxHeightCells;
-		this.#native = nativeImageNode(Buffer.from(this.#base64Data, "base64"), this.#mimeType, {
+		const href = transcriptImageLink({ data: this.#base64Data, mimeType: this.#mimeType }, this.#options.sourcePath);
+		const node = nativeImageNode(Buffer.from(this.#base64Data, "base64"), this.#mimeType, {
 			alt: imageFallback(this.#mimeType, this.#dimensions, this.#options.filename),
 			w: this.#dimensions.widthPx,
 			h: this.#dimensions.heightPx,
@@ -750,8 +771,10 @@ export class Image implements Component {
 							h: maxH && maxH > 0 ? `${maxH}lines` : undefined,
 						}
 					: undefined,
+			...openableImageProps(href),
 		});
-		return this.#native;
+		this.#native = { linked, node };
+		return node;
 	}
 
 	render(width: number): readonly string[] {
@@ -759,6 +782,7 @@ export class Image implements Component {
 		const hasProtocol = imageProtocol != null;
 		const cellDimensions = getCellDimensions();
 		const kittyUnicodePlaceholders = getKittyGraphics().unicodePlaceholders;
+		const sixelBackground = imageProtocol === ImageProtocol.Sixel ? getTerminalBackgroundColor() : undefined;
 		// observe() must run on every pass — even a cache hit — so the image keeps
 		// its display-order slot in the budget. Only graphics-capable frames count
 		// toward (and are demoted by) the budget; without a protocol every image is
@@ -771,6 +795,7 @@ export class Image implements Component {
 		// re-encode the full image on every render pass.
 		const imageId = this.#imageId;
 		const transmitsSeparately = imageProtocol === ImageProtocol.Kitty && imageId != null;
+		const linked = imageLinksEnabled();
 
 		if (
 			this.#cachedLines &&
@@ -779,7 +804,10 @@ export class Image implements Component {
 			this.#cachedImageProtocol === imageProtocol &&
 			this.#cachedCellWidthPx === cellDimensions.widthPx &&
 			this.#cachedCellHeightPx === cellDimensions.heightPx &&
+			this.#cachedSixelBackground === sixelBackground &&
 			this.#cachedKittyUnicodePlaceholders === kittyUnicodePlaceholders &&
+			// The text fallback embeds a link only under an enabled hyperlink policy.
+			this.#cachedLinked === linked &&
 			(!transmitsSeparately || this.#budget?.shouldTransmit(imageId) !== true) &&
 			// Cached rows reserved for a pending SIXEL encode must not reach scrollback.
 			!(scrollbackRenderDepth > 0 && this.#sixel !== undefined && this.#sixel.sequence === undefined)
@@ -801,7 +829,7 @@ export class Image implements Component {
 				maxHeightCells: this.#options.maxHeightCells,
 				imageId: this.#imageId,
 				includeTransmit: needsTransmit,
-				sixel: (widthPx, heightPx) => this.#sixelSequence(widthPx, heightPx),
+				sixel: (widthPx, heightPx) => this.#sixelSequence(widthPx, heightPx, sixelBackground!),
 			});
 
 			if (result?.transmit && this.#imageId != null && this.#budget !== undefined) {
@@ -849,7 +877,9 @@ export class Image implements Component {
 		this.#cachedImageProtocol = imageProtocol;
 		this.#cachedCellWidthPx = cellDimensions.widthPx;
 		this.#cachedCellHeightPx = cellDimensions.heightPx;
+		this.#cachedSixelBackground = sixelBackground;
 		this.#cachedKittyUnicodePlaceholders = kittyUnicodePlaceholders;
+		this.#cachedLinked = linked;
 
 		return lines;
 	}
@@ -864,7 +894,11 @@ export class Image implements Component {
 	 */
 	#fallbackLines(): string[] {
 		const fallback = this.#theme.fallbackColor(
-			imageFallback(this.#mimeType, this.#dimensions, this.#options.filename),
+			linkedImageText(
+				imageFallback(this.#mimeType, this.#dimensions, this.#options.filename),
+				{ data: this.#base64Data, mimeType: this.#mimeType },
+				this.#options.sourcePath,
+			),
 		);
 		if (this.#renderedGraphicRows <= 1) return [fallback];
 		const lines: string[] = [];

package/src/components/markdown.d.ts

@@ -2,6 +2,51 @@ import { type TokensList } from "@linxiraos/pi-utils/marked";
 import type { DescribeContext, NativeNode } from "../native/node";
 import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
+/**
+ * `text` as the streaming renderer lexes it: OSC 8 terminators unified and
+ * tabs expanded. {@link Markdown.getLastRenderStableText} is a prefix of this
+ * form, not of the raw source, so append-only publishers that mix settled
+ * prefixes with whole blocks must compare both in this form. Rendering it is
+ * byte-identical to rendering `text`.
+ */
+export declare function streamingMarkdownSource(text: string): string;
+/**
+ * Streaming `md` source for a native terminal, minus a still-growing table row:
+ * the unterminated last line when a GFM table (a run of pipe lines holding a
+ * header and its delimiter row, outer pipes optional) sits right above it,
+ * outside any open code fence. GFM continues a table on any non-blank line, so
+ * that line is a row whatever it holds so far. The terminal sizes columns by
+ * every row it gets, so a half-streamed row (an unclosed link shows its whole
+ * URL) would rewrap the table each frame, and TSP cannot ask it to skip one.
+ * The result keeps the newline before the held line, so it is a prefix of
+ * `text` and of the result for every append to it: streaming stays
+ * append-only. Pass untrimmed source: trimming first drops the newline that
+ * marks the last row finished, so that row would be held too.
+ */
+export declare function holdPartialTableRow(text: string): string;
+/**
+ * `text`, one inline run whose end is still streaming, with a trailing open
+ * link or math span closed the way the finished text most likely closes it,
+ * or `undefined` when nothing at its end is open. A link gains its missing
+ * `)` (one per open parenthesis in its destination), so it renders as the
+ * link it becomes instead of literal brackets and URL. A math body is cut back
+ * to its last valid form (a half-typed command, dangling `^`/`_`, or the first
+ * `$` of a `$$` closer dropped, open braces closed) and closed, so the
+ * rendered math grows in place instead of raw LaTeX turning into symbols at
+ * the closer. A `$` body needs a LaTeX character, so a price (`$5 per`) is
+ * never speculated. Only prose is: escaped openers and anything inside a code
+ * span, closed or still being written, stay literal.
+ */
+export declare function speculativeInlineClose(text: string): string | undefined;
+/**
+ * Streaming `md` source for a native terminal with the open link or math span
+ * at its end speculatively closed ({@link speculativeInlineClose}), as the TUI
+ * renders it. Only the last block is read (a span cannot cross a blank line),
+ * and source inside an open code fence is left as it is. Each frame rewrites
+ * only the guessed closers at the end, which the reconciler sends as a small
+ * `splice`.
+ */
+export declare function speculativeStreamingSource(text: string): string;
 /** @internal exported for tests — the grown-line block-kind gate. */
 export declare function fastLineStartHazard(grownLine: string): boolean;
 /**
@@ -140,9 +185,10 @@ export declare class Markdown implements Component {
      */
     describe(_cx: DescribeContext): NativeNode;
     /**
-     * Width-independent source prefix of the last render ending at a frozen
-     * Markdown block boundary that no append can move: it stops in front of a
-     * display-math opener whose block an append could still close. Only
+     * Width-independent source prefix of the last render that no append can
+     * change: up to a frozen Markdown block boundary, stopping in front of a
+     * display-math opener whose block an append could still close, or, while a
+     * list streams as the last block, up to its newest top-level item. Only
      * meaningful while streaming (transient render cache on); grows
      * monotonically under append-only `setText`.
      */