@moku-labs/game 0.15.28 → 0.15.30

package/dist/testing.d.mts

@@ -1,7 +1,7 @@
-import { Er as Json, Qn as FeaturePlugin, br as FakeClock, er as AnyFlow, hr as NodeFx, mr as Hint, or as NodeTable, ur as Descriptor, vr as ClockSource } from "./types-C_nC_M4p.mjs";
-import { t as createApp } from "./index-Dn_v0Fqs.mjs";
-import { b as saveOf, v as WithGameState, y as memory } from "./types-Bsa1nFyU.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-DBYmnluy.mjs";
+import { $n as FeaturePlugin, Dr as Json, dr as Descriptor, gr as NodeFx, hr as Hint, sr as NodeTable, tr as AnyFlow, xr as FakeClock, yr as ClockSource } from "./types-D27I4Q7b.mjs";
+import { t as createApp } from "./index-B2GejbLf.mjs";
+import { b as saveOf, v as WithGameState, y as memory } from "./types-BWRJcZ3n.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-f31cEZ7f.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/plugins/clock/fake.d.ts

package/dist/testing.mjs

@@ -1,4 +1,4 @@
-import { en as refuseStart, in as type, m as flattenFeatures, t as createApp, tn as exit } from "./src-DPvSTM8O.mjs";
+import { en as refuseStart, in as type, m as flattenFeatures, t as createApp, tn as exit } from "./src-B4JjsuEy.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-Bxxl_mQX.mjs";

package/dist/{types-bEJEga5m.d.mts → types-BAp9HdR4.d.mts}

@@ -1,4 +1,4 @@
-import { An as ProjectionMotion, Cn as ChangeHook, Dn as MotionCause, En as Motion, Er as Json, Fn as ViewHandle, G as TransformValue, In as Api$1, J as Api$3, Kr as Api, Mn as ReducedMotion, On as MotionHandle, Sn as TagType, Tn as Ease, _r as Api$5, cn as AnyComponentValue, dn as ComponentType, gr as Answer, kn as NumericFields, mr as Hint, ni as Require, on as AnyComponent, pn as Entity, s as Events$1, sn as AnyComponentType, t as Api$4, tn as Api$2, ur as Descriptor, ut as ViewportSize } from "./types-C_nC_M4p.mjs";
+import { An as NumericFields, Cn as TagType, Dn as Motion, Dr as Json, En as Ease, In as ViewHandle, K as TransformValue, Ln as Api$1, Nn as ReducedMotion, On as MotionCause, Y as Api$3, _r as Answer, cn as AnyComponentType, dr as Descriptor, dt as ViewportSize, fn as ComponentType, hr as Hint, jn as ProjectionMotion, kn as MotionHandle, ln as AnyComponentValue, mn as Entity, nn as Api$2, qr as Api, ri as Require, s as Events$1, sn as AnyComponent, t as Api$4, vr as Api$5, wn as ChangeHook } from "./types-D27I4Q7b.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 import { Node, Yoga } from "yoga-layout/load";
@@ -2790,6 +2790,12 @@ type Root = {
     h: number;
   } | undefined;
   pending?: boolean;
