@vgai/engine 0.5.11 → 0.5.12

package/src/pixi/ingest.ts

@@ -1,88 +1,20 @@
 import { installSceneCapture2D, type SceneCapture2DHandle } from './scene-capture';
 
-/**
- * A manifest's `extraDeps` resolve to TWO kinds of importmap entry:
- * `namespaces` are today's registry-known bare specifiers
- * (host-namespace-registry.ts), re-exported via a blob module
- * (`ingest-iframe-2d.ts`'s `makeHostNamespaceReexportUrl`); `urls` are the
- * D-Z3 fallback — a specifier that isn't registered but IS present in the
- * open project's own `node_modules`, mapped DIRECTLY to its
- * `/project-game-static/node_modules/<spec>/<esm entry>` URL (no host-side
- * import, no blob — the dep executes in the iframe realm and its own
- * transitive `import 'pixi.js'` resolves through the same importmap back to
- * the host pixi trap). All probing/decision logic (which kind a specifier
- * resolves to, exports-map parsing, anti-shim throws) lives editor-side
- * (`host-namespace-registry.ts`) — this engine module only carries the
- * ALREADY-DECIDED shape; `ingest-iframe-2d.ts` stays decision-free and just
- * merges both maps into the iframe importmap.
- */
-export interface ExtraDepsResolution2D {
-  namespaces: Record<string, Record<string, unknown>>;
-  urls: Record<string, string>;
-}
-
 /** A registered unmodified PixiJS game (the Pixi analog of `IngestGame`). */
 export interface IngestGame2D {
   id: string;
   name: string;
   description: string;
-  /** Shared-pixi path: import + run the unmodified game module. */
-  load?: () => Promise<unknown>;
-  /** Tier ceiling: how reachable the game's pixi instance is. */
-  tier?: 'shared' | 'iframe-reachable' | 'opaque-embed';
+  /** Import + run the unmodified game module in the host's own realm. */
+  load: () => Promise<unknown>;
+  /** How long to wait for the game's first captured frame before failing. */
   captureTimeoutMs?: number;
-  /**
-   * IFRAME-REACHABLE-MULTI fields (Track P): an externalized built bundle
-   * mounted via `mountIngestGame2DIframeReachableMulti`
-   * (`./ingest-iframe-2d.ts`) instead of `load()` — populated only when `tier`
-   * is `'iframe-reachable'` AND `load` is absent. Mirror
-   * `IframeReachableMultiOpts`'s fields, EXCEPT `extraDeps`/`pixiNamespace` are
-   * THUNKS here, not resolved values — the same "lazy, only invoked at mount
-   * time" shape `load` already uses, so building this descriptor
-   * (`resolveIngest2DDescriptor` / the canvas surface's
-   * `ingest/surface-canvas.ts`, editor-side — Wave 0.6 replaced the three
-   * per-surface `discovery*.ts` modules with one manifest-driven registry) never
-   * has to be async just to wire up which specifiers/ version-skew URL a game
-   * needs; only actually MOUNTING it (the ingest-mode mount bridge) pays for the
-   * dynamic import of `@pixi/sound`/`gsap`/spine/ a standalone pixi build.
-   */
-  bundleUrl?: string;
-  /** <base href> for the iframe (see `IframeReachableMultiOpts.baseHref`). */
-  baseHref?: string;
-  /** Host-side Assets.init basePath remap (see `IframeReachableMultiOpts.assetBaseUrl`). */
-  assetBaseUrl?: string;
-  /**
-   * Lazily resolve this game's bare-specifier -> extraDeps resolution via the
-   * editor's host-namespace registry. Absent (or omitted) means no extra deps
-   * beyond pixi.js.
-   */
-  extraDeps?: () => Promise<ExtraDepsResolution2D>;
-  /**
-   * Lazily resolve the trapped-pixi namespace for version-skewed games (a
-   * dynamic `import()` of the manifest's `pixiModuleUrl`) — absent means
-   * "mount against the host's own `pixi.js`" (no skew).
-   */
-  pixiNamespace?: () => Promise<unknown>;
-  /** DOM the game expects before boot (see `IframeReachableMultiOpts.bodyHtml`). */
-  bodyHtml?: string;
-  /**
-   * Lazily read an OPAQUE prebuilt bundle's self-contained HTML (D-W2) — the pixi
-   * twin of `IngestGame.embedHtml`. Always a lazy thunk here (no in-tree Pixi
-   * opaque-embed fixture exists yet to need a plain-string form, unlike the three
-   * side): `resolveIngest2DDescriptor` (adapter-resolver.ts) builds one that reads
-   * the declared `entryHtml` file's bytes through the `/project-game-static/`
-   * route, only when the game is actually mounted. The host runs the resolved HTML
-   * in a sandboxed iframe at the embed-only floor (Tier 0-1),
-   * `mountIngestGame2DEmbed` (`./ingest-iframe-2d.ts`).
-   */
-  embedHtml?: () => Promise<string>;
 }
 
 export interface IngestMount2D {
-  /** The captured live stage Container (null if capture failed/degraded). */
-  stage: unknown | null;
+  /** The captured live stage Container. */
+  stage: unknown;
   capture: SceneCapture2DHandle;
-  embedOnly: boolean;
   setPaused(paused: boolean): void;
   dispose(): void;
 }
