@vgai/engine 0.5.16 → 0.5.17

package/src/canvas-react/pixi-react-adapter.tsx

@@ -171,21 +171,32 @@ export function createPixiReactAdapter(
         return null;
       }
 
-      const game = runtime?.ctx.game;
       // The React seam every dom root already has — `useWorldState`,
       // `useDebugProvider`/`useDebugCommand`/`useDebugEmit`
       // (`../react/world-state`) — works identically inside a canvas root
       // because a canvas root IS React. `host.game` is genuinely absent in
       // bare/foreign hosts, so the provider is conditional and those hooks
       // stay the inert no-ops they already document themselves to be.
+      //
+      // READ FROM `host.game`, NEVER FROM `runtime` — the same rule, and the
+      // same reasoning, as the three lane's (`../world3d-react/r3f-adapter.tsx`,
+      // beside its own `const game = host.game`). The two providers answer
+      // different questions: `EngineBridge` rides `bridge` (the vgai runtime
+      // CONTEXT, which must not enter an ecosystem-native tree), `WorldProvider`
+      // rides the Game handle the host already holds. Keyed off `runtime`, a
+      // world mounted with `engineRuntime: false` gets no `WorldProvider` at
+      // all and every `useDebugProvider` in it no-ops IN SILENCE — no error, and
+      // `vgai eval 'await game.providers()'` lists only the built-ins. That is
+      // exactly what happened on the three lane. It has never fired here only
+      // because `pixi-react-root-factory.tsx` still leaves the runtime on;
+      // that flag is the tracked component-root migration's to flip, and this
+      // seam must not be waiting for it.
+      const game = host.game;
       const world = createElement(Fragment, null, content, createElement(Lifecycle));
+      const provided = game ? createElement(WorldProvider, { game }, world) : world;
       const element = bridge
-        ? createElement(
-            EngineBridge.Provider,
-            { value: bridge },
-            game ? createElement(WorldProvider, { game }, world) : world,
-          )
-        : world;
+        ? createElement(EngineBridge.Provider, { value: bridge }, provided)
+        : provided;
 
       const root: PixiReactRoot = createRoot(canvas);
 
@@ -207,50 +218,74 @@ export function createPixiReactAdapter(
         sharedTicker: false,
       };
 
-      // `root.render` is async: it awaits `Application.init()` (which is what
-      // creates the renderer) and only then hands the tree to the reconciler.
-      // A crash inside init rejects here, which is the loud failure we want.
-      const app: Application = await root.render(element, initOptions);
-      runtime?.setApplication(app);
+      // Install the reconcile-error listener BEFORE `root.render`: Pixi hands
+      // the Application back after `init()` but React can already have thrown
+      // during that same turn. Attaching after the await loses the real error
+      // and turns it into a misleading ten-second timeout.
+      let reportReconcileFailure!: (why: string) => void;
+      const reconcileFailure = new Promise<string>((resolve) => {
+        reportReconcileFailure = resolve;
+      });
+      const onError = (event: ErrorEvent): void => {
+        reportReconcileFailure(
+          `the Pixi tree crashed before its first commit — ${event.message} ` +
+            '(mount() fails loudly instead of hanging)',
+        );
+      };
+      globalThis.addEventListener?.('error', onError);
 
