@neta-art/cohub 12.5.0 → 13.0.0

package/dist/board/stage/assets.js

@@ -1,7 +1,7 @@
-import { probeMediaInfo } from "../../protocol/dist/core/media.js";
-import { MEDIA_VARIANT_SIZES, imageVariantUrl, variantSource } from "../../media.js";
+import { MEDIA_VARIANT_SIZES, fitsVideoFrames, imageVariantUrl, mediaHost, mediaVariantSize, variantSource, videoFrameUrl } from "../../protocol/dist/core/media.js";
+import { loadMediaInfo, loadMediaSize } from "../../media.js";
 import { boardModelFormat } from "../model/media.js";
-import { boardAssetKey, boardAssetKeySource, boardAssetRefKey } from "../model/asset-key.js";
+import { boardAssetKey, boardAssetKeySource, boardAssetRefKey, boardMediaNaturalSize } from "../model/asset-key.js";
 import { loadVideoThumbnailTexture, videoTextureNaturalSize } from "../render/video-thumbnail.js";
 import { planLruTrim } from "./lru.js";
 import { defaultBoardDeviceBudget } from "./device.js";
@@ -9,12 +9,43 @@ import { scheduleBoardIdle } from "./idle.js";
 import { boardImageTexturePool, loadBoardImageTexture, loadFittedImageTexture, readTextureTone, shrinkBoardTexture, unloadBoardImageTexture } from "./texture-pool.js";
 import { Texture } from "pixi.js";
 //#region src/board/stage/assets.ts
+const SMALLEST_VARIANT = MEDIA_VARIANT_SIZES[0];
 function variantUrl(source, edge, cover) {
 	if (!(edge <= 1536)) return null;
 	const url = imageVariantUrl(source, edge, cover ? "cover" : "contain");
 	return url && url !== source ? url : null;
 }
-const SMALLEST_VARIANT = MEDIA_VARIANT_SIZES[0];
+const frameAspects = /* @__PURE__ */ new Map();
+const FRAME_ASPECT_LIMIT = 2048;
+const FRAME_SLACK = 1.25;
+function learnAspect(source, { width, height }) {
+	if (!width || !height || frameAspects.has(source)) return;
+	frameAspects.set(source, width / height);
+	if (frameAspects.size > FRAME_ASPECT_LIMIT) frameAspects.delete(frameAspects.keys().next().value);
+}
+const FRAME_FACTS_WAIT_MS = 300;
+async function factSize(source) {
+	const timeout = new Promise((resolve) => setTimeout(resolve, FRAME_FACTS_WAIT_MS, null));
+	const info = await Promise.race([loadMediaInfo(source, "video"), timeout]);
+	return info?.width && info.height ? {
+		width: info.width,
+		height: info.height
+	} : void 0;
+}
+function frameUrl(source, edge, natural) {
+	return videoFrameUrl(source, mediaVariantSize(edge), {
+		natural,
+		aspect: natural ? null : frameAspects.get(source)
+	});
+}
+function textureMedia(media, url) {
+	return media === "video" && url && variantSource(url)?.type === "video" ? "image" : media;
+}
+function slotOf(media, source, frameless = false) {
+	return media === "video" && !frameless && videoFrameUrl(source, SMALLEST_VARIANT) ? "image" : media;
+}
+const FRAMELESS = /* @__PURE__ */ new Error("Video frame failed");
+const NO_PREVIEW = /* @__PURE__ */ new Error("No preview without decoding the video");
 function boundEdge({ width, height }, cover) {
 	return cover ? Math.min(width, height) : Math.max(width, height);
 }
@@ -62,7 +93,8 @@ function createBoardAssetManager(options) {
 		}
 		await unloadBoardImageTexture(url, texture);
 	});
