@moku-labs/game 0.4.6 → 0.6.0

package/README.md

@@ -192,7 +192,9 @@ createApp({ plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin] });
 | `@moku-labs/game/assets` | Node and Bun | Asset keys, the manifest, strings, the pack |
 | `@moku-labs/game/inspect` | anywhere | Read a running game |
 | `@moku-labs/game/control` | dev builds | Drive a running game |
+| `@moku-labs/game/hot` | the Bun dev server | The `bunfig.toml` plugin that hot swaps views. See [Hot swap](./docs/hot-swap.md) |
 | `@moku-labs/game/lint` | oxlint | The game lint rules, as an oxlint JS plugin |
+| `@moku-labs/game/project` | Node and Bun | Where every engine id of a game is defined, line fresh at the call. The bin `moku-game-index`. See [Project index](./docs/project-index.md) |
 | `@moku-labs/game/jsx-runtime`, `/jsx-dev-runtime` | anywhere | The JSX runtime. A game never imports it by hand. |
 
 ### Lint for games
@@ -224,9 +226,11 @@ Each rule takes `{ "files": [...], "ignores": [...] }`. The defaults follow the
 | [Plugins](./docs/plugins.md) | The dependency graph, the plugin table, every root export |
 | [Interface in JSX](./docs/jsx.md) | Tags, components, styles, popups |
 | [Doors for the editor](./docs/doors.md) | `/inspect` and `/control`, base sources and commands |
+| [Hot swap](./docs/hot-swap.md) | Save a view, see it in the running page, no reload |
 | [Events](./docs/events.md) | Every event and its payload |
 | [Configuration](./docs/configuration.md) | Every config field and its default |
 | [Lint for games](./docs/lint.md) | The `moku-game` oxlint rules, their options and defaults |
+| [Project index](./docs/project-index.md) | `openProject`, the key scheme, `find` and `watch`, the `moku-game-index` bin |
 | [Testing](./docs/testing.md) | Headless and visual tests, all scripts, test layout, lint rules |
 | [`llms.txt`](./llms.txt) | The engine in one page, for an AI that writes a game |
 
