@volter/editor-threejs 0.5.57

package/src/adapter/ingest/structural-ids.ts

@@ -0,0 +1,139 @@
+/**
+ * Structural identity — the deterministic id scheme (and the small material
+ * reflection helper that rides along with it) the editor's three authoring
+ * adapter uses to address the objects of a world whose source carries no
+ * serve-time identity stamps
+ * (`packages/editor/src/projection/three.ts`, `structuralIdentity`).
+ *
+ * Identity: each object gets a **structural-path id** — deterministic from the
+ * scene's shape (position in the tree + three.js type + name), so the SAME id
+ * re-binds to the SAME object after the game rebuilds its scene within a
+ * session. The pure walk returns that identity beside the native objects; the
+ * editor keeps the reverse lookup in its authoring adapter rather than writing
+ * editor currency into a foreign graph.
+ *
+ * This module used to be the shared core of a per-game JSON sidecar
+ * persistence system, which was deleted outright (2026-08-02) — ingest edits
+ * are LIVE-ONLY now. The id scheme survives because it is what makes the live
+ * hierarchy/selection/inspector work at all; nothing here reads or writes a
+ * file.
+ */
+
+import type * as THREE from 'three';
+import { setUserData } from '../../ecs/user-data';
+
+/** Fixed id for the captured render camera (not a scene child, so no structural path). */
+export const CAMERA_ID = 'ingest:camera';
+
+/**
+ * The editor parks its OWN objects — grid, its two lights, the particle
+ * BatchedRenderer, every TransformControls/gizmo helper — on layer 31
+ * (`@vgai/threejs/viewport/editor-layers`'s `EDITOR_LAYER`) so the game camera
+ * never sees them. On an ingest root those objects are added to the GAME'S OWN
+ * scene, which is the same tree this walk indexes.
+ */
+const EDITOR_ONLY_LAYER_MASK = 1 << 31;
+
+/**
+ * Editor furniture, not game content. Excluded from the walk entirely — see
+ * {@link collectStructuralIds} for why that exclusion is what makes the id
+ * scheme's central promise true.
+ */
+function isEditorOnly(o: THREE.Object3D): boolean {
+  return (o.layers.mask & EDITOR_ONLY_LAYER_MASK) !== 0;
+}
+
+/**
+ * The material whose colour a mesh's swatch reflects, if it has one.
+ *
+ * A multi-material mesh reflects its FIRST slot — that is what a single swatch
+ * can honestly stand for, and it is also the slot a creation-site anchor for
+ * `material.color` resolves against. Returns `null` for anything with no
+ * `color` at all rather than fabricating one.
+ */
+export function colorMaterialOf(o: THREE.Object3D): THREE.MeshStandardMaterial | null {
+  const mat = (o as THREE.Mesh).material;
+  if (!mat) return null;
+  const m = (Array.isArray(mat) ? mat[0] : mat) as THREE.MeshStandardMaterial | undefined;
+  return m?.color ? m : null;
+}
+
+/** Result of a structural-path walk: the id→object map plus a few reflection stats. */
+export interface StructuralIdWalk {
+  byId: Map<string, THREE.Object3D>;
+  count: number;
+  meshes: number;
+  lights: number;
+}
+
+/**
+ * (Re)collect structural-path ids for every object under `scene` (and, if
+ * given, the separately-captured render `camera`, under the fixed
+ * {@link CAMERA_ID}). Idempotent and deterministic from scene structure
+ * (position + type + name) — so a re-walk after the game rebuilds part of its
+ * tree re-binds the same ids to the same objects.
+ *
+ * EDITOR FURNITURE IS EXCLUDED, and that exclusion is load-bearing rather than
+ * cosmetic. On an ingest root the editor adds its grid, lights, particle
+ * BatchedRenderer and TransformControls gizmo to the GAME'S OWN scene, and
+ * they arrive asynchronously — some before the walk, some after. Indexing them
+ * made a game object's path depend on how much editor furniture happened to be
+ * attached at walk time, so the same mesh changed id across a re-walk (observed
+ * in the games-fps ingest: an object addressed as `ingest:106/0/0/0:…` came
+ * back as `ingest:102/0:Mesh:Cube004` — four root slots earlier, exactly the
+ * grid + two editor lights + BatchedRenderer).
+ *
+ * Skipping the furniture entirely — not merely declining to give it an id —
+ * is what fixes that: the game's own children occupy 0..N-1 whatever else is
+ * parented alongside them. It also keeps gizmo handles and the grid out of the
+ * hierarchy/inspector projections built on this walk, where they were
+ * selectable and colorable as if they were game content.
+ */
+export function collectStructuralIds(
+  scene: THREE.Object3D,
+  camera?: THREE.Object3D | undefined,
+): StructuralIdWalk {
+  const byId = new Map<string, THREE.Object3D>();
+  let count = 0;
+  let meshes = 0;
+  let lights = 0;
+  const visit = (
+    o: THREE.Object3D & { isMesh?: boolean; isLight?: boolean },
+    path: string,
+  ): void => {
+    const id = `ingest:${path}:${o.type}:${o.name || ''}`;
+    byId.set(id, o);
+    count++;
+    if (o.isLight) lights++;
+    else if (o.isMesh) meshes++;
+    visitChildren(o, path);
+  };
+  const visitChildren = (o: THREE.Object3D, path: string): void => {
+    let i = 0;
+    for (const c of o.children) {
+      if (isEditorOnly(c)) continue;
+      visit(c, path ? `${path}/${i}` : `${i}`);
+      i++;
+    }
+  };
+  visitChildren(scene, '');
+  if (camera) {
+    byId.set(CAMERA_ID, camera);
+    count++;
+  }
+  return { byId, count, meshes, lights };
+}
+
+/**
+ * Compatibility entry point for first-party callers that explicitly want
+ * structural ids stamped into their own graph. Foreign ingest authoring uses
+ * {@link collectStructuralIds} and never calls this mutating form.
+ */
+export function assignStructuralIds(
+  scene: THREE.Object3D,
+  camera?: THREE.Object3D | undefined,
+): StructuralIdWalk {
+  const walk = collectStructuralIds(scene, camera);
+  for (const [id, object] of walk.byId) setUserData(object, 'entityId', id);
+  return walk;
+}

