@volter/project 0.0.0-stage → 0.5.204

package/src/adapter/loop-gate-report.ts

@@ -0,0 +1,53 @@
+/**
+ * Capability-gate shortfall reporting (D10, T7.6) — the honesty half of the
+ * play-control contract. §(d) draws the `loop` axis (`gated | self-driven`) on
+ * its own: a `self-driven` world (an ingested game
+ * driving its own rAF/ticker) pauses for real ONLY if its adapter implements an
+ * explicit loop-gate capability (`MountedRootBase.setPaused`/`step`) —
+ * otherwise it "honestly reports so" rather than a silent no-op (the
+ * D5 §5.2 finding: gating a raw-rAF loop from outside was
+ * demonstrated and REJECTED). The audio seam (`SystemAdapters.AudioAdapter`)
+ * has the identical shape: absent or unable to silence a world's audio on pause
+ * must report, not pretend.
+ *
+ * Pure compute + message-formatting — callers own the actual
+ * `console.warn`/`editorConsole.warn` call; this module never logs.
+ */
+
+/** Greppable prefix for a loop-gate shortfall (pause requested, world's loop
+ *  could not actually be gated). */
+export const LOOP_GATE_PREFIX = 'loop-gate';
+
+/** Greppable prefix for an audio-gate shortfall (pause requested, world's
+ *  audio could not actually be silenced). */
+export const AUDIO_GATE_PREFIX = 'audio-gate';
+
+/** One shortfall instance: which world, and why the capability wasn't there. */
+export interface CapabilityGateReport {
+  readonly worldId: string;
+  readonly reason: string;
+}
+
+function formatGateMessage(
+  prefix: string,
+  capability: string,
+  report: CapabilityGateReport,
+): string {
+  return (
+    `${prefix} world "${report.worldId}": pause requested but ${capability} cannot be gated ` +
+    `(${report.reason}) — reporting honestly instead of silently no-op-ing. ` +
+    `${prefix} ${JSON.stringify(report)}`
+  );
+}
+
+/** Format a loop-gate shortfall message (a `self-driven` world with no
+ *  working pause capability). */
+export function formatLoopGateMessage(report: CapabilityGateReport): string {
+  return formatGateMessage(LOOP_GATE_PREFIX, "this world's loop", report);
+}
+
+/** Format an audio-gate shortfall message (a world with no `AudioAdapter`, or
+ *  whose adapter cannot actually silence it). */
+export function formatAudioGateMessage(report: CapabilityGateReport): string {
+  return formatGateMessage(AUDIO_GATE_PREFIX, "this world's audio", report);
+}

package/src/adapter/manifest-interpreter.ts

@@ -0,0 +1,64 @@
+/**
+ * The manifest's SOLE INTERPRETER (owner ruling, 2026-08-20 — see
+ * docs/ARCHITECTURE-CORE.md §adapter). `volter.project.json` is static
+ * inventory; the adapter seam is the ONE layer that turns it into execution
+ * bindings, and host code consumes the manifest through THESE derivations —
+ * never by reading `manifest.roots` directly (the guard is
+ * `packages/engine/test/manifest-sole-interpreter.test.ts`).
+ *
+ * Why a doorway and not a convention: one deriver means one direction of
+ * truth (manifest → adapter → host). When the project's own `editor/volter.adapter.ts`
+ * later interposes on a derivation, every host path that asked the
+ * interpreter gets the project's answer for free; a path that read the raw
+ * field would silently keep the mechanical one.
+ *
+ * The module-free audiences named by the ruling (a bundled CLI's raw
+ * discovery over unvalidated files, Vite config time, synchronous
+ * dep-optimization, and the loader that CONSTRUCTS the resolution) remain
+ * direct readers by design; everything else asks here.
+ *
+ * These functions are pure and synchronous over an already-loaded manifest —
+ * interpreting inventory never evaluates project modules, so any host realm
+ * may import this. They are structurally generic so both the loader's
+ * `ResolvedGameManifest` and the editor's lenient `EditModeManifest` view
+ * flow through the same doorway.
+ */
+
+/**
+ * The declared adapter roots, in mount order (the loader already sorted by
+ * `zOrder`, ties by declaration order). This is the mount plan, the readiness
+ * roster, and the enumeration every other derivation composes from.
+ */
+export function declaredRoots<Root>(manifest: {
+  readonly roots: readonly Root[];
+}): readonly Root[] {
+  return manifest.roots;
+}
+
+/** The root declaring `id`, or undefined — never a silent first-wins pick. */
+export function rootById<Root extends { readonly id: string }>(
+  manifest: { readonly roots: readonly Root[] },
+  id: string,
+): Root | undefined {
+  return manifest.roots.find((root) => root.id === id);
+}
+
+/** Whether any declared root mounts on `surface` (e.g. the editor's
+ *  "does this project have a Three world" gates). The parameter is the closed
+ *  surface union, not `string` — a typo'd literal must stay a compile error,
+ *  not a silent forever-false. */
+export function hasRootOnSurface(
+  manifest: { readonly roots: readonly { readonly surface: string }[] },
+  surface: 'three' | 'canvas' | 'dom',
+): boolean {
+  return manifest.roots.some((root) => root.surface === surface);
+}
+
+/** The declared ingest roots (`adapter.type === 'ingest'`), in mount order.
+ *  Composite-manifest rules (exactly one, ≥2 is a loud named error) belong to
+ *  the call sites that state them. */
+export function ingestRoots<
+  Root extends { readonly adapter: { readonly type: string } },
+>(manifest: { readonly roots: readonly Root[] }): Root[] {
+  return manifest.roots.filter((root) => root.adapter.type === 'ingest');
+}

