@moku-labs/game 0.0.2 → 0.0.3

package/dist/define-BMo0pHe_.d.mts

@@ -0,0 +1,51 @@
+import { c as Source, d as HeadlessApp, n as Command, o as InputSchema } from "./types-D0uYTTC3.mjs";
+
+//#region src/plugins/flow/doors/define.d.ts
+/**
+ * Declares a source: a read-only view the editor lists, reads and watches. The types flow from
+ * the object: the input from `input`, the app from the `read` parameter, the output from its
+ * result.
+ *
+ * @param source - The descriptor.
+ * @returns The same descriptor, frozen.
+ * @throws {Error} When the id is not a dotted name such as `"game.position"`.
+ * @example
+ * ```ts
+ * // A game's .dev module: the orders on the board, re-read after every edge.
+ * export const orders = defineSource({
+ *   id: "timber.orders",
+ *   title: "Orders",
+ *   input: {},
+ *   changes: "edge",
+ *   read: app => app.flow.state().path
+ * });
+ * read(app, orders); // "board/awaitIntent"
+ * ```
+ */
+declare function defineSource<S extends InputSchema, O, App = HeadlessApp>(source: Source<S, O, App>): Source<S, O, App>;
+/**
+ * Declares a command: a dev-only action the editor lists and runs. Its body starts with the
+ * inline dev guard, so a production build drops it.
+ *
+ * @param command - The descriptor.
+ * @returns The same descriptor, frozen.
+ * @throws {Error} When the id is not a dotted name such as `"game.answer"`.
+ * @example
+ * ```ts
+ * // A game's .dev module: open the shop from anywhere, through the graph.
+ * export const openShop = defineCommand({
+ *   id: "timber.openShop",
+ *   title: "Open the shop",
+ *   input: {},
+ *   effect: "route",
+ *   run: app => {
+ *     if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+ *     return app.flow.walk([{ at: "home", intent: "shop" }]);
+ *   }
+ * });
+ * (await run(app, openShop)).state.path; // "shop"
+ * ```
+ */
+declare function defineCommand<S extends InputSchema, O, App = HeadlessApp>(command: Command<S, O, App>): Command<S, O, App>;
+//#endregion
+export { defineSource as n, defineCommand as t };

package/dist/{registry-DlpRCibU.mjs → dev-CcwFrwok.mjs}

@@ -381,4 +381,33 @@ function graphHash(graph) {
 	return hashText(stableJson(graph));
 }
 //#endregion
-export { graphHash as a, pushEntry as c, framePath as i, describeGraph as n, slotNames as o, findNode as r, compact as s, collectFlows as t };
+//#region src/plugins/flow/doors/dev.ts
+/**
+* Reads the dev flag at call time. Undefined means off: production is the default.
+*
+* @returns True only when `__MOKU_GAME_DEV__` is exactly `true`.
+* @example
+* ```ts
+* // The dev page set the flag in web/dev.ts before the engine started.
+* globalThis.__MOKU_GAME_DEV__ = true;
+* isDev(); // true
+* ```
+*/
+function isDev() {
+	return typeof __MOKU_GAME_DEV__ !== "undefined" && __MOKU_GAME_DEV__ === true;
+}
+/**
+* Builds the error a control command throws outside a dev build.
+*
+* @returns The error, ready to throw.
+* @example
+* ```ts
+* // A production build called a /control command.
+* controlRefused().message; // "[game] Control commands run in dev builds only.\n  Define __MOKU_GAME_DEV__ as true in the dev build."
+* ```
+*/
+function controlRefused() {
+	return /* @__PURE__ */ new Error("[game] Control commands run in dev builds only.\n  Define __MOKU_GAME_DEV__ as true in the dev build.");
+}
+//#endregion
+export { findNode as a, slotNames as c, describeGraph as i, compact as l, isDev as n, framePath as o, collectFlows as r, graphHash as s, controlRefused as t, pushEntry as u };

package/dist/index.d.mts