package/src/adapter/ingest/visible-capture-window.ts

@@ -0,0 +1,302 @@
+/**
+ * The capture window is a budget of VISIBLE time, not of wall-clock time.
+ *
+ * WHY THIS MODULE EXISTS. An ingest mount waits for the game to render its
+ * first frame and fails by name when that never happens
+ * (`scene-capture.ts`'s `waitForCapture`). That wait used to be a plain
+ * `setTimeout`, i.e. a wall-clock deadline started AT BOOT — and a game cannot
+ * render while its tab is hidden, because the browser parks `requestAnimation
+ * Frame` for a backgrounded document. The two facts together make one
+ * deterministic failure: a tab that opens in the BACKGROUND (the normal human
+ * path — `vgai edit` auto-opens a tab that routinely lands behind the current
+ * window) burns its whole capture window unable to draw, the deadline fires,
+ * the mount dies terminally, and foregrounding the tab later changes nothing.
+ * Agents, whose tabs happen to be visible, never saw it.
+ *
+ * So the clock only runs while the document is VISIBLE. Hidden time is not
+ * spent, and while a tab is hidden the wait PARKS rather than expiring: the
+ * capture trap stays installed, the game's modules stay live, and the first
+ * frame the tab draws after the human brings it forward is trapped exactly as
+ * it would have been at boot. That is the retry — no second mount, no
+ * re-running `load()` (which would re-construct module-level state: the
+ * ARCHITECTURE-CORE "LOADING CONSTRUCTS, once" contract), and no forcing of a
+ * frame: the game's own loop resumes on its own when the browser un-parks it.
+ *
+ * There is deliberately no wall-clock cap on the parked state. An unspent
+ * budget is not a failure — a human returning to the tab is what spends it —
+ * and a cap would be exactly the boot-time clock this module exists to
+ * remove. The parked wait is reported instead of being silent: see
+ * `CaptureWaitObserver` in `scene-capture.ts` and `vgai status`'s
+ * `ingestCaptureWait`.
+ *
+ * The state machine is a pure function of (banked segments, now, hidden) so
+ * the whole accrual rule is testable with no browser and no timers
+ * (`packages/engine/test/visible-capture-window.test.ts`); the runtime half
+ * below is only the timer arm/disarm around it.
+ */
+
+/**
+ * Everything the budget reads about the outside world. Injected so the pure
+ * core stays pure and the runtime half is drivable by a fake in tests — and,
+ * as a side effect, so this module never hard-depends on `document` existing
+ * (unit runners, SSR).
+ */
+export interface VisibilityClock {
+  /** Milliseconds, monotonic-ish; `performance.now()`/`Date.now()` both fit. */
+  now(): number;
+  /** True while the document is hidden (no rAF, so no frame can be captured). */
+  hidden(): boolean;
+  /**
+   * True while the browser is not presenting frames. This is wider than
+   * `hidden()`: WebKit also stops rAF for an unfocused window (and can suspend
+   * the page entirely) while `document.hidden` still reads false.
+   *
+   * Optional for compatibility with injected clocks; absent means `hidden()`.
+   */
+  suspended?(): boolean;
+  /** Why {@link suspended} is true, when the clock can say. */
+  suspensionReason?(): 'hidden' | 'unfocused' | 'page-suspended' | null;
+  /** Subscribe to visibility transitions; returns the unsubscribe. */
+  subscribe(onChange: () => void): () => void;
+}
+
+/** The real one: `document.visibilityState` + `visibilitychange`. Falls back
+ *  to permanently-visible where there is no `document` at all, which is the
+ *  honest answer for a headless caller — it has no tab to background. */
+export function documentVisibilityClock(): VisibilityClock {
+  const doc = typeof document === 'undefined' ? null : document;
+  const win = doc?.defaultView ?? null;
+  let pageSuspended = false;
+  const reason = (): 'hidden' | 'unfocused' | 'page-suspended' | null => {
+    if (pageSuspended) return 'page-suspended';
+    if (doc?.hidden === true) return 'hidden';
+    // WebKit stops rAF when the browser window becomes inactive, including
+    // when another app is in front. Page Visibility can still say `visible`
+    // in that state. Focus is a platform fact, not a Safari/UA sniff, and in
+    // browsers that keep rendering while unfocused this merely parks the
+    // expiry clock until either a frame arrives or focus returns.
+    if (doc && typeof doc.hasFocus === 'function' && !doc.hasFocus()) return 'unfocused';
+    return null;
+  };
+  return {
+    now: () => (typeof performance === 'undefined' ? Date.now() : performance.now()),
+    hidden: () => doc?.hidden === true,
+    suspended: () => reason() !== null,
+    suspensionReason: reason,
+    subscribe(onChange) {
+      if (!doc) return () => {};
+      const onPageHide = () => {
+        pageSuspended = true;
+        onChange();
+      };
+      const onPageShow = () => {
+        pageSuspended = false;
+        onChange();
+      };
+      doc.addEventListener('visibilitychange', onChange);
+      win?.addEventListener('blur', onChange);
+      win?.addEventListener('focus', onChange);
+      win?.addEventListener('pagehide', onPageHide);
+      win?.addEventListener('pageshow', onPageShow);
+      return () => {
+        doc.removeEventListener('visibilitychange', onChange);
+        win?.removeEventListener('blur', onChange);
+        win?.removeEventListener('focus', onChange);
+        win?.removeEventListener('pagehide', onPageHide);
+        win?.removeEventListener('pageshow', onPageShow);
+      };
+    },
+  };
+}
+
+/**
+ * The banked halves of the wait plus the segment currently running. Immutable:
+ * every transition returns a new value, so a caller can hold one and compare.
+ */
+export interface VisibleBudgetState {
+  /** The window, in VISIBLE milliseconds. */
+  readonly budgetMs: number;
+  /** Visible time banked from completed segments. */
+  readonly visibleMs: number;
+  /** Hidden time banked from completed segments (reported, never spent). */
+  readonly hiddenMs: number;
+  /** When the current segment started. */
+  readonly since: number;
+  /** Whether the current segment is a hidden one. */
+  readonly hidden: boolean;
+}
+
+/** Open the window at `now`, in whichever visibility the document is in. */
+export function beginVisibleBudget(
+  budgetMs: number,
+  now: number,
+  hidden: boolean,
+): VisibleBudgetState {
+  return { budgetMs, visibleMs: 0, hiddenMs: 0, since: now, hidden };
+}
+
+/**
+ * Apply the document's current visibility at `now`: bank the segment that just
+ * ended into its own bucket and start the next one. A call that does not change
+ * visibility is a no-op *by value* (same accrual, same segment start), so a
+ * duplicate `visibilitychange` can never bank a zero-length segment twice or
+ * restart the clock.
+ */
+export function applyVisibility(
+  state: VisibleBudgetState,
+  now: number,
+  hidden: boolean,
+): VisibleBudgetState {
+  if (hidden === state.hidden) return state;
+  const elapsed = Math.max(0, now - state.since);
+  return {
+    budgetMs: state.budgetMs,
+    visibleMs: state.hidden ? state.visibleMs : state.visibleMs + elapsed,
+    hiddenMs: state.hidden ? state.hiddenMs + elapsed : state.hiddenMs,
+    since: now,
+    hidden,
+  };
+}
+
+/** Visible time spent so far, including the segment in flight. */
+export function visibleElapsedMs(state: VisibleBudgetState, now: number): number {
+  return state.visibleMs + (state.hidden ? 0 : Math.max(0, now - state.since));
+}
+
+/** Hidden time so far, including the segment in flight. Never spent — it is
+ *  reported so a failure message can say what the window did NOT count. */
+export function hiddenElapsedMs(state: VisibleBudgetState, now: number): number {
+  return state.hiddenMs + (state.hidden ? Math.max(0, now - state.since) : 0);
+}
+
+/** Visible time left in the window; `0` once it is spent. */
+export function visibleRemainingMs(state: VisibleBudgetState, now: number): number {
+  return Math.max(0, state.budgetMs - visibleElapsedMs(state, now));
+}
+
+/** A live view of one running window, for the status wire and the failure message. */
+export interface VisibleCaptureWindow {
+  /** The window's size, in visible milliseconds. */
+  readonly budgetMs: number;
+  /** Visible milliseconds spent so far. */
+  elapsedVisibleMs(): number;
+  /** Milliseconds this window has spent browser-suspended (not counted). */
+  elapsedHiddenMs(): number;
+  /**
+   * Whether the document itself is hidden. Kept distinct from browser
+   * suspension so status never calls an unfocused, still-visible window hidden.
+   */
+  isHidden(): boolean;
+  /** Whether the expiry budget is parked because the browser is not presenting frames. */
+  isSuspended(): boolean;
+  /** The browser condition parking the budget, when observable. */
+  suspensionReason(): 'hidden' | 'unfocused' | 'page-suspended' | null;
+  /** Stop the timer and drop the visibility listener. Idempotent. */
+  cancel(): void;
+}
+
+/**
+ * How a caller configures ONE such wait — the options both `waitForCapture`s
+ * take (`adapter/ingest/scene-capture.ts` on the three surface,
+ * `pixi/scene-capture.ts` on the canvas surface). Passing a bare number
+ * instead is `{ timeoutMs }`, the shape every existing caller uses.
+ *
+ * It lives HERE, with the window, rather than once per lane, because every
+ * field is a parameter of the mechanism above and none of them is a parameter
+ * of a surface: `timeoutMs` is {@link startVisibleCaptureWindow}'s `budgetMs`,
+ * `visibility` is its {@link VisibilityClock}, and `onWait` hands out the
+ * {@link VisibleCaptureWindow} it returns. The two lanes had identical copies
+ * of this — which is what a shape with no lane-specific field looks like when
+ * it is declared per lane — while both already imported those three names from
+ * this module. Genuinely per-surface shapes (`CapturedRuntime` vs
+ * `CapturedRuntime2D`: a three scene/renderer against a Pixi stage/app) stay in
+ * their own lanes and keep their own names.
+ */
+export interface CaptureWaitOptions {
+  /** The capture window, in VISIBLE milliseconds (default 10s). */
+  timeoutMs?: number | undefined;
+  /** Injected in tests; defaults to the document's own visibility. */
+  visibility?: VisibilityClock | undefined;
+  /**
+   * Called with a LIVE view of the wait when it begins, and with `null` the
+   * moment it ends (captured, expired, or the window was cancelled).
+   *
+   * A wait parked on a hidden tab is otherwise indistinguishable from a hung
+   * mount: nothing renders, nothing fails, and every door reports silence.
+   * This is the seam the editor publishes to `vgai status` so the answer is
+   * "waiting for the first visible frame — the tab is hidden", not a countdown
+   * that is not running.
+   */
+  onWait?: ((wait: VisibleCaptureWindow | null) => void) | undefined;
+}
+
+/**
+ * Start a window that calls `onExpire` after `budgetMs` of VISIBLE time.
+ * While browser frame presentation is suspended the timer is disarmed entirely
+ * (so a throttled background timer cannot fire it late either) and re-armed
+ * with the remaining budget when frame presentation resumes.
+ */
+export function startVisibleCaptureWindow(opts: {
+  budgetMs: number;
+  onExpire: () => void;
+  /** Defaults to the document's own visibility. */
+  clock?: VisibilityClock;
+  /** Defaults to `setTimeout`/`clearTimeout`. */
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (handle: unknown) => void;
+}): VisibleCaptureWindow {
+  const clock = opts.clock ?? documentVisibilityClock();
+  const setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h as ReturnType<typeof setTimeout>));
+
+  const suspended = () => clock.suspended?.() ?? clock.hidden();
+  let state = beginVisibleBudget(opts.budgetMs, clock.now(), suspended());
+  let timer: unknown = null;
+  let done = false;
+
+  function disarm(): void {
+    if (timer !== null) {
+      clearTimer(timer);
+      timer = null;
+    }
+  }
+
+  function arm(): void {
+    disarm();
+    if (done || state.hidden) return;
+    timer = setTimer(
+      () => {
+        timer = null;
+        if (done) return;
+        done = true;
+        unsubscribe();
+        opts.onExpire();
+      },
+      visibleRemainingMs(state, clock.now()),
+    );
+  }
+
+  const unsubscribe = clock.subscribe(() => {
+    if (done) return;
+    state = applyVisibility(state, clock.now(), suspended());
+    arm();
+  });
+
+  arm();
+
+  return {
+    budgetMs: opts.budgetMs,
+    elapsedVisibleMs: () => visibleElapsedMs(state, clock.now()),
+    elapsedHiddenMs: () => hiddenElapsedMs(state, clock.now()),
+    isHidden: () => clock.hidden(),
+    isSuspended: () => state.hidden,
+    suspensionReason: () =>
+      state.hidden ? (clock.suspensionReason?.() ?? (clock.hidden() ? 'hidden' : null)) : null,
+    cancel() {
+      if (done) return;
+      done = true;
+      disarm();
+      unsubscribe();
+    },
+  };
+}

