@vgai/engine 0.5.4 → 0.5.6

package/dist/render/render-features.js

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+export const RENDER_FEATURES = [
+    {
+        key: 'autoBatch',
+        label: 'Auto-batching',
+        description: 'Automatically batch entities sharing geometry+material into one draw call (InstancedMesh/BatchedMesh) while keeping each Object3D as the handle. The headline perf win; opt out per-entity for custom-shader/skinned meshes.',
+        kind: 'toggle',
+        default: true,
+        apply: 'live',
+        perEntity: true,
+    },
+    {
+        key: 'frustumCulling',
+        label: 'Frustum culling',
+        description: 'Per-instance frustum culling for batched content.',
+        kind: 'toggle',
+        default: true,
+        apply: 'live',
+        perEntity: true,
+    },
+    {
+        key: 'lod',
+        label: 'Level of detail',
+        description: 'Distance-based geometry swap (LOD) for eligible entities.',
+        kind: 'toggle',
+        default: true,
+        apply: 'live',
+        perEntity: true,
+    },
+    {
+        key: 'shadows',
+        label: 'Shadows',
+        description: 'Enable the shadow map. Per-entity cast/receive still applies.',
+        kind: 'toggle',
+        default: true,
+        apply: 'live',
+        perEntity: true,
+    },
+    {
+        key: 'postProcessing',
+        label: 'Post-processing',
+        description: 'Master switch for the post-processing stack (individual effects nest beneath it).',
+        kind: 'toggle',
+        default: true,
+        apply: 'live',
+        perEntity: false,
+    },
+    {
+        key: 'resolutionScale',
+        label: 'Resolution scale',
+        description: 'Device-pixel-ratio multiplier (1.0 = native). The cheapest perf dial.',
+        kind: 'number',
+        default: 1,
+        apply: 'live',
+        perEntity: false,
+        range: [0.25, 2],
+    },
+    {
+        key: 'antialias',
+        label: 'Antialiasing',
+        description: 'MSAA via renderer construction. Applies on reload (renderer re-init).',
+        kind: 'toggle',
+        default: true,
+        apply: 'reload',
+        perEntity: false,
+    },
+    {
+        key: 'backend',
+        label: 'Renderer backend',
+        description: 'GPU backend: auto picks WebGPU when available, else WebGL2. Applies on reload.',
+        kind: 'enum',
+        default: 'auto',
+        apply: 'reload',
+        perEntity: false,
+        options: ['auto', 'webgl', 'webgpu'],
+    },
+];
+/** Map for O(1) lookup by key. */
+export const RENDER_FEATURE_BY_KEY = new Map(RENDER_FEATURES.map((f) => [f.key, f]));
+/**
+ * Build a Zod object for the render settings, derived from the registry so the
+ * schema can never drift from the feature list. All fields optional — absence
+ * means "inherit" in the cascade. `perEntityOnly` builds the per-entity override
+ * schema (only features whose `perEntity` is true).
+ */
+export function buildRenderingZod(opts = {}) {
+    const shape = {};
+    for (const f of RENDER_FEATURES) {
+        if (opts.perEntityOnly && !f.perEntity)
+            continue;
+        let base;
+        if (f.kind === 'toggle')
+            base = z.boolean();
+        else if (f.kind === 'number')
+            base = z.number();
+        else
+            base = z.enum(f.options);
+        shape[f.key] = base.optional().describe(f.description);
+    }
+    return z
+        .object(shape)
+        .describe(opts.perEntityOnly
+        ? 'Per-entity render overrides (omit a field to inherit from the scene/engine default)'
+        : 'Scene render settings (omit a field to inherit the engine default)');
+}

package/dist/render/render-settings.d.ts

