@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/history/types.ts

@@ -0,0 +1,100 @@
+declare const resourceKeyBrand: unique symbol;
+
+/** Stable for the lifetime of one open project session, including across file moves. */
+export type ResourceKey = string & { readonly [resourceKeyBrand]: true };
+
+export type ResourceKind =
+  | 'scene'
+  | 'prefab'
+  | 'ui-tree'
+  | 'material'
+  | 'data'
+  | 'manifest'
+  | 'settings'
+  | 'source'
+  | 'overlay'
+  | 'project-file'
+  | 'session-state';
+
+export interface ResourceDescriptor {
+  readonly key: ResourceKey;
+  readonly kind: ResourceKind;
+  readonly scope: 'project' | 'session';
+  readonly displayName: string;
+  readonly location: string | null;
+  readonly sessionId: string | null;
+}
+
+export interface ResourceSnapshot {
+  readonly revision: number;
+  readonly contentType: string;
+  readonly bytes: Uint8Array;
+  readonly sha256: string;
+}
+
+export interface SnapshotRef {
+  readonly revision: number;
+  readonly contentType: string;
+  readonly sha256: string;
+  readonly blobKey: string;
+  readonly byteLength: number;
+}
+
+export type PreflightResult =
+  | { readonly ok: true }
+  | {
+      readonly ok: false;
+      readonly reason: 'missing' | 'revision-conflict' | 'content-conflict' | 'expired';
+      readonly actualRevision?: number;
+      readonly actualSha256?: string;
+    };
+
+export interface ResourceDriver {
+  readonly descriptor: ResourceDescriptor;
+  capture(): Promise<ResourceSnapshot>;
+  preflight(expected: SnapshotRef): Promise<PreflightResult>;
+  restore(snapshot: SnapshotRef): Promise<void>;
+  estimateBytes(snapshot: SnapshotRef): number;
+}
+
+export type HistoryStatus =
+  | 'committed'
+  | 'undoing'
+  | 'undone'
+  | 'redoing'
+  | 'failed'
+  | 'failed-partial'
+  | 'expired';
+
+export interface HistoryError {
+  readonly code:
+    | 'busy'
+    | 'conflict'
+    | 'expired'
+    | 'apply-failed'
+    | 'compensation-failed'
+    | 'history-limit';
+  readonly message: string;
+  readonly resources: readonly ResourceKey[];
+  readonly cause?: unknown;
+}
+
+export interface ResourceChange {
+  readonly resource: ResourceKey;
+  readonly before: SnapshotRef;
+  readonly after: SnapshotRef;
+}
+
+export interface HistoryTransaction {
+  readonly id: string;
+  readonly label: string;
+  readonly detail: string | null;
+  readonly timestamp: number;
+  readonly scope: 'project' | 'session';
+  readonly sessionId: string | null;
+  readonly changes: readonly ResourceChange[];
+  readonly byteSize: number;
+  readonly mergeKey: string | null;
+  readonly status: HistoryStatus;
+  readonly error: HistoryError | null;
+}

package/src/hmr-registration-group.ts

