@f5-sales-demo/pi-tui 20.15.3 → 20.16.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/pi-tui",
-	"version": "20.15.3",
+	"version": "20.16.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@f5-sales-demo/pi-natives": "20.15.3",
-		"@f5-sales-demo/pi-utils": "20.15.3",
+		"@f5-sales-demo/pi-natives": "20.16.0",
+		"@f5-sales-demo/pi-utils": "20.16.0",
 		"marked": "^18.0"
 	},
 	"devDependencies": {

package/src/components/image.ts

@@ -15,6 +15,7 @@ export interface ImageOptions {
 	maxWidthCells?: number;
 	maxHeightCells?: number;
 	filename?: string;
+	imageId?: number;
 }
 
 export class Image implements Component {
@@ -60,6 +61,7 @@ export class Image implements Component {
 			const result = renderImage(this.#base64Data, this.#dimensions, {
 				maxWidthCells: maxWidth,
 				maxHeightCells: this.#options.maxHeightCells,
+				imageId: this.#options.imageId,
 			});
 
 			if (result) {

package/src/components/markdown.ts

@@ -1,6 +1,6 @@
 import { marked, type Token, type Tokens } from "marked";
 import type { SymbolTheme } from "../symbols";
-import { TERMINAL } from "../terminal-capabilities";
+import { getImageDimensions, imageFallback, renderImage, stableKittyImageId, TERMINAL } from "../terminal-capabilities";
 import type { Component } from "../tui";
 import {
 	applyBackgroundToLine,
@@ -16,6 +16,21 @@ import {
  * Default text styling for markdown content.
  * Applied to all text unless overridden by markdown formatting.
  */
+export interface ResolvedMarkdownMedia {
+	id: string;
+	data: string;
+	mimeType: string;
+	filename?: string;
+}
+
+export type MarkdownMediaResolver = (request: { source: string; alt: string }) => Promise<ResolvedMarkdownMedia>;
+
+export interface MarkdownMediaOptions {
+	resolve: MarkdownMediaResolver;
+	onInvalidate?: () => void;
+}
+
+/** Default text styling for markdown content. */
 export interface DefaultTextStyle {
 	/** Foreground color function */
 	color?: (text: string) => string;
@@ -74,6 +89,16 @@ type ListToken = Token & { items: Array<{ tokens?: Token[] }>; ordered: boolean;
 type TableCellToken = { tokens?: Token[] };
 type TableToken = Token & { header: TableCellToken[]; rows: TableCellToken[][]; raw?: string };
 
+function isImageToken(token: Token): token is Tokens.Image {
+	return (
+		token.type === "image" &&
+		"href" in token &&
+		typeof token.href === "string" &&
+		"text" in token &&
+		typeof token.text === "string"
+	);
+}
+
 function formatHyperlink(text: string, target: string): string {
 	if (!TERMINAL.hyperlinks || !target) {
 		return text;
@@ -96,6 +121,11 @@ export class Markdown implements Component {
 	#defaultStylePrefix?: string;
 	/** Number of spaces used to indent code block content. */
 	#codeBlockIndent: number;
+	#mediaOptions?: MarkdownMediaOptions;
+	#mediaCache = new Map<
+		string,
+		{ status: "pending" } | { status: "loaded"; media: ResolvedMarkdownMedia } | { status: "error"; message: string }
+	>();
 
 	// Cache for rendered output
 	#cachedText?: string;
@@ -109,6 +139,7 @@ export class Markdown implements Component {
 		theme: MarkdownTheme,
 		defaultTextStyle?: DefaultTextStyle,
 		codeBlockIndent: number = 2,
+		mediaOptions?: MarkdownMediaOptions,
 	) {
 		this.#text = text;
 		this.#paddingX = paddingX;
@@ -116,6 +147,7 @@ export class Markdown implements Component {
 		this.#theme = theme;
 		this.#defaultTextStyle = defaultTextStyle;
 		this.#codeBlockIndent = Math.max(0, Math.floor(codeBlockIndent));
+		this.#mediaOptions = mediaOptions;
 	}
 
 	setText(text: string): void {
@@ -326,8 +358,12 @@ export class Markdown implements Component {
 			}
 
 			case "paragraph": {
-				const paragraphText = this.#renderInlineTokens(token.tokens || [], styleContext);
-				lines.push(paragraphText);
+				const paragraphTokens = token.tokens || [];
+				if (this.#mediaOptions && paragraphTokens.some(child => child.type === "image")) {
+					lines.push(...this.#renderParagraphWithMedia(paragraphTokens, width, styleContext));
+				} else {
+					lines.push(this.#renderInlineTokens(paragraphTokens, styleContext));
+				}
 				// Don't add spacing if next token is space or list
 				if (nextTokenType && nextTokenType !== "list" && nextTokenType !== "space") {
 					lines.push("");
@@ -476,6 +512,75 @@ export class Markdown implements Component {
 		return lines;
 	}
 
+	#renderParagraphWithMedia(tokens: Token[], width: number, styleContext?: InlineStyleContext): string[] {
+		const lines: string[] = [];
+		let inline: Token[] = [];
+		const flushInline = (): void => {
+			if (inline.length === 0) return;
+			const rendered = this.#renderInlineTokens(inline, styleContext);
+			lines.push(...rendered.split("\n"));
+			inline = [];
+		};
+		for (const token of tokens) {
+			if (!isImageToken(token)) {
+				inline.push(token);
+				continue;
+			}
+			flushInline();
+			lines.push(...this.#renderMarkdownMedia(token, width));
+		}
+		flushInline();
+		return lines;
+	}
+
+	#renderMarkdownMedia(token: Tokens.Image, width: number): string[] {
+		const source = token.href;
+		let state = this.#mediaCache.get(source);
+		if (!state) {
+			state = { status: "pending" };
+			this.#mediaCache.set(source, state);
+			void this.#mediaOptions
+				?.resolve({ source, alt: token.text })
+				.then(media => {
+					this.#mediaCache.set(source, { status: "loaded", media });
+				})
+				.catch(error => {
+					this.#mediaCache.set(source, {
+						status: "error",
+						message: error instanceof Error ? error.message : String(error),
+					});
+				})
+				.finally(() => {
+					this.invalidate();
+					this.#mediaOptions?.onInvalidate?.();
+				});
+		}
+		if (state.status === "pending") {
+			return [this.#theme.link(`[Loading media: ${token.text || source}]`)];
+		}
+		if (state.status === "error") {
+			return [this.#theme.linkUrl(`[Media unavailable: ${state.message}]`)];
+		}
+		const dimensions = getImageDimensions(state.media.data, state.media.mimeType) ?? undefined;
+		if (dimensions && TERMINAL.imageProtocol) {
+			const rendered = renderImage(state.media.data, dimensions, {
+				maxWidthCells: Math.max(1, width),
+				imageId: stableKittyImageId(state.media.id),
+			});
+			if (rendered) {
+				const result = Array.from({ length: Math.max(0, rendered.rows - 1) }, () => "");
+				const moveUp = rendered.rows > 1 ? `\x1b[${rendered.rows - 1}A` : "";
+				result.push(moveUp + rendered.sequence);
+				return result;
+			}
+		}
+		return [
+			this.#theme.linkUrl(
+				imageFallback(state.media.mimeType, dimensions, state.media.filename ?? token.text ?? undefined),
+			),
+		];
+	}
+
 	#renderInlineTokens(tokens: Token[], styleContext?: InlineStyleContext): string {
 		let result = "";
 		const resolvedStyleContext = styleContext ?? this.#getDefaultInlineStyleContext();

package/src/index.ts

@@ -49,6 +49,8 @@ export {
 export * from "./keybindings";
 // Kitty keyboard protocol helpers
 export * from "./keys";
+// Media playback state machine
+export * from "./media-playback";
 // Mermaid diagram support
 // Input buffering for batch splitting
 export * from "./stdin-buffer";

package/src/media-playback.ts

@@ -0,0 +1,100 @@
+export type MediaPlaybackState = "stopped" | "playing" | "paused";
+
+export interface MediaPlaybackOptions {
+	autoplay: boolean;
+	loop: boolean;
+	fpsCap: number;
+	reducedMotion: boolean;
+}
+
+export class MediaPlaybackScheduler {
+	readonly #durations: number[];
+	readonly #options: MediaPlaybackOptions;
+	#state: MediaPlaybackState = "stopped";
+	#frameIndex = 0;
+	#lastTick = 0;
+	#visible = false;
+	#autoplayConsumed = false;
+	#resumeWhenVisible = false;
+
+	constructor(frameDurationsMs: number[], options: MediaPlaybackOptions) {
+		if (frameDurationsMs.length === 0) throw new Error("media playback requires at least one frame");
+		if (!Number.isFinite(options.fpsCap) || options.fpsCap < 1) throw new Error("fpsCap must be positive");
+		const minimumDuration = 1000 / Math.min(60, options.fpsCap);
+		this.#durations = frameDurationsMs.map(duration => Math.max(minimumDuration, duration));
+		this.#options = options;
+	}
+
+	get state(): MediaPlaybackState {
+		return this.#state;
+	}
+
+	get frameIndex(): number {
+		return this.#frameIndex;
+	}
+
+	setVisible(visible: boolean, now: number): void {
+		if (visible === this.#visible) return;
+		this.#visible = visible;
+		if (!visible && this.#state === "playing") {
+			this.#resumeWhenVisible = true;
+			this.pause();
+			return;
+		}
+		if (!visible) return;
+		if (this.#resumeWhenVisible) {
+			this.#resumeWhenVisible = false;
+			this.play(now);
+			return;
+		}
+		if (this.#options.autoplay && !this.#options.reducedMotion && !this.#autoplayConsumed) {
+			this.#autoplayConsumed = true;
+			this.play(now);
+		}
+	}
+
+	play(now: number): void {
+		if (this.#frameIndex >= this.#durations.length) this.#frameIndex = 0;
+		this.#lastTick = now;
+		this.#state = "playing";
+	}
+
+	pause(): void {
+		if (this.#state === "playing") this.#state = "paused";
+	}
+
+	stop(): void {
+		this.#state = "stopped";
+		this.#frameIndex = 0;
+		this.#resumeWhenVisible = false;
+		this.#autoplayConsumed = true;
+	}
+
+	tick(now: number): number {
+		if (this.#state !== "playing") return this.#frameIndex;
+		let elapsed = Math.max(0, now - this.#lastTick);
+		while (elapsed >= (this.#durations[this.#frameIndex] ?? Number.POSITIVE_INFINITY)) {
+			const duration = this.#durations[this.#frameIndex] ?? Number.POSITIVE_INFINITY;
+			elapsed -= duration;
+			if (this.#frameIndex + 1 < this.#durations.length) {
+				this.#frameIndex++;
+				this.#lastTick = now - elapsed;
+				continue;
+			}
+			if (this.#options.loop) {
+				this.#frameIndex = 0;
+				this.#lastTick = now - elapsed;
+				continue;
+			}
+			this.#state = "stopped";
+			this.#frameIndex = this.#durations.length - 1;
+			break;
+		}
+		return this.#frameIndex;
+	}
+
+	dispose(): void {
+		this.#state = "stopped";
+		this.#resumeWhenVisible = false;
+	}
+}

package/src/terminal-capabilities.ts

@@ -218,6 +218,7 @@ export interface ImageRenderOptions {
 	maxWidthCells?: number;
 	maxHeightCells?: number;
 	preserveAspectRatio?: boolean;
+	imageId?: number;
 }
 
 // Default cell dimensions - updated by TUI when terminal responds to query
@@ -231,6 +232,21 @@ export function setCellDimensions(dims: CellDimensions): void {
 	cellDimensions = dims;
 }
 
+/** Derive a deterministic Kitty image/placement id from a durable media id. */
+export function stableKittyImageId(mediaId: string): number {
+	let hash = 0x811c9dc5;
+	for (let index = 0; index < mediaId.length; index++) {
+		hash ^= mediaId.charCodeAt(index);
+		hash = Math.imul(hash, 0x01000193);
+	}
+	return ((hash >>> 0) % 2_147_483_646) + 1;
+}
+
+/** Delete a Kitty image and all placements that use its stable id. */
+export function deleteKittyImage(imageId: number): string {
+	return `\x1b_Ga=d,d=I,i=${imageId},q=2;\x1b\\`;
+}
+
 export function encodeKitty(
 	base64Data: string,
 	options: {
@@ -497,6 +513,7 @@ export function renderImage(
 		const sequence = encodeKitty(base64Data, {
 			columns: fit.columns,
 			rows: fit.rows,
+			imageId: options.imageId,
 		});
 		return { sequence, rows: fit.rows };
 	}

package/src/tui.ts

@@ -41,6 +41,9 @@ export interface Component {
 	 * Called when theme changes or when component needs to re-render from scratch.
 	 */
 	invalidate(): void;
+
+	/** Release timers, subprocesses, and terminal placements when removed from a container. */
+	unmount?(): void;
 }
 
 /**
@@ -183,10 +186,12 @@ export class Container implements Component {
 		const index = this.children.indexOf(component);
 		if (index !== -1) {
 			this.children.splice(index, 1);
+			component.unmount?.();
 		}
 	}
 
 	clear(): void {
+		for (const child of this.children) child.unmount?.();
 		this.children = [];
 	}
 
@@ -239,6 +244,8 @@ export class TUI extends Container {
 	#maxLinesRendered = 0; // High-water line count used for clear-on-shrink policy
 	#fullRedrawCount = 0;
 	#stopped = false;
+	#viewportObservers = new Map<number, { callback: (visible: boolean) => void; visible: boolean }>();
+	#nextViewportObserverId = 1;
 
 	// Overlay stack for modal components rendered on top of base content
 	overlayStack: {
@@ -260,6 +267,43 @@ export class TUI extends Container {
 		return this.#fullRedrawCount;
 	}
 
+	registerViewportObserver(callback: (visible: boolean) => void): { marker: string; dispose: () => void } {
+		const id = this.#nextViewportObserverId++;
+		this.#viewportObservers.set(id, { callback, visible: false });
+		return {
+			marker: `\x1b_pi:v=${id}\x07`,
+			dispose: () => {
+				const observer = this.#viewportObservers.get(id);
+				if (observer?.visible) observer.callback(false);
+				this.#viewportObservers.delete(id);
+			},
+		};
+	}
+
+	#updateViewportObservers(lines: string[], height: number): void {
+		if (this.#viewportObservers.size === 0) return;
+		const visibleIds = new Set<number>();
+		const viewportTop = Math.max(0, lines.length - height);
+		const marker = /\x1b_pi:v=(\d+)\x07/gu;
+		for (let index = 0; index < lines.length; index++) {
+			lines[index] = lines[index].replace(marker, (_sequence, rawId: string) => {
+				const id = Number(rawId);
+				if (index >= viewportTop && this.#viewportObservers.has(id)) visibleIds.add(id);
+				return "";
+			});
+		}
+		for (const [id, observer] of this.#viewportObservers) {
+			const visible = visibleIds.has(id);
+			if (visible === observer.visible) continue;
+			observer.visible = visible;
+			try {
+				observer.callback(visible);
+			} catch {
+				// Viewport observers must not break terminal rendering.
+			}
+		}
+	}
+
 	getShowHardwareCursor(): boolean {
 		return this.#showHardwareCursor;
 	}
@@ -1022,6 +1066,7 @@ export class TUI extends Container {
 
 		// Render all components to get new lines
 		let newLines = this.render(width);
+		this.#updateViewportObservers(newLines, height);
 
 		// Clamp any oversized lines before dirty-checking so the truncated form
 		// matches what we store in #previousLines, preventing perpetual repaints.