@vgai/engine 0.5.14 → 0.5.16

package/src/canvas-react/world-context.ts

@@ -11,7 +11,8 @@
  *     the ONE game-scoped registry (`getDebugRegistry(host.game)`), so a
  *     component's effect can `ctx.debug.registerStateProvider(...)` and be
  *     visible to `vgai eval`/the editor's debug panels.
- *  2. **`ctx.input` is the game-owned `InputManager`** (`host.game.input` — the
+ *  2. **`ctx.input` is the game-owned `InputManager` when a Game hosts the
+ *     root** (`host.game.input` — the
  *     same instance every sibling root shares), and this module registers the
  *     per-world debug-registry seams (`setVirtualInputTarget`/
  *     `setInputActionsSource`/`setInputTraceSource`) that make `game.input.*`
@@ -19,13 +20,14 @@
  *     `DEBUG_INPUT_UNAVAILABLE`. The project's input map loads through
  *     `Game.loadInputMap` (the game-owned, load-once path every root shares).
  *     A missing/unparseable map degrades LOUDLY without failing the mount — a
- *     canvas world with no declared actions is legal.
- *  3. **Absent subsystems fail loudly at the ctx surface.** A canvas world
- *     builds no THREE scene/camera, no Rapier world, no composer, no first-party
- *     audio/particles/debug-draw, and is handed no `AssetCache` (the canvas host
- *     context carries none — see `adapter/host-context.ts`). Reading those
- *     `ctx` fields yields a throwing getter naming the limitation and the
- *     sanctioned alternative, never a silent `undefined`.
+ *     canvas world with no declared actions is legal. A bare/foreign mount
+ *     receives `null`, visibly in the type, rather than a throwing getter.
+ *  3. **Absent subsystems are absent from the type.** A canvas world builds no
+ *     THREE scene/camera, Rapier world, composer, first-party audio/particles/
+ *     debug-draw, or Three-flavoured `AssetCache`. Its explicit
+ *     {@link CanvasGameContext} cannot name those fields, so misuse fails at
+ *     the call site during typechecking instead of from a throwing getter at
+ *     runtime.
  *
  * The Pixi handles themselves are deliberately NOT re-exposed here: a component
  * reaches the live `Application` (and therefore `app.stage`, `app.renderer`,
@@ -42,6 +44,7 @@ import {
   DEFAULT_SEEDED_RANDOM_SEED,
   getSeededRandom,
 } from '../core/seeded-random';
+import type { SimClock } from '../core/sim-clock';
 import { createSimClock, getSimClock, type SimClockInternal } from '../core/sim-clock';
 import { createSystemRunner } from '../core/system-runner';
 import {
@@ -49,7 +52,7 @@ import {
   type DebugRegistry,
   getDebugRegistry,
 } from '../runtime/debug-registry';
-import type { GameContext } from '../runtime/types';
+import type { ComponentContextBase } from '../runtime/types';
 
 /** The conventional input-map location every scaffolded project ships. Shared
  *  verbatim with the three lane — a project has ONE input map, whatever surface
@@ -70,12 +73,20 @@ export interface CanvasRootContextOptions {
   readonly inputMapPath?: string | null | undefined;
 }
 
+/** The engine services a Canvas component genuinely receives. Pixi's own
+ * `useApplication()` and `Assets` remain the doors to rendering and assets.
+ * `disposeAfter` is excluded because it accepts a `THREE.Object3D`; Canvas
+ * code schedules `displayObject.destroy()` with `clock.after()` instead. */
+export type CanvasGameContext = ComponentContextBase & {
+  readonly clock: Omit<SimClock, 'disposeAfter'>;
+};
+
 /** What {@link createCanvasRootContext} returns — the engine runtime one canvas
  *  world owns, plus the wiring hooks the adapter's `mount()` drives. */
 export interface CanvasRootRuntime {
-  /** The (partial, loud-on-absence) `GameContext` this world's components read
-   *  through `useGameContext`. See this module's header for what is present. */
-  readonly ctx: GameContext;
+  /** The explicit Canvas context this world's components read through
+   *  `useGameContext`. See {@link CanvasGameContext}. */
+  readonly ctx: CanvasGameContext;
   /** The world-local phase runner `mount().update(dt)` ticks. */
   readonly systems: ReturnType<typeof createSystemRunner>;
   /** The mounted world's `SystemAdapters` bag (`mounted.systems`) —
@@ -95,32 +106,6 @@ export interface CanvasRootRuntime {
   dispose(): void;
 }
 
-/** Install a throwing getter for a `GameContext` field this world genuinely
- *  does not build — a component reaching for it fails LOUDLY at its own call
- *  site, naming the limitation, instead of reading `undefined` and breaking
- *  somewhere downstream. Non-enumerable so spreads/serialization of the ctx
- *  never trip it. */
-function defineAbsentCtxField(
-  target: Record<string, unknown>,
-  worldId: string,
-  key: string,
-  why: string,
-): void {
-  Object.defineProperty(target, key, {
-    configurable: true,
-    enumerable: false,
-    get(): never {
-      throw new Error(
-        `canvas world "${worldId}": ctx.${key} is not available — ${why} ` +
-          '(A canvas world ctx provides: input, systems, clock, debug, random, game, roots, ' +
-          "registerSystemAdapter. The Pixi runtime itself comes from @pixi/react's " +
-          'useApplication() — app.stage, app.renderer, app.ticker — and assets from Pixi`s own ' +
-          'Assets.)',
-      );
-    },
-  });
-}
-
 /**
  * Build the engine runtime for one canvas world from a `CanvasHostContext`.
  * React-free on purpose: everything here is plain engine wiring the adapter
@@ -145,13 +130,14 @@ export function createCanvasRootContext(
 
   const ctxRaw: Record<string, unknown> = {
     systems,
+    input: host.game?.input ?? null,
     registerSystemAdapter: (kind: keyof SystemAdapters, adapter: SystemAdapters[typeof kind]) => {
       // biome-ignore lint/suspicious/noExplicitAny: same per-key record write the three lane performs; correct by construction
       (systemAdapters as any)[kind] = adapter;
       host.game?.notifySystemAdaptersChanged();
     },
   };
-  const ctx = ctxRaw as unknown as GameContext;
+  const ctx = ctxRaw as unknown as CanvasGameContext;
   if (host.game) {
     ctx.game = host.game;
     ctx.roots = host.game.roots;
@@ -188,7 +174,7 @@ export function createCanvasRootContext(
         );
       },
     });
-  ctx.clock = clock;
+  ctxRaw['clock'] = clock;
 
   // --- ctx.input + the debug-registry input seams — the game-owned
   // InputManager, polled by the game-scoped runner each frame; this world
@@ -198,7 +184,6 @@ export function createCanvasRootContext(
   if (host.game) {
     const game = host.game;
     const input = game.input;
-    ctxRaw['input'] = input;
     debugRegistry.setInputActionsSource(id, () =>
       input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })),
     );
@@ -239,68 +224,8 @@ export function createCanvasRootContext(
         );
       });
     }
-  } else {
-    defineAbsentCtxField(
-      ctxRaw,
-      id,
-      'input',
-      'input is game-owned and this mount has no Game host (host.game is absent — bare ' +
-        'harness/foreign host); mount through the vgai host to get the shared InputManager.',
-    );
   }
 
-  // --- Loud absence for everything a canvas world genuinely does not build. ---
-  const threeWhy =
-    'a canvas world renders through PixiJS and owns no THREE scene graph; the world root is ' +
-    "the Pixi stage, reached with @pixi/react's useApplication().app.stage.";
-  defineAbsentCtxField(ctxRaw, id, 'scene', threeWhy);
-  defineAbsentCtxField(ctxRaw, id, 'camera', threeWhy);
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'sceneIndex',
-    'the live scene index walks a THREE.Scene; a canvas world has none (walk the Pixi display ' +
-      'tree from useApplication().app.stage instead).',
-  );
-  const rapierWhy =
-    'canvas worlds do not build the first-party Rapier runtime; drive physics from inside the ' +
-    'tree with the 2D physics library of your choice.';
-  defineAbsentCtxField(ctxRaw, id, 'rapierWorld', rapierWhy);
-  defineAbsentCtxField(ctxRaw, id, 'rapier', rapierWhy);
-  defineAbsentCtxField(ctxRaw, id, 'physics', rapierWhy);
-  defineAbsentCtxField(ctxRaw, id, 'collisions', rapierWhy);
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'assets',
-    'the canvas host context carries no AssetCache (that cache is a GLTF/texture loader ' +
-      "resolving THREE objects); load textures/spritesheets with Pixi's own `Assets`.",
-  );
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'composer',
-    'a canvas world has no postprocessing EffectComposer; use Pixi filters on a Container.',
-  );
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'audio',
-    'canvas worlds build no first-party audio context; use Web Audio directly (or @pixi/sound).',
-  );
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'particles',
-    'canvas worlds build no three.quarks particle runtime; use a Pixi particle container.',
-  );
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'debugDraw',
-    'canvas worlds build no debug-draw helper; draw into a Pixi `Graphics` in the tree.',
-  );
-
   return {
     ctx,
     systems,

package/src/ecs/user-data.ts

@@ -111,6 +111,8 @@
  *                           JSX props for renderer/editor integration.
  * - `constraints`         — live project-owned spatial constraints projected
  *                           into the shared Inspector and viewport.
+ * - `authoringSubject`    — transient identity/inspection for an ecosystem-native
+ *                           subject represented by an Object3D proxy.
  * - `splineControlPoint`  — index of a spline control-point drag handle.
  * - `vcDirIdx`            — view-cube face direction index (0=+X,1=-X,2=+Y,...).
  */
@@ -118,6 +120,7 @@
 import type * as THREE from 'three';
 import type { ParticleSystem } from 'three.quarks';
 import type { ConstraintMark } from '../adapter/constraint';
+import type { Object3DAuthoringSubjectMark } from '../adapter/object3d-authoring-subject';
 import type { RapierEditableBody } from '../adapter/rapier-physics-adapter';
 import type { ReflectionProbeMark } from '../adapter/reflection-probe';
 import type { AnimationRuntimeInspection } from '../animation/runtime-inspection';
@@ -197,6 +200,7 @@ export interface UserDataSchema {
   skeletonEnabled: boolean;
   envObject: boolean;
   constraints: readonly ConstraintMark[];
+  authoringSubject: Object3DAuthoringSubjectMark;
   reflectionProbe: ReflectionProbeMark;
   vcDirIdx: number;
   /** W1a navmesh path-probe preview polyline: the routed waypoints, mirrored
@@ -252,6 +256,7 @@ export const UserDataKeys = {
   skeletonEnabled: 'skeletonEnabled',
   envObject: 'envObject',
   constraints: 'constraints',
+  authoringSubject: 'authoringSubject',
   reflectionProbe: 'reflectionProbe',
   vcDirIdx: 'vcDirIdx',
   navPathPoints: 'navPathPoints',

package/src/input/input-manager.ts

@@ -310,6 +310,9 @@ export class InputManager {
   private mouseButtonsJustUp = new Set<number>();
   private mouseDeltaX = 0;
   private mouseDeltaY = 0;
+  /** Last `mousemove` client position. Device-poll only — action maps read delta, not this. */
+  private mouseClientX = 0;
+  private mouseClientY = 0;
   private gamepads: (Gamepad | null)[] = [];
   // Gamepad button edge tracking (P1.6c). Keys are `${gamepadIndex}:${buttonIndex}`.
   // `Prev` is last frame's pressed set; `Down` is this frame's; the just-down/up
@@ -568,6 +571,8 @@ export class InputManager {
     if (e.movementX !== 0 || e.movementY !== 0) this.lastActiveDevice = 'mouse';
     this.mouseDeltaX += e.movementX;
     this.mouseDeltaY += e.movementY;
+    this.mouseClientX = e.clientX;
+    this.mouseClientY = e.clientY;
   };
 
   /** F2 — real window blur: drop focus and flush held REAL-device state
@@ -1690,6 +1695,99 @@ export class InputManager {
     return { x: this.mouseDeltaX, y: this.mouseDeltaY };
   }
 
+  /**
+   * Device-poll door (not an action binding). Every getter checks
+   * {@link inputActive} at READ time so a poll while play is off or the
+   * tab is unfocused is inert — the same predicate `onKeyDown` / `onMouseMove`
+   * already use. Inventing an implicit `registerAction` per key would define
+   * bindings the project's own `.inputmap` never named.
+   */
+  isDeviceKeyPressed(code: string): boolean {
+    if (!this.inputActive) return false;
+    return this.keysDown.has(code);
+  }
+
+  isDeviceKeyJustPressed(code: string): boolean {
+    if (!this.inputActive) return false;
+    return this.keysJustDown.has(code);
+  }
+
+  isDeviceKeyJustReleased(code: string): boolean {
+    if (!this.inputActive) return false;
+    return this.keysJustUp.has(code);
+  }
+
+  /** `button` is the DOM `MouseEvent.button` index (0 left, 1 middle, 2 right). */
+  isDeviceMouseButtonPressed(button: number): boolean {
+    if (!this.inputActive) return false;
+    return this.mouseButtons.has(button);
+  }
+
+  isDeviceMouseButtonJustPressed(button: number): boolean {
+    if (!this.inputActive) return false;
+    return this.mouseButtonsJustDown.has(button);
+  }
+
+  isDeviceMouseButtonJustReleased(button: number): boolean {
+    if (!this.inputActive) return false;
+    return this.mouseButtonsJustUp.has(button);
+  }
+
+  /**
+   * This-frame mouse delta in DOM space (Y +down). Callers that need Unity
+   * `Pointer.delta` (Y-up) flip Y themselves.
+   */
+  getDeviceMouseDelta(): { x: number; y: number } {
+    if (!this.inputActive) return { x: 0, y: 0 };
+    return { x: this.mouseDeltaX, y: this.mouseDeltaY };
+  }
+
+  /** Last `mousemove` client position in DOM space (origin top-left, Y +down). */
+  getDeviceMousePosition(): { x: number; y: number } {
+    if (!this.inputActive) return { x: 0, y: 0 };
+    return { x: this.mouseClientX, y: this.mouseClientY };
+  }
+
+  hasDeviceGamepad(): boolean {
+    if (!this.inputActive) return false;
+    return this.gamepads.some((pad) => pad !== null);
+  }
+
+  isDeviceGamepadButtonPressed(button: number): boolean {
+    if (!this.inputActive) return false;
+    const index = this.firstConnectedGamepadIndex();
+    if (index < 0) return false;
+    return this.gamepadButtonsDown.has(`${index}:${button}`);
+  }
+
+  isDeviceGamepadButtonJustPressed(button: number): boolean {
+    if (!this.inputActive) return false;
+    const index = this.firstConnectedGamepadIndex();
+    if (index < 0) return false;
+    return this.gamepadButtonsJustDown.has(`${index}:${button}`);
+  }
+
+  isDeviceGamepadButtonJustReleased(button: number): boolean {
+    if (!this.inputActive) return false;
+    const index = this.firstConnectedGamepadIndex();
+    if (index < 0) return false;
+    return this.gamepadButtonsJustUp.has(`${index}:${button}`);
+  }
+
+  getDeviceGamepadAxis(axis: number): number {
+    if (!this.inputActive) return 0;
+    const index = this.firstConnectedGamepadIndex();
+    if (index < 0) return 0;
+    return this.gamepads[index]?.axes[axis] ?? 0;
+  }
+
+  private firstConnectedGamepadIndex(): number {
+    for (let i = 0; i < this.gamepads.length; i++) {
+      if (this.gamepads[i] !== null) return i;
+    }
+    return -1;
+  }
+
   /**
    * F4 (spec §12 "Schema and Examples" — the F3 prompt-switching gap): which
    * device family most recently produced real input, or `null` before any
@@ -2295,6 +2393,30 @@ export class InputManager {
     element.addEventListener('click', this.onPointerLockClick);
   }
 
+  /**
+   * Release pointer lock on the element {@link requestPointerLock} wired.
+   *
+   * Godot's `Input.mouse_mode = MOUSE_MODE_VISIBLE` is this call: drop the
+   * lock if this manager holds it, and unwire the click-to-lock listener so a
+   * later click does not recapture. Idempotent. A host with no
+   * `document.exitPointerLock` (headless) still unwires — the lock never
+   * existed there.
+   *
+   * Only the lock THIS manager requested is released. An editor viewport
+   * holding lock on a different element is not ours to drop.
+   */
+  exitPointerLock() {
+    const el = this.pointerLockElement;
+    if (el) {
+      el.removeEventListener('click', this.onPointerLockClick);
+      this.pointerLockElement = null;
+    }
+    this.pointerLocked = false;
+    const doc = typeof document !== 'undefined' ? document : undefined;
+    if (!doc || typeof doc.exitPointerLock !== 'function') return;
+    if (el && doc.pointerLockElement === el) doc.exitPointerLock();
+  }
+
   /** Clean up event listeners */
   dispose() {
     if (this.disposed) return;

package/src/manifest/schema.ts

@@ -398,7 +398,7 @@ export const LearnMetadataSchema = z
       .optional()
       .describe(
         'Optional Learn-site lesson URL that teaches this project 1:1 ' +
-          '(e.g. https://vgai-learn.pages.dev/quick-starts/joints/)',
+          '(e.g. https://vgai-learn.pages.dev/manual/physics/joints/)',
       ),
   })
   .strict()

package/src/pixi/authoring.ts

@@ -44,11 +44,246 @@ export type Overlay2D = Record<string, Override2D>;
 function kindOf(o: Container): string {
   const ctor = o.constructor?.name?.toLowerCase() ?? 'container';
   if (ctor.includes('animatedsprite')) return 'animatedsprite';
+  if (ctor.includes('nineslice')) return 'nineslicesprite';
+  if (ctor.includes('tiling')) return 'tilingsprite';
   if (ctor.includes('sprite')) return 'sprite';
   if (ctor.includes('text')) return 'text';
+  if (ctor.includes('graphics')) return 'graphics';
   return 'container';
 }
 
+/**
+ * Hierarchy row text — the Pixi sibling of three's `object.name || object.type`.
+ *
+ * Authored `.label` first. Then a GAME name: a field, a bag key, or a class
+ * that owns this `.view`. Stock Pixi types (`Sprite`, `Graphics`, `_Container`)
+ * 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`.
+ */
+function displayLabel(o: Container): string {
+  const authored = authoredLabel(o);
+  if (authored) return authored;
+  const owner = viewOwnerLabel(o);
+  if (owner) return owner;
+  const asset = textureLabel(o);
+  if (asset) return asset;
+  const ctor = usefulCtorName(o);
+  if (ctor) return ctor;
+  return kindOf(o);
+}
+
+/** Pixi v8 stamps Sprite/Graphics `.label` with the class name. That is not an authored name. */
+function authoredLabel(o: Container): string | undefined {
+  const authored = o.label?.trim();
+  if (!authored || isGenericPixiCtor(authored)) return undefined;
+  return authored;
+}
+
+function isMinifiedCtor(name: string): boolean {
+  return name.length <= 2 && name === name.toLowerCase();
+}
+
+/** Pixi's own display types. The shipped build prefixes them `_`. */
+const STOCK_PIXI_CTOR = new Set([
+  'container',
+  'displayobject',
+  'sprite',
+  'animatedsprite',
+  'nineslicesprite',
+  'tilingsprite',
+  'text',
+  'bitmaptext',
+  'htmltext',
+  'graphics',
+  'mesh',
+]);
+
+function isGenericPixiCtor(name: string): boolean {
+  if (isMinifiedCtor(name) || name === 'Object' || name === 'Function') return true;
+  return STOCK_PIXI_CTOR.has(name.replace(/^_+/, '').toLowerCase());
+}
+
+function textureLabel(object: Container): string | undefined {
+  const texture = (object as Container & { texture?: { label?: string } }).texture;
+  const raw = texture?.label?.trim();
+  if (!raw || /^(_?texture)?(empty|white)$/i.test(raw)) return undefined;
+  const leaf = raw.split('/').pop() ?? raw;
+  return leaf.replace(/\.[a-z0-9]+$/i, '') || undefined;
+}
+
+function usefulCtorName(value: object): string | undefined {
+  const name = value.constructor?.name;
+  if (!name || isGenericPixiCtor(name)) return undefined;
+  return name.replace(/^_+/, '') || undefined;
+}
+
+function fieldLabel(key: string): string | undefined {
+  const trimmed = key.replace(/^_+/, '');
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function isPixiDisplay(value: object): boolean {
+  return (
+    'addChild' in value &&
+    typeof (value as { addChild?: unknown }).addChild === 'function' &&
+    'children' in value
+  );
+}
+
+/**
+ * Bubbo-style owner, identity only. TitleScreen keeps `this._cannon` and
+ * parents `this._cannon.view`. A grouping node is the field itself
+ * (`this._bottomAnimContainer`). A pool or atlas lives in a bag — Array,
+ * Map, Set, or an object literal (`_decor[]`, `allSystems`, `_parts[id]`).
+ * Scan each ancestor's own fields first — a flood walk of Pixi internals
+ * never reached `_cannon` inside the budget.
+ */
+function viewOwnerLabel(view: Container): string | undefined {
+  const seen = new WeakSet<object>();
+  let host: unknown = view.parent;
+  for (let hops = 0; hops < 8 && host && typeof host === 'object'; hops++) {
+    const found = labelFromHolder(host, view, seen) ?? findHeldOwner(host, view, 2, seen);
+    if (found) return found;
+    host = (host as { parent?: unknown }).parent;
+  }
+  return undefined;
+}
+
+function isGameFieldKey(key: string): boolean {
+  // Skip display-list indices (`0`, `1`) and Pixi internals (`children`).
+  return /^_?[A-Za-z][A-Za-zA-Z0-9]*$/.test(key) && !PIXI_INTERNAL_KEY.has(key);
+}
+
+const PIXI_INTERNAL_KEY = new Set([
+  'parent',
+  'children',
+  'transform',
+  'position',
+  'scale',
+  'pivot',
+  'skew',
+  'worldTransform',
+  'localTransform',
+]);
+
+function labelFromHolder(host: object, view: Container, seen: WeakSet<object>): string | undefined {
+  if (seen.has(host)) return undefined;
+  seen.add(host);
+  const asBag = nameInBag(host, view, undefined, seen);
+  if (asBag) return asBag;
+  for (const [key, value] of Object.entries(host as Record<string, unknown>)) {
+    if (!isGameFieldKey(key)) continue;
+    const named = nameIfHoldsView(host, key, value, view);
+    if (named) return named;
+    const nested = nameInBag(value, view, key, seen);
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
+function nameInBag(
+  value: unknown,
+  view: Container,
+  fieldKey: string | undefined,
+  seen: WeakSet<object>,
+): string | undefined {
+  const entries = bagEntries(value);
+  if (!entries) return undefined;
+  for (const [itemKey, item] of entries) {
+    const named = nameBagItem(value, item, usableBagKey(itemKey) ?? fieldKey, view, seen);
+    if (named) return named;
+  }
+  return undefined;
+}
+
+function nameBagItem(
+  bag: unknown,
+  item: unknown,
+  key: string | undefined,
+  view: Container,
+  seen: WeakSet<object>,
+): string | undefined {
+  if (key) {
+    const named = nameIfHoldsView(
+      item && typeof item === 'object' ? item : (bag as object),
+      key,
+      item,
+      view,
+    );
+    if (named) return named;
+  } else if (item && typeof item === 'object' && (item as { view?: unknown }).view === view) {
+    const named = usefulCtorName(item);
+    if (named) return named;
+  }
+  if (item && typeof item === 'object' && !isPixiDisplay(item)) {
+    return labelFromHolder(item, view, seen);
+  }
+  return undefined;
+}
+
+function usableBagKey(key: string): string | undefined {
+  if (!key || /^\d+$/.test(key)) return undefined;
+  return isGameFieldKey(key) || key.includes('-') ? (fieldLabel(key) ?? key) : undefined;
+}
+
+function bagEntries(value: unknown): readonly [string, unknown][] | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  // Game arrays are allowed to be exotic subclasses. Do not dispatch through
+  // their overridable `map`: one shipped Pixi game returns its elements rather
+  // than `[key, value]` pairs there, which made hierarchy labeling throw while
+  // destructuring the result. The authoring seam treats game objects as
+  // untrusted observations, so normalize with indexed reads into our own array.
+  if (Array.isArray(value)) {
+    const entries: [string, unknown][] = [];
+    for (let index = 0; index < value.length; index++) {
+      entries.push([String(index), value[index]]);
+    }
+    return entries;
+  }
+  if (value instanceof Map) return [...value.entries()].map(([key, item]) => [String(key), item]);
+  if (value instanceof Set) return [...value].map((item, index) => [String(index), item]);
+  if (Object.getPrototypeOf(value) !== Object.prototype) return undefined;
+  return Object.entries(value as Record<string, unknown>);
+}
+
+function nameIfHoldsView(
+  host: object,
+  key: string,
+  value: unknown,
+  view: Container,
+): string | undefined {
+  if (value === view) {
+    const field = fieldLabel(key);
+    if (field && field.toLowerCase() !== 'view') {
+      return usefulCtorName(value as object) ?? field;
+    }
+    return usefulCtorName(value as object) ?? usefulCtorName(host) ?? field;
+  }
+  if (value && typeof value === 'object' && (value as { view?: unknown }).view === view) {
+    return usefulCtorName(value) ?? fieldLabel(key);
+  }
+  return undefined;
+}
+
+function findHeldOwner(
+  held: object,
+  view: Container,
+  depth: number,
+  seen: WeakSet<object>,
+): string | undefined {
+  const direct = labelFromHolder(held, view, seen);
+  if (direct) return direct;
+  if (depth <= 0) return undefined;
+  for (const value of Object.values(held as Record<string, unknown>)) {
+    if (!value || typeof value !== 'object' || isPixiDisplay(value)) continue;
+    const found = findHeldOwner(value, view, depth - 1, seen);
+    if (found) return found;
+  }
+  return undefined;
+}
+
 /**
  * WHERE A ROW'S ID COMES FROM — the identity axis of the canvas authoring
  * surface.
@@ -147,7 +382,7 @@ export class AuthoringAdapter2D {
     const self = o as Container & { __authId?: string };
     return {
       id: self.__authId ?? '',
-      label: o.label ?? kindOf(o),
+      label: displayLabel(o),
       kind: kindOf(o),
       parentId: (o.parent as (Container & { __authId?: string }) | null)?.__authId ?? null,
       childIds: o.children.map((c) => (c as Container & { __authId?: string }).__authId ?? ''),

package/src/pixi/ingest.ts

@@ -1,5 +1,9 @@
 import type { VisibleCaptureWindow } from '../adapter/ingest/visible-capture-window';
-import { installSceneCapture2D, type SceneCapture2DHandle } from './scene-capture';
+import {
+  type CapturedRuntime2D,
+  installSceneCapture2D,
+  type SceneCapture2DHandle,
+} from './scene-capture';
 
 /** A registered unmodified PixiJS game (the Pixi analog of `IngestGame`). */
 export interface IngestGame2D {
@@ -39,9 +43,12 @@ export async function mountIngestGame2D(
   opts: {
     captureTimeoutMs?: number;
     onWait?: (wait: VisibleCaptureWindow | null) => void;
+    acceptCapture?: (runtime: CapturedRuntime2D) => boolean;
   } = {},
 ): Promise<IngestMount2D> {
-  const capture = installSceneCapture2D(pixiNamespace);
+  const capture = installSceneCapture2D(pixiNamespace, {
+    ...(opts.acceptCapture ? { accept: opts.acceptCapture } : {}),
+  });
   try {
     await game.load();
   } catch (err) {