@@ -0,0 +1,67 @@
+/**
+ * Owns a module's registry contributions across Vite Fast Refresh.
+ *
+ * A module-local `registered` boolean is not sufficient: Vite may reload the
+ * contributor without reloading the registry (duplicates), or reload the
+ * registry without reloading the contributor (missing entries). Tracking the
+ * unregister callbacks in `import.meta.hot.data` gives the contribution one
+ * explicit lifetime and keeps strict duplicate-id checks meaningful.
+ */
+
+export interface HmrRegistrationContext {
+  readonly data?: Record<string, unknown>;
+  dispose(callback: (data: Record<string, unknown>) => void): void;
+}
+
+export interface HmrRegistrationGroup {
+  ensure(register: (track: (unregister: () => void) => void) => void): void;
+  reset(): void;
+}
+
+interface PersistedRegistrationGroup {
+  dispose(): void;
+}
+
+export function createHmrRegistrationGroup(
+  hot: HmrRegistrationContext | undefined,
+  key: string,
+): HmrRegistrationGroup {
+  const persistedKey = `vgai:registration-group:${key}`;
+  // Test runners and non-Vite hosts can expose a partial `import.meta.hot`
+  // shim without `data`. In that case the group still owns its local
+  // registrations, but there is no cross-refresh persistence to maintain.
+  const hotData = hot?.data;
+  const previous = hotData?.[persistedKey] as PersistedRegistrationGroup | undefined;
+  previous?.dispose();
+
+  let active = false;
+  let unregisters: Array<() => void> = [];
+
+  const reset = () => {
+    active = false;
+    const owned = unregisters;
+    unregisters = [];
+    for (let i = owned.length - 1; i >= 0; i--) owned[i]!();
+  };
+
+  const group: HmrRegistrationGroup = {
+    ensure(register) {
+      if (active) return;
+      active = true;
+      try {
+        register((unregister) => unregisters.push(unregister));
+      } catch (error) {
+        reset();
+        throw error;
+      }
+    },
+    reset,
+  };
+
+  if (hotData) {
+    hotData[persistedKey] = { dispose: reset } satisfies PersistedRegistrationGroup;
+    hot.dispose(reset);
+  }
+
+  return group;
+}

package/src/hmr-stable-react-context.ts

@@ -0,0 +1,23 @@
+import { type Context, createContext } from 'react';
+
+/**
+ * Preserve a React context object across Vite module replacement.
+ *
+ * A provider from the previous module generation can remain mounted while a
+ * freshly imported consumer renders. If both generations call
+ * `createContext()`, the consumer observes a different context and falsely
+ * reports that it is outside the provider. Vite keeps `import.meta.hot.data`
+ * for exactly this kind of module-local state handoff.
+ */
+export function createHmrStableReactContext<T>(
+  hotData: Record<string, unknown> | undefined,
+  key: string,
+  defaultValue: T,
+): Context<T> {
+  const existing = hotData?.[key];
+  if (existing) return existing as Context<T>;
+
+  const context = createContext(defaultValue);
+  if (hotData) hotData[key] = context;
+  return context;
+}

package/src/hosted-example.ts

@@ -27,6 +27,8 @@
 
 import { setAssetPrefix } from '@engine/loader';
 import { GameManifestSchema } from '@engine/manifest/schema';
+import { BUNDLED_EDITOR_COMPATIBILITY } from './build-identity';
+import { assertProjectCompatibility } from './editor-compatibility';
 import type { ActiveProject } from './project-manager';
 
 /** Folder-name shape shared by every `examples/<id>/` — also a path-safety gate. */
@@ -44,7 +46,12 @@ export async function openExampleProject(exampleId: string): Promise<ActiveProje
   if (!res.ok) {
     throw new Error(`HTTP ${res.status} fetching ${manifestUrl} — not a bundled example?`);
   }
-  const manifest = GameManifestSchema.parse(await res.json());
+  const rawManifest: unknown = await res.json();
+  assertProjectCompatibility(
+    rawManifest && typeof rawManifest === 'object' ? rawManifest : {},
+    BUNDLED_EDITOR_COMPATIBILITY,
+  );
+  const manifest = GameManifestSchema.parse(rawManifest);
 
   // Namespace relative asset resolution to this example's staged public/ —
   // the same prefix `browser-play-entry.ts` sets at play dispatch, applied
