@moku-labs/game 0.4.2 → 0.4.4

package/dist/{types-CVUHPvMB.d.mts → types-C-4f2jD_.d.mts}

@@ -1,4 +1,4 @@
-import { $ as Ease, I as AnyComponentValue, Kt as Json, L as ComponentHandle, Nt as TypeTag, P as AnyComponent, Rt as Api, V as Entity, ct as TrackSegment, it as NumericFields, k as Api$2, m as Api$3, rt as MotionHandle, st as TrackOptions, ut as Api$1, vn as Require, z as ComponentType } from "./types-Dy1xB68L.mjs";
+import { $ as Ease, Gt as Events$2, I as AnyComponentValue, K as Owner, Kt as Json, L as ComponentHandle, Nt as TypeTag, P as AnyComponent, Pt as Descriptor, Rt as Api, Ut as Api$5, V as Entity, ct as TrackSegment, et as LayerSort, it as NumericFields, k as Api$2, m as Api$3, o as Events$4, rt as MotionHandle, sn as Events$3, st as TrackOptions, t as Api$4, tt as LayerSpec, ut as Api$1, vn as Require, z as ComponentType } from "./types-Dy1xB68L.mjs";
 import { D as TextApi, H as InputApi, I as I18nApi, c as UiNode, i as Finding, n as ElementChange, o as JsxState, r as ElementMotion, v as StylesState } from "./types-VErbiEXy.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
@@ -22,8 +22,8 @@ type LayoutState = {
   order: number;
   cleanups: Array<() => void>;
 };
