@moku-labs/game 0.14.11 → 0.14.12

package/dist/testing.d.mts

@@ -1,7 +1,7 @@
-import { Dt as AnyFlow, Ht as ClockSource, Nt as NodeTable, Wt as FakeClock, Xt as Json, ht as FeaturePlugin } from "./types-BT9S_Lo2.mjs";
-import { t as createApp } from "./index-0GIP3tgm.mjs";
-import { n as saveOf, t as memory } from "./memory-DR1ibF_s.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-CrhefcLu.mjs";
+import { Bt as NodeFx, Dt as AnyFlow, Gt as FakeClock, Lt as Descriptor, Nt as NodeTable, Ut as ClockSource, Zt as Json, ht as FeaturePlugin, zt as Hint } from "./types-BjTtGSFb.mjs";
+import { t as createApp } from "./index-CLQ8NOTw.mjs";
+import { n as saveOf, t as memory } from "./memory-pUQ7YZWC.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-CMHNsKjW.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/plugins/clock/fake.d.ts
@@ -26,6 +26,101 @@ import { AnyPluginInstance } from "@moku-labs/core";
  */
 declare function fakeClock(start?: number): FakeClock;
 //#endregion
+//#region src/testing/fake-fx.d.ts
+/**
+ * What a test tells `fakeFx`.
+ *
+ * @example
+ * ```ts
+ * const options: FakeFxOptions = {
+ *   answer: descriptor => (descriptor.kind === "popup" ? { intent: "again" } : undefined),
+ *   path: "board/place"
+ * };
+ * ```
+ */
+type FakeFxOptions = {
+  /**
+   * What an awaited effect resolves with: a value, or a promise of one. Called once for every
+   * `await fx(descriptor)`, at the call, with the descriptor itself. Without it every awaited
+   * effect resolves `undefined`. A promise that never settles holds the body at its `await`, as a
+   * real effect can. A throw and a rejection stand for a handler that fails, and end as they do
+   * in the game: the awaited effect rejects, except for a descriptor with `cosmetic: true`
+   * (`sfx`, `play`, `haptic`, `music`), which resolves `undefined`. The game also writes the warn
+   * entry `flow:fx-cosmetic-failed` there. The fake has no log and writes nothing.
+   *
+   * @example
+   * ```ts
+   * // The popup is answered, a sound never ends: a body that waits for the sound stays there.
+   * fakeFx({
+   *   answer: descriptor =>
+   *     descriptor.kind === "sfx" ? new Promise<never>(() => undefined) : { intent: "again" }
+   * });
+   * ```
+   */
+  answer?: (descriptor: Descriptor) => unknown;
+  /**
+   * The path of the node under test. Only the error of a refused `fx.start` names it. `"test"`
+   * by default.
+   */
+  path?: string;
+};
+/**
+ * What `fakeFx` returns: the `fx` for the node context, and the three lists it records into.
+ * Each list is one array for the whole life of the fake: a list read before the body ran holds
+ * the later calls too, and a test starts a list over with `list.length = 0`. The lists hold the
+ * objects the body passed, not copies. The holder is frozen, so a list cannot be replaced by
+ * another array the fake would not write to.
+ *
+ * @example
+ * ```ts
+ * const { fx, started }: FakeFx = fakeFx();
+ *
+ * fx.start({ kind: "sfx", payload: { key: "ui.tap" } });
+ * started; // [{ kind: "sfx", payload: { key: "ui.tap" } }]
+ * ```
+ */
+type FakeFx = {
+  /** The `fx` to put into the node context: `{ ...context, fx: fake.fx }`. */readonly fx: NodeFx; /** Every `await fx(descriptor)` in call order, recorded at the call, answered or not. */
+  readonly awaited: Descriptor[]; /** Every `fx.start(descriptor)` in call order. A refused start is not in it. */
+  readonly started: Descriptor[]; /** Every `fx.emit(hint)` in call order. */
+  readonly emitted: Hint[];
+};
+/**
+ * Builds the `fx` of a node context for a unit test that calls `node.run(context)` itself, with no
+ * app and no runner. It records every call and plays no effect: `await fx(descriptor)` goes to
+ * `awaited` and resolves with `options.answer(descriptor)`, `fx.start(descriptor)` goes to
+ * `started`, `fx.emit(hint)` goes to `emitted`. `fx.start` refuses a descriptor with `answers`
+ * and a `guide` with the error the game throws. An `answer` that fails rejects the awaited
+ * effect, and resolves `undefined` for a `cosmetic` descriptor, as in the game. There is no
+ * handler, no log, no fast mode and no abort signal here: for those, walk the graph with
+ * `createHeadless`.
+ *
+ * @param options - The answer of an awaited effect, and the node path for the refusal message.
+ * @returns The `fx` and the lists `awaited`, `started` and `emitted`.
+ * @example
+ * ```ts
+ * // The body of the node "place" runs fx.start(sfx("ui.tap")), then pushes input.cell to
+ * // session.marks. `context` is the rest of its context: input, player, session, rng, out,
+ * // signal and now.
+ * const fx = fakeFx();
+ *
+ * await place.run?.({ ...context, fx: fx.fx });
+ *
+ * fx.started; // [{ kind: "sfx", payload: { key: "ui.tap", bus: "sfx" }, cosmetic: true }]
+ * fx.awaited; // []: the body waited for no effect
+ *
+ * // The node "retry" awaits a popup that takes answers. The test gives the player's pick.
+ * const picked = fakeFx({
+ *   answer: descriptor => (descriptor.kind === "popup" ? { intent: "again" } : undefined)
+ * });
+ *
+ * await retry.run?.({ ...context, fx: picked.fx });
+ *
+ * picked.awaited; // [{ kind: "popup", payload: { name: "Retry" }, answers: ["again", "home"] }]
+ * ```
+ */
+declare function fakeFx(options?: FakeFxOptions): FakeFx;
+//#endregion
 //#region src/testing/isolate.d.ts
 /**
  * A stub for one node or sub-flow of the isolated flow: the outcome it ends with, and its payload.
@@ -151,4 +246,4 @@ declare function stub<const Name extends string>(outcome: Name, payload?: Json):
  */
 declare function isolate<Nodes extends NodeTable>(feature: FeaturePlugin, options: IsolateOptions<Nodes>): (seams?: IsolateSeams) => IsolatedApp;
 //#endregion
