@moku-labs/game 0.0.0

package/dist/index.d.mts

@@ -0,0 +1,327 @@
+import { A as Patch, B as PauseReason, C as State, D as Root, E as Json, F as StoreApi, G as State$4, H as types_d_exports$2, I as RngApi, J as Events, K as types_d_exports$4, O as State$3, P as SaveUnreadableError, R as Api$2, T as Config$3, U as Api$3, V as State$2, W as Config$4, _ as GuideOptions, a as Kit, b as Api, c as exit, d as type, f as FeatureDescription, g as Descriptor, i as GameTypes, k as types_d_exports$3, l as slot, n as Config$1, o as State$1, q as Config$5, r as FeaturePlugin, s as types_d_exports$1, t as Api$1, u as to, v as Hint, w as types_d_exports, x as Config, z as Config$2 } from "./types-BfsmUzLC.mjs";
+
+//#region src/plugins/clock/index.d.ts
+/**
+ * Clock plugin: `app.clock.now()`, `app.clock.scheduleAt(moment)`, `app.clock.onElapsed(fn)`.
+ *
+ * @example
+ * ```ts
+ * ctx.require(clockPlugin).scheduleAt(nextDue);
+ * ```
+ */
+declare const clockPlugin: import("@moku-labs/core").PluginInstance<"clock", Config, State, Api, {}> & Record<never, never>;
+//#endregion
+//#region src/plugins/flow/index.d.ts
+/**
+ * Flow plugin: `app.flow.run()`, `app.flow.gate.answer(...)`, `app.flow.fx.handle(...)`.
+ *
+ * @example
+ * ```ts
+ * createApp({ pluginConfigs: { flow: { mainFlow } }, onStart: startGraph });
+ * ```
+ */
+declare const flowPlugin: import("@moku-labs/core").PluginInstance<"flow", Config$1, State$1, Api$1, {
+  "flow:edge": {
+    flow: string;
+    node: string;
+    outcome: string;
+    payload: Json;
+    next: string;
+    patches: {
+      doc: Patch[];
+      session: Patch[];
+    };
+    index: number;
+    now: number;
+  };
+  "flow:rest": {
+    path: string;
+    checkpoint: boolean;
+  };
+  "flow:error": {
+    path: string;
+    error: unknown;
+    rolledBackTo: string;
+    retry: boolean;
+  };
+}> & Record<never, never>;
+//#endregion
+//#region src/plugins/lifecycle/index.d.ts
+/**
+ * Lifecycle plugin: `app.lifecycle.push(reason)`, `app.lifecycle.pop(reason)`.
+ *
+ * @example
+ * ```ts
+ * ctx.require(lifecyclePlugin).push("background");
+ * ```
+ */
+declare const lifecyclePlugin: import("@moku-labs/core").PluginInstance<"lifecycle", Config$2, State$2, Api$2, {
+  "lifecycle:changed": {
+    reason: PauseReason;
+    action: "push" | "pop";
+    reasons: readonly PauseReason[];
+    paused: boolean;
+    resumed: boolean;
+  };
+}> & Record<never, never>;
+//#endregion
+//#region src/plugins/model/index.d.ts
+/**
+ * Model plugin: `app.model.store`, `app.model.rng`.
+ *
+ * @example
+ * ```ts
+ * const transaction = ctx.require(modelPlugin).store.begin();
+ * ```
+ */
+declare const modelPlugin: import("@moku-labs/core").PluginInstance<"model", Config$3, State$3, {
+  store: StoreApi;
+  rng: RngApi;
+}, {
+  "model:committed": {
+    roots: readonly Root[];
+    cause: "edge" | "rollback" | "restore" | "load";
+  };
+}> & Record<never, never>;
+//#endregion
+//#region src/plugins/time/index.d.ts
+/**
+ * Time plugin: `app.time.onFrame(phase, fn)`, `app.time.step(dt)`.
+ *
+ * @example
+ * ```ts
+ * ctx.require(timePlugin).onFrame("animate", advanceTweens);
+ * ```
+ */
+declare const timePlugin: import("@moku-labs/core").PluginInstance<"time", Config$4, State$4, Api$3, {}> & Record<never, never>;
+//#endregion
+//#region src/plugins/flow/feature.d.ts
+/**
+ * Turns a feature description into a plugin that registers it with `flow.features` in `onInit`.
+ * Throws for a name that is reserved or already a plugin. The plugin carries `logicOnly`: the
+ * same plugin built from the V1 keys of the description, for headless tests.
+ *
+ * @param name - Feature name. Shares the namespace with plugin names.
+ * @param description - What the feature brings: nodes, flows, slot contributions.
+ * @returns The feature plugin, with its `logicOnly` twin.
+ * @throws {Error} When the name is reserved or belongs to an engine plugin.
+ * @example
+ * ```ts
+ * export const boardFeature = defineFeature("board", {
+ *   flows: [boardFlow],
+ *   contribute: { afterWin: { flow: rewardFlow, order: 10 } }
+ * });
+ * ```
+ */
+declare function defineFeature(name: string, description: FeatureDescription): FeaturePlugin;
+//#endregion
+//#region src/plugins/flow/fx/descriptors.d.ts
+/**
+ * Creates a fire-and-forget cosmetic descriptor for `fx.emit`. It is dispatched only after the
+ * commit of its transaction and dropped in fast mode.
+ *
+ * @param kind - Effect kind a handler is registered for.
+ * @param payload - Plain JSON for the handler.
+ * @returns The hint as plain data.
+ * @example
+ * ```ts
+ * fx.emit(hint("sparkle", { cell: "c3" }));
+ * ```
+ */
+declare function hint(kind: string, payload?: Json): Hint;
+/**
+ * Creates the awaited effect that asks the clock for one `elapsed` at this moment. `undefined`
+ * means nothing is due and leaves the `moment` key out, so the descriptor stays plain JSON. Its
+ * handler runs in fast mode too.
+ *
+ * @param moment - Epoch milliseconds of the next due timer, or `undefined`.
+ * @returns The descriptor a node awaits.
+ * @example
+ * ```ts
+ * await fx(schedule(rules.nextDue(player, tables)));
+ * ```
+ */
+declare function schedule(moment: number | undefined): Descriptor;
+/**
+ * Creates the tutorial descriptor: it narrows the gate to one answer until the node exits. Its
+ * visual part (highlight, hand, text) is handled by `ui` later. The highlight list is copied, so
+ * a later change of the caller's array cannot reach the descriptor.
+ *
+ * @param options - The allowed answer and the visual hints.
+ * @returns The descriptor a node awaits.
+ * @example
+ * ```ts
+ * await fx(guide({ allow: { intent: "merge", payload: { from: "c2", to: "c3" } }, hand: "drag" }));
+ * ```
+ */
+declare function guide(options: GuideOptions): Descriptor;
+//#endregion
+//#region src/teardown.d.ts
+/**
+ * @file Teardown registry — the single allowlisted module-scope state of the package.
+ */
+/**
+ * Function that frees one plugin's resources.
+ *
+ * @example
+ * ```ts
+ * const dispose: Disposer = () => cancelAnimationFrame(handle);
+ * ```
+ */
+type Disposer = () => void | Promise<void>;
+/**
+ * Registers a disposer for one plugin of one app. A second call with the same key replaces the first.
+ *
+ * @param global - The app's frozen global config object, used as identity.
+ * @param key - Plugin name.
+ * @param dispose - Function that frees the plugin's resources.
+ * @example
+ * ```ts
+ * teardown.register(ctx.global, "time", stopLoop);
+ * ```
+ */
+declare function register(global: object, key: string, dispose: Disposer): void;
+/**
+ * Runs and removes the disposer of one plugin. A missing key is a no-op.
+ * A throwing disposer is reported and never rethrown, so one plugin cannot block the stop of the others.
+ *
+ * @param global - The app's global config object.
+ * @param key - Plugin name.
+ * @returns Resolves when the disposer has finished.
+ * @example
+ * ```ts
+ * await teardown.run(global, "time");
+ * ```
+ */
+declare function run(global: object, key: string): Promise<void>;
+/**
+ * Teardown registry keyed by `ctx.global`.
+ *
+ * @example
+ * ```ts
+ * onStop: ({ global }) => teardown.run(global, "time")
+ * ```
+ */
+declare const teardown: {
+  register: typeof register;
+  run: typeof run;
+};
+//#endregion
+//#region src/index.d.ts
+/**
+ * Creates a game application.
+ *
+ * @example
+ * ```ts
+ * const app = createApp({ plugins: [boardFeature] });
+ * ```
+ */
+declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<Config$5, Events, (import("@moku-labs/core").PluginInstance<"time", Config$4, State$4, Api$3, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"lifecycle", Config$2, State$2, Api$2, {
+  "lifecycle:changed": {
+    reason: PauseReason;
+    action: "push" | "pop";
+    reasons: readonly PauseReason[];
+    paused: boolean;
+    resumed: boolean;
+  };
+}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"model", Config$3, State$3, {
+  store: StoreApi;
+  rng: RngApi;
+}, {
+  "model:committed": {
+    roots: readonly Root[];
+    cause: "edge" | "rollback" | "restore" | "load";
+  };
+}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"clock", Config, State, Api, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"flow", Config$1, State$1, Api$1, {
+  "flow:edge": {
+    flow: string;
+    node: string;
+    outcome: string;
+    payload: Json;
+    next: string;
+    patches: {
+      doc: Patch[];
+      session: Patch[];
+    };
+    index: number;
+    now: number;
+  };
+  "flow:rest": {
+    path: string;
+    checkpoint: boolean;
+  };
+  "flow:error": {
+    path: string;
+    error: unknown;
+    rolledBackTo: string;
+    retry: boolean;
+  };
+}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common/browser").LogConfig, import("@moku-labs/common/browser").LogState, import("@moku-labs/common/browser").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common/browser").EnvConfig, import("@moku-labs/common/browser").EnvState, import("@moku-labs/common/browser").EnvApi>]>> | undefined) => import("@moku-labs/core").App<Config$5, Events, (import("@moku-labs/core").PluginInstance<"time", Config$4, State$4, Api$3, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"lifecycle", Config$2, State$2, Api$2, {
+  "lifecycle:changed": {
+    reason: PauseReason;
+    action: "push" | "pop";
+    reasons: readonly PauseReason[];
+    paused: boolean;
+    resumed: boolean;
+  };
+}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"model", Config$3, State$3, {
+  store: StoreApi;
+  rng: RngApi;
+}, {
+  "model:committed": {
+    roots: readonly Root[];
+    cause: "edge" | "rollback" | "restore" | "load";
+  };
+}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"clock", Config, State, Api, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"flow", Config$1, State$1, Api$1, {
+  "flow:edge": {
+    flow: string;
+    node: string;
+    outcome: string;
+    payload: Json;
+    next: string;
+    patches: {
+      doc: Patch[];
+      session: Patch[];
+    };
+    index: number;
+    now: number;
+  };
+  "flow:rest": {
+    path: string;
+    checkpoint: boolean;
+  };
+  "flow:error": {
+    path: string;
+    error: unknown;
+    rolledBackTo: string;
+    retry: boolean;
+  };
+}> & Record<never, never>) | ExtraPlugins[number], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common/browser").LogConfig, import("@moku-labs/common/browser").LogState, import("@moku-labs/common/browser").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common/browser").EnvConfig, import("@moku-labs/common/browser").EnvState, import("@moku-labs/common/browser").EnvApi>]>>;
+/**
+ * Creates a game plugin.
+ *
+ * @example
+ * ```ts
+ * export const scorePlugin = createPlugin("score", { api: createScoreApi });
+ * ```
+ */
+declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$5, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common/browser").LogConfig, import("@moku-labs/common/browser").LogState, import("@moku-labs/common/browser").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common/browser").EnvConfig, import("@moku-labs/common/browser").EnvState, import("@moku-labs/common/browser").EnvApi>]>>;
+/**
+ * Binds the authoring helpers to the types of one game: "createApp for a game". The binding is
+ * type-only; at run time these are the same functions the plugins export. One line per helper,
+ * no logic: anything a single plugin can own lives in that plugin.
+ *
+ * @returns The helpers typed with the game's `player` and `session`.
+ * @example
+ * ```ts
+ * export const { defineNode, defineFlow, defineFeature } = defineGame<{
+ *   player: Player;
+ *   session: Session;
+ *   assets: AssetKey;
+ *   strings: StringTable;
+ * }>();
+ * ```
+ */
+declare function defineGame<Types extends GameTypes>(): Kit<Types>;
+//#endregion
+export { types_d_exports as Clock, types_d_exports$1 as Flow, types_d_exports$2 as Lifecycle, types_d_exports$3 as Model, SaveUnreadableError, types_d_exports$4 as Time, clockPlugin, createApp, createPlugin, defineFeature, defineGame, exit, flowPlugin, guide, hint, lifecyclePlugin, modelPlugin, schedule, slot, teardown, timePlugin, to, type };