@@ -0,0 +1,35 @@
+import { type RenderFeatureValue } from './render-features';
+/**
+ * Cascade resolution for render settings: engine default → scene → entity, with
+ * tri-state inherit (an absent value inherits from the next level up)..
+ */
+/** A partial override map (scene-level or entity-level). Absent key = inherit. */
+export type RenderScope = Partial<Record<string, RenderFeatureValue>>;
+/** Fully-resolved settings: every registry key present. */
+export type ResolvedRenderSettings = Record<string, RenderFeatureValue>;
+/**
+ * Resolve effective settings. `entity` overrides only apply to features whose
+ * `perEntity` flag is set; non-per-entity features resolve across engine→scene
+ * only. `??` walks up the chain on `undefined` (inherit) but lets an explicit
+ * `false`/`0` override (they are not nullish).
+ */
+export declare function resolveRenderSettings(scene?: RenderScope, entity?: RenderScope): ResolvedRenderSettings;
+/**
+ * A small observable holding the live scene-level resolved settings. Live
+ * features re-apply when a value changes (subscribers are notified with the
+ * changed key). This is the seam a future player-facing graphics menu would
+ * drive — for now it backs the editor toggles + the runtime systems.
+ */
+export declare class RenderSettings {
+    private values;
+    private listeners;
+    constructor(scene?: RenderScope);
+    get(key: string): RenderFeatureValue;
+    /** Set a scene-level value; notifies subscribers if it changed. */
+    set(key: string, value: RenderFeatureValue): void;
+    /** Resolve the effective value for an entity (entity override → scene → default). */
+    forEntity(key: string, entity?: RenderScope): RenderFeatureValue;
+    subscribe(fn: (key: string, value: RenderFeatureValue) => void): () => void;
+    snapshot(): ResolvedRenderSettings;
+}
+//# sourceMappingURL=render-settings.d.ts.map

package/dist/render/render-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-settings.d.ts","sourceRoot":"","sources":["../../src/render/render-settings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE7E;;;GAGG;AAEH,kFAAkF;AAClF,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;AAEtE,2DAA2D;AAC3D,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAExE;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,CAAC,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,WAAW,GACnB,sBAAsB,CAOxB;AAED;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,SAAS,CAA+D;gBAEpE,KAAK,CAAC,EAAE,WAAW;IAI/B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB;IAIpC,mEAAmE;IACnE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI;IAMjD,qFAAqF;IACrF,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,kBAAkB;IAKhE,SAAS,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAAG,MAAM,IAAI;IAK3E,QAAQ,IAAI,sBAAsB;CAGnC"}

package/dist/render/render-settings.js