-export { type HeadlessApp, type HeadlessGame, type IsolateOptions, type IsolateSeams, type Repro, type ReproResult, type Stub, type StubsOf, createHeadless, fakeClock, isolate, memory, runRepro, saveOf, stepFrames, stub };
+export { type FakeFx, type FakeFxOptions, type HeadlessApp, type HeadlessGame, type IsolateOptions, type IsolateSeams, type Repro, type ReproResult, type Stub, type StubsOf, createHeadless, fakeClock, fakeFx, isolate, memory, runRepro, saveOf, stepFrames, stub };

package/dist/testing.mjs

@@ -1,7 +1,93 @@
-import { Kt as type, Ut as exit, t as createApp } from "./src-Do697seR.mjs";
+import { Ut as refuseStart, Wt as exit, qt as type, t as createApp } from "./src-CtC8w3_z.mjs";
 import { n as saveOf, t as memory } from "./memory-CWlqhS7l.mjs";
 import { t as fakeClock } from "./fake-MpzwZhIZ.mjs";
 import { i as stepFrames, r as runRepro, t as createHeadless } from "./headless-BA6ffzqD.mjs";
+//#region src/testing/fake-fx.ts
+/** The node path a refused `fx.start` names when the test gives none. */
+const defaultPath = "test";
+/**
+* Builds the `fx` of a node context for a unit test that calls `node.run(context)` itself, with no
+* app and no runner. It records every call and plays no effect: `await fx(descriptor)` goes to
+* `awaited` and resolves with `options.answer(descriptor)`, `fx.start(descriptor)` goes to
+* `started`, `fx.emit(hint)` goes to `emitted`. `fx.start` refuses a descriptor with `answers`
+* and a `guide` with the error the game throws. An `answer` that fails rejects the awaited
+* effect, and resolves `undefined` for a `cosmetic` descriptor, as in the game. There is no
+* handler, no log, no fast mode and no abort signal here: for those, walk the graph with
+* `createHeadless`.
+*
+* @param options - The answer of an awaited effect, and the node path for the refusal message.
+* @returns The `fx` and the lists `awaited`, `started` and `emitted`.
+* @example
+* ```ts
+* // The body of the node "place" runs fx.start(sfx("ui.tap")), then pushes input.cell to
+* // session.marks. `context` is the rest of its context: input, player, session, rng, out,
+* // signal and now.
+* const fx = fakeFx();
+*
+* await place.run?.({ ...context, fx: fx.fx });
+*
+* fx.started; // [{ kind: "sfx", payload: { key: "ui.tap", bus: "sfx" }, cosmetic: true }]
+* fx.awaited; // []: the body waited for no effect
+*
+* // The node "retry" awaits a popup that takes answers. The test gives the player's pick.
+* const picked = fakeFx({
+*   answer: descriptor => (descriptor.kind === "popup" ? { intent: "again" } : undefined)
+* });
+*
+* await retry.run?.({ ...context, fx: picked.fx });
+*
+* picked.awaited; // [{ kind: "popup", payload: { name: "Retry" }, answers: ["again", "home"] }]
+* ```
+*/
+function fakeFx(options = {}) {
+	const path = options.path ?? defaultPath;
+	const awaited = [];
+	const started = [];
+	const emitted = [];
+	/**
+	* Records one awaited effect and answers it. Both happen at the call. An `answer` that throws
+	* or rejects is a handler that fails: the effect rejects, never the call. A `cosmetic`
+	* descriptor swallows that failure and resolves `undefined`, as the gateway of the game does.
+	*
+	* @param descriptor - The descriptor the body awaits.
+	* @returns A promise of what `options.answer` gives for it.
+	*/
+	const run = async (descriptor) => {
+		awaited.push(descriptor);
+		try {
+			return await options.answer?.(descriptor);
+		} catch (error) {
+			if (descriptor.cosmetic !== true) throw error;
+		}
+	};
+	const fx = Object.assign(run, {
+		/**
+		* Records one hint. Nothing releases it: the test has no edge to commit.
+		*
+		* @param item - The hint.
+		*/
+		emit: (item) => {
+			emitted.push(item);
+		},
+		/**
+		* Records one started effect, unless the real `fx.start` would refuse it.
+		*
+		* @param descriptor - The descriptor the body starts.
+		* @throws {Error} When the descriptor has `answers` or is a `guide`.
+		*/
+		start: (descriptor) => {
+			refuseStart(descriptor, path);
+			started.push(descriptor);
+		}
+	});
+	return Object.freeze({
+		fx,
+		awaited,
+		started,
+		emitted
+	});
+}
+//#endregion
 //#region src/testing/isolate.ts
 const noPayload = null;
 /** Id of the harness main flow. */
