@moku-labs/game 0.15.3 → 0.15.5

package/dist/testing.d.mts

@@ -1,7 +1,7 @@
-import { Jn as FeaturePlugin, Sr as Json, Xn as AnyFlow, dr as NodeFx, gr as FakeClock, mr as ClockSource, nr as NodeTable, or as Descriptor, ur as Hint } from "./types-DlC3Ytbj.mjs";
-import { t as createApp } from "./index-ByvWj9OX.mjs";
-import { b as saveOf, v as WithGameState, y as memory } from "./types-BApuIqwq.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-D0U5AXiK.mjs";
+import { Jn as FeaturePlugin, Sr as Json, Xn as AnyFlow, dr as NodeFx, gr as FakeClock, mr as ClockSource, nr as NodeTable, or as Descriptor, ur as Hint } from "./types-DnttyLeu.mjs";
+import { t as createApp } from "./index-Bq_93oZv.mjs";
+import { b as saveOf, v as WithGameState, y as memory } from "./types-6inPYTzE.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-DDkRwLnJ.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/plugins/clock/fake.d.ts

package/dist/testing.mjs

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

package/dist/{types-BApuIqwq.d.mts → types-6inPYTzE.d.mts}

@@ -1,7 +1,7 @@
-import { At as Orientation, Dr as PlayerStateProvider, E as Config$2, Jn as FeaturePlugin, Mr as SnapshotOf, Or as ProviderCall, Pn as Config$1, Sr as Json, Xn as AnyFlow, a as Config$3, ar as TypeTag, br as Config, d as Manifest, gr as FakeClock, k as PixiModule, kr as SaveDoc, mr as ClockSource, n as AssetsIo } from "./types-DlC3Ytbj.mjs";
-import { o as AudioContextLike, s as Config$4 } from "./types-CsMLBPf-.mjs";
-import { H as TextKey, I as I18nApi, V as StringTable } from "./types-yLdzHyTl.mjs";
-import { ft as platformPlugin, i as screen, mt as PlatformProvider, t as createApp, wt as audioPlugin, xt as effectsPlugin } from "./index-ByvWj9OX.mjs";
+import { At as Orientation, Dr as PlayerStateProvider, E as Config$2, Jn as FeaturePlugin, Mr as SnapshotOf, Or as ProviderCall, Pn as Config$1, Sr as Json, Xn as AnyFlow, a as Config$3, ar as TypeTag, br as Config, d as Manifest, gr as FakeClock, k as PixiModule, kr as SaveDoc, mr as ClockSource, n as AssetsIo } from "./types-DnttyLeu.mjs";
+import { o as AudioContextLike, s as Config$4 } from "./types-C2g2KYCN.mjs";
+import { H as TextKey, I as I18nApi, V as StringTable } from "./types-CWSMo70I.mjs";
+import { ft as platformPlugin, i as screen, mt as PlatformProvider, t as createApp, wt as audioPlugin, xt as effectsPlugin } from "./index-Bq_93oZv.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/plugins/model/store/providers/memory.d.ts

package/dist/{types-CsMLBPf-.d.mts → types-C2g2KYCN.d.mts}

@@ -1,5 +1,5 @@
-import { A as PixiSprite, An as TrackSegment, Hr as Api$1, Mn as Api$2, Nt as FilterCache, O as PixiFilter, On as ReducedMotion, Ot as FilterSlot, Qr as Require, Rr as Events$5, Sr as Json, T as Api$4, Tn as NumericFields, Zr as Events$2, Zt as Api$3, an as ComponentHandle, ar as TypeTag, in as AnyComponentValue, j as PixiTexture, jt as Point, k as PixiModule, kn as TrackOptions, kt as FilterSlotInputs, ln as Entity, nn as AnyComponent, or as Descriptor, s as Events$1, sn as ComponentType, t as Api$5, v as Events$4, wn as MotionHandle, xn as Ease, xr as Events$3, yr as Api$6 } from "./types-DlC3Ytbj.mjs";
-import { I as I18nApi, J as StylesState, S as TextApi, c as UiNode, i as Finding, j as InputApi, n as ElementChange, o as JsxState, r as ElementMotion } from "./types-yLdzHyTl.mjs";
+import { A as PixiSprite, An as TrackSegment, Hr as Api$1, Mn as Api$2, Nt as FilterCache, O as PixiFilter, On as ReducedMotion, Ot as FilterSlot, Qr as Require, Rr as Events$5, Sr as Json, T as Api$4, Tn as NumericFields, Zr as Events$2, Zt as Api$3, an as ComponentHandle, ar as TypeTag, in as AnyComponentValue, j as PixiTexture, jt as Point, k as PixiModule, kn as TrackOptions, kt as FilterSlotInputs, ln as Entity, nn as AnyComponent, or as Descriptor, s as Events$1, sn as ComponentType, t as Api$5, v as Events$4, wn as MotionHandle, xn as Ease, xr as Events$3, yr as Api$6 } from "./types-DnttyLeu.mjs";
+import { I as I18nApi, J as StylesState, S as TextApi, c as UiNode, i as Finding, j as InputApi, n as ElementChange, o as JsxState, r as ElementMotion } from "./types-CWSMo70I.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 import { Node, Yoga } from "yoga-layout/load";

package/dist/{types-yLdzHyTl.d.mts → types-CWSMo70I.d.mts}