@@ -1,16 +1,15 @@
-import { $ as PauseReason, A as Config$4, B as types_d_exports$8, C as SceneIdOf, D as Hint, E as GuideOptions, F as Config$3, G as SaveUnreadableError, J as RngApi, L as Json, N as types_d_exports$12, R as Root, T as Descriptor, V as Patch, X as Api$2, Z as Config$2, _ as DefineNode, a as GameTypes, at as State, c as TextStylesOf, ct as Events, d as exit, et as State$2, f as slot, h as FeatureDescription, i as FeaturePlugin, j as State$4, k as Api$3, l as types_d_exports$4, m as type, n as BundlesOf, nt as Api, ot as types_d_exports$3, p as to, q as StoreApi, r as Config$1, rt as Config, s as State$1, st as Config$5, t as Api$1, tt as types_d_exports$7, u as defineFlow, z as State$3 } from "./types-JNc_UQBo.mjs";
-import { A as ComponentHandle, B as SystemDefinition, C as ProjectionSpec, F as Mut, I as Narrowed, M as ComponentValue, R as QueryTerm, S as ProjectionMotion, V as TagType, a as types_d_exports$9, d as Config$7, f as State$6, g as Ease, h as DescriptionNode, i as State$5, j as ComponentType, k as AnyComponentValue, l as ViewportSize, n as Config$6, p as types_d_exports$14, t as Api$4, u as Api$5, x as NumericFields, z as ResourceType } from "./types-BxkNNYul.mjs";
-import { a as DefineBundles, c as LoadReason, d as Tier, i as Config$8, n as BundleMap, p as types_d_exports$1, r as BundleSpec, s as LoadBundles, t as Api$6, u as State$7 } from "./types-DWILGrPn.mjs";
-import { A as Transform, B as types_d_exports$5, C as NineSliceValue, D as Sprite, E as ShapeValue, H as InputApi, I as I18nApi, L as Message, M as sprite, N as Argument, O as SpriteOptions, P as Config$9, R as State$8, S as NineSlice, T as Shape, U as State$9, V as Config$10, W as types_d_exports$6, _ as Style, b as defineComponent, d as popup, f as defineTokens, g as ResolvedStyle, h as IsFlags, j as TransformValue, k as SpriteValue, l as Box, p as IntrinsicElementsFor, s as PopupComponent, u as LocalWrite, w as Parent, x as Display, y as WhenFlags, z as TypedTr } from "./types-yg_ywtT-.mjs";
-import { a as Config$11, c as TextApi, d as TextValue, f as types_d_exports$11, i as types_d_exports$13, l as TextStyleInput, n as State$11, o as Point, r as UiApi, s as State$10, t as Config$12, u as TextStyles } from "./types-DD-QrG_z.mjs";
-import { a as Config$13, c as SlotValues, d as types_d_exports, f as ExternalPlayer, g as Step, h as SfxDescriptor, i as BuildTools, l as State$12, m as PlayDescriptor, n as AnimationDefinition, o as MotionKeyframe, p as HapticDescriptor, r as AnimationSpec, s as SlotTags, t as AnimApi, u as Target } from "./types-CTPS9GBu.mjs";
-import { c as AnySceneProjection, d as SceneDefinition, f as SceneSpec, h as types_d_exports$10, i as MusicOptions, l as DefineScene, m as State$14, n as Config$14, o as State$13, p as ScenesApi, r as MusicDescriptor, s as types_d_exports$2, t as AudioApi, u as LayerMap } from "./types-DYLnSgMI.mjs";
+import { $t as types_d_exports$3, At as Json, B as Mut, Bt as StoreApi, Ct as Config$5, D as ProjectionMotion, E as NumericFields, Et as types_d_exports$13, F as ComponentHandle, G as SystemDefinition, I as ComponentType, J as BundlesOf, Jt as types_d_exports$8, K as TagType, Kt as PauseReason, L as ComponentValue, Mt as State$3, Nt as types_d_exports$9, O as ProjectionSpec, Ot as Config$3, P as AnyComponentValue, Pt as Patch, Q as GameTypes, Qt as State, Rt as SaveUnreadableError, St as Api$4, U as QueryTerm, Ut as Api$2, V as Narrowed, Vt as RngApi, W as ResourceType, Wt as Config$2, X as EmitterIdOf, Xt as Config, Y as Config$1, Yt as Api, Z as FeaturePlugin, _ as State$6, at as slot, b as DescriptionNode, bt as Hint, c as types_d_exports$10, ct as FeatureDescription, en as Config$7, et as State$1, g as Config$6, gt as SceneIdOf, h as Api$5, it as exit, jt as Root, m as ViewportSize, n as Config$4, nt as types_d_exports$5, ot as to, q as Api$1, qt as State$2, rt as defineFlow, s as State$4, st as type, t as Api$3, tn as Events, tt as TextStylesOf, ut as DefineNode, v as types_d_exports$15, vt as Descriptor, wt as State$5, x as Ease, yt as GuideOptions } from "./types-Cjf3ywai.mjs";
+import { a as DefineBundles, c as LoadReason, d as Tier, i as Config$8, n as BundleMap, p as types_d_exports$1, r as BundleSpec, s as LoadBundles, t as Api$6, u as State$7 } from "./types-DgwbzDLP.mjs";
+import { A as Transform, B as types_d_exports$6, C as NineSliceValue, D as Sprite, E as ShapeValue, H as InputApi, I as I18nApi, L as Message, M as sprite, N as Argument, O as SpriteOptions, P as Config$9, R as State$8, S as NineSlice, T as Shape, U as State$9, V as Config$10, W as types_d_exports$7, _ as Style, b as defineComponent, d as popup, f as defineTokens, g as ResolvedStyle, h as IsFlags, j as TransformValue, k as SpriteValue, l as Box, p as IntrinsicElementsFor, s as PopupComponent, u as LocalWrite, w as Parent, x as Display, y as WhenFlags, z as TypedTr } from "./types-C0SLQsx0.mjs";
+import { C as Point, D as TextStyles, E as TextStyleInput, O as TextValue, S as Config$12, T as TextApi, _ as Step, a as Config$11, b as UiApi, c as SlotTags, d as Target, f as types_d_exports, g as SfxDescriptor, h as PlayDescriptor, i as BuildTools, k as types_d_exports$12, l as SlotValues, m as HapticDescriptor, n as AnimationDefinition, o as FramesValue, p as ExternalPlayer, r as AnimationSpec, s as MotionKeyframe, t as AnimApi, u as State$10, v as Config$13, w as State$11, x as types_d_exports$14, y as State$12 } from "./types-KlE_GL1z.mjs";
+import { A as FilterValueOf, C as EmitterValue, D as DisplacementValue, E as ColorMatrixValue, M as NoiseValue, N as OutlineValue, O as FilterComponent, P as UniformDeclaration, S as EmitterDefinition, T as BlurValue, _ as EffectsApi, b as types_d_exports$4, c as AnySceneProjection, d as SceneDefinition, f as SceneSpec, g as Config$15, h as types_d_exports$11, i as MusicOptions, j as GlowValue, k as FilterSpec, l as DefineScene, m as State$15, n as Config$14, o as State$13, p as ScenesApi, r as MusicDescriptor, s as types_d_exports$2, t as AudioApi, u as LayerMap, w as AlphaValue, x as EmitterConfig, y as State$14 } from "./types-BTycq8_Z.mjs";
 
 //#region src/plugins/text/components.d.ts
 /**
  * Words on the screen: a string or a message, the style it is drawn in, and the string `text`
- * resolved out of it. A game writes `content`, `style`, `bind` and `anchor`; `resolved` is
- * engine-owned and `ui` and the tests read it.
+ * resolved out of it. A game writes `content`, `style`, `bind`, `anchor` and `alpha`; `resolved`
+ * is engine-owned and `ui` and the tests read it. `alpha` (1 by default) fades the whole block and
+ * is patched in place, so a tween on it rebuilds nothing.
  */
 declare const Text: ComponentType<TextValue>;
 /**
@@ -37,7 +36,7 @@ type LabelOptions = {
  * ```ts
  * label({ text: "+5", style: "board.float", at: { x: 90, y: 180 } });
  * // [Text({ content: "+5", style: "board.float", bind: undefined,
- * //   anchor: { x: 0.5, y: 0.5 }, resolved: "" }),
+ * //   anchor: { x: 0.5, y: 0.5 }, alpha: 1, resolved: "" }),
  * //  Transform({ x: 90, y: 180, rotation: 0, scale: 1 })]
  * ```
  */
