@moku-labs/game 0.0.1 → 0.0.2

package/dist/types-DYLnSgMI.d.mts

@@ -0,0 +1,570 @@
+import { I as Events$1, L as Json, P as Api$2, Q as Events$2, T as Descriptor, k as Api$1, lt as Require, t as Api } from "./types-JNc_UQBo.mjs";
+import { L as Owner, _ as LayerSort, u as Api$3, v as LayerSpec } from "./types-BxkNNYul.mjs";
+import { o as Events$3, t as Api$4 } from "./types-DWILGrPn.mjs";
+import { Log } from "@moku-labs/common/browser";
+import { PluginCtx } from "@moku-labs/core";
+
+//#region src/plugins/scenes/types.d.ts
+declare namespace types_d_exports$1 {
+  export { AnySceneProjection, CheckedProjections, Config$1 as Config, DefineScene, Deps$1 as Deps, Events, KernelSlice$1 as KernelSlice, LayerMap, RunContext, SceneDefinition, SceneLayer, SceneOwner, SceneProjection, SceneSpec, ScenesApi, ScenesCtx, SortRule, State$1 as State, UiLayer };
+}
+/**
+ * How a layer orders what is drawn in it. The scene's name for the rule `world` stores.
+ *
+ * @example
+ * ```ts
+ * const sort: SortRule = "y";
+ * ```
+ */
+type SortRule = LayerSort;
+/**
+ * What a scene declares about its layers: the key is the layer name, the order of the keys is
+ * draw order, bottom first. An omitted `sort` means `"none"`.
+ *
+ * @example
+ * ```ts
+ * const layers: LayerMap = { background: {}, cells: {}, items: { sort: "y" }, lifted: {} };
+ * ```
+ */
+type LayerMap = Record<string, {
+  sort?: SortRule;
+}>;
+/**
+ * The name of the layer every scene gets on top of the layers it declared, where popups and the
+ * HUD are mounted. A scene that declares it keeps the place it wrote it in.
+ *
+ * @example
+ * ```ts
+ * const layer: UiLayer = "ui";
+ * ```
+ */
+type UiLayer = "ui";
+/**
+ * The layer names the projections of a scene may use: the keys the scene declared and the
+ * appended `ui`, which is there whether the scene wrote it or not.
+ *
+ * @example
+ * ```ts
+ * const layer: SceneLayer<{ cells: Record<never, never> }> = "ui"; // or "cells"
+ * ```
+ */
+type SceneLayer<Layers extends LayerMap> = (keyof Layers & string) | UiLayer;
+/**
+ * Any projection as a scene reads it. `projection()` widens `lift` to `string` when the author
+ * declared none, so this is the loosest shape `defineScene` accepts.
+ *
+ * @example
+ * ```ts
+ * const spec: AnySceneProjection = { name: "board.items", layer: "items", lift: "lifted" };
+ * ```
+ */
+type AnySceneProjection = {
+  readonly name: string;
+  readonly layer: string;
+  readonly lift?: string;
+};
+/**
+ * The three fields of a `ProjectionSpec` a scene reads, with both layers checked against the
+ * layers the scene declares. It is what a wrong `layer` or `lift` is reported against.
+ *
+ * @example
+ * ```ts
+ * const spec: SceneProjection<"items" | "lifted"> = { name: "board.items", layer: "items" };
+ * ```
+ */
+type SceneProjection<Layer extends string> = {
+  readonly name: string;
+  readonly layer: Layer;
+  readonly lift?: Layer;
+};
+/**
+ * Checks the `lift` of one projection. A projection built without a `lift` carries the widened
+ * `string` of `projection()`, which is the one lift that is always accepted.
+ */
+type CheckedLift<Layer extends string, Spec> = Spec extends {
+  readonly lift?: infer Lift;
+} ? string extends Exclude<Lift, undefined> ? Spec : Exclude<Lift, undefined> extends Layer ? Spec : SceneProjection<Layer> : Spec;
+/**
+ * Checks one projection of a scene: first its `layer`, then its `lift`. A projection that fails
+ * becomes `SceneProjection<Layer>`, so the compiler prints the layer names it accepts.
+ */
+type CheckedProjection<Layer extends string, Spec> = Spec extends {
+  readonly layer: infer Declared;
+} ? Declared extends Layer ? CheckedLift<Layer, Spec> : SceneProjection<Layer> : SceneProjection<Layer>;
+/**
+ * Checking type: validates the projections of a scene one by one against its layer names, so the
+ * error sits on the projection that is wrong and not on the whole list.
+ *
+ * @example
+ * ```ts
+ * type Checked = CheckedProjections<"items", readonly [{ name: "board.items"; layer: "items" }]>;
+ * ```
+ */
+type CheckedProjections<Layer extends string, List> = { readonly [Index in keyof List]: CheckedProjection<Layer, List[Index]> };
+/**
+ * What the author passes to `defineScene`. The layer names come from the keys of `layers` plus
+ * the appended `ui`; `NoInfer` keeps `projections` out of that inference, so a wrong name is
+ * reported on the projection and never widens the layer union. `music` is an asset key of the
+ * game, narrowed to its audio keys once the scanner splits them.
+ *
+ * @example
+ * ```ts
+ * const spec: SceneSpec<{ items: Record<never, never> }, readonly [], string, "board"> = {
+ *   bundle: "board",
+ *   layers: { items: {} },
+ *   projections: []
+ * };
+ * ```
+ */
+type SceneSpec<Layers extends LayerMap, Projections extends readonly AnySceneProjection[], Asset extends string, Bundle extends string> = {
+  bundle: Bundle;
+  layers: Layers;
+  projections: Projections & CheckedProjections<NoInfer<SceneLayer<Layers>>, NoInfer<Projections>>;
+  music?: Asset;
+};
+/**
+ * The signature of `defineScene` bound to the asset and bundle keys of one game.
+ * `defineGame<Types>()` returns it; the loose export accepts any string.
+ *
+ * @example
+ * ```ts
+ * const defineGameScene: DefineScene<"board.music", "board"> = defineScene;
+ * ```
+ */
+type DefineScene<Asset extends string, Bundle extends string> = <Layers extends LayerMap, const Projections extends readonly AnySceneProjection[]>(id: string, scene: SceneSpec<Layers, Projections, Asset, Bundle>) => SceneDefinition;
+/**
+ * A scene as `defineScene` returns it: plain frozen data, ready for the `scenes` key of a feature.
+ *
+ * @example
+ * ```ts
+ * // What defineScene("board", { bundle: "board", layers: { items: { sort: "y" } }, projections: [] })
+ * // returns: { id: "board", bundle: "board", music: undefined,
+ * //   layers: [{ name: "items", sort: "y" }, { name: "ui", sort: "none" }], projections: [] }
+ * ```
+ */
+type SceneDefinition = {
+  readonly id: string;
+  readonly bundle: string;
+  readonly music: string | undefined; /** Draw order, bottom first. */
+  readonly layers: readonly LayerSpec[]; /** Names of the projections the scene mounts. */
+  readonly projections: readonly string[];
+};
+/**
+ * The one owner every mount of this plugin carries. One is enough: one scene is mounted at a
+ * time, and `unmount` is what flushes.
+ *
+ * @example
+ * ```ts
+ * const owner: SceneOwner = { kind: "plugin", name: "scenes" };
+ * ```
+ */
+type SceneOwner = Owner & {
+  kind: "plugin";
+  name: "scenes";
+};
+/**
+ * scenes plugin config: none. A scene is data in a feature, and a transition effect is V3 work
+ * of `anim`, so a key here would have no reader.
+ *
+ * @example
+ * ```ts
+ * const config: Config = {};
+ * ```
+ */
+type Config$1 = Record<string, never>;
+/**
+ * scenes plugin state.
+ */
+type State$1 = {
+  /** Scene id to its declaration, filled in `onStart` from `flow.features`. */scenes: Map<string, SceneDefinition>; /** Id of the scene that is mounted now. */
+  current: string | undefined; /** Fast mode: the scene a transit node named, applied at the next rest node. */
+  pending: string | undefined;
+  owner: SceneOwner; /** The remover of the `onEnter` callback: set in `onStart`, run in `onStop`. */
+  teardown: (() => void) | undefined;
+};
+/**
+ * scenes plugin events.
+ *
+ * @example
+ * ```ts
+ * // A game plugin starts the music of the scene the graph switched to.
+ * createPlugin("music", {
+ *   depends: [scenesPlugin],
+ *   hooks: ctx => ({ "scenes:changed": ({ music }) => ctx.log.info("scene music", { music }) })
+ * }); // entering the board logs { music: "board.theme" }
+ * ```
+ */
+type Events = {
+  /** The mounted scene changed. */"scenes:changed": {
+    from: string | undefined;
+    to: string;
+    music: string | undefined;
+  };
+};
+/**
+ * scenes plugin API, `app.scenes`. A scene is switched by the graph, never by a call, so the
+ * plugin answers one question and takes no orders.
+ *
+ * @example
+ * ```ts
+ * // A headless test walks from the menu onto the board and asks what is mounted.
+ * await app.flow.walk([{ at: "home", intent: "play" }]);
+ * app.scenes.current(); // "board"
+ * ```
+ */
+type ScenesApi = {
+  /**
+   * The id of the mounted scene.
+   *
+   * @returns The scene id, `undefined` before the first switch and after the app stopped.
+   * @example
+   * ```ts
+   * // A dev overlay writes the scene next to the frame counter.
+   * app.scenes.current(); // "board", or undefined while the first bundle still loads
+   * ```
+   */
+  current(): string | undefined;
+};
+/**
+ * Resolved dependency APIs.
+ */
+type Deps$1 = {
+  flow: Api;
+  world: Api$3;
+  assets: Api$4;
+  time: Api$1;
+};
+/**
+ * What the kernel context offers before the deps are attached.
+ *
+ * `index.ts` writes `events` with an annotated `register` (core spec `14-EVENT-REGISTRATION.md`
+ * row 8), so the own event reaches the context the kernel hands the factories and `emit` is the
+ * kernel's own, scenes-typed one. No member of the context is cast.
+ */
+type KernelSlice$1 = PluginCtx<Config$1, State$1, Events> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+  readonly require: Require;
+};
+/**
+ * Domain context shared by the files of the plugin.
+ */
+type ScenesCtx = KernelSlice$1 & {
+  readonly deps: Deps$1;
+};
+/**
+ * The mode and the abort signal `flow.onEnter` hands every callback.
+ *
+ * @example
+ * ```ts
+ * const run: RunContext = { mode: "live", signal: new AbortController().signal };
+ * ```
+ */
+type RunContext = {
+  mode: "live" | "fast";
+  signal: AbortSignal;
+};
+declare namespace types_d_exports {
+  export { AudioApi, AudioContextLike, AudioCtx, BundleUnloaded, Bus, BusState, Config, Deps, KernelSlice, LifecycleChanged, ModelCommitted, MusicDescriptor, MusicOptions, MusicRequest, MusicSwitch, MusicTrack, SceneChanged, SfxRequest, SoundEntry, State, Volumes };
+}
+/**
+ * The three volume buses. `master` carries the whole game, `music` the scene track, `sfx` every
+ * sound a node or a timeline fires.
+ *
+ * @example
+ * ```ts
+ * const bus: Bus = "music";
+ * ```
+ */
+type Bus = "master" | "music" | "sfx";
+/**
+ * The part of `AudioContext` the plugin uses. A test passes its own through `config.context`, so
+ * nothing in the unit tests touches a sound card. `state` adds Safari's `"interrupted"`, which a
+ * phone call or the lock screen puts a context into.
+ *
+ * @example
+ * ```ts
+ * // A dev tool builds the engine's context itself and hands it to the plugin.
+ * const context: AudioContextLike = new AudioContext();
+ * createApp({ plugins: [...screen, audioPlugin], pluginConfigs: { audio: { context: () => context } } });
+ * ```
+ */
+type AudioContextLike = Pick<AudioContext, "destination" | "currentTime" | "createGain" | "createBufferSource" | "decodeAudioData" | "resume" | "close"> & {
+  readonly state: AudioContext["state"] | "interrupted";
+};
+/**
+ * What `music` accepts besides the key. An absent `fadeMs` means `config.musicFadeMs` at play time.
+ *
+ * @example
+ * ```ts
+ * const options: MusicOptions = { fadeMs: 200 };
+ * ```
+ */
+type MusicOptions = {
+  fadeMs?: number;
+};
+/**
+ * `music` bound to the audio asset keys of one game. `defineGame` returns it through `audioFor`;
+ * the loose export accepts any string.
+ *
+ * @example
+ * ```ts
+ * const gameMusic: MusicDescriptor<"board.theme"> = music;
+ * ```
+ */
+type MusicDescriptor<Asset extends string> = (key: Asset | null, options?: MusicOptions) => Descriptor;
+/**
+ * Reads the player's volume choice out of the committed player state. Every bus it names is
+ * applied; the ones it leaves out keep the value they had.
+ *
+ * @example
+ * ```ts
+ * const volumes: Volumes = player => (player as { settings: { audio: { music: number } } }).settings.audio;
+ * ```
+ */
+type Volumes = (player: Json) => Partial<Record<Bus, number>>;
+/**
+ * audio plugin config.
+ *
+ * @example
+ * ```ts
+ * createApp({
+ *   plugins: [...screen, audioPlugin],
+ *   pluginConfigs: { audio: { musicFadeMs: 400, volumes: player => player.settings.audio } }
+ * });
+ * ```
+ */
+type Config = {
+  /** Start gain of each bus, 0..1. Overridden per commit when `volumes` is set. */buses: {
+    master: number;
+    music: number;
+    sfx: number;
+  }; /** Cross-fade of a music switch, in real milliseconds of the context clock. */
+  musicFadeMs: number; /** Reads the player's choice from the committed player. `undefined`: the buses stay at `buses`. */
+  volumes: Volumes | undefined; /** Context factory, the test seam. `undefined`: `new AudioContext()` when the global exists, otherwise headless. */
+  context: (() => AudioContextLike) | undefined; /** How many started sounds `journal()` keeps, newest last. `0` turns the journal off. */
+  journal: number;
+};
+/**
+ * One sound that started: a play of an `sfx` or a music track that began. `at` is the elapsed
+ * game time in milliseconds, `app.time.snapshot().elapsed` at the start.
+ *
+ * @example
+ * ```ts
+ * const entry: SoundEntry = { key: "ui.click", bus: "sfx", kind: "sfx", at: 1600 };
+ * ```
+ */
+type SoundEntry = {
+  readonly key: string;
+  readonly bus: Bus;
+  readonly kind: "sfx" | "music";
+  readonly at: number;
+};
+/**
+ * What the plugin keeps for one bus: its gain node while a context exists, the volume a game or
+ * the player chose, and whether it is muted.
+ *
+ * @example
+ * ```ts
+ * const entry: BusState = { gain: undefined, volume: 0.6, muted: false };
+ * ```
+ */
+type BusState = {
+  gain: GainNode | undefined;
+  volume: number;
+  muted: boolean;
+};
+/**
+ * The music that is playing, or the key remembered until the first touch unlocks the context.
+ * `source` and `gain` are `undefined` exactly while the track is only remembered.
+ *
+ * @example
+ * ```ts
+ * const track: MusicTrack = { key: "board.theme", source: undefined, gain: undefined };
+ * ```
+ */
+type MusicTrack = {
+  key: string;
+  source: AudioBufferSourceNode | undefined;
+  gain: GainNode | undefined;
+};
+/**
+ * A music switch that waits for its buffer to decode. Its identity is the token: a later request
+ * replaces it, and the replaced switch neither starts nor fades anything when its buffer arrives.
+ *
+ * @example
+ * ```ts
+ * const waiting: MusicSwitch = { key: "ui.theme" };
+ * ```
+ */
+type MusicSwitch = {
+  key: string;
+};
+/**
+ * audio plugin state.
+ */
+type State = {
+  /** `undefined` means headless: no graph, no sound, every member still keeps its value. */context: AudioContextLike | undefined;
+  buses: Record<Bus, BusState>; /** A lifecycle push is in force: every bus is held at zero. */
+  paused: boolean;
+  unlocked: boolean; /** A gesture called `resume()` and it has not settled yet. */
+  resuming: boolean; /** Sounds fired while `resuming`, one per key; played when the context runs, dropped when it does not. */
+  pendingSfx: Map<string, SfxRequest>; /** Per key, evicted per key on `assets:bundle-unloaded`. */
+  decoded: Map<string, Promise<AudioBuffer>>; /** Asset keys that already got their one warning. */
+  warned: Set<string>; /** `config.volumes` threw once and was reported; it is not reported again this run. */
+  warnedVolumes: boolean;
+  music: MusicTrack | undefined; /** The latest switch still decoding; `undefined` once it started or a later request replaced it. */
+  musicPending: MusicSwitch | undefined; /** Removes the two window listeners of the unlock. */
+  unlock: (() => void) | undefined; /** The removers of the two fx handlers. */
+  removers: Array<() => void>;
+  /**
+   * The sounds that started, oldest first, at most `config.journal` of them. Frozen: a write
+   * replaces the whole list, so `journal()` hands it out without a copy.
+   */
+  journal: readonly SoundEntry[];
+};
+/**
+ * audio plugin API, `app.audio`. Three buses and the unlock flag: what a game changes about sound
+ * it commits to the player state, which this plugin applies on the next commit.
+ *
+ * @example
+ * ```ts
+ * // A dev overlay pulls the music down and reads the value back.
+ * app.audio.setVolume("music", 0.2);
+ * app.audio.volume("music"); // 0.2
+ * ```
+ */
+type AudioApi = {
+  /**
+   * Sets the volume of one bus and schedules the new gain at once. The value is clamped to 0..1
+   * and `NaN` becomes 0. Nothing is persisted: a game stores the choice in the player state and
+   * lets `config.volumes` apply it, so the next commit overwrites what this call set.
+   *
+   * @param bus - The bus to change.
+   * @param value - The new volume, 0..1.
+   * @throws {Error} When the bus does not exist.
+   * @example
+   * ```ts
+   * // A test turns the music off before it walks the graph, so nothing rings.
+   * app.audio.setVolume("music", 0);
+   * app.audio.volume("music"); // 0
+   * ```
+   */
+  setVolume(bus: Bus, value: number): void;
+  /**
+   * The stored volume of a bus, never the live gain: a muted or paused bus still answers the
+   * value the player chose.
+   *
+   * @param bus - The bus to read.
+   * @returns The stored volume, 0..1.
+   * @throws {Error} When the bus does not exist.
+   * @example
+   * ```ts
+   * // The settings screen draws the slider of the sfx bus at its stored place.
+   * app.audio.mute("sfx", true);
+   * app.audio.volume("sfx"); // 1: muting does not move the slider
+   * ```
+   */
+  volume(bus: Bus): number;
+  /**
+   * Mutes or unmutes one bus. The flag is independent of the pause: a bus muted here stays muted
+   * when the game comes back from the background.
+   *
+   * @param bus - The bus to change.
+   * @param on - `true` mutes it, `false` lets it play again.
+   * @throws {Error} When the bus does not exist.
+   * @example
+   * ```ts
+   * // A dev overlay silences the whole game while a profiler trace runs.
+   * app.audio.mute("master", true);
+   * app.audio.volume("master"); // 1, and nothing is heard
+   * ```
+   */
+  mute(bus: Bus, on: boolean): void;
+  /**
+   * Tells whether the browser let the audio context run. It is false until the first pointer
+   * event on the page resumed it, and false for the whole of a headless run.
+   *
+   * @returns True once the context is running.
+   * @example
+   * ```ts
+   * // A "tap to start" screen stays up until the browser allowed sound.
+   * app.audio.unlocked(); // false before the first touch, true after it
+   * ```
+   */
+  unlocked(): boolean;
+  /**
+   * The sounds that started, oldest first: every play of an `sfx` and every music track that
+   * began, at most `config.journal` of them. A sound dropped before the unlock, a missing file
+   * and a music switch to the track that already plays are not in it. Empty while
+   * `config.journal` is 0, the default, and after the app stopped.
+   *
+   * @returns The journal, frozen; a later sound replaces the list and leaves this one as it was.
+   * @example
+   * ```ts
+   * // A test composed with `pluginConfigs.audio = { journal: 200 }` taps "deliver" after the
+   * // first touch and checks the chime was heard.
+   * app.audio.journal();
+   * // [{ key: "board.theme", bus: "music", kind: "music", at: 0 },
+   * //  { key: "orders.complete", bus: "sfx", kind: "sfx", at: 1600 }]
+   * ```
+   */
+  journal(): readonly SoundEntry[];
+};
+/**
+ * Resolved dependency APIs.
+ */
+type Deps = {
+  flow: Api;
+  assets: Api$4;
+  model: Api$2;
+  time: Api$1;
+};
+/**
+ * What the kernel context offers before the deps are attached.
+ *
+ * `audio` owns no event, so `emit` is the kernel's and never called here.
+ */
+type KernelSlice = PluginCtx<Config, State> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+  readonly require: Require;
+};
+/**
+ * Domain context shared by the files of the plugin: the kernel slice plus the resolved deps.
+ */
+type AudioCtx = KernelSlice & {
+  readonly deps: Deps;
+};
+/**
+ * Payload of the `model:committed` hook: the source of every volume a game sets.
+ */
+type ModelCommitted = Events$1["model:committed"];
+/**
+ * Payload of the `scenes:changed` hook: `music` is the track the next scene declared.
+ */
+type SceneChanged = Events["scenes:changed"];
+/**
+ * Payload of the `lifecycle:changed` hook: the pause that holds every bus at zero.
+ */
+type LifecycleChanged = Events$2["lifecycle:changed"];
+/**
+ * Payload of the `assets:bundle-unloaded` hook: `keys` names every decoded sound that is gone.
+ */
+type BundleUnloaded = Events$3["assets:bundle-unloaded"];
+/**
+ * What one play of a sound asks for: the key and the bus the sound goes to.
+ */
+type SfxRequest = {
+  key: string;
+  bus: string;
+};
+/**
+ * What one music switch asks for: the key, or `null` to fade the current track out.
+ */
+type MusicRequest = {
+  key: string | null;
+  fadeMs: number;
+};
+//#endregion
+export { SoundEntry as a, AnySceneProjection as c, SceneDefinition as d, SceneSpec as f, types_d_exports$1 as h, MusicOptions as i, DefineScene as l, State$1 as m, Config as n, State as o, ScenesApi as p, MusicDescriptor as r, types_d_exports as s, AudioApi as t, LayerMap as u };