@moku-labs/game 0.15.7 → 0.15.8

package/dist/testing.d.mts

@@ -1,6 +1,6 @@
 import { Cr as Json, Yn as FeaturePlugin, Zn as AnyFlow, _r as FakeClock, dr as Hint, fr as NodeFx, hr as ClockSource, rr as NodeTable, sr as Descriptor } from "./types-C4D9UVgb.mjs";
-import { t as createApp } from "./index-CU4Oc2Qv.mjs";
-import { b as saveOf, v as WithGameState, y as memory } from "./types-MocH_igX.mjs";
+import { t as createApp } from "./index-B3dfnsUZ.mjs";
+import { b as saveOf, v as WithGameState, y as memory } from "./types-BcEtn9XV.mjs";
 import { a as createHeadless, i as ReproResult, n as HeadlessGame, o as runRepro, r as Repro, s as stepFrames, t as HeadlessApp } from "./headless-DobgwTKK.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 

package/dist/testing.mjs

@@ -1,4 +1,4 @@
-import { an as exit, cn as type, in as refuseStart, m as flattenFeatures, t as createApp } from "./src-nJYt0LMr.mjs";
+import { an as refuseStart, ln as type, m as flattenFeatures, on as exit, t as createApp } from "./src-DNVAJHwd.mjs";
 import { n as saveOf, t as memory } from "./memory-CWlqhS7l.mjs";
 import { t as fakeClock } from "./fake-6mazmHK3.mjs";
 import { i as stepFrames, r as runRepro, t as createHeadless } from "./headless-BA6ffzqD.mjs";

package/dist/{types-MocH_igX.d.mts → types-BcEtn9XV.d.mts}

@@ -1,7 +1,7 @@
 import { A as PixiModule, Ar as SaveDoc, Cr as Json, D as Config$2, Fn as Config$1, Nr as SnapshotOf, Or as PlayerStateProvider, Yn as FeaturePlugin, Zn as AnyFlow, _r as FakeClock, a as Config$3, d as Manifest, hr as ClockSource, jt as Orientation, kr as ProviderCall, n as AssetsIo, or as TypeTag, xr as Config } from "./types-C4D9UVgb.mjs";
-import { o as AudioContextLike, s as Config$4 } from "./types-BkcgFOoB.mjs";
-import { H as TextKey, I as I18nApi, V as StringTable } from "./types-CZGuMhV8.mjs";
-import { ft as platformPlugin, i as screen, mt as PlatformProvider, t as createApp, wt as audioPlugin, xt as effectsPlugin } from "./index-CU4Oc2Qv.mjs";
+import { o as AudioContextLike, s as Config$4 } from "./types-CPxx3NSG.mjs";
+import { H as StringTable, L as I18nApi, U as TextKey } from "./types-CYoGvBkh.mjs";
+import { ft as platformPlugin, i as screen, mt as PlatformProvider, t as createApp, wt as audioPlugin, xt as effectsPlugin } from "./index-B3dfnsUZ.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/plugins/model/store/providers/memory.d.ts

package/dist/{types-BkcgFOoB.d.mts → types-CPxx3NSG.d.mts}

@@ -1,5 +1,5 @@
 import { $r as Require, A as PixiModule, An as TrackOptions, At as FilterSlotInputs, Cr as Json, E as Api$4, En as NumericFields, M as PixiTexture, Mt as Point, Nn as Api$2, Pt as FilterCache, Qr as Events$2, Qt as Api$3, Sn as Ease, Sr as Events$3, Tn as MotionHandle, Ur as Api$1, an as AnyComponentValue, br as Api$6, cn as ComponentType, j as PixiSprite, jn as TrackSegment, k as PixiFilter, kn as ReducedMotion, kt as FilterSlot, on as ComponentHandle, or as TypeTag, rn as AnyComponent, s as Events$1, sr as Descriptor, t as Api$5, un as Entity, v as Events$4, zr as Events$5 } from "./types-C4D9UVgb.mjs";
-import { I as I18nApi, J as StylesState, S as TextApi, c as UiNode, i as Finding, j as InputApi, n as ElementChange, o as JsxState, r as ElementMotion } from "./types-CZGuMhV8.mjs";
+import { C as TextApi, L as I18nApi, M as InputApi, Y as StylesState, c as UiNode, i as Finding, n as ElementChange, o as JsxState, r as ElementMotion } from "./types-CYoGvBkh.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 import { Node, Yoga } from "yoga-layout/load";
@@ -2809,8 +2809,36 @@ type MusicRequest = {
 };
 //#endregion
 //#region src/plugins/ui/layout/types.d.ts