+  /**
+   * Present from the reconcile that found the root in the scene `world` builds aside (spec 31)
+   * until the reconcile that finds it committed, which gives the slots out again. Absent on every
+   * other root.
+   */
+  aside?: true;
 };
 /**
  * Where the focus ring was last drawn: the layer and order of its root, the rect grown by the
@@ -2950,6 +2956,7 @@ type JsxState = {
   /**
    * The elements whose `Box` came since the last `sync`: their enter hooks played at the `Box` (F49) and are settled
    * there, after the game's systems, played again when a system changed what a hook read (F48). The first `count` slots are the queue; the array keeps its length, so a frame allocates nothing.
+   * An element of a scene `world` builds aside stays queued, its hook unplayed, until the swap (spec 31).
    */
   entering: {
     list: Entity[];
@@ -2969,7 +2976,8 @@ type JsxState = {
   written: number; /** The wall times of the last taps on a `DebugTrigger` view, five at the most. */
   debugTaps: number[]; /** Whether `ui:debug-trigger-no-agent` was logged: once per app. */
   debugWarned: boolean; /** Elements that carry `Overlay`, from their enter to their despawn (spec 22 O4.5). */
-  overlays: Set<Entity>;
+  overlays: Set<Entity>; /** How many roots carry `aside`, as the last reconcile counted them: 0 while no scene is built aside. */
+  asideRoots: number;
 };
 /**
  * One node of the snapshot `tree()` answers with. `rect` is natural: under a `fit` ancestor it

package/dist/{types-Bsa1nFyU.d.mts → types-BWRJcZ3n.d.mts}

@@ -1,7 +1,7 @@
-import { Er as Json, Ir as SnapshotOf, Mr as ProviderCall, Nr as SaveDoc, Q as PixiModule, Qn as FeaturePlugin, Rn as Config$1, Y as Config$2, a as Config$3, br as FakeClock, ct as Orientation, d as Manifest, er as AnyFlow, jr as PlayerStateProvider, lr as TypeTag, n as AssetsIo, vr as ClockSource, wr as Config } from "./types-C_nC_M4p.mjs";
-import { o as AudioContextLike, s as Config$4 } from "./types-C76NQm-h.mjs";
-import { R as I18nApi, U as StringTable, W as TextKey } from "./types-bEJEga5m.mjs";
-import { St as effectsPlugin, Tt as audioPlugin, ht as PlatformProvider, i as screen, pt as platformPlugin, t as createApp } from "./index-Dn_v0Fqs.mjs";
+import { $ as PixiModule, $n as FeaturePlugin, Dr as Json, Lr as SnapshotOf, Mr as PlayerStateProvider, Nr as ProviderCall, Pr as SaveDoc, Tr as Config, X as Config$2, a as Config$3, d as Manifest, lt as Orientation, n as AssetsIo, tr as AnyFlow, ur as TypeTag, xr as FakeClock, yr as ClockSource, zn as Config$1 } from "./types-D27I4Q7b.mjs";
+import { o as AudioContextLike, s as Config$4 } from "./types-DjQkfbfZ.mjs";
+import { R as I18nApi, U as StringTable, W as TextKey } from "./types-BAp9HdR4.mjs";
+import { St as effectsPlugin, Tt as audioPlugin, ht as PlatformProvider, i as screen, pt as platformPlugin, t as createApp } from "./index-B2GejbLf.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/plugins/model/store/providers/memory.d.ts

package/dist/{types-DTetCcBC.d.mts → types-CgE5L_7f.d.mts}

@@ -1,5 +1,5 @@
-import { Er as Json, Fr as Snapshot } from "./types-C_nC_M4p.mjs";
-import { t as HeadlessApp } from "./headless-DBYmnluy.mjs";
+import { Dr as Json, Ir as Snapshot } from "./types-D27I4Q7b.mjs";
+import { t as HeadlessApp } from "./headless-f31cEZ7f.mjs";
 import { Log } from "@moku-labs/common/browser";
 
 //#region src/plugins/flow/doors/types.d.ts

package/dist/{types-C_nC_M4p.d.mts → types-D27I4Q7b.d.mts}

@@ -3969,14 +3969,16 @@ type Motion = MotionHandle | void;
 /**
  * Why a motion hook plays: `"mount"` when the view or element comes or goes with its screen (a scene mount or
  * unmount, a load, a restore, a paused or fast world), `"change"` when a commit changed a live screen (a new key,
- * a key that left, a new element in a live tree, a popup).
+ * a key that left, a new element in a live tree, a popup). `"discard"` when an aborted scene build dropped the view
+ * before it was ever drawn (`projection.discard()`): it plays no exit, so a game's hook never sees it; the removal
+ * hook of `ui` reads it through `causeOf` and drops the root at once.
  *
  * @example
  * ```ts
  * const cause: MotionCause = "change";
  * ```
  */
-type MotionCause = "mount" | "change";
+type MotionCause = "mount" | "change" | "discard";
 /**
  * What reduced motion does to one track: `"cut"` (the default) lands it on its target at the next frame step, or holds
  * a loop on its first key; `"keep"` plays it as written. The engine never guesses which tracks are fades: the author
@@ -4481,7 +4483,29 @@ type ProjectionState = {
    * The despawn count of the ecs when the sweep last looked for dead elements; -1 after a new
    * key, so the next sweep looks.
    */
-  sweptDespawns: number;
+  sweptDespawns: number; /** The running build of the next scene; absent when none runs, never written as `undefined`. */
+  building?: Building; /** The `onBuild` checks: every one answers true before `built()` does. Kept across builds. */
+  buildChecks: Array<() => boolean>;
+};
+/**
+ * The build of the next scene aside (spec 31): its projections mounted into a table of their own, so a name never has
+ * two records in `mounted`, and every entity the build spawned, so `isBuilding` answers with one lookup. Absent while
+ * no build runs.
+ */
+type Building = {
+  /** The projection list of the coming scene, in its order: the places of its screen roots. */names: readonly string[]; /** The layer list of the coming scene, as the caller handed it: the build checked the names against it. */
+  layers: ReadonlyArray<LayerSpec>; /** Who owns the entities of the projections the build mounts. */
+  owner: Owner; /** The projections only the coming list names, mounted aside until the commit moves them into `mounted`. */
+  mounted: Map<string, Mounted>; /** Every entity of the build: the views it spawned and the entities `adopt` marked. */
+  entities: Set<Entity>; /** The game clock at the start of this frame (world's `input` phase), or at the build start in its own frame. */
+  frameStart: number; /** Milliseconds per frame the building work may take. */
+  budgetMs: number;
+  /**
+   * Whether a reconcile passed over a mounted projection the coming list drops, which keeps what it showed when the
+   * switch began: `"change"`, or `"rerun"` when that reconcile forced `view`. The commit and the discard then mark the
+   * world dirty, so one still mounted reads the store in the next frame. Absent while none was passed over.
+   */
+  held?: "change" | "rerun";
 };
 /**
  * projection module API, `app.world.projection`: the bridge from the model to entities.
@@ -4680,8 +4704,8 @@ type ProjectionApi = {
   membershipVersion(): number;
   /**
    * How the view of an entity came, or how it is leaving: `"mount"` when a direct reconcile or an unmount moved it,
-   * `"change"` when a live commit did. A despawned view still answers until the next sweep, so a hook on its removal
-   * can ask. `undefined` for an entity no projection made.
+   * `"change"` when a live commit did, `"discard"` when `discard()` dropped the build it belonged to. A despawned view
+   * still answers until the next sweep, so a hook on its removal can ask. `undefined` for an entity no projection made.
    *
    * @param entity - A view, or a view in its removal hook.
    * @returns The cause, or `undefined`.
@@ -4744,11 +4768,12 @@ type ProjectionApi = {
   entityOf(projection: string, key: string): Entity | undefined;
   /**
    * The live view entities of a mounted projection, in the order of its model keys. A view that
-   * plays its exit is left out, and so is an element registered with `registerKey`. Every call
-   * hands out a new array.
+   * plays its exit is left out, and so is an element registered with `registerKey`. A projection
+   * the running build mounts answers its building views (`isBuilding` tells them apart), so a host
+   * of the coming scene can take them before the swap. Every call hands out a new array.
    *
    * @param name - Name of the projection.
-   * @returns The entities, or `[]` when the projection is not mounted.
+   * @returns The entities, or `[]` when the projection is neither mounted nor being built.
    * @example
    * ```ts
    * // `ui` hosts the board inside a slot and parents every board item to it on reconcile.
@@ -4864,6 +4889,161 @@ type ProjectionApi = {
    * ```
    */
   rerunAll(): void;
