@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/tools/define-tool.ts

@@ -0,0 +1,191 @@
+/**
+ * Project tools — W4/W3 of `docs/DATA-TOOLS-DESIGN.md` (§3 contract).
+ *
+ * A project tool is ONE file, `src/tools/<name>.tool.tsx`, discovered by
+ * folder scan (same physics as data assets, §3.1: zero registration, delete
+ * the file → gone). The file exports exactly two things:
+ *
+ * ```tsx
+ * export const tool = defineTool({
+ *   id: 'tuning',          // stable slug — becomes the tab's test id
+ *   title: 'Tuning',       // the tab label (rendered after a ⚙ marker)
+ *   placement: 'document', // project-global dashboard (§3.2; 'dock' = deprecated alias)
+ * });
+ * export default function Tuning() { … }   // plain React
+ * ```
+ *
+ * or, selection-scoped (W3 — §3.2's second placement):
+ *
+ * ```tsx
+ * export const tool = defineTool({
+ *   id: 'spin',
+ *   title: 'Spin',
+ *   placement: 'inspector',                  // selection-scoped section
+ *   match: (node) => node?.kind === 'mesh',  // same contract as the
+ * });                                        // inspector-section registry
+ * export default function Spin({ node }: InspectorToolProps) { … }
+ * ```
+ *
+ * The editor renders dock tools as visually distinct tabs after a separator
+ * at the end of the bottom dock's tab row (§3.5); inspector tools render as
+ * a ⚙-marked section in the Inspector rail whenever `match` accepts the
+ * current selection. Both render inside an error boundary — a crashing tool
+ * never takes the editor down. Tools are EDITOR-ONLY: no game build bundles
+ * `src/tools/` (§4 — nothing in game code imports it), so dev/cheat surfaces
+ * can never leak into a tester serve.
+ *
+ * This module is deliberately react-free metadata (the engine core outside
+ * `src/react/` must not import react — `test/react-core-import-ban.test.ts`);
+ * the react-facing tool hooks live in `@engine/react/use-data`, and the
+ * editor-styled widget kit tools build panels from is `@editor/widgets`.
+ */
+
+import type { AuthoringAdapter, EditorNode } from '../adapter';
+
+/**
+ * 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 {
+  /**
+   * Stable slug for this tool: letters/digits/`-`/`_` only. It becomes the
+   * mount's `data-testid` (`bottom-tab-tool-<id>` for dock tools,
+   * `inspector-tool-<id>` for inspector tools), so keep it short and never
+   * rename it casually — automation and saved layouts key off it.
+   */
+  id: string;
+  /** Human label: the dock tab text, or the inspector section's header,
+   *  rendered after the ⚙ project-tool marker (§3.5). */
+  title: string;
+}
+
+/** 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). */
+export interface InspectorToolConfig extends ToolConfigBase {
+  placement: 'inspector';
+  /**
+   * When this section appears — the SAME contract as the editor's
+   * `inspector-section-registry`: called with the currently selected node
+   * (`null` in the no-selection/environment state) and the active authoring
+   * adapter; return `true` to render. Keep it cheap and pure — it runs on
+   * every inspector render. A `match` that throws is treated as `false`
+   * (with one console teaching error), never crashing the inspector.
+   */
+  match: (node: EditorNode | null, adapter: AuthoringAdapter) => boolean;
+}
+
+/** Metadata for a project tool — a discriminated union on `placement`. */
+export type ToolConfig = GlobalToolConfig | InspectorToolConfig;
+
+/**
+ * Props the editor passes to an INSPECTOR tool's default-exported component
+ * (dock tools receive no props). Everything richer (live game store, field
+ * addresses) arrives through the §3.3 hooks, not through more props.
+ */
+export interface InspectorToolProps {
+  /** The selected node your `match` accepted (`null` in the no-selection
+   *  state, if your `match` chose to accept it). */
+  node: EditorNode | null;
+  /** The selected node's stable id (`null` in the no-selection state). */
+  nodeId: string | null;
+}
+
+const TEMPLATE_EXAMPLE = 'the template worked example: src/tools/example.tool.tsx';
+
+/** Teaching-error helper (§6.5): every rejection names the fix and cites the
+ *  template example by path. */
+function toolError(problem: string, fix: string): Error {
+  return new Error(`defineTool: ${problem} — ${fix} (see ${TEMPLATE_EXAMPLE}).`);
+}
+
+/**
+ * Validate and freeze a project tool's metadata (docs/DATA-TOOLS-DESIGN.md
+ * §3.1). Call it once at module scope of a `src/tools/<name>.tool.tsx` file
+ * and export the result as `tool`, next to a default-exported React
+ * component — the editor's folder scan picks the file up automatically.
+ *
+ * Fails loud (§6.5 "errors teach") on anything malformed rather than letting
+ * a half-shaped tool render confusingly: bad `id`/`title`, an unknown
+ * placement, an inspector tool without a callable `match`.
+ *
+ * The returned config is frozen: tool metadata is a definition, not state
+ * (the same immutability rule data assets follow, §2.1).
+ */
+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: 'document' })",
+    );
+  }
+  const { id, title, placement } = config;
+  if (
+    placement !== 'document' &&
+    placement !== 'utility' &&
+    placement !== 'dock' &&
+    placement !== 'inspector'
+  ) {
+    throw toolError(
+      `unknown placement ${JSON.stringify(placement)}`,
+      "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)) {
+    throw toolError(
+      `invalid id ${JSON.stringify(id)}`,
+      'pass a non-empty slug of letters, digits, "-" or "_" — it becomes the tool\'s data-testid (bottom-tab-tool-<id> / inspector-tool-<id>)',
+    );
+  }
+  if (typeof title !== 'string' || title.trim() === '') {
+    throw toolError(`invalid title ${JSON.stringify(title)}`, 'pass a short human-readable label');
+  }
+  if (placement === 'inspector') {
+    if (typeof config.match !== 'function') {
+      throw toolError(
+        `placement 'inspector' requires a match function (got ${JSON.stringify(config.match)})`,
+        "pass match: (node) => boolean — e.g. match: (node) => node?.kind === 'mesh' — deciding which selections show this section",
+      );
+    }
+    return Object.freeze({ id, title, placement, match: config.match });
+  }
+  return Object.freeze({ id, title, placement });
+}

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