@@ -55,8 +62,11 @@ export async function openExampleProject(exampleId: string): Promise<ActiveProje
   return {
     rootPath: `/examples/${exampleId}`,
     config: {
+      manifestVersion: manifest.manifestVersion,
       name: manifest.name,
-      defaultScene: manifest.worlds[0]?.scene ?? null,
+      version: manifest.version,
+      engine: manifest.engine,
+      defaultScene: manifest.roots[0]?.scene ?? null,
       ...(manifest.resolution ? { resolution: manifest.resolution } : {}),
     },
     exampleId,

package/src/hotkeys.ts

@@ -4,7 +4,22 @@ import { useEffect } from 'react';
 // Types
 // ---------------------------------------------------------------------------
 
-export type HotkeyScope = 'viewport' | 'hierarchy' | 'inspector' | 'asset-browser' | 'global';
+export type HotkeyScope =
+  | 'viewport'
+  | 'hierarchy'
+  | 'inspector'
+  | 'asset-browser'
+  | 'workspace'
+  | 'global';
+
+const HOTKEY_SCOPES = new Set<HotkeyScope>([
+  'viewport',
+  'hierarchy',
+  'inspector',
+  'asset-browser',
+  'workspace',
+  'global',
+]);
 
 export interface HotkeyBinding {
   /** The key to match (`e.key`, lowercase). Ignored when `code` is set. */
@@ -17,10 +32,17 @@ export interface HotkeyBinding {
   shift?: boolean;
   /** Require Alt/Option (D4 — `wrap`'s `Ctrl+Alt+G`). */
   alt?: boolean;
-  /** Scope this binding belongs to. `'global'` bindings fire regardless of panel focus. */
-  scope: HotkeyScope;
+  /** Scope(s) this binding belongs to. `'global'` bindings fire regardless of panel focus. */
+  scope: HotkeyScope | readonly HotkeyScope[];
   /** Action to execute when the binding matches. */
   action: (e: KeyboardEvent) => void;
+  /** Optional runtime gate. When it returns false, the binding yields to the
+   * browser and does not call preventDefault(). Use this for commands whose
+   * shortcut overlaps native behavior, such as Copy with a DOM text selection. */
+  when?: (e: KeyboardEvent) => boolean;
+  /** Allow this binding while a form control/contenteditable owns focus.
+   * Reserved for commands such as Save that are expected inside editors. */
+  allowInEditable?: boolean;
   /** Human-readable label for menus / tooltips. */
   label?: string;
 }
@@ -31,12 +53,58 @@ export interface HotkeyBinding {
 
 let _activeScope: HotkeyScope = 'viewport';
 
+const ACTIVE_SCOPE_DATA_KEY = 'editorActiveHotkeyScope';
+
 export function getActiveScope(): HotkeyScope {
+  const shared = document.documentElement.dataset[ACTIVE_SCOPE_DATA_KEY];
+  if (shared && HOTKEY_SCOPES.has(shared as HotkeyScope)) return shared as HotkeyScope;
   return _activeScope;
 }
 
 export function setActiveScope(scope: HotkeyScope): void {
   _activeScope = scope;
+  // Vite can temporarily retain both pre- and post-HMR module instances.
+  // The editor shell is the durable ownership authority, so mirror the value
+  // onto the shared document rather than trusting one module-local singleton.
+  document.documentElement.dataset[ACTIVE_SCOPE_DATA_KEY] = scope;
+}
+
+/** True when a DOM target belongs to a native text-editing surface. Shared
+ * by the global dispatcher and panel-local handlers so bubbled Backspace,
+ * Delete, and clipboard shortcuts cannot mutate editor state while typing. */
+export function isEditableTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof Element)) return false;
+  if (
+    target instanceof HTMLInputElement ||
+    target instanceof HTMLTextAreaElement ||
+    target instanceof HTMLSelectElement
+  ) {
+    return true;
+  }
+  if (target instanceof HTMLElement && target.isContentEditable) return true;
+  return Boolean(target.closest('[contenteditable]:not([contenteditable="false"])'));
+}
+
+function scopeFromOwnershipEvent(event: Event): HotkeyScope | null {
+  for (const target of event.composedPath()) {
+    if (!(target instanceof HTMLElement)) continue;
+    // Dockview moves focus through internal navigation sentinels that sit
+    // directly under the shell. A focusin on that infrastructure must not
+    // erase the concrete panel established by the preceding pointerdown.
+    // Pointerdown still uses the fallback, so genuinely clicking unclaimed
+    // chrome neutralizes authoring commands as intended.
+    if (event.type === 'focusin' && target.hasAttribute('data-editor-hotkey-fallback')) continue;
+    const candidate = target.dataset['editorHotkeyScope'];
+    if (candidate && HOTKEY_SCOPES.has(candidate as HotkeyScope)) {
+      return candidate as HotkeyScope;
+    }
+  }
+  return null;
+}
+
+function handleOwnershipEvent(event: Event): void {
+  const scope = scopeFromOwnershipEvent(event);
+  if (scope) setActiveScope(scope);
 }
 
 // ---------------------------------------------------------------------------
