@neta-art/cohub 12.2.0 → 12.4.0

package/dist/board/stage/frame-budget.js

@@ -0,0 +1,69 @@
+//#region src/board/stage/frame-budget.ts
+const INITIAL = {
+	materialize: 48,
+	plate: 2400,
+	resolution: 32
+};
+const KINDS = Object.keys(INITIAL);
+const MIN_SHARE = 1 / 8;
+const LATE_FRAMES = 1.5;
+const MOVING_SHARE = .25;
+const RESTING_SHARE = .6;
+const COST_SMOOTHING = .3;
+const DEFAULT_INTERVAL = 1e3 / 60;
+const MIN_INTERVAL = 4;
+const INTERVAL_DRIFT = 1.01;
+const perKind = (value) => ({
+	materialize: value,
+	plate: value,
+	resolution: value
+});
+function fixedBoardFrameBudget() {
+	let done = perKind(0);
+	return {
+		allow: (kind) => Math.max(0, INITIAL[kind] - done[kind]),
+		spend(kind, units) {
+			done[kind] += units;
+		},
+		reset() {
+			done = perKind(0);
+		}
+	};
+}
+function createBoardFrameClock(now = () => performance.now()) {
+	let interval = DEFAULT_INTERVAL;
+	let previous = NaN;
+	let deadline = Number.POSITIVE_INFINITY;
+	let late = false;
+	const cost = perKind(0);
+	for (const kind of KINDS) cost[kind] = DEFAULT_INTERVAL * MOVING_SHARE / INITIAL[kind];
+	const last = perKind(0);
+	let done = perKind(0);
+	return {
+		get interval() {
+			return interval;
+		},
+		begin(frameTime, { moving, chained }) {
+			const delta = frameTime - previous;
+			previous = frameTime;
+			late = moving && chained && delta > interval * LATE_FRAMES;
+			if (chained && delta >= MIN_INTERVAL) interval = Math.min(interval * INTERVAL_DRIFT, delta);
+			deadline = now() + interval * (moving ? MOVING_SHARE : RESTING_SHARE);
+			for (const kind of KINDS) if (done[kind] > 0) last[kind] = done[kind];
+			done = perKind(0);
+		},
+		allow(kind) {
+			const floor = Math.ceil(INITIAL[kind] * MIN_SHARE);
+			const fit = Math.floor((deadline - now()) / cost[kind]);
+			const ceiling = late ? Math.floor(last[kind] / 2) : Math.max(INITIAL[kind], last[kind] * 2);
+			return Math.max(done[kind] === 0 ? floor : 0, Math.min(fit, ceiling - done[kind]));
+		},
+		spend(kind, units, ms) {
+			if (units <= 0) return;
+			done[kind] += units;
+			cost[kind] += (Math.max(ms, .001) / units - cost[kind]) * COST_SMOOTHING;
+		}
+	};
+}
+//#endregion
+export { createBoardFrameClock, fixedBoardFrameBudget };

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

@@ -0,0 +1,4 @@
+//#region src/board/stage/idle.d.ts
+declare function scheduleBoardIdle(task: () => void, delay: number): () => void;
+//#endregion
+export { scheduleBoardIdle };

package/dist/board/stage/idle.js

@@ -0,0 +1,26 @@
+//#region src/board/stage/idle.ts
+function scheduleBoardIdle(task, delay) {
+	const scheduler = globalThis.scheduler;
+	if (scheduler?.postTask) {
+		const controller = new AbortController();
+		scheduler.postTask(task, {
+			priority: "background",
+			delay,
+			signal: controller.signal
+		}).catch((error) => {
+			if (!controller.signal.aborted) throw error;
+		});
+		return () => controller.abort();
+	}
+	let idle = 0;
+	const timer = setTimeout(() => {
+		if (typeof requestIdleCallback === "function") idle = requestIdleCallback(task, { timeout: 1e3 });
+		else task();
+	}, delay);
+	return () => {
+		clearTimeout(timer);
+		if (idle) cancelIdleCallback(idle);
+	};
+}
+//#endregion
+export { scheduleBoardIdle };

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

@@ -1,10 +1,14 @@
 import { COMPACT_LRU_BUDGET, DEFAULT_LRU_BUDGET, LruBudget, LruEntry, LruTrim, planLruTrim, selectLruEvictions } from "./lru.js";