@@ -1,4 +1,4 @@
-import { Cn as MotionCause, En as ProjectionMotion, Hr as Api, Jt as TransformValue, Mn as Api$1, Mt as ViewportSize, Qr as Require, Sn as Motion, Sr as Json, T as Api$3, Tn as NumericFields, Zt as Api$2, fr as Answer, in as AnyComponentValue, jn as ViewHandle, ln as Entity, nn as AnyComponent, or as Descriptor, pr as Api$5, rn as AnyComponentType, s as Events$1, sn as ComponentType, t as Api$4, ur as Hint, vn as TagType, wn as MotionHandle, yn as ChangeHook } from "./types-DlC3Ytbj.mjs";
+import { Cn as MotionCause, En as ProjectionMotion, Hr as Api, Jt as TransformValue, Mn as Api$1, Mt as ViewportSize, Qr as Require, Sn as Motion, Sr as Json, T as Api$3, Tn as NumericFields, Zt as Api$2, fr as Answer, in as AnyComponentValue, jn as ViewHandle, ln as Entity, nn as AnyComponent, or as Descriptor, pr as Api$5, rn as AnyComponentType, s as Events$1, sn as ComponentType, t as Api$4, ur as Hint, vn as TagType, wn as MotionHandle, yn as ChangeHook } from "./types-DnttyLeu.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 
@@ -1694,12 +1694,23 @@ type State = {
   cache: Map<string, TextLayout>; /** What every live label container was last filled from, by container. */
   drawn: WeakMap<object, DrawnLabel>; /** Entities to re-resolve in the next layout phase. */
   dirty: Set<Entity>;
+  /**
+   * The labels whose `Text` came while the world was live since the layout system last ran. The
+   * flush of phase `layout` brings the ones `ui` adds in its solve, and they are resolved right
+   * after it.
+   */
+  added: Entity[];
+  /**
+   * The labels the step after the last layout flush resolved. The next system run writes their
+   * `Text` once more, so `ui` measures the string they show.
+   */
+  rewrite: Entity[];
   /**
    * Counts the dev hot swaps that replaced a font or an inline icon of a live label. A label
    * container drawn under an older count is built again on its next update.
    */
   generation: number; /** Warning keys already written, so a style, a tag, a glyph or a font warns once. */
-  warned: Set<string>; /** The system, the two world hooks and the display adapter. */
+  warned: Set<string>; /** The system, the step after the layout flush, the two world hooks and the display adapter. */
   removers: Array<() => void>;
 };
 /**
@@ -2504,12 +2515,6 @@ type Root = {
     h: number;
   } | undefined;
   pending?: boolean;
-  /**
-   * The release of the hold on the feature the root shows (`world.ecs.hold`): the feature of a
-   * popup's component, or of a JSX projection. Called when the sweep drops the root. Optional
-   * like `pending`: `mountRoot` always writes it.
-   */
-  held?: (() => void) | undefined;
 };
 /**
  * Where the focus ring was last drawn: the layer and order of its root, the rect grown by the
@@ -2680,9 +2685,7 @@ 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>; /** Component name to the feature whose `ui` key lists it: the feature a popup root holds. */
-  featureOfComponent: Map<string, string>; /** Projection name to the feature that registered it: the feature a JSX root holds. */
-  featureOfProjection: Map<string, string>;
+  overlays: Set<Entity>;
 };
 /**
  * One node of the snapshot `tree()` answers with. `rect` is natural: under a `fit` ancestor it

package/dist/{types-B0bmoyRT.d.mts → types-DFoxDq-g.d.mts}

@@ -1,5 +1,5 @@
-import { Sr as Json, jr as Snapshot } from "./types-DlC3Ytbj.mjs";
-import { t as HeadlessApp } from "./headless-D0U5AXiK.mjs";
+import { Sr as Json, jr as Snapshot } from "./types-DnttyLeu.mjs";
+import { t as HeadlessApp } from "./headless-DDkRwLnJ.mjs";
 import { Log } from "@moku-labs/common/browser";
 
 //#region src/plugins/flow/doors/types.d.ts

package/dist/{types-DlC3Ytbj.d.mts → types-DnttyLeu.d.mts}

@@ -3365,31 +3365,12 @@ type FeatureTextStyles = {
   readonly kind: "textStyles";
   readonly map: Record<string, object>;
 };
-/**
- * When the systems of a feature run. `"always"` (the default): every frame, as before. `"active"`: only while the
- * feature is active — a node of it is on the flow stack, a scene it declares is mounted, a view of a projection it
- * registered exists, or `ui` holds a popup or a JSX root of it — leaving included, until the last view is gone.
- * Skipping changes nothing the flow sees: systems never write the model. The systems the engine's plugins
- * register always run.
- *
- * @example
- * ```ts
- * // features/board/index.ts: the board's four systems stop on the ward and on the splash.
- * export const boardFeature = defineFeature("board", {
- *   flows: [mergeBoard],
- *   systems: [looks, fade, leaving, veil],
- *   systemsRun: "active"
- * });
- * ```
- */
-type SystemsRun = "always" | "active";
 /**
  * What a feature brings to the game. The logic keys are typed here; the keys of later milestones
  * pass through the index signature until their plugin types them. `flow` stores them untouched,
  * and `logicOnly` drops them. The V2 screen plugins read five of them through the index signature:
  * `projections`, `systems` and `components` (`world`), `scenes` (`scenes`, `assets`, and the
- * scene-id check of `flow`) and `assets` (`assets`). `world` also reads the typed `systemsRun`.
- * The V3 interface keys are typed below.
+ * scene-id check of `flow`) and `assets` (`assets`). The V3 interface keys are typed below.
  *
  * @example
  * ```ts
@@ -3419,8 +3400,13 @@ type FeatureDescription = {
   strings?: Record<string, CompiledMessagesLike | (() => Promise<unknown>)>; /** Text styles the feature owns, read by `text`. */
   textStyles?: FeatureTextStyles; /** Particle emitters the feature owns, read by `effects`. */
   emitters?: readonly FeatureEmitter[]; /** Filters the feature puts on its interface components, read by `effects`. */
