@volter/game-editor 0.5.65

package/catalog/project-source/src/lib/bake/object3d-bake.ts

@@ -0,0 +1,121 @@
+import type { ToolContext } from '@volter/editor-sdk/tools/registry';
+import type * as THREE from 'three';
+import type { Object3DSourceBuild } from '../bake/object3d-source';
+import {
+  collectMorphTargets,
+  exportObject3DToGlb,
+  type GlbValidationOptions,
+  installNodeThreePolyfills,
+  validateExportedGlb,
+} from './gltf-bake';
+
+type SourceFacts = Record<string, unknown>;
+
+type ToolOutcome<T> = { ok: true; value: T } | { ok: false; error: unknown };
+
+async function captureOutcome<T>(operation: Promise<T>): Promise<ToolOutcome<T>> {
+  try {
+    return { ok: true, value: await operation };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
+export interface Object3DBakeOptions<
+  TBuild extends Object3DSourceBuild,
+  TFacts extends SourceFacts,
+> {
+  ctx: ToolContext;
+  name: string;
+  dryRun: boolean;
+  build(): TBuild;
+  resolveAnimations?(
+    build: TBuild,
+  ): readonly THREE.AnimationClip[] | Promise<readonly THREE.AnimationClip[]>;
+  validateSource?(build: TBuild, animations: readonly THREE.AnimationClip[]): void | Promise<void>;
+  /** Round-trip validation thresholds. May be a function of the built source
+   *  so source-derived facts (bone count, a sampled vertex color) can be
+   *  asserted against the reimported GLB. `requiredClips` and
+   *  `requiredMorphTargets` are NOT settable here: both are read off the built
+   *  source below, so no lib can bake an asset that quietly asserts less than
+   *  what it authored. */
+  validation:
+    | Omit<GlbValidationOptions, 'requiredClips' | 'requiredMorphTargets'>
+    | ((build: TBuild) => Omit<GlbValidationOptions, 'requiredClips' | 'requiredMorphTargets'>);
+  inspectSource(build: TBuild): TFacts;
+}
+
+/**
+ * Compile an ordinary Object3D factory into the runtime asset pair. This is a
+ * build helper, not a modeling abstraction: geometry, materials, hierarchy,
+ * rigging, and animation remain native Three.js in the caller.
+ */
+export async function bakeObject3DSource<
+  TBuild extends Object3DSourceBuild,
+  TFacts extends SourceFacts,
+>(options: Object3DBakeOptions<TBuild, TFacts>) {
+  const { ctx } = options;
+  const projectOutputs = ctx.projectOutputs;
+  if (!projectOutputs) throw new Error('Object3D baking requires a project output writer.');
+  if (ctx.signal?.aborted) throw new Error('Object3D baking was cancelled.');
+
+  const restoreGlobals = installNodeThreePolyfills();
+  let built: TBuild | undefined;
+  const runOperation = async () => {
+    const currentBuild = options.build();
+    built = currentBuild;
+    const animations = options.resolveAnimations
+      ? await options.resolveAnimations(currentBuild)
+      : (currentBuild.animations ?? []);
+    await options.validateSource?.(currentBuild, animations);
+
+    const requiredMorphTargets = collectMorphTargets(currentBuild.root);
+    const glb = await exportObject3DToGlb(currentBuild.root, animations);
+    const validationOptions =
+      typeof options.validation === 'function'
+        ? options.validation(currentBuild)
+        : options.validation;
+    const validation = await validateExportedGlb(glb, {
+      ...validationOptions,
+      requiredClips: animations.map((clip) => clip.name),
+      requiredMorphTargets,
+    });
+    const model = `public/models/generated/${options.name}.glb`;
+    const output = await projectOutputs.write(
+      [{ path: model, content: glb, mediaType: 'model/gltf-binary', role: 'asset' }],
+      { dryRun: options.dryRun },
+    );
+    return {
+      model,
+      ...options.inspectSource(currentBuild),
+      ...validation,
+      ...output,
+    };
+  };
+
+  const outcome = await captureOutcome(runOperation());
+  const operationError = outcome.ok ? undefined : outcome.error;
+
+  const cleanupErrors: unknown[] = [];
+  if (built) {
+    try {
+      built.dispose();
+    } catch (error) {
+      cleanupErrors.push(error);
+    }
+  }
+  try {
+    restoreGlobals();
+  } catch (error) {
+    cleanupErrors.push(error);
+  }
+  if (cleanupErrors.length > 0) {
+    throw new AggregateError(
+      operationError === undefined ? cleanupErrors : [operationError, ...cleanupErrors],
+      'Object3D baking failed to clean up completely.',
+    );
+  }
+  if (operationError !== undefined) throw operationError;
+  if (!outcome.ok) throw outcome.error;
+  return outcome.value;
+}

package/catalog/project-source/src/lib/bake/object3d-lifecycle.ts

@@ -0,0 +1,15 @@
+import type * as THREE from 'three';
+
+export function disposeObject3D(root: THREE.Object3D): void {
+  root.traverse((object) => {
+    const mesh = object as THREE.Mesh;
+    mesh.geometry?.dispose();
+    for (const material of Array.isArray(mesh.material)
+      ? mesh.material
+      : mesh.material
+        ? [mesh.material]
+        : []) {
+      material.dispose();
+    }
+  });
+}

package/catalog/project-source/src/lib/bake/object3d-source.ts

@@ -0,0 +1,8 @@
+import type * as THREE from 'three';
+
+/** Project-local structural boundary between raw Three.js source and bake/preview helpers. */
+export interface Object3DSourceBuild {
+  root: THREE.Object3D;
+  animations?: readonly THREE.AnimationClip[];
+  dispose(): void;
+}

package/catalog/project-source/src/lib/bake/params.ts

@@ -0,0 +1,75 @@
+/**
+ * Reading a declared params schema as tuning controls.
+ *
+ * The parameterization contract (the `vgai-3d-assets` skill,
+ * "Parametric asset libs") says a
+ * parametric asset lib exports a PAIR — a declared parameter object and the
+ * function that takes it — and that any tuning UI is DERIVED from that
+ * declaration, never hand-mirrored. A hand-kept control table is a second
+ * list of the same facts, and second lists rot: a knob added to the schema
+ * gets no control, and a bound changed there silently leaves a slider driving
+ * values the generator would reject at parse.
+ *
+ * `z.toJSONSchema` is zod's own public projection of exactly what was
+ * declared — bounds, defaults, and `.describe()` prose — so this file is the
+ * whole mechanism. Both shipped libs (`lib/humanoid`, `lib/castle`)
+ * bind their Builder controls to it; a lib of your own gets a tuning UI by
+ * declaring a schema and nothing else.
+ */
+
+import type { z } from 'zod';
+import * as zod from 'zod';
+
+/** One numeric knob, read off a declared params schema. */
+export interface NumericParamDescriptor {
+  readonly key: string;
+  readonly min: number;
+  readonly max: number;
+  /** The declared default; absent for an optional param that has none. */
+  readonly default?: number;
+  /** The field's `.describe()` prose — control hint / tooltip copy. */
+  readonly description: string;
+  /** True when the param may be omitted (it has no default). */
+  readonly optional: boolean;
+}
+
+/** Every bounded numeric field of a params schema, in declaration order.
+ *  Fields without both bounds are skipped: an unbounded number has no slider
+ *  range, so a UI must decide what to do with it explicitly. */
+export function describeNumericParams(schema: z.ZodType): readonly NumericParamDescriptor[] {
+  const json = zod.toJSONSchema(schema) as {
+    properties?: Record<
+      string,
+      { type?: string; minimum?: number; maximum?: number; default?: unknown; description?: string }
+    >;
+    required?: string[];
+  };
+  const required = new Set(json.required ?? []);
+  return Object.entries(json.properties ?? {}).flatMap(([key, property]) => {
+    const { minimum, maximum } = property;
+    if (property.type !== 'number' || minimum === undefined || maximum === undefined) return [];
+    return [
+      {
+        key,
+        min: minimum,
+        max: maximum,
+        ...(typeof property.default === 'number' ? { default: property.default } : {}),
+        description: property.description ?? '',
+        optional: !required.has(key),
+      },
+    ];
+  });
+}
+
+/** Descriptor defaults as a plain params object — the initial state of a
+ *  control set. Params with no declared default are omitted (the generator's
+ *  own "natural" behavior stands until the user types a value). */
+export function defaultParams(
+  descriptors: readonly NumericParamDescriptor[],
+): Record<string, number> {
+  return Object.fromEntries(
+    descriptors
+      .filter((descriptor) => descriptor.default !== undefined)
+      .map((descriptor) => [descriptor.key, descriptor.default as number]),
+  );
+}

package/catalog/project-source/src/lib/bake/rest-relative-animation.ts

@@ -0,0 +1,217 @@
+/**
+ * REST-RELATIVE CLIP AUTHORING + the clip self-checks, for any rigged asset:
+ * `assertClipRestBoundaries` (does it return to REST — what an additive layer
+ * needs) and `assertClipLoops` (does it return to WHERE IT STARTED — what a
+ * cyclic clip needs), plus `sampleAnimatedDeformedBounds`.
+ *
+ * Skeleton-agnostic by construction — it speaks `THREE.Bone`, `THREE.Object3D`
+ * and `THREE.AnimationClip` and knows nothing about humanoids — so it lives
+ * here in `lib/bake`, the procedural-asset family's shared home, beside
+ * `clip-layering.ts`. `lib/humanoid/rest-relative-animation.ts` re-exports it
+ * verbatim, so every import path that ever worked still does.
+ *
+ * REMOVAL LINE: delete this file and its humanoid re-export. You lose the
+ * ability to AUTHOR clips as pose deltas and the loud checks; retargeted
+ * clips and baking are unaffected.
+ */
+
+import * as THREE from 'three';
+
+export type EulerDelta = readonly [x: number, y: number, z: number];
+
+function createTrackInterpolant(track: THREE.KeyframeTrack): {
+  evaluate(time: number): ArrayLike<number>;
+} {
+  // Three assigns this native factory at runtime, but its r180 declarations
+  // omit the property. Keep the runtime factory so custom track interpolation
+  // remains intact.
+  const factory = (
+    track as THREE.KeyframeTrack & {
+      createInterpolant?: () => { evaluate(time: number): ArrayLike<number> };
+    }
+  ).createInterpolant;
+  if (!factory) throw new Error(`Animation track ${track.name} has no interpolant factory.`);
+  return factory.call(track);
+}
+
+/** Build an absolute quaternion track from local deltas without erasing rest orientation. */
+export function createRestRelativeQuaternionTrack(
+  bone: THREE.Bone,
+  times: readonly number[],
+  deltas: readonly EulerDelta[],
+): THREE.QuaternionKeyframeTrack {
+  if (times.length !== deltas.length || times.length === 0) {
+    throw new Error(
+      `Rest-relative track for ${bone.name} needs one delta per time (${times.length} times, ${deltas.length} deltas).`,
+    );
+  }
+  const rest = bone.quaternion.clone().normalize();
+  const values: number[] = [];
+  let previous: THREE.Quaternion | undefined;
+  for (const [x, y, z] of deltas) {
+    const delta = new THREE.Quaternion().setFromEuler(new THREE.Euler(x, y, z));
+    const value = rest.clone().multiply(delta).normalize();
+    if (previous && previous.dot(value) < 0) value.set(-value.x, -value.y, -value.z, -value.w);
+    values.push(value.x, value.y, value.z, value.w);
+    previous = value;
+  }
+  return new THREE.QuaternionKeyframeTrack(`${bone.name}.quaternion`, [...times], values);
+}
+
+/** Assert that a clip intentionally authored to return to rest actually does so. */
+export function assertClipRestBoundaries(
+  root: THREE.Object3D,
+  clip: THREE.AnimationClip,
+  sampleTimes: readonly number[] = [0, clip.duration],
+  toleranceRadians = 1e-4,
+): void {
+  for (const track of clip.tracks) {
+    if (!track.name.endsWith('.quaternion')) continue;
+    const nodeName = track.name.slice(0, -'.quaternion'.length);
+    const node = root.getObjectByName(nodeName);
+    if (!node) throw new Error(`Clip '${clip.name}' targets missing node '${nodeName}'.`);
+    const rest = node.quaternion.clone().normalize();
+    const interpolant = createTrackInterpolant(track);
+    for (const time of sampleTimes) {
+      const sample = interpolant.evaluate(time);
+      const value = new THREE.Quaternion(sample[0], sample[1], sample[2], sample[3]).normalize();
+      const angle = 2 * Math.acos(THREE.MathUtils.clamp(Math.abs(rest.dot(value)), -1, 1));
+      if (!Number.isFinite(angle) || angle > toleranceRadians) {
+        throw new Error(
+          `Clip '${clip.name}' erases the rest orientation of '${nodeName}' at t=${time.toFixed(3)} (error ${angle.toFixed(6)} rad).`,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Assert that a clip authored to LOOP actually does: every track's first and
+ * last keyframe values agree within `tolerance`, over a positive duration.
+ *
+ * The cyclic sibling of {@link assertClipRestBoundaries}, and deliberately a
+ * different check. That one asks "does the clip return to REST" — the property
+ * an additive layer needs, measured against the skeleton. This one asks "does
+ * the clip return to WHERE IT STARTED", which is what a looping clip needs and
+ * is a strictly weaker, skeleton-free property: a walk cycle, a wingbeat or an
+ * idle breath holds a pose that is nowhere near rest and must still meet
+ * itself seamlessly. Reaching for the rest check on a cyclic clip fails every
+ * honest loop; reaching for neither is how a one-frame pop ships, because the
+ * seam is exactly the frame nobody scrubs to.
+ *
+ * Works on the raw track VALUES rather than an interpolant, so it is exact and
+ * says nothing about the interpolation between the ends: what it catches is
+ * the authoring mistake — a phase gradient that does not close, a sine sampled
+ * over an open interval, a keyed track whose last value was never brought back
+ * — not a curve's shape.
+ *
+ * Throws naming the failing track and its drift; returns nothing when clean.
+ */
+export function assertClipLoops(clip: THREE.AnimationClip, tolerance = 1e-4): void {
+  if (!(clip.duration > 0)) {
+    throw new Error(
+      `Clip '${clip.name}' cannot loop: its duration is ${clip.duration} — a cycle with no length.`,
+    );
+  }
+  for (const track of clip.tracks) {
+    const stride = track.getValueSize();
+    const { values } = track;
+    if (values.length < stride) {
+      throw new Error(`Clip '${clip.name}' track '${track.name}' has no keyframe values.`);
+    }
+    let drift = 0;
+    for (let i = 0; i < stride; i += 1) {
+      drift = Math.max(
+        drift,
+        Math.abs((values[i] as number) - (values[values.length - stride + i] as number)),
+      );
+    }
+    if (!Number.isFinite(drift) || drift > tolerance) {
+      throw new Error(
+        `Clip '${clip.name}' does not loop: track '${track.name}' drifts by ${drift.toFixed(5)} ` +
+          `between t=0 and t=${clip.duration} (tolerance ${tolerance}).`,
+      );
+    }
+  }
+}
+
+export interface AnimatedBoundsSample {
+  bindDiagonal: number;
+  maximumDiagonal: number;
+  maximumExpansionRatio: number;
+  samples: number;
+}
+
+/** Sample precise SkinnedMesh bounds across a clip, restoring the source pose afterward. */
+export function sampleAnimatedDeformedBounds(
+  root: THREE.Object3D,
+  clip: THREE.AnimationClip,
+  sampleCount = 20,
+  allowedExpansionRatio = 3,
+): AnimatedBoundsSample {
+  if (sampleCount < 1) throw new Error('Animated bounds sampling needs at least one interval.');
+  const saved = new Map<
+    THREE.Object3D,
+    { position: THREE.Vector3; quaternion: THREE.Quaternion; scale: THREE.Vector3 }
+  >();
+  root.traverse((object) => {
+    saved.set(object, {
+      position: object.position.clone(),
+      quaternion: object.quaternion.clone(),
+      scale: object.scale.clone(),
+    });
+  });
+  const preciseBounds = () => {
+    root.updateMatrixWorld(true);
+    const bounds = new THREE.Box3();
+    root.traverse((object) => {
+      const mesh = object as THREE.Mesh;
+      if (!mesh.isMesh || !mesh.geometry) return;
+      if ((mesh as THREE.SkinnedMesh).isSkinnedMesh) {
+        const skinned = mesh as THREE.SkinnedMesh;
+        skinned.computeBoundingBox();
+        if (skinned.boundingBox) {
+          bounds.union(skinned.boundingBox.clone().applyMatrix4(skinned.matrixWorld));
+        }
+      } else {
+        if (!mesh.geometry.boundingBox) mesh.geometry.computeBoundingBox();
+        if (mesh.geometry.boundingBox) {
+          bounds.union(mesh.geometry.boundingBox.clone().applyMatrix4(mesh.matrixWorld));
+        }
+      }
+    });
+    if (bounds.isEmpty()) throw new Error('Animated bounds sampling found no mesh bounds.');
+    const diagonal = bounds.getSize(new THREE.Vector3()).length();
+    if (!Number.isFinite(diagonal) || diagonal <= 0) {
+      throw new Error(`Animated bounds produced invalid diagonal ${diagonal}.`);
+    }
+    return diagonal;
+  };
+
+  const bindDiagonal = preciseBounds();
+  const mixer = new THREE.AnimationMixer(root);
+  mixer.clipAction(clip).play();
+  let maximumDiagonal = bindDiagonal;
+  try {
+    for (let index = 0; index <= sampleCount; index += 1) {
+      mixer.setTime((clip.duration * index) / sampleCount);
+      maximumDiagonal = Math.max(maximumDiagonal, preciseBounds());
+    }
+  } finally {
+    mixer.stopAllAction();
+    mixer.uncacheRoot(root);
+    for (const [object, transform] of saved) {
+      object.position.copy(transform.position);
+      object.quaternion.copy(transform.quaternion);
+      object.scale.copy(transform.scale);
+    }
+    root.updateMatrixWorld(true);
+  }
+  const maximumExpansionRatio = maximumDiagonal / bindDiagonal;
+  if (!Number.isFinite(maximumExpansionRatio) || maximumExpansionRatio > allowedExpansionRatio) {
+    throw new Error(
+      `Clip '${clip.name}' expands deformed bounds by ${maximumExpansionRatio.toFixed(3)}× (limit ${allowedExpansionRatio}×).`,
+    );
+  }
+  return { bindDiagonal, maximumDiagonal, maximumExpansionRatio, samples: sampleCount + 1 };
+}

package/catalog/project-source/src/lib/bake/use-model.ts

@@ -0,0 +1,95 @@
+import { useMemo } from 'react';
+import type * as THREE from 'three';
+import { clone as cloneSkeleton } from 'three/addons/utils/SkeletonUtils.js';
+
+/**
+ * THE SEAM BETWEEN A MODEL BUILDER AND A PREFAB.
+ *
+ * A game authors a 3D asset as a builder returning an Object3D — that is what
+ * `project.bake.preview` photographs in isolation and what `project.bake`
+ * bakes. To place one in a world it has to become an R3F component, and until
+ * this existed the engine offered no way across that gap, so every project
+ * hand-rolled the same three decisions: build once or per instance, clone or
+ * duplicate, and how to hold the result across renders.
+ *
+ * The obvious hand-rolled answer is wrong, and wrong SILENTLY:
+ *
+ *     const model = useMemo(() => build(), []);   // <- stale after any edit
+ *
+ * React Fast Refresh re-renders a mounted component rather than remounting it,
+ * and deliberately preserves hook state. An empty dep array therefore survives
+ * every hot update, so the component goes on handing out the Object3D built
+ * from the module version before the edit. The new geometry is built correctly
+ * and nothing ever asks for it. Nothing errors; the model simply stops
+ * changing, which reads as "HMR is broken" and sends people to restart the
+ * host — the failure that motivated this file.
+ *
+ * `useModel` keys its cache on the BUILDER ITSELF. A hot update re-executes the
+ * module that defines the builder, which mints a new function identity, so the
+ * dep changes exactly when the source changed and at no other time.
+ *
+ * Instances share buffers: the builder runs once per builder identity, and each
+ * caller gets a `clone()`, which copies the scene graph while sharing geometry
+ * and material by reference. A hall with ten of a machine pays for ten graph
+ * entries and one set of buffers.
+ *
+ *     function Scanner(props: ThreeElements['group']) {
+ *       const model = useModel(buildScanner);
+ *       return <group {...props}><primitive object={model} /></group>;
+ *     }
+ *
+ * Disposal is deliberately NOT done here. The shared source outlives any one
+ * component, and clones share its buffers, so disposing on unmount would free
+ * geometry still in use by every sibling. A project that spawns and destroys
+ * models at runtime owns that lifetime itself — `disposeObject3D` is next door.
+ */
+const sources = new WeakMap<() => THREE.Object3D, THREE.Object3D>();
+
+/** Build (or reuse) a model and return an instance of it, HMR-correct. */
+export function useModel(build: () => THREE.Object3D): THREE.Object3D {
+  return useMemo(() => instantiate(build), [build]);
+}
+
+/**
+ * The same thing outside React, for callers placing models imperatively. Kept
+ * beside the hook rather than duplicated, so both share one cache.
+ */
+export function instantiate(build: () => THREE.Object3D): THREE.Object3D {
+  let source = sources.get(build);
+  if (!source) {
+    source = build();
+    sources.set(build, source);
+  }
+  return cloneModel(source);
+}
+
+/**
+ * Clone a built model — and use `SkeletonUtils` when it is RIGGED.
+ *
+ * `Object3D.clone()` copies the meshes and the bones but NOT the bone↔skeleton
+ * wiring: the copied `SkinnedMesh` keeps a reference to the ORIGINAL's
+ * `THREE.Skeleton`, so it is driven by the original's bones and the clone's own
+ * bones drive nothing. One instance animates and every other stands frozen —
+ * with no error anywhere, because nothing is broken, only pointed elsewhere.
+ * This is the same trap the 3D-assets skill names for a baked GLB
+ * ("a SKINNED GLB must be cloned with `SkeletonUtils.clone`"); it applies to a
+ * model MODULE for exactly the same reason, and `useModel` is the seam every
+ * model module reaches a scene through.
+ *
+ * Measured by the adventurer driver: a story wound its clip onto the clone's
+ * bones and the character rendered its REST pose in every variant.
+ *
+ * `animations` is carried across too. Three's clone drops the field, and the
+ * model-file contract puts a model's clips on `root.animations` — a prefab
+ * that could not read them would have to rebuild them, which is a second
+ * implementation of the thing the module already shipped.
+ */
+function cloneModel(source: THREE.Object3D): THREE.Object3D {
+  let rigged = false;
+  source.traverse((object) => {
+    if ((object as THREE.SkinnedMesh).isSkinnedMesh === true) rigged = true;
+  });
+  const copy = rigged ? cloneSkeleton(source) : source.clone();
+  if (source.animations.length > 0) copy.animations = source.animations;
+  return copy;
+}

package/catalog/project-source/src/lib/react-root/index.ts

@@ -0,0 +1,20 @@
+/**
+ * React as the implementer of this project's `dom` roots.
+ *
+ * A `dom` root is one of the three things the host can hand you: an
+ * `HTMLElement` (the others being a `<canvas>` and a shared `three`
+ * instance). What mounts into that element is entirely your choice — the
+ * engine has no opinion and ships no default, which is why this file lives in
+ * your project rather than in the engine.
+ *
+ * React is the shipped choice because the editor's JSX authoring
+ * (OID-addressed hierarchy, style/className write-back to source) is built on
+ * it. Nothing forces it: register your own factory for `'dom'` and the same
+ * root mounts Vue, Svelte, or plain DOM. You lose the JSX authoring panels
+ * until that stack supplies its own authoring adapter — the panel is the
+ * reward for implementing the adapter, and the game runs regardless.
+ *
+ * Thirty lines, and every one of them is React's own API — `createRoot`,
+ * `flushSync`, `unmount`. Copied in, yours to edit.
+ */
+export { createReactRootAdapter, registerReactAdapter } from './react-root-adapter';

package/catalog/project-source/src/lib/react-root/react-root-adapter.tsx

@@ -0,0 +1,57 @@
+import { WorldProvider } from '@volter/game-runtime/react/world-state';
+import type { GameDomHostContext } from '@volter/game-runtime/runtime/host-context';
+import type { MountedReactGame, ReactRootAdapter } from '@volter/game-runtime/runtime/create-runtime';
+import { isAdapterRegistered, registerAdapter } from '@volter/game-runtime/runtime/mount-game';
+import { type ComponentType, createElement } from 'react';
+import { flushSync } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+
+interface ReactEntryModule {
+  readonly default?: ComponentType;
+}
+
+/** Construct one canonical React root adapter for direct host composition. */
+export function createReactRootAdapter(id: string, Entry: ComponentType): ReactRootAdapter {
+  return {
+    id,
+    async mount(host: GameDomHostContext): Promise<MountedReactGame> {
+      if (!host.game) throw new Error(`React root "${id}" requires a Game host.`);
+      const reactRoot = createRoot(host.container);
+      flushSync(() => {
+        reactRoot.render(createElement(WorldProvider, { game: host.game! }, createElement(Entry)));
+      });
+      return {
+        kind: 'dom',
+        container: host.container,
+        drivesOwnLoop: false,
+        dispose: () => reactRoot.unmount(),
+      };
+    },
+  };
+}
+
+/**
+ * Register React as the factory for this project's `dom` roots. Call once at
+ * module load, before mounting — ADD the call to your `src/main.ts` yourself:
+ * the scaffold's main.ts registers only `three`, and installing this
+ * capability does not edit it.
+ *
+ * Registration is what makes a `dom` root mount at all; the engine ships no
+ * default. Swap React out by not calling this and registering your own
+ * factory for `'dom'` instead — the host hands that factory an `HTMLElement`
+ * and asks for a dispose, which is all `createApp().mount(el)` or
+ * `new Svelte({ target })` needs.
+ */
+export function registerReactAdapter(): void {
+  if (isAdapterRegistered('dom')) return;
+  registerAdapter('dom', (root, { entryModule }) => {
+    const Entry = (entryModule as ReactEntryModule | undefined)?.default;
+    if (!Entry) {
+      throw new Error(
+        `React root "${root.id}" entry "${root.entry ?? '(missing)'}" must default-export a component.`,
+      );
+    }
+
+    return { kind: 'dom', adapter: createReactRootAdapter(root.id, Entry) };
+  });
+}