@moku-labs/game 0.9.0 → 0.11.0

package/dist/app/system.d.mts

@@ -0,0 +1,144 @@
+import { tn as PlayerStateProvider } from "../types-ZQLYXo5X.mjs";
+import { ot as PlatformProvider } from "../index-8TiJQjQA.mjs";
+import { _ as SystemShellFactory, g as SystemName, h as SystemModules } from "../types-Ca_z_4tQ.mjs";
+import { Back, Haptics, KeepAwake, Lifecycle, Store } from "@moku-labs/system";
+
+//#region src/app/system.d.ts
+/**
+ * What the bridge reads of the system app: the four capabilities, each one there only when the
+ * game names its plugin. A system app of `lifecyclePlugin`, `backPlugin`, `hapticsPlugin` and
+ * `keepAwakePlugin` has all of them.
+ *
+ * @example
+ * ```ts
+ * const modules = { system: () => import("@moku-labs/system"), haptics: () => import("@moku-labs/system/haptics") };
+ * const slice: SystemSlice = await createSystemApp(["haptics"], "moku-game", modules); // slice.haptics only
+ * ```
+ */
+type SystemSlice = {
+  /** Pause and resume, from `@moku-labs/system/lifecycle`. */readonly lifecycle?: Lifecycle.LifecycleApi; /** The hardware Back press and the exit, from `@moku-labs/system/back`. */
+  readonly back?: Back.BackApi; /** Impact, outcome and selection ticks, from `@moku-labs/system/haptics`. */
+  readonly haptics?: Haptics.HapticsApi; /** The screen wake lock, from `@moku-labs/system/keep-awake`. */
+  readonly keepAwake?: KeepAwake.KeepAwakeApi;
+};
+/**
+ * What the store save reads of the system store: one read and one write.
+ *
+ * @example
+ * ```ts
+ * const system = createApp({ plugins: [storePlugin] }); // createApp of @moku-labs/system
+ * const store: StoreSlice = system.store;
+ * ```
+ */
+type StoreSlice = Pick<Store.StoreApi, "get" | "set">;
+/**
+ * The system app of the game shell: the capabilities of the plugins the game names, the store
+ * among them, and the start and stop of the app.
+ *
+ * @example
+ * ```ts
+ * const system: SystemApp = await createSystemApp(["lifecycle", "store"], "com.mokulabs.timber", {
+ *   system: () => import("@moku-labs/system"),
+ *   lifecycle: () => import("@moku-labs/system/lifecycle"),
+ *   store: () => import("@moku-labs/system/store")
+ * });
+ * await system.start(); // system.lifecycle and system.store answer from here on
+ * ```
+ */
+type SystemApp = SystemSlice & {
+  /** Key-value persistence, from `@moku-labs/system/store`. */readonly store?: Store.StoreApi; /** Starts the system app: every capability picks its provider. */
+  readonly start: () => Promise<void>; /** Stops the system app: every capability lets go of its provider. */
+  readonly stop: () => Promise<void>;
+};
+/**
+ * Builds the engine's provider over the system app. On iOS `exit` answers `unsupported`, so Leave
+ * lands back on Home there, as on the web page. A capability the slice lacks is inert, as the
+ * platform plugin is without a provider: its subscriptions remove nothing and its calls do nothing.
+ *
+ * @param system - The system app, with the capabilities the game names.
+ * @returns The provider to pass as the `platform` seam of `game.screen()`.
+ * @example
+ * ```ts
+ * import { createApp as createSystem } from "@moku-labs/system";
+ * const system = createSystem({ plugins: [lifecyclePlugin, backPlugin, hapticsPlugin, keepAwakePlugin] });
+ * fromSystem(system).haptic("success"); // the shell plays system.haptics.notify("success")
+ * fromSystem({}).exit(); // does nothing: the game named no back capability
+ * ```
+ */
+declare function fromSystem(system: SystemSlice): PlatformProvider;
+/**
+ * Creates the `@moku-labs/system` app of the named plugins, in the fixed order `lifecycle`,
+ * `back`, `haptics`, `keepAwake`, `store`, each name once. The store is named after `namespace`.
+ * Each plugin is loaded by its loader in `modules`, and only the named ones are called, so a page
+ * loads only the plugins its game names. The app is not started.
+ *
+ * @param names - The system plugins the game names, in any order.
+ * @param namespace - The store name: the native identifier, or `"moku-game"`.
+ * @param modules - The loaders of the page: the package, and one per named plugin.
+ * @returns The system app, not started.
+ * @throws {Error} When a named plugin has no loader in `modules`, or a loader rejects because
+ *   `@moku-labs/system` is not installed.
+ * @example
+ * ```ts
+ * // A shell of its own: the store named after the app, and the haptics.
+ * const system = await createSystemApp(["store", "haptics"], "com.mokulabs.timber", {
+ *   system: () => import("@moku-labs/system"),
+ *   haptics: () => import("@moku-labs/system/haptics"),
+ *   store: () => import("@moku-labs/system/store")
+ * });
+ * await system.start();
+ * await system.haptics?.selection(); // { ok: false, provider: "web", reason: "unsupported" } in iOS Safari
+ * ```
+ */
+declare function createSystemApp(names: readonly SystemName[], namespace: string, modules: SystemModules): Promise<SystemApp>;
+/**
+ * Builds the save provider over the system store: idb on the web, the Tauri store in the native
+ * app. It holds the document it loaded and applies each commit's patches to it, then queues one
+ * write of the whole value, so the writes stay in commit order. A read the store refuses rejects
+ * the load: answering "new player" would overwrite a real save at the first commit. A write the
+ * store refuses is reported from `commit` and rejects `commitDurable`; the next write still goes.
+ *
+ * @param store - The system store.
+ * @param key - The store key of the save.
+ * @param report - Takes the problem of a write `commit` could not store.
+ * @returns The provider to pass as the `provider` seam of `game.screen()`.
+ * @example
+ * ```ts
+ * import { createApp as createSystem } from "@moku-labs/system";
+ * const system = createSystem({ plugins: [storePlugin], pluginConfigs: { store: { name: "com.mokulabs.timber" } } });
+ * await system.start();
+ * const save = storeSave(system.store, "save", problem => problems.push(problem));
+ * await save.load(); // null for a new player; rejects when the store cannot be read
+ * ```
+ */
+declare function storeSave(store: StoreSlice, key: string, report: (problem: string) => void): PlayerStateProvider;
+/**
+ * Makes the system shell factory of a page over its loaders. The factory builds the shell from the
+ * resolved `config.ts`: the `@moku-labs/system` app of the names `config.system` lists, plus the
+ * store when `config.save` is `"store"`, in the fixed order. It hands the engine the platform
+ * provider over that app and, for a store save, the save provider. Nothing loads until the page
+ * calls the factory, and the page starts the shell before the game. The generated `main.ts`
+ * passes it to `startPage` with one loader per name, only when `config.ts` names a system plugin
+ * or the store save.
+ *
+ * @param modules - The loaders of the page: the package, and one per named plugin.
+ * @returns The factory the page calls; it throws the messages of `createSystemApp`.
+ * @example
+ * ```ts
+ * // The in-memory .moku/build/main.ts of moku-game build, for a game whose config.ts names back.
+ * import { startPage } from "@moku-labs/game/app/page";
+ * import { systemShellOf } from "@moku-labs/game/app/system";
+ * import game from "../../index.ts";
+ * import config from "../../config.ts";
+ *
+ * await startPage(game, config, {
+ *   system: systemShellOf({
+ *     system: () => import("@moku-labs/system"),
+ *     back: () => import("@moku-labs/system/back")
+ *   })
+ * });
+ * ```
+ */
+declare function systemShellOf(modules: SystemModules): SystemShellFactory;
+//#endregion
+export { StoreSlice, SystemApp, type SystemModules, SystemSlice, createSystemApp, fromSystem, storeSave, systemShellOf };

