@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/module-mode.ts

@@ -11,18 +11,18 @@
  * override (`setActiveAuthoring`).
  *
  * FINDING (report prominently — see this slice's "Report back"): this is a
- * gap `play-mode.ts`'s existing `resolveWorldAdapter` call (its single-world
+ * gap `play-mode.ts`'s existing `resolveRootAdapter` call (its single-world
  * Play branch) does NOT close. That branch always calls
  * `installPlayAuthoring(store)`, which drives the hierarchy/inspector from
  * `getActiveAuthoring(store)` — i.e. the FIRST-PARTY `.vscn`-over-`store`
  * adapter — never from `session.mounted.authoring`. That's the right choice
- * for `default-three`/`default-pixi`/`default-react` worlds (their mounted
+ * for `default-three`/`default-pixi`/`default-react` roots (their mounted
  * scene mirrors the store's OWN document), but it is WRONG for a `{ module }`
  * world: a custom adapter builds its scene from its own code, so driving the
  * inspector from the store's `.vscn` document would show an unrelated (empty,
  * for a fresh CLI-on-folder project) tree instead of the module's real
  * objects. `play-mode.ts` is out of scope for this slice (sibling agent's
- * region), so rather than leave `{ module }` worlds unreachable through the
+ * region), so rather than leave `{ module }` roots unreachable through the
  * real editor UI at all, this file gives them their OWN auto-mount route —
  * mirroring ingest mode's already-established shape (auto-mount on load,
  * install the mounted adapter as the override, swap the viewport onto the
@@ -56,17 +56,17 @@
  * world for every kind (its `'module'` switch case is kind-agnostic) and
  * ALREADY hands it back as the correctly-kinded `WorldMountSpec` — so the fix
  * is routing, not an engine change: mirror `ingest-mode.ts`'s
- * `enterIngestModeReact` recipe (one-element `resolveAllWorlds` + worlds-path
- * `createGameRuntime({ container, worlds })`) instead of the legacy single-
+ * `enterIngestModeReact` recipe (one-element `resolveAllWorlds` + roots-path
+ * `createGameRuntime({ container, roots })`) instead of the legacy single-
  * adapter path. `tryManifestModuleRoute` below picks between the two based on
- * `firstWorld.kind` — threejs module worlds keep calling
+ * `firstWorld.surface` — threejs module roots keep calling
  * `enterModuleModeFromManifestWorld` byte-for-byte; the D-X6 guard stays
  * reachable (and its own tests unmodified) for any caller that still invokes
  * that function directly with a non-three world.
  */
 
 import type { AuthoringAdapter } from '@engine/adapter';
-import type { ResolvedGameManifest, ResolvedWorldEntry } from '@engine/manifest/load';
+import type { ResolvedAdapterRoot, ResolvedGameManifest } from '@engine/manifest/load';
 import type { GameSession, WorldMountSpec } from '@engine/runtime/create-runtime';
 import { setUserData } from '@engine/scene/user-data';
 import type * as THREE from 'three';
@@ -76,7 +76,7 @@ import {
   formatTierShortfallMessage,
   type TierShortfallReport,
 } from './achieved-tier';
-import { resolveAllWorlds, resolveWorldAdapter } from './adapter-resolver';
+import { resolveAllWorlds, resolveRootAdapter } from './adapter-resolver';
 import { setActiveAuthoring } from './authoring/active-adapter';
 import { setActiveSystems } from './authoring/active-systems';
 import { makeEmbedOnlyAdapter } from './authoring/embed-only-adapter';
@@ -92,12 +92,6 @@ import { getCurrentProject } from './project-manager';
 interface ModuleSession {
   store: EditorStore;
   stop: () => void;
-  /** Absent on the worlds-path route (D-Y1 below) — that route owns no
-   *  standalone canvas of its own; `createGameRuntime`'s worlds-path session
-   *  builds and tears down its own per-world surface(s) directly inside the
-   *  game container. Present (and removed on exit) only for the legacy
-   *  threejs single-adapter path's own hand-created canvas. */
-  canvas?: HTMLCanvasElement | undefined;
 }
 
 let _session: ModuleSession | null = null;
