@moku-labs/game 0.15.2 → 0.15.3

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-BHgJ1F6f.mjs";
-import { t as createApp } from "./index-w2uyRKkj.mjs";
-import { b as saveOf, v as WithGameState, y as memory } from "./types-DEYQF_tT.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-D6BrEwCf.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-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 { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/plugins/clock/fake.d.ts

package/dist/testing.mjs

@@ -1,4 +1,4 @@
-import { in as exit, p as flattenFeatures, rn as refuseStart, sn as type, t as createApp } from "./src-Ca8W8Dvv.mjs";
+import { an as exit, cn as type, in as refuseStart, m as flattenFeatures, t as createApp } from "./src-xChMXzwH.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-jiWJhLPE.d.mts → types-B0bmoyRT.d.mts}

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

package/dist/{types-DEYQF_tT.d.mts → types-BApuIqwq.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-BHgJ1F6f.mjs";
-import { o as AudioContextLike, s as Config$4 } from "./types-fpFKYm6E.mjs";
-import { H as TextKey, I as I18nApi, V as StringTable } from "./types-Bm7DVtA_.mjs";
-import { Ct as audioPlugin, bt as effectsPlugin, dt as platformPlugin, i as screen, pt as PlatformProvider, t as createApp } from "./index-w2uyRKkj.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-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 { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/plugins/model/store/providers/memory.d.ts

package/dist/{types-fpFKYm6E.d.mts → types-CsMLBPf-.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-BHgJ1F6f.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-Bm7DVtA_.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-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 { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 import { Node, Yoga } from "yoga-layout/load";
@@ -167,11 +167,19 @@ type Track = {
    */
   readonly reveals: "alpha" | "place" | "both" | undefined;
   /**
-   * The patch the track writes, one per track with every field of `to` in it: a frame fills it in
-   * place instead of building one. A field the frame leaves alone carries its stored value back.
-   * Rebuilt when the track loses a field.
+   * The patch the track writes when a frame moves every field, one per track with every field of
+   * `to` in it: a frame fills it in place instead of building one. Rebuilt when the track loses a
+   * field.
    */
   patch: Record<string, unknown>;
+  /**
+   * The patch of a frame that moves only some fields (another writer holds one, or one stands
+   * still): exactly the fields `partialMoved` flags, filled in place by the next frame that moves
+   * the same ones and built again when they change, so a field the track lost, which never moves
+   * again, is never in it. `undefined` until the first such frame.
+   */
+  partial: Record<string, unknown> | undefined; /** The `moved` flags `partial` was built for, by slot. */
+  readonly partialMoved: Uint8Array;
 };
 /**
  * A motion handle that can also be advanced by hand: what the timeline cursor needs, so a track

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

@@ -3365,12 +3365,31 @@ 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`). The V3 interface keys are typed below.
+ * scene-id check of `flow`) and `assets` (`assets`). `world` also reads the typed `systemsRun`.
+ * The V3 interface keys are typed below.
  *
  * @example
  * ```ts
@@ -3400,7 +3419,8 @@ 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[];
+  filters?: readonly FeatureFilter[]; /** When the feature's systems run, read by `world`. Absent is `"always"`. */
+  systemsRun?: SystemsRun;
   [later: string]: unknown;
 };
 /**
@@ -3600,7 +3620,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, 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, SystemsRun, Target, TextStylesOf, TypeTag, WorldEvent };
 }
 /**
  * flow plugin events.
@@ -5206,6 +5226,7 @@ type QueryTuple<Terms extends readonly QueryTerm[]> = [Entity, ...QueryValues<Te
  * const run = (entities: Iterable<[Entity]>, ctx: SystemContext): void => {
  *   ctx.res(Pointer).x = 0;
  *   ctx.time.delta; // 16
+ *   ctx.resumed; // false: the system ran in the frame before
  * };
  * ```
  */
@@ -5214,6 +5235,13 @@ type SystemContext = {
   res<Value extends object>(resource: ResourceType<Value>): Value;
   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.
+   */
+  readonly resumed: boolean;
 };
 /**
  * A system definition, typed over its query tuple.
@@ -5297,20 +5325,49 @@ type AnySystem = {
   run(entities: Iterable<readonly unknown[]>, ctx: SystemContext): void;
 };
 /**
- * One registered system, the frame it was registered in, its query resolved once and the walk the
- * runner resets for every run. A system registered during a frame runs from the next frame on.
- * Spec 28 (deferred) extends it with the system's scope.
+ * 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.
  */
 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.
+   */
+  readonly scope: number; /** The system's last chance to run was skipped because its feature was not active. */
+  skipped: boolean;
   /**
    * The walk of the declared query, made at registration; `undefined` for an empty query, which
    * the runner never walks. An entry built without one gets it on its first run.
    */
   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.
+ */
+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;
+};
 /**
  * A structural change queued while a phase runs. Applied in call order when the phase ends.
  *
@@ -5363,7 +5420,8 @@ 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>;
+  time: Readonly<Time>; /** Written before every run: the system's runs before this one were skipped for its scope. */
+  resumed: boolean;
 };
 /**
  * The JSON kind of one component field, read from its default value: what the editor's component
@@ -5565,7 +5623,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;
+  despawns: number; /** Which features are active, for the systems of the features with `systemsRun: "active"`. */
+  scope: ScopeState;
 };
 /**
  * ecs module API, `app.world.ecs`: the screen as data. Plain-object components in one store per
@@ -5597,6 +5656,40 @@ type EcsApi = {
    * ```
    */
   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.
