@moku-labs/game 0.8.0 → 0.10.0

package/dist/{types-DlgsfOmW.d.mts → types-BM4shh8K.d.mts}

@@ -1,6 +1,5 @@
-import { $ as Events$4, A as Api, E as Descriptor, F as Api$2, L as Events$3, R as Json, T as TypeTag, lt as Events$2, t as Api$1, ut as Require } from "./types-ERb2Y9U5.mjs";
-import { $ as Ease, I as AnyComponentValue, K as Owner, L as ComponentHandle, P as AnyComponent, V as Entity, ct as TrackSegment, et as LayerSort, it as NumericFields, k as Api$3, m as Api$4, o as Events$5, rt as MotionHandle, st as TrackOptions, t as Api$5, tt as LayerSpec, z as ComponentType } from "./types-BWzCSRM2.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-DgdMLZnV.mjs";
+import { A as Api$2, B as ComponentType, F as AnyComponent, H as Entity, It as TypeTag, L as AnyComponentValue, Lt as Descriptor, R as ComponentHandle, Sn as Require, Xt as Json, Yt as Events$2, at as NumericFields, ct as TrackOptions, dn as Events$3, dt as Api$1, et as Ease, h as Api$5, hn as Api, it as MotionHandle, lt as TrackSegment, nt as LayerSpec, q as Owner, qt as Api$4, s as Events$4, t as Api$3, tt as LayerSort, xn as Events$5 } from "./types-ZQLYXo5X.mjs";
+import { A as InputApi, c as UiNode, i as Finding, n as ElementChange, o as JsxState, q as I18nApi, r as ElementMotion, tt as StylesState, x as TextApi } from "./types-BUwDHKXm.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 import { Node, Yoga } from "yoga-layout/load";
@@ -633,7 +632,7 @@ type RunningTimeline = {
   ended: boolean;
 };
 declare namespace types_d_exports$3 {
-  export { AnimApi, AnimCtx, AnimationDefinition, AnimationSpec, AnyAnimationDefinition, BuildTools, Config$3 as Config, Cursor, Deps$3 as Deps, ErasedFields, Events$1 as Events, ExternalPlayer, FrameLoop, FramesValue, FxStep, HapticDescriptor, HapticKind, KernelSlice$3 as KernelSlice, MarkListener, MotionKeyframe, PlayDescriptor, PlayHandle, Pose, RunningTimeline, SfxDescriptor, SlotRecord, SlotTags, SlotValue, SlotValues, State$3 as State, Step, StepMotion, Target, TimelineRuntime, Track };
+  export { AnimApi, AnimCtx, AnimPlayerValue, AnimationDefinition, AnimationSpec, AnyAnimationDefinition, BuildTools, Config$3 as Config, Cursor, Deps$3 as Deps, ErasedFields, Events$1 as Events, ExternalPlayer, FrameLoop, FramesValue, FxStep, HapticDescriptor, HapticKind, KernelSlice$3 as KernelSlice, MarkListener, MotionKeyframe, PlayDescriptor, PlayHandle, Pose, RunningTimeline, SfxDescriptor, SlotRecord, SlotTags, SlotValue, SlotValues, State$3 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
@@ -1057,6 +1056,44 @@ type AnimApi = {
    */
   replace(definition: AnyAnimationDefinition): void;
 };
+/**
+ * What a system may do with anim, read with `res(AnimPlayer)`: play. A system that needs more
+ * than play is a plugin. Play on a change, never on every frame: keep the handle in a resource, or
+ * take away the tag that asked for the play.
+ *
+ * @example
+ * ```ts
+ * // A fresh item pops once: the system plays, then takes the Fresh tag away.
+ * const popIn = system({ name: "popIn", phase: "input", query: [Fresh], run: (items, { world, res }) => {
+ *   for (const [entity] of items) {
+ *     res(AnimPlayer).play(pop, { thing: entity });
+ *     world.untag(entity, Fresh);
+ *   }
+ * } });
+ * ```
+ */
+type AnimPlayerValue = {
+  /**
+   * Plays an animation from a system, the way `app.anim.play` does. The registered animation of
+   * `animation.id` wins when a feature brought one, so a hot swap reaches the system. Played from
+   * phase `input`, the tree moves in `animate` of the same frame; from a later phase it moves
+   * from the next frame.
+   *
+   * @param animation - What `defineAnimation` returned.
+   * @param slots - One target, or a list of targets, per declared slot.
+   * @returns The handle: `cancel()`, `finish()`, `active()`, `done`, `marks()`.
+   * @throws {Error} Before `anim` started: `[game] AnimPlayer is not ready: anim has not started.`
+   * @example
+   * ```ts
+   * const lift = defineAnimation("look.hover", { slots: { thing: type<Target>() },
+   *   build: ({ thing }) => tween(thing, Transform, { scale: 1.1 }, { ms: 100 }) });
+   * // Inside a system of phase "input": entity 1048576 is the item under the pointer.
+   * const handle = res(AnimPlayer).play(lift, { thing: 1_048_576 });
+   * handle.active(); // true until the lift lands 100 ms later, then false
+   * ```
+   */
+  play<Tags extends SlotTags>(animation: AnimationDefinition<Tags>, slots: SlotValues<Tags>): PlayHandle;
+};
 /**
  * Resolved dependency APIs. `renderer` is not among them: `anim` writes its `Sprite` and reads
  * its `Transform` through the component objects, which are plain data, composes the root pose
@@ -1066,7 +1103,7 @@ type AnimApi = {
 type Deps$3 = {
   time: Api;
   flow: Api$1;
-  world: Api$3;
+  world: Api$2;
 };
 /**
  * What the kernel context offers before the deps are attached.
@@ -1086,243 +1123,8 @@ type KernelSlice$3 = PluginCtx<Config$3, State$3, Events$1> & {
 type AnimCtx = KernelSlice$3 & {
   readonly deps: Deps$3;
 };
-//#endregion
-//#region src/plugins/ui/layout/types.d.ts
-/**
- * layout module state. `nodes` is attach minus detach: Yoga 3.2.1 has no instance counter.
- */
-type LayoutState = {
-  yoga: Yoga | undefined;
-  byEntity: Map<Entity, Node>;
-  nodes: number;
-  measured: number;
-  solves: number;
-  scrolling: Entity | undefined;
-  scrollStart: {
-    pointerY: number;
-    offset: number;
-  };
-  order: number;
-  cleanups: Array<() => void>;
-};
 declare namespace types_d_exports$2 {
-  export { Config$2 as Config, Deps$2 as Deps, ElementChange, ElementMotion, Finding, FocusRing, KernelSlice$2 as KernelSlice, State$2 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
- * focused control. Colours are `0xRRGGBB`, lengths reference units.
- *
- * @example
- * ```ts
- * // A dashed ink ring with a cream halo, 9 u outside the control.
- * const ring: FocusRing = {
- *   stroke: 0x3a2212, strokeWidth: 4, dash: 10, offset: 9, halo: 0xfff3d6, haloWidth: 12
- * };
- * ```
- */
-type FocusRing = {
-  /** The colour of the dashed ring. */stroke: number; /** The stroke width of the dashed ring. */
-  strokeWidth: number; /** The dash length of the ring, with gaps of half a dash; 0 draws it solid. */
-  dash: number; /** How far outside the control's rect the ring runs, on every side. */
-  offset: number; /** The colour of the solid halo drawn under the ring. */
-  halo: number; /** The stroke width of the halo, centred on the same path as the ring. */
-  haloWidth: number;
-};
-/**
- * The look of a text field while it is edited: the caret, the selection box and the IME
- * underline. Colours are `0xRRGGBB`, lengths reference units, `keyboardMargin` CSS px. The caret
- * does not blink.
- *
- * @example
- * ```ts
- * // A thick ink caret, a pale blue selection, the field 16 px above the keyboard.
- * const look: TextInputLook = {
- *   caretWidth: 3, caret: 0x3a2212, selection: 0x3390ff, selectionAlpha: 0.35,
- *   composingUnderline: 3, keyboardMargin: 16
- * };
- * ```
- */
-type TextInputLook = {
-  /** The width of the caret. */caretWidth: number; /** The colour of the caret and of the underline under an IME composing range. */
-  caret: number; /** The colour of the selection box. */
-  selection: number; /** The alpha of the selection box. */
-  selectionAlpha: number; /** The height of the underline under an IME composing range. */
-  composingUnderline: number; /** How far above the keyboard the bottom of the edited field is lifted, in CSS px. */
-  keyboardMargin: number;
-};
-/**
- * ui plugin config.
- *
- * @example
- * ```ts
- * createApp({ pluginConfigs: { ui: { tapTargetPt: 48, breakpoints: { tall: 2, wide: 1.5 } } } });
- * // A game with a white focus ring on a dark board.
- * createApp({
- *   pluginConfigs: {
- *     ui: {
- *       focusRing: {
- *         stroke: 0xffffff, strokeWidth: 4, dash: 10, offset: 9, halo: 0x000000, haloWidth: 12
- *       }
- *     }
- *   }
- * });
- * // A game whose text fields have an ink caret.
- * createApp({
- *   pluginConfigs: {
- *     ui: {
- *       textInput: {
- *         caretWidth: 3, caret: 0x3a2212, selection: 0x3390ff, selectionAlpha: 0.35,
- *         composingUnderline: 3, keyboardMargin: 16
- *       }
- *     }
- *   }
- * });
- * ```
- */
-type Config$2 = {
-  /** 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;
-    wide: number;
-  };
-  /**
-   * The ring drawn around the control the keyboard focused. Shallow merge: a game that sets
-   * `focusRing` gives all six fields.
-   */
-  focusRing: FocusRing;
-  /**
-   * The caret, the selection and the IME underline of a text field. Shallow merge: a game that
-   * sets `textInput` gives all six fields.
-   */
-  textInput: TextInputLook;
-};
-/**
- * ui plugin state: one branch per module.
- */
-type State$2 = {
-  jsx: JsxState;
-  styles: StylesState;
-  layout: LayoutState;
-};
-/**
- * Resolved dependency APIs. `anim` is here for the dev hot swap, which replaces animations; the
- * motions of `ui` reach `anim` through the tween driver behind every `ViewHandle`.
- */
-type Deps$2 = {
-  anim: AnimApi;
-  time: Api;
-  flow: Api$1;
-  world: Api$3;
-  renderer: Api$4;
-  input: InputApi;
-  i18n: I18nApi;
-  text: TextApi;
-};
-/**
- * What the kernel context offers before the deps are attached.
- *
- * `ui` owns no event of its own; `emit` sends the global `ui:hot-swap` of the dev hot swap.
- */
-type KernelSlice$2 = PluginCtx<Config$2, State$2, Events$2> & {
-  readonly global: object;
-  readonly log: Log.LogApi;
-  readonly require: Require;
-};
-/**
- * Domain context shared by the three modules: the kernel slice plus the resolved deps.
- */
-type UiCtx = KernelSlice$2 & {
-  readonly deps: Deps$2;
-};
-/**
- * ui plugin API, `app.ui`. The screen is one more projection, so three members read it the way a
- * test reads the board: a snapshot, a key lookup and a list of findings; the fourth types into a
- * text field.
- *
- * @example
- * ```ts
- * // A headless scenario taps the claim button of the reward popup.
- * app.ui.tree().type; // "row", the root element of the HUD
- * app.input.tap(app.ui.find("claim") ?? 0);
- * app.ui.lint(); // []
- * ```
- */
-type UiApi = {
-  /**
-   * The live screen as plain data: every root in layer order, every element in child order, with
-   * its rect in root coordinates, its resolved style and its seven state flags. A rect is natural:
-   * under a `fit: "contain"` element it is the rect before that scale, and the fitted element
-   * adds `fitScale`. A windowed scroll adds `window`, and its content lists the live rows only.
-   * Works headless.
-   *
-   * @returns The root node; several roots come back under one `screen` node.
-   * @example
-   * ```ts
-   * // On an iPhone SE the 970 u board is drawn smaller to fit the slot between the bars.
-   * const screen = app.ui.tree();
-   * screen.children.map(child => child.key); // ["fitTop", "slot", "fitBottom"]
-   * const board = screen.children[1]?.children[0];
-   * board?.rect.w; // 970, the natural width
-   * board?.fitScale; // 0.805, the 781 u the slot leaves over 970 u
-   * ```
-   */
-  tree(): UiNode;
-  /**
-   * The entity of a keyed element, so a test can tap it and `anim` can aim at it. Popup roots
-   * come first, then the projection roots in layer order.
-   *
-   * @param key - The `key` prop of the element.
-   * @returns The entity, or `undefined` for an unknown or exiting element.
-   * @example
-   * ```ts
-   * // A headless scenario answers the gate through the button of the popup.
-   * app.input.tap(app.ui.find("claim") ?? 0); // true
-   * app.ui.find("nothing"); // undefined
-   * ```
-   */
-  find(key: string): Entity | undefined;
-  /**
-   * Reads the live screen against the five rules: a tap target under `tapTargetPt` at the size
-   * it is drawn (a `fit: "contain"` on it or above it shrinks it), a text that does not fit its
-   * box in some registered locale, an absolute element with no `reason`, a clipping element
-   * (`scroll`, `overflow: "hidden"`) whose style names a nine-slice it never draws, and a root
-   * element whose style sets a `zIndex` it ignores. Never throws; empty when nothing is mounted.
-   *
-   * @returns One finding per rule and element.
-   * @example
-   * ```ts
-   * // A game test keeps the board honest on an iPhone SE: a 140 u cell in the 0.8 slot.
-   * app.ui.lint(); // [{ rule: "tap-target", key: "cell", detail: "39 x 39 pt" }]
-   * // A list styled with a nine-slice: the clip keeps it from drawing.
-   * app.ui.lint(); // [{ rule: "nine-slice-clipped", key: "orders", detail: "scroll" }]
-   * // A screen root that asks to be drawn over the others: the layer decides that.
-   * app.ui.lint(); // [{ rule: "z-index-on-root", key: "board", detail: "zIndex 2" }]
-   * ```
-   */
-  lint(): readonly Finding[];
-  /**
-   * Types into a text field the way a player does, for a headless test or an agent: the field
-   * becomes the one being edited, `value` cut to its `maxLength` is written into it, and the
-   * local field it names is written, so the component re-renders on the next frame. Nothing
-   * reaches the gate: Enter submits.
-   *
-   * @param key - The `key` prop of the `input` element.
-   * @param value - The text to type.
-   * @returns True when the field took the text; false with one warning when no live `input` has
-   *   the key.
-   * @example
-   * ```ts
-   * // A headless test renames the player through the Rename popup.
-   * app.ui.fill("nameField", "Alex"); // true
-   * app.time.step(16);
-   * app.input.pressKey("Enter"); // true: the gate took { intent: "save", payload: { name: "Alex" } }
-   * app.ui.fill("nothing", "Alex"); // false, with the warning "ui:fill-without-input"
-   * ```
-   */
-  fill(key: string, value: string): boolean;
-};
-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 };
+  export { AnySceneProjection, CheckedProjections, Config$2 as Config, DefineScene, Deps$2 as Deps, Events, KernelSlice$2 as KernelSlice, LayerMap, RunContext, SceneDefinition, SceneLayer, SceneOwner, SceneProjection, SceneSpec, ScenesApi, ScenesCtx, SortRule, State$2 as State, UiLayer };
 }
 /**
  * How a layer orders what is drawn in it. The scene's name for the rule `world` stores.
@@ -1487,11 +1289,11 @@ type SceneOwner = Owner & {
  * const config: Config = {};
  * ```
  */
-type Config$1 = Record<string, never>;
+type Config$2 = Record<string, never>;
 /**
  * scenes plugin state.
  */
-type State$1 = {
+type State$2 = {
   /** 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;
   /**
@@ -1567,10 +1369,10 @@ type ScenesApi = {
 /**
  * Resolved dependency APIs.
  */
-type Deps$1 = {
+type Deps$2 = {
   flow: Api$1;
-  world: Api$3;
-  assets: Api$5;
+  world: Api$2;
+  assets: Api$3;
   time: Api;
 };
 /**
@@ -1580,7 +1382,7 @@ type Deps$1 = {
  * 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> & {
+type KernelSlice$2 = PluginCtx<Config$2, State$2, Events> & {
   readonly global: object;
   readonly log: Log.LogApi;
   readonly require: Require;
@@ -1588,8 +1390,8 @@ type KernelSlice$1 = PluginCtx<Config$1, State$1, Events> & {
 /**
  * Domain context shared by the files of the plugin.
  */
-type ScenesCtx = KernelSlice$1 & {
-  readonly deps: Deps$1;
+type ScenesCtx = KernelSlice$2 & {
+  readonly deps: Deps$2;
 };
 /**
  * The mode and the abort signal `flow.onEnter` hands every callback.
@@ -1603,8 +1405,8 @@ 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 };
+declare namespace types_d_exports$1 {
+  export { AudioApi, AudioContextLike, AudioCtx, AudioSessionLike, AudioSessionType, BundleUnloaded, Bus, BusState, Config$1 as Config, Deps$1 as Deps, KernelSlice$1 as KernelSlice, LifecycleChanged, ModelCommitted, MusicDescriptor, MusicMode, MusicOptions, MusicRequest, MusicSwitch, MusicTrack, RetiringTrack, SceneChanged, SfxRequest, SoundEntry, State$1 as State, StreamTrack, Volumes };
 }
 /**
  * The three volume buses. `master` carries the whole game, `music` the scene track, `sfx` every
@@ -1742,7 +1544,7 @@ type RetiringTrack = {
  * });
  * ```
  */
-type Config = {
+type Config$1 = {
   /** Start gain of each bus, 0..1. Overridden per commit when `volumes` is set. */buses: {
     master: number;
     music: number;
@@ -1815,7 +1617,7 @@ type MusicSwitch = {
 /**
  * audio plugin state.
  */
-type State = {
+type State$1 = {
   /** `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;
@@ -1943,10 +1745,10 @@ type AudioApi = {
 /**
  * Resolved dependency APIs.
  */
-type Deps = {
+type Deps$1 = {
   flow: Api$1;
-  assets: Api$5;
-  model: Api$2;
+  assets: Api$3;
+  model: Api$4;
   time: Api;
 };
 /**
@@ -1954,7 +1756,7 @@ type Deps = {
  *
  * `audio` owns no event, so `emit` is the kernel's and never called here.
  */
-type KernelSlice = PluginCtx<Config, State> & {
+type KernelSlice$1 = PluginCtx<Config$1, State$1> & {
   readonly global: object;
   readonly log: Log.LogApi;
   readonly require: Require;
@@ -1962,13 +1764,13 @@ type KernelSlice = PluginCtx<Config, State> & {
 /**
  * Domain context shared by the files of the plugin: the kernel slice plus the resolved deps.
  */
-type AudioCtx = KernelSlice & {
-  readonly deps: Deps;
+type AudioCtx = KernelSlice$1 & {
+  readonly deps: Deps$1;
 };
 /**
  * Payload of the `model:committed` hook: the source of every volume a game sets.
  */
-type ModelCommitted = Events$3["model:committed"];
+type ModelCommitted = Events$2["model:committed"];
 /**
  * Payload of the `scenes:changed` hook: `music` is the track the next scene declared.
  */
@@ -1976,11 +1778,11 @@ type SceneChanged = Events["scenes:changed"];
 /**
  * Payload of the `lifecycle:changed` hook: the pause that holds every bus at zero.
  */
-type LifecycleChanged = Events$4["lifecycle:changed"];
+type LifecycleChanged = Events$3["lifecycle:changed"];
 /**
  * Payload of the `assets:bundle-unloaded` hook: `keys` names every decoded sound that is gone.
  */
-type BundleUnloaded = Events$5["assets:bundle-unloaded"];
+type BundleUnloaded = Events$4["assets:bundle-unloaded"];
 /**
  * What one play of a sound asks for: the key and the bus the sound goes to.
  */
@@ -1996,4 +1798,239 @@ type MusicRequest = {
   fadeMs: number;
 };
 //#endregion
-export { HAPTIC_KINDS as A, sfx as B, MotionKeyframe as C, HapticKind as D, types_d_exports$3 as E, mark as F, use as G, spawned as H, parallel as I, wait as K, play as L, external as M, frames as N, SfxDescriptor as O, haptic as P, sequence as R, FramesValue as S, Target as T, stagger as U, spawn as V, tween as W, State$2 as _, SoundEntry as a, AnimApi as b, AnySceneProjection as c, SceneDefinition as d, SceneSpec as f, Config$2 as g, types_d_exports$1 as h, MusicOptions as i, defineAnimation as j, Step 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, UiApi as v, State$3 as w, Config$3 as x, types_d_exports$2 as y, set as z };
+//#region src/plugins/ui/layout/types.d.ts
+/**
+ * layout module state. `nodes` is attach minus detach: Yoga 3.2.1 has no instance counter.
+ */
+type LayoutState = {
+  yoga: Yoga | undefined;
+  byEntity: Map<Entity, Node>;
+  nodes: number;
+  measured: number;
+  solves: number;
+  scrolling: Entity | undefined;
+  scrollStart: {
+    pointerY: number;
+    offset: number;
+  };
+  order: number;
+  cleanups: Array<() => void>;
+};
+declare namespace types_d_exports {
+  export { Config, Deps, ElementChange, ElementMotion, Finding, FocusRing, KernelSlice, State, TextInputLook, UiApi, UiCtx, UiNode };
+}
+/**
+ * The look of the keyboard focus ring: a dashed ring with a solid halo under it, drawn around the
+ * focused control. Colours are `0xRRGGBB`, lengths reference units.
+ *
+ * @example
+ * ```ts
+ * // A dashed ink ring with a cream halo, 9 u outside the control.
+ * const ring: FocusRing = {
+ *   stroke: 0x3a2212, strokeWidth: 4, dash: 10, offset: 9, halo: 0xfff3d6, haloWidth: 12
+ * };
+ * ```
+ */
+type FocusRing = {
+  /** The colour of the dashed ring. */stroke: number; /** The stroke width of the dashed ring. */
+  strokeWidth: number; /** The dash length of the ring, with gaps of half a dash; 0 draws it solid. */
+  dash: number; /** How far outside the control's rect the ring runs, on every side. */
+  offset: number; /** The colour of the solid halo drawn under the ring. */
+  halo: number; /** The stroke width of the halo, centred on the same path as the ring. */
+  haloWidth: number;
+};
+/**
+ * The look of a text field while it is edited: the caret, the selection box and the IME
+ * underline. Colours are `0xRRGGBB`, lengths reference units, `keyboardMargin` CSS px. The caret
+ * does not blink.
+ *
+ * @example
+ * ```ts
+ * // A thick ink caret, a pale blue selection, the field 16 px above the keyboard.
+ * const look: TextInputLook = {
+ *   caretWidth: 3, caret: 0x3a2212, selection: 0x3390ff, selectionAlpha: 0.35,
+ *   composingUnderline: 3, keyboardMargin: 16
+ * };
+ * ```
+ */
+type TextInputLook = {
+  /** The width of the caret. */caretWidth: number; /** The colour of the caret and of the underline under an IME composing range. */
+  caret: number; /** The colour of the selection box. */
+  selection: number; /** The alpha of the selection box. */
+  selectionAlpha: number; /** The height of the underline under an IME composing range. */
+  composingUnderline: number; /** How far above the keyboard the bottom of the edited field is lifted, in CSS px. */
+  keyboardMargin: number;
+};
+/**
+ * ui plugin config.
+ *
+ * @example
+ * ```ts
+ * createApp({ pluginConfigs: { ui: { tapTargetPt: 48, breakpoints: { tall: 2, wide: 1.5 } } } });
+ * // A game with a white focus ring on a dark board.
+ * createApp({
+ *   pluginConfigs: {
+ *     ui: {
+ *       focusRing: {
+ *         stroke: 0xffffff, strokeWidth: 4, dash: 10, offset: 9, halo: 0x000000, haloWidth: 12
+ *       }
+ *     }
+ *   }
+ * });
+ * // A game whose text fields have an ink caret.
+ * createApp({
+ *   pluginConfigs: {
+ *     ui: {
+ *       textInput: {
+ *         caretWidth: 3, caret: 0x3a2212, selection: 0x3390ff, selectionAlpha: 0.35,
+ *         composingUnderline: 3, keyboardMargin: 16
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+type Config = {
+  /** 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;
+    wide: number;
+  };
+  /**
+   * The ring drawn around the control the keyboard focused. Shallow merge: a game that sets
+   * `focusRing` gives all six fields.
+   */
+  focusRing: FocusRing;
+  /**
+   * The caret, the selection and the IME underline of a text field. Shallow merge: a game that
+   * sets `textInput` gives all six fields.
+   */
+  textInput: TextInputLook;
+};
+/**
+ * ui plugin state: one branch per module.
+ */
+type State = {
+  jsx: JsxState;
+  styles: StylesState;
+  layout: LayoutState;
+};
+/**
+ * Resolved dependency APIs. `anim` is here for the dev hot swap, which replaces animations; the
+ * motions of `ui` reach `anim` through the tween driver behind every `ViewHandle`.
+ */
+type Deps = {
+  anim: AnimApi;
+  time: Api;
+  flow: Api$1;
+  world: Api$2;
+  renderer: Api$5;
+  input: InputApi;
+  i18n: I18nApi;
+  text: TextApi;
+};
+/**
+ * What the kernel context offers before the deps are attached.
+ *
+ * `ui` owns no event of its own; `emit` sends the global `ui:hot-swap` of the dev hot swap.
+ */
+type KernelSlice = PluginCtx<Config, State, Events$5> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+  readonly require: Require;
+};
+/**
+ * Domain context shared by the three modules: the kernel slice plus the resolved deps.
+ */
+type UiCtx = KernelSlice & {
+  readonly deps: Deps;
+};
+/**
+ * ui plugin API, `app.ui`. The screen is one more projection, so three members read it the way a
+ * test reads the board: a snapshot, a key lookup and a list of findings; the fourth types into a
+ * text field.
+ *
+ * @example
+ * ```ts
+ * // A headless scenario taps the claim button of the reward popup.
+ * app.ui.tree().type; // "row", the root element of the HUD
+ * app.input.tap(app.ui.find("claim") ?? 0);
+ * app.ui.lint(); // []
+ * ```
+ */
+type UiApi = {
+  /**
+   * The live screen as plain data: every root in layer order, every element in child order, with
+   * its rect in root coordinates, its resolved style and its seven state flags. A rect is natural:
+   * under a `fit: "contain"` element it is the rect before that scale, and the fitted element
+   * adds `fitScale`. A windowed scroll adds `window`, and its content lists the live rows only.
+   * Works headless.
+   *
+   * @returns The root node; several roots come back under one `screen` node.
+   * @example
+   * ```ts
+   * // On an iPhone SE the 970 u board is drawn smaller to fit the slot between the bars.
+   * const screen = app.ui.tree();
+   * screen.children.map(child => child.key); // ["fitTop", "slot", "fitBottom"]
+   * const board = screen.children[1]?.children[0];
+   * board?.rect.w; // 970, the natural width
+   * board?.fitScale; // 0.805, the 781 u the slot leaves over 970 u
+   * ```
+   */
+  tree(): UiNode;
+  /**
+   * The entity of a keyed element, so a test can tap it and `anim` can aim at it. Popup roots
+   * come first, then the projection roots in layer order.
+   *
+   * @param key - The `key` prop of the element.
+   * @returns The entity, or `undefined` for an unknown or exiting element.
+   * @example
+   * ```ts
+   * // A headless scenario answers the gate through the button of the popup.
+   * app.input.tap(app.ui.find("claim") ?? 0); // true
+   * app.ui.find("nothing"); // undefined
+   * ```
+   */
+  find(key: string): Entity | undefined;
+  /**
+   * Reads the live screen against the five rules: a tap target under `tapTargetPt` at the size
+   * it is drawn (a `fit: "contain"` on it or above it shrinks it), a text that does not fit its
+   * box in some registered locale, an absolute element with no `reason`, a clipping element
+   * (`scroll`, `overflow: "hidden"`) whose style names a nine-slice it never draws, and a root
+   * element whose style sets a `zIndex` it ignores. Never throws; empty when nothing is mounted.
+   *
+   * @returns One finding per rule and element.
+   * @example
+   * ```ts
+   * // A game test keeps the board honest on an iPhone SE: a 140 u cell in the 0.8 slot.
+   * app.ui.lint(); // [{ rule: "tap-target", key: "cell", detail: "39 x 39 pt" }]
+   * // A list styled with a nine-slice: the clip keeps it from drawing.
+   * app.ui.lint(); // [{ rule: "nine-slice-clipped", key: "orders", detail: "scroll" }]
+   * // A screen root that asks to be drawn over the others: the layer decides that.
+   * app.ui.lint(); // [{ rule: "z-index-on-root", key: "board", detail: "zIndex 2" }]
+   * ```
+   */
+  lint(): readonly Finding[];
+  /**
+   * Types into a text field the way a player does, for a headless test or an agent: the field
+   * becomes the one being edited, `value` cut to its `maxLength` is written into it, and the
+   * local field it names is written, so the component re-renders on the next frame. Nothing
+   * reaches the gate: Enter submits.
+   *
+   * @param key - The `key` prop of the `input` element.
+   * @param value - The text to type.
+   * @returns True when the field took the text; false with one warning when no live `input` has
+   *   the key.
+   * @example
+   * ```ts
+   * // A headless test renames the player through the Rename popup.
+   * app.ui.fill("nameField", "Alex"); // true
+   * app.time.step(16);
+   * app.input.pressKey("Enter"); // true: the gate took { intent: "save", payload: { name: "Alex" } }
+   * app.ui.fill("nothing", "Alex"); // false, with the warning "ui:fill-without-input"
+   * ```
+   */
+  fill(key: string, value: string): boolean;
+};
+//#endregion
+export { SfxDescriptor as A, sequence as B, Config$3 as C, Target as D, State$3 as E, frames as F, stagger as G, sfx as H, haptic as I, wait as J, tween as K, mark as L, HAPTIC_KINDS as M, defineAnimation as N, types_d_exports$3 as O, external as P, parallel as R, AnimPlayerValue as S, MotionKeyframe as T, spawn as U, set as V, spawned as W, SceneSpec as _, AudioApi as a, types_d_exports$2 as b, MusicDescriptor as c, State$1 as d, types_d_exports$1 as f, SceneDefinition as g, LayerMap as h, types_d_exports as i, Step as j, HapticKind as k, MusicOptions as l, DefineScene as m, State as n, AudioContextLike as o, AnySceneProjection as p, use as q, UiApi as r, Config$1 as s, Config as t, SoundEntry as u, ScenesApi as v, FramesValue as w, AnimApi as x, State$2 as y, play as z };