package/src/adapter/native-entry-surface.ts

@@ -0,0 +1,100 @@
+/**
+ * THE ENTRY MODULE'S DECLARED SURFACE — what a project's root entry may export
+ * for its own debugger, and the already-validated bindings a host hands on.
+ *
+ * This is the contract, not an implementation: a root entry writes
+ *
+ *   export { debug } from './commands';
+ *
+ * and the command module imports no Volter API — its functions are the
+ * application's own functions over its own stores. The READER that validates
+ * one of these exports, and the adapter that projects it onto the session's
+ * debug/input doors, are the game runtime's
+ * (`@volter/editor-game/runtime/adapter/native-debug-module`).
+ */
+
+import type { ContractSystemEmptySlot } from './ingest/contract-system-slots';
+import type { SystemAdapters } from './system-adapter';
+
+export const NATIVE_INPUT_VALUE_TYPES = [
+  'digital',
+  'scalar',
+  'vector2',
+  'pointerDelta',
+  'pointerPosition',
+] as const;
+export type NativeInputValueType = (typeof NATIVE_INPUT_VALUE_TYPES)[number];
+export type NativeInputValue = boolean | number | { readonly x: number; readonly y: number };
+
+/** A table may be a THUNK, evaluated once at install (after every project
+ *  module has run), so a game whose declarations accrete during module
+ *  evaluation — the dev-tools registry's `stat()`/`cheat()` lines beside each
+ *  mechanic — hands a complete snapshot without ordering its own imports
+ *  around the debugger. */
+export type NativeTable<T> = Readonly<Record<string, T>> | (() => Readonly<Record<string, T>>);
+
+/** A command is a plain function, or `{ description, run }` when it wants the
+ *  session's `game.commands()` listing to say what it does. Argument
+ *  validation stays inside the function — the game's words at the game's
+ *  door. */
+export type NativeCommandEntry =
+  | ((...args: unknown[]) => unknown)
+  | { readonly description?: string; readonly run: (...args: unknown[]) => unknown };
+
+export interface NativeDebugModule {
+  readonly commands?: NativeTable<NativeCommandEntry>;
+  readonly state?: NativeTable<() => unknown>;
+  readonly input?: {
+    /** May be a thunk, read LIVE on every use — an app whose action set loads
+     *  asynchronously (an input map fetched at boot) answers with what it has
+     *  NOW rather than freezing the empty pre-load set at install. */
+    readonly actions:
+      | Readonly<Record<string, NativeInputValueType>>
+      | (() => Readonly<Record<string, NativeInputValueType>>);
+    readonly set: (action: string, value: NativeInputValue) => void;
+    readonly clear: () => void;
+    /** Optional native-scheduler operation. The adapter never synthesizes one. */
+    readonly tap?: (action: string) => void;
+    /** Optional native-scheduler operation. The adapter never adds a host phase. */
+    readonly scheduleAtTick?: (tick: number, action: string, value: NativeInputValue) => void;
+  };
+  /** The app's own EVENT STREAM, bridged into the session's tick-stamped
+   *  event log at install — the entry-export replacement for the react
+   *  emit hook. The app owns the emitter; the host only forwards. */
+  readonly events?: {
+    readonly subscribe: (listener: (event: string, detail?: unknown) => void) => () => void;
+  };
+  /**
+   * `false` while the app is intentionally BETWEEN worlds — a scene remount in flight (a
+   * `reload_current_scene`-style restart unmounts the running scene and the fresh one arrives
+   * on an ASYNC React commit). Session tick drivers (`runTicksWhenSettled`, behind both
+   * run-ticks doors) wait for `true` before each tick, so which tick first runs the fresh
+   * world is a function of the sim, never of wall timing between driver calls. Omitted =
+   * always settled.
+   */
+  readonly settled?: () => boolean;
+}
+
+/** One root's `debug` export, already read and validated, with the root it came from. */
+export interface NativeDebugBinding {
+  readonly rootId: string;
+  readonly debug: NativeDebugModule;
+}
+
+/** One root's statically declared, already-validated system-adapter slots. */
+export interface NativeSystemsBinding {
+  readonly rootId: string;
+  readonly slots: Readonly<Partial<SystemAdapters>>;
+  /**
+   * The slots this root's `systems` table answered with `absent(reason)` — the
+   * positive absences, in the game's own words.
+   *
+   * They are carried rather than dropped because they are the ONLY thing that
+   * can tell a coverage reader "this game has no networking" apart from "nobody
+   * ever looked". Nothing is installed for them (that would be the stub adapter
+   * `absent()`'s own comment forbids); they exist to be READ — through
+   * `binding.observation.entrySystems`, which is the product door the coverage
+   * table renders from.
+   */
+  readonly absent: readonly ContractSystemEmptySlot[];
+}