@@ -6037,6 +6130,22 @@ 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
@@ -6800,6 +6909,12 @@ type KeptState = {
   verifySkipped: number; /** True while `bypass(true)` draws everything live for an extract. */
   bypassed: boolean; /** Render passes the last flush cost: the estimate `sync.renderPasses()` adds (P9.2). */
   flushPasses: number;
+  /**
+   * The frame `collect` read had no mark and no whole-frame reason: nothing a kept picture reads changed, so a kept
+   * record that owes nothing is drawn from its picture as it stands, without its step (E5). Set by `collect`, spent by
+   * the next flush.
+   */
+  calm: boolean;
 };
 //#endregion
 //#region src/plugins/renderer/viewport/types.d.ts
@@ -7900,6 +8015,12 @@ type SyncInternal = {
    */
   layerOf(entity: Entity): string | undefined; /** The overlays of this frame: modes, ranges, reasons, dims, HUD parts, and the pictures to take (spec 22). */
   stepOverlays(): void;
+  /**
+   * Hands Pixi again the filters of every view whose filters were switched on or off since they were written: Pixi
+   * holds only the enabled ones (E3). Run by the draw callback before anything reads the tree, so a switch is drawn in
+   * the frame it was made. Allocates nothing when no filter was switched.
+   */
+  stepFilters(): void;
   /**
    * The `Graphics` paths the engine drew since the last call (shapes, clip masks, nine-slice outlines), and zeroes the
    * count: the monitor's `stats().redraws` (spec 26 R2.3).
@@ -8229,14 +8350,16 @@ type SyncState = {
   overlay: OverlayState; /** `Graphics` paths drawn since the monitor last took them: shapes, clip masks, outlines (spec 26 R2.3). */
   redraws: number;
   /**
-   * Where the walk of `shown` stopped for the entities whose loops asked since the last sync pass (spec 26 R1.7.3):
-   * an entity with several endless loops is walked once a frame. Cleared by every pass, which may change the tree.
+   * Where the walk of `shown` stopped for the entities whose loops asked (spec 26 R1.7.3), at the `passesVersion` it
+   * was taken: an answer stands while the version does, so an entity with several endless loops is walked once, and a
+   * still board not at all (E4). One record per entity, made at its first ask, dropped with its view.
    */
-  held: Map<Entity, Unseen>;
+  held: Map<Entity, HeldUnseen>;
   /**
-   * Moves on with every change that may change the render passes of a frame: a filter set or forgotten, a node's
-   * `renderable` flipped, a view hung, wrapped or dropped (a pass that did work), a kept picture taken or let go, a
-   * write a plugin announced with `invalidate` (a filter switched on or off).
+   * Moves on with every change that may change the render passes of a frame or where a walk of `shown` stops: a filter
+   * set, forgotten or switched, a node's `renderable` flipped (every hidden reason, the alpha's too), a view hung,
+   * moved, wrapped or dropped (a pass that did work), a kept picture taken or let go, a HUD factor, a new viewport, a
+   * write a plugin announced with `invalidate`.
    */
   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. */
@@ -8256,6 +8379,11 @@ type OverdrawState = {
   matrix: PixiFilter | undefined;
   listeners: Array<(on: boolean) => void>;
 };
+/** Where the walk of `shown` stopped for one entity, and the `passesVersion` it was taken at. */
+type HeldUnseen = {
+  answer: Unseen;
+  at: number;
+};
 /**
  * The filtered views' part of the render passes, counted once and read every frame while nothing it reads changed: the
  * version and the root it was counted at, and every filter of the filter table with its `enabled` then (a plugin may
@@ -11056,7 +11184,13 @@ type State$1 = {
    */
   named: readonly string[];
   owner: SceneOwner; /** The remover of the `onEnter` callback: set in `onStart`, run in `onStop`. */
-  teardown: (() => void) | undefined;
+  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;
 };
 /**
  * scenes plugin events.

package/dist/{types-Bm7DVtA_.d.mts → types-yLdzHyTl.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-BHgJ1F6f.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-DlC3Ytbj.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 
@@ -2504,6 +2504,12 @@ 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
@@ -2674,7 +2680,9 @@ 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>; /** 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>;
 };
 /**
  * One node of the snapshot `tree()` answers with. `rect` is natural: under a `fit` ancestor it

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

@@ -1,9 +1,9 @@
-import { Ir as Api$3, T as Api, Zt as Api$1, yr as Api$2 } from "./types-BHgJ1F6f.mjs";
-import { P as AnimApi, r as UiApi } from "./types-fpFKYm6E.mjs";
-import { j as InputApi } from "./types-Bm7DVtA_.mjs";
-import { r as Repro } from "./headless-D6BrEwCf.mjs";
-import { a as InputOf, r as ControlApp } from "./types-jiWJhLPE.mjs";
-import { t as commands } from "./commands-C_GccOFq.mjs";
+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";
 
 //#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-BvkKJOSz.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-G6F0Mi9H.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,6 +101,8 @@ 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
 //   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
@@ -527,6 +529,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"`.
 - 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.

package/package.json

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