@swifttui/web 0.4.1 → 0.4.3

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 import { ResolvedWebHostTerminalPalette, ResolvedWebHostTerminalStyle, WebHostANSIColors, WebHostTerminalAppearance, WebHostTerminalCursorStyle, WebHostTerminalPalette, WebHostTerminalRenderStyle, WebHostTerminalStyle, WebHostTerminalTheme, applyWebHostTerminalStyle, decodeWebHostTerminalRenderStyleBase64, encodeWebHostTerminalRenderStyleBase64, mergeWebHostTerminalStyle, normalizeWebHostTerminalStyle, resolveWebHostTerminalRenderStyle, webTUITerminalBackgroundColor } from "./src/WebHostTerminalStyle.js";
-import { SUPPORTED_SURFACE_VERSION, WebHostAccessibilityAnnouncement, WebHostAccessibilityLiveRegion, WebHostAccessibilityNode, WebHostAccessibilityPoint, WebHostFocusPresentation, WebHostFocusSemantics, WebHostFrameDiagnosticRecord, WebHostKeyInput, WebHostMouseInput, WebHostOutputDecoder, WebHostOutputRecord, WebHostOutputSink, WebHostResyncRequest, WebHostRuntimeIssue, WebHostScrollRegion, WebHostSurfaceCell, WebHostSurfaceDamage, WebHostSurfaceDamageRange, WebHostSurfaceDamageTextRow, WebHostSurfaceDeltaFrame, WebHostSurfaceDeltaRow, WebHostSurfaceFrame, WebHostSurfaceImage, WebHostSurfaceImageFormat, WebHostSurfaceLineStyle, WebHostSurfaceLinkRow, WebHostSurfaceLinkRun, WebHostSurfaceRect, WebHostSurfaceSize, WebHostSurfaceStyle, encodeCapabilitiesControlMessage, encodeKeyInputMessage, encodeMouseInputMessage, encodePasteInputMessage, encodeRenderStyleControlMessage, encodeResizeControlMessage, encodeResyncControlMessage } from "./src/WebHostSurfaceTransport.js";
+import { MAX_IMAGE_RECOVERY_ID_BYTES, MAX_OUTSTANDING_IMAGE_RECOVERY_IDS, SUPPORTED_SURFACE_VERSION, WebHostAccessibilityAnnouncement, WebHostAccessibilityLiveRegion, WebHostAccessibilityNode, WebHostAccessibilityPoint, WebHostFocusPresentation, WebHostFocusSemantics, WebHostFrameDiagnosticRecord, WebHostImagePayloadRequestHandler, WebHostKeyInput, WebHostMouseInput, WebHostOutputDecoder, WebHostOutputRecord, WebHostOutputSink, WebHostResyncRequest, WebHostRuntimeIssue, WebHostScrollRegion, WebHostSurfaceCell, WebHostSurfaceDamage, WebHostSurfaceDamageRange, WebHostSurfaceDamageTextRow, WebHostSurfaceDeltaFrame, WebHostSurfaceDeltaRow, WebHostSurfaceFrame, WebHostSurfaceImage, WebHostSurfaceImageFormat, WebHostSurfaceLineStyle, WebHostSurfaceLinkRow, WebHostSurfaceLinkRun, WebHostSurfaceRect, WebHostSurfaceSize, WebHostSurfaceStyle, encodeCapabilitiesControlMessage, encodeKeyInputMessage, encodeMouseInputMessage, encodePasteInputMessage, encodeRenderStyleControlMessage, encodeResizeControlMessage, encodeResyncControlMessage, isWebHostImageRecoveryId } from "./src/WebHostSurfaceTransport.js";
 import { SurfaceMetrics, WebHostSurfacePainter, WebHostSurfaceRendererKind, resolvedSurfaceBackground, resolvedSurfaceForeground } from "./src/SurfaceRenderer.js";
 import { WebHostSceneDescriptor, WebHostSceneManifest, WebHostSceneManifestSource, loadWebHostSceneManifest, normalizeWebHostSceneManifest, webTUISceneManifestFromDescriptors, webTUISceneManifestToJSON } from "./src/WebHostSceneManifest.js";
 import { WebHostSceneBridge, WebHostSceneRuntime, WebHostSceneRuntimeOptions, WheelMode } from "./src/WebHostSceneRuntime.js";
 import { WebSocketSceneBridge, WebSocketSceneBridgeFactory, WebSocketSceneBridgeOptions, WebSocketSceneSocket, webSocketSceneURL } from "./src/WebSocketSceneBridge.js";
 import { WebHostAppController, WebHostAppOptions, WebHostBridgeFactory, WebHostBridgeFactoryOptions, WebHostEmbeddedHostConfig, WebHostVisibilityDocument, createWebHostApp } from "./src/WebHostApp.js";
-import { DomSurfacePainter } from "./src/DomSurfacePainter.js";
+import { DomSurfacePainter, DomSurfacePainterOptions } from "./src/DomSurfacePainter.js";
 import { StdIOPipe } from "./src/wasi/StdIOPipe.js";
 import { JSPIConstructors, WasmEngineCapabilities, WasmEngineFamily, WasmEngineProbeSignals, classifyWasmEngineFamily, collectWasmEngineProbeSignals, jspiConstructors, mainThreadStackProfileEnvironmentDefaults, resolveWasmEngineCapabilities, stackProfileEnvironmentDefaults } from "./src/wasi/WasmEngineCapabilities.js";
 import { BrowserWASIBridge, BrowserWASIBridgeOptions, BrowserWASIOutputSink } from "./src/wasi/BrowserWASIBridge.js";
-export { BrowserWASIBridge, BrowserWASIBridgeOptions, BrowserWASIOutputSink, DomSurfacePainter, JSPIConstructors, ResolvedWebHostTerminalPalette, ResolvedWebHostTerminalStyle, SUPPORTED_SURFACE_VERSION, StdIOPipe, SurfaceMetrics, WasmEngineCapabilities, WasmEngineFamily, WasmEngineProbeSignals, WebHostANSIColors, WebHostAccessibilityAnnouncement, WebHostAccessibilityLiveRegion, WebHostAccessibilityNode, WebHostAccessibilityPoint, WebHostAppController, WebHostAppOptions, WebHostBridgeFactory, WebHostBridgeFactoryOptions, WebHostEmbeddedHostConfig, WebHostFocusPresentation, WebHostFocusSemantics, WebHostFrameDiagnosticRecord, WebHostKeyInput, WebHostMouseInput, WebHostOutputDecoder, WebHostOutputRecord, WebHostOutputSink, WebHostResyncRequest, WebHostRuntimeIssue, WebHostSceneBridge, WebHostSceneDescriptor, WebHostSceneManifest, WebHostSceneManifestSource, WebHostSceneRuntime, WebHostSceneRuntimeOptions, WebHostScrollRegion, WebHostSurfaceCell, WebHostSurfaceDamage, WebHostSurfaceDamageRange, WebHostSurfaceDamageTextRow, WebHostSurfaceDeltaFrame, WebHostSurfaceDeltaRow, WebHostSurfaceFrame, WebHostSurfaceImage, WebHostSurfaceImageFormat, WebHostSurfaceLineStyle, WebHostSurfaceLinkRow, WebHostSurfaceLinkRun, WebHostSurfacePainter, WebHostSurfaceRect, WebHostSurfaceRendererKind, WebHostSurfaceSize, WebHostSurfaceStyle, WebHostTerminalAppearance, WebHostTerminalCursorStyle, WebHostTerminalPalette, WebHostTerminalRenderStyle, WebHostTerminalStyle, WebHostTerminalTheme, WebHostVisibilityDocument, WebSocketSceneBridge, WebSocketSceneBridgeFactory, WebSocketSceneBridgeOptions, WebSocketSceneSocket, WheelMode, applyWebHostTerminalStyle, classifyWasmEngineFamily, collectWasmEngineProbeSignals, createWebHostApp, decodeWebHostTerminalRenderStyleBase64, encodeCapabilitiesControlMessage, encodeKeyInputMessage, encodeMouseInputMessage, encodePasteInputMessage, encodeRenderStyleControlMessage, encodeResizeControlMessage, encodeResyncControlMessage, encodeWebHostTerminalRenderStyleBase64, jspiConstructors, loadWebHostSceneManifest, mainThreadStackProfileEnvironmentDefaults, mergeWebHostTerminalStyle, normalizeWebHostSceneManifest, normalizeWebHostTerminalStyle, resolveWasmEngineCapabilities, resolveWebHostTerminalRenderStyle, resolvedSurfaceBackground, resolvedSurfaceForeground, stackProfileEnvironmentDefaults, webSocketSceneURL, webTUISceneManifestFromDescriptors, webTUISceneManifestToJSON, webTUITerminalBackgroundColor };
+export { BrowserWASIBridge, BrowserWASIBridgeOptions, BrowserWASIOutputSink, DomSurfacePainter, DomSurfacePainterOptions, JSPIConstructors, MAX_IMAGE_RECOVERY_ID_BYTES, MAX_OUTSTANDING_IMAGE_RECOVERY_IDS, ResolvedWebHostTerminalPalette, ResolvedWebHostTerminalStyle, SUPPORTED_SURFACE_VERSION, StdIOPipe, SurfaceMetrics, WasmEngineCapabilities, WasmEngineFamily, WasmEngineProbeSignals, WebHostANSIColors, WebHostAccessibilityAnnouncement, WebHostAccessibilityLiveRegion, WebHostAccessibilityNode, WebHostAccessibilityPoint, WebHostAppController, WebHostAppOptions, WebHostBridgeFactory, WebHostBridgeFactoryOptions, WebHostEmbeddedHostConfig, WebHostFocusPresentation, WebHostFocusSemantics, WebHostFrameDiagnosticRecord, WebHostImagePayloadRequestHandler, WebHostKeyInput, WebHostMouseInput, WebHostOutputDecoder, WebHostOutputRecord, WebHostOutputSink, WebHostResyncRequest, WebHostRuntimeIssue, WebHostSceneBridge, WebHostSceneDescriptor, WebHostSceneManifest, WebHostSceneManifestSource, WebHostSceneRuntime, WebHostSceneRuntimeOptions, WebHostScrollRegion, WebHostSurfaceCell, WebHostSurfaceDamage, WebHostSurfaceDamageRange, WebHostSurfaceDamageTextRow, WebHostSurfaceDeltaFrame, WebHostSurfaceDeltaRow, WebHostSurfaceFrame, WebHostSurfaceImage, WebHostSurfaceImageFormat, WebHostSurfaceLineStyle, WebHostSurfaceLinkRow, WebHostSurfaceLinkRun, WebHostSurfacePainter, WebHostSurfaceRect, WebHostSurfaceRendererKind, WebHostSurfaceSize, WebHostSurfaceStyle, WebHostTerminalAppearance, WebHostTerminalCursorStyle, WebHostTerminalPalette, WebHostTerminalRenderStyle, WebHostTerminalStyle, WebHostTerminalTheme, WebHostVisibilityDocument, WebSocketSceneBridge, WebSocketSceneBridgeFactory, WebSocketSceneBridgeOptions, WebSocketSceneSocket, WheelMode, applyWebHostTerminalStyle, classifyWasmEngineFamily, collectWasmEngineProbeSignals, createWebHostApp, decodeWebHostTerminalRenderStyleBase64, encodeCapabilitiesControlMessage, encodeKeyInputMessage, encodeMouseInputMessage, encodePasteInputMessage, encodeRenderStyleControlMessage, encodeResizeControlMessage, encodeResyncControlMessage, encodeWebHostTerminalRenderStyleBase64, isWebHostImageRecoveryId, jspiConstructors, loadWebHostSceneManifest, mainThreadStackProfileEnvironmentDefaults, mergeWebHostTerminalStyle, normalizeWebHostSceneManifest, normalizeWebHostTerminalStyle, resolveWasmEngineCapabilities, resolveWebHostTerminalRenderStyle, resolvedSurfaceBackground, resolvedSurfaceForeground, stackProfileEnvironmentDefaults, webSocketSceneURL, webTUISceneManifestFromDescriptors, webTUISceneManifestToJSON, webTUITerminalBackgroundColor };

