@moku-labs/game 0.2.0 → 0.3.0

package/dist/{types-X9jXjka3.d.mts → types-VErbiEXy.d.mts}

@@ -1,10 +1,214 @@
-import { At as Json, D as ProjectionMotion, I as ComponentType, L as ComponentValue, N as AnyComponentType, P as AnyComponentValue, R as Entity, St as Api, T as MotionHandle, bt as Hint, h as Api$2, j as ViewHandle, m as ViewportSize, nn as Require, p as Point$1, q as Api$1, t as Api$3, vt as Descriptor, w as Motion, y as ChangeHook } from "./types-BZ1OLf24.mjs";
+import { B as ComponentValue, D as Point$2, F as AnyComponentType, I as AnyComponentValue, It as Hint, Kt as Json, O as ViewportSize, P as AnyComponent, Pt as Descriptor, Rt as Api, V as Entity, Z as ChangeHook, at as ProjectionMotion, dn as Api$5, it as NumericFields, k as Api$2, lt as ViewHandle, m as Api$3, nt as Motion, o as Events$1, rt as MotionHandle, t as Api$4, ut as Api$1, vn as Require, z as ComponentType } from "./types-Dy1xB68L.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 
-//#region src/plugins/input/types.d.ts
-declare namespace types_d_exports$1 {
-  export { Config$1 as Config, Deps, Direction, GesturePhase, InputApi, InputCtx, KernelSlice, KeyInput, KeyListener, Point, PointerListener, RawSample, State$1 as State, TapListener, Target };
+//#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;
+};
+/**
+ * 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$2 {
+  export { Carried, Config$2 as Config, Deps$1 as Deps, Direction, GesturePhase, InputApi, InputCtx, KernelSlice$1 as KernelSlice, KeyInput, KeyListener, Point$1 as Point, PointerListener, RawSample, State$2 as State, TapListener, Target };
 }
 /**
  * A point in reference units, as `renderer.viewport.toReference` answers it.
@@ -14,7 +218,7 @@ declare namespace types_d_exports$1 {
  * const point: Point = { x: 540, y: 960 };
  * ```
  */
