@moku-labs/game 0.4.6 → 0.6.0

package/dist/{run-D_R0oJ6g.mjs → run-Bcyg32M5.mjs}

@@ -525,7 +525,8 @@ function invalidBookmark() {
 	return /* @__PURE__ */ new Error("[game] The bookmark is not a flow.bookmark() value.\n  Pass the JSON that game.bookmark returned.");
 }
 /**
-* Reads a bookmark out of JSON, the value `flow.bookmark()` made and the editor kept.
+* Reads a bookmark out of JSON, the value `flow.bookmark()` made and the editor kept. The
+* `scene` the `game.bookmark` door added is kept when present.
 *
 * @param value - The JSON the editor sent.
 * @returns The bookmark.
@@ -539,8 +540,9 @@ function readBookmark(value) {
 	if (!isRecord(value)) throw invalidBookmark();
 	const { path, input, player, session, graph } = value;
 	const rng = readRng(value.rng);
-	if (typeof path !== "string" || typeof graph !== "string" || !(input !== void 0 && player !== void 0 && session !== void 0) || rng === void 0) throw invalidBookmark();
-	return {
+	if (!(typeof path === "string" && typeof graph === "string") || !(input !== void 0 && player !== void 0 && session !== void 0) || rng === void 0) throw invalidBookmark();
+	const { scene } = value;
+	if (scene === void 0) return {
 		path,
 		input,
 		player,
@@ -548,6 +550,16 @@ function readBookmark(value) {
 		rng,
 		graph
 	};
+	if (typeof scene !== "string") throw invalidBookmark();
+	return {
+		path,
+		input,
+		player,
+		session,
+		rng,
+		graph,
+		scene
+	};
 }
 /**
 * Builds the error of a value that is not a repro.
@@ -1051,9 +1063,10 @@ const fillCommand = defineCommand({
 //#endregion
 //#region src/plugins/flow/control.ts
 /**
-* Enters a bookmark, or a repro's bookmark followed by its route.
+* Enters a bookmark, or a repro's bookmark followed by its route. A bookmark's `scene` is handed
+* to `scenes.expect` first, so a rest node without a scene of its own mounts it.
 *
-* @param app - The app.
+* @param app - The app; with `scenes`, the bookmark's scene is expected before the restore.
 * @param input - Exactly one of a bookmark and a repro, as JSON.
 * @param input.bookmark - A `flow.bookmark()` value.
 * @param input.repro - A `/testing` repro.
@@ -1063,7 +1076,9 @@ const fillCommand = defineCommand({
 async function restoreFrom(app, input) {
 	const { bookmark, repro } = input;
 	if (bookmark !== void 0 && repro === void 0) {
-		await app.flow.restore(readBookmark(bookmark));
+		const read = readBookmark(bookmark);
+		if (read.scene !== void 0) app.scenes?.expect(read.scene);
+		await app.flow.restore(read);
 		return app.flow.state();
 	}
 	if (repro !== void 0 && bookmark === void 0) {
@@ -1127,13 +1142,15 @@ const walkCommand = defineCommand({
 	}
 });
 /**
-* Takes a bookmark of the rest point: the node plus the committed state, plain JSON.
+* Takes a bookmark of the rest point: the node plus the committed state, plain JSON. An app with
+* the screen plugins adds the mounted `scene`, so a restore in a fresh page builds it again.
 *
 * @example
 * ```ts
-* // The editor keeps the position before a risky test.
+* // The editor keeps the position while the Settings popup stands over Home.
 * const { value } = await run(app, commands.bookmark);
-* value.path; // "board/awaitIntent"
+* value.path; // "settings/open"
+* value.scene; // "home"
 * ```
 */
 const bookmarkCommand = defineCommand({
@@ -1144,12 +1161,18 @@ const bookmarkCommand = defineCommand({
 	run: (app) => {
 		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
 		app.log.debug("moku:dev", { command: "game.bookmark" });
-		return app.flow.bookmark();
+		const bookmark = app.flow.bookmark();
+		const scene = app.scenes?.current();
+		return scene === void 0 ? bookmark : {
+			...bookmark,
+			scene
+		};
 	}
 });
 /**
 * Restores a bookmark, or a repro: its state at its checkpoint, then its route. Replaces the
-* state outside the graph, so the session is tainted and the command journaled.
+* state outside the graph, so the session is tainted and the command journaled. A bookmark's
+* `scene` goes to `scenes.expect` first: a bookmark at a popup comes back with the scene under it.
 *
 * @example
 * ```ts
@@ -1157,6 +1180,12 @@ const bookmarkCommand = defineCommand({
 * const repro = { player: { coins: 40 }, checkpoint: "home", route: [{ at: "home", intent: "play" }] };
 * const ran = await run(app, commands.restore, { repro });
 * ran.state; // { path: "board/awaitIntent", frame: 12, tainted: true }
+*
+* // A fresh page restores the bookmark game.bookmark took at the Settings popup over Home.
+* bookmark.scene; // "home"
+* await run(app, commands.restore, { bookmark });
+* await app.flow.walk([]); // the scene stage runs after the restore resolved
+* app.scenes.current(); // "home"
 * ```
 */
 const restoreCommand = defineCommand({

package/dist/{runtime-Bhu442L8.d.mts → runtime-HTlmRb81.d.mts}

@@ -1,4 +1,4 @@
-import { a as JsxChild, m as UiIntrinsicElements, t as DescriptionNode } from "./types-VErbiEXy.mjs";
+import { a as JsxChild, m as UiIntrinsicElements, t as DescriptionNode } from "./types-BaUUcIaN.mjs";
 
 //#region src/plugins/ui/jsx/runtime.d.ts
 /** What the compiler passes as props: the children plus whatever the tag declared. */

package/dist/testing.d.mts

@@ -1,8 +1,8 @@
-import { $t as SaveDoc, Kt as Json, Qt as ProviderCall, Ut as Api$2, Zt as PlayerStateProvider, an as Api$3, k as Api$1, m as Api, pn as FakeClock } from "./types-Dy1xB68L.mjs";
-import { _ as stepFrames, a as InputOf, d as HeadlessApp, f as HeadlessGame, g as runRepro, h as createHeadless, m as ReproResult, p as Repro, r as ControlApp } from "./types-DtmFVCHf.mjs";
-import { H as InputApi } from "./types-VErbiEXy.mjs";
-import { G as UiApi, g as AnimApi } from "./types-C-4f2jD_.mjs";
-import { t as commands } from "./commands-C83eQ5B9.mjs";
+import { $t as SaveDoc, Kt as Json, Qt as ProviderCall, Ut as Api$2, Zt as PlayerStateProvider, an as Api$3, k as Api$1, m as Api, pn as FakeClock } from "./types-BMEn0tSC.mjs";
+import { _ as stepFrames, a as InputOf, d as HeadlessApp, f as HeadlessGame, g as runRepro, h as createHeadless, m as ReproResult, p as Repro, r as ControlApp } from "./types-CYYKjvLn.mjs";
+import { H as InputApi } from "./types-BaUUcIaN.mjs";
+import { b as AnimApi, v as UiApi } from "./types-CXyipKhE.mjs";
+import { t as commands } from "./commands-mzE9PX0H.mjs";
 
 //#region src/plugins/clock/fake.d.ts
 /**

package/dist/testing.mjs

@@ -1,5 +1,5 @@
 import { n as saveOf, t as memory } from "./memory-CvgdnsQO.mjs";
-import { a as stepFrames, i as runRepro, n as commands, r as createHeadless, t as run } from "./run-D_R0oJ6g.mjs";
+import { a as stepFrames, i as runRepro, n as commands, r as createHeadless, t as run } from "./run-Bcyg32M5.mjs";
 import { n as read, t as sources } from "./sources-DVWJ8nfr.mjs";
 import { createBrandConsole } from "@moku-labs/common/cli";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
@@ -629,7 +629,7 @@ function addressesOf(keys) {
 * ```
 */
 function parentOf(parent) {
-	if (typeof parent !== "object" || parent === null || Array.isArray(parent)) return void 0;
+	if (!(typeof parent === "object" && parent !== null && !Array.isArray(parent))) return void 0;
 	return typeof parent.entity === "number" ? parent.entity : void 0;
 }
 /**
@@ -663,6 +663,20 @@ function stateOf(app) {
 	};
 }
 /**
+* The ui tree without the words of its texts, at every depth.
+*
+* @param node - A node of the ui source.
+* @returns The node and its children, none with `content`.
+*/
+function withoutContent(node) {
+	const copy = {
+		...node,
+		children: node.children.map((child) => withoutContent(child))
+	};
+	delete copy.content;
+	return copy;
+}
+/**
 * Reads the screen a checkpoint saves: the ui tree, and every entity a projection names as
 * `{ projection, key, components }`, sorted by projection then key. Ui parts, rings and unkeyed
 * views appear through the tree only, or not at all.
@@ -675,13 +689,14 @@ function describeOf(app) {
 	const views = [];
 	for (const entity of read(app, sources.entities)) {
 		const address = addresses.get(entity.id);
-		if (address !== void 0) views.push({
+		if (address === void 0) continue;
+		views.push({
 			...address,
 			components: withParentAddress(entity.components, addresses)
 		});
 	}
 	return {
-		ui: read(app, sources.ui),
+		ui: withoutContent(read(app, sources.ui)),
 		views: views.toSorted(byAddress)
 	};
 }

package/dist/{types-Dy1xB68L.d.mts → types-BMEn0tSC.d.mts}

@@ -27,9 +27,21 @@ type Config$8 = {
   referenceLong: number;
 };
 /**
- * Global events. Empty: every event belongs to a plugin.
+ * Global events: the few that cross plugins with no `depends` edge. Every other event belongs to a
+ * plugin.
+ *
+ * @example
+ * ```ts
+ * // ui, after a dev save of features/board/effects.ts; effects hooks it with no depends on ui.
+ * ctx.emit("ui:hot-swap", { file: "features/board/effects.ts", module: { starsBurst } });
+ * ```
  */
-type Events$6 = Record<never, never>;
+type Events$6 = {
+  /** A dev hot swap was applied: the saved module's new exports. `ui` emits it, `effects` replaces its emitters on it. */"ui:hot-swap": {
+    file: string;
+    module: Readonly<Record<string, unknown>>;
+  };
+};
 /**
  * Public API type of a plugin instance, read from its phantom carrier.
  * Mirrors the kernel's non-exported `ExtractPluginApi`.
@@ -2141,6 +2153,11 @@ type Bookmark = {
   session: Json;
   rng: RngState;
   graph: string;
+  /**
+   * The scene mounted when the bookmark was taken. Written by the `game.bookmark` door, read by
+   * `game.restore`; `flow.restore` ignores it.
+   */
+  scene?: string;
 };
 /**
  * What `onEnter` callbacks learn about the node being entered.
@@ -3432,6 +3449,23 @@ type ProjectionApi = {
    * ```
    */
   register(spec: AnyProjectionSpec): void;
+  /**
+   * Swaps the stored spec of a registered projection. A mounted one has its layers checked against
+   * the current scene and runs the new `view` for every item on the next frame, directly. An
+   * unmounted one is only stored; its next `mount` uses it. Nothing changes when the call throws.
+   *
+   * @param spec - The new projection, under the name it was registered with.
+   * @throws {Error} When no projection of that name is registered, or when a mounted one names a
+   * `layer` or `lift` the scene does not declare.
+   * @example
+   * ```ts
+   * // The dev hot swap in `ui`: the saved `view.ts` exports a new `boardItems`.
+   * const world = ctx.require(worldPlugin);
+   * world.projection.replace(boardItems); // the next frame draws every item with the new view
+   * world.projection.replace(shopItems); // throws: Projection "shop.items" is not registered
+   * ```
+   */
+  replace(spec: AnyProjectionSpec): void;
   /**
    * Stores the layer list of the scene. The order of the list is draw order; every call stores a
    * new frozen array.
@@ -3696,9 +3730,10 @@ type ProjectionApi = {
    *
    * @example
    * ```ts
-   * // `i18n` switched the locale: every label has to be projected again.
+   * // The ui hot swap replaced the saved `hud` projection: every mounted view runs `view` again.
    * const world = ctx.require(worldPlugin);
-   * world.projection.rerunAll(); // the next frame writes the new strings with no motion
+   * world.projection.replace(hud);
+   * world.projection.rerunAll(); // the next frame draws the new view, with no motion
    * ```
    */
   rerunAll(): void;

package/dist/{types-VErbiEXy.d.mts → types-BaUUcIaN.d.mts}

@@ -1,4 +1,4 @@
-import { B as ComponentValue, D as Point$2, F as AnyComponentType, I as AnyComponentValue, It as Hint, Kt as Json, O as ViewportSize, P as AnyComponent, Pt as Descriptor, Rt as Api, V as Entity, Z as ChangeHook, at as ProjectionMotion, dn as Api$5, it as NumericFields, k as Api$2, lt as ViewHandle, m as Api$3, nt as Motion, o as Events$1, rt as MotionHandle, t as Api$4, ut as Api$1, vn as Require, z as ComponentType } from "./types-Dy1xB68L.mjs";
+import { B as ComponentValue, D as Point$2, F as AnyComponentType, I as AnyComponentValue, It as Hint, Kt as Json, O as ViewportSize, P as AnyComponent, Pt as Descriptor, Rt as Api, V as Entity, Z as ChangeHook, at as ProjectionMotion, dn as Api$5, it as NumericFields, k as Api$2, lt as ViewHandle, m as Api$3, nt as Motion, o as Events$1, rt as MotionHandle, t as Api$4, ut as Api$1, vn as Require, z as ComponentType } from "./types-BMEn0tSC.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 
@@ -834,7 +834,7 @@ type State$1 = {
  * i18n plugin events.
  */
 type Events = {
-  /** The current locale changed and its messages are loaded. */"i18n:locale-changed": {
+  /** The current locale changed, or its messages were replaced. */"i18n:locale-changed": {
     locale: string;
   };
 };
@@ -960,6 +960,24 @@ type I18nApi = {
    * ```
    */
   locales(): readonly string[];
+  /**
+   * Swaps the compiled module of one feature in a loaded locale, for the dev hot swap. The one
+   * registered module whose keys overlap `messages` takes them, the locale is merged again and
+   * every key may warn once more. When the locale is the current one or the fallback,
+   * `i18n:locale-changed` is emitted with the current locale, so `text` re-resolves every label.
+   * A locale not loaded yet is left alone: its loader imports the new module later.
+   *
+   * @param locale - The locale of the saved `generated/strings.<locale>.ts`.
+   * @param messages - The `default` export of the new module.
+   * @throws {Error} When no registered module, or more than one, shares a key with `messages`.
+   * @example
+   * ```ts
+   * // ui's hot swap: generated/strings.ru.ts was written again with "hud.orders" as "3 заказа!".
+   * ctx.require(i18nPlugin).replace("ru", next.default); // emits i18n:locale-changed
+   * app.i18n.plain(tr("hud.orders", { n: 3 })); // "3 заказа!": text redraws the label
+   * ```
+   */
+  replace(locale: string, messages: CompiledMessages): void;
 };
 /**
  * What the kernel context offers this plugin.
@@ -1407,7 +1425,8 @@ type State = {
 };
 /**
  * text plugin API, `app.text`. Two questions: how big a piece of text is, and which styles the
- * game registered. Everything else happens in the frame.
+ * game registered; and one order, the dev hot swap of a styles file. Everything else happens in
+ * the frame.
  *
  * @example
  * ```ts
@@ -1464,6 +1483,26 @@ type TextApi = {
    * ```
    */
   styles(): readonly string[];
+  /**
+   * The dev hot swap of a styles file: writes every style of the map over the table. A known
+   * name keeps the feature that owns it, a new name is added and usable at once. The fonts the
+   * styles name are read, the measured layouts are dropped, and every label is laid out again
+   * on the next frame and redrawn with the new style, even when its text and its style name did
+   * not change. The game loop is woken for that frame.
+   *
+   * @param styles - What `defineTextStyles` returned in the saved module.
+   * @example
+   * ```ts
+   * // `ui` hot swaps a saved `hud/styles.ts`: the "hud.title" labels redraw at 64 px.
+   * const uiStyles = defineTextStyles({
+   *   "hud.title": { font: "ui.font-body", size: 64, fill: 0xff0000 }
+   * });
+   *
+   * ctx.require(textPlugin).replaceStyles(uiStyles);
+   * ctx.require(textPlugin).measure("12", "hud.title").height; // 76.8 on the 0.6 em fallback
+   * ```
+   */
+  replaceStyles(styles: TextStyles): void;
 };
 /**
  * Resolved dependency APIs.
@@ -2646,9 +2685,10 @@ type JsxState = {
 /**
  * One node of the snapshot `tree()` answers with. `rect` is natural: under a `fit` ancestor it
  * is the rect before that ancestor's scale. An element with `fit: "contain"` adds `fitScale`,
- * the scale it is drawn at. An `input` adds `value`: the text being typed while it is edited,
- * else the local field it writes. A windowed `scroll` adds `window`: the rows that exist, which
- * are the children of its content, and how many the list has.
+ * the scale it is drawn at. A `text` adds `content`: the words it draws. An `input` adds `value`:
+ * the text being typed while it is edited, else the local field it writes. A windowed `scroll`
+ * adds `window`: the rows that exist, which are the children of its content, and how many the
+ * list has.
  *
  * @example
  * ```ts
@@ -2673,6 +2713,19 @@ type UiNode = {
   state: IsFlags;
   local?: Record<string, unknown>;
   fitScale?: number;
+  /**
+   * The words a `text` draws, as one plain string: the string `text` resolved after `tr()` and
+   * `bind`, its tags and icons left out, else its `content` prop while that is a plain string.
+   * Absent on any other tag and on a text that draws nothing.
+   *
+   * @example
+   * ```ts
+   * // Home in Russian: `<text key="title" content={tr("home.title")} />` under the root row.
+   * const title = app.ui.tree().children.find(node => node.key === "title");
+   * title?.content; // "Лесной городок"
+   * ```
+   */
+  content?: string;
   value?: string;
   /**
    * The rows of a windowed scroll that exist and how many the list has.