@moku-labs/game 0.0.2 → 0.0.3

package/dist/types-BTycq8_Z.d.mts

@@ -0,0 +1,1196 @@
+import { At as Json, C as LayerSpec, Dt as Api$4, F as ComponentHandle, Gt as Events$2, H as Owner, I as ComponentType, R as Entity, S as LayerSort, St as Api$3, a as PixiSprite, d as FilterSlot, h as Api$1, i as PixiModule, kt as Events$1, nn as Require, o as PixiTexture, p as Point, q as Api, r as PixiFilter, t as Api$2, vt as Descriptor } from "./types-Cjf3ywai.mjs";
+import { o as Events$3, t as Api$5 } from "./types-DgwbzDLP.mjs";
+import { t as AnimApi } from "./types-KlE_GL1z.mjs";
+import { Log } from "@moku-labs/common/browser";
+import { PluginCtx } from "@moku-labs/core";
+
+//#region src/plugins/effects/filters/types.d.ts
+/**
+ * One uniform of a custom filter, as declared: a number is an `f32`, `{ color }` a `0xrrggbb`
+ * hex sent as a `vec3<f32>`, a tuple of 2 to 4 numbers a `vecN<f32>`.
+ *
+ * @example
+ * ```ts
+ * const uniforms: Record<string, UniformDeclaration> = { amount: 0.5, color: { color: 0xffd700 }, offset: [2, 2] };
+ * ```
+ */
+type UniformDeclaration = number | {
+  readonly color: number;
+} | readonly [number, number] | readonly [number, number, number] | readonly [number, number, number, number];
+/**
+ * The component field a uniform declaration becomes: a number for a number and for a colour, a
+ * list of numbers for a tuple.
+ *
+ * @example
+ * ```ts
+ * type Amount = UniformValue<0.5>; // number
+ * ```
+ */
+type UniformValue<Declaration> = Declaration extends number ? number : Declaration extends {
+  readonly color: number;
+} ? number : readonly number[];
+/**
+ * The value of a filter component made by `defineFilter`: one field per uniform, then `enabled`
+ * and `order`.
+ *
+ * @example
+ * ```ts
+ * type TintValue = FilterValueOf<{ amount: number; color: { color: number } }>;
+ * // { amount: number; color: number; enabled: boolean; order: number }
+ * ```
+ */
+type FilterValueOf<Uniforms extends Record<string, UniformDeclaration>> = { -readonly [Name in keyof Uniforms]: UniformValue<Uniforms[Name]> } & {
+  enabled: boolean;
+  order: number;
+};
+/**
+ * What `defineFilter` takes besides the id. `wgsl` is the fragment body only; the engine
+ * prepends the vertex stage, the input bindings and the `FilterUniforms` struct.
+ *
+ * @example
+ * ```ts
+ * const spec: FilterSpec<{ amount: number }> = {
+ *   wgsl: "@fragment fn mainFragment(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> { return textureSample(uTexture, uSampler, uv) * fu.amount; }",
+ *   uniforms: { amount: 1 }
+ * };
+ * ```
+ */
+type FilterSpec<Uniforms extends Record<string, UniformDeclaration>> = {
+  /** The fragment body: `fn mainFragment` and its helpers, without the engine's header. */readonly wgsl: string; /** The uniforms in struct order. Default `{}`. */
+  readonly uniforms?: Uniforms; /** Render passes one apply of the filter costs, an integer of at least 1. Default `1`. */
+  readonly passes?: number; /** Pixels around the view's bounds, or the name of a number uniform whose live value they are. Default `0`. */
+  readonly padding?: number | string;
+};
+/**
+ * How one uniform travels to the GPU: its name, its WGSL type and the form it was declared in.
+ *
+ * @example
+ * ```ts
+ * const spec: UniformSpec = { name: "color", type: "vec3<f32>", form: "color", size: 3 };
+ * ```
+ */
+type UniformSpec = {
+  readonly name: string;
+  readonly type: "f32" | "vec2<f32>" | "vec3<f32>" | "vec4<f32>";
+  readonly form: "number" | "color" | "vector";
+  readonly size: number;
+};
+/**
+ * The filter a component made by `defineFilter` carries: the assembled WGSL, the uniforms in
+ * struct order, the passes one apply costs and the padding.
+ *
+ * @example
+ * ```ts
+ * Tint.filter.passes; // 1
+ * Tint.filter.uniforms.map(uniform => uniform.name); // ["amount", "color"]
+ * ```
+ */
+type FilterDefinition = {
+  readonly id: string;
+  readonly source: string;
+  readonly uniforms: readonly UniformSpec[];
+  readonly passes: number;
+  readonly padding: number | string;
+};
+/**
+ * A filter component type: the `component()` of its id, with the filter definition attached. Its
+ * numeric fields are tweenable like any component.
+ *
+ * @example
+ * ```ts
+ * const Tint: FilterComponent<{ amount: number; enabled: boolean; order: number }> =
+ *   defineFilter("fx.tint", { wgsl: tintBody, uniforms: { amount: 0 } });
+ * Tint.componentName; // "fx.tint"
+ * ```
+ */
+type FilterComponent<Value extends object> = ComponentType<Value> & {
+  readonly filter: FilterDefinition;
+};
+/**
+ * One field of a stored filter value: a number, a switch, an asset key or a vector.
+ *
+ * @example
+ * ```ts
+ * const field: FilterField = 0.5;
+ * ```
+ */
+type FilterField = number | boolean | string | readonly number[];
+/**
+ * The stored value of any filter component, with the kind erased: the filter sync reads every
+ * kind through it.
+ */
+type FilterFields = {
+  readonly enabled: boolean;
+  readonly order: number;
+  readonly [field: string]: FilterField;
+};
+/**
+ * `Glow`: a soft halo of `color` around the opaque pixels of the view.
+ *
+ * @example
+ * ```ts
+ * const value: GlowValue = { strength: 2, distance: 10, color: 0xffffff, alpha: 1, enabled: true, order: 0 };
+ * ```
+ */
+type GlowValue = {
+  strength: number;
+  distance: number;
+  color: number;
+  alpha: number;
+  enabled: boolean;
+  order: number;
+};
+/**
+ * `Outline`: a ring of `thickness` pixels in `color` around the opaque pixels of the view.
+ *
+ * @example
+ * ```ts
+ * const value: OutlineValue = { thickness: 2, color: 0x000000, alpha: 1, enabled: true, order: 0 };
+ * ```
+ */
+type OutlineValue = {
+  thickness: number;
+  color: number;
+  alpha: number;
+  enabled: boolean;
+  order: number;
+};
+/**
+ * `Blur`: Pixi's blur. `quality: 0` means `config.blur.quality`; `resolution: 0` means
+ * `config.blur.phoneResolution` on a phone, otherwise 1.
+ *
+ * @example
+ * ```ts
+ * const value: BlurValue = { strength: 8, quality: 0, resolution: 0, repeatEdgePixels: true, enabled: true, order: 0 };
+ * ```
+ */
+type BlurValue = {
+  strength: number;
+  quality: number;
+  resolution: number;
+  repeatEdgePixels: boolean;
+  enabled: boolean;
+  order: number;
+};
+/**
+ * `ColorMatrix`: brightness, saturation, contrast, hue and grayscale composed in that order.
+ * Every default is the identity.
+ *
+ * @example
+ * ```ts
+ * const value: ColorMatrixValue = { brightness: 1, saturation: 0, contrast: 0, hue: 0, grayscale: 1, enabled: true, order: 0 };
+ * ```
+ */
+type ColorMatrixValue = {
+  brightness: number;
+  saturation: number;
+  contrast: number;
+  hue: number;
+  grayscale: number;
+  enabled: boolean;
+  order: number;
+};
+/**
+ * `Noise`: Pixi's noise with its seed always given, so two runs draw the same grain.
+ *
+ * @example
+ * ```ts
+ * const value: NoiseValue = { amount: 0.5, seed: 7, enabled: true, order: 0 };
+ * ```
+ */
+type NoiseValue = {
+  amount: number;
+  seed: number;
+  enabled: boolean;
+  order: number;
+};
+/**
+ * `Displacement`: Pixi's displacement over the texture of an asset key.
+ *
+ * @example
+ * ```ts
+ * const value: DisplacementValue = { map: "fx.ripple", scaleX: 20, scaleY: 20, enabled: true, order: 0 };
+ * ```
+ */
+type DisplacementValue = {
+  map: string;
+  scaleX: number;
+  scaleY: number;
+  enabled: boolean;
+  order: number;
+};
+/**
+ * `Alpha`: Pixi's alpha over the whole subtree, as one layer.
+ *
+ * @example
+ * ```ts
+ * const value: AlphaValue = { alpha: 0.5, enabled: true, order: 0 };
+ * ```
+ */
+type AlphaValue = {
+  alpha: number;
+  enabled: boolean;
+  order: number;
+};
+/**
+ * The five built-in kinds drawn by a Pixi core filter.
+ *
+ * @example
+ * ```ts
+ * const kind: CoreKind = "blur";
+ * ```
+ */
+type CoreKind = "blur" | "colorMatrix" | "noise" | "displacement" | "alpha";
+/**
+ * Where a filter kind comes from: our or a game's WGSL, or a Pixi core filter.
+ */
+type KindSource = {
+  readonly source: "wgsl";
+  readonly definition: FilterDefinition;
+} | {
+  readonly source: "core";
+  readonly core: CoreKind;
+};
+/**
+ * A filter kind before it is registered: its id, its component and its source.
+ */
+type KindEntry = KindSource & {
+  readonly id: string;
+  readonly component: ComponentHandle<FilterFields>;
+};
+/**
+ * One registered filter kind. `index` is the registration order: the built-ins first, then the
+ * filters of every feature in feature order.
+ */
+type FilterKind = KindEntry & {
+  readonly index: number;
+};
+/**
+ * The values of the uniform group of one of our filter instances: a number per `f32`, a vector
+ * per colour and tuple. Written every frame.
+ */
+type UniformValues = Record<string, number | Float32Array>;
+/**
+ * The uniform group of one of our filter instances, as the instance writes it.
+ */
+type FilterUniforms = {
+  readonly uniforms: UniformValues;
+};
+/**
+ * The Pixi object of one kind on one view, with the passes one apply of it costs now: what the
+ * builders of `instance.ts` make before the instance gets its sort keys.
+ */
+type FilterBody = {
+  readonly kind: "wgsl";
+  readonly filter: PixiFilter;
+  readonly group: FilterUniforms | undefined;
+  readonly definition: FilterDefinition;
+  passes: number;
+} | {
+  readonly kind: "blur";
+  readonly filter: InstanceType<PixiModule["BlurFilter"]>;
+  passes: number;
+} | {
+  readonly kind: "colorMatrix";
+  readonly filter: InstanceType<PixiModule["ColorMatrixFilter"]>;
+  passes: number;
+} | {
+  readonly kind: "noise";
+  readonly filter: InstanceType<PixiModule["NoiseFilter"]>;
+  passes: number;
+} | {
+  readonly kind: "displacement";
+  readonly filter: InstanceType<PixiModule["DisplacementFilter"]>;
+  readonly sprite: PixiSprite; /** The asset key the map sprite shows now. */
+  map: string;
+  passes: number;
+} | {
+  readonly kind: "alpha";
+  readonly filter: InstanceType<PixiModule["AlphaFilter"]>;
+  passes: number;
+};
+/**
+ * The instance of one kind on one view: its Pixi object, and what it sorts by on the view, the
+ * `order` of its component (written every frame) and the `index` of its kind.
+ */
+type FilterInstance = FilterBody & {
+  order: number;
+  readonly index: number;
+};
+/**
+ * What the filter sync keeps for one entity: the kinds it carries, one instance per kind, the
+ * instances waiting to be destroyed after the next assignment, the slots last handed to
+ * `renderer.sync.filters.set`, the core kinds whose component changed this frame, and the
+ * instances of this frame in their sorted order (one array, reused every frame).
+ */
+type FilteredView = {
+  readonly kinds: Set<string>;
+  readonly instances: Map<string, FilterInstance>;
+  readonly retired: FilterInstance[];
+  assigned: readonly FilterSlot[];
+  readonly changed: Set<string>;
+  readonly placed: FilterInstance[];
+};
+//#endregion
+//#region src/plugins/effects/particles/types.d.ts
+/**
+ * An inclusive `[min, max]` range; every particle draws its own value from it.
+ *
+ * @example
+ * ```ts
+ * const lifeMs: Range = [500, 900];
+ * ```
+ */
+type Range = readonly [min: number, max: number];
+/**
+ * A value over the life of a particle, linear from its birth (`from`) to its death (`to`).
+ *
+ * @example
+ * ```ts
+ * const shrink: Curve = { from: 1, to: 0.2 };
+ * ```
+ */
+type Curve = {
+  readonly from: number;
+  readonly to: number;
+};
+/**
+ * Where a particle is born, around the origin of its emitter, in reference units. `circle` is
+ * uniform over the disc, `ring` uniform between `radius − width / 2` and `radius + width / 2`,
+ * `rect` uniform over the centred box.
+ *
+ * @example
+ * ```ts
+ * const burstRing: Shape = { kind: "ring", radius: 48, width: 16 };
+ * ```
+ */
+type Shape = {
+  readonly kind: "point";
+} | {
+  readonly kind: "circle";
+  readonly radius: number;
+} | {
+  readonly kind: "rect";
+  readonly w: number;
+  readonly h: number;
+} | {
+  readonly kind: "ring";
+  readonly radius: number;
+  readonly width: number;
+};
+/**
+ * A particle effect as data, what `defineEmitter` takes. Every field is optional except
+ * `textures` and exactly one of `burst` and `rate`. Speeds are reference units per second, angles
+ * degrees with 0 to the right and 90 down, spins radians per second.
+ *
+ * @example
+ * ```ts
+ * const stars: EmitterConfig = {
+ *   textures: ["fx.star", "fx.sparkle"], burst: 40, lifeMs: [500, 900], speed: [300, 700],
+ *   gravity: 900, drag: 0.2, shape: { kind: "circle", radius: 24 }, alpha: { from: 1, to: 0 }
+ * };
+ * ```
+ */
+type EmitterConfig = {
+  /** 1 to 16 asset keys of one atlas page; a particle picks one at random. */readonly textures: readonly string[]; /** Particles emitted once, when the component appears or its `effect` changes. */
+  readonly burst?: number; /** Particles per second while `active` is true and the entity lives. */
+  readonly rate?: number; /** Life of a particle in milliseconds. Default `[600, 1000]`. */
+  readonly lifeMs?: Range; /** Start speed in reference units per second. Default `[0, 0]`. */
+  readonly speed?: Range; /** Start direction in degrees, 0 right, 90 down. Default `[0, 360]`. */
+  readonly angle?: Range; /** Downward acceleration in reference units per second². Default `0`. */
+  readonly gravity?: number; /** Velocity lost per second, 0..1: `v *= (1 − drag) ^ seconds`. Default `0`. */
+  readonly drag?: number; /** Spin in radians per second. Default `[0, 0]`. */
+  readonly spin?: Range; /** Where particles are born around the origin. Default `{ kind: "point" }`. */
+  readonly shape?: Shape; /** Scale over life. Default `{ from: 1, to: 1 }`. */
+  readonly scale?: Curve; /** Alpha over life, 0..1. Default `{ from: 1, to: 1 }`. */
+  readonly alpha?: Curve; /** Tint over life, `0xrrggbb`, linear per channel. Default white to white. */
+  readonly tint?: Curve; /** `"world"`: particles outlive the entity. `"local"`: they move and die with it. Default `"world"`. */
+  readonly space?: "world" | "local"; /** Milliseconds simulated before the first frame, for streams, 0..5000. Default `0`. */
+  readonly prewarmMs?: number; /** Hard ceiling of live particles of one instance, 1..5000. Default `256`. */
+  readonly maxParticles?: number; /** Blend mode of the particle container. Default `"normal"`. */
+  readonly blend?: "normal" | "add";
+};
+/**
+ * An `EmitterConfig` with every default filled in. `burst` and `rate` stay as given: exactly one
+ * of them is present.
+ *
+ * @example
+ * ```ts
+ * defineEmitter("fx.steam", { textures: ["fx.puff"], rate: 12 }).config.lifeMs; // [600, 1000]
+ * ```
+ */
+type ResolvedEmitterConfig = Required<Omit<EmitterConfig, "burst" | "rate">> & Pick<EmitterConfig, "burst" | "rate">;
+/**
+ * A particle effect as `defineEmitter` returns it: frozen, registered through the `emitters` key
+ * of a feature and started by an `Emitter` component that names its id.
+ *
+ * @example
+ * ```ts
+ * const steam: EmitterDefinition = defineEmitter("fx.steam", { textures: ["fx.puff"], rate: 12 });
+ * steam.config.rate; // 12
+ * ```
+ */
+type EmitterDefinition = {
+  readonly id: string;
+  readonly config: ResolvedEmitterConfig;
+};
+/**
+ * The value of the `Emitter` component: which effect runs on the entity and whether a stream
+ * emits. `""` draws nothing.
+ *
+ * @example
+ * ```ts
+ * const value: EmitterValue = { effect: "fx.steam", active: true };
+ * ```
+ */
+type EmitterValue = {
+  effect: string;
+  active: boolean;
+};
+/**
+ * The cosmetic random source of one instance: xorshift32 over its own seed, never `Math.random`
+ * and never the model's rng.
+ */
+type Rng = {
+  /** The next number in `[0, 1)`. */next(): number; /** An integer in `[0, count)`. */
+  int(count: number): number; /** A number in `[min, max]`. */
+  between(min: number, max: number): number;
+};
+/**
+ * A Pixi particle container: what one emitter instance draws in.
+ */
+type PixiParticleContainer = InstanceType<PixiModule["ParticleContainer"]>;
+/**
+ * One particle of a container, as the container keeps it.
+ */
+type PixiParticle = PixiParticleContainer["particleChildren"][number];
+/**
+ * What one effect id bakes to on first use: the 64-entry curve tables, the reach rectangle's half
+ * side and the resolved textures. Dropped when a bundle with one of its textures leaves.
+ */
+type BakedEmitter = {
+  readonly id: string;
+  readonly config: ResolvedEmitterConfig; /** Scale per 1/64 of the life. */
+  readonly scaleTable: Float32Array; /** Alpha per 1/64 of the life, 0..1. */
+  readonly alphaTable: Float32Array; /** Tint per 1/64 of the life, packed as Pixi's `0xbbggrr`. */
+  readonly tintTable: Uint32Array; /** Half side of the box no particle leaves, in reference units. */
+  readonly reach: number;
+  readonly textures: readonly PixiTexture[]; /** The texture source of the first texture: every texture of the effect samples it. */
+  readonly source: PixiTexture["source"] | undefined; /** The largest side of the textures, in pixels. */
+  readonly maxSide: number;
+};
+/**
+ * The per-particle numbers a Pixi particle has no field for, one entry per live particle, in the
+ * order of `particleChildren`.
+ */
+type BornFields = {
+  readonly age: Float32Array;
+  readonly life: Float32Array;
+  readonly vx: Float32Array;
+  readonly vy: Float32Array;
+  readonly spin: Float32Array;
+  readonly variant: Float32Array;
+};
+/**
+ * One running effect: its container, the plugin-owned entity that carries it, the particle pool
+ * and the numbers the step needs.
+ */
+type EmitterInstance = {
+  readonly id: string;
+  readonly baked: BakedEmitter; /** The entity whose `Emitter` started it. */
+  readonly host: Entity; /** The plugin-owned entity whose `Display` is the container. */
+  readonly entity: Entity;
+  readonly container: PixiParticleContainer; /** Retired particles, reused before a new one is made. */
+  readonly pool: PixiParticle[];
+  readonly born: BornFields; /** Fraction of a particle owed to the next frame of a stream. */
+  carry: number;
+  readonly rng: Rng; /** The point the container was placed at, in root space (world space only). */
+  readonly origin: Readonly<Point>;
+  readonly space: "world" | "local"; /** Pixi's particle class, from the module the renderer loaded. */
+  readonly particleClass: PixiModule["Particle"];
+};
+declare namespace types_d_exports$2 {
+  export { AlphaValue, BlurValue, BundleUnloaded$1 as BundleUnloaded, ColorMatrixValue, Config$2 as Config, CoreKind, Curve, Deps$2 as Deps, DisplacementValue, EffectsApi, EffectsCtx, EffectsStats, EmitterConfig, EmitterDefinition, EmitterValue, FilterComponent, FilterDefinition, FilterSpec, FilterValueOf, GlowValue, KernelSlice$2 as KernelSlice, NoiseValue, OutlineValue, Range, ResolvedEmitterConfig, Shape, State$2 as State, UniformDeclaration, UniformSpec, UniformValue };
+}
+/**
+ * effects plugin config. `maxParticles` here is the global warning line; the `maxParticles` of an
+ * emitter config caps one instance.
+ *
+ * @example
+ * ```ts
+ * createApp({
+ *   plugins: [...screen, effectsPlugin],
+ *   pluginConfigs: { effects: { maxPasses: 16, phone: false } }
+ * });
+ * ```
+ */
+type Config$2 = {
+  /** Live particles over all instances above which one dev warning fires per crossing. */maxParticles: number; /** Render passes per frame above which one dev warning fires per crossing. */
+  maxPasses: number; /** Whether this device is a phone. `"auto"`: a coarse pointer and a short side of at most 820 CSS px, read once in `onStart`. */
+  phone: boolean | "auto";
+  /**
+   * What a `Blur` with `quality: 0` and `resolution: 0` resolves to. Shallow merge: a game that
+   * sets `blur` gives both fields.
+   */
+  blur: {
+    quality: number;
+    phoneResolution: number;
+  };
+};
+/**
+ * effects plugin state: the particle half, the filter half, and what both share.
+ */
+type State$2 = {
+  /** Resolved in `onStart`. */phone: boolean; /** The `emitters` of every feature, read in `onStart`. */
+  emitters: Map<string, EmitterDefinition>; /** Per effect id, built on first use. */
+  baked: Map<string, BakedEmitter>; /** Host entity to its running instance. */
+  instances: Map<Entity, EmitterInstance>; /** World-space instances whose host left, stepped until empty. */
+  orphans: Set<EmitterInstance>; /** Ordinal of the next instance: the cosmetic seed. */
+  seedCounter: number; /** Live particles after the last step. */
+  particles: number; /** Filter kinds whose WGSL failed the dev check. */
+  broken: Set<string>; /** The filter kinds, built-ins first, then the filters of every feature. */
+  kinds: Map<string, FilterKind>; /** The dev WGSL check per kind; `broken` holds the failed ones. */
+  checks: Map<string, "pending" | "ok">; /** Entity to the filters the sync keeps for it. */
+  views: Map<Entity, FilteredView>; /** Keys of the one-shot warnings: `"emitter:fx.x"`, `"texture:board.cell"`, `"atlas:fx.x"`. */
+  warned: Set<string>; /** Whether each budget warning is in force, so a crossing warns once. */
+  over: {
+    particles: boolean;
+    passes: boolean;
+    fullScreen: boolean;
+  }; /** The teardown closure, the two systems and the world hooks. */
+  removers: Array<() => void>;
+};
+/**
+ * What `app.effects.stats()` answers: live particles, running emitter instances, filter instances
+ * on views, and the render passes of the frame as the renderer counts them.
+ *
+ * @example
+ * ```ts
+ * const stats: EffectsStats = { particles: 120, emitters: 3, filters: 25, renderPasses: 49 };
+ * ```
+ */
+type EffectsStats = {
+  /** Live particles over every instance and orphan after the last step. */particles: number; /** Running instances plus the orphans still flying. */
+  emitters: number; /** Filter instances over every view. */
+  filters: number; /** `renderer.sync.renderPasses()`, read at call time. */
+  renderPasses: number;
+};
+/**
+ * effects plugin API, `app.effects`. Everything a game does with effects is data on entities;
+ * the API only counts.
+ *
+ * @example
+ * ```ts
+ * // A test waits for a merge burst to land before it compares the board.
+ * while (app.effects.stats().particles > 0) app.time.step(16);
+ * app.effects.stats().particles; // 0
+ * ```
+ */
+type EffectsApi = {
+  /**
+   * Counts what runs now. `renderPasses` is the renderer's own number, read at call time; the
+   * others are the plugin's. Headless every number is 0.
+   *
+   * @returns A fresh object: live particles, emitter instances with orphans, filter instances
+   *   and render passes.
+   * @example
+   * ```ts
+   * // After the board rests: one steam stream, 24 enabled glows on 24 views, one disabled blur.
+   * app.effects.stats();
+   * // { particles: 18, emitters: 1, filters: 25, renderPasses: 49 }: 1 + 24 × (1 + 1), the disabled blur costs 0
+   * ```
+   */
+  stats(): EffectsStats;
+};
+/**
+ * Resolved dependency APIs.
+ */
+type Deps$2 = {
+  flow: Api;
+  world: Api$1;
+  renderer: Api$2;
+  assets: Api$5;
+  anim: AnimApi;
+};
+/**
+ * What the kernel context offers before the deps are attached. `effects` owns no event, so
+ * `emit` is the kernel's and never called here.
+ */
+type KernelSlice$2 = PluginCtx<Config$2, State$2> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+  readonly require: Require;
+};
+/**
+ * Domain context shared by both modules: the kernel slice plus the resolved deps.
+ */
+type EffectsCtx = KernelSlice$2 & {
+  readonly deps: Deps$2;
+};
+/**
+ * Payload of the `assets:bundle-unloaded` hook: `keys` names every texture that is gone.
+ */
+type BundleUnloaded$1 = Events$3["assets:bundle-unloaded"];
+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$1;
+  assets: Api$5;
+  time: Api$3;
+};
+/**
+ * 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$5;
+  model: Api$4;
+  time: Api$3;
+};
+/**
+ * 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 { FilterValueOf as A, EmitterValue as C, DisplacementValue as D, ColorMatrixValue as E, NoiseValue as M, OutlineValue as N, FilterComponent as O, UniformDeclaration as P, EmitterDefinition as S, BlurValue as T, EffectsApi as _, SoundEntry as a, types_d_exports$2 as b, AnySceneProjection as c, SceneDefinition as d, SceneSpec as f, Config$2 as g, types_d_exports$1 as h, MusicOptions as i, GlowValue as j, FilterSpec 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, EffectsStats as v, AlphaValue as w, EmitterConfig as x, State$2 as y };