@@ -63,37 +131,32 @@ export function registerHotkeys(bindings: HotkeyBinding[]): () => void {
 // ---------------------------------------------------------------------------
 
 function handleKeyDown(e: KeyboardEvent): void {
-  // Skip when typing in form inputs — D4 (spec27 §6 D4 "each shortcut fires
-  // only when not typing") widens this to `[contenteditable]` too (no
-  // in-repo editor uses one today — `WorldTextEditor`/`GameHierarchy`'s
-  // rename both use a real `<textarea>`/`<input>`, already covered above —
-  // but the guard should hold for a future contentEditable surface without
-  // needing another fix here).
-  if (
-    e.target instanceof HTMLInputElement ||
-    e.target instanceof HTMLTextAreaElement ||
-    e.target instanceof HTMLSelectElement ||
-    (e.target instanceof HTMLElement && e.target.isContentEditable)
-  )
-    return;
+  // Skip ordinary editor commands while typing — D4 (spec27 §6 D4 "each
+  // shortcut fires only when not typing") covers form fields and future
+  // contentEditable surfaces. A binding must explicitly opt in when its
+  // conventional behavior belongs inside an editor too (currently Save).
+  const editableTarget = isEditableTarget(e.target);
 
   const mod = e.metaKey || e.ctrlKey;
   const key = e.key.toLowerCase();
   const code = e.code;
-  const scope = _activeScope;
+  const scope = getActiveScope();
 
   // Check scoped bindings first, then global
   const passes: HotkeyScope[] = scope === 'global' ? ['global'] : [scope, 'global'];
 
   for (const pass of passes) {
     for (const b of _bindings) {
-      if (b.scope !== pass) continue;
+      const bindingScopes = Array.isArray(b.scope) ? b.scope : [b.scope];
+      if (!bindingScopes.includes(pass)) continue;
+      if (editableTarget && !b.allowInEditable) continue;
 
       const keyMatch = b.code ? b.code === code : b.key === key;
       if (!keyMatch) continue;
       if ((b.mod ?? false) !== mod) continue;
       if ((b.shift ?? false) !== e.shiftKey) continue;
       if ((b.alt ?? false) !== e.altKey) continue;
+      if (b.when && !b.when(e)) continue;
 
       e.preventDefault();
       b.action(e);
@@ -107,12 +170,20 @@ let _installed = false;
 /** Attach the global keydown listener. Call once at startup. */
 export function installHotkeys(): void {
   if (_installed) return;
+  // Capture ownership before React's panel-local bubble handlers run. The
+  // closest declarative scope in the composed path wins; the shell's
+  // `workspace` marker is therefore a safe neutral fallback for menus,
+  // utilities, document editors, and unclaimed chrome.
+  window.addEventListener('pointerdown', handleOwnershipEvent, true);
+  window.addEventListener('focusin', handleOwnershipEvent, true);
   window.addEventListener('keydown', handleKeyDown);
   _installed = true;
 }
 
 /** Detach the global keydown listener. */
 export function uninstallHotkeys(): void {
+  window.removeEventListener('pointerdown', handleOwnershipEvent, true);
+  window.removeEventListener('focusin', handleOwnershipEvent, true);
   window.removeEventListener('keydown', handleKeyDown);
   _installed = false;
 }

package/src/ingest/discovery-react.ts

@@ -9,7 +9,7 @@
  *
  * UNLIKE `discovery.ts`/`discovery2d.ts`, this module does NOT also glob the
  * entry module itself: an `ingest-react` world mounts through
- * `resolveWorldAdapter` (`adapter-resolver.ts`'s `resolveIngestReactAdapter`,
+ * `resolveRootAdapter` (`adapter-resolver.ts`'s `resolveIngestReactAdapter`,
  * N1) — the SAME `/@fs/`-dynamic-import + `createRoot` host stack
  * `default-react` uses — rather than a capture-based bridge, so there is no
  * "build an `IngestGame`/`IngestGame2D` descriptor with its own `load`
@@ -17,7 +17,7 @@
  * `games-react/*\/vgai.game.json`, validate its single world is a real
  * `ingest-react` `'deduped'` world, and hand back the parsed
  * `ResolvedGameManifest` + that world's absolute on-disk folder (the
- * `projectRoot` `resolveWorldAdapter` needs for its `entry`'s `/@fs/`
+ * `projectRoot` `resolveRootAdapter` needs for its `entry`'s `/@fs/`
  * dynamic import and its `loadProjectGameProvider` lookup) — see
  * `ingest-mode.ts`'s `enterIngestModeReact` for the mount step.
  *
@@ -62,21 +62,21 @@ export interface IngestGameReact {
 
 function buildIngestGameReact(folderId: string, raw: unknown): IngestGameReact {
   const manifest = loadGameManifest(raw);
-  if (manifest.worlds.length !== 1) {
+  if (manifest.roots.length !== 1) {
     throw new Error(
       `react ingest discovery: "${folderId}/vgai.game.json" must declare exactly one world ` +
-        `(found ${manifest.worlds.length}).`,
+        `(found ${manifest.roots.length}).`,
     );
   }
-  const world = manifest.worlds[0]!;
+  const world = manifest.roots[0]!;
   if (
-    world.kind !== 'react' ||
+    world.surface !== 'react' ||
     world.adapter.type !== 'ingest' ||
     world.adapter.identity !== 'ingest-react'
   ) {
     throw new Error(
       `react ingest discovery: "${folderId}/vgai.game.json"'s world must be a react { ingest } ` +
-        `world (found kind "${world.kind}", adapter identity "${world.adapter.identity}").`,
+        `world (found kind "${world.surface}", adapter identity "${world.adapter.identity}").`,
     );
   }
   if (world.adapter.strategy !== 'deduped') {
@@ -117,9 +117,8 @@ export function getIngestGameReact(folderId: string): IngestGameReact | undefine
 
 /**
  * The absolute on-disk `projectRoot` for a discovered react ingest game's
- * folder — what `resolveWorldAdapter`/`resolveAllWorlds` need to resolve its
- * `entry` (and, transitively, `loadProjectGameProvider`'s
- * `src/ui/game-state.tsx` lookup). `undefined` when
+ * folder — what `resolveRootAdapter`/`resolveAllWorlds` need to resolve its
+ * `entry`. `undefined` when
  * `__VGAI_ENGINE_ROOT__` isn't defined (browser-mode static build — no dev
  * server, no `/@fs/` route to resolve through anyway).
  */

package/src/ingest/discovery.ts

@@ -98,7 +98,7 @@ function buildModuleLoadedGame(
   if (!world.entry) {
     throw new Error(
       `ingest discovery: "${folderId}" (strategy "${strategy}") has no \`entry\` — ` +
-        "shared/deduped ingest worlds need the game module's folder-relative path there.",
+        "shared/deduped ingest roots need the game module's folder-relative path there.",
     );
   }
   const key = `./games/${folderId}/${world.entry}`;
@@ -139,13 +139,13 @@ function buildFileBackedGame(
 
 function buildIngestGame(folderId: string, raw: unknown): IngestGame {
   const manifest = loadGameManifest(raw);
-  if (manifest.worlds.length !== 1) {
+  if (manifest.roots.length !== 1) {
     throw new Error(
       `ingest discovery: "${folderId}/vgai.game.json" must declare exactly one world ` +
-        `(found ${manifest.worlds.length}).`,
+        `(found ${manifest.roots.length}).`,
     );
   }
-  const world = manifest.worlds[0]!;
+  const world = manifest.roots[0]!;
   if (world.adapter.type !== 'ingest' || world.adapter.identity !== 'ingest-three') {
     throw new Error(
       `ingest discovery: "${folderId}/vgai.game.json"'s world must be a threejs { ingest } ` +

package/src/ingest/discovery2d.ts

@@ -69,7 +69,7 @@ function buildModuleLoadedGame2D(
   if (!world.entry) {
     throw new Error(
       `world2d ingest discovery: "${folderId}" (strategy "${strategy}") has no \`entry\` — ` +
-        "shared/deduped ingest-pixi worlds need the game module's folder-relative path there.",
+        "shared/deduped ingest-pixi roots need the game module's folder-relative path there.",
     );
   }
   const key = `./games-2d/${folderId}/${world.entry}`;
@@ -88,7 +88,7 @@ function buildModuleLoadedGame2D(
  * the manifest's Track P fields (docs/PIXI-INGEST-LANDING-DESIGN.md §2) —
  * `bundleUrl` is required by the schema's cross-field check for this
  * strategy (exactly one of `bundleUrl`/`entryHtml`); `entryHtml`-only
- * iframe-reachable worlds still have no builder here (mirrors the
+ * iframe-reachable roots still have no builder here (mirrors the
  * `resolveIngestDescriptor`/three-side gap: reading a raw HTML/inline-source
  * file's contents needs a runtime fetch this synchronous builder doesn't do).
  * `extraDeps`/`pixiModuleUrl` become LAZY thunks (`IngestGame2D.extraDeps`/
@@ -131,13 +131,13 @@ export function buildIframeReachableGame2D(
 
 function buildIngestGame2D(folderId: string, raw: unknown): IngestGame2D {
   const manifest = loadGameManifest(raw);
-  if (manifest.worlds.length !== 1) {
+  if (manifest.roots.length !== 1) {
     throw new Error(
       `world2d ingest discovery: "${folderId}/vgai.game.json" must declare exactly one world ` +
-        `(found ${manifest.worlds.length}).`,
+        `(found ${manifest.roots.length}).`,
     );
   }
-  const world = manifest.worlds[0]!;
+  const world = manifest.roots[0]!;
   if (world.adapter.type !== 'ingest' || world.adapter.identity !== 'ingest-pixi') {
     throw new Error(
       `world2d ingest discovery: "${folderId}/vgai.game.json"'s world must be a pixijs ` +

package/src/ingest/games/bloom-composer/vgai.game.json

@@ -1,16 +1,16 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "name": "Bloom EffectComposer repro standin (F13)",
   "version": "0.1.0",
   "engine": {
     "version": "0.1.0"
   },
-  "worlds": [
+  "roots": [
     {
       "id": "bloom-composer",
-      "kind": "threejs",
       "description": "A self-made, source-available three.js game that renders through its OWN EffectComposer (RenderPass + UnrealBloomPass) — a repro standin for F13 (docs/FTUE-EXTERNAL-R3F-GAME.md), NOT an upstream title (sanctioned stand-in precedent: ADAPTER-MAXIMAL-SPEC.json coverage_standins, same spirit as own-three-bundled). Exposes a dev-only window.__vgaiBloomComposer inspection hook reading its own composer's real render-target size. Used to prove the host ingest resize path never drives a game's own composer (docs/WAVE14-F13-BLOOM-COMPOSER-REPRO-DESIGN.md).",
       "adapter": {
+        "surface": "threejs",
         "ingest": {
           "strategy": "deduped"
         }

package/src/ingest/games/embed-bundle/vgai.game.json

@@ -1,16 +1,16 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "name": "Opaque bundle (embed-only floor)",
   "version": "0.1.0",
   "engine": {
     "version": "0.1.0"
   },
-  "worlds": [
+  "roots": [
     {
       "id": "embed-bundle",
-      "kind": "threejs",
       "description": "A self-contained opaque bundle (a dependency-free canvas app) standing in for any prebuilt bundle whose renderer the editor cannot reach. Demonstrates the iframe embed/lifecycle FLOOR (Tier 0–1): hosted + sized + disposed, scene NOT introspectable. Payload-agnostic — a real opaque three.js bundle (own realm-local three) is hosted identically.",
       "adapter": {
+        "surface": "threejs",
         "ingest": {
           "strategy": "opaque-embed",
           "entryHtml": "embed.html"

package/src/ingest/games/games-fps/vgai.game.json

@@ -1,16 +1,16 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "name": "three.js — Octree FPS (games_fps)",
   "version": "0.1.0",
   "engine": {
     "version": "0.1.0"
   },
-  "worlds": [
+  "roots": [
     {
       "id": "games-fps",
-      "kind": "threejs",
       "description": "Upstream mrdoob/three.js example: octree collisions, GLTF world, 100 physics spheres, pointer-lock FPS. Own scene/camera/renderer/rAF/input.",
       "adapter": {
+        "surface": "threejs",
         "ingest": {
           "strategy": "shared",
           "assets": {

package/src/ingest/games/iframe-reachable/vgai.game.json

@@ -1,16 +1,16 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "name": "Prebuilt bundle in iframe (reachable three)",
   "version": "0.1.0",
   "engine": {
     "version": "0.1.0"
   },
-  "worlds": [
+  "roots": [
     {
       "id": "iframe-reachable",
-      "kind": "threejs",
       "description": "A prebuilt bundle hosted in its OWN iframe document, but whose three is REACHABLE: the iframe importmap resolves `three` to the host instance (blob re-export), so its scene is captured in-realm and edited live in the editor (cov-iframe-reachable, tier 2–3). The middle tier between shared-ESM and opaque embed.",
       "adapter": {
+        "surface": "threejs",
         "ingest": {
           "strategy": "iframe-reachable",
           "entryHtml": "game-source.js"

package/src/ingest/games/interactive-cubes/vgai.game.json

@@ -1,16 +1,16 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "name": "three.js — Interactive Cubes",
   "version": "0.1.0",
   "engine": {
     "version": "0.1.0"
   },
-  "worlds": [
+  "roots": [
     {
       "id": "interactive-cubes",
-      "kind": "threejs",
       "description": "Upstream webgl_interactive_cubes: 2000 procedurally-placed cubes, orbiting camera, per-frame raycaster hover-highlight. Own scene/camera/renderer/rAF. No external assets.",
       "adapter": {
+        "surface": "threejs",
         "ingest": {
           "strategy": "shared"
         }

package/src/ingest/games/mismatched-three/vgai.game.json

@@ -1,16 +1,16 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "name": "Mismatched/bundled three (graceful degrade)",
   "version": "0.1.0",
   "engine": {
     "version": "0.1.0"
   },
-  "worlds": [
+  "roots": [
     {
       "id": "mismatched-three",
-      "kind": "threejs",
       "description": "A game that uses a SEPARATE (non-host) three — stands in for a bundled/mismatched three version the capture trap cannot instrument. The editor detects the capture failure and degrades to embed-only (cov-mismatched-three) — never a silent failure.",
       "adapter": {
+        "surface": "threejs",
         "ingest": {
           "strategy": "shared",
           "captureTimeoutMs": 2500

package/src/ingest/games/own-three-bundled/vgai.game.json

@@ -1,16 +1,16 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "name": "Bundles-own-three (build-time dedupe)",
   "version": "0.1.0",
   "engine": {
     "version": "0.1.0"
   },
-  "worlds": [
+  "roots": [
     {
       "id": "own-three-bundled",
-      "kind": "threejs",
       "description": "A source-available game that ships its OWN nested node_modules/three. Build-time dedupe (resolve.dedupe:[three]) collapses it to the editor instance → LIVE capture + edit (cov-bundled-dedupe). A passing live ingest proves the collapse (else the bare import would hit the nested stub and capture would fail).",
       "adapter": {
+        "surface": "threejs",
         "ingest": {
           "strategy": "deduped"
         }