package/src/adapter/physics-adapter-2d.ts

@@ -0,0 +1,30 @@
+/**
+ * The canvas surface's physics seam, keyed by the substrate's display object
+ * (`D`, opaque by default). The implementer names its own display type
+ * (`@volter/editor-game/runtime/pixi/system-adapters` is `PhysicsAdapter2D<Container>`).
+ */
+
+/**
+ * PhysicsAdapter2D — the Pixi analog of the 3D PhysicsAdapter (rapier-physics-adapter).
+ * Lets the editor coordinate editing of a Rapier-2D-driven entity WITHOUT owning the
+ * simulation: report transform ownership, then freeze → commit → unfreeze so a drag
+ * sticks instead of being stomped by the next physics step.
+ *
+ * KEYED BY THE DISPLAY OBJECT, and that is this surface's own vocabulary rather
+ * than a shortcut: the canvas gizmo's real caller
+ * (`editor/src/authoring/pixi-live-write-target.ts`) resolves node id → display
+ * itself before it asks, so there is no node-id hop on this lane at all.
+ *
+ * `keyedBy` is REQUIRED here and optional on the 3D {@link PhysicsAdapter} —
+ * see that interface's doc comment for why the union has to be tagged, and why
+ * the newcomer is the shape obliged to say so.
+ */
+export interface PhysicsAdapter2D<D = unknown> {
+  /** Discriminates this shape from the node-id-keyed {@link PhysicsAdapter}
+   *  inside `SystemAdapters['physics']`. */
+  readonly keyedBy: 'display';
+  ownerOf(display: D): 'physics' | 'none';
+  freeze(display: D): void;
+  commit(display: D, position: [number, number], rotation: number): void;
+  unfreeze(display: D): void;
+}

package/src/adapter/render-audio.ts