package/src/adapter/object3d-authoring-subject.ts

@@ -0,0 +1,50 @@
+/**
+ * Transient authoring identity for a native subject represented by an
+ * Object3D proxy.
+ *
+ * Some ecosystem-native objects are not Object3Ds themselves: Rapier bodies
+ * and joints are the first examples. A project library may already own a
+ * viewport proxy for one of those objects. This mark lets the ordinary
+ * Object3D authoring projection name and inspect that proxy without teaching
+ * the editor shell the library's nouns or creating a persisted sidecar.
+ *
+ * The mark is observation only. Its values are read from the native owner at
+ * the moment they are requested, and any authored change still belongs in the
+ * owning TS/TSX or ecosystem artifact.
+ */
+
+import type { PropertyDescriptor } from '@volter/editor-project/adapter/authoring';
+import type * as THREE from 'three';
+import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
+
+export interface Object3DAuthoringSubjectField extends PropertyDescriptor {
+  /** Read the current value from the native subject. */
+  readonly value: () => unknown;
+}
+
+export interface Object3DAuthoringSubjectMark {
+  readonly label: string;
+  readonly kind: string;
+  readonly typeLabel?: string;
+  readonly fields?: () => readonly Object3DAuthoringSubjectField[];
+  /** Presentation-only selection feedback for proxies hidden by default. */
+  readonly selectionChanged?: (selected: boolean) => void;
+}
+
+export function object3DAuthoringSubjectOf(
+  object: THREE.Object3D | null | undefined,
+): Object3DAuthoringSubjectMark | null {
+  const mark = getUserData(object, 'authoringSubject');
+  return mark && typeof mark.label === 'string' && typeof mark.kind === 'string' ? mark : null;
+}
+
+export function setObject3DAuthoringSubject(
+  object: THREE.Object3D,
+  mark: Object3DAuthoringSubjectMark,
+): void {
+  setUserData(object, 'authoringSubject', mark);
+}
+
+export function clearObject3DAuthoringSubject(object: THREE.Object3D): void {
+  deleteUserData(object, 'authoringSubject');
+}

