@linxiraos/pi-tui 1.1.27 → 1.2.0

package/src/components/image.d.ts

@@ -29,6 +29,8 @@ export interface ImageOptions {
  * synchronously instead of committing its reserved blank rows.
  */
 export declare function renderForScrollback<T>(render: () => T): T;
+/** Widest an {@link Image} rendered at `width` columns draws; callers sizing a raster for it (`SvgFigure`) match it. */
+export declare function imageMaxColumns(width: number): number;
 /** Default count of inline images kept as live graphics before older ones fall back to text. */
 export declare const DEFAULT_MAX_INLINE_IMAGES = 8;
 /**
@@ -73,6 +75,13 @@ export declare class ImageBudget {
      * gets a fresh id every call.
      */
     acquireId(key?: string): number;
+    /**
+     * Retire the graphic held under `key` as soon as no frame shows it, instead
+     * of when the residency sweep reaches it. For an owner that replaced the
+     * image for good — a streaming SVG figure's earlier raster — so superseded
+     * revisions never push older images (scrollback included) out of the store.
+     */
+    release(key: string): void;
     /**
      * Start an alternate-buffer lifecycle. Call once per `?1049h`, before the
      * first pass of the fullscreen overlay or resize borrow that owns the buffer.
@@ -140,50 +149,8 @@ export declare class ImageBudget {
      * the image is purged from the terminal store.
      */
     registerPlacementGeometry(imageId: number, widthPx: number, heightPx: number): void;
-    /**
-     * Record this frame's native-scrollback commit target (the frame-row count
-     * that is committed once the frame's writes land). Called once per rendered
-     * frame — including frames that emit no placements — so an epoch whose rows
-     * commit while its line is never rewritten is still flagged before the next
-     * re-emission.
-     */
-    observeCommitWatermark(committedTo: number): void;
-    /**
-     * End the physical-row coordinate epoch after observing its final commit
-     * watermark. Placement ids and latched archive state survive, but attachment
-     * rows do not: the next placement emit records them in the new-width frame.
-     */
-    beginPlacementCoordinateEpoch(): void;
-    /**
-     * Resolve the placement id and geometry for a direct-placement emit whose
-     * topmost attached cell sits at `attachTopFrameRow` — the first frame row
-     * the placement covers, i.e. the block's first *visible* row, not its
-     * origin (-1 when the writer has no frame-space position: alt-screen,
-     * resize, ConPTY-truncated replays). `committedTo` is this frame's commit
-     * target in the same frame-row space (-1 when unknown).
-     *
-     * Invariant: a placement id may be re-used (Kitty replace strips that id's
-     * cells everywhere, scrollback included) only while none of the cells it
-     * attached have entered native scrollback. The epoch — the `p=` id —
-     * advances exactly when the archived flag says otherwise; rewrites with no
-     * commit progression keep replacing the same id in place.
-     */
-    resolvePlacementEmit(imageId: number, attachTopFrameRow: number, committedTo: number): {
-        placementId: number;
-        widthPx: number;
-        heightPx: number;
-    } | null;
-    /**
-     * Restart every placement epoch after a destructive history clear (`CSI 3 J`
-     * full paint). The clear destroys all placement cells — scrollback rows are
-     * gone and the replay rewrites the viewport — so no archive remains to
-     * protect. Reverting to epoch 1 lets the replay recreate every visible
-     * placement after the terminal-wide cleanup.
-     */
-    resetPlacementEpochs(): ReadonlyArray<{
-        imageId: number;
-        lastEpoch: number;
-    }>;
+    /** Source dimensions used by the frame writer to clip a direct placement. */
+    getPlacementGeometry(imageId: number): ImageDimensions | undefined;
     /**
      * Queue a one-time transmit for `imageId` on the surface the in-flight pass
      * paints. No-op if that surface already holds the data, so a repeated call
@@ -218,6 +185,7 @@ export declare class Image implements Component {
     /** Return source metadata without exposing the encoded image buffer. */
     debugState(): Record<string, unknown>;
     invalidate(): void;
+    releaseRenderCaches(): void;
     /**
      * A native `image` backed by a content-addressed blob; the terminal fits
      * it. Cell caps become `ch`/`lines` bounds. The inline-image budget and

package/src/components/image.ts

@@ -10,8 +10,7 @@ import {
 	renderImage,
 	TERMINAL,
 } from "../terminal-capabilities";
-import { registerNativeBlob } from "../native/blobs";
-import { node } from "../native/describe";
+import { nativeImageNode } from "../native/blobs";
 import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 
@@ -58,35 +57,20 @@ export function renderForScrollback<T>(render: () => T): T {
 
 const EMPTY_IDS: readonly number[] = [];
 const EMPTY_TRANSMITS: readonly string[] = [];
-const EMPTY_STALE_EPOCHS: ReadonlyArray<{ imageId: number; lastEpoch: number }> = [];
 const SAVE_CURSOR = "\x1b7";
 const RESTORE_CURSOR = "\x1b8";
 // Direct placements reserve height with leading zero-width rows. Keep them
 // non-plain so transcript blank-edge trimming does not collapse image-only blocks.
 const RESERVED_IMAGE_ROW = "\x1b[0m";
 
+/** Widest an {@link Image} rendered at `width` columns draws; callers sizing a raster for it (`SvgFigure`) match it. */
+export function imageMaxColumns(width: number): number {
+	return Math.max(1, width - 2);
+}
+
 /** Default count of inline images kept as live graphics before older ones fall back to text. */
 export const DEFAULT_MAX_INLINE_IMAGES = 8;
 
-/** Per-image direct-placement emit state tracked by {@link ImageBudget}. */
-interface PlacementEmitState {
-	widthPx: number;
-	heightPx: number;
-	/** Current placement-id (`p=`) generation. */
-	epoch: number;
-	/** First frame row the current epoch's last emit attached cells to. */
-	lastAttachTopFrameRow: number | undefined;
-	/**
-	 * Whether any cell attached by the current epoch's last emit has entered
-	 * native scrollback. Set by {@link ImageBudget.observeCommitWatermark}
-	 * comparing each frame's raw commit target against the attach top —
-	 * era-local comparisons, so a divergence recommit that rewinds and
-	 * re-advances the ledger is detected the moment it re-crosses the attach
-	 * top, and a stale pre-rewind peak can never re-trigger.
-	 */
-	cellsArchived: boolean;
-}
-
 /** A surface the renderer paints frames on. */
 type Surface = "screen" | "alt";
 const SURFACES: readonly Surface[] = ["screen", "alt"];
@@ -218,22 +202,10 @@ export class ImageBudget {
 	 * fullscreen overlay keeps its placements and is restored from cache on exit.
 	 */
 	#liveIds: Record<Surface, Set<number>> = { screen: new Set(), alt: new Set() };
-	/**
-	 * Per-image direct-placement emit state: source pixel geometry for the
-	 * renderer's clipped source rectangle, plus the placement-id epoch (see
-	 * {@link resolvePlacementEmit}). Entries deliberately live as long as the
-	 * terminal's own placement registry for the image — they are the ledger the
-	 * destructive-clear sweep uses to delete every registry entry an image ever
-	 * placed — and die with it on demotion purge (`d=I`) or full cleanup.
-	 */
-	#placementState = new Map<number, PlacementEmitState>();
-	/**
-	 * States with an un-archived live attach top — the only ones a frame's
-	 * commit watermark can affect. {@link observeCommitWatermark} runs every
-	 * rendered frame, so it scans this set (bounded by concurrently live
-	 * placements) instead of every image ever registered.
-	 */
-	#watchedPlacements = new Set<PlacementEmitState>();
+	/** Source pixel dimensions for clipping direct placements at the viewport edge. */
+	#placementGeometry = new Map<number, ImageDimensions>();
+	/** Ids whose owner replaced them for good ({@link release}); retired once no frame shows them. */
+	#released = new Set<number>();
 
 	constructor(cap: number = DEFAULT_MAX_INLINE_IMAGES, requestRender: () => void = () => {}) {
 		this.#cap = normalizeCap(cap);
@@ -284,6 +256,17 @@ export class ImageBudget {
 		return id;
 	}
 
+	/**
+	 * Retire the graphic held under `key` as soon as no frame shows it, instead
+	 * of when the residency sweep reaches it. For an owner that replaced the
+	 * image for good — a streaming SVG figure's earlier raster — so superseded
+	 * revisions never push older images (scrollback included) out of the store.
+	 */
+	release(key: string): void {
+		const id = this.#keyToId.get(key);
+		if (id !== undefined) this.#released.add(id);
+	}
+
 	/**
 	 * Start an alternate-buffer lifecycle. Call once per `?1049h`, before the
 	 * first pass of the fullscreen overlay or resize borrow that owns the buffer.
@@ -405,6 +388,13 @@ export class ImageBudget {
 			if (this.#passShowsLive(id)) liveIds.add(id);
 		}
 		const transmitted = this.#transmitted[this.#surface];
+		for (const id of this.#released) {
+			// #retire refuses while this pass or the other surface still shows it.
+			if (transmitted.has(id)) this.#retire(id);
+			if (this.#isTransmitted(id)) continue;
+			this.#forgetKeyForId(id);
+			this.#released.delete(id);
+		}
 		if (this.#cap <= 0 || transmitted.size <= this.#cap) return;
 		for (const id of transmitted) {
 			if (transmitted.size <= this.#cap) break;
@@ -456,7 +446,7 @@ export class ImageBudget {
 		// terminal, so cancel it instead of transmitting then purging.
 		if (!this.#pendingTransmits[this.#surface].delete(imageId)) this.#purgeIds.push(imageId);
 		this.#transmitted[this.#surface].delete(imageId);
-		if (!this.#isTransmitted(imageId)) this.#deletePlacementState(imageId);
+		if (!this.#isTransmitted(imageId)) this.#placementGeometry.delete(imageId);
 		this.#forgetKeyForId(imageId);
 		return true;
 	}
@@ -499,8 +489,8 @@ export class ImageBudget {
 		this.#resetPurgeIds = [];
 		this.#keyToId.clear();
 		this.#idToKey.clear();
-		this.#placementState.clear();
-		this.#watchedPlacements.clear();
+		this.#placementGeometry.clear();
+		this.#released.clear();
 		for (const surface of SURFACES) this.#liveIds[surface].clear();
 		return [...ids];
 	}
@@ -516,115 +506,18 @@ export class ImageBudget {
 	 * the image is purged from the terminal store.
 	 */
 	registerPlacementGeometry(imageId: number, widthPx: number, heightPx: number): void {
-		const state = this.#placementState.get(imageId);
-		if (state) {
-			state.widthPx = widthPx;
-			state.heightPx = heightPx;
-			return;
-		}
-		this.#placementState.set(imageId, {
-			widthPx,
-			heightPx,
-			epoch: 1,
-			lastAttachTopFrameRow: undefined,
-			cellsArchived: false,
-		});
-	}
-
-	/**
-	 * Record this frame's native-scrollback commit target (the frame-row count
-	 * that is committed once the frame's writes land). Called once per rendered
-	 * frame — including frames that emit no placements — so an epoch whose rows
-	 * commit while its line is never rewritten is still flagged before the next
-	 * re-emission.
-	 */
-	observeCommitWatermark(committedTo: number): void {
-		if (committedTo < 0 || this.#watchedPlacements.size === 0) return;
-		for (const state of this.#watchedPlacements) {
-			if (state.lastAttachTopFrameRow !== undefined && committedTo > state.lastAttachTopFrameRow) {
-				// Latched: the flag only clears when the next emit consumes it,
-				// so the state needs no further per-frame scans until then.
-				state.cellsArchived = true;
-				this.#watchedPlacements.delete(state);
-			}
-		}
-	}
-
-	/**
-	 * End the physical-row coordinate epoch after observing its final commit
-	 * watermark. Placement ids and latched archive state survive, but attachment
-	 * rows do not: the next placement emit records them in the new-width frame.
-	 */
-	beginPlacementCoordinateEpoch(): void {
-		for (const state of this.#placementState.values()) state.lastAttachTopFrameRow = undefined;
-		this.#watchedPlacements.clear();
-	}
-
-	/**
-	 * Resolve the placement id and geometry for a direct-placement emit whose
-	 * topmost attached cell sits at `attachTopFrameRow` — the first frame row
-	 * the placement covers, i.e. the block's first *visible* row, not its
-	 * origin (-1 when the writer has no frame-space position: alt-screen,
-	 * resize, ConPTY-truncated replays). `committedTo` is this frame's commit
-	 * target in the same frame-row space (-1 when unknown).
-	 *
-	 * Invariant: a placement id may be re-used (Kitty replace strips that id's
-	 * cells everywhere, scrollback included) only while none of the cells it
-	 * attached have entered native scrollback. The epoch — the `p=` id —
-	 * advances exactly when the archived flag says otherwise; rewrites with no
-	 * commit progression keep replacing the same id in place.
-	 */
-	resolvePlacementEmit(
-		imageId: number,
-		attachTopFrameRow: number,
-		committedTo: number,
-	): { placementId: number; widthPx: number; heightPx: number } | null {
-		const state = this.#placementState.get(imageId);
-		if (!state) return null;
-		// Frames that commit as they write (seam/full-paint chunk passes) pass
-		// their own commit target; fold it in before deciding, so a commit that
-		// lands in the same frame as the re-emission still advances the epoch.
-		if (committedTo >= 0 && state.lastAttachTopFrameRow !== undefined && committedTo > state.lastAttachTopFrameRow) {
-			state.cellsArchived = true;
-			this.#watchedPlacements.delete(state);
-		}
-		if (state.cellsArchived) {
-			state.epoch += 1;
-			state.cellsArchived = false;
-			state.lastAttachTopFrameRow = undefined;
-		}
-		if (attachTopFrameRow >= 0) {
-			state.lastAttachTopFrameRow = attachTopFrameRow;
-			this.#watchedPlacements.add(state);
-		}
-		return { placementId: state.epoch, widthPx: state.widthPx, heightPx: state.heightPx };
-	}
-
-	/**
-	 * Restart every placement epoch after a destructive history clear (`CSI 3 J`
-	 * full paint). The clear destroys all placement cells — scrollback rows are
-	 * gone and the replay rewrites the viewport — so no archive remains to
-	 * protect. Reverting to epoch 1 lets the replay recreate every visible
-	 * placement after the terminal-wide cleanup.
-	 */
-	resetPlacementEpochs(): ReadonlyArray<{ imageId: number; lastEpoch: number }> {
-		let stale: Array<{ imageId: number; lastEpoch: number }> | undefined;
-		for (const [imageId, state] of this.#placementState) {
-			stale ??= [];
-			stale.push({ imageId, lastEpoch: state.epoch });
-			state.epoch = 1;
-			state.lastAttachTopFrameRow = undefined;
-			state.cellsArchived = false;
+		const geometry = this.#placementGeometry.get(imageId);
+		if (geometry) {
+			geometry.widthPx = widthPx;
+			geometry.heightPx = heightPx;
+		} else {
+			this.#placementGeometry.set(imageId, { widthPx, heightPx });
 		}
-		this.#watchedPlacements.clear();
-		return stale ?? EMPTY_STALE_EPOCHS;
 	}
 
-	#deletePlacementState(imageId: number): void {
-		const state = this.#placementState.get(imageId);
-		if (!state) return;
-		this.#watchedPlacements.delete(state);
-		this.#placementState.delete(imageId);
+	/** Source dimensions used by the frame writer to clip a direct placement. */
+	getPlacementGeometry(imageId: number): ImageDimensions | undefined {
+		return this.#placementGeometry.get(imageId);
 	}
 
 	/**
@@ -800,6 +693,11 @@ export class Image implements Component {
 		this.#cachedWidth = undefined;
 	}
 
+	releaseRenderCaches(): void {
+		this.#cachedLines = undefined;
+		this.#cachedWidth = undefined;
+	}
+
 	/**
 	 * SIXEL sequence for a target size. A new size starts the encode off the JS
 	 * thread and answers `undefined` until it settles; the settled encode
@@ -839,11 +737,9 @@ export class Image implements Component {
 	 */
 	describe(_cx: DescribeContext): NativeNode {
 		if (this.#native) return this.#native;
-		const blob = registerNativeBlob(Buffer.from(this.#base64Data, "base64"), this.#mimeType);
 		const maxW = this.#options.maxWidthCells;
 		const maxH = this.#options.maxHeightCells;
-		this.#native = node("image", {
-			blob,
+		this.#native = 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,
@@ -892,7 +788,7 @@ export class Image implements Component {
 		}
 
 		const cap = this.#options.maxWidthCells;
-		const maxWidth = cap != null && cap > 0 ? Math.min(width - 2, cap) : width - 2;
+		const maxWidth = cap != null && cap > 0 ? Math.min(imageMaxColumns(width), cap) : imageMaxColumns(width);
 
 		let lines: string[];
 

package/src/components/key-value-list.d.ts

@@ -21,6 +21,7 @@ export declare class KeyValueList implements Component {
     constructor(rows: readonly KeyValueRow[], options: KeyValueListOptions);
     setRows(rows: readonly KeyValueRow[]): boolean;
     invalidate(): void;
+    releaseRenderCaches(): void;
     /** An aligned `kv` grid; label width and value wrapping are the terminal's. */
     describe(_cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];

package/src/components/key-value-list.ts

@@ -54,6 +54,10 @@ export class KeyValueList implements Component {
 		this.#native = undefined;
 	}
 
+	releaseRenderCaches(): void {
+		this.#cache = undefined;
+	}
+
 	/** An aligned `kv` grid; label width and value wrapping are the terminal's. */
 	describe(_cx: DescribeContext): NativeNode {
 		this.#native ??= node("kv", {

package/src/components/layout/row.d.ts

@@ -48,6 +48,7 @@ export declare class Row implements Component, MouseRoutable {
     setDecorations(prefix: LayoutDecoration | undefined, gap: LayoutDecoration | undefined, suffix: LayoutDecoration | undefined): void;
     setIgnoreTight(ignore: boolean): this;
     invalidate(): void;
+    releaseRenderCaches(): void;
     dispose(): void;
     /**
      * A flex `row`: each child sits in a slot carrying its width bounds

package/src/components/layout/row.ts

@@ -168,6 +168,13 @@ export class Row implements Component, MouseRoutable {
 		}
 	}
 
+	releaseRenderCaches(): void {
+		this.#memo = undefined;
+		for (const child of uniqueLayoutComponents(this.#children.map(item => item.content))) {
+			child.releaseRenderCaches?.();
+		}
+	}
+
 	dispose(): void {
 		for (const child of uniqueLayoutComponents(this.#children.map(item => item.content))) {
 			child.dispose?.();

package/src/components/layout/stack.d.ts

@@ -43,6 +43,7 @@ export declare class Stack implements Component, MouseRoutable {
     setHeight(height: number | undefined): void;
     setIgnoreTight(ignore: boolean): this;
     invalidate(): void;
+    releaseRenderCaches(): void;
     dispose(): void;
     /**
      * A `col` of slots carrying each child's height bounds (fixed → min = max

package/src/components/layout/stack.ts

@@ -140,6 +140,13 @@ export class Stack implements Component, MouseRoutable {
 		}
 	}
 
+	releaseRenderCaches(): void {
+		this.#memo = undefined;
+		for (const child of uniqueLayoutComponents(this.#children.map(item => item.content))) {
+			child.releaseRenderCaches?.();
+		}
+	}
+
 	dispose(): void {
 		for (const child of uniqueLayoutComponents(this.#children.map(item => item.content))) {
 			child.dispose?.();

package/src/components/markdown.d.ts

@@ -1,13 +1,27 @@
+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";
 /** @internal exported for tests — the grown-line block-kind gate. */
 export declare function fastLineStartHazard(grownLine: string): boolean;
-/** @internal exported for tests — the windowed lexer's first-probe window size. */
-export declare const LEX_WINDOW_BYTES: number;
+/**
+ * Lex a whole document with the renderer's rules (math, custom rules,
+ * strikethrough). Callers that split a document along its blocks (table
+ * charts) lex through this so they see the blocks Markdown renders.
+ */
+export declare function lexDocument(text: string): TokensList;
+/**
+ * `source` as a fenced code block in `lang`: the fence is one backtick longer
+ * than any backtick run in the source (at least three), so the block always
+ * closes where intended. `open` leaves it unclosed, the source verbatim, for
+ * a body that is still arriving.
+ */
+export declare function fencedCode(lang: string, source: string, options?: {
+    open?: boolean;
+}): string;
 /** A hyperlink as the renderer sees it: inline `[text](href)`, `<autolink>`, bare GFM URL, or reference link. */
 export interface MarkdownLink {
-    /** Visible link text (equals `href` for autolinks and bare URLs). */
+    /** Flattened visible label with whitespace collapsed to one row; falls back to `href` when empty. */
     text: string;
     /** Destination exactly as marked resolved it (references resolved, no normalization). */
     href: string;
@@ -19,6 +33,17 @@ export interface MarkdownLink {
  * Duplicate hrefs are kept; callers decide how to fold them.
  */
 export declare function extractMarkdownLinks(text: string): MarkdownLink[];
+/**
+ * Rewrite the destinations of inline links and link reference definitions in
+ * `text` to `resolve(href)`, leaving everything else byte-for-byte intact.
+ * Hosts that render the Markdown source themselves (a native terminal's `md`
+ * node) resolve relative destinations against their own idea of the working
+ * directory; handing them the session-resolved target keeps links pointing at
+ * what the author meant. Links inside code, images, autolinks and reference
+ * uses (`[x][ref]`, rewritten through their definition) are untouched; a link
+ * whose source cannot be located exactly is left as written.
+ */
+export declare function rewriteMarkdownLinkDestinations(text: string, resolve: (href: string) => string | undefined): string;
 /** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */
 export declare function clearRenderCache(): void;
 /**
@@ -28,6 +53,13 @@ export declare function clearRenderCache(): void;
 export interface DefaultTextStyle {
     /** Foreground color function */
     color?: (text: string) => string;
+    /**
+     * The `color` foreground is prose-level: semantically-themed markdown spans
+     * (headings, links) keep their own `md*` theme colors instead of being
+     * painted over by it, while plain text runs still use `color`. Unset keeps
+     * the historical behavior where `color` paints every run.
+     */
+    proseFg?: boolean;
     /** Background color function */
     bgColor?: (text: string) => string;
     /** Bold text */
@@ -99,6 +131,7 @@ export declare class Markdown implements Component {
     debugState(): Record<string, unknown>;
     setText(text: string): boolean;
     invalidate(): void;
+    releaseRenderCaches(): void;
     /**
      * The unrendered source as an `md` node, `stream` while the streaming
      * (transient) cache is on. Append-only growth yields a fresh node of the