@simpludify/web 0.1.7 → 0.2.0

package/dist/index.js

@@ -1,5 +1,5 @@
 import "./style.css";
-import { ActionController, Aspect, Camera, CanvasButton as CanvasButton$1, CanvasUI, Engine, EngineError, EventBus, FixedStepRunner, GamepadAxis, GamepadBindings, GamepadButton, GeometryTilemapLayer, InputCapture, InputCaptureState, InputDevice, Lifetime, MouseButton, PointerRouting, Renderable, ReplayPlayer, Scene, ScenePointer, SceneState, Shape, TilemapLayer, Transform, VirtualInput, canvasControlText, canvasHoverHighlight, canvasOpacity, canvasScrollbars, canvasSliderGeometry, checkedGamepadBindings, cleanupAll, containsScreenPoint, createViewTransform, defineEvent, gamepadDeadZone, gamepadIndex, imageSize, intersectUI, isKeyCode, isMouseButton, positive, screenPoint, screenToWorld, spriteFrameBounds, worldToScreen, wrapCanvasText } from "@simpludify/core";
+import { ActionController, Aspect, Camera, CanvasButton as CanvasButton$1, CanvasUI, Engine, EngineError, EventBus, FixedStepRunner, GamepadAxis, GamepadBindings, GamepadButton, GeometryTilemapLayer, InputCapture, InputCaptureState, InputDevice, Lifetime, Logger, MouseButton, PointerRouting, Renderable, ReplayPlayer, Scene, ScenePointer, SceneState, Shape, TilemapLayer, Transform, VirtualInput, canvasControlText, canvasHoverHighlight, canvasOpacity, canvasScrollbars, canvasSliderGeometry, checkedGamepadBindings, cleanupAll, containsScreenPoint, createViewTransform, defaultCanvasStyle, defineEvent, gamepadDeadZone, gamepadIndex, imageSize, intersectUI, isKeyCode, isMouseButton, positive, screenPoint, screenToWorld, spriteFrameBounds, worldToScreen, wrapCanvasText } from "@simpludify/core";
 import { Application, CanvasTextMetrics, Container, Graphics, Rectangle, RendererType, Sprite, Text, TextStyle, Texture } from "pixi.js";
 export * from "@simpludify/core";
 // packages/web/src/canvas-node.ts
@@ -17,6 +17,1222 @@ function CanvasButton(text, click, style = {}) {
 		return click(signal);
 	}, style);
 }