@@ -112,7 +111,7 @@ type ProjectionFor<Player, Session> = <const LayerName extends string, const Lif
  * app.anim.play(coinsFly, { from: purse, to: counter }).marks(); // []: the first frame is next
  * ```
  */
-declare const animPlugin: import("@moku-labs/core").PluginInstance<"anim", Config$13, State$12, AnimApi, {
+declare const animPlugin: import("@moku-labs/core").PluginInstance<"anim", Config$11, State$10, AnimApi, {
   "anim:mark": {
     animation: string;
     mark: string;
@@ -190,6 +189,23 @@ declare const audioPlugin: import("@moku-labs/core").PluginInstance<"audio", Con
  */
 declare const clockPlugin: import("@moku-labs/core").PluginInstance<"clock", Config, State, Api, {}> & Record<never, never>;
 //#endregion
+//#region src/plugins/effects/index.d.ts
+/**
+ * Effects plugin: `app.effects.stats()`; the `Emitter` component and every filter component do
+ * the rest as data on entities.
+ *
+ * @example
+ * ```ts
+ * // A game composes it next to the screen set; its features bring the emitters and filters.
+ * const app = createApp({
+ *   plugins: [...screen, effectsPlugin, boardFeature],
+ *   pluginConfigs: { renderer: { mount: "#game" }, effects: { maxPasses: 16 } }
+ * });
+ * app.effects.stats(); // { particles: 0, emitters: 0, filters: 0, renderPasses: 0 }: nothing runs before start
+ * ```
+ */
+declare const effectsPlugin: import("@moku-labs/core").PluginInstance<"effects", Config$15, State$14, EffectsApi, {}> & Record<never, never>;
+//#endregion
 //#region src/plugins/flow/index.d.ts
 /**
  * Flow plugin: `app.flow.run()`, `app.flow.gate.answer(...)`, `app.flow.fx.handle(...)`.
@@ -338,7 +354,7 @@ declare const modelPlugin: import("@moku-labs/core").PluginInstance<"model", Con
  * app.renderer.host.kind(); // "webgpu" in Chrome, "webgl" on an older device
  * ```
  */