+  /**
+   * Starts building the next scene aside, while the current one stays mounted, drawn and alive. The projections only
+   * the coming list names are mounted at once, direct, against the committed state, into a table of their own: their
+   * views are spawned and flagged building (`isBuilding`), and their screen roots take the `Order` of their place in
+   * the coming list. `entityOf` does not answer for them until `commit`. A projection the current scene mounts and
+   * the coming list declares alike (F23) is not touched now. Answers `false` and touches nothing when a listed
+   * projection is mounted now under other layer rules: building it beside its live twin would need two records under
+   * one name, so the caller takes the one-block path (`setLayers`, `unmount`, `mount`). Nothing is built when the call
+   * throws: the entities a throwing `view` left behind are despawned first.
+   *
+   * @param names - The projection list of the coming scene, in its order.
+   * @param owner - Who owns the entities of the projections the build mounts.
+   * @param layers - The layer list of the coming scene: the names are checked against it, not the current list.
+   * @param budgetMs - Milliseconds per frame the building work of the other plugins may take, read through `left`.
+   * @returns True when the build runs, false when a listed projection is mounted now under other layer rules.
+   * @throws {Error} When a build already runs, for an unknown name, for a `layer` or `lift` the coming list does not
+   *   declare, and when a `view` throws.
+   * @example
+   * ```ts
+   * // `scenes` leaves the ward, whose HUD draws in `ui` sorted by order.
+   * const projection = ctx.require(worldPlugin).projection;
+   *
+   * // The shop sorts `ui` otherwise: nothing is built, `scenes` mounts the shop in one block.
+   * projection.build(
+   *   ["hud", "shop.shelf"],
+   *   { kind: "plugin", name: "scenes" },
+   *   [{ name: "ui", sort: "none" }],
+   *   4
+   * ); // false
+   *
+   * // The board declares `ui` alike: the HUD stays, the board items are built aside.
+   * projection.build(
+   *   ["board.items", "hud"],
+   *   { kind: "plugin", name: "scenes" },
+   *   [{ name: "items", sort: "y" }, { name: "ui", sort: "order" }],
+   *   4
+   * ); // true
+   * projection.entityOf("board.items", "i7"); // undefined until the commit
+   *
+   * // A second build before the commit or the discard of the first:
+   * projection.build(["shop.shelf"], { kind: "plugin", name: "scenes" }, [{ name: "ui", sort: "none" }], 4);
+   * // throws: A scene is already being built
+   * ```
+   */
+  build(names: readonly string[], owner: Owner, layers: ReadonlyArray<LayerSpec>, budgetMs: number): boolean;
+  /**
+   * Whether the running build is done: true when a build runs and every `onBuild` check answers true, false without a
+   * build. A caller polls it once a frame; it is never an event.
+   *
+   * @returns True when the build can be committed.
+   * @example
+   * ```ts
+   * // `scenes`, in its `signals` callback while the board builds:
+   * const projection = ctx.require(worldPlugin).projection;
+   * projection.built(); // false on the first build frame: the renderer still creates views
+   * projection.built(); // true two frames later: commit now
+   * ```
+   */
+  built(): boolean;
+  /**
+   * The swap of a build: its projections become mounted, each at the `Order` of its place in the coming list as
+   * `mount` would write it, a kept projection (F23) takes its new place, every building flag clears and the table is
+   * dropped. Each moved and kept projection takes the layer list `setLayers` stored just before, so the next scene
+   * compares it by identity as after a `mount`. The loops of the moved views start in the next live sweep. Does nothing
+   * without a build.
+   *
+   * @example
+   * ```ts
+   * // `scenes`, in the frame `built()` first answers true: the layers, the leaving list out, the build in.
+   * const projection = ctx.require(worldPlugin).projection;
+   * projection.setLayers([{ name: "items", sort: "y" }, { name: "ui", sort: "order" }]);
+   * projection.unmount(["ward.beds"]);
+   * projection.commit();
+   * projection.entityOf("board.items", "i7"); // 1048600: mounted now
+   * projection.built(); // false: nothing builds any more
+   * ```
+   */
+  commit(): void;
+  /**
+   * Drops the running build: every entity it spawned, its views and the entities `adopt` marked, is despawned at once
+   * with no motion, and the table is dropped. A dropped view leaves with the cause `"discard"`, which a removal hook
+   * reads through `causeOf`. The mounted projections, the layer list and the scene of the world are not touched. Does
+   * nothing without a build.
+   *
+   * @example
+   * ```ts
+   * // `scenes`: a restore aborted the node while the board was built.
+   * const projection = ctx.require(worldPlugin).projection;
+   * projection.discard();
+   * projection.causeOf(1_048_600); // "discard", until the next sweep
+   * projection.isBuilding(1_048_600); // false
+   * ```
+   */
+  discard(): void;
+  /**
+   * Milliseconds of building budget left in this frame: the build's `budgetMs` minus the game clock time since the
+   * frame started (read at the start of world's `input` phase). The clock counts whole milliseconds. Negative once
+   * the frame spent more; `Infinity` with no build. Allocates nothing.
+   *
+   * @returns The milliseconds left, or `Infinity`.
+   * @example
+   * ```ts
+   * // A renderer build step creates held views while the frame has budget, at least one a frame.
+   * const projection = ctx.require(worldPlugin).projection;
+   * projection.left(); // 3: 1 ms of the 4 ms budget is spent
+   * projection.left(); // -1 after 4 ms more of views: the rest waits for the next frame
+   * ```
+   */
+  left(): number;
+  /**
+   * Whether an entity belongs to the running build: a view it spawned, or an entity `adopt` marked. One set lookup;
+   * false with no build and after the commit. Allocates nothing.
+   *
+   * @param entity - The entity to ask about.
+   * @returns True for an entity of the running build.
+   * @example
+   * ```ts
+   * // The renderer pass sorts the views of the coming scene out of its live work.
+   * const projection = ctx.require(worldPlugin).projection;
+   * projection.isBuilding(1_048_600); // true: a board item the build spawned
+   * projection.isBuilding(1_048_576); // false: a ward bed on screen
+   * ```
+   */
+  isBuilding(entity: Entity): boolean;
+  /**
+   * Registers one part of the build that has to be done before the swap: `built()` answers true only when every
+   * registered check does. A registration stays across builds.
+   *
+   * @param check - Answers true when the caller's part of the running build is done.
+   * @returns The remover; calling it twice is safe.
+   * @example
+   * ```ts
+   * // The renderer, at start: its part is done when no building view waits for its Pixi object.
+   * const off = ctx.require(worldPlugin).projection.onBuild(() => state.aside.count === 0);
+   *
+   * off(); // onStop: the renderer is gone
+   * ```
+   */
+  onBuild(check: () => boolean): () => void;
+  /**
+   * Marks an entity another plugin spawned for a building root as building, so `isBuilding` answers for the whole
+   * tree and `discard` despawns it with the rest. Does nothing with no build; the commit clears the mark with every
+   * other.
+   *
+   * @param entity - The entity to mark.
+   * @example
+   * ```ts
+   * // `ui` spawns an element of a building root and marks it right away.
+   * const world = ctx.require(worldPlugin);
+   * const button = world.ecs.spawn({ kind: "plugin", name: "ui" }, []);
+   * world.projection.adopt(button);
+   * world.projection.isBuilding(button); // true until the commit
+   * ```
+   */
+  adopt(entity: Entity): void;
 };
 /**
  * projection methods the plugin root drives from the frame and the hooks. Not public.
@@ -4880,6 +5060,13 @@ type ProjectionInternal = {
    * Reconciles when the world is dirty. Runs at the start of `time` phase `input`.
    */
   reconcileIfDirty(): void;