@@ -0,0 +1,20 @@
+/**
+ * The offline-audio seam: what a caller's renderer hands back, and the
+ * function shape that produces it. The contract owns both because
+ * `SystemAdapters`'s audio door names them; the gameplay export
+ * (`editor-game/src/host/gameplay-export.ts`) is what drives a renderer.
+ */
+
+/** What a caller's renderer hands back: real PCM in a native `AudioBuffer`.
+ *  `AudioBuffer` — not a volter type — is the point: any offline audio path in
+ *  the platform already produces one. */
+export interface RenderedAudio {
+  readonly buffer: AudioBuffer;
+  readonly durationSeconds: number;
+}
+
+/** Render `[start, end)` (absolute/canonical seconds) offline and
+ *  deterministically. The offset trap in the module doc is the renderer's to
+ *  honour: identical `(start, end)` on an unchanged score must produce
+ *  identical samples, since the capture driver relies on it. */
+export type OfflineAudioRenderer = (start: number, end: number) => Promise<RenderedAudio>;

package/src/adapter/render-memory.ts

@@ -0,0 +1,34 @@
+/**
+ * What a render-memory reading IS — the shape `SystemAdapters`'s memory door
+ * answers with. The contract owns the shape; the measurement that fills it
+ * walks a live three.js scene and is the game runtime's
+ * (`@volter/editor-game/runtime/dev/render-memory`).
+ */
+
+export interface RenderMemoryEntry {
+  readonly name: string;
+  readonly bytes: number;
+}
+
+export interface RenderMemoryUnestimated {
+  readonly name: string;
+  readonly reason: string;
+}
+
+export interface RenderMemorySnapshot {
+  readonly counts: {
+    readonly geometries: number;
+    readonly textures: number;
+    /** Compiled program count, or `null` when the renderer doesn't expose it
+     *  (`renderer.info.programs` is populated only after the first render). */
+    readonly programs: number | null;
+  };
+  /** Sum of every ESTIMABLE texture (nulls excluded — they are in
+   *  `unestimated`). */
+  readonly estimatedTextureBytes: number;
+  /** Exact sum of geometry attribute + index buffers. */
+  readonly estimatedGeometryBytes: number;
+  readonly topTextures: readonly RenderMemoryEntry[];
+  readonly topGeometries: readonly RenderMemoryEntry[];
+  readonly unestimated: readonly RenderMemoryUnestimated[];
+}

package/src/adapter/renderer-config.ts

@@ -0,0 +1,84 @@
+/**
+ * `WorldRendererConfig` — what a WORLD may declare about the renderer that
+ * draws it, and therefore part of the ROOT CONTRACT: `MountedThreeRoot
+ * .rendererConfig` reports it (`./root-adapter.ts`) and
+ * `./root-seam-contract.ts` lists it as a contract field.
+ *
+ * The contract owns the SHAPE and no three.js code: the function that applies
+ * it to a live `WebGLRenderer` (and restores what it found on dispose) is the
+ * three.js twin's, `@volter/threejs-runtime/adapter/renderer-config`. The host
+ * owns the `WebGLRenderer` (`ThreeHostContext.renderer`) and configures it
+ * with this engine's defaults: ACES tone mapping, sRGB output, PCF-soft
+ * shadows. Those defaults are right for a world authored against them and
+ * WRONG for a world authored against a different engine's pipeline — an
+ * imported Godot 3 GLES2 game does gamma-space lighting with no tonemapper at
+ * all, so ACES quietly desaturates and darkens every colour its author picked.
+ *
+ * Three properties of the shape are load-bearing:
+ *
+ *  - **It is per-renderer, never engine-wide.** Every field is a
+ *    `WebGLRenderer` instance property, and a play root gets its own renderer.
+ *    Nothing here reaches a module-level three global, so one world's
+ *    declaration cannot change how the editor's own viewport, another root, or
+ *    a thumbnail bake renders.
+ *  - **Absent means "leave the host's value alone".** Every field is optional
+ *    and an omitted one is never written, so declaring a tone mapping does not
+ *    silently reset the clear colour.
+ *  - **It is restored on dispose.** The renderer outlives the mount, so a
+ *    world that did not put back what it found would leak its pipeline into
+ *    whatever mounts next.
+ *
+ * This is deliberately NOT a general render-settings system. It carries what a
+ * world can honestly state about its own colour pipeline and nothing else; a
+ * property the host fixes at CONSTRUCTION (the WebGL context's `antialias`
+ * attribute, and therefore the MSAA sample count) cannot be declared here,
+ * because there would be no honest moment to apply it.
+ */
+
+/** The tone-mapping operators three exposes, named as data rather than as three's numeric enum. */
+export type WorldToneMapping =
+  | 'none'
+  | 'linear'
+  | 'reinhard'
+  | 'cineon'
+  | 'aces'
+  | 'agx'
+  | 'neutral';
+
+/**
+ * The output transfer function the frame is written with.
+ *
+ *  - `srgb` — three's own default and this engine's: linear lighting, sRGB encode on output.
+ *  - `srgb-linear` — NO output transform. This is what a gamma-space renderer needs: the shading
+ *    result is already in display space and encoding it a second time washes the frame out.
+ */
+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
+   * non-bottom root `alpha: true`), and forcing it opaque here would hide every layer below.
+   */
+  readonly clearColor?: string | undefined;
+}

