@vgai/engine 0.5.0 → 0.5.2

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/engine",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Readable TypeScript game engine and universal host for Three.js, PixiJS, and React games.",
   "keywords": ["game-engine", "three.js", "pixijs", "react", "ai-agents"],
   "type": "module",

package/schemas/engine-capabilities.json

@@ -16,7 +16,7 @@
       ],
       "notes": "Grepped packages/engine/src for ccd/CCD/setCcdEnabled: zero matches, 2D and 3D. No call ever sets a ccd flag. Workaround: keep dynamic-body per-step travel small relative to the thinnest collider, or add intermediate colliders.",
       "evidenceHashes": {
-        "packages/engine/src/scene/scene-loader.ts": "53c8f6d756363c0638c576b7e5a3d425fe0e77ce929dac9d462b8999b7000db8",
+        "packages/engine/src/scene/scene-loader.ts": "07fb9086e95959fd84e71ccc57581bb00d1f6eca1137853492b6a569755e8db5",
         "packages/engine/src/world2d/scene2d-loader.ts": "f0f74eefd9cce16bbe7826225a52f2b0407ab141641dcdd370bcff1d091bce69"
       }
     },
@@ -32,7 +32,7 @@
       "notes": "Grepped for maxBodies/MAX_ENTITIES/entity limit/body limit/entityCount: no matches. No invented numbers — nothing caps entity/body count and no perf test here establishes a safe ceiling. Treat large counts (hundreds+ dynamic bodies) as unvalidated, not 'supported at scale'.",
       "evidenceHashes": {
         "packages/engine/src/setup/setup-physics.ts": "0540c502f420018b24dac8b77c486f30f905f0a05b02ead7ed3899e5aa612ee5",
-        "packages/engine/src/scene/scene-loader.ts": "53c8f6d756363c0638c576b7e5a3d425fe0e77ce929dac9d462b8999b7000db8"
+        "packages/engine/src/scene/scene-loader.ts": "07fb9086e95959fd84e71ccc57581bb00d1f6eca1137853492b6a569755e8db5"
       }
     },
     {
@@ -91,7 +91,7 @@
       ],
       "notes": "Track P shipped 2026-07-03; proven: bubbo-bubbo/puzzling-potions/flappy-pixi. Tiers/limits: docs/CAPABILITY-TIERS.md, docs/PIXI-INGEST-LANDING-DESIGN.md.",
       "evidenceHashes": {
-        "docs/BACKBONE-TASKS.md": "206ce2818efcf2b12876160d7366d41a6afec6b545b025a98a3fcf2915cdf824"
+        "docs/BACKBONE-TASKS.md": "4d58398e22ed0261ec246668cac115ec9cfdde9881920070e95ee642f1323eb1"
       }
     },
     {
@@ -104,7 +104,7 @@
       ],
       "notes": "Scope is native-DOM React ONLY (D-N1): R3F/@pixi/react games are canvas games and ride the three.js/pixi seams instead. Generality limit: ONE proven game (react-rpg — menu-to-dungeon e2e under React 19; both game-2 candidates rejected on evidence, R-N7). Game deps must be host-installed root deps (D-N6). Open R-N6: vendored react games' raw window listeners bypass the play-mode input gate. Design: docs/REACT-INGEST-LANDING-DESIGN.md.",
       "evidenceHashes": {
-        "docs/BACKBONE-TASKS.md": "206ce2818efcf2b12876160d7366d41a6afec6b545b025a98a3fcf2915cdf824"
+        "docs/BACKBONE-TASKS.md": "4d58398e22ed0261ec246668cac115ec9cfdde9881920070e95ee642f1323eb1"
       }
     },
     {

package/schemas/vgai-game.schema.json

@@ -446,11 +446,11 @@
           "description": "Short kebab-case feature tags used as gallery/catalog filter facets"
         },
         "thumbnail": {
-          "description": "Optional thumbnail image reference (engine-repo-relative, e.g. docs/example-screenshots/<id>/<shot>.png; generated per FT-11, never hand-made)",
+          "description": "Optional thumbnail image reference, PROJECT-relative (canonical path: learn/thumbnail.png — the §3 schema path). Generated per FT-11 by the deterministic render tooling (scripts/generate-learn-thumbnails.ts), never hand-made",
           "type": "string"
         },
         "preview": {
-          "description": "Optional short preview video/loop reference (generated per FT-11)",
+          "description": "Optional short preview video/loop reference, PROJECT-relative (canonical path: learn/preview.mp4; generated per FT-11)",
           "type": "string"
         },
         "lesson": {

package/src/adapter/authoring.ts

@@ -89,6 +89,7 @@ export type EditorNodeRole =
   | 'document'
   | 'story'
   | 'component'
+  | 'instance'
   | 'element'
   | 'entity'
   | 'boundary';
@@ -153,6 +154,34 @@ export interface HierarchyProvider {
 export interface SelectionProvider {
   get(): string[];
   set(ids: string[]): void;
+  /** Resolve a raw native/render hit to the semantic authoring subject. The
+   * shell must not infer ownership from ancestry or substrate-specific kinds.
+   * Older adapters may omit this; raw ids then remain the selection ids. */
+  resolve?(
+    rawId: string,
+    options?: { intent?: 'normal' | 'deep'; scopeId?: string | null },
+  ): SelectionResolution | null;
+}
+
+/** Adapter-owned result of semantic selection resolution. Separate ids keep
+ * selection, inspection, and manipulation from becoming accidental aliases. */
+export interface SelectionResolution {
+  /** Hierarchy selection and default Inspector subject. */
+  id: string;
+  /** Optional alternate Inspector subject. Defaults to {@link id}. */
+  inspectorId?: string;
+  /** Native transform subject. `null` means the selection is non-spatial. */
+  transformId?: string | null;
+  /** Nearest closed component/prefab/assembly boundary, when any. */
+  boundaryId?: string | null;
+}
+
+export type TransformChannel = 'position' | 'rotation' | 'scale';
+
+export interface TransformEditability {
+  writable: boolean;
+  /** Human-facing explanation for a disabled gizmo/field. */
+  reason?: string;
 }
 
 export interface TransformProvider {
@@ -160,6 +189,10 @@ export interface TransformProvider {
   dimensions?(id: string): '2d' | '3d' | null;
   get(id: string): Transform;
   owner(id: string): TransformOwner;
+  /** Pre-gesture persistence check. Omitted means the adapter's transform
+   * capability applies uniformly. A false result must suppress manipulation
+   * before the live object is moved, never discover refusal at drag end. */
+  editability?(id: string, channel: TransformChannel): TransformEditability;
   /** Pause whatever controller fights the gizmo (physics/script) for editing. */
   beginEdit(id: string): void;
   apply(id: string, t: Transform): void;
@@ -237,6 +270,15 @@ export interface StructureProvider {
    *  `wrap`). Absent ⇒ the shell's context menu shows no Unwrap item for this
    *  adapter. */
   unwrap?(id: string): void;
+  /** Group sibling authoring objects beneath one new spatial parent. The
+   * adapter owns transform preservation, persistence, and undo semantics.
+   * Returns the new group id, or null when the selection cannot be grouped. */
+  group?(ids: readonly string[]): string | null;
+  /** Dissolve a plain spatial group and return the ids of its promoted
+   * children. Absent means this adapter has no lossless ungroup operation. */
+  ungroup?(id: string): string[];
+  /** Preflight for an Ungroup affordance. Omit when ungroup is never offered. */
+  canUngroup?(id: string): boolean;
   /**
    * D4.R2 (spec27 §6 D4 reopen) — remove every id in `ids` as ONE undoable
    * op (a single Ctrl+Z restores the whole batch), instead of the caller

package/src/adapter/index.ts

@@ -39,6 +39,7 @@ export type {
   RootGroup,
   RootGroupsProvider,
   SelectionProvider,
+  SelectionResolution,
   SpriteAtlas2D,
   SpriteAtlasFrame2D,
   SpriteFrames2DDescriptor,
@@ -50,6 +51,8 @@ export type {
   TilemapCell,
   TilemapEditGrid,
   TilemapEditProvider,
+  TransformChannel,
+  TransformEditability,
   TransformProvider,
 } from './authoring';
 export {

package/src/adapter/ingest/overlay-apply.ts

@@ -26,6 +26,24 @@ import type { IngestOverlay } from './overlay-file';
 /** Fixed id for the captured render camera (not a scene child, so no structural path). */
 export const CAMERA_ID = 'ingest:camera';
 
+/**
+ * The editor parks its OWN objects — grid, its two lights, the particle
+ * BatchedRenderer, every TransformControls/gizmo helper — on layer 31
+ * (`packages/editor/src/editor-layers.ts`'s `EDITOR_LAYER`) so the game camera
+ * never sees them. In ingest mode those objects are added to the GAME'S OWN
+ * scene, which is the same tree this walk indexes.
+ */
+const EDITOR_ONLY_LAYER_MASK = 1 << 31;
+
+/**
+ * Editor furniture, not game content. Excluded from the walk entirely — see
+ * {@link assignStructuralIds} for why that exclusion is what makes the id
+ * scheme's central promise true.
+ */
+function isEditorOnly(o: THREE.Object3D): boolean {
+  return (o.layers.mask & EDITOR_ONLY_LAYER_MASK) !== 0;
+}
+
 /** The single (non-array) standard-ish material of a mesh, if it has a color. */
 export function colorMaterialOf(o: THREE.Object3D): THREE.MeshStandardMaterial | null {
   const mat = (o as THREE.Mesh).material;
@@ -49,6 +67,28 @@ export interface StructuralIdWalk {
  * (position + type + name) — the prerequisite for overlay reapplication
  * across an independent fresh walk (editor reload, or a shipped build that
  * never ran the editor at all).
+ *
+ * EDITOR FURNITURE IS EXCLUDED, and that exclusion is load-bearing rather than
+ * cosmetic. In ingest mode the editor adds its grid, lights, particle
+ * BatchedRenderer and TransformControls gizmo to the GAME'S OWN scene, and
+ * they arrive asynchronously — some before the walk, some after. Indexing them
+ * made a game object's path depend on how much editor furniture happened to be
+ * attached at walk time, which broke the two promises above:
+ *
+ *   • Across a RELOAD, the same mesh changed id. Observed in the games-fps
+ *     overlay-persistence e2e: an object saved as `ingest:106/0/0/0:…` came
+ *     back as `ingest:102/0:Mesh:Cube004` — four root slots earlier, exactly
+ *     the grid + two editor lights + BatchedRenderer — so the persisted
+ *     override landed on nothing and was reported as an orphan.
+ *   • A SHIPPED build (no editor, so no furniture at all) minted a different
+ *     id set than the editor that authored the overlay — i.e. the ship path
+ *     this module exists to serve could not reliably consume its own output.
+ *
+ * Skipping the furniture entirely — not merely declining to give it an id —
+ * is what fixes both: the game's own children occupy 0..N-1 whatever else is
+ * parented alongside them. It also keeps gizmo handles and the grid out of the
+ * hierarchy/inspector projections built on this walk, where they were
+ * selectable and colorable as if they were game content.
  */
 export function assignStructuralIds(
   scene: THREE.Object3D,
@@ -68,13 +108,17 @@ export function assignStructuralIds(
     count++;
     if (o.isLight) lights++;
     else if (o.isMesh) meshes++;
-    o.children.forEach((c, i) => {
-      visit(c, `${path}/${i}`);
-    });
+    visitChildren(o, path);
+  };
+  const visitChildren = (o: THREE.Object3D, path: string): void => {
+    let i = 0;
+    for (const c of o.children) {
+      if (isEditorOnly(c)) continue;
+      visit(c, path ? `${path}/${i}` : `${i}`);
+      i++;
+    }
   };
-  scene.children.forEach((c, i) => {
-    visit(c, `${i}`);
-  });
+  visitChildren(scene, '');
   if (camera) {
     setUserData(camera, 'entityId', CAMERA_ID);
     byId.set(CAMERA_ID, camera);

package/src/adapter/ingest/scene-capture.ts

@@ -59,6 +59,32 @@ export interface CapturedRuntime {
   renderer: THREE.WebGLRenderer;
 }
 
+/** Options for {@link installSceneCapture}. */
+export interface SceneCaptureOptions {
+  /**
+   * True when `renderer` is one the HOST constructed for its own drawing.
+   *
+   * The trap lives on the shared `WebGLRenderer.prototype` — that sharing is
+   * the whole mechanism — so the host's renders arrive here too, and the trap
+   * captures the first scene it sees. Any host renderer built after the trap
+   * installs (the editor bakes model thumbnails and asset previews on demand,
+   * each with its own offscreen renderer and its own little light rig) is a
+   * candidate to be captured AS THE GAME.
+   *
+   * That is what made `cov-mismatched-three` — the spec for "a game bundling
+   * its own three is DETECTED and degrades to embed-only, never silently" —
+   * pass or fail on timing alone: whether a thumbnail happened to bake inside
+   * the game's 2.5s capture window. When it did, the editor adopted its own
+   * preview scene as the game and `captureFailed` never fired.
+   *
+   * Identity, not shape, is the discriminator: a host renderer and a game
+   * renderer are the same class, both built after install, both drawing real
+   * scenes. The host is the only party that knows which is which, so it says
+   * so (`packages/editor/src/host-renderers.ts`).
+   */
+  isHostRenderer?: (renderer: unknown) => boolean;
+}
+
 /** Handle returned by {@link installSceneCapture}. */
 export interface SceneCaptureHandle {
   /** The captured runtime, or null until the game renders its first frame. */
@@ -120,6 +146,7 @@ interface EffectComposerCtorLike {
 export function installSceneCapture(
   threeNamespace: unknown,
   effectComposerCtor?: unknown,
+  opts?: SceneCaptureOptions,
 ): SceneCaptureHandle {
   const THREE_NS = threeNamespace as ThreeLike;
   const proto = THREE_NS.WebGLRenderer.prototype;
@@ -173,8 +200,30 @@ export function installSceneCapture(
       const self = this;
       return function render(this: unknown, ...args: unknown[]) {
         const [scene, camera] = args;
-        drawCount++;
-        if (!captured && scene && (scene as { isScene?: boolean }).isScene) {
+        // Attribute the draw to the GAME, not to whoever shares this prototype.
+        // The trap patches `WebGLRenderer.prototype.render` on the editor's own
+        // three, so the EDITOR viewport's renders land here too. Counting them
+        // made `getDrawCount()` climb while the ingested game was paused, which
+        // is what the pause assertions in `14-ingest-feature-matrix` were
+        // measuring — the loop gate was doing its job (both games use
+        // `setAnimationLoop`, so they ARE gateable) and the instrument was
+        // reporting someone else's frames. Before capture every render still
+        // counts: that is how the first game frame is detected at all.
+        if (!captured || (self as unknown) === captured.renderer) drawCount++;
+        // Never capture a scene the HOST owns. The trap sits on the shared
+        // `WebGLRenderer.prototype`, so the editor's own viewport renders
+        // arrive here too — and when a game bundles its own MISMATCHED three
+        // (the case this whole degrade-to-embed-only path exists for), the
+        // editor's scene is then the only thing that ever reaches the trap.
+        // It was duly "captured" as the game: the editor got a hierarchy of
+        // its own GridHelper, BatchedRenderer and viewport lights presented as
+        // the ingested game's content, and `captureFailed` — the signal the
+        // whole graceful-degradation contract is built on — never fired.
+        // Whether that happened at all came down to whether the editor
+        // rendered a frame inside the game's capture window, so the same
+        // session could pass or fail on timing alone.
+        const isHostRender = opts?.isHostRenderer?.(self) === true;
+        if (!captured && !isHostRender && scene && (scene as { isScene?: boolean }).isScene) {
           captured = {
             scene: scene as THREE.Scene,
             camera: camera as THREE.Camera,

package/src/adapter/vgai-scene-game-adapter.ts

@@ -668,6 +668,30 @@ export class VgaiSceneGameAdapter implements GameAdapter {
       };
     }
 
+    // Warm the GPU program cache before the first visible frame. A mount gets
+    // a fresh WebGL context, so without this every scene material compiles
+    // lazily INSIDE the first draw calls — measured as ~0.5s of main-thread
+    // driver stalls on every editor play press. Gated on
+    // KHR_parallel_shader_compile: with the extension, compileAsync overlaps
+    // the compiles with the play transition; WITHOUT it (software
+    // rasterizers — SwiftShader in CI) compileAsync degenerates into one big
+    // synchronous compile that delays mount by whole seconds, strictly worse
+    // than the lazy first-draw path it was replacing. Best-effort: lazy
+    // compilation stays correct if it throws, and test hosts pass renderer
+    // stubs without these methods.
+    const glContext = typeof renderer.getContext === 'function' ? renderer.getContext() : undefined;
+    const parallelCompile =
+      !!glContext &&
+      typeof glContext.getExtension === 'function' &&
+      !!glContext.getExtension('KHR_parallel_shader_compile');
+    if (!headless && parallelCompile && typeof renderer.compileAsync === 'function') {
+      try {
+        await renderer.compileAsync(scene, camera);
+      } catch {
+        // Fall back to lazy compilation.
+      }
+    }
+
     // Idempotency guard for disposeGame — see below. Declared here (not inside
     // disposeGame) so hotReload can also refuse to run on an already-disposed
     // adapter.

package/src/manifest/schema.ts

@@ -346,13 +346,17 @@ export const LearnMetadataSchema = z
       .string()
       .optional()
       .describe(
-        'Optional thumbnail image reference (engine-repo-relative, e.g. ' +
-          'docs/example-screenshots/<id>/<shot>.png; generated per FT-11, never hand-made)',
+        'Optional thumbnail image reference, PROJECT-relative (canonical path: ' +
+          'learn/thumbnail.png — the §3 schema path). Generated per FT-11 by the deterministic ' +
+          'render tooling (scripts/generate-learn-thumbnails.ts), never hand-made',
       ),
     preview: z
       .string()
       .optional()
-      .describe('Optional short preview video/loop reference (generated per FT-11)'),
+      .describe(
+        'Optional short preview video/loop reference, PROJECT-relative (canonical path: ' +
+          'learn/preview.mp4; generated per FT-11)',
+      ),
     lesson: z
       .string()
       .optional()

package/src/runtime/create-runtime.ts

@@ -25,6 +25,7 @@ import {
   type WorldInstance,
 } from './game';
 import { createInputRouter, type RouterAdapterRoot, stackOrder } from './input-router';
+import { installRenderControlHarness, isRenderModeRequested } from './render-control';
 
 // Re-export the camera-precedence helper from its new home so existing importers
 // (`import { adoptSceneCamera } from '@engine/runtime/create-runtime'`) keep working.
@@ -393,6 +394,23 @@ export interface WorldsRuntimeConfig {
    *  (a test, a bespoke host) may also set it directly. Omitting it falls
    *  back to `createGame`'s own fixed default. */
   seed?: number | undefined;
+  /**
+   * G3/FT-11 (docs/FTUE-LEARN-SYSTEM-DESIGN.md §8 G3) — test-only overrides
+   * for the render-control seam this host now wires up for EVERY session
+   * (see `createWorldsGameRuntime`): `location` is where `?vgai-render=1`
+   * is read from (defaults to the real `window.location`; a Node test has
+   * no `window` and must inject one to exercise the seam), `target` is
+   * where the harness publishes (defaults to the real `window` — override
+   * in a unit test to avoid touching the global object; mirrors
+   * `RenderControlHarnessOptions.target`/`.location` and the
+   * `debugBridge.url` override precedent in `mount-manifest.ts`).
+   */
+  renderControl?:
+    | {
+        readonly location?: { readonly search: string } | undefined;
+        readonly target?: Record<string, unknown> | undefined;
+      }
+    | undefined;
 }
 
 /**
@@ -818,6 +836,57 @@ async function mountAllWorldSpecs(
   return { mountedEntries, routerEntries };
 }
 
+/**
+ * G3/FT-11 — publish the render-control harness (`render-control.ts`) for a
+ * live session, returning its retraction (wired into the session's own
+ * `stop()`, same leave-nothing-live rule as the debug bridge's `uninstall()`
+ * in mount-manifest.ts — render-control has no uninstall surface of its own,
+ * a render page being a single-load host by design, so the retraction is
+ * the publication's inverse). Split out of `createWorldsGameRuntime` purely
+ * to keep that function's cyclomatic complexity down (the same reason
+ * `mountAllWorldSpecs`/`installDefaultWorldDevGlobals` are split out).
+ *
+ * The clock is a documented no-op: a manifest-mounted game has no global
+ * cinematic AnimationClock to seek (a cinematic fixture that HAS one
+ * installs its own harness with the real clock, e.g.
+ * packages/engine/e2e/render-cinematic/main.ts) — the meaningful advance
+ * path for a plain game is `simulateSubsteps` (I5 `--simulate`), which
+ * drives `game.runFrame`.
+ */
+function installSessionRenderHarness(
+  game: GameInternal,
+  location: { readonly search: string },
+  targetOverride: Record<string, unknown> | undefined,
+): (() => void) | undefined {
+  const target =
+    targetOverride ??
+    (typeof window !== 'undefined' ? (window as unknown as Record<string, unknown>) : undefined);
+  if (target === undefined) return undefined;
+  installRenderControlHarness({
+    game,
+    clock: {
+      seek() {
+        /* no global cinematic clock on a manifest-mounted game — see above */
+      },
+      seekFrame() {
+        /* intentional no-op, as seek() */
+      },
+    },
+    readiness: {
+      // Mount is complete by the time this harness exists (the install site
+      // in `createWorldsGameRuntime` is after `mountAllWorldSpecs`
+      // resolved) — the hook resolving immediately IS the readiness
+      // statement, not an assumption.
+      scene() {},
+    },
+    location,
+    target,
+  });
+  return () => {
+    delete target['__vgaiRender'];
+  };
+}
+
 async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<GameSession> {
   const { container, roots: specs, width, height, headless = false, seed } = config;
   if (specs.length === 0) {
@@ -896,10 +965,27 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
       return () => extraUpdaters.delete(fn);
     },
   };
+  // G3/FT-11 (docs/FTUE-LEARN-SYSTEM-DESIGN.md §8 G3): every manifest/host-
+  // mounted game is a deterministic-capture candidate — the render-control
+  // seam (`?vgai-render=1`, render-control.ts) is wired HERE, at the one
+  // host every boot path shares (mountGameFromManifest, mountManifestWorlds,
+  // and direct createGameRuntime callers all reach this function), instead
+  // of asking every project's entry page to install it the way the e2e
+  // fixtures do. Production-protected twice over: `isRenderModeRequested`
+  // gates on the query param, and `installRenderControlHarness` re-checks it
+  // internally (its AC 4), so a normal gameplay page sees zero change.
+  const renderModeLocation =
+    config.renderControl?.location ?? (typeof window !== 'undefined' ? window.location : undefined);
+  const renderMode = renderModeLocation !== undefined && isRenderModeRequested(renderModeLocation);
   let started = false;
   const loop = createGameLoop({
     fixedTimestep: 1 / 60,
     maxSubSteps: 8,
+    // Render mode runs the loop in EXTERNAL-DRIVE mode (game-loop.ts, I2):
+    // no RAF is ever armed, so nothing advances gameplay between the capture
+    // host's explicit `simulateSubsteps`/`renderOnce` calls — wall-clock time
+    // passing while a screenshot is taken must not move the world.
+    externalDrive: renderMode,
     update: (dt) => {
       if (started) game.runFrame(dt);
       for (const fn of extraUpdaters) fn(dt);
@@ -942,6 +1028,16 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
   // purely to keep this function's own cyclomatic complexity down.
   const retractDevGlobals = installDefaultWorldDevGlobals(game);
 
+  // G3/FT-11 — publish `window.__vgaiRender` for the deterministic capture
+  // host. Installed at the TAIL of the mount (same position as
+  // mount-manifest.ts's debug bridge): every world's `mount()`/`setup()` has
+  // resolved by now, so the harness's `scene` readiness hook reporting ready
+  // is truthful. See `installSessionRenderHarness` below.
+  const retractRenderHarness =
+    renderMode && renderModeLocation !== undefined
+      ? installSessionRenderHarness(game, renderModeLocation, config.renderControl?.target)
+      : undefined;
+
   function fullCleanup(): void {
     loop.stop();
     router.dispose();
@@ -964,6 +1060,7 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
     }
     game.dispose();
     retractDevGlobals();
+    retractRenderHarness?.();
   }
 
   return {

package/src/runtime/game.ts

@@ -1262,7 +1262,17 @@ export function createGame(opts: {
       // "no state bridge" warning at registration (probe: every real react
       // world mount), eroding the signal for a genuinely un-observable
       // ingested world.
-      if (!isFirstPartyMounted(world.mounted) && world.kind !== 'react' && !world.mounted.observe) {
+      // A mount exposing the engine's real ComponentManager (notably the R3F
+      // first-party adapter) is observable through Game.queryByComponent +
+      // Game.state even though it does not carry the classic scene adapter's
+      // `firstParty` brand. Requiring a foreign-world `observe` bridge there
+      // produces a false warning while the canonical bridge is already live.
+      if (
+        !isFirstPartyMounted(world.mounted) &&
+        !world.mounted.components &&
+        world.kind !== 'react' &&
+        !world.mounted.observe
+      ) {
         console.warn(
           `[game] world "${world.id}" (kind: ${world.kind}, adapter: "${world.adapter.id}"): ` +
             'no state bridge — this mounted game has no `observe` (WorldStateObserver); ' +

package/src/scene/asset-ref-check.ts

@@ -189,7 +189,7 @@ function formatIssues(issues: { path: PropertyKey[]; message: string }[]): strin
  * structured errors (empty = every new reference resolved and validated) —
  * never throws; callers decide how to present/escalate a non-empty result
  * (the CLI folds these into one `ApplyDiffCliError` message, the SDK raises
- * a declared `ASSET_REF_INVALID` `OperationError`).
+ * a declared `ASSET_REF_INVALID` `ToolError`).
  */
 export function dereferenceNewAssetRefs(
   inputScene: SceneFile,

package/src/scene/scene-loader.ts

@@ -1,6 +1,6 @@
 import type RAPIER from '@dimforge/rapier3d-compat';
 import * as THREE from 'three';
-import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
+import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';
 import type { BatchedRenderer } from 'three.quarks';
 import { initNavigation, NavMeshManager } from '../ai/navigation';
 import { buildClipMap } from '../animation/clip-map';
@@ -148,7 +148,7 @@ async function loadEnvTexture(
     const ext = path.split('.').pop()?.toLowerCase();
     const rawTexture =
       ext === 'hdr'
-        ? await new RGBELoader(loadingManager).loadAsync(resolveUrl(path))
+        ? await new HDRLoader(loadingManager).loadAsync(resolveUrl(path))
         : await new THREE.TextureLoader(loadingManager).loadAsync(resolveUrl(path));
     rawTexture.mapping = THREE.EquirectangularReflectionMapping;
     const envMap = pmremGenerator.fromEquirectangular(rawTexture).texture;

package/src/scene/user-data.ts

@@ -73,6 +73,16 @@
  *                           surfaced in the play-mode hierarchy with a *synthetic*
  *                           descriptor (it has no `.vscn` record). Marks it as
  *                           ephemeral: selectable/movable for testing, never saved.
+ * - `authoringRoot`       — explicit opt-in for a runtime descendant to become
+ *                           its own authoring object instead of a part of the
+ *                           nearest ancestor owner.
+ * - `authoringInstance`   — source OID of the custom-component callsite that
+ *                           rendered this existing Object3D. Used to group
+ *                           implementation parts without adding wrappers.
+ * - `authoringLabel`      — authored literal name (or component tag fallback)
+ *                           for that source-backed component instance.
+ * - `behaviorType`        — registry key on the compatibility R3F Behavior
+ *                           attachment group; authoring projects it as a component.
  * - `editorHelper`        — `true` for editor-only helper objects (gizmos, wireframes).
  * - `editorHelperType`    — which kind of helper (lights/particles/pivot/navmesh/...).
  * - `editorIcon`          — `true` for editor billboard icon sprites.
@@ -145,6 +155,10 @@ export interface UserDataSchema {
   __ingestNextId: number;
   engineInternal: boolean;
   liveObject: boolean;
+  authoringRoot: boolean;
+  authoringInstance: string;
+  authoringLabel: string;
+  behaviorType: string;
   editorHelper: boolean;
   editorHelperType: EditorHelperType;
   editorIcon: boolean;
@@ -190,6 +204,10 @@ export const UserDataKeys = {
   __ingestNextId: '__ingestNextId',
   engineInternal: 'engineInternal',
   liveObject: 'liveObject',
+  authoringRoot: 'authoringRoot',
+  authoringInstance: 'authoringInstance',
+  authoringLabel: 'authoringLabel',
+  behaviorType: 'behaviorType',
   editorHelper: 'editorHelper',
   editorHelperType: 'editorHelperType',
   editorIcon: 'editorIcon',

package/src/world3d-react/behavior.tsx

@@ -22,12 +22,11 @@
  *    byte-identical to an un-wrapped mesh. `cloneElement` would have to
  *    merge a ref without clobbering an authored one — fragile across
  *    forwardRef/ref-as-prop shapes — and adds nothing the group doesn't.
- *  - The wrapper is also the Behavior's OWN presence in the scene graph: it
- *    carries the `<Behavior>` call site's `userData-oid` stamp (fiber
- *    pierces the forwarded dashed prop onto the group's userData), which is
- *    what makes the Behavior node itself selectable/source-addressable in
- *    the editor hierarchy, with its schema-declared config editable like any
- *    other JSX prop.
+ *  - The wrapper carries the `<Behavior>` call site's `userData-oid` stamp so
+ *    its config stays source-addressable. It is an INTERNAL attachment node,
+ *    not an independent spatial authoring object: the R3F authoring adapter
+ *    projects this config onto the wrapped object's Inspector and promotes
+ *    the child through the hierarchy.
  *  - Transform semantics: the group stays at identity, so the child's
  *    authored `position`/`rotation`/`scale` are unchanged by wrapping.
  *
@@ -43,7 +42,7 @@
 // their fiber import — project entry files importing this module keep their
 // own `@react-three/fiber` import for the scene itself.
 import type { ThreeElements } from '@react-three/fiber';
-import { createElement, useContext, useEffect, useRef } from 'react';
+import { createElement, useContext, useEffect, useLayoutEffect, useRef } from 'react';
 import type { Group } from 'three';
 import type { GameComponent } from '../ecs/game-component';
 import { type BehaviorRegistry, EngineBridge, resolveBehaviorClass } from './engine-bridge';
@@ -70,7 +69,11 @@ export function Behavior<Reg extends BehaviorRegistry = BehaviorRegistry>(
   // The live instance the config-reapply effect targets (never re-attach).
   const liveRef = useRef<GameComponent | null>(null);
 
-  useEffect(() => {
+  // Attachment is part of the committed world, not deferred follow-up work.
+  // A layout effect runs before `createR3FAdapter.mount()` resolves its first
+  // committed tree, so deterministic hosts can begin stepping immediately
+  // without losing every warm-up tick to an unflushed passive effect.
+  useLayoutEffect(() => {
     if (!bridge?.registry) {
       // Loud degrade, never a crash: a mount without the adapter's bridge
       // (e.g. a foreign harness rendering this tree directly) — or a bridge
@@ -123,13 +126,18 @@ export function Behavior<Reg extends BehaviorRegistry = BehaviorRegistry>(
   // OID stamper rewrites JSX syntax only, so a JSX `<group>` here would get
   // behavior.tsx's OWN stamp AND the forwarded call-site oid (a duplicate
   // `userData-oid` attribute). The wrapper group must carry exactly ONE
-  // identity — the `<Behavior>` CALL SITE's oid — so the editor's hierarchy
-  // selects/edits the Behavior element the author actually wrote.
+  // identity — the `<Behavior>` CALL SITE's oid — so the editor can edit the
+  // config while projecting the wrapper as a component of its child.
   return createElement(
     'group',
     {
       ref: groupRef,
-      name: `Behavior:${type}`,
+      // `Behavior: ` WITH the space: the editor's R3F adapter labels this node
+      // `Behavior: ${behaviorType}` when it projects it as an entity, but falls
+      // back to this `name` when the same node is projected as a component
+      // boundary. Without the space the hierarchy showed one of two different
+      // labels for the identical concept depending on which branch ran.
+      name: `Behavior: ${type}`,
       'userData-oid': oid,
       'userData-behaviorType': type,
     },