@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

package/src/scene/schema/material.ts

@@ -1,103 +1,108 @@
 import { z } from 'zod';
 
-export const SceneMaterialSchema = z
-  .object({
-    type: z
-      .enum(['standard', 'physical', 'basic', 'toon', 'custom'])
-      .describe('Material shading model. "custom" resolves `def` against the material registry'),
-    def: z
-      .string()
-      .optional()
-      .describe('Registered custom-material name (required when type is "custom")'),
-    uniforms: z
-      .record(z.string(), z.union([z.number(), z.string(), z.boolean(), z.array(z.number())]))
-      .optional()
-      .describe('Authored uniform values for a custom material, keyed by uniform name'),
-    color: z.string().optional().describe('Base color as CSS hex string (e.g. "#ff0000")'),
-    metalness: z.number().optional().describe('Metalness factor 0–1 (standard/physical only)'),
-    roughness: z.number().optional().describe('Roughness factor 0–1 (standard/physical only)'),
-    map: z.string().optional().describe('Path to albedo/diffuse texture image'),
-    normalMap: z.string().optional().describe('Path to normal map texture image'),
-    emissive: z.string().optional().describe('Emissive color as CSS hex string'),
-    emissiveIntensity: z.number().optional().describe('Emissive light intensity multiplier'),
-    emissiveMap: z.string().optional().describe('Path to emissive map texture image'),
-    aoMap: z.string().optional().describe('Path to ambient occlusion map texture image'),
-    lightMap: z
-      .string()
-      .optional()
-      .describe(
-        "Path to a baked lightmap texture (uses the mesh's second UV set). Applies the pre-baked GI/shadow result on top of the material.",
-      ),
-    lightMapIntensity: z.number().optional().describe('Lightmap intensity multiplier (default 1).'),
-    roughnessMap: z.string().optional().describe('Path to roughness map texture image'),
-    metalnessMap: z.string().optional().describe('Path to metalness map texture image'),
-    opacity: z.number().optional().describe('Opacity 0–1. Set transparent: true to enable'),
-    transparent: z.boolean().optional().describe('Enable alpha blending for this material'),
-    side: z.enum(['front', 'back', 'double']).optional().describe('Which face sides to render'),
-    flatShading: z.boolean().optional().describe('Use flat (faceted) shading instead of smooth'),
+const SceneMaterialObjectSchema = z.object({
+  type: z
+    .enum(['standard', 'physical', 'basic', 'toon', 'custom'])
+    .describe('Material shading model. "custom" resolves `def` against the material registry'),
+  def: z
+    .string()
+    .optional()
+    .describe('Registered custom-material name (required when type is "custom")'),
+  uniforms: z
+    .record(z.string(), z.union([z.number(), z.string(), z.boolean(), z.array(z.number())]))
+    .optional()
+    .describe('Authored uniform values for a custom material, keyed by uniform name'),
+  color: z.string().optional().describe('Base color as CSS hex string (e.g. "#ff0000")'),
+  metalness: z.number().optional().describe('Metalness factor 0–1 (standard/physical only)'),
+  roughness: z.number().optional().describe('Roughness factor 0–1 (standard/physical only)'),
+  map: z.string().optional().describe('Path to albedo/diffuse texture image'),
+  normalMap: z.string().optional().describe('Path to normal map texture image'),
+  emissive: z.string().optional().describe('Emissive color as CSS hex string'),
+  emissiveIntensity: z.number().optional().describe('Emissive light intensity multiplier'),
+  emissiveMap: z.string().optional().describe('Path to emissive map texture image'),
+  aoMap: z.string().optional().describe('Path to ambient occlusion map texture image'),
+  lightMap: z
+    .string()
+    .optional()
+    .describe(
+      "Path to a baked lightmap texture (uses the mesh's second UV set). Applies the pre-baked GI/shadow result on top of the material.",
+    ),
+  lightMapIntensity: z.number().optional().describe('Lightmap intensity multiplier (default 1).'),
+  roughnessMap: z.string().optional().describe('Path to roughness map texture image'),
+  metalnessMap: z.string().optional().describe('Path to metalness map texture image'),
+  opacity: z.number().optional().describe('Opacity 0–1. Set transparent: true to enable'),
+  transparent: z.boolean().optional().describe('Enable alpha blending for this material'),
+  side: z.enum(['front', 'back', 'double']).optional().describe('Which face sides to render'),
+  flatShading: z.boolean().optional().describe('Use flat (faceted) shading instead of smooth'),
 
-    // Physical material feature groups (physical only, all optional)
-    clearcoat: z
-      .object({
-        clearcoat: z.number().describe('Clearcoat layer intensity 0–1'),
-        clearcoatRoughness: z.number().optional().describe('Clearcoat roughness 0–1'),
-        clearcoatMap: z.string().optional().describe('Path to clearcoat intensity map'),
-        clearcoatRoughnessMap: z.string().optional().describe('Path to clearcoat roughness map'),
-      })
-      .optional()
-      .describe('Clearcoat layer (physical only)'),
+  // Physical material feature groups (physical only, all optional)
+  clearcoat: z
+    .object({
+      clearcoat: z.number().describe('Clearcoat layer intensity 0–1'),
+      clearcoatRoughness: z.number().optional().describe('Clearcoat roughness 0–1'),
+      clearcoatMap: z.string().optional().describe('Path to clearcoat intensity map'),
+      clearcoatRoughnessMap: z.string().optional().describe('Path to clearcoat roughness map'),
+    })
+    .optional()
+    .describe('Clearcoat layer (physical only)'),
 
-    transmission: z
-      .object({
-        transmission: z.number().describe('Transmission intensity 0–1 (glass, liquid)'),
-        ior: z.number().optional().describe('Index of refraction (default 1.5)'),
-        thickness: z.number().optional().describe('Volume thickness for refraction'),
-        attenuationColor: z.string().optional().describe('Color absorbed over distance'),
-        attenuationDistance: z
-          .number()
-          .optional()
-          .describe('Distance at which attenuation color takes full effect'),
-        transmissionMap: z.string().optional().describe('Path to transmission map'),
-      })
-      .optional()
-      .describe('Light transmission (physical only)'),
+  transmission: z
+    .object({
+      transmission: z.number().describe('Transmission intensity 0–1 (glass, liquid)'),
+      ior: z.number().optional().describe('Index of refraction (default 1.5)'),
+      thickness: z.number().optional().describe('Volume thickness for refraction'),
+      attenuationColor: z.string().optional().describe('Color absorbed over distance'),
+      attenuationDistance: z
+        .number()
+        .optional()
+        .describe('Distance at which attenuation color takes full effect'),
+      transmissionMap: z.string().optional().describe('Path to transmission map'),
+    })
+    .optional()
+    .describe('Light transmission (physical only)'),
 
-    sheen: z
-      .object({
-        sheen: z.number().describe('Sheen intensity 0–1 (fabric, velvet)'),
-        sheenColor: z.string().optional().describe('Sheen tint color'),
-        sheenRoughness: z.number().optional().describe('Sheen roughness 0–1'),
-        sheenColorMap: z.string().optional().describe('Path to sheen color map'),
-        sheenRoughnessMap: z.string().optional().describe('Path to sheen roughness map'),
-      })
-      .optional()
-      .describe('Sheen layer (physical only)'),
+  sheen: z
+    .object({
+      sheen: z.number().describe('Sheen intensity 0–1 (fabric, velvet)'),
+      sheenColor: z.string().optional().describe('Sheen tint color'),
+      sheenRoughness: z.number().optional().describe('Sheen roughness 0–1'),
+      sheenColorMap: z.string().optional().describe('Path to sheen color map'),
+      sheenRoughnessMap: z.string().optional().describe('Path to sheen roughness map'),
+    })
+    .optional()
+    .describe('Sheen layer (physical only)'),
 
-    iridescence: z
-      .object({
-        iridescence: z.number().describe('Iridescence intensity 0–1 (soap bubbles, oil slick)'),
-        iridescenceIOR: z.number().optional().describe('Thin-film IOR (default 1.3)'),
-        iridescenceThicknessRange: z
-          .tuple([z.number(), z.number()])
-          .optional()
-          .describe('Min/max thin-film thickness in nm'),
-        iridescenceMap: z.string().optional().describe('Path to iridescence intensity map'),
-        iridescenceThicknessMap: z
-          .string()
-          .optional()
-          .describe('Path to iridescence thickness map'),
-      })
-      .optional()
-      .describe('Iridescence thin-film (physical only)'),
+  iridescence: z
+    .object({
+      iridescence: z.number().describe('Iridescence intensity 0–1 (soap bubbles, oil slick)'),
+      iridescenceIOR: z.number().optional().describe('Thin-film IOR (default 1.3)'),
+      iridescenceThicknessRange: z
+        .tuple([z.number(), z.number()])
+        .optional()
+        .describe('Min/max thin-film thickness in nm'),
+      iridescenceMap: z.string().optional().describe('Path to iridescence intensity map'),
+      iridescenceThicknessMap: z.string().optional().describe('Path to iridescence thickness map'),
+    })
+    .optional()
+    .describe('Iridescence thin-film (physical only)'),
 
-    displacementMap: z.string().optional().describe('Path to displacement/height map'),
-    displacementScale: z.number().optional().describe('Displacement height multiplier'),
-    displacementBias: z.number().optional().describe('Displacement offset'),
-  })
-  .describe('Material appearance properties');
+  displacementMap: z.string().optional().describe('Path to displacement/height map'),
+  displacementScale: z.number().optional().describe('Displacement height multiplier'),
+  displacementBias: z.number().optional().describe('Displacement offset'),
+});
+
+export const SceneMaterialSchema = SceneMaterialObjectSchema.superRefine((material, ctx) => {
+  if (material.type === 'custom' && !material.def?.trim()) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['def'],
+      message: 'Custom material requires a non-empty registered definition name',
+    });
+  }
+}).describe('Material appearance properties');
 
 /** Partial schema for prefab instance overrides (type not required). */