-      // A reconcile-time crash (e.g. an un-extended component) surfaces as an
-      // uncaught window error and the first commit never lands — without this
-      // guard `mount()` would await `committed` forever. Convert that class of
-      // failure into a loud mount error.
-      await new Promise<void>((resolve, reject) => {
-        const fail = (why: string) => {
-          cleanup();
-          try {
-            app.destroy(false, { children: true });
-          } catch {
-            /* the world never fully came up; teardown failure must not mask why */
-          }
-          runtime?.dispose();
-          reject(new Error(`createPixiReactAdapter: root "${id}" — ${why}`));
-        };
-        const onError = (event: ErrorEvent) =>
-          fail(
-            `the Pixi tree crashed before its first commit — ${event.message} ` +
-              '(mount() fails loudly instead of hanging)',
+      let app: Application | undefined;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        // `root.render` is async: it awaits `Application.init()` (which is what
+        // creates the renderer) and only then hands the tree to the reconciler.
+        // A crash inside init rejects here, which is the loud failure we want.
+        const renderedApp = await root.render(element, initOptions);
+        app = renderedApp;
+        runtime?.setApplication(renderedApp);
+
+        // A reconcile-time crash (e.g. an un-extended component) surfaces as
+        // an uncaught window error and the first commit never lands. Race that
+        // exact signal against the commit and the last-resort ceiling.
+        const timeout = new Promise<string>((resolve) => {
+          timer = setTimeout(
+            () =>
+              resolve(
+                `no first commit within ${FIRST_COMMIT_TIMEOUT_MS / 1000}s ` +
+                  '(mount() fails loudly instead of hanging)',
+              ),
+            FIRST_COMMIT_TIMEOUT_MS,
           );
-        const timer = setTimeout(
-          () =>
-            fail(
-              `no first commit within ${FIRST_COMMIT_TIMEOUT_MS / 1000}s ` +
-                '(mount() fails loudly instead of hanging)',
-            ),
-          FIRST_COMMIT_TIMEOUT_MS,
-        );
-        const cleanup = () => {
-          clearTimeout(timer);
-          globalThis.removeEventListener?.('error', onError);
-        };
-        globalThis.addEventListener?.('error', onError);
-        void Promise.all([committed, effectsReady]).then(() => {
-          cleanup();
-          resolve();
         });
-      });
+        const failure = await Promise.race([
+          Promise.all([committed, effectsReady]).then(() => null),
+          reconcileFailure,
+          timeout,
+        ]);
+        if (failure !== null) {
+          throw new Error(`createPixiReactAdapter: root "${id}" — ${failure}`);
+        }
+      } catch (error) {
+        try {
+          app?.destroy(false, { children: true });
+        } catch {
+          /* the world never fully came up; teardown failure must not mask why */
+        }
+        runtime?.dispose();
+        throw error;
+      } finally {
+        if (timer !== undefined) clearTimeout(timer);
+        globalThis.removeEventListener?.('error', onError);
+      }
+
+      // `app` is assigned before the first-commit race. Reaching here proves
+      // both initialization and commit succeeded, so narrow once for the live
+      // mounted-root methods below.
+      if (app === undefined) {
+        runtime?.dispose();
+        throw new Error(`createPixiReactAdapter: root "${id}" initialized without an Application`);
+      }
+      const mountedApp = app;
 
       // Pin the ticker's clock to GAME time. `Ticker.lastTime` starts at -1, so
       // without this the first `update()` would report a 1ms phantom delta on
@@ -258,23 +293,27 @@ export function createPixiReactAdapter(
       // sees is exactly the `dt` the host handed us — no wall clock anywhere,
       // which is what makes a paused world's resume frame ordinary rather than
       // one giant catch-up step.
-      app.ticker.lastTime = 0;
+      mountedApp.ticker.lastTime = 0;
       let elapsedMs = 0;
       let disposed = false;
       const registry = host.game ? getDebugRegistry(host.game) : null;
       const systemAdapters: SystemAdapters =
         runtime?.systemAdapters ?? (registry ? { debug: registry.adapter } : {});
+      const disposeComplete = unmounted.then(() => {
+        mountedApp.destroy(false, { children: true });
+      });
 
       return {
         kind: 'canvas',
         // The reconciler's real root container — the same `PIXI.Container`
         // `RootInstance.pixiStage()` hands the editor.
-        stage: app.stage,
+        stage: mountedApp.stage,
         drivesOwnLoop: false,
         // Adapter surface: the host's shared debug registry. A native component
         // tree registers nothing; its entry-module `debug` export is projected
         // after mount by the shared native adapter.
         systems: systemAdapters,
+        disposeComplete,
         update(dt: number): void {
           if (disposed) return;
           elapsedMs += dt * 1000;
@@ -282,18 +321,25 @@ export function createPixiReactAdapter(
           // the native path has none. The real Pixi ticker remains the one
           // scheduler `useTick` observes, and the host only gates/advances it.
           runtime?.systems.run(dt);
-          app.ticker.update(elapsedMs);
+          mountedApp.ticker.update(elapsedMs);
         },
         resize(width: number, height: number): void {
           if (disposed) return;
           // `autoDensity: true` makes Pixi re-stamp `canvas.style.width`/
           // `.height` from this call, so the on-screen box follows the logical
           // size with no explicit CSS write from the host.
-          app.renderer.resize(width, height);
+          mountedApp.renderer.resize(width, height);
         },
         dispose(): void {
           if (disposed) return;
           disposed = true;
+          // Pixi's EventSystem owns document.pointermove + window.pointerup
+          // (and its event ticker's global listener). React's deletion commit
+          // is asynchronous, so waiting to destroy the Application leaves
+          // those listeners live when the host audits this game realm. Detach
+          // the input target synchronously; the later Application.destroy()
+          // repeats this idempotently after every useTick cleanup has landed.
+          mountedApp.renderer.events.setTargetElement(null as unknown as HTMLElement);
           // Rendering `null` children is the only unmount path `@pixi/react`
           // exposes publicly (its `unmountRoot` helper is internal), and React
           // commits that deletion on its own schedule — NOT synchronously. So
@@ -302,7 +348,6 @@ export function createPixiReactAdapter(
           // a ticker destroyed before it lands throws inside React's commit.
           // `removeView` stays false — the canvas belongs to the HOST.
           void root.render(null, initOptions);
-          void unmounted.then(() => app.destroy(false, { children: true }));
           runtime?.dispose();
         },
       };

package/src/data/curve.ts

@@ -59,7 +59,7 @@ export interface CurveAxes {
   y: { min: number; max: number; label?: string };
 }
 
-/** How the marker rides out to the emitted JSON Schema — the editor's and the dev menu's detection key, the exact shape `dataRef` uses with `x-vgai-ref`. */
+/** How the marker rides out to the emitted JSON Schema — the editor's detection key, the exact shape `dataRef` uses with `x-vgai-ref`. */
 const CURVE_META_KEY = 'x-vgai-curve';
 
 function axisLabel(axes: CurveAxes, axis: 'x' | 'y'): string {
@@ -155,7 +155,7 @@ export function curve(axes: CurveAxes): z.ZodType<CurveValue> {
  * Read a curve field's declared axes back off a LIVE Zod schema (as opposed to
  * the emitted JSON Schema, which the editor's Data panel reads instead).
  *
- * This is the dev-menu capability's detection door: it derives its rows by
+ * This is the dev-tools capability's detection door: it derives its rows by
  * walking the game's own `TuningSchema` object, so it needs the axes from the
  * schema in hand. Wrappers (`.optional()`, `.default(…)`, `.describe(…)` chains
  * that re-wrap) hide the metadata behind an inner type, so a bounded unwrap

package/src/dev/instruments.ts

@@ -25,11 +25,11 @@
  * game registry.
  *
  * ── THE DOOR ────────────────────────────────────────────────────────────────
- * This module is IMPLEMENTATION ONLY. It publishes nothing itself: the dev-menu
- * capability's own registry adopts this list (`installDevMenuInstruments`) and
+ * This module is IMPLEMENTATION ONLY. It publishes nothing itself: the dev-tools
+ * capability's own registry adopts this list (`installDevToolsInstruments`) and
  * publishes each instrument through the SAME door every declaration in that
  * capability uses — one provider per reading (`instrument.timescale`), one
- * command per action (`instrument.timescale.set`), plus the `dev-menu` index
+ * command per action (`instrument.timescale.set`), plus the `dev-tools` index
  * provider. That is deliberate and load-bearing: the registry IS the product,
  * so every reader of an instrument reaches the SAME registration.
  *
@@ -43,7 +43,7 @@
  * ── RESOURCE OWNERSHIP, STATED ONCE ─────────────────────────────────────────
  * {@link createDevInstruments} owns everything it allocates: the frame-time
  * ring buffer and its ONE `game.onRenderStep` subscription. SHARER: the
- * dev-menu capability's `DevMenuBridge`, which creates one set per mounted
+ * dev-tools capability's `DevToolsBridge`, which creates one set per mounted
  * game. TEARDOWN: the returned {@link DevInstrumentSet.dispose} — the ONE path
  * that ends it. Nothing else here holds a resource; the time-scale, pause and
  * collider instruments only drive state that `Game` already owns.

package/src/dev/register-render-vitals.ts

@@ -36,8 +36,8 @@
  *                        the drawing buffer halves was never fill-bound.
  *
  * ── GATING ──────────────────────────────────────────────────────────────────
- * The caller gates. Both seeders call this only under `devLayersEnabled()`
- * (`runtime/dev-layers.ts` — the ONE owner of "is this a dev context"), so a
+ * The caller gates. Both seeders call this only under `devBuildEnabled()`
+ * (`runtime/dev-build.ts` — the ONE owner of "is this a dev context"), so a
  * ship build registers nothing and pays nothing. Each also requires a `Game`
  * shell (there is no profiler to fold without one) and a non-headless mount
  * (nothing brackets a submission, so the readings could only ever be empty).

package/src/dev/static-batch-advisor.ts

@@ -6,7 +6,7 @@
  * require someone to ASK, and both require that someone to already know that
  * static batching exists, is possible here, and is spelled `<Frozen>`. An
  * agent building a game does not know any of that, so the measurement has to
- * do the routing itself — the same idiom as the dev-menu's unconfigured-section
+ * do the routing itself — the same idiom as dev-tools' unconfigured-section
  * warning: the reading names the exact edit.
  *
  * ── THE DECISION IS PURE, THE SCHEDULE IS NOT ───────────────────────────────
@@ -146,7 +146,7 @@ export function decideStaticBatchAdvisory(
  * Once per PAGE, not once per module evaluation — a hot reload re-runs this
  * module, and an advisory that reappears on every save is one that gets muted
  * along with everything else on the console. Same mechanism, and the same
- * reason, as the dev menu's unconfigured-section warning.
+ * reason, as dev-tools' unconfigured-section warning.
  */
 const WARNED_KEY = '__vgaiStaticBatchAdvised';
 

package/src/input/input-manager.ts

@@ -679,10 +679,32 @@ export class InputManager {
    * data reaches `isPressed`/`isJustPressed`/`isJustReleased`.
    */
   async loadMap(url: string) {
+    await this.fetchMap(url, false);
+  }
+
+  /**
+   * `loadMap`'s OPTIONAL sibling: apply the map at `url` when the project
+   * ships one and report `false` — SILENTLY — when it does not exist.
+   *
+   * The host loads the conventional map path at mount for every three/canvas
+   * root, including the scaffolded shape that has declared no actions yet, so
+   * "no map on disk" is the ordinary state of a brand-new project and must not
+   * print an error on every boot. Everything else stays exactly as loud as
+   * `loadMap`: a map that EXISTS and is malformed (or any non-404 failure)
+   * still logs and throws.
+   */
+  async loadMapIfPresent(url: string): Promise<boolean> {
+    return this.fetchMap(url, true);
+  }
+
+  /** Shared fetch/validate/apply for {@link loadMap} and
+   *  {@link loadMapIfPresent}; `optional` decides only what a 404 means. */
+  private async fetchMap(url: string, optional: boolean): Promise<boolean> {
     let data: InputMapFile;
     try {
       const res = await fetch(resolveUrl(url));
       if (!res.ok) {
+        if (optional && res.status === 404) return false;
         throw new Error(`HTTP ${res.status} ${res.statusText}`);
       }
       const json = await res.json();
@@ -697,6 +719,7 @@ export class InputManager {
       throw err instanceof AssetParseError ? err : new Error(message);
     }
     this.applyParsedMap(data);
+    return true;
   }
 
   /**

package/src/manifest/load.ts

@@ -79,9 +79,6 @@ export interface ResolvedAdapterRoot {
   readonly entry: string | undefined;
   readonly zOrder: number;
   readonly pausable: boolean;
-  /** `dev: true` — this root is a DEV LAYER, not shipped game content. See
-   *  `manifest/schema.ts`'s `dev` field for the four readers. */
-  readonly dev: boolean;
   readonly loop: 'gated' | 'self-driven';
 }
 
@@ -256,9 +253,6 @@ function checkEngineVersionPin(version: string): void {
  * resolution; `entry` drives the entry cross-field rule and is
  * carried through; `zOrder` drives the final sort; `pausable`/`loop` are
  * carried through as-is (their consumers are the runtime/CLI, T3.2/T3.3);
- * `dev` is carried through for the four dev-layer readers (`mountManifestRoots`'s
- * ship gate, the host's topmost stacking pass, the play compositor's capture
- * exclusion, and the editor's chrome-not-content seam);
  * `description` (T3.3
  * slice 3) is carried through as-is — its consumer today is
  * `resolveIngestDescriptor` (packages/editor/src/adapter-resolver.ts), which
@@ -276,7 +270,6 @@ function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
     entry: root.entry,
     zOrder: root.zOrder,
     pausable: root.pausable,
-    dev: root.dev,
     loop: root.loop,
   };
 }

package/src/manifest/schema.ts

@@ -315,19 +315,6 @@ export const AdapterRootSchema = z
       .boolean()
       .default(true)
       .describe('Whether play-mode pause/step applies to this root'),
-    dev: z
-      .boolean()
-      .default(false)
-      .describe(
-        "Marks this root as a DEV LAYER: the game's own dev GUI, not shipped game content. " +
-          'Four readers act on it. `mountManifestRoots` mounts it only when dev layers are ' +
-          'enabled (`devLayersEnabled`, runtime/dev-layers.ts), so a production build carries ' +
-          'no dev GUI; the host stacks every dev root ABOVE every non-dev root (a dev layer ' +
-          'sits topmost, and as a DOM layer it steals no input from the game while closed); ' +
-          'the play compositor EXCLUDES dev layers from a capture unless the capture asks for ' +
-          'them; and the editor mounts a dev root as edit-time CHROME rather than authorable ' +
-          'content (no hierarchy entry, no OID stamping, no JSX write-back, not selectable).',
-      ),
     loop: z
       .enum(['gated', 'self-driven'])
       .default('gated')
@@ -475,17 +462,9 @@ export const GameManifestSchema = z
         // root): a second root of the same medium parsed cleanly and was then
         // silently never mounted, which is the failure mode this rejects.
         //
-        // DEV LAYERS ARE COUNTED SEPARATELY. A `dev: true` root is not content
-        // competing for the medium — it is the game's dev GUI stacked above
-        // everything (`create-runtime.ts`'s stacking pass), and the editor
-        // mounts it as chrome, not as the one dom document. Counting it with
-        // the content roots would make the ratified shape — a game with a HUD
-        // and a dev panel, both `dom` — unrepresentable. The one-per-medium
-        // rule still applies WITHIN the dev band, for the same
-        // silently-never-mounted reason.
         const idsByMedium = new Map<string, string[]>();
         for (const root of roots) {
-          const medium = `${root.dev ? 'dev ' : ''}${rootMedium(root)}`;
+          const medium = rootMedium(root);
           const ids = idsByMedium.get(medium);
           if (ids) ids.push(root.id);
           else idsByMedium.set(medium, [root.id]);
@@ -507,9 +486,7 @@ export const GameManifestSchema = z
         "The Game's explicit, non-empty adapter-root composition. There is no implicit root. " +
           'Root ids are unique, and a project declares at most ONE world root per medium — ' +
           'one `three`, one `dom`, one canvas-surface root (first-party canvas, canvas ingest ' +
-          'and canvas module are the same medium). A `dev: true` root is counted in its own ' +
-          'band: a dev layer is chrome stacked above the game, not content competing for the ' +
-          'medium, so a game may declare a `dom` HUD and a `dom` dev layer — but not two of either.',
+          'and canvas module are the same medium).',
       ),
     authoring: z
       .object({

package/src/pixi/authoring.ts

@@ -60,7 +60,12 @@ function kindOf(o: Container): string {
  * are not names — they used to win and hide every owner. Then the texture
  * alias (`Sprite.from('satellite')`). Then a remaining game constructor
  * (`TitleScreen`, `PrimaryButton`). Bare `new Container()` still reads as
- * `container`.
+ * `container` — plus its child count when it has children, because ten
+ * unnamed siblings that all read `container` name nothing at all; the
+ * editor loads games that never labelled anything and the panel still has
+ * to be legible. The count is DISPLAY only (row ids keep using raw
+ * `.label`) and rides only this last fallthrough: a row that earned a real
+ * name is never decorated.
  */
 function displayLabel(o: Container): string {
   const authored = authoredLabel(o);
@@ -71,13 +76,26 @@ function displayLabel(o: Container): string {
   if (asset) return asset;
   const ctor = usefulCtorName(o);
   if (ctor) return ctor;
-  return kindOf(o);
+  const kind = kindOf(o);
+  const childCount = o.children?.length ?? 0;
+  return childCount > 0 ? `${kind} (${childCount})` : kind;
 }
 
-/** Pixi v8 stamps Sprite/Graphics `.label` with the class name. That is not an authored name. */
+/**
+ * Pixi v8 stamps Sprite/Graphics `.label` with the class name. That is not an
+ * authored name.
+ *
+ * The minified-constructor guard is about the SAME leak: a shipped build's
+ * `_Container` becomes `e`, and that `e` is a class name wearing a label's
+ * clothes. It is only that leak when the label IS this object's own class
+ * name — `container.label = 'fx'` (or 'ui', 'hp') is a name the game
+ * actually authored, and a game gets to be terse.
+ */
 function authoredLabel(o: Container): string | undefined {
   const authored = o.label?.trim();
-  if (!authored || isGenericPixiCtor(authored)) return undefined;
+  if (!authored) return undefined;
+  if (isMinifiedCtor(authored) && authored !== o.constructor?.name) return authored;
+  if (isGenericPixiCtor(authored)) return undefined;
   return authored;
 }
 
@@ -313,11 +331,52 @@ export const STRUCTURAL_CANVAS_IDENTITY: CanvasIdentity = {
   idFor: (object, path) => `w2d:${path.join('/')}:${kindOf(object)}:${object.label ?? ''}`,
 };
 
+/** One remembered row name, with every input it was derived from. */
+interface NameMemo {
+  readonly label: string;
+  readonly kind: string;
+  readonly parent: Container | null;
+  readonly type: unknown;
+  readonly own: string | null;
+  readonly texture: unknown;
+  readonly childCount: number;
+}
+
 export class AuthoringAdapter2D {
   private readonly byId = new Map<string, Container>();
   private overlay: Overlay2D = {};
   private dirty = false;
   private readonly identity: CanvasIdentity;
+  /**
+   * THE ROW-NAME MEMO — what makes a hierarchy read linear instead of a
+   * reflective flood walk per node per read.
+   *
+   * {@link displayLabel} is not a field read. For anything the game did not
+   * label itself it calls `viewOwnerLabel`, which climbs eight ancestors and
+   * reflects over each one's own fields, its bags, and two levels of whatever
+   * those hold — a deliberate search for the game object that owns this
+   * `.view`. Measured 2026-08-20 on a 1822-node `@pixi/react` canvas world,
+   * with the tab VISIBLE and the world rendering, one full projection walk
+   * cost ~800ms, essentially all of it here: once a world has rendered, the
+   * ancestors' own fields include Pixi's live render-group graph, so the
+   * search walks that too and finds nothing, every time, for every node.
+   *
+   * And it was asked four times per node per derivation — the projection
+   * walk, the conformance probe and the hierarchy facet each re-ask — which
+   * is how a status snapshot reached 115,433 `toNode` calls on one tree.
+   *
+   * ## What invalidates a remembered name
+   *
+   * Every input the derivation reads OFF THE OBJECT: its authored `.label`,
+   * its class, its texture, its parent, and how many children it has. Any of
+   * those changing re-derives — so a rename, a reparent, a retexture, and a
+   * sibling added or removed are all seen. What a remembered name does NOT
+   * re-notice is a game reassigning an ANCESTOR's field to point at this view
+   * after the fact, with the tree otherwise untouched; `viewOwnerLabel` is a
+   * naming heuristic, not a verdict, and the alternative is the 800ms walk
+   * above on every read of the tree.
+   */
+  private readonly names = new WeakMap<Container, NameMemo>();
 
   constructor(
     private readonly root: Container,
@@ -378,12 +437,45 @@ export class AuthoringAdapter2D {
     return this.byId.get(id) ?? null;
   }
 
+  /** This object's row name, derived once and remembered until one of the
+   *  inputs it is derived from changes. See {@link names}. */
+  private nameOf(o: Container): NameMemo {
+    const cached = this.names.get(o);
+    const parent = o.parent ?? null;
+    const type = o.constructor;
+    const own = o.label ?? null;
+    const texture = (o as Container & { texture?: unknown }).texture ?? null;
+    const childCount = o.children?.length ?? 0;
+    if (
+      cached &&
+      cached.parent === parent &&
+      cached.type === type &&
+      cached.own === own &&
+      cached.texture === texture &&
+      cached.childCount === childCount
+    ) {
+      return cached;
+    }
+    const derived: NameMemo = {
+      label: displayLabel(o),
+      kind: kindOf(o),
+      parent,
+      type,
+      own,
+      texture,
+      childCount,
+    };
+    this.names.set(o, derived);
+    return derived;
+  }
+
   private toNode(o: Container): EditorNode2D {
     const self = o as Container & { __authId?: string };
+    const { label, kind } = this.nameOf(o);
     return {
       id: self.__authId ?? '',
-      label: displayLabel(o),
-      kind: kindOf(o),
+      label,
+      kind,
       parentId: (o.parent as (Container & { __authId?: string }) | null)?.__authId ?? null,
       childIds: o.children.map((c) => (c as Container & { __authId?: string }).__authId ?? ''),
     };

package/src/react/world-state.tsx

@@ -70,6 +70,21 @@ export function useGame(): Game {
   return game;
 }
 
+/**
+ * {@link useGame}'s non-throwing sibling: the `Game` when one hosts this tree,
+ * `null` otherwise.
+ *
+ * For components that legitimately mount BOTH under a running game and under a
+ * host that has none — the editor design-mounts a world to author it, and a
+ * story renders a component with no game at all. Those components must degrade
+ * (a dev/QA surface that simply has nothing to drive) rather than throw during
+ * render, which would take the whole world down with it. Everything else uses
+ * `useGame`, whose throw is the honest report of a wiring bug.
+ */
+export function useOptionalGame(): Game | null {
+  return useContext(GameContext);
+}
+
 /**
  * Subscribe to a selected slice of game state. Re-renders only when the
  * selected value changes: the selector re-runs at most once per completed

package/src/render/soft-particle-depth.ts

@@ -91,9 +91,9 @@
  *   callers are `registerParticleSystem` / `unregisterParticleSystem`.
  * - The render target and override material belong to the
  *   {@link SoftParticleDepthPass} instance and die with its `dispose()`. The
- *   pass itself is owned by whichever adapter mount created it (the R3F adapter
- *   and `setup-three-root-adapter`), and that mount's teardown is the one path
- *   allowed to end it.
+ *   pass is owned by the renderer loop that calls it: an adapter mount for a
+ *   runtime renderer, or the editor Scene viewport for its renderer. That
+ *   owner's teardown is the one path allowed to end it.
  */
 
 import * as THREE from 'three';
@@ -203,16 +203,11 @@ function drawsIntoDepth(object: THREE.Object3D): boolean {
  * The three renderer members this prepass CANNOT do without — the render-target
  * swap it draws through, and the buffer size it sizes that target from.
  *
- * A real `WebGLRenderer` has all of them. A DESIGN-TIME settle does not: a
- * stand-in that only has to answer `render` mounts a world so the editor can
- * read it, and reaching for `getDrawingBufferSize` on one threw
- * `renderer.getDrawingBufferSize is not a function` out of the first driven
- * frame — so a world whose particles merely *declare* a proximity fade could
- * not be settled at all. A prepass is an EFFECT: with no renderer to run it on,
- * the right answer is the inert far-depth default every batch is already bound
- * to (see {@link farDepthTexture}), which is pixel-identical to a batch that
- * never asked for soft particles. So this degrades, loudly and once, instead of
- * taking the frame down with it.
+ * A real `WebGLRenderer` has all of them. A design-time stand-in that only has
+ * to answer `render` may mount a world so another host can read it, but cannot
+ * run this effect. The editor does not pass that stand-in here: its real
+ * viewport renderer owns its own pass. Other incomplete hosts still degrade
+ * loudly and once instead of taking the frame down.
  */
 const REQUIRED_RENDERER_MEMBERS = [
   'getDrawingBufferSize',