+  /**
+   * Records the moment a frame starts, for the budget `left()` counts down. Runs first in `time`
+   * phase `input`, with the moment `Now` gets; a frame without a build only reads a field.
+   *
+   * @param now - The game clock at the start of the frame.
+   */
+  startFrame(now: number): void;
   /**
    * Empties the hint buffer. Runs once per frame, reconcile or not.
    */
@@ -7142,9 +7329,11 @@ type PerfLongFrameLine = PerfLine<"longFrame"> & LongFrameEntry & {
  * it on the 2b debug build; `"pool-trim"` is the pool trim of spec 25, detail `PoolTrimDetail`; `"warm"` is the end of
  * a pipeline warm-up run of spec 27, detail `WarmDetail`; `"sections"` is a switch of the monitor's sections, detail
  * `{ on, off }`: the names of the sections on and off, in the order of `MONITOR_SECTIONS`; `"scale"` is a move of the
- * render scale of the adaptive frame rate, detail `{ from, to, reason, fps }`).
+ * render scale of the adaptive frame rate, detail `{ from, to, reason, fps }`; `"scene:build"` is the start of a
+ * scene built aside on a live switch (spec 31), detail `{ from, to }`, and the `"scene"` line of its commit carries
+ * `buildFrames`, `buildMs` and the budget of a frame it ran with, `budgetMs`, too).
  */
-type PerfEventName = "scene" | "overlay" | "bundle" | "compile" | "upload" | "resolution" | "device-lost" | "device-restored" | "pause" | "resume" | "switch" | "display" | "command" | "recorder" | "rate" | "devtools" | "pool-trim" | "warm" | "shader" | "problem" | "debug" | "sections" | "scale";
+type PerfEventName = "scene" | "scene:build" | "overlay" | "bundle" | "compile" | "upload" | "resolution" | "device-lost" | "device-restored" | "pause" | "resume" | "switch" | "display" | "command" | "recorder" | "rate" | "devtools" | "pool-trim" | "warm" | "shader" | "problem" | "debug" | "sections" | "scale";
 /**
  * What an `overlay` event line says happened to an overlay (spec 22 O10.2): it opened, landed (its enter motion is
  * over), started to leave, is gone, or its range went live or was kept again (the live fallback).
@@ -10040,6 +10229,12 @@ type View = {
   hiddenSelf: number; /** The reasons that hide the whole subtree, on the top (`hidden.ts`). */
   hiddenTop: number; /** The HUD factor an overlay fades this view with (a `HudPart`), 1 for every other view (spec 22 O7). */
   hud: number;
+  /**
+   * A held top of a scene build (spec 31): a view of the next scene with no parent, or with a live parent, built while
+   * the current scene stays drawn. It hangs nowhere in the stage, is listed in `SyncState.heldViews`, and is attached
+   * in the pass after the commit.
+   */
+  held: boolean;
 };
 /**
  * The crop of a `"cover"` sprite: a texture that shows the part of `base` covering one box.
@@ -10800,8 +10995,10 @@ type SyncInternal = {
    */
   rebuildAll(): void;
   /**
-   * One pass over the change sets: removed, layers, added, changed, the views that lost their `Parent`, the orphans
-   * whose parent has a view now, the adapters' values, the invalidated keys and the nine-slice switch.
+   * One pass over the change sets: removed, layers, the held views of a scene build that was committed, added, changed,
+   * the views that lost their `Parent`, the orphans whose parent has a view now, the adapters' values, the invalidated
+   * keys and the nine-slice switch; then, while a scene is built aside, the views of its aside queue under the build
+   * budget (spec 31).
    */
   pass(): void;
   /**
@@ -10864,6 +11061,13 @@ type SyncInternal = {
    * @returns True when it drew a probe in this frame: the frame is then no sample of the adaptive rate.
    */
   warmStep(): boolean;