-import { BoardImageTexturePool, boardImageTexturePool, createBoardImageTexturePool, loadBoardImageTexture, loadFittedImageTexture, shrinkBoardTexture, unloadBoardImageTexture } from "./texture-pool.js";
-import { BoardAssetManager, BoardAssetManagerOptions, BoardModelPreviewRequest, BoardModelPreviews, createBoardAssetManager } from "./assets.js";
-import { toBoardPointerEvent } from "./pointer.js";
-import { createBoardPointerGestures } from "./pointer-gestures.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 { BOARD_LONG_PRESS_MS, BoardStagePress } from "./presses.js";
+import { BoardFrameBudget, BoardFrameWork } from "./frame-budget.js";
 import { BoardLiveStroke, BoardScene, BoardSceneNode, SceneSyncInput, createBoardScene } from "./scene.js";
 import { BoardItemView, BoardItemViewContext, BoardItemViewInstance, BoardItemViewLayer, createBoardItemViewLayer } from "./views.js";
 import { BoardStage, BoardStageOptions, BoardStagePointerPhase, BoardStageStats, BoardStageTheme, mountBoardStage } from "./stage.js";
+import { BOARD_BENCH_PHASES, BoardBenchPercentiles, BoardBenchPhase, BoardBenchPhaseReport, BoardBenchReport, BoardBenchSettle, runBoardStageBench } from "./bench.js";
+import { BOARD_DEVICE_TIERS, BoardDeviceBudget, BoardDeviceEnvironment, BoardDeviceSignals, BoardDeviceTier, boardDeviceBudget, boardDeviceTier, defaultBoardDeviceBudget, readBoardDeviceSignals } from "./device.js";
+import { toBoardPointerEvent } from "./pointer.js";
+import { createBoardPointerGestures } from "./pointer-gestures.js";
 import { BoardOverlayInput, drawBoardOverlay, expandFrame } from "./overlay.js";
-export { BoardAssetManager, BoardAssetManagerOptions, BoardImageTexturePool, BoardItemView, BoardItemViewContext, BoardItemViewInstance, BoardItemViewLayer, BoardLiveStroke, BoardModelPreviewRequest, BoardModelPreviews, BoardOverlayInput, BoardScene, BoardSceneNode, BoardStage, BoardStageOptions, BoardStagePointerPhase, BoardStageStats, BoardStageTheme, COMPACT_LRU_BUDGET, DEFAULT_LRU_BUDGET, LruBudget, LruEntry, LruTrim, SceneSyncInput, boardImageTexturePool, createBoardAssetManager, createBoardImageTexturePool, createBoardItemViewLayer, createBoardPointerGestures, createBoardScene, drawBoardOverlay, expandFrame, loadBoardImageTexture, loadFittedImageTexture, mountBoardStage, planLruTrim, selectLruEvictions, shrinkBoardTexture, toBoardPointerEvent, unloadBoardImageTexture };
+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 };

package/dist/board/stage/index.js

@@ -1,10 +1,13 @@
 import { COMPACT_LRU_BUDGET, DEFAULT_LRU_BUDGET, planLruTrim, selectLruEvictions } from "./lru.js";
-import { boardImageTexturePool, createBoardImageTexturePool, loadBoardImageTexture, loadFittedImageTexture, shrinkBoardTexture, unloadBoardImageTexture } from "./texture-pool.js";
+import { BOARD_DEVICE_TIERS, boardDeviceBudget, boardDeviceTier, defaultBoardDeviceBudget, readBoardDeviceSignals } from "./device.js";
+import { boardImageTexturePool, createBoardImageTexturePool, loadBoardImageTexture, loadFittedImageTexture, readTextureTone, shrinkBoardTexture, unloadBoardImageTexture } from "./texture-pool.js";
 import { createBoardAssetManager } from "./assets.js";
+import { BOARD_BENCH_PHASES, runBoardStageBench } from "./bench.js";
 import { toBoardPointerEvent } from "./pointer.js";
 import { createBoardPointerGestures } from "./pointer-gestures.js";
 import { createBoardScene } from "./scene.js";
+import { BOARD_LONG_PRESS_MS } from "./presses.js";
 import { drawBoardOverlay, expandFrame } from "./overlay.js";
 import { createBoardItemViewLayer } from "./views.js";
 import { mountBoardStage } from "./stage.js";