package/dist/app/system.mjs

@@ -0,0 +1,329 @@
+import { t as applyTo } from "../drafts-BawpSaVp.mjs";
+//#region src/app/system.ts
+/** The system plugins in the order the shell composes them, whatever the order of `config.ts`. */
+const systemOrder = [
+	"lifecycle",
+	"back",
+	"haptics",
+	"keepAwake",
+	"store"
+];
+/** The store namespace of a game with no native identifier. */
+const defaultNamespace = "moku-game";
+/** The store key of the save, inside the game's namespace. */
+const saveKey = "save";
+/**
+* Removes nothing: the remover of a subscription the shell cannot make, because the game did not
+* name the capability.
+*/
+function removeNothing() {}
+/**
+* Plays one tick of the engine with the capability of its kind: the three impacts, the three
+* outcome patterns, and the selection tick.
+*
+* @param haptics - The haptics capability of the system app.
+* @param kind - One of the seven kinds of `HAPTIC_KINDS`.
+* @returns What the shell answered.
+*/
+function play(haptics, kind) {
+	switch (kind) {
+		case "light":
+		case "medium":
+		case "heavy": return haptics.impact(kind);
+		case "success":
+		case "warning":
+		case "error": return haptics.notify(kind);
+		case "selection": return haptics.selection();
+	}
+}
+/**
+* Asks the shell without waiting for the answer. A capability answers with a `SystemResult`, never
+* a throw, and the provider of the engine returns nothing: a tick the shell cannot play (iOS
+* Safari, a desktop) is an honest `unsupported`, not an error of the game. A capability the game
+* did not name is not asked.
+*
+* @param capability - The capability, or `undefined` when the game did not name it.
+* @param ask - The capability call.
+*/
+function send(capability, ask) {
+	if (capability !== void 0) ask(capability);
+}
+/**
+* Subscribes through a capability, or subscribes nothing when the game did not name it.
+*
+* @param capability - The capability, or `undefined` when the game did not name it.
+* @param listen - The subscription; it returns its remover.
+* @returns The remover of the subscription, or one that removes nothing.
+*/
+function subscribe(capability, listen) {
+	return capability === void 0 ? removeNothing : listen(capability);
+}
+/**
+* Builds the engine's provider over the system app. On iOS `exit` answers `unsupported`, so Leave
+* lands back on Home there, as on the web page. A capability the slice lacks is inert, as the
+* platform plugin is without a provider: its subscriptions remove nothing and its calls do nothing.
+*
+* @param system - The system app, with the capabilities the game names.
+* @returns The provider to pass as the `platform` seam of `game.screen()`.
+* @example
+* ```ts
+* import { createApp as createSystem } from "@moku-labs/system";
+* const system = createSystem({ plugins: [lifecyclePlugin, backPlugin, hapticsPlugin, keepAwakePlugin] });
+* fromSystem(system).haptic("success"); // the shell plays system.haptics.notify("success")
+* fromSystem({}).exit(); // does nothing: the game named no back capability
+* ```
+*/
+function fromSystem(system) {
+	return {
+		onPause: (fn) => subscribe(system.lifecycle, (lifecycle) => lifecycle.onPause(fn)),
+		onResume: (fn) => subscribe(system.lifecycle, (lifecycle) => lifecycle.onResume(fn)),
+		onBack: (fn) => subscribe(system.back, (back) => back.onPress(fn)),
+		haptic: (kind) => send(system.haptics, (haptics) => play(haptics, kind)),
+		keepAwake: (on) => send(system.keepAwake, (keepAwake) => keepAwake.set(on)),
+		exit: () => send(system.back, (back) => back.exit())
+	};
+}
+/**
+* Refuses a named plugin the page has no loader for, before anything loads. The generated
+* `main.ts` writes a loader per name; a page of its own may miss one.
+*
+* @param names - The system plugins of the shell.
+* @param modules - The loaders of the page.
+* @throws {Error} When a name has no loader.
+*/
+function checkLoaders(names, modules) {
+	const missing = names.find((name) => modules[name] === void 0);
+	if (missing !== void 0) throw new Error(`[game] config.system names "${missing}", but main.ts has no loader for it.`);
+}
+/**
+* One plugin per capability, through the loader of the page. The loaders are checked first, so
+* each one called is there.
+*/
+const capabilityPlugins = {
+	lifecycle: (modules) => modules.lifecycle?.().then((module) => module.lifecyclePlugin),
+	back: (modules) => modules.back?.().then((module) => module.backPlugin),
+	haptics: (modules) => modules.haptics?.().then((module) => module.hapticsPlugin),
+	keepAwake: (modules) => modules.keepAwake?.().then((module) => module.keepAwakePlugin)
+};
+/**
+* Loads `@moku-labs/system` and the plugins of the names, all at once, with the loaders of the
+* page.
+*
+* @param names - The system plugins, in the fixed order.
+* @param modules - The loaders of the page.
+* @returns The `createApp` of the package, the capability plugins in the order of the names, and
+*   the store plugin when the names hold it.
+* @throws {Error} When a name has no loader, or a loader rejects: the package is not installed.
+*/
+async function loadSystem(names, modules) {
+	checkLoaders(names, modules);
+	const capabilities = names.filter((name) => name !== "store");
+	try {
+		const [system, store, ...plugins] = await Promise.all([
+			modules.system(),
+			names.includes("store") ? modules.store?.().then((module) => module.storePlugin) : void 0,
+			...capabilities.map((name) => capabilityPlugins[name](modules))
+		]);
+		return {
+			createApp: system.createApp,
+			capabilities: plugins,
+			store
+		};
+	} catch (error) {
+		throw new Error("[game] config.system needs @moku-labs/system.\n  Install it: bun add @moku-labs/system@^0.3.1.", { cause: error });
+	}
+}
+/**
+* Creates the `@moku-labs/system` app of the named plugins, in the fixed order `lifecycle`,
+* `back`, `haptics`, `keepAwake`, `store`, each name once. The store is named after `namespace`.
+* Each plugin is loaded by its loader in `modules`, and only the named ones are called, so a page
+* loads only the plugins its game names. The app is not started.
+*
+* @param names - The system plugins the game names, in any order.
+* @param namespace - The store name: the native identifier, or `"moku-game"`.
+* @param modules - The loaders of the page: the package, and one per named plugin.
+* @returns The system app, not started.
+* @throws {Error} When a named plugin has no loader in `modules`, or a loader rejects because
+*   `@moku-labs/system` is not installed.
+* @example
+* ```ts
+* // A shell of its own: the store named after the app, and the haptics.
+* const system = await createSystemApp(["store", "haptics"], "com.mokulabs.timber", {
+*   system: () => import("@moku-labs/system"),
+*   haptics: () => import("@moku-labs/system/haptics"),
+*   store: () => import("@moku-labs/system/store")
+* });
+* await system.start();
+* await system.haptics?.selection(); // { ok: false, provider: "web", reason: "unsupported" } in iOS Safari
+* ```
+*/
+async function createSystemApp(names, namespace, modules) {
+	const { createApp, capabilities, store } = await loadSystem(systemOrder.filter((name) => names.includes(name)), modules);
+	if (store === void 0) return createApp({ plugins: capabilities });
+	return createApp({
+		plugins: [...capabilities, store],
+		pluginConfigs: { store: { name: namespace } }
+	});
+}
+/**
+* Names why the store said no: the reason, and the store's own words when it gave some.
+*
+* @param failure - The failed answer of the store.
+* @returns The reason, for an error message.
+* @example
+* ```ts
+* failureText({ ok: false, provider: "tauri", reason: "denied", message: "not allowed" }); // "denied, not allowed"
+* ```
+*/
+function failureText(failure) {
+	return failure.message === void 0 ? failure.reason : `${failure.reason}, ${failure.message}`;
+}
+/**
+* Builds the message of a save the store did not take.
+*
+* @param reason - Why the store did not take it.
+* @returns The message.
+* @example
+* ```ts
+* notStored("denied"); // "[game] The save was not stored: denied.\n  Check the store permission of the native build; progress since the last stored save is lost on close."
+* ```
+*/
+function notStored(reason) {
+	return `[game] The save was not stored: ${reason}.\n  Check the store permission of the native build; progress since the last stored save is lost on close.`;
+}
+/**
+* Writes the whole save once, after the write before it. It never rejects, so one refused write
+* never stops the writes after it.
+*
+* @param previous - The write before this one, or `undefined` for the first.
+* @param store - The system store.
+* @param key - The store key of the save.
+* @param value - The document and its version.
+* @returns The problem of a write the store did not take, or `undefined` once it is stored.
+*/
+async function write(previous, store, key, value) {
+	await previous;
+	try {
+		const result = await store.set(key, value);
+		return result.ok ? void 0 : notStored(failureText(result));
+	} catch (error) {
+		return notStored(error instanceof Error ? error.message : String(error));
+	}
+}
+/**
+* Reports the problem of a write nobody waits for, once the write is done.
+*
+* @param written - The queued write.
+* @param report - Takes the problem of a write the store did not take.
+*/
+async function reportProblem(written, report) {
+	const problem = await written;
+	if (problem !== void 0) report(problem);
+}
+/**
+* Builds the save provider over the system store: idb on the web, the Tauri store in the native
+* app. It holds the document it loaded and applies each commit's patches to it, then queues one
+* write of the whole value, so the writes stay in commit order. A read the store refuses rejects
+* the load: answering "new player" would overwrite a real save at the first commit. A write the
+* store refuses is reported from `commit` and rejects `commitDurable`; the next write still goes.
+*
+* @param store - The system store.
+* @param key - The store key of the save.
+* @param report - Takes the problem of a write `commit` could not store.
+* @returns The provider to pass as the `provider` seam of `game.screen()`.
+* @example
+* ```ts
+* import { createApp as createSystem } from "@moku-labs/system";
+* const system = createSystem({ plugins: [storePlugin], pluginConfigs: { store: { name: "com.mokulabs.timber" } } });
+* await system.start();
+* const save = storeSave(system.store, "save", problem => problems.push(problem));
+* await save.load(); // null for a new player; rejects when the store cannot be read
+* ```
+*/
+function storeSave(store, key, report) {
+	const held = {
+		document: void 0,
+		written: void 0
+	};
+	/**
+	* Applies the patches of one commit to the held document and queues the write of the whole
+	* value after the last one.
+	*
+	* @param patches - Doc patches since the last commit.
+	* @param version - Schema version this build writes.
+	* @returns The problem of this write, or `undefined` once it is stored.
+	*/
+	const queue = (patches, version) => {
+		const document = applyTo(held.document ?? {}, patches);
+		const written = write(held.written, store, key, {
+			state: document,
+			version
+		});
+		held.document = document;
+		held.written = written;
+		return written;
+	};
+	return {
+		load: async () => {
+			const read = await store.get(key);
+			if (!read.ok) throw new Error(`[game] The save could not be read from the system store: ${failureText(read)}.\n  The game does not start over it; check the store permission of the native build.`);
+			if (read.value === void 0) return null;
+			held.document = read.value.state;
+			return {
+				state: read.value.state,
+				version: read.value.version
+			};
+		},
+		commit: (patches, version) => {
+			reportProblem(queue(patches, version), report);
+		},
+		commitDurable: async (patches, _txId, version) => {
+			const problem = await queue(patches, version);
+			if (problem !== void 0) throw new Error(problem);
+		},
+		flush: async () => {
+			await held.written;
+		}
+	};
+}
+/**
+* Makes the system shell factory of a page over its loaders. The factory builds the shell from the
+* resolved `config.ts`: the `@moku-labs/system` app of the names `config.system` lists, plus the
+* store when `config.save` is `"store"`, in the fixed order. It hands the engine the platform
+* provider over that app and, for a store save, the save provider. Nothing loads until the page
+* calls the factory, and the page starts the shell before the game. The generated `main.ts`
+* passes it to `startPage` with one loader per name, only when `config.ts` names a system plugin
+* or the store save.
+*
+* @param modules - The loaders of the page: the package, and one per named plugin.
+* @returns The factory the page calls; it throws the messages of `createSystemApp`.
+* @example
+* ```ts
+* // The in-memory .moku/build/main.ts of moku-game build, for a game whose config.ts names back.
+* import { startPage } from "@moku-labs/game/app/page";
+* import { systemShellOf } from "@moku-labs/game/app/system";
+* import game from "../../index.ts";
+* import config from "../../config.ts";
+*
+* await startPage(game, config, {
+*   system: systemShellOf({
+*     system: () => import("@moku-labs/system"),
+*     back: () => import("@moku-labs/system/back")
+*   })
+* });
+* ```
+*/
+function systemShellOf(modules) {
+	return async (config, report) => {
+		const app = await createSystemApp(config.save === "store" ? [...config.system, "store"] : config.system, config.native?.identifier ?? defaultNamespace, modules);
+		return {
+			handle: app,
+			platform: fromSystem(app),
+			save: app.store === void 0 ? void 0 : storeSave(app.store, saveKey, report),
+			start: () => app.start(),
+			stop: () => app.stop()
+		};
+	};
+}
+//#endregion
+export { createSystemApp, fromSystem, storeSave, systemShellOf };

