@moku-labs/game 0.14.9 → 0.14.10

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-CUNcMkD1.mjs";
-import { t as createApp } from "./index-BRdctuIb.mjs";
-import { n as saveOf, t as memory } from "./memory-D6S7BUAo.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-TowWxARz.mjs";
+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-pXWn22ql.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 { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/plugins/clock/fake.d.ts

package/dist/testing.mjs

@@ -1,4 +1,4 @@
-import { Kt as type, Ut as exit, t as createApp } from "./src-DiPISDVO.mjs";
+import { Kt as type, Ut as exit, t as createApp } from "./src-CzfMhkry.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";

package/dist/{types-p12uOu00.d.mts → types-6yCbzHHn.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-CUNcMkD1.mjs";
+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 { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 

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

@@ -1583,7 +1583,9 @@ type FxApi = {
   onHint(listener: HintListener): () => void;
 };
 /**
- * The `fx` of a node context: awaited effects by call, cosmetic hints by `emit`.
+ * The `fx` of a node context, and of the context of `recover`. Three ways to reach what is not
+ * logic: `await fx(descriptor)` runs an effect and waits for it, `fx.start(descriptor)` starts one
+ * now and does not wait, `fx.emit(hint)` keeps a cosmetic hint until the edge has committed.
  *
  * @example
  * ```ts
@@ -1594,7 +1596,45 @@ type FxApi = {
  * ```
  */
 type NodeFx = ((descriptor: Descriptor) => Promise<unknown>) & {
+  /**
+   * Buffers one cosmetic hint. It reaches its handler and the `onHint` listeners only after the
+   * commit of the edge, so a node that fails shows nothing. Fast mode drops it.
+   *
+   * @param hint - The hint, built with `hint(kind, payload)`.
+   * @example
+   * ```ts
+   * // The "merge" node: the sparkle belongs to the merge, so it is shown once the merge is real.
+   * run: ({ fx, session, input, out }) => {
+   *   session.merged.push(input.cell);
+   *   fx.emit(hint("sparkle", { cell: "c3" })); // nothing is shown yet
+   *
+   *   return out.done(); // the edge commits, then the handler of "sparkle" gets the hint
+   * }
+   * ```
+   */
   emit(hint: Hint): void;
+  /**
+   * 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.
+   *
+   * @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.
+   * @example
+   * ```ts
+   * // The "place" node of a board game: the tap sound starts, the mark is placed at once.
+   * run: ({ fx, session, input, out }) => {
+   *   fx.start(sfx("ui.tap")); // undefined: the handler of "sfx" is already playing "ui.tap"
+   *   session.marks.push(input.cell);
+   *
+   *   return out.placed(); // the edge commits while the sound still plays
+   * }
+   * ```
+   */
+  start(descriptor: Descriptor): void;
 };
 //#endregion
 //#region src/plugins/flow/inbox/types.d.ts
@@ -3284,10 +3324,19 @@ type TrackOptions = {
  * and goes through `ecs.set`, so `changed()` sees it. Muted fields are never written, also not on
  * `finish()`.
  *
+ * A driver with additive tracks keeps the value under them: an additive track adds an offset to
+ * it, and an absolute track of 0 ms to a field moves it. Such a driver reports the offsets with
+ * `offsetsOf`, so the world can compare the value under a loop with the rest pose.
+ *
  * @example
  * ```ts
  * // `anim` hands the world its own tween core in `onStart`.
- * const driver: TweenDriver = { track: startTrack, cancelAll: cancelTracksOf };
+ * const driver: TweenDriver = {
+ *   track: startTrack,
+ *   cancelAll: cancelTracksOf,
+ *   // A card sways 0.04 rad to one side right now: { rotation: 0.04 }
+ *   offsetsOf: addedOffsets
+ * };
  * const off = ctx.require(worldPlugin).projection.setDriver(driver);
  *
  * off(); // `anim` stopped: the world writes instantly again
@@ -3311,6 +3360,18 @@ type TweenDriver = {
    * @param entity - The entity whose tracks end.
    */
   cancelAll(entity: Entity): void;
+  /**
+   * What the running additive tracks add to each field of one component of one entity right now:
+   * the offset of a loop. The world takes it off the stored value before it compares a view with
+   * its rest pose, so a view that only sways is home. Optional: a driver without additive tracks
+   * leaves it out, and the world reads that as no offset.
+   *
+   * @param entity - The entity to ask about.
+   * @param component - The component to ask about.
+   * @returns Field name to the sum of the offsets on it. A field no additive track adds to is
+   *   left out.
+   */
+  offsetsOf?(entity: Entity, component: AnyComponent): Readonly<Record<string, number>>;
 };
 /**
  * One node of an element description, as `ui` builds it. The world never imports `ui`: it knows
@@ -3385,7 +3446,10 @@ type ChangeHooks<Item> = {
  * The motion hooks of a projection. Every one is optional; without a hook the component diff is
  * written directly. `loop` starts what moves a view for its whole life (an additive sway, a spin):
  * it is played wherever `enter` plays, next to it, and its motion is kept apart from the view's
- * other motions, so a change never cancels it; it ends when the view dies.
+ * other motions, so a change never cancels it; it ends when the view dies. A view that entered
+ * directly (a mount, a load, a restore, a paused or fast world) plays no `enter`, and a direct
+ * reconcile ends every track of a view: the loop is then started by the first frame in which the
+ * world is live and a tween driver is installed, once.
  *
  * @example
  * ```ts
@@ -3473,7 +3537,9 @@ type AnyProjectionSpec = {
  * Why a reconcile runs. Merged over the frame; the cause table decides play or direct. A
  * `"restore"` and a `"load"` replace the state, so their reconcile also brings every live view to
  * its rest pose, whether its item changed or not, and every element to the rest pose its owner
- * recorded with `setRest`.
+ * recorded with `setRest`. A `"rollback"` commits the state of the last rest point: a live view
+ * whose item did not change and that stands off its rest pose is settled, as `settle(entity)`
+ * does. An element another plugin owns is not.
  *
  * @example
  * ```ts
@@ -3484,21 +3550,6 @@ type Cause = "edge" | "rollback" | "restore" | "load" | "mount" | "rerun";
 /**
  * One live or exiting view: the entity of one key of one projection, its rest pose and the
  * motions that still run on it.
- *
- * @example
- * ```ts
- * const view: View = {
- *   entity: 1_048_576,
- *   projection: "board.items",
- *   key: "i7",
- *   item: { id: "i7" },
- *   rest: new Map(),
- *   handles: [],
- *   lifted: false,
- *   dropWhenStill: false,
- *   exiting: false
- * };
- * ```
  */
 type View$1 = {
   entity: Entity;
@@ -3509,6 +3560,13 @@ type View$1 = {
   handles: MotionHandle[];
   lifted: boolean; /** `lift(false)` is waiting for the last motion to end. */
   dropWhenStill: boolean;
+  /**
+   * The `loop` hook of the view is still to be started. Set when the view enters in a direct
+   * reconcile, which plays no hook, and whenever a flush ends its tracks, the loop among them.
+   * The sweep starts the loop and clears the flag, only while the world is live and a tween
+   * driver is installed. It is the only trigger, so a loop starts once.
+   */
+  loopOwed: boolean;
   exiting: boolean;
 };
 /**
@@ -3534,17 +3592,16 @@ type Mounted = {
 /**
  * One track the projection started on the driver. The world keeps the component name and the
  * handle, so it knows which components are driven without knowing how the driver runs them.
- *
- * @example
- * ```ts
- * const track: Track = { entity: 1_048_576, component: "Transform", handle: flight };
- * track.handle.active(); // true while the flight runs
- * ```
  */
 type Track = {
   entity: Entity;
   component: string;
   handle: MotionHandle;
+  /**
+   * Whether the track adds to its fields instead of owning them, as the loop of a view does. An
+   * additive track drives no component: a settle may bring the component home under it.
+   */
+  additive: boolean;
 };
 /**
  * The rest pose of one entity, by component name: the last output of `view(item)` for a view, or
@@ -3589,9 +3646,17 @@ type ProjectionState = {
   dirty: Dirty | undefined;
   hints: Hint[]; /** The tracks the projection started, with the handle that says whether they still run. */
   tracks: Track[]; /** The tween engine `anim` installed, or `undefined`: then every target is written at once. */
-  driver: TweenDriver | undefined; /** The rest pose of an entity that is not a view, recorded by its owner through `setRest`. */
+  driver: TweenDriver | undefined;
+  /**
+   * The rest pose of an entity that is not a view, recorded by its owner through `setRest`. The
+   * entry of an entity that is gone is dropped by the sweep and by the converge step.
+   */
   rests: Map<Entity, RestPose>; /** Projection name to key to the entity a plugin above registered under it. */
-  keys: Map<string, Map<string, Entity>>; /** The reverse of `keys`, so `keyOf` answers for a registered element too. */
+  keys: Map<string, Map<string, Entity>>;
+  /**
+   * The reverse of `keys`, so `keyOf` answers for a registered element too. The entry of an
+   * entity that is gone is dropped with its rest pose, and its side of `keys` with it.
+   */
   keysByEntity: Map<Entity, ProjectionKey>; /** Entity to component name to the fields another writer owns. */
   mutes: Map<Entity, Map<string, Set<string>>>; /** The `onConverged` listeners: the owners of elements, told after a restore or a load. */
   converged: Array<() => void>;
@@ -3700,8 +3765,8 @@ type ProjectionApi = {
   unmount(names: readonly string[]): void;
   /**
    * A drop with no commit: cancels the view's motions and plays settle for every loose component.
-   * In mode `paused` or `fast` the rest pose is written at once. No-op for an entity that is not
-   * a live view.
+   * A view that loops comes home too, and its loop runs on. In mode `paused` or `fast` the rest
+   * pose is written at once. No-op for an entity that is not a live view.
    *
    * @param entity - The entity of the view that was dropped.
    * @example
@@ -3732,7 +3797,8 @@ type ProjectionApi = {
   /**
    * Moves a view into or out of its projection's `lift` layer. `lift(entity, false)` on a view
    * that still moves takes effect when its last motion ends, so a settling view stays above the
-   * board until it is home.
+   * board until it is home. A reconcile or a `settle(entity)` that ends the motions of the view
+   * applies the pending drop itself.
    *
    * @param entity - The entity of the view.
    * @param on - True to lift, false to drop back.
@@ -3865,6 +3931,7 @@ type ProjectionApi = {
    * It is also where a restore and a load put the element: after their reconcile every track on
    * the entity is ended and every recorded component it still carries is written, muted fields
    * left out. So the owner records the pose it draws the element with, every time that changes.
+   * The pose of an entity that is gone is dropped in the next live frame.
    *
    * @param entity - The entity of the element.
    * @param component - The component whose rest value is recorded.
@@ -3882,6 +3949,8 @@ type ProjectionApi = {
   /**
    * Gives an entity a projection and key of its own, so `entityOf` and `keyOf` answer for it next
    * to the live views. That is how an element becomes a target for `anim`, `input` and `guide`.
+   * A key whose entity is gone is dropped in the next live frame, also when the remover was never
+   * called.
    *
    * @param projection - Name the element is addressed under.
    * @param key - Key the element is addressed under.
@@ -3957,7 +4026,10 @@ type ProjectionInternal = {
   pushHint(hint: Hint): void;
   /**
    * Sweeps the views whose motions ended: the despawn queue, the convergence check and the
-   * pending drops. The tracks themselves are advanced by the driver.
+   * pending drops. Then it drops the rest pose and the registered key of every element whose
+   * entity is gone, and starts the loop of every live view that owes one. It runs once per
+   * frame and does nothing unless the world is live. The tracks themselves are advanced by the
+   * driver.
    */
   sweep(): void;
   /**

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

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

package/dist/{types-HbY-NiRP.d.mts → types-Biehq93s.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-CUNcMkD1.mjs";
-import { o as AudioContextLike, s as Config$4 } from "./types-CmhczThS.mjs";
-import { _t as audioPlugin, ct as PlatformProvider, ht as effectsPlugin, i as screen, ot as platformPlugin, t as createApp } from "./index-BRdctuIb.mjs";
-import { t as memory } from "./memory-D6S7BUAo.mjs";
+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-DxKupZ6I.mjs";
+import { _t as audioPlugin, ct as PlatformProvider, ht as effectsPlugin, i as screen, ot as platformPlugin, t as createApp } from "./index-pXWn22ql.mjs";
+import { t as memory } from "./memory-DR1ibF_s.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/app/types.d.ts
@@ -154,9 +154,18 @@ type GameDefinition<Plugins extends readonly AnyPluginInstance[] = readonly [],
   session: Session; /** The long side the layout needs, in reference units. Default 1920. */
   referenceLong?: number; /** The rng seed of a new save. Default 42. */
   seed?: number; /** The shared layer: composed first among the features. */
-  shared?: FeaturePlugin; /** The features of the screen app, in order, after `shared`. */
+  shared?: FeaturePlugin;
+  /**
+   * The features of the screen app, in order, after `shared`. The headless app composes their
+   * logic too, unless `headless.features` names its own list.
+   */
   features?: readonly FeaturePlugin[]; /** The game's own plugins, after the features. Their APIs land on `screen().app`. */
-  plugins?: Plugins; /** What the headless app composes: the logic of these features and these plugins, nothing else. */
+  plugins?: Plugins;
+  /**
+   * What the headless app composes: the logic of these features and these plugins, nothing else.
+   * `headless.features` left out is the definition's `features`; `headless: { features: [] }`
+   * composes no feature. `shared` and `plugins` are never taken by default.
+   */
   headless?: {
     features?: readonly FeaturePlugin[];
     plugins?: HeadlessPlugins;
@@ -360,8 +369,9 @@ type ScreenSeams<Player, Session, Source, Provider> = HeadlessSeams<Player, Sess
 type GameApp<Plugins extends readonly AnyPluginInstance[] = readonly [], HeadlessPlugins extends readonly AnyPluginInstance[] = readonly [], Player extends Json = Json, Session extends Json = Json> = {
   /**
    * Makes the logic app: the core plugins, the logic of `headless.features` and the
-   * `headless.plugins`. No screen plugin, no game plugin unless listed. Each call gives a fresh
-   * app, clock and provider.
+   * `headless.plugins`. A definition without `headless.features` gives the logic of its
+   * `features`. No screen plugin, no `shared`, no game plugin unless listed. Each call gives a
+   * fresh app, clock and provider.
    *
    * @param seams - What the test pins: seed, clock, provider, player, session.
    * @returns The app, not started, and its clock and provider.

package/dist/{types-CmhczThS.d.mts → types-DxKupZ6I.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-CUNcMkD1.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-p12uOu00.mjs";
+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-6yCbzHHn.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 import { Node, Yoga } from "yoga-layout/load";
@@ -16,7 +16,7 @@ import { Node, Yoga } from "yoga-layout/load";
  *   id: 1, entity: 1_048_576, component: Transform, to: { x: 200 },
  *   keys: { x: "1048576:Transform:x" }, ms: 350, ease: "out", delayMs: 0, elapsed: 0,
  *   from: undefined, muted: () => new Set(), additive: false, driven: false, bornFrame: 4,
- *   ended: false, segments: undefined, repeatsLeft: 0, held: false
+ *   ended: false, segments: undefined, repeatsLeft: 0, held: false, masked: new Set()
  * };
  * ```
  */
@@ -55,6 +55,12 @@ type Track = {
    * walk clears it, so the next hold writes the first key again.
    */
   held: boolean;
+  /**
+   * The fields an additive track skipped at its last write because another writer owned them.
+   * When such a field is given back, the track adds to the value it finds there and not to the
+   * base it kept. Empty for a track that owns its fields.
+   */
+  masked: Set<string>;
 };
 /**
  * A motion handle that can also be advanced by hand: what the timeline cursor needs, so a track
@@ -901,7 +907,12 @@ type State$3 = {
   nextId: number; /** `"<entity>:<component>:<field>"` to the id of the absolute track that drives the field. */
   owner: Map<string, number>; /** Per field key, the delta each additive track contributes. */
   offsets: Map<string, Map<number, number>>; /** Per field key, the value the offsets are added to. Dropped when no track drives the field. */
-  bases: Map<string, number>; /** The running timelines, by id. */
+  bases: Map<string, number>;
+  /**
+   * Per entity, its running additive tracks. `offsetsOf` of the driver reads it, so the cost of
+   * one answer is the loops of that entity and not every track of the game.
+   */
+  additive: Map<Entity, Set<Track>>; /** The running timelines, by id. */
   timelines: Map<number, RunningTimeline>; /** The `animations` of every feature, read in `onStart`. */
   registry: Map<string, AnyAnimationDefinition>; /** `onMark` subscribers, in subscription order. */
   markListeners: Set<MarkListener>; /** Counter of the frame steps. A track born in the running step is not advanced by it. */

package/dist/{types-Ck18SF1P.d.mts → types-S8UOeAML.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-CUNcMkD1.mjs";
-import { x as AnimApi } from "./types-CmhczThS.mjs";
+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-DxKupZ6I.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 

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-CUNcMkD1.mjs";
-import { r as UiApi, x as AnimApi } from "./types-CmhczThS.mjs";
-import { A as InputApi } from "./types-p12uOu00.mjs";
-import { r as Repro } from "./headless-TowWxARz.mjs";
-import { a as InputOf, r as ControlApp } from "./types-CsejHij6.mjs";
-import { t as commands } from "./commands-BiZwnDBd.mjs";
+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-DxKupZ6I.mjs";
+import { A as InputApi } from "./types-6yCbzHHn.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-fUjYUA67.mjs";
 
 //#region src/visual/types.d.ts
 /** The base commands of the `/control` door, keyed by their short names. */

package/llms.txt

@@ -43,6 +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.
 - 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.
@@ -121,7 +122,7 @@ type NodeContext = {
   player: Player;        // draft of the saved player tree, mutate it
   session: Session;      // draft of the session tree, never saved
   rng: RngView;          // rng.stream(id) gives a deterministic stream
-  fx: NodeFx;            // await fx(descriptor), fx.emit(hint(...))
+  fx: NodeFx;            // await fx(descriptor), fx.start(descriptor), fx.emit(hint(...))
   out: Out;              // one method per declared outcome
   signal: AbortSignal;   // aborted on stop, restore and inbox delivery
   now: number;           // clock.now() read once at node entry
@@ -260,9 +261,9 @@ The game never calls `flow.run()`. The page runs the graph after `app.start()`;
 
 A game is a folder: `index.ts` (`export default defineGameApp({ ... })`), `config.ts` (plain data, `satisfies GameConfig`), `core/`, `shared/`, `features/`, `plugins/`, `generated/`, `tests/` with `tests/scenarios/<name>.ts`. No `web/`, no `native.ts`, no `platform-bridge.ts`, no `bunfig.toml`, no `createApp` call. `.moku/` holds what `moku-game` writes; the game's `.gitignore` lists it. Scripts of the game's `package.json`: `"dev": "moku-game dev"`, `"build": "moku-game build"`, `"native:ios-sim": "moku-game native build ios --simulator"`.
 
-- `defineGameApp(definition)` returns the game, `{ headless(seams?), screen(seams?) }`, and creates no app. Every type comes from the object; no generic at the call site. Keys: `flow` (required), `safeNode` (default: the start of the main flow), `player` and `session` (required), `referenceLong` (1920), `seed` (42), `shared` (composed first among the features), `features`, `plugins` (their APIs land on `screen().app`), `headless: { features?, plugins? }`, `pluginConfigs`.
+- `defineGameApp(definition)` returns the game, `{ headless(seams?), screen(seams?) }`, and creates no app. Every type comes from the object; no generic at the call site. Keys: `flow` (required), `safeNode` (default: the start of the main flow), `player` and `session` (required), `referenceLong` (1920), `seed` (42), `shared` (composed first among the features), `features`, `plugins` (their APIs land on `screen().app`), `headless: { features?, plugins? }` (`features` left out takes the game's `features`, `[]` means none, `shared` is not composed), `pluginConfigs`.
 - `pluginConfigs` takes every plugin of the screen app but the keys the shell writes. A seam-owned key is a compile error: `model.playerProvider`, `initialPlayer`, `initialSession`, `seed` (the game keeps `schemaVersion`, `migrations`); all of `clock` and `platform`; `flow.mainFlow`, `safeNode`; `renderer.mount`; `assets.manifest`, `io`; `audio.context`.
-- `game.headless(seams?)` composes the core plugins, `logicOnly` of `headless.features`, then `headless.plugins`. `game.screen(seams?)` composes the screen set, `audio`, `effects`, `platform`, then `shared`, the features and the game's plugins. Both return `{ app, clock, provider }`, the app not started; each call is fresh. Defaults: `fakeClock(startMoment)` (`startMoment` is `1_000_000`), a fresh `memory()` save, the seed of the definition or 42.
+- `game.headless(seams?)` composes the core plugins, `logicOnly` of `headless.features` (of `features` when left out), then `headless.plugins`. `game.screen(seams?)` composes the screen set, `audio`, `effects`, `platform`, then `shared`, the features and the game's plugins. Both return `{ app, clock, provider }`, the app not started; each call is fresh. Defaults: `fakeClock(startMoment)` (`startMoment` is `1_000_000`), a fresh `memory()` save, the seed of the definition or 42.
 - Seams of both: `seed`, `clock`, `provider`, `player`, `session`. Screen only: `manifest` (a URL or the parsed file), `io`, `platform`, `keepAwake` (false), `audio: { context?, journal? }`, `renderer: { mount?, loadPixi?, preference? }`. Without a mount the renderer is inert, so `game.screen()` runs in plain Bun.
 - `defineGameApp` throws `[game] defineGameApp needs flow.` and `[game] defineGameApp: features[2] is not a feature.` for what TypeScript cannot stop.
 - A game's exit plugin calls `ctx.require(platformPlugin).exit()` itself.
@@ -479,7 +480,11 @@ The graph. Modules `runner`, `gate`, `inbox`, `fx`, `features`. Runner methods s
 - `features.register(name, description)`, `features.all()`, `features.contributions(slotName)`.
 - `FlowState` is `{ running, path, stack, pending: { fx?, gate? }, mode }`.
 - `Bookmark` is `{ path, input, player, session, rng, graph, scene?, rest? }`. Serialisable. `scene` is written by the `game.bookmark` door and read by `game.restore`; `flow.restore` ignores it. `path` names a rest node, or the transit node that waits at the gate for an effect that takes answers (a `popup`, or a hand-written descriptor with `answers`); `rest: { path, input }` then names the rest point before it (left out when the graph started at that node or a restore entered it), and the state is the one committed when that node was entered. `restore` needs a running graph. A rest checkpoint is always accepted. Any other node is accepted only when the graph did not change since the bookmark; with another graph a transit bookmark is entered at `rest` instead when that is a checkpoint, and the log gets `flow:restore-fell-back`.
-- 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 with no motion running, 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.
+- 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.
+- 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.
 - Events: `flow:edge` `{ flow, node, outcome, payload, next, patches: { doc, session }, index, now }` after the commit of an edge. `flow:rest` `{ path, checkpoint }`. `flow:error` `{ path, error, rolledBackTo, retry }`.
 - Config: `mainFlow` default `undefined` and required before `run()`, `safeNode: string | undefined` default `undefined` which means the main flow's `start`, `retries` default `1`, `settleTimeoutMs` default `2000`, `journalLimit` default `500`, `holdMs` default `0`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/game",
-  "version": "0.14.9",
+  "version": "0.14.10",
   "description": "2D puzzle game engine on TypeScript and PixiJS, built on @moku-labs/core.",
   "type": "module",
   "sideEffects": [
@@ -155,11 +155,11 @@
     "@arethetypeswrong/core": "0.18.3",
     "@biomejs/biome": "2.4.16",
     "@formatjs/icu-messageformat-parser": "3.5.20",
-    "@moku-labs/ci": "1.5.5",
-    "@moku-labs/common": "0.3.7",
-    "@moku-labs/core": "1.7.5",
-    "@moku-labs/native": "0.3.5",
-    "@moku-labs/system": "0.3.4",
+    "@moku-labs/ci": "1.5.7",
+    "@moku-labs/common": "0.3.10",
+    "@moku-labs/core": "1.7.6",
+    "@moku-labs/native": "0.3.8",
+    "@moku-labs/system": "0.3.7",
     "@types/bun": "1.4.2",
     "@vitest/coverage-istanbul": "4.0.18",
     "eslint": "9.39.3",