package/dist/index.js

@@ -1,7 +1,7 @@
 import { StdIOPipe } from "./src/wasi/StdIOPipe.js";
 import { classifyWasmEngineFamily, collectWasmEngineProbeSignals, jspiConstructors, mainThreadStackProfileEnvironmentDefaults, resolveWasmEngineCapabilities, stackProfileEnvironmentDefaults } from "./src/wasi/WasmEngineCapabilities.js";
 import { applyWebHostTerminalStyle, decodeWebHostTerminalRenderStyleBase64, encodeWebHostTerminalRenderStyleBase64, mergeWebHostTerminalStyle, normalizeWebHostTerminalStyle, resolveWebHostTerminalRenderStyle, webTUITerminalBackgroundColor } from "./src/WebHostTerminalStyle.js";
-import { SUPPORTED_SURFACE_VERSION, WebHostOutputDecoder, encodeCapabilitiesControlMessage, encodeKeyInputMessage, encodeMouseInputMessage, encodePasteInputMessage, encodeRenderStyleControlMessage, encodeResizeControlMessage, encodeResyncControlMessage } from "./src/WebHostSurfaceTransport.js";
+import { MAX_IMAGE_RECOVERY_ID_BYTES, MAX_OUTSTANDING_IMAGE_RECOVERY_IDS, SUPPORTED_SURFACE_VERSION, WebHostOutputDecoder, encodeCapabilitiesControlMessage, encodeKeyInputMessage, encodeMouseInputMessage, encodePasteInputMessage, encodeRenderStyleControlMessage, encodeResizeControlMessage, encodeResyncControlMessage, isWebHostImageRecoveryId } from "./src/WebHostSurfaceTransport.js";
 import { BrowserWASIBridge } from "./src/wasi/BrowserWASIBridge.js";
 import { WebSocketSceneBridge, webSocketSceneURL } from "./src/WebSocketSceneBridge.js";
 import { loadWebHostSceneManifest, normalizeWebHostSceneManifest, webTUISceneManifestFromDescriptors, webTUISceneManifestToJSON } from "./src/WebHostSceneManifest.js";
@@ -9,4 +9,4 @@ import { resolvedSurfaceBackground, resolvedSurfaceForeground } from "./src/Surf
 import { DomSurfacePainter } from "./src/DomSurfacePainter.js";
 import { WebHostSceneRuntime } from "./src/WebHostSceneRuntime.js";
 import { createWebHostApp } from "./src/WebHostApp.js";
-export { BrowserWASIBridge, DomSurfacePainter, SUPPORTED_SURFACE_VERSION, StdIOPipe, WebHostOutputDecoder, WebHostSceneRuntime, WebSocketSceneBridge, applyWebHostTerminalStyle, classifyWasmEngineFamily, collectWasmEngineProbeSignals, createWebHostApp, decodeWebHostTerminalRenderStyleBase64, encodeCapabilitiesControlMessage, encodeKeyInputMessage, encodeMouseInputMessage, encodePasteInputMessage, encodeRenderStyleControlMessage, encodeResizeControlMessage, encodeResyncControlMessage, encodeWebHostTerminalRenderStyleBase64, jspiConstructors, loadWebHostSceneManifest, mainThreadStackProfileEnvironmentDefaults, mergeWebHostTerminalStyle, normalizeWebHostSceneManifest, normalizeWebHostTerminalStyle, resolveWasmEngineCapabilities, resolveWebHostTerminalRenderStyle, resolvedSurfaceBackground, resolvedSurfaceForeground, stackProfileEnvironmentDefaults, webSocketSceneURL, webTUISceneManifestFromDescriptors, webTUISceneManifestToJSON, webTUITerminalBackgroundColor };
+export { BrowserWASIBridge, DomSurfacePainter, MAX_IMAGE_RECOVERY_ID_BYTES, MAX_OUTSTANDING_IMAGE_RECOVERY_IDS, SUPPORTED_SURFACE_VERSION, StdIOPipe, WebHostOutputDecoder, WebHostSceneRuntime, WebSocketSceneBridge, applyWebHostTerminalStyle, classifyWasmEngineFamily, collectWasmEngineProbeSignals, createWebHostApp, decodeWebHostTerminalRenderStyleBase64, encodeCapabilitiesControlMessage, encodeKeyInputMessage, encodeMouseInputMessage, encodePasteInputMessage, encodeRenderStyleControlMessage, encodeResizeControlMessage, encodeResyncControlMessage, encodeWebHostTerminalRenderStyleBase64, isWebHostImageRecoveryId, jspiConstructors, loadWebHostSceneManifest, mainThreadStackProfileEnvironmentDefaults, mergeWebHostTerminalStyle, normalizeWebHostSceneManifest, normalizeWebHostTerminalStyle, resolveWasmEngineCapabilities, resolveWebHostTerminalRenderStyle, resolvedSurfaceBackground, resolvedSurfaceForeground, stackProfileEnvironmentDefaults, webSocketSceneURL, webTUISceneManifestFromDescriptors, webTUISceneManifestToJSON, webTUITerminalBackgroundColor };

package/dist/src/CanvasSurfacePainter.d.ts

@@ -0,0 +1,16 @@
+import { WebHostImagePayloadRequestHandler } from "./WebHostSurfaceTransport.js";
+import { NormalizedSurfaceImageFormat } from "./normalizeWireTokens.js";
+//#region src/CanvasSurfacePainter.d.ts
+interface CanvasSurfacePainterOptions {
+  /** Injectable decode seam for browser hosts and deterministic failure tests. */
+  decodeImage?: (dataBase64: string, format: NormalizedSurfaceImageFormat, imageID: string) => Promise<CanvasImageSource>;
+  /**
+   * Reports supported, positive-area images whose payload cannot be resolved
+   * locally. Returning the admitted subset keeps rejected IDs eligible for a
+   * later paint; `void` preserves legacy all-accepted behavior.
+   */
+  onImagePayloadMiss?: WebHostImagePayloadRequestHandler;
+}
+//#endregion
+export { CanvasSurfacePainterOptions };
+//# sourceMappingURL=CanvasSurfacePainter.d.ts.map

package/dist/src/CanvasSurfacePainter.js

@@ -1,8 +1,10 @@
 import { webTUITerminalBackgroundColor } from "./WebHostTerminalStyle.js";
+import { isWebHostImageRecoveryId } from "./WebHostSurfaceTransport.js";
 import { canRenderBoxDrawing, drawBoxDrawing } from "./BoxDrawingRenderer.js";
 import { resolvedSurfaceBackground, resolvedSurfaceForeground } from "./SurfaceRenderer.js";
-import { isSupportedImageFormat, normalizeScalingMode } from "./normalizeWireTokens.js";
-//#region src/CanvasSurfacePainter.ts
+import { isSupportedImageFormat } from "./normalizeWireTokens.js";
+import { registerCanvasSurfacePainterConformanceControl } from "./SurfacePainterConformanceControl.js";
+const MAX_UNRESOLVED_IMAGE_PAYLOAD_CHARACTERS = 64 * 1024 * 1024;
 /**
 * Draws SwiftTUI surface frames onto a 2D canvas: background fills, per-cell
 * text/box-drawing/decorations, surface images, and damage-scoped dirty-region
@@ -15,8 +17,29 @@ import { isSupportedImageFormat, normalizeScalingMode } from "./normalizeWireTok
 */
 var CanvasSurfacePainter = class {
 	imageCache = /* @__PURE__ */ new Map();
+	unresolvedImageIds = /* @__PURE__ */ new Set();
+	unresolvedImagePayloadCharacters = 0;
+	imageDecoder;
+	onImagePayloadMiss;
 	canvas;
 	requestRedraw = () => {};
+	lastEpoch;
+	pendingImagePayloadMissIds = /* @__PURE__ */ new Set();
+	imagePayloadMissScheduled = false;
+	constructor(options = {}) {
+		this.imageDecoder = options.decodeImage ?? decodeImage;
+		this.onImagePayloadMiss = options.onImagePayloadMiss ?? (() => {});
+		registerCanvasSurfacePainterConformanceControl(this, {
+			evictImages: (ids) => {
+				for (const id of ids) {
+					this.removeUnresolvedImage(id);
+					this.imageCache.delete(id);
+					this.pendingImagePayloadMissIds.delete(id);
+				}
+			},
+			visibleImageIDs: (images) => [...new Set(images.filter(isPaintableSurfaceImage).filter((image) => this.imageCache.get(image.id)?.image !== void 0).map((image) => image.id))].sort()
+		});
+	}
 	/**
 	* Binds the canvas the painter draws into and the callback used to request a
 	* full repaint after an asynchronous image decode completes.
@@ -25,12 +48,21 @@ var CanvasSurfacePainter = class {
 		this.canvas = canvas;
 		this.requestRedraw = requestRedraw;
 	}
-	paint(metrics, frame, damage) {
+	paint(metrics, frame, damage, recoveredImagePayloadIds = []) {
 		const canvas = this.canvas;
 		const context = canvas?.getContext("2d");
 		if (!canvas || !context) return;
+		if (frame?.epoch !== void 0 && frame.epoch !== this.lastEpoch) {
+			this.lastEpoch = frame.epoch;
+			for (const cached of this.imageCache.values()) if (!cached.image) cached.missReported = false;
+		}
+		this.sweepUnresolvedImages(frame?.images);
 		const dirtyRegion = frame ? this.dirtyRegionForDamage(damage, frame, metrics) : void 0;
-		if (dirtyRegion?.rects.length === 0) return;
+		const recoveredPayloadIds = new Set(recoveredImagePayloadIds);
+		if (dirtyRegion?.rects.length === 0) {
+			this.prepareImages(frame?.images ?? [], recoveredPayloadIds);
+			return;
+		}
 		const scale = globalThis.window?.devicePixelRatio || 1;
 		context.setTransform(scale, 0, 0, scale, 0, 0);
 		context.textBaseline = "alphabetic";
@@ -45,7 +77,7 @@ var CanvasSurfacePainter = class {
 		}
 		if (!frame) return;
 		this.drawRows(context, frame, metrics, dirtyRegion);
-		this.drawImages(context, frame.images ?? [], metrics, dirtyRegion);
+		this.drawImages(context, frame.images ?? [], metrics, dirtyRegion, recoveredPayloadIds);
 	}
 	drawRows(context, frame, metrics, dirtyRegion) {
 		if (dirtyRegion) {
@@ -68,21 +100,28 @@ var CanvasSurfacePainter = class {
 			this.drawCell(context, metrics, x, y, text, span, style);
 		}
 	}
-	drawImages(context, images, metrics, dirtyRegion) {
+	drawImages(context, images, metrics, dirtyRegion, recoveredPayloadIds) {
+		const missingPayloadIds = /* @__PURE__ */ new Set();
 		for (const image of images) {
-			if (!isSupportedImageFormat(image.format)) continue;
-			this.drawImage(context, {
-				...image,
-				scalingMode: normalizeScalingMode(image.scalingMode)
-			}, metrics, dirtyRegion);
+			if (!isPaintableSurfaceImage(image)) continue;
+			this.drawImage(context, image, metrics, dirtyRegion, missingPayloadIds, recoveredPayloadIds);
 		}
+		this.reportImagePayloadMisses(missingPayloadIds);
 	}