package/src/adapter/reflection-probe.ts

@@ -0,0 +1,75 @@
+/**
+ * Format-neutral live reflection-probe mark.
+ *
+ * A project-owned scene component writes this mark onto the Object3D it
+ * returns. The renderer capability owns capture and material integration; the
+ * editor only reads the mark to draw ordinary probe gizmos and expose the
+ * capture command/status. Authored truth remains the component's JSX props —
+ * this is a live adapter seam, not another document format.
+ */
+import type * as THREE from 'three';
+import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
+
+export type ReflectionProbeShape = 'box' | 'sphere';
+export type ReflectionProbeCaptureMode = 'on-change' | 'manual' | 'realtime';
+export type ReflectionProbeCaptureStatus = 'idle' | 'queued' | 'capturing' | 'ready' | 'error';
+
+export interface ReflectionProbeConfig {
+  readonly shape: ReflectionProbeShape;
+  /** Full local-space box dimensions. */
+  readonly size: readonly [number, number, number];
+  /** Local-space sphere radius when `shape === 'sphere'`. */
+  readonly radius: number;
+  /** Local-space distance over which this probe fades at its boundary. */
+  readonly blendDistance: number;
+  /** Larger values win before equal-priority probes blend. */
+  readonly priority: number;
+  readonly intensity: number;
+  readonly parallaxProjection: boolean;
+  /** Full local-space projection-box dimensions. */
+  readonly parallaxSize: readonly [number, number, number];
+  readonly parallaxOffset: readonly [number, number, number];
+  readonly captureOffset: readonly [number, number, number];
+  readonly captureMode: ReflectionProbeCaptureMode;
+  readonly resolution: number;
+  readonly near: number;
+  readonly far: number;
+  readonly cullMask: number;
+  readonly captureShadows: boolean;
+}
+
+export interface ReflectionProbeSnapshot {
+  readonly status: ReflectionProbeCaptureStatus;
+  /** Monotonic browser time from `performance.now()`, or null before capture. */
+  readonly lastCapturedAt: number | null;
+  readonly message?: string;
+}
+
+export interface ReflectionProbeMark {
+  readonly config: ReflectionProbeConfig;
+  readonly revision: number;
+  recapture(): void;
+  getSnapshot(): ReflectionProbeSnapshot;
+  subscribe(listener: () => void): () => void;
+}
+
+export function reflectionProbeOf(
+  object: THREE.Object3D | null | undefined,
+): ReflectionProbeMark | null {
+  const candidate = getUserData(object, 'reflectionProbe');
+  if (!candidate || typeof candidate !== 'object') return null;
+  const mark = candidate as Partial<ReflectionProbeMark>;
+  return mark.config &&
+    typeof mark.recapture === 'function' &&
+    typeof mark.getSnapshot === 'function'
+    ? (candidate as ReflectionProbeMark)
+    : null;
+}
+
+export function setReflectionProbeMark(object: THREE.Object3D, mark: ReflectionProbeMark): void {
+  setUserData(object, 'reflectionProbe', mark);
+}
+
+export function clearReflectionProbeMark(object: THREE.Object3D): void {
+  deleteUserData(object, 'reflectionProbe');
+}