-export { COMPACT_LRU_BUDGET, DEFAULT_LRU_BUDGET, boardImageTexturePool, createBoardAssetManager, createBoardImageTexturePool, createBoardItemViewLayer, createBoardPointerGestures, createBoardScene, drawBoardOverlay, expandFrame, loadBoardImageTexture, loadFittedImageTexture, mountBoardStage, planLruTrim, selectLruEvictions, shrinkBoardTexture, toBoardPointerEvent, unloadBoardImageTexture };
+export { BOARD_BENCH_PHASES, BOARD_DEVICE_TIERS, BOARD_LONG_PRESS_MS, COMPACT_LRU_BUDGET, DEFAULT_LRU_BUDGET, 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/presses.d.ts

@@ -0,0 +1,21 @@
+//#region src/board/stage/presses.d.ts
+declare const BOARD_LONG_PRESS_MS = 450;
+type BoardStagePress = {
+  pointerId: number;
+  pointerType: string;
+  clientX: number;
+  clientY: number;
+};
+declare function boardStagePress(event: PointerEvent): BoardStagePress;
+declare function createBoardLongPress(fire: (press: BoardStagePress) => void): {
+  start(event: PointerEvent): void;
+  move(event: PointerEvent): void;
+  end(event: PointerEvent): void;
+  cancel: () => void;
+};
+declare function createGhostClickGuard(view: Window | null): {
+  arm(): void;
+  dispose: () => void | undefined;
+};
+//#endregion
+export { BOARD_LONG_PRESS_MS, BoardStagePress, boardStagePress, createBoardLongPress, createGhostClickGuard };

package/dist/board/stage/presses.js

@@ -0,0 +1,66 @@
+import "../editor/tool.js";
+//#region src/board/stage/presses.ts
+const BOARD_LONG_PRESS_MS = 450;
+const GHOST_CLICK_MS = 700;
+function boardStagePress(event) {
+	return {
+		pointerId: event.pointerId,
+		pointerType: event.pointerType,
+		clientX: event.clientX,
+		clientY: event.clientY
+	};
+}
+function createBoardLongPress(fire) {
+	let pending = null;
+	const cancel = () => {
+		if (pending) clearTimeout(pending.timer);
+		pending = null;
+	};
+	return {
+		start(event) {
+			if (pending) return cancel();
+			if (event.pointerType === "mouse" || event.button !== 0) return;
+			const press = boardStagePress(event);
+			pending = {
+				press,
+				timer: setTimeout(() => {
+					pending = null;
+					fire(press);
+				}, 450)
+			};
+		},
+		move(event) {
+			if (!pending || event.pointerId !== pending.press.pointerId) return;
+			const { clientX, clientY } = pending.press;
+			if (Math.hypot(event.clientX - clientX, event.clientY - clientY) > 8) cancel();
+		},
+		end(event) {
+			if (pending?.press.pointerId === event.pointerId) cancel();
+		},
+		cancel
+	};
+}
+function createGhostClickGuard(view) {
+	let disarm = null;
+	return {
+		arm() {
+			disarm?.();
+			if (!view) return;
+			const drop = (event) => {
+				event.preventDefault();
+				event.stopImmediatePropagation();
+				disarm?.();
+			};
+			const timer = setTimeout(() => disarm?.(), GHOST_CLICK_MS);
+			view.addEventListener("click", drop, true);
+			disarm = () => {
+				clearTimeout(timer);
+				view.removeEventListener("click", drop, true);
+				disarm = null;
+			};
+		},
+		dispose: () => disarm?.()
+	};
+}
+//#endregion
+export { BOARD_LONG_PRESS_MS, boardStagePress, createBoardLongPress, createGhostClickGuard };

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

@@ -5,6 +5,7 @@ import "../model/index.js";
 import { BoardLod } from "../render/lod.js";
 import { BoardCardRendererResolver, BoardRenderContext } from "../render/renderers/board-renderer-registry.js";
 import "../render/index.js";
+import { BoardFrameBudget } from "./frame-budget.js";
 import { Container, Graphics } from "pixi.js";
 //#region src/board/stage/scene.d.ts
 type BoardLiveStroke = {
@@ -32,6 +33,7 @@ type SceneSyncInput = {
   /** The world area on screen; live cards outside it skip rendering. */
   view?: Rect;
   lod?: BoardLod;
+  budget?: BoardFrameBudget;
 };
 type BoardSceneNode = {
   item: BoardSceneItem;
@@ -41,6 +43,7 @@ type BoardScene = {
   sync: (input: SceneSyncInput) => void;
   getNode: (itemId: string) => BoardSceneNode | null;
   holders: (key: string) => ReadonlySet<string>;
+  repaintFar: (keys: ReadonlySet<string>, assetKey: (item: BoardSceneItem) => string | null) => void;
   readonly liveVersion: number;
   liveIds: () => ReadonlySet<string>;
   /** Live cards and cards drawn on far plates. */
@@ -48,6 +51,7 @@ type BoardScene = {
     live: number;
     far: number;
   };
+  readonly settling: boolean;
   readonly animated: boolean;
   tick: (clock: number) => number | null;
   redrawText: () => void;

package/dist/board/stage/scene.js

@@ -1,16 +1,14 @@
 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 } from "../render/lod.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 { fixedBoardFrameBudget } from "./frame-budget.js";
 import { Graphics, Text } from "pixi.js";
 //#region src/board/stage/scene.ts
 const FAR_CHUNK = 256;
-const FAR_PAINT_BUDGET = 2400;
-const MATERIALIZE_BATCH = 48;
 const LOD_ZOOM_STEPS = 8;
-const RESOLUTION_BATCH = 32;
 const Z_LIFTED = 1e9;
 const Z_LIVE_STROKE = Number.MAX_SAFE_INTEGER - 1;
 const Z_OVERLAY = Number.MAX_SAFE_INTEGER;
@@ -47,6 +45,8 @@ function createBoardScene(options) {
 	const pendingResolution = /* @__PURE__ */ new Set();
 	let liveVersion = 0;
 	let lifted = /* @__PURE__ */ new Set();
+	const fixedBudget = fixedBoardFrameBudget();
+	let budget = fixedBudget;
 	const liveStrokes = /* @__PURE__ */ new Map();
 	function setHeldKey(context, cardId, item) {
 		const desiredKey = item ? context.assetKey(item) : null;
@@ -168,7 +168,7 @@ function createBoardScene(options) {
 	function lodSize(renderer, item) {
 		let size = lodSizes.get(item);
 		if (size === void 0) {
-			size = renderer.lod?.size?.(item) ?? Math.max(item.frame.width, item.frame.height);
+			size = boardLodSize(renderer, item);
 			lodSizes.set(item, size);
 		}
 		return size;
@@ -210,19 +210,20 @@ function createBoardScene(options) {
 				live.add(id);
 				continue;
 			}
-			if (lodSize(renderer, item) * context.zoom / lod[renderer.lod?.kind ?? "card"] >= (nearIds.has(id) ? .8 : 1)) near.push(item);
+			if (boardLodRatio(renderer, lodSize(renderer, item), context.zoom, lod) >= (nearIds.has(id) ? .8 : 1)) near.push(item);
 		}
 		const room = Math.max(0, lod.live - live.size);
 		const limited = near.length > room;
+		const allowance = budget.allow("materialize");
 		const { focus, view } = input;
-		const ranked = focus && (limited || near.length > MATERIALIZE_BATCH) ? near.map(({ id, frame }) => ({
+		const ranked = focus && (limited || near.length > allowance) ? near.map(({ id, frame }) => ({
 			id,
 			offscreen: view && !rectsIntersect(itemBounds(frame), view) ? 1 : 0,
 			distance: (frame.x + frame.width / 2 - focus.x) ** 2 + (frame.y + frame.height / 2 - focus.y) ** 2
 		})).sort((a, b) => a.offscreen - b.offscreen || a.distance - b.distance) : near;
 		let admitted = 0;
 		let deferred = false;
-		for (const { id } of ranked.slice(0, room)) if (!cards.has(id) && admitted++ >= MATERIALIZE_BATCH) deferred = true;
+		for (const { id } of ranked.slice(0, room)) if (!cards.has(id) && admitted++ >= allowance) deferred = true;
 		else live.add(id);
 		if (deferred) options.requestFrame?.();
 		nearIds = live;
@@ -255,6 +256,7 @@ function createBoardScene(options) {
 	const plates = /* @__PURE__ */ new Map();
 	let paintedPlan = null;
 	let paintedSig = "";
+	let platesPending = false;
 	let covered = EMPTY_IDS;
 	/**
 	* Repaint the plates whose cards changed, within a per-frame budget. A card
@@ -263,17 +265,19 @@ function createBoardScene(options) {
 	function paintPlates(input, current) {
 		const { context, globalSig, scene } = input;
 		if (current === paintedPlan && globalSig === paintedSig) return false;
-		let budget = FAR_PAINT_BUDGET;
+		const start = performance.now();
+		const allowance = budget.allow("plate");
+		let painted = 0;
 		let pending = false;
 		let changed = false;
 		for (const run of current.runs.values()) {
 			let plate = plates.get(run.key);
 			if (plate?.sig === globalSig && sameItems(plate.items, run.items)) continue;
-			if (budget <= 0) {
+			if (painted >= allowance) {
 				pending = true;
 				continue;
 			}
-			budget -= run.items.length;
+			painted += run.items.length;
 			if (!plate) {
 				plate = {
 					graphics: new Graphics({ label: "board-far-plate" }),
@@ -292,6 +296,7 @@ function createBoardScene(options) {
 			const host = hostFor(run.items[0], scene);
 			if (graphics.parent !== host) host.addChild(graphics);
 		}
+		const paintMs = performance.now() - start;
 		for (const [key, plate] of plates) {
 			if (current.runs.has(key)) continue;
 			plates.delete(key);
@@ -301,6 +306,8 @@ function createBoardScene(options) {
 		const next = /* @__PURE__ */ new Set();
 		for (const plate of plates.values()) for (const item of plate.items) next.add(item.id);
 		covered = next;
+		budget.spend("plate", painted, paintMs);
+		platesPending = pending;
 		if (pending) options.requestFrame?.();
 		else {
 			paintedPlan = current;
@@ -308,11 +315,19 @@ function createBoardScene(options) {
 		}
 		return changed;
 	}
+	function repaintFar(keys, assetKey) {
+		for (const plate of plates.values()) {
+			if (!plate.items.some((item) => keys.has(assetKey(item) ?? ""))) continue;
+			plate.sig = "";
+			paintedPlan = null;
+		}
+	}
 	function clearPlates() {
 		for (const plate of plates.values()) plate.graphics.destroy();
 		plates.clear();
 		paintedPlan = null;
 		paintedSig = "";
+		platesPending = false;
 		covered = EMPTY_IDS;
 		plan = null;
 		planInputs = [];
@@ -379,6 +394,8 @@ function createBoardScene(options) {
 	}
 	function sync(input) {
 		const { items, scene, context, getItem, pinnedIds, globalSig, structureVersion } = input;
+		fixedBudget.reset();
+		budget = input.budget ?? fixedBudget;
 		const resolution = `${textZoomBucket(context.zoom)}:${boardCardDetailed(context.zoom)}:${context.textResolution}`;
 		if (resolution !== lastResolution) {
 			lastResolution = resolution;
@@ -398,6 +415,8 @@ function createBoardScene(options) {
 		for (const id of current.live) wanted.add(id);
 		for (const id of cards.keys()) if (current.far.has(id) && !covered.has(id)) wanted.add(id);
 		let liveSetChanged = false;
+		let made = 0;
+		let making = 0;
 		for (const [id, entry] of [...cards]) if (!wanted.has(id)) {
 			recycle(id, entry, context, false);
 			liveSetChanged = true;
@@ -414,7 +433,10 @@ function createBoardScene(options) {
 				entry = void 0;
 			}
 			if (!entry) {
+				const start = performance.now();
 				materialize(item, context, globalSig, scene);
+				making += performance.now() - start;
+				made += 1;
 				liveSetChanged = true;
 				continue;
 			}
@@ -438,6 +460,7 @@ function createBoardScene(options) {
 				pendingResolution.delete(id);
 			}
 		}
+		budget.spend("materialize", made, making);
 		if (input.view) cullCards(input.view, pinnedIds);
 		refreshResolution(context);
 		if (liveSetChanged) liveVersion += 1;
@@ -469,15 +492,20 @@ function createBoardScene(options) {
 		for (const [id] of ids) pendingResolution.add(id);
 	}
 	function refreshResolution(context) {
-		let budget = RESOLUTION_BATCH;
+		if (pendingResolution.size === 0) return;
+		const start = performance.now();
+		const allowance = budget.allow("resolution");
+		let refreshed = 0;
 		for (const id of pendingResolution) {
-			if (budget-- === 0) break;
+			if (refreshed === allowance) break;
 			pendingResolution.delete(id);
 			const entry = cards.get(id);
 			if (!entry) continue;
 			entry.renderer.resolution?.(entry.container, entry.item, context);
 			if (entry.renderer.tick) tickingIds.add(id);
+			refreshed += 1;
 		}
+		budget.spend("resolution", refreshed, performance.now() - start);
 		if (pendingResolution.size) options.requestFrame?.();
 	}
 	function tick(clock) {
@@ -540,6 +568,7 @@ function createBoardScene(options) {
 			} : null;
 		},
 		holders: (key) => holders.get(key) ?? EMPTY_IDS,
+		repaintFar,
 		get liveVersion() {
 			return liveVersion;
 		},
@@ -548,6 +577,9 @@ function createBoardScene(options) {
 			live: cards.size,
 			far: covered.size
 		}),
+		get settling() {
+			return Boolean(plan?.deferred) || platesPending || pendingResolution.size > 0;
+		},
 		get animated() {
 			return animatedIds.size > 0;
 		},

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

@@ -7,7 +7,7 @@ import { BoardScene, BoardSceneItem } from "../model/scene.js";
 import { BoardShapeColors } from "../model/palette.js";
 import { BoardAssetSource } from "../model/media-playback.js";
 import "../model/index.js";
-import { BoardPointerEvent } from "../editor/interaction.js";
+import { BoardActivation, BoardPointerEvent } from "../editor/interaction.js";
 import { BoardEditor } from "../editor/editor.js";
 import "../editor/index.js";
 import { BoardRenderStyle } from "../render/style.js";
@@ -15,6 +15,7 @@ import { BoardLod } from "../render/lod.js";
 import { BoardCardRendererResolver, BoardRenderLabels, BoardRenderPalette } from "../render/renderers/board-renderer-registry.js";
 import "../render/index.js";
 import { BoardAssetManager } from "./assets.js";
+import { BoardStagePress } from "./presses.js";
 import { BoardLiveStroke } from "./scene.js";
 import { BoardItemView } from "./views.js";
 import { Graphics, Renderer } from "pixi.js";
@@ -34,6 +35,8 @@ type BoardStageOptions = {
   source: BoardAssetSource;
   renderers?: BoardCardRendererResolver;
   views?: readonly BoardItemView[];
+  /** `below` needs a theme with `imageBackground`; views there get no input. */
+  viewLayer?: "above" | "below";
   theme?: () => BoardStageTheme;
   labels?: () => BoardRenderLabels;
   taskRun?: (taskRunId: string) => {
@@ -51,6 +54,12 @@ type BoardStageOptions = {
     scene: BoardScene;
   }) => void;
   onPointer?: (phase: BoardStagePointerPhase, event: PointerEvent, input: BoardPointerEvent) => boolean | undefined;
+  onActivate?: (item: BoardSceneItem, activation: BoardActivation) => void;
+  onLongPress?: (item: BoardSceneItem, press: BoardStagePress) => void;
+  /** A press on a card key (`BoardCardRenderer.hitAt`); return false to leave it to the editor. */
+  onHit?: (item: BoardSceneItem, action: string, press: BoardStagePress) => boolean | undefined;
+  /** Card keys `onHit` acts on; others go to the editor. */
+  handlesHit?: (item: BoardSceneItem, action: string) => boolean;
   onDoubleClick?: (item: BoardSceneItem | null, point: WorldPoint) => boolean | undefined;
   onSurfaceChange?: (size: {
     width: number;
@@ -60,8 +69,8 @@ type BoardStageOptions = {
   onLiveChange?: (ids: ReadonlySet<string>) => void;
   safeRect?: () => Rect;
   scriptCapabilities?: Record<string, (id: string, input: unknown) => Promise<unknown>>;
-  /** Level-of-detail thresholds and live budget; read every frame. */
   lod?: () => BoardLod | undefined;
+  prefetch?: number;
 };
 type BoardStage = {
   readonly ready: Promise<boolean>;
@@ -92,6 +101,16 @@ type BoardStageStats = {
   textures: number;
   cooling: number;
   textureBytes: number;
+  loading: number;
+  prefetching: number;
+  waiting: number;
+  settling: boolean;
+  frame: {
+    p50: number;
+    p95: number;
+    max: number;
+  };
+  interval: number;
 };
 declare function mountBoardStage(host: HTMLElement, options: BoardStageOptions): BoardStage;
 //#endregion