+// packages/web/src/shared-images.ts
+/** Renderer-local, live-reference cache. No idle retention or process-global state. */
+var SharedImages = class {
+	load;
+	entries = /* @__PURE__ */ new Map();
+	loaded = 0;
+	references = 0;
+	dead = false;
+	constructor(load) {
+		this.load = load;
+	}
+	get diagnostics() {
+		let pending = 0;
+		for (const entry of this.entries.values()) if (!entry.resource) pending++;
+		return {
+			imageReferences: this.references,
+			imageEntries: this.entries.size,
+			pendingImages: pending
+		};
+	}
+	get textures() {
+		return this.loaded;
+	}
+	acquire(key, signal, request) {
+		const url = request?.url ?? String(key);
+		const cancelled = () => new EngineError("GAME_DISPOSED", "Image use cancelled", { path: url });
+		if (this.dead || signal.aborted) return Promise.reject(cancelled());
+		let entry = this.entries.get(key);
+		const fresh = !entry;
+		if (!entry) {
+			entry = {
+				controller: new AbortController(),
+				consumers: /* @__PURE__ */ new Set(),
+				frames: /* @__PURE__ */ new Map()
+			};
+			this.entries.set(key, entry);
+		}
+		const current = entry;
+		const promise = new Promise((resolve, reject) => {
+			let released = false, settled = false;
+			const release = () => {
+				if (released) return;
+				released = true;
+				signal.removeEventListener("abort", release);
+				current.consumers.delete(consumer);
+				this.references--;
+				if (!settled) {
+					settled = true;
+					reject(cancelled());
+				}
+				if (!current.consumers.size) {
+					if (this.entries.get(key) === current) this.entries.delete(key);
+					current.controller.abort();
+					const resource = current.resource;
+					delete current.resource;
+					for (const texture of current.frames.values()) texture.destroy(false);
+					current.frames.clear();
+					if (resource) {
+						this.loaded--;
+						resource.release();
+					}
+				}
+			};
+			const consumer = {
+				ready: (resource) => {
+					if (released || settled) return;
+					settled = true;
+					signal.removeEventListener("abort", release);
+					resolve({
+						texture: resource.texture,
+						release,
+						textureFor: (frame) => {
+							if (released) throw new EngineError("GAME_DISPOSED", "Image lease released");
+							if (!frame) return resource.texture;
+							const rect = spriteFrameBounds(frame, resource.texture.width, resource.texture.height);
+							const key = `${rect.x},${rect.y},${rect.width},${rect.height}`;
+							let texture = current.frames.get(key);
+							if (!texture) {
+								texture = new Texture({
+									source: resource.texture.source,
+									frame: new Rectangle(rect.x, rect.y, rect.width, rect.height)
+								});
+								current.frames.set(key, texture);
+							}
+							return texture;
+						}
+					});
+				},
+				fail: (error) => {
+					if (released || settled) return;
+					settled = true;
+					reject(error);
+					release();
+				},
+				release
+			};
+			this.references++;
+			current.consumers.add(consumer);
+			signal.addEventListener("abort", release, { once: true });
+			if (current.resource) consumer.ready(current.resource);
+		});
+		if (fresh) Promise.resolve().then(() => this.load(url, current.controller.signal, request?.mode)).then((resource) => {
+			if (!current.consumers.size) {
+				resource.release();
+				return;
+			}
+			current.resource = resource;
+			this.loaded++;
+			for (const consumer of current.consumers) consumer.ready(resource);
+		}, (error) => {
+			if (this.entries.get(key) === current) this.entries.delete(key);
+			for (const consumer of [...current.consumers]) consumer.fail(error);
+		});
+		return promise;
+	}
+	dispose() {
+		if (this.dead) return;
+		this.dead = true;
+		for (const entry of [...this.entries.values()]) for (const consumer of [...entry.consumers]) consumer.release();
+	}
+};
+// packages/web/src/asset-loaders.ts
+var missing = "simpludify:missing-image";
+async function assetResponse(url, signal, reload) {
+	let response;
+	try {
+		response = await fetch(url, {
+			signal,
+			cache: reload ? "reload" : "default"
+		});
+	} catch (cause) {
+		signal.throwIfAborted();
+		throw new EngineError("ASSET_NETWORK", "Asset request did not complete", {}, { cause });
+	}
+	if (!response.ok) {
+		const status = response.status;
+		throw new EngineError(status === 408 || status === 429 || status >= 500 ? "ASSET_NETWORK" : "ASSET_LOAD_FAILED", "Asset request failed", { status });
+	}
+	return response;
+}
+function decodeImage(url, signal) {
+	return new Promise((resolve, reject) => {
+		signal.throwIfAborted();
+		const image = new Image();
+		const cleanup = () => {
+			image.onload = image.onerror = null;
+			signal.removeEventListener("abort", abort);
+		};
+		const abort = () => {
+			cleanup();
+			image.removeAttribute("src");
+			reject(signal.reason);
+		};
+		signal.addEventListener("abort", abort, { once: true });
+		image.onload = () => {
+			cleanup();
+			resolve(image);
+		};
+		image.onerror = () => {
+			cleanup();
+			reject(new EngineError("ASSET_LOAD_FAILED", "Image could not be decoded", { path: url }));
+		};
+		image.crossOrigin = "anonymous";
+		image.src = url;
+	});
+}
+function checkerboard() {
+	const canvas = document.createElement("canvas");
+	canvas.width = canvas.height = 16;
+	const draw = canvas.getContext("2d");
+	if (draw) {
+		draw.fillStyle = "#000";
+		draw.fillRect(0, 0, 16, 16);
+		draw.fillStyle = "#f0f";
+		draw.fillRect(0, 0, 8, 8);
+		draw.fillRect(8, 8, 8, 8);
+	}
+	return canvas;
+}
+async function loadImageResource(url, signal, mode) {
+	let objectURL;
+	try {
+		if (mode && url !== missing) {
+			const response = await assetResponse(url, signal, mode === "reload");
+			objectURL = URL.createObjectURL(await response.blob());
+		}
+		const image = url === missing ? checkerboard() : await decodeImage(objectURL ?? url, signal);
+		signal.throwIfAborted();
+		const texture = Texture.from(image, true);
+		if (!(texture.width > 0 && texture.height > 0)) {
+			texture.destroy(true);
+			throw new EngineError("ASSET_LOAD_FAILED", "Image has no drawable dimensions");
+		}
+		let released = false;
+		return {
+			texture,
+			release: () => {
+				if (released) return;
+				released = true;
+				texture.destroy(true);
+			}
+		};
+	} finally {
+		if (objectURL) URL.revokeObjectURL(objectURL);
+	}
+}
+function createImagePool(load = loadImageResource) {
+	return new SharedImages(load);
+}
+function imageAsset(image) {
+	return {
+		value: Object.freeze({
+			width: image.texture.width,
+			height: image.texture.height
+		}),
+		image,
+		release: image.release
+	};
+}
+var nextFont = 0;
+var systemFont = "system-ui, sans-serif";
+async function registerFont(data, signal) {
+	const family = `SimpludifyFont${++nextFont}`;
+	const face = await new FontFace(family, data).load();
+	signal.throwIfAborted();
+	document.fonts.add(face);
+	return {
+		value: `${family}, ${systemFont}`,
+		release: () => {
+			document.fonts.delete(face);
+		}
+	};
+}
+function browserAssetAdapter(images, decode) {
+	const load = async (kind, url, signal, reload) => {
+		if (kind === "image") return imageAsset(await images.acquire(reload ? Symbol() : url, signal, {
+			url,
+			mode: reload ? "reload" : "explicit"
+		}));
+		const response = await assetResponse(url, signal, reload);
+		if (kind === "json") return {
+			value: await response.json(),
+			release() {}
+		};
+		const data = await response.arrayBuffer();
+		signal.throwIfAborted();
+		if (kind === "font") return await registerFont(data, signal);
+		return {
+			value: await decode(data),
+			release() {}
+		};
+	};
+	return {
+		load,
+		fallback: async (kind, url, signal) => {
+			if (url) return await load(kind, url, signal, false);
+			if (kind === "image") return imageAsset(await images.acquire(missing, signal));
+			if (kind === "audio") return {
+				value: null,
+				release() {}
+			};
+			if (kind === "font") return {
+				value: systemFont,
+				release() {}
+			};
+		}
+	};
+}
+// packages/web/src/assets.ts
+var cancelled = () => new EngineError("ASSET_CANCELLED", "Asset use has been released");
+var invalid = (field) => new EngineError("INVALID_VALUE", `Invalid asset ${field}`);
+function numberIn(value, min, max, field) {
+	if (!Number.isSafeInteger(value) || value < min || value > max) throw invalid(field);
+	return value;
+}
+function settings(options) {
+	const retry = options.retry;
+	const once = retry?.once;
+	if (once !== void 0 && once !== "immediate") {
+		if (!once || typeof once !== "object") throw invalid("retry");
+		if ("delayMs" in once) numberIn(once.delayMs, 0, 3e5, "retry delay");
+		else if (!("until" in once) || typeof once.until?.then !== "function") throw invalid("retry event");
+	}
+	return {
+		timeoutMs: numberIn(options.timeoutMs ?? 3e4, 1, 3e5, "timeout"),
+		network: numberIn(retry?.network ?? 0, 0, 5, "network retries"),
+		networkDelayMs: numberIn(retry?.networkDelayMs ?? 250, 0, 3e5, "network retry delay"),
+		once
+	};
+}
+function assetURL(value, base) {
+	if (typeof value === "string" && !value.trim()) throw invalid("URL");
+	if (typeof value !== "string" && !(value instanceof URL)) throw invalid("URL");
+	try {
+		const url = new URL(value, base);
+		if (![
+			"http:",
+			"https:",
+			"data:",
+			"blob:"
+		].includes(url.protocol) || url.username || url.password) throw invalid("URL");
+		return url.href;
+	} catch {
+		throw invalid("URL");
+	}
+}
+function wait(promise, signal) {
+	if (signal.aborted) return Promise.reject(signal.reason);
+	return new Promise((resolve, reject) => {
+		const abort = () => reject(signal.reason);
+		signal.addEventListener("abort", abort, { once: true });
+		promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+	});
+}
+function pause(ms, signal) {
+	if (signal.aborted) return Promise.reject(signal.reason);
+	if (!ms) return Promise.resolve();
+	return new Promise((resolve, reject) => {
+		const abort = () => {
+			clearTimeout(timer);
+			reject(signal.reason);
+		};
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", abort);
+			resolve();
+		}, ms);
+		signal.addEventListener("abort", abort, { once: true });
+	});
+}
+function progress(entries) {
+	let total = 0;
+	let failed = 0;
+	let fallback = 0;
+	let loading = 0;
+	let completed = 0;
+	for (const entry of entries) {
+		total++;
+		if (entry.task) loading++;
+		if (entry.status === "failed") failed++;
+		if (entry.status === "fallback") fallback++;
+		if (entry.status !== "loading") completed++;
+	}
+	return Object.freeze({
+		total,
+		completed,
+		failed,
+		fallback,
+		loading,
+		ratio: total ? completed / total : 1,
+		state: loading ? "loading" : total ? "complete" : "idle"
+	});
+}
+var nextStore = 0;
+var AssetHandle = class AssetHandle {
+	kind;
+	entry;
+	store;
+	remove;
+	ready;
+	cancelled = new AbortController();
+	imageSource;
+	/** @internal */
+	constructor(kind, entry, store, remove) {
+		this.kind = kind;
+		this.entry = entry;
+		this.store = store;
+		this.remove = remove;
+		this.imageSource = kind === "image" ? Object.freeze({
+			kind: "image",
+			url: entry.id
+		}) : void 0;
+		this.ready = store.ready(entry, this.cancelled.signal).then(() => this);
+		this.ready.catch(() => {});
+	}
+	get id() {
+		return this.entry.id;
+	}
+	get url() {
+		return this.entry.url;
+	}
+	get status() {
+		return this.cancelled.signal.aborted ? "released" : this.entry.status;
+	}
+	get loading() {
+		return !this.cancelled.signal.aborted && this.entry.task !== void 0;
+	}
+	get value() {
+		return this.status === "released" ? void 0 : this.entry.asset?.value;
+	}
+	get error() {
+		return this.status === "released" ? void 0 : this.entry.error;
+	}
+	get progress() {
+		return progress(this.status === "released" ? [] : [this.entry]);
+	}
+	/** Stable Renderable source. SpriteSheet accepts its URL. */
+	get source() {
+		return this.imageSource;
+	}
+	onChange(listener) {
+		const signal = this.cancelled.signal;
+		signal.throwIfAborted();
+		const notify = () => listener(this);
+		const off = () => {
+			this.entry.listeners.delete(notify);
+			signal.removeEventListener("abort", off);
+		};
+		this.entry.listeners.add(notify);
+		signal.addEventListener("abort", off, { once: true });
+		return off;
+	}
+	/** @internal A playback or Game font owns a separate reference. */
+	retain(store) {
+		this.cancelled.signal.throwIfAborted();
+		if (this.store !== store) throw new EngineError("ASSET_OWNERSHIP", "Asset belongs to another Game");
+		let release = () => {};
+		const use = new AssetHandle(this.kind, this.entry, store, () => release());
+		release = store.retain(this.entry, () => use.release());
+		return use;
+	}
+	async reload(options = {}) {
+		if (this.cancelled.signal.aborted) throw cancelled();
+		await wait(this.store.start(this.entry, options, true), this.cancelled.signal);
+		return this;
+	}
+	release() {
+		if (this.cancelled.signal.aborted) return;
+		this.cancelled.abort(cancelled());
+		this.remove();
+	}
+};
+var AssetScope = class AssetScope {
+	store;
+	global;
+	lifetime = new Lifetime();
+	handles = /* @__PURE__ */ new Map();
+	listeners = /* @__PURE__ */ new Set();
+	previous;
+	/** @internal */
+	constructor(store, owner, global = false) {
+		this.store = store;
+		this.global = global;
+		if (owner?.disposed) throw cancelled();
+		const unregister = store.register(this);
+		let removeOwner;
+		try {
+			removeOwner = owner?.onDispose(() => this.dispose());
+		} catch (error) {
+			unregister();
+			throw error;
+		}
+		const off = store.observe(() => this.notify());
+		this.lifetime.onDispose(() => {
+			off();
+			unregister();
+			removeOwner?.();
+			this.listeners.clear();
+		});
+	}
+	get disposed() {
+		return this.lifetime.disposed;
+	}
+	onDispose(callback) {
+		return this.lifetime.onDispose(callback);
+	}
+	scope(owner = this) {
+		if (this.disposed) throw cancelled();
+		return new AssetScope(this.store, owner);
+	}
+	load(request) {
+		if (this.disposed) throw cancelled();
+		const entry = this.store.entry(request);
+		const existing = this.handles.get(entry);
+		if (existing) return existing;
+		let drop = () => {};
+		const handle = new AssetHandle(request.kind, entry, this.store, () => {
+			this.handles.delete(entry);
+			drop();
+		});
+		this.handles.set(entry, handle);
+		drop = this.store.retain(entry, () => handle.release());
+		if (entry.status === "loading" && !entry.task) this.store.start(entry, request, false).catch(() => {});
+		else this.store.changed();
+		return handle;
+	}
+	get progress() {
+		return this.global ? this.store.progress : progress(this.handles.keys());
+	}
+	onProgress(listener) {
+		if (this.disposed) throw cancelled();
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	notify() {
+		if (!this.listeners.size) return;
+		const snapshot = this.progress;
+		const previous = this.previous;
+		if (previous && previous.total === snapshot.total && previous.completed === snapshot.completed && previous.failed === snapshot.failed && previous.fallback === snapshot.fallback && previous.loading === snapshot.loading) return;
+		this.previous = snapshot;
+		for (const listener of [...this.listeners]) if (this.listeners.has(listener)) this.store.deliver(() => listener(snapshot));
+	}
+	dispose() {
+		if (this.disposed) return;
+		try {
+			this.lifetime.dispose();
+		} finally {
+			for (const handle of [...this.handles.values()]) handle.release();
+		}
+	}
+};
+/** @internal One resource directory per Game. The adapter owns decoded resources. */
+var AssetStore = class {
+	adapter;
+	logger;
+	base;
+	prefix = `simpludify-asset:${++nextStore}:`;
+	entries = /* @__PURE__ */ new Map();
+	images = /* @__PURE__ */ new Map();
+	idle = /* @__PURE__ */ new Set();
+	listeners = /* @__PURE__ */ new Set();
+	scopes = /* @__PURE__ */ new Set();
+	notifying = false;
+	notificationScheduled = false;
+	capacity;
+	customFallback = {};
+	sequence = 0;
+	dead = false;
+	constructor(adapter, logger, base, options = {}) {
+		this.adapter = adapter;
+		this.logger = logger;
+		this.base = base;
+		this.capacity = numberIn(options.cacheEntries ?? 16, 0, 1024, "cache capacity");
+		for (const kind of [
+			"image",
+			"audio",
+			"font"
+		]) {
+			const custom = options.fallback?.[kind];
+			if (custom !== void 0) this.customFallback[kind] = assetURL(custom, base);
+		}
+	}
+	register(scope) {
+		if (this.dead) throw cancelled();
+		this.scopes.add(scope);
+		return () => {
+			this.scopes.delete(scope);
+		};
+	}
+	observe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	deliver(listener) {
+		const report = (cause) => {
+			this.logger.report(cause, {
+				source: "engine.assets",
+				message: "Asset observer failed",
+				fatal: false
+			});
+		};
+		try {
+			const result = listener();
+			if (result != null) Promise.resolve(result).catch(report);
+		} catch (cause) {
+			report(cause);
+		}
+	}
+	changed() {
+		if (this.notifying) {
+			if (!this.notificationScheduled) {
+				this.notificationScheduled = true;
+				queueMicrotask(() => {
+					this.notificationScheduled = false;
+					this.changed();
+				});
+			}
+			return;
+		}
+		this.notifying = true;
+		try {
+			for (const listener of [...this.listeners]) if (this.listeners.has(listener)) this.deliver(listener);
+		} finally {
+			this.notifying = false;
+		}
+	}
+	get progress() {
+		return progress([...this.entries.values()].filter((entry) => entry.users.size > 0));
+	}
+	entry(request) {
+		if (this.dead) throw cancelled();
+		if (![
+			"image",
+			"audio",
+			"font",
+			"json"
+		].includes(request.kind)) throw invalid("kind");
+		settings(request);
+		const url = assetURL(request.url, this.base);
+		const key = `${request.kind}\0${url}`;
+		const existing = this.entries.get(key);
+		if (existing) return existing;
+		let usable = () => {};
+		let fail = () => {};
+		const first = new Promise((resolve, reject) => {
+			usable = resolve;
+			fail = reject;
+		});
+		first.catch(() => {});
+		const entry = {
+			key,
+			url,
+			kind: request.kind,
+			id: this.prefix + ++this.sequence,
+			first,
+			usable,
+			fail,
+			users: /* @__PURE__ */ new Set(),
+			listeners: /* @__PURE__ */ new Set(),
+			validators: /* @__PURE__ */ new Set(),
+			status: "loading",
+			asset: void 0,
+			task: void 0,
+			controller: void 0,
+			error: void 0
+		};
+		this.entries.set(key, entry);
+		if (entry.kind === "image") this.images.set(entry.id, entry);
+		return entry;
+	}
+	retain(entry, dispose) {
+		this.idle.delete(entry);
+		entry.users.add(dispose);
+		return () => {
+			if (!entry.users.delete(dispose)) return;
+			if (!entry.users.size) {
+				if (!this.dead && !entry.task && entry.status === "ready" && this.capacity) {
+					this.idle.add(entry);
+					if (this.idle.size > this.capacity) {
+						const oldest = this.idle.values().next().value;
+						if (oldest) this.evict(oldest);
+					}
+				} else this.evict(entry);
+			}
+			this.changed();
+		};
+	}
+	release(resource) {
+		if (resource) this.deliver(() => resource.release());
+	}
+	evict(entry) {
+		if (this.entries.get(entry.key) === entry) this.entries.delete(entry.key);
+		this.images.delete(entry.id);
+		this.idle.delete(entry);
+		entry.controller?.abort(cancelled());
+		entry.fail(cancelled());
+		const asset = entry.asset;
+		entry.asset = void 0;
+		this.release(asset);
+	}
+	async ready(entry, signal) {
+		signal.throwIfAborted();
+		if (entry.asset) return;
+		await wait(entry.status === "failed" && entry.task ? entry.task : entry.first, signal);
+		signal.throwIfAborted();
+		if (!entry.asset) throw entry.error ?? cancelled();
+	}
+	start(entry, options, reload) {
+		if (entry.task) return entry.task;
+		if (this.dead || !entry.users.size) return Promise.reject(cancelled());
+		const policy = settings(options);
+		const controller = new AbortController();
+		entry.controller = controller;
+		entry.task = Promise.resolve().then(async () => {
+			try {
+				await this.load(entry, policy, reload, controller.signal);
+			} finally {
+				entry.task = void 0;
+				entry.controller = void 0;
+				this.changed();
+			}
+		});
+		entry.task.catch(() => {});
+		const task = entry.task;
+		this.changed();
+		return task;
+	}
+	async attempt(promise, signal) {
+		promise.then((asset) => {
+			if (signal.aborted) this.release(asset);
+		}, () => {});
+		return await wait(promise, signal);
+	}
+	commit(entry, asset, fallback) {
+		try {
+			for (const validate of entry.validators) validate(asset);
+		} catch (error) {
+			this.release(asset);
+			throw error;
+		}
+		const old = entry.asset;
+		entry.asset = asset;
+		entry.status = fallback ? "fallback" : "ready";
+		if (!fallback) entry.error = void 0;
+		entry.usable();
+		for (const listener of [...entry.listeners]) if (entry.listeners.has(listener)) this.deliver(listener);
+		this.release(old);
+		this.changed();
+	}
+	async fallback(entry, signal, owner) {
+		const custom = this.customFallback[entry.kind];
+		if (custom && !signal.aborted) try {
+			const asset = await this.attempt(this.adapter.fallback(entry.kind, custom, signal), signal);
+			if (asset) {
+				if (owner.aborted) {
+					this.release(asset);
+					throw owner.reason;
+				}
+				this.commit(entry, asset, true);
+				return;
+			}
+		} catch (cause) {
+			if (owner.aborted) throw owner.reason;
+			this.logger.warn("Custom asset fallback failed", {
+				source: "engine.assets",
+				cause
+			});
+		}
+		const asset = await this.attempt(this.adapter.fallback(entry.kind, void 0, owner), owner);
+		if (asset) {
+			if (owner.aborted) {
+				this.release(asset);
+				throw owner.reason;
+			}
+			this.commit(entry, asset, true);
+		}
+	}
+	async load(entry, policy, reload, owner) {
+		const deadline = AbortSignal.timeout(policy.timeoutMs);
+		const signal = AbortSignal.any([owner, deadline]);
+		let network = policy.network;
+		let once = policy.once;
+		let failure;
+		try {
+			for (;;) try {
+				signal.throwIfAborted();
+				const asset = await this.attempt(this.adapter.load(entry.kind, entry.url, signal, reload), signal);
+				if (!asset) throw invalid("adapter result");
+				if (signal.aborted) {
+					this.release(asset);
+					throw signal.reason;
+				}
+				this.commit(entry, asset, false);
+				return;
+			} catch (cause) {
+				owner.throwIfAborted();
+				failure = cause;
+				entry.error = cause;
+				if (!entry.asset) {
+					await this.fallback(entry, signal, owner);
+					if (entry.asset) this.logger.warn("Using an asset fallback", {
+						source: "engine.assets",
+						code: "ASSET_FALLBACK",
+						details: {
+							kind: entry.kind,
+							id: entry.id
+						},
+						cause
+					});
+				}
+				if (signal.aborted) break;
+				if (cause instanceof EngineError && cause.code === "ASSET_NETWORK") {
+					if (!network) break;
+					network--;
+					await pause(policy.networkDelayMs, signal);
+				} else {
+					const retry = once;
+					once = void 0;
+					if (!retry) break;
+					if (retry !== "immediate") if ("delayMs" in retry) await pause(retry.delayMs, signal);
+					else await wait(Promise.resolve(retry.until), signal);
+				}
+			}
+		} catch (cause) {
+			owner.throwIfAborted();
+			failure = cause;
+		}
+		if (deadline.aborted) failure = new EngineError("ASSET_TIMEOUT", "Asset load deadline expired", {}, { cause: failure });
+		failure ??= new EngineError("ASSET_LOAD_FAILED", "Asset could not be loaded");
+		entry.error = failure;
+		if (!entry.asset) {
+			entry.status = "failed";
+			entry.fail(failure);
+		}
+		this.logger.report(failure, {
+			source: "engine.assets",
+			message: "Asset loading failed",
+			fatal: false
+		});
+		if (reload || !entry.asset) throw failure;
+	}
+	async image(id, signal) {
+		const entry = this.images.get(id);
+		if (!entry || this.dead || signal.aborted) throw cancelled();
+		const controller = new AbortController();
+		const pending = AbortSignal.any([signal, controller.signal]);
+		let frames;
+		const subscriptions = /* @__PURE__ */ new Set();
+		const validate = (asset) => {
+			for (const frame of frames?.() ?? []) asset.image?.textureFor(frame);
+		};
+		const release = () => {
+			if (controller.signal.aborted) return;
+			controller.abort(cancelled());
+			for (const listener of subscriptions) entry.listeners.delete(listener);
+			subscriptions.clear();
+			entry.validators.delete(validate);
+			drop();
+		};
+		const drop = this.retain(entry, release);
+		try {
+			await this.ready(entry, pending);
+			pending.throwIfAborted();
+			entry.validators.add(validate);
+			const current = () => {
+				if (controller.signal.aborted || !entry.asset?.image) throw cancelled();
+				return entry.asset.image;
+			};
+			return {
+				get texture() {
+					return current().texture;
+				},
+				textureFor: (frame) => {
+					const lease = current();
+					if (!frame) return lease.texture;
+					return entry.status === "fallback" ? lease.texture : lease.textureFor(frame);
+				},
+				useFrames: (required) => {
+					frames = required;
+				},
+				onChange: (listener) => {
+					if (controller.signal.aborted) return () => {};
+					subscriptions.add(listener);
+					entry.listeners.add(listener);
+					return () => {
+						subscriptions.delete(listener);
+						entry.listeners.delete(listener);
+					};
+				},
+				release
+			};
+		} catch (error) {
+			release();
+			throw error;
+		}
+	}
+	dispose() {
+		if (this.dead) return;
+		this.dead = true;
+		this.listeners.clear();
+		for (const scope of [...this.scopes]) this.deliver(() => scope.dispose());
+		for (const entry of [...this.entries.values()]) {
+			for (const dispose of [...entry.users]) this.deliver(dispose);
+			if (this.entries.get(entry.key) === entry) this.evict(entry);
+		}
+	}
+};
+function isAssetImage(url) {
+	return url.startsWith("simpludify-asset:");
+}
+// packages/web/src/audio.ts
+function volume(value) {
+	if (!Number.isFinite(value) || value < 0 || value > 1) throw new EngineError("INVALID_VALUE", "Audio volume must be between zero and one");
+	return value;
+}
+function voiceLimit(value) {
+	if (value !== void 0 && (!Number.isSafeInteger(value) || value <= 0)) throw new EngineError("INVALID_VALUE", "Audio voice limit must be a positive integer");
+	return value;
+}
+var AudioGroup = class {
+	name;
+	parent;
+	gain;
+	level;
+	maxVoices;
+	/** @internal */
+	constructor(name, parent, options = {}) {
+		this.name = name;
+		this.parent = parent;
+		this.level = volume(options.volume ?? 1);
+		this.maxVoices = voiceLimit(options.maxVoices);
+	}
+	get volume() {
+		return this.level;
+	}
+	set volume(value) {
+		this.level = volume(value);
+		if (this.gain) this.gain.gain.value = this.level;
+	}
+	/** @internal */
+	node(context) {
+		if (this.gain) return this.gain;
+		const output = this.parent?.node(context) ?? context.destination;
+		const gain = context.createGain();
+		gain.gain.value = this.level;
+		gain.connect(output);
+		this.gain = gain;
+		return gain;
+	}
+	/** @internal */
+	disconnect() {
+		this.gain?.disconnect();
+		this.gain = void 0;
+	}
+};
+var AudioPlayback = class {
+	audio;
+	use;
+	group;
+	finished;
+	assetId;
+	resolve = () => {};
+	phase = "pending";
+	done = false;
+	source;
+	gain;
+	buffer;
+	position = 0;
+	startedAt = 0;
+	level;
+	looping;
+	offOwner;
+	/** @internal */
+	constructor(audio, use, group, options) {
+		this.audio = audio;
+		this.use = use;
+		this.group = group;
+		this.assetId = use.id;
+		this.level = volume(options.volume ?? 1);
+		this.looping = options.loop ?? false;
+		this.finished = new Promise((resolve) => {
+			this.resolve = resolve;
+		});
+		this.offOwner = options.owner?.onDispose(() => this.stop());
+		use.ready.then(() => this.startIfReady()).catch((cause) => this.fail(cause));
+	}
+	get state() {
+		return this.phase;
+	}
+	get volume() {
+		return this.level;
+	}
+	set volume(value) {
+		this.level = volume(value);
+		if (this.gain) this.gain.gain.value = this.level;
+	}
+	get loop() {
+		return this.looping;
+	}
+	set loop(value) {
+		if (typeof value !== "boolean") throw new EngineError("INVALID_VALUE", "Audio loop must be boolean");
+		this.looping = value;
+		if (this.source) this.source.loop = value;
+	}
+	pause() {
+		if (this.phase !== "playing" && this.phase !== "pending") return;
+		try {
+			if (this.phase === "playing") {
+				this.position += Math.max(0, this.audio.device().currentTime - this.startedAt);
+				this.clearSource(true);
+			}
+			this.phase = "paused";
+		} catch (cause) {
+			this.fail(cause);
+		}
+	}
+	resume() {
+		if (this.phase !== "paused") return;
+		this.phase = "pending";
+		this.startIfReady();
+	}
+	stop() {
+		this.finish("stopped");
+	}
+	/** @internal */
+	replace() {
+		this.finish("replaced");
+	}
+	/** @internal */
+	startIfReady() {
+		if (this.phase !== "pending") return;
+		const current = this.buffer === void 0 ? this.use.value : this.buffer;
+		if (current === void 0) return;
+		try {
+			const context = this.audio.device();
+			if (context.state !== "running") return;
+			this.buffer = current;
+			const buffer = current ?? context.createBuffer(1, 1, context.sampleRate);
+			if (this.position >= buffer.duration) {
+				if (!this.looping) {
+					this.finish("ended");
+					return;
+				}
+				this.position %= buffer.duration;
+			}
+			if (!this.gain) {
+				this.gain = context.createGain();
+				this.gain.gain.value = this.level;
+				this.gain.connect(this.group.node(context));
+			}
+			const source = context.createBufferSource();
+			this.source = source;
+			source.buffer = buffer;
+			source.loop = this.looping;
+			source.connect(this.gain);
+			source.onended = () => {
+				if (this.source === source) this.finish("ended");
+			};
+			this.startedAt = context.currentTime;
+			source.start(0, this.position);
+			this.phase = "playing";
+		} catch (cause) {
+			this.fail(cause);
+		}
+	}
+	clearSource(stop) {
+		const source = this.source;
+		this.source = void 0;
+		if (!source) return;
+		source.onended = null;
+		try {
+			if (stop) source.stop();
+		} finally {
+			source.disconnect();
+		}
+	}
+	fail(cause) {
+		if (this.done) return;
+		this.audio.report(cause, "Audio playback failed");
+		this.finish("failed");
+	}
+	finish(reason) {
+		if (this.done) return;
+		this.done = true;
+		this.phase = reason;
+		this.buffer = void 0;
+		this.audio.remove(this);
+		try {
+			cleanupAll([
+				() => this.clearSource(reason !== "ended"),
+				() => this.gain?.disconnect(),
+				() => this.offOwner?.(),
+				() => this.use.release()
+			], "Audio playback cleanup failed");
+		} catch (cause) {
+			this.audio.report(cause, "Audio playback cleanup failed");
+		} finally {
+			this.offOwner = void 0;
+			this.gain = void 0;
+			this.resolve(reason);
+		}
+	}
+};
+/** One Web Audio context per Game, created only when audio is requested. */
+var GameAudio = class {
+	assets;
+	logger;
+	shutdown = new AbortController();
+	groups = /* @__PURE__ */ new Map();
+	voices = /* @__PURE__ */ new Set();
+	context;
+	master = new AudioGroup("master", void 0);
+	/** @internal */
+	constructor(host, assets, logger) {
+		this.assets = assets;
+		this.logger = logger;
+		this.groups.set("master", this.master);
+		this.group("music");
+		this.group("effects");
+		const gesture = (event) => {
+			if (event.isTrusted && (this.context || this.voices.size)) this.unlock();
+		};
+		const options = {
+			capture: true,
+			signal: this.shutdown.signal
+		};
+		host.addEventListener("pointerup", gesture, options);
+		host.addEventListener("keydown", gesture, options);
+	}
+	get state() {
+		return this.context?.state ?? (this.shutdown.signal.aborted ? "closed" : "idle");
+	}
+	group(name, options) {
+		this.assertAlive();
+		if (typeof name !== "string" || !name.trim()) throw new EngineError("INVALID_VALUE", "Audio group name cannot be empty");
+		const existing = this.groups.get(name);
+		if (existing) {
+			if (options) throw new EngineError("AUDIO_GROUP_EXISTS", "Audio group is already configured");
+			return existing;
+		}
+		const parent = this.groups.get(options?.parent ?? "master");
+		if (!parent) throw new EngineError("AUDIO_GROUP_UNKNOWN", "Unknown parent audio group");
+		const group = new AudioGroup(name, parent, options);
+		this.groups.set(name, group);
+		return group;
+	}
+	play(asset, options = {}) {
+		this.assertAlive();
+		if (asset?.kind !== "audio") throw new EngineError("INVALID_VALUE", "An audio asset is required");
+		if (options.owner?.disposed) throw new EngineError("OWNER_DISPOSED", "Audio playback owner is disposed");
+		volume(options.volume ?? 1);
+		if (options.loop !== void 0 && typeof options.loop !== "boolean") throw new EngineError("INVALID_VALUE", "Audio loop must be boolean");
+		const limit = voiceLimit(options.maxVoices);
+		const group = this.groups.get(options.group ?? "effects");
+		if (!group) throw new EngineError("AUDIO_GROUP_UNKNOWN", "Unknown playback group");
+		const use = asset.retain(this.assets);
+		let voice;
+		try {
+			voice = new AudioPlayback(this, use, group, options);
+		} catch (error) {
+			use.release();
+			throw error;
+		}
+		this.voices.add(voice);
+		if (limit !== void 0) this.enforceLimit(limit, (item) => item.assetId === voice.assetId);
+		for (let node = group; node; node = node.parent) {
+			const limit = node.maxVoices;
+			const ancestor = node;
+			if (limit !== void 0) this.enforceLimit(limit, (item) => {
+				for (let parent = item.group; parent; parent = parent.parent) if (parent === ancestor) return true;
+				return false;
+			});
+		}
+		return voice;
+	}
+	enforceLimit(limit, applies) {
+		const voices = [...this.voices].filter(applies);
+		for (const voice of voices.slice(0, Math.max(0, voices.length - limit))) voice.replace();
+	}
+	assertAlive() {
+		if (this.shutdown.signal.aborted) throw new EngineError("GAME_DISPOSED", "Audio is disposed");
+	}
+	/** @internal */
+	device() {
+		this.assertAlive();
+		if (!this.context) {
+			this.context = new AudioContext();
+			this.context.addEventListener("statechange", this.drain, { signal: this.shutdown.signal });
+		}
+		return this.context;
+	}
+	/** @internal */
+	decode(bytes) {
+		return this.device().decodeAudioData(bytes);
+	}
+	/** Call from a trusted user gesture to start pending playback. */
+	async unlock() {
+		if (this.shutdown.signal.aborted) return false;
+		try {
+			const context = this.device();
+			if (context.state !== "running") {
+				if (navigator.userActivation?.isActive === false) return false;
+				const signal = this.shutdown.signal;
+				let timer;
+				let abort = () => {};
+				try {
+					await Promise.race([context.resume(), new Promise((resolve) => {
+						abort = resolve;
+						signal.addEventListener("abort", abort, { once: true });
+						timer = setTimeout(resolve, 1500);
+					})]);
+				} finally {
+					clearTimeout(timer);
+					signal.removeEventListener("abort", abort);
+				}
+			}
+			if (this.shutdown.signal.aborted || context.state !== "running") return false;
+			this.drain();
+			return true;
+		} catch (cause) {
+			if (!this.shutdown.signal.aborted) this.report(cause, "Audio context could not resume");
+			return false;
+		}
+	}
+	drain = () => {
+		for (const voice of [...this.voices]) voice.startIfReady();
+	};
+	/** @internal */
+	remove(voice) {
+		this.voices.delete(voice);
+	}
+	/** @internal */
+	report(cause, message) {
+		this.logger.report(cause, {
+			source: "engine.audio",
+			message,
+			fatal: false
+		});
+	}
+	/** @internal */
+	dispose() {
+		if (this.shutdown.signal.aborted) return;
+		this.shutdown.abort();
+		const context = this.context;
+		this.context = void 0;
+		try {
+			cleanupAll([...[...this.voices].map((voice) => () => voice.stop()), ...[...this.groups.values()].reverse().map((group) => () => group.disconnect())], "Audio cleanup failed");
+		} finally {
+			this.groups.clear();
+			if (context && context.state !== "closed") context.close().catch((cause) => this.report(cause, "Audio context could not close"));
+		}
+	}
+};
 // packages/web/src/gamepad-layout.ts
 var positions = Object.fromEntries(Object.entries(GamepadButton).map(([name, index]) => [index, name]));
 var faces = Object.freeze({
@@ -1100,7 +2316,7 @@ function nativeGeometry(el, node, ui, clip) {
 	const background = style.background ?? 2316622;
 	const color = `#${style.color.toString(16).padStart(6, "0")}`;
 	el.style.cssText = `left:${b.x * scale}px;top:${b.y * scale}px;width:${b.width * scale}px;height:${b.height * scale}px;padding:${style.padding * scale}px;font-size:${style.fontSize * scale}px;--s-native-color:${color};--s-native-background:#${background.toString(16).padStart(6, "0")};color-scheme:${(background >> 16) * .2126 + (background >> 8 & 255) * .7152 + (background & 255) * .0722 > 128 ? "light" : "dark"};clip-path:inset(${Math.max(0, c.y - b.y) * scale}px ${Math.max(0, b.x + b.width - c.x - c.width) * scale}px ${Math.max(0, b.y + b.height - c.y - c.height) * scale}px ${Math.max(0, c.x - b.x) * scale}px);`;
-	el.style.fontFamily = style.fontFamily;
+	el.style.fontFamily = node.inheritsFont ? `var(--s-font, ${defaultCanvasStyle.fontFamily})` : style.fontFamily;
 	if (el.disabled && document.activeElement === el) el.blur();
 }
 /** Native editors must not cover later Canvas hit surfaces or overlay scrollbars. */
@@ -1166,6 +2382,7 @@ var CanvasVisual = class {
 	entries = /* @__PURE__ */ new Map();
 	metrics = /* @__PURE__ */ new Map();
 	dirty = true;
+	defaultFont = defaultCanvasStyle.fontFamily;
 	dead = false;
 	active = false;
 	cacheResolution;
@@ -1230,7 +2447,8 @@ var CanvasVisual = class {
 		};
 	}
 	measure = (node, contentWidth = Infinity) => {
-		const { fontSize, fontFamily, textWrap } = node.style;
+		const { fontSize, textWrap } = node.style;
+		const fontFamily = this.fontFamily(node);
 		const content = canvasControlText(node);
 		const adornment = node.control?.model.kind === "checkbox" ? 30 : 0;
 		const key = JSON.stringify([
@@ -1390,8 +2608,16 @@ var CanvasVisual = class {
 		button.style.cssText = `left:${c.x * s}px;top:${c.y * s}px;width:${c.width * s}px;height:${c.height * s}px;`;
 		if (button.disabled && document.activeElement === button) button.blur();
 	}
+	fontFamily(node) {
+		return node.inheritsFont ? this.defaultFont : node.style.fontFamily;
+	}
 	update(width, height) {
 		if (this.dead || this.ui.disposed) return;
+		const family = this.host.style.getPropertyValue("--s-font").trim() || defaultCanvasStyle.fontFamily;
+		if (this.defaultFont !== family) {
+			this.defaultFont = family;
+			this.ui.invalidate(true);
+		}
 		const layout = this.ui.layout(width, height, this.measure);
 		if (!this.active) {
 			this.host.append(this.element);
@@ -1473,12 +2699,14 @@ var CanvasVisual = class {
 				entry.label.setAttribute("aria-hidden", String(canvasOpacity(node) === 0));
 			}
 			const b = node.bounds, s = node.style;
+			const fontFamily = this.fontFamily(node);
 			const scrollBox = intersectUI(b, clip);
 			if (node.style.scroll && scrollBox.width > 0 && scrollBox.height > 0 && canvasOpacity(node) > 0) scrollVisible = true;
 			let enabled = !node.busy;
 			for (let p = node; p; p = p.parent) enabled &&= p.enabled;
 			const signature = JSON.stringify([
 				node.paintRevision,
+				fontFamily,
 				b.x,
 				b.y,
 				b.width,
@@ -1512,6 +2740,7 @@ var CanvasVisual = class {
 			entry.maskSignature = maskSignature;
 			const paintSignature = JSON.stringify([
 				node.paintRevision,
+				fontFamily,
 				b.width,
 				b.height,
 				enabled
@@ -1569,7 +2798,7 @@ var CanvasVisual = class {
 						entry.text.text = m.text;
 					}
 					const textStyleKey = JSON.stringify([
-						s.fontFamily,
+						fontFamily,
 						s.fontSize,
 						s.color
 					]);
@@ -1577,7 +2806,7 @@ var CanvasVisual = class {
 						this.resources.changedText(entry.text.styleKey);
 						entry.textStyleKey = textStyleKey;
 						entry.text.style = {
-							fontFamily: s.fontFamily,
+							fontFamily,
 							fontSize: s.fontSize,
 							fill: s.color
 						};
@@ -1857,119 +3086,6 @@ function pruneUITextKeys(renderer, keys) {
 		keys.delete(key);
 	}
 }
-// packages/web/src/shared-images.ts
-/** Renderer-local, live-reference cache. No idle retention or process-global state. */
-var SharedImages = class {
-	load;
-	entries = /* @__PURE__ */ new Map();
-	references = 0;
-	dead = false;
-	constructor(load) {
-		this.load = load;
-	}
-	get diagnostics() {
-		let pending = 0;
-		for (const entry of this.entries.values()) if (!entry.resource) pending++;
-		return {
-			imageReferences: this.references,
-			imageEntries: this.entries.size,
-			pendingImages: pending
-		};
-	}
-	acquire(key, signal) {
-		const cancelled = () => new EngineError("GAME_DISPOSED", "Image use cancelled", { path: key });
-		if (this.dead || signal.aborted) return Promise.reject(cancelled());
-		let entry = this.entries.get(key);
-		const fresh = !entry;
-		if (!entry) {
-			entry = {
-				key,
-				controller: new AbortController(),
-				consumers: /* @__PURE__ */ new Set(),
-				frames: /* @__PURE__ */ new Map()
-			};
-			this.entries.set(key, entry);
-		}
-		const current = entry;
-		const promise = new Promise((resolve, reject) => {
-			let released = false, settled = false;
-			const release = () => {
-				if (released) return;
-				released = true;
-				signal.removeEventListener("abort", release);
-				current.consumers.delete(consumer);
-				this.references--;
-				if (!settled) {
-					settled = true;
-					reject(cancelled());
-				}
-				if (!current.consumers.size) {
-					if (this.entries.get(key) === current) this.entries.delete(key);
-					current.controller.abort();
-					const resource = current.resource;
-					delete current.resource;
-					for (const texture of current.frames.values()) texture.destroy(false);
-					current.frames.clear();
-					resource?.release();
-				}
-			};
-			const consumer = {
-				ready: (resource) => {
-					if (released || settled) return;
-					settled = true;
-					signal.removeEventListener("abort", release);
-					resolve({
-						texture: resource.texture,
-						release,
-						textureFor: (frame) => {
-							if (released) throw new EngineError("GAME_DISPOSED", "Image lease released");
-							if (!frame) return resource.texture;
-							const rect = spriteFrameBounds(frame, resource.texture.width, resource.texture.height);
-							const key = `${rect.x},${rect.y},${rect.width},${rect.height}`;
-							let texture = current.frames.get(key);
-							if (!texture) {
-								texture = new Texture({
-									source: resource.texture.source,
-									frame: new Rectangle(rect.x, rect.y, rect.width, rect.height)
-								});
-								current.frames.set(key, texture);
-							}
-							return texture;
-						}
-					});
-				},
-				fail: (error) => {
-					if (released || settled) return;
-					settled = true;
-					reject(error);
-					release();
-				},
-				release
-			};
-			this.references++;
-			current.consumers.add(consumer);
-			signal.addEventListener("abort", release, { once: true });
-			if (current.resource) consumer.ready(current.resource);
-		});
-		if (fresh) Promise.resolve().then(() => this.load(key, current.controller.signal)).then((resource) => {
-			if (!current.consumers.size) {
-				resource.release();
-				return;
-			}
-			current.resource = resource;
-			for (const consumer of current.consumers) consumer.ready(resource);
-		}, (error) => {
-			if (this.entries.get(key) === current) this.entries.delete(key);
-			for (const consumer of [...current.consumers]) consumer.fail(error);
-		});
-		return promise;
-	}
-	dispose() {
-		if (this.dead) return;
-		this.dead = true;
-		for (const entry of [...this.entries.values()]) for (const consumer of [...entry.consumers]) consumer.release();
-	}
-};
 // packages/web/src/tilemap-visual.ts
 /** Renderer-owned sparse visible set; sheet pixels are owned by SharedImages. */
 var TilemapVisual = class {
@@ -2027,7 +3143,16 @@ var TilemapVisual = class {
 				return;
 			}
 			this.lease = lease;
+			lease.useFrames?.(() => Array.from(this.map.tileIds(), (id) => this.map.sheet.get(id).frame));
 			this.sync();
+			lease.onChange?.(() => {
+				if (this.disposed || !isCurrent()) return;
+				this.textures.clear();
+				this.revision = -1;
+				this.invalid = true;
+				this.sync();
+				this.changed();
+			});
 		}).catch((error) => {
 			if (!this.disposed) this.fail(error);
 		}).finally(() => {
@@ -2246,6 +3371,7 @@ var PixiRenderer = class {
 	host;
 	background;
 	onError;
+	assetServices;
 	app = new Application();
 	pendingUITextKeys = /* @__PURE__ */ new Set();
 	canvasPresentations = /* @__PURE__ */ new Set();
@@ -2338,7 +3464,7 @@ var PixiRenderer = class {
 		};
 	}
 	scenes = /* @__PURE__ */ new Set();
-	images = new SharedImages((url, signal) => this.image(url, signal));
+	images;
 	tilemaps = /* @__PURE__ */ new Set();
 	get tilemapDiagnostics() {
 		let sprites = 0, visibleTiles = 0, visitedCells = 0, updatedTiles = 0, createdSprites = 0, destroyedSprites = 0, validatedFrames = 0;
@@ -2384,19 +3510,20 @@ var PixiRenderer = class {
 	ready = false;
 	dead = false;
 	visualCount = 0;
-	textureCount = 0;
 	get diagnostics() {
 		return {
 			presentations: this.scenes.size,
 			visuals: this.visualCount,
-			textures: this.textureCount,
+			textures: this.images.textures,
 			...this.images.diagnostics
 		};
 	}
-	constructor(host, background = "#101922", onError = () => {}) {
+	constructor(host, background = "#101922", onError = () => {}, assetServices) {
 		this.host = host;
 		this.background = background;
 		this.onError = onError;
+		this.assetServices = assetServices;
+		this.images = assetServices?.images ?? createImagePool((...args) => this.image(...args));
 	}
 	async init() {
 		await this.app.init({
@@ -2419,54 +3546,11 @@ var PixiRenderer = class {
 		this.app.canvas.setAttribute("aria-label", "Game world");
 		this.host.prepend(this.app.canvas);
 	}
-	async image(url, signal) {
-		const image = new Image();
-		await new Promise((resolve, reject) => {
-			const clear = () => {
-				image.onload = null;
-				image.onerror = null;
-				signal.removeEventListener("abort", abort);
-			};
-			const abort = () => {
-				clear();
-				image.src = "";
-				reject(new EngineError("GAME_DISPOSED", "Image loading cancelled", { path: url }));
-			};
-			image.onload = () => {
-				clear();
-				resolve();
-			};
-			image.onerror = () => {
-				clear();
-				reject(new EngineError("ASSET_LOAD_FAILED", "Could not load sprite", { path: url }));
-			};
-			if (signal.aborted) {
-				abort();
-				return;
-			}
-			signal.addEventListener("abort", abort, { once: true });
-			image.crossOrigin = "anonymous";
-			image.src = url;
-		});
-		if (signal.aborted) throw new EngineError("GAME_DISPOSED", "Image loading cancelled", { path: url });
-		const texture = Texture.from(image, true);
-		if (!(texture.width > 0 && texture.height > 0)) {
-			texture.destroy(true);
-			throw new EngineError("ASSET_LOAD_FAILED", "Image has no drawable dimensions", { path: url });
-		}
-		this.textureCount++;
-		let released = false;
-		return {
-			texture,
-			release: () => {
-				if (released) return;
-				released = true;
-				this.textureCount--;
-				texture.destroy(true);
-			}
-		};
+	image(url, signal, mode) {
+		return loadImageResource(url, signal, mode);
 	}
 	acquireImage(url, signal) {
+		if (isAssetImage(url)) return this.assetServices?.store.image(url, signal) ?? Promise.reject(new EngineError("ASSET_CANCELLED", "Image asset does not belong to this renderer"));
 		try {
 			const parsed = new URL(url, document.baseURI);
 			if (![
@@ -2572,6 +3656,7 @@ var PixiRenderer = class {
 		const commitImage = (entry, resource, source) => {
 			if (source.kind !== "image") return;
 			const texture = resource.textureFor(source.frame);
+			resource.useFrames?.(() => source.frame ? [source.frame] : []);
 			const previous = entry.image;
 			const sprite = entry.display instanceof Sprite ? entry.display : new Sprite(texture);
 			sprite.texture = texture;
@@ -2579,7 +3664,17 @@ var PixiRenderer = class {
 			entry.image = resource;
 			replace(entry, sprite, source);
 			appearance(entry);
-			if (previous !== resource) previous?.release();
+			if (previous !== resource) {
+				previous?.release();
+				resource.onChange?.(() => {
+					if (!valid(entry) || entry.image !== resource || !entry.displayedSource) return;
+					try {
+						commitImage(entry, resource, entry.displayedSource);
+					} catch (error) {
+						fail(entry, error);
+					}
+				});
+			}
 		};
 		const update = (entry) => {
 			const component = entry.component;
@@ -2917,7 +4012,9 @@ var PixiRenderer = class {
 				p.dispose();
 			}),
 			() => this.pendingUITextKeys.clear(),
-			() => this.images.dispose(),
+			() => {
+				if (!this.assetServices) this.images.dispose();
+			},
 			() => this.destroyApp()
 		], "Renderer cleanup failed");
 	}
@@ -3165,6 +4262,13 @@ var Game = class {
 	element;
 	camera;
 	gamepads;
+	logger;
+	assets;
+	audio;
+	defaultFont;
+	fontUse;
+	imagePool = createImagePool();
+	assetStore;
 	renderer;
 	keyboard;
 	captures;
@@ -3202,8 +4306,14 @@ var Game = class {
 		const renderer = this.renderer;
 		if (!renderer.prepareVirtualInput) throw new EngineError("RENDERER_CAPABILITY", "Renderer does not support virtual input presentation");
 		const presentation = renderer.prepareVirtualInput(input);
-		input.onDispose(() => presentation.dispose());
-		return presentation;
+		const off = input.onDispose(() => presentation.dispose());
+		return {
+			update: () => presentation.update(),
+			dispose: () => {
+				off();
+				presentation.dispose();
+			}
+		};
 	}
 	canvas;
 	canvasPresentation;
@@ -3245,6 +4355,10 @@ var Game = class {
 	height = 450;
 	ratio = 1;
 	scenes = /* @__PURE__ */ new Map();
+	retainedScenes = /* @__PURE__ */ new Map();
+	sceneRetention;
+	activeRetention = "dispose";
+	detachPresentation;
 	pendingScene;
 	defaultUI = [];
 	ui;
@@ -3262,6 +4376,12 @@ var Game = class {
 	errorBox;
 	constructor(options = {}) {
 		this.options = options;
+		this.sceneRetention = retentionPolicy(options.sceneRetention ?? "dispose");
+		const { console: consoleEnabled = !options.onError, ...logging } = options.logging ?? {};
+		this.logger = new Logger({
+			...logging,
+			...consoleEnabled ? { sink: (entry) => console[entry.level](entry.message) } : {}
+		});
 		this.engine = new Engine(options.seed === void 0 ? {} : { seed: options.seed });
 		this.fixed = options.fixedStep ? new FixedStepRunner(this.engine, options.fixedStep) : void 0;
 		this.camera = options.camera ?? new Camera();
@@ -3292,6 +4412,9 @@ var Game = class {
 			...theme,
 			...options.tokens
 		};
+		this.defaultFont = tokens.font;
+		this.assetStore = new AssetStore(browserAssetAdapter(this.imagePool, (data) => this.audio.decode(data)), this.logger, document.baseURI, options.assets);
+		this.assets = new AssetScope(this.assetStore, void 0, true);
 		this.element = document.createElement("div");
 		this.element.className = "simpludify";
 		this.element.tabIndex = 0;
@@ -3303,18 +4426,25 @@ var Game = class {
 		this.errorBox.hidden = true;
 		this.element.append(this.errorBox);
 		(options.parent ?? document.body).append(this.element);
+		this.audio = new GameAudio(this.element, this.assetStore, this.logger);
 		try {
-			this.renderer = options.renderer?.(this.element) ?? new PixiRenderer(this.element, tokens.background, (error) => this.report(error));
+			this.renderer = options.renderer?.(this.element) ?? new PixiRenderer(this.element, tokens.background, (error) => this.report(error, "engine.renderer"), {
+				store: this.assetStore,
+				images: this.imagePool
+			});
 		} catch (error) {
 			this.element.remove();
 			this.engine.dispose();
+			this.audio.dispose();
+			this.assetStore.dispose();
+			this.imagePool.dispose();
 			throw error;
 		}
 		this.frames = options.frames ?? {
 			request: (callback) => requestAnimationFrame(callback),
 			cancel: (handle) => cancelAnimationFrame(handle)
 		};
-		this.captures = new InputCaptureManager(this.element, this.engine.input, () => this.engine.scene, () => this.pointers.release(), this.report);
+		this.captures = new InputCaptureManager(this.element, this.engine.input, () => this.engine.scene, () => this.pointers.release(), (error) => this.report(error, "engine.input"));
 		this.keyboard = new BrowserInput(this.element, this.engine.input);
 		this.gamepads = new GamepadInput(this.engine.input, {
 			observe: (pads) => this.captures.sample(pads),
@@ -3329,7 +4459,7 @@ var Game = class {
 				world: this.screenToWorld(screen),
 				view: this.view
 			};
-		}, this.report, () => this.updateProjection(), this.engine.input);
+		}, (error) => this.report(error, "engine.input"), () => this.updateProjection(), this.engine.input);
 		document.addEventListener("visibilitychange", () => {
 			this.previousTime = void 0;
 			this.fixed?.reset();
@@ -3339,12 +4469,26 @@ var Game = class {
 			try {
 				this.resize();
 			} catch (error) {
-				this.report(error);
+				this.report(error, "engine.resize", true);
 				this.dispose();
 			}
 		});
 		this.observer.observe(this.element);
 	}
+	/** Choose the Game default font for DOM and Canvas UI. */
+	setFont(asset) {
+		this.assertAlive();
+		if (asset && asset.kind !== "font") throw new EngineError("INVALID_VALUE", "A font asset is required");
+		const next = asset?.retain(this.assetStore);
+		const old = this.fontUse;
+		this.fontUse = next;
+		const update = () => {
+			this.element.style.setProperty("--s-font", next?.value ?? this.defaultFont);
+		};
+		next?.onChange(update);
+		update();
+		old?.release();
+	}
 	assertAlive() {
 		if (this.dead) throw new EngineError("GAME_DISPOSED", "Game has been disposed");
 	}
@@ -3426,12 +4570,15 @@ var Game = class {
 		if (this.startPromise) throw new EngineError("UI_ALREADY_STARTED", "Define default UI before run");
 		this.defaultUI.push(...nodes);
 	}
-	scene(id, setup) {
+	scene(id, setup, options = {}) {
 		this.assertAlive();
 		if (typeof id !== "string" || !id.length) throw new EngineError("INVALID_VALUE", "Scene id must not be empty");
 		if (typeof setup !== "function") throw new EngineError("INVALID_VALUE", "Scene setup must be a function");
 		if (this.scenes.has(id)) throw new EngineError("DUPLICATE_SCENE", "Scene id is already registered", { sceneId: id });
-		this.scenes.set(id, setup);
+		this.scenes.set(id, {
+			setup,
+			retention: retentionPolicy(options.retention ?? this.sceneRetention)
+		});
 		return this;
 	}
 	wait(promise) {
@@ -3468,6 +4615,12 @@ var Game = class {
 				this.assertAlive();
 				this.frame = this.frames.request(this.tick);
 			} catch (error) {
+				if (!this.dead) this.logger.report(error, {
+					source: "engine.startup",
+					message: "Simpludify could not start",
+					fatal: true,
+					standardOutput: false
+				});
 				this.dispose();
 				throw error;
 			}
@@ -3480,11 +4633,25 @@ var Game = class {
 		return this.navigate(id);
 	}
 	navigate(id) {
-		const setup = this.scenes.get(id);
-		if (!setup) return Promise.reject(new EngineError("SCENE_NOT_FOUND", "Unknown scene", { sceneId: id }));
+		const registration = this.scenes.get(id);
+		if (!registration) return Promise.reject(new EngineError("SCENE_NOT_FOUND", "Unknown scene", { sceneId: id }));
 		if (this.pendingScene?.id === id) return this.pendingScene.task;
 		const task = this.queue.then(async () => {
 			this.assertAlive();
+			const beforeActivate = () => {
+				if (this.pendingScene?.task === task) this.pendingScene = void 0;
+			};
+			const existing = this.retainedScenes.get(id);
+			if (existing) {
+				if (this.engine.scene === existing.scene && existing.scene.state === SceneState.Active) return;
+				try {
+					await this.present(existing.scene, existing.nodes, existing.canvas, beforeActivate, registration.retention);
+				} catch (error) {
+					this.reportPreparation(error);
+					throw error;
+				}
+				return;
+			}
 			const scene = new Scene(id), nodes = [], controller = new AbortController();
 			let canvas;
 			const pointer = this.channelFor(scene);
@@ -3492,8 +4659,10 @@ var Game = class {
 			this.staging = scene;
 			scene.onDispose(() => controller.abort());
 			try {
-				await this.wait(Promise.resolve(setup({
+				const assets = this.assets.scope(scene);
+				await this.wait(Promise.resolve(registration.setup({
 					scene,
+					assets,
 					get tweens() {
 						return scene.tweens;
 					},
@@ -3524,10 +4693,18 @@ var Game = class {
 					onDispose: (callback) => scene.onDispose(callback)
 				})));
 				this.assertAlive();
-				await this.present(scene, nodes, canvas, () => {
-					if (this.pendingScene?.task === task) this.pendingScene = void 0;
+				if (registration.retention === "retain") scene.onDispose(() => {
+					if (this.retainedScenes.get(id)?.scene === scene) this.retainedScenes.delete(id);
+				});
+				await this.present(scene, nodes, canvas, beforeActivate, registration.retention);
+				this.assertAlive();
+				if (registration.retention === "retain" && !scene.disposed) this.retainedScenes.set(id, {
+					scene,
+					nodes,
+					canvas
 				});
 			} catch (error) {
+				this.reportPreparation(error);
 				try {
 					scene.dispose();
 				} catch (cleanupError) {
@@ -3547,10 +4724,22 @@ var Game = class {
 		this.queue = task.catch(() => {});
 		return task;
 	}
-	async present(scene, nodes, canvas, beforeActivate) {
-		let prepared, ui, committed = false;
+	reportPreparation(error) {
+		if (this.ready && !this.dead) this.logger.report(error, {
+			source: "engine.scene",
+			message: "Simpludify could not prepare the requested scene",
+			fatal: false,
+			standardOutput: false
+		});
+	}
+	async present(scene, nodes, canvas, beforeActivate, retention = "dispose") {
+		let prepared, ui, activated = false, committed = false;
 		let canvasPresentation;
 		let virtualPresentation;
+		const hooks = [];
+		const detach = () => {
+			for (const off of hooks.splice(0)) off();
+		};
 		try {
 			const preparing = this.renderer.prepare(scene);
 			preparing.then((value) => {
@@ -3563,28 +4752,34 @@ var Game = class {
 			prepared = await this.wait(preparing);
 			this.assertAlive();
 			ui = mountUI(nodes, this.report);
-			scene.onDispose(ui.dispose);
+			hooks.push(scene.onDispose(ui.dispose));
 			if (canvas) {
 				canvas.setErrorHandler(this.report);
 				const renderer = this.renderer;
 				if (!renderer.prepareCanvasUI) throw new EngineError("RENDERER_CAPABILITY", "Renderer does not support Canvas UI");
 				canvasPresentation = renderer.prepareCanvasUI(canvas, this.pointers.routing);
-				scene.onDispose(() => canvasPresentation?.dispose());
+				hooks.push(scene.onDispose(() => canvasPresentation?.dispose()));
 			}
 			virtualPresentation = this.prepareVirtual(scene);
-			scene.markReady();
+			if (scene.state === SceneState.Preparing) scene.markReady();
 			beforeActivate?.();
 			this.errorBox.hidden = true;
 			try {
 				if (this.playback && this.playbackScene !== scene) this.stopReplay();
-				this.engine.activate(scene);
+				this.engine.activate(scene, { previous: this.activeRetention });
 			} catch (error) {
-				if (this.engine.scene !== scene || scene.state !== SceneState.Active) throw error;
-				this.report(error);
+				if (this.engine.scene !== scene) throw error;
+				activated = scene.disposed;
+				if (scene.state !== SceneState.Active) throw error;
+				this.report(error, "engine.scene");
 			}
+			activated = true;
 			this.assertAlive();
-			const oldPrepared = this.prepared, oldUI = this.ui, oldCanvas = this.canvasPresentation, oldVirtual = this.virtualPresentation;
+			if (scene.disposed) throw new EngineError("SCENE_DISPOSED", "Scene was disposed during activation");
+			const oldPrepared = this.prepared, oldUI = this.ui, oldCanvasUI = this.canvas, detachOld = this.detachPresentation, oldCanvas = this.canvasPresentation, oldVirtual = this.virtualPresentation;
 			this.prepared = prepared;
+			this.detachPresentation = detach;
+			this.activeRetention = retention;
 			this.ui = ui;
 			this.canvas = canvas;
 			this.canvasPresentation = canvasPresentation;
@@ -3595,6 +4790,13 @@ var Game = class {
 				this.element.append(ui.element);
 			} finally {
 				for (const cleanup of [
+					() => detachOld?.(),
+					() => {
+						if (oldCanvasUI && !oldCanvasUI.disposed) {
+							oldCanvasUI.focus();
+							oldCanvasUI.stopMotion();
+						}
+					},
 					() => oldPrepared?.dispose(),
 					() => oldUI?.dispose(),
 					() => oldCanvas?.dispose(),
@@ -3613,6 +4815,7 @@ var Game = class {
 			this.assertAlive();
 		} catch (error) {
 			if (!committed) for (const cleanup of [
+				detach,
 				() => prepared?.dispose(),
 				() => ui?.dispose(),
 				() => canvasPresentation?.dispose(),
@@ -3622,7 +4825,15 @@ var Game = class {
 			} catch (cleanupError) {
 				this.report(cleanupError);
 			}
-			if (committed) this.dispose();
+			if (activated && !this.dead) {
+				this.logger.report(error, {
+					source: "engine.presentation",
+					message: "Simpludify could not present the active scene",
+					fatal: true,
+					standardOutput: false
+				});
+				this.dispose();
+			}
 			throw error;
 		}
 	}
@@ -3801,16 +5012,21 @@ var Game = class {
 			}
 			if (!this.dead) this.frame = this.frames.request(this.tick);
 		} catch (error) {
-			this.report(error);
+			this.report(error, "engine.frame", true);
 			this.dispose();
 		}
 	};
-	report = (error) => {
-		this.errorBox.textContent = error instanceof Error ? error.message : String(error);
+	report = (error, source = "engine.runtime", fatal = false) => {
+		const message = fatal ? "Simpludify stopped after a runtime error" : "Simpludify encountered a runtime error";
+		this.logger.report(error, {
+			source,
+			fatal,
+			message
+		});
+		this.errorBox.textContent = message;
 		this.errorBox.hidden = false;
 		try {
 			if (this.options.onError) this.options.onError(error);
-			else console.error(error);
 		} catch {}
 	};
 	dispose() {
@@ -3829,10 +5045,15 @@ var Game = class {
 			() => this.virtualPresentation?.dispose(),
 			() => this.canvas?.dispose(),
 			() => this.observer.disconnect(),
+			() => this.detachPresentation?.(),
 			() => this.ui?.dispose(),
 			() => this.prepared?.dispose(),
 			() => this.renderer.dispose(),
+			() => this.audio.dispose(),
 			() => this.engine.dispose(),
+			() => this.fontUse?.release(),
+			() => this.assetStore.dispose(),
+			() => this.imagePool.dispose(),
 			() => this.element.remove()
 		]) try {
 			cleanup();
@@ -3846,11 +5067,18 @@ var Game = class {
 		this.canvasPresentation = void 0;
 		this.virtualPresentation = void 0;
 		this.defaultCanvas = void 0;
+		this.fontUse = void 0;
 		this.defaultUI.length = 0;
 		this.scenes.clear();
+		this.retainedScenes.clear();
+		this.detachPresentation = void 0;
 		this.pendingScene = void 0;
 	}
 };
+function retentionPolicy(value) {
+	if (value !== "dispose" && value !== "retain") throw new EngineError("INVALID_VALUE", "Unknown scene retention policy");
+	return value;
+}
 function validFontFamily(value) {
 	const syntax = value.replace(/"(?:\\[^\r\n]|[^"\\])*"|'(?:\\[^\r\n]|[^'\\])*'/g, "family").replace(/\\(?:[0-9a-f]{1,6}[ \t]?|[^\r\n])/gi, "x");
 	return value.trim().length > 0 && !/[\r\n\0]/.test(value) && !/[;{}<>\\"']|url\s*\(/i.test(syntax);