package/src/adapter/renderer-config.ts

@@ -0,0 +1,116 @@
+/**
+ * `applyWorldRendererConfig` — the three.js half of the renderer-config seam.
+ *
+ * The SHAPE is the project contract's (`@volter/editor-project/adapter/renderer-config`,
+ * whose header states the rule and the three load-bearing properties); this
+ * file is what writes it onto a live `WebGLRenderer` and hands back the
+ * restore. `world3d-react/r3f-root-factory.tsx` is the declarer,
+ * `runtime/create-runtime.ts` the host, the editor's world-root stage the
+ * applier.
+ */
+
+import type {
+  WorldOutputColorSpace,
+  WorldRendererConfig,
+  WorldShadowMapType,
+  WorldToneMapping,
+} from '@volter/editor-project/adapter/renderer-config';
+import type * as THREE from 'three';
+
+export type {
+  WorldOutputColorSpace,
+  WorldRendererConfig,
+  WorldShadowMapType,
+  WorldToneMapping,
+} from '@volter/editor-project/adapter/renderer-config';
+
+/**
+ * Apply `config` to `renderer`, returning the restore function that puts back what was there.
+ *
+ * `three` is passed in rather than imported for values so the enum constants come from the HOST's
+ * three instance — the same identity rule `r3f-root-factory.tsx` follows for the scene and camera.
+ */
+export function applyWorldRendererConfig(
+  three: typeof THREE,
+  renderer: THREE.WebGLRenderer,
+  config: WorldRendererConfig,
+): () => void {
+  // A host that mounts a world WITHOUT rasterizing it hands the adapter a duck-typed renderer —
+  // the editor's design session (`createDesignTimeRenderer`: four members, deliberately never
+  // widened) and jsdom test harnesses both do. Such a surface has no colour pipeline to configure:
+  // the frame the user sees is drawn by a DIFFERENT renderer (the editor's own), so applying the
+  // world's config there is meaningless — and calling `getClearColor` on it is a TypeError that
+  // unmounts the whole world at edit time (measured: every Godot port's edit viewport blanked with
+  // '"world" failed to mount — renderer.getClearColor is not a function'). Detect the real
+  // `WebGLRenderer` surface by the one method this function must call, and no-op otherwise.
+  if (typeof renderer.getClearColor !== 'function') {
+    return () => {};
+  }
+  const toneMappings: Record<WorldToneMapping, THREE.ToneMapping> = {
+    none: three.NoToneMapping,
+    linear: three.LinearToneMapping,
+    reinhard: three.ReinhardToneMapping,
+    cineon: three.CineonToneMapping,
+    aces: three.ACESFilmicToneMapping,
+    agx: three.AgXToneMapping,
+    neutral: three.NeutralToneMapping,
+  };
+  const colorSpaces: Record<WorldOutputColorSpace, THREE.ColorSpace> = {
+    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)[] = [];
+
+  if (config.toneMapping !== undefined) {
+    const previous = renderer.toneMapping;
+    renderer.toneMapping = toneMappings[config.toneMapping];
+    restores.push(() => {
+      renderer.toneMapping = previous;
+    });
+  }
+  if (config.toneMappingExposure !== undefined) {
+    const previous = renderer.toneMappingExposure;
+    renderer.toneMappingExposure = config.toneMappingExposure;
+    restores.push(() => {
+      renderer.toneMappingExposure = previous;
+    });
+  }
+  if (config.outputColorSpace !== undefined) {
+    const previous = renderer.outputColorSpace;
+    renderer.outputColorSpace = colorSpaces[config.outputColorSpace];
+    restores.push(() => {
+      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);
+    // Alpha is READ BACK and re-passed, never assumed: see `clearColor`'s doc above.
+    const alpha = renderer.getClearAlpha();
+    renderer.setClearColor(new three.Color(config.clearColor), alpha);
+    restores.push(() => {
+      renderer.setClearColor(previousColor, alpha);
+    });
+  }
+
+  return () => {
+    // Reverse order, so a field written twice (it cannot be, today) unwinds correctly.
+    for (let i = restores.length - 1; i >= 0; i--) restores[i]?.();
+  };
+}