-  filters?: readonly FeatureFilter[]; /** When the feature's systems run, read by `world`. Absent is `"always"`. */
-  systemsRun?: SystemsRun;
+  filters?: readonly FeatureFilter[];
+  /**
+   * The key of 0.15.3, removed: typed `never`, so a game that still writes it is told. A system
+   * now runs while its query has an entity, and `scenes` on `system()` limits it to some scenes:
+   * delete the key (world README, "When a system runs").
+   */
+  systemsRun?: never;
   [later: string]: unknown;
 };
 /**
@@ -3620,7 +3606,7 @@ declare function to<const TargetName extends string, Payload, Output>(target: Ta
  */
 declare function slot(name: string): SlotNode;
 declare namespace types_d_exports$4 {
-  export { Allow, Answer, AnyFlow, AnyNode, AnyNodeContext, Api$3 as Api, Bookmark, BundlesOf, CheckedEdges, Config$4 as Config, Contribution, DefineNode, Deps$4 as Deps, Descriptor, Edges, Effect, EffectHandler, EffectOptions, EmitterIdOf, EnterCallback, Events$4 as Events, Exit, FeatureDescription, FeatureEmitter, FeatureFilter, FeaturePlugin, FeatureTree, FeaturesApi, FlowCtx, FlowDefinition, FlowEntry, FlowGraph, FlowKit, FlowSpec, FlowState, FxApi, FxHandler, GameState, GameTypes, GateApi, GraphError, GraphNode, GuideOptions, Hint, HudKeysOf, InboxApi, JournalEntry, KernelSlice$4 as KernelSlice, LifecycleChanged, Mapped, NodeContext, NodeDefinition, NodeFx, NodeInfo, NodeSpec, NodeTable, OutcomeTags, Position, RecoverContext, RegisteredFeature, Result, RouteStep, RunnerApi, SceneIdOf, SlotNode, Stage, State$4 as State, StringTableLike, SystemsRun, Target, TextStylesOf, TypeTag, WorldEvent };
+  export { Allow, Answer, AnyFlow, AnyNode, AnyNodeContext, Api$3 as Api, Bookmark, BundlesOf, CheckedEdges, Config$4 as Config, Contribution, DefineNode, Deps$4 as Deps, Descriptor, Edges, Effect, EffectHandler, EffectOptions, EmitterIdOf, EnterCallback, Events$4 as Events, Exit, FeatureDescription, FeatureEmitter, FeatureFilter, FeaturePlugin, FeatureTree, FeaturesApi, FlowCtx, FlowDefinition, FlowEntry, FlowGraph, FlowKit, FlowSpec, FlowState, FxApi, FxHandler, GameState, GameTypes, GateApi, GraphError, GraphNode, GuideOptions, Hint, HudKeysOf, InboxApi, JournalEntry, KernelSlice$4 as KernelSlice, LifecycleChanged, Mapped, NodeContext, NodeDefinition, NodeFx, NodeInfo, NodeSpec, NodeTable, OutcomeTags, Position, RecoverContext, RegisteredFeature, Result, RouteStep, RunnerApi, SceneIdOf, SlotNode, Stage, State$4 as State, StringTableLike, Target, TextStylesOf, TypeTag, WorldEvent };
 }
 /**
  * flow plugin events.
@@ -4313,8 +4299,8 @@ type View$1 = {
   cause: MotionCause;
 };
 /**
- * One mounted projection: its owner, the live views by key, the despawn queue and the items of
- * the last reconcile.
+ * One mounted projection: its owner, the live views by key, the despawn queue, the items of the
+ * last reconcile, its place in the list of its scene and the layer list of that scene.
  *
  * @example
  * ```ts
@@ -4323,7 +4309,8 @@ type View$1 = {
  *   live: new Map(),
  *   queue: [],
  *   items: new Map(),
- *   order: -1
+ *   order: -1,
+ *   layers: Object.freeze([{ name: "items", sort: "y" }])
  * };
  * ```
  */
@@ -4337,6 +4324,11 @@ type Mounted = {
    * minus the length of that list (the roots of one scene take −n … −1, in list order).
    */
   order: number;
+  /**
+   * The layer list (`setLayers`) of the scene the projection was mounted into or kept by last, compared by
+   * identity: a `mount` under the same list is a second mount of one scene, a `mount` under a new one keeps it.
+   */
+  layers: ReadonlyArray<LayerSpec>;
 };
 /**
  * One track the projection started on the driver. The world keeps the component name and the
@@ -4510,17 +4502,30 @@ type ProjectionApi = {
   layers(): ReadonlyArray<LayerSpec>;
   /**
    * Marks projections mounted under an owner and reconciles them at once, direct: a scene brings
-   * its own transition. Nothing is mounted when the call throws.
+   * its own transition. A screen root draws at the `Order` of its place in the list, −n … −1. A
+   * projection a scene before mounted (under another layer list, `setLayers`) stays mounted when
+   * the new list declares its `layer` and `lift` alike: its views keep their entities and their
+   * motions, no hook runs, and its screen roots take the `Order` of their place in this list. One
+   * whose layer the new list declares otherwise is unmounted and mounted again. One mounted under
+   * the current layer list already is a second mount of one scene: it warns
+   * `world:already-mounted` and changes nothing. Nothing is mounted when the call throws.
    *
    * @param names - Names of the projections to mount.
    * @param owner - Who owns the entities of these projections.
    * @throws {Error} For an unknown name, or a `layer` or `lift` the scene does not declare.
    * @example
    * ```ts
-   * // `scenes` mounts the projections of the board scene it just switched to.
+   * // `scenes` mounts the board scene it just switched to: its HUD screen is listed last, at -1.
    * const world = ctx.require(worldPlugin);
-   * world.projection.mount(["board.cells", "board.items"], { kind: "plugin", name: "scenes" });
+   * world.projection.mount(["board.items", "hud"], { kind: "plugin", name: "scenes" });
    * world.projection.entityOf("board.items", "i7"); // 1048576, the picture is already there
+   *
+   * // The shop lists the HUD too and declares `ui` alike: the shop's layers, the board's items
+   * // out, the shop's list in.
+   * world.projection.setLayers([{ name: "ui", sort: "order" }]);
+   * world.projection.unmount(["board.items"]);
+   * world.projection.mount(["hud", "shop.shelf"], { kind: "plugin", name: "scenes" });
+   * world.ecs.get(world.projection.entityOf("hud", "hud") ?? 0, Order)?.value; // -2: the same entity, first of two
    * ```
    */
   mount(names: readonly string[], owner: Owner): void;