+  /**
+   * The render phase's half of a scene build (spec 31): tells whether the pass made views of the build aside in this
+   * frame, and clears the count, so a frame the pass did not run in reads false. A field read and no allocation.
+   *
+   * @returns True when this frame did building work: such a frame is no sample of the adaptive rate.
+   */
+  takeBuildWork(): boolean;
   /**
    * Uploads up to `renderer.uploads` queued texture sources (F60), in a drawn frame, right after the warm-up's probes
    * and before the stage pass. Asks for the next frame while sources wait. One compare and no allocation while the
@@ -11170,6 +11374,28 @@ type SyncCounts = {
   views: number;
   pooled: number;
 };
+/**
+ * The building entities whose view waits to be made (spec 31): sorted out of `added` by the pass while a scene is
+ * built aside, made in chunks after the live pass under `world.projection.left()`. The queue is dense, from `head` to
+ * `count`, in the order the pass sorted them, and emptied when the head reaches the end. Private to `sync`.
+ */
+type AsideQueue = {
+  entities: Entity[];
+  count: number;
+  head: number; /** The entities of the queue that have no view yet: a parent that waits here is made before its child. */
+  waiting: Set<Entity>; /** The views the pass made aside in the current frame, read and cleared by the render phase (`takeBuildWork`). */
+  made: number;
+};
+/**
+ * The held tops of a scene build, in the order they were made (spec 31): dense, from 0 to `count`. A slot whose view
+ * went, or that hangs under a building parent by now, is stale and skipped. Not `held`, the unseen cache of the
+ * loops. Private to `sync`.
+ */
+type HeldViews = {
+  entities: Entity[];
+  count: number; /** The dev check named a building view under the stage in this build: named once. */
+  reported: boolean;
+};
 /**
  * sync module state.
  */
@@ -11253,7 +11479,9 @@ type SyncState = {
    */
   passesVersion: number; /** The filtered views' passes of `renderPassesOf`, counted at `passesVersion` `at` under `root`. */
   passes: PassCount; /** The name of the scene's HUD layer (`above: "overlays"`), kept with the layers; `undefined` without one. */
-  hudLayer: string | undefined;
+  hudLayer: string | undefined; /** The building entities waiting for their view (spec 31). */
+  aside: AsideQueue; /** The held tops of the scene build, attached in the pass after its commit (spec 31). */
+  heldViews: HeldViews;
   cleanups: Array<() => void>;
 };
 /**
@@ -11288,7 +11516,7 @@ type PassCount = {
   enabled: boolean[];
 };
 declare namespace types_d_exports$1 {
-  export { AnySceneProjection, CheckedProjections, Config$1 as Config, DefineScene, Deps$1 as Deps, Events$1 as Events, KernelSlice$1 as KernelSlice, LayerMap, RunContext, SceneDefinition, SceneLayer, SceneOwner, SceneProjection, SceneSpec, SceneState, ScenesApi, ScenesCtx, SortRule, State$1 as State, UiLayer };
+  export { AnySceneProjection, CheckedProjections, Config$1 as Config, DefineScene, Deps$1 as Deps, Events$1 as Events, KernelSlice$1 as KernelSlice, LayerMap, RunContext, SceneBuild, SceneDefinition, SceneLayer, SceneOwner, SceneProjection, SceneSpec, SceneState, ScenesApi, ScenesCtx, SortRule, State$1 as State, UiLayer };
 }
 /**
  * How a layer orders what is drawn in it. The scene's name for the rule `world` stores.
@@ -11483,15 +11711,45 @@ type SceneOwner = Owner & {
   name: "scenes";
 };
 /**
- * scenes plugin config: none. A scene is data in a feature, and a transition effect is V3 work
- * of `anim`, so a key here would have no reader.
+ * scenes plugin config. A scene is data in a feature; the one key is the budget of a live switch.
  *
  * @example
  * ```ts
- * const config: Config = {};
+ * // The default: half of each frame, read at the start of every build: 8.33… ms at 60 Hz, 4.17 ms at 120 Hz.
+ * const config: Config = { buildMs: "auto" };
+ *
+ * // A game on a slow phone gives the next scene a fixed 3 ms of each frame: the switch takes more frames.
+ * const fixed: Config = { buildMs: 3 };
  * ```
  */
-type Config$1 = Record<string, never>;
+type Config$1 = {
+  /**
+   * Milliseconds per frame the next scene's building work may take on a live switch with a
+   * drawing renderer: a finite number above 0, or `"auto"` (the default) for half of the frame
+   * interval the loop runs at, `500 / time.rate().fps`, read once at the build start.
+   */
+  buildMs: number | "auto";
+};
+/**
+ * The running build of the next scene (spec 31): what the commit needs, and how to stop
+ * listening. Absent while no build runs.
+ */
+type SceneBuild = {
+  /** The scene being built. */scene: SceneDefinition; /** The bundles it names, as they were awaited. */
+  named: readonly string[]; /** The scene current at the build start, the one that leaves at the commit. */
+  from: string | undefined; /** Frames the build waited in so far. */
+  frames: number; /** The building budget of a frame the build runs with, ms: `buildMs`, or what `"auto"` gave at its start. */
+  budgetMs: number; /** The page clock of an agent build at the build start, ms; 0 in a build without the flag. */
+  startedAt: number; /** Removes the frame callback and the abort listener of the build. */
+  off: () => void; /** Settles the switch once the build is committed, discarded or dropped by a stop. */
+  resolve: () => void;
+  /**
+   * Rejects the switch when the commit threw.
+   *
+   * @param error - What the commit threw.
+   */
+  reject: (error: unknown) => void;
+};
 /**
  * scenes plugin state.
  */
@@ -11513,6 +11771,11 @@ type State$1 = {
   named: readonly string[];
   owner: SceneOwner; /** The remover of the `onEnter` callback: set in `onStart`, run in `onStop`. */
   teardown: (() => void) | undefined;
+  /**
+   * The build of the next scene on a live switch, from its start to its commit or discard.
+   * Absent otherwise: deleted, never written as `undefined`.
+   */
+  build?: SceneBuild;
 };
 /**
  * scenes plugin events.
@@ -11588,7 +11851,11 @@ type Deps$1 = {
   world: Api$2;
   assets: Api;
   time: Api$7;
-  model: Api$5; /** The performance log of an agent build names every switch. */
+  model: Api$5;
+  /**
+   * Whether the renderer draws, which chooses the path of a switch, and the performance log of
+   * an agent build that names every switch.
+   */
   renderer: Api$1;
 };
 /**
@@ -12212,7 +12479,12 @@ type State = {
    * The bundles a scene named before and the list names no more: held until a phase `sync` finds nothing carrying
    * `Exiting`, so a leaving scene's pictures stay until its elements played their exit (F51, F51b).
    */
