@moku-labs/game 0.15.1 → 0.15.3

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

@@ -1,4 +1,4 @@
-import { An as Api$1, At as ViewportSize, Br as Api, Cn as NumericFields, Kt as TransformValue, Sn as MotionHandle, T as Api$3, Xr as Require, Yt as Api$2, _n as ChangeHook, an as ComponentType, bn as Motion, br as Json, cr as Hint, dr as Api$5, en as AnyComponent, gn as TagType, ir as Descriptor, kn as ViewHandle, nn as AnyComponentValue, s as Events$1, sn as Entity, t as Api$4, tn as AnyComponentType, ur as Answer, wn as ProjectionMotion, xn as MotionCause } from "./types-E2ykwIUO.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";
 
@@ -1630,11 +1630,6 @@ type DrawnLabel = {
 /**
  * A dev warning that is written once per key. Pure modules take it as an argument, so nothing
  * below the plugin context reaches the log itself.
- *
- * @example
- * ```ts
- * const warn: Warn = (key, message) => seen.has(key) || log.warn(message);
- * ```
  */
 type Warn = (key: string, message: string, data?: Record<string, unknown>) => void;
 /**
@@ -1651,18 +1646,21 @@ type LayoutOptions = {
 /**
  * What was resolved for one entity last, so the frame step knows whether anything moved. `unit`
  * is what the shown string of a bound label was built from: the rounded value for `"int"`, whole
- * seconds for a time format.
+ * seconds for a time format. `bindRef` is the bind object `bind` was keyed from, so the key is
+ * built once per attached bind and a frame compares one reference.
  *
  * @example
  * ```ts
+ * const left = bind(Countdown, "left", { format: "mm:ss" });
  * const seen: SeenText = {
- *   content: "", style: "digits", bind: "Countdown.left:mm:ss", locale: "ru", unit: 95
+ *   content: "", style: "digits", bindRef: left, bind: "Countdown.left:mm:ss", locale: "ru", unit: 95
  * };
  * ```
  */
 type SeenText = {
   content: unknown;
   style: string;
+  bindRef: TextBind | undefined;
   bind: string | undefined;
   locale: string;
   unit: number | undefined;
@@ -2483,6 +2481,8 @@ type PopupLink = {
  * popup (its open is an event), the cause of its projection view otherwise, `"mount"` after a
  * restore or a load. `slot` is the host element the root is laid out in (`undefined` for the
  * viewport), `slotRect` the content box it was last solved in, in the host's own units.
+ * `pending` is true while the solve running now still waits to lay the root out; `mountRoot`
+ * creates it `false`.
  */
 type Root = {
   entity: Entity;
@@ -2503,6 +2503,13 @@ type Root = {
     w: number;
     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
@@ -2632,7 +2639,10 @@ type TextState = {
  * the element that hosts it; `fields` holds the text fields by entity. `hints` buffers the hints
  * released since the last frame step; `scrolls` holds the scroll containers; `windowRenders`
  * counts the re-renders of a windowed list its range made. `styled` and `written` count the style
- * passes and the write passes of the reconcile, for `UiCounters`.
+ * passes and the write passes of the reconcile, for `UiCounters`. `hostsVersion` moves on when a
+ * host came, went, became live or was patched, and when a view lost its `Parent` or its `Held`;
+ * `hostsSeen` and `membershipSeen` are that version and the world's membership version at the
+ * last full hosting step, which runs again only when one of them moved.
  */
 type JsxState = {
   components: Map<string, AnyComponentDefinition>;
@@ -2644,7 +2654,10 @@ type JsxState = {
   exiting: Set<Entity>;
   removing: Set<Entity>;
   hosts: Set<Entity>;
-  hosted: Map<Entity, Entity>; /** The host elements that became live in this solve: the solve hosts their views in the same frame (spec 16 U2). */
+  hosted: Map<Entity, Entity>;
+  hostsVersion: number;
+  hostsSeen: number;
+  membershipSeen: number; /** The host elements that became live in this solve: the solve hosts their views in the same frame (spec 16 U2). */
   risen: Set<Entity>; /** The views the full hosting step of this frame took back from their host; their removal lands at the flush. */
   released: Set<Entity>; /** The cause the elements entered by the diff running now take: the root's for its first build, else `"change"`. */
   building: MotionCause | undefined;
@@ -2667,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-DoHwXeQi.d.mts → visual-G6F0Mi9H.d.mts}

@@ -1,9 +1,9 @@
-import { Pr as Api$3, T as Api, Yt as Api$1, _r as Api$2 } from "./types-E2ykwIUO.mjs";
-import { P as AnimApi, r as UiApi } from "./types-Bw-qLjFZ.mjs";
-import { j as InputApi } from "./types-G3ZAAsbd.mjs";
-import { r as Repro } from "./headless-B0mH9qYg.mjs";
-import { a as InputOf, r as ControlApp } from "./types-D44EL4gT.mjs";
-import { t as commands } from "./commands-BynjWVVy.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-DoHwXeQi.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.1",
+  "version": "0.15.3",
   "description": "2D puzzle game engine on TypeScript and PixiJS, built on @moku-labs/core.",
   "type": "module",
   "sideEffects": [
@@ -102,10 +102,12 @@
     "lint:fix": "biome check --write . && eslint --fix .",
     "format": "biome format --write .",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tests/fixtures/episodes-game",
-    "test": "bun --bun vitest run",
+    "test": "bun --bun vitest run --project unit --project integration",
     "test:unit": "bun --bun vitest run --project unit",
     "test:integration": "bun --bun vitest run --project integration",
     "test:coverage": "bun --bun vitest run --project unit --project integration --coverage",
+    "test:perf": "node ./node_modules/vitest/vitest.mjs run --project perf",
+    "bench:perf": "node ./node_modules/vitest/vitest.mjs bench --run --project perf",
     "build": "tsdown",
     "mini:pack": "bun tests/fixtures/moku-game.ts pack --root tests/fixtures/mini-game",
     "mini:dev": "bun tests/fixtures/moku-game.ts dev --root tests/fixtures/mini-game",