-type Point = {
+type Point$1 = {
   x: number;
   y: number;
 };
@@ -67,7 +271,7 @@ type RawSample = {
  * const phase: GesturePhase = "dragging";
  * ```
  */
-type GesturePhase = "idle" | "pressed" | "longPressed" | "dragging";
+type GesturePhase = "idle" | "pressed" | "longPressed" | "dragging" | "tracing";
 /**
  * What `onTap` hands a listener: the view the finger let go on, inside the tap slop.
  *
@@ -127,9 +331,12 @@ type KeyListener = (key: KeyInput) => boolean | void;
  * createApp({ plugins: [...screen], pluginConfigs: { input: { heldScale: 1.08 } } });
  * // A game with its own cursors: the config merges shallowly, so both values are given.
  * createApp({ plugins: [...screen], pluginConfigs: { input: { cursor: { control: "grab", idle: "default" } } } });
+ * // A word grid with 40 px cells: the finger's path is hit-tested every 16 px, below the
+ * // shortest cell span, so a fast finger skips no letter.
+ * createApp({ plugins: [...screen], pluginConfigs: { input: { traceStepPx: 16 } } });
  * ```
  */
-type Config$1 = {
+type Config$2 = {
   /** Largest move, in reference px, that still counts as a tap or a long press. */tapSlopPx: number; /** Hold time, in ms of `time`, after which a `Pressable` answers. */
   longPressMs: number; /** Move, in reference px, that turns a press on a `Draggable` into a drag. */
   dragStartPx: number; /** Shortest swipe, in reference px. */
@@ -152,11 +359,30 @@ type Config$1 = {
     control: string;
     idle: string;
   };
+  /**
+   * Reference px between two hit tests along the finger's path inside one frame of a trace. Keep
+   * it below the shortest cell span: a longer step jumps over a cell.
+   */
+  traceStepPx: number;
+  /**
+   * The hit circle of a trace cell: its radius is this times the short side of the cell's hit
+   * box, around the box centre. A diagonal then crosses no corner of a neighbour.
+   */
+  traceInset: number;
+};
+/**
+ * One view a drag carries on top of the held one: hung under the held view from the grab to the
+ * release.
+ */
+type Carried = {
+  /** The carried view. */entity: Entity; /** The `Parent` it had at the grab, hung back under it on the release. */
+  parent: Entity | undefined; /** The remover `world.projection.mute` returned for its root pose. */
+  unmute: () => void;
 };
 /**
  * input plugin state: the raw queue the DOM handlers write, and the one gesture in progress.
  */
-type State$1 = {
+type State$2 = {
   /** 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. */
@@ -165,14 +391,24 @@ type State$1 = {
     projection: string;
     key: string;
   } | undefined; /** Reference px at pointer down. */
-  start: Point; /** `Transform` minus the pointer at the moment of the grab. */
-  grabOffset: Point; /** Sum of `time.delta` since pointer down. No device clock is ever read. */
+  start: Point$1; /** `Transform` minus the pointer at the moment of the grab. */
+  grabOffset: Point$1; /** Sum of `time.delta` since pointer down. No device clock is ever read. */
   pressedMs: number; /** The drop target that carries `Hovered` during a drag. */
   hovered: Entity | undefined; /** The view that carries `PointerOver`: a press would take it, and a mouse or a pen is over it. */
   pointerOver: Entity | undefined; /** The `Parent` the held view had at the grab. It is hung back under it on the release. */
   parent: Entity | undefined; /** The rest scale of the held view in root space: the base of `heldScale`, set back on drop. */
-  restScale: number | undefined; /** The remover `world.projection.mute` returned, while a drag runs. */
-  unmute: (() => void) | undefined;
+  restScale: number | undefined;
+  /**
+   * The root pose of the held view, written at the grab and at every move. A carried view is
+   * placed from it when the held view despawns before the release and takes its `Transform`.
+   */
+  heldPose: TransformValue | undefined; /** The remover `world.projection.mute` returned, while a drag runs. */
+  unmute: (() => void) | undefined; /** The views a drag carries on top of the held one, in `carry` order; empty outside a drag. */
+  carried: Carried[]; /** The cells of the trace in progress, in path order; empty outside a trace. */
+  path: Entity[]; /** The intent of the first cell of the trace; a cell of another intent closes the path. */
+  traceIntent: string | undefined; /** True once a cell of another intent was crossed: the path neither grows nor pops. */
+  traceClosed: boolean; /** Where the finger was at the last frame of the trace: the segment starts there. */
+  lastPoint: Point$1 | undefined;
   canvas: HTMLCanvasElement | undefined;
   offFrame: (() => void) | undefined;
   detach: (() => void) | undefined; /** Registered through `onTap`, called in this order on every tap. */
@@ -252,6 +488,26 @@ type InputApi = {
    * ```
    */
   swipe(target: Target, direction: Direction): boolean;
+  /**
+   * Reads the `Traceable` of every cell and answers one path, the way a finger drawn through the
+   * cells would: the intent of the cells and `{ path }`, the cell payloads in order. Every cell
+   * must name the same intent. An empty list, a cell with no `Traceable` and two intents warn and
+   * answer `false` without calling the gate. Nothing is tagged `Traced`.
+   *
+   * @param path - The cells in the order the finger goes through them.
+   * @returns What `flow.gate.answer` returned: true when the gate took the answer.
+   * @example
+   * ```ts
+   * // A word-game test spells a word without a finger.
+   * app.input.trace([
+   *   { projection: "board.cells", key: "b3" },
+   *   { projection: "board.cells", key: "c3" },
+   *   { projection: "board.cells", key: "d3" }
+   * ]);
+   * // true: answers { intent: "word", payload: { path: [{ cell: "b3" }, { cell: "c3" }, { cell: "d3" }] } }
+   * ```
+   */
+  trace(path: readonly Target[]): boolean;
   /**
    * Registers a listener called on every tap — a press and a release inside `tapSlopPx` — on the
    * topmost view the hit test accepted, before the `Tappable` answer. A view that carries only
@@ -375,7 +631,7 @@ type InputApi = {
 /**
  * Resolved dependency APIs.
  */
-type Deps = {
+type Deps$1 = {
   time: Api;
   flow: Api$1;
   world: Api$2;
@@ -386,7 +642,7 @@ type Deps = {
  *
  * `input` owns no event, so `emit` is the kernel's and never called here.
  */
-type KernelSlice = PluginCtx<Config$1, State$1> & {
+type KernelSlice$1 = PluginCtx<Config$2, State$2> & {
   readonly global: object;
   readonly log: Log.LogApi;
   readonly require: Require;
@@ -394,11 +650,11 @@ type KernelSlice = PluginCtx<Config$1, State$1> & {
 /**
  * Domain context of the input plugin: the kernel slice plus the four resolved dependencies.
  */
-type InputCtx = KernelSlice & {
-  readonly deps: Deps;
+type InputCtx = KernelSlice$1 & {
+  readonly deps: Deps$1;
 };
-declare namespace types_d_exports {
-  export { Argument, CompiledMessage, CompiledMessages, Config, ElementNode, Events, I18nApi, I18nCtx, I18nKit, IntlKit, KeysWithoutParameters, Message, Part, RegisteredModule, ResolvedModule, State, StringTable, StringsLoader, TypedTr };
+declare namespace types_d_exports$1 {
+  export { Argument, CompiledMessage, CompiledMessages, Config$1 as Config, DurationStyle, ElementNode, Events, I18nApi, I18nCtx, I18nKit, IntlKit, KeysWithoutParameters, Message, Part, RegisteredModule, ResolvedModule, State$1 as State, StringTable, StringsLoader, TypedTr };
 }
 /**
  * One interface element handed to a message as a parameter. Structural on purpose: it mirrors
@@ -475,7 +731,31 @@ type IntlKit = {
   number(options?: Intl.NumberFormatOptions): Intl.NumberFormat; /** The list format of the locale, which ICU MessageFormat 1 has no syntax for. */
   list(options?: Intl.ListFormatOptions): Intl.ListFormat; /** The date and time format of the locale. */
   date(options?: Intl.DateTimeFormatOptions): Intl.DateTimeFormat;
+  /**
+   * The duration format of the locale. A compiled `{left, duration}` reads it with
+   * `secondsDisplay: "always"`, so a countdown at zero still says "0 sec".
+   *
+   * @param options - The `Intl.DurationFormat` options.
+   * @returns The memoised formatter for these options.
+   * @throws {Error} When the runtime has no `Intl.DurationFormat`.
+   * @example
+   * ```ts
+   * const intl = createIntlKit("en");
+   * intl.duration({ style: "short" }).format({ minutes: 1, seconds: 35 }); // "1 min, 35 sec"
+   * ```
+   */
+  duration(options?: Intl.DurationFormatOptions): Intl.DurationFormat;
 };
+/**
+ * How a duration reads: `"long"` (1 minute, 35 seconds), `"short"` (1 min, 35 sec), `"narrow"`
+ * (1m 35s) or `"digital"` (0:01:35). A string file names one in `{left, duration, short}`.
+ *
+ * @example
+ * ```ts
+ * const style: DurationStyle = "digital"; // app.i18n.duration(95_000, style) is "0:01:35"
+ * ```
+ */
+type DurationStyle = "long" | "short" | "narrow" | "digital";
 /**
  * One message as the build wrote it: a plain function of the parameters and the locale's kit.
  * There is no ICU parser at run time.
@@ -515,7 +795,7 @@ type StringsLoader = () => Promise<CompiledMessages | {
  * createApp({ pluginConfigs: { i18n: { locale: "ru", fallback: "en", locales: {} } } });
  * ```
  */
-type Config = {
+type Config$1 = {
   /** The locale at start. */locale: string; /** The locale a missing key is read from before it is reported missing. */
   fallback: string;
   /**
@@ -542,7 +822,7 @@ type ResolvedModule = {
 /**
  * i18n plugin state.
  */
-type State = {
+type State$1 = {
   /** 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. */
   loaded: Map<string, CompiledMessages>; /** One kit per locale, built on first use. */
@@ -650,6 +930,25 @@ type I18nApi = {
    * ```
    */
   has(key: string): boolean;
+  /**
+   * 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
+   * non-finite value reads as zero; the seconds are always shown. `text` formats a field bound
+   * with `format: "duration"` through this call.
+   *
+   * @param ms - The duration in milliseconds.
+   * @param style - How the duration reads. Default `"short"`.
+   * @returns The duration as text.
+   * @throws {Error} When the runtime has no `Intl.DurationFormat`.
+   * @example
+   * ```ts
+   * // The out-of-energy popup shows when the next refill comes, locale "en".
+   * app.i18n.duration(95_000); // "1 min, 35 sec"
+   * app.i18n.duration(95_000, "digital"); // "0:01:35"
+   * app.i18n.duration(500); // "1 sec": rounded up
+   * ```
+   */
+  duration(ms: number, style?: DurationStyle): string;
   /**
    * Every locale at least one feature or the config brought a module for, sorted.
    *
@@ -669,264 +968,543 @@ type I18nApi = {
  * row 8), so the own event reaches the context the kernel hands the factories and `emit` is the
  * kernel's own, i18n-typed one. No member of the context is cast.
  */
-type I18nCtx = PluginCtx<Config, State, Events> & {
+type I18nCtx = PluginCtx<Config$1, State$1, Events> & {
   readonly global: object;
   readonly log: Log.LogApi;
   readonly require: Require;
 };
 /**
- * The key-to-parameters table a game generates: `generated/strings.ts` exports it as `Strings`.
- * A key with no parameters carries `Record<never, never>`.
+ * The key-to-parameters table a game generates: `generated/strings.ts` exports it as `Strings`.
+ * A key with no parameters carries `Record<never, never>`.
+ *
+ * @example
+ * ```ts
+ * const table: StringTable = { "hud.orders": { n: 3 }, "orders.complete": {} };
+ * ```
+ */
+type StringTable = Record<string, unknown>;
+/**
+ * The keys of a table whose message takes no parameters, so `tr` may be called with the key
+ * alone.
+ *
+ * @example
+ * ```ts
+ * type Keys = KeysWithoutParameters<{ "home.play": Record<never, never>; "hud.orders": { n: number } }>;
+ * // "home.play"
+ * ```
+ */
+type KeysWithoutParameters<Table extends StringTable> = { [Key in keyof Table]: Record<never, never> extends Table[Key] ? Key : never }[keyof Table] & string;
+/**
+ * `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.
+ *
+ * @example
+ * ```ts
+ * const { tr } = i18nFor<{ "hud.orders": { n: number } }>();
+ * tr("hud.orders", { n: 3 }); // { key: "hud.orders", params: { n: 3 } }
+ * ```
+ */
+type TypedTr<Table extends StringTable> = {
+  <Key extends KeysWithoutParameters<Table>>(key: Key): Message<Key, Table[Key]>;
+  <Key extends keyof Table & string>(key: Key, params: Table[Key]): Message<Key, Table[Key]>;
+};
+/**
+ * What `defineGame` spreads from this plugin.
+ *
+ * @example
+ * ```ts
+ * const kit: I18nKit<{ "home.play": Record<never, never> }> = i18nFor();
+ * kit.tr("home.play"); // { key: "home.play" }
+ * ```
+ */
+type I18nKit<Table extends StringTable> = {
+  tr: TypedTr<Table>;
+};
+declare namespace types_d_exports {
+  export { AdvanceTable, BindField, BindOptions, BundleLoaded, BundleUnloaded, Config, CountdownValue, Deps, DrawnLabel, IconRun, KernelSlice, LayoutOptions, Line, LocaleChanged, Point, Run, SeenText, Size, State, TextAlign, TextApi, TextBind, TextCtx, TextFormat, 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;
+};
+/**
+ * How a bound number is shown. `"int"` rounds it; the three time formats take milliseconds and
+ * show whole seconds, rounded up, so a timer never reads zero while time is left.
+ *
+ * @example
+ * ```ts
+ * const format: TextFormat = "mm:ss"; // 95_000 ms shows "01:35"
+ * ```
+ */
+type TextFormat = "int" | "mm:ss" | "h:mm:ss" | "duration";
+/** The brand only `bind()` puts on a `TextBind`. Type-only: nothing is emitted for it. */
+declare const textBind: unique symbol;
+/**
+ * Which numeric component field a label shows, and how. Plain data in the component, so a
+ * snapshot lists it; nominal, so only `bind()` makes one and a hand-written literal does not
+ * compile.
+ *
+ * @example
+ * ```ts
+ * const Counter = component("Counter", { value: 0 });
+ * const coins: TextBind = bind(Counter, "value");
+ * // { component: "Counter", field: "value", format: "int" }
+ * ```
+ */
+type TextBind = {
+  readonly component: string;
+  readonly field: string;
+  readonly format: TextFormat;
+} & {
+  readonly [textBind]: true;
+};
+/**
+ * The numeric fields of a component value, by name: what `bind()` takes as its field.
+ *
+ * @example
+ * ```ts
+ * type Fields = BindField<{ value: number; name: string }>; // "value"
+ * ```
+ */
+type BindField<Value extends object> = keyof NumericFields<Value> & string;
+/**
+ * What `bind()` takes after the field. The format is `"int"` when left out.
+ *
+ * @example
+ * ```ts
+ * const options: BindOptions = { format: "mm:ss" };
+ * ```
+ */
+type BindOptions = {
+  format?: TextFormat;
+};
+/**
+ * A moment to count down to, and how much is left. A game writes `until`, a moment of `clock` in
+ * epoch milliseconds; `left` is engine-owned and follows what the label shows.
+ *
+ * @example
+ * ```ts
+ * // clock.now() is 1_790_000_000_000: the chest opens in 95 s.
+ * const chest: CountdownValue = { until: 1_790_000_095_000, left: 95_000 };
+ * ```
+ */
+type CountdownValue = {
+  until: number;
+  left: number;
+};
+/**
+ * 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 table: StringTable = { "hud.orders": { n: 3 }, "orders.complete": {} };
+ * 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 StringTable = Record<string, unknown>;
+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;
+};
 /**
- * The keys of a table whose message takes no parameters, so `tr` may be called with the key
- * alone.
+ * What `defineTextStyles` returns and a feature registers under its `textStyles` key. Structural
+ * on purpose: `flow` carries the map, `text` reads it.
  *
  * @example
  * ```ts
- * type Keys = KeysWithoutParameters<{ "home.play": Record<never, never>; "hud.orders": { n: number } }>;
- * // "home.play"
+ * const styles: TextStyles = { kind: "textStyles", map: { "hud.title": bodyStyle } };
  * ```
  */
-type KeysWithoutParameters<Table extends StringTable> = { [Key in keyof Table]: Record<never, never> extends Table[Key] ? Key : never }[keyof Table] & string;
+type TextStyles = {
+  readonly kind: "textStyles";
+  readonly map: Record<string, TextStyle>;
+};
 /**
- * `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.
+ * 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 { tr } = i18nFor<{ "hud.orders": { n: number } }>();
- * tr("hud.orders", { n: 3 }); // { key: "hud.orders", params: { n: 3 } }
+ * const table: AdvanceTable = { size: 32, lineHeight: 40, advances: new Map([["1", 18]]) };
  * ```
  */
-type TypedTr<Table extends StringTable> = {
-  <Key extends KeysWithoutParameters<Table>>(key: Key): Message<Key, Table[Key]>;
-  <Key extends keyof Table & string>(key: Key, params: Table[Key]): Message<Key, Table[Key]>;
+type AdvanceTable = {
+  size: number;
+  lineHeight: number;
+  advances: Map<string, number>;
 };
 /**
- * What `defineGame` spreads from this plugin.
+ * One run of glyphs: the text and the flags every glyph in it shares.
  *
  * @example
  * ```ts
- * const kit: I18nKit<{ "home.play": Record<never, never> }> = i18nFor();
- * kit.tr("home.play"); // { key: "home.play" }
+ * const run: TextRun = { kind: "text", text: "+5", bold: true, italic: false, color: 0xffe082 };
  * ```
  */
-type I18nKit<Table extends StringTable> = {
-  tr: TypedTr<Table>;
+type TextRun = {
+  kind: "text";
+  text: string;
+  bold: boolean;
+  italic: boolean;
+  color: number | undefined;
 };
-//#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.
+ * One inline icon: an asset key drawn square at the line height.
  *
  * @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 }
- * };
+ * const run: IconRun = { kind: "icon", key: "hud.coin" };
  * ```
  */
-type TransformValue = {
-  x: number;
-  y: number;
-  rotation: number;
-  scale: number;
-  pivot: Point$1;
+type IconRun = {
+  kind: "icon";
+  key: string;
 };
 /**
- * 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.
+ * A piece of a line: glyphs or one inline icon.
  *
  * @example
  * ```ts
- * const fit: SpriteFit = "cover";
+ * const runs: Run[] = [{ kind: "icon", key: "hud.coin" }];
  * ```
  */
-type SpriteFit = "fill" | "contain" | "cover";
+type Run = TextRun | IconRun;
 /**
- * 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.
+ * One laid-out line and how wide it is.
  *
  * @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"
- * };
+ * const line: Line = { runs: [{ kind: "icon", key: "hud.coin" }], width: 38.4 };
  * ```
  */
-type SpriteValue = {
-  texture: string;
-  tint: number;
-  alpha: number;
-  anchor: Point$1;
+type Line = {
+  runs: Run[];
   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.
+ * A laid-out block: its lines and the size `measure` answers with.
  *
  * @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
- * };
+ * const layout: TextLayout = { lines: [], width: 0, height: 0 };
  * ```
  */
-type NineSliceValue = {
-  texture: string;
+type TextLayout = {
+  lines: Line[];
   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.
+ * 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 value: DisplayValue = { object: spineAnimation };
+ * const warn: Warn = (key, message) => seen.has(key) || log.warn(message);
  * ```
  */
-type DisplayValue = {
-  object: unknown;
+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;
 };
 /**
- * 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.
+ * What was resolved for one entity last, so the frame step knows whether anything moved. `unit`
+ * is what the shown string of a bound label was built from: the rounded value for `"int"`, whole
+ * seconds for a time format.
  *
  * @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
+ * const seen: SeenText = {
+ *   content: "", style: "digits", bind: "Countdown.left:mm:ss", locale: "ru", unit: 95
  * };
- * // 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;
+type SeenText = {
+  content: unknown;
+  style: string;
+  bind: string | undefined;
+  locale: string;
+  unit: number | undefined;
 };
 /**
- * What `sprite()` takes: the two things every visual needs, and the four that have defaults.
+ * text plugin config.
  *
  * @example
  * ```ts
- * const options: SpriteOptions = { texture: "board.cell", at: { x: 540, y: 300 } };
+ * createApp({ pluginConfigs: { text: { fonts: { body: "ui.body", digits: "ui.digits" } } } });
  * ```
  */
-type SpriteOptions = {
-  texture: string;
-  at: Point$1;
-  tint?: number;
-  alpha?: number;
-  anchor?: Point$1;
-  scale?: number;
+type Config = {
+  /** The two fonts every game ships in its boot bundle. They back the built-in styles. */fonts: {
+    body: string;
+    digits: string;
+  };
 };
 /**
- * Where a view sits: reference units, radians, uniform scale, and the local point it turns
- * around.
+ * text plugin state.
  */
-declare const Transform: ComponentType<TransformValue>;
+type State = {
+  /** 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>;
+};
 /**
- * One textured quad. `texture` is an asset key, resolved through the texture providers; a size
- * and a `fit` draw it into a box.
+ * 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"]
+ * ```
  */
-declare const Sprite: ComponentType<SpriteValue>;
+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[];
+};
 /**
- * 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.
+ * Resolved dependency APIs.
  */
-declare const NineSlice: ComponentType<{
-  texture: string;
-  width: number;
-  height: number;
-  alpha: number;
-  tint: number;
-  debug: boolean;
-  clip: boolean;
-}>;
+type Deps = {
+  time: Api;
+  flow: Api$1;
+  world: Api$2;
+  renderer: Api$3;
+  assets: Api$4;
+  i18n: I18nApi;
+  clock: Api$5;
+};
 /**
- * The entity this view moves with. `0` means no parent.
+ * What the kernel context offers before the deps are attached.
+ *
+ * `text` owns no event, so `emit` is the kernel's and never called here.
  */
-declare const Parent: ComponentType<{
-  entity: number;
-}>;
+type KernelSlice = PluginCtx<Config, State> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+  readonly require: Require;
+};
 /**
- * A display object the game owns. Never pooled, never destroyed by `sync`.
+ * Domain context shared by the files of the plugin: the kernel slice plus the resolved deps.
  */
-declare const Display: ComponentType<DisplayValue>;
+type TextCtx = KernelSlice & {
+  readonly deps: Deps;
+};
 /**
- * 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.
+ * Payload of the `assets:bundle-loaded` hook: a bundle landed, so a font may be readable now.
  */
-declare const Shape: ComponentType<ShapeValue>;
+type BundleLoaded = Events$1["assets:bundle-loaded"];
 /**
- * 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 } })]
- * ```
+ * Payload of the `assets:bundle-unloaded` hook: `keys` names the assets that left.
  */
-declare function sprite(options: SpriteOptions): [ComponentValue<SpriteValue>, ComponentValue<TransformValue>];
+type BundleUnloaded = Events$1["assets:bundle-unloaded"];
+/**
+ * Payload of the `i18n:locale-changed` hook: every message has to be resolved again.
+ */
+type LocaleChanged = Events["i18n:locale-changed"];
 //#endregion
 //#region src/plugins/ui/jsx/component.d.ts
 /**
@@ -1314,11 +1892,6 @@ type ButtonLocal = Record<string, unknown> & Brand<"ButtonLocal">;
 type ButtonEscape = boolean & Brand<"ButtonEscape">;
 /** What a text draws: a plain string, or a message of the game's string table. */
 type TextContent = (string | Message) & Brand<"TextContent">;
-/** The component field a text follows instead of a content. */
-type TextBind = {
-  component: string;
-  field: string;
-} & Brand<"TextBind">;
 /** The text style key, or a layout style when the built-in `body` is meant. */
 type TextStyleProp = (string | Style) & Brand<"TextStyleProp">;
 /** The asset key of an image. */
@@ -1329,6 +1902,23 @@ type IconName = string & Brand<"IconName">;
 type ImageFit = ("contain" | "cover" | "fill") & Brand<"ImageFit">;
 /** The axis a scroll container moves on. `"x"` throws until V4. */
 type ScrollAxis = ("x" | "y") & Brand<"ScrollAxis">;
+/** How many rows a windowed scroll has. */
+type ScrollRows = number & Brand<"ScrollRows">;
+/** The height of every row, in reference units; above 0. */
+type ScrollRowHeight = number & Brand<"ScrollRowHeight">;
+/** Rows kept alive beyond each edge of the viewport; 5 when left out. */
+type ScrollOverscan = number & Brand<"ScrollOverscan">;
+/**
+ * Builds the row at an index; called at reconcile for the rows in the window, never at build time.
+ *
+ * @example
+ * ```tsx
+ * <scroll key="shop" style={list} rows={items.length} rowHeight={80} overscan={5}
+ *         row={index => <ShopRow key={items[index].id} item={items[index]} />} />;
+ * // at offset 0: rows 0 to 24 exist, 25 of the 1000, for 80 u rows in a 1600 u list with overscan 5
+ * ```
+ */
+type ScrollRow = ((index: number) => DescriptionNode) & Brand<"ScrollRow">;
 /** The world projections whose live views a container draws inside itself. */
 type HostedProjections = readonly string[] & Brand<"HostedProjections">;
 /** The local field of the nearest component instance a text field writes on every keystroke. */
@@ -1409,11 +1999,15 @@ type ButtonTagProps = CommonProps & {
   local?: ButtonLocal;
 });
 /**
- * What a text takes: a content or a bind, and the style key that carries its size.
+ * What a text takes: a content or a bind, and the style key that carries its size. Only `bind()`
+ * makes a bind; the text shows the bound field of a component of its own entity, so the bound
+ * component goes in `components`.
  *
  * @example
  * ```ts
  * const props: TextTagProps = { content: "120", style: "digits" };
+ * // The coin counter: Counter is an extra component, the text shows Math.round of its value.
+ * const coins: TextTagProps = { bind: bind(Counter, "value"), components: [Counter({ value: 25 })] };
  * ```
  */
 type TextTagProps = Omit<CommonProps, "style"> & {
@@ -1460,17 +2054,40 @@ type IconProps = CommonProps & {
  * ```
  */
 type PanelProps = CommonProps;
+/** The child form of a scroll: its children are the content, laid out whole. */
+type ScrollChildForm = {
+  rows?: never;
+  rowHeight?: never;
+  overscan?: never;
+  row?: never;
+};
+/** The windowed form of a scroll: only the rows in view plus `overscan` exist. */
+type ScrollWindowForm = {
+  rows: ScrollRows;
+  rowHeight: ScrollRowHeight;
+  overscan?: ScrollOverscan;
+  row: ScrollRow;
+  children?: never;
+};
 /**
- * What a scroll container takes.
+ * What a scroll container takes: children for a short list, or `rows`, `rowHeight` and `row` for
+ * a long one, whose rows exist only in the window.
  *
  * @example
  * ```ts
  * const props: ScrollProps = { axis: "y" };
+ * // 1000 orders of 120 u in a 1600 u list: rows 0 to 18 exist at offset 0.
+ * const orders: ScrollProps = {
+ *   style: { height: 1600 },
+ *   rows: 1000,
+ *   rowHeight: 120,
+ *   row: index => ({ type: "row", key: `order${index}`, props: {}, children: [] })
+ * };
  * ```
  */
 type ScrollProps = CommonProps & {
   axis?: ScrollAxis;
-};
+} & (ScrollChildForm | ScrollWindowForm);
 /**
  * What a text field takes. `local` is required: every keystroke writes that field of the local
  * state of the nearest component, and Enter answers `submit` with `{ [local]: value }`. `style` is
@@ -1686,9 +2303,10 @@ type JsxChild = DescriptionNode | string | number | boolean | null | undefined |
 type ElementChange<Value> = (view: ViewHandle<unknown>, previous: Value, next: Value, hint?: Hint) => Motion;
 /**
  * The motion hooks of one element: the hook triple of `world.projection`, which `defineMotion`
- * of `anim` returns. `ui` plays two `change` hooks itself and hands them typed values: `Box` gets
- * the rects, `Transform` the rest poses. A hook for any other component name is accepted, so every
- * `defineMotion` result fits, and `ui` never plays it.
+ * of `anim` returns. `ui` plays the `change` hooks of `Box` (the rects), of `Transform` (the rest
+ * poses) and of every extra component of the `components` prop (its values before and after). A
+ * hook for any other component name is accepted, so every `defineMotion` result fits, and `ui`
+ * never plays it. Every hook gets the hint routed to the element's key in that frame step.
  *
  * @example
  * ```ts
@@ -1773,14 +2391,37 @@ type Instance = {
   props: object;
   dirty: boolean;
 };
+/**
+ * The range a windowed scroll holds and what it was cut with: `rows` rows of `rowHeight`, the
+ * indexes `first` to `last` alive, `overscan` of them beyond each edge of the viewport. `last` is
+ * `first - 1` for an empty list.
+ *
+ * @example
+ * ```ts
+ * // P18's list scrolled to -3840 u: 24 of its 1000 rows exist.
+ * const window: ScrollWindow = { rows: 1000, rowHeight: 120, overscan: 5, first: 27, last: 50 };
+ * ```
+ */
+type ScrollWindow = {
+  rows: number;
+  rowHeight: number;
+  overscan: number;
+  first: number;
+  last: number;
+};
 /**
  * One live element: the entity, the Yoga node, the resolved style and the place in the tree.
  * `rect` is natural: under a `fit` ancestor it is the rect before that ancestor's scale. `fit`
  * is the element's own fit scale (1 without `fit: "contain"`), and `rest` the rest `Transform`
  * last written for it. `loop` is the motion of the running `loop` hook, kept apart from
  * `handles`: it never ends, so the exit sweep must not wait for it. `extras` holds the values of
- * the `components` prop added last time, by component name; `warnedOwned` the names of the
- * `components` values the element owns that were already logged.
+ * the `components` prop added last time, by component name; `extraHandles` the motion the last
+ * `change` hook of each of them returned; `warnedOwned` the names of the `components` values the
+ * element owns that were already logged. A windowed scroll carries its `window` and the one-time
+ * warnings of its props in `warned`; `scrolledIn` marks an element a range change of a windowed
+ * scroll created: it plays no `enter` hook. A text or an icon that sizes itself keeps in
+ * `measuredSize` what its measure function last answered, before Yoga's clamp: a bound text whose
+ * new string measures the same asks for no solve.
  */
 type Element = {
   entity: Entity;
@@ -1817,7 +2458,15 @@ type Element = {
   entered: boolean;
   dropKey: (() => void) | undefined;
   extras: ReadonlyMap<string, AnyComponentValue>;
+  extraHandles: Map<string, MotionHandle>;
   warnedOwned: Set<string>;
+  warned: Set<string>;
+  scrolledIn: boolean;
+  window?: ScrollWindow;
+  measuredSize?: {
+    width: number;
+    height: number;
+  };
 };
 /**
  * The popup side of a root: the handler that shows it now and the root it was opened over.
@@ -1971,7 +2620,9 @@ type TextState = {
 };
 /**
  * jsx module state. `hosts` holds the elements with a `hosts` prop; `hosted` maps a world view to
- * the element that hosts it; `fields` holds the text fields by entity.
+ * the element that hosts it; `fields` holds the text fields by entity. `hints` buffers the hints
+ * released since the last frame step; `scrolls` holds the scroll containers; `windowRenders`
+ * counts the re-renders of a windowed list its range made.
  */
 type JsxState = {
   components: Map<string, AnyComponentDefinition>;
@@ -1988,12 +2639,16 @@ type JsxState = {
   focus: FocusState;
   fields: Map<Entity, Field>;
   text: TextState;
+  hints: Hint[];
+  scrolls: Set<Entity>;
+  windowRenders: number;
 };
 /**
  * One node of the snapshot `tree()` answers with. `rect` is natural: under a `fit` ancestor it
  * is the rect before that ancestor's scale. An element with `fit: "contain"` adds `fitScale`,
  * the scale it is drawn at. An `input` adds `value`: the text being typed while it is edited,
- * else the local field it writes.
+ * else the local field it writes. A windowed `scroll` adds `window`: the rows that exist, which
+ * are the children of its content, and how many the list has.
  *
  * @example
  * ```ts
@@ -2019,6 +2674,20 @@ type UiNode = {
   local?: Record<string, unknown>;
   fitScale?: number;
   value?: string;
+  /**
+   * The rows of a windowed scroll that exist and how many the list has.
+   *
+   * @example
+   * ```ts
+   * // P18's shop list of 1000 rows, 120 u each in 1600 u, scrolled to -3840 u: 24 rows exist.
+   * const window: UiNode["window"] = { first: 27, last: 50, rows: 1000 };
+   * ```
+   */
+  window?: {
+    first: number;
+    last: number;
+    rows: number;
+  };
   children: UiNode[];
 };
 /**
@@ -2055,4 +2724,4 @@ type CommonProps = {
   components?: ElementComponents;
 };
 //#endregion
-export { Transform as A, types_d_exports as B, NineSliceValue as C, Sprite as D, ShapeValue as E, Events as F, InputApi as H, I18nApi as I, Message as L, sprite as M, Argument as N, SpriteOptions as O, Config as P, State as R, NineSlice as S, Shape as T, State$1 as U, Config$1 as V, types_d_exports$1 as W, Style as _, JsxChild as a, defineComponent as b, UiNode as c, popup as d, defineTokens as f, ResolvedStyle as g, IsFlags as h, Finding as i, TransformValue as j, SpriteValue as k, Box as l, UiIntrinsicElements as m, ElementChange as n, JsxState as o, IntrinsicElementsFor as p, ElementMotion as r, PopupComponent as s, DescriptionNode as t, LocalWrite as u, StylesState as v, Parent as w, Display as x, WhenFlags as y, TypedTr as z };
+export { SpriteValue as $, TextStyleInput as A, types_d_exports$1 as B, Config as C, TextApi as D, State as E, Config$1 as F, Display as G, InputApi as H, I18nApi as I, Parent as J, NineSlice as K, Message as L, TextValue as M, types_d_exports as N, TextBind as O, Argument as P, SpriteOptions as Q, State$1 as R, BindOptions as S, Point as T, State$2 as U, Config$2 as V, types_d_exports$2 as W, ShapeValue as X, Shape as Y, Sprite as Z, Style as _, JsxChild as a, defineComponent as b, UiNode as c, popup as d, Transform as et, defineTokens as f, ResolvedStyle as g, IsFlags as h, Finding as i, TextStyles as j, TextFormat as k, Box as l, UiIntrinsicElements as m, ElementChange as n, sprite as nt, JsxState as o, IntrinsicElementsFor as p, NineSliceValue as q, ElementMotion as r, PopupComponent as s, DescriptionNode as t, TransformValue as tt, LocalWrite as u, StylesState as v, CountdownValue as w, BindField as x, WhenFlags as y, TypedTr as z };