@vgai/engine 0.5.13 → 0.5.15

package/src/manifest/load.ts

@@ -62,6 +62,13 @@ export type ResolvedAdapter =
       readonly assets: Record<string, string> | undefined;
       readonly domStubs: string[] | undefined;
       readonly captureTimeoutMs: number | undefined;
+      /**
+       * The component this root'''s WORLD is, in the game'''s own source (see the
+       * field'''s schema description). Present ⇒ Edit mounts THAT component
+       * alone as a still design-time document and Play mounts the game
+       * through `entry`; absent ⇒ `entry` is what both modes mount.
+       */
+      readonly world?: { readonly entry: string; readonly export?: string | undefined } | undefined;
     };
 
 export interface ResolvedAdapterRoot {
@@ -86,7 +93,16 @@ export interface ResolvedGameManifest {
   readonly engine: { readonly version: string };
   /** Sorted by zOrder; ties broken by original array order (§3). */
   readonly roots: readonly ResolvedAdapterRoot[];
-  readonly server: { readonly room: string; readonly module: string } | undefined;
+  readonly server:
+    | {
+        readonly room: string;
+        readonly module: string;
+        /** The declared endpoint, or `undefined` = the scaffold default (see
+         *  the schema's own description; the editor resolves it against the
+         *  page host, which the loader has no business knowing). */
+        readonly endpoint: string | undefined;
+      }
+    | undefined;
   readonly resolution: { readonly width: number; readonly height: number } | undefined;
   /** Construction-time renderer properties no world can declare for itself — see the schema. */
   readonly rendering: { readonly antialias: boolean } | undefined;
@@ -218,6 +234,7 @@ function resolveAdapter(root: AdapterRoot): ResolvedAdapter {
     assets: ingest.assets,
     domStubs: ingest.domStubs,
     captureTimeoutMs: ingest.captureTimeoutMs,
+    world: ingest.world,
   };
 }
 
@@ -312,7 +329,11 @@ export function loadGameManifest(raw: unknown): ResolvedGameManifest {
   const roots = resolvedWithIndex.map(({ root }) => root);
 
   const server = manifest.server
-    ? { room: manifest.server.room, module: manifest.server.module ?? DEFAULT_SERVER_MODULE }
+    ? {
+        room: manifest.server.room,
+        module: manifest.server.module ?? DEFAULT_SERVER_MODULE,
+        endpoint: manifest.server.endpoint,
+      }
     : undefined;
 
   return {

package/src/manifest/schema.ts

@@ -154,8 +154,9 @@ export const RootAdapterSchema = z
                     'game`s entry has had ITS relative imports rewritten to whatever url the server ' +
                     'considers canonical for those files. Module identity is per-url, so the shim ' +
                     'silently binds a SECOND, freshly-evaluated copy of the whole game and every ' +
-                    'provider reports a game that never started. Measured on three-descent: 285 ' +
-                    'segments through the game`s graph, 0 through the shim`s, and no error anywhere.',
+                    'provider reports a game that never started. Measured on a vendored three ' +
+                    'game: 285 world segments through the game`s own graph, 0 through the shim`s, ' +
+                    'and no error anywhere.',
                 ),
               dataWriter: z
                 .string()
@@ -163,17 +164,18 @@ export const RootAdapterSchema = z
                 .describe(
                   "Project-relative path to a HOST-ADDED ES module that writes this game's own " +
                     'DATA file back — the sibling of a source write for a game whose authorable ' +
-                    'truth is not source. Descent places its robots, powerups and hostages in ' +
-                    'binary records inside `descent.hog`, reaching no source literal, so an ' +
+                    'truth is not source. A level-based game places its enemies, pickups and ' +
+                    'objectives in binary records inside a level file, reaching no source ' +
+                    'literal, so an ' +
                     'authored move of one is an edit to that file and nothing else can write it. ' +
                     'The module declares two exports and the host knows nothing else about it: ' +
                     '`dataFile` (a project-relative string — the ONE file this writer edits) and ' +
                     '`planDataEdit(bytes, {record, property, baseline, next})`, which returns ' +
                     '`{changed: true, bytes}` or `{changed: false, reason}` and may be async. ' +
                     'It is loaded in the editor realm beside the game, so it may `import()` the ' +
-                    "game's own modules to resolve what only a running game knows (Descent's " +
-                    'writer asks the game`s own `find_point_seg` which segment a moved object ' +
-                    'landed in, and refuses "outside the mine" rather than writing data the game ' +
+                    "game's own modules to resolve what only a running game knows (a level " +
+                    'writer asks the game`s own spatial lookup which cell a moved object ' +
+                    'landed in, and refuses "outside the level" rather than writing data the game ' +
                     'would read back wrong). It NEVER fabricates: a record it cannot address, or ' +
                     'a property it does not model, is a named refusal. ' +
                     'An object is anchored to a record by carrying `userData.vgaiRecordIndex` — ' +
@@ -186,6 +188,23 @@ export const RootAdapterSchema = z
                 .describe(
                   'Path-substring -> served-URL rewrites for this ingested game (IngestGame.assets today)',
                 ),
+              moduleAliases: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe(
+                  "The game's OWN bundler path aliases, restated as a mounting fact so its " +
+                    'source resolves unedited. A game built with its own Vite/webpack config ' +
+                    'routinely imports itself through an alias (`~/lib/config`, `@/store/x`); the ' +
+                    "editor boots Vite from the ENGINE's config and never reads a game's own, so " +
+                    'without this every such import is an unresolvable specifier and the mount dies ' +
+                    'at transform time. Key = the specifier PREFIX exactly as the game writes it ' +
+                    '("~/"); value = the repo-root-relative directory it means ' +
+                    '("/vendor/games/<id>/src/"). SELF-SCOPING: the host honors an entry only for ' +
+                    "importers inside the vendored game folder the value points into, so one game's " +
+                    "alias can never capture another module's import. Rewriting the game's own " +
+                    'imports instead would be a large non-seam-shaped diff against unmodified ' +
+                    'source — this declares the fact rather than editing it away.',
+                ),
               domStubs: z
                 .array(z.string())
                 .optional()
@@ -200,6 +219,34 @@ export const RootAdapterSchema = z
                     'FAILS by name. A game that needs a long boot (streamed world assets, a menu ' +
                     'the player must clear) raises it; the default is 10s.',
                 ),
+              world: z
+                .object({
+                  entry: z
+                    .string()
+                    .describe(
+                      "Project-relative path to the game's OWN module exporting that component",
+                    ),
+                  export: z
+                    .string()
+                    .optional()
+                    .describe(
+                      'Named export to read from that module; omit when the module default-exports it',
+                    ),
+                })
+                .strict()
+                .optional()
+                .describe(
+                  "The component this root's WORLD is, in the game's own source — a three root " +
+                    'whose scene is a React/R3F component tree names it here. Two readers, and ' +
+                    'they mount different things: the editor mounts THIS component alone as the ' +
+                    "root's design-time document (a still scene — its frameloop runs ONE bounded " +
+                    'settle at mount, so physics-owned bodies rest at their authored spawn, and ' +
+                    'is then frozen forever; nothing moves in Edit), while `entry` ' +
+                    'above stays what PLAY mounts (the whole game, its own composition, its own ' +
+                    'HUD and loop). Declaring it is what lets a scene be a scene in Edit rather ' +
+                    "than the running game's mount surfaces. A game whose world is not a " +
+                    'component omits it and keeps mounting through `entry` in both modes.',
+                ),
             })
             .strict()
             .describe(
@@ -246,6 +293,19 @@ export const AdapterRootSchema = z
         'Module exporting a world root — a TSX/R3F component or a setup()/adapter (three), or a ' +
           'React component (dom). Required for every built-in adapter root.',
       ),