@@ -5236,15 +5241,18 @@ type SystemContext = {
   readonly snapshot: Snapshot;
   readonly time: Readonly<Time>;
   /**
-   * True on the first run after one or more runs of this system were skipped because its feature was not active
-   * (`systemsRun: "active"`). Nothing was kept for it while it slept: `world.changed()` holds this frame's changes
-   * only, so a system that caches what it drew rebuilds from the components when this is true. Always false for a
-   * system that always runs. Read it during the run.
+   * True on the first run after one or more of this system's runs were skipped: its query had no entity, or none of
+   * its `scenes` was mounted or leaving. Nothing was kept for it while it slept: `world.changed()` holds this frame's
+   * changes only, so a system that caches what it drew, or remembers what it saw last, starts over from the
+   * components when this is true. False on every other run. Read it during the run.
    */
   readonly resumed: boolean;
 };
 /**
- * A system definition, typed over its query tuple.
+ * A system definition, typed over its query tuple. A system with a query runs only while its query
+ * can match: before each run the world looks at the store of every term, and when one of them holds
+ * no entity the run is skipped (no walk, no `mut()` mark, no timing). A system without a query
+ * always runs. `scenes` limits either kind to some scenes.
  *
  * @example
  * ```ts
@@ -5263,10 +5271,42 @@ type SystemDefinition<Terms extends readonly QueryTerm[]> = {
   readonly phase: WorldPhase;
   readonly query: Terms;
   /**
-   * Runs the system once a frame in its phase. `entities` walks the declared `query` once; every
-   * row it hands out is the same array, rewritten for the next row, so a row is valid until the
-   * next row. A system that keeps a row copies what it keeps: `const [entity, transform] = row`.
-   * `ecs.query()` called inside `run` hands out a new array per row.
+   * The scenes the system runs on: it runs only while one of them is mounted or leaving. A scene
+   * leaves from the switch that replaces it until nothing carries `Exiting` any more, so the exits
+   * of its JSX elements play to the end; any exit counts, also one of the next scene, so a leave may
+   * last longer than the scene's own exits. The next scene's entities already stand during a leave:
+   * a query that matches them too hands them to the system, so it writes only its own scene's
+   * entities. Left out, the system runs on every scene. Read once, when the system registers. A dev
+   * build throws at start for a name no feature declares as a scene. For a system without a query,
+   * or one whose entities stand on every screen.
+   *
+   * @example
+   * ```ts
+   * // features/board/world/systems/idle.ts: no query, so `scenes` alone keeps it to the board.
+   * const BoardIdle = resource("BoardIdle", { ms: 0 });
+   * export const idle = system({
+   *   name: "board.idle",
+   *   phase: "animate",
+   *   query: [],
+   *   scenes: ["board"],
+   *   run: (_rows, { res, time }) => {
+   *     res(BoardIdle).ms += time.delta;
+   *   }
+   * });
+   * // On the ward it is not run and BoardIdle.ms stands still. On the board it grows by each
+   * // frame's delta. After the switch to the ward it runs while the board's elements play their
+   * // exit, then not any more.
+   * ```
+   */
+  readonly scenes?: readonly string[];
+  /**
+   * Runs the system once a frame in its phase, unless it is skipped: a term of its `query` has no
+   * entity, or none of its `scenes` is mounted or leaving. `entities` walks the declared `query`
+   * once; every row it hands out is the same array, rewritten for the next row, so a row is valid
+   * until the next row. A system that keeps a row copies what it keeps:
+   * `const [entity, transform] = row`. `ecs.query()` called inside `run` hands out a new array per
+   * row. Work that must happen when the query has no entity (end a press, reset a resource) belongs
+   * in a system without a query.
    */
   run(entities: Iterable<QueryTuple<Terms>>, ctx: SystemContext): void;
 };
