@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/data/vite-plugin-data.ts

@@ -0,0 +1,290 @@
+/**
+ * `vgaiDataCheck` — build-path validation for data assets and project tools
+ * (docs/DATA-TOOLS-DESIGN.md §6.7, the enforcement half of W5). A Vite plugin
+ * for the PROJECT's own `vite.config.ts` (the template wires it; the editor
+ * dev server boots Vite from the ENGINE's config and never runs this — its
+ * surface is covered by `vgai doctor` instead). Build-only (`apply: 'build'`):
+ * in dev, `defineData`'s parse-on-load already fails loud in the console.
+ *
+ * Three checks, all failing the build loud:
+ *
+ * 1. **Schema integrity** (`buildStart`): every registered asset's
+ *    `.data.json` is read fresh from disk and validated through
+ *    {@link parseDataJson} — the EXACT parse `defineData` runs at load (§9.1:
+ *    an emitted-JSON-Schema validator here could disagree with runtime; the
+ *    Zod schema itself never can). The schemas arrive EXECUTABLE because
+ *    `vite.config.ts` statically imports the project's data-asset registry
+ *    (`src/data/assets.ts` in the template) — Vite's config loader bundles
+ *    config-relative TS imports, which is what makes this the one build-side
+ *    place project Zod schemas can run.
+ * 2. **Ref integrity** (`buildStart`): every `file#key(.field)*` string in
+ *    every `src/data/*.data.json` (registered or not) must resolve — shared
+ *    definition with `vgai doctor` via {@link findDanglingDataRefs}, so the
+ *    two surfaces can never disagree about what "dangling" means. A second,
+ *    narrower ref check runs alongside it for REGISTERED assets only: any
+ *    field declared with `dataRef(target)` (`./data-ref.ts`) whose `target`
+ *    names no asset currently on disk fails loud too (§9.4's "renamed the
+ *    target file" hole, closed for declared refs — see
+ *    `collectDeclaredRefFields`/`findMissingRefTargets` in `data-check-core.ts`).
+ * 3. **Tools never ship** (`generateBundle`): no emitted chunk may contain a
+ *    module from `src/tools/` or a `*.tool.*` file (§4: tester serves and
+ *    standalone builds strip tools entirely; W4 made this true by
+ *    construction — nothing imports tools — and this check PINS it against
+ *    the day some game module imports a tool "just for a helper").
+ *
+ * Unregistered data files (a `.data.json` with no entry in the passed
+ * `assets` list) are a WARNING, not an error: they still get ref-integrity
+ * and runtime parse-on-load, but no build-time schema check — the warning
+ * names the registry file to fix.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import type { Plugin } from 'vite';
+import type { z } from 'zod';
+import { parseDataJson, toDataJsonSchema } from './data-asset';
+import {
+  collectDeclaredRefFields,
+  findDanglingDataRefs,
+  findMissingRefTargets,
+} from './data-check-core';
+
+/** One registered data asset: its executable Zod schema + the project-relative path of its `.data.json`. */
+export interface DataCheckAsset {
+  readonly schema: z.ZodType;
+  /** e.g. `'src/data/tuning.data.json'` — read fresh from disk at buildStart. */
+  readonly sourcePath: string;
+}
+
+export interface VgaiDataCheckOptions {
+  readonly assets: readonly DataCheckAsset[];
+  /** Project root the `sourcePath`s resolve against. Default: `process.cwd()` (vite build's cwd). */
+  readonly root?: string;
+}
+
+/** Recursively collect `*.data.json` under `dir` (absent dir → empty — a project with no data assets builds fine). */
+function findDataFiles(dir: string): string[] {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const out: string[] = [];
+  for (const entry of entries) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) out.push(...findDataFiles(full));
+    else if (entry.endsWith('.data.json')) out.push(full);
+  }
+  return out;
+}
+
+/** `src/data/tuning.data.json` → `tuning` (normalizing either slash direction). */
+function assetStem(sourcePath: string): string {
+  const rel = sourcePath.split('\\').join('/');
+  return (
+    rel
+      .split('/')
+      .pop()
+      ?.replace(/\.data\.json$/, '') ?? rel
+  );
+}
+
+/**
+ * Parse every data file in the project once — the registered subset gets
+ * schema validation, the whole set feeds ref integrity. Unparseable files
+ * become errors; unregistered files become warnings naming the registry.
+ *
+ * DUPLICATE-STEM GUARD: `findDataFiles` walks `src/data/` recursively, so two
+ * files in different subdirectories can share a stem (e.g.
+ * `src/data/enemies.data.json` and `src/data/legacy/enemies.data.json`) — the
+ * exact identity `file#key` refs AND the registry's `sourcePath` lookup both
+ * address by stem alone (§2.2). Without this guard `parsedByStem.set` would
+ * silently last-wins the collision, and check 1 below could validate a
+ * REGISTERED asset's schema against a totally unrelated file's JSON. Detected
+ * here (one error per colliding path, naming every path) and excluded from
+ * `parsedByStem` entirely — any resolution against a duplicate stem would be
+ * an arbitrary, possibly-wrong pick, so neither check 1 nor check 2 (ref
+ * integrity) resolves anything through it once it's flagged.
+ */
+interface ParsedDataFiles {
+  parsedByStem: Map<string, unknown>;
+  /** Stems the duplicate-stem guard already flagged — check 1 skips its own
+   *  redundant "not found on disk" for these (the duplicate-stem error
+   *  already explains why the stem has no single resolvable payload). */
+  ambiguousStems: Set<string>;
+}
+
+function parseAllDataFiles(
+  root: string,
+  registered: ReadonlySet<string>,
+  errors: string[],
+  warnings: string[],
+): ParsedDataFiles {
+  const parsedByStem = new Map<string, unknown>();
+  const pathsByStem = new Map<string, string[]>();
+  for (const abs of findDataFiles(join(root, 'src', 'data'))) {
+    const rel = relative(root, abs).split('\\').join('/');
+    const stem = assetStem(rel);
+    const paths = pathsByStem.get(stem);
+    if (paths) paths.push(rel);
+    else pathsByStem.set(stem, [rel]);
+
+    try {
+      parsedByStem.set(stem, JSON.parse(readFileSync(abs, 'utf-8')));
+    } catch (err) {
+      errors.push(
+        `"${rel}" is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      continue;
+    }
+    if (!registered.has(rel)) {
+      warnings.push(
+        `"${rel}" is not registered in the data-asset registry (src/data/assets.ts), so it gets ` +
+          'no build-time schema check (runtime parse-on-load still applies). Register it there — ' +
+          'the template ships the worked example.',
+      );
+    }
+  }
+
+  const ambiguousStems = new Set<string>();
+  for (const [stem, paths] of pathsByStem) {
+    if (paths.length < 2) continue;
+    ambiguousStems.add(stem);
+    errors.push(
+      `asset stem "${stem}" is claimed by ${paths.length} files (${paths.join(', ')}) — ` +
+        '"file#key" refs and the data-asset registry address a file by its stem alone (§2.2), so ' +
+        'this is an unresolvable identity collision. Rename one — asset stems must be unique ' +
+        'across the whole project, not just per directory.',
+    );
+    parsedByStem.delete(stem); // arbitrary otherwise — neither check below may resolve through it
+  }
+
+  return { parsedByStem, ambiguousStems };
+}
+
+/**
+ * The fs half of checks 1 + 2, extracted from the plugin hook so it is
+ * directly unit-testable against a fixture folder (no rollup context needed).
+ */
+export function collectDataCheckProblems(options: VgaiDataCheckOptions): {
+  errors: string[];
+  warnings: string[];
+} {
+  const root = options.root ?? process.cwd();
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const registered = new Set(options.assets.map((a) => a.sourcePath.split('\\').join('/')));
+  const { parsedByStem, ambiguousStems } = parseAllDataFiles(root, registered, errors, warnings);
+
+  // Check 1 — registered assets validate through the exact runtime parse.
+  for (const asset of options.assets) {
+    const rel = asset.sourcePath.split('\\').join('/');
+    if (!parsedByStem.has(assetStem(rel))) {
+      // An AMBIGUOUS stem already has its own duplicate-stem error above,
+      // which fully explains why there's no single payload to validate
+      // against — a second "not found on disk" here would just be
+      // confusing noise about a file that plainly IS on disk.
+      if (!ambiguousStems.has(assetStem(rel))) {
+        errors.push(
+          `registered data asset "${rel}" was not found on disk — fix the path in the registry ` +
+            '(src/data/assets.ts) or restore the file.',
+        );
+      }
+      continue;
+    }
+    try {
+      parseDataJson(asset.schema, parsedByStem.get(assetStem(rel)), rel);
+    } catch (err) {
+      errors.push(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  // Check 2 — no dangling refs anywhere.
+  for (const dangling of findDanglingDataRefs(parsedByStem)) {
+    errors.push(
+      `dangling data ref in "src/data/${dangling.inAsset}.data.json" at ${dangling.atPath}: ` +
+        `"${dangling.ref}" — "${dangling.missingSegment}" does not exist in ` +
+        `src/data/${dangling.targetAsset}.data.json. Fix the key or remove the ref ` +
+        '(refs are "file#key" strings — docs/DATA-TOOLS-DESIGN.md §2.2).',
+    );
+  }
+
+  // Check 2b — every declared `dataRef(target)` field (registered assets
+  // only, same set check 1 already validates) must name a target that's
+  // actually on disk — the §9.4 fix: this fires even if NO current value
+  // happens to look like a ref, unlike check 2 above (see
+  // `data-check-core.ts`'s module doc).
+  const assetNames = new Set(parsedByStem.keys());
+  for (const asset of options.assets) {
+    const rel = asset.sourcePath.split('\\').join('/');
+    const declared = collectDeclaredRefFields(toDataJsonSchema(asset.schema));
+    for (const missing of findMissingRefTargets(declared, assetNames)) {
+      errors.push(
+        `"${rel}" declares field "${missing.fieldPath}" as dataRef('${missing.targetStem}'), but ` +
+          `no "src/data/${missing.targetStem}.data.json" exists. Restore/rename the target file, ` +
+          `or update the dataRef('${missing.targetStem}') call in the schema.`,
+      );
+    }
+  }
+
+  return { errors, warnings };
+}
+
+/** True iff a bundled module id is tool code that must never ship (§4). Pure, unit-tested. */
+export function isToolModuleId(id: string): boolean {
+  const normalized = id.split('\\').join('/');
+  return /\/src\/tools\//.test(normalized) || /\.tool\.[tj]sx?(\?|$)/.test(normalized);
+}
+
+/**
+ * Build-path validation plugin — see the module doc. Wire it in the project's
+ * `vite.config.ts`, passing the data-asset registry:
+ *
+ * ```ts
+ * import { vgaiDataCheck } from '@vgai/engine/data/vite-plugin-data';
+ * import { dataAssets } from './src/data/assets';
+ * export default defineConfig({
+ *   plugins: [vgaiDataCheck({
+ *     root: __dirname,
+ *     assets: dataAssets.map((a) => ({ schema: a.schema, sourcePath: `src/data/${a.name}.data.json` })),
+ *   })],
+ * });
+ * ```
+ */
+export function vgaiDataCheck(options: VgaiDataCheckOptions): Plugin {
+  return {
+    name: 'vgai:data-check',
+    apply: 'build',
+    buildStart() {
+      const { errors, warnings } = collectDataCheckProblems(options);
+      for (const warning of warnings) this.warn(warning);
+      if (errors.length > 0) {
+        // ONE error carrying every problem — fail loud with the full picture,
+        // not a fix-one-rebuild-see-the-next loop.
+        this.error(
+          `data-asset validation failed (${errors.length} problem${errors.length === 1 ? '' : 's'} ` +
+            `— docs/DATA-TOOLS-DESIGN.md §6.7):\n${errors.map((e) => `  - ${e}`).join('\n')}`,
+        );
+      }
+    },
+    generateBundle(_outputOptions, bundle) {
+      const leaked = new Set<string>();
+      for (const output of Object.values(bundle)) {
+        if (output.type !== 'chunk') continue;
+        for (const id of Object.keys(output.modules)) {
+          if (isToolModuleId(id)) leaked.add(id.split('\\').join('/'));
+        }
+      }
+      if (leaked.size > 0) {
+        this.error(
+          'project tool code reached the game build — tools are editor-only and must never ship ' +
+            'to players (docs/DATA-TOOLS-DESIGN.md §4). Remove every game-code import of these ' +
+            `modules (tools may import game code, never the reverse):\n${[...leaked]
+              .map((id) => `  - ${id}`)
+              .join('\n')}`,
+        );
+      }
+    },
+  };
+}

package/src/dev/performance-profiler.ts

@@ -0,0 +1,213 @@
+export interface PerformanceTiming {
+  readonly name: string;
+  readonly ms: number;
+}
+
+export interface PerformanceFrame {
+  readonly id: number;
+  readonly timestamp: number;
+  readonly intervalMs: number;
+  readonly cpuMs: number;
+  readonly phases: readonly PerformanceTiming[];
+}
+
+export interface PerformanceSnapshot {
+  readonly enabled: boolean;
+  readonly recording: boolean;
+  readonly fps: number;
+  readonly cpuMs: number;
+  readonly p95Ms: number;
+  readonly p99Ms: number;
+  readonly frames: readonly PerformanceFrame[];
+  readonly phases: readonly PerformanceTiming[];
+  readonly systems: readonly PerformanceTiming[];
+  readonly components: readonly PerformanceTiming[];
+  readonly render: {
+    readonly gpuMs: number | null;
+    readonly drawCalls: number;
+    readonly triangles: number;
+    readonly geometries: number;
+    readonly textures: number;
+  };
+}
+
+const now = () => globalThis.performance?.now() ?? Date.now();
+
+function percentile(values: readonly number[], fraction: number): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.floor((sorted.length - 1) * fraction))] ?? 0;
+}
+
+/** Game-owned, bounded external store for browser-native performance diagnostics. */
+export function createPerformanceProfiler(initiallyEnabled = false) {
+  const listeners = new Set<() => void>();
+  const frames: PerformanceFrame[] = [];
+  const currentPhases = new Map<string, number>();
+  const currentSystems = new Map<string, number>();
+  const currentComponents = new Map<string, number>();
+  let enabled = initiallyEnabled;
+  let recording = false;
+  let frameId = 0;
+  let frameStart = 0;
+  let lastFrameStart = 0;
+  let phaseStart = 0;
+  let systemStart = 0;
+  let componentStart = 0;
+  let render = {
+    gpuMs: null as number | null,
+    drawCalls: 0,
+    triangles: 0,
+    geometries: 0,
+    textures: 0,
+  };
+  let snapshot: PerformanceSnapshot = {
+    enabled,
+    recording,
+    fps: 0,
+    cpuMs: 0,
+    p95Ms: 0,
+    p99Ms: 0,
+    frames,
+    phases: [],
+    systems: [],
+    components: [],
+    render,
+  };
+
+  function publish(): void {
+    const latest = frames.at(-1);
+    const intervals = frames.map((frame) => frame.intervalMs).filter((value) => value > 0);
+    snapshot = {
+      enabled,
+      recording,
+      fps: latest?.intervalMs ? 1000 / latest.intervalMs : 0,
+      cpuMs: latest?.cpuMs ?? 0,
+      p95Ms: percentile(intervals, 0.95),
+      p99Ms: percentile(intervals, 0.99),
+      frames,
+      phases: latest?.phases ?? [],
+      systems: [...currentSystems].map(([name, ms]) => ({ name, ms })).sort((a, b) => b.ms - a.ms),
+      components: [...currentComponents]
+        .map(([name, ms]) => ({ name, ms }))
+        .sort((a, b) => b.ms - a.ms),
+      render,
+    };
+    for (const listener of listeners) listener();
+  }
+
+  return {
+    get enabled() {
+      return enabled;
+    },
+    set enabled(value: boolean) {
+      if (enabled === value) return;
+      enabled = value;
+      publish();
+    },
+    get recording() {
+      return recording;
+    },
+    startRecording() {
+      enabled = true;
+      recording = true;
+      frames.length = 0;
+      publish();
+    },
+    stopRecording() {
+      recording = false;
+      publish();
+    },
+    clear() {
+      frames.length = 0;
+      publish();
+    },
+    beginFrame() {
+      if (!enabled) return;
+      currentPhases.clear();
+      currentSystems.clear();
+      currentComponents.clear();
+      render = { gpuMs: null, drawCalls: 0, triangles: 0, geometries: 0, textures: 0 };
+      frameStart = now();
+    },
+    beginPhase() {
+      if (!enabled) return;
+      phaseStart = now();
+    },
+    endPhase(name: string) {
+      if (!enabled) return;
+      const elapsed = now() - phaseStart;
+      currentPhases.set(name, (currentPhases.get(name) ?? 0) + elapsed);
+      if (recording)
+        performance.measure(`vgai.phase.${name}`, { start: phaseStart, duration: elapsed });
+    },
+    systemObserver: {
+      beginSystem() {
+        if (!enabled) return;
+        systemStart = now();
+      },
+      endSystem(scope: string, phase: string, name: string) {
+        if (!enabled) return;
+        const end = now();
+        const key = `${scope} / ${phase} / ${name}`;
+        currentSystems.set(key, (currentSystems.get(key) ?? 0) + end - systemStart);
+      },
+    },
+    beginComponent() {
+      if (!recording) return;
+      componentStart = now();
+    },
+    endComponent(name: string) {
+      if (!recording) return;
+      currentComponents.set(name, (currentComponents.get(name) ?? 0) + now() - componentStart);
+    },
+    reportRender(stats: {
+      gpuMs: number | null;
+      drawCalls: number;
+      triangles: number;
+      geometries: number;
+      textures: number;
+    }) {
+      if (!enabled) return;
+      render = {
+        gpuMs: stats.gpuMs ?? render.gpuMs,
+        drawCalls: render.drawCalls + stats.drawCalls,
+        triangles: render.triangles + stats.triangles,
+        geometries: render.geometries + stats.geometries,
+        textures: render.textures + stats.textures,
+      };
+    },
+    endFrame() {
+      if (!enabled) return;
+      const timestamp = now();
+      const intervalMs = lastFrameStart === 0 ? 0 : frameStart - lastFrameStart;
+      lastFrameStart = frameStart;
+      const frame: PerformanceFrame = {
+        id: ++frameId,
+        timestamp,
+        intervalMs,
+        cpuMs: timestamp - frameStart,
+        phases: [...currentPhases].map(([name, ms]) => ({ name, ms })).sort((a, b) => b.ms - a.ms),
+      };
+      frames.push(frame);
+      if (frames.length > 600) frames.splice(0, frames.length - 600);
+      if (recording)
+        performance.measure('vgai.frame', { start: frameStart, duration: frame.cpuMs });
+      publish();
+    },
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+    exportJSON() {
+      return JSON.stringify({ version: 1, capturedAt: new Date().toISOString(), frames }, null, 2);
+    },
+  };
+}
+
+export type PerformanceProfiler = ReturnType<typeof createPerformanceProfiler>;

package/src/dev/webgl-gpu-timer.ts

@@ -0,0 +1,53 @@
+interface DisjointTimerQueryExtension {
+  readonly TIME_ELAPSED_EXT: number;
+  readonly GPU_DISJOINT_EXT: number;
+}
+
+/** Non-blocking WebGL2 timer query; results are consumed on later frames. */
+export function createWebGLGpuTimer(context: WebGLRenderingContext | WebGL2RenderingContext) {
+  const gl = context as WebGL2RenderingContext;
+  const extension = gl.getExtension(
+    'EXT_disjoint_timer_query_webgl2',
+  ) as DisjointTimerQueryExtension | null;
+  const supported = extension !== null && typeof gl.createQuery === 'function';
+  const pending: WebGLQuery[] = [];
+  let active: WebGLQuery | null = null;
+  let latestMs: number | null = null;
+
+  return {
+    begin() {
+      if (!supported || active) return;
+      active = gl.createQuery();
+      if (active) gl.beginQuery(extension!.TIME_ELAPSED_EXT, active);
+    },
+    end() {
+      if (!supported || !active) return;
+      gl.endQuery(extension!.TIME_ELAPSED_EXT);
+      pending.push(active);
+      active = null;
+    },
+    poll(): number | null {
+      if (!supported) return null;
+      if (gl.getParameter(extension!.GPU_DISJOINT_EXT)) {
+        for (const query of pending.splice(0)) gl.deleteQuery(query);
+        return null;
+      }
+      while (pending.length > 0) {
+        const query = pending[0]!;
+        if (!gl.getQueryParameter(query, gl.QUERY_RESULT_AVAILABLE)) break;
+        pending.shift();
+        latestMs = (gl.getQueryParameter(query, gl.QUERY_RESULT) as number) / 1_000_000;
+        gl.deleteQuery(query);
+      }
+      return latestMs;
+    },
+    dispose() {
+      if (active) {
+        gl.endQuery(extension!.TIME_ELAPSED_EXT);
+        gl.deleteQuery(active);
+        active = null;
+      }
+      for (const query of pending.splice(0)) gl.deleteQuery(query);
+    },
+  };
+}

package/src/ecs/component-manager.ts

@@ -2,23 +2,28 @@ import type * as PIXI from 'pixi.js';
 import type * as THREE from 'three';
 import { PHASE_ORDER, type SystemPhaseName } from '../core/types';
 import type { PhysicsRefs, PhysicsRegistry } from '../physics/physics-registry';
-import { isFirstPartyMounted, type WorldInstance, type WorldKind } from '../runtime/game';
+import { type AdapterSurface, isFirstPartyMounted, type WorldInstance } from '../runtime/game';
 import type { GameContext } from '../runtime/types';
 import type { Physics2DRefs, Physics2DRegistry } from '../world2d/physics2d-registry';
-import { GameComponent, type GameComponentClass, type NodeOf } from './game-component';
+import {
+  GameComponent,
+  type GameComponentClass,
+  linkGameComponentHmrClasses,
+  type NodeOf,
+} from './game-component';
 import { logHmrSwapMiss } from './hmr-swap-report';
 
 /**
- * The manager's node/instance types, widened over every `WorldKind` (T7.2
- * slice 2, D8 §3). `NodeOf<WorldKind>` distributes to `THREE.Object3D |
+ * The manager's node/instance types, widened over every `AdapterSurface` (T7.2
+ * slice 2, D8 §3). `NodeOf<AdapterSurface>` distributes to `THREE.Object3D |
  * PIXI.Container` (react contributes `never`, which drops out of the
  * union) — this is what lets a single manager instance be constructed for
  * ANY one kind (threejs, pixijs, or react) while still type-checking
  * `attach()` calls made with a default-kind (`GameComponent`, K =
  * 'threejs') instance, unmodified, from every existing call site.
  */
-type AnyNode = NodeOf<WorldKind>;
-type AnyComponent = GameComponent<WorldKind>;
+type AnyNode = NodeOf<AdapterSurface>;
+type AnyComponent = GameComponent<AdapterSurface>;
 
 /**
  * Optional identity a caller of `attach()` can supply for a component instance
@@ -42,10 +47,10 @@ export interface RegistryAttachInfo {
  * ctx` identity (the same probe `isFirstPartyMounted` narrows for) rather
  * than by id, so it works unmodified whether this manager belongs to the
  * default world or a second/third registered world (`test/
- * game-two-worlds.test.ts`).
+ * game-two-roots.test.ts`).
  *
  * WORLD-WIRING STATE (T7.2 slice 2 — was a KNOWN GAP in slice 1, now closed
- * two ways): `ctx.game`/`ctx.worlds` exist from the start of `mount()`, but
+ * two ways): `ctx.game`/`ctx.roots` exist from the start of `mount()`, but
  * the `WorldInstance` itself is constructed by `registerThreeWorld` in
  * `create-runtime.ts` only AFTER `mount()` returns — i.e. AFTER
  * scene-authored components have already been attached by the scene loader
@@ -65,7 +70,7 @@ export interface RegistryAttachInfo {
  */
 function resolveWorldInstance(ctx: GameContext): WorldInstance | undefined {
   if (!ctx.game) return undefined;
-  for (const w of ctx.game.worlds) {
+  for (const w of ctx.game.roots) {
     if (isFirstPartyMounted(w.mounted) && w.mounted.ctx === ctx) return w;
   }
   return undefined;
@@ -98,7 +103,7 @@ function describeNode(node: AnyNode): string {
  * `test/system-runs-before-component-tick.test.ts`).
  *
  * Kind (T7.2 slice 2, D8 §3): a manager is constructed for exactly ONE
- * `WorldKind` (`opts.kind`, default `'threejs'` — every existing call site
+ * `AdapterSurface` (`opts.kind`, default `'threejs'` — every existing call site
  * omits it and gets the same manager slice 1 built). `attach()` enforces two
  * rules against that kind, loudly:
  *  - a `'react'`-kind manager throws on EVERY attach (react entities host no
@@ -118,9 +123,9 @@ function describeNode(node: AnyNode): string {
 export function createComponentManager(
   ctx: GameContext,
   physics?: PhysicsRegistry,
-  opts?: { kind?: WorldKind; physics2d?: Physics2DRegistry },
+  opts?: { kind?: AdapterSurface; physics2d?: Physics2DRegistry },
 ) {
-  const kind: WorldKind = opts?.kind ?? 'threejs';
+  const kind: AdapterSurface = opts?.kind ?? 'threejs';
   const physics2d = opts?.physics2d;
 
   const byPhase = new Map<SystemPhaseName, AnyComponent[]>();
@@ -322,9 +327,12 @@ export function createComponentManager(
           // flushed). Failures are loud — logged with the component name —
           // never swallowed silently.
           try {
+            ctx.game?.profiler.beginComponent();
             inst.update(dt, ctx);
           } catch (err) {
             console.error(`[component-manager] ${inst.constructor.name}.update() threw:`, err);
+          } finally {
+            ctx.game?.profiler.endComponent(inst.constructor.name);
           }
         }
       } finally {
@@ -362,6 +370,7 @@ export function createComponentManager(
     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);
     Object.setPrototypeOf(inst, NewClass.prototype);
     migratePhase(inst, oldPhase, newPhase);
     reparseSchemaOnSwap(inst, NewClass, name);
@@ -601,6 +610,30 @@ export function createComponentManager(
       return byEntity.get(node) ?? [];
     },
 
+    /**
+     * Get the first attached instance of a given component class on an
+     * entity node — the typed single-component sibling of `getComponents`
+     * (issue #99: `onTriggerEnter`'s `other` is a raw node; this is how a
+     * handler asks "does my trigger partner have a `Collectible` (or
+     * whatever marker) component?" instead of an untyped `getComponents`
+     * walk or a fragile `other.name === '...'` display-name check).
+     * Matches via `instanceof`, so a subclass of `cls` is returned too
+     * (same subclass handling as `queryByComponent`). Same ordering as
+     * `getComponents` (attach order for that node) and, like
+     * `getComponents`, does NOT exclude instances pending-detach this tick
+     * — a caller inside a phase tick that cares should filter itself, same
+     * as any other `getComponents` consumer. `undefined` if the node has no
+     * attached instance of `cls`.
+     */
+    getComponent<T extends AnyComponent>(node: AnyNode, cls: new () => T): T | undefined {
+      const instances = byEntity.get(node);
+      if (!instances) return undefined;
+      for (const inst of instances) {
+        if (inst instanceof cls) return inst;
+      }
+      return undefined;
+    },
+
     /**
      * Query all live attached instances of a given component class within
      * THIS manager — the per-world half of the §5 cross-world query