package/dist/app.d.mts

@@ -0,0 +1,37 @@
+import { Xt as Json } from "./types-ZQLYXo5X.mjs";
+import { a as GameHandle, c as MemoryProvider, d as SaveKind, f as Scenario, g as SystemName, i as GameDefinition, l as PageAgent, n as GameApp, o as GamePluginConfigs, p as ScreenSeams, r as GameConfig, s as HeadlessSeams } from "./types-Ca_z_4tQ.mjs";
+import { AnyPluginInstance } from "@moku-labs/core";
+
+//#region src/app/define.d.ts
+/**
+ * The moment the default fake clock starts at, in epoch milliseconds. A test stamps times from it.
+ *
+ * @example
+ * ```ts
+ * game.headless().clock.now() === startMoment; // true
+ * ```
+ */
+declare const startMoment = 1000000;
+/**
+ * Turns a game's one data object into the game: `game.headless()` for logic tests and
+ * `game.screen()` for the page and the screen tests. Every type comes from the object: the plugin
+ * tuples, the player and the session. Checks the definition at once, so an error points at
+ * `index.ts`.
+ *
+ * @param definition - The game: its flow, starting state, features, plugins and plugin configs.
+ * @returns The game, with `headless()` and `screen()`; no app is created yet.
+ * @throws {Error} When `flow` is missing, or an entry of `shared`, `features` or `headless.features` is not a feature.
+ * @example
+ * ```ts
+ * // index.ts of a game: the whole game, no createApp call. Its tests import it as `game`.
+ * export default defineGameApp({
+ *   flow: mainFlow, safeNode: "home", player: startingPlayer, session: startingSession,
+ *   shared: sharedFeature, features: [homeFeature, boardFeature, rewardFeature], plugins: [loadingPlugin],
+ *   headless: { features: [rewardFeature] }, pluginConfigs: { ui: { tapTargetPt: 48 } }
+ * });
+ * game.headless({ seed: 7 }).app.flow.state().running; // false: the test starts it
+ * ```
+ */
+declare function defineGameApp<const Plugins extends readonly AnyPluginInstance[] = readonly [], const HeadlessPlugins extends readonly AnyPluginInstance[] = readonly [], Player extends Json = Json, Session extends Json = Json>(definition: GameDefinition<Plugins, HeadlessPlugins, Player, Session>): GameApp<Plugins, HeadlessPlugins, Player, Session>;
+//#endregion
+export { type GameApp, type GameConfig, type GameDefinition, type GameHandle, type GamePluginConfigs, type HeadlessSeams, type MemoryProvider, type PageAgent, type SaveKind, type Scenario, type ScreenSeams, type SystemName, defineGameApp, startMoment };