@@ -5321,23 +5361,28 @@ type SystemFor<Player, Session> = <const Terms extends readonly QueryTerm[]>(def
 type AnySystem = {
   readonly name: string;
   readonly phase: WorldPhase;
-  readonly query: readonly QueryTerm[]; /** As `SystemDefinition.run`: one row array per walk, valid until the next row. */
+  readonly query: readonly QueryTerm[]; /** As `SystemDefinition.scenes`: the scenes it runs on, every scene when left out. */
+  readonly scenes?: readonly string[]; /** As `SystemDefinition.run`: one row array per walk, valid until the next row. */
   run(entities: Iterable<readonly unknown[]>, ctx: SystemContext): void;
 };
+/** One component store, keyed by entity: a component's value, `true` for a tag. */
+type ComponentStore = Map<Entity, object | true>;
 /**
  * One registered system, the frame it was registered in, its query resolved once, the walk the
- * runner resets for every run and its scope. A system registered during a frame runs from the
- * next frame on. Module state: no game reads it.
+ * runner resets for every run, the stores its check reads and its scenes. A system registered
+ * during a frame runs from the next frame on. Module state: no game reads it.
  */
 type SystemEntry = {
   readonly definition: AnySystem;
   readonly frame: number;
   readonly plan: QueryPlan;
   /**
-   * The index of its feature in `ScopeState` for a system of a feature with `systemsRun: "active"`, -1 for a
-   * system that always runs.
+   * The store of each term, in term order, kept once it exists: a store lives as long as the
+   * systems of its world, so the check before a run reads sizes and looks nothing up.
+   * `undefined` for a term no entity carried yet.
    */
-  readonly scope: number; /** The system's last chance to run was skipped because its feature was not active. */
+  readonly stores: Array<ComponentStore | undefined>; /** The scenes it runs on, read once at registration; `undefined` for every scene. */
+  readonly scenes: readonly string[] | undefined; /** Its last chance to run was skipped: the next run is told so with `resumed`. */
   skipped: boolean;
   /**
    * The walk of the declared query, made at registration; `undefined` for an empty query, which
@@ -5346,27 +5391,14 @@ type SystemEntry = {
   walk?: SystemWalk | undefined;
 };
 /**
- * Which features are active, kept so a phase reads one byte per scoped system. Indexed by the feature's position in
- * `flow.features.all()`. Filled in `onStart`, sized once; nothing in it grows per frame.
+ * Which scene is mounted and which are still leaving, as `scenes` tells the world with
+ * `ecs.setScene`: what a system with `scenes` runs on. Changed at a scene switch only; a phase
+ * reads it.
  */
-type ScopeState = {
-  /** Feature names by index, registration order. */names: string[]; /** Feature name to index. */
-  index: Map<string, number>; /** Projection name to the index of the feature that registered it (rule V). */
-  projections: Map<string, number>; /** Flow id to node name to the owner's index (rule N); built from one `describe()` when first needed. */
-  owners: Map<string, Map<string, number>> | undefined; /** `describe()` threw: every feature counts as on the stack while the stack is not empty (fail-safe). */
-  ownersFailed: boolean; /** The `flow.state()` object the stack flags were read from. */
-  flow: FlowState | undefined; /** 1 while a frame of the stack addresses a node the feature owns. */
-  onStack: Uint8Array; /** The holds `scenes` and `ui` keep on the feature. */
-  holds: Int32Array; /** The live and leaving views of the projections the feature registered. */
-  views: Int32Array; /** 1 while the feature is active, as of the last evaluation. */
-  active: Uint8Array; /** A hold or a view count moved since the last evaluation. */
-  dirty: boolean; /** At least one registered system runs only while its feature is active. */
-  scoped: boolean;
-  /**
-   * Moves on at every start and every stop: a hold's release remembers the generation it was
-   * taken in, and a release from an older one changes nothing (spec 28 W7.1).
-   */
-  generation: number;
+type SceneState$1 = {
+  /** The mounted scene, `undefined` before the first switch. */mounted: string | undefined; /** The scenes a switch replaced while something still carries `Exiting`, oldest first; no repeats. */
+  leaving: string[]; /** The scene ids the features declare, read at start for the dev check of `scenes`; `undefined` before. */
+  declared: ReadonlySet<string> | undefined;
 };
 /**
  * A structural change queued while a phase runs. Applied in call order when the phase ends.
@@ -5420,7 +5452,7 @@ type PhaseContext = {
   /** The ecs API the systems of this world receive. */readonly world: EcsApi; /** The resource reader, one function per world. */
   readonly res: <Value extends object>(resource: ResourceType<Value>) => Value; /** The frozen model snapshot of the running frame. */
   snapshot: Snapshot; /** The running frame's `Time`. */
-  time: Readonly<Time>; /** Written before every run: the system's runs before this one were skipped for its scope. */
+  time: Readonly<Time>; /** Written before every run: the system's last chance to run before this one was skipped. */
   resumed: boolean;
 };
 /**
@@ -5623,8 +5655,8 @@ type EcsState = {
   walkReported: boolean; /** The plans of `ecs.query()` by the type of their first term, made once per tuple of types. */
   queryPlans: Map<AnyComponentType, KnownPlan[]>; /** The entity lists of ended `ecs.query()` walks, taken by the next walks: no key copy per call. */
   walkLists: Entity[][]; /** How many entities were despawned since the world began: the sweep looks for dead elements when it moved. */
-  despawns: number; /** Which features are active, for the systems of the features with `systemsRun: "active"`. */
-  scope: ScopeState;
+  despawns: number; /** The mounted scene and the leaving ones, for the systems with `scenes`. */
+  scene: SceneState$1;
 };
 /**
  * ecs module API, `app.world.ecs`: the screen as data. Plain-object components in one store per
@@ -5641,55 +5673,23 @@ type EcsState = {
 type EcsApi = {
   /**
    * Registers a system at the end of its phase list. A system registered during a frame runs
-   * from the next frame on.
+   * from the next frame on. In every frame the system is skipped while a term of its query has no
+   * entity, or while none of its `scenes` is mounted or leaving.
    *
    * @param definition - The system, built with `system()`.
    * @returns The remover; calling it twice is a no-op.
-   * @throws {Error} When a system of that name is already registered.
+   * @throws {Error} When a system of that name is already registered, and in a dev build after
+   *   start for a name in `scenes` that no feature declares as a scene.
    * @example
    * ```ts
    * // `text` registers its layout system when the plugin starts.
    * const world = ctx.require(worldPlugin);
-   * const off = world.ecs.system(measureLabels); // runs from the next frame
+   * const off = world.ecs.system(measureLabels); // runs from the next frame on which a label exists
    *
    * off(); // the plugin stops
    * ```
    */
   system(definition: AnySystem): () => void;
-  /**
-   * Keeps a feature active while something of it is shown that the world cannot see: `scenes` holds the feature that
-   * declares the mounted scene, `ui` the feature of each popup or JSX root it holds. Holds are counted; the returned
-   * release is idempotent. A name that is not a registered feature holds nothing (a dev warning
-   * `world:hold-unknown-feature`). Takes effect at the next phase that runs systems.
-   *
-   * @param feature - The feature to keep active.
-   * @returns The release.
-   * @example
-   * ```ts
-   * // scenes, as it mounts the scene "ward" that the feature "screens" declares:
-   * const release = ctx.require(worldPlugin).ecs.hold("screens");
-   * app.world.ecs.isActive("screens"); // true
-   * release(); // the next scene replaced the ward
-   * app.world.ecs.isActive("screens"); // false: no node, view or hold of "screens" is left
-   * ```
-   */
-  hold(feature: string): () => void;
-  /**
-   * Whether a feature is active now: a node of it is on the flow stack, a scene it declares is mounted, a view of a
-   * projection it registered exists (leaving included), or `ui` holds a popup or JSX root of it. Answers for any
-   * feature, whatever its `systemsRun`; the systems of a feature with `systemsRun: "active"` run exactly while this
-   * is true. False for a name that is not a feature.
-   *
-   * @param feature - The feature name.
-   * @returns True while it is active.
-   * @example
-   * ```ts
-   * // A test of the board: the graph rests at the board's awaitIntent and the shop sheet is closed.
-   * app.world.ecs.isActive("board"); // true: a node of the board is on the stack, its views are drawn
-   * app.world.ecs.isActive("shop"); // false: no view of the sheet, no node of the shop on the stack
-   * ```
-   */
-  isActive(feature: string): boolean;
   /**
    * Creates an entity. The id is reserved and returned at once, also inside a phase, where the
    * components are attached when the phase ends.
@@ -5990,6 +5990,24 @@ type EcsApi = {
    * ```
    */
   setMode(mode: WorldMode): void;
+  /**
+   * Tells the world which scene is mounted now, for the systems that list `scenes`. The scene
+   * mounted before it, and any scene still leaving, keep their systems running until nothing
+   * carries `Exiting` any more: the elements of their JSX views played their exit (the views themselves
+   * go at the switch). Each system reads it
+   * before its next run. The same scene again changes nothing. `scenes` calls it in the block that
+   * mounts a scene; a game never needs to.
+   *
+   * @param scene - The id of the scene now mounted.
+   * @example
+   * ```ts
+   * // scenes, in the block that replaces the ward with the board:
+   * ctx.require(worldPlugin).ecs.setScene("board");
+   * // In the next frame a system with scenes: ["board"] runs. One with scenes: ["ward"] runs
+   * // until the ward's elements played their exit, then sleeps.
+   * ```
+   */
+  setScene(scene: string): void;
   /**
    * The component type behind a name. A type registers itself on first use, so a name nobody
    * wrote, read or queried yet is unknown.
@@ -6130,22 +6148,6 @@ type EcsInternal = {
    * Drops every entity, component, resource, system and hook.
    */
   clear(): void;
-  /**
-   * Counts a new view of a projection for the feature that registered it (rule V of `systemsRun`).
-   *
-   * @param projection - The projection name.
-   */
-  viewCame(projection: string): void;
-  /**
-   * Takes back the count of a despawned view; never below 0.
-   *
-   * @param projection - The projection name.
-   */
-  viewLeft(projection: string): void;
-  /**
-   * Drops every view count: the projections were cleared.
-   */
-  viewsCleared(): void;
 };
 //#endregion
 //#region src/plugins/world/ecs/systems.d.ts