-export const SceneMaterialOverrideSchema = SceneMaterialSchema.partial();
+export const SceneMaterialOverrideSchema = SceneMaterialObjectSchema.partial();
 
 export type SceneMaterial = z.infer<typeof SceneMaterialSchema>;
 

package/src/scene/schema/scene-file.ts

@@ -1,7 +1,6 @@
 import { z } from 'zod';
 import { type SceneEntity, SceneEntitySchema } from './entity';
 import { SceneEnvironmentSchema } from './environment';
-import { UIRootSchema } from './ui';
 
 export const SceneFileSchema = z
   .object({
@@ -9,13 +8,8 @@ export const SceneFileSchema = z
     name: z.string().describe('Scene display name'),
     environment: SceneEnvironmentSchema.optional().describe('Scene-level environment settings'),
     entities: z.array(SceneEntitySchema).describe('Top-level entities in the scene'),
-    // UI roots (HUD/menus) attached to the scene graph as data. Optional and
-    // additive — pre-UI scenes (no `ui` field) load unchanged (A4 versioning).
-    ui: z
-      .array(UIRootSchema)
-      .optional()
-      .describe('React UI roots (canvases) attached to the scene graph (A1)'),
   })
+  .strict()
   .describe('Scene file (.vscn.json)');
 
 export type SceneFile = z.infer<typeof SceneFileSchema>;

