@vgai/engine 0.4.1 → 0.5.0-canary.20260719.0

package/src/dev/webgl-frame-capture.ts

@@ -0,0 +1,424 @@
+/**
+ * First-party WebGL2 single-frame draw-call capture (W4b, F11 frame debugger).
+ *
+ * WHY FIRST-PARTY, NOT spectorjs (recorded per the "use libraries directly, no
+ * wrappers" rule): the capture seam we need is the WebGL2 context this engine
+ * ALREADY owns end-to-end (`renderer.getContext()` in
+ * `vgai-scene-game-adapter.ts`). spectorjs is absent from node_modules, and its
+ * actual value is a bundled inspector UI we would discard — adopting it imports
+ * ~2MB of library to keep ~10% of it, and it wraps the context with its own
+ * global patching model rather than the instance-shadow-and-restore discipline
+ * the rest of dev/ uses (see `webgl-gpu-timer.ts`, the raw-context precedent
+ * this mirrors: instance shadowing, restore-in-finally, mock-GL unit test). So
+ * we instrument the real context directly, at the one seam we control.
+ *
+ * DISCIPLINE (mirrors webgl-gpu-timer.ts):
+ *  - Patching happens ONLY inside `beginPass()` and ONLY while `armed`. Every
+ *    patch is an OWN-property shadow on the context instance; the WebGL2
+ *    prototype is NEVER touched. `endPass()` restores every original in a
+ *    `finally` (own props reassigned, prototype-inherited methods `delete`d so
+ *    the real method shows through again), so a throwing draw cannot leave the
+ *    context wrapped.
+ *  - HONESTY (adapters never fabricate): a value we cannot measure at this seam
+ *    is recorded as `null` with the reason implied by the field, never zeroed
+ *    or guessed. Program/framebuffer LABELS are capture-local identity tags
+ *    (`program#N`), not the object's real GL debug name (raw WebGL2 exposes
+ *    none). Framebuffer dimensions are only reported when cheaply knowable
+ *    (renderbuffer color attachment); a texture-attachment FBO's size is not
+ *    queryable in raw WebGL2, so it is `null`, not invented (see below —
+ *    a documented deviation from the plan's non-nullable width/height).
+ *  - Draw attribution is a single pending-annotation slot consumed by the NEXT
+ *    draw and then cleared: a second draw with no fresh annotation records
+ *    `annotation: null` (counted as unattributed), never the previous draw's.
+ */
+
+/** The five WebGL2 draw entry points this instrument wraps. */
+export type FrameCaptureEntryPoint =
+  | 'drawArrays'
+  | 'drawElements'
+  | 'drawArraysInstanced'
+  | 'drawElementsInstanced'
+  | 'drawRangeElements';
+
+/** Per-draw attribution supplied by {@link WebGLFrameCapture.annotateNextDraw}
+ *  (the render adapter derives it from the three.js object about to draw). */
+export interface DrawAnnotation {
+  object: { name: string; type: string; entityId?: string };
+  geometry: { type: string; name: string; attributes: string[]; indexed: boolean };
+  material: { type: string; name: string };
+}
+
+/** Where a draw rendered: the default framebuffer (canvas) or a bound FBO. */
+export type DrawTarget =
+  | { kind: 'canvas' }
+  | {
+      kind: 'framebuffer';
+      /** Color-attachment width, or `null` when not cheaply queryable
+       *  (texture attachment — raw WebGL2 has no size query). */
+      width: number | null;
+      height: number | null;
+      /** Capture-local identity tag (`framebuffer#N`), not a GL debug name. */
+      label: string | null;
+    };
+
+export interface FrameCaptureDrawCall {
+  readonly index: number;
+  readonly entryPoint: FrameCaptureEntryPoint;
+  /** Decoded primitive mode, e.g. `'TRIANGLES'`, `'LINES'` (raw enum when
+   *  unrecognised). */
+  readonly mode: string;
+  /** Vertex/index count passed to the draw. */
+  readonly count: number;
+  /** Instance count for the instanced entry points, else `null` (not 0 —
+   *  a non-instanced draw has no instance count to report). */
+  readonly instanceCount: number | null;
+  /** Capture-local program identity (`program#N`), or `null` when no program
+   *  was bound via `useProgram`. */
+  readonly programLabel: string | null;
+  readonly target: DrawTarget;
+  /** Shadow-tracked viewport `[x, y, w, h]` at draw time. */
+  readonly viewport: readonly [number, number, number, number];
+  readonly state: {
+    readonly blend: boolean;
+    readonly depthTest: boolean;
+    readonly depthWrite: boolean;
+    readonly cull: 'front' | 'back' | 'none';
+    readonly scissor: boolean;
+  };
+  /** The annotation this draw consumed, or `null` when none was pending
+   *  (unattributed — e.g. a shadow/composer pass draw). */
+  readonly annotation: DrawAnnotation | null;
+}
+
+export interface FrameCapture {
+  readonly id: number;
+  /** Injected capture timestamp (ms) — see `createWebGLFrameCapture` options. */
+  readonly capturedAt: number;
+  readonly drawCalls: readonly FrameCaptureDrawCall[];
+  readonly totals: {
+    /** Draws RECORDED (excludes any dropped past the cap). */
+    readonly drawCalls: number;
+    /** Recorded draws with `annotation: null`. */
+    readonly unattributed: number;
+    /** Draws dropped because the cap was hit (0 when nothing was dropped). */
+    readonly truncated: number;
+  };
+  readonly notes: readonly string[];
+}
+
+export interface WebGLFrameCaptureOptions {
+  /** Injected clock for `capturedAt`; defaults to `Date.now`. Injectable so a
+   *  test gets deterministic timestamps (mirrors the profiler stamping time
+   *  through a single `now()` indirection rather than a module-level call). */
+  now?: () => number;
+  /** Hard cap on recorded draws (default 5000). Draws past it are dropped and
+   *  counted in `totals.truncated`, with a note. */
+  maxDrawCalls?: number;
+}
+
+export interface WebGLFrameCapture {
+  /** Arm a single capture; the NEXT `beginPass()` patches the context. */
+  arm(): void;
+  readonly armed: boolean;
+  /** If armed, shadow-patch the context. No-op otherwise (zero patching when
+   *  not armed). Must be paired with `endPass()`. */
+  beginPass(): void;
+  /** Restore all patches (in `finally`) and, if a pass was patched, return the
+   *  assembled {@link FrameCapture}. Returns `null` if `beginPass` did not
+   *  patch (was not armed). One-shot: disarms after. */
+  endPass(): FrameCapture | null;
+  /** Set the annotation the next draw will consume (then cleared). */
+  annotateNextDraw(annotation: DrawAnnotation): void;
+}
+
+const DEFAULT_MAX_DRAW_CALLS = 5000;
+
+/** GL primitive-mode enum → name (decoded once, from the live context). */
+function buildModeTable(gl: WebGL2RenderingContext): Map<number, string> {
+  return new Map<number, string>([
+    [gl.POINTS, 'POINTS'],
+    [gl.LINES, 'LINES'],
+    [gl.LINE_LOOP, 'LINE_LOOP'],
+    [gl.LINE_STRIP, 'LINE_STRIP'],
+    [gl.TRIANGLES, 'TRIANGLES'],
+    [gl.TRIANGLE_STRIP, 'TRIANGLE_STRIP'],
+    [gl.TRIANGLE_FAN, 'TRIANGLE_FAN'],
+  ]);
+}
+
+export function createWebGLFrameCapture(
+  gl: WebGL2RenderingContext,
+  options: WebGLFrameCaptureOptions = {},
+): WebGLFrameCapture {
+  const nowFn = options.now ?? (() => Date.now());
+  const maxDrawCalls = options.maxDrawCalls ?? DEFAULT_MAX_DRAW_CALLS;
+  const modeTable = buildModeTable(gl);
+
+  // Persistent identity maps (stable labels across passes).
+  const programLabels = new Map<WebGLProgram, string>();
+  const framebufferLabels = new Map<WebGLFramebuffer, string>();
+  let nextProgramId = 0;
+  let nextFramebufferId = 0;
+  let captureId = 0;
+
+  // Shadow-tracked GL state (updated by the wrapped setters during a pass).
+  let currentProgram: WebGLProgram | null = null;
+  let currentFramebuffer: WebGLFramebuffer | null = null;
+  let currentViewport: [number, number, number, number] = [0, 0, 0, 0];
+
+  // Per-pass accumulators.
+  let armed = false;
+  let patched = false;
+  let drawCalls: FrameCaptureDrawCall[] = [];
+  let truncated = 0;
+  let notes: string[] = [];
+  let pendingAnnotation: DrawAnnotation | null = null;
+
+  // Saved originals for restore. Value is the original fn; a key present in
+  // `wasOwn` means it was an own property (restore by assignment), otherwise
+  // it was prototype-inherited (restore by delete).
+  const originals = new Map<string, unknown>();
+  const wasOwn = new Set<string>();
+
+  function decodeMode(mode: number): string {
+    return modeTable.get(mode) ?? `0x${mode.toString(16)}`;
+  }
+
+  function labelForProgram(program: WebGLProgram | null): string | null {
+    if (!program) return null;
+    let label = programLabels.get(program);
+    if (label === undefined) {
+      label = `program#${nextProgramId++}`;
+      programLabels.set(program, label);
+    }
+    return label;
+  }
+
+  /** Best-effort color-attachment dimensions for a bound draw FBO. Only a
+   *  RENDERBUFFER color attachment is cheaply queryable in raw WebGL2; a
+   *  texture attachment is not, so this returns nulls (honest absence). All
+   *  reads are guarded — a mock/foreign context returns nulls, never throws. */
+  function measureFramebufferSize(): { width: number | null; height: number | null } {
+    try {
+      const type = gl.getFramebufferAttachmentParameter(
+        gl.DRAW_FRAMEBUFFER,
+        gl.COLOR_ATTACHMENT0,
+        gl.FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE,
+      );
+      if (type === gl.RENDERBUFFER) {
+        const rb = gl.getFramebufferAttachmentParameter(
+          gl.DRAW_FRAMEBUFFER,
+          gl.COLOR_ATTACHMENT0,
+          gl.FRAMEBUFFER_ATTACHMENT_OBJECT_NAME,
+        ) as WebGLRenderbuffer | null;
+        if (!rb) return { width: null, height: null };
+        const prev = gl.getParameter(gl.RENDERBUFFER_BINDING) as WebGLRenderbuffer | null;
+        gl.bindRenderbuffer(gl.RENDERBUFFER, rb);
+        const width = gl.getRenderbufferParameter(gl.RENDERBUFFER, gl.RENDERBUFFER_WIDTH) as number;
+        const height = gl.getRenderbufferParameter(
+          gl.RENDERBUFFER,
+          gl.RENDERBUFFER_HEIGHT,
+        ) as number;
+        gl.bindRenderbuffer(gl.RENDERBUFFER, prev);
+        return { width, height };
+      }
+    } catch {
+      // Foreign/mock context or an attachment we can't introspect — degrade
+      // to unknown dimensions rather than throwing mid-capture.
+    }
+    return { width: null, height: null };
+  }
+
+  function currentTarget(): DrawTarget {
+    if (!currentFramebuffer) return { kind: 'canvas' };
+    let label = framebufferLabels.get(currentFramebuffer);
+    if (label === undefined) {
+      label = `framebuffer#${nextFramebufferId++}`;
+      framebufferLabels.set(currentFramebuffer, label);
+    }
+    const { width, height } = measureFramebufferSize();
+    return { kind: 'framebuffer', width, height, label };
+  }
+
+  function readCull(): 'front' | 'back' | 'none' {
+    if (!gl.getParameter(gl.CULL_FACE)) return 'none';
+    return gl.getParameter(gl.CULL_FACE_MODE) === gl.FRONT ? 'front' : 'back';
+  }
+
+  function recordDraw(
+    entryPoint: FrameCaptureEntryPoint,
+    mode: number,
+    count: number,
+    instanceCount: number | null,
+  ): void {
+    if (drawCalls.length >= maxDrawCalls) {
+      truncated++;
+      pendingAnnotation = null;
+      return;
+    }
+    const annotation = pendingAnnotation;
+    pendingAnnotation = null;
+    drawCalls.push({
+      index: drawCalls.length,
+      entryPoint,
+      mode: decodeMode(mode),
+      count,
+      instanceCount,
+      programLabel: labelForProgram(currentProgram),
+      target: currentTarget(),
+      viewport: [...currentViewport] as [number, number, number, number],
+      state: {
+        blend: Boolean(gl.getParameter(gl.BLEND)),
+        depthTest: Boolean(gl.getParameter(gl.DEPTH_TEST)),
+        depthWrite: Boolean(gl.getParameter(gl.DEPTH_WRITEMASK)),
+        cull: readCull(),
+        scissor: Boolean(gl.getParameter(gl.SCISSOR_TEST)),
+      },
+      annotation: annotation ?? null,
+    });
+  }
+
+  // Cast to an index signature to shadow methods without fighting the DOM lib
+  // types on every wrapped name.
+  const target = gl as unknown as Record<string, unknown>;
+
+  function patch(name: string, wrapper: (original: (...a: unknown[]) => unknown) => unknown): void {
+    const original = target[name] as (...a: unknown[]) => unknown;
+    originals.set(name, original);
+    if (Object.hasOwn(gl, name)) wasOwn.add(name);
+    target[name] = wrapper(original.bind(gl));
+  }
+
+  function restoreAll(): void {
+    for (const [name, original] of originals) {
+      if (wasOwn.has(name)) target[name] = original;
+      else delete target[name];
+    }
+    originals.clear();
+    wasOwn.clear();
+  }
+
+  function installPatches(): void {
+    // Seed shadow state from the live context so the first draw's viewport /
+    // framebuffer / program reflect reality even before any setter fires.
+    try {
+      const vp = gl.getParameter(gl.VIEWPORT) as ArrayLike<number> | null;
+      if (vp && vp.length >= 4) currentViewport = [vp[0]!, vp[1]!, vp[2]!, vp[3]!];
+      currentFramebuffer = gl.getParameter(gl.FRAMEBUFFER_BINDING) as WebGLFramebuffer | null;
+      currentProgram = gl.getParameter(gl.CURRENT_PROGRAM) as WebGLProgram | null;
+    } catch {
+      // Mock context without full getParameter coverage — start from defaults.
+    }
+
+    patch('useProgram', (original) => (program: unknown) => {
+      currentProgram = (program as WebGLProgram) ?? null;
+      return original(program);
+    });
+    patch('bindFramebuffer', (original) => (bindTarget: unknown, framebuffer: unknown) => {
+      // Track the DRAW framebuffer binding (FRAMEBUFFER and DRAW_FRAMEBUFFER
+      // both affect it; READ_FRAMEBUFFER does not).
+      if (bindTarget === gl.FRAMEBUFFER || bindTarget === gl.DRAW_FRAMEBUFFER) {
+        currentFramebuffer = (framebuffer as WebGLFramebuffer) ?? null;
+      }
+      return original(bindTarget, framebuffer);
+    });
+    patch('viewport', (original) => (x: unknown, y: unknown, w: unknown, h: unknown) => {
+      currentViewport = [x as number, y as number, w as number, h as number];
+      return original(x, y, w, h);
+    });
+
+    patch('drawArrays', (original) => (mode: unknown, first: unknown, count: unknown) => {
+      recordDraw('drawArrays', mode as number, count as number, null);
+      return original(mode, first, count);
+    });
+    patch(
+      'drawElements',
+      (original) => (mode: unknown, count: unknown, type: unknown, offset: unknown) => {
+        recordDraw('drawElements', mode as number, count as number, null);
+        return original(mode, count, type, offset);
+      },
+    );
+    patch(
+      'drawArraysInstanced',
+      (original) => (mode: unknown, first: unknown, count: unknown, instanceCount: unknown) => {
+        recordDraw('drawArraysInstanced', mode as number, count as number, instanceCount as number);
+        return original(mode, first, count, instanceCount);
+      },
+    );
+    patch(
+      'drawElementsInstanced',
+      (original) =>
+        (mode: unknown, count: unknown, type: unknown, offset: unknown, instanceCount: unknown) => {
+          recordDraw(
+            'drawElementsInstanced',
+            mode as number,
+            count as number,
+            instanceCount as number,
+          );
+          return original(mode, count, type, offset, instanceCount);
+        },
+    );
+    patch(
+      'drawRangeElements',
+      (original) =>
+        (
+          mode: unknown,
+          start: unknown,
+          end: unknown,
+          count: unknown,
+          type: unknown,
+          offset: unknown,
+        ) => {
+          recordDraw('drawRangeElements', mode as number, count as number, null);
+          return original(mode, start, end, count, type, offset);
+        },
+    );
+  }
+
+  return {
+    arm() {
+      armed = true;
+    },
+    get armed() {
+      return armed;
+    },
+    beginPass() {
+      if (!armed || patched) return;
+      patched = true;
+      drawCalls = [];
+      truncated = 0;
+      notes = [];
+      pendingAnnotation = null;
+      installPatches();
+    },
+    endPass(): FrameCapture | null {
+      if (!patched) {
+        armed = false;
+        return null;
+      }
+      try {
+        if (truncated > 0) {
+          notes.push(
+            `Draw list capped at ${maxDrawCalls}; ${truncated} later draw(s) were not recorded.`,
+          );
+        }
+        const unattributed = drawCalls.reduce((n, d) => n + (d.annotation === null ? 1 : 0), 0);
+        return {
+          id: ++captureId,
+          capturedAt: nowFn(),
+          drawCalls: drawCalls.slice(),
+          totals: { drawCalls: drawCalls.length, unattributed, truncated },
+          notes: notes.slice(),
+        };
+      } finally {
+        restoreAll();
+        patched = false;
+        armed = false;
+        pendingAnnotation = null;
+      }
+    },
+    annotateNextDraw(annotation: DrawAnnotation) {
+      pendingAnnotation = annotation;
+    },
+  };
+}