-	drawImage(context, image, metrics, dirtyRegion) {
-		const decodedImage = this.cachedImage(image);
-		if (!decodedImage) return;
+	prepareImages(images, recoveredPayloadIds) {
+		const missingPayloadIds = /* @__PURE__ */ new Set();
+		for (const image of images) {
+			if (!isPaintableSurfaceImage(image)) continue;
+			this.cachedImage(image, missingPayloadIds, recoveredPayloadIds);
+		}
+		this.reportImagePayloadMisses(missingPayloadIds);
+	}
+	drawImage(context, image, metrics, dirtyRegion, missingPayloadIds, recoveredPayloadIds) {
 		const [boundsX, boundsY, boundsWidth, boundsHeight] = image.bounds;
 		const [clipX, clipY, clipWidth, clipHeight] = image.visibleBounds;
 		if (boundsWidth <= 0 || boundsHeight <= 0 || clipWidth <= 0 || clipHeight <= 0) return;
+		const decodedImage = this.cachedImage(image, missingPayloadIds, recoveredPayloadIds);
+		if (!decodedImage) return;
 		if (dirtyRegion && !dirtyRegionIntersectsCellRect(dirtyRegion, clipX, clipY, clipWidth, clipHeight)) return;
 		context.save();
 		context.beginPath();
@@ -91,21 +130,116 @@ var CanvasSurfacePainter = class {
 		context.drawImage(decodedImage, boundsX * metrics.cellWidth, boundsY * metrics.cellHeight, boundsWidth * metrics.cellWidth, boundsHeight * metrics.cellHeight);
 		context.restore();
 	}
-	cachedImage(image) {
-		const cached = this.imageCache.get(image.id);
+	cachedImage(image, missingPayloadIds, recoveredPayloadIds) {
+		let cached = this.imageCache.get(image.id);
 		if (cached?.image) return cached.image;
-		if (!cached?.promise && image.dataBase64) {
-			const promise = decodeImage(image.dataBase64, image.format);
-			this.imageCache.set(image.id, { promise });
+		const beginsRecoveredGeneration = image.dataBase64 !== void 0 && recoveredPayloadIds.delete(image.id);
+		if (image.dataBase64 !== void 0 && (cached?.payload === void 0 || beginsRecoveredGeneration)) {
+			if (!this.canTrackUnresolvedImage(image.id, image.dataBase64)) return;
+			cached = {
+				payload: image.dataBase64,
+				retries: 0
+			};
+			this.setUnresolvedImage(image.id, cached);
+		} else if (!cached) {
+			if (!isWebHostImageRecoveryId(image.id)) return;
+			if (!this.canTrackUnresolvedImage(image.id)) return;
+			cached = { missReported: false };
+			this.setUnresolvedImage(image.id, cached);
+			missingPayloadIds.add(image.id);
+			return;
+		}
+		const attempts = cached.retries ?? 0;
+		if (cached.payload === void 0) {
+			if (!cached.missReported) {
+				cached.missReported = true;
+				missingPayloadIds.add(image.id);
+			}
+			return;
+		}
+		if (attempts >= 3) {
+			if (!cached.missReported) {
+				cached.missReported = true;
+				missingPayloadIds.add(image.id);
+			}
+			return;
+		}
+		if (!cached.promise) {
+			const nextAttempts = attempts + 1;
+			const promise = this.imageDecoder(cached.payload, image.format, image.id);
+			cached.promise = promise;
+			cached.retries = nextAttempts;
 			promise.then((decodedImage) => {
 				if (this.imageCache.get(image.id)?.promise !== promise) return;
+				this.removeUnresolvedImage(image.id);
 				this.imageCache.set(image.id, { image: decodedImage });
 				this.requestRedraw();
 			}).catch(() => {
-				this.imageCache.delete(image.id);
+				const latest = this.imageCache.get(image.id);
+				if (latest?.promise !== promise) return;
+				latest.promise = void 0;
+				if ((latest.retries ?? 0) >= 3 && !latest.missReported) {
+					latest.missReported = true;
+					if (isWebHostImageRecoveryId(image.id)) this.scheduleImagePayloadMiss(image.id);
+				}
+				this.requestRedraw();
 			});
 		}
 	}
+	canTrackUnresolvedImage(id, payload) {
+		const existing = this.imageCache.get(id);
+		const existingPayloadCharacters = existing?.image ? 0 : existing?.payload?.length ?? 0;
+		const nextPayloadCharacters = this.unresolvedImagePayloadCharacters - existingPayloadCharacters + (payload?.length ?? 0);
+		return (this.unresolvedImageIds.has(id) || this.unresolvedImageIds.size < 256) && nextPayloadCharacters <= 67108864;
+	}
+	setUnresolvedImage(id, cached) {
+		const existing = this.imageCache.get(id);
+		if (this.unresolvedImageIds.has(id)) this.unresolvedImagePayloadCharacters -= existing?.payload?.length ?? 0;
+		this.imageCache.set(id, cached);
+		this.unresolvedImageIds.add(id);
+		this.unresolvedImagePayloadCharacters += cached.payload?.length ?? 0;
+		this.pendingImagePayloadMissIds.delete(id);
+	}
+	removeUnresolvedImage(id) {
+		if (!this.unresolvedImageIds.delete(id)) return;
+		this.unresolvedImagePayloadCharacters -= this.imageCache.get(id)?.payload?.length ?? 0;
+		this.pendingImagePayloadMissIds.delete(id);
+	}
+	sweepUnresolvedImages(images) {
+		const presentedIds = /* @__PURE__ */ new Set();
+		for (const image of images ?? []) {
+			if (!this.unresolvedImageIds.has(image.id)) continue;
+			if (isPaintableSurfaceImage(image)) presentedIds.add(image.id);
+		}
+		for (const id of this.unresolvedImageIds) {
+			if (presentedIds.has(id)) continue;
+			this.removeUnresolvedImage(id);
+			this.imageCache.delete(id);
+		}
+	}
+	reportImagePayloadMisses(ids) {
+		if (ids.size === 0) return;
+		const candidateIds = [...ids].sort();
+		this.applyImagePayloadMissAdmission(candidateIds, this.onImagePayloadMiss(candidateIds));
+	}
+	scheduleImagePayloadMiss(id) {
+		this.pendingImagePayloadMissIds.add(id);
+		if (this.imagePayloadMissScheduled) return;
+		this.imagePayloadMissScheduled = true;
+		queueMicrotask(() => {
+			this.imagePayloadMissScheduled = false;
+			const ids = [...this.pendingImagePayloadMissIds].sort();
+			this.pendingImagePayloadMissIds.clear();
+			if (ids.length > 0) this.applyImagePayloadMissAdmission(ids, this.onImagePayloadMiss(ids));
+		});
+	}
+	applyImagePayloadMissAdmission(candidateIds, admittedIds) {
+		const acceptedIds = new Set(Array.isArray(admittedIds) ? admittedIds : candidateIds);
+		for (const id of candidateIds) {
+			const cached = this.imageCache.get(id);
+			if (cached && !cached.image) cached.missReported = acceptedIds.has(id);
+		}
+	}
 	drawCell(context, metrics, x, y, text, span, style) {
 		const rectX = x * metrics.cellWidth;
 		const rectY = y * metrics.cellHeight;
@@ -180,6 +314,11 @@ var CanvasSurfacePainter = class {
 		context.setLineDash([]);
 	}
 };
+function isPaintableSurfaceImage(image) {
+	const [, , boundsWidth, boundsHeight] = image.bounds;
+	const [, , clipWidth, clipHeight] = image.visibleBounds;
+	return isSupportedImageFormat(image.format) && boundsWidth > 0 && boundsHeight > 0 && clipWidth > 0 && clipHeight > 0;
+}
 /**
 * The CSS font string for a cell, folding the surface emphasis bits (bold,
 * italic) over the host terminal's font size/family. Exposed so the host can
@@ -258,6 +397,6 @@ function dirtyRegionIntersectsCellRect(region, x, y, width, height) {
 	return false;
 }
 //#endregion
-export { CanvasSurfacePainter, fontForStyle };
+export { CanvasSurfacePainter, MAX_UNRESOLVED_IMAGE_PAYLOAD_CHARACTERS, fontForStyle };
 
 //# sourceMappingURL=CanvasSurfacePainter.js.map

package/dist/src/CanvasSurfacePainter.js.map

@@ -1 +1 @@
-{"version":3,"file":"CanvasSurfacePainter.js","names":[],"sources":["../../src/CanvasSurfacePainter.ts"],"sourcesContent":["import {\n  canRenderBoxDrawing,\n  drawBoxDrawing,\n} from \"./BoxDrawingRenderer.ts\";\nimport {\n  resolvedSurfaceBackground,\n  resolvedSurfaceForeground,\n  type SurfaceMetrics,\n  type WebHostSurfacePainter,\n} from \"./SurfaceRenderer.ts\";\nimport {\n  isSupportedImageFormat,\n  normalizeScalingMode,\n  type NormalizedSurfaceImageFormat,\n} from \"./normalizeWireTokens.ts\";\nimport {\n  type ResolvedWebHostTerminalStyle,\n  webTUITerminalBackgroundColor,\n} from \"./WebHostTerminalStyle.ts\";\nimport type {\n  WebHostSurfaceDamage,\n  WebHostSurfaceFrame,\n  WebHostSurfaceImage,\n  WebHostSurfaceStyle,\n} from \"./WebHostSurfaceTransport.ts\";\n\n/**\n * A read-only snapshot of the cell grid geometry and active style the painter\n * needs for a single paint pass — see {@link SurfaceMetrics}, shared with the\n * DOM painter. The alias keeps this painter's original public name stable.\n */\nexport type CanvasSurfaceMetrics = SurfaceMetrics;\n\ninterface CachedWebHostImage {\n  image?: CanvasImageSource;\n  promise?: Promise<CanvasImageSource>;\n}\n\ninterface DirtyRect {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\ninterface DirtyCellRange {\n  start: number;\n  end: number;\n}\n\ntype DirtyRowRanges = \"full\" | DirtyCellRange[];\n\ninterface DirtyRegion {\n  rects: DirtyRect[];\n  rows: Map<number, DirtyRowRanges>;\n}\n\n/**\n * Draws SwiftTUI surface frames onto a 2D canvas: background fills, per-cell\n * text/box-drawing/decorations, surface images, and damage-scoped dirty-region\n * painting. The painter caches decoded images and asks the host to repaint once\n * an image finishes decoding (via the `requestRedraw` callback).\n *\n * Geometry and style are supplied per paint via {@link CanvasSurfaceMetrics};\n * the painter holds only the canvas handle, the image cache, and the redraw\n * callback as durable state.\n */\nexport class CanvasSurfacePainter implements WebHostSurfacePainter {\n  private readonly imageCache = new Map<string, CachedWebHostImage>();\n  private canvas?: HTMLCanvasElement;\n  private requestRedraw: () => void = () => {};\n\n  /**\n   * Binds the canvas the painter draws into and the callback used to request a\n   * full repaint after an asynchronous image decode completes.\n   */\n  attach(\n    canvas: HTMLCanvasElement,\n    requestRedraw: () => void\n  ): void {\n    this.canvas = canvas;\n    this.requestRedraw = requestRedraw;\n  }\n\n  paint(\n    metrics: CanvasSurfaceMetrics,\n    frame: WebHostSurfaceFrame | undefined,\n    damage?: WebHostSurfaceDamage\n  ): void {\n    const canvas = this.canvas;\n    const context = canvas?.getContext(\"2d\");\n    if (!canvas || !context) {\n      return;\n    }\n\n    const dirtyRegion = frame\n      ? this.dirtyRegionForDamage(damage, frame, metrics)\n      : undefined;\n    if (dirtyRegion?.rects.length === 0) {\n      return;\n    }\n\n    const scale = globalThis.window?.devicePixelRatio || 1;\n    context.setTransform(scale, 0, 0, scale, 0, 0);\n    context.textBaseline = \"alphabetic\";\n\n    context.fillStyle = webTUITerminalBackgroundColor(metrics.style);\n    if (dirtyRegion) {\n      for (const rect of dirtyRegion.rects) {\n        context.clearRect(rect.x, rect.y, rect.width, rect.height);\n        context.fillRect(rect.x, rect.y, rect.width, rect.height);\n      }\n    } else {\n      context.clearRect(0, 0, canvas.width / scale, canvas.height / scale);\n      context.fillRect(0, 0, metrics.columns * metrics.cellWidth, metrics.rows * metrics.cellHeight);\n    }\n\n    if (!frame) {\n      return;\n    }\n\n    this.drawRows(context, frame, metrics, dirtyRegion);\n    this.drawImages(context, frame.images ?? [], metrics, dirtyRegion);\n  }\n\n  private drawRows(\n    context: CanvasRenderingContext2D,\n    frame: WebHostSurfaceFrame,\n    metrics: CanvasSurfaceMetrics,\n    dirtyRegion?: DirtyRegion\n  ): void {\n    if (dirtyRegion) {\n      for (const [y, ranges] of dirtyRegion.rows) {\n        const row = frame.rows[y] ?? [];\n        this.drawRow(context, frame, metrics, row, y, ranges);\n      }\n      return;\n    }\n\n    for (let y = 0; y < frame.rows.length; y += 1) {\n      const row = frame.rows[y] ?? [];\n      this.drawRow(context, frame, metrics, row, y);\n    }\n  }\n\n  private drawRow(\n    context: CanvasRenderingContext2D,\n    frame: WebHostSurfaceFrame,\n    metrics: CanvasSurfaceMetrics,\n    row: WebHostSurfaceFrame[\"rows\"][number],\n    y: number,\n    ranges?: DirtyRowRanges\n  ): void {\n    for (const cell of row) {\n      const [x, text, span, styleIndex] = cell;\n      if (ranges !== undefined && !cellIntersectsRanges(x, span, ranges)) {\n        continue;\n      }\n      const style = frame.styles[styleIndex] ?? undefined;\n      this.drawCell(context, metrics, x, y, text, span, style);\n    }\n  }\n\n  private drawImages(\n    context: CanvasRenderingContext2D,\n    images: WebHostSurfaceImage[],\n    metrics: CanvasSurfaceMetrics,\n    dirtyRegion?: DirtyRegion\n  ): void {\n    for (const image of images) {\n      if (!isSupportedImageFormat(image.format)) {\n        continue;\n      }\n      this.drawImage(\n        context,\n        {\n          ...image,\n          scalingMode: normalizeScalingMode(image.scalingMode),\n        },\n        metrics,\n        dirtyRegion\n      );\n    }\n  }\n\n  private drawImage(\n    context: CanvasRenderingContext2D,\n    image: WebHostSurfaceImage,\n    metrics: CanvasSurfaceMetrics,\n    dirtyRegion?: DirtyRegion\n  ): void {\n    const decodedImage = this.cachedImage(image);\n    if (!decodedImage) {\n      return;\n    }\n\n    const [boundsX, boundsY, boundsWidth, boundsHeight] = image.bounds;\n    const [clipX, clipY, clipWidth, clipHeight] = image.visibleBounds;\n    if (boundsWidth <= 0 || boundsHeight <= 0 || clipWidth <= 0 || clipHeight <= 0) {\n      return;\n    }\n    if (\n      dirtyRegion\n      && !dirtyRegionIntersectsCellRect(dirtyRegion, clipX, clipY, clipWidth, clipHeight)\n    ) {\n      return;\n    }\n\n    context.save();\n    context.beginPath();\n    context.rect(\n      clipX * metrics.cellWidth,\n      clipY * metrics.cellHeight,\n      clipWidth * metrics.cellWidth,\n      clipHeight * metrics.cellHeight\n    );\n    context.clip();\n    context.drawImage(\n      decodedImage,\n      boundsX * metrics.cellWidth,\n      boundsY * metrics.cellHeight,\n      boundsWidth * metrics.cellWidth,\n      boundsHeight * metrics.cellHeight\n    );\n    context.restore();\n  }\n\n  private cachedImage(\n    image: WebHostSurfaceImage\n  ): CanvasImageSource | undefined {\n    const cached = this.imageCache.get(image.id);\n    if (cached?.image) {\n      return cached.image;\n    }\n\n    if (!cached?.promise && image.dataBase64) {\n      const promise = decodeImage(image.dataBase64, image.format);\n      this.imageCache.set(image.id, { promise });\n      void promise.then((decodedImage) => {\n        const latest = this.imageCache.get(image.id);\n        if (latest?.promise !== promise) {\n          return;\n        }\n        this.imageCache.set(image.id, { image: decodedImage });\n        this.requestRedraw();\n      }).catch(() => {\n        this.imageCache.delete(image.id);\n      });\n    }\n\n    return undefined;\n  }\n\n  private drawCell(\n    context: CanvasRenderingContext2D,\n    metrics: CanvasSurfaceMetrics,\n    x: number,\n    y: number,\n    text: string,\n    span: number,\n    style?: WebHostSurfaceStyle | null\n  ): void {\n    const rectX = x * metrics.cellWidth;\n    const rectY = y * metrics.cellHeight;\n    const width = Math.max(1, span) * metrics.cellWidth;\n    const background = resolvedSurfaceBackground(style, metrics.style);\n    const foreground = resolvedSurfaceForeground(style, metrics.style);\n    const opacity = style?.opacity ?? 1;\n\n    if (background) {\n      context.globalAlpha = opacity;\n      context.fillStyle = background;\n      context.fillRect(rectX, rectY, width, metrics.cellHeight);\n    }\n\n    if (text !== \" \") {\n      context.globalAlpha = opacity;\n      context.fillStyle = foreground;\n      context.strokeStyle = foreground;\n      if (!canRenderBoxDrawing(text) || !drawBoxDrawing(context, text, {\n        x: rectX,\n        y: rectY,\n        width,\n        height: metrics.cellHeight,\n      })) {\n        context.font = fontForStyle(metrics.style, style);\n        context.fillText(\n          text,\n          rectX,\n          rectY + Math.floor((metrics.cellHeight + metrics.style.fontSize) / 2) - 2\n        );\n      }\n    }\n\n    this.drawTextLine(context, metrics, rectX, rectY, width, style?.underline, \"underline\", foreground);\n    this.drawTextLine(context, metrics, rectX, rectY, width, style?.strikethrough, \"strike\", foreground);\n    context.globalAlpha = 1;\n  }\n\n  private dirtyRegionForDamage(\n    damage: WebHostSurfaceDamage | undefined,\n    frame: WebHostSurfaceFrame,\n    metrics: CanvasSurfaceMetrics\n  ): DirtyRegion | undefined {\n    if (!damage || damage.requiresFullTextRepaint || damage.requiresFullGraphicsReplay) {\n      return undefined;\n    }\n\n    const rects: DirtyRect[] = [];\n    const rows = new Map<number, DirtyRowRanges>();\n    for (const [row, ranges] of damage.textRows) {\n      if (row < 0 || row >= frame.height) {\n        continue;\n      }\n      if (ranges.length === 0) {\n        rects.push(cellRect(metrics, 0, row, frame.width));\n        rows.set(row, \"full\");\n        continue;\n      }\n      const rowRanges: DirtyCellRange[] = rows.get(row) === \"full\"\n        ? []\n        : [...(rows.get(row) as DirtyCellRange[] | undefined ?? [])];\n      for (const [start, end] of ranges) {\n        const lowerBound = Math.max(0, Math.min(frame.width, Math.floor(start)));\n        const upperBound = Math.max(lowerBound, Math.min(frame.width, Math.ceil(end)));\n        if (lowerBound >= upperBound) {\n          continue;\n        }\n        rects.push(cellRect(metrics, lowerBound, row, upperBound - lowerBound));\n        rowRanges.push({ start: lowerBound, end: upperBound });\n      }\n      if (rows.get(row) !== \"full\" && rowRanges.length > 0) {\n        rows.set(row, normalizeCellRanges(rowRanges));\n      }\n    }\n    return { rects, rows };\n  }\n\n  private drawTextLine(\n    context: CanvasRenderingContext2D,\n    metrics: CanvasSurfaceMetrics,\n    x: number,\n    y: number,\n    width: number,\n    line: WebHostSurfaceStyle[\"underline\"],\n    placement: \"underline\" | \"strike\",\n    fallbackColor: string\n  ): void {\n    if (!line) {\n      return;\n    }\n    context.strokeStyle = line.color ?? fallbackColor;\n    context.lineWidth = line.pattern === \"double\" ? 2 : 1;\n    if (line.pattern === \"dot\") {\n      context.setLineDash([1, 3]);\n    } else if (line.pattern === \"dash\") {\n      context.setLineDash([4, 3]);\n    } else {\n      context.setLineDash([]);\n    }\n\n    const lineY = placement === \"underline\"\n      ? y + metrics.cellHeight - 2\n      : y + Math.floor(metrics.cellHeight / 2);\n    context.beginPath();\n    context.moveTo(x, lineY);\n    context.lineTo(x + width, lineY);\n    context.stroke();\n    context.setLineDash([]);\n  }\n}\n\n/**\n * The CSS font string for a cell, folding the surface emphasis bits (bold,\n * italic) over the host terminal's font size/family. Exposed so the host can\n * reuse the exact same metric when measuring cell dimensions.\n */\nexport function fontForStyle(\n  terminalStyle: ResolvedWebHostTerminalStyle,\n  style?: WebHostSurfaceStyle | null\n): string {\n  const emphasis = style?.em ?? 0;\n  const italic = (emphasis & 2) !== 0 ? \"italic \" : \"\";\n  const weight = (emphasis & 1) !== 0 ? \"700 \" : \"\";\n  return `${italic}${weight}${terminalStyle.fontSize}px ${terminalStyle.fontFamily}`;\n}\n\nfunction cellRect(\n  metrics: CanvasSurfaceMetrics,\n  x: number,\n  y: number,\n  span: number\n): DirtyRect {\n  return {\n    x: x * metrics.cellWidth,\n    y: y * metrics.cellHeight,\n    width: Math.max(1, span) * metrics.cellWidth,\n    height: metrics.cellHeight,\n  };\n}\n\nasync function decodeImage(\n  dataBase64: string,\n  format: NormalizedSurfaceImageFormat\n): Promise<CanvasImageSource> {\n  const bytes = decodeBase64Bytes(dataBase64);\n  const blob = new Blob([bytes], { type: `image/${format}` });\n\n  if (typeof createImageBitmap === \"function\") {\n    // Animated GIFs collapse to their first frame in createImageBitmap\n    // — that matches the Kitty path's first-frame composite. Phase 7\n    // will replace this with a frame ticker.\n    return createImageBitmap(blob);\n  }\n\n  return new Promise((resolve, reject) => {\n    const image = new Image();\n    const url = URL.createObjectURL(blob);\n    image.onload = () => {\n      URL.revokeObjectURL(url);\n      resolve(image);\n    };\n    image.onerror = () => {\n      URL.revokeObjectURL(url);\n      reject(new Error(`Failed to decode ${format} image`));\n    };\n    image.src = url;\n  });\n}\n\nfunction decodeBase64Bytes(\n  value: string\n): Uint8Array {\n  if (typeof atob === \"function\") {\n    const binary = atob(value);\n    const bytes = new Uint8Array(binary.length);\n    for (let index = 0; index < binary.length; index += 1) {\n      bytes[index] = binary.charCodeAt(index);\n    }\n    return bytes;\n  }\n\n  return new Uint8Array(Buffer.from(value, \"base64\"));\n}\n\nfunction normalizeCellRanges(\n  ranges: DirtyCellRange[]\n): DirtyCellRange[] {\n  const sorted = ranges\n    .filter((range) => range.end > range.start)\n    .sort((lhs, rhs) => lhs.start - rhs.start || lhs.end - rhs.end);\n  const normalized: DirtyCellRange[] = [];\n  for (const range of sorted) {\n    const previous = normalized[normalized.length - 1];\n    if (previous && range.start <= previous.end) {\n      previous.end = Math.max(previous.end, range.end);\n      continue;\n    }\n    normalized.push({ ...range });\n  }\n  return normalized;\n}\n\nfunction cellIntersectsRanges(\n  x: number,\n  span: number,\n  ranges: DirtyRowRanges\n): boolean {\n  if (ranges === \"full\") {\n    return true;\n  }\n  const start = Math.floor(x);\n  const end = start + Math.max(1, Math.ceil(span));\n  return ranges.some((range) => start < range.end && end > range.start);\n}\n\nfunction dirtyRegionIntersectsCellRect(\n  region: DirtyRegion,\n  x: number,\n  y: number,\n  width: number,\n  height: number\n): boolean {\n  const startRow = Math.max(0, Math.floor(y));\n  const endRow = Math.max(startRow, Math.ceil(y + height));\n  const rectRange = {\n    start: Math.floor(x),\n    end: Math.floor(x) + Math.max(1, Math.ceil(width)),\n  };\n  for (let row = startRow; row < endRow; row += 1) {\n    const ranges = region.rows.get(row);\n    if (!ranges) {\n      continue;\n    }\n    if (cellIntersectsRanges(rectRange.start, rectRange.end - rectRange.start, ranges)) {\n      return true;\n    }\n  }\n  return false;\n}\n"],"mappings":"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"}
+{"version":3,"file":"CanvasSurfacePainter.js","names":[],"sources":["../../src/CanvasSurfacePainter.ts"],"sourcesContent":["import {\n  canRenderBoxDrawing,\n  drawBoxDrawing,\n} from \"./BoxDrawingRenderer.ts\";\nimport {\n  resolvedSurfaceBackground,\n  resolvedSurfaceForeground,\n  type SurfaceMetrics,\n  type WebHostSurfacePainter,\n} from \"./SurfaceRenderer.ts\";\nimport {\n  isSupportedImageFormat,\n  type NormalizedSurfaceImageFormat,\n} from \"./normalizeWireTokens.ts\";\nimport {\n  type ResolvedWebHostTerminalStyle,\n  webTUITerminalBackgroundColor,\n} from \"./WebHostTerminalStyle.ts\";\nimport {\n  isWebHostImageRecoveryId,\n  type WebHostImagePayloadRequestHandler,\n  type WebHostSurfaceDamage,\n  type WebHostSurfaceFrame,\n  type WebHostSurfaceImage,\n  type WebHostSurfaceStyle,\n} from \"./WebHostSurfaceTransport.ts\";\nimport {\n  registerCanvasSurfacePainterConformanceControl,\n} from \"./SurfacePainterConformanceControl.ts\";\n\n/**\n * A read-only snapshot of the cell grid geometry and active style the painter\n * needs for a single paint pass — see {@link SurfaceMetrics}, shared with the\n * DOM painter. The alias keeps this painter's original public name stable.\n */\nexport type CanvasSurfaceMetrics = SurfaceMetrics;\n\ninterface CachedWebHostImage {\n  image?: CanvasImageSource;\n  promise?: Promise<CanvasImageSource>;\n  payload?: string;\n  /** Total decode attempts already started; bounded by MAX_IMAGE_DECODE_ATTEMPTS. */\n  retries?: number;\n  missReported?: boolean;\n}\n\nexport const MAX_IMAGE_DECODE_ATTEMPTS = 3;\nexport const MAX_UNRESOLVED_IMAGE_CACHE_ENTRIES = 256;\nexport const MAX_UNRESOLVED_IMAGE_PAYLOAD_CHARACTERS = 64 * 1024 * 1024;\n\nexport interface CanvasSurfacePainterOptions {\n  /** Injectable decode seam for browser hosts and deterministic failure tests. */\n  decodeImage?: (\n    dataBase64: string,\n    format: NormalizedSurfaceImageFormat,\n    imageID: string\n  ) => Promise<CanvasImageSource>;\n  /**\n   * Reports supported, positive-area images whose payload cannot be resolved\n   * locally. Returning the admitted subset keeps rejected IDs eligible for a\n   * later paint; `void` preserves legacy all-accepted behavior.\n   */\n  onImagePayloadMiss?: WebHostImagePayloadRequestHandler;\n}\n\ninterface DirtyRect {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\ninterface DirtyCellRange {\n  start: number;\n  end: number;\n}\n\ntype DirtyRowRanges = \"full\" | DirtyCellRange[];\n\ninterface DirtyRegion {\n  rects: DirtyRect[];\n  rows: Map<number, DirtyRowRanges>;\n}\n\n/**\n * Draws SwiftTUI surface frames onto a 2D canvas: background fills, per-cell\n * text/box-drawing/decorations, surface images, and damage-scoped dirty-region\n * painting. The painter caches decoded images and asks the host to repaint once\n * an image finishes decoding (via the `requestRedraw` callback).\n *\n * Geometry and style are supplied per paint via {@link CanvasSurfaceMetrics};\n * the painter holds only the canvas handle, the image cache, and the redraw\n * callback as durable state.\n */\nexport class CanvasSurfacePainter implements WebHostSurfacePainter {\n  private readonly imageCache = new Map<string, CachedWebHostImage>();\n  private readonly unresolvedImageIds = new Set<string>();\n  private unresolvedImagePayloadCharacters = 0;\n  private readonly imageDecoder: NonNullable<CanvasSurfacePainterOptions[\"decodeImage\"]>;\n  private readonly onImagePayloadMiss: WebHostImagePayloadRequestHandler;\n  private canvas?: HTMLCanvasElement;\n  private requestRedraw: () => void = () => {};\n  private lastEpoch?: number;\n  private readonly pendingImagePayloadMissIds = new Set<string>();\n  private imagePayloadMissScheduled = false;\n\n  constructor(options: CanvasSurfacePainterOptions = {}) {\n    this.imageDecoder = options.decodeImage ?? decodeImage;\n    this.onImagePayloadMiss = options.onImagePayloadMiss ?? (() => {});\n    registerCanvasSurfacePainterConformanceControl(this, {\n      evictImages: (ids) => {\n        for (const id of ids) {\n          this.removeUnresolvedImage(id);\n          this.imageCache.delete(id);\n          this.pendingImagePayloadMissIds.delete(id);\n        }\n      },\n      visibleImageIDs: (images) => [...new Set(\n        images\n          .filter(isPaintableSurfaceImage)\n          .filter((image) => this.imageCache.get(image.id)?.image !== undefined)\n          .map((image) => image.id)\n      )].sort(),\n    });\n  }\n\n  /**\n   * Binds the canvas the painter draws into and the callback used to request a\n   * full repaint after an asynchronous image decode completes.\n   */\n  attach(\n    canvas: HTMLCanvasElement,\n    requestRedraw: () => void\n  ): void {\n    this.canvas = canvas;\n    this.requestRedraw = requestRedraw;\n  }\n\n  paint(\n    metrics: CanvasSurfaceMetrics,\n    frame: WebHostSurfaceFrame | undefined,\n    damage?: WebHostSurfaceDamage,\n    recoveredImagePayloadIds: readonly string[] = []\n  ): void {\n    const canvas = this.canvas;\n    const context = canvas?.getContext(\"2d\");\n    if (!canvas || !context) {\n      return;\n    }\n\n    if (frame?.epoch !== undefined && frame.epoch !== this.lastEpoch) {\n      this.lastEpoch = frame.epoch;\n      for (const cached of this.imageCache.values()) {\n        if (!cached.image) {\n          cached.missReported = false;\n        }\n      }\n    }\n    this.sweepUnresolvedImages(frame?.images);\n\n    const dirtyRegion = frame\n      ? this.dirtyRegionForDamage(damage, frame, metrics)\n      : undefined;\n    const recoveredPayloadIds = new Set(recoveredImagePayloadIds);\n    if (dirtyRegion?.rects.length === 0) {\n      this.prepareImages(frame?.images ?? [], recoveredPayloadIds);\n      return;\n    }\n\n    const scale = globalThis.window?.devicePixelRatio || 1;\n    context.setTransform(scale, 0, 0, scale, 0, 0);\n    context.textBaseline = \"alphabetic\";\n\n    context.fillStyle = webTUITerminalBackgroundColor(metrics.style);\n    if (dirtyRegion) {\n      for (const rect of dirtyRegion.rects) {\n        context.clearRect(rect.x, rect.y, rect.width, rect.height);\n        context.fillRect(rect.x, rect.y, rect.width, rect.height);\n      }\n    } else {\n      context.clearRect(0, 0, canvas.width / scale, canvas.height / scale);\n      context.fillRect(0, 0, metrics.columns * metrics.cellWidth, metrics.rows * metrics.cellHeight);\n    }\n\n    if (!frame) {\n      return;\n    }\n\n    this.drawRows(context, frame, metrics, dirtyRegion);\n    this.drawImages(\n      context,\n      frame.images ?? [],\n      metrics,\n      dirtyRegion,\n      recoveredPayloadIds\n    );\n  }\n\n  private drawRows(\n    context: CanvasRenderingContext2D,\n    frame: WebHostSurfaceFrame,\n    metrics: CanvasSurfaceMetrics,\n    dirtyRegion?: DirtyRegion\n  ): void {\n    if (dirtyRegion) {\n      for (const [y, ranges] of dirtyRegion.rows) {\n        const row = frame.rows[y] ?? [];\n        this.drawRow(context, frame, metrics, row, y, ranges);\n      }\n      return;\n    }\n\n    for (let y = 0; y < frame.rows.length; y += 1) {\n      const row = frame.rows[y] ?? [];\n      this.drawRow(context, frame, metrics, row, y);\n    }\n  }\n\n  private drawRow(\n    context: CanvasRenderingContext2D,\n    frame: WebHostSurfaceFrame,\n    metrics: CanvasSurfaceMetrics,\n    row: WebHostSurfaceFrame[\"rows\"][number],\n    y: number,\n    ranges?: DirtyRowRanges\n  ): void {\n    for (const cell of row) {\n      const [x, text, span, styleIndex] = cell;\n      if (ranges !== undefined && !cellIntersectsRanges(x, span, ranges)) {\n        continue;\n      }\n      const style = frame.styles[styleIndex] ?? undefined;\n      this.drawCell(context, metrics, x, y, text, span, style);\n    }\n  }\n\n  private drawImages(\n    context: CanvasRenderingContext2D,\n    images: WebHostSurfaceImage[],\n    metrics: CanvasSurfaceMetrics,\n    dirtyRegion: DirtyRegion | undefined,\n    recoveredPayloadIds: Set<string>\n  ): void {\n    const missingPayloadIds = new Set<string>();\n    for (const image of images) {\n      if (!isPaintableSurfaceImage(image)) {\n        continue;\n      }\n      this.drawImage(\n        context,\n        image,\n        metrics,\n        dirtyRegion,\n        missingPayloadIds,\n        recoveredPayloadIds\n      );\n    }\n    this.reportImagePayloadMisses(missingPayloadIds);\n  }\n\n  private prepareImages(\n    images: WebHostSurfaceImage[],\n    recoveredPayloadIds: Set<string>\n  ): void {\n    const missingPayloadIds = new Set<string>();\n    for (const image of images) {\n      if (!isPaintableSurfaceImage(image)) {\n        continue;\n      }\n      this.cachedImage(image, missingPayloadIds, recoveredPayloadIds);\n    }\n    this.reportImagePayloadMisses(missingPayloadIds);\n  }\n\n  private drawImage(\n    context: CanvasRenderingContext2D,\n    image: WebHostSurfaceImage,\n    metrics: CanvasSurfaceMetrics,\n    dirtyRegion: DirtyRegion | undefined,\n    missingPayloadIds: Set<string>,\n    recoveredPayloadIds: Set<string>\n  ): void {\n    const [boundsX, boundsY, boundsWidth, boundsHeight] = image.bounds;\n    const [clipX, clipY, clipWidth, clipHeight] = image.visibleBounds;\n    if (boundsWidth <= 0 || boundsHeight <= 0 || clipWidth <= 0 || clipHeight <= 0) {\n      return;\n    }\n\n    const decodedImage = this.cachedImage(\n      image,\n      missingPayloadIds,\n      recoveredPayloadIds\n    );\n    if (!decodedImage) {\n      return;\n    }\n\n    if (\n      dirtyRegion\n      && !dirtyRegionIntersectsCellRect(dirtyRegion, clipX, clipY, clipWidth, clipHeight)\n    ) {\n      return;\n    }\n\n    context.save();\n    context.beginPath();\n    context.rect(\n      clipX * metrics.cellWidth,\n      clipY * metrics.cellHeight,\n      clipWidth * metrics.cellWidth,\n      clipHeight * metrics.cellHeight\n    );\n    context.clip();\n    context.drawImage(\n      decodedImage,\n      boundsX * metrics.cellWidth,\n      boundsY * metrics.cellHeight,\n      boundsWidth * metrics.cellWidth,\n      boundsHeight * metrics.cellHeight\n    );\n    context.restore();\n  }\n\n  private cachedImage(\n    image: WebHostSurfaceImage,\n    missingPayloadIds: Set<string>,\n    recoveredPayloadIds: Set<string>\n  ): CanvasImageSource | undefined {\n    let cached = this.imageCache.get(image.id);\n    if (cached?.image) {\n      return cached.image;\n    }\n\n    const beginsRecoveredGeneration = image.dataBase64 !== undefined\n      && recoveredPayloadIds.delete(image.id);\n    if (\n      image.dataBase64 !== undefined\n      && (cached?.payload === undefined || beginsRecoveredGeneration)\n    ) {\n      if (!this.canTrackUnresolvedImage(image.id, image.dataBase64)) {\n        return undefined;\n      }\n      cached = {\n        payload: image.dataBase64,\n        retries: 0,\n      };\n      this.setUnresolvedImage(image.id, cached);\n    } else if (!cached) {\n      if (!isWebHostImageRecoveryId(image.id)) {\n        return undefined;\n      }\n      if (!this.canTrackUnresolvedImage(image.id)) {\n        return undefined;\n      }\n      cached = { missReported: false };\n      this.setUnresolvedImage(image.id, cached);\n      missingPayloadIds.add(image.id);\n      return undefined;\n    }\n\n    const attempts = cached.retries ?? 0;\n    if (cached.payload === undefined) {\n      if (!cached.missReported) {\n        cached.missReported = true;\n        missingPayloadIds.add(image.id);\n      }\n      return undefined;\n    }\n    if (attempts >= MAX_IMAGE_DECODE_ATTEMPTS) {\n      if (!cached.missReported) {\n        cached.missReported = true;\n        missingPayloadIds.add(image.id);\n      }\n      return undefined;\n    }\n\n    if (!cached.promise) {\n      const nextAttempts = attempts + 1;\n      const promise = this.imageDecoder(cached.payload, image.format, image.id);\n      cached.promise = promise;\n      cached.retries = nextAttempts;\n      void promise.then((decodedImage) => {\n        const latest = this.imageCache.get(image.id);\n        if (latest?.promise !== promise) {\n          return;\n        }\n        this.removeUnresolvedImage(image.id);\n        this.imageCache.set(image.id, { image: decodedImage });\n        this.requestRedraw();\n      }).catch(() => {\n        const latest = this.imageCache.get(image.id);\n        if (latest?.promise !== promise) {\n          return;\n        }\n        latest.promise = undefined;\n        if (\n          (latest.retries ?? 0) >= MAX_IMAGE_DECODE_ATTEMPTS\n          && !latest.missReported\n        ) {\n          latest.missReported = true;\n          if (isWebHostImageRecoveryId(image.id)) {\n            this.scheduleImagePayloadMiss(image.id);\n          }\n        }\n        this.requestRedraw();\n      });\n    }\n\n    return undefined;\n  }\n\n  private canTrackUnresolvedImage(\n    id: string,\n    payload?: string\n  ): boolean {\n    const existing = this.imageCache.get(id);\n    const existingPayloadCharacters = existing?.image\n      ? 0\n      : existing?.payload?.length ?? 0;\n    const nextPayloadCharacters = this.unresolvedImagePayloadCharacters\n      - existingPayloadCharacters\n      + (payload?.length ?? 0);\n    return (\n      (this.unresolvedImageIds.has(id)\n        || this.unresolvedImageIds.size < MAX_UNRESOLVED_IMAGE_CACHE_ENTRIES)\n      && nextPayloadCharacters <= MAX_UNRESOLVED_IMAGE_PAYLOAD_CHARACTERS\n    );\n  }\n\n  private setUnresolvedImage(\n    id: string,\n    cached: CachedWebHostImage\n  ): void {\n    const existing = this.imageCache.get(id);\n    if (this.unresolvedImageIds.has(id)) {\n      this.unresolvedImagePayloadCharacters -= existing?.payload?.length ?? 0;\n    }\n    this.imageCache.set(id, cached);\n    this.unresolvedImageIds.add(id);\n    this.unresolvedImagePayloadCharacters += cached.payload?.length ?? 0;\n    this.pendingImagePayloadMissIds.delete(id);\n  }\n\n  private removeUnresolvedImage(\n    id: string\n  ): void {\n    if (!this.unresolvedImageIds.delete(id)) {\n      return;\n    }\n    this.unresolvedImagePayloadCharacters -=\n      this.imageCache.get(id)?.payload?.length ?? 0;\n    this.pendingImagePayloadMissIds.delete(id);\n  }\n\n  private sweepUnresolvedImages(\n    images: WebHostSurfaceImage[] | undefined\n  ): void {\n    const presentedIds = new Set<string>();\n    for (const image of images ?? []) {\n      if (!this.unresolvedImageIds.has(image.id)) {\n        continue;\n      }\n      if (isPaintableSurfaceImage(image)) {\n        presentedIds.add(image.id);\n      }\n    }\n    for (const id of this.unresolvedImageIds) {\n      if (presentedIds.has(id)) {\n        continue;\n      }\n      this.removeUnresolvedImage(id);\n      this.imageCache.delete(id);\n    }\n  }\n\n  private reportImagePayloadMisses(\n    ids: Set<string>\n  ): void {\n    if (ids.size === 0) {\n      return;\n    }\n    const candidateIds = [...ids].sort();\n    this.applyImagePayloadMissAdmission(\n      candidateIds,\n      this.onImagePayloadMiss(candidateIds)\n    );\n  }\n\n  private scheduleImagePayloadMiss(\n    id: string\n  ): void {\n    this.pendingImagePayloadMissIds.add(id);\n    if (this.imagePayloadMissScheduled) {\n      return;\n    }\n    this.imagePayloadMissScheduled = true;\n    queueMicrotask(() => {\n      this.imagePayloadMissScheduled = false;\n      const ids = [...this.pendingImagePayloadMissIds].sort();\n      this.pendingImagePayloadMissIds.clear();\n      if (ids.length > 0) {\n        this.applyImagePayloadMissAdmission(\n          ids,\n          this.onImagePayloadMiss(ids)\n        );\n      }\n    });\n  }\n\n  private applyImagePayloadMissAdmission(\n    candidateIds: readonly string[],\n    admittedIds: readonly string[] | void\n  ): void {\n    // Callbacks authored against the former void contract commonly use a\n    // concise `array.push(...)` body, whose runtime result is a number.\n    const acceptedIds = new Set(\n      Array.isArray(admittedIds) ? admittedIds : candidateIds\n    );\n    for (const id of candidateIds) {\n      const cached = this.imageCache.get(id);\n      if (cached && !cached.image) {\n        cached.missReported = acceptedIds.has(id);\n      }\n    }\n  }\n\n  private drawCell(\n    context: CanvasRenderingContext2D,\n    metrics: CanvasSurfaceMetrics,\n    x: number,\n    y: number,\n    text: string,\n    span: number,\n    style?: WebHostSurfaceStyle | null\n  ): void {\n    const rectX = x * metrics.cellWidth;\n    const rectY = y * metrics.cellHeight;\n    const width = Math.max(1, span) * metrics.cellWidth;\n    const background = resolvedSurfaceBackground(style, metrics.style);\n    const foreground = resolvedSurfaceForeground(style, metrics.style);\n    const opacity = style?.opacity ?? 1;\n\n    if (background) {\n      context.globalAlpha = opacity;\n      context.fillStyle = background;\n      context.fillRect(rectX, rectY, width, metrics.cellHeight);\n    }\n\n    if (text !== \" \") {\n      context.globalAlpha = opacity;\n      context.fillStyle = foreground;\n      context.strokeStyle = foreground;\n      if (!canRenderBoxDrawing(text) || !drawBoxDrawing(context, text, {\n        x: rectX,\n        y: rectY,\n        width,\n        height: metrics.cellHeight,\n      })) {\n        context.font = fontForStyle(metrics.style, style);\n        context.fillText(\n          text,\n          rectX,\n          rectY + Math.floor((metrics.cellHeight + metrics.style.fontSize) / 2) - 2\n        );\n      }\n    }\n\n    this.drawTextLine(context, metrics, rectX, rectY, width, style?.underline, \"underline\", foreground);\n    this.drawTextLine(context, metrics, rectX, rectY, width, style?.strikethrough, \"strike\", foreground);\n    context.globalAlpha = 1;\n  }\n\n  private dirtyRegionForDamage(\n    damage: WebHostSurfaceDamage | undefined,\n    frame: WebHostSurfaceFrame,\n    metrics: CanvasSurfaceMetrics\n  ): DirtyRegion | undefined {\n    if (!damage || damage.requiresFullTextRepaint || damage.requiresFullGraphicsReplay) {\n      return undefined;\n    }\n\n    const rects: DirtyRect[] = [];\n    const rows = new Map<number, DirtyRowRanges>();\n    for (const [row, ranges] of damage.textRows) {\n      if (row < 0 || row >= frame.height) {\n        continue;\n      }\n      if (ranges.length === 0) {\n        rects.push(cellRect(metrics, 0, row, frame.width));\n        rows.set(row, \"full\");\n        continue;\n      }\n      const rowRanges: DirtyCellRange[] = rows.get(row) === \"full\"\n        ? []\n        : [...(rows.get(row) as DirtyCellRange[] | undefined ?? [])];\n      for (const [start, end] of ranges) {\n        const lowerBound = Math.max(0, Math.min(frame.width, Math.floor(start)));\n        const upperBound = Math.max(lowerBound, Math.min(frame.width, Math.ceil(end)));\n        if (lowerBound >= upperBound) {\n          continue;\n        }\n        rects.push(cellRect(metrics, lowerBound, row, upperBound - lowerBound));\n        rowRanges.push({ start: lowerBound, end: upperBound });\n      }\n      if (rows.get(row) !== \"full\" && rowRanges.length > 0) {\n        rows.set(row, normalizeCellRanges(rowRanges));\n      }\n    }\n    return { rects, rows };\n  }\n\n  private drawTextLine(\n    context: CanvasRenderingContext2D,\n    metrics: CanvasSurfaceMetrics,\n    x: number,\n    y: number,\n    width: number,\n    line: WebHostSurfaceStyle[\"underline\"],\n    placement: \"underline\" | \"strike\",\n    fallbackColor: string\n  ): void {\n    if (!line) {\n      return;\n    }\n    context.strokeStyle = line.color ?? fallbackColor;\n    context.lineWidth = line.pattern === \"double\" ? 2 : 1;\n    if (line.pattern === \"dot\") {\n      context.setLineDash([1, 3]);\n    } else if (line.pattern === \"dash\") {\n      context.setLineDash([4, 3]);\n    } else {\n      context.setLineDash([]);\n    }\n\n    const lineY = placement === \"underline\"\n      ? y + metrics.cellHeight - 2\n      : y + Math.floor(metrics.cellHeight / 2);\n    context.beginPath();\n    context.moveTo(x, lineY);\n    context.lineTo(x + width, lineY);\n    context.stroke();\n    context.setLineDash([]);\n  }\n}\n\nfunction isPaintableSurfaceImage(\n  image: WebHostSurfaceImage\n): boolean {\n  const [, , boundsWidth, boundsHeight] = image.bounds;\n  const [, , clipWidth, clipHeight] = image.visibleBounds;\n  return isSupportedImageFormat(image.format)\n    && boundsWidth > 0\n    && boundsHeight > 0\n    && clipWidth > 0\n    && clipHeight > 0;\n}\n\n/**\n * The CSS font string for a cell, folding the surface emphasis bits (bold,\n * italic) over the host terminal's font size/family. Exposed so the host can\n * reuse the exact same metric when measuring cell dimensions.\n */\nexport function fontForStyle(\n  terminalStyle: ResolvedWebHostTerminalStyle,\n  style?: WebHostSurfaceStyle | null\n): string {\n  const emphasis = style?.em ?? 0;\n  const italic = (emphasis & 2) !== 0 ? \"italic \" : \"\";\n  const weight = (emphasis & 1) !== 0 ? \"700 \" : \"\";\n  return `${italic}${weight}${terminalStyle.fontSize}px ${terminalStyle.fontFamily}`;\n}\n\nfunction cellRect(\n  metrics: CanvasSurfaceMetrics,\n  x: number,\n  y: number,\n  span: number\n): DirtyRect {\n  return {\n    x: x * metrics.cellWidth,\n    y: y * metrics.cellHeight,\n    width: Math.max(1, span) * metrics.cellWidth,\n    height: metrics.cellHeight,\n  };\n}\n\nasync function decodeImage(\n  dataBase64: string,\n  format: NormalizedSurfaceImageFormat\n): Promise<CanvasImageSource> {\n  const bytes = decodeBase64Bytes(dataBase64);\n  const blob = new Blob([bytes], { type: `image/${format}` });\n\n  if (typeof createImageBitmap === \"function\") {\n    // Animated GIFs collapse to their first frame in createImageBitmap\n    // — that matches the Kitty path's first-frame composite. Phase 7\n    // will replace this with a frame ticker.\n    return createImageBitmap(blob);\n  }\n\n  return new Promise((resolve, reject) => {\n    const image = new Image();\n    const url = URL.createObjectURL(blob);\n    image.onload = () => {\n      URL.revokeObjectURL(url);\n      resolve(image);\n    };\n    image.onerror = () => {\n      URL.revokeObjectURL(url);\n      reject(new Error(`Failed to decode ${format} image`));\n    };\n    image.src = url;\n  });\n}\n\nfunction decodeBase64Bytes(\n  value: string\n): Uint8Array {\n  if (typeof atob === \"function\") {\n    const binary = atob(value);\n    const bytes = new Uint8Array(binary.length);\n    for (let index = 0; index < binary.length; index += 1) {\n      bytes[index] = binary.charCodeAt(index);\n    }\n    return bytes;\n  }\n\n  return new Uint8Array(Buffer.from(value, \"base64\"));\n}\n\nfunction normalizeCellRanges(\n  ranges: DirtyCellRange[]\n): DirtyCellRange[] {\n  const sorted = ranges\n    .filter((range) => range.end > range.start)\n    .sort((lhs, rhs) => lhs.start - rhs.start || lhs.end - rhs.end);\n  const normalized: DirtyCellRange[] = [];\n  for (const range of sorted) {\n    const previous = normalized[normalized.length - 1];\n    if (previous && range.start <= previous.end) {\n      previous.end = Math.max(previous.end, range.end);\n      continue;\n    }\n    normalized.push({ ...range });\n  }\n  return normalized;\n}\n\nfunction cellIntersectsRanges(\n  x: number,\n  span: number,\n  ranges: DirtyRowRanges\n): boolean {\n  if (ranges === \"full\") {\n    return true;\n  }\n  const start = Math.floor(x);\n  const end = start + Math.max(1, Math.ceil(span));\n  return ranges.some((range) => start < range.end && end > range.start);\n}\n\nfunction dirtyRegionIntersectsCellRect(\n  region: DirtyRegion,\n  x: number,\n  y: number,\n  width: number,\n  height: number\n): boolean {\n  const startRow = Math.max(0, Math.floor(y));\n  const endRow = Math.max(startRow, Math.ceil(y + height));\n  const rectRange = {\n    start: Math.floor(x),\n    end: Math.floor(x) + Math.max(1, Math.ceil(width)),\n  };\n  for (let row = startRow; row < endRow; row += 1) {\n    const ranges = region.rows.get(row);\n    if (!ranges) {\n      continue;\n    }\n    if (cellIntersectsRanges(rectRange.start, rectRange.end - rectRange.start, ranges)) {\n      return true;\n    }\n  }\n  return false;\n}\n"],"mappings":"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"}

package/dist/src/DomSurfacePainter.d.ts

@@ -1,6 +1,15 @@
-import { WebHostSurfaceDamage, WebHostSurfaceFrame } from "./WebHostSurfaceTransport.js";
+import { WebHostImagePayloadRequestHandler, WebHostSurfaceDamage, WebHostSurfaceFrame } from "./WebHostSurfaceTransport.js";
 import { SurfaceMetrics, WebHostSurfacePainter } from "./SurfaceRenderer.js";
 //#region src/DomSurfacePainter.d.ts
+interface DomSurfacePainterOptions {
+  /**
+   * Reports supported, positive-area image IDs absent from the retained DOM
+   * cache. Returning the admitted subset lets bounded transports keep overflow
+   * IDs eligible on the next presentation frame; `void` preserves legacy
+   * all-accepted behavior for custom hosts.
+   */
+  onImagePayloadMiss?: WebHostImagePayloadRequestHandler;
+}
 /**
  * Draws SwiftTUI surface frames as a DOM element tree instead of canvas
  * pixels: one absolutely positioned row container per grid row, one `<span>`
@@ -19,6 +28,7 @@ import { SurfaceMetrics, WebHostSurfacePainter } from "./SurfaceRenderer.js";
  * `letter-spacing`, measured once per font/size pair.
  */
 declare class DomSurfacePainter implements WebHostSurfacePainter {
+  private readonly onImagePayloadMiss;
   private root?;
   private rowsLayer?;
   private imagesLayer?;
@@ -28,12 +38,16 @@ declare class DomSurfacePainter implements WebHostSurfacePainter {
   private renderedGridKey?;
   private hasRenderedFrame;
   private letterSpacing?;
+  private reportedMissingImageIds;
+  private lastImageRecoveryFrame?;
+  private lastEpoch?;
+  constructor(options?: DomSurfacePainterOptions);
   /**
    * Binds the container the painter renders into. The runtime owns the
    * container's size; the painter owns everything inside it.
    */
   attach(root: HTMLElement): void;
-  paint(metrics: SurfaceMetrics, frame: WebHostSurfaceFrame | undefined, damage?: WebHostSurfaceDamage): void;
+  paint(metrics: SurfaceMetrics, frame: WebHostSurfaceFrame | undefined, damage?: WebHostSurfaceDamage, _recoveredImagePayloadIds?: readonly string[]): void;
   private rebuildRow;
   private ensureRowElement;
   private applyRootStyle;
@@ -47,5 +61,5 @@ declare class DomSurfacePainter implements WebHostSurfacePainter {
   private reconcileImages;
 }
 //#endregion
-export { DomSurfacePainter };
+export { DomSurfacePainter, DomSurfacePainterOptions };
 //# sourceMappingURL=DomSurfacePainter.d.ts.map

package/dist/src/DomSurfacePainter.js

@@ -1,6 +1,8 @@
 import { webTUITerminalBackgroundColor } from "./WebHostTerminalStyle.js";
+import { isWebHostImageRecoveryId } from "./WebHostSurfaceTransport.js";
 import { resolvedSurfaceBackground, resolvedSurfaceForeground } from "./SurfaceRenderer.js";
 import { isSupportedImageFormat, normalizeScalingMode } from "./normalizeWireTokens.js";
+import { registerDomSurfacePainterConformanceControl } from "./SurfacePainterConformanceControl.js";
 import { fontForStyle } from "./CanvasSurfacePainter.js";
 //#region src/DomSurfacePainter.ts
 /**
@@ -21,6 +23,7 @@ import { fontForStyle } from "./CanvasSurfacePainter.js";
 * `letter-spacing`, measured once per font/size pair.
 */
 var DomSurfacePainter = class {
+	onImagePayloadMiss;
 	root;
 	rowsLayer;
 	imagesLayer;
@@ -30,6 +33,22 @@ var DomSurfacePainter = class {
 	renderedGridKey;
 	hasRenderedFrame = false;
 	letterSpacing;
+	reportedMissingImageIds = /* @__PURE__ */ new Set();
+	lastImageRecoveryFrame;
+	lastEpoch;
+	constructor(options = {}) {
+		this.onImagePayloadMiss = options.onImagePayloadMiss ?? (() => {});
+		registerDomSurfacePainterConformanceControl(this, {
+			evictImages: (ids) => {
+				for (const id of ids) {
+					this.renderedImages.get(id)?.container.remove();
+					this.renderedImages.delete(id);
+					this.reportedMissingImageIds.delete(id);
+				}
+			},
+			visibleImageIDs: () => [...this.renderedImages.keys()].sort()
+		});
+	}
 	/**
 	* Binds the container the painter renders into. The runtime owns the
 	* container's size; the painter owns everything inside it.
@@ -51,11 +70,18 @@ var DomSurfacePainter = class {
 		this.appliedMetricsKey = void 0;
 		this.renderedGridKey = void 0;
 		this.hasRenderedFrame = false;
+		this.reportedMissingImageIds.clear();
+		this.lastImageRecoveryFrame = void 0;
+		this.lastEpoch = void 0;
 	}
-	paint(metrics, frame, damage) {
+	paint(metrics, frame, damage, _recoveredImagePayloadIds) {
 		const root = this.root;
 		const rowsLayer = this.rowsLayer;
 		if (!root || !rowsLayer) return;
+		if (frame?.epoch !== void 0 && frame.epoch !== this.lastEpoch) {
+			this.lastEpoch = frame.epoch;
+			this.reportedMissingImageIds.clear();
+		}
 		const metricsKey = metricsKeyFor(metrics);
 		const metricsChanged = metricsKey !== this.appliedMetricsKey;
 		if (metricsChanged) {
@@ -65,7 +91,8 @@ var DomSurfacePainter = class {
 		if (!frame) {
 			this.rowElements = [];
 			rowsLayer.replaceChildren();
-			this.reconcileImages([], metrics);
+			this.lastImageRecoveryFrame = void 0;
+			this.reconcileImages([], metrics, false);
 			this.renderedGridKey = void 0;
 			this.hasRenderedFrame = false;
 			return;
@@ -81,7 +108,9 @@ var DomSurfacePainter = class {
 			if (row < 0 || row >= frame.rows.length) continue;
 			this.rebuildRow(row, frame, metrics);
 		}
-		this.reconcileImages(frame.images ?? [], metrics);
+		const allowRecoveryRequests = frame !== this.lastImageRecoveryFrame;
+		this.lastImageRecoveryFrame = frame;
+		this.reconcileImages(frame.images ?? [], metrics, allowRecoveryRequests);
 		this.hasRenderedFrame = true;
 	}
 	rebuildRow(y, frame, metrics) {
@@ -143,10 +172,12 @@ var DomSurfacePainter = class {
 		};
 		return value;
 	}
-	reconcileImages(images, metrics) {
+	reconcileImages(images, metrics, allowRecoveryRequests) {
 		const layer = this.imagesLayer;
 		if (!layer) return;
 		const next = /* @__PURE__ */ new Map();
+		const currentMissingImageIds = /* @__PURE__ */ new Set();
+		const newlyMissingImageIds = /* @__PURE__ */ new Set();
 		for (const rawImage of images) {
 			if (!isSupportedImageFormat(rawImage.format)) continue;
 			const image = {
@@ -156,7 +187,13 @@ var DomSurfacePainter = class {
 			const [boundsX, boundsY, boundsWidth, boundsHeight] = image.bounds;
 			const [clipX, clipY, clipWidth, clipHeight] = image.visibleBounds;
 			const existing = this.renderedImages.get(image.id);
-			if (!existing && !image.dataBase64 || boundsWidth <= 0 || boundsHeight <= 0 || clipWidth <= 0 || clipHeight <= 0) continue;
+			if (boundsWidth <= 0 || boundsHeight <= 0 || clipWidth <= 0 || clipHeight <= 0) continue;
+			if (!existing && image.dataBase64 === void 0) {
+				if (!isWebHostImageRecoveryId(image.id)) continue;
+				currentMissingImageIds.add(image.id);
+				if (!this.reportedMissingImageIds.has(image.id)) newlyMissingImageIds.add(image.id);
+				continue;
+			}
 			const entry = existing ?? makeImageEntry();
 			entry.container.style.left = `${clipX * metrics.cellWidth}px`;
 			entry.container.style.top = `${clipY * metrics.cellHeight}px`;
@@ -178,6 +215,14 @@ var DomSurfacePainter = class {
 		}
 		for (const [id, entry] of this.renderedImages) if (!next.has(id)) entry.container.remove();
 		this.renderedImages = next;
+		for (const id of this.reportedMissingImageIds) if (!currentMissingImageIds.has(id)) this.reportedMissingImageIds.delete(id);
+		if (allowRecoveryRequests && newlyMissingImageIds.size > 0) {
+			const candidateIds = [...newlyMissingImageIds].sort();
+			const admittedIds = this.onImagePayloadMiss(candidateIds);
+			const acceptedIds = Array.isArray(admittedIds) ? admittedIds : candidateIds;
+			const candidates = new Set(candidateIds);
+			for (const id of acceptedIds) if (candidates.has(id)) this.reportedMissingImageIds.add(id);
+		}
 	}
 };
 /**