@@ -9321,9 +9323,9 @@ type HostState = {
    */
   uninstallPasses: (() => void) | undefined;
   /**
-   * Swaps Pixi's own bitmap text pipe back in. Set once per host state when the renderer's pipe,
-   * whose SDF shader applies the alpha once, went into Pixi's registry, so a restore reuses it;
-   * `undefined` while inert and when the module lacked the pieces.
+   * Swaps Pixi's own bitmap text and batch pipes back in and drops the SDF batcher. Set once per host state when the
+   * renderer's batched distance-field text went into Pixi's registry, so a restore reuses it; `undefined` while inert
+   * and when the module lacked the pieces.
    */
   uninstallSdfText: (() => void) | undefined;
   /**
@@ -10536,9 +10538,9 @@ declare namespace types_d_exports$2 {
  * the render textures and matrices the kept pictures are drawn with (an `AlphaFilter` runs their pre-pass), and the
  * extension registry with the seven classes the counting of a dev or debug build swaps
  * (the three WebGPU draw classes, the filter system, both texture systems and the batcher pipe whose `buildStart`
- * begins every instruction rebuild; production swaps the encoder alone, to count the passes) and the bitmap text
- * pipe `host` swaps for one whose SDF shader applies the alpha once (with the WGSL and GLSL shader
- * pieces it compiles that shader from). The module object
+ * begins every instruction rebuild; production swaps the encoder alone, to count the passes), and the pieces of
+ * batched distance-field text `host` installs: Pixi's `Batcher` with its geometry and buffers, the bitmap text pipe
+ * and the batcher pipe it subclasses, and the WGSL and GLSL shader pieces of the batch's SDF shader. The module object
  * never arrives through a static import: `config.loadPixi()` returns it, so a game without a screen carries no
  * Pixi in its bundle.
  *
@@ -10550,10 +10552,11 @@ declare namespace types_d_exports$2 {
  * pixi.FilterSystem.extension.name; // "filter"
  * pixi.BatcherPipe.extension.name; // "batch"
  * pixi.BitmapTextPipe.extension.name; // "bitmapText"
+ * pixi.ExtensionType.Batcher; // "batcher"
  * pixi.defaultFilterVert.startsWith("in vec2 aPosition;"); // true
  * ```
  */
-type PixiModule = Pick<typeof import("pixi.js"), "AlphaFilter" | "Application" | "BatcherPipe" | "BitmapFont" | "BitmapText" | "BitmapTextPipe" | "BlurFilter" | "Bounds" | "Cache" | "ColorMatrixFilter" | "Container" | "DisplacementFilter" | "Filter" | "FilterSystem" | "GlProgram" | "GlTextureSystem" | "GpuBatchAdaptor" | "GpuEncoderSystem" | "GpuGraphicsAdaptor" | "GpuProgram" | "GpuTextureSystem" | "Graphics" | "Matrix" | "NineSliceSprite" | "NoiseFilter" | "Particle" | "ParticleContainer" | "Rectangle" | "RenderGroupPipe" | "RenderTexture" | "Shader" | "Sprite" | "Texture" | "TexturePool" | "UniformGroup" | "bitmapFontTextParser" | "bitmapFontXMLStringParser" | "colorBit" | "colorBitGl" | "compileHighShaderGlProgram" | "compileHighShaderGpuProgram" | "defaultFilterVert" | "extensions" | "generateTextureBatchBit" | "generateTextureBatchBitGl" | "getBatchSamplersUniformGroup" | "localUniformMSDFBit" | "localUniformMSDFBitGl" | "mSDFBit" | "mSDFBitGl" | "roundPixelsBit" | "roundPixelsBitGl">;
+type PixiModule = Pick<typeof import("pixi.js"), "AlphaFilter" | "Application" | "Batcher" | "BatcherPipe" | "BitmapFont" | "BitmapText" | "BitmapTextPipe" | "BlurFilter" | "Bounds" | "Buffer" | "BufferUsage" | "Cache" | "ColorMatrixFilter" | "Container" | "DefaultBatcher" | "DisplacementFilter" | "ExtensionType" | "Filter" | "FilterSystem" | "Geometry" | "GlProgram" | "GlTextureSystem" | "GpuBatchAdaptor" | "GpuEncoderSystem" | "GpuGraphicsAdaptor" | "GpuProgram" | "GpuTextureSystem" | "Graphics" | "Matrix" | "NineSliceSprite" | "NoiseFilter" | "Particle" | "ParticleContainer" | "Rectangle" | "RenderGroupPipe" | "RenderTexture" | "Shader" | "Sprite" | "Texture" | "TexturePool" | "UniformGroup" | "bitmapFontTextParser" | "bitmapFontXMLStringParser" | "colorBit" | "colorBitGl" | "compileHighShaderGlProgram" | "compileHighShaderGpuProgram" | "defaultFilterVert" | "extensions" | "generateTextureBatchBit" | "generateTextureBatchBitGl" | "getBatchSamplersUniformGroup" | "mSDFBit" | "mSDFBitGl" | "roundPixelsBit" | "roundPixelsBitGl">;
 /**
  * One Pixi application: renderer, canvas and stage.
  */
@@ -11184,13 +11187,7 @@ type State$1 = {
    */
   named: readonly string[];
   owner: SceneOwner; /** The remover of the `onEnter` callback: set in `onStart`, run in `onStop`. */
-  teardown: (() => void) | undefined; /** Scene id to the feature that declares it, filled in `onStart`. */
-  owners: Map<string, string>;
-  /**
-   * The release of the hold on the mounted scene's feature (`world.ecs.hold`), so the systems of a
-   * feature with `systemsRun: "active"` run while its scene is mounted.
-   */
-  held: (() => void) | undefined;
+  teardown: (() => void) | undefined;
 };
 /**
  * scenes plugin events.

package/dist/{visual-G6F0Mi9H.d.mts → visual-DalSHy9z.d.mts}

@@ -1,9 +1,9 @@
-import { Ir as Api$3, T as Api, Zt as Api$1, yr as Api$2 } from "./types-DlC3Ytbj.mjs";
-import { P as AnimApi, r as UiApi } from "./types-CsMLBPf-.mjs";
-import { j as InputApi } from "./types-yLdzHyTl.mjs";
-import { r as Repro } from "./headless-D0U5AXiK.mjs";
-import { a as InputOf, r as ControlApp } from "./types-B0bmoyRT.mjs";
-import { t as commands } from "./commands-31d2BEwc.mjs";
+import { Ir as Api$3, T as Api, Zt as Api$1, yr as Api$2 } from "./types-DnttyLeu.mjs";
+import { P as AnimApi, r as UiApi } from "./types-C2g2KYCN.mjs";
+import { j as InputApi } from "./types-CWSMo70I.mjs";
+import { r as Repro } from "./headless-DDkRwLnJ.mjs";
+import { a as InputOf, r as ControlApp } from "./types-DFoxDq-g.mjs";
+import { t as commands } from "./commands-e_I5i8dK.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-G6F0Mi9H.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-DalSHy9z.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/llms.txt

@@ -101,8 +101,7 @@ function defineFeature(name: string, description: FeatureDescription): FeaturePl
 //   contribute?: Record<string, { flow: AnyFlow; order: number; when?: (snapshot: Snapshot) => boolean }>;
 //   features?: readonly FeaturePlugin[];                       // sub-features, composed right after this one
 //   projections?, systems?, components?, scenes?, assets?;   // V2 keys, read by world, scenes and assets
-//   systemsRun?: "always" | "active";                         // read by world. "always" (default) or "active":
-//                                                             // the feature's systems run only while a node, scene, view or ui root of it is there
+//   systemsRun?: never;                                        // the 0.15.3 key, removed: a system runs while its query has an entity
 //   animations?: readonly AnimationDefinition[];              // V3, read by anim
 //   ui?: readonly ComponentDefinition[];                      // V3, read by ui (defineComponent results)
 //   strings?: Record<locale, CompiledMessages | (() => Promise<unknown>)>;   // V3, read by i18n
@@ -529,7 +528,7 @@ The graph. Modules `runner`, `gate`, `inbox`, `fx`, `features`. Runner methods s
 - `app.assets`: `load(bundle)`, `unload(bundle)`, `isLoaded(bundle)`, `has(bundle)` (the manifest carries it, loaded or not), `texture(key)`, `font(key)`, `audio(key)`, `usage()`. Per bundle in a feature's `assets.ts`: `defineBundles({ ep01: { tier: "feature", release: "leave", mipmaps: ["items/**"] } })`. `release: "leave"` also unloads the bundle, with reason `"leave"`, at the next rest once nothing holds it: not pinned by the node entered, not named by the mounted scene, no node of its feature on the stack; a bundle the outgoing scene named leaves one rest later. The default `"budget"` leaves only under the texture budget. `mipmaps` (`true` or globs relative to `assets/`) uploads the textures with their full chain; such a texture stays loose in a pack. A sub-feature with resources gets its own bundles, named like its folder, with `dir` and `parent` in the manifest; a code-only one has none. `companions.add({ load(bundle), unload(bundle) })` adds what loads and unloads with every bundle; `i18n` adds the strings of a sub-feature that way, only when `assets` is composed. Events `assets:bundle-loaded`, `assets:bundle-progress`, `assets:bundle-unloaded` (`reason: "budget" | "request" | "leave"`), `assets:replaced` (dev). Config: `manifest`, `textureBudgetMb: 192`, `preloadDepth: 2`, `baseUrl`, `io`.
 - `resource(name, defaults)` clones plain JSON defaults into every world. `resource(name, () => value)` calls the factory once per world on first read, so the value may hold a `Map` or a function: `const Looks = resource("boardLooks", () => ({ shown: new Map<World.Entity, { look: string }>() }))`. A system keeps its own state there; `snapshot()` leaves a value that is not JSON out.
 - `Now` is the engine resource of the frame's moment: `world` writes `clock.now()` into it at start and first thing in every frame, headless too, so every system of a frame reads one moment: `const { now } = res(Now)`; a fake clock makes it exact. A system that shows time writes its component only when its picture changes. `snapshot().resources` holds `Now: { now }`. Reserved resource names: `Now`, `Pointer`, `AnimPlayer`, `UiCounters`; a game resource of one of them throws `[game] world: the resource name "Now" is the engine's (the frame's moment).`
-- Systems that run where their feature is: `defineFeature("board", { systems, systemsRun: "active" })` runs the feature's systems only while it is active: a node of it on the flow stack (outer frames of sub-flows included), a scene it declares mounted (`scenes` holds it), a view of a projection it registered, leaving included, or a popup or JSX root of it that `ui` holds until its exit ended. `"always"` (default) and the systems the engine's plugins or `ecs.system` register run every frame. A skipped system keeps its slot, walks no query, marks nothing and allocates nothing; `ctx.resumed` is true on its first run after a skip (a cache it drew is rebuilt then). `app.world.ecs.isActive(feature)` answers for any feature; `ecs.hold(feature)` returns a release (`scenes` and `ui` call it). The active set is read at the start of each phase that runs systems. Dev warnings `world:feature-never-active`, `world:hold-unknown-feature`, `world:bad-feature-entry` with `key: "systemsRun"`.
+- When a system runs: before each run the world checks it. A system with a `query` is skipped while a term of its query has no entity (the smallest store among the terms is empty): no walk, no `mut()` mark, no timing. A system without a query always runs. `system({ ..., scenes: ["board"] })` runs only while one of those scenes is mounted or leaving: `scenes` calls `app.world.ecs.setScene(id)` at every switch, and the scene before leaves until nothing carries `Exiting` (the elements of its JSX views played their exit; the next scene's entities already stand then, so a `scenes` system writes only its own scene's entities). A dev build throws at start for a name in `scenes` no feature declares: `[game] System "board.idle" runs on the scene "bord", which no feature declares.` `ctx.resumed` is true on the first run after a skip (a cache or a remembered cue starts over then). The same for every system, the engine's included; 0 B a frame. A run with no rows does not happen any more: work a system did besides its rows (a hover, a drop or a press that ends, a resource reset, something that outlives its entities) goes to a system with `query: []` and `scenes`, reading its rows with `world.query()`. From 0.15.3: delete `systemsRun` from every feature (the type refuses it), rewrite the systems that work outside their rows, add `scenes` only to a system whose entities stand on every screen; `ecs.hold` and `ecs.isActive` are gone (a test asks `app.scenes.current()` or whether the system ran). World README, "When a system runs".
 - Motion hooks are told why they play: `enter(view, item, hint, cause)` and `exit(view, item, hint, cause)` get `World.MotionCause`, `"mount"` (the view comes or goes with its screen: a mount, an unmount, a load, a restore, a paused or fast world) or `"change"` (a commit). A world projection plays them only for `"change"`; `ui` plays them for both. `app.world.projection.causeOf(entity)` answers how a view came or how it is leaving, also in a removal hook of its despawn, until the next frame.
 - `app.world.projection.replace(spec)` swaps the spec of a registered projection; a mounted one runs its new `view` on the next frame. An unknown name throws. The caller is the dev hot swap.
 - `input`: one followed pointer. A finger that has not started a gesture (pressed, inside the tap slop, no long press, no trace) gives way to the next finger that goes down, wherever it rests, and its press is cancelled; a finger that started a gesture keeps it. `Pointer.id` is the followed `pointerId` (`-1` at rest): a system that measures the finger's travel starts over when it changes.