@@ -152,14 +146,14 @@ export function withStoreSelection(
  * .local` (always resolved/explicit for a module world — the loader requires
  * it, `manifest/load.ts`'s `resolveCapabilities`) is the declared tier; the
  * ACTUAL achieved tier is recomputed here (in addition to
- * `resolveWorldAdapter`'s own internal, warn-only check, T3.4 slice 1) purely
+ * `resolveRootAdapter`'s own internal, warn-only check, T3.4 slice 1) purely
  * to expose the structured values on the `__vgaiModule` dev/e2e hook below —
  * this does not log a second shortfall line, it only reads the same pure
  * computation slice 1 already logs from inside the resolver.
  */
 export async function enterModuleModeFromManifestWorld(
   store: EditorStore,
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   projectRoot: string,
 ): Promise<void> {
   const gameContainer = getGameContainer();
@@ -171,24 +165,26 @@ export async function enterModuleModeFromManifestWorld(
   store.setPlayState('playing');
   editorConsole.log(`Mounting custom adapter module for world "${world.id}"`, 'adapter');
 
-  // `resolveWorldAdapter`'s `module` branch (T3.4 slice 1) already: path-guards
+  // `resolveRootAdapter`'s `module` branch (T3.4 slice 1) already: path-guards
   // + shape-checks the module, then wraps its `mount` with the achieved-tier
   // warn-only check (`withAchievedTierCheck`) — reused verbatim here, not
   // duplicated.
-  const adapter = await resolveWorldAdapter(world, projectRoot);
+  const adapter = await resolveRootAdapter(world, projectRoot);
 
-  const canvas = document.createElement('canvas');
-  canvas.style.cssText = 'width:100%;height:100%;display:block;';
-  gameContainer.appendChild(canvas);
   const w = gameContainer.clientWidth || 800;
   const h = gameContainer.clientHeight || 600;
 
   const { createGameRuntime } = await import('@engine/runtime/create-runtime');
-  const session = await createGameRuntime({ canvas, width: w, height: h, adapter });
+  const session = await createGameRuntime({
+    container: gameContainer,
+    width: w,
+    height: h,
+    roots: [{ id: world.id, kind: 'threejs', adapter }],
+  });
   const mounted = session.mounted;
 
   // D-X6 honesty guard (docs/EXTERNAL-FOLDER-INGEST-DESIGN.md §2/§6 slice S4):
-  // this route only wires up THREE.Scene-shaped worlds — everything below
+  // this route only wires up THREE.Scene-shaped roots — everything below
   // (`tagObjectsWithEntityIds`, `store.enterPlayScene`) assumes `mounted.scene`
   // exists. A pixi/react `{ module }` world's mounted result has NO `.scene`
   // at all (`MountedPixiWorld`/`MountedReactWorld`, `@engine/adapter` —
@@ -197,19 +193,19 @@ export async function enterModuleModeFromManifestWorld(
   // `undefined` into `enterPlayScene` — exactly the silent dead end D-X6
   // replaces with a loud, named error (anti-shim / degrade-loudly). Trust
   // the mounted result's OWN self-declared `kind` tag over the manifest's
-  // `world.kind` — it is what the module ACTUALLY returned; an absent `kind`
+  // `world.surface` — it is what the module ACTUALLY returned; an absent `kind`
   // (a pre-T7.5 module adapter that never had to declare one) is treated as
   // the historical threejs-only default, so existing module fixtures are
   // unaffected.
   const mountedKind = (mounted as unknown as { kind?: string }).kind;
   if (mountedKind !== undefined && mountedKind !== 'threejs') {
-    canvas.remove();
+    session.stop();
     store.setPlayState('stopped');
     throw new Error(
       `enterModuleModeFromManifestWorld: world "${world.id}" (kind: "${mountedKind}") is a ` +
         '{ module } adapter whose mounted result is not a threejs world — v1 module-mount ' +
-        'route only wires up THREE.Scene-shaped worlds into enterPlayScene ' +
-        '(docs/EXTERNAL-FOLDER-INGEST-DESIGN.md D-X6). Pixi/react { module } worlds have no ' +
+        'route only wires up THREE.Scene-shaped roots into enterPlayScene ' +
+        '(docs/EXTERNAL-FOLDER-INGEST-DESIGN.md D-X6). Pixi/react { module } roots have no ' +
         'mount plumbing yet — kind-parameterized HostContext + per-kind module mounting is ' +
         'wave 2, gated on its own design doc. This throws loudly instead of silently passing ' +
         '`undefined` into enterPlayScene.',
@@ -218,7 +214,6 @@ export async function enterModuleModeFromManifestWorld(
 
   _session = {
     store,
-    canvas,
     stop: () => session.stop(),
   };
 
@@ -246,7 +241,7 @@ export async function enterModuleModeFromManifestWorld(
     world.capabilities.local,
     achievedTier,
   );
-  // Belt-and-suspenders: resolveWorldAdapter's own wrapping already warned once
+  // Belt-and-suspenders: resolveRootAdapter's own wrapping already warned once
   // via editorConsole (slice 1) — this does not warn again, only formats the
   // SAME message onto the structured dev/e2e hook below for assertions.
   if (shortfall) {
@@ -291,14 +286,13 @@ export function exitModuleMode(): void {
   } catch {
     /* ignore */
   }
-  s.canvas?.remove();
   delete (window as unknown as Record<string, unknown>)['__vgaiModule'];
   editorConsole.log('Module adapter mode stopped', 'adapter');
 }
 
 // ---------------------------------------------------------------------------
 // D-Y1 (docs/EXTERNAL-REACT-AND-MODULE-DESIGN.md §1/§4 slice S1) —
-// worlds-path routing for non-three `{ module }` worlds
+// roots-path routing for non-three `{ module }` roots
 // ---------------------------------------------------------------------------
 
 /**
@@ -306,7 +300,7 @@ export function exitModuleMode(): void {
  * world through the WORLDS PATH — the D-Y1 sibling of
  * `enterModuleModeFromManifestWorld` above, mirroring `ingest-mode.ts`'s
  * `enterIngestModeReact` recipe exactly: one-element `resolveAllWorlds` +
- * worlds-path `createGameRuntime({ container, worlds })`, which hands the
+ * roots-path `createGameRuntime({ container, roots })`, which hands the
  * module adapter its own native `World2DHost`/`ReactWorldHost` — no
  * `HostContext`, no `.scene` assumption, no engine-side change needed (the
  * wave-2 study's §0 finding: `resolveAllWorlds`'s `'module'` case is already
@@ -314,13 +308,13 @@ export function exitModuleMode(): void {
  *
  * Only THIS one world mounts (mirrors the legacy path's own "only ever the
  * first world" behavior, `tryManifestModuleRoute` below): `manifest`'s other
- * worlds (if any) are discarded via the one-element `{ ...manifest, worlds:
+ * roots (if any) are discarded via the one-element `{ ...manifest, roots:
  * [world] }` passed to `resolveAllWorlds` — a real multi-world manifest whose
  * FIRST world is a non-three module adapter is out of scope here exactly as
  * it always was for the legacy route.
  *
  * `withAchievedTierCheck` (already wrapped inside `resolveModuleAdapter`,
- * reached identically through `resolveAllWorlds` -> `resolveWorldAdapter` ->
+ * reached identically through `resolveAllWorlds` -> `resolveRootAdapter` ->
  * the `'module'` case) runs completely unmodified here — an over-claiming
  * module world still gets its shortfall logged loudly by the resolver itself;
  * this function neither bypasses nor re-derives that check, only reads the
@@ -342,8 +336,8 @@ export function exitModuleMode(): void {
  * not scene-adoption-keyed) — exactly like `enterIngestModeReact`.
  */
 /**
- * Mount a single `{ module }` world (any kind) through the SCOPED worlds-path
- * recipe — a one-element `resolveAllWorlds` + worlds-path `createGameRuntime`
+ * Mount a single `{ module }` world (any kind) through the SCOPED roots-path
+ * recipe — a one-element `resolveAllWorlds` + roots-path `createGameRuntime`
  * — with NO global side effects of its own (no `setActiveAuthoring`, no
  * `store`/viewport writes, no dev hooks). Extracted (D-V4,
  * docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md) so BOTH this file's own
@@ -356,22 +350,22 @@ export function exitModuleMode(): void {
  */
 export async function mountModuleWorldRuntime(
   manifest: ResolvedGameManifest,
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   projectRoot: string,
   container: HTMLElement,
   width: number,
   height: number,
 ): Promise<{ session: GameSession; specs: WorldMountSpec[] }> {
   const { createGameRuntime } = await import('@engine/runtime/create-runtime');
-  const specs = await resolveAllWorlds({ ...manifest, worlds: [world] }, projectRoot);
-  const session = await createGameRuntime({ container, worlds: specs, width, height });
+  const specs = await resolveAllWorlds({ ...manifest, roots: [world] }, projectRoot);
+  const session = await createGameRuntime({ container, roots: specs, width, height });
   return { session, specs };
 }
 
 export async function enterModuleModeWorldsPath(
   store: EditorStore,
   manifest: ResolvedGameManifest,
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   projectRoot: string,
 ): Promise<void> {
   const gameContainer = getGameContainer();
@@ -382,7 +376,7 @@ export async function enterModuleModeWorldsPath(
 
   store.setPlayState('playing');
   editorConsole.log(
-    `Mounting custom adapter module for world "${world.id}" (kind: ${world.kind}, worlds path)`,
+    `Mounting custom adapter module for world "${world.id}" (kind: ${world.surface}, roots path)`,
     'adapter',
   );
 
@@ -397,7 +391,7 @@ export async function enterModuleModeWorldsPath(
     h,
   );
 
-  const worldInstance = session.game.worlds[0]!;
+  const worldInstance = session.game.roots[0]!;
   const mounted = worldInstance.mounted;
   const adapterId = specs[0]!.adapter.id;
 
@@ -423,7 +417,7 @@ export async function enterModuleModeWorldsPath(
     world.capabilities.local,
     achievedTier,
   );
-  // Belt-and-suspenders: resolveWorldAdapter's own wrapping already warned once
+  // Belt-and-suspenders: resolveRootAdapter's own wrapping already warned once
   // via editorConsole (T3.4 slice 1) — this does not warn again, only formats
   // the SAME message onto the structured dev/e2e hook below for assertions.
   if (shortfall) {
@@ -449,14 +443,14 @@ export async function enterModuleModeWorldsPath(
  * whose FIRST world declares a `{ module }` adapter auto-mounts it. Same
  * "applied or not" contract as `tryManifestIngestRoute`.
  *
- * D-Y1: dispatches on `firstWorld.kind` — threejs keeps calling
+ * D-Y1: dispatches on `firstWorld.surface` — threejs keeps calling
  * `enterModuleModeFromManifestWorld` byte-for-byte (its own D-X6 guard stays
  * as the backstop for any OTHER path that might still funnel a non-three
  * mount into it); `pixijs`/`react` route through the new
  * `enterModuleModeWorldsPath` above instead.
  *
  * D-V2 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md, F24 composite): if the
- * manifest declares ANY `{ ingest }` world (anywhere in `worlds`, not just
+ * manifest declares ANY `{ ingest }` world (anywhere in `roots`, not just
  * first), this route declines — composites are owned by the ingest routes
  * (`ingest-mode.ts`'s `tryManifestIngestRoute*`), which mount the one ingest
  * world through their own enter path and any `{ module }` SIBLING through
@@ -471,8 +465,8 @@ export async function enterModuleModeWorldsPath(
 export async function tryManifestModuleRoute(store: EditorStore): Promise<boolean> {
   if (getEditorMode() === 'browser') return false; // no dev server to serve /vgai.game.json / /@fs/ from
   const manifest = await fetchGameManifest().catch(() => null);
-  if (manifest?.worlds.some((w) => w.adapter.type === 'ingest')) return false;
-  const firstWorld = manifest?.worlds[0];
+  if (manifest?.roots.some((w) => w.adapter.type === 'ingest')) return false;
+  const firstWorld = manifest?.roots[0];
   if (firstWorld === undefined || firstWorld.adapter.type !== 'module') return false;
 
   const project = getCurrentProject();
@@ -492,7 +486,7 @@ export async function tryManifestModuleRoute(store: EditorStore): Promise<boolea
     return true;
   }
   try {
-    if (firstWorld.kind === 'pixijs' || firstWorld.kind === 'react') {
+    if (firstWorld.surface === 'pixijs' || firstWorld.surface === 'react') {
       await enterModuleModeWorldsPath(store, manifest!, firstWorld, project.rootPath);
     } else {
       await enterModuleModeFromManifestWorld(store, firstWorld, project.rootPath);
@@ -501,10 +495,10 @@ export async function tryManifestModuleRoute(store: EditorStore): Promise<boolea
     editorConsole.error(`Manifest { module } auto-mount failed: ${err}`, 'adapter');
     // D-W3 (docs/WAVE4-FTUE-HARDENING-DESIGN.md §D-W3, F9) — the fourth of the
     // four manifest-route catch blocks (three/pixi/react in ingest-mode.ts,
-    // this one for `{ module }` worlds); same loud-banner-slot population.
+    // this one for `{ module }` roots); same loud-banner-slot population.
     setMountFailureReport({
       worldId: firstWorld.id,
-      kind: firstWorld.kind,
+      kind: firstWorld.surface,
       identity: firstWorld.adapter.identity,
       message: formatMountFailureMessage(err),
     });

package/src/play-log-events.ts

@@ -0,0 +1,26 @@
+import type { TickStampedEvent } from '@engine/adapter/system-adapter';
+import type { LogEntry } from './editor-api';
+
+/** Convert newly observed game-authored debug events into persistent JSONL entries. */
+export function debugEventsToLogEntries(
+  events: readonly TickStampedEvent[],
+  sinceSeq: number,
+  wallTime = Date.now(),
+): { entries: LogEntry[]; lastSeq: number } {
+  const fresh = events.filter((event) => event.seq > sinceSeq).sort((a, b) => a.seq - b.seq);
+  return {
+    entries: fresh.map((event) => ({
+      t: wallTime,
+      level: 'info',
+      source: 'game-event',
+      msg: event.event,
+      tick: event.tick,
+      simT: event.simT,
+      meta: {
+        seq: event.seq,
+        ...(event.detail !== undefined ? { detail: event.detail } : {}),
+      },
+    })),
+    lastSeq: fresh.at(-1)?.seq ?? sinceSeq,
+  };
+}