@@ -248,11 +252,22 @@ bun run release          # moku-release
 
 Every script is in [docs/testing.md](./docs/testing.md#scripts).
 
+### Hot swap
+
+A save of a view file swaps it in the running page, with the same state. One line in the game's `bunfig.toml`:
+
+```toml
+[serve.static]
+plugins = ["@moku-labs/game/hot"]
+```
+
+A save of a logic file reloads the page. What swaps and what reloads: [docs/hot-swap.md](./docs/hot-swap.md).
+
 ## Requirements
 
 - **Node `>= 24`** and **Bun `>= 1.3.14`**. Use `bun` only.
 - **TypeScript** in strict mode, with `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess`.
-- **`pixi.js` `^8.0.0`** as a peer dependency. `playwright-core` for visual tests and `sharp` for the asset pack are optional peers. `yoga-layout` is loaded lazily by `ui`. The string compiler uses `@formatjs/icu-messageformat-parser` at build time only.
+- **`pixi.js` `^8.0.0`** as a peer dependency. `playwright-core` for visual tests, `sharp` for the asset pack and `typescript` for the project index are optional peers. `yoga-layout` is loaded lazily by `ui`. The string compiler uses `@formatjs/icu-messageformat-parser` at build time only.
 - **[`@moku-labs/core`](https://github.com/moku-labs/core)** is the kernel. **[`@moku-labs/common`](https://github.com/moku-labs/common)** brings `log` and `env`.
 
 ## License

package/bin/moku-game-index.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { runCli } from "../dist/project.mjs";
+
+process.exitCode = await runCli(process.argv.slice(2));

package/dist/assets.d.mts

@@ -1,4 +1,4 @@
-import { l as Manifest } from "./types-Dy1xB68L.mjs";
+import { l as Manifest } from "./types-BMEn0tSC.mjs";
 
 //#region src/plugins/assets/scan/cli.d.ts
 /**

package/dist/{commands-C83eQ5B9.d.mts → commands-mzE9PX0H.d.mts}

@@ -1,7 +1,7 @@
-import { C as Captured, Et as Bookmark, T as DebugSwitches, Vt as Time, an as Api, k as Api$2, kt as FlowState, m as Api$1 } from "./types-Dy1xB68L.mjs";
-import { d as HeadlessApp, n as Command, r as ControlApp } from "./types-DtmFVCHf.mjs";
-import { H as InputApi } from "./types-VErbiEXy.mjs";
-import { G as UiApi, g as AnimApi, t as AudioApi } from "./types-C-4f2jD_.mjs";
+import { C as Captured, Et as Bookmark, T as DebugSwitches, Vt as Time, an as Api, k as Api$2, kt as FlowState, m as Api$1 } from "./types-BMEn0tSC.mjs";
+import { d as HeadlessApp, n as Command, r as ControlApp } from "./types-CYYKjvLn.mjs";
+import { H as InputApi } from "./types-BaUUcIaN.mjs";
+import { b as AnimApi, p as ScenesApi, t as AudioApi, v as UiApi } from "./types-CXyipKhE.mjs";
 
 //#region src/plugins/flow/doors/commands.d.ts
 /**
@@ -48,11 +48,19 @@ declare const commands: Readonly<{
   walk: Command<{
     route: "json";
   }, FlowState, ControlApp>;
-  bookmark: Command<{}, Bookmark, ControlApp>;
+  bookmark: Command<{}, Bookmark, HeadlessApp & {
+    readonly log: import("@moku-labs/common/browser").LogApi;
+  } & {
+    readonly scenes?: ScenesApi;
+  }>;
   restore: Command<{
     bookmark: "json?";
     repro: "json?";
-  }, FlowState, ControlApp>;
+  }, FlowState, HeadlessApp & {
+    readonly log: import("@moku-labs/common/browser").LogApi;
+  } & {
+    readonly scenes?: ScenesApi;
+  }>;
   step: Command<{
     frames: "number";
     deltaMs: "number?";

package/dist/control.d.mts

@@ -1,6 +1,6 @@
-import { d as HeadlessApp, i as InputArguments, n as Command, o as InputSchema, s as Ran } from "./types-DtmFVCHf.mjs";
-import { t as commands } from "./commands-C83eQ5B9.mjs";
-import { t as defineCommand } from "./define-BKWjWgyQ.mjs";
+import { d as HeadlessApp, i as InputArguments, n as Command, o as InputSchema, s as Ran } from "./types-CYYKjvLn.mjs";
+import { t as commands } from "./commands-mzE9PX0H.mjs";
+import { t as defineCommand } from "./define-BbgXv4cy.mjs";
 
 //#region src/plugins/flow/doors/dev.d.ts
 /**

package/dist/control.mjs

@@ -1,4 +1,4 @@
 import { t as controlRefused } from "./dev-wKLgOw7c.mjs";
-import { n as commands, t as run } from "./run-D_R0oJ6g.mjs";
+import { n as commands, t as run } from "./run-Bcyg32M5.mjs";
 import { s as defineCommand } from "./input-CK4nxBO1.mjs";
 export { commands, controlRefused, defineCommand, run };

package/dist/{define-BKWjWgyQ.d.mts → define-BbgXv4cy.d.mts}

@@ -1,4 +1,4 @@
-import { c as Source, d as HeadlessApp, n as Command, o as InputSchema } from "./types-DtmFVCHf.mjs";
+import { c as Source, d as HeadlessApp, n as Command, o as InputSchema } from "./types-CYYKjvLn.mjs";
 
 //#region src/plugins/flow/doors/define.d.ts
 /**

package/dist/hot.d.mts

@@ -0,0 +1,85 @@
+//#region src/hot.d.ts
+/**
+ * Which files get the hot swap footer. A file has to match `include` and must not match
+ * `exclude`. Only the game's own files can get it: the game root is the working directory of
+ * the dev server, and a file outside it (the engine source, a linked package) always loads
+ * unchanged.
+ *
+ * @example
+ * ```ts
+ * // A game keeps its views in `look/` folders instead of `.tsx` files.
+ * const options: HotOptions = { include: /\/look\/.*\.ts$/ };
+ * ```
+ */
+type HotOptions = {
+  /**
+   * The files that get the footer. Default: `.tsx` files, `styles.ts`, `view.ts`,
+   * `animations.ts`, `effects.ts` and `generated/strings.<locale>.ts`. Bun runs it as the load
+   * filter on the absolute path, so it should not anchor at the start.
+   */
+  include?: RegExp;
+  /**
+   * The files that load unchanged although they match `include`. Default: anything under
+   * `node_modules/`, `web/`, `generated/`, `__tests__/` or `tests/`, and `.test`/`.spec` files.
+   * Tested on the path relative to the game root with a leading `/` and `/` separators, also on
+   * Windows: `/features/home/view.tsx`. A folder above the game root never excludes a file. A
+   * `generated/strings.<locale>.ts` file is never excluded: the generated strings swap.
+   */
+  exclude?: RegExp;
+};
+/**
+ * The part of Bun's plugin builder the hot plugin uses. Bun's `PluginBuilder` fits it, so the
+ * shipped types need no `bun` import.
+ */
+type HotBuild = {
+  /**
+   * Registers a load callback for the files whose path matches `filter`.
+   *
+   * @param options - The filter on the absolute path of a module.
+   * @param options.filter - Only a path that matches it loads through the callback.
+   * @param callback - Reads the module and returns its source and loader.
+   */
+  onLoad(options: {
+    filter: RegExp;
+  }, callback: (args: {
+    path: string;
+  }) => Promise<{
+    contents: string;
+    loader: "ts" | "tsx";
+  }>): void;
+};
+/**
+ * A Bun plugin object, as `[serve.static] plugins` in `bunfig.toml` loads it.
+ */
+type HotPlugin = {
+  /** The plugin name Bun reports in its errors. */name: string;
+  /**
+   * Registers the load callback that appends the footer.
+   *
+   * @param build - Bun's plugin builder.
+   */
+  setup(build: HotBuild): void;
+};
+/**
+ * Creates the Bun plugin that hot swaps the views of a running game in the dev server. The
+ * default export is `hot()`; call it with options for another folder layout. The dev server runs
+ * in the game root: `exclude` is tested on the path relative to it, and a file outside it loads
+ * unchanged.
+ *
+ * @param options - The files that get the footer; both filters have defaults.
+ * @returns The Bun plugin object.
+ * @example
+ * ```ts
+ * // bunfig.toml of a game with the default layout:
+ * //   [serve.static]
+ * //   plugins = ["@moku-labs/game/hot"]
+ * // A game that keeps its views in `look/` folders exports its own plugin from `hot.ts`
+ * // and lists `plugins = ["./hot.ts"]` instead:
+ * export default hot({ include: /\/look\/.*\.ts$/ });
+ * ```
+ */
+declare function hot(options?: HotOptions): HotPlugin;
+/** The Bun plugin with the default filters, for `plugins = ["@moku-labs/game/hot"]` in `bunfig.toml`. */
+declare const _default: HotPlugin;
+//#endregion
+export { HotBuild, HotOptions, HotPlugin, _default as default, hot };

package/dist/hot.mjs

@@ -0,0 +1,108 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+//#region src/hot.ts
+/**
+* @file Hot entry (subpath `./hot`): the Bun plugin of the dev server that hot swaps the views of
+* a running game. It appends a footer to every view module it loads: the module accepts its own
+* update and hands the new exports to the running game through `globalThis.__moku_hot`. The `ui`
+* plugin installs that handler in dev builds only. What swaps: styles, components, projections,
+* animations, text styles, emitters and generated strings. A view module is a `.tsx` file, a
+* `styles.ts`, a `view.ts`, an `animations.ts`, an `effects.ts` or a generated
+* `generated/strings.<locale>.ts`; a logic module never gets the footer, so its save reaches the
+* root and the page reloads and restores its state. The plugin lives in `[serve.static]` of
+* `bunfig.toml`, the dev server only: `Bun.build` of a production build never loads it.
+*/
+/**
+* The default view modules: `.tsx` files, `styles.ts`, `view.ts`, `animations.ts`, `effects.ts`
+* and the generated strings of a locale.
+*/
+const DEFAULT_INCLUDE = /(\.tsx|\/styles\.ts|\/view\.ts|\/animations\.ts|\/effects\.ts|\/generated\/strings\.[\w-]+\.ts)$/;
+/** The generated strings of one locale, the one file under `generated/` that swaps. */
+const STRINGS = /\/generated\/strings\.[\w-]+\.ts$/;
+/** The default folders and test files that never hot swap. The outer group only scopes the `$`. */
+const DEFAULT_EXCLUDE = /(\/(node_modules|web|generated|__tests__|tests)\/|\.(test|spec)\.tsx?$)/;
+/**
+* Gives the path of a module relative to the game root, the working directory of the dev server.
+*
+* @param file - The absolute path of the module.
+* @param root - The game root.
+* @returns The path with a leading `/` and `/` separators, or `undefined` outside the game root.
+* @example
+* ```ts
+* gamePath("/work/tests/game/features/home/view.tsx", "/work/tests/game"); // "/features/home/view.tsx"
+* ```
+*/
+function gamePath(file, root) {
+	const inGame = path.relative(root, file).replaceAll("\\", "/");
+	if (inGame.startsWith("../") || path.isAbsolute(inGame)) return void 0;
+	return `/${inGame}`;
+}
+/**
+* Builds the footer that makes a module accept its own update and hand it to the running game.
+* Bun only sees `import.meta.hot.accept(...)` written out in full, so the footer never aliases it.
+*
+* @param file - The absolute path of the module.
+* @returns The footer source, one line per statement.
+* @example
+* ```ts
+* footerOf("/game/features/home/view.tsx").includes('swap(next, "/game/features/home/view.tsx");'); // true
+* ```
+*/
+function footerOf(file) {
+	return [
+		"if (import.meta.hot) {",
+		"  import.meta.hot.accept();",
+		"  import.meta.hot.accept(next => {",
+		"    const swap = globalThis.__moku_hot;",
+		String.raw`    if (typeof swap !== "function") throw new Error("[game] No running game takes the hot swap.\n  Open the game page, then save again.");`,
+		`    swap(next, ${JSON.stringify(file)});`,
+		"  });",
+		"}",
+		""
+	].join("\n");
+}
+/**
+* Creates the Bun plugin that hot swaps the views of a running game in the dev server. The
+* default export is `hot()`; call it with options for another folder layout. The dev server runs
+* in the game root: `exclude` is tested on the path relative to it, and a file outside it loads
+* unchanged.
+*
+* @param options - The files that get the footer; both filters have defaults.
+* @returns The Bun plugin object.
+* @example
+* ```ts
+* // bunfig.toml of a game with the default layout:
+* //   [serve.static]
+* //   plugins = ["@moku-labs/game/hot"]
+* // A game that keeps its views in `look/` folders exports its own plugin from `hot.ts`
+* // and lists `plugins = ["./hot.ts"]` instead:
+* export default hot({ include: /\/look\/.*\.ts$/ });
+* ```
+*/
+function hot(options = {}) {
+	const include = options.include ?? DEFAULT_INCLUDE;
+	const exclude = options.exclude ?? DEFAULT_EXCLUDE;
+	return {
+		name: "@moku-labs/game/hot",
+		setup: (build) => {
+			build.onLoad({ filter: include }, async ({ path: file }) => {
+				const source = await readFile(file, "utf8");
+				const loader = file.endsWith(".tsx") ? "tsx" : "ts";
+				const inGame = gamePath(file, process.cwd());
+				const strings = STRINGS.test(inGame ?? "");
+				if (inGame === void 0 || !strings && exclude.test(inGame)) return {
+					contents: source,
+					loader
+				};
+				return {
+					contents: `${source}\n${footerOf(file)}`,
+					loader
+				};
+			});
+		}
+	};
+}
+/** The Bun plugin with the default filters, for `plugins = ["@moku-labs/game/hot"]` in `bunfig.toml`. */
+var hot_default = hot();
+//#endregion
+export { hot_default as default, hot };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { $ as Ease, A as Config$8, B as ComponentValue, Bt as State$7, Ct as to, Dt as DefineNode, Ft as GuideOptions, G as Narrowed, Ht as types_d_exports$14, It as Hint, J as ResourceType, Jt as State$5, Kt as Json, L as ComponentHandle, M as State$8, Mt as SceneIdOf, N as types_d_exports$16, O as ViewportSize, Pt as Descriptor, Q as DescriptionNode, Rt as Api$5, S as types_d_exports$11, St as slot, Tt as FeatureDescription, W as Mut, Wt as Config$5, X as TagType, Xt as Patch, Y as SystemDefinition, Yt as types_d_exports$9, _n as Events$1, _t as State$3, a as DefineBundles, an as Api$3, at as ProjectionMotion, b as State$6, bt as defineFlow, c as LoadReason, cn as PauseReason, d as Tier, dn as Api$1, dt as BundlesOf, en as SaveUnreadableError, fn as Config$2, ft as Config$3, gn as Config$9, h as Config$6, hn as types_d_exports$3, ht as GameTypes, i as Config$1, it as NumericFields, k as Api$6, ln as State$4, m as Api$4, mn as State$2, mt as FeaturePlugin, n as BundleMap, nn as StoreApi, on as Config$4, ot as ProjectionSpec, p as types_d_exports$1, pt as EmitterIdOf, q as QueryTerm, qt as Root, r as BundleSpec, rn as RngApi, s as LoadBundles, sn as Events, t as Api, u as State$1, un as types_d_exports$8, ut as Api$2, vn as Require, vt as TextStylesOf, wt as type, xt as exit, yt as types_d_exports$5, z as ComponentType, zt as Config$7 } from "./types-Dy1xB68L.mjs";
-import { $ as SpriteValue, A as TextStyleInput, B as types_d_exports$6, C as Config$12, D as TextApi, E as State$11, F as Config$10, G as Display, H as InputApi, I as I18nApi, J as Parent, K as NineSlice, L as Message, M as TextValue, N as types_d_exports$13, O as TextBind, P as Argument, Q as SpriteOptions, R as State$9, S as BindOptions, T as Point, U as State$10, V as Config$11, W as types_d_exports$7, X as ShapeValue, Y as Shape, Z as Sprite, _ as Style, b as defineComponent, d as popup, et as Transform, f as defineTokens, g as ResolvedStyle, h as IsFlags, j as TextStyles, k as TextFormat, l as Box, nt as sprite, p as IntrinsicElementsFor, q as NineSliceValue, s as PopupComponent, tt as TransformValue, u as LocalWrite, w as CountdownValue, x as BindField, y as WhenFlags, z as TypedTr } from "./types-VErbiEXy.mjs";
-import { A as haptic, B as tween, C as HapticKind, D as defineAnimation, E as HAPTIC_KINDS, F as set, G as UiApi, H as wait, I as sfx, K as types_d_exports$15, L as spawn, M as parallel, N as play, O as external, P as sequence, R as spawned, S as types_d_exports, T as Step, U as Config$15, V as use, W as State$15, _ as Config$13, b as State$12, c as AnySceneProjection, d as SceneDefinition, f as SceneSpec, g as AnimApi, h as types_d_exports$12, i as MusicOptions, j as mark, k as frames, l as DefineScene, m as State$14, n as Config$14, o as State$13, p as ScenesApi, r as MusicDescriptor, s as types_d_exports$2, t as AudioApi, u as LayerMap, v as FramesValue, w as SfxDescriptor, x as Target, y as MotionKeyframe, z as stagger } from "./types-C-4f2jD_.mjs";
-import { _ as NoiseValue, a as types_d_exports$4, c as EmitterValue, d as ColorMatrixValue, f as DisplacementValue, g as GlowValue, h as FilterValueOf, i as State$16, l as AlphaValue, m as FilterSpec, n as EffectsApi, o as EmitterConfig, p as FilterComponent, s as EmitterDefinition, t as Config$16, u as BlurValue, v as OutlineValue, y as UniformDeclaration } from "./types-w646dMeA.mjs";
+import { $ as Ease, A as Config$8, B as ComponentValue, Bt as State$7, Ct as to, Dt as DefineNode, Ft as GuideOptions, G as Narrowed, Ht as types_d_exports$14, It as Hint, J as ResourceType, Jt as State$5, Kt as Json, L as ComponentHandle, M as State$8, Mt as SceneIdOf, N as types_d_exports$16, O as ViewportSize, Pt as Descriptor, Q as DescriptionNode, Rt as Api$5, S as types_d_exports$11, St as slot, Tt as FeatureDescription, W as Mut, Wt as Config$5, X as TagType, Xt as Patch, Y as SystemDefinition, Yt as types_d_exports$9, _n as Events$1, _t as State$3, a as DefineBundles, an as Api$3, at as ProjectionMotion, b as State$6, bt as defineFlow, c as LoadReason, cn as PauseReason, d as Tier, dn as Api$1, dt as BundlesOf, en as SaveUnreadableError, fn as Config$2, ft as Config$3, gn as Config$9, h as Config$6, hn as types_d_exports$3, ht as GameTypes, i as Config$1, it as NumericFields, k as Api$6, ln as State$4, m as Api$4, mn as State$2, mt as FeaturePlugin, n as BundleMap, nn as StoreApi, on as Config$4, ot as ProjectionSpec, p as types_d_exports$1, pt as EmitterIdOf, q as QueryTerm, qt as Root, r as BundleSpec, rn as RngApi, s as LoadBundles, sn as Events, t as Api, u as State$1, un as types_d_exports$8, ut as Api$2, vn as Require, vt as TextStylesOf, wt as type, xt as exit, yt as types_d_exports$5, z as ComponentType, zt as Config$7 } from "./types-BMEn0tSC.mjs";
+import { $ as SpriteValue, A as TextStyleInput, B as types_d_exports$6, C as Config$12, D as TextApi, E as State$11, F as Config$10, G as Display, H as InputApi, I as I18nApi, J as Parent, K as NineSlice, L as Message, M as TextValue, N as types_d_exports$13, O as TextBind, P as Argument, Q as SpriteOptions, R as State$9, S as BindOptions, T as Point, U as State$10, V as Config$11, W as types_d_exports$7, X as ShapeValue, Y as Shape, Z as Sprite, _ as Style, b as defineComponent, d as popup, et as Transform, f as defineTokens, g as ResolvedStyle, h as IsFlags, j as TextStyles, k as TextFormat, l as Box, nt as sprite, p as IntrinsicElementsFor, q as NineSliceValue, s as PopupComponent, tt as TransformValue, u as LocalWrite, w as CountdownValue, x as BindField, y as WhenFlags, z as TypedTr } from "./types-BaUUcIaN.mjs";
+import { A as HAPTIC_KINDS, B as sfx, C as MotionKeyframe, D as HapticKind, E as types_d_exports, F as mark, G as use, H as spawned, I as parallel, K as wait, L as play, M as external, N as frames, O as SfxDescriptor, P as haptic, R as sequence, S as FramesValue, T as Target, U as stagger, V as spawn, W as tween, _ as State$15, b as AnimApi, c as AnySceneProjection, d as SceneDefinition, f as SceneSpec, g as Config$15, h as types_d_exports$12, i as MusicOptions, j as defineAnimation, k as Step, l as DefineScene, m as State$14, n as Config$14, o as State$13, p as ScenesApi, r as MusicDescriptor, s as types_d_exports$2, t as AudioApi, u as LayerMap, v as UiApi, w as State$12, x as Config$13, y as types_d_exports$15, z as set } from "./types-CXyipKhE.mjs";
+import { _ as NoiseValue, a as types_d_exports$4, c as EmitterValue, d as ColorMatrixValue, f as DisplacementValue, g as GlowValue, h as FilterValueOf, i as State$16, l as AlphaValue, m as FilterSpec, n as EffectsApi, o as EmitterConfig, p as FilterComponent, s as EmitterDefinition, t as Config$16, u as BlurValue, v as OutlineValue, y as UniformDeclaration } from "./types-ClF8say0.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";