+    styles: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "Project-root-relative CSS files this root's mount needs — the PAGE-level stylesheet a " +
+          'game written to own a browser tab keeps its layout in (an ingested game is the ' +
+          'standing case: its own entry imported the sheet, the host shim that replaces that ' +
+          'entry cannot, because `html`/`body`/`*` rules would restyle the editor). Declared ' +
+          'here, the editor serves each file rewritten to apply ONLY inside the container it ' +
+          "mounts the root's DOM in (`@scope`; packages/editor/server/scoped-game-css.ts), so " +
+          "the HUD is styled on the UI board's story cards and on the game surface without the " +
+          'editor seeing a single one of those rules. The files themselves are never modified.',
+      ),
     zOrder: z
       .number()
       .int()
@@ -338,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()
@@ -481,6 +541,15 @@ export const GameManifestSchema = z
     server: z
       .object({
         room: z.string().describe('Colyseus room name'),
+        endpoint: z
+          .string()
+          .optional()
+          .describe(
+            'WebSocket endpoint the editor reports for this room, e.g. "wss://rooms.example.com". ' +
+              'Omit to declare the scaffold default, `ws://<the page host>:2567` — the port ' +
+              "`server/colyseus-setup.ts` listens on. Stated here because the endpoint is the game's " +
+              'own deployment fact, not something the editor may guess',
+          ),
         module: z
           .string()
           .optional()

package/src/pixi/authoring.ts

@@ -49,16 +49,47 @@ function kindOf(o: Container): string {
   return 'container';
 }
 
+/**
+ * WHERE A ROW'S ID COMES FROM — the identity axis of the canvas authoring
+ * surface.
+ *
+ * The tree walk is the same whatever authored the tree; what differs is
+ * whether the display objects carry an authored address. A first-party
+ * `@pixi/react` world's containers do (the `data-oid` the editor's transform
+ * stamps, which the reconciler lands on the instance), and keying on it is
+ * what makes selection survive a remount. A tree the editor did NOT author has
+ * no such address, so its ids are structural paths — stable for as long as the
+ * tree's shape is, which is the best that graph can honestly offer.
+ *
+ * Both are the SAME adapter over the SAME surface; only this collaborator
+ * changes. {@link STRUCTURAL_CANVAS_IDENTITY} is the default.
+ */
+export interface CanvasIdentity {
+  /** Called once at the start of every walk — where an implementation that
+   *  disambiguates repeats (one JSX element rendered ninety times) resets its
+   *  per-walk counters. */
+  beginWalk?(): void;
+  /** The id for one display object at one position in the tree. */
+  idFor(object: Container, path: readonly number[]): string;
+}
+
+/** Deterministic structural-path ids: `w2d:<path>:<kind>:<label>`. */
+export const STRUCTURAL_CANVAS_IDENTITY: CanvasIdentity = {
+  idFor: (object, path) => `w2d:${path.join('/')}:${kindOf(object)}:${object.label ?? ''}`,
+};
+
 export class AuthoringAdapter2D {
   private readonly byId = new Map<string, Container>();
   private overlay: Overlay2D = {};
   private dirty = false;
+  private readonly identity: CanvasIdentity;
 
   constructor(
     private readonly root: Container,
-    opts: { overlay?: Overlay2D } = {},
+    opts: { overlay?: Overlay2D; identity?: CanvasIdentity } = {},
   ) {
     if (opts.overlay) this.overlay = opts.overlay;
+    this.identity = opts.identity ?? STRUCTURAL_CANVAS_IDENTITY;
     this.refresh();
   }
 
@@ -73,20 +104,21 @@ export class AuthoringAdapter2D {
    */
   reindex(): { count: number; sprites: number } {
     this.byId.clear();
+    this.identity.beginWalk?.();
     let count = 0;
     let sprites = 0;
-    const visit = (o: Container, path: string): void => {
-      const id = `w2d:${path}:${kindOf(o)}:${o.label ?? ''}`;
+    const visit = (o: Container, path: readonly number[]): void => {
+      const id = this.identity.idFor(o, path);
       (o as Container & { __authId?: string }).__authId = id;
       this.byId.set(id, o);
       count++;
       if (kindOf(o).includes('sprite')) sprites++;
       o.children.forEach((c, i) => {
-        visit(c as Container, `${path}/${i}`);
+        visit(c as Container, [...path, i]);
       });
     };
     this.root.children.forEach((c, i) => {
-      visit(c as Container, `${i}`);
+      visit(c as Container, [i]);
     });
     return { count, sprites };
   }

package/src/pixi/index.ts

@@ -10,10 +10,12 @@
 
 export {
   AuthoringAdapter2D,
+  type CanvasIdentity,
   type EditorNode2D,
   type Overlay2D,
   type Override2D,
   type Property2D,
+  STRUCTURAL_CANVAS_IDENTITY,
   type Transform2DValue,
 } from './authoring';
 export { type IngestGame2D, type IngestMount2D, mountIngestGame2D } from './ingest';

package/src/pixi/ingest.ts

@@ -1,3 +1,4 @@
+import type { VisibleCaptureWindow } from '../adapter/ingest/visible-capture-window';
 import { installSceneCapture2D, type SceneCapture2DHandle } from './scene-capture';
 
 /** A registered unmodified PixiJS game (the Pixi analog of `IngestGame`). */
@@ -25,11 +26,20 @@ export interface IngestMount2D {
  * instance, runs the game's `load()`, waits for the game to render its first
  * frame (capturing its live stage), and exposes loop gating + cleanup. A game
  * whose pixi the trap cannot reach never captures, and the mount FAILS by name.
+ *
+ * `onWait` is the three lane's own seam (`ingest-root-adapter.ts` passes
+ * `setCaptureWait`): the capture window PARKS while the tab is hidden, and a
+ * parked wait is otherwise indistinguishable from a hung mount at every door.
+ * Threading it here is what lets `vgai status` say "waiting for the first
+ * visible frame — the tab is hidden" over a canvas ingest too.
  */
 export async function mountIngestGame2D(
   pixiNamespace: unknown,
   game: IngestGame2D,
-  opts: { captureTimeoutMs?: number } = {},
+  opts: {
+    captureTimeoutMs?: number;
+    onWait?: (wait: VisibleCaptureWindow | null) => void;
+  } = {},
 ): Promise<IngestMount2D> {
   const capture = installSceneCapture2D(pixiNamespace);
   try {
@@ -41,7 +51,10 @@ export async function mountIngestGame2D(
 
   const timeout = opts.captureTimeoutMs ?? game.captureTimeoutMs ?? 8000;
   try {
-    const rt = await capture.waitForCapture(timeout);
+    const rt = await capture.waitForCapture({
+      timeoutMs: timeout,
+      ...(opts.onWait ? { onWait: opts.onWait } : {}),
+    });
     return {
       stage: rt.stage,
       capture,

package/src/pixi/render-pass-bracket.ts

@@ -0,0 +1,117 @@
+/**
+ * The render-pass BRACKET on the Pixi surface — the canvas-substrate answer to
+ * the question the three lane answers with the render accessor-trap's
+ * `setRenderPassHooks` (`adapter/ingest/scene-capture.ts`): *when does this
+ * renderer's pass begin and end?*
+ *
+ * ## Why the renderer's own runners, and not another wrap
+ *
+ * Pixi's `AbstractRenderer.render()` emits five runners in a fixed order —
+ * `prerender → renderStart → render → renderEnd → postrender` (verified in the
+ * installed pixi.js 8.19,
+ * `rendering/renderers/shared/system/AbstractRenderer.mjs`). EVERY GL draw the
+ * pass issues happens between the first and the last: the batcher draws under
+ * `render`, and even the back-buffer blit, the one draw that is easy to miss,
+ * runs under `renderStart`/`renderEnd` (`gl/GlBackBufferSystem.mjs`). So a
+ * listener added to `prerender` and `postrender` brackets the whole pass using
+ * the renderer's OWN published seam — no instance shadowing, no prototype
+ * patch, no ordering assumption beyond the one Pixi itself guarantees.
+ *
+ * `SystemRunner.add(item)` binds by METHOD NAME (`item[runnerName]` must
+ * exist) and `remove(item)` takes it back off, so installing and uninstalling
+ * is symmetric and touches nothing else on the renderer.
+ *
+ * ## Honest absence
+ *
+ * A renderer that publishes no such runners is not bracketed by guesswork:
+ * this returns `null`, and the caller treats that exactly like a missing
+ * WebGL2 context — the capability is absent, never faked.
+ */
+
+import type { RenderPassHooks } from '../adapter/ingest/scene-capture';
+
+/** The slice of a Pixi renderer this reads — structural, so a headless test
+ *  hands in a plain object with two runners and nothing else. */
+interface RunnerLike {
+  add(item: unknown): unknown;
+  remove(item: unknown): unknown;
+}
+
+interface RendererWithRunners {
+  runners?: {
+    prerender?: RunnerLike;
+    postrender?: RunnerLike;
+  };
+}
+
+function runnerPair(renderer: unknown): { pre: RunnerLike; post: RunnerLike } | null {
+  if (!renderer || typeof renderer !== 'object') return null;
+  const runners = (renderer as RendererWithRunners).runners;
+  const pre = runners?.prerender;
+  const post = runners?.postrender;
+  if (!pre || typeof pre.add !== 'function' || typeof pre.remove !== 'function') return null;
+  if (!post || typeof post.add !== 'function' || typeof post.remove !== 'function') return null;
+  return { pre, post };
+}
+
+/**
+ * Bracket a Pixi renderer's render pass with `hooks.before`/`hooks.after`.
+ *
+ * Returns the uninstall function, or `null` when this renderer publishes no
+ * `prerender`/`postrender` runners — the honest "cannot bracket this", which
+ * the caller reads as "no render-debug capability here".
+ *
+ * Neither hook may throw — the same contract the three lane's `RenderPassHooks`
+ * carries, and for a sharper reason here: these run as listeners on the
+ * renderer's own runners, so a throwing `before` aborts the game's frame AND
+ * skips the `postrender` emit that would have closed the pass. The assembly
+ * point (`ingest/ingest-render-debug.ts`) is where that contract is kept.
+ */
+export function installPixiRenderPassBracket(
+  renderer: unknown,
+  hooks: RenderPassHooks,
+): (() => void) | null {
+  const pair = runnerPair(renderer);
+  if (!pair) return null;
+
+  // One object per runner: `SystemRunner.add` binds by method name, so the
+  // `prerender` listener and the `postrender` listener cannot be the same
+  // object unless it answers to both — keeping them separate makes each
+  // `remove()` exact.
+  const preListener = {
+    prerender() {
+      hooks.before();
+    },
+  };
+  const postListener = {
+    postrender() {
+      hooks.after();
+    },
+  };
+
+  pair.pre.add(preListener);
+  pair.post.add(postListener);
+
+  let uninstalled = false;
+  return () => {
+    if (uninstalled) return;
+    uninstalled = true;
+    pair.pre.remove(preListener);
+    pair.post.remove(postListener);
+  };
+}
+
+/**
+ * The captured Pixi renderer's real WebGL2 context, or `undefined`.
+ *
+ * `WebGLRenderer.gl` is the renderer's own published field — `GlContextSystem`
+ * assigns it (`this._renderer.gl = gl`,
+ * `rendering/renderers/gl/context/GlContextSystem.mjs`) as part of
+ * initialisation, and `WebGLRenderer.d.ts` declares it. A WebGPU renderer, or
+ * a renderer that has not initialised a context, simply has none — which is the
+ * answer, not an error.
+ */
+export function pixiRenderingContext(renderer: unknown): unknown {
+  if (!renderer || typeof renderer !== 'object') return undefined;
+  return (renderer as { gl?: unknown }).gl;
+}

package/src/pixi/scene-capture.ts

@@ -18,6 +18,27 @@
  * all, and its mount fails by name.
  */
 
+import {
+  documentVisibilityClock,
+  startVisibleCaptureWindow,
+  type VisibilityClock,
+  type VisibleCaptureWindow,
+} from '../adapter/ingest/visible-capture-window';
+
+/**
+ * Options for {@link SceneCapture2DHandle.waitForCapture} — the same shape the
+ * three lane's `CaptureWaitOptions` has, because it is the same wait. Passing a
+ * bare number is `{ timeoutMs }`, which is what every existing caller does.
+ */
+export interface CaptureWait2DOptions {
+  /** The capture window, in VISIBLE milliseconds (default 10s). */
+  timeoutMs?: number | undefined;
+  /** Injected in tests; defaults to the document's own visibility. */
+  visibility?: VisibilityClock | undefined;
+  /** Live view of the wait while it runs, `null` the moment it ends. */
+  onWait?: ((wait: VisibleCaptureWindow | null) => void) | undefined;
+}
+
 /** A live Pixi runtime captured from an external PixiJS game. */
 export interface CapturedRuntime2D {
   /** The game's root stage Container. */
@@ -30,7 +51,24 @@ export interface CapturedRuntime2D {
 
 export interface SceneCapture2DHandle {
   readonly captured: CapturedRuntime2D | null;
-  waitForCapture(timeoutMs?: number): Promise<CapturedRuntime2D>;
+  /**
+   * Resolve once the game's stage is captured.
+   *
+   * The timeout is a budget of **VISIBLE** time, not wall-clock time — the same
+   * rule the three lane has had since `visible-capture-window.ts`, and for the
+   * same measured reason: a hidden document cannot render (the browser parks
+   * rAF), so counting hidden time against the game counts time it was not
+   * allowed to use. MEASURED on the bubbo-bubbo ingest with a plain
+   * `setTimeout` here: the mount succeeded when the auto-opened tab happened to
+   * be in front and died terminally 8s later when it was behind — "canvas
+   * ingest: game … rendered no capturable frame", with foregrounding the tab
+   * afterwards changing nothing. The normal HUMAN path is the backgrounded one.
+   *
+   * So the wait PARKS while hidden, the trap stays installed, and the first
+   * frame the tab draws after it comes forward is trapped exactly as it would
+   * have been at boot. Rejects only when the window is spent while VISIBLE.
+   */
+  waitForCapture(options?: number | CaptureWait2DOptions): Promise<CapturedRuntime2D>;
   getDrawCount(): number;
   /** Pause/resume the captured game's own ticker (loop-host gating). */
   setPaused(paused: boolean): void;
@@ -84,24 +122,36 @@ export function installSceneCapture2D(pixiNamespace: unknown): SceneCapture2DHan
       if (paused) app.ticker.stop();
       else app.ticker.start();
     },
-    waitForCapture(timeoutMs = 10_000) {
+    waitForCapture(options) {
+      const opts: CaptureWait2DOptions =
+        typeof options === 'number' ? { timeoutMs: options } : (options ?? {});
+      const timeoutMs = opts.timeoutMs ?? 10_000;
       if (captured) return Promise.resolve(captured);
       return new Promise<CapturedRuntime2D>((resolve, reject) => {
-        const timer = setTimeout(() => {
-          const i = waiters.indexOf(wrapped);
-          if (i >= 0) waiters.splice(i, 1);
-          reject(
-            new Error(
-              `pixi scene capture timed out after ${timeoutMs}ms — the game never ` +
-                `rendered, or it bundles its own (un-shared) copy of pixi.js.`,
-            ),
-          );
-        }, timeoutMs);
+        const captureWindow = startVisibleCaptureWindow({
+          budgetMs: timeoutMs,
+          clock: opts.visibility ?? documentVisibilityClock(),
+          onExpire: () => {
+            const i = waiters.indexOf(wrapped);
+            if (i >= 0) waiters.splice(i, 1);
+            opts.onWait?.(null);
+            reject(
+              new Error(
+                `pixi scene capture timed out after ${timeoutMs}ms of VISIBLE time ` +
+                  `(${Math.round(captureWindow.elapsedHiddenMs())}ms hidden, which is not counted — ` +
+                  'a hidden tab cannot render) — the game never rendered, or it bundles its own ' +
+                  '(un-shared) copy of pixi.js.',
+              ),
+            );
+          },
+        });
         const wrapped = (rt: CapturedRuntime2D) => {
-          clearTimeout(timer);
+          captureWindow.cancel();
+          opts.onWait?.(null);
           resolve(rt);
         };
         waiters.push(wrapped);
+        opts.onWait?.(captureWindow);
       });
     },
     uninstall() {

package/src/pixi/system-adapters.ts

@@ -6,8 +6,20 @@ import type { Physics2DRegistry } from './physics-registry';
  * Lets the editor coordinate editing of a Rapier-2D-driven entity WITHOUT owning the
  * simulation: report transform ownership, then freeze → commit → unfreeze so a drag
  * sticks instead of being stomped by the next physics step.
+ *
+ * KEYED BY THE DISPLAY OBJECT, and that is this surface's own vocabulary rather
+ * than a shortcut: the canvas gizmo's real caller
+ * (`editor/src/authoring/pixi-live-write-target.ts`) resolves node id → display
+ * itself before it asks, so there is no node-id hop on this lane at all.
+ *
+ * `keyedBy` is REQUIRED here and optional on the 3D {@link PhysicsAdapter} —
+ * see that interface's doc comment for why the union has to be tagged, and why
+ * the newcomer is the shape obliged to say so.
  */
 export interface PhysicsAdapter2D {
+  /** Discriminates this shape from the node-id-keyed {@link PhysicsAdapter}
+   *  inside `SystemAdapters['physics']`. */
+  readonly keyedBy: 'display';
   ownerOf(display: Container): 'physics' | 'none';
   freeze(display: Container): void;
   commit(display: Container, position: [number, number], rotation: number): void;
@@ -18,6 +30,7 @@ export function createPhysicsAdapter2D(physics: Physics2DRegistry): PhysicsAdapt
   // Remember each frozen body's prior type so unfreeze restores it.
   const frozen = new WeakMap<Container, number>();
   return {
+    keyedBy: 'display',
     ownerOf(display) {
       const refs = physics.get(display);
       if (!refs) return 'none';
@@ -47,3 +60,31 @@ export function createPhysicsAdapter2D(physics: Physics2DRegistry): PhysicsAdapt
     },
   };
 }
+
+/**
+ * ONE carrier over several, each owning a DIFFERENT set of display objects.
+ *
+ * The canvas ingest mount is the case: the host always builds a registry-backed
+ * carrier for objects the editor itself created, and an ingested game may ALSO
+ * declare one over its own simulation's objects. Neither is a superset of the
+ * other and neither can answer for the other's objects, so the composition is
+ * ownership-routed rather than layered — `ownerOf` asks each in order and the
+ * FIRST to claim the object handles every other call for it. A display object
+ * nobody claims answers `'none'` and the freeze/commit/unfreeze trio no-ops,
+ * which is exactly what a single unclaiming carrier already does.
+ *
+ * Order is precedence: earlier carriers win a (never-expected) double claim,
+ * so the caller states its own preference instead of this function inventing
+ * one.
+ */
+export function composePhysicsAdapters2D(carriers: readonly PhysicsAdapter2D[]): PhysicsAdapter2D {
+  const ownerFor = (display: Container): PhysicsAdapter2D | null =>
+    carriers.find((carrier) => carrier.ownerOf(display) === 'physics') ?? null;
+  return {
+    keyedBy: 'display',
+    ownerOf: (display) => (ownerFor(display) ? 'physics' : 'none'),
+    freeze: (display) => ownerFor(display)?.freeze(display),
+    commit: (display, position, rotation) => ownerFor(display)?.commit(display, position, rotation),
+    unfreeze: (display) => ownerFor(display)?.unfreeze(display),
+  };
+}