-declare const rendererPlugin: import("@moku-labs/core").PluginInstance<"renderer", Config$6, State$5, Api$4, {
+declare const rendererPlugin: import("@moku-labs/core").PluginInstance<"renderer", Config$4, State$4, Api$3, {
   "renderer:device-lost": {
     kind: "webgpu" | "webgl";
     reason: string;
@@ -361,7 +377,7 @@ declare const rendererPlugin: import("@moku-labs/core").PluginInstance<"renderer
  * export const awaitIntent = defineNode({ scene: "board", rest: true, outcomes: { merge: type() } });
  * ```
  */
-declare const scenesPlugin: import("@moku-labs/core").PluginInstance<"scenes", Record<string, never>, State$14, ScenesApi, {
+declare const scenesPlugin: import("@moku-labs/core").PluginInstance<"scenes", Record<string, never>, State$15, ScenesApi, {
   "scenes:changed": {
     from: string | undefined;
     to: string;
@@ -386,7 +402,7 @@ declare const scenesPlugin: import("@moku-labs/core").PluginInstance<"scenes", R
  * app.text.styles(); // ["body", "digits", "hud.digits"]
  * ```
  */
-declare const textPlugin: import("@moku-labs/core").PluginInstance<"text", Config$11, State$10, TextApi, {}> & Record<never, never>;
+declare const textPlugin: import("@moku-labs/core").PluginInstance<"text", Config$12, State$11, TextApi, {}> & Record<never, never>;
 //#endregion
 //#region src/plugins/time/index.d.ts
 /**
@@ -401,11 +417,12 @@ declare const textPlugin: import("@moku-labs/core").PluginInstance<"text", Confi
  * });
  * ```
  */
-declare const timePlugin: import("@moku-labs/core").PluginInstance<"time", Config$4, State$4, Api$3, {}> & Record<never, never>;
+declare const timePlugin: import("@moku-labs/core").PluginInstance<"time", Config$5, State$5, Api$4, {}> & Record<never, never>;
 //#endregion
 //#region src/plugins/ui/index.d.ts
 /**
- * Ui plugin: `app.ui.tree()`, `app.ui.find(...)`, `app.ui.lint()`, the components `Box` and
+ * Ui plugin: `app.ui.tree()`, `app.ui.find(...)`, `app.ui.lint()`, `app.ui.fill(...)`, the
+ * text field `<input local>`, the components `Box` and
  * `LocalWrite`, and the helpers `defineComponent`, `defineStyle`, `defineTokens` and `popup`.
  *
  * @example
@@ -417,7 +434,7 @@ declare const timePlugin: import("@moku-labs/core").PluginInstance<"time", Confi
  * app.input.tap(app.ui.find("claim") ?? 0);
  * ```
  */
-declare const uiPlugin: import("@moku-labs/core").PluginInstance<"ui", Config$12, State$11, UiApi, {}> & Record<never, never>;
+declare const uiPlugin: import("@moku-labs/core").PluginInstance<"ui", Config$13, State$12, UiApi, {}> & Record<never, never>;
 //#endregion
 //#region src/plugins/world/index.d.ts
 /**
@@ -433,7 +450,7 @@ declare const uiPlugin: import("@moku-labs/core").PluginInstance<"ui", Config$12
  * app.world.projection.entityOf("board.items", "i7"); // 1048576
  * ```
  */
-declare const worldPlugin: import("@moku-labs/core").PluginInstance<"world", Config$7, State$6, Api$5, {
+declare const worldPlugin: import("@moku-labs/core").PluginInstance<"world", Config$6, State$6, Api$5, {
   "world:reconciled": {
     mode: "play" | "direct";
     projections: number;
@@ -789,6 +806,22 @@ declare function defineScene<Layers extends LayerMap, const Projections extends
 declare const Animation: ComponentType<{
   playing: number;
 }>;
+/**
+ * A frame loop on an entity, for as long as the entity carries it: every `1000 / fps` ms
+ * `Sprite.texture` becomes the next key of `keys`, after the last key it wraps to the first. No
+ * timeline around it, not counted by `Animation` or `app.anim.active()`. A running `frames` step on
+ * the same entity owns the sprite until it ends; the loop goes on from where its clock stands.
+ * Paused and fast world modes and reduced motion stop the clock on the frame it shows.
+ *
+ * @example
+ * ```ts
+ * // A coin spins on the board for its whole life: a projection view returns both components.
+ * const coinSpin = ["items.coin-0", "items.coin-1", "items.coin-2", "items.coin-3"] as const;
+ * const coin = [Sprite({ texture: "items.coin-0" }), Frames({ keys: coinSpin, fps: 12 })];
+ * Frames({ keys: coinSpin, fps: 12 }).value.loop; // true: the default
+ * ```
+ */
+declare const Frames: ComponentType<FramesValue>;
 //#endregion
 //#region src/plugins/anim/motion.d.ts
 /**
@@ -1242,6 +1275,147 @@ declare function resolve(style: Style | undefined, flags: StyleFlags, viewport:
  */
 declare function music(key: string | null, options?: MusicOptions): Descriptor;
 //#endregion
+//#region src/plugins/effects/filters/builtins.d.ts
+/**
+ * A soft halo of `color` around the opaque pixels of a view and its subtree, `distance` pixels
+ * wide, that follows the shape: rounded corners stay rounded. Its alpha is
+ * `strength × alpha ×` the share of the disc of radius `distance` around the pixel the view
+ * covers, so `strength: 2` is full next to a straight edge and fades to nothing at `distance`.
+ * The view is padded by its live `distance`. One render pass per apply.
+ *
+ * @example
+ * ```ts
+ * // A merged item glows, and a motion hook tweens the glow away.
+ * Glow({ strength: 4 }).value; // { strength: 4, distance: 10, color: 0xffffff, alpha: 1, enabled: true, order: 0 }
+ * view.tween(Glow, { strength: 0 }, { ms: 200 });
+ * ```
+ */
+declare const Glow: FilterComponent<GlowValue>;
+/**
+ * A ring of `thickness` pixels in `color` around the opaque pixels of a view and its subtree; the
+ * view is padded by its live `thickness`. One render pass per apply.
+ *
+ * @example
+ * ```ts
+ * // The selected card is outlined in honey.
+ * Outline({ thickness: 4, color: 0xffc233 }).value; // { thickness: 4, color: 0xffc233, alpha: 1, enabled: true, order: 0 }
+ * ```
+ */
+declare const Outline: FilterComponent<OutlineValue>;
+/**
+ * Pixi's blur over a view and its subtree. `quality: 0` means `config.blur.quality`;
+ * `resolution: 0` means `config.blur.phoneResolution` on a phone, otherwise 1. `repeatEdgePixels`
+ * keeps the padding at 0. Costs `2 × quality` render passes per apply.
+ *
+ * @example
+ * ```ts
+ * // The board behind a popup: the filter sits on the ui slot that hosts the board.
+ * Blur({ strength: 6 }).value; // { strength: 6, quality: 0, resolution: 0, repeatEdgePixels: true, enabled: true, order: 0 }
+ * ```
+ */
+declare const Blur: ComponentType<BlurValue>;
+/**
+ * Pixi's colour matrix: brightness, saturation, contrast, hue in degrees and grayscale, composed
+ * in that order from the identity on every change. Every default is the identity.
+ *
+ * @example
+ * ```ts
+ * // A locked card goes gray.
+ * ColorMatrix({ grayscale: 1 }).value.grayscale; // 1
+ * ```
+ */
+declare const ColorMatrix: ComponentType<ColorMatrixValue>;
+/**
+ * Pixi's noise. The seed is always given, never Pixi's random default, so two runs draw the same
+ * grain.
+ *
+ * @example
+ * ```ts
+ * Noise({ amount: 0.2, seed: 7 }).value; // { amount: 0.2, seed: 7, enabled: true, order: 0 }
+ * ```
+ */
+declare const Noise: ComponentType<NoiseValue>;
+/**
+ * Pixi's displacement over the texture of the asset key `map`. Nothing is drawn while the map is
+ * not loaded; a missing key warns once.
+ *
+ * @example
+ * ```ts
+ * // Heat haze over the furnace.
+ * Displacement({ map: "fx.ripple", scaleX: 8, scaleY: 8 }).value.map; // "fx.ripple"
+ * ```
+ */
+declare const Displacement: ComponentType<DisplacementValue>;
+/**
+ * Pixi's alpha over a view and its subtree as one layer, so overlapping children do not show
+ * through each other.
+ *
+ * @example
+ * ```ts
+ * Alpha({ alpha: 0.5 }).value; // { alpha: 0.5, enabled: true, order: 0 }
+ * ```
+ */
+declare const Alpha: ComponentType<AlphaValue>;
+//#endregion
+//#region src/plugins/effects/filters/define.d.ts
+/**
+ * Turns a WGSL fragment body into a filter component type. The engine prepends the vertex stage,
+ * the input bindings and a `FilterUniforms` struct in declaration order, bound as `fu`. Every
+ * number uniform is a number field, so the existing `tween` drives it; a colour is one hex field
+ * sent as a `vec3<f32>`; a tuple is an array field and not tweenable. Every filter component also
+ * carries `enabled: true` and `order: 0`. Register it through the `filters` key of a feature.
+ *
+ * @param id - The filter id, also the component name; unique, and not one of the built-ins.
+ * @param spec - The body, the uniforms, the passes one apply costs and the padding.
+ * @returns The component type, with the frozen `filter` definition attached.
+ * @throws {Error} When the id is empty, the body has no `mainFragment`, a uniform is reserved,
+ *   badly named or of no known form, or the passes or the padding break their rules.
+ * @example
+ * ```ts
+ * // features/board/effects.ts: a gold tint a motion hook tweens on a merge.
+ * const Tint = defineFilter("fx.tint", { wgsl: tintBody, uniforms: { amount: 0, color: { color: 0xffd700 } } });
+ * Tint({ amount: 1 }).value; // { amount: 1, color: 0xffd700, enabled: true, order: 0 }
+ * Tint.filter.passes; // 1
+ * ```
+ */
+declare function defineFilter<Uniforms extends Record<string, UniformDeclaration> = Record<never, never>>(id: string, spec: FilterSpec<Uniforms>): FilterComponent<FilterValueOf<Uniforms>>;
+//#endregion
+//#region src/plugins/effects/particles/component.d.ts
+/**
+ * A particle effect on an entity. A `burst` effect emits when the component appears or its
+ * `effect` changes; a `rate` effect emits while `active` is true and the entity lives. An effect in
+ * `"world"` space outlives the entity, one in `"local"` space moves and dies with it. `""` draws
+ * nothing. Plain JSON: it shows in `snapshot()`.
+ *
+ * @example
+ * ```ts
+ * // A merged item bursts stars from its enter hook; the generator steams for its whole life.
+ * view.set(Emitter, { effect: "fx.starsBurst" });
+ * Emitter({ effect: "fx.steam" }).value; // { effect: "fx.steam", active: true }
+ * ```
+ */
+declare const Emitter: ComponentType<EmitterValue>;
+//#endregion
+//#region src/plugins/effects/particles/define.d.ts
+/**
+ * Describes a particle effect. Every field is optional except `textures` and exactly one of
+ * `burst` and `rate`; the definition is frozen, registered through the `emitters` key of a feature
+ * and started by an `Emitter` component naming its id.
+ *
+ * @param id - The effect id, unique across the features of the game.
+ * @param config - The effect as data.
+ * @returns The frozen definition `{ id, config }`, the config with every default filled in.
+ * @throws {Error} When the id is empty or a field breaks its rule.
+ * @example
+ * ```ts
+ * // features/board/effects.ts: the steam over the generator.
+ * const steam = defineEmitter("fx.steam", { textures: ["fx.puff"], rate: 12, space: "local" });
+ * steam.config.rate; // 12
+ * steam.config.lifeMs; // [600, 1000], the default
+ * ```
+ */
+declare function defineEmitter(id: string, config: EmitterConfig): EmitterDefinition;
+//#endregion
 //#region src/index.d.ts
 /**
  * Creates a game application.
@@ -1255,7 +1429,7 @@ declare function music(key: string | null, options?: MusicOptions): Descriptor;
  * });
  * ```
  */
-declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<Config$5, Events, (import("@moku-labs/core").PluginInstance<"time", Config$4, State$4, Api$3, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"lifecycle", Config$2, State$2, Api$2, {
+declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<Config$7, Events, (import("@moku-labs/core").PluginInstance<"time", Config$5, State$5, Api$4, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"lifecycle", Config$2, State$2, Api$2, {
   "lifecycle:changed": {
     reason: PauseReason;
     action: "push" | "pop";
@@ -1295,7 +1469,7 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
     rolledBackTo: string;
     retry: boolean;
   };
-}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common/browser").LogConfig, import("@moku-labs/common/browser").LogState, import("@moku-labs/common/browser").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common/browser").EnvConfig, import("@moku-labs/common/browser").EnvState, import("@moku-labs/common/browser").EnvApi>]>> | undefined) => import("@moku-labs/core").App<Config$5, Events, (import("@moku-labs/core").PluginInstance<"time", Config$4, State$4, Api$3, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"lifecycle", Config$2, State$2, Api$2, {
+}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common/browser").LogConfig, import("@moku-labs/common/browser").LogState, import("@moku-labs/common/browser").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common/browser").EnvConfig, import("@moku-labs/common/browser").EnvState, import("@moku-labs/common/browser").EnvApi>]>> | undefined) => import("@moku-labs/core").App<Config$7, Events, (import("@moku-labs/core").PluginInstance<"time", Config$5, State$5, Api$4, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"lifecycle", Config$2, State$2, Api$2, {
   "lifecycle:changed": {
     reason: PauseReason;
     action: "push" | "pop";
@@ -1348,14 +1522,15 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  * });
  * ```
  */
-declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$5, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common/browser").LogConfig, import("@moku-labs/common/browser").LogState, import("@moku-labs/common/browser").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common/browser").EnvConfig, import("@moku-labs/common/browser").EnvState, import("@moku-labs/common/browser").EnvApi>]>>;
+declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$7, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common/browser").LogConfig, import("@moku-labs/common/browser").LogState, import("@moku-labs/common/browser").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common/browser").EnvConfig, import("@moku-labs/common/browser").EnvState, import("@moku-labs/common/browser").EnvApi>]>>;
 /**
  * Binds the authoring helpers to the types of one game: "createApp for a game". Each plugin binds
  * its own helpers (`flowFor`, `projectionFor`, `componentsFor`, `bundlesFor`, `scenesFor`); this
  * only spreads them, so the kit's type is inferred and never written by hand. At run time these
  * are the same functions and component objects the plugins export.
  *
- * @returns The helpers typed with the game's `player`, `session`, `assets`, `bundles` and `strings`.
+ * @returns The helpers typed with the game's `player`, `session`, `assets`, `bundles`, `strings`
+ *   and `emitters`.
  * @example
  * ```ts
  * // kit.ts of a game: bound once, imported by every node, flow and view file.
@@ -1364,6 +1539,16 @@ declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<
  * ```
  */
 declare function defineGame<Types extends GameTypes>(): {
+  defineEmitter: (id: EmitterIdOf<Types>, config: Omit<EmitterConfig, "textures"> & {
+    readonly textures: readonly Types["assets"][];
+  }) => EmitterDefinition;
+  Emitter: Narrowed<EmitterValue, {
+    effect?: EmitterIdOf<Types>;
+    active?: boolean;
+  }>;
+  Displacement: Narrowed<DisplacementValue, Partial<Omit<DisplacementValue, "map">> & {
+    map?: Types["assets"];
+  }>;
   music: MusicDescriptor<Types["assets"]>;
   defineComponent: typeof defineComponent;
   defineStyle: <const Given extends Style<Types["assets"]>>(style: Given) => Readonly<Given>;
@@ -1392,6 +1577,9 @@ declare function defineGame<Types extends GameTypes>(): {
     bus?: string;
   }) => SfxDescriptor;
   play: typeof play;
+  Frames: Narrowed<FramesValue, Partial<Omit<FramesValue, "keys">> & {
+    keys?: readonly Types["assets"][];
+  }>;
   defineScene: DefineScene<Types["assets"], BundlesOf<Types>>;
   defineBundles: DefineBundles<BundlesOf<Types>>;
   load: LoadBundles<BundlesOf<Types>>;
@@ -1415,14 +1603,14 @@ declare function defineGame<Types extends GameTypes>(): {
 };
 /**
  * The screen plugins, in dependency order. A game with a screen spreads them into `plugins`;
- * a headless test leaves them out. V2: `world`, `renderer`, `input`, `assets`, `scenes`. V3 appends `anim`, `i18n`, `text`, `ui`; `audio` stays opt-in: `[...screen, audioPlugin]`.
+ * a headless test leaves them out. V2: `world`, `renderer`, `input`, `assets`, `scenes`. V3 appends `anim`, `i18n`, `text`, `ui`; `audio` and `effects` stay opt-in: `[...screen, audioPlugin, effectsPlugin]`.
  *
  * @example
  * ```ts
  * createApp({ plugins: [...screen, boardFeature], pluginConfigs: { renderer: { mount: "#game" } } });
  * ```
  */
-declare const screen: readonly [import("@moku-labs/core").PluginInstance<"world", Config$7, State$6, Api$5, {
+declare const screen: readonly [import("@moku-labs/core").PluginInstance<"world", Config$6, State$6, Api$5, {
   "world:reconciled": {
     mode: "play" | "direct";
     projections: number;
@@ -1434,7 +1622,7 @@ declare const screen: readonly [import("@moku-labs/core").PluginInstance<"world"
     hintsRouted: number;
     hintsDropped: number;
   };
-}> & Record<never, never>, import("@moku-labs/core").PluginInstance<"renderer", Config$6, State$5, Api$4, {
+}> & Record<never, never>, import("@moku-labs/core").PluginInstance<"renderer", Config$4, State$4, Api$3, {
   "renderer:device-lost": {
     kind: "webgpu" | "webgl";
     reason: string;
@@ -1458,13 +1646,13 @@ declare const screen: readonly [import("@moku-labs/core").PluginInstance<"world"
     reason: "budget" | "request";
     keys: readonly string[];
   };
-}> & Record<never, never>, import("@moku-labs/core").PluginInstance<"scenes", Record<string, never>, State$14, ScenesApi, {
+}> & Record<never, never>, import("@moku-labs/core").PluginInstance<"scenes", Record<string, never>, State$15, ScenesApi, {
   "scenes:changed": {
     from: string | undefined;
     to: string;
     music: string | undefined;
   };
-}> & Record<never, never>, import("@moku-labs/core").PluginInstance<"anim", Config$13, State$12, AnimApi, {
+}> & Record<never, never>, import("@moku-labs/core").PluginInstance<"anim", Config$11, State$10, AnimApi, {
   "anim:mark": {
     animation: string;
     mark: string;
@@ -1476,6 +1664,6 @@ declare const screen: readonly [import("@moku-labs/core").PluginInstance<"world"
   "i18n:locale-changed": {
     locale: string;
   };
-}> & Record<never, never>, import("@moku-labs/core").PluginInstance<"text", Config$11, State$10, TextApi, {}> & Record<never, never>, import("@moku-labs/core").PluginInstance<"ui", Config$12, State$11, UiApi, {}> & Record<never, never>];
+}> & Record<never, never>, import("@moku-labs/core").PluginInstance<"text", Config$12, State$11, TextApi, {}> & Record<never, never>, import("@moku-labs/core").PluginInstance<"ui", Config$13, State$12, UiApi, {}> & Record<never, never>];
 //#endregion
-export { types_d_exports as Anim, Animation, types_d_exports$1 as Assets, types_d_exports$2 as Audio, Box, types_d_exports$3 as Clock, type DescriptionNode, Display, Draggable, DropTarget, Exiting, types_d_exports$4 as Flow, Held, Hovered, types_d_exports$5 as I18n, types_d_exports$6 as Input, Layer, types_d_exports$7 as Lifecycle, LocalWrite, types_d_exports$8 as Model, NineSlice, Order, Parent, Pointer, PointerOver, Pressable, Pressed, types_d_exports$9 as Renderer, SaveUnreadableError, types_d_exports$10 as Scenes, Shape, Sprite, Swipeable, Tappable, Text, types_d_exports$11 as TextTypes, types_d_exports$12 as Time, Touchable, Transform, Tree, types_d_exports$13 as Ui, types_d_exports$14 as World, animPlugin, assetsPlugin, audioPlugin, clockPlugin, component, createApp, createPlugin, defineAnimation, defineBundles, defineComponent, defineFeature, defineGame, defineMotion, defineScene, defineStyle, defineTextStyles, defineTokens, exit, external, flowPlugin, frames, guide, haptic, hint, i18nPlugin, inputPlugin, label, lifecyclePlugin, load, mark, modelPlugin, music, mut, parallel, play, popup, projection, rendererPlugin, resolve, resource, scenesPlugin, schedule, screen, sequence, set, sfx, slot, spawn, spawned, sprite, stagger, system, tag, textPlugin, timePlugin, to, tr, tween, type, uiPlugin, use, wait, worldPlugin };
+export { Alpha, types_d_exports as Anim, Animation, types_d_exports$1 as Assets, types_d_exports$2 as Audio, Blur, Box, types_d_exports$3 as Clock, ColorMatrix, type DescriptionNode, Displacement, Display, Draggable, DropTarget, types_d_exports$4 as Effects, Emitter, Exiting, types_d_exports$5 as Flow, Frames, Glow, Held, Hovered, types_d_exports$6 as I18n, types_d_exports$7 as Input, Layer, types_d_exports$8 as Lifecycle, LocalWrite, types_d_exports$9 as Model, NineSlice, Noise, Order, Outline, Parent, Pointer, PointerOver, Pressable, Pressed, types_d_exports$10 as Renderer, SaveUnreadableError, types_d_exports$11 as Scenes, Shape, Sprite, Swipeable, Tappable, Text, types_d_exports$12 as TextTypes, types_d_exports$13 as Time, Touchable, Transform, Tree, types_d_exports$14 as Ui, types_d_exports$15 as World, animPlugin, assetsPlugin, audioPlugin, clockPlugin, component, createApp, createPlugin, defineAnimation, defineBundles, defineComponent, defineEmitter, defineFeature, defineFilter, defineGame, defineMotion, defineScene, defineStyle, defineTextStyles, defineTokens, effectsPlugin, exit, external, flowPlugin, frames, guide, haptic, hint, i18nPlugin, inputPlugin, label, lifecyclePlugin, load, mark, modelPlugin, music, mut, parallel, play, popup, projection, rendererPlugin, resolve, resource, scenesPlugin, schedule, screen, sequence, set, sfx, slot, spawn, spawned, sprite, stagger, system, tag, textPlugin, timePlugin, to, tr, tween, type, uiPlugin, use, wait, worldPlugin };