package/src/ecs/component-manager.ts

@@ -5,9 +5,10 @@ import type { PhysicsRefs, PhysicsRegistry } from '../physics/physics-registry';
 import { type AdapterSurface, isFirstPartyMounted, type WorldInstance } from '../runtime/game';
 import type { GameContext } from '../runtime/types';
 import type { Physics2DRefs, Physics2DRegistry } from '../world2d/physics2d-registry';
+import type { World2DContext } from '../world2d/types';
 import {
+  type AnyGameComponentClass,
   GameComponent,
-  type GameComponentClass,
   linkGameComponentHmrClasses,
   type NodeOf,
 } from './game-component';
@@ -24,6 +25,7 @@ import { logHmrSwapMiss } from './hmr-swap-report';
  */
 type AnyNode = NodeOf<AdapterSurface>;
 type AnyComponent = GameComponent<AdapterSurface>;
+type ComponentRuntimeContext = GameContext | World2DContext;
 
 /**
  * Optional identity a caller of `attach()` can supply for a component instance
@@ -68,10 +70,19 @@ export interface RegistryAttachInfo {
  * instance ends up with a defined, correct `world` by the time
  * `createGameRuntime`/`registerThreeWorld` returns.
  */
-function resolveWorldInstance(ctx: GameContext): WorldInstance | undefined {
+function resolveWorldInstance(
+  ctx: ComponentRuntimeContext,
+  self: unknown,
+): WorldInstance | undefined {
   if (!ctx.game) return undefined;
   for (const w of ctx.game.roots) {
     if (isFirstPartyMounted(w.mounted) && w.mounted.ctx === ctx) return w;
+    // A non-first-party world exposing ITS manager via the optional
+    // `MountedWorldBase.components` capability (e.g. `@engine/world3d-react`'s
+    // R3F mount) — matched by manager identity (`self` is the manager doing
+    // this attach), the same one-owner-per-world guarantee the ctx-identity
+    // probe above gives the first-party mount.
+    if (self !== undefined && w.mounted.components === self) return w;
   }
   return undefined;
 }
@@ -121,13 +132,20 @@ function describeNode(node: AnyNode): string {
  * just to satisfy this signature.
  */
 export function createComponentManager(
-  ctx: GameContext,
+  ctx: ComponentRuntimeContext,
   physics?: PhysicsRegistry,
   opts?: { kind?: AdapterSurface; physics2d?: Physics2DRegistry },
 ) {
   const kind: AdapterSurface = opts?.kind ?? 'threejs';
   const physics2d = opts?.physics2d;
 
+  // The manager object this factory returns — captured after construction so
+  // `performAttach` can hand `resolveWorldInstance` its own identity (the
+  // `MountedWorldBase.components` capability match; see that function's doc).
+  // Safe closure-over-a-later-assignment: `performAttach` only ever runs
+  // after the return below.
+  let selfManager: unknown;
+
   const byPhase = new Map<SystemPhaseName, AnyComponent[]>();
   const byEntity = new Map<AnyNode, AnyComponent[]>();
 
@@ -332,7 +350,7 @@ export function createComponentManager(
           } catch (err) {
             console.error(`[component-manager] ${inst.constructor.name}.update() threw:`, err);
           } finally {
-            ctx.game?.profiler.endComponent(inst.constructor.name);
+            ctx.game?.profiler.endComponent(inst.constructor.name, phase);
           }
         }
       } finally {
@@ -363,14 +381,14 @@ export function createComponentManager(
   function swapOneIfMatched(
     inst: AnyComponent,
     name: string,
-    NewClass: GameComponentClass,
+    NewClass: AnyGameComponentClass,
   ): boolean {
     const trackedKey = registryKeyOf.get(inst);
     const isMatch = trackedKey !== undefined ? trackedKey === name : inst.constructor.name === name;
     if (!isMatch) return false;
     const oldPhase = (inst.constructor as typeof GameComponent).phase ?? 'gameLogic';
     const newPhase = (NewClass as unknown as typeof GameComponent).phase ?? 'gameLogic';
-    linkGameComponentHmrClasses(inst.constructor as unknown as GameComponentClass, NewClass);
+    linkGameComponentHmrClasses(inst.constructor as unknown as AnyGameComponentClass, NewClass);
     Object.setPrototypeOf(inst, NewClass.prototype);
     migratePhase(inst, oldPhase, newPhase);
     reparseSchemaOnSwap(inst, NewClass, name);
@@ -412,7 +430,7 @@ export function createComponentManager(
    */
   function reparseSchemaOnSwap(
     inst: AnyComponent,
-    NewClass: GameComponentClass,
+    NewClass: AnyGameComponentClass,
     key: string,
   ): void {
     const schema = NewClass.schema;
@@ -476,7 +494,7 @@ export function createComponentManager(
 
   function performAttach(node: AnyNode, instance: AnyComponent, registry?: RegistryAttachInfo) {
     instance.node = node;
-    instance.world = resolveWorldInstance(ctx) as WorldInstance;
+    instance.world = resolveWorldInstance(ctx, selfManager) as WorldInstance;
     const refs = resolvePhysicsRefs(node);
     instance.rigidBody = refs?.body ?? null;
     instance.collider = refs?.collider ?? null;
@@ -533,7 +551,7 @@ export function createComponentManager(
     byEntity.delete(node);
   }
 
-  return {
+  const manager = {
     /** Attach a component instance to an entity node (Object3D in a threejs
      *  world, PIXI.Container in a pixijs world). Validates the attach rules
      *  (§3: react-world throw, kind-mismatch throw) synchronously before any
@@ -722,7 +740,11 @@ export function createComponentManager(
      * can sum it without re-deriving it from a side-channel.
      */
     // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the GameComponent-subclass guard (§7.1-5) and the warnOnMiss option are both load-bearing early-exit branches ahead of the existing match loop — splitting them into separate helpers would obscure that hotSwap has exactly one guarded entry point
-    hotSwap(name: string, NewClass: GameComponentClass, opts?: { warnOnMiss?: boolean }): number {
+    hotSwap(
+      name: string,
+      NewClass: AnyGameComponentClass,
+      opts?: { warnOnMiss?: boolean },
+    ): number {
       if (typeof NewClass !== 'function' || !(NewClass.prototype instanceof GameComponent)) {
         // biome-ignore lint/suspicious/noConsole: structured, greppable — mirrors logHmrSwapMiss's own deliberate direct console.warn
         console.warn(
@@ -734,6 +756,15 @@ export function createComponentManager(
         );
         return 0;
       }
+      if (kind === 'react' || (NewClass.declaredKind !== 'any' && NewClass.declaredKind !== kind)) {
+        // biome-ignore lint/suspicious/noConsole: same guarded, greppable HMR refusal as the subclass check above
+        console.warn(
+          `[component-manager] hotSwap("${name}"): refused — ` +
+            `"${NewClass.name}" declares kind "${NewClass.declaredKind}" but this manager owns ` +
+            `"${kind}" entities, so no live instance was touched.`,
+        );
+        return 0;
+      }
       let matched = 0;
       for (const [, instances] of byEntity) {
         for (const inst of instances) {
@@ -776,6 +807,8 @@ export function createComponentManager(
       detachedThisTick.clear();
     },
   };
+  selfManager = manager;
+  return manager;
 }
 
 export type ComponentManager = ReturnType<typeof createComponentManager>;

package/src/ecs/game-component.ts

@@ -6,6 +6,7 @@ import type { z } from 'zod';
 import type { SystemPhaseName } from '../core/types';
 import type { AdapterSurface, WorldInstance } from '../runtime/game';
 import type { GameContext } from '../runtime/types';
+import type { World2DContext } from '../world2d/types';
 
 /**
  * Map a {@link AdapterSurface} to its native world node type (T7.2, D8 —
@@ -33,6 +34,11 @@ export type ColliderOf<K extends AdapterSurface> = K extends 'threejs'
     ? RAPIER2D.Collider
     : never;
 
+/** Native lifecycle context for a component's declared surface. */
+export type ComponentContextOf<K extends AdapterSurface> = K extends 'pixijs'
+  ? World2DContext
+  : GameContext;
+
 /**
  * Base class for game components attached to entities.
  *
@@ -209,23 +215,46 @@ export abstract class GameComponent<K extends AdapterSurface = 'threejs'> {
   collider: ColliderOf<K> | null = null;
 
   /** Called once after the entity is fully constructed (node, physics, etc.). */
-  init?(ctx: GameContext): void | Promise<void>;
+  init?(ctx: ComponentContextOf<K>): void | Promise<void>;
 
   /** Called every fixed timestep. */
-  abstract update(dt: number, ctx: GameContext): void;
+  abstract update(dt: number, ctx: ComponentContextOf<K>): void;
 
   /** Called when the entity is destroyed or the component is removed. */
-  dispose?(ctx: GameContext): void;
+  dispose?(ctx: ComponentContextOf<K>): void;
 
   /** Called when a sensor overlap with `other` begins. */
-  onTriggerEnter?(other: NodeOf<K>, ctx: GameContext): void;
+  onTriggerEnter?(other: NodeOf<K>, ctx: ComponentContextOf<K>): void;
 
   /** Called when a sensor overlap with `other` ends. */
-  onTriggerExit?(other: NodeOf<K>, ctx: GameContext): void;
+  onTriggerExit?(other: NodeOf<K>, ctx: ComponentContextOf<K>): void;
 }
 
-/** Constructor type for GameComponent subclasses (carries static phase/schema). */
-export type GameComponentClass = (new () => GameComponent) & {
-  phase?: SystemPhaseName;
-  schema?: z.ZodObject<z.ZodRawShape>;
-};
+/** Constructor type for one surface's GameComponent subclasses. The default
+ * remains Three so existing scene registries stay surface-narrowed. */
+export type GameComponentClass<K extends AdapterSurface = 'threejs'> =
+  (new () => GameComponent<K>) & {
+    declaredKind: AdapterSurface | 'any';
+    phase?: SystemPhaseName;
+    schema?: z.ZodObject<z.ZodRawShape>;
+  };
+
+/** Cross-surface constructor contract for tooling such as HMR and script
+ * discovery. React contributes no class because React nodes cannot host
+ * GameComponents. Runtime attach still enforces each class's declaredKind. */
+export type AnyGameComponentClass = GameComponentClass<'threejs'> | GameComponentClass<'pixijs'>;
+
+export function gameComponentClassMatchesSurface(
+  component: AnyGameComponentClass,
+  surface: 'threejs',
+): component is GameComponentClass<'threejs'>;
+export function gameComponentClassMatchesSurface(
+  component: AnyGameComponentClass,
+  surface: 'pixijs',
+): component is GameComponentClass<'pixijs'>;
+export function gameComponentClassMatchesSurface(
+  component: AnyGameComponentClass,
+  surface: 'threejs' | 'pixijs',
+): boolean {
+  return component.declaredKind === surface || component.declaredKind === 'any';
+}