package/src/adapter/root-adapter.ts

@@ -0,0 +1,243 @@
+/**
+ * RootAdapter — the host ⇄ runtime contract. A ROOT is *anything that mounts*.
+ *
+ * This is the interface the host depends on. First-party content and
+ * unmodified external games are peer root adapters. A game is the
+ * manifest's complete roots array, while each adapter owns exactly one
+ * root.
+ */
+
+import type { AdapterSurface } from './adapter-surface';
+import type { AuthoringAdapter } from './authoring';
+import type { HostContextFor } from './host-context';
+import type { WorldRendererConfig } from './renderer-config';
+import type { SystemAdapters } from './system-adapter';
+
+/**
+ * The ingested-world observation contract (T7.4 slice 2, "the
+ * must-answer"). Cross-world data flow with a
+ * foreign game is observation via an adapter-provided interface, not ordinary
+ * shared state (that's D7's answer for first-party↔first-party flow).
+ * Optional on {@link MountedThreeRoot} —
+ * absence means the adapter has nothing genuinely observable to expose (the
+ * anti-shim rule: never fabricate state), and the world takes the honest
+ * "no state bridge" tier hit (see `Game.registerRoot` in `runtime/game.ts`)
+ * rather than silently offering an `undefined`-forever subscription.
+ */
+export interface RootStateObserver {
+  /**
+   * Notified at most once per frame IF the adapter can hook the game's own
+   * update (`loop: 'gated'` roots, §(d)); self-driven roots (`loop:
+   * 'self-driven'`, raw-rAF) may notify on their OWN rAF cadence instead —
+   * consumers must not assume our frame timing. Returns an unsubscribe
+   * function.
+   */
+  subscribe(onChange: () => void): () => void;
+  /**
+   * A cheap, adapter-chosen snapshot of this world's observable state.
+   * Returns a STABLE reference while nothing has changed (so a selector run
+   * over it can cheaply bail out by reference, same spirit as
+   * `GameStateBridge`'s frame-version cache). Shape is adapter-defined —
+   * not centrally schematized in v1.
+   */
+  snapshot(): unknown;
+}
+
+/**
+ * Everything a mounted world provides except its render surface. Tagged
+ * mounted-root variants carry their native surface fields: a Three scene and
+ * camera, a declared canvas substrate root, or a DOM container.
+ */
+export interface MountedRootBase {
+  /**
+   * Loop model:
+   *  - `false` (host-driven): first-party + "clean" externals. The host ticks
+   *    `update(dt)` in its loop.
+   *  - `true` (self-driven): an unmodified game that owns its renderer + rAF.
+   *    The host does NOT tick it. Pause/step control is a DECLARED CAPABILITY,
+   *    not a promise: implement `setPaused`/`step` only where the game exposes
+   *    a sanctioned pause/step mechanism. Gating a raw-rAF loop from outside
+   *    was demonstrated and REJECTED (D5 — it halts the loop rather than
+   *    pausing it). Where `setPaused` is absent the host reports the
+   *    shortfall loudly, naming the mechanism that would close it (T7.6).
+   */
+  readonly drivesOwnLoop: boolean;
+
+  /**
+   * Which host clock owns an opaque mounted root's single `update(dt)` hook.
+   *
+   * `fixed` (the default) preserves the adapter seam's original contract:
+   * the callback runs once per consumed simulation substep. `display` is for
+   * a reconciler whose one native advance is inseparably BOTH its callbacks
+   * and its draw (React Three Fiber's `advance()` is the measured case). The
+   * real host then withholds it from fixed catch-up substeps and invokes it
+   * exactly once from the display pass. A direct/offline `runFrame` that does
+   * not skip render phases still invokes it once, preserving capture and
+   * explicit-tick semantics.
+   *
+   * Absent means `fixed`. This changes no foreign/ingest adapter unless that
+   * adapter opts in explicitly.
+   */
+  readonly updateCadence?: 'fixed' | 'display';
+
+  update?(dt: number): void; // host-driven only
+  fixedUpdate?(dt: number): void;
+  setPaused?(paused: boolean): void; // capability, not promise — see loop-model note above
+  step?(): void;
+
+  resize?(width: number, height: number): void;
+  /** Does this world claim a pointer at (x, y), in CSS pixels from its surface's top-left? The input
+   *  router asks it of a world stacked above the bottom one (a 2D layer's interactive Pixi objects).
+   *  Absent: such a world claims no point, and input falls through to the bottom world. */
+  hitTest?(x: number, y: number): boolean;
+  dispose(): void;
+  /** Resolves after an asynchronous native reconciler has run every component
+   * cleanup started by {@link dispose}. Omitted by synchronously-disposing
+   * roots. Hosts use this before auditing/reclaiming realm-owned resources. */
+  readonly disposeComplete?: Promise<void>;
+
+  /** Optional capability providers — absence = "not supported", host degrades. */
+  readonly authoring?: AuthoringAdapter;
+  readonly systems?: SystemAdapters;
+  /** Adapter-owned evaluation identity used to bind static system factories. */
+  readonly systemScope?: object;
+  /** Optional state-observation capability (T7.4 slice 2, §4) — absent means
+   *  "no state bridge"; `Game.registerRoot` reports this loudly, once, for
+   *  self-driven mount. A host-driven mount ticks inside the game's frame,
+   *  where the editor reads it directly, so it needs none. */
+  readonly observe?: RootStateObserver;
+}
+
+/** A live, mounted Three world. The host obtains `scene`/`camera` to render
+ * and author it; they are opaque here, and `@volter/editor-threejs` names the
+ * Three-typed root. */
+export interface MountedThreeRoot<Scene = unknown, Camera = unknown> extends MountedRootBase {
+  readonly kind: 'three';
+  /** The live scene + camera the editor inspects/renders for authoring. */
+  readonly scene: Scene;
+  readonly camera: Camera;
+  /**
+   * The colour pipeline this world was authored for, REPORTED rather than
+   * applied — the adapter has already applied it to the renderer its own host
+   * handed it (`./renderer-config.ts`).
+   *
+   * It is here because the host that MOUNTS a world is not always the host
+   * that DRAWS it. The editor's design session mounts against a
+   * non-rasterizing renderer on purpose and then draws the mounted scene with
+   * the editor viewport's own `WebGLRenderer`, so the world's declaration
+   * lands on a surface with no pixels while the surface with pixels never
+   * hears it. Reporting the declaration is what lets that host apply the same
+   * config, through the same `applyWorldRendererConfig`, to the renderer that
+   * actually produces the frame.
+   *
+   * Absent means the world declared nothing and the drawing host should leave
+   * its own configuration alone — the same "absent = don't touch" rule the
+   * config's own fields follow.
+   */
+  readonly rendererConfig?: WorldRendererConfig | undefined;
+}
+
+/**
+ * A canvas substrate's native root, carried without teaching the universal
+ * host that substrate's API. The declaration is explicit — editor substrate
+ * adapters dispatch on `name`; they never infer a library from object shape.
+ */
+export interface MountedCanvasSubstrate<T = unknown> {
+  readonly name: string;
+  readonly root: T;
+  /** The substrate's own module namespace when authoring needs constructors
+   * (for example Babylon's native GizmoManager). Omitted when the projection
+   * only needs the root itself, as Pixi's does. */
+  readonly api?: unknown;
+}
+
+/** A live, mounted canvas world. The host owns the canvas and lifecycle; the
+ * mounted root states which native substrate inhabits it and hands that
+ * substrate's root through opaquely. */
+export interface MountedCanvasRoot extends MountedRootBase {
+  readonly kind: 'canvas';
+  /** The same host-owned canvas passed to `mount`. */
+  readonly canvas: HTMLCanvasElement;
+  readonly substrate: MountedCanvasSubstrate;
+}
+
+/** A live, mounted react world (T6.2) — the react analog of
+ *  {@link MountedThreeRoot}. `container` is the DOM-root layer the host
+ *  handed the adapter's `mount` (the SAME element `RootInstance.reactRoot()`
+ *  returns) — a react world's tree renders into it via `createRoot`. */
+export interface MountedReactRoot extends MountedRootBase {
+  readonly kind: 'dom';
+  readonly container: HTMLElement;
+}
+
+/** Every kind of live, mounted world. */
+export type MountedRoot = MountedThreeRoot | MountedCanvasRoot | MountedReactRoot;
+
+/** Map a {@link AdapterSurface} to its mounted-world shape — lets generic
+ *  code over
+ *  `K extends AdapterSurface` name the right surface without a manual union. */
+export type MountedRootFor<K extends AdapterSurface> = K extends 'three'
+  ? MountedThreeRoot
+  : K extends 'canvas'
+    ? MountedCanvasRoot
+    : K extends 'dom'
+      ? MountedReactRoot
+      : never;
+
+/**
+ * The interface every root implements to run on the host. Generic over
+ * {@link AdapterSurface} so `mount` receives and returns its native surface
+ * types. Bare `RootAdapter` denotes the first-party Three surface.
+ *
+ * `K` parameterizes both halves of `mount`: `HostContextFor<K>` selects the
+ * host context and `MountedRootFor<K>` selects the mounted result. Production
+ * adapters are genuine `RootAdapter<K>` subtypes —
+ * `Pixi2DRootAdapter extends RootAdapter<'canvas'>`, `ReactRootAdapter extends
+ * RootAdapter<'dom'>` (`runtime/create-runtime.ts`).
+ */
+/**
+ * The `= 'three'` default is type-level only: an author who writes bare
+ * `RootAdapter` for
+ * a pixi root gets a compile error on `mount`'s return type, because
+ * `MountedRootFor<'three'>` demands `scene`/`camera` a `MountedCanvasRoot` has
+ * not got.
+ */
+export interface RootAdapter<K extends AdapterSurface = 'three'> {
+  /** Stable id (telemetry/registry/conformance). */
+  readonly id: string;
+  /** Build/start the game against the host context for ITS surface; return the
+   *  handle. */
+  mount(host: HostContextFor<K>): Promise<MountedRootFor<K>>;
+}
+
+/**
+ * One surface tag paired with an adapter typed FOR that surface.
+ *
+ * A resolver that turns a manifest root into a mountable
+ * adapter handles every surface in one function, so its return type has to
+ * span all three. Returning the bare union `RootAdapter<'three'> |
+ * RootAdapter<'canvas'> | RootAdapter<'dom'>` does NOT work — a union of
+ * function types INTERSECTS its parameters, so `.mount(host)` becomes
+ * uncallable with any single host value (no one object is simultaneously a
+ * `ThreeHostContext`, a `CanvasHostContext` and a `DomHostContext`).
+ *
+ * Carrying the tag ALONGSIDE the adapter fixes that structurally: this is a
+ * discriminated union on `surface`, so `switch (resolved.surface)` narrows
+ * `resolved.adapter` to ONE `RootAdapter<K>` inside each branch — a single
+ * signature again, hence `.mount(host)` is callable with that surface's own
+ * host context, checked by the compiler instead of asserted.
+ */
+export type SurfaceAdapterFor<K extends AdapterSurface> = {
+  readonly surface: K;
+  readonly adapter: RootAdapter<K>;
+};
+
+/** Every surface's {@link SurfaceAdapterFor}, as one discriminated union.
+ *  Written out member-by-member (rather than as a distributive conditional)
+ *  so `assertNever` sees exactly three variants and a hypothetical 4th
+ *  `AdapterSurface` member fails to compile HERE, at the vocabulary, rather
+ *  than silently widening every consumer's exhaustiveness guard. */
+export type SurfaceAdapter =
+  | SurfaceAdapterFor<'three'>
+  | SurfaceAdapterFor<'canvas'>
+  | SurfaceAdapterFor<'dom'>;