-	function releaseTexture(media, url, texture) {
+	function releaseTexture(asset, url, texture) {
+		const media = textureMedia(asset, url);
 		const pendingKey = `${media}:${url}`;
 		const promise = unloadTexture(url, texture, media).catch(() => {}).then(() => {
 			if (url && pendingUnloads.get(pendingKey) === promise) pendingUnloads.delete(pendingKey);
@@ -78,11 +110,11 @@ function createBoardAssetManager(options) {
 		if (typeof requestAnimationFrame === "function") requestAnimationFrame(release);
 		else setTimeout(release, 0);
 	}
-	const resolveFileUrl = options.resolveFileUrl;
 	const entries = /* @__PURE__ */ new Map();
+	const keysByPath = /* @__PURE__ */ new Map();
 	const pathVersions = /* @__PURE__ */ new Map();
 	const starters = /* @__PURE__ */ new Map();
-	const failedModels = /* @__PURE__ */ new Set();
+	const unavailable = /* @__PURE__ */ new Set();
 	const queue = [];
 	const listeners = /* @__PURE__ */ new Set();
 	let active = 0;
@@ -92,6 +124,7 @@ function createBoardAssetManager(options) {
 		model: 0
 	};
 	let disposed = false;
+	let stopSource = null;
 	let focus = null;
 	let trimTimer = null;
 	let trimSince = 0;
@@ -131,27 +164,52 @@ function createBoardAssetManager(options) {
 		cancelTone = toneQueue.size > 0 ? scheduleBoardIdle(readNextTone, 0) : null;
 	}
 	const keys = /* @__PURE__ */ new WeakMap();
+	const itemEpochs = /* @__PURE__ */ new Map();
 	let keyEpoch = 0;
 	function managedAssetKey(item) {
-		const cached = keys.get(item);
-		if (cached?.epoch === keyEpoch) return cached.key;
-		const key = resolveAssetKey(item);
-		keys.set(item, {
-			epoch: keyEpoch,
-			key
-		});
-		return key;
+		const itemEpoch = itemEpochs.get(item.id) ?? 0;
+		let record = keys.get(item);
+		if (record?.epoch !== keyEpoch || record.itemEpoch !== itemEpoch) {
+			const { key: base, natural } = resolveAsset(item);
+			const source = base ? boardAssetKeySource(base) : null;
+			const path = source?.kind === "file" ? source.value : null;
+			record = {
+				epoch: keyEpoch,
+				itemEpoch,
+				base,
+				path,
+				version: 0,
+				key: base,
+				natural
+			};
+			keys.set(item, record);
+		}
+		if (record.path !== null) {
+			const version = pathVersions.get(record.path) ?? 0;
+			if (version !== record.version) {
+				record.version = version;
+				record.key = `local:${version}:${record.base}`;
+			}
+		}
+		return record.key;
 	}
-	function resolveAssetKey(item) {
+	function resolveAsset(item) {
 		const asset = options.itemAsset?.(item);
+		const natural = (asset === void 0 ? boardMediaNaturalSize(item) : asset?.natural) ?? null;
 		const key = asset === void 0 ? boardAssetKey(item) : asset && boardAssetRefKey(asset);
-		if (!key) return null;
-		const source = boardAssetKeySource(key);
-		if (source?.media === "video" && options.loadVideoPreviews === false) return null;
-		if (source?.media === "model" && !modelPreviewable(item)) return null;
-		if (source?.kind !== "file") return key;
-		const version = pathVersions.get(source.value) ?? 0;
-		return version > 0 ? `local:${version}:${key}` : key;
+		const source = key ? boardAssetKeySource(key) : null;
+		if (source?.media === "video" && source.kind === "url" && options.loadVideoPreviews === false && slotOf("video", source.value) === "video") return {
+			key: null,
+			natural
+		};
+		if (source?.media === "model" && !modelPreviewable(item)) return {
+			key: null,
+			natural
+		};
+		return {
+			key,
+			natural
+		};
 	}
 	function clearRetry(entry) {
 		if (entry.retryTimer) {
@@ -163,9 +221,11 @@ function createBoardAssetManager(options) {
 		let entry = entries.get(key);
 		if (!entry) {
 			const source = boardAssetKeySource(key);
+			const path = source?.kind === "file" ? source.value : null;
 			entry = {
 				media: source?.media ?? "image",
 				cover: source?.fit === "cover",
+				path,
 				source: null,
 				url: null,
 				texture: null,
@@ -177,11 +237,17 @@ function createBoardAssetManager(options) {
 				loading: false,
 				error: false,
 				attempts: 0,
+				frameless: false,
 				retryAt: 0,
 				retryTimer: null,
 				lastUsedAt: now()
 			};
 			entries.set(key, entry);
+			if (path !== null) {
+				const keyed = keysByPath.get(path);
+				if (keyed) keyed.add(key);
+				else keysByPath.set(path, /* @__PURE__ */ new Set([key]));
+			}
 		}
 		return entry;
 	}
@@ -203,6 +269,10 @@ function createBoardAssetManager(options) {
 		starters.delete(key);
 		if (entry.url || entry.texture) releaseTexture(entry.media, entry.url ?? "", entry.texture);
 		entries.delete(key);
+		if (entry.path === null) return;
+		const keyed = keysByPath.get(entry.path);
+		keyed?.delete(key);
+		if (keyed?.size === 0) keysByPath.delete(entry.path);
 	}
 	function scheduleTrim() {
 		const at = now();
@@ -214,8 +284,8 @@ function createBoardAssetManager(options) {
 			if (!disposed) trim();
 		}, TRIM_DELAY);
 	}
-	function shrunkFootprint({ media, texture }) {
-		if (!shrinkTexture || media !== "image" || !texture) return void 0;
+	function shrunkFootprint({ media, texture, url }) {
+		if (!shrinkTexture || textureMedia(media, url ?? "") !== "image" || !texture) return void 0;
 		const scale = SHRINK_EDGE / Math.max(texture.width, texture.height);
 		return scale < 1 ? Math.round(texture.width * scale) * Math.round(texture.height * scale) * 4 : void 0;
 	}
@@ -275,7 +345,9 @@ function createBoardAssetManager(options) {
 			entry.texture = texture;
 			entry.url = loaded.url;
 			entry.edge = loaded.edge;
-			if (loaded.edge === Number.POSITIVE_INFINITY && !variantSource(loaded.url)) entry.natural = videoTextureNaturalSize(texture) ?? {
+			const decoded = videoTextureNaturalSize(texture);
+			if (decoded) entry.natural = decoded;
+			else if (loaded.edge === Number.POSITIVE_INFINITY && !variantSource(loaded.url)) entry.natural = {
 				width: texture.width,
 				height: texture.height
 			};
@@ -292,23 +364,27 @@ function createBoardAssetManager(options) {
 			notify(key);
 			return;
 		}
-		const media = entry.media;
+		if (error === FRAMELESS && entry.source && entry.refs > 0) return enqueue(key, "video", textureLoad("video", entry.source));
+		const final = entry.media === "model" || error === NO_PREVIEW;
 		entry.error = true;
 		entry.attempts += 1;
 		entry.retryAt = now() + Math.min(1e3 * 2 ** entry.attempts, MAX_RETRY_DELAY);
-		console.warn(`[board] failed to load preview for ${key}`, error);
-		if (media === "model") failedModels.add(key);
+		if (error !== NO_PREVIEW) console.warn(`[board] failed to load preview for ${key}`, error);
+		if (final) unavailable.add(key);
 		if (entry.refs <= 0) evict(key, entry);
 		else {
-			if (media !== "model") scheduleRetry(key, entry);
+			if (!final) scheduleRetry(key, entry);
 			notify(key);
 		}
 	}
 	function refinable(key, entry) {
-		return entry.media === "image" && (entry.refs > 0 || warm.has(key)) && entry.texture !== null && entry.source !== null && entry.want > entry.edge;
+		if (entry.media === "model" || !(entry.refs > 0 || warm.has(key)) || !entry.texture || !entry.source || entry.want <= entry.edge) return false;
+		return entry.media === "image" || frameUrl(entry.source, entry.want, entry.natural) !== entry.url;
 	}
 	function refine(key, entry) {
-		if (refinable(key, entry) && !entry.loading && entry.source) enqueue(key, "image", textureLoad("image", entry.source));
+		if (entry.loading || !entry.source || entry.media === "model") return;
+		if (refinable(key, entry)) enqueue(key, slotOf(entry.media, entry.source, entry.frameless), textureLoad(entry.media, entry.source));
+		else if (entry.media === "video" && entry.natural === void 0 && entry.texture && boundEdge(entry.texture, false) < entry.want && !fitsVideoFrames(entry.source)) probeNaturalSize(key, entry, entry.source);
 	}
 	function enqueue(key, media, load) {
 		if (queue.some((task) => task.key === key)) return;
@@ -362,55 +438,79 @@ function createBoardAssetManager(options) {
 			task.load(entry).then((loaded) => done(loaded), (error) => done(null, error));
 		}
 	}
+	async function loadSized(entry, url, media, resized, slack = 2) {
+		const { cover, want: edge } = entry;
+		const pending = pendingUnloads.get(`${media}:${url}`);
+		if (pending) await pending;
+		if (disposed) return null;
+		const texture = await loadTexture(url, media);
+		if (!texture) return null;
+		const bound = boundEdge(texture, cover);
+		if (media === "image" && shrinkTexture && edge < bound / slack) {
+			const longEdge = Math.round(edge * Math.max(texture.width, texture.height) / bound);
+			const small = await shrinkTexture(texture, longEdge).catch(() => null);
+			if (small) {
+				releaseTexture(media, url, texture);
+				return {
+					texture: small,
+					url: "",
+					edge
+				};
+			}
+		}
+		return {
+			texture,
+			url,
+			edge: sharpEdge(texture, edge, resized, cover)
+		};
+	}
 	function textureLoad(media, source) {
 		return async (entry) => {
 			entry.source = source;
 			const { cover, want: edge } = entry;
-			const variant = media === "image" ? variantUrl(source, Math.max(edge, SMALLEST_VARIANT), cover) : null;
-			const url = variant ?? source;
-			const pending = pendingUnloads.get(`${media}:${url}`);
-			if (pending) await pending;
-			if (disposed) return null;
-			if (media === "image" && !variant && useSharedImagePool && Number.isFinite(edge)) {
-				const fitted = await loadFittedImageTexture(url, edge, cover).catch(() => null);
+			if (media === "video") {
+				if (entry.natural === void 0 && !entry.frameless && mediaHost(source)?.metaHeaders) entry.natural = await factSize(source);
+				const frame = entry.frameless ? null : frameUrl(source, edge, entry.natural);
+				if (frame) {
+					const loaded = await loadSized(entry, frame, "image", true, FRAME_SLACK).catch(() => null);
+					if (loaded) {
+						learnAspect(source, loaded.texture);
+						if (!entry.natural && !fitsVideoFrames(source) && loaded.edge === Number.POSITIVE_INFINITY) loaded.edge = boundEdge(loaded.texture, false);
+					}
+					if (loaded || entry.texture) return loaded;
+					entry.frameless = true;
+					throw FRAMELESS;
+				}
+				if (options.loadVideoPreviews === false) throw NO_PREVIEW;
+				return loadSized(entry, source, "video", false);
+			}
+			const variant = variantUrl(source, Math.max(edge, SMALLEST_VARIANT), cover);
+			if (!variant && useSharedImagePool && Number.isFinite(edge)) {
+				const fitted = await loadFittedImageTexture(source, edge, cover).catch(() => null);
 				if (fitted) return {
 					texture: fitted,
 					url: "",
 					edge: sharpEdge(fitted, edge, true, cover)
 				};
 			}
-			const texture = await loadTexture(url, media);
-			if (!texture) return null;
-			const bound = boundEdge(texture, cover);
-			if (media === "image" && shrinkTexture && edge < bound / 2) {
-				const longEdge = Math.round(edge * Math.max(texture.width, texture.height) / bound);
-				const small = await shrinkTexture(texture, longEdge).catch(() => null);
-				if (small) {
-					releaseTexture(media, url, texture);
-					return {
-						texture: small,
-						url: "",
-						edge
-					};
-				}
-			}
-			return {
-				texture,
-				url,
-				edge: sharpEdge(texture, edge, Boolean(variant), cover)
-			};
+			return loadSized(entry, variant ?? source, "image", Boolean(variant));
 		};
 	}
-	function resolveFile(key, media, path) {
+	function startFile(key, media, path) {
 		return (entry) => {
 			const fresh = entry.attempts > 0;
 			entry.loading = true;
-			resolveFileUrl(path, fresh ? { fresh } : void 0).then((url) => {
+			options.resolveFile(path, fresh ? { fresh } : void 0).then((file) => {
 				if (disposed || entries.get(key) !== entry) return;
 				if (entry.refs <= 0 && !warm.has(key)) return evict(key, entry);
-				if (!url) return adopt(key, entry, null, /* @__PURE__ */ new Error(`Unavailable file: ${path}`));
+				if (!file) return adopt(key, entry, null, /* @__PURE__ */ new Error(`Unavailable file: ${path}`));
+				const { url, media: facts } = file;
+				if (facts && !entry.natural) entry.natural = {
+					width: facts.width,
+					height: facts.height
+				};
 				entry.loading = false;
-				enqueue(key, media, textureLoad(media, url));
+				enqueue(key, slotOf(media, url, entry.frameless), textureLoad(media, url));
 			}, (error) => {
 				if (!disposed) adopt(key, entry, null, error);
 			});
@@ -418,12 +518,10 @@ function createBoardAssetManager(options) {
 	}
 	function probeNaturalSize(key, entry, source) {
 		entry.natural = null;
-		probeMediaInfo(source, { type: "image" }).then(({ width, height }) => {
-			if (disposed || entries.get(key) !== entry || !width || !height) return;
-			entry.natural = {
-				width,
-				height
-			};
+		loadMediaSize(source, entry.media === "video" ? "video" : "image").then((size) => {
+			if (disposed || entries.get(key) !== entry || !size) return;
+			entry.natural = size;
+			refine(key, entry);
 			notify(key);
 		});
 	}
@@ -457,34 +555,36 @@ function createBoardAssetManager(options) {
 			return load ? () => enqueue(key, "model", load) : null;
 		}
 		const media = source.media;
-		if (source.kind === "file") return resolveFile(key, media, source.value);
+		if (source.kind === "file") return startFile(key, media, source.value);
 		const load = textureLoad(media, source.value);
-		return () => enqueue(key, media, load);
+		return (entry) => enqueue(key, slotOf(media, source.value, entry.frameless), load);
 	}
 	const manager = {
 		assetKey: managedAssetKey,
 		invalidatePath(path) {
-			if (disposed) return;
-			const stale = [...entries.keys()].filter((key) => {
-				const source = boardAssetKeySource(key);
-				return source?.kind === "file" && source.value === path;
-			});
-			if (stale.length === 0) return;
+			const stale = keysByPath.get(path);
+			if (disposed || !stale) return;
 			pathVersions.set(path, (pathVersions.get(path) ?? 0) + 1);
-			keyEpoch += 1;
-			for (const key of stale) notify(key);
+			for (const key of [...stale]) notify(key);
 		},
-		invalidateItemAssets() {
-			if (options.itemAsset) keyEpoch += 1;
+		invalidateItemAssets(ids) {
+			if (!options.itemAsset) return;
+			if (!ids) {
+				keyEpoch += 1;
+				itemEpochs.clear();
+				return;
+			}
+			for (const id of ids) itemEpochs.set(id, (itemEpochs.get(id) ?? 0) + 1);
 		},
 		requestItem(item, edge = Number.POSITIVE_INFINITY) {
 			if (disposed) return;
 			const key = managedAssetKey(item);
-			if (!key || failedModels.has(key)) return;
+			if (!key || unavailable.has(key)) return;
 			const source = boardAssetKeySource(key);
 			if (!source) return;
 			const entry = ensureEntry(key);
 			entry.lastUsedAt = now();
+			if (!entry.natural) entry.natural = keys.get(item)?.natural ?? entry.natural;
 			entry.center = {
 				x: item.frame.x + item.frame.width / 2,
 				y: item.frame.y + item.frame.height / 2
@@ -659,6 +759,7 @@ function createBoardAssetManager(options) {
 		},
 		destroy() {
 			disposed = true;
+			stopSource?.();
 			if (trimTimer !== null) clearTimeout(trimTimer);
 			trimTimer = null;
 			cancelTone?.();
@@ -669,13 +770,15 @@ function createBoardAssetManager(options) {
 			unwarmable.clear();
 			listeners.clear();
 			pathVersions.clear();
+			itemEpochs.clear();
 			starters.clear();
-			failedModels.clear();
+			unavailable.clear();
 			for (const [key, entry] of entries) evict(key, entry);
 			entries.clear();
 			for (const release of [...retiring]) release();
 		}
 	};
+	stopSource = options.subscribe?.((path) => manager.invalidatePath(path)) ?? null;
 	return manager;
 }
 //#endregion

package/dist/board/stage/backdrop.d.ts

@@ -0,0 +1,25 @@
+import { BoardAssetSource } from "../model/media-playback.js";
+import "../model/index.js";
+import { BoardBackdrop } from "../render/backdrop.js";
+import { BoardBackdropView } from "../render/backdrop-layer.js";
+import "../render/index.js";
+import { BoardImageTexturePool } from "./texture-pool.js";
+import { Renderer } from "pixi.js";
+//#region src/board/stage/backdrop.d.ts
+type BoardBackdropStatus = {
+  src: string;
+  status: "loading" | "ready" | "error";
+};
+declare function createBoardStageBackdrop(options: {
+  renderer: Renderer;
+  source: BoardAssetSource;
+  pool?: BoardImageTexturePool;
+  requestFrame: () => void;
+  onStatus?: (status: BoardBackdropStatus | null) => void;
+}): {
+  container: import("pixi.js").Container<import("pixi.js").ContainerChild>;
+  sync(backdrop: BoardBackdrop, view: BoardBackdropView, reducedMotion: boolean): void;
+  destroy(): void;
+};
+//#endregion
+export { BoardBackdropStatus, createBoardStageBackdrop };

package/dist/board/stage/backdrop.js

@@ -0,0 +1,104 @@
+import { imageVariantUrl, mediaVariantSize } from "../../protocol/dist/core/media.js";
+import { parseBoardMediaSource } from "../../protocol/dist/board-model.js";
+import { createBoardBackdropLayer } from "../render/backdrop-layer.js";
+import { boardImageTexturePool } from "./texture-pool.js";
+import { RendererType } from "pixi.js";
+//#region src/board/stage/backdrop.ts
+const FADE_MS = 160;
+const RETRY_MIN_MS = 2e3;
+const RETRY_MAX_MS = 32e3;
+function createBoardStageBackdrop(options) {
+	const layer = createBoardBackdropLayer({ patterns: options.renderer.type === RendererType.WEBGL });
+	const pool = options.pool ?? boardImageTexturePool;
+	let loadKey = null;
+	let file = null;
+	let held = null;
+	let texture = null;
+	let readyAt = 0;
+	let generation = 0;
+	let retry = null;
+	const reload = () => {
+		loadKey = null;
+		options.requestFrame();
+	};
+	const stopFiles = options.source.subscribe?.((path) => {
+		if (path === file) reload();
+	});
+	function retryLater(key) {
+		const delay = retry?.key === key ? retry.delay * 2 : RETRY_MIN_MS;
+		stopRetry();
+		if (delay <= RETRY_MAX_MS) retry = {
+			key,
+			delay,
+			timer: setTimeout(reload, delay)
+		};
+	}
+	function stopRetry() {
+		if (retry) clearTimeout(retry.timer);
+		retry = null;
+	}
+	function show(key, next) {
+		if (held) pool.release(held);
+		if (next && !texture) readyAt = performance.now();
+		held = key;
+		texture = next;
+	}
+	function edgeFor(image, view) {
+		if (image.fit !== "repeat") return Math.max(view.width, view.height) * view.density;
+		return image.tile ? Math.max(image.tile.width, image.tile.height) * view.density : Number.POSITIVE_INFINITY;
+	}
+	async function load(image, edge, current, attempt) {
+		const report = (status) => {
+			if (current === generation) options.onStatus?.({
+				src: image.src,
+				status
+			});
+		};
+		report("loading");
+		const source = parseBoardMediaSource(image.src);
+		file = source?.kind === "file" ? source.value : null;
+		const url = file ? await options.source.resolveFile(file).then((resolved) => resolved?.url ?? null, () => null) : image.src;
+		if (current !== generation) return;
+		const fit = image.fit === "cover" ? "cover" : "contain";
+		const key = url && (edge <= 1536 && imageVariantUrl(url, mediaVariantSize(edge), fit) || url);
+		const loaded = key ? await pool.acquire(key).catch(() => null) : null;
+		if (current !== generation) {
+			if (key && loaded) pool.release(key);
+			return;
+		}
+		show(loaded ? key : null, loaded);
+		report(loaded ? "ready" : "error");
+		if (loaded) stopRetry();
+		else retryLater(attempt);
+		options.requestFrame();
+	}
+	return {
+		container: layer.container,
+		sync(backdrop, view, reducedMotion) {
+			const next = backdrop.image ? `${backdrop.image.fit} ${backdrop.image.src}` : null;
+			if (next !== loadKey) {
+				loadKey = next;
+				generation += 1;
+				if (retry && retry.key !== next) stopRetry();
+				if (backdrop.image && next) load(backdrop.image, edgeFor(backdrop.image, view), generation, next);
+				else {
+					file = null;
+					show(null, null);
+					options.onStatus?.(null);
+				}
+			}
+			const fade = reducedMotion ? 1 : Math.min(1, (performance.now() - readyAt) / FADE_MS);
+			layer.sync(backdrop, view, texture, fade);
+			if (texture && fade < 1) options.requestFrame();
+		},
+		destroy() {
+			generation += 1;
+			stopRetry();
+			stopFiles?.();
+			show(null, null);
+			layer.destroy();
+		}
+	};
+}
+//#endregion
+export { createBoardStageBackdrop };

package/dist/board/stage/index.d.ts

@@ -1,6 +1,7 @@
 import { COMPACT_LRU_BUDGET, DEFAULT_LRU_BUDGET, LruBudget, LruEntry, LruTrim, planLruTrim, selectLruEvictions } from "./lru.js";
 import { BoardImageTexturePool, boardImageTexturePool, createBoardImageTexturePool, loadBoardImageTexture, loadFittedImageTexture, readTextureTone, shrinkBoardTexture, unloadBoardImageTexture } from "./texture-pool.js";
 import { BoardAssetChange, BoardAssetManager, BoardAssetManagerOptions, BoardAssetPrefetch, BoardModelPreviewRequest, BoardModelPreviews, createBoardAssetManager } from "./assets.js";
+import { BoardBackdropStatus } from "./backdrop.js";
 import { BOARD_LONG_PRESS_MS, BoardStagePress } from "./presses.js";
 import { BoardFrameBudget, BoardFrameWork } from "./frame-budget.js";
 import { BoardLiveStroke, BoardScene, BoardSceneNode, SceneSyncInput, createBoardScene } from "./scene.js";
@@ -11,4 +12,4 @@ import { BOARD_DEVICE_TIERS, BoardDeviceBudget, BoardDeviceEnvironment, BoardDev
 import { toBoardPointerEvent } from "./pointer.js";
 import { createBoardPointerGestures } from "./pointer-gestures.js";
 import { BoardOverlayInput, drawBoardOverlay, expandFrame } from "./overlay.js";
-export { BOARD_BENCH_PHASES, BOARD_DEVICE_TIERS, BOARD_LONG_PRESS_MS, BoardAssetChange, BoardAssetManager, BoardAssetManagerOptions, BoardAssetPrefetch, BoardBenchPercentiles, BoardBenchPhase, BoardBenchPhaseReport, BoardBenchReport, BoardBenchSettle, BoardDeviceBudget, BoardDeviceEnvironment, BoardDeviceSignals, BoardDeviceTier, type BoardFrameBudget, type BoardFrameWork, BoardImageTexturePool, BoardItemView, BoardItemViewContext, BoardItemViewInstance, BoardItemViewLayer, BoardLiveStroke, BoardModelPreviewRequest, BoardModelPreviews, BoardOverlayInput, BoardScene, BoardSceneNode, BoardStage, BoardStageOptions, BoardStagePointerPhase, type BoardStagePress, BoardStageStats, BoardStageTheme, COMPACT_LRU_BUDGET, DEFAULT_LRU_BUDGET, LruBudget, LruEntry, LruTrim, SceneSyncInput, boardDeviceBudget, boardDeviceTier, boardImageTexturePool, createBoardAssetManager, createBoardImageTexturePool, createBoardItemViewLayer, createBoardPointerGestures, createBoardScene, defaultBoardDeviceBudget, drawBoardOverlay, expandFrame, loadBoardImageTexture, loadFittedImageTexture, mountBoardStage, planLruTrim, readBoardDeviceSignals, readTextureTone, runBoardStageBench, selectLruEvictions, shrinkBoardTexture, toBoardPointerEvent, unloadBoardImageTexture };
+export { BOARD_BENCH_PHASES, BOARD_DEVICE_TIERS, BOARD_LONG_PRESS_MS, BoardAssetChange, BoardAssetManager, BoardAssetManagerOptions, BoardAssetPrefetch, type BoardBackdropStatus, BoardBenchPercentiles, BoardBenchPhase, BoardBenchPhaseReport, BoardBenchReport, BoardBenchSettle, BoardDeviceBudget, BoardDeviceEnvironment, BoardDeviceSignals, BoardDeviceTier, type BoardFrameBudget, type BoardFrameWork, BoardImageTexturePool, BoardItemView, BoardItemViewContext, BoardItemViewInstance, BoardItemViewLayer, BoardLiveStroke, BoardModelPreviewRequest, BoardModelPreviews, BoardOverlayInput, BoardScene, BoardSceneNode, BoardStage, BoardStageOptions, BoardStagePointerPhase, type BoardStagePress, BoardStageStats, BoardStageTheme, COMPACT_LRU_BUDGET, DEFAULT_LRU_BUDGET, LruBudget, LruEntry, LruTrim, SceneSyncInput, boardDeviceBudget, boardDeviceTier, boardImageTexturePool, createBoardAssetManager, createBoardImageTexturePool, createBoardItemViewLayer, createBoardPointerGestures, createBoardScene, defaultBoardDeviceBudget, drawBoardOverlay, expandFrame, loadBoardImageTexture, loadFittedImageTexture, mountBoardStage, planLruTrim, readBoardDeviceSignals, readTextureTone, runBoardStageBench, selectLruEvictions, shrinkBoardTexture, toBoardPointerEvent, unloadBoardImageTexture };

package/dist/board/stage/scene.js

@@ -1,9 +1,9 @@
 import { parseBoardItem } from "../../protocol/dist/board-model.js";
 import { drawPointsBounds } from "../../protocol/dist/board-layout.js";
 import { itemBounds, rectsIntersect } from "../model/geometry.js";
-import { DEFAULT_BOARD_LOD, boardCardDetailed, boardLodRatio, boardLodSize } from "../render/lod.js";
 import { textZoomBucket } from "../render/text-resolution.js";
 import { clippingAncestor, isClippingFrame, syncClipGroup } from "../render/clip.js";
+import { DEFAULT_BOARD_LOD, boardCardDetailed, boardLodRatio, boardLodSize } from "../render/lod.js";
 import { fixedBoardFrameBudget } from "./frame-budget.js";
 import { Graphics, Text } from "pixi.js";
 //#region src/board/stage/scene.ts
@@ -14,6 +14,7 @@ const Z_LIVE_STROKE = Number.MAX_SAFE_INTEGER - 1;
 const Z_OVERLAY = Number.MAX_SAFE_INTEGER;
 const POOL_LIMIT_PER_RENDERER = 48;
 const EMPTY_IDS = /* @__PURE__ */ new Set();
+const NO_PLATES = /* @__PURE__ */ new Map();
 function idSetSignature(ids) {
 	let hash = ids.size;
 	for (const id of ids) {
@@ -257,13 +258,19 @@ function createBoardScene(options) {
 	let paintedPlan = null;
 	let paintedSig = "";
 	let platesPending = false;
-	let covered = EMPTY_IDS;
+	let covered = NO_PLATES;
 	/**
 	* Repaint the plates whose cards changed, within a per-frame budget. A card
 	* is covered once a plate draws it; until then it stays live if it already is.
 	*/
 	function paintPlates(input, current) {
 		const { context, globalSig, scene } = input;
+		for (const id of input.staleIds ?? EMPTY_IDS) {
+			const plate = covered.get(id);
+			if (!plate) continue;
+			plate.sig = "";
+			paintedPlan = null;
+		}
 		if (current === paintedPlan && globalSig === paintedSig) return false;
 		const start = performance.now();
 		const allowance = budget.allow("plate");
@@ -303,8 +310,8 @@ function createBoardScene(options) {
 			plate.graphics.destroy();
 			changed = true;
 		}
-		const next = /* @__PURE__ */ new Set();
-		for (const plate of plates.values()) for (const item of plate.items) next.add(item.id);
+		const next = /* @__PURE__ */ new Map();
+		for (const plate of plates.values()) for (const item of plate.items) next.set(item.id, plate);
 		covered = next;
 		budget.spend("plate", painted, paintMs);
 		platesPending = pending;
@@ -328,7 +335,7 @@ function createBoardScene(options) {
 		paintedPlan = null;
 		paintedSig = "";
 		platesPending = false;
-		covered = EMPTY_IDS;
+		covered = NO_PLATES;
 		plan = null;
 		planInputs = [];
 		nearIds = EMPTY_IDS;