@moku-labs/game 0.4.5 → 0.5.0

package/dist/index.mjs

@@ -3,7 +3,7 @@ import { a as enableDraftPatches, i as dropDrafts, o as finishDrafts, r as deepF
 import { c as findNode, d as slotNames, f as compact, i as servePaused, l as framePath, n as captureFrame, o as collectFlows, p as pushEntry, r as serveCaptures, s as describeGraph, t as cancelCaptures, u as graphHash } from "./capture-fpd83Mi5.mjs";
 import { A as system, C as Exiting, D as component, E as Tree, O as mut, S as sprite, T as Order, _ as Parent, a as visualOf$1, b as Transform, c as Text, d as defineTextStyles, f as label, g as NineSlice, h as Display, j as tag, k as resource, l as bind, m as textFor, n as fitScaleOf, o as visualRectOf, p as readStyle, r as samePose, s as Countdown, t as CONTENT, u as builtInStyles, v as Shape, w as Layer, x as componentsFor, y as Sprite } from "./visual-DUvvPPCt.mjs";
 import { n as isDev } from "./dev-wKLgOw7c.mjs";
-import { n as flatten, r as defineComponent } from "./flatten-BkXuscAV.mjs";
+import { i as isComponentDefinition, n as flatten, r as defineComponent } from "./flatten-BkXuscAV.mjs";
 import { envPlugin, logPlugin } from "@moku-labs/common/browser";
 import { createCoreConfig } from "@moku-labs/core";
 /**
@@ -7359,6 +7359,17 @@ function createProjectionApi(ctx, deps) {
 		}
 		state.hints.length = 0;
 	};
+	/**
+	* Marks every mounted projection dirty and forces `view` for every item on the next frame.
+	*/
+	const forceRerun = () => {
+		const dirty = state.dirty ?? emptyDirty();
+		dirty.causes.push("rerun");
+		dirty.roots.add("player");
+		dirty.roots.add("session");
+		dirty.force = true;
+		state.dirty = dirty;
+	};
 	const restOf = (entity) => state.rests.get(entity) ?? emptyRest();
 	const elementView = (entity) => ({
 		entity,
@@ -7376,6 +7387,13 @@ function createProjectionApi(ctx, deps) {
 			if (state.specs.has(spec.name)) throw new Error(`[game] Projection "${spec.name}" is registered twice.\n  Give the second projection another name.`);
 			state.specs.set(spec.name, spec);
 		},
+		replace: (spec) => {
+			if (!state.specs.has(spec.name)) throw new Error(`[game] Projection "${spec.name}" is not registered.\n  Register it before replacing it.`);
+			const mounted = state.mounted.has(spec.name);
+			if (mounted) checkLayers(pctx, spec);
+			state.specs.set(spec.name, spec);
+			if (mounted) forceRerun();
+		},
 		setLayers: (list) => {
 			state.layers = Object.freeze(list.map((layer) => ({ ...layer })));
 		},
@@ -7510,14 +7528,7 @@ function createProjectionApi(ctx, deps) {
 				state.rests.delete(entity);
 			};
 		},
-		rerunAll: () => {
-			const dirty = state.dirty ?? emptyDirty();
-			dirty.causes.push("rerun");
-			dirty.roots.add("player");
-			dirty.roots.add("session");
-			dirty.force = true;
-			state.dirty = dirty;
-		},
+		rerunAll: forceRerun,
 		markDirty: (roots, cause) => {
 			const dirty = state.dirty ?? emptyDirty();
 			dirty.causes.push(cause);
@@ -7663,6 +7674,7 @@ function exposeEcs(ecs, projection) {
 function exposeProjection(projection) {
 	return {
 		register: projection.register,
+		replace: projection.replace,
 		setLayers: projection.setLayers,
 		layers: projection.layers,
 		mount: projection.mount,
@@ -14471,8 +14483,8 @@ function stopAnim(state) {
 * from a node are the same timeline.
 */
 /**
-* Creates the anim API: `app.anim.play`, `finishAll`, `active`, `onMark`, `reducedMotion` and
-* `setReducedMotion`.
+* Creates the anim API: `app.anim.play`, `finishAll`, `active`, `onMark`, `reducedMotion`,
+* `setReducedMotion` and `replace`.
 *
 * @param ctx - Kernel context of the anim plugin.
 * @returns The plugin API.
@@ -14493,6 +14505,10 @@ function createAnimApi(ctx) {
 		reducedMotion: () => actx.state.reducedMotion,
 		setReducedMotion: (on) => {
 			actx.state.reducedMotion = on;
+		},
+		replace: (definition) => {
+			if (!actx.state.registry.has(definition.id)) throw new Error(`[game] Animation "${definition.id}" is not registered.\n  Register it before replacing it.`);
+			actx.state.registry.set(definition.id, definition);
 		}
 	};
 }
@@ -16565,13 +16581,19 @@ const assetsPlugin = /*#__PURE__*/ createPlugin$1("assets", {
 //#endregion
 //#region src/plugins/scenes/api.ts
 /**
-* Creates the scenes API: `app.scenes.current()`.
+* Creates the scenes API: `app.scenes.current()` and `app.scenes.expect(id)`.
 *
 * @param ctx - Kernel context of the scenes plugin.
 * @returns The plugin API.
 */
 function createScenesApi(ctx) {
-	return { current: () => ctx.state.current };
+	return {
+		current: () => ctx.state.current,
+		expect: (id) => {
+			if (!ctx.state.scenes.has(id)) throw new Error(`[game] Scene "${id}" is not registered.\n  List it in the scenes of a feature.`);
+			ctx.state.pending = id;
+		}
+	};
 }
 //#endregion
 //#region src/plugins/scenes/switch.ts
@@ -16639,6 +16661,23 @@ function targetOf(ctx, node, run) {
 	return target;
 }
 /**
+* Reads the scene an `over` node asks for. An over node never switches a mounted scene; a rest
+* one takes the expected scene while nothing is mounted, so a restore at a popup builds the scene
+* under it. A scene the over node names itself is only warned about.
+*
+* @param ctx - Domain context of the plugin.
+* @param node - The over node being entered.
+* @returns The expected scene id, or `undefined` when nothing has to happen.
+*/
+function overTargetOf(ctx, node) {
+	const state = ctx.state;
+	if (node.scene !== void 0) ctx.log.warn("scenes: an over node cannot name a scene", { path: node.path });
+	if (!node.rest || state.current !== void 0) return void 0;
+	const target = state.pending;
+	state.pending = void 0;
+	return target;
+}
+/**
 * Builds the scene in one synchronous block: the layers, then the projections of the old scene
 * out, then the ones of the new scene in, then the frame loop out of its idle cap, and only then
 * the event.
@@ -16663,8 +16702,9 @@ function apply(ctx, scene) {
 	});
 }
 /**
-* The `scene` stage of entering a node: the whole switch. An `over` node never switches, a node
-* without a scene keeps the current one, and an aborted node returns without touching anything.
+* The `scene` stage of entering a node: the whole switch. An `over` node never switches a mounted
+* scene, a node without a scene keeps the current one, and an aborted node returns without
+* touching anything.
 *
 * @param ctx - Domain context of the plugin.
 * @param node - The node being entered.
@@ -16681,11 +16721,7 @@ function apply(ctx, scene) {
 * ```
 */
 async function enterScene(ctx, node, run) {
-	if (node.over) {
-		if (node.scene !== void 0) ctx.log.warn("scenes: an over node cannot name a scene", { path: node.path });
-		return;
-	}
-	const target = targetOf(ctx, node, run);
+	const target = node.over ? overTargetOf(ctx, node) : targetOf(ctx, node, run);
 	if (target === void 0 || target === ctx.state.current) return;
 	const scene = ctx.state.scenes.get(target);
 	if (scene === void 0) throw new Error(`[game] Scene "${target}" is not registered.\n  List it in the scenes of a feature.`);
@@ -20476,7 +20512,7 @@ function read(target, name) {
 * @param entry - What the feature put in its `emitters` list.
 * @returns True when it carries an id and a config with textures.
 */
-function isEmitterDefinition(entry) {
+function isEmitterDefinition$1(entry) {
 	if (typeof entry !== "object" || entry === null) return false;
 	const config = read(entry, "config");
 	return typeof read(entry, "id") === "string" && typeof config === "object" && config !== null && Array.isArray(read(config, "textures"));
@@ -20494,7 +20530,7 @@ function isFilterComponent(entry) {
 }
 /** The check of each feature key `effects` reads. */
 const entryChecks = {
-	emitters: isEmitterDefinition,
+	emitters: isEmitterDefinition$1,
 	filters: isFilterComponent
 };
 /**
@@ -20643,31 +20679,61 @@ function stopEffects(state) {
 //#endregion
 //#region src/plugins/effects/handlers.ts
 /**
-* @file effects plugin — the one hook: a bundle that left takes the effects drawn with its
-* textures along, particles and `Displacement` maps alike, whatever their space.
+* @file effects plugin — the two hooks: a bundle that left takes the effects drawn with its
+* textures along, particles and `Displacement` maps alike, whatever their space; a dev hot swap
+* replaces the registered emitters its module exports.
+*/
+/**
+* Replaces every registered emitter the saved module exports and drops its bake, so the next
+* instance bakes the new config; a live instance keeps its own bake. An id no feature registered
+* warns `effects:hot-unknown-emitter`: a new emitter needs a feature, so a reload.
+*
+* @param ctx - Kernel context of the effects plugin.
+* @param module - The new exports of the saved module.
 */
+function replaceEmitters(ctx, module) {
+	const { state } = ctx;
+	for (const entry of Object.values(module)) {
+		if (!isEmitterDefinition$1(entry)) continue;
+		if (!state.emitters.has(entry.id)) {
+			ctx.log.warn("effects:hot-unknown-emitter", { id: entry.id });
+			continue;
+		}
+		state.emitters.set(entry.id, entry);
+		state.baked.delete(entry.id);
+	}
+}
 /**
-* Creates the hook handlers. The domain context is built when the hook first fires, not while
-* this factory runs: the kernel registers hooks before it builds the plugin APIs.
+* Creates the hook handlers. The domain context is built when a hook that needs the deps first
+* fires, not while this factory runs: the kernel registers hooks before it builds the plugin APIs.
 *
 * @param ctx - Kernel context of the effects plugin.
-* @returns The hook of the plugin.
+* @returns The hooks of the plugin.
 */
 function createHandlers$2(ctx) {
 	let effects;
-	return { 
-	/**
-	* Retires the particle instances and the `Displacement` filters whose textures left, drops
-	* their bakes, and lets their keys warn again once the bundle is back.
-	*
-	* @param payload - The bundle that left and the keys it carried.
-	*/
-"assets:bundle-unloaded": (payload) => {
-		effects ??= withDeps$3(ctx);
-		retireParticleKeys(effects, payload.keys);
-		retireFilterMaps(effects, payload.keys);
-		for (const key of payload.keys) effects.state.warned.delete(`texture:${key}`);
-	} };
+	return {
+		/**
+		* Retires the particle instances and the `Displacement` filters whose textures left, drops
+		* their bakes, and lets their keys warn again once the bundle is back.
+		*
+		* @param payload - The bundle that left and the keys it carried.
+		*/
+		"assets:bundle-unloaded": (payload) => {
+			effects ??= withDeps$3(ctx);
+			retireParticleKeys(effects, payload.keys);
+			retireFilterMaps(effects, payload.keys);
+			for (const key of payload.keys) effects.state.warned.delete(`texture:${key}`);
+		},
+		/**
+		* Replaces the registered emitters a dev hot swap brought. Only dev emits it.
+		*
+		* @param payload - The saved file and its new exports.
+		*/
+		"ui:hot-swap": (payload) => {
+			replaceEmitters(ctx, payload.module);
+		}
+	};
 }
 //#endregion
 //#region src/plugins/effects/state.ts
@@ -21033,6 +21099,19 @@ function isReady(entry) {
 	return typeof entry.messages !== "function";
 }
 /**
+* Tells a lazy strings module, a loader that fetches it, from the module itself.
+*
+* @param value - The module, or the loader that fetches it.
+* @returns True for a function.
+* @example
+* ```ts
+* isLoader(async () => ({ "hud.orders": "Orders" })); // true
+* ```
+*/
+function isLoader(value) {
+	return typeof value === "function";
+}
+/**
 * Records one module under its locale, keeping the name it can be blamed under.
 *
 * @param state - The plugin state.
@@ -21042,9 +21121,8 @@ function isReady(entry) {
 */
 function register(state, locale, from, value) {
 	const entries = state.registered.get(locale) ?? [];
-	if (typeof value === "function") {
-		const load = value;
-		const loader = async () => messagesOf(await load());
+	if (isLoader(value)) {
+		const loader = async () => messagesOf(await value());
 		entries.push({
 			from,
 			messages: loader
@@ -21084,7 +21162,8 @@ function mergeEager(state) {
 	}
 }
 /**
-* Runs the loaders of one locale, once, and merges everything registered for it.
+* Runs the loaders of one locale, once, and merges everything registered for it. The resolved
+* modules replace the loaders in the registry, so `replace` finds the keys of a lazy locale too.
 *
 * @param state - The plugin state.
 * @param locale - The locale to load.
@@ -21102,7 +21181,9 @@ async function loadLocale(state, locale) {
 			messages
 		});
 	}
-	state.loaded.set(locale, mergeLocales(resolved));
+	const merged = mergeLocales(resolved);
+	state.registered.set(locale, resolved);
+	state.loaded.set(locale, merged);
 }
 /**
 * Collects every compiled module, merges the eager locales and resolves the start locale and the
@@ -21127,7 +21208,8 @@ async function startI18n(ctx) {
 /**
 * @file i18n plugin — the public API factory: the current locale, the switch that loads a module
 * and sends the one event, the two `format` forms every label goes through, and the duration a
-* countdown reads. This is the only place in the engine where a locale is read.
+* countdown reads, and the swap of one module the dev hot swap calls. This is the only place in the
+* engine where a locale is read.
 */
 /**
 * Answers the formatter kit of one locale, building it on first use.
@@ -21224,10 +21306,55 @@ async function setLocale(ctx, locale) {
 	await chain;
 }
 /**
+* Wraps a module that matches no single registered module in the message shape of the framework.
+*
+* @param locale - The locale of the module.
+* @returns The error to throw.
+*/
+function noSingleModule(locale) {
+	return /* @__PURE__ */ new Error(`[game] Strings for "${locale}" match no single registered module.\n  Replace them with the module of one feature, or reload the page.`);
+}
+/**
+* Tells whether a registered module is resolved and carries at least one key of `messages`.
+*
+* @param entry - The registered module.
+* @param messages - The new module.
+* @returns True when the entry is the one `messages` replaces, or one of several.
+*/
+function overlaps(entry, messages) {
+	return isReady(entry) && Object.keys(entry.messages).some((key) => Object.hasOwn(messages, key));
+}
+/**
+* Swaps the one registered module of a loaded locale whose keys overlap the new module, merges
+* the locale again and tells `text` when a label may read it.
+*
+* @param ctx - Kernel context of the i18n plugin.
+* @param locale - The locale of the new module.
+* @param messages - The new module.
+* @throws {Error} When no registered module, or more than one, shares a key with the new one.
+*/
+function replaceModule(ctx, locale, messages) {
+	const { state } = ctx;
+	if (!state.loaded.has(locale)) return;
+	const entries = state.registered.get(locale) ?? [];
+	const owners = entries.filter((entry) => overlaps(entry, messages));
+	const [owner] = owners;
+	if (owner === void 0 || owners.length > 1) throw noSingleModule(locale);
+	const next = entries.map((entry) => entry === owner ? {
+		from: owner.from,
+		messages
+	} : entry);
+	const merged = mergeLocales(next.filter((entry) => isReady(entry)));
+	state.registered.set(locale, next);
+	state.loaded.set(locale, merged);
+	state.warned.clear();
+	if (locale === state.locale || locale === ctx.config.fallback) ctx.emit("i18n:locale-changed", { locale: state.locale });
+}
+/**
 * Builds the API of the plugin.
 *
 * @param ctx - Kernel context of the i18n plugin.
-* @returns The seven members of `app.i18n`.
+* @returns The eight members of `app.i18n`.
 */
 function createI18nApi(ctx) {
 	return {
@@ -21240,7 +21367,8 @@ function createI18nApi(ctx) {
 			style,
 			secondsDisplay: "always"
 		}).format(durationInput(ms)),
-		locales: () => [...ctx.state.registered.keys()].toSorted()
+		locales: () => [...ctx.state.registered.keys()].toSorted(),
+		replace: (locale, messages) => replaceModule(ctx, locale, messages)
 	};
 }
 //#endregion
@@ -21310,7 +21438,7 @@ function createI18nState() {
 */
 const i18nPlugin = /*#__PURE__*/ createPlugin$1("i18n", {
 	depends: [flowPlugin],
-	events: (register) => register.map({ "i18n:locale-changed": "The current locale changed and its messages are loaded" }),
+	events: (register) => register.map({ "i18n:locale-changed": "The current locale changed, or its messages were replaced" }),
 	config: {
 		locale: "en",
 		fallback: "en",
@@ -25663,7 +25791,7 @@ function createTextAdapter(ctx) {
 			if (pixi === void 0 || object === void 0) return;
 			const container = asContainer(object);
 			container.alpha = next.alpha;
-			if (previous.resolved === next.resolved && previous.style === next.style && samePoint(previous.anchor, next.anchor)) return;
+			if (previous.resolved === next.resolved && previous.style === next.style && samePoint(previous.anchor, next.anchor) && ctx.state.drawn.get(container)?.style === styleOf$1(ctx, next.style)) return;
 			redraw(ctx, pixi, container, previous, next);
 		},
 		destroy: (object) => {
@@ -25691,11 +25819,13 @@ function asContainer(object) {
 //#region src/plugins/text/lifecycle.ts
 /**
 * @file text plugin — lifecycle: the dependency resolution, the style table read out of the
-* feature descriptions, the four registrations `onStart` opens, and the teardown that closes
-* exactly those.
+* feature descriptions and written again by the dev hot swap, the four registrations `onStart`
+* opens, and the teardown that closes exactly those.
 */
 /** The owner of the two built-in styles, which no feature can collide with. */
 const BUILT_IN = "text";
+/** The owner of a style name the dev hot swap added, which no feature registered at start. */
+const HOT_SWAP = "hot swap";
 /**
 * Resolves the seven dependency APIs with `ctx.require`.
 *
@@ -25775,6 +25905,28 @@ function collectFonts(ctx) {
 	}
 }
 /**
+* Writes the styles of a saved styles file over the table: a known name keeps its owner, a new
+* name is added. Then the fonts of the new styles are read, the layouts measured with the old
+* styles are dropped, and every label is marked, so the next frame lays it out again and the
+* display adapter redraws it with the new style object.
+*
+* @param ctx - Domain context of the text plugin.
+* @param styles - What `defineTextStyles` returned in the saved module.
+*/
+function replaceStyles(ctx, styles) {
+	for (const [name, value] of Object.entries(styles.map)) {
+		const style = readStyle(name, value);
+		if (style === void 0) continue;
+		ctx.state.styles.set(name, style);
+		if (!ctx.state.styleOwner.has(name)) ctx.state.styleOwner.set(name, HOT_SWAP);
+	}
+	collectFonts(ctx);
+	installFonts(ctx);
+	ctx.state.cache.clear();
+	markDirty(ctx);
+	ctx.deps.time.wake();
+}
+/**
 * Opens what the plugin owns: the style table, the font keys, the layout system, the two world
 * hooks of `Text` and the display adapter. The fonts of a bundle that is already loaded are read
 * at once, because the boot bundle lands before this runs.
@@ -25818,12 +25970,13 @@ function stopText(state) {
 //#endregion
 //#region src/plugins/text/api.ts
 /**
-* @file text plugin — API factory. Three members: how big a piece of text is, whether a font has
-* a glyph, and which styles the game registered. The domain context is built on the first call, because the kernel builds the
+* @file text plugin — API factory. Four members: how big a piece of text is, whether a font has
+* a glyph, which styles the game registered, and the dev hot swap of a styles file. The domain context is built on the first call, because the kernel builds the
 * plugin APIs before every dependency is resolvable.
 */
 /**
-* Creates the text API: `app.text.measure(...)`, `app.text.hasGlyph(...)` and `app.text.styles()`.
+* Creates the text API: `app.text.measure(...)`, `app.text.hasGlyph(...)`, `app.text.styles()`
+* and `app.text.replaceStyles(...)`.
 *
 * @param ctx - Kernel context of the text plugin.
 * @returns The plugin API.
@@ -25840,7 +25993,10 @@ function createTextApi(ctx) {
 			return sizeOf(layoutFor(tctx, sourceOf(tctx, content), style));
 		},
 		hasGlyph: (char, style) => hasGlyphOf(text(), char, style),
-		styles: () => Object.freeze([...ctx.state.styles.keys()])
+		styles: () => Object.freeze([...ctx.state.styles.keys()]),
+		replaceStyles: (styles) => {
+			replaceStyles(text(), styles);
+		}
 	};
 }
 //#endregion
@@ -27591,6 +27747,10 @@ function rowStyleOf(style, rowHeight) {
 * @file ui/jsx — `tree()`: the live screen as plain data. A pure reader over the state, so it
 * answers in plain Bun with no renderer at all.
 */
+/**
+* The warning a tree read drops: `text` already reported a bad tag when it resolved the label.
+*/
+function quiet() {}
 /** What `tree()` answers with when nothing is mounted. */
 const EMPTY = {
 	key: void 0,
@@ -27614,21 +27774,53 @@ const EMPTY = {
 	children: []
 };
 /**
+* The words of a tagged string, as a reader sees them: the text of every run joined, the tags
+* and the icons left out.
+*
+* @param source - A resolved string, or a plain `content` prop.
+* @returns The plain string.
+* @example
+* ```ts
+* plainOf("<b>+5</b> <icon=hud.coin>"); // "+5 "
+* ```
+*/
+function plainOf(source) {
+	let plain = "";
+	for (const run of parseTags(source, quiet)) if (run.kind === "text") plain += run.text;
+	return plain;
+}
+/**
+* The text a text element draws: the string `text` resolved for its entity, after `tr()` and
+* binds, else its `content` prop when that is a plain string, as before its first frame.
+*
+* @param element - The element to read.
+* @param resolvedOf - Reads the resolved string of an entity; none for a tree read without a world.
+* @returns The plain string, or `undefined` for any other element and for an empty text.
+*/
+function contentOf$2(element, resolvedOf) {
+	if (element.type !== "text") return void 0;
+	const resolved = resolvedOf?.(element.entity);
+	const source = resolved === void 0 || resolved === "" ? element.node.props.content : resolved;
+	const plain = typeof source === "string" ? plainOf(source) : "";
+	return plain === "" ? void 0 : plain;
+}
+/**
 * Turns one element and its subtree into snapshot nodes. The rect is natural; a fitted element
-* adds the scale it is drawn at; a text field adds its value; a windowed scroll adds its window.
-* The spacers of a windowed scroll are left out: its content lists the live rows.
+* adds the scale it is drawn at; a text adds the words it draws; a text field adds its value; a
+* windowed scroll adds its window. The spacers of a windowed scroll are left out: its content
+* lists the live rows.
 *
 * @param state - The jsx state.
 * @param element - The element to read.
+* @param resolvedOf - Reads the resolved string of a text entity; none in a read without a world.
 * @returns The node, with its children in child order.
 */
-function nodeOf(state, element) {
+function nodeOf(state, element, resolvedOf) {
 	const children = [];
 	for (const child of element.children) {
 		const childElement = state.elements.get(child);
-		if (childElement !== void 0 && !isOwnKey(childElement.key)) children.push(nodeOf(state, childElement));
+		if (childElement !== void 0 && !isOwnKey(childElement.key)) children.push(nodeOf(state, childElement, resolvedOf));
 	}
-	const local = element.instance === void 0 ? void 0 : state.instances.get(element.instance)?.local;
 	const node = {
 		key: element.key,
 		type: element.type,
@@ -27637,10 +27829,15 @@ function nodeOf(state, element) {
 		state: { ...element.is },
 		children
 	};
-	const fitted = element.style.fit === "contain" ? {
+	const content = contentOf$2(element, resolvedOf);
+	const worded = content === void 0 ? node : {
 		...node,
+		content
+	};
+	const fitted = element.style.fit === "contain" ? {
+		...worded,
 		fitScale: element.fit
-	} : node;
+	} : worded;
 	const field = state.fields.get(element.entity);
 	const valued = field === void 0 ? fitted : {
 		...fitted,
@@ -27655,6 +27852,7 @@ function nodeOf(state, element) {
 			rows: window.rows
 		}
 	};
+	const local = element.instance === void 0 ? void 0 : state.instances.get(element.instance)?.local;
 	return local === void 0 ? windowed : {
 		...windowed,
 		local: { ...local }
@@ -27689,17 +27887,18 @@ function sortedRoots(state, layers) {
 *
 * @param state - The jsx state.
 * @param layers - The layer names of the scene, in draw order.
+* @param resolvedOf - Reads the string `text` resolved for an entity; none in a read without a world.
 * @returns One root node, or every root under a `screen` node.
 * @example
 * ```ts
 * readTree({ roots: new Map(), elements: new Map() } as unknown as JsxState).type; // "screen"
 * ```
 */
-function readTree(state, layers = []) {
+function readTree(state, layers = [], resolvedOf) {
 	const nodes = [];
 	for (const root of sortedRoots(state, layers)) {
 		const element = root.element === void 0 ? void 0 : state.elements.get(root.element);
-		if (element !== void 0) nodes.push(nodeOf(state, element));
+		if (element !== void 0) nodes.push(nodeOf(state, element, resolvedOf));
 	}
 	const single = nodes.length === 1 ? nodes[0] : void 0;
 	if (single !== void 0) return single;
@@ -30113,6 +30312,7 @@ function createJsxApi(ctx, modules) {
 	});
 	const frame = createReconciler(ctx, modules, fields);
 	const focus = createFocus(ctx, frame.markPointer, layerNames, fields);
+	const resolvedOf = (entity) => ctx.deps.world.ecs.get(entity, Text)?.resolved;
 	const find = (key) => {
 		for (const root of sortedRoots(state, layerNames())) {
 			const entity = state.byKey.get(root.entity)?.get(key);
@@ -30120,7 +30320,7 @@ function createJsxApi(ctx, modules) {
 		}
 	};
 	return {
-		tree: () => readTree(state, layerNames()),
+		tree: () => readTree(state, layerNames(), resolvedOf),
 		find,
 		lint: () => runLint(ctx),
 		fill: (key, value) => {
@@ -30146,6 +30346,15 @@ function createJsxApi(ctx, modules) {
 			if (state.components.has(definition.name)) throw new Error(`[game] Component "${definition.name}" is defined twice.\n  Use one defineComponent() call and import it.`);
 			state.components.set(definition.name, definition);
 		},
+		replace: (definition) => {
+			state.components.set(definition.name, definition);
+		},
+		refreshAll: () => {
+			for (const root of state.roots.values()) {
+				root.dirty = true;
+				root.needsSolve = true;
+			}
+		},
 		mountRoot: frame.mountRoot,
 		unmountRoot: frame.unmountRoot,
 		reclaimPopup: (component, props, link) => reclaimPopup(ctx, state, component, props, link),
@@ -31543,6 +31752,347 @@ function createLayoutApi(ctx) {
 	};
 }
 //#endregion
+//#region src/plugins/ui/hot.ts
+/** The global the footer of `@moku-labs/game/hot` calls. */
+const HOT_GLOBAL = "__moku_hot";
+/** A strings module `assets:keys` generates; the group is its locale. */
+const STRINGS_FILE = /\/generated\/strings\.([\w-]+)\.ts$/;
+/**
+* The `kind` of every value a game registers by value at start: ECS component and tag types
+* (filters too), nodes, slots, flows, asset bundles and plugin owners. Any other `kind` marks
+* data, an effect descriptor or a timeline step, which a node reads through the live binding.
+*/
+const REGISTERED_KINDS = {
+	component: true,
+	tag: true,
+	node: true,
+	slot: true,
+	flow: true,
+	bundles: true,
+	plugin: true
+};
+/**
+* Tells whether a value carries own members a definition could sit on.
+*
+* @param value - One export of the module.
+* @returns True for an object or a function.
+* @example
+* ```ts
+* hasMembers({ id: "home" }); // true
+* ```
+*/
+function hasMembers(value) {
+	return typeof value === "object" && value !== null || typeof value === "function";
+}
+/**
+* Tells whether a value is an object, not `null` and not a function.
+*
+* @param value - One export, or one member of it.
+* @returns True for an object.
+* @example
+* ```ts
+* isObject({ rate: 12 }); // true
+* ```
+*/
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Tells whether a value has an own string member of that name.
+*
+* @param value - One export of the module.
+* @param name - The member asked for.
+* @returns True when the value itself holds a string there.
+* @example
+* ```ts
+* hasOwnString({ kind: "flow" }, "kind"); // true
+* ```
+*/
+function hasOwnString(value, name) {
+	return Object.hasOwn(value, name) && typeof Reflect.get(value, name) === "string";
+}
+/**
+* Tells a projection spec from any other export: a string `name` and `layer`, a `from` and a
+* `view`, and a `key` unless `from` returns one plain object.
+*
+* @param value - One export of the module.
+* @returns True when `projection()` built it.
+* @example
+* ```ts
+* isProjectionSpec({ name: "hud", layer: "ui", from: () => ({}), view: () => [] }); // true
+* ```
+*/
+function isProjectionSpec(value) {
+	if (!isObject(value)) return false;
+	const typeOf = (name) => typeof Reflect.get(value, name);
+	const hasKeyOrNone = typeOf("key") === "undefined" || typeOf("key") === "function";
+	return typeOf("name") === "string" && typeOf("layer") === "string" && typeOf("from") === "function" && typeOf("view") === "function" && hasKeyOrNone;
+}
+/**
+* Tells an animation from any other export: an own string `id`, a `build` function and `slots`.
+*
+* @param value - One export of the module.
+* @returns True when `defineAnimation` built it.
+* @example
+* ```ts
+* isAnimationDefinition({ id: "hud.coinsFly", slots: {}, build: () => [] }); // true
+* ```
+*/
+function isAnimationDefinition(value) {
+	return isObject(value) && hasOwnString(value, "id") && typeof Reflect.get(value, "build") === "function" && Object.hasOwn(value, "slots");
+}
+/**
+* Tells an emitter from any other export: an own string `id` and a `config` object.
+*
+* @param value - One export of the module.
+* @returns True when `defineEmitter` built it.
+* @example
+* ```ts
+* isEmitterDefinition({ id: "fx.steam", config: { rate: 12 } }); // true
+* ```
+*/
+function isEmitterDefinition(value) {
+	return isObject(value) && hasOwnString(value, "id") && isObject(Reflect.get(value, "config"));
+}
+/**
+* Tells compiled messages from any other export: a record whose values are all functions.
+*
+* @param value - The `default` export of a strings file.
+* @returns True when `assets:keys` wrote it.
+* @example
+* ```ts
+* isCompiledMessages({ "hud.orders": () => [] }); // true
+* ```
+*/
+function isCompiledMessages(value) {
+	return isObject(value) && Object.values(value).every((message) => typeof message === "function");
+}
+/**
+* Tells text styles from any other export: `kind` `"textStyles"` and a `map`.
+*
+* @param value - One export of the module.
+* @returns True when `defineTextStyles` built it.
+* @example
+* ```ts
+* isTextStyles({ kind: "textStyles", map: {} }); // true
+* ```
+*/
+function isTextStyles(value) {
+	return isObject(value) && Reflect.get(value, "kind") === "textStyles" && isObject(Reflect.get(value, "map"));
+}
+/**
+* Tells whether an export is something the game registers by value at start. An own string
+* `kind` decides alone: a flow, a node, a slot, an ECS component or tag, a filter, bundles or a
+* plugin owner refuse, a descriptor such as `sfx(...)` or a step such as `mark(...)` passes.
+* Without a `kind`, an object with an own string `id` or `name` refuses: a scene, a system, a
+* feature or a plugin. A function without a `kind` passes, since every function has an own `name`.
+*
+* @param value - One export of the module.
+* @returns True when swapping the binding would not reach the running game.
+* @example
+* ```ts
+* isRegisteredAtStart({ kind: "sfx", payload: { key: "ui.pop" } }); // false
+* ```
+*/
+function isRegisteredAtStart(value) {
+	if (!hasMembers(value)) return false;
+	const kind = Object.hasOwn(value, "kind") ? Reflect.get(value, "kind") : void 0;
+	if (typeof kind === "string") return Object.hasOwn(REGISTERED_KINDS, kind);
+	if (typeof value === "function") return false;
+	return hasOwnString(value, "id") || hasOwnString(value, "name");
+}
+/**
+* The locale of a strings file `assets:keys` generates, read from its path with `/` separators.
+*
+* @param file - The path of the saved module.
+* @returns The locale, or `undefined` for any other file.
+* @example
+* ```ts
+* localeOf("/game/generated/strings.ru.ts"); // "ru"
+* ```
+*/
+function localeOf(file) {
+	return STRINGS_FILE.exec(file.replaceAll("\\", "/"))?.[1];
+}
+/**
+* Files one export under the kind it is, in the order component, projection, animation, emitter,
+* strings, text styles. The `default` export of a strings file counts as strings.
+*
+* @param swaps - What the module swaps so far.
+* @param entry - The export name and its value.
+* @param locale - The locale of the file when it is a strings file.
+* @returns Why the module is refused when the export is registered at start, else `undefined`.
+*/
+function fileExport(swaps, entry, locale) {
+	const [name, value] = entry;
+	const isStrings = name === "default" && locale !== void 0 && isCompiledMessages(value);
+	if (isComponentDefinition(value)) swaps.components.push(value);
+	else if (isProjectionSpec(value)) swaps.projections.push(value);
+	else if (isAnimationDefinition(value)) swaps.animations.push(value);
+	else if (isEmitterDefinition(value)) swaps.emitters.push(value.id);
+	else if (isStrings) swaps.strings.push({
+		locale,
+		messages: value
+	});
+	else if (isTextStyles(value)) swaps.textStyles.push(value);
+	else if (isRegisteredAtStart(value)) return `exports "${name}", registered at start`;
+}
+/**
+* Sorts the exports of a saved module into what it swaps. Anything else, a style, a token, a
+* number, a plain function, is left alone: Bun already gave the importers the new binding.
+*
+* @param next - The new module namespace, `undefined` when the module did not evaluate.
+* @param file - The path of the saved module.
+* @returns The swaps, or why the module is refused.
+* @example
+* ```ts
+* sortExports({}, "/game/features/hud/view.tsx"); // { reason: "no exports" }
+* ```
+*/
+function sortExports(next, file) {
+	if (!hasMembers(next)) return { reason: "the module did not evaluate" };
+	const exports = Object.entries(next);
+	if (exports.length === 0) return { reason: "no exports" };
+	const locale = localeOf(file);
+	const swaps = {
+		module: Object.fromEntries(exports),
+		components: [],
+		projections: [],
+		animations: [],
+		emitters: [],
+		strings: [],
+		textStyles: []
+	};
+	for (const entry of exports) {
+		const reason = fileExport(swaps, entry, locale);
+		if (reason !== void 0) return { reason };
+	}
+	return swaps;
+}
+/**
+* The reason of a refused replace: the first line of what it threw, without the `[game] ` prefix
+* and the closing period.
+*
+* @param error - What the replace threw.
+* @returns The reason of the refusal.
+* @example
+* ```ts
+* refusalOf(new Error('[game] Strings for "ru" match no single registered module.\n  Reload.')); // 'Strings for "ru" match no single registered module'
+* ```
+*/
+function refusalOf(error) {
+	return (error instanceof Error ? error.message : String(error)).replace(/\n.*/s, "").replace(/^\[game\] /, "").replace(/\.$/, "");
+}
+/**
+* Refuses the swap: one info entry, then the throw Bun turns into a full reload.
+*
+* @param ctx - Domain context of the ui plugin.
+* @param file - The path of the saved module.
+* @param reason - Why it cannot be swapped in place.
+* @throws {Error} Always, with the file and the reason.
+*/
+function refuse(ctx, file, reason) {
+	ctx.log.info("ui:hot-refused", {
+		file,
+		reason
+	});
+	throw new Error(`[game] Hot swap refused for ${file}: ${reason}.\n  The page reloads and restores its state.`);
+}
+/**
+* Runs one replace that may throw, and turns its throw into a refusal.
+*
+* @param ctx - Domain context of the ui plugin.
+* @param file - The path of the saved module.
+* @param replace - The replace of `world`, `anim` or `i18n`.
+* @throws {Error} When the replace throws.
+*/
+function replaceOrRefuse(ctx, file, replace) {
+	try {
+		replace();
+	} catch (error) {
+		refuse(ctx, file, refusalOf(error));
+	}
+}
+/**
+* Runs the replaces that may throw, before anything else is written: `world` refuses a new
+* projection or an undeclared layer, `anim` a new animation, `i18n` strings that match no single
+* module. A refusal then writes no component and no text style; a replace before it stands until
+* the reload.
+*
+* @param ctx - Domain context of the ui plugin.
+* @param file - The path of the saved module.
+* @param swaps - What the module swaps.
+* @throws {Error} When one of them is refused.
+*/
+function replaceRefusable(ctx, file, swaps) {
+	const { world, anim, i18n } = ctx.deps;
+	for (const spec of swaps.projections) replaceOrRefuse(ctx, file, () => world.projection.replace(spec));
+	for (const definition of swaps.animations) replaceOrRefuse(ctx, file, () => anim.replace(definition));
+	for (const { locale, messages } of swaps.strings) replaceOrRefuse(ctx, file, () => i18n.replace(locale, messages));
+}
+/**
+* The data of the `ui:hot-swap` log line: the file and the names of what was swapped, the
+* locales of the strings and the names of the text styles.
+*
+* @param file - The path of the saved module.
+* @param swaps - What the module swapped.
+* @returns One list of names per kind.
+*/
+function summaryOf(file, swaps) {
+	return {
+		file,
+		components: swaps.components.map((definition) => definition.name),
+		projections: swaps.projections.map((spec) => spec.name),
+		animations: swaps.animations.map((definition) => definition.id),
+		emitters: swaps.emitters,
+		strings: swaps.strings.map((strings) => strings.locale),
+		textStyles: swaps.textStyles.flatMap((styles) => Object.keys(styles.map))
+	};
+}
+/**
+* Builds the handler of one app: sort the exports, run the replaces that may throw, write the
+* components and the text styles, and repaint every view. The repaint runs for every module that
+* is not refused, so a module of styles only, whose bindings Bun already patched, shows on the
+* next frame too.
+*
+* @param ctx - Domain context of the ui plugin.
+* @param jsx - The jsx module, which owns the component registry and the roots.
+* @returns The handler the footer calls.
+*/
+function createSwap(ctx, jsx) {
+	return (next, file) => {
+		const sorted = sortExports(next, file);
+		if ("reason" in sorted) refuse(ctx, file, sorted.reason);
+		replaceRefusable(ctx, file, sorted);
+		for (const definition of sorted.components) jsx.replace(definition);
+		for (const styles of sorted.textStyles) ctx.deps.text.replaceStyles(styles);
+		jsx.refreshAll();
+		ctx.deps.world.projection.rerunAll();
+		ctx.deps.time.wake();
+		ctx.emit("ui:hot-swap", {
+			file,
+			module: sorted.module
+		});
+		ctx.log.info("ui:hot-swap", summaryOf(file, sorted));
+	};
+}
+/**
+* Installs the hot swap handler of this app on `globalThis.__moku_hot`. `startUi` calls it in a
+* dev build only. A second app on the page takes the global over; the remover deletes it only
+* while it is still this app's handler.
+*
+* @param ctx - Domain context of the ui plugin.
+* @param jsx - The jsx module, which owns the component registry and the roots.
+* @returns The remover, for the cleanups of the plugin state.
+*/
+function installHot(ctx, jsx) {
+	const swap = createSwap(ctx, jsx);
+	Reflect.set(globalThis, HOT_GLOBAL, swap);
+	return () => {
+		if (Reflect.get(globalThis, HOT_GLOBAL) === swap) Reflect.deleteProperty(globalThis, HOT_GLOBAL);
+	};
+}
+//#endregion
 //#region src/plugins/ui/lifecycle.ts
 /**
 * @file ui plugin — lifecycle: the dependency resolution, the Yoga load, the component registry
@@ -31550,14 +32100,15 @@ function createLayoutApi(ctx) {
 * closes exactly those.
 */
 /**
-* Resolves the seven dependency APIs with `ctx.require`. `anim` is required for the edge only:
-* its work reaches `ui` through the tween driver behind every handle.
+* Resolves the eight dependency APIs with `ctx.require`. `anim` serves the dev hot swap, which
+* replaces animations; the motions reach `anim` through the tween driver behind every handle.
 *
 * @param ctx - Kernel context of the ui plugin.
-* @returns The seven dependency APIs.
+* @returns The eight dependency APIs.
 */
 function resolveDeps(ctx) {
 	return {
+		anim: ctx.require(animPlugin),
 		time: ctx.require(timePlugin),
 		flow: ctx.require(flowPlugin),
 		world: ctx.require(worldPlugin),
@@ -31634,8 +32185,9 @@ function openRegistrations(ctx, jsx, layout) {
 }
 /**
 * Loads Yoga, reads the components of every feature, opens the registrations and, on a page,
-* makes the hidden input of the text fields. Nothing solves before the wasm module resolved; a
-* tree seen earlier waits and is reconciled on the next frame.
+* makes the hidden input of the text fields. A dev build also installs the hot swap handler the
+* view modules call. Nothing solves before the wasm module resolved; a tree seen earlier waits
+* and is reconciled on the next frame.
 *
 * @param ctx - Kernel context of the ui plugin.
 * @throws {Error} When two features define the same component name.
@@ -31646,6 +32198,7 @@ async function startUi(ctx) {
 	registerComponents(uctx, jsx);
 	openRegistrations(uctx, jsx, layout);
 	jsx.open();
+	if (typeof __MOKU_GAME_DEV__ !== "undefined" && __MOKU_GAME_DEV__) uctx.state.layout.cleanups.push(installHot(uctx, jsx));
 	await layout.load();
 }
 /**