-  sceneLeaving: string[]; /** How many entities carry `Exiting` now, counted from the world's `onAdded` and `onRemoved` of the tag. */
+  sceneLeaving: string[];
+  /**
+   * The bundles of the scene being built aside, from the last `sceneComing` call: held like `sceneNamed` from the
+   * build start until `sceneBundles` names them at the swap, or until a discarded build empties the list (F61 S2).
+   */
+  sceneComing: string[]; /** How many entities carry `Exiting` now, counted from the world's `onAdded` and `onRemoved` of the tag. */
   exiting: number; /** Registered companions, in registration order. */
   companions: BundleCompanion[]; /** A live rest was announced; the arriving node's `load` stage runs the release. */
   restPending: boolean;
@@ -12465,7 +12737,8 @@ type Api = {
    * released by `release: "leave"` while it stays in the list. A bundle the list named before and names no more
    * stays held until a phase `sync` finds nothing carrying `Exiting`, so a leaving scene's pictures stay until its
    * elements played their exit, also when the exit starts only in the frame after the switch; then a `"leave"` one
-   * goes (F51, F51b). Called by `scenes`; a game never calls it.
+   * goes (F51, F51b). It empties the list of `sceneComing`: the coming scene is now the mounted one. Called by
+   * `scenes`; a game never calls it.
    *
    * @param named - The bundle names of the mounted scene, the scene bundle first.
    * @example
@@ -12478,6 +12751,23 @@ type Api = {
    * ```
    */
   sceneBundles(named: readonly string[]): void;
+  /**
+   * Tells assets which bundles the scene being built aside names, while the scene before stays mounted (F61 S2).
+   * Each call replaces the list. A bundle in it is held as a mounted scene's is: never a victim of the budget, never
+   * released by `release: "leave"`. The next `sceneBundles` call empties it, because the coming scene is then the
+   * mounted one; a discarded build calls it with `[]`. Called by `scenes`; a game never calls it.
+   *
+   * @param named - The bundle names of the coming scene, the scene bundle first.
+   * @example
+   * ```ts
+   * // scenes, at the build start of the switch from the ward to the board of episode 1.
+   * ctx.require(assetsPlugin).sceneComing(["board", "ep01"]);
+   * // a rest or budget pressure during the build leaves board and ep01 loaded
+   * ctx.require(assetsPlugin).sceneComing([]);
+   * // the build was discarded: board and ep01 are held no more
+   * ```
+   */
+  sceneComing(named: readonly string[]): void;
   /**
    * Tells whether the manifest carries a bundle, loaded or not. It reads the manifest only, so it
    * answers the same live and headless.
@@ -12597,4 +12887,4 @@ type BundleCompanion = {
   unload(bundle: string): void;
 };
 //#endregion
-export { PixiSprite as $, FeatureTree as $n, types_d_exports$8 as $r, WarmDetail as $t, Display as A, ProjectionMotion as An, Patch as Ar, PerfChangeEntry as At, Sprite as B, GameTypes as Bn, Api$6 as Br, PerfMarkLine as Bt, ScenesApi as C, ChangeHook as Cn, Api$5 as Cr, PERF_GAP_BUCKETS as Ct, FilterSlot as D, MotionCause as Dn, Root as Dr, PassRecord as Dt, DebugSwitches as E, Motion as En, Json as Er, PassKind as Et, Overlay as F, ViewHandle as Fn, Snapshot as Fr, PerfEventName as Ft, TransformValue as G, types_d_exports$4 as Gn, types_d_exports$7 as Gr, PerfTelemetryLine as Gt, SpriteOptions as H, Position as Hn, Events$6 as Hr, PerfSampleLine as Ht, OverlayValue as I, Api$3 as In, SnapshotOf as Ir, PerfGapLine as It, Api$1 as J, slot as Jn, FrameRate as Jr, ProblemEventDetail as Jt, sprite as K, defineFlow as Kn, Api$7 as Kr, PerfThermalLine as Kt, Parent as L, BundlesOf as Ln, StoreApi as Lr, PerfHeaderLine as Lt, HudPartValue as M, ReducedMotion as Mn, ProviderCall as Mr, PerfCounts as Mt, NineSlice$1 as N, TrackOptions as Nn, SaveDoc as Nr, PerfDisplay as Nt, FilterSlotInputs as O, MotionHandle as On, State$6 as Or, PerfCause as Ot, NineSliceValue as P, TrackSegment as Pn, SaveUnreadableError as Pr, PerfEventLine as Pt, PixiModule as Q, FeaturePlugin as Qn, Time as Qr, ShaderWhat as Qt, Shape as R, Config$4 as Rn, RngApi as Rr, PerfLogLine as Rt, SceneSpec as S, TagType as Sn, types_d_exports$5 as Sr, PERF_CAUSES as St, types_d_exports$1 as T, Ease as Tn, Events$5 as Tr, PROBLEM_RULES as Tt, SpriteValue as U, State$4 as Un, PauseReason as Ur, PerfSpikeLine as Ut, SpriteBlend as V, HudKeysOf as Vn, Config$7 as Vr, PerfMeasured as Vt, Transform as W, TextStylesOf as Wn, State$7 as Wr, PerfStartupLine as Wt, MonitorConfig as X, type as Xn, State$8 as Xr, SHADER_WHATS as Xt, Config$2 as Y, to as Yn, RateChange as Yr, ProblemRule as Yt, PixiFilter as Z, FeatureDescription as Zn, ThermalReading as Zr, ShaderEventDetail as Zt, AnySceneProjection as _, Narrowed as _n, Api$4 as _r, LongFrameEntry as _t, Config as a, types_d_exports$3 as an, JournalEntry as ar, Captured as at, LayerMap as b, SystemDefinition as bn, FakeClock as br, OverlayEventDetail as bt, LoadBundles as c, AnyComponentValue as cn, SceneIdOf as cr, Orientation as ct, Manifest as d, ComponentType as dn, Effect as dr, FilterCache as dt, Config$9 as ei, DEMAND_REASONS as en, AnyFlow as er, PixiTexture as et, ReadyBundles as f, ComponentValue as fn, EffectOptions as fr, FrameColumns as ft, types_d_exports as g, Mut as gn, Answer as gr, FrameRing as gt, Usage as h, FrameDiff as hn, NodeFx as hr, FrameRecord as ht, BundleSpec as i, State$3 as in, FlowState as ir, types_d_exports$2 as it, HudPart as j, ProjectionSpec as jn, PlayerStateProvider as jr, PerfCollectorLine as jt, SyncApi as k, NumericFields as kn, types_d_exports$6 as kr, PerfChange as kt, LoadReason as l, ComponentHandle as ln, TypeTag as lr, Point as lt, Tier as m, EntitySnapshot as mn, Hint as mr, FrameReadout as mt, AssetsIo as n, Require as ni, Config$3 as nn, DefineNode as nr, State$2 as nt, DefineBundles as o, AnyComponent as on, NodeTable as or, MonitorCounts as ot, State as p, Entity as pn, GuideOptions as pr, FrameReadResult as pt, AdaptiveScale as q, exit as qn, Config$8 as qr, PoolTrimDetail as qt, BundleMap as r, Explained as rn, FlowGraph as rr, Under as rt, Events as s, AnyComponentType as sn, RouteStep as sr, RenderStats as st, Api as t, Events$8 as ti, Api$2 as tn, Bookmark as tr, PoolTrim as tt, LoadResult as u, ComponentSchema as un, Descriptor as ur, ViewportSize as ut, DefineScene as v, QueryTerm as vn, ClockSource as vr, MONITOR_SECTIONS as vt, State$1 as w, DescriptionNode as wn, Config$6 as wr, PERF_LOG_VERSION as wt, SceneDefinition as x, SystemFor as xn, State$5 as xr, OverlayWhat as xt, Events$1 as y, ResourceType as yn, Config$5 as yr, MonitorSections as yt, ShapeValue as z, EmitterIdOf as zn, RngState as zr, PerfLongFrameLine as zt };
+export { PixiModule as $, FeaturePlugin as $n, Time as $r, ShaderWhat as $t, SyncApi as A, NumericFields as An, types_d_exports$6 as Ar, PerfChange as At, ShapeValue as B, EmitterIdOf as Bn, RngState as Br, PerfLongFrameLine as Bt, SceneSpec as C, TagType as Cn, types_d_exports$5 as Cr, PERF_CAUSES as Ct, DebugSwitches as D, Motion as Dn, Json as Dr, PassKind as Dt, types_d_exports$1 as E, Ease as En, Events$5 as Er, PROBLEM_RULES as Et, NineSliceValue as F, TrackSegment as Fn, SaveUnreadableError as Fr, PerfEventLine as Ft, Transform as G, TextStylesOf as Gn, State$7 as Gr, PerfStartupLine as Gt, SpriteBlend as H, HudKeysOf as Hn, Config$7 as Hr, PerfMeasured as Ht, Overlay as I, ViewHandle as In, Snapshot as Ir, PerfEventName as It, AdaptiveScale as J, exit as Jn, Config$8 as Jr, PoolTrimDetail as Jt, TransformValue as K, types_d_exports$4 as Kn, types_d_exports$7 as Kr, PerfTelemetryLine as Kt, OverlayValue as L, Api$3 as Ln, SnapshotOf as Lr, PerfGapLine as Lt, HudPart as M, ProjectionSpec as Mn, PlayerStateProvider as Mr, PerfCollectorLine as Mt, HudPartValue as N, ReducedMotion as Nn, ProviderCall as Nr, PerfCounts as Nt, FilterSlot as O, MotionCause as On, Root as Or, PassRecord as Ot, NineSlice$1 as P, TrackOptions as Pn, SaveDoc as Pr, PerfDisplay as Pt, PixiFilter as Q, FeatureDescription as Qn, ThermalReading as Qr, ShaderEventDetail as Qt, Parent as R, BundlesOf as Rn, StoreApi as Rr, PerfHeaderLine as Rt, SceneDefinition as S, SystemFor as Sn, State$5 as Sr, OverlayWhat as St, State$1 as T, DescriptionNode as Tn, Config$6 as Tr, PERF_LOG_VERSION as Tt, SpriteOptions as U, Position as Un, Events$6 as Ur, PerfSampleLine as Ut, Sprite as V, GameTypes as Vn, Api$6 as Vr, PerfMarkLine as Vt, SpriteValue as W, State$4 as Wn, PauseReason as Wr, PerfSpikeLine as Wt, Config$2 as X, to as Xn, RateChange as Xr, ProblemRule as Xt, Api$1 as Y, slot as Yn, FrameRate as Yr, ProblemEventDetail as Yt, MonitorConfig as Z, type as Zn, State$8 as Zr, SHADER_WHATS as Zt, AnySceneProjection as _, Mut as _n, Answer as _r, FrameRing as _t, Config as a, State$3 as an, FlowState as ar, types_d_exports$2 as at, Events$1 as b, ResourceType as bn, Config$5 as br, MonitorSections as bt, LoadBundles as c, AnyComponentType as cn, RouteStep as cr, RenderStats as ct, Manifest as d, ComponentSchema as dn, Descriptor as dr, ViewportSize as dt, types_d_exports$8 as ei, WarmDetail as en, FeatureTree as er, PixiSprite as et, ReadyBundles as f, ComponentType as fn, Effect as fr, FilterCache as ft, types_d_exports as g, FrameDiff as gn, NodeFx as gr, FrameRecord as gt, Usage as h, EntitySnapshot as hn, Hint as hr, FrameReadout as ht, BundleSpec as i, Explained as in, FlowGraph as ir, Under as it, Display as j, ProjectionMotion as jn, Patch as jr, PerfChangeEntry as jt, FilterSlotInputs as k, MotionHandle as kn, State$6 as kr, PerfCause as kt, LoadReason as l, AnyComponentValue as ln, SceneIdOf as lr, Orientation as lt, Tier as m, Entity as mn, GuideOptions as mr, FrameReadResult as mt, AssetsIo as n, Events$8 as ni, Api$2 as nn, Bookmark as nr, PoolTrim as nt, DefineBundles as o, types_d_exports$3 as on, JournalEntry as or, Captured as ot, State as p, ComponentValue as pn, EffectOptions as pr, FrameColumns as pt, sprite as q, defineFlow as qn, Api$7 as qr, PerfThermalLine as qt, BundleMap as r, Require as ri, Config$3 as rn, DefineNode as rr, State$2 as rt, Events as s, AnyComponent as sn, NodeTable as sr, MonitorCounts as st, Api as t, Config$9 as ti, DEMAND_REASONS as tn, AnyFlow as tr, PixiTexture as tt, LoadResult as u, ComponentHandle as un, TypeTag as ur, Point as ut, Config$1 as v, Narrowed as vn, Api$4 as vr, LongFrameEntry as vt, ScenesApi as w, ChangeHook as wn, Api$5 as wr, PERF_GAP_BUCKETS as wt, LayerMap as x, SystemDefinition as xn, FakeClock as xr, OverlayEventDetail as xt, DefineScene as y, QueryTerm as yn, ClockSource as yr, MONITOR_SECTIONS as yt, Shape as z, Config$4 as zn, RngApi as zr, PerfLogLine as zt };

package/dist/{types-C76NQm-h.d.mts → types-DjQkfbfZ.d.mts}

@@ -1,5 +1,5 @@
-import { $ as PixiSprite, Cr as Api$6, D as FilterSlot, Er as Json, Hr as Events$5, In as Api$2, J as Api$4, Kr as Api$1, Mn as ReducedMotion, Nn as TrackOptions, O as FilterSlotInputs, On as MotionHandle, Pn as TrackSegment, Q as PixiModule, Tn as Ease, Tr as Events$3, Z as PixiFilter, cn as AnyComponentValue, dn as ComponentType, dt as FilterCache, et as PixiTexture, k as SyncApi, kn as NumericFields, ln as ComponentHandle, lr as TypeTag, lt as Point, ni as Require, on as AnyComponent, pn as Entity, s as Events$1, t as Api$5, ti as Events$2, tn as Api$3, ur as Descriptor, y as Events$4 } from "./types-C_nC_M4p.mjs";
-import { N as InputApi, R as I18nApi, X as StylesState, c as UiNode, i as Finding, l as LayoutState, n as ElementChange, o as JsxState, r as ElementMotion, w as TextApi } from "./types-bEJEga5m.mjs";
+import { $ as PixiModule, A as SyncApi, An as NumericFields, Dr as Json, En as Ease, Er as Events$3, Fn as TrackSegment, Ln as Api$2, Nn as ReducedMotion, O as FilterSlot, Pn as TrackOptions, Q as PixiFilter, Ur as Events$5, Y as Api$4, b as Events$4, dr as Descriptor, et as PixiSprite, fn as ComponentType, ft as FilterCache, k as FilterSlotInputs, kn as MotionHandle, ln as AnyComponentValue, mn as Entity, ni as Events$2, nn as Api$3, qr as Api$1, ri as Require, s as Events$1, sn as AnyComponent, t as Api$5, tt as PixiTexture, un as ComponentHandle, ur as TypeTag, ut as Point, wr as Api$6 } from "./types-D27I4Q7b.mjs";
+import { N as InputApi, R as I18nApi, X as StylesState, c as UiNode, i as Finding, l as LayoutState, n as ElementChange, o as JsxState, r as ElementMotion, w as TextApi } from "./types-BAp9HdR4.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 

package/dist/{visual-BMRHt4IB.d.mts → visual-f6mtELhG.d.mts}

@@ -1,9 +1,9 @@
-import { Br as Api$3, Cr as Api$2, J as Api, tn as Api$1 } from "./types-C_nC_M4p.mjs";
-import { P as AnimApi, r as UiApi } from "./types-C76NQm-h.mjs";
-import { N as InputApi } from "./types-bEJEga5m.mjs";
-import { r as Repro } from "./headless-DBYmnluy.mjs";
-import { a as InputOf, r as ControlApp } from "./types-DTetCcBC.mjs";
-import { t as commands } from "./commands-BJ4gG5WZ.mjs";
+import { Vr as Api$3, Y as Api, nn as Api$1, wr as Api$2 } from "./types-D27I4Q7b.mjs";
+import { P as AnimApi, r as UiApi } from "./types-DjQkfbfZ.mjs";
+import { N as InputApi } from "./types-BAp9HdR4.mjs";
+import { r as Repro } from "./headless-f31cEZ7f.mjs";
+import { a as InputOf, r as ControlApp } from "./types-CgE5L_7f.mjs";
+import { t as commands } from "./commands-BUfZJUx6.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-BMRHt4IB.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-f6mtELhG.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-ncFMQIus.mjs";
-import { n as commands, t as run } from "./run-DRcc2SKF.mjs";
+import { n as read, t as sources } from "./sources-DM5Zcl4o.mjs";
+import { n as commands, t as run } from "./run-DyL8rl2P.mjs";
 import path from "node:path";
 import { createBrandConsole } from "@moku-labs/common/cli";
 import { mkdir, readFile, writeFile } from "node:fs/promises";