package/src/scene/user-data.ts

@@ -42,6 +42,8 @@
  *                           mixer; see xstate-animation-binding.ts).
  * - `_availableClips`     — string[] of clip names discovered on the GLTF
  *                           (inspector dropdown; same names as `_animClips`' keys).
+ * - `_xstateAnimation`    — live native XState/Three binding exposed for
+ *                           play-mode inspection; removed when binding disposes.
  *
  * Disposal contract:
  * - `__sharedGeometry`    — `true` when a mesh's geometry is shared/cached and MUST
@@ -77,6 +79,8 @@
  * - `editorHelper`        — `true` for editor-only helper objects (gizmos, wireframes).
  * - `editorHelperType`    — which kind of helper (lights/particles/pivot/navmesh/...).
  * - `editorIcon`          — `true` for editor billboard icon sprites.
+ * - `skeletonVisible`     — per-entity editor preference for its bone overlay.
+ * - `skeletonEnabled`     — resolved visibility preference on a skeleton helper.
  * - `envObject`           — `true` for environment objects (ambient light, etc.).
  * - `splineControlPoint`  — index of a spline control-point drag handle.
  * - `vcDirIdx`            — view-cube face direction index (0=+X,1=-X,2=+Y,...).
@@ -84,6 +88,8 @@
 
 import type * as THREE from 'three';
 import type { ParticleSystem } from 'three.quarks';
+import type { AnyActor } from 'xstate';
+import type { XStateAnimationBinding } from '../animation/xstate-animation-binding';
 import type { SceneEntity } from './scene-types';
 
 /** The kinds of editor helper objects tagged via `editorHelperType`. */
@@ -95,7 +101,8 @@ export type EditorHelperType =
   | 'splines'
   | 'particles'
   | 'pivot'
-  | 'navmesh';
+  | 'navmesh'
+  | 'skeletons';
 
 /**
  * Maps each canonical accessor name to its value type. This is the single
@@ -115,6 +122,7 @@ export interface UserDataSchema {
   _animMixer: THREE.AnimationMixer;
   _animClips: Map<string, THREE.AnimationClip>;
   _availableClips: string[];
+  _xstateAnimation: XStateAnimationBinding & { readonly actor: AnyActor };
   __sharedGeometry: boolean;
   __shadeOrig: THREE.Material | THREE.Material[];
   __shadeUnlit: THREE.Material[];
@@ -128,6 +136,8 @@ export interface UserDataSchema {
   editorHelper: boolean;
   editorHelperType: EditorHelperType;
   editorIcon: boolean;
+  skeletonVisible: boolean;
+  skeletonEnabled: boolean;
   envObject: boolean;
   vcDirIdx: number;
 }
@@ -154,6 +164,7 @@ export const UserDataKeys = {
   _animMixer: '_animMixer',
   _animClips: '_animClips',
   _availableClips: '_availableClips',
+  _xstateAnimation: '_xstateAnimation',
   __sharedGeometry: '__sharedGeometry',
   __shadeOrig: '__shadeOrig',
   __shadeUnlit: '__shadeUnlit',
@@ -167,6 +178,8 @@ export const UserDataKeys = {
   editorHelper: 'editorHelper',
   editorHelperType: 'editorHelperType',
   editorIcon: 'editorIcon',
+  skeletonVisible: 'skeletonVisible',
+  skeletonEnabled: 'skeletonEnabled',
   envObject: 'envObject',
   vcDirIdx: 'vcDirIdx',
 } as const satisfies Record<UserDataKey, string>;

package/src/setup/setup-renderer.ts

@@ -74,7 +74,7 @@ export function applyRendererSettings(
  * `opts` is additive (T6.1 slice 1, COMPOSITION-DESIGN.md D5 §1/§4): omitted
  * entirely, construction is byte-identical to before (no `alpha`/
  * `preserveDrawingBuffer` keys at all) — the legacy single-canvas host never
- * passes it. The worlds path passes `alpha:true` for every stacked canvas
+ * passes it. The roots path passes `alpha:true` for every stacked canvas
  * above the bottom one (so its clear-alpha-0 shows the layer below through
  * it) and `preserveDrawingBuffer:true` for every stacked canvas (the
  * recorded capture-tier cost, paid once here rather than re-derived later).

package/src/tools/define-tool.ts

@@ -9,7 +9,7 @@
  * export const tool = defineTool({
  *   id: 'tuning',          // stable slug — becomes the tab's test id
  *   title: 'Tuning',       // the tab label (rendered after a ⚙ marker)
- *   placement: 'dock',     // project-global dashboard tab (§3.2)
+ *   placement: 'document', // project-global dashboard (§3.2; 'dock' = deprecated alias)
  * });
  * export default function Tuning() { … }   // plain React
  * ```
@@ -42,9 +42,39 @@
 
 import type { AuthoringAdapter, EditorNode } from '../adapter';
 
-/** The two placements (§3.2). Deliberately nothing else — no floating
- *  windows, no in-game overlay host (§3.2 "deliberately NOT built"). */
-export type ToolPlacement = 'dock' | 'inspector';
+/**
+ * Tool placements. Since W0 of the editor workspace-shell program
+ * (docs/EDITOR-WORKSPACE-SHELL-TODO.md §7.2), placement describes MEANING,
+ * not a physical container:
+ *
+ * - `'document'` — a substantial project-global surface (tuning dashboard,
+ *   table, graph) that belongs in the center workspace;
+ * - `'inspector'` — a selection-scoped section in the right Inspector rail;
+ * - `'utility'` — a transient output/debug surface for the bottom drawer;
+ * - `'dock'` — DEPRECATED physical compatibility alias. Existing dock tools
+ *   remain in the bottom panel so projects do not lose the ability to tune
+ *   them while watching the Game/Scene.
+ *
+ * Only an explicit `document` declaration replaces the center subject.
+ * `utility` and legacy `dock` remain in the bottom drawer. Deliberately
+ * still nothing else — no floating windows, no in-game overlay
+ * host (docs/DATA-TOOLS-DESIGN.md §3.2 "deliberately NOT built").
+ */
+export type ToolPlacement = 'document' | 'inspector' | 'utility' | 'dock';
+
+/** The project-global (non-selection-scoped) placements. */
+export type GlobalToolPlacement = 'document' | 'utility' | 'dock';
+
+/**
+ * Compatibility means preserving behavior: legacy `'dock'` tools remain in
+ * the bottom panel. New tools choose `'document'`, `'utility'`, or
+ * `'inspector'` deliberately.
+ */
+export function normalizeToolPlacement(
+  placement: ToolPlacement,
+): 'document' | 'inspector' | 'utility' {
+  return placement === 'dock' ? 'utility' : placement;
+}
 
 /** Fields every tool declares — see {@link defineTool} for the contract. */
 interface ToolConfigBase {
@@ -60,9 +90,10 @@ interface ToolConfigBase {
   title: string;
 }
 
-/** A project-global dashboard tab in the bottom dock (§3.2, W4). */
-export interface DockToolConfig extends ToolConfigBase {
-  placement: 'dock';
+/** A project-global tool (§3.2 W4; `'dock'` preserves its historical bottom
+ *  placement through the `'utility'` compatibility normalization). */
+export interface GlobalToolConfig extends ToolConfigBase {
+  placement: GlobalToolPlacement;
 }
 
 /** A selection-scoped Inspector section (§3.2, W3). */
@@ -80,7 +111,7 @@ export interface InspectorToolConfig extends ToolConfigBase {
 }
 
 /** Metadata for a project tool — a discriminated union on `placement`. */
-export type ToolConfig = DockToolConfig | InspectorToolConfig;
+export type ToolConfig = GlobalToolConfig | InspectorToolConfig;
 
 /**
  * Props the editor passes to an INSPECTOR tool's default-exported component
@@ -120,14 +151,22 @@ export function defineTool(config: ToolConfig): Readonly<ToolConfig> {
   if (config === null || typeof config !== 'object') {
     throw toolError(
       'expected a config object',
-      "call it as defineTool({ id, title, placement: 'dock' })",
+      "call it as defineTool({ id, title, placement: 'document' })",
     );
   }
   const { id, title, placement } = config;
-  if (placement !== 'dock' && placement !== 'inspector') {
+  if (
+    placement !== 'document' &&
+    placement !== 'utility' &&
+    placement !== 'dock' &&
+    placement !== 'inspector'
+  ) {
     throw toolError(
       `unknown placement ${JSON.stringify(placement)}`,
-      "the placements are 'dock' (project-global bottom tab) and 'inspector' (selection-scoped section, §3.2)",
+      "the placements are 'document' (project-global center document), 'inspector' " +
+        "(selection-scoped section) and 'utility' (transient bottom-drawer output); " +
+        "'dock' remains accepted as a deprecated bottom-panel alias " +
+        '(docs/EDITOR-WORKSPACE-SHELL-TODO.md §7.2)',
     );
   }
   if (typeof id !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(id)) {

package/src/world2d/authoring-2d.ts

@@ -31,6 +31,8 @@ export interface Property2D {
 
 /** A persisted edit overlay keyed by structural-path id (the 2D analog of IngestOverlay). */
 export interface Override2D {
+  label?: string;
+  alpha?: number;
   position?: [number, number];
   rotation?: number;
   scale?: [number, number];
@@ -110,7 +112,11 @@ export class AuthoringAdapter2D {
   // --- Transforms ---
   getTransform(id: string): Transform2DValue | null {
     const o = this.byId.get(id);
-    if (!o) return null;
+    // A tracked node isn't guaranteed to be a real PixiJS display object with
+    // a transform (e.g. test doubles / non-positional fixture nodes walked
+    // via the composite adapter's overlay path) — treat a missing position
+    // the same as a missing node: no transform to report, not a crash.
+    if (!o || !o.position || !o.scale) return null;
     return {
       position: [o.position.x, o.position.y],
       rotation: o.rotation,
@@ -156,6 +162,8 @@ export class AuthoringAdapter2D {
     if (!o) return;
     o[path] = value;
     this.overlay[id] ??= {};
+    if (path === 'label') this.overlay[id].label = value as string;
+    if (path === 'alpha') this.overlay[id].alpha = value as number;
     if (path === 'tint') this.overlay[id].tint = value as number;
     if (path === 'visible') this.overlay[id].visible = value as boolean;
     this.dirty = true;
@@ -164,6 +172,8 @@ export class AuthoringAdapter2D {
   private applyOverride(id: string, ov: Override2D): void {
     const o = this.byId.get(id);
     if (!o) return;
+    if (ov.label !== undefined) o.label = ov.label;
+    if (ov.alpha !== undefined) o.alpha = ov.alpha;
     if (ov.position) o.position.set(ov.position[0], ov.position[1]);
     if (ov.rotation !== undefined) o.rotation = ov.rotation;
     if (ov.scale) o.scale.set(ov.scale[0], ov.scale[1]);
@@ -201,6 +211,12 @@ export class AuthoringAdapter2D {
   serializeOverlay(): Overlay2D {
     return this.overlay;
   }
+  /** Replace, rather than merge, overlay state after an exact history restore. */
+  replaceOverlay(overlay: Overlay2D): void {
+    this.overlay = structuredClone(overlay);
+    for (const [id, ov] of Object.entries(this.overlay)) this.applyOverride(id, ov);
+    this.dirty = true;
+  }
   /** Clear the dirty flag after a successful save (mirrors IngestAuthoringAdapter). */
   markClean(): void {
     this.dirty = false;

package/src/world2d/collision-2d.ts

@@ -47,7 +47,7 @@ export type Collision2DSystem = ReturnType<typeof createCollision2DSystem>;
  * structural slice: the unified `ComponentManager` (`ecs/component-manager.ts`,
  * what production wires up since T7.3 slice 1, and the only manager left —
  * the world2d silo's manager is deleted, T7.3 slice 2) satisfies it — this
- * dispatcher has no dependency on which `WorldKind` a caller's manager was
+ * dispatcher has no dependency on which `AdapterSurface` a caller's manager was
  * constructed for.
  */
 export interface TriggerDispatchComponents {

package/src/world2d/pixi-game-adapter.ts

@@ -25,10 +25,10 @@ export interface World2DHost {
   canvas: HTMLCanvasElement;
   width: number;
   height: number;
-  /** Screen-space React/HUD overlay container. */
-  ui?: HTMLDivElement;
+  /** Shared Game root when mounted by the universal multi-world host. */
+  game?: GameInternal;
   /** DPR override (T6.1 slice 1, COMPOSITION-DESIGN.md D5 §3 — "one DPR
-   *  everywhere"): the worlds-path host computes ONE dpr for every stacked
+   *  everywhere"): the roots-path host computes ONE dpr for every stacked
    *  surface and passes it here; omitted -> `createPixiSurface`'s own
    *  default (`window.devicePixelRatio`, uncapped) — today's behavior. */
   dpr?: number;
@@ -109,7 +109,7 @@ export class PixiSceneGameAdapter {
       width: host.width,
       height: host.height,
       ...(sceneData?.background ? { background: sceneData.background } : {}),
-      // T6.1 slice 1 (worlds-path host hints — see `World2DHost`'s fields):
+      // T6.1 slice 1 (roots-path host hints — see `World2DHost`'s fields):
       // all optional, all no-ops when the host is the legacy
       // `createWorld2DRuntime` entry (which never sets them), so behavior
       // there is unchanged.
@@ -128,15 +128,17 @@ export class PixiSceneGameAdapter {
     const writeTransforms2D = createTransformWriter2D(physics2d);
     const collisions2d = createCollision2DSystem(rapier2dWorld, eventQueue);
 
-    const systems = createSystemRunner();
-    systems.add('physics', () => rapier2dWorld.step(eventQueue));
-    systems.add('postPhysics', () => {
-      collisions2d.drain();
-      writeTransforms2D();
-    });
-    systems.add('render', () => surface.render());
-
-    const uiContainer = host.ui ?? document.createElement('div');
+    const systems = createSystemRunner(host.game?.profiler.systemObserver, 'pixijs');
+    systems.add('physics', () => rapier2dWorld.step(eventQueue), { name: 'physics2d.step' });
+    systems.add(
+      'postPhysics',
+      () => {
+        collisions2d.drain();
+        writeTransforms2D();
+      },
+      { name: 'physics2d.sync' },
+    );
+    systems.add('render', () => surface.render(), { name: 'pixi.render' });
 
     const ctx: World2DContext = {
       app: surface.app,
@@ -147,7 +149,7 @@ export class PixiSceneGameAdapter {
       collisions2d,
       components: null!,
       systems,
-      uiContainer,
+      ...(host.game ? { game: host.game } : {}),
     };
 
     // T7.3 slice 1/2: the pixi world's components attach onto the SAME
@@ -235,16 +237,15 @@ export interface World2DSession {
  * surface-host-backend-neutral allows). Owns the canvas and constructs a real `Game`
  * (T7.3 slice 1) with exactly one `'pixijs'`-kind `WorldInstance`, driven each fixed
  * substep through `Game.runFrame` — the world2d analog of `createGameRuntime`'s
- * `registerDefaultThreeWorld` (`runtime/create-runtime.ts`). Before T7.3 this ran its
+ * `registerThreeWorld` (`runtime/create-runtime.ts`). Before T7.3 this ran its
  * own standalone `createGameLoop` calling `mounted.update` directly; that loop is
  * retired here in favor of one shared frame executor per game root.
  */
 export async function createWorld2DRuntime(
   config: PixiSceneConfig & World2DHost,
 ): Promise<World2DSession> {
-  const { canvas, width, height, ui, ...sceneConfig } = config;
+  const { canvas, width, height, ...sceneConfig } = config;
   const adapter = new PixiSceneGameAdapter(sceneConfig);
-  const mounted = await adapter.mount({ canvas, width, height, ...(ui ? { ui } : {}) });
 
   const assets = createAssetCache();
   // `game` is referenced here before its `const` below only textually — this
@@ -258,6 +259,7 @@ export async function createWorld2DRuntime(
     },
   });
   const game: GameInternal = createGame({ loop, assets });
+  const mounted = await adapter.mount({ canvas, width, height, game });
 
   // T7.5: `mounted` (a `MountedGame2D`, extending `MountedPixiWorld`) and
   // `adapter` (this `PixiSceneGameAdapter`, satisfying `WorldInstance.adapter`'s

package/src/world2d/scene2d-loader.ts

@@ -183,6 +183,7 @@ function createPhysics2D(ctx: World2DContext, entity: Entity2D, display: Contain
   if (p.restitution !== undefined) colDesc.setRestitution(p.restitution);
   if (p.sensor) {
     colDesc.setSensor(true);
+    colDesc.setActiveCollisionTypes(rapier2d.ActiveCollisionTypes.ALL);
     colDesc.setActiveEvents(rapier2d.ActiveEvents.COLLISION_EVENTS);
   } else {
     colDesc.setActiveEvents(rapier2d.ActiveEvents.COLLISION_EVENTS);

package/src/world2d/types.ts

@@ -5,6 +5,7 @@ import type { createSystemRunner } from '../core/system-runner';
 import type { SystemPhaseName } from '../core/types';
 import type { ComponentManager } from '../ecs/component-manager';
 import type { GameComponent } from '../ecs/game-component';
+import type { Game } from '../runtime/game';
 import type { Collision2DSystem } from './collision-2d';
 import type { Physics2DRegistry } from './physics2d-registry';
 
@@ -38,8 +39,13 @@ export interface World2DContext {
   components: ComponentManager;
   /** The phase-ordered system runner (shared with the 3D path). */
   systems: ReturnType<typeof createSystemRunner>;
-  /** DOM overlay for screen-space React/HUD UI (pointer-events:none by default). */
-  uiContainer: HTMLDivElement;
+  /**
+   * The shared Game root when this world is mounted by a first-party host.
+   * This is the cross-world data path: a Pixi component can query gameplay
+   * components owned by a sibling Three.js world without a mirror store or a
+   * bespoke synchronization bridge.
+   */
+  game?: Game | undefined;
 }
 
 /** Constructor type for `GameComponent<'pixijs'>` subclasses used in a world2d