@@ -191,4 +277,4 @@ function isolate(feature, options) {
 	});
 }
 //#endregion
-export { createHeadless, fakeClock, isolate, memory, runRepro, saveOf, stepFrames, stub };
+export { createHeadless, fakeClock, fakeFx, isolate, memory, runRepro, saveOf, stepFrames, stub };

package/dist/{types-DMoi447V.d.mts → types-BX4Ge_j5.d.mts}

@@ -1,5 +1,5 @@
-import { A as Api$1, B as ComponentType, D as FilterSlot, H as Entity, O as Point, R as ComponentHandle, Sn as Require, _ as PixiFilter, b as PixiTexture, dt as Api, h as Api$2, s as Events, t as Api$3, v as PixiModule, xn as Events$1, y as PixiSprite } from "./types-BT9S_Lo2.mjs";
-import { x as AnimApi } from "./types-kNiV7iFj.mjs";
+import { A as Api$1, B as ComponentType, Cn as Require, D as FilterSlot, H as Entity, O as Point, R as ComponentHandle, Sn as Events$1, _ as PixiFilter, b as PixiTexture, dt as Api, h as Api$2, s as Events, t as Api$3, v as PixiModule, y as PixiSprite } from "./types-BjTtGSFb.mjs";
+import { x as AnimApi } from "./types-Y_rCuXtj.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 

package/dist/{types-BT9S_Lo2.d.mts → types-BjTtGSFb.d.mts}

