@moku-labs/game 0.14.12 → 0.14.13

package/dist/{types-DOlpeuGx.d.mts → types-7GXcXxxv.d.mts}

@@ -1,4 +1,4 @@
-import { A as Api$2, B as ComponentType, Cn as Require, F as AnyComponent, H as Entity, Ht as Api$5, I as AnyComponentType, L as AnyComponentValue, Lt as Descriptor, O as Point$2, Q as ChangeHook, V as ComponentValue, Zt as Json, at as NumericFields, dt as Api$1, gn as Api, h as Api$3, it as MotionHandle, k as ViewportSize, ot as ProjectionMotion, rt as Motion, s as Events$1, t as Api$4, ut as ViewHandle, zt as Hint } from "./types-BjTtGSFb.mjs";
+import { Ar as Api, Br as Require, Gt as AnyComponentType, It as TransformValue, Jn as Descriptor, Kt as AnyComponentValue, Qn as Hint, T as Api$3, Wt as AnyComponent, Yt as ComponentType, Zt as Entity, bn as Api$1, bt as ViewportSize, dn as MotionCause, er as Answer, fn as MotionHandle, mn as ProjectionMotion, on as TagType, pn as NumericFields, s as Events$1, sn as ChangeHook, t as Api$4, tr as Api$5, un as Motion, ur as Json, yn as ViewHandle, zt as Api$2 } from "./types-BGcda5Le.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 
@@ -329,10 +329,10 @@ type Tokens = {
  */
 type StylesState = {
   flags: WhenFlags;
-  viewport: ViewportSize | undefined;
+  viewport: Readonly<ViewportSize> | undefined;
 };
 declare namespace types_d_exports$2 {
-  export { Argument, CompiledMessage, CompiledMessages, Config$2 as Config, DurationStyle, ElementNode, Events, I18nApi, I18nCtx, I18nKit, IntlKit, KeysWithoutParameters, Message, Part, RegisteredModule, ResolvedModule, State$2 as State, StringTable, StringsLoader, TypedTr };
+  export { Argument, CompiledMessage, CompiledMessages, Config$2 as Config, DurationStyle, ElementNode, Events, I18nApi, I18nCtx, I18nKit, IntlKit, KeysWithoutParameters, Message, Part, RegisteredModule, ResolvedModule, State$2 as State, StringTable, StringsLoader, TextKey, TypedTr };
 }
 /**
  * One interface element handed to a message as a parameter. Structural on purpose: it mirrors
@@ -489,6 +489,11 @@ type Config$2 = {
 type RegisteredModule = {
   /** The feature that brought the module, or `"pluginConfigs.i18n"` for a configured one. */from: string; /** The module itself, or the loader that fetches it on first use. */
   messages: CompiledMessages | StringsLoader;
+  /**
+   * Set for a sub-feature's lazy module: the bundle it loads and unloads with. Its loader is kept
+   * and never replaced.
+   */
+  bundle?: string;
 };
 /**
  * One registered module whose loader already ran, ready to be merged into a locale.
@@ -501,24 +506,38 @@ type ResolvedModule = {
  * i18n plugin state.
  */
 type State$2 = {
-  /** The current locale; `config.locale` until `setLocale`. */locale: string; /** Per locale, one entry per feature and one for the config, filled in `onStart`. */
-  registered: Map<string, RegisteredModule[]>; /** Merged and resolved modules per locale. */
+  /** The current locale; `config.locale` until `setLocale`. */locale: string;
+  /**
+   * Per locale, one entry per feature and one for the config, filled in `onStart`. Coupled
+   * entries keep their loader.
+   */
+  registered: Map<string, RegisteredModule[]>; /** Merged modules per locale: resolved non-coupled modules plus the coupled modules of loaded bundles. */
   loaded: Map<string, CompiledMessages>; /** One kit per locale, built on first use. */
-  intl: Map<string, IntlKit>; /** Keys already reported missing, so each warns once. */
-  warned: Set<string>; /** The `setLocale` in flight; a later call waits for it. */
-  loading: Promise<void> | undefined;
+  intl: Map<string, IntlKit>; /** Keys already reported missing (or of a bundle not loaded), so each warns once. */
+  warned: Set<string>; /** The strings load in flight (start, `setLocale` or a bundle); the next one waits for it. */
+  loading: Promise<void> | undefined; /** Bundles assets reported loaded, each with the token of the load that brought it. */
+  held: Map<string, symbol>; /** Resolved coupled modules while their bundle is loaded: bundle to locale to messages. */
+  bundled: Map<string, Map<string, CompiledMessages>>; /** Sub-features whose lazy strings live with the bundle of their name. Filled in `onStart`. */
+  coupled: Set<string>; /** True once `onStart` collected the registry; before that a companion call only records the bundle. */
+  started: boolean;
 };
 /**
  * i18n plugin events.
  */
 type Events = {
-  /** The current locale changed, or its messages were replaced. */"i18n:locale-changed": {
+  /**
+   * The current locale changed, its messages were replaced, or the strings of a bundle arrived
+   * for a key shown missing.
+   */
+  "i18n:locale-changed": {
     locale: string;
   };
 };
 /**
  * i18n plugin API, `app.i18n`. Messages are data everywhere else in the game; this is the one
- * place a locale is read and a sentence becomes parts.
+ * place a locale is read and a sentence becomes parts. `Key` is what `isKey` narrows to: the app
+ * of a game (`game.screen().app`) carries `I18n.TextKey<Strings>` of its generated table; an engine
+ * plugin's `ctx.require(i18nPlugin)` has no table, and `isKey` narrows to `string`.
  *
  * @example
  * ```ts
@@ -528,7 +547,7 @@ type Events = {
  * app.i18n.plain(tr("hud.orders", { n: 3 })); // "3 orders"
  * ```
  */
-type I18nApi = {
+type I18nApi<Key extends string = string> = {
   /**
    * The locale every `format` without a second argument reads.
    *
@@ -541,8 +560,9 @@ type I18nApi = {
   locale(): string;
   /**
    * Switches the current locale. A lazy module is imported once, then `i18n:locale-changed` is
-   * emitted; `text` re-resolves every message on it. A call for the locale already current
-   * resolves at once and emits nothing.
+   * emitted; `text` re-resolves every message on it. The modules of every sub-feature whose bundle
+   * is loaded are imported for the new locale before the event; a sub-feature whose bundle is not
+   * loaded is left alone. A call for the locale already current resolves at once and emits nothing.
    *
    * @param locale - The locale to switch to.
    * @returns A promise that settles when the messages of that locale are loaded.
@@ -552,12 +572,16 @@ type I18nApi = {
    * // features/settings/nodes.ts: the language button of the settings screen.
    * await app.i18n.setLocale("en"); // loads the compiled module, then emits i18n:locale-changed
    * app.i18n.locale(); // "en"
+   * // The ward of episode 1 is on screen (bundle "ep01" loaded): strings.ep01.en came with the switch.
+   * app.i18n.plain(tr("ep01.ward.title")); // "Ward"
    * ```
    */
   setLocale(locale: string): Promise<void>;
   /**
    * Formats a message in the current locale. Resolution order is the current locale, then
    * `config.fallback`, then missing: a missing key gives one text part `⟦key⟧` and one warning.
+   * A key of a sub-feature whose strings live with its bundle, while that bundle is not loaded,
+   * gives `⟦key⟧` too, and its one warning names the bundle.
    *
    * @param message - What `tr` returned.
    * @returns The parts of the sentence, adjacent text merged.
@@ -565,12 +589,14 @@ type I18nApi = {
    * ```ts
    * // text resolves the `content` of a Text component every time the locale changes.
    * app.i18n.format(tr("hud.orders", { n: 3 })); // [{ kind: "text", text: "3 заказа" }]
+   * // Bundle "ep01" is not loaded: one warn "i18n: the bundle of a key is not loaded" { bundle: "ep01" }
+   * app.i18n.format(tr("ep01.ward.title")); // [{ kind: "text", text: "⟦ep01.ward.title⟧" }]
    * ```
    */
   format(message: Message): readonly Part[];
   /**
    * Formats a message in another registered locale, without switching. `ui.lint` measures a
-   * label in every locale this way.
+   * label in every locale this way. Every loaded locale carries the strings of every loaded bundle.
    *
    * @param message - What `tr` returned.
    * @param locale - The registered locale to read.
@@ -597,7 +623,8 @@ type I18nApi = {
    */
   plain(message: Message): string;
   /**
-   * Tells whether a key exists in the current locale or in the fallback.
+   * Tells whether a key exists in the current locale or in the fallback. A key of a sub-feature
+   * whose bundle is not loaded answers false.
    *
    * @param key - The message key.
    * @returns True when `format` would find a message for it.
@@ -605,9 +632,37 @@ type I18nApi = {
    * ```ts
    * // A projection hides the label of an order that has no description yet.
    * app.i18n.has("orders.hint"); // false: no locale brought that key
+   * app.i18n.has("ep01.ward.title"); // false until bundle "ep01" is loaded, then true
    * ```
    */
   has(key: string): boolean;
+  /**
+   * Tells whether a value read from saved JSON is a key the game still has: a key of the loaded
+   * tables of the current locale or of the fallback. For a key of a sub-feature whose strings are
+   * not loaded yet it answers by the prefix: `"<feature>."` of a known sub-feature that has strings
+   * is accepted (the exact key is checked when its bundle loads, and `text` shows `⟦key⟧` and warns
+   * once if it does not exist). Anything that is not a string answers false. The compiled tables
+   * carry no parameter list, so a key that takes parameters answers true as well: the check is
+   * for a key renamed or removed since the save was written. Call it where the app is: an effect
+   * handler, app or page code, the code that loads a save. On the app of a game a true answer types
+   * the value as a key `tr` takes alone (`I18n.TextKey<Strings>`); through
+   * `ctx.require(i18nPlugin)` it types it as a `string`.
+   *
+   * @param value - What the save or a data source holds.
+   * @returns True when the value is a key of the game's tables; it is then typed as one.
+   * @example
+   * ```ts
+   * // The page restores the toast kept in the save before it shows it.
+   * const { app } = game.screen();
+   * await app.start();
+   * app.i18n.isKey("ui.toast.saved"); // true: the value is typed TextKey, so tr takes it alone
+   * app.i18n.isKey("ui.toast.removedLastYear"); // false: renamed since, the toast shows its fallback
+   * app.i18n.isKey(3); // false: not a string
+   * // An engine plugin asks the same question; a true answer types the value as a string.
+   * ctx.require(i18nPlugin).isKey("casefile.title"); // true while the casefile bundle is not loaded
+   * ```
+   */
+  isKey(value: unknown): value is Key;
   /**
    * Formats milliseconds in the current locale through `Intl.DurationFormat`. The value is rounded
    * up to whole seconds, so a countdown never reads zero while time is left; a negative or
@@ -628,7 +683,8 @@ type I18nApi = {
    */
   duration(ms: number, style?: DurationStyle): string;
   /**
-   * Every locale at least one feature or the config brought a module for, sorted.
+   * Every locale at least one feature, sub-feature or the config brought a module for, sorted. A
+   * sub-feature's lazy module counts while its bundle is not loaded.
    *
    * @returns The registered locales.
    * @example
@@ -640,19 +696,23 @@ type I18nApi = {
   locales(): readonly string[];
   /**
    * Swaps the compiled module of one feature in a loaded locale, for the dev hot swap. The one
-   * registered module whose keys overlap `messages` takes them, the locale is merged again and
-   * every key may warn once more. When the locale is the current one or the fallback,
-   * `i18n:locale-changed` is emitted with the current locale, so `text` re-resolves every label.
-   * A locale not loaded yet is left alone: its loader imports the new module later.
+   * module in memory whose keys overlap `messages` takes them (a sub-feature's module of a loaded
+   * bundle included), the locale is merged again and every key may warn once more. When the locale
+   * is the current one or the fallback, `i18n:locale-changed` is emitted with the current locale,
+   * so `text` re-resolves every label. A locale not loaded yet, and the module of a sub-feature
+   * whose bundle is not loaded, are left alone: the loader imports the new module later.
    *
-   * @param locale - The locale of the saved `generated/strings.<locale>.ts`.
+   * @param locale - The locale of the saved `generated/strings.<locale>.ts` or `strings.<feature>.<locale>.ts`.
    * @param messages - The `default` export of the new module.
-   * @throws {Error} When no registered module, or more than one, shares a key with `messages`.
+   * @throws {Error} When no module in memory, or more than one, shares a key with `messages`.
    * @example
    * ```ts
    * // ui's hot swap: generated/strings.ru.ts was written again with "hud.orders" as "3 заказа!".
    * ctx.require(i18nPlugin).replace("ru", next.default); // emits i18n:locale-changed
    * app.i18n.plain(tr("hud.orders", { n: 3 })); // "3 заказа!": text redraws the label
+   * // generated/strings.ep01.ru.ts was written again while bundle "ep01" is loaded.
+   * ctx.require(i18nPlugin).replace("ru", next.default); // emits i18n:locale-changed
+   * app.i18n.plain(tr("ep01.ward.title")); // "Палата!"
    * ```
    */
   replace(locale: string, messages: CompiledMessages): void;
@@ -667,7 +727,8 @@ type I18nApi = {
 type I18nCtx = PluginCtx<Config$2, State$2, Events> & {
   readonly global: object;
   readonly log: Log.LogApi;
-  readonly require: Require;
+  readonly require: Require; /** Whether a plugin of that name is composed, whatever its place in the list. */
+  readonly has: (name: string) => boolean;
 };
 /**
  * The key-to-parameters table a game generates: `generated/strings.ts` exports it as `Strings`.
@@ -690,6 +751,21 @@ type StringTable = Record<string, unknown>;
  * ```
  */
 type KeysWithoutParameters<Table extends StringTable> = { [Key in keyof Table]: Record<never, never> extends Table[Key] ? Key : never }[keyof Table] & string;
+/**
+ * The keys of a string table that take no parameters: what a data table or a save may hold and
+ * `tr` takes alone. Derived from the `Strings` type `moku-game keys` already writes (a key whose
+ * parameters are `Record<string, never>`), so no list is generated and the type cannot drift from
+ * the table.
+ *
+ * @example
+ * ```ts
+ * // core/tables.ts of a game
+ * import type { Strings } from "@generated/strings";
+ * type HintKey = I18n.TextKey<Strings>; // "board.hint.blue" | "board.hint.red" | …, never "hud.orders"
+ * export const generators: Record<string, { readonly hint: HintKey }> = { red: { hint: "board.hint.red" } };
+ * ```
+ */
+type TextKey<Table extends StringTable> = KeysWithoutParameters<Table>;
 /**
  * `tr` as one game reads it: the key is checked against the generated table, and the parameters
  * are the ones that key declares. A key with no parameters takes no second argument.
@@ -714,214 +790,22 @@ type TypedTr<Table extends StringTable> = {
  * ```
  */
 type I18nKit<Table extends StringTable> = {
-  tr: TypedTr<Table>;
-};
-//#endregion
-//#region src/plugins/renderer/components.d.ts
-/**
- * Where a view sits, in reference units and radians. Relative to the `Parent` when there is one.
- * `pivot` is the local point the view turns and scales around, and `x`, `y` is where that point
- * lands; the default pivot `{ x: 0, y: 0 }` is the view's own origin.
- *
- * @example
- * ```ts
- * // A 200 x 80 button that grows around its centre.
- * const value: TransformValue = {
- *   x: 640, y: 340, rotation: 0, scale: 1.1, pivot: { x: 100, y: 40 }
- * };
- * ```
- */
-type TransformValue = {
-  x: number;
-  y: number;
-  rotation: number;
-  scale: number;
-  pivot: Point$2;
-};
-/**
- * How a sized sprite fills its box: `"fill"` stretches, `"contain"` scales uniformly inside the
- * box and centres, `"cover"` scales uniformly over the box and crops the overflow.
- *
- * @example
- * ```ts
- * const fit: SpriteFit = "cover";
- * ```
- */
-type SpriteFit = "fill" | "contain" | "cover";
-/**
- * One textured quad. `texture` is an asset key; `defineGame` narrows it to the game's keys.
- * `width` and `height` are the box in reference units; 0 on an axis keeps the texture's own size
- * there. `anchor` is the point of the box that sits on the `Transform`. `alpha` fades the quad
- * and the entity's children.
- *
- * @example
- * ```ts
- * const value: SpriteValue = {
- *   texture: "board.bg-forest-meadow", tint: 0xffffff, alpha: 1, anchor: { x: 0, y: 0 },
- *   width: 1080, height: 1920, fit: "cover"
- * };
- * ```
- */
-type SpriteValue = {
-  texture: string;
-  tint: number;
-  alpha: number;
-  anchor: Point$2;
-  width: number;
-  height: number;
-  fit: SpriteFit;
-};
-/**
- * A stretchable panel. The slice borders come with the texture, not with the component. `debug`
- * strokes the bounds and the four cut lines over the panel: cyan, red when the corners overlap or
- * the texture is missing. `clip` masks the children of the entity to the `width × height` box,
- * the same rule as `Shape.clip`: the mask is a filled rectangle and is never drawn, and the panel
- * itself is never masked. `alpha` fades the panel and the entity's children.
- *
- * @example
- * ```ts
- * const value: NineSliceValue = {
- *   texture: "ui.panel", width: 600, height: 320, alpha: 1, tint: 0xffffff, debug: false,
- *   clip: false
- * };
- * // The board tray, outlined while its insets are checked.
- * const tray: NineSliceValue = {
- *   ...value, texture: "board.board-tray", width: 1000, height: 1040, debug: true
- * };
- * // A text field: a long value never draws outside the frame.
- * const field: NineSliceValue = {
- *   ...value, texture: "ui.field", width: 480, height: 96, clip: true
- * };
- * ```
- */
-type NineSliceValue = {
-  texture: string;
-  width: number;
-  height: number;
-  alpha: number;
-  tint: number;
-  debug: boolean;
-  clip: boolean;
-};
-/**
- * The escape hatch: the game owns a Pixi object and `sync` only attaches and detaches it.
- *
- * @example
- * ```ts
- * const value: DisplayValue = { object: spineAnimation };
- * ```
- */
-type DisplayValue = {
-  object: unknown;
-};
-/**
- * A filled rounded rectangle or a triangle, anchored at the top left of the `Transform`. `kind`
- * picks the outline: `"rect"` (the default) or `"triangle"`, which fills its `w × h` box pointing
- * right (rotate the element for another direction) and ignores `radius`. `fillAlpha` is the alpha
- * of the fill alone: 0 draws only the stroke, a ring. `alpha` fades the whole shape and the
- * entity's children: a disabled button at 0.6 draws its icon at 0.6 too. `dash` is the
- * dash length of the stroke in reference units, with gaps of half a dash; 0 strokes a solid line.
- * `clip` masks the children of the entity to the shape, always solid, which is how `ui` draws a
- * scroll and an overflow. The shape itself is never masked, so its stroke is drawn whole.
- *
- * @example
- * ```ts
- * const value: ShapeValue = {
- *   kind: "rect", w: 320, h: 96, fill: 0x101018, fillAlpha: 1, alpha: 1, radius: 16,
- *   stroke: 0x000000, strokeWidth: 0, dash: 0, clip: false
- * };
- * // The honey ring on a selected cell: a stroke and no fill.
- * const ring: ShapeValue = {
- *   kind: "rect", w: 140, h: 140, fill: 0xffffff, fillAlpha: 0, alpha: 1, radius: 24,
- *   stroke: 0xffc233, strokeWidth: 6, dash: 0, clip: false
- * };
- * // The play glyph of a watch button, and a dashed focus ring: 10 u dashes, 5 u gaps.
- * const play: ShapeValue = { ...ring, kind: "triangle", w: 36, h: 40, fillAlpha: 1, strokeWidth: 0 };
- * const focus: ShapeValue = { ...ring, w: 200, h: 80, stroke: 0x3a2212, strokeWidth: 4, dash: 10 };
- * ```
- */
-type ShapeValue = {
-  kind: "rect" | "triangle";
-  w: number;
-  h: number;
-  fill: number;
-  fillAlpha: number;
-  alpha: number;
-  radius: number;
-  stroke: number;
-  strokeWidth: number;
-  dash: number;
-  clip: boolean;
-};
-/**
- * What `sprite()` takes: the two things every visual needs, and the four that have defaults.
- *
- * @example
- * ```ts
- * const options: SpriteOptions = { texture: "board.cell", at: { x: 540, y: 300 } };
- * ```
- */
-type SpriteOptions = {
-  texture: string;
-  at: Point$2;
-  tint?: number;
-  alpha?: number;
-  anchor?: Point$2;
-  scale?: number;
+  /** `tr`, checked against the game's table. */tr: TypedTr<Table>;
+  /**
+   * Checks a key that does not take parameters against the game's table and returns it, typed:
+   * what a data table stores instead of a `string`. The same string at run time.
+   *
+   * @param key - A key of the game's table that takes no parameters.
+   * @returns The same key, typed as its literal.
+   * @example
+   * ```ts
+   * // core/tables.ts of a game: the hint of every generator, checked when the table is written.
+   * export const generators = { red: { hint: key("board.hint.red") }, blue: { hint: key("board.hint.blue") } };
+   * tr(generators.red.hint); // { key: "board.hint.red" }
+   * ```
+   */
+  key: <const Key extends TextKey<Table>>(key: Key) => Key;
 };
-/**
- * Where a view sits: reference units, radians, uniform scale, and the local point it turns
- * around.
- */
-declare const Transform: ComponentType<TransformValue>;
-/**
- * One textured quad. `texture` is an asset key, resolved through the texture providers; a size
- * and a `fit` draw it into a box.
- */
-declare const Sprite: ComponentType<SpriteValue>;
-/**
- * A stretchable panel, sized in reference units, with its own alpha and tint. `debug: true` draws
- * the slice outline over it. `clip: true` masks the children of the entity to the panel box.
- */
-declare const NineSlice: ComponentType<{
-  texture: string;
-  width: number;
-  height: number;
-  alpha: number;
-  tint: number;
-  debug: boolean;
-  clip: boolean;
-}>;
-/**
- * The entity this view moves with. `0` means no parent.
- */
-declare const Parent: ComponentType<{
-  entity: number;
-}>;
-/**
- * A display object the game owns. Never pooled, never destroyed by `sync`.
- */
-declare const Display: ComponentType<DisplayValue>;
-/**
- * A filled rounded rectangle or a right-pointing triangle, drawn with Pixi `Graphics` and redrawn
- * only when a field changed. `fillAlpha: 0` draws only the stroke, `dash` above 0 dashes it.
- * `clip: true` masks the children of the entity to the shape.
- */
-declare const Shape: ComponentType<ShapeValue>;
-/**
- * Bundles the two components every visual needs, so a projection `view` reads as one line.
- *
- * @param options - Texture key, position, and the four values that have defaults.
- * @returns The `Sprite` and the `Transform` value, in that order.
- * @example
- * ```ts
- * sprite({ texture: "board.cell", at: { x: 540, y: 300 } });
- * // [Sprite({ texture: "board.cell", tint: 0xffffff, alpha: 1, anchor: { x: 0.5, y: 0.5 },
- * //   width: 0, height: 0, fit: "fill" }),
- * //  Transform({ x: 540, y: 300, rotation: 0, scale: 1, pivot: { x: 0, y: 0 } })]
- * ```
- */
-declare function sprite(options: SpriteOptions): [ComponentValue<SpriteValue>, ComponentValue<TransformValue>];
 declare namespace types_d_exports$1 {
   export { Carried, Config$1 as Config, Deps$1 as Deps, Direction, GesturePhase, InputApi, InputCtx, KernelSlice$1 as KernelSlice, KeyInput, KeyListener, Point$1 as Point, PointerListener, RawSample, State$1 as State, TapListener, Target };
 }
@@ -1099,8 +983,14 @@ type Carried = {
  */
 type State$1 = {
   /** Written by the DOM handlers, drained by the frame step. */samples: RawSample[];
-  phase: GesturePhase; /** The one active pointer. A sample of any other pointer is dropped while this is set. */
-  pointerId: number | undefined; /** The pressed or held entity. */
+  phase: GesturePhase;
+  /**
+   * The one followed pointer. A sample of any other pointer is dropped while this is set, except
+   * a press while this pointer rests (phase `pressed`, not `moved`): that press takes the pointer
+   * over and cancels the resting press.
+   */
+  pointerId: number | undefined; /** The followed pointer left the tap slop since its press: it started a gesture and keeps the pointer. */
+  moved: boolean; /** The pressed or held entity. */
   entity: Entity | undefined; /** The projection key of `entity`, read once at press time. */
   key: {
     projection: string;
@@ -2282,6 +2172,21 @@ declare const Box: ComponentType<{
  * and `ui` merges the patch into the nearest component instance.
  */
 declare const LocalWrite: ComponentType<LocalWriteValue>;
+/**
+ * On the view a player taps five times within three seconds to open the editor's overlay on a debug build: the
+ * version line of the settings, usually. One helper on top of `app.debug.overlay.open()`; a game that wants another
+ * gesture calls that itself. The view must take a press (a `button`, or any element with `Touchable`); a `button`
+ * that names no intent is the plain choice. Without the agent flag the tag does nothing.
+ *
+ * @example
+ * ```tsx
+ * // The version line of the settings sheet. Five taps open the overlay of `moku-game build --debug` on the phone.
+ * <button key="versionLine" style={versionLineStyle} components={[DebugTrigger()]}>
+ *   <text key="version" style="settings.version" content={tr("settings.version", { version: "1.4.0" })} />
+ * </button>
+ * ```
+ */
+declare const DebugTrigger: TagType;
 /**
  * Builds the effect a node awaits to show a popup. The gate opens for the outcomes of the
  * component, so the node resolves with the intent one of its buttons answered. `over` names the
@@ -2300,6 +2205,7 @@ declare const LocalWrite: ComponentType<LocalWriteValue>;
  * });
  * popup(Reward, { gold: 5 });
  * // { kind: "popup", payload: { component: "Reward", props: { gold: 5 } }, answers: ["claim"] }
+ * await fx(popup(Reward, { gold: 5 })); // Answer<"claim">: { intent: "claim" }
  * ```
  * @example
  * ```ts
@@ -2313,9 +2219,9 @@ declare const LocalWrite: ComponentType<LocalWriteValue>;
  * //   answers: ["reset", "cancel"] }
  * ```
  */
-declare function popup<Properties extends object, Local extends object>(component: PopupComponent<Properties, Local>, props: Properties, options?: {
+declare function popup<Properties extends object, Local extends object, Outcomes extends Record<string, unknown>>(component: PopupComponent<Properties, Local, Outcomes>, props: Properties, options?: {
   over?: string;
-}): Descriptor;
+}): Descriptor<Answer<keyof Outcomes & string>>;
 //#endregion
 //#region src/plugins/ui/jsx/types.d.ts
 /**
@@ -2421,14 +2327,15 @@ type ComponentDefinition<Properties extends object = object, Local extends objec
 /**
  * A component that names outcomes, which is what `popup` takes. `Local` stays a parameter
  * because the `local` argument of `view` is contravariant: pinned to `object` it would refuse
- * every component that keeps local state.
+ * every component that keeps local state. `Outcomes` are its outcomes, so the popup's answer names
+ * one of them.
  *
  * @example
  * ```ts
- * const settings: PopupComponent<{ volume: number }, { tab: string }> = Settings;
+ * const settings: PopupComponent<{ volume: number }, { tab: string }, { close: { saved: boolean } }> = Settings;
  * ```
  */
-type PopupComponent<Properties extends object, Local extends object = object> = ComponentDefinition<Properties, Local, Record<string, unknown>>;
+type PopupComponent<Properties extends object, Local extends object = object, Outcomes extends Record<string, unknown> = Record<string, unknown>> = ComponentDefinition<Properties, Local, Outcomes>;
 /**
  * A component definition with its type arguments erased, as the registry stores it.
  */
@@ -2484,13 +2391,21 @@ type StyleBasis = {
  * `measuredSize` what its measure function last answered, before Yoga's clamp: a bound text whose
  * new string measures the same asks for no solve. `basis` is what `style` was resolved on, set
  * once the style is on the layout node and the components are written; an element without one is
- * patched in full at its next patch.
+ * patched in full at its next patch. `index` is its place among the element children of its parent
+ * at the last diff (0 for a root element): with its `zIndex` it gives the child its `Order`.
+ * `cause` is why the element appeared: `"mount"` when it came with the first build of its root and
+ * the root came by a mount, `"change"` otherwise; its `enter` hook is told. `rebuilds` counts the
+ * patches in a row that brought a loop of another reference that is not really another loop: a
+ * dev build names the element once it reaches three.
  */
 type Element = {
   entity: Entity;
   identity: string;
   type: string;
   key: string | undefined;
+  index: number;
+  cause: MotionCause;
+  rebuilds: number;
   parentType: string | undefined;
   root: Entity;
   node: DescriptionNode;
@@ -2545,7 +2460,10 @@ type PopupLink = {
 /**
  * One reconciled tree: a projection view or a popup, with the flags the frame step reads.
  * `covered` is true while the root is kept under another popup; every element of the root then
- * resolves `is.covered`.
+ * resolves `is.covered`. `cause` is how the root came, read at its first build: `"change"` for a
+ * popup (its open is an event), the cause of its projection view otherwise, `"mount"` after a
+ * restore or a load. `slot` is the host element the root is laid out in (`undefined` for the
+ * viewport), `slotRect` the content box it was last solved in, in the host's own units.
  */
 type Root = {
   entity: Entity;
@@ -2558,6 +2476,14 @@ type Root = {
   element: Entity | undefined;
   popup: PopupLink | undefined;
   covered: boolean;
+  cause: MotionCause | undefined;
+  slot: Entity | undefined;
+  slotRect: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+  } | undefined;
 };
 /**
  * Where the focus ring was last drawn: the layer and order of its root, the rect grown by the
@@ -2699,7 +2625,10 @@ type JsxState = {
   exiting: Set<Entity>;
   removing: Set<Entity>;
   hosts: Set<Entity>;
-  hosted: Map<Entity, Entity>;
+  hosted: Map<Entity, Entity>; /** The host elements that became live in this solve: the solve hosts their views in the same frame (spec 16 U2). */
+  risen: Set<Entity>; /** The views the full hosting step of this frame took back from their host; their removal lands at the flush. */
+  released: Set<Entity>; /** The cause the elements entered by the diff running now take: the root's for its first build, else `"change"`. */
+  building: MotionCause | undefined;
   reconciles: number;
   focus: FocusState;
   fields: Map<Entity, Field>;
@@ -2716,7 +2645,10 @@ type JsxState = {
    */
   epoch: number;
   styled: number;
-  written: number;
+  written: number; /** The wall times of the last taps on a `DebugTrigger` view, five at the most. */
+  debugTaps: number[]; /** Whether `ui:debug-trigger-no-agent` was logged: once per app. */
+  debugWarned: boolean; /** Elements that carry `Overlay`, from their enter to their despawn (spec 22 O4.5). */
+  overlays: Set<Entity>;
 };
 /**
  * One node of the snapshot `tree()` answers with. `rect` is natural: under a `fit` ancestor it
@@ -2825,4 +2757,4 @@ type CommonProps = {
   components?: ElementComponents;
 };
 //#endregion
-export { types_d_exports$2 as $, InputApi as A, SpriteOptions as B, TextFormat as C, types_d_exports as D, TextValue as E, NineSliceValue as F, Argument as G, Transform as H, Parent as I, IntlKit as J, Config$2 as K, Shape as L, types_d_exports$1 as M, Display as N, defineComponent as O, NineSlice as P, TypedTr as Q, ShapeValue as R, TextBind as S, TextStyles as T, TransformValue as U, SpriteValue as V, sprite as W, Part as X, Message as Y, State$2 as Z, Config as _, JsxChild as a, State as b, UiNode as c, popup as d, IsFlags as et, defineTokens as f, BindOptions as g, BindField as h, Finding as i, WhenFlags as it, State$1 as j, Config$1 as k, Box as l, UiIntrinsicElements as m, ElementChange as n, Style as nt, JsxState as o, IntrinsicElementsFor as p, I18nApi as q, ElementMotion as r, StylesState as rt, PopupComponent as s, DescriptionNode as t, ResolvedStyle as tt, LocalWrite as u, CountdownValue as v, TextStyleInput as w, TextApi as x, Point as y, Sprite as z };
+export { Config$1 as A, State$2 as B, TextBind as C, TextValue as D, TextStyles as E, Config$2 as F, IsFlags as G, TextKey as H, I18nApi as I, StylesState as J, ResolvedStyle as K, IntlKit as L, State$1 as M, types_d_exports$1 as N, types_d_exports as O, Argument as P, Message as R, TextApi as S, TextStyleInput as T, TypedTr as U, StringTable as V, types_d_exports$2 as W, WhenFlags as Y, BindOptions as _, JsxChild as a, Point as b, UiNode as c, LocalWrite as d, popup as f, BindField as g, UiIntrinsicElements as h, Finding as i, InputApi as j, defineComponent as k, Box as l, IntrinsicElementsFor as m, ElementChange as n, JsxState as o, defineTokens as p, Style as q, ElementMotion as r, PopupComponent as s, DescriptionNode as t, DebugTrigger as u, Config as v, TextFormat as w, State as x, CountdownValue as y, Part as z };