@moku-labs/game 0.0.2 → 0.1.0

package/dist/types-CqkrEY06.d.mts

@@ -0,0 +1,1734 @@
+import { A as TrackSegment, At as Json, E as NumericFields, F as ComponentHandle, I as ComponentType, M as AnyComponent, P as AnyComponentValue, R as Entity, St as Api, T as MotionHandle, _t as TypeTag, h as Api$2, k as TrackOptions, nn as Require, q as Api$1, t as Api$3, x as Ease } from "./types-BZ1OLf24.mjs";
+import { o as Events$1, t as Api$4 } from "./types-C47fKNcn.mjs";
+import { F as Events$2, H as InputApi, I as I18nApi, L as Message, c as UiNode, i as Finding, n as ElementChange, o as JsxState, r as ElementMotion, v as StylesState } from "./types-X9jXjka3.mjs";
+import { Log } from "@moku-labs/common/browser";
+import { PluginCtx } from "@moku-labs/core";
+import { Node, Yoga } from "yoga-layout/load";
+
+//#region src/plugins/text/types.d.ts
+declare namespace types_d_exports$2 {
+  export { AdvanceTable, BundleLoaded, BundleUnloaded, Config$2 as Config, Deps$2 as Deps, DrawnLabel, IconRun, KernelSlice$2 as KernelSlice, LayoutOptions, Line, LocaleChanged, Point, Run, SeenText, Size, State$2 as State, TextAlign, TextApi, TextBind, TextCtx, TextLayout, TextRun, TextShadow, TextStyle, TextStyleInput, TextStyles, TextValue, TextWrap, Warn };
+}
+/**
+ * A point in reference units: where a label sits, and which point of the block sits there.
+ *
+ * @example
+ * ```ts
+ * const anchor: Point = { x: 0.5, y: 0.5 };
+ * ```
+ */
+type Point = {
+  x: number;
+  y: number;
+};
+/**
+ * The size of a measured block, in reference pixels.
+ *
+ * @example
+ * ```ts
+ * const size: Size = { width: 57.6, height: 38.4 };
+ * ```
+ */
+type Size = {
+  width: number;
+  height: number;
+};
+/**
+ * Which numeric component field a label shows. The component is named, not imported: a HUD is
+ * written before the game's components are in scope.
+ *
+ * @example
+ * ```ts
+ * const bind: TextBind = { component: "Counter", field: "value" };
+ * ```
+ */
+type TextBind = {
+  component: string;
+  field: string;
+};
+/**
+ * What the `Text` component holds. `resolved` is engine-owned: a game writes `content`, `style`,
+ * `bind`, `anchor` and `alpha`, and reads `resolved`. `alpha` fades every run, shadow and icon of
+ * the block together, 1 by default; a change is written in place and a tween can drive it.
+ *
+ * @example
+ * ```ts
+ * const value: TextValue = {
+ *   content: "+5", style: "body", bind: undefined, anchor: { x: 0.5, y: 0.5 }, alpha: 1,
+ *   resolved: "+5"
+ * };
+ * // The hint of an empty name field, at half alpha.
+ * const hint: TextValue = { ...value, content: "Your name", alpha: 0.5, resolved: "Your name" };
+ * ```
+ */
+type TextValue = {
+  content: string | Message;
+  style: string;
+  bind: TextBind | undefined;
+  anchor: Point;
+  alpha: number;
+  resolved: string;
+};
+/**
+ * Where the lines of a block sit inside the widest of them.
+ *
+ * @example
+ * ```ts
+ * const align: TextAlign = "center";
+ * ```
+ */
+type TextAlign = "left" | "center" | "right";
+/**
+ * The wrap width of a style in reference pixels, or `"none"` for one line per `\n` segment.
+ *
+ * @example
+ * ```ts
+ * const wrap: TextWrap = 480;
+ * ```
+ */
+type TextWrap = number | "none";
+/**
+ * The drop shadow of a style as the plugin stores it: a copy of every glyph run in `color`, at
+ * `alpha`, moved by `dx` and `dy` reference pixels.
+ *
+ * @example
+ * ```ts
+ * const shadow: TextShadow = { color: 0x5b3a1e, dx: 0, dy: 4, alpha: 1 };
+ * ```
+ */
+type TextShadow = {
+  color: number;
+  dx: number;
+  dy: number;
+  alpha: number;
+};
+/**
+ * One style as a game writes it: the font and the size are required, the rest has defaults.
+ *
+ * @example
+ * ```ts
+ * // A popup title: cream display glyphs over a brown shadow 4 px down.
+ * const title: TextStyleInput = {
+ *   font: "ui.font-display", size: 56, fill: 0xfff3d6, shadow: { color: 0x5b3a1e, dx: 0, dy: 4 }
+ * };
+ *
+ * defineTextStyles({ "popup.title": title }).map["popup.title"]?.shadow;
+ * // { color: 0x5b3a1e, dx: 0, dy: 4, alpha: 1 }
+ * ```
+ */
+type TextStyleInput = {
+  font: string;
+  bold?: string;
+  italic?: string;
+  size: number;
+  fill: number; /** The outline colour. Drawn only when `strokeWidth` is above 0. */
+  stroke?: number;
+  /**
+   * The outline width in reference px: 8 copies of each glyph run on a circle this wide (12 from 6
+   * on), tinted `stroke`. 0 draws none. It never changes what `measure` answers.
+   */
+  strokeWidth?: number;
+  letterSpacing?: number;
+  align?: TextAlign;
+  wrap?: TextWrap;
+  digits?: boolean;
+  /**
+   * A drop shadow under every glyph run, in reference px at the style size. `alpha` is 1 when
+   * left out. It never changes what `measure` answers.
+   */
+  shadow?: {
+    color: number;
+    dx: number;
+    dy: number;
+    alpha?: number;
+  };
+};
+/**
+ * One style as the plugin stores it: every field filled, `bold` and `italic` only when the game
+ * shipped those MSDF fonts, `shadow` only when the style has one.
+ *
+ * @example
+ * ```ts
+ * const style: TextStyle = {
+ *   font: "ui.font-body", bold: undefined, italic: undefined, size: 32, fill: 0xffffff,
+ *   stroke: 0x000000, strokeWidth: 0, letterSpacing: 0, align: "left", wrap: "none",
+ *   digits: false, shadow: undefined
+ * };
+ * ```
+ */
+type TextStyle = {
+  font: string;
+  bold: string | undefined;
+  italic: string | undefined;
+  size: number;
+  fill: number;
+  stroke: number;
+  strokeWidth: number;
+  letterSpacing: number;
+  align: TextAlign;
+  wrap: TextWrap;
+  digits: boolean;
+  shadow: TextShadow | undefined;
+};
+/**
+ * What `defineTextStyles` returns and a feature registers under its `textStyles` key. Structural
+ * on purpose: `flow` carries the map, `text` reads it.
+ *
+ * @example
+ * ```ts
+ * const styles: TextStyles = { kind: "textStyles", map: { "hud.title": bodyStyle } };
+ * ```
+ */
+type TextStyles = {
+  readonly kind: "textStyles";
+  readonly map: Record<string, TextStyle>;
+};
+/**
+ * The advances of one font at the size the `.fnt` was exported with. Widths scale by
+ * `style.size / size`; kerning pairs are ignored.
+ *
+ * @example
+ * ```ts
+ * const table: AdvanceTable = { size: 32, lineHeight: 40, advances: new Map([["1", 18]]) };
+ * ```
+ */
+type AdvanceTable = {
+  size: number;
+  lineHeight: number;
+  advances: Map<string, number>;
+};
+/**
+ * One run of glyphs: the text and the flags every glyph in it shares.
+ *
+ * @example
+ * ```ts
+ * const run: TextRun = { kind: "text", text: "+5", bold: true, italic: false, color: 0xffe082 };
+ * ```
+ */
+type TextRun = {
+  kind: "text";
+  text: string;
+  bold: boolean;
+  italic: boolean;
+  color: number | undefined;
+};
+/**
+ * One inline icon: an asset key drawn square at the line height.
+ *
+ * @example
+ * ```ts
+ * const run: IconRun = { kind: "icon", key: "hud.coin" };
+ * ```
+ */
+type IconRun = {
+  kind: "icon";
+  key: string;
+};
+/**
+ * A piece of a line: glyphs or one inline icon.
+ *
+ * @example
+ * ```ts
+ * const runs: Run[] = [{ kind: "icon", key: "hud.coin" }];
+ * ```
+ */
+type Run = TextRun | IconRun;
+/**
+ * One laid-out line and how wide it is.
+ *
+ * @example
+ * ```ts
+ * const line: Line = { runs: [{ kind: "icon", key: "hud.coin" }], width: 38.4 };
+ * ```
+ */
+type Line = {
+  runs: Run[];
+  width: number;
+};
+/**
+ * A laid-out block: its lines and the size `measure` answers with.
+ *
+ * @example
+ * ```ts
+ * const layout: TextLayout = { lines: [], width: 0, height: 0 };
+ * ```
+ */
+type TextLayout = {
+  lines: Line[];
+  width: number;
+  height: number;
+};
+/**
+ * What one label container was last filled from: the style object and the laid-out block. An
+ * update with the same style object, the same anchor and the same lines and runs writes the new
+ * text and positions into the objects already there.
+ */
+type DrawnLabel = {
+  style: TextStyle;
+  layout: TextLayout;
+};
+/**
+ * A dev warning that is written once per key. Pure modules take it as an argument, so nothing
+ * below the plugin context reaches the log itself.
+ *
+ * @example
+ * ```ts
+ * const warn: Warn = (key, message) => seen.has(key) || log.warn(message);
+ * ```
+ */
+type Warn = (key: string, message: string, data?: Record<string, unknown>) => void;
+/**
+ * What the pure layout needs next to the runs, the style and the tables.
+ *
+ * @example
+ * ```ts
+ * const options: LayoutOptions = { warn: () => undefined };
+ * ```
+ */
+type LayoutOptions = {
+  warn: Warn;
+};
+/**
+ * What was resolved for one entity last, so the frame step knows whether anything moved.
+ *
+ * @example
+ * ```ts
+ * const seen: SeenText = { content: "+5", style: "body", bind: undefined, locale: "ru" };
+ * ```
+ */
+type SeenText = {
+  content: unknown;
+  style: string;
+  bind: string | undefined;
+  locale: string;
+};
+/**
+ * text plugin config.
+ *
+ * @example
+ * ```ts
+ * createApp({ pluginConfigs: { text: { fonts: { body: "ui.body", digits: "ui.digits" } } } });
+ * ```
+ */
+type Config$2 = {
+  /** The two fonts every game ships in its boot bundle. They back the built-in styles. */fonts: {
+    body: string;
+    digits: string;
+  };
+};
+/**
+ * text plugin state.
+ */
+type State$2 = {
+  /** Built-in styles first, then the styles of every feature in feature order. */styles: Map<string, TextStyle>; /** Style name to the feature that brought it, for the duplicate error. */
+  styleOwner: Map<string, string>; /** The config fonts plus every `font`, `bold` and `italic` of every style. */
+  fontKeys: Set<string>; /** The parsed advance table per font key, filled when `assets` has the font. */
+  tables: Map<string, AdvanceTable>; /** The font keys handed to `renderer.sync.fonts.install`. */
+  installed: Set<string>; /** What was resolved for an entity last. */
+  seen: Map<Entity, SeenText>; /** `bind.component` to its world type; `undefined` after the one warning. */
+  bindTypes: Map<string, AnyComponent | undefined>; /** The measured size of every live label, for `ui`. */
+  measured: Map<Entity, Size>; /** Layout per `style + resolved`, oldest dropped first. */
+  cache: Map<string, TextLayout>; /** What every live label container was last filled from, by container. */
+  drawn: WeakMap<object, DrawnLabel>; /** Entities to re-resolve in the next layout phase. */
+  dirty: Set<Entity>; /** Warning keys already written, so a style, a tag, a glyph or a font warns once. */
+  warned: Set<string>; /** The system, the two world hooks and the display adapter. */
+  removers: Array<() => void>;
+};
+/**
+ * text plugin API, `app.text`. Two questions: how big a piece of text is, and which styles the
+ * game registered. Everything else happens in the frame.
+ *
+ * @example
+ * ```ts
+ * app.text.measure("120", "digits"); // { width: 57.6, height: 38.4 }
+ * app.text.styles(); // ["body", "digits"]
+ * ```
+ */
+type TextApi = {
+  /**
+   * The size of a piece of text in reference pixels, from the advance table of the style's font.
+   * A `Message` is formatted in the current locale first. Never touches a canvas, so the answer
+   * is the same in a browser and in plain Bun. Cached per style and resolved string.
+   *
+   * @param content - A plain string, or what `tr` returned.
+   * @param style - A registered style name. An unknown one warns once and measures as `body`.
+   * @returns The width and height of the block.
+   * @example
+   * ```ts
+   * // `ui.layout` asks once per invalidation, from the Yoga measure function of a text element.
+   * const text = ctx.require(textPlugin);
+   *
+   * text.measure("120", "digits"); // { width: 57.6, height: 38.4 } on the 0.6 em fallback
+   * ```
+   */
+  measure(content: string | Message, style: string): Size;
+  /**
+   * Whether the font of a style has a glyph for one character, the lookup Pixi draws by. A
+   * character its font lacks is drawn as nothing and `measure` counts it 0 wide. While the font is
+   * not loaded every character counts, as the 0.6 em fallback measures it. An unknown style warns
+   * once and looks up `body`.
+   *
+   * @param char - One character, a whole code point.
+   * @param style - A registered style name.
+   * @returns False only for a character a loaded font has no glyph for.
+   * @example
+   * ```ts
+   * // `ui` measures the caret of a text field over the characters the font draws.
+   * const text = ctx.require(textPlugin);
+   *
+   * text.hasGlyph("A", "body"); // true
+   * text.hasGlyph("😀", "body"); // false once the body font is loaded: it has no emoji glyph
+   * ```
+   */
+  hasGlyph(char: string, style: string): boolean;
+  /**
+   * The registered style names: the two built-ins first, then the styles of every feature in
+   * feature order.
+   *
+   * @returns A frozen list of style names.
+   * @example
+   * ```ts
+   * // A dev overlay lists what a game may write in a `style` prop.
+   * app.text.styles(); // ["body", "digits", "hud.digits"]
+   * ```
+   */
+  styles(): readonly string[];
+};
+/**
+ * Resolved dependency APIs.
+ */
+type Deps$2 = {
+  time: Api;
+  flow: Api$1;
+  world: Api$2;
+  renderer: Api$3;
+  assets: Api$4;
+  i18n: I18nApi;
+};
+/**
+ * What the kernel context offers before the deps are attached.
+ *
+ * `text` owns no event, so `emit` is the kernel's and never called here.
+ */
+type KernelSlice$2 = PluginCtx<Config$2, State$2> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+  readonly require: Require;
+};
+/**
+ * Domain context shared by the files of the plugin: the kernel slice plus the resolved deps.
+ */
+type TextCtx = KernelSlice$2 & {
+  readonly deps: Deps$2;
+};
+/**
+ * Payload of the `assets:bundle-loaded` hook: a bundle landed, so a font may be readable now.
+ */
+type BundleLoaded = Events$1["assets:bundle-loaded"];
+/**
+ * Payload of the `assets:bundle-unloaded` hook: `keys` names the assets that left.
+ */
+type BundleUnloaded = Events$1["assets:bundle-unloaded"];
+/**
+ * Payload of the `i18n:locale-changed` hook: every message has to be resolved again.
+ */
+type LocaleChanged = Events$2["i18n:locale-changed"];
+//#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$1 {
+  export { Config$1 as Config, Deps$1 as Deps, ElementChange, ElementMotion, Finding, FocusRing, KernelSlice$1 as KernelSlice, State$1 as State, TextInputLook, UiApi, UiCtx, UiNode };
+}
+/**
+ * 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$1 = {
+  /** 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$1 = {
+  jsx: JsxState;
+  styles: StylesState;
+  layout: LayoutState;
+};
+/**
+ * Resolved dependency APIs. `anim` is not here: its edge is validation only, and its work
+ * reaches `ui` through the tween driver behind every `ViewHandle`.
+ */
+type Deps$1 = {
+  time: Api;
+  flow: Api$1;
+  world: Api$2;
+  renderer: Api$3;
+  input: InputApi;
+  i18n: I18nApi;
+  text: TextApi;
+};
+/**
+ * What the kernel context offers before the deps are attached.
+ *
+ * `ui` owns no event, so `emit` is the kernel's and never called here.
+ */
+type KernelSlice$1 = PluginCtx<Config$1, State$1> & {
+  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$1 & {
+  readonly deps: Deps$1;
+};
+/**
+ * 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`. 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
+//#region src/plugins/anim/tween/types.d.ts
+/**
+ * One running track: the numeric fields of one component of one entity moving from the values
+ * read at the end of the delay to the exact target, straight or through keyframe segments. A
+ * track with repeats walks again from its first segment each time a run ends.
+ *
+ * @example
+ * ```ts
+ * const track: Track = {
+ *   id: 1, entity: 1_048_576, component: Transform, to: { x: 200 },
+ *   keys: { x: "1048576:Transform:x" }, ms: 350, ease: "out", delayMs: 0, elapsed: 0,
+ *   from: undefined, muted: () => new Set(), additive: false, driven: false, bornFrame: 4,
+ *   ended: false, segments: undefined, repeatsLeft: 0, held: false
+ * };
+ * ```
+ */
+type Track = {
+  readonly id: number;
+  readonly entity: Entity;
+  readonly component: AnyComponent; /** The target fields. Retarget deletes the fields a newer absolute track took over. */
+  to: Record<string, number>;
+  /**
+   * The key of the owner, bases and offsets tables per field, built once when the track starts.
+   * It keeps a field `to` lost, which nothing reads again.
+   */
+  readonly keys: Readonly<Record<string, string>>;
+  readonly ms: number;
+  readonly ease: Ease;
+  readonly delayMs: number;
+  elapsed: number; /** Read when the delay ends, never earlier. */
+  from: Record<string, number> | undefined;
+  readonly muted: () => ReadonlySet<string>;
+  readonly additive: boolean; /** True for a track a timeline step advances by hand; the frame step leaves it alone. */
+  readonly driven: boolean; /** The frame step the track was born in. That step does not advance it a second time. */
+  readonly bornFrame: number;
+  ended: boolean;
+  /**
+   * The keyframe segments the track walks over `ms`, or `undefined` for a straight track. A
+   * segment without an ease runs on the track's `ease`.
+   */
+  readonly segments: readonly TrackSegment[] | undefined;
+  /**
+   * The runs still to go after the one that plays: `0` for a track that runs once, `Infinity`
+   * for a loop (`repeat: "forever"`), which never ends by itself.
+   */
+  repeatsLeft: number;
+  /**
+   * True while a loop stands on its first key and has written it: the hold writes once, and the
+   * walk clears it, so the next hold writes the first key again.
+   */
+  held: boolean;
+};
+/**
+ * A motion handle that can also be advanced by hand: what the timeline cursor needs, so a track
+ * born inside a frame step still consumes the remainder of that step's delta.
+ *
+ * @example
+ * ```ts
+ * const motion: StepMotion = { ...inert, advance: () => 0 };
+ * motion.advance(16); // 0: nothing is left over
+ * ```
+ */
+type StepMotion = MotionHandle & {
+  /**
+   * Advances the track by one delta.
+   *
+   * @param deltaMs - Milliseconds of game time to consume.
+   * @returns The milliseconds left over past the end of the track.
+   */
+  advance(deltaMs: number): number;
+};
+//#endregion
+//#region src/plugins/anim/timeline/steps.d.ts
+/**
+ * Every haptic tick `haptic(kind)` takes, in one frozen list: the three impacts, the selection
+ * tick and the three notifications. `platform` checks a kind against it before it plays one.
+ *
+ * @example
+ * ```ts
+ * HAPTIC_KINDS.includes("light"); // true
+ * ```
+ */
+declare const HAPTIC_KINDS: readonly ["light", "medium", "heavy", "selection", "success", "warning", "error"];
+/**
+ * Runs the steps one after another. The remainder past a step's end reaches the next step in the
+ * same frame, so the tree takes exactly the sum of its durations.
+ *
+ * @param steps - The steps, in order.
+ * @returns The sequence step.
+ * @example
+ * ```ts
+ * sequence(wait(100), mark("done"));
+ * // { kind: "sequence", steps: [{ kind: "wait", ms: 100 }, { kind: "mark", name: "done" }] }
+ * ```
+ */
+declare function sequence(...steps: readonly Step[]): Step;
+/**
+ * Runs every step at once and ends with the longest one.
+ *
+ * @param steps - The steps.
+ * @returns The parallel step.
+ * @example
+ * ```ts
+ * parallel(wait(100), wait(300)); // ends after 300 ms
+ * ```
+ */
+declare function parallel(...steps: readonly Step[]): Step;
+/**
+ * Builds one step per item and starts each one `staggerMs` later than the one before. The build
+ * function runs here, so no function survives in the data.
+ *
+ * @param items - What to build a step for.
+ * @param staggerMs - Delay between two neighbouring items, in game milliseconds.
+ * @param build - Builds the step of one item.
+ * @returns The parallel of delayed sequences.
+ * @example
+ * ```ts
+ * stagger(["a", "b"], 60, item => mark(item));
+ * // parallel(sequence(wait(0), mark("a")), sequence(wait(60), mark("b")))
+ * ```
+ */
+declare function stagger<Item>(items: readonly Item[], staggerMs: number, build: (item: Item, index: number) => Step): Step;
+/**
+ * Holds still for a while.
+ *
+ * @param durationMs - How long to wait, in game milliseconds.
+ * @returns The wait step.
+ * @example
+ * ```ts
+ * wait(120); // { kind: "wait", ms: 120 }
+ * ```
+ */
+declare function wait(durationMs: number): Step;
+/**
+ * Names a point in the choreography. Reaching it emits `anim:mark`, calls the `onMark` listeners
+ * and appends the name to `marks()`. It is the only way out of a timeline.
+ *
+ * @param name - Name of the mark.
+ * @returns The mark step.
+ * @example
+ * ```ts
+ * mark("landed"); // { kind: "mark", name: "landed" }
+ * ```
+ */
+declare function mark(name: string): Step;
+/**
+ * Moves the numeric fields of one component of one target to an exact target value. The component
+ * is any handle `world.ecs` takes, so the kit's `Sprite` and `NineSlice` of `defineGame` pass as
+ * they are.
+ *
+ * By default the fields are local: they are written into the target's own `Transform`. With
+ * `space: "root"` the `x`, `y`, `rotation` and `scale` of a `Transform` are a root pose, the space
+ * `at()` answers in, and are turned into the space of the target's `Parent` when the track starts.
+ * That aims a hosted view, such as a board item inside the board slot, at another element. A
+ * field the step does not name stays where it is, so under a turned parent name `x` and `y`
+ * together. A target without a parent, and a component other than `Transform`, move as in the
+ * local space.
+ *
+ * @param target - The projection key or the entity to animate.
+ * @param component - The component to animate.
+ * @param to - The numeric target fields.
+ * @param options - Duration, easing, delay, the additive flag and the space of the fields.
+ * @param options.ms - Duration in game milliseconds.
+ * @param options.ease - Easing curve; `"out"` when omitted.
+ * @param options.delayMs - How long the track waits before it reads its start values.
+ * @param options.additive - `true` adds an offset instead of owning the fields.
+ * @param options.space - `"root"` reads the `Transform` fields as a root pose; `"local"` when
+ *   omitted.
+ * @returns The tween step.
+ * @example
+ * ```ts
+ * // An order is delivered: the board item flies out of the scaled board slot onto the order card.
+ * const deliverFly = defineAnimation("orders.deliverFly", {
+ *   slots: { item: type<Target>(), card: type<Target>() },
+ *   build: ({ item, card }, { at }) =>
+ *     tween(item, Transform, { x: at(card).x, y: at(card).y, scale: at(card).scale }, {
+ *       ms: 400, ease: "inCubic", space: "root"
+ *     })
+ * });
+ * app.anim.play(deliverFly, {
+ *   item: { projection: "board.items", key: "i1" },
+ *   card: { projection: "hud", key: "card0" }
+ * });
+ * // 400 ms later the item covers the card at the card's size; its Transform stays slot-local
+ * ```
+ */
+declare function tween<Value extends object>(target: Target, component: ComponentHandle<Value>, to: Partial<NumericFields<Value>>, options: {
+  ms: number;
+  ease?: Ease;
+  delayMs?: number;
+  additive?: boolean;
+  space?: "local" | "root";
+}): Step;
+/**
+ * Writes a component patch at once. Any field may be written, not only the numeric ones. The
+ * component is any handle `world.ecs` takes, the kit's `Sprite` and `NineSlice` included.
+ *
+ * @param target - The projection key or the entity to write.
+ * @param component - The component to write.
+ * @param patch - The fields to overwrite.
+ * @returns The set step.
+ * @example
+ * ```ts
+ * set({ projection: "hud", key: "coins" }, Sprite, { texture: "hud.coin-gold" });
+ * // { kind: "set", patch: { texture: "hud.coin-gold" }, ... }
+ * ```
+ */
+declare function set<Value extends object>(target: Target, component: ComponentHandle<Value>, patch: Partial<Value>): Step;
+/**
+ * Plays a frame sprite: one texture key of the list per frame of `fps`, written into `Sprite`.
+ *
+ * @param target - The projection key or the entity to animate.
+ * @param options - The keys, the frame rate and whether the list repeats.
+ * @param options.keys - The texture keys, in play order.
+ * @param options.fps - Frames per second of the list.
+ * @param options.loop - `true` repeats the list until the step is finished.
+ * @returns The frames step.
+ * @example
+ * ```ts
+ * frames({ projection: "board", key: "c3" }, { keys: ["fx.pop-1", "fx.pop-2"], fps: 12 });
+ * // { kind: "frames", keys: ["fx.pop-1", "fx.pop-2"], fps: 12, loop: false, ... }
+ * ```
+ */
+declare function frames(target: Target, options: {
+  keys: readonly string[];
+  fps: number;
+  loop?: boolean;
+}): Step;
+/**
+ * Makes a temporary entity when the step is reached: a flying coin, a toast sign, a sparkle. The
+ * entity is owned by `anim`, drawn in `layer` at `order`, and despawned when the timeline ends, is
+ * finished or is cancelled. Later steps of the same timeline aim at it with `spawned(id)`.
+ *
+ * @param id - Name of the entity inside this timeline; one timeline spawns each id once.
+ * @param components - The component values the entity starts with, as `world.ecs.spawn` takes.
+ * @param options - Where the entity is drawn.
+ * @param options.layer - The layer; `"ui"` when omitted.
+ * @param options.order - The draw order inside the layer; `0` when omitted.
+ * @returns The spawn step.
+ * @example
+ * ```ts
+ * spawn("coin1", [Sprite({ texture: "ui.icon-coin" }), Transform({ x: 540, y: 900 })], { order: 50 });
+ * // { kind: "spawn", id: "coin1", components: [...], layer: "ui", order: 50 }
+ * ```
+ */
+declare function spawn(id: string, components: readonly AnyComponentValue[], options?: {
+  layer?: string;
+  order?: number;
+}): Step;
+/**
+ * Aims a later step at the entity a `spawn` step of the same timeline made. Before that step is
+ * reached nothing answers the id, so a step aimed at it ends silently.
+ *
+ * @param id - The id the `spawn` step was given.
+ * @returns The target.
+ * @example
+ * ```ts
+ * tween(spawned("coin1"), Transform, { x: 40, y: 120 }, { ms: 600, ease: "inCubic" });
+ * // { kind: "tween", target: { spawned: "coin1" }, ... }
+ * ```
+ */
+declare function spawned(id: string): {
+  spawned: string;
+};
+/**
+ * A sound. `anim` owns the descriptor because it sits below `audio`; `audio` owns the handler,
+ * and a game without `audio` plays nothing and hears no error.
+ *
+ * @param key - Asset key of the sound.
+ * @param options - The bus to play it on.
+ * @param options.bus - `"sfx"` when omitted.
+ * @returns The descriptor, usable as a timeline step and as `fx(...)` in a node.
+ * @example
+ * ```ts
+ * sfx("board.merge"); // { kind: "sfx", payload: { key: "board.merge", bus: "sfx" }, cosmetic: true }
+ * ```
+ */
+declare function sfx(key: string, options?: {
+  bus?: string;
+}): SfxDescriptor;
+/**
+ * A haptic tick. `platform` owns the handler; a device without one stays still.
+ *
+ * @param kind - Which tick to play, one of `HAPTIC_KINDS`, for example `"light"`.
+ * @returns The descriptor, usable as a timeline step and as `fx(...)` in a node.
+ * @example
+ * ```ts
+ * haptic("light"); // { kind: "haptic", payload: { kind: "light" }, cosmetic: true }
+ * ```
+ */
+declare function haptic(kind: HapticKind): HapticDescriptor;
+/**
+ * Reserved for Spine and the other external players. It throws until one arrives, so nobody
+ * builds a choreography on a door that is not open yet.
+ *
+ * @param _player - The player that would run the clip.
+ * @param _clip - Name of the clip.
+ * @throws {Error} Always.
+ * @example
+ * ```ts
+ * external(spine, "idle"); // throws: External players arrive with Spine.
+ * ```
+ */
+declare function external(_player: ExternalPlayer, _clip: string): never;
+/**
+ * Nests one animation inside another. The nested tree is built here, so its marks are reported
+ * under the nested id and no function survives in the data. Pass the outer `tools` when the
+ * nested `build` reads `at`.
+ *
+ * @param animation - The animation to nest.
+ * @param slots - One target, or a list of targets, per slot of the nested animation.
+ * @param tools - The build tools of the outer animation; without them `at` is the identity pose.
+ * @returns The use step.
+ * @example
+ * ```ts
+ * use(popCard, { card: { projection: "hud", key: "order" } });
+ * // { kind: "use", id: "hud.popCard", step: { kind: "sequence", ... } }
+ * ```
+ */
+declare function use<Tags extends SlotTags>(animation: AnimationDefinition<Tags>, slots: SlotValues<Tags>, tools?: BuildTools): Step;
+/**
+ * The effect descriptor a node awaits to play a choreography. The payload names the animation,
+ * so the handler resolves the definition from the registry the features filled.
+ *
+ * @param animation - The animation to play.
+ * @param slots - One target, or a list of targets, per slot.
+ * @returns The descriptor, cosmetic, so a failing build never breaks the node.
+ * @example
+ * ```ts
+ * play(coinsFly, { from: { projection: "hud", key: "purse" } });
+ * // { kind: "play", payload: { animation: "hud.coinsFly", slots: { from: { ... } } }, cosmetic: true }
+ * ```
+ */
+declare function play<Tags extends SlotTags>(animation: AnimationDefinition<Tags>, slots: SlotValues<Tags>): PlayDescriptor;
+/**
+ * Declares one animation: an id, the slots it takes and the pure function that builds its step
+ * tree. `build` runs once per play, so the same animation may play twice at once.
+ *
+ * @param id - Animation id, unique across the features of a game.
+ * @param spec - The slots and the build function.
+ * @returns The animation as frozen plain data.
+ * @example
+ * ```ts
+ * const coinsFly = defineAnimation("hud.coinsFly", {
+ *   slots: { from: type<Target>() },
+ *   build: ({ from }) => tween(from, Transform, { scale: 0.4 }, { ms: 600 })
+ * });
+ * coinsFly.id; // "hud.coinsFly"
+ * ```
+ */
+declare function defineAnimation<Tags extends SlotTags>(id: string, spec: AnimationSpec<Tags>): AnimationDefinition<Tags>;
+//#endregion
+//#region src/plugins/anim/timeline/types.d.ts
+/**
+ * The value of the component a step names, with its shape erased: the value type of
+ * `AnyComponent`. A step is built against the real component, so `set(target, Sprite, patch)`
+ * checks the patch; the step tree and the runtime then carry the component erased, which lets one
+ * choreography mix components.
+ *
+ * @example
+ * ```ts
+ * const patch: ErasedFields = { texture: "hud.coin-gold" };
+ * ```
+ */
+type ErasedFields = AnyComponent extends ComponentType<infer Value> ? Value : never;
+/**
+ * A sound, owned by `anim` and handled by `audio`. It is a `flow` descriptor and a timeline step
+ * at once: `fx(sfx("board.merge"))` in a node, or `sfx("board.merge")` inside a `sequence`.
+ *
+ * @example
+ * ```ts
+ * const descriptor: SfxDescriptor = {
+ *   kind: "sfx", payload: { key: "board.merge", bus: "sfx" }, cosmetic: true
+ * };
+ * ```
+ */
+type SfxDescriptor = {
+  readonly kind: "sfx";
+  readonly payload: {
+    readonly key: string;
+    readonly bus: string;
+  };
+  readonly cosmetic: true;
+};
+/**
+ * One haptic tick a device can play: the impact, selection and notification families of Tauri.
+ * `HAPTIC_KINDS` lists the same seven at runtime.
+ *
+ * @example
+ * ```ts
+ * const kind: HapticKind = "success";
+ * ```
+ */
+type HapticKind = (typeof HAPTIC_KINDS)[number];
+/**
+ * A haptic tick, owned by `anim` and handled by `platform`. Like `sfx` it is a descriptor and a
+ * timeline step at once.
+ *
+ * @example
+ * ```ts
+ * const descriptor: HapticDescriptor = {
+ *   kind: "haptic", payload: { kind: "light" }, cosmetic: true
+ * };
+ * ```
+ */
+type HapticDescriptor = {
+  readonly kind: "haptic";
+  readonly payload: {
+    readonly kind: HapticKind;
+  };
+  readonly cosmetic: true;
+};
+/**
+ * The two descriptors `anim` owns. As a step, the descriptor is dispatched through
+ * `flow.fx.dispatch` when the step is reached; a kind nobody handles is silent.
+ *
+ * @example
+ * ```ts
+ * const step: FxStep = { kind: "haptic", payload: { kind: "light" }, cosmetic: true };
+ * ```
+ */
+type FxStep = SfxDescriptor | HapticDescriptor;
+/**
+ * The descriptor `play(animation, slots)` builds. The payload names the animation, so the
+ * handler resolves the definition from the registry instead of carrying a function.
+ *
+ * @example
+ * ```ts
+ * const descriptor: PlayDescriptor = {
+ *   kind: "play",
+ *   payload: { animation: "hud.coinsFly", slots: { from: { projection: "hud", key: "coins" } } },
+ *   cosmetic: true
+ * };
+ * ```
+ */
+type PlayDescriptor = {
+  readonly kind: "play";
+  readonly payload: {
+    readonly animation: string;
+    readonly slots: Json;
+  };
+  readonly cosmetic: true;
+};
+/**
+ * One step of a choreography: plain frozen data with no callback inside, so a step tree can be
+ * read, logged and compared. A `spawn` step carries the component values of a temporary entity,
+ * made when the step is reached and despawned when the timeline ends.
+ *
+ * @example
+ * ```ts
+ * const step: Step = { kind: "wait", ms: 120 };
+ * ```
+ */
+type Step = {
+  readonly kind: "sequence";
+  readonly steps: readonly Step[];
+} | {
+  readonly kind: "parallel";
+  readonly steps: readonly Step[];
+} | {
+  readonly kind: "wait";
+  readonly ms: number;
+} | {
+  readonly kind: "mark";
+  readonly name: string;
+} | {
+  readonly kind: "tween";
+  readonly target: Target;
+  readonly component: AnyComponent;
+  readonly to: Readonly<Record<string, number>>;
+  readonly ms: number;
+  readonly ease: Ease;
+  readonly delayMs: number;
+  readonly additive: boolean; /** `"root"`: the `Transform` fields are a root pose, turned local when the track starts. */
+  readonly space: "local" | "root";
+} | {
+  readonly kind: "set";
+  readonly target: Target;
+  readonly component: AnyComponent;
+  readonly patch: Readonly<ErasedFields>;
+} | {
+  readonly kind: "frames";
+  readonly target: Target;
+  readonly keys: readonly string[];
+  readonly fps: number;
+  readonly loop: boolean;
+} | {
+  readonly kind: "spawn";
+  readonly id: string;
+  readonly components: readonly AnyComponentValue[];
+  readonly layer: string;
+  readonly order: number;
+} | FxStep | {
+  readonly kind: "use";
+  readonly id: string;
+  readonly step: Step;
+};
+/**
+ * Reserved for Spine and the other external players: `external` throws, and this is the shape it
+ * would take. Exported as a type only.
+ *
+ * @example
+ * ```ts
+ * const player: ExternalPlayer = { name: "spine", play: () => undefined };
+ * ```
+ */
+type ExternalPlayer = {
+  readonly name: string;
+  play(clip: string): unknown;
+};
+/**
+ * Where one step of a running timeline stands. One mutable record per step of the tree, built
+ * when the timeline starts.
+ */
+type Cursor = {
+  readonly step: Step;
+  readonly children: readonly Cursor[]; /** Position in a `sequence`, and the last written key of a `frames` step. */
+  index: number; /** Consumed milliseconds of a `wait` or a `frames` step. */
+  elapsed: number;
+  motion: StepMotion | undefined;
+  started: boolean;
+  ended: boolean; /** The entity a running `frames` step holds against its `Frames` loop, until the step ends. */
+  held: Entity | undefined;
+};
+/**
+ * What the cursor reaches the rest of the engine through. Injected, so `timeline` never imports
+ * the run-time code of `tween` or of another plugin.
+ */
+type TimelineRuntime = {
+  /**
+   * Resolves a target to an entity.
+   *
+   * @param target - The projection key, the entity or the spawned id a step names.
+   * @param spawned - The spawn table of the timeline that asks; a spawned id resolves only there.
+   * @returns The entity, or `undefined` when no live view, element or spawned entity holds it.
+   */
+  entityOf(target: Target, spawned?: ReadonlyMap<string, Entity>): Entity | undefined;
+  /**
+   * Spawns a temporary entity owned by `anim`. The timeline that spawned it despawns it when it
+   * ends, whichever way it ends.
+   *
+   * @param components - The component values the entity starts with, `Layer` and `Order` included.
+   * @returns The new entity.
+   */
+  spawn(components: readonly AnyComponentValue[]): Entity;
+  /**
+   * Reads a component of an entity, which is also the liveness check of a step.
+   *
+   * @param entity - The entity to read.
+   * @param component - The component to read.
+   * @returns The stored value, or `undefined`.
+   */
+  read(entity: Entity, component: AnyComponent): Readonly<ErasedFields> | undefined;
+  /**
+   * Writes a patch through `ecs.set`, so `changed()` sees it.
+   *
+   * @param entity - The entity to write.
+   * @param component - The component to write.
+   * @param patch - The fields to overwrite.
+   */
+  write(entity: Entity, component: AnyComponent, patch: Partial<ErasedFields>): void;
+  /**
+   * Turns the root-space target of a `tween` step into the local target under the entity's
+   * parent, through `localPoseOf` of `renderer`.
+   *
+   * @param entity - The entity the step moves.
+   * @param component - The component the step drives; only `Transform` is converted.
+   * @param to - The numeric target fields, in root space.
+   * @returns The target fields in the space of the entity's parent.
+   */
+  toLocal(entity: Entity, component: AnyComponent, to: Readonly<Record<string, number>>): Record<string, number>;
+  /**
+   * Starts one track on the tween core.
+   *
+   * @param entity - The entity to animate.
+   * @param component - The component to animate.
+   * @param to - The numeric target fields.
+   * @param options - Duration, easing, delay and the additive flag.
+   * @returns The motion of the track, advanceable by hand.
+   */
+  start(entity: Entity, component: AnyComponent, to: Record<string, number>, options: TrackOptions): StepMotion;
+  /**
+   * Hands a descriptor step to `flow.fx.dispatch`.
+   *
+   * @param descriptor - The `sfx` or `haptic` step that was reached.
+   */
+  dispatch(descriptor: FxStep): void;
+  /**
+   * Reports a mark: the event, the `onMark` listeners and the timeline's own list.
+   *
+   * @param animation - Id of the animation the mark belongs to.
+   * @param name - Name of the mark.
+   */
+  mark(animation: string, name: string): void;
+  /**
+   * Lifts the idle frame rate, because something started to move.
+   */
+  wake(): void;
+  /**
+   * Claims the sprite of an entity for a running `frames` step: the `Frames` loop of the entity
+   * writes nothing while any claim is open.
+   *
+   * @param entity - The entity the step writes.
+   */
+  holdFrames(entity: Entity): void;
+  /**
+   * Gives one claim back. At the last one the `Frames` loop writes its current key again on its
+   * next step, so the sprite does not stay on the step's last key.
+   *
+   * @param entity - The entity the step wrote.
+   */
+  releaseFrames(entity: Entity): void;
+};
+/**
+ * One running timeline: its cursor, the marks it reached, the entities it counts on, the entities
+ * it spawned and despawns at its end, and the resolver of its `done` promise.
+ */
+type RunningTimeline = {
+  readonly id: number;
+  readonly animation: string;
+  readonly cursor: Cursor;
+  readonly marks: string[];
+  readonly entities: readonly Entity[]; /** The entities its `spawn` steps made, by spawn id. Despawned when the timeline ends. */
+  readonly spawned: Map<string, Entity>;
+  readonly resolve: () => void;
+  ended: boolean;
+};
+declare namespace types_d_exports {
+  export { AnimApi, AnimCtx, AnimationDefinition, AnimationSpec, AnyAnimationDefinition, BuildTools, Config, Cursor, Deps, ErasedFields, Events, ExternalPlayer, FrameLoop, FramesValue, FxStep, HapticDescriptor, HapticKind, KernelSlice, MarkListener, MotionKeyframe, PlayDescriptor, PlayHandle, Pose, RunningTimeline, SfxDescriptor, SlotRecord, SlotTags, SlotValue, SlotValues, State, Step, StepMotion, Target, TimelineRuntime, Track };
+}
+/**
+ * What a step and a slot are pointed at: the projection key of a live view or of an element a
+ * plugin above registered with `registerKey`, an entity, or the id of an entity a `spawn` step of
+ * the same timeline made (`spawned(id)`). A node passes keys, never entities.
+ *
+ * @example
+ * ```ts
+ * const counter: Target = { projection: "hud", key: "coins" };
+ * const flyingCoin: Target = spawned("coin1"); // { spawned: "coin1" }
+ * ```
+ */
+type Target = {
+  projection: string;
+  key: string;
+} | Entity | {
+  spawned: string;
+};
+/**
+ * The pose `at(target)` answers with: where the target rests in root (reference) space, its rest
+ * `Transform` composed through the `Parent` chain, or the identity pose when nothing is there.
+ *
+ * @example
+ * ```ts
+ * const pose: Pose = { x: 540, y: 960, rotation: 0, scale: 1 };
+ * ```
+ */
+type Pose = {
+  x: number;
+  y: number;
+  rotation: number;
+  scale: number;
+};
+/**
+ * The slot declaration of an animation: one type tag per slot, each carrying one target or a
+ * list of targets.
+ *
+ * @example
+ * ```ts
+ * const slots: SlotTags = { items: type<Target[]>(), card: type<Target>() };
+ * ```
+ */
+type SlotTags = Readonly<Record<string, TypeTag<Target> | TypeTag<Target[]>>>;
+/**
+ * The targets `play` and `use` take, read off the slot tags of the animation.
+ *
+ * @example
+ * ```ts
+ * type Slots = SlotValues<{ card: TypeTag<Target> }>; // { card: Target }
+ * ```
+ */
+type SlotValues<Tags extends SlotTags> = { [Name in keyof Tags]: SlotValue<Tags[Name]> };
+/**
+ * What one slot tag stands for: a list of targets when the tag declared one, a single target
+ * otherwise. Distributive on purpose, so the erased `SlotTags` widens to both.
+ *
+ * @example
+ * ```ts
+ * type One = SlotValue<TypeTag<Target>>; // Target
+ * ```
+ */
+type SlotValue<Tag> = Tag extends TypeTag<Target[]> ? Target[] : Target;
+/**
+ * The slots of a running animation with their tags erased, as `build` and the `play` handler
+ * read them.
+ *
+ * @example
+ * ```ts
+ * const slots: SlotRecord = { card: { projection: "hud", key: "order" } };
+ * ```
+ */
+type SlotRecord = SlotValues<SlotTags>;
+/**
+ * What `build` is handed next to the slots: `at` reads where a target rests at play time, in root
+ * space (its rest `Transform` composed through the `Parent` chain, every pivot applied), so a
+ * choreography can fly one element to where another one rests, even inside a scaled slot. A view
+ * that has a `Parent` itself is aimed at that pose with a `tween` in `space: "root"`.
+ *
+ * @example
+ * ```ts
+ * const tools: BuildTools = { at: () => ({ x: 0, y: 0, rotation: 0, scale: 1 }) };
+ * ```
+ */
+type BuildTools = {
+  at(target: Target): Pose;
+};
+/**
+ * One animation: an id, the slots it takes and the pure function that builds its step tree. The
+ * same definition may play twice at once, because `build` runs per play.
+ *
+ * @example
+ * ```ts
+ * const coinsFly: AnimationDefinition<{ from: TypeTag<Target> }> = defineAnimation("hud.coinsFly", {
+ *   slots: { from: type<Target>() },
+ *   build: ({ from }) => tween(from, Transform, { scale: 0.4 }, { ms: 600 })
+ * });
+ * coinsFly.id; // "hud.coinsFly"
+ * ```
+ */
+type AnimationDefinition<Tags extends SlotTags = SlotTags> = {
+  readonly id: string;
+  readonly slots: Tags;
+  build(slots: SlotValues<Tags>, tools: BuildTools): Step;
+};
+/**
+ * What `defineAnimation` is given: the slots the animation takes and the pure function that
+ * builds its step tree.
+ *
+ * @example
+ * ```ts
+ * const spec: AnimationSpec<{ card: TypeTag<Target> }> = {
+ *   slots: { card: type<Target>() },
+ *   build: ({ card }) => tween(card, Transform, { scale: 1.2 }, { ms: 120 })
+ * };
+ * ```
+ */
+type AnimationSpec<Tags extends SlotTags> = {
+  readonly slots: Tags;
+  build(slots: SlotValues<Tags>, tools: BuildTools): Step;
+};
+/**
+ * An animation with its slot tags erased, as the registry stores it.
+ *
+ * @example
+ * ```ts
+ * const stored: AnyAnimationDefinition = { id: "hud.coinsFly", slots: {}, build: () => wait(0) };
+ * ```
+ */
+type AnyAnimationDefinition = AnimationDefinition<SlotTags>;
+/**
+ * What `play` hands back: the motion contract over the whole step tree, the promise of its end
+ * and the marks it reached so far.
+ *
+ * @example
+ * ```ts
+ * const deliverOrder = defineAnimation("orders.deliver", { slots: { card: type<Target>() },
+ *   build: ({ card }) => sequence(tween(card, Transform, { x: 100 }, { ms: 100 }), mark("done")) });
+ * const handle: PlayHandle = app.anim.play(deliverOrder, { card: { projection: "board.items", key: "a" } });
+ * handle.marks(); // []: nothing reached yet
+ * ```
+ */
+type PlayHandle = MotionHandle & {
+  readonly done: Promise<void>;
+  marks(): readonly string[];
+};
+/**
+ * A listener of `onMark`: the animation id and the name of the mark that was reached.
+ *
+ * @example
+ * ```ts
+ * const reached: string[] = [];
+ * const listener: MarkListener = (_animation, mark) => reached.push(mark);
+ * ```
+ */
+type MarkListener = (animation: string, mark: string) => void;
+/**
+ * anim plugin events.
+ *
+ * @example
+ * ```ts
+ * // A feature plugin logs every mark a choreography reaches.
+ * createPlugin("rewardLog", {
+ *   depends: [animPlugin],
+ *   hooks: ctx => ({ "anim:mark": ({ mark }) => ctx.log.info("mark", { mark }) })
+ * }); // a reached mark("done") step logs { mark: "done" }
+ * ```
+ */
+type Events = {
+  /** A `mark` step was reached, or jumped by `finish()`. */"anim:mark": {
+    animation: string;
+    mark: string;
+  }; /** A timeline ended or was finished. Not emitted on `cancel()`. */
+  "anim:finished": {
+    animation: string;
+  };
+};
+/**
+ * One key of a keyframe track in `defineMotion`: where on the track it sits (`at`, 0..1 of
+ * `transition.ms`), the curve of the segment that ends on it (default `"inOut"`) and the pose.
+ * `dx` and `dy` are offsets from the rest pose in reference units; `rotation` (radians), `scale`
+ * and `alpha` are absolute. A field the key leaves out holds the previous key's value.
+ *
+ * An enter walk starts on the first key and ends on the rest pose at `at: 1`; an exit walk starts
+ * where the view is and ends on the last key, the pose the element leaves in.
+ *
+ * In a loop (`loop: { track }`) every Transform field is an offset added to the rest pose: `dx`, `dy`, `rotation`
+ * and `scale` (`scale: 0.05` grows a scale-1 view to 1.05). `alpha` stays absolute. The loop
+ * stands on its first key until that key's `at`, and its last key repeats its first one.
+ *
+ * @example
+ * ```ts
+ * // A popup board at 42 % of its swing: 14 u below its rest, tilted 5°, slightly larger.
+ * const key: MotionKeyframe = { at: 0.42, ease: "out", Transform: { dy: 14, rotation: 0.087, scale: 1.04 } };
+ * ```
+ */
+type MotionKeyframe = {
+  readonly at: number;
+  readonly ease?: Ease;
+  readonly Transform?: {
+    readonly dx?: number;
+    readonly dy?: number;
+    readonly rotation?: number;
+    readonly scale?: number;
+  };
+  readonly Shape?: {
+    readonly alpha?: number;
+  };
+  readonly Sprite?: {
+    readonly alpha?: number;
+  };
+  readonly NineSlice?: {
+    readonly alpha?: number;
+  };
+};
+/**
+ * The value of the `Frames` component: a frame loop that lives as long as its entity. `keys` and
+ * `fps` mean what they mean on the `frames` step; `loop: false` stops on the last key and
+ * `playing: false` holds the key on the screen. A new `keys` array restarts at key 0, the same
+ * array keeps its phase.
+ *
+ * @example
+ * ```ts
+ * const spin: FramesValue = { keys: ["items.coin-0", "items.coin-1"], fps: 12, loop: true, playing: true };
+ * ```
+ */
+type FramesValue = {
+  keys: readonly string[];
+  fps: number;
+  loop: boolean;
+  playing: boolean;
+};
+/**
+ * Where the `Frames` loop of one entity stands. `keys` is the array last seen, for the restart
+ * check; `index` is the key the clock last landed on, `-1` before the first one; `written` is
+ * false while that key still has to reach the sprite.
+ */
+type FrameLoop = {
+  keys: readonly string[];
+  elapsed: number;
+  index: number;
+  written: boolean;
+};
+/**
+ * anim plugin config. The timings live in the steps and in `defineMotion`, not here: a
+ * choreography that reads its duration from a config cannot be read as text.
+ *
+ * @example
+ * ```ts
+ * createApp({ plugins: [...screen], pluginConfigs: { anim: { maxTracks: 500, reducedMotion: true } } });
+ * ```
+ */
+type Config = {
+  /** Dev guard: one warning each time the running track count rises past this number. */maxTracks: number;
+  /**
+   * Start value of reduced motion: every track but a loop takes 0 ms and every loop stands on
+   * its first key. `app.anim.setReducedMotion(on)` switches it while the game runs.
+   */
+  reducedMotion: boolean;
+};
+/**
+ * anim plugin state: the one track table, the field bookkeeping of the retarget policy and the
+ * offsets accumulator, the running timelines and the animation registry.
+ */
+type State = {
+  /** The one track table. Insertion order is advance order. */tracks: Map<number, Track>; /** Ids of tracks and timelines. */
+  nextId: number; /** `"<entity>:<component>:<field>"` to the id of the absolute track that drives the field. */
+  owner: Map<string, number>; /** Per field key, the delta each additive track contributes. */
+  offsets: Map<string, Map<number, number>>; /** Per field key, the value the offsets are added to. Dropped when no track drives the field. */
+  bases: Map<string, number>; /** The running timelines, by id. */
+  timelines: Map<number, RunningTimeline>; /** The `animations` of every feature, read in `onStart`. */
+  registry: Map<string, AnyAnimationDefinition>; /** `onMark` subscribers, in subscription order. */
+  markListeners: Set<MarkListener>; /** Counter of the frame steps. A track born in the running step is not advanced by it. */
+  frame: number; /** True while the track count is over `maxTracks`, so the warning is one per crossing. */
+  overMaxTracks: boolean; /** The live reduced-motion switch. The frozen `Config.reducedMotion` only seeds it. */
+  reducedMotion: boolean; /** Remover of `world.projection.setDriver`. */
+  removeDriver: (() => void) | undefined; /** Remover of `time.onFrame("animate")`. */
+  offFrame: (() => void) | undefined; /** Remover of `flow.fx.handle("play")`. */
+  offPlay: (() => void) | undefined; /** Bound in `onInit`, so the teardown context can end everything with the state alone. */
+  finishAll: (() => void) | undefined; /** One loop per entity that carries `Frames`, kept by the two world hooks. */
+  frameLoops: Map<Entity, FrameLoop>; /** How many running `frames` steps write this entity now. Its loop writes nothing above 0. */
+  framesHeld: Map<Entity, number>;
+  /**
+   * Per entity that carries `Frames`, the remover of its `world.projection.mute` on
+   * `Sprite.texture`: the loop owns that field, so a projection never corrects it back.
+   */
+  frameMutes: Map<Entity, () => void>; /** Removers of the `onAdded` and `onRemoved` hooks on `Frames`. */
+  offFrames: Array<() => void>;
+};
+/**
+ * anim plugin API, `app.anim`: play a choreography, end everything, count what runs and listen
+ * to the marks. A choreography may spawn temporary entities; they live exactly as long as its
+ * timeline.
+ *
+ * @example
+ * ```ts
+ * // A choreography runs in game time: two frames of 50 ms play the 100 ms slide of a card.
+ * const deliverOrder = defineAnimation("orders.deliver", { slots: { card: type<Target>() },
+ *   build: ({ card }) => sequence(tween(card, Transform, { x: 100 }, { ms: 100 }), mark("done")) });
+ * app.anim.play(deliverOrder, { card: { projection: "board.items", key: "a" } });
+ * app.time.step(50); // app.anim.active() is 1: the card slides
+ * app.time.step(50); // app.anim.active() is 0: the card rests at x 100
+ * ```
+ */
+type AnimApi = {
+  /**
+   * Builds the step tree of an animation with the given targets and starts it. The tree runs
+   * from the next frame step on, in game time, so `time.setScale` and a pause apply to it. `at`
+   * inside `build` answers where a target rests in root space, even inside a scaled slot. A
+   * `tween` with `space: "root"` lands a hosted view on such a pose: a board item inside the board
+   * slot flies onto an order card of the HUD.
+   *
+   * @param animation - What `defineAnimation` returned.
+   * @param slots - One target, or a list of targets, per declared slot.
+   * @returns The handle of the running timeline.
+   * @throws {Error} When the tree spawns one id twice.
+   * @example
+   * ```ts
+   * // The player delivers order card "a": it slides to x 100 in 100 ms, then reaches "done".
+   * const deliverOrder = defineAnimation("orders.deliver", { slots: { card: type<Target>() },
+   *   build: ({ card }) => sequence(tween(card, Transform, { x: 100 }, { ms: 100 }), mark("done")) });
+   * const handle = app.anim.play(deliverOrder, { card: { projection: "board.items", key: "a" } });
+   * app.time.step(100);
+   * handle.marks(); // ["done"], and handle.done resolves
+   * ```
+   */
+  play<Tags extends SlotTags>(animation: AnimationDefinition<Tags>, slots: SlotValues<Tags>): PlayHandle;
+  /**
+   * Ends every track and every timeline now: each writes its exact target, the marks of a
+   * running timeline are jumped in tree order, every entity a timeline spawned is despawned and
+   * every pending `done` resolves.
+   *
+   * @example
+   * ```ts
+   * // A /control tool skips the delivery mid-flight: the card lands on x 100 at once.
+   * const deliverOrder = defineAnimation("orders.deliver", { slots: { card: type<Target>() },
+   *   build: ({ card }) => sequence(tween(card, Transform, { x: 100 }, { ms: 100 }), mark("done")) });
+   * app.anim.play(deliverOrder, { card: { projection: "board.items", key: "a" } });
+   * app.time.step(50);
+   * app.anim.finishAll(); // app.anim.active() is 0
+   * ```
+   */
+  finishAll(): void;
+  /**
+   * How many tracks are in the table, the delayed ones and the running loops included. A loop
+   * never ends by itself, so a screen at rest counts one track per loop lane it shows. A `Frames`
+   * component is not a track: a spinning coin counts nothing.
+   *
+   * @returns The number of running tracks.
+   * @example
+   * ```ts
+   * // The assertion every motion test ends with: the screen came to rest.
+   * const deliverOrder = defineAnimation("orders.deliver", { slots: { card: type<Target>() },
+   *   build: ({ card }) => sequence(tween(card, Transform, { x: 100 }, { ms: 100 }), mark("done")) });
+   * app.anim.play(deliverOrder, { card: { projection: "board.items", key: "a" } });
+   * app.time.step(100);
+   * app.anim.active(); // 0
+   * ```
+   */
+  active(): number;
+  /**
+   * Whether reduced motion is on. It starts at `Config.reducedMotion` and `setReducedMotion`
+   * switches it.
+   *
+   * @returns True while every new track takes 0 ms and every loop stands on its first key.
+   * @example
+   * ```ts
+   * // A settings popup shows the switch as the player left it.
+   * app.anim.reducedMotion(); // false: the start value of Config.reducedMotion
+   * ```
+   */
+  reducedMotion(): boolean;
+  /**
+   * Switches reduced motion. While it is on, every track started from then on takes 0 ms: enter
+   * and exit, state changes, change and settle motions, drag returns and timeline tweens land on
+   * their target at the next frame, and their marks and sounds still fire. Every loop stands on
+   * its first key, a running one at once. Tracks already running keep their length. A `Frames`
+   * loop stops on the frame it shows and walks on from that frame when the switch goes off.
+   *
+   * @param on - True for less motion, false for the full motion.
+   * @example
+   * ```ts
+   * // The player turns on "Less motion" in the settings popup.
+   * app.anim.setReducedMotion(true);
+   * app.anim.reducedMotion(); // true: a popup opened now stands in its rest pose next frame
+   * ```
+   */
+  setReducedMotion(on: boolean): void;
+  /**
+   * Registers a listener called for every mark a timeline reaches, next to the `anim:mark`
+   * event. A listener that throws is logged and the listeners after it still run.
+   *
+   * @param fn - Called with the animation id and the mark name.
+   * @returns The remover; calling it twice is a no-op.
+   * @example
+   * ```ts
+   * // A test waits for the "done" mark instead of counting frames.
+   * const ping = defineAnimation("fx.ping", { slots: {}, build: () => sequence(wait(100), mark("done")) });
+   * const reached: string[] = [];
+   * app.anim.onMark((animation, name) => reached.push(`${animation}:${name}`));
+   * app.anim.play(ping, {});
+   * app.time.step(100); // reached: ["fx.ping:done"]
+   * ```
+   */
+  onMark(fn: MarkListener): () => void;
+};
+/**
+ * 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
+ * of `at` with the pure `rootPoseOf` of `renderer/sync/pose.ts`, and turns the target of a
+ * `tween` in `space: "root"` local with the pure `localPoseOf` of the same module.
+ */
+type Deps = {
+  time: Api;
+  flow: Api$1;
+  world: Api$2;
+};
+/**
+ * What the kernel context offers before the deps are attached.
+ *
+ * `index.ts` writes `events` with an annotated `register` (core spec `14-EVENT-REGISTRATION.md`
+ * row 8), so the own events reach the context the kernel hands the factories and `emit` is the
+ * kernel's own, anim-typed one. No member of the context is cast.
+ */
+type KernelSlice = PluginCtx<Config, State, Events> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+  readonly require: Require;
+};
+/**
+ * Domain context of the anim plugin: the kernel slice and the three resolved dependencies.
+ */
+type AnimCtx = KernelSlice & {
+  readonly deps: Deps;
+};
+//#endregion
+export { UiApi as A, spawned as C, wait as D, use as E, TextApi as F, TextStyleInput as I, TextStyles as L, Config$2 as M, Point as N, Config$1 as O, State$2 as P, TextValue as R, spawn as S, tween as T, parallel as _, State as a, set as b, HapticKind as c, HAPTIC_KINDS as d, defineAnimation as f, mark as g, haptic as h, MotionKeyframe as i, types_d_exports$1 as j, State$1 as k, SfxDescriptor as l, frames as m, Config as n, Target as o, external as p, FramesValue as r, types_d_exports as s, AnimApi as t, Step as u, play as v, stagger as w, sfx as x, sequence as y, types_d_exports$2 as z };