@@ -1419,7 +1419,8 @@ type GateApi = {
 //#region src/plugins/flow/fx/types.d.ts
 /**
  * An effect a node awaits. With `answers` the runner opens the gate for those intents.
- * `cosmetic: true` swallows a handler error and resolves `undefined`.
+ * `cosmetic: true` keeps a handler error away from the node: the effect resolves `undefined` and
+ * the log gets the warn entry `flow:fx-cosmetic-failed` with `{ kind, message }`.
  *
  * @example
  * ```ts
@@ -1617,9 +1618,10 @@ type NodeFx = ((descriptor: Descriptor) => Promise<unknown>) & {
    * Starts an effect now and does not wait for it: the handler is called at once and the body goes
    * on. Fast mode and the node's signal apply as for `await fx(descriptor)`. A handler that fails
    * never fails the node: the log gets the error entry `flow:fx-start-failed` with
-   * `{ path, kind }`, and a `cosmetic` descriptor is silent. After the abort of the node nothing is
-   * started, and a rejection that comes after the abort is not logged: the handler was told to
-   * stop.
+   * `{ path, kind }`. For a `cosmetic` descriptor it gets the warn entry `flow:fx-cosmetic-failed`
+   * with `{ kind, message }` instead, as it does when the effect is awaited. After the abort of the
+   * node nothing is started, and a rejection that comes after the abort is not logged: the handler
+   * was told to stop.
    *
    * @param descriptor - The effect to start. Not one with `answers` and not a `guide`.
    * @throws {Error} When the descriptor has `answers` or is a `guide`: an answer has to be awaited.
@@ -7489,4 +7491,4 @@ type FlowRest = {
  */
 type HotSwap = Events$6["ui:hot-swap"];
 //#endregion
-export { DescriptionNode as $, types_d_exports$5 as $t, Api$2 as A, FlowGraph as At, ComponentType as B, Answer as Bt, types_d_exports$1 as C, slot as Ct, FilterSlot as D, AnyFlow as Dt, DebugSwitches as E, FeatureDescription as Et, AnyComponent as F, SceneIdOf as Ft, Mut as G, State$4 as Gt, Entity as H, ClockSource as Ht, AnyComponentType as I, TypeTag as It, QueryTerm as J, Config$5 as Jt, Narrowed as K, types_d_exports$4 as Kt, AnyComponentValue as L, Descriptor as Lt, Explained as M, JournalEntry as Mt, State$2 as N, NodeTable as Nt, Point as O, Bookmark as Ot, types_d_exports$2 as P, RouteStep as Pt, ChangeHook as Q, State$5 as Qt, ComponentHandle as R, GuideOptions as Rt, Under as S, Require as Sn, exit as St, RenderStats as T, type as Tt, EntitySnapshot as U, Config$4 as Ut, ComponentValue as V, Api$4 as Vt, FrameDiff as W, FakeClock as Wt, SystemDefinition as X, Json as Xt, ResourceType as Y, Events$4 as Yt, TagType as Z, Root as Zt, PixiFilter as _, State$7 as _n, Position as _t, Config as a, Snapshot as an, NumericFields as at, PixiTexture as b, Config$8 as bn, types_d_exports$3 as bt, LoadBundles as c, RngState as cn, TrackOptions as ct, State as d, Events$5 as dn, Api$3 as dt, Patch as en, Ease as et, Tier as f, PauseReason as fn, BundlesOf as ft, Config$1 as g, Config$7 as gn, GameTypes as gt, Api$1 as h, Api$7 as hn, FeaturePlugin as ht, BundleSpec as i, SaveUnreadableError as in, MotionHandle as it, Config$2 as j, FlowState as jt, ViewportSize as k, DefineNode as kt, LoadReason as l, Api$6 as ln, TrackSegment as lt, types_d_exports as m, types_d_exports$6 as mn, EmitterIdOf as mt, AssetsIo as n, ProviderCall as nn, LayerSpec as nt, DefineBundles as o, StoreApi as on, ProjectionMotion as ot, Usage as p, State$6 as pn, Config$3 as pt, Owner as q, Api$5 as qt, BundleMap as r, SaveDoc as rn, Motion as rt, Events as s, RngApi as sn, ProjectionSpec as st, Api as t, PlayerStateProvider as tn, LayerSort as tt, Manifest as u, Config$6 as un, ViewHandle as ut, PixiModule as v, Time as vn, State$3 as vt, Captured as w, to as wt, State$1 as x, Events$6 as xn, defineFlow as xt, PixiSprite as y, types_d_exports$7 as yn, TextStylesOf as yt, ComponentSchema as z, Hint as zt };
+export { DescriptionNode as $, State$5 as $t, Api$2 as A, FlowGraph as At, ComponentType as B, NodeFx as Bt, types_d_exports$1 as C, Require as Cn, slot as Ct, FilterSlot as D, AnyFlow as Dt, DebugSwitches as E, FeatureDescription as Et, AnyComponent as F, SceneIdOf as Ft, Mut as G, FakeClock as Gt, Entity as H, Api$4 as Ht, AnyComponentType as I, TypeTag as It, QueryTerm as J, Api$5 as Jt, Narrowed as K, State$4 as Kt, AnyComponentValue as L, Descriptor as Lt, Explained as M, JournalEntry as Mt, State$2 as N, NodeTable as Nt, Point as O, Bookmark as Ot, types_d_exports$2 as P, RouteStep as Pt, ChangeHook as Q, Root as Qt, ComponentHandle as R, GuideOptions as Rt, Under as S, Events$6 as Sn, exit as St, RenderStats as T, type as Tt, EntitySnapshot as U, ClockSource as Ut, ComponentValue as V, Answer as Vt, FrameDiff as W, Config$4 as Wt, SystemDefinition as X, Events$4 as Xt, ResourceType as Y, Config$5 as Yt, TagType as Z, Json as Zt, PixiFilter as _, Config$7 as _n, Position as _t, Config as a, SaveUnreadableError as an, NumericFields as at, PixiTexture as b, types_d_exports$7 as bn, types_d_exports$3 as bt, LoadBundles as c, RngApi as cn, TrackOptions as ct, State as d, Config$6 as dn, Api$3 as dt, types_d_exports$5 as en, Ease as et, Tier as f, Events$5 as fn, BundlesOf as ft, Config$1 as g, Api$7 as gn, GameTypes as gt, Api$1 as h, types_d_exports$6 as hn, FeaturePlugin as ht, BundleSpec as i, SaveDoc as in, MotionHandle as it, Config$2 as j, FlowState as jt, ViewportSize as k, DefineNode as kt, LoadReason as l, RngState as ln, TrackSegment as lt, types_d_exports as m, State$6 as mn, EmitterIdOf as mt, AssetsIo as n, PlayerStateProvider as nn, LayerSpec as nt, DefineBundles as o, Snapshot as on, ProjectionMotion as ot, Usage as p, PauseReason as pn, Config$3 as pt, Owner as q, types_d_exports$4 as qt, BundleMap as r, ProviderCall as rn, Motion as rt, Events as s, StoreApi as sn, ProjectionSpec as st, Api as t, Patch as tn, LayerSort as tt, Manifest as u, Api$6 as un, ViewHandle as ut, PixiModule as v, State$7 as vn, State$3 as vt, Captured as w, to as wt, State$1 as x, Config$8 as xn, defineFlow as xt, PixiSprite as y, Time as yn, TextStylesOf as yt, ComponentSchema as z, Hint as zt };

package/dist/{types-Bc9AvZVO.d.mts → types-CAPv9l29.d.mts}

@@ -1,5 +1,5 @@
-import { Xt as Json, an as Snapshot } from "./types-BT9S_Lo2.mjs";
-import { t as HeadlessApp } from "./headless-CrhefcLu.mjs";
+import { Zt as Json, on as Snapshot } from "./types-BjTtGSFb.mjs";
+import { t as HeadlessApp } from "./headless-CMHNsKjW.mjs";
 import { Log } from "@moku-labs/common/browser";
 
 //#region src/plugins/flow/doors/types.d.ts

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

@@ -1,4 +1,4 @@
-import { A as Api$2, B as ComponentType, F as AnyComponent, H as Entity, I as AnyComponentType, L as AnyComponentValue, Lt as Descriptor, O as Point$2, Q as ChangeHook, Sn as Require, V as ComponentValue, Vt as Api$5, Xt as Json, at as NumericFields, dt as Api$1, h as Api$3, hn as Api, it as MotionHandle, k as ViewportSize, ot as ProjectionMotion, rt as Motion, s as Events$1, t as Api$4, ut as ViewHandle, zt as Hint } from "./types-BT9S_Lo2.mjs";
+import { A as Api$2, B as ComponentType, Cn as Require, F as AnyComponent, H as Entity, Ht as Api$5, I as AnyComponentType, L as AnyComponentValue, Lt as Descriptor, O as Point$2, Q as ChangeHook, V as ComponentValue, Zt as Json, at as NumericFields, dt as Api$1, gn as Api, h as Api$3, it as MotionHandle, k as ViewportSize, ot as ProjectionMotion, rt as Motion, s as Events$1, t as Api$4, ut as ViewHandle, zt as Hint } from "./types-BjTtGSFb.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 
@@ -2461,6 +2461,15 @@ type ScrollWindow = {
   first: number;
   last: number;
 };
+/**
+ * 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
+ * raw `style` and the state flags say what they said, the resolved style is kept.
+ */
+type StyleBasis = {
+  epoch: number;
+  rowHeight: number | undefined;
+};
 /**
  * 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`
@@ -2473,7 +2482,9 @@ type ScrollWindow = {
  * 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.
+ * new string measures the same asks for no solve. `basis` is what `style` was resolved on, set
+ * once the style is on the layout node and the components are written; an element without one is
+ * patched in full at its next patch.
  */
 type Element = {
   entity: Entity;
@@ -2519,6 +2530,7 @@ type Element = {
     width: number;
     height: number;
   };
+  basis?: StyleBasis;
 };
 /**
  * The popup side of a root: the handler that shows it now and the root it was opened over.
@@ -2674,7 +2686,8 @@ 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. `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.
+ * counts the re-renders of a windowed list its range made. `styled` and `written` count the style
+ * passes and the write passes of the reconcile, for `UiCounters`.
  */
 type JsxState = {
   components: Map<string, AnyComponentDefinition>;
@@ -2695,6 +2708,15 @@ type JsxState = {
   scrolls: Set<Entity>;
   windowRenders: number; /** True from a restore or a load until the next reconcile built every root again. */
   remount: boolean;
+  /**
+   * Counts what changes every style at once: a new viewport, a dev hot swap. An element last
+   * patched in an earlier epoch is patched in full, however equal its description is. A new
+   * locale and a font that arrives are no epoch: `text` resolves the labels again and the
+   * remeasure step measures them.
+   */
+  epoch: number;
+  styled: number;
+  written: number;
 };
 /**
  * One node of the snapshot `tree()` answers with. `rect` is natural: under a `fit` ancestor it

package/dist/{types-kNiV7iFj.d.mts → types-Y_rCuXtj.d.mts}

@@ -1,5 +1,5 @@
-import { A as Api$2, B as ComponentType, F as AnyComponent, H as Entity, It as TypeTag, L as AnyComponentValue, Lt as Descriptor, R as ComponentHandle, Sn as Require, Xt as Json, Yt as Events$2, at as NumericFields, ct as TrackOptions, dn as Events$3, dt as Api$1, et as Ease, h as Api$5, hn as Api, it as MotionHandle, lt as TrackSegment, nt as LayerSpec, q as Owner, qt as Api$4, s as Events$4, t as Api$3, tt as LayerSort, xn as Events$5 } from "./types-BT9S_Lo2.mjs";
-import { A as InputApi, c as UiNode, i as Finding, n as ElementChange, o as JsxState, q as I18nApi, r as ElementMotion, rt as StylesState, x as TextApi } from "./types-BZa187kz.mjs";
+import { A as Api$2, B as ComponentType, Cn as Require, F as AnyComponent, H as Entity, It as TypeTag, Jt as Api$4, L as AnyComponentValue, Lt as Descriptor, R as ComponentHandle, Sn as Events$5, Xt as Events$2, Zt as Json, at as NumericFields, ct as TrackOptions, dt as Api$1, et as Ease, fn as Events$3, gn as Api, h as Api$5, it as MotionHandle, lt as TrackSegment, nt as LayerSpec, q as Owner, s as Events$4, t as Api$3, tt as LayerSort } from "./types-BjTtGSFb.mjs";
+import { A as InputApi, c as UiNode, i as Finding, n as ElementChange, o as JsxState, q as I18nApi, r as ElementMotion, rt as StylesState, x as TextApi } from "./types-DOlpeuGx.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 import { Node, Yoga } from "yoga-layout/load";
@@ -1840,7 +1840,8 @@ type LayoutState = {
   scrollStart: {
     pointerY: number;
     offset: number;
-  };
+  }; /** 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>;
 };

package/dist/{types-yiHtzg1Y.d.mts → types-gisvSHoC.d.mts}

@@ -1,7 +1,7 @@
-import { Dt as AnyFlow, Ht as ClockSource, Jt as Config, Wt as FakeClock, Xt as Json, a as Config$3, g as Config$2, ht as FeaturePlugin, n as AssetsIo, pt as Config$1, tn as PlayerStateProvider, u as Manifest, v as PixiModule } from "./types-BT9S_Lo2.mjs";
-import { o as AudioContextLike, s as Config$4 } from "./types-kNiV7iFj.mjs";
-import { _t as audioPlugin, ct as PlatformProvider, ht as effectsPlugin, i as screen, ot as platformPlugin, t as createApp } from "./index-0GIP3tgm.mjs";
-import { t as memory } from "./memory-DR1ibF_s.mjs";
+import { Dt as AnyFlow, Gt as FakeClock, Ut as ClockSource, Yt as Config, Zt as Json, a as Config$3, g as Config$2, ht as FeaturePlugin, n as AssetsIo, nn as PlayerStateProvider, pt as Config$1, u as Manifest, v as PixiModule } from "./types-BjTtGSFb.mjs";
+import { o as AudioContextLike, s as Config$4 } from "./types-Y_rCuXtj.mjs";
+import { _t as audioPlugin, ct as PlatformProvider, ht as effectsPlugin, i as screen, ot as platformPlugin, t as createApp } from "./index-CLQ8NOTw.mjs";
+import { t as memory } from "./memory-pUQ7YZWC.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/app/types.d.ts

package/dist/visual.d.mts

@@ -1,9 +1,9 @@
-import { A as Api$1, h as Api, ln as Api$3, qt as Api$2 } from "./types-BT9S_Lo2.mjs";
-import { r as UiApi, x as AnimApi } from "./types-kNiV7iFj.mjs";
-import { A as InputApi } from "./types-BZa187kz.mjs";
-import { r as Repro } from "./headless-CrhefcLu.mjs";
-import { a as InputOf, r as ControlApp } from "./types-Bc9AvZVO.mjs";
-import { t as commands } from "./commands-d5Zlh9hf.mjs";
+import { A as Api$1, Jt as Api$2, h as Api, un as Api$3 } from "./types-BjTtGSFb.mjs";
+import { r as UiApi, x as AnimApi } from "./types-Y_rCuXtj.mjs";
+import { A as InputApi } from "./types-DOlpeuGx.mjs";
+import { r as Repro } from "./headless-CMHNsKjW.mjs";
+import { a as InputOf, r as ControlApp } from "./types-CAPv9l29.mjs";
+import { t as commands } from "./commands-BaCx2B9j.mjs";
 
 //#region src/visual/types.d.ts
 /** The base commands of the `/control` door, keyed by their short names. */

package/llms.txt

@@ -11,7 +11,7 @@ Facts: Bun only. ESM only. `"sideEffects"` lists the root entry `./dist/index.mj
 - `@moku-labs/game/app/page` (the browser): `startPage`, the page the generated `.moku/main.ts` calls.
 - `@moku-labs/game/app/system` (the browser, the native shell): `systemShellOf`, `fromSystem`, `storeSave`, `createSystemApp`, the type `SystemModules`, over the optional peer `@moku-labs/system`. The one entry that names it, in types only: the page hands it the loaders.
 - `@moku-labs/game/cli` (node and bun only): `runCli`, the bin `moku-game`, `preparePage`, the editor's dev page, and `watchKeys`, the watch that keeps `generated/` fresh next to it.
-- `@moku-labs/game/testing`: headless play, repro runs, isolated feature tests (`isolate`, `stub`), fake clock, in-memory save provider. No `node:` import.
+- `@moku-labs/game/testing`: headless play, repro runs, isolated feature tests (`isolate`, `stub`), fake clock, the `fx` of a node for a unit test (`fakeFx`), in-memory save provider. No `node:` import.
 - `@moku-labs/game/visual` (node and bun only): the visual tests `defineVisualTest`, `runVisualTests`, `parseVisualArgv`. The bin runs them: `moku-game visual`.
 - `@moku-labs/game/assets` (node and bun only): the asset key scanner, the production packer and the string compiler. The package bin `moku-game-assets` runs it.
 - `@moku-labs/game/inspect`: the read door of the editor, safe in a production build. See "Doors for the editor".
@@ -43,7 +43,7 @@ Root exports:
 - Transit node: has `run`, no `rest`. Rest node: `rest: true`. The graph waits there. Without `run` it is a pure wait.
 - A pure wait ends in two ways. A gate answer whose `intent` is an outcome name: the answer payload becomes the outcome payload. Or a world event whose `type` is listed in the node's `inbox`: the event payload becomes the outcome payload.
 - Transition: rest node to rest node. It is a transaction. On an error the runner discards, rolls back to the last rest point, retries `retries` times, then enters `safeNode`. A failure inside `safeNode` rejects `run()`.
-- Three ways to run an effect in a node. `await fx(descriptor)`: the node waits for it. `fx.start(descriptor)`: it starts now and the node goes on; write it in place of `void fx(...)`. A failure of a started effect is the log entry `flow:fx-start-failed` and never fails the node; a descriptor with `answers` and a `guide` are refused, they have to be awaited. `fx.emit(hint(...))`: released after the commit of the edge, dropped in fast mode.
+- Three ways to run an effect in a node. `await fx(descriptor)`: the node waits for it. `fx.start(descriptor)`: it starts now and the node goes on; write it in place of `void fx(...)`. A failure of a started effect is the log entry `flow:fx-start-failed` and never fails the node. A `cosmetic` descriptor (`sfx`, `play`, `haptic`, `music`) that fails, awaited or started, is the warn entry `flow:fx-cosmetic-failed` with `{ kind, message }` and resolves `undefined`; a descriptor with `answers` and a `guide` are refused, they have to be awaited. `fx.emit(hint(...))`: released after the commit of the edge, dropped in fast mode.
 - Every failure is written into the log by the engine: an `error` entry `flow:error` with `{ path, rolledBackTo, retry, error: { message, stack } }`. Read it with `app.log.trace()`. A game needs no plugin for it.
 - `recover` on a rest node: `recover: async ({ player, session, rng, fx, signal, now }) => { ... }`. It runs only when the runner gave up on a transition and enters this node as `safeNode`, before the node is entered. The rollback left the state of the failed rest point; `recover` writes the drafts so the safe node can draw itself. What it wrote commits as one edge with `outcome: "recover"` and becomes the rest point. A `recover` that throws rejects `run()`. A retry does not run it. So the safe node stays a pure wait: no `run` body, no extra outcome, no self edge.
 - Entering a rest node calls `model.store.markRest()`: the save provider gets the patches. Leaving a `barrier` node calls `markBarrier(txId)`: a durable write, and rollback cannot cross it.
@@ -483,6 +483,7 @@ The graph. Modules `runner`, `gate`, `inbox`, `fx`, `features`. Runner methods s
 - After a rollback (a node failed) a view of a projection that the node moved and that still stands off its rest pose is settled, also when its item did not change. Ui elements are not settled by a rollback, and a timeline the failed node started without `await` runs on.
 - A loop adds its sway on top of the value under it. The world compares that value with the rest pose, so a looping view that stands at home is never settled, and one a node moved is brought home while its loop runs on. A custom tween driver may report what its additive tracks add with the optional `offsetsOf(entity, component)`; without it the stored value is compared as it stands.
 - The `loop` hook of a view runs while the world is live and `anim` is installed: a view that entered on a load, a mount or a restore gets its loop from the next live frame. `anim.finishAll()` ends it; the next flush of the world (a load, a restore, a commit in a paused or fast world) owes it again.
+- For a JSX screen ui compares the description prop by prop, by value: inline styles are fine, an equal description costs nothing (no style pass, no layout, no write), hooks stay built once (a function compares by identity). A style object changed in place is not seen: build a new one.
 - A projection may build a new item object on every commit. A view whose components did not change keeps its running motions; only a real component change cancels them. No frozen item tables are needed.
 - After a `restore` or a load the picture is the one of the restored state, whatever played before: every view of a mounted projection stands on its rest pose, its `loop` starts again on the next live frame and no other motion runs, and every ui root is built again through the mount path, so `enter` hooks run and a loop starts as after a fresh mount. Scroll offsets, local state, hover and focus start anew. Look an element up again with `ui.find(key)` after a restore. A rest node names the scene it is shown on (`scene: "splash"`): a restore into a node without `scene` keeps the mounted scene.
 - `restore` of a rest node resolves when the node is entered. `restore` of a transit node runs it again from its start, so its effects before the gate play again, and resolves once its gate is open. The open gate is not the draw: the popup shows on the next frame. `restore` also resolves when the loop ends before the bookmark was entered, after a stop or a fatal error, and nothing is entered then.
@@ -659,7 +660,7 @@ The scanner keys it `ui.font-body`, which is the `text` config default `fonts.bo
 
 ## Testing entry
 
-Exports of `@moku-labs/game/testing`: `createHeadless`, `runRepro`, `stepFrames`, `fakeClock`, `memory`, `saveOf`, `isolate`, `stub`. The visual tests `defineVisualTest`, `runVisualTests`, `parseVisualArgv` come from `@moku-labs/game/visual`, node and bun only (see `docs/testing.md` in the engine repository).
+Exports of `@moku-labs/game/testing`: `createHeadless`, `runRepro`, `stepFrames`, `fakeClock`, `memory`, `saveOf`, `isolate`, `stub`, `fakeFx`. `fakeFx(options?)` is the `fx` of a node context for a unit test that calls `node.run?.({ ...context, fx: fake.fx })`: it returns `{ fx, awaited, started, emitted }`, `options.answer(descriptor)` gives what an awaited effect resolves with, and `fx.start` refuses `answers` and a `guide` as the game does. The visual tests `defineVisualTest`, `runVisualTests`, `parseVisualArgv` come from `@moku-labs/game/visual`, node and bun only (see `docs/testing.md` in the engine repository).
 
 - `createHeadless(app): Promise<HeadlessGame>`. Pass an app that is not started. It sets mode `"fast"`, awaits `app.start()`, starts `flow.run()` unless the app's `onStart` already did, and resolves when the loop rests for the first time: `game.state().path` already names the first rest node. A fatal error of `run()` rejects the call.
 - `HeadlessGame`: `walk(route): Promise<FlowState>`, `answer(answer): boolean`, `state()`, `history()`, `stop()`. `walk` and `stop` throw a fatal error of the loop again when the headless runner owns `run()`.

package/package.json

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