@@ -0,0 +1,51 @@
+import { RENDER_FEATURES } from './render-features';
+/**
+ * Resolve effective settings. `entity` overrides only apply to features whose
+ * `perEntity` flag is set; non-per-entity features resolve across engine→scene
+ * only. `??` walks up the chain on `undefined` (inherit) but lets an explicit
+ * `false`/`0` override (they are not nullish).
+ */
+export function resolveRenderSettings(scene, entity) {
+    const out = {};
+    for (const f of RENDER_FEATURES) {
+        const entityVal = f.perEntity ? entity?.[f.key] : undefined;
+        out[f.key] = entityVal ?? scene?.[f.key] ?? f.default;
+    }
+    return out;
+}
+/**
+ * A small observable holding the live scene-level resolved settings. Live
+ * features re-apply when a value changes (subscribers are notified with the
+ * changed key). This is the seam a future player-facing graphics menu would
+ * drive — for now it backs the editor toggles + the runtime systems.
+ */
+export class RenderSettings {
+    values;
+    listeners = new Set();
+    constructor(scene) {
+        this.values = resolveRenderSettings(scene);
+    }
+    get(key) {
+        return this.values[key];
+    }
+    /** Set a scene-level value; notifies subscribers if it changed. */
+    set(key, value) {
+        if (this.values[key] === value)
+            return;
+        this.values[key] = value;
+        for (const fn of this.listeners)
+            fn(key, value);
+    }
+    /** Resolve the effective value for an entity (entity override → scene → default). */
+    forEntity(key, entity) {
+        const f = entity?.[key];
+        return f ?? this.values[key];
+    }
+    subscribe(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    snapshot() {
+        return { ...this.values };
+    }
+}

package/dist/render/spark-renderer-lifecycle.d.ts

@@ -0,0 +1,18 @@
+import type { SparkRenderer } from '@sparkjsdev/spark';
+import type * as THREE from 'three';
+export declare const SPARK_DISCOVERY_INTERVAL_MS = 500;
+/** Gate fallback discovery so ordinary non-splat scenes are never traversed every frame. */
+export declare function shouldDiscoverGaussianSplat(lastCheckAt: number, now: number): boolean;
+/** True when a native scene currently contains at least one Gaussian payload. */
+export declare function sceneHasGaussianSplat(scene: THREE.Object3D): boolean;
+/**
+ * Stop and dispose Spark after its asynchronous depth-sort worker is idle.
+ *
+ * SparkRenderer.dispose() rejects any worker calls still in flight. Spark's
+ * automatic update path intentionally does not await those calls, so disposing
+ * synchronously during an editor stop otherwise produces an unhandled
+ * `Worker terminate` rejection. Disable future work immediately, then release
+ * the renderer once the current sort has naturally settled.
+ */
+export declare function disposeSparkRendererWhenIdle(renderer: SparkRenderer): void;
+//# sourceMappingURL=spark-renderer-lifecycle.d.ts.map

package/dist/render/spark-renderer-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spark-renderer-lifecycle.d.ts","sourceRoot":"","sources":["../../src/render/spark-renderer-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAKpC,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C,4FAA4F;AAC5F,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAErF;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,GAAG,OAAO,CAMpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAgC1E"}

package/dist/render/spark-renderer-lifecycle.js

@@ -0,0 +1,57 @@
+import { hasUserData } from '../ecs/user-data';
+const IDLE_POLL_MS = 16;
+const MAX_IDLE_WAIT_MS = 3_000;
+export const SPARK_DISCOVERY_INTERVAL_MS = 500;
+/** Gate fallback discovery so ordinary non-splat scenes are never traversed every frame. */
+export function shouldDiscoverGaussianSplat(lastCheckAt, now) {
+    return now - lastCheckAt >= SPARK_DISCOVERY_INTERVAL_MS;
+}
+/** True when a native scene currently contains at least one Gaussian payload. */
+export function sceneHasGaussianSplat(scene) {
+    let found = false;
+    scene.traverse((object) => {
+        if (!found && hasUserData(object, 'gaussianSplat'))
+            found = true;
+    });
+    return found;
+}
+/**
+ * Stop and dispose Spark after its asynchronous depth-sort worker is idle.
+ *
+ * SparkRenderer.dispose() rejects any worker calls still in flight. Spark's
+ * automatic update path intentionally does not await those calls, so disposing
+ * synchronously during an editor stop otherwise produces an unhandled
+ * `Worker terminate` rejection. Disable future work immediately, then release
+ * the renderer once the current sort has naturally settled.
+ */
+export function disposeSparkRendererWhenIdle(renderer) {
+    renderer.autoUpdate = false;
+    renderer.sortDirty = false;
+    if (renderer.updateTimeoutId !== -1) {
+        clearTimeout(renderer.updateTimeoutId);
+        renderer.updateTimeoutId = -1;
+    }
+    if (renderer.sortTimeoutId !== -1) {
+        clearTimeout(renderer.sortTimeoutId);
+        renderer.sortTimeoutId = -1;
+    }
+    let remainingIdleWaitMs = MAX_IDLE_WAIT_MS;
+    const disposeWhenIdle = () => {
+        if (renderer.sorting) {
+            if (remainingIdleWaitMs > 0) {
+                remainingIdleWaitMs -= IDLE_POLL_MS;
+                setTimeout(disposeWhenIdle, IDLE_POLL_MS);
+            }
+            else {
+                // A stuck upstream worker is safer to abandon than to turn a routine
+                // editor stop into an unhandled rejection. Page teardown will reclaim
+                // the worker; normal sorts complete in a few milliseconds.
+                // biome-ignore lint/suspicious/noConsole: This rare upstream worker leak must degrade loudly.
+                console.warn('SparkRenderer did not become idle; skipped worker termination.');
+            }
+            return;
+        }
+        renderer.dispose();
+    };
+    disposeWhenIdle();
+}

package/dist/render/viewport-shading.d.ts

@@ -0,0 +1,17 @@
+import * as THREE from 'three';
+/** Temporary developer-facing shading modes. These never become scene data. */
+export type ViewportShadingMode = 'solid' | 'unlit' | 'wireframe' | 'normals' | 'overdraw';
+/**
+ * Applies a render-only material view and restores every native material in a
+ * `finally` block. Gameplay and authoring therefore always observe the real
+ * materials; only renderer work inside {@link render} sees the diagnostic view.
+ */
+export declare class ViewportShadingRenderer {
+    private readonly _derived;
+    private readonly _normals;
+    private readonly _overdraw;
+    render(scene: THREE.Scene, mode: ViewportShadingMode, draw: () => void, include?: (mesh: THREE.Mesh) => boolean): void;
+    dispose(): void;
+    private _materialFor;
+}
+//# sourceMappingURL=viewport-shading.d.ts.map

package/dist/render/viewport-shading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport-shading.d.ts","sourceRoot":"","sources":["../../src/render/viewport-shading.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,+EAA+E;AAC/E,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC;AAoB3F;;;;GAIG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IACpE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,SAAS,CASvB;IAEH,MAAM,CACJ,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,MAAM,IAAI,EAChB,OAAO,GAAE,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,OAAoB,GAClD,IAAI;IA0BP,OAAO,IAAI,IAAI;IAUf,OAAO,CAAC,YAAY;CAgCrB"}

package/dist/render/viewport-shading.js

@@ -0,0 +1,87 @@
+import * as THREE from 'three';
+function materialColor(material) {
+    const color = material.color;
+    return color?.clone() ?? new THREE.Color(0xbec7d1);
+}
+function textureOf(material, key) {
+    return (material[key] ?? null);
+}
+/**
+ * Applies a render-only material view and restores every native material in a
+ * `finally` block. Gameplay and authoring therefore always observe the real
+ * materials; only renderer work inside {@link render} sees the diagnostic view.
+ */
+export class ViewportShadingRenderer {
+    _derived = new Map();
+    _normals = new THREE.MeshNormalMaterial();
+    _overdraw = new THREE.MeshBasicMaterial({
+        color: 0xffffff,
+        transparent: true,
+        opacity: 0.08,
+        depthTest: false,
+        depthWrite: false,
+        blending: THREE.AdditiveBlending,
+        side: THREE.DoubleSide,
+        toneMapped: false,
+    });
+    render(scene, mode, draw, include = () => true) {
+        if (mode === 'solid') {
+            draw();
+            return;
+        }
+        const originals = [];
+        scene.traverse((object) => {
+            const mesh = object;
+            if (!mesh.isMesh || !mesh.material || !include(mesh))
+                return;
+            originals.push({ mesh, material: mesh.material });
+            mesh.material = Array.isArray(mesh.material)
+                ? mesh.material.map((material) => this._materialFor(material, mode))
+                : this._materialFor(mesh.material, mode);
+        });
+        try {
+            draw();
+        }
+        finally {
+            for (const { mesh, material } of originals)
+                mesh.material = material;
+        }
+    }
+    dispose() {
+        for (const pair of this._derived.values()) {
+            pair.unlit.dispose();
+            pair.wireframe.dispose();
+        }
+        this._derived.clear();
+        this._normals.dispose();
+        this._overdraw.dispose();
+    }
+    _materialFor(material, mode) {
+        if (mode === 'normals')
+            return this._normals;
+        if (mode === 'overdraw')
+            return this._overdraw;
+        let pair = this._derived.get(material);
+        if (!pair) {
+            const common = {
+                color: materialColor(material),
+                map: textureOf(material, 'map'),
+                alphaMap: textureOf(material, 'alphaMap'),
+                alphaTest: material.alphaTest,
+                opacity: material.opacity,
+                transparent: material.transparent,
+                side: material.side,
+                depthTest: material.depthTest,
+                depthWrite: material.depthWrite,
+                vertexColors: Boolean(material.vertexColors),
+                fog: material.fog ?? true,
+            };
+            pair = {
+                unlit: new THREE.MeshBasicMaterial(common),
+                wireframe: new THREE.MeshBasicMaterial({ ...common, wireframe: true }),
+            };
+            this._derived.set(material, pair);
+        }
+        return pair[mode];
+    }
+}

package/dist/runtime/create-runtime.d.ts

@@ -0,0 +1,259 @@
+import * as THREE from 'three';
+import type { DomHostContext } from '../adapter/host-context';
+import type { MountedPixiRoot, MountedReactRoot, MountedRoot, MountedThreeRoot, RootAdapter } from '../adapter/root-adapter';
+import { type Game, type GameInternal, type RootInstance } from './game';
+import type { PlaytestContext } from './types';
+/**
+ * Register a three world onto the Game shell. `opts.id` defaults to
+ * `'main'` — the single-world callers (`createGameRuntime`, slice-1/2 tests)
+ * are unaffected; a second/third world (T7.1 slice 3's two-world proof, and
+ * real multi-world manifests later) pass an explicit id. This is the ONE
+ * registration code path for a three world, whatever its id.
+ */
+export declare function registerThreeRoot(game: GameInternal, adapter: RootAdapter, mounted: MountedThreeRoot, opts?: {
+    id?: string | undefined;
+    pausable?: boolean | undefined;
+}): RootInstance;
+/**
+ * Register a canvas world onto the Game shell — the pixi analog of
+ * {@link registerThreeRoot}. `adapter` is the seam's own
+ * `RootAdapter<'canvas'>`; `RootInstance.adapter` itself only needs `.id`
+ * (`AdapterHandle`, `runtime/game.ts`), so this passes through with zero cast.
+ * `stage` is the one field every `MountedPixiRoot` actually carries.
+ */
+export declare function registerPixiRoot(game: GameInternal, adapter: RootAdapter<'canvas'>, mounted: MountedPixiRoot, opts?: {
+    id?: string | undefined;
+    pausable?: boolean | undefined;
+}): RootInstance;
+/**
+ * Register a react world onto the Game shell (T6.2 slice 1) — the react
+ * analog of {@link registerThreeRoot}/{@link registerPixiRoot}. A react
+ * world has no `frame` hooks (react's own
+ * `createRoot` schedules its commits; `GameInternal.runFrame` correctly
+ * leaves a world with no `frame` untouched by its opaque-`update` fallback
+ * too, since `MountedReactGame` declares no `update`). `adapter` is typed
+ * as the real {@link ReactRootAdapter} shape (T7.5, same reasoning as
+ * `registerPixiRoot`'s doc comment above) — `RootInstance.adapter` only
+ * needs `.id`, so this passes through with zero cast.
+ */
+export declare function registerReactRoot(game: GameInternal, adapter: RootAdapter<'dom'>, mounted: MountedReactRoot, container: HTMLElement, opts?: {
+    id?: string | undefined;
+    pausable?: boolean | undefined;
+}): RootInstance;
+/**
+ * One world to mount in the {@link RootsRuntimeConfig} roots path (T6.1
+ * slice 1) — the host-facing mirror of `manifest/load.ts`'s
+ * `ResolvedAdapterRoot` (same `id`/`zOrder`/`pausable`/`loop` fields; the
+ * manifest-to-host translation itself is the editor's job, not this file's).
+ *
+ * `react` (T6.2 slice 1) mounts as a DOM-root layer `<div>` in the SAME
+ * stack instead of a canvas — see {@link ReactRootMountSpec}/{@link
+ * ReactRootAdapter} below.
+ */
+export interface RootMountSpecBase {
+    /** Manifest id — must be unique within one `roots` array. */
+    readonly id: string;
+    /** Canvas stacking order (D5 §1); ties broken by array
+     *  order, mirroring `manifest/load.ts`'s `loadGameManifest` sort. Defaults
+     *  to `0`. */
+    readonly zOrder?: number | undefined;
+    /** Whether play-mode pause/step applies to this world (D10). Defaults to `true`. */
+    readonly pausable?: boolean | undefined;
+    /**
+     * `vgai.project.json`'s `dev: true` — this root is a DEV LAYER (the game's
+     * own dev GUI), not shipped game content. Two things happen here: the
+     * surface is stacked ABOVE every non-dev root (a dev layer sits topmost),
+     * and it is marked `data-vgai-dev-layer="true"` so the play compositor can
+     * leave it out of a capture (`composite-screenshot.ts`). Whether a dev root
+     * reaches this function at all is the CALLER's gate —
+     * `mountManifestRoots` asks `devLayersEnabled()` before building the spec.
+     *
+     * It steals no input from the game while closed for a reason that predates
+     * this flag and needs no new mechanism: a dev layer is a `dom` root, DOM
+     * layers are `pointer-events:none` (see `mountOneReactRoot`) with the
+     * mounted tree opting individual elements back in, and the input router
+     * never sees DOM roots at all.
+     */
+    readonly dev?: boolean | undefined;
+    /** `'gated'` (host-driven, default) or `'self-driven'` (this world drives
+     *  its own loop — D5's "composited, unsynchronized" tier). Carried through
+     *  for parity with `ResolvedAdapterRoot`; T6.1 slice 1 does not yet
+     *  validate it against the mounted adapter's actual `drivesOwnLoop` (that
+     *  cross-check, if ever needed, is T7.6's loop-gate surface). */
+    readonly loop?: 'gated' | 'self-driven' | undefined;
+    /**
+     * Optional claim predicate for the delegating input router (D5 §2a), over
+     * a point RELATIVE TO THE CONTAINER. Absent means: this world claims only
+     * if it ends up the bottom (lowest zOrder) world — see
+     * `input-router.ts`'s `resolveClaimingRoot`.
+     */
+    readonly hitTest?: ((x: number, y: number) => boolean) | undefined;
+}
+export interface ThreeRootMountSpec extends RootMountSpecBase {
+    readonly kind: 'three';
+    readonly adapter: RootAdapter;
+}
+/**
+ * `adapter` is the SEAM's `RootAdapter<'canvas'>` — a canvas root's mount
+ * honestly returns only a `MountedPixiRoot`, and naming the real contract
+ * here is what keeps the resolver cast-free.
+ */
+export interface PixiRootMountSpec extends RootMountSpecBase {
+    readonly kind: 'canvas';
+    readonly adapter: RootAdapter<'canvas'>;
+}
+/**
+ * A live, mounted react world (T6.2 slice 1) — the react analog of a mounted
+ * canvas world. React roots render from game state via the T7.4 bridge
+ * instead of a per-frame `update`, so this shape carries no `update`/`fixedUpdate`/
+ * `ctx`/`frame` — `drivesOwnLoop` is always `false` (react's `createRoot`
+ * schedules its OWN commits; the host's fixed-step loop never drives it,
+ * and it is correctly skipped by `GameInternal.runFrame`'s per-world
+ * `frame`-hooks/opaque-`update` dispatch — see `registerReactRoot` below,
+ * which registers this `RootInstance` with no `frame`, same as any other
+ * opaque mount with nothing to tick).
+ *
+ * Deliberately carries NO `firstParty: true` brand: that brand specifically
+ * means "has a `.ctx: GameContext`" (`isFirstPartyMounted`,
+ * `runtime/game.ts`) — a react world has no Rapier/ComponentManager/
+ * GameContext at all, so branding it first-party would be a type lie.
+ * `Game.registerRoot`'s "no state bridge" console warning explicitly exempts
+ * `kind: 'dom'` (§7.1-15): a react world has no `observe` BY DESIGN — that
+ * hook is scoped to `useRootObservation` (the ingested/foreign-world case),
+ * not `useWorldState` (`ui/game-state.tsx`), which a react world's own
+ * mounted tree uses instead — it reads `Game.state` directly (T7.4's actual
+ * bridge for first-party-observable state), never a per-world `observe`.
+ *
+ * `kind`/`container` (T7.5) satisfy `MountedReactRoot` (`adapter/
+ * root-adapter.ts`) — `container` is the SAME `DomHostContext.container` the
+ * adapter's `mount` was handed (identity matters, mirroring `threeScene()`/
+ * `pixiStage()`'s "same instance the adapter mounted" contract); every
+ * `ReactRootAdapter` implementer echoes it back here so `mounted` alone
+ * (with no separately-threaded `container`) satisfies the union
+ * `RootInstanceInit.mounted`/`RootInstance.mounted` with zero cast.
+ */
+export interface MountedReactGame extends MountedReactRoot {
+    readonly drivesOwnLoop: false;
+}
+/**
+ * A react-shaped adapter — the structural contract `RootMountSpec`'s
+ * `react` variant requires. Deliberately
+ * NOT tied to a concrete implementer here so an editor-resolved adapter (the
+ * `default-react` resolver branch, T6.2's editor-side follow-up) can satisfy
+ * this shape without this file importing react-dom or any editor code.
+ *
+ * A genuine `RootAdapter<'dom'>` refinement (`HostContextFor<'dom'>` =
+ * `DomHostContext` = {@link DomHostContext}), narrowing only the return type to
+ * {@link MountedReactGame}.
+ */
+export interface ReactRootAdapter extends RootAdapter<'dom'> {
+    readonly id: string;
+    mount(host: DomHostContext): Promise<MountedReactGame>;
+}
+/** WO-34, same reasoning as {@link PixiRootMountSpec} above: the seam's
+ *  `RootAdapter<'dom'>` is what a DOM root actually guarantees. */
+export interface ReactRootMountSpec extends RootMountSpecBase {
+    readonly kind: 'dom';
+    readonly adapter: RootAdapter<'dom'>;
+}
+export type RootMountSpec = ThreeRootMountSpec | PixiRootMountSpec | ReactRootMountSpec;
+/**
+ * Mount N adapter roots (three + canvas + react)
+ * on ONE `Game`, stacked in `container` per D5 §1.
+ * `roots[0]` participates in `Game.defaultRoot`'s existing "first three
+ * root, else first root" rule.
+ */
+export interface RootsRuntimeConfig {
+    /** The host creates one absolutely-positioned surface per world inside
+     *  this element (D5 §1) — a canvas for three/canvas, a DOM-root `<div>`
+     *  layer for react — plus one shared UI overlay above all of them. */
+    container: HTMLElement;
+    roots: RootMountSpec[];
+    width?: number | undefined;
+    height?: number | undefined;
+    /**
+     * Mirrors `ThreeHostContext.headless` (Node conformance tests — no GPU): skips
+     * real `WebGLRenderer` construction for every three world in this
+     * session (a stand-in renderer is used instead, exactly as
+     * `SetupThreeRootAdapter.mount` already special-cases `host.headless`
+     * internally). Pixijs roots are unaffected — Pixi already falls back to
+     * a 2D canvas renderer with no GPU. Never set `true` in a real host.
+     */
+    headless?: 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
+     *  first — see `createRootsGameRuntime`). The manifest-aware boot path
+     *  (`mount-manifest.ts`'s `mountManifestRoots`) is the real caller that
+     *  resolves this from `manifest.determinism`/`?vgai-seed=`/its own
+     *  explicit-config leg; a caller building `RootsRuntimeConfig` by hand
+     *  (a test, a bespoke host) may also set it directly. Omitting it falls
+     *  back to `createGame`'s own fixed default. */
+    seed?: number | undefined;
+    /** Private-play or Team Test identity supplied by the host. Networking
+     * remains game-owned; games may use `roomKey` in their direct room join. */
+    playtest?: PlaytestContext | null | undefined;
+    /**
+     * Test-only overrides for the render-control seam this host now wires up
+     * for EVERY session (see `createRootsGameRuntime`): `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;
+}
+/**
+ * Handle returned by createGameRuntime() for controlling the running game.
+ *
+ * This is the GENERIC host handle — it has no first-party concepts (no
+ * `GameContext`, no `GameSetupFn`). First-party features (the live `GameContext`,
+ * warm-restart hot reload) are reached by casting `mounted` to `MountedSetupThreeRoot`
+ * (the editor does this for HMR/physics-sync — those are inherently first-party).
+ *
+ * `scene`/`camera`/`mounted` alias the Game's `defaultRoot`: it is the first
+ * three root (else the first
+ * world) by DECLARATION order, per `Game.defaultRoot`'s existing rule —
+ * independent of `zOrder`/canvas stacking, which is a rendering-only concern.
+ */
+export interface GameSession {
+    stop(): void;
+    pause(): void;
+    resume(): void;
+    step(): void;
+    /** Resize every world's render buffer. `pixelRatio` (W2c device preview)
+     *  optionally re-pins the three renderers' DPR in the same pass; omitted,
+     *  the mount-time ratio is left untouched (legacy behavior). */
+    resize(width: number, height: number, pixelRatio?: number): void;
+    readonly scene: THREE.Scene;
+    readonly camera: THREE.PerspectiveCamera;
+    /** The default world's mounted root, as the honest `MountedRoot` union —
+     *  narrow on `.kind` before reaching for a surface's own members (the same
+     *  discriminant `scene`/`camera` above use). This deliberately does NOT
+     *  claim `MountedThreeRoot`: a roots-path session whose default world is
+     *  canvas or dom returns that world's mount, and the old
+     *  `as MountedThreeRoot` cast made every such value a type-level lie. For a
+     *  first-party three mount, narrow to `'three'` and cast to
+     *  `MountedSetupThreeRoot` for the first-party extras. */
+    readonly mounted: MountedRoot;
+    /** The Game root (T6.1 slice 1) — the multi-world entry point
+     *  (`game.roots`/`game.world(id)`/`game.queryByComponent`) for callers
+     *  that need more than the default-world aliases above. */
+    readonly game: Game;
+}
+/**
+ * Bootstrap the game host and mount a game adapter.
+ *
+ * `createGameRuntime` is the universal HOST: it owns the root surfaces,
+ * renderers, loop, and asset cache. Every game — including a one-root game —
+ * uses the same explicit adapter-root path.
+ */
+export declare function createGameRuntime(config: RootsRuntimeConfig): Promise<GameSession>;
+//# sourceMappingURL=create-runtime.d.ts.map

package/dist/runtime/create-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-runtime.d.ts","sourceRoot":"","sources":["../../src/runtime/create-runtime.ts"],"names":[],"mappings":"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"}