-declare namespace types_d_exports$1 {
-  export { Config$1 as Config, Deps$1 as Deps, ElementChange, ElementMotion, Finding, FocusRing, KernelSlice$1 as KernelSlice, State$1 as State, TextInputLook, UiApi, UiCtx, UiNode };
+declare namespace types_d_exports$3 {
+  export { Config$3 as Config, Deps$3 as Deps, ElementChange, ElementMotion, Finding, FocusRing, KernelSlice$3 as KernelSlice, State$3 as State, TextInputLook, UiApi, UiCtx, UiNode };
 }
 /**
  * The look of the keyboard focus ring: a dashed ring with a solid halo under it, drawn around the
@@ -96,7 +96,7 @@ type TextInputLook = {
  * });
  * ```
  */
-type Config$1 = {
+type Config$3 = {
   /** Smallest tap target `lint()` accepts, in CSS px (points). */tapTargetPt: number; /** `when` flags: `tall` when height / width is at least `tall`, `wide` the other way round. */
   breakpoints: {
     tall: number;
@@ -116,7 +116,7 @@ type Config$1 = {
 /**
  * ui plugin state: one branch per module.
  */
-type State$1 = {
+type State$3 = {
   jsx: JsxState;
   styles: StylesState;
   layout: LayoutState;
@@ -125,7 +125,7 @@ type State$1 = {
  * Resolved dependency APIs. `anim` is not here: its edge is validation only, and its work
  * reaches `ui` through the tween driver behind every `ViewHandle`.
  */
-type Deps$1 = {
+type Deps$3 = {
   time: Api;
   flow: Api$1;
   world: Api$2;
@@ -139,7 +139,7 @@ type Deps$1 = {
  *
  * `ui` owns no event, so `emit` is the kernel's and never called here.
  */
-type KernelSlice$1 = PluginCtx<Config$1, State$1> & {
+type KernelSlice$3 = PluginCtx<Config$3, State$3> & {
   readonly global: object;
   readonly log: Log.LogApi;
   readonly require: Require;
@@ -147,8 +147,8 @@ type KernelSlice$1 = PluginCtx<Config$1, State$1> & {
 /**
  * Domain context shared by the three modules: the kernel slice plus the resolved deps.
  */
-type UiCtx = KernelSlice$1 & {
-  readonly deps: Deps$1;
+type UiCtx = KernelSlice$3 & {
+  readonly deps: Deps$3;
 };
 /**
  * ui plugin API, `app.ui`. The screen is one more projection, so three members read it the way a
@@ -865,8 +865,8 @@ type RunningTimeline = {
   readonly resolve: () => void;
   ended: boolean;
 };
-declare namespace types_d_exports {
-  export { AnimApi, AnimCtx, AnimationDefinition, AnimationSpec, AnyAnimationDefinition, BuildTools, Config, Cursor, Deps, ErasedFields, Events, ExternalPlayer, FrameLoop, FramesValue, FxStep, HapticDescriptor, HapticKind, KernelSlice, MarkListener, MotionKeyframe, PlayDescriptor, PlayHandle, Pose, RunningTimeline, SfxDescriptor, SlotRecord, SlotTags, SlotValue, SlotValues, State, Step, StepMotion, Target, TimelineRuntime, Track };
+declare namespace types_d_exports$2 {
+  export { AnimApi, AnimCtx, AnimationDefinition, AnimationSpec, AnyAnimationDefinition, BuildTools, Config$2 as Config, Cursor, Deps$2 as Deps, ErasedFields, Events$1 as Events, ExternalPlayer, FrameLoop, FramesValue, FxStep, HapticDescriptor, HapticKind, KernelSlice$2 as KernelSlice, MarkListener, MotionKeyframe, PlayDescriptor, PlayHandle, Pose, RunningTimeline, SfxDescriptor, SlotRecord, SlotTags, SlotValue, SlotValues, State$2 as State, Step, StepMotion, Target, TimelineRuntime, Track };
 }
 /**
  * What a step and a slot are pointed at: the projection key of a live view or of an element a
@@ -1034,7 +1034,7 @@ type MarkListener = (animation: string, mark: string) => void;
  * }); // a reached mark("done") step logs { mark: "done" }
  * ```
  */
-type Events = {
+type Events$1 = {
   /** A `mark` step was reached, or jumped by `finish()`. */"anim:mark": {
     animation: string;
     mark: string;
@@ -1118,7 +1118,7 @@ type FrameLoop = {
  * createApp({ plugins: [...screen], pluginConfigs: { anim: { maxTracks: 500, reducedMotion: true } } });
  * ```
  */
-type Config = {
+type Config$2 = {
   /** Dev guard: one warning each time the running track count rises past this number. */maxTracks: number;
   /**
    * Start value of reduced motion: every track but a loop takes 0 ms and every loop stands on
@@ -1130,7 +1130,7 @@ type Config = {
  * anim plugin state: the one track table, the field bookkeeping of the retarget policy and the
  * offsets accumulator, the running timelines and the animation registry.
  */
-type State = {
+type State$2 = {
   /** The one track table. Insertion order is advance order. */tracks: Map<number, Track>; /** Ids of tracks and timelines. */
   nextId: number; /** `"<entity>:<component>:<field>"` to the id of the absolute track that drives the field. */
   owner: Map<string, number>; /** Per field key, the delta each additive track contributes. */
@@ -1278,7 +1278,7 @@ type AnimApi = {
  * of `at` with the pure `rootPoseOf` of `renderer/sync/pose.ts`, and turns the target of a
  * `tween` in `space: "root"` local with the pure `localPoseOf` of the same module.
  */
-type Deps = {
+type Deps$2 = {
   time: Api;
   flow: Api$1;
   world: Api$2;
@@ -1290,7 +1290,7 @@ type Deps = {
  * row 8), so the own events reach the context the kernel hands the factories and `emit` is the
  * kernel's own, anim-typed one. No member of the context is cast.
  */
-type KernelSlice = PluginCtx<Config, State, Events> & {
+type KernelSlice$2 = PluginCtx<Config$2, State$2, Events$1> & {
   readonly global: object;
   readonly log: Log.LogApi;
   readonly require: Require;
@@ -1298,8 +1298,659 @@ type KernelSlice = PluginCtx<Config, State, Events> & {
 /**
  * Domain context of the anim plugin: the kernel slice and the three resolved dependencies.
  */
-type AnimCtx = KernelSlice & {
+type AnimCtx = KernelSlice$2 & {
+  readonly deps: Deps$2;
+};
+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$1;
+  world: Api$2;
+  assets: Api$4;
+  time: Api;
+};
+/**
+ * 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, AudioSessionLike, AudioSessionType, BundleUnloaded, Bus, BusState, Config, Deps, KernelSlice, LifecycleChanged, ModelCommitted, MusicDescriptor, MusicMode, MusicOptions, MusicRequest, MusicSwitch, MusicTrack, RetiringTrack, SceneChanged, SfxRequest, SoundEntry, State, StreamTrack, 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" | "createMediaElementSource" | "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>>;
+/**
+ * How a music track is played. `"decode"`: one AudioBuffer per track, gapless, about 58 MB per
+ * 150 s at 48 kHz. `"stream"`: an `<audio>` element on a `blob:` URL of the bytes `assets` holds,
+ * about 12 MB, and a gap at every loop: 5 to 49 ms in Chromium, about 0.4 s in WebKit. A tight
+ * loop keeps `"decode"`; a long track that tolerates a seam takes `"stream"`.
+ *
+ * @example
+ * ```ts
+ * const mode: MusicMode = "stream";
+ * ```
+ */
+type MusicMode = "decode" | "stream";
+/**
+ * What the page asks iOS for. `"ambient"`: mixes with other apps, the silent switch mutes it.
+ * `"playback"`: stops other apps, plays through the switch. `"auto"`: WebKit picks.
+ *
+ * @example
+ * ```ts
+ * const session: AudioSessionType = "playback";
+ * ```
+ */
+type AudioSessionType = "ambient" | "playback" | "auto";
+/**
+ * The part of `navigator.audioSession` the plugin writes. `lib.dom` has no type for it, and only
+ * WebKit has the object at all.
+ *
+ * @example
+ * ```ts
+ * // What Safari answers before the plugin started: no override.
+ * const session: AudioSessionLike = { type: "auto" };
+ * ```
+ */
+type AudioSessionLike = {
+  type: string;
+};
+/**
+ * One music track played by an element at `music: "stream"`: the element, its source node in the
+ * graph, the track gain every level goes through, and the `blob:` URL the element reads.
+ *
+ * @example
+ * ```ts
+ * // `state.music.stream` once "board.theme" plays at `music: "stream"`.
+ * const { element, url }: StreamTrack = track;
+ * element.loop; // true
+ * url.startsWith("blob:"); // true
+ * ```
+ */
+type StreamTrack = {
+  element: HTMLAudioElement;
+  node: MediaElementAudioSourceNode;
+  gain: GainNode;
+  url: string;
+};
+/**
+ * A streamed track that fades out. Its timer frees the element when the fade ends: an element has
+ * no `stop(when)` on the context clock.
+ *
+ * @example
+ * ```ts
+ * // A switch at `musicFadeMs: 600` keeps the old track here for 600 ms.
+ * const entry: RetiringTrack = { stream: oldTrack, timer: setTimeout(free, 600) };
+ * ```
+ */
+type RetiringTrack = {
+  stream: StreamTrack;
+  timer: ReturnType<typeof setTimeout>;
+};
+/**
+ * audio plugin config.
+ *
+ * @example
+ * ```ts
+ * createApp({
+ *   plugins: [...screen, audioPlugin],
+ *   pluginConfigs: {
+ *     audio: { musicFadeMs: 400, music: "stream", session: "playback", 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; /** How music plays. `"stream"` needs MP3 or AAC: WebM Opus is silent through a media element in WebKit (bug 276813). Sounds always decode. */
+  music: MusicMode; /** Set on `navigator.audioSession.type` in `onStart`, before the context exists. No-op where the API is missing (every Chromium, Firefox). */
+  session: AudioSessionType;
+};
+/**
+ * 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` plays a decoded track, `stream` a streamed one; they are never both set. Both
+ * `undefined`: the key is only remembered (a locked context, or a refused `play()`).
+ *
+ * @example
+ * ```ts
+ * const track: MusicTrack = { key: "board.theme", gain: undefined, source: undefined, stream: undefined };
+ * ```
+ */
+type MusicTrack = {
+  key: string;
+  gain: GainNode | undefined;
+  source: AudioBufferSourceNode | undefined;
+  stream: StreamTrack | 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 `navigator.audioSession` that took `config.session`; `stop` writes `"auto"` back to it. */
+  session: AudioSessionLike | undefined; /** Streamed tracks that fade out, each freed by its timer. */
+  retiring: Set<RetiringTrack>;
+  /**
+   * 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 one bus is muted: the stored flag `mute` wrote. A pause does not change it, and
+   * a headless run answers it too.
+   *
+   * @param bus - The bus to read.
+   * @returns True while the bus is muted.
+   * @throws {Error} When the bus does not exist.
+   * @example
+   * ```ts
+   * // The settings screen draws the Sound switch off after the player muted the game.
+   * app.audio.mute("master", true);
+   * app.audio.muted("master"); // true
+   * ```
+   */
+  muted(bus: Bus): boolean;
+  /**
+   * 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$1;
+  assets: Api$4;
+  model: Api$5;
+  time: Api;
+};
+/**
+ * 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$2["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$3["lifecycle:changed"];
+/**
+ * Payload of the `assets:bundle-unloaded` hook: `keys` names every decoded sound that is gone.
+ */
+type BundleUnloaded = Events$4["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 { UiApi as A, spawned as C, wait as D, use as E, Config$1 as O, spawn as S, tween as T, parallel as _, State as a, set as b, HapticKind as c, HAPTIC_KINDS as d, defineAnimation as f, mark as g, haptic as h, MotionKeyframe as i, types_d_exports$1 as j, State$1 as k, SfxDescriptor as l, frames as m, Config as n, Target as o, external as p, FramesValue as r, types_d_exports as s, AnimApi as t, Step as u, play as v, stagger as w, sfx as x, sequence as y };
+export { haptic as A, tween as B, HapticKind as C, defineAnimation as D, HAPTIC_KINDS as E, set as F, UiApi as G, wait as H, sfx as I, types_d_exports$3 as K, spawn as L, parallel as M, play as N, external as O, sequence as P, spawned as R, types_d_exports$2 as S, Step as T, Config$3 as U, use as V, State$3 as W, Config$2 as _, SoundEntry as a, State$2 as b, AnySceneProjection as c, SceneDefinition as d, SceneSpec as f, AnimApi as g, types_d_exports$1 as h, MusicOptions as i, mark as j, frames as k, 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, FramesValue as v, SfxDescriptor as w, Target as x, MotionKeyframe as y, stagger as z };