+/**
+ * The patches the scroll step writes with, one object each, filled in place: a frame builds none.
+ * Every number in them is a whole reference unit.
+ */
+type ScrollPatches = {
+  scroll: {
+    offset: number;
+    min: number;
+  };
+  state: {
+    offset: number;
+    max: number;
+    moving: boolean;
+  };
+  scrollable: {
+    moving: boolean;
+  };
+  x: {
+    x: number;
+  };
+  y: {
+    y: number;
+  };
+};
 /**
  * layout module state. `nodes` is attach minus detach: Yoga 3.2.1 has no instance counter.
+ * `scrolling` is the scroll the finger holds; `scrollClock` the ms the scroll step has run, the
+ * clock of the samples; `scrollRing` the last pointer samples of the press on its axis, a
+ * position and a time each, `scrollHead` the slot the next one takes and `scrollSamples` how
+ * many it holds; `scrollMoved` when the finger last moved.
  */
 type LayoutState = {
   yoga: Yoga | undefined;
@@ -2819,10 +2847,12 @@ type LayoutState = {
   measured: number;
   solves: number;
   scrolling: Entity | undefined;
-  scrollStart: {
-    pointerY: number;
-    offset: number;
-  }; /** One line of the `body` style as the icons were last measured with it; none before that. */
+  scrollClock: number;
+  scrollRing: Float64Array;
+  scrollHead: number;
+  scrollSamples: number;
+  scrollMoved: number;
+  scrollPatches: ScrollPatches; /** One line of the `body` style as the icons were last measured with it; none before that. */
   iconLine: number | undefined;
   order: number;
   cleanups: Array<() => void>;
@@ -2960,7 +2990,7 @@ type UiCtx = KernelSlice & {
 /**
  * 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.
+ * text field, the fifth scrolls a `scroll`.
  *
  * @example
  * ```ts
@@ -3043,6 +3073,28 @@ type UiApi = {
    * ```
    */
   fill(key: string, value: string): boolean;
+  /**
+   * Scrolls a `scroll` element to an offset from its start, at once: the offset is kept inside 0
+   * to `max`, a fling or a glide stops, and `ScrollState` reads the new offset with
+   * `moving: false`. A finger that holds the scroll goes on from there. Works headless, for a
+   * test, an agent or a visual test (the `game.scroll` command, the step `{ scroll: { key, to } }`).
+   *
+   * @param key - The `key` prop of the `scroll` element.
+   * @param to - How far from the start, in reference units. `NaN` leaves the scroll where it is.
+   * @returns True when a live scroll took it. False in two cases, each with one warning `{ key }`:
+   *   `ui:scroll-without-scroll` when no live `scroll` has the key, and `ui:scroll-before-solve`
+   *   when the `scroll` came in this frame and its first solve has not placed it yet: call it
+   *   again after the frame.
+   * @example
+   * ```ts
+   * // A test shows the order strip on its events: the strip is 306 u over a 696 u track.
+   * app.ui.scroll("strip", 0); // true
+   * app.world.ecs.get(app.ui.find("strip") ?? 0, ScrollState); // { offset: 0, max: 390, moving: false }
+   * app.ui.scroll("strip", 999); // true: it stands on the end, offset 390
+   * app.ui.scroll("nothing", 0); // false, with the warning "ui:scroll-without-scroll"
+   * ```
+   */
+  scroll(key: string, to: number): boolean;
 };
 //#endregion
 export { sequence as $, GlowValue as A, Target as B, BlurValue as C, FilterComponent as D, FilterArea as E, AnimPlayerValue as F, HAPTIC_KINDS as G, HapticKind as H, Config$3 as I, frames as J, defineAnimation as K, FramesValue as L, OutlineValue as M, UniformDeclaration as N, FilterSpec as O, AnimApi as P, play as Q, MotionKeyframe as R, AlphaValue as S, DisplacementValue as T, SfxDescriptor as U, types_d_exports$3 as V, Step as W, mark as X, haptic as Y, parallel as Z, State$2 as _, AudioApi as a, tween as at, EmitterDefinition as b, MusicDescriptor as c, OverlayApi as ct, State$1 as d, set as et, VolumesFor as f, EffectsStats as g, EffectsApi as h, types_d_exports as i, stagger as it, NoiseValue as j, FilterValueOf as k, MusicOptions as l, types_d_exports$4 as lt, Config$2 as m, State as n, spawn as nt, AudioContextLike as o, use as ot, types_d_exports$1 as p, external as q, UiApi as r, spawned as rt, Config$1 as s, wait as st, Config as t, sfx as tt, SoundEntry as u, types_d_exports$2 as v, ColorMatrixValue as w, EmitterValue as x, EmitterConfig as y, State$3 as z };

package/dist/{types-CZGuMhV8.d.mts → types-CYoGvBkh.d.mts}

@@ -990,7 +990,12 @@ type State$1 = {
    * over and cancels the resting press.
    */
   pointerId: number | undefined; /** The followed pointer left the tap slop since its press: it started a gesture and keeps the pointer. */
-  moved: boolean; /** The pressed or held entity. */
+  moved: boolean;
+  /**
+   * The press belongs to a scroll: it landed on a moving one and stopped it, or it was handed to
+   * one past the tap slop. Its release answers nothing and runs no `onTap` listener.
+   */
+  caught: boolean; /** The pressed or held entity. */
   entity: Entity | undefined; /** The projection key of `entity`, read once at press time. */
   key: {
     projection: string;
@@ -1870,8 +1875,51 @@ type ImageTexture = string & Brand<"ImageTexture">;
 type IconName = string & Brand<"IconName">;
 /** How an image or an icon fills its rect: inside it, over it (cropped), or stretched. */
 type ImageFit = ("contain" | "cover" | "fill") & Brand<"ImageFit">;
-/** The axis a scroll container moves on. `"x"` throws until V4. */
+/**
+ * The axis a scroll container moves on: `"y"`, the default, or `"x"`. Fixed when the scroll
+ * spawns: another axis on a later render keeps the first one, with one warning
+ * `ui:scroll-axis-fixed`. A windowed scroll moves on `"y"` only: `"x"` with `rows` throws.
+ *
+ * @example
+ * ```tsx
+ * // The order strip of the board moves sideways; the cards in it lay out in a row.
+ * <scroll key="strip" axis="x" style={{ width: 306, height: 120 }}>
+ *   <row key="track" style={{ width: 696, height: 120 }} />
+ * </scroll>;
+ * // ScrollState of the strip: { offset: 0, max: 390, moving: false }
+ * ```
+ */
 type ScrollAxis = ("x" | "y") & Brand<"ScrollAxis">;
+/**
+ * The stops a scroll comes to rest on, as offsets from the start, kept inside 0 to `max`. A
+ * release glides to the stop nearest to where its velocity carries in 260 ms, on the curve
+ * `1 − (1 − p)³`, in `min(620, 260 + distance × 1.1)` ms; without `snap` it flings.
+ *
+ * @example
+ * ```tsx
+ * // Three stops: the events, the orders, the end. A slow release at offset 300 glides to 318.
+ * <scroll key="strip" axis="x" snap={[0, 318, 390]} style={{ width: 306, height: 120 }}>
+ *   <row key="track" style={{ width: 696, height: 120 }} />
+ * </scroll>;
+ * ```
+ */
+type ScrollSnap = readonly number[] & Brand<"ScrollSnap">;
+/**
+ * How far a scroll stands from its start, in reference units, kept inside 0 to `max`; 0 when
+ * left out. The first frame draws it there. A later render with another value glides there on
+ * the curve and in the time of `snap`; the same value changes nothing, so a scroll the finger
+ * moved stays where it was left.
+ *
+ * @example
+ * ```tsx
+ * // The strip opens on the orders; closing the pinned column moves the game to 306.
+ * <scroll key="strip" axis="x" offset={318} snap={[0, 318, 390]} style={{ width: 306, height: 120 }}>
+ *   <row key="track" style={{ width: 696, height: 120 }} />
+ * </scroll>;
+ * // first drawn frame: the content stands 318 u left of its rest, the orders in view
+ * ```
+ */
+type ScrollOffset = number & Brand<"ScrollOffset">;
 /** How many rows a windowed scroll has. */
 type ScrollRows = number & Brand<"ScrollRows">;
 /** The height of every row, in reference units; above 0. */
@@ -2041,11 +2089,14 @@ type ScrollWindowForm = {
 };
 /**
  * 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.
+ * a long one, whose rows exist only in the window; the `axis` it moves on, the `snap` stops a
+ * release glides to, and the `offset` it stands at.
  *
  * @example
  * ```ts
  * const props: ScrollProps = { axis: "y" };
+ * // The order strip: sideways, three stops, opened on the orders.
+ * const strip: ScrollProps = { axis: "x", snap: [0, 318, 390], offset: 318 };
  * // 1000 orders of 120 u in a 1600 u list: rows 0 to 18 exist at offset 0.
  * const orders: ScrollProps = {
  *   style: { height: 1600 },
@@ -2057,6 +2108,8 @@ type ScrollWindowForm = {
  */
 type ScrollProps = CommonProps & {
   axis?: ScrollAxis;
+  snap?: ScrollSnap;
+  offset?: ScrollOffset;
 } & (ScrollChildForm | ScrollWindowForm);
 /**
  * What a text field takes. `local` is required: every keystroke writes that field of the local
@@ -2200,6 +2253,31 @@ declare const Box: ComponentType<{
  * and `ui` merges the patch into the nearest component instance.
  */
 declare const LocalWrite: ComponentType<LocalWriteValue>;
+/**
+ * On every scroll container: where it stands and whether it moves, for a game system and the
+ * read door. `ui` writes it in a frame where the offset or `max` changed, and once more with
+ * `moving: false` when it stops; a game reads it and never writes it.
+ *
+ * @example
+ * ```ts
+ * // A board system dims the events of the order strip while it rests on the orders.
+ * export const stripMist = system({
+ *   name: "board.stripMist",
+ *   phase: "animate",
+ *   query: [ScrollState, OrderStrip],
+ *   run: entities => {
+ *     for (const [entity, scroll] of entities) {
+ *       // scroll: { offset: 318, max: 390, moving: false }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const ScrollState: ComponentType<{
+  offset: number;
+  max: number;
+  moving: boolean;
+}>;
 /**
  * On the view a player taps five times within three seconds to open the editor's overlay on a debug build: the
  * version line of the settings, usually. One helper on top of `app.debug.overlay.open()`; a game that wants another
@@ -2396,6 +2474,35 @@ type ScrollWindow = {
   first: number;
   last: number;
 };
+/**
+ * How a scroll container moves, kept on its element: the axis it spawned with, what moves it now
+ * (the finger `"held"`, a `"fling"` after a release, a `"glide"` to a stop or to a new `offset`
+ * prop, or nothing, `"still"`), and the numbers of that motion in offsets from the start, 0 to
+ * `max`. `offset` is exact: the components get it in whole units. `velocity` is in units a ms,
+ * positive toward `max`. A glide runs from `from` to `to` over `duration` ms, `elapsed` of them
+ * gone. `pointer` and `start` are the finger on the axis and the offset where the press began.
+ * `seen` is the `offset` prop of the last render, 0 when it is left out; `placed` turns true when
+ * the first solve put the scroll at it. `atProp` is true while the scroll follows that prop: it
+ * stands at it or glides to it, so a new range puts it at the prop again. The first place and a
+ * glide to a new prop set it; a press and `app.ui.scroll` clear it, and a fling or a snap glide
+ * only comes after a press. Plain numbers written in place: a frame allocates nothing.
+ */
+type ScrollMotion = {
+  axis: "x" | "y";
+  mode: "still" | "held" | "fling" | "glide";
+  offset: number;
+  max: number;
+  velocity: number;
+  from: number;
+  to: number;
+  duration: number;
+  elapsed: number;
+  pointer: number;
+  start: number;
+  seen: number;
+  placed: boolean;
+  atProp: boolean;
+};
 /**
  * What the style of an element was resolved on besides its own node: the epoch of the jsx state,
  * and the row height when the element is a row of a windowed scroll. While both stand, and the
@@ -2415,7 +2522,7 @@ type StyleBasis = {
  * `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
+ * scroll created: it plays no `enter` hook. A scroll carries its `scroll` motion from its enter. 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. `basis` is what `style` was resolved on, set
  * once the style is on the layout node and the components are written; an element without one is
@@ -2469,6 +2576,7 @@ type Element = {
   warned: Set<string>;
   scrolledIn: boolean;
   window?: ScrollWindow;
+  scroll?: ScrollMotion;
   measuredSize?: {
     width: number;
     height: number;
@@ -2794,4 +2902,4 @@ type CommonProps = {
   components?: ElementComponents;
 };
 //#endregion
-export { Config$1 as A, State$2 as B, TextBind as C, TextValue as D, TextStyles as E, Config$2 as F, IsFlags as G, TextKey as H, I18nApi as I, StylesState as J, ResolvedStyle as K, IntlKit as L, State$1 as M, types_d_exports$1 as N, types_d_exports as O, Argument as P, Message as R, TextApi as S, TextStyleInput as T, TypedTr as U, StringTable as V, types_d_exports$2 as W, WhenFlags as Y, BindOptions as _, JsxChild as a, Point as b, UiNode as c, LocalWrite as d, popup as f, BindField as g, UiIntrinsicElements as h, Finding as i, InputApi as j, defineComponent as k, Box as l, IntrinsicElementsFor as m, ElementChange as n, JsxState as o, defineTokens as p, Style as q, ElementMotion as r, PopupComponent as s, DescriptionNode as t, DebugTrigger as u, Config as v, TextFormat as w, State as x, CountdownValue as y, Part as z };
+export { defineComponent as A, Part as B, TextApi as C, TextStyles as D, TextStyleInput as E, Argument as F, types_d_exports$2 as G, StringTable as H, Config$2 as I, Style as J, IsFlags as K, I18nApi as L, InputApi as M, State$1 as N, TextValue as O, types_d_exports$1 as P, IntlKit as R, State as S, TextFormat as T, TextKey as U, State$2 as V, TypedTr as W, WhenFlags as X, StylesState as Y, BindField as _, JsxChild as a, CountdownValue as b, UiNode as c, LocalWrite as d, ScrollState as f, UiIntrinsicElements as g, IntrinsicElementsFor as h, Finding as i, Config$1 as j, types_d_exports as k, Box as l, defineTokens as m, ElementChange as n, JsxState as o, popup as p, ResolvedStyle as q, ElementMotion as r, PopupComponent as s, DescriptionNode as t, DebugTrigger as u, BindOptions as v, TextBind as w, Point as x, Config as y, Message as z };

package/dist/{visual-BV2A3kpr.d.mts → visual-CxQ4Iqd3.d.mts}

@@ -1,9 +1,9 @@
 import { E as Api, Lr as Api$3, Qt as Api$1, br as Api$2 } from "./types-C4D9UVgb.mjs";
-import { P as AnimApi, r as UiApi } from "./types-BkcgFOoB.mjs";
-import { j as InputApi } from "./types-CZGuMhV8.mjs";
+import { P as AnimApi, r as UiApi } from "./types-CPxx3NSG.mjs";
+import { M as InputApi } from "./types-CYoGvBkh.mjs";
 import { r as Repro } from "./headless-DobgwTKK.mjs";
 import { a as InputOf, r as ControlApp } from "./types-Mj75CDO6.mjs";
-import { t as commands } from "./commands-C8aWbThW.mjs";
+import { t as commands } from "./commands-DWyII1jn.mjs";
 
 //#region src/visual/types.d.ts
 /** The base commands of the `/control` door, keyed by their short names. */

package/dist/visual.d.mts

@@ -1,2 +1,2 @@
-import { a as VisualApp, c as VisualRenderer, d as VisualStart, f as VisualStep, h as VisualTolerance, i as CheckpointResult, l as VisualReport, m as VisualTestResult, n as runVisualTests, o as VisualOptions, p as VisualTest, r as defineVisualTest, s as VisualPage, t as parseVisualArgv, u as VisualSetup } from "./visual-BV2A3kpr.mjs";
+import { a as VisualApp, c as VisualRenderer, d as VisualStart, f as VisualStep, h as VisualTolerance, i as CheckpointResult, l as VisualReport, m as VisualTestResult, n as runVisualTests, o as VisualOptions, p as VisualTest, r as defineVisualTest, s as VisualPage, t as parseVisualArgv, u as VisualSetup } from "./visual-CxQ4Iqd3.mjs";
 export { type CheckpointResult, type VisualApp, type VisualOptions, type VisualPage, type VisualRenderer, type VisualReport, type VisualSetup, type VisualStart, type VisualStep, type VisualTest, type VisualTestResult, type VisualTolerance, defineVisualTest, parseVisualArgv, runVisualTests };

package/dist/visual.mjs

@@ -1,5 +1,5 @@
 import { n as read, t as sources } from "./sources-OvHvyeJS.mjs";
-import { n as commands, t as run } from "./run-DlxDjgOO.mjs";
+import { n as commands, t as run } from "./run-BqYmcNo7.mjs";
 import path from "node:path";
 import { createBrandConsole } from "@moku-labs/common/cli";
 import { mkdir, readFile, writeFile } from "node:fs/promises";

package/llms.txt

@@ -27,7 +27,7 @@ Root exports:
 - Class: `SaveUnreadableError`.
 - Plugin instances: `timePlugin`, `lifecyclePlugin`, `modelPlugin`, `clockPlugin`, `flowPlugin`, `worldPlugin`, `rendererPlugin`, `inputPlugin`, `assetsPlugin`, `scenesPlugin`, `animPlugin`, `i18nPlugin`, `textPlugin`, `uiPlugin`, `audioPlugin`, `effectsPlugin`, `platformPlugin`; the list `screen` = `world`, `renderer`, `input`, `assets`, `scenes`, `anim`, `i18n`, `text`, `ui`. `effects`, `audio` and `platform` are opt-in: `plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin]`, `platform` last.
 - Screen helpers from the root: `component`, `tag`, `resource`, `mut`, `system`, `projection`, `Layer`, `Order`, `Exiting`, `Tree`, `Now`, `Transform`, `Sprite`, `NineSlice`, `Shape`, `Parent`, `Display`, `Overlay`, `HudPart`, `sprite`, `Tappable`, `Pressable`, `Draggable`, `DropTarget`, `Swipeable`, `Traceable`, `Touchable`, `Held`, `Hovered`, `PointerOver`, `Pressed`, `Pointer`, `Traced`, `defineBundles`, `load`, `defineScene`.
-- Interface helpers from the root (V3): `defineAnimation`, `sequence`, `parallel`, `stagger`, `tween`, `set`, `wait`, `mark`, `frames`, `sfx`, `haptic`, `use`, `spawn`, `spawned`, `play`, `external`, `defineMotion`, `Animation`, `Frames`, the resource `AnimPlayer`; `tr`, `messageArgument`, `messageDuration`; `Text`, `label`, `defineTextStyles`, `bind`, `Countdown` and the types `BindOptions`, `CountdownValue`, `TextFormat`; `defineComponent`, `popup`, `defineStyle`, `defineTokens`, `resolve`, `Box`, `LocalWrite`, `DebugTrigger`; `music`.
+- Interface helpers from the root (V3): `defineAnimation`, `sequence`, `parallel`, `stagger`, `tween`, `set`, `wait`, `mark`, `frames`, `sfx`, `haptic`, `use`, `spawn`, `spawned`, `play`, `external`, `defineMotion`, `Animation`, `Frames`, the resource `AnimPlayer`; `tr`, `messageArgument`, `messageDuration`; `Text`, `label`, `defineTextStyles`, `bind`, `Countdown` and the types `BindOptions`, `CountdownValue`, `TextFormat`; `defineComponent`, `popup`, `defineStyle`, `defineTokens`, `resolve`, `Box`, `LocalWrite`, `DebugTrigger`, `ScrollState`; `music`.
 - Effects helpers from the root (V5): `defineEmitter`, `Emitter`, `defineFilter`, `Glow`, `Outline`, `Blur`, `ColorMatrix`, `Noise`, `Displacement`, `Alpha`.
 - Platform from the root (V6): the types `PlatformProvider`, `BackResult`, `HapticKind` and the frozen list `HAPTIC_KINDS`.
 - `defineGame<Types>()` returns, typed by the game's `player`, `session`, `assets`, `bundles`, `scenes`, `strings` and `textStyles`: `defineNode`, `defineFlow`, `defineFeature`, `projection`, `sprite`, `Sprite`, `NineSlice`, `defineBundles`, `load`, `defineScene`, `defineAnimation`, `frames`, `sfx`, `play`, `tr`, `label`, `defineTextStyles`, `defineComponent`, `defineStyle`, `defineTokens`, `popup`, `music`, `Frames`, `defineEmitter`, `Emitter`, `Displacement`, and `system` (its `ctx.snapshot` typed by `player` and `session`), `volumes` (the `audio` config's reader of the typed player), `key` (string keys from data, below). `Types` is `{ player; session; assets: string; bundles?: string; scenes?: string; strings: Record<string, unknown>; textStyles?: string; emitters?: string }`.
@@ -548,7 +548,7 @@ The graph. Modules `runner`, `gate`, `inbox`, `fx`, `features`. Runner methods s
 
 A screen is a projection whose `view` returns JSX. The game's `tsconfig.json` sets `"jsx": "react-jsx"` and `"jsxImportSource": "@moku-labs/game"`; screens are `.tsx` files. There is no DOM and no React.
 
-- Tags: `screen`, `layer`, `row`, `column`, `stack`, `spacer`, `panel` (swallows taps), `image` (`texture`, `fit?: "contain" | "cover" | "fill"`), `icon` (`name`, `fit?`), `text` (`content: string | Message`, or `bind={bind(Counter, "value")}` with `components={[Counter({ value })]}`; formats `int`, `mm:ss`, `h:mm:ss`, `duration`; `Countdown({ until })` with `bind(Countdown, "left", { format: "mm:ss" })` counts down to a `clock` moment; `style` is a text style key), `button` (`intent` + `payload`, or `local`, never both), `scroll` (`axis: "y"`; children for a short list, or the windowed form `rows`, `rowHeight`, `overscan?` (5), `row: index => node`; row state belongs in the model, a row that leaves the window loses its local state), `input` (a text field; its text lives in the component's `local`, see the ui README). Common props: `key`, `style`, `state: { active?, disabled?, selected? }`, `motion`, `components` (extra component values for the element's entity, such as a filter: `components={[Glow({ strength: 2 })]}`, or `DebugTrigger()`: five taps within 3000 ms of wall time on that view call `app.debug.overlay.open()` on a page with the agent flag, nothing elsewhere; put it on a `button` naming nothing); containers take `hosts?: string[]` (projections drawn inside the element: world views hang under it from the slot's first frame; a JSX projection is laid out in the slot's content box). Children draw and are hit in markup order at equal `zIndex`; the roots of a scene draw in the order of its `projections` (the `ui` layer sorts by `Order`; `ui: { sort: "none" }` keeps insertion order). `defineMotion({ when: "change" })` plays its `enter` and `exit` only for a commit or a popup, never when its screen mounts or unmounts; declare a motion at module level (`ui:motion-rebuilt` names a loop rebuilt in a view). Style adds `nineSlice`, `tint`, `offsetX`, `offsetY`, `scale`, `origin`, `fit: "contain"`; state variants `is: { hover, pressed, disabled, active, selected, covered }`. `popup(Component, props, { over })` stacks a popup over a kept one.
+- Tags: `screen`, `layer`, `row`, `column`, `stack`, `spacer`, `panel` (swallows taps), `image` (`texture`, `fit?: "contain" | "cover" | "fill"`), `icon` (`name`, `fit?`), `text` (`content: string | Message`, or `bind={bind(Counter, "value")}` with `components={[Counter({ value })]}`; formats `int`, `mm:ss`, `h:mm:ss`, `duration`; `Countdown({ until })` with `bind(Countdown, "left", { format: "mm:ss" })` counts down to a `clock` moment; `style` is a text style key), `button` (`intent` + `payload`, or `local`, never both), `scroll` (`axis?: "x" | "y"` (`"y"`), fixed at spawn, another one later warns `ui:scroll-axis-fixed`; children for a short list, laid out as a column on `y` and a row on `x`, or the windowed form `rows`, `rowHeight`, `overscan?` (5), `row: index => node`, on `y` only: `axis: "x"` with `rows` throws `[game] A windowed scroll moves on y only.`; row state belongs in the model, a row that leaves the window loses its local state; `snap?: number[]` stops in offsets, kept inside `0..max`: a release glides to the stop nearest `offset + v × 260` (v in units a ms) on `1 − (1 − p)³` over `min(620, 260 + distance × 1.1)` ms; without `snap` a release flings, `v ×= 0.998` a ms until under 0.02, 0 when the finger rested over 50 ms; `offset?: number` (0) where it stands from the start, drawn there in its first frame, a new value glides there, the same value does nothing; hard edges, nothing passes on to a parent scroll; a press on a child that leaves the tap slop along the scroll's axis goes to the scroll and the child answers nothing, a finger on a moving scroll only stops it; every number in `time.delta` ms, so a time scale applies; the public component `ScrollState { offset, max, moving }` on its entity, whole units `0..max`, written when it changes and once with `moving: false` when it stops, read by a system and by `game.explain`; `app.ui.scroll(key, to)` and the visual step `{ scroll: { key, to } }` set it at once), `input` (a text field; its text lives in the component's `local`, see the ui README). Common props: `key`, `style`, `state: { active?, disabled?, selected? }`, `motion`, `components` (extra component values for the element's entity, such as a filter: `components={[Glow({ strength: 2 })]}`, or `DebugTrigger()`: five taps within 3000 ms of wall time on that view call `app.debug.overlay.open()` on a page with the agent flag, nothing elsewhere; put it on a `button` naming nothing); containers take `hosts?: string[]` (projections drawn inside the element: world views hang under it from the slot's first frame; a JSX projection is laid out in the slot's content box). Children draw and are hit in markup order at equal `zIndex`; the roots of a scene draw in the order of its `projections` (the `ui` layer sorts by `Order`; `ui: { sort: "none" }` keeps insertion order). `defineMotion({ when: "change" })` plays its `enter` and `exit` only for a commit or a popup, never when its screen mounts or unmounts; declare a motion at module level (`ui:motion-rebuilt` names a loop rebuilt in a view). Style adds `nineSlice`, `tint`, `offsetX`, `offsetY`, `scale`, `origin`, `fit: "contain"`; state variants `is: { hover, pressed, disabled, active, selected, covered }`. `popup(Component, props, { over })` stacks a popup over a kept one.
 - Style vocabulary (`defineStyle`, plain data): flow `direction`, `wrap`, `justify`, `align`, `alignSelf`, `gap`, `grow`, `shrink`; box `padding`, `margin`, `width`, `height`, `minWidth`, `minHeight`, `maxWidth`, `maxHeight`, `aspect`, `overflow`; position `position`, `left`, `top`, `right`, `bottom`, `reason`; visual `fill`, `stroke`, `strokeWidth`, `radius`, `alpha`; variants `is: { pressed?, disabled?, active?, selected? }` and `when: { portrait?, landscape?, tall?, wide? }`, each a partial style merged in when the flag holds. Lengths are reference units or `"safeArea.top" | "safeArea.right" | "safeArea.bottom" | "safeArea.left"`. No font size here: it comes from the text style.
 - `defineComponent(name, { local?, outcomes?, view(props, local) })`. A component with `outcomes` is a popup: `await fx(popup(Component, props))` opens the gate for its outcomes and resolves with `{ intent, payload }` of the pressed button. A button with `local` writes into the nearest component instance; it never reaches the graph.
 - `tr(key, params?)` returns a frozen `Message` `{ key, params }`; no locale is read at the call site. Strings live in `strings/<locale>.json` of any feature or sub-feature, as ICU MessageFormat 1 (`{n, plural, one {# order} other {# orders}}`, `select`, `selectordinal`, `number`, `date`, `time`; no skeletons, no `currency`). `bun run assets:keys` compiles them. The keys of the top-level features and the layers go into `generated/strings.<locale>.ts`, which one feature registers; a sub-feature's keys start with `<name>.` (`ep01.title`) and go into `generated/strings.<name>.<locale>.ts`, which the sub-feature registers lazily, `strings: { en: () => import("@generated/strings.ep01.en"), ru: () => import("@generated/strings.ep01.ru") }`. With `assets` composed those modules load and unload with the bundle named like the sub-feature: every way the bundle comes (a node entry, a scene's `bundles`, `load`, a restore, the `safeNode`) brings its strings, a locale switch brings them in the new locale, and while the bundle is not loaded a key of it gives `⟦key⟧` and `has(key)` is false. A compiled module calls the root helpers `messageArgument(value, intl)` (an element stays an element part, a list goes through `Intl.ListFormat`, a number through `Intl.NumberFormat`, else text) and `messageDuration(ms)` (`95_000` gives `{ minutes: 1, seconds: 35 }`). `app.i18n`: `locale()`, `setLocale(locale)` (async, emits `i18n:locale-changed`), `format(message, locale?)` returns `Part[]`, `plain(message)` returns a string, `has(key)`, `isKey(value)`, `locales()`, `replace(locale, messages)` (dev hot swap of a generated strings file). Config: `locale: "en"`, `fallback: "en"`, `locales: {}`.
@@ -556,7 +556,7 @@ A screen is a projection whose `view` returns JSX. The game's `tsconfig.json` se
 - Text: `Text` component, `label({ text, style, at, anchor? })` for board text in a projection view, `defineTextStyles({ "hud.digits": { font, size, fill, bold?, italic?, stroke?, strokeWidth?, letterSpacing?, align?, wrap?, digits? } })` under the feature's `textStyles` key. Tags inside a string: `<b>`, `<i>`, `<color=#rrggbb>`, `<icon=key>`, `\<`, `\n`. Built-in styles `body` and `digits` from config `fonts: { body: "ui.font-body", digits: "ui.font-digits" }`. `app.text.measure(content, style)` gives the same numbers in a browser and in Bun. `app.text.replaceStyles(styles)` is the dev hot swap of a saved `defineTextStyles` value.
 - Animation is data: `defineAnimation(id, { slots: { name: type<Anim.Target>() }, build: (slots, { at }) => Step })`. Steps: `sequence(...)`, `parallel(...)`, `stagger(items, ms, item => Step)`, `tween(target, Component, to, { ms, ease?, delayMs?, additive?, space?, reduced? })`, `set(target, Component, patch)`, `wait(ms)`, `mark(name)`, `frames(target, { keys, fps, loop? })`, `sfx(key, { bus? })`, `haptic(kind)`, `use(animation, slots, tools?)`, `spawn` (a temporary entity, flying coins, that the timeline despawns when it ends; see the anim README). `Frames({ keys, fps, loop, playing })` is a component that walks a sprite through its textures for the entity's whole life. A target is `{ projection, key }` or an entity. A timeline resolves each `{ projection, key }` target once, when it starts: every step writes the view that held the key then, also after a commit removed it and while its exit plays, until it despawns; a view spawned again under the same key is not followed, and a key nothing held at the start is looked up at its step. `reduced: "keep"` (on a `tween` step, `transition` and `loop` of `defineMotion`, `TweenOptions`, `RestOptions`) plays a track as written under reduced motion, a fade for one; the default `"cut"` lands it at once or holds a loop on its first key. A node plays it with `await fx(play(animation, slots))`; in fast mode it finishes at once. `defineMotion({ states, transition?, on: { enter?, exit?, change? }, when? })` builds the enter, exit and change hooks for a projection or the `motion` prop of a tag; `when: "change"` plays enter and exit only for a commit, so an element that comes or goes with its screen stands at rest and leaves without a motion (default `"always"`). Events `anim:mark` `{ animation, mark }` and `anim:finished` `{ animation }`. `app.anim.replace(definition)` is the dev hot swap: the next `play` builds the new tree. A system cannot `require` a plugin, so it plays through the resource `AnimPlayer`: `res(AnimPlayer).play(animation, slots)` returns the same handle as `app.anim.play`, and the registered animation of `animation.id` wins, so a hot swap reaches the system. Play on a change, never every frame; from phase `input` the tree moves in `animate` of the same frame. Before `anim` starts it throws `[game] AnimPlayer is not ready: anim has not started.` Config `maxTracks: 2000`.
 - Audio is opt-in: `plugins: [...screen, audioPlugin]`. `fx(sfx("orders.complete"))` resolves when the sound started. `await fx(music("board.theme"))` cross-fades; `music(null)` fades out; a scene's `music` key switches the track on `scenes:changed`. Buses `master`, `music`, `sfx`. Volumes come from the committed player: config `volumes: player => (player as Player).settings.audio`, applied on every `model:committed`. `app.audio`: `setVolume(bus, value)`, `volume(bus)`, `mute(bus, on)`, `muted(bus)`, `unlocked()`, `journal()` (the last started sounds, empty unless config `journal` is above 0). Config: `buses: { master: 1, music: 0.6, sfx: 1 }`, `musicFadeMs: 600`, `volumes`, `context`, `journal: 0`, `music: "decode" | "stream"` default `"decode"` (gapless buffer; `"stream"` is an `<audio>` element, less memory, a gap at every loop), `session: "ambient" | "playback" | "auto"` default `"ambient"` (iOS only: ambient mixes with other apps and obeys the silent switch). The context is asked to run at start: where the shell lets audio play (a native webview with the gesture requirement off) `unlocked()` is true with no touch; a browser that wants a gesture unlocks on the first `pointerdown` or `touchend`. Without `audio` every `sfx` and `music` effect resolves `undefined` at once, so the same node runs in a game with no sound.
-- `app.ui`: `tree()` the live screen as plain data (a text node carries `content`, the words it draws after `tr()` and `bind`; a text field carries `value`), `find(key)` the entity of a keyed element, `fill(key, value)` types into the text field with that `key`, `lint()` tap targets under `tapTargetPt` (default `44`), text that overflows in some locale, absolute elements without `reason`. Config: `tapTargetPt: 44`, `breakpoints: { tall: 2, wide: 1.5 }`. `ui` emits only the dev global event `ui:hot-swap`, see "Hot swap".
+- `app.ui`: `tree()` the live screen as plain data (a text node carries `content`, the words it draws after `tr()` and `bind`; a text field carries `value`), `find(key)` the entity of a keyed element, `fill(key, value)` types into the text field with that `key`, `scroll(key, to)` puts the `scroll` with that `key` at `to` from its start at once, inside `0..max`, its fling or glide stopped (`false` and `ui:scroll-without-scroll` for no live `scroll`, `false` and `ui:scroll-before-solve` for a `scroll` its first solve has not placed yet), `lint()` tap targets under `tapTargetPt` (default `44`), text that overflows in some locale, absolute elements without `reason`. Config: `tapTargetPt: 44`, `breakpoints: { tall: 2, wide: 1.5 }`. `ui` emits only the dev global event `ui:hot-swap`, see "Hot swap".
 
 ```tsx
 // features/hud/view.tsx
@@ -654,7 +654,7 @@ A plugin that owns a resource stores it in its state and frees it in `onStop: ({
 Two subpaths, neither on the root (V4). An editor, MCP tools and e2e scripts reach a running game through them; `docs/doors.md` in the engine repository has the full catalogue.
 
 - `@moku-labs/game/inspect`: `read(app, source, input?)` reads once; `watch(app, source, input, fn)` reads on the `signals` phase when the source changes and returns the stop function; `defineSource`; the frozen catalogue `sources`; the types `Source`, `InputSchema`, `InputOf`. Every source only reads, so the door is safe in a production build. Keys of `sources`: `graph`, `position`, `history`, `tainted`, `cheats`, `model`, `entities`, `projections`, `ui`, `locate`, `render`, `sounds`, `audioMuted`, `effects`, `filters`, `assets`, `log`, `explain`, `diff`, `schema`, `at`; their ids are `game.<key>`. `filters` answers `{ kinds, off }` of `effects.diagnostics`. `locate` takes `{ key }` (a ui element) or `{ target }` (a view by projection key) and answers its box in CSS px, the numbers Playwright clicks. `at` takes `{ x, y }` in CSS px and lists the views under that point, topmost first. `explain` takes `{ entity }` and answers that entity in full, `undefined` for a stale id. `diff` takes `{ from, to }` frames and answers what changed per entity; it throws in a production build and for a frame outside the last 120. `schema` lists every component and tag type the world met, with the JSON kind of each field. `audioMuted` answers whether the master bus is muted. `sounds` throws `[game] The source game.sounds needs audioPlugin.`, `audioMuted` throws `[game] The source game.audioMuted needs audioPlugin.` and `effects` and `filters` throw `[game] The source game.effects needs effectsPlugin.` (`game.filters` for `filters`) when that plugin is not installed; the editor lists such a source as not installed.
-- `@moku-labs/game/control`: `run(app, command, input?)` resolves `{ value, state }`, `state` being `{ path, frame, tainted }`; `defineCommand`; `controlRefused`; `controlReadOnly`; the frozen catalogue `commands`; the types `Command`, `Ran`, `ControlReadOnlyError`. Keys of `commands`: `answer`, `tap`, `drag`, `key`, `fill`, `walk`, `bookmark`, `restore`, `saveExport`, `saveImport`, `step`, `pause`, `resume`, `capture`, `debug`, `reducedMotion`, `timeScale`, `frameRate`, `mute`, `trace`, `filter`. `capture` resolves `{ png }`, and `{ png, legend }` with `legend: true`; `undefined` while the renderer is inert. `timeScale` takes `{ scale }`; 0 freezes game time while the frames keep running. `frameRate` takes `{ fps? }`, calls `time.setRate(fps ?? "auto")` and answers `time.rate()`. `mute` takes `{ muted }`, mutes the master bus and answers the flag. Without `audioPlugin` it throws `[game] The command game.mute needs audioPlugin.` `trace` takes `{ path }`, a list of views by projection key, and answers whether the gate took the answer. `filter` takes `{ kind, on }`, switches the filter kind through `effects.diagnostics` (cosmetic) and answers the off kinds; an unknown kind throws `[game] No filter kind "fx.nope".` naming the known ones; without `effectsPlugin` it throws `[game] The command game.filter needs effectsPlugin.`
+- `@moku-labs/game/control`: `run(app, command, input?)` resolves `{ value, state }`, `state` being `{ path, frame, tainted }`; `defineCommand`; `controlRefused`; `controlReadOnly`; the frozen catalogue `commands`; the types `Command`, `Ran`, `ControlReadOnlyError`. Keys of `commands`: `answer`, `tap`, `drag`, `key`, `fill`, `scroll`, `walk`, `bookmark`, `restore`, `saveExport`, `saveImport`, `step`, `pause`, `resume`, `capture`, `debug`, `reducedMotion`, `timeScale`, `frameRate`, `mute`, `trace`, `filter`. `capture` resolves `{ png }`, and `{ png, legend }` with `legend: true`; `undefined` while the renderer is inert. `timeScale` takes `{ scale }`; 0 freezes game time while the frames keep running. `frameRate` takes `{ fps? }`, calls `time.setRate(fps ?? "auto")` and answers `time.rate()`. `mute` takes `{ muted }`, mutes the master bus and answers the flag. Without `audioPlugin` it throws `[game] The command game.mute needs audioPlugin.` `trace` takes `{ path }`, a list of views by projection key, and answers whether the gate took the answer. `scroll` takes `{ key, to }`, calls `ui.scroll(key, to)` and answers what it answers; a visual test writes it as the step `{ scroll: { key, to } }`. `filter` takes `{ kind, on }`, switches the filter kind through `effects.diagnostics` (cosmetic) and answers the off kinds; an unknown kind throws `[game] No filter kind "fx.nope".` naming the known ones; without `effectsPlugin` it throws `[game] The command game.filter needs effectsPlugin.`
 - Commands run in dev builds and debug builds. `__MOKU_GAME_DEV__ === true` (the dev page, a test's `vi.stubGlobal("__MOKU_GAME_DEV__", true)`) or `__MOKU_GAME_CONTROL__ === true` (`--debug`) runs every command; `__MOKU_GAME_AGENT__ === true` alone (`--debug=read`) runs the `read` and `cosmetic` ones and `run` refuses the others with `controlReadOnly(id)`, an error with `reason: "read-only"`: `[game] The command game.tap changes the game: this debug build runs read and cosmetic commands only.`; no flag: `run` throws `[game] Control commands run in dev builds only.` `moku-game build` defines the three flags `false`; a game without the shell uses a bundler `define` and should add `__MOKU_GAME_AGENT__: "false"` and `__MOKU_GAME_CONTROL__: "false"`. `saveExport` answers the committed `{ player, session, rng }` (read); `saveImport` takes `{ save }` of `saveExport`, restores it at the main flow's start and flushes the store (raw: not on a `--debug=read` page).
 - A command's effect is `read`, `route`, `cosmetic`, `cheat` or `raw`. A `cheat` or `raw` command taints the session and is journaled; read it with `sources.tainted` and `sources.cheats`. Of the base commands `restore` and `saveImport` are `raw`; `capture` with `diff` writes the state too, so a `--debug=read` page refuses it. `bookmark` answers `flow.bookmark()` plus `scene`, the mounted scene; `restore` calls `scenes.expect(scene)` before `flow.restore`, so a bookmark at a popup restores the scene under it, also on a page that shows another scene. A bookmark taken while an effect that takes answers waits names the waiting transit node (`info/show` in the mini game) and carries `rest`; `restore` of it answers once that node's gate is open, with `pending.gate` in its value, and the popup shows on the next frame.
 - A game's own: `defineSource({ id, title, input, changes, read })` with `changes` `"frame"`, `"commit"` or `"edge"`, and `defineCommand({ id, title, input, effect, run, overlay?, value? })`: `overlay: "toggle"` (input exactly `{ on: "boolean" }` and `value: app => boolean`, the switch's state) or `overlay: "button"` (no required input, no value) lists the command in the editor's overlay, which shows only such commands; any other combination is a type error. The id is camelCase words joined by dots, at least two: `dice.rolls`. An input schema maps field names to `"string"`, `"number"`, `"boolean"` or `"json"`; a trailing `?` makes one optional. A command body starts with `if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();`: it runs in dev and is refused on a debug page. A `.dev` command meant for a debug page writes the agent form for a read or cosmetic effect, `if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_AGENT__ === "undefined" || !__MOKU_GAME_AGENT__)) throw controlRefused();`, and the control form (`__MOKU_GAME_CONTROL__` in place of `__MOKU_GAME_AGENT__`) for the others. Keep them in `.dev` modules that only the dev page, a debug page and the tests import: the editor's dev page (`preparePage` with agents) and `moku-game build --debug` import every `**/*.dev.ts`, `moku-game build` none.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/game",
-  "version": "0.15.7",
+  "version": "0.15.8",
   "description": "2D puzzle game engine on TypeScript and PixiJS, built on @moku-labs/core.",
   "type": "module",
   "sideEffects": [