@@ -91,9 +23,8 @@ export interface IngestMount2D {
  * Mount an UNMODIFIED PixiJS game via the shared-instance capture path — the 2D
  * analog of `mountIngestGame`. Installs the render trap on the host's pixi
  * instance, runs the game's `load()`, waits for the game to render its first
- * frame (capturing its live stage), and exposes loop gating + cleanup. If capture
- * times out (pixi unreachable / bundled / mismatched), degrades to embed-only —
- * never a silent failure.
+ * frame (capturing its live stage), and exposes loop gating + cleanup. A game
+ * whose pixi the trap cannot reach never captures, and the mount FAILS by name.
  */
 export async function mountIngestGame2D(
   pixiNamespace: unknown,
@@ -102,7 +33,7 @@ export async function mountIngestGame2D(
 ): Promise<IngestMount2D> {
   const capture = installSceneCapture2D(pixiNamespace);
   try {
-    await game.load?.();
+    await game.load();
   } catch (err) {
     capture.uninstall();
     throw new Error(`pixi ingest: game "${game.id}" failed to load: ${err}`);
@@ -114,18 +45,13 @@ export async function mountIngestGame2D(
     return {
       stage: rt.stage,
       capture,
-      embedOnly: false,
       setPaused: (p) => capture.setPaused(p),
       dispose: () => capture.uninstall(),
     };
-  } catch {
-    // Capture failed → pixi unreachable/mismatched → degrade to embed-only.
-    return {
-      stage: null,
-      capture,
-      embedOnly: true,
-      setPaused: () => {},
-      dispose: () => capture.uninstall(),
-    };
+  } catch (err) {
+    capture.uninstall();
+    throw new Error(
+      `pixi ingest: game "${game.id}" rendered no capturable frame within ${timeout}ms: ${err}`,
+    );
   }
 }

package/src/pixi/scene-capture.ts

@@ -14,8 +14,8 @@
  * CRITICAL (same module-identity gatekeeper as the 3D path): the trap must be
  * installed on the SAME `pixi.js` module instance the game uses. A bundler/dev-server
  * that dedupes `pixi.js` makes an ESM game's `import 'pixi.js'` resolve to the host
- * instance, so it is trapped; a game bundling its own pixi cannot be captured this
- * way (degrade to iframe-reachable or opaque-embed tiers — see the spec).
+ * instance, so it is trapped; a game bundling its own pixi cannot be captured at
+ * all, and its mount fails by name.
  */
 
 /** A live Pixi runtime captured from an external PixiJS game. */

package/src/react/use-data.ts

@@ -59,11 +59,16 @@ export function useData<T>(handle: DataHandle<T>): T {
  * this rejects with a teaching error (a shipped game could never reach the
  * route anyway — builds strip `src/tools/` entirely, §4).
  *
- * Serialization matches the editor Data panel's diff-minimal contract:
- * `"$schema"` first, 2-space indent, trailing newline. When `value` carries
- * no `"$schema"` key (the common case — `DataHandle.get()` strips it), the
- * conventional sibling reference (`./<name>.schema.json`, §2.1) is restored
- * so a tool write never silently drops VS Code validation from the file.
+ * The body is PARSED VALUES, never serialized text: the dev server's fold
+ * (`packages/editor/server/data-file-serialize.ts`) owns key order and the
+ * `"$schema"`-first diff-minimal serialization, and it must — a parsed JS
+ * object has already reindexed integer-like keys ("1","2","10"), so only the
+ * server, which still has the file's raw text, can keep a one-field write a
+ * one-line diff. When `value` carries no `"$schema"` key (the common case —
+ * `DataHandle.get()` strips it), the conventional sibling reference
+ * (`./<name>.schema.json`, §2.1) is restored so a tool write never silently
+ * drops VS Code validation from the file. Undo for data writes is git;
+ * every accepted write is recorded server-side as a project revision.
  */
 export async function writeData(
   projectRelativePath: string,
@@ -77,9 +82,9 @@ export async function writeData(
     );
   }
 
-  // "$schema" first for minimal diffs; restore the conventional sibling
-  // reference when the caller's object (typically `{ ...handle.get() }`,
-  // which never carries it) omits the line.
+  // Restore the conventional sibling "$schema" reference when the caller's
+  // object (typically `{ ...handle.get() }`, which never carries it) omits
+  // it; the server fold serializes it first.
   const { $schema, ...rest } = value;
   const schemaRef =
     $schema ??
@@ -87,24 +92,14 @@ export async function writeData(
       .split('/')
       .pop()
       ?.replace(/\.data\.json$/, '')}.schema.json`;
-  const content = `${JSON.stringify({ $schema: schemaRef, ...rest }, null, 2)}\n`;
-
-  const transactionalWriter = (
-    globalThis as typeof globalThis & {
-      __vgaiHistoryWriteData?: (path: string, content: string) => Promise<void>;
-    }
-  ).__vgaiHistoryWriteData;
-  if (transactionalWriter) {
-    await transactionalWriter(projectRelativePath, content);
-    return;
-  }
+  const values = { $schema: schemaRef, ...rest };
 
   let res: Response;
   try {
     res = await fetch('/__editor/data-file', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ path: projectRelativePath, content }),
+      body: JSON.stringify({ path: projectRelativePath, values }),
     });
   } catch (err) {
     throw new Error(

package/src/render/viewport-shading.ts

@@ -1,9 +1,10 @@
 import * as THREE from 'three';
 
 /** Temporary developer-facing shading modes. These never become scene data. */
-export type ViewportShadingMode = 'solid' | 'unlit' | 'wireframe' | 'normals' | 'overdraw';
+export type ViewportShadingMode = 'solid' | 'clay' | 'unlit' | 'wireframe' | 'normals' | 'overdraw';
 
 type MaterialPair = {
+  clay: THREE.MeshStandardMaterial;
   unlit: THREE.MeshBasicMaterial;
   wireframe: THREE.MeshBasicMaterial;
 };
@@ -73,6 +74,7 @@ export class ViewportShadingRenderer {
 
   dispose(): void {
     for (const pair of this._derived.values()) {
+      pair.clay.dispose();
       pair.unlit.dispose();
       pair.wireframe.dispose();
     }
@@ -106,6 +108,19 @@ export class ViewportShadingRenderer {
         fog: (material as THREE.Material & { fog?: boolean }).fog ?? true,
       };
       pair = {
+        clay: new THREE.MeshStandardMaterial({
+          color: 0xaeb6c0,
+          roughness: 0.82,
+          metalness: 0,
+          flatShading: true,
+          alphaMap: textureOf(material, 'alphaMap'),
+          alphaTest: material.alphaTest,
+          opacity: material.opacity,
+          transparent: material.transparent,
+          side: material.side,
+          depthTest: material.depthTest,
+          depthWrite: material.depthWrite,
+        }),
         unlit: new THREE.MeshBasicMaterial(common),
         wireframe: new THREE.MeshBasicMaterial({ ...common, wireframe: true }),
       };

package/src/runtime/create-runtime.ts

@@ -280,6 +280,18 @@ export interface RootsRuntimeConfig {
    * a 2D canvas renderer with no GPU. Never set `true` in a real host.
    */
   headless?: boolean | undefined;
+  /**
+   * `vgai.project.json`'s `rendering.antialias` — whether every three root's
+   * WebGL context is built with a multisampled drawing buffer.
+   *
+   * It is a RUNTIME-CONFIG option rather than a world's own
+   * `WorldRendererConfig` field for the reason that file's header gives: a
+   * context's sample count is fixed at CREATION, before any world exists, so
+   * there is no honest moment at which a world could ask for it. The
+   * manifest-aware boot path (`mount-manifest.ts`) is the real reader;
+   * omitting it leaves `createHostRenderer`'s own registry default alone.
+   */
+  antialias?: boolean | undefined;
   /** D15 (T-D15.1) — the root seed `ctx.random` boots from on every world
    *  mounted onto this session's Game, forwarded to `createGame` BEFORE any
    *  world's `mount()`/`setup()` runs (this function constructs the Game
@@ -414,6 +426,9 @@ interface OneRootContext {
   readonly dpr: number;
   readonly isBottom: boolean;
   readonly headless: boolean;
+  /** `RootsRuntimeConfig.antialias` — see that field. Undefined leaves
+   *  `createHostRenderer`'s own registry default alone. */
+  readonly antialias: boolean | undefined;
   readonly assets: ReturnType<typeof createAssetCache>;
 }
 
@@ -425,13 +440,22 @@ async function mountOneThreeRoot(
   spec: ThreeRootMountSpec,
   ctx: OneRootContext,
 ): Promise<OneRootResult> {
-  const { game, canvas, w, h, dpr, isBottom, headless, assets } = ctx;
+  const { game, canvas, w, h, dpr, isBottom, headless, assets, antialias } = ctx;
   const renderer = headless
     ? createHeadlessRendererStub()
-    : createHostRenderer(canvas, w, h, undefined, {
-        alpha: !isBottom,
-        preserveDrawingBuffer: true,
-      });
+    : createHostRenderer(
+        canvas,
+        w,
+        h,
+        // The manifest's `rendering.antialias` reaches the WebGL context here and NOWHERE else:
+        // `createHostRenderer` passes it straight to the constructor, and the sample count is
+        // fixed from that moment. Omitted → the render-settings registry's own default.
+        antialias === undefined ? undefined : { antialias },
+        {
+          alpha: !isBottom,
+          preserveDrawingBuffer: true,
+        },
+      );
   renderer.setSize(w, h, false); // backing resolution only — CSS stacking owns layout size
   // Defect E4.R1 (Fable review): `createHostRenderer`'s OWN construction-time
   // `setSize` call (`setup-renderer.ts`, `updateStyle` defaulting `true` —
@@ -896,6 +920,7 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
     dpr,
     headless,
     assets,
+    antialias: config.antialias,
   });
 
   // --- Delegating input router (D5 §2a) ---

package/src/runtime/mount-game.ts

@@ -56,7 +56,7 @@ export interface ManifestHost {
   /** Resolve asset/scene URLs relative to the project — forwarded to a
    *  registered {@link AdapterSurfaceFactory} via {@link AdapterSurfaceFactoryContext},
    *  never called by this module itself (a factory only needs it for a
-   *  non-default resolution scheme, e.g. a hosted-editor iframe). */
+   *  non-default resolution scheme, e.g. a project served under a base path). */
   resolveUrl?(path: string): string;
   readonly width?: number | undefined;
   readonly height?: number | undefined;

package/src/runtime/mount-manifest.ts

@@ -276,7 +276,7 @@ function resolveThreeAdapter(
     throw new Error(
       `mountManifestRoots: world "${world.id}" (three) declares an { ingest } adapter — ` +
         "ingest roots require the editor's dev-server-backed mount machinery (an EditorStore " +
-        "plus iframe/DOM capture, see adapter-resolver.ts's resolveIngestThreeAdapter) and are " +
+        "plus in-realm scene capture, see adapter-resolver.ts's resolveIngestThreeAdapter) and are " +
         'not supported by mountManifestRoots (no porting aids, no hosted ingest routes).',
     );
   }
@@ -442,6 +442,10 @@ export async function mountManifestRoots(opts: MountManifestOptions): Promise<Ga
     width: opts.width ?? manifest.resolution?.width,
     height: opts.height ?? manifest.resolution?.height,
     headless: opts.headless,
+    // `rendering.antialias` reaches the WebGL context at CONSTRUCTION and can be honoured
+    // nowhere else — see the manifest schema's own `rendering` block and
+    // `world3d-react/renderer-config.ts`'s header for why it is not a world-level declaration.
+    ...(manifest.rendering === undefined ? {} : { antialias: manifest.rendering.antialias }),
     seed: resolvedSeed,
     playtest: opts.playtest,
   });

package/src/world3d-react/r3f-adapter.tsx

@@ -29,7 +29,14 @@ import {
 import { createElement, type ReactNode } from 'react';
 import type { MountedThreeRoot, RootAdapter, ThreeHostContext } from '../adapter';
 import { type RenderVitalsRegistration, registerRenderVitals } from '../dev/register-render-vitals';
+import {
+  createRenderDebugAdapter,
+  frameCaptureContextFor,
+  type RenderDebugWiring,
+} from '../dev/render-debug-adapter';
+import { collectRenderMemory } from '../dev/render-memory';
 import { RENDER_SUBMIT_PHASE } from '../dev/render-vitals';
+import { createWebGLFrameCapture } from '../dev/webgl-frame-capture';
 import { WorldProvider } from '../react/world-state';
 import { devLayersEnabled } from '../runtime/dev-layers';
 import { EngineBridge, type EngineBridgeValue } from './engine-bridge';
@@ -395,6 +402,26 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
         });
       }
 
+      // Engine-owned render introspection, built over the SAME renderer and
+      // scene Fiber uses. A design-time stand-in has no context and a
+      // headless mount returned above, so both honestly omit the capability.
+      // `frameCaptureContextFor` is the same construction gate as the classic
+      // Three adapter; no editor-side renderer inference is involved.
+      const rendererContext =
+        typeof host.renderer.getContext === 'function' ? host.renderer.getContext() : undefined;
+      const frameCaptureContext = frameCaptureContextFor(false, rendererContext);
+      const frameCapture = frameCaptureContext
+        ? createWebGLFrameCapture(frameCaptureContext)
+        : null;
+      const renderDebugWiring: RenderDebugWiring | null = frameCapture
+        ? createRenderDebugAdapter({
+            capture: frameCapture,
+            scene: state.scene,
+            memory: () => collectRenderMemory(live().scene, host.renderer.info),
+          })
+        : null;
+      if (renderDebugWiring) runtime.systemAdapters.renderDebug = renderDebugWiring.adapter;
+
       // The engine drives every `useFrame` through the mounted world's
       // `update(dt)` hook, never off a raw host-loop callback. That is the
       // whole pause story: `runFrameImpl` (`runtime/game.ts`) calls
@@ -447,9 +474,10 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           return live().camera;
         },
         drivesOwnLoop: false,
-        // Adapter surface: `debug` pre-seeded (the shared game registry's
-        // adapter); game code adds capabilities via
-        // `ctx.registerSystemAdapter` exactly as in a classic world.
+        // Adapter surface: `debug` (the shared game registry) and, when a real
+        // WebGL2 context exists, `renderDebug` are engine-seeded. Game code
+        // adds its own capabilities via `ctx.registerSystemAdapter` exactly
+        // as in a classic world.
         systems: runtime.systemAdapters,
         update(dt: number): void {
           elapsed += dt;
@@ -467,50 +495,56 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           // then fiber's advance (useFrame callbacks + the actual render see
           // the fresh state). Both are host-gated: neither runs while frozen.
           systems.run(dt);
-          const profiler = host.game?.profiler;
-          if (!profiler?.enabled) {
-            advance(elapsed, true, current);
-            return;
-          }
-          // Issue #1504's measurement, produced where the draw actually
-          // happens. `advance()` under `frameloop: 'never'` is what calls
-          // `gl.render(scene, camera)`, so this bracket — not a phase span
-          // inside `systems` — is the frame's CPU submission cost, and it is
-          // also what makes this frame a PRESENTATION as far as the vitals
-          // fold is concerned (`../dev/render-vitals.ts`: no bracket, no
-          // display frame). The profiler's phase clock is a stack, so
-          // bracketing here cannot truncate an enclosing phase.
-          const info = host.renderer.info as RendererCounters | undefined;
-          const passesBefore = info?.render.frame ?? 0;
-          profiler.beginPhase();
+          renderDebugWiring?.beforeRender();
           try {
-            advance(elapsed, true, current);
+            const profiler = host.game?.profiler;
+            if (!profiler?.enabled) {
+              advance(elapsed, true, current);
+              return;
+            }
+            // Issue #1504's measurement, produced where the draw actually
+            // happens. `advance()` under `frameloop: 'never'` is what calls
+            // `gl.render(scene, camera)`, so this bracket — not a phase span
+            // inside `systems` — is the frame's CPU submission cost, and it is
+            // also what makes this frame a PRESENTATION as far as the vitals
+            // fold is concerned (`../dev/render-vitals.ts`: no bracket, no
+            // display frame). The profiler's phase clock is a stack, so
+            // bracketing here cannot truncate an enclosing phase.
+            const info = host.renderer.info as RendererCounters | undefined;
+            const passesBefore = info?.render.frame ?? 0;
+            profiler.beginPhase();
+            try {
+              advance(elapsed, true, current);
+            } finally {
+              profiler.endPhase(RENDER_SUBMIT_PHASE);
+            }
+            // Checked, not assumed — a duck-typed/design-time renderer supplies
+            // only what a mount needs, and a mount with no counters must report
+            // NOTHING rather than throw once per frame (the classic adapter's
+            // `postFrame` pays for the same assumption for the same reason).
+            // `gpuMs` is null: this path runs no GPU timer, and the profiler
+            // keeps the previous reading rather than inventing a zero.
+            if (info) {
+              profiler.reportRender({
+                gpuMs: null,
+                drawCalls: info.render.calls,
+                triangles: info.render.triangles,
+                geometries: info.memory.geometries,
+                textures: info.memory.textures,
+                renderPasses: info.render.frame - passesBefore,
+              });
+            }
           } finally {
-            profiler.endPhase(RENDER_SUBMIT_PHASE);
-          }
-          // Checked, not assumed — a duck-typed/design-time renderer supplies
-          // only what a mount needs, and a mount with no counters must report
-          // NOTHING rather than throw once per frame (the classic adapter's
-          // `postFrame` pays for the same assumption for the same reason).
-          // `gpuMs` is null: this path runs no GPU timer, and the profiler
-          // keeps the previous reading rather than inventing a zero.
-          if (info) {
-            profiler.reportRender({
-              gpuMs: null,
-              drawCalls: info.render.calls,
-              triangles: info.render.triangles,
-              geometries: info.memory.geometries,
-              textures: info.memory.textures,
-              renderPasses: info.render.frame - passesBefore,
-            });
+            renderDebugWiring?.afterRender();
           }
         },
         resize(width: number, height: number): void {
           live().setSize(width, height);
         },
         dispose(): void {
-          // Unmount FIRST so component effect cleanups run, then tear the
-          // runtime down (scoped debug-registry strip).
+          // Reject/restore a pending capture while its renderables still
+          // exist, then unmount component effects and strip runtime state.
+          renderDebugWiring?.dispose();
           root.unmount();
           // The vitals fold owns two `profiler.subscribe` registrations, and
           // `runtime.dispose()`'s `strip(id)` removes the REGISTRATIONS only —

package/src/world3d-react/renderer-config.ts

@@ -47,11 +47,27 @@ export type WorldToneMapping =
  */
 export type WorldOutputColorSpace = 'srgb' | 'srgb-linear';
 
+/**
+ * The shadow-map filter, named as data rather than as three's numeric enum.
+ *
+ * This is a renderer INSTANCE property (`WebGLRenderer.shadowMap.type`), not a context attribute,
+ * so unlike MSAA it has an honest moment at which a world can ask for it — which is the whole test
+ * this file's header states. A source engine that declares its own shadow filter (Godot 3's
+ * `rendering/quality/shadows/filter_mode`) would otherwise inherit whatever the host built with.
+ */
+export type WorldShadowMapType = 'basic' | 'pcf' | 'pcf-soft' | 'vsm';
+
 /** What a world may declare about the renderer that draws it. Every field is optional; see header. */
 export interface WorldRendererConfig {
   readonly toneMapping?: WorldToneMapping | undefined;
   readonly toneMappingExposure?: number | undefined;
   readonly outputColorSpace?: WorldOutputColorSpace | undefined;
+  /**
+   * `WebGLRenderer.shadowMap.type`. Writing it after a shadow map has already been built needs
+   * `shadowMap.needsUpdate`, which this function sets — three caches the compiled depth material
+   * per type and would otherwise keep filtering with the previous one.
+   */
+  readonly shadowMapType?: WorldShadowMapType | undefined;
   /**
    * The colour the frame is cleared to, as a CSS hex string. The renderer's existing clear ALPHA
    * is preserved: a stacked canvas is transparent on purpose (`create-runtime.ts` gives every
@@ -95,6 +111,12 @@ export function applyWorldRendererConfig(
     srgb: three.SRGBColorSpace,
     'srgb-linear': three.LinearSRGBColorSpace,
   };
+  const shadowMapTypes: Record<WorldShadowMapType, THREE.ShadowMapType> = {
+    basic: three.BasicShadowMap,
+    pcf: three.PCFShadowMap,
+    'pcf-soft': three.PCFSoftShadowMap,
+    vsm: three.VSMShadowMap,
+  };
 
   const restores: (() => void)[] = [];
 
@@ -119,6 +141,15 @@ export function applyWorldRendererConfig(
       renderer.outputColorSpace = previous;
     });
   }
+  if (config.shadowMapType !== undefined && renderer.shadowMap !== undefined) {
+    const previous = renderer.shadowMap.type;
+    renderer.shadowMap.type = shadowMapTypes[config.shadowMapType];
+    renderer.shadowMap.needsUpdate = true;
+    restores.push(() => {
+      renderer.shadowMap.type = previous;
+      renderer.shadowMap.needsUpdate = true;
+    });
+  }
   if (config.clearColor !== undefined) {
     const previousColor = new three.Color();
     renderer.getClearColor(previousColor);

package/src/world3d-react/world-context.ts

@@ -130,7 +130,8 @@ export interface R3FRootRuntime {
   /** The world-local phase runner `mount().update(dt)` ticks. */
   readonly systems: ReturnType<typeof createSystemRunner>;
   /** The mounted world's `SystemAdapters` bag (`mounted.systems`) —
-   *  `ctx.registerSystemAdapter` writes into it; `debug` is pre-seeded. */
+   *  `ctx.registerSystemAdapter` writes into it; `debug` is pre-seeded here,
+   *  and the R3F mount adds renderer-backed engine capabilities after commit. */
   readonly systemAdapters: SystemAdapters;
   /** The registry every registration of this world's lands in — the game's
    *  own when a `Game` hosts it, a private mount-local one otherwise. Exposed

package/dist/asset-formats/instances.d.ts

@@ -1,17 +0,0 @@
-import { z } from 'zod';
-/**
- * `.instances.json` — a declarative, authored-data instance-transform asset
- * (F3). Referenced by `mesh.instances` as a bare array of 10-number tuples,
- * one per instance, each `[posX,posY,posZ, quatX,quatY,quatZ,quatW,
- * scaleX,scaleY,scaleZ]`. The scene loader fetches+parses this file and
- * renders it as one `THREE.InstancedMesh` (one draw call) — bulk transform
- * data is referenced as an asset, never inlined into the referencing
- * document (gate G4).
- *
- * WO-8: the document that referenced it was `.vscn.json`, and that format is
- * deleted. `.instances.json` survives as a FETCHED-ASSET format with its own
- * `parseInstancesFile` — nothing in the shipped tree references one today.
- */
-export declare const InstancesFileSchema: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
-export type InstancesFile = z.infer<typeof InstancesFileSchema>;
-//# sourceMappingURL=instances.d.ts.map

package/dist/asset-formats/instances.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../src/asset-formats/instances.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,kKAoB7B,CAAC;AAEJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/asset-formats/instances.js

@@ -1,31 +0,0 @@
-import { z } from 'zod';
-/**
- * `.instances.json` — a declarative, authored-data instance-transform asset
- * (F3). Referenced by `mesh.instances` as a bare array of 10-number tuples,
- * one per instance, each `[posX,posY,posZ, quatX,quatY,quatZ,quatW,
- * scaleX,scaleY,scaleZ]`. The scene loader fetches+parses this file and
- * renders it as one `THREE.InstancedMesh` (one draw call) — bulk transform
- * data is referenced as an asset, never inlined into the referencing
- * document (gate G4).
- *
- * WO-8: the document that referenced it was `.vscn.json`, and that format is
- * deleted. `.instances.json` survives as a FETCHED-ASSET format with its own
- * `parseInstancesFile` — nothing in the shipped tree references one today.
- */
-export const InstancesFileSchema = z
-    .array(z.tuple([
-    z.number().describe('posX'),
-    z.number().describe('posY'),
-    z.number().describe('posZ'),
-    z.number().describe('quatX'),
-    z.number().describe('quatY'),
-    z.number().describe('quatZ'),
-    z.number().describe('quatW'),
-    z.number().describe('scaleX'),
-    z.number().describe('scaleY'),
-    z.number().describe('scaleZ'),
-]))
-    .describe('Instance-transform asset (.instances.json): an array of 10-number tuples ' +
-    '[posX,posY,posZ, quatX,quatY,quatZ,quatW, scaleX,scaleY,scaleZ], one per instance. ' +
-    'Referenced by a mesh via `mesh.instances` and rendered as a single THREE.InstancedMesh ' +
-    '(one draw call).');

package/dist/asset-formats/parse.d.ts

@@ -1,20 +0,0 @@
-import { AssetParseError } from '../asset-parse-error';
-import type { InstancesFile } from './instances';
-import type { MaterialFile } from './material';
-export { AssetParseError };
-/**
- * Parse a `.mat.json` shared material asset (T4.6). There is no version-range
- * gate for this format — `MaterialFileSchema`'s `version` field is RESERVED
- * (see `schema-consumption-map.ts`).
- *
- * Formerly `@engine/scene/parse`'s `parseMaterialFile`; moved here when WO-8
- * deleted the `.vscn` scene format that module was named for.
- */
-export declare function parseMaterialFile(json: unknown, filePath?: string): MaterialFile;
-/**
- * Parse a `.instances.json` instance-transform asset (F3). Mirrors
- * `parseMaterialFile` exactly — no version-range gate (the format is a bare
- * tuple array, no `version` field).
- */
-export declare function parseInstancesFile(json: unknown, filePath?: string): InstancesFile;
-//# sourceMappingURL=parse.d.ts.map

package/dist/asset-formats/parse.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/asset-formats/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM/C,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,CAMhF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,aAAa,CAMlF"}