@vgai/engine 0.5.21 → 0.5.22

package/src/world3d-react/r3f-root-factory.tsx

@@ -1,8 +1,6 @@
 /**
  * `r3fRootFactory` — mount a `three` root whose entry module DEFAULT-EXPORTS a
- * React component.
- *
- * The idiomatic-shape fix (D26). A model asked for an R3F world writes:
+ * React component. This is the ONE first-party three mount:
  *
  * ```tsx
  * export default function World() {
@@ -10,15 +8,13 @@
  * }
  * ```
  *
- * It does NOT write `export const adapter = createR3FAdapter({ id, content })`.
- * That export is pure vgai ceremony wrapped around a component the author
- * already wrote, and it is the second-largest non-idiomatic thing left in a
- * world file (the largest is the missing `<Canvas>`, which is a separate
- * question about who owns the canvas — see D26).
- *
- * The `dom` root already settled this convention: its factory reads
- * `entryModule.default` and wraps it. This is the same contract for three
- * roots, so both surfaces answer "what do I export?" the same way.
+ * The world is an ordinary R3F app. Everything vgai-shaped stays at the entry
+ * module's STATIC surface (`export { debug, systems } from './commands'`) and
+ * on the host's side of the seam; no vgai runtime context ever enters the
+ * React tree. The host controls Fiber's `frameloop: 'never'` scheduler, wires
+ * the game-scoped input seams from outside (`../runtime/game-input-seams.ts`),
+ * and installs `WorldProvider` off the Game handle so the lib-legal react
+ * doors (`useWorldState`, `useOptionalGame`, `useDebugProvider`) resolve.
  *
  * ## Why this is NOT in `mount-game.ts`
  *
@@ -30,22 +26,443 @@
  * there would make R3F unconditional for every game, including ones with no
  * React at all.
  *
- * ## Compatibility
+ * ## The mount mechanics (fiber v9, host-gated)
  *
- * An `adapter` export still wins, so existing worlds are untouched and a game
- * needing full control over its own `RootAdapter` keeps it.
+ * three.js identity: this module never imports `three` itself for scene
+ * objects — fiber's internal `import * as THREE from 'three'` must resolve to
+ * the SAME instance the engine's `ThreeHostContext.three` points at, which the
+ * importing project guarantees via its Vite
+ * `resolve.dedupe: ['three', 'react', 'react-dom']`.
  */
 
-import { type ComponentType, createElement } from 'react';
-import type { RootAdapter } from '../adapter/root-adapter';
+import {
+  advance,
+  createRoot,
+  extend,
+  flushSync,
+  events as pointerEvents,
+  type RootState,
+} from '@react-three/fiber';
+import { type ComponentType, createElement, Fragment, useEffect } from 'react';
+import type { MountedThreeRoot, RootAdapter, ThreeHostContext } from '../adapter';
+import type { SystemAdapters } from '../adapter/system-adapter';
+import { type RenderVitalsRegistration, registerRenderVitals } from '../dev/register-render-vitals';
+import {
+  createRenderDebugAdapter,
+  frameCaptureContextFor,
+  type RenderDebugWiring,
+} from '../dev/render-debug-adapter';
+import { collectRenderMemory } from '../dev/render-memory';
+import { RENDER_SUBMIT_PHASE } from '../dev/render-vitals';
+import { createWebGLFrameCapture } from '../dev/webgl-frame-capture';
+import { WorldProvider } from '../react/world-state';
+import { getDebugRegistry } from '../runtime/debug-registry';
+import { devBuildEnabled } from '../runtime/dev-build';
+import { DEFAULT_INPUT_MAP_PATH, wireGameInputSeams } from '../runtime/game-input-seams';
 import type { AdapterSurfaceFactory } from '../runtime/mount-game';
-import { createR3FAdapter } from './r3f-adapter';
+
+/** The slice of `WebGLRenderer.info` the vitals reporter reads. Declared
+ *  structurally rather than imported from `three`, per this module's own
+ *  identity rule (see the header): a duck-typed host renderer legitimately has
+ *  no `info` at all, which is why every read of it is guarded. */
+interface RendererCounters {
+  readonly render: { readonly calls: number; readonly triangles: number; readonly frame: number };
+  readonly memory: { readonly geometries: number; readonly textures: number };
+}
 
 interface R3FEntryModuleExports {
-  /** The idiomatic shape: the world IS a component. */
+  /** The one shape: the world IS a component. */
   readonly default?: ComponentType;
-  /** Full control, and still the winner when present. */
-  readonly adapter?: RootAdapter;
+}
+
+/**
+ * Build the `RootAdapter` for one default-exported R3F world. Mounts through
+ * react-three-fiber, gated entirely by the host's own loop and rendering
+ * through the host's own `WebGLRenderer` — never a second renderer, never a
+ * second `requestAnimationFrame` loop.
+ */
+function threeWorldAdapter(id: string, component: ComponentType): RootAdapter {
+  const content = createElement(component);
+
+  return {
+    id,
+
+    async mount(host: ThreeHostContext): Promise<MountedThreeRoot> {
+      // Headless honesty — every `mount()` must work headless: the conformance
+      // kit runs `mount()` in Node — no canvas, no WebGL, no fiber
+      // reconciler. Guard the ENTIRE fiber mount behind `!host.headless` and
+      // return a bare, real scene + camera instead (still `instanceof
+      // host.three.Scene` / `.Camera` — the identity rule holds even here,
+      // since this uses the host's own `three` instance, not a fresh import).
+      // Residual: the hierarchy is empty under headless conformance —
+      // recorded as design O2, not hidden; a react-nil-style headless
+      // reconciler mount is the known fix, out of scope.
+      if (host.headless) {
+        const scene = new host.three.Scene();
+        const camera = new host.three.PerspectiveCamera();
+        return {
+          kind: 'three',
+          scene,
+          camera,
+          drivesOwnLoop: false,
+          dispose(): void {
+            /* nothing was ever mounted */
+          },
+        };
+      }
+
+      // Fiber v9 made the THREE catalogue tree-shakeable: `<Canvas>` calls
+      // `extend(THREE)` for you, a bare `createRoot` does NOT — without this,
+      // the FIRST three intrinsic in the tree (`<color>`, `<ambientLight>`,
+      // …) throws "X is not part of the THREE namespace! Did you forget to
+      // extend?" at reconcile time. Extending with `host.three` (not a fresh
+      // `import * as THREE`) keeps the catalogue on the host's deduped three
+      // instance — the same identity rule the returned scene/camera rely on.
+      // `extend` merges into a module-global catalogue, so calling it once
+      // per mount is idempotent.
+      extend(host.three as unknown as Parameters<typeof extend>[0]);
+
+      // THE HOST WIRES THIS GAME'S INPUT FROM OUTSIDE THE TREE: the project's
+      // declared map, and this root's `game.input.*` seams on the debug
+      // registry. Skipping those made a fresh scaffold's bot/autoplay/
+      // `vgai eval` input doors throw `DEBUG_INPUT_UNAVAILABLE` and left the
+      // declared actions unloaded. The conventional path is optional — quiet
+      // when the project ships no map, since a brand-new project declares no
+      // actions yet. Actions must exist before any component's first frame
+      // reads them — wait for the (never-rejecting) load before the first
+      // commit.
+      const gameDebugRegistry = host.game ? getDebugRegistry(host.game) : null;
+      if (gameDebugRegistry) {
+        await wireGameInputSeams(host, gameDebugRegistry, {
+          id,
+          inputMapPath: DEFAULT_INPUT_MAP_PATH,
+          optionalInputMap: true,
+        });
+      }
+
+      const canvas = host.surface.canvas;
+      const root = createRoot(canvas);
+
+      // `RootState` (the live scene/camera/gl fiber built) only arrives via
+      // the `onCreated` callback — `root.render()`'s return value is
+      // TECHNICALLY the same store, but `onCreated` is the supported hook, and
+      // waiting for it (rather than assuming the first commit already ran
+      // synchronously) is the honest choice under React 19's concurrent
+      // renderer, which does not guarantee a synchronous first commit the way
+      // legacy ReactDOM.render did.
+      let resolveState!: (state: RootState) => void;
+      const statePromise = new Promise<RootState>((resolve) => {
+        resolveState = resolve;
+      });
+      let resolveEffectsReady!: () => void;
+      const effectsReady = new Promise<void>((resolve) => {
+        resolveEffectsReady = resolve;
+      });
+      // Rendered after the game's content. React runs passive effects in tree
+      // order, so when this fires every provider/command effect in the
+      // initial tree has registered. A Play acknowledgement is a claim that
+      // the mounted game's command surface exists, not merely that Fiber
+      // allocated a scene.
+      function MountEffectsReady(): null {
+        useEffect(resolveEffectsReady, []);
+        return null;
+      }
+
+      // `root.configure()` is ASYNC in fiber v9 (`Promise<ReconcilerRoot>`) —
+      // it must be awaited before `render()`.
+      await root.configure({
+        // The engine's renderer, not a second one — fiber renders THROUGH
+        // `host.renderer` instead of constructing its own `WebGLRenderer`.
+        gl: host.renderer,
+        // …and the host's shadow map, not fiber's.
+        //
+        // `configure()` runs `gl.shadowMap.enabled = !!shadows`
+        // UNCONDITIONALLY, against its own default of `false`. Passing nothing
+        // therefore does not mean "leave it alone" — it means "turn shadows
+        // off on the renderer the host just configured" (FX-5: every three
+        // root silently read flat, with no error anywhere). Reading it back
+        // off the renderer is exactly "don't clobber": a boolean also pins
+        // `shadowMap.type` to `PCFSoftShadowMap`, which is what
+        // `createHostRenderer` already sets, so the round trip is lossless
+        // and the HOST stays the one deciding.
+        //
+        // Optional-chained even though `WebGLRenderer.shadowMap` is not
+        // optional: a headless/stub host renderer is a real shape in this
+        // repo's tests, and fiber's own `if (gl.shadowMap)` guard means the
+        // value it reads there is ignored anyway.
+        shadows: host.renderer.shadowMap?.enabled ?? false,
+        // The engine's gated loop is the ONLY loop — fiber must never run its
+        // own rAF (that would defeat editor pause; `drivesOwnLoop: false`).
+        frameloop: 'never',
+        // `RenderProps.size` types as the FULL `Size` (width/height/top/left),
+        // so `top`/`left` are pinned to 0 (this bridge always fills its whole
+        // canvas; no offset viewport).
+        size: { width: host.surface.width, height: host.surface.height, top: 0, left: 0 },
+        // Fiber's pointer-event manager, passed EXPLICITLY. There IS no
+        // default for a bare `createRoot`: the `events = createPointerEvents`
+        // default lives in the `<Canvas>` COMPONENT, which this mount does not
+        // use, and `configure` gates on `if (events && !state.events.handlers)`.
+        // With `events` undefined the store keeps its initial
+        // `{ priority, enabled, connected: false }` — no handlers, nothing
+        // bound to the canvas, no error — and every mesh-level pointer prop
+        // (`onClick`, `onPointerOver`, `onPointerMissed`) is dead. Proven by a
+        // control experiment differing ONLY in this property.
+        events: pointerEvents,
+        onCreated: (state) => resolveState(state),
+      });
+
+      // No `<StrictMode>` — the host mounts once; StrictMode's deliberate
+      // double-invoke of effects would double-subscribe `useFrame` callbacks
+      // against a host loop that only ticks once per frame.
+      //
+      // `WorldProvider` rides `host.game` — the React seam every dom root
+      // already has (`useWorldState`, `useOptionalGame`, `useDebugProvider` in
+      // lib code), and the only way a capability hook can reach the ONE
+      // game-scoped registry the editor/`vgai eval` read. `host.game` is
+      // genuinely absent in bare/headless hosts, so the provider is
+      // conditional and those hooks stay the inert no-ops they already
+      // document themselves to be.
+      const game = host.game;
+      const world = createElement(
+        Fragment,
+        null,
+        content,
+        createElement(MountEffectsReady, { key: 'vgai-mount-effects-ready' }),
+      );
+      const provided = game ? createElement(WorldProvider, { game }, world) : world;
+      root.render(provided);
+      // A reconcile-time crash (e.g. a missing `extend` catalogue entry)
+      // surfaces as an uncaught window error and `onCreated` never fires —
+      // without this guard, `mount()` would await `statePromise` FOREVER and
+      // silently wedge every world declared after this one (roots mount
+      // sequentially). Convert that class of failure into a loud mount error.
+      const state = await new Promise<RootState>((resolve, reject) => {
+        const onError = (event: ErrorEvent) => {
+          cleanup();
+          root.unmount();
+          gameDebugRegistry?.strip(id);
+          reject(
+            new Error(
+              `three world "${id}": fiber crashed before its first commit — ${event.message} ` +
+                '(mount() fails loudly instead of hanging on onCreated)',
+            ),
+          );
+        };
+        const timer = setTimeout(() => {
+          cleanup();
+          root.unmount();
+          gameDebugRegistry?.strip(id);
+          reject(
+            new Error(
+              `three world "${id}": onCreated did not fire within 10s — the R3F tree never ` +
+                'reached its first commit (mount() fails loudly instead of hanging)',
+            ),
+          );
+        }, 10_000);
+        const cleanup = () => {
+          clearTimeout(timer);
+          window.removeEventListener('error', onError);
+        };
+        window.addEventListener('error', onError);
+        void Promise.all([statePromise, effectsReady]).then(([s]) => {
+          cleanup();
+          resolve(s);
+        });
+      });
+
+      // Clock hardening: fiber's internal `update()` calls
+      // `state.clock.getDelta()` BEFORE its `frameloop:'never'` branch, and a
+      // RUNNING (or autoStart) `THREE.Clock` accumulates WALL time into
+      // `elapsedTime` as a side effect — skewing the deltas the 'never'
+      // branch derives from the game timestamps `update(dt)` feeds below.
+      // Stopped + autoStart=false makes `getDelta()` a pure no-op, so
+      // `useFrame` deltas come from game time alone.
+      state.clock.autoStart = false;
+      state.clock.stop();
+
+      // THE STORE IS THE TRUTH, NOT THE `onCreated` SNAPSHOT.
+      //
+      // `state` is one immutable zustand snapshot: every `set(...)` produces a
+      // NEW state object. A world that legitimately REPLACES the default
+      // camera — `useThree(s => s.set)({ camera })`, which is exactly what
+      // drei's `makeDefault` does — never reaches anything read off `state`
+      // directly, and fiber's own `update()` renders
+      // `state.gl.render(state.scene, state.camera)` off the state object it
+      // is HANDED. Measured: an authored `OrthographicCamera` world rendered
+      // from fiber's default (0, 0, 5) forever, culling every ground polygon.
+      // `state.get()` is fiber's own `StoreApi.getState`, carried on
+      // `RootState` for precisely this reason; it is a plain map read.
+      const live = (): RootState => state.get();
+
+      // --- Live render vitals, host-seeded ---------------------------------
+      // A running game must be able to explain its own frame cost through the
+      // debug registry, with no capability to install and nothing for a game
+      // to write. Gate: `devBuildEnabled()` (the ONE owner of "is this a dev
+      // context" — a ship build registers nothing and pays nothing) and a
+      // `Game` shell (the readings are folded out of that game's profiler
+      // frames). "Not headless" needs no term here: a headless mount returned
+      // above, before fiber was ever configured.
+      let renderVitals: RenderVitalsRegistration | null = null;
+      if (host.game && devBuildEnabled()) {
+        // The readings are folded out of profiler frames, and the profiler is
+        // a flag the editor already sets on play — under the dev gate this is
+        // the same cost arriving a little earlier, not a new one.
+        host.game.profiler.enabled = true;
+        if (!gameDebugRegistry) {
+          throw new Error(`three world "${id}": mounted Game has no debug registry.`);
+        }
+        renderVitals = registerRenderVitals({
+          registry: gameDebugRegistry,
+          worldId: id,
+          profiler: host.game.profiler,
+          scene: live().scene,
+          renderer: host.renderer,
+        });
+      }
+
+      // Engine-owned render introspection, built over the SAME renderer and
+      // scene Fiber uses. A design-time stand-in has no context and a
+      // headless mount returned above, so both honestly omit the capability.
+      const rendererContext =
+        typeof host.renderer.getContext === 'function' ? host.renderer.getContext() : undefined;
+      const frameCaptureContext = frameCaptureContextFor(false, rendererContext);
+      const frameCapture = frameCaptureContext
+        ? createWebGLFrameCapture(frameCaptureContext)
+        : null;
+      const renderDebugWiring: RenderDebugWiring | null = frameCapture
+        ? createRenderDebugAdapter({
+            capture: frameCapture,
+            scene: state.scene,
+            memory: () => collectRenderMemory(live().scene, host.renderer.info),
+          })
+        : null;
+      // The session debug registry is host instrumentation, not component
+      // context. Publishing the existing adapter here lets coverage and
+      // editor panels see the same door without wrapping the R3F tree. The
+      // world's own declared systems merge in from the entry module at the
+      // Game layer (`installDeclaredSystemAdapters`).
+      const systemAdapters: SystemAdapters = gameDebugRegistry
+        ? { debug: gameDebugRegistry.adapter }
+        : {};
+      if (renderDebugWiring) systemAdapters.renderDebug = renderDebugWiring.adapter;
+
+      // The engine drives every `useFrame` through the mounted world's
+      // `update(dt)` hook, never off a raw host-loop callback. That is the
+      // whole pause story: `runFrameImpl` (`runtime/game.ts`) calls
+      // `mounted.update?.(dt)` per substep for a host-driven world and SKIPS
+      // it while that world is frozen, and `Game.play.step()` ticks it exactly
+      // once.
+      //
+      // `advance(timestamp, runGlobalEffects, state)`'s `timestamp` is
+      // consumed as `THREE.Clock.elapsedTime` DIRECTLY when
+      // `frameloop:'never'` (verified against fiber's `update()`
+      // implementation): `delta = timestamp - clock.elapsedTime;
+      // clock.elapsedTime = timestamp`. So `timestamp` must be a
+      // monotonically increasing SECONDS value — GAME time, not wall time:
+      // `update` simply isn't called while this world is frozen, so
+      // accumulating its `dt` means fiber's clock does not advance across a
+      // pause. Wall clock would leak the pause duration into the first
+      // resumed frame as one giant `useFrame` delta.
+      let elapsed = 0;
+
+      return {
+        kind: 'three',
+        // Fiber's REAL `THREE.Scene`/`THREE.Camera`. Checkout development
+        // dedupes `three`; a registry-installed project and the prebundled
+        // editor can legitimately have distinct constructor identities, so
+        // editor boundaries recognize Three's stable structural brands
+        // (`isScene`, `isCamera`) rather than relying only on `instanceof`.
+        //
+        // Both are GETTERS over the live store, not snapshot fields: the host
+        // and the editor must see the camera the world actually renders
+        // through, including one the world swapped in after the first commit
+        // (see `live` above).
+        get scene() {
+          return live().scene;
+        },
+        get camera() {
+          return live().camera;
+        },
+        drivesOwnLoop: false,
+        // Adapter surface: `debug` (the shared game registry) and, when a real
+        // WebGL2 context exists, `renderDebug` are engine-seeded. The game's
+        // own capabilities arrive as the entry module's declared `systems`.
+        systems: systemAdapters,
+        update(dt: number): void {
+          elapsed += dt;
+          const current = live();
+          renderDebugWiring?.beforeRender();
+          try {
+            const profiler = host.game?.profiler;
+            if (!profiler?.enabled) {
+              advance(elapsed, true, current);
+              return;
+            }
+            // The frame's CPU submission cost, produced where the draw
+            // actually happens: `advance()` under `frameloop: 'never'` is what
+            // calls `gl.render(scene, camera)`, and this bracket is also what
+            // makes this frame a PRESENTATION as far as the vitals fold is
+            // concerned (`../dev/render-vitals.ts`: no bracket, no display
+            // frame). The profiler's phase clock is a stack, so bracketing
+            // here cannot truncate an enclosing phase.
+            const info = host.renderer.info as RendererCounters | undefined;
+            const passesBefore = info?.render.frame ?? 0;
+            profiler.beginPhase();
+            try {
+              advance(elapsed, true, current);
+            } finally {
+              profiler.endPhase(RENDER_SUBMIT_PHASE);
+            }
+            // Checked, not assumed — a duck-typed/design-time renderer
+            // supplies only what a mount needs, and a mount with no counters
+            // must report NOTHING rather than throw once per frame. `gpuMs` is
+            // null: this path runs no GPU timer, and the profiler keeps the
+            // previous reading rather than inventing a zero.
+            if (info) {
+              profiler.reportRender({
+                gpuMs: null,
+                drawCalls: info.render.calls,
+                triangles: info.render.triangles,
+                geometries: info.memory.geometries,
+                textures: info.memory.textures,
+                renderPasses: info.render.frame - passesBefore,
+              });
+            }
+          } finally {
+            renderDebugWiring?.afterRender();
+          }
+        },
+        resize(width: number, height: number): void {
+          live().setSize(width, height);
+        },
+        dispose(): void {
+          // Reject/restore a pending capture while its renderables still
+          // exist, then unmount component effects and strip this world's
+          // registrations.
+          renderDebugWiring?.dispose();
+          // The editor audits and disposes the mounted game's window/document
+          // realm immediately after `session.stop()`. Fiber's ordinary
+          // `unmount()` submits a concurrent reconciler update, so component
+          // effect cleanups could still be pending at that boundary and the
+          // audit would truthfully report/reclaim listeners the world was
+          // about to remove itself. Force the unmount COMMIT (not fiber's
+          // deliberately delayed renderer/context disposal) to finish here: a
+          // stopped root owns no live component lifecycle beyond this method.
+          flushSync(() => root.unmount());
+          // The vitals fold owns two `profiler.subscribe` registrations —
+          // ended here, before the strip, so a subscription can never outlive
+          // the door it feeds.
+          renderVitals?.dispose();
+          renderVitals = null;
+          // `strip(id)` ends this world's PROVIDERS AND COMMANDS (the
+          // render-vitals door above is the one this mount registers under
+          // `id`); sibling roots are untouched. It does NOT end the input
+          // seams `wireGameInputSeams` set — see that module's LIFETIME note.
+          gameDebugRegistry?.strip(id);
+        },
+      };
+    },
+  };
 }
 
 /**
@@ -54,52 +471,26 @@ interface R3FEntryModuleExports {
  * Two callers need this answer and must never disagree about it: the runtime
  * mount ({@link r3fRootFactory}, below) and the EDITOR's design session
  * (`packages/editor/src/authoring/r3f-design-session.ts`), which design-mounts
- * the same entry so edit mode authors the live fiber scene. When only the
- * runtime knew about the default-export shape, the converted starter played
- * fine under `npm run game` and edit mode showed "(no scene loaded)".
+ * the same entry so edit mode authors the live fiber scene.
  *
- * Returns `null` when the module is neither shape — the callers differ on what
- * to do about that (the factory throws, the design session declines the world
- * and leaves existing paths alone).
+ * Returns `null` when the module has no default-exported component — the
+ * callers differ on what to do about that (the factory throws, the design
+ * session declines the world and leaves existing paths alone).
  */
 export function resolveR3FEntryAdapter(entryModule: unknown, rootId: string): RootAdapter | null {
   const mod = entryModule as R3FEntryModuleExports | undefined;
-  if (mod?.adapter) return mod.adapter;
-  if (typeof mod?.default === 'function') {
-    return createR3FAdapter({
-      id: rootId,
-      content: createElement(mod.default),
-      // A default-exported R3F component is an ordinary R3F app. The host
-      // controls Fiber's native `frameloop: 'never'` scheduler; the vgai
-      // runtime CONTEXT (`useGameContext`, `ctx.systems`) never enters its
-      // React tree.
-      //
-      // This flag governs that context and nothing else. It does NOT govern
-      // `WorldProvider`: `useDebugProvider`/`useDebugCommand`/`useWorldState`
-      // are the documented door a game declares its own state/commands
-      // through, and they must work in the idiomatic shape — which is the
-      // ONLY shape `vgai create` scaffolds. `r3f-adapter.tsx` therefore keys
-      // that provider off `host.game`, not off this flag; see the comment
-      // beside `const game = host.game` there for the measured symptom
-      // (`vgai eval 'await game.providers()'` listing only built-ins).
-      engineRuntime: false,
-    });
-  }
+  if (typeof mod?.default === 'function') return threeWorldAdapter(rootId, mod.default);
   return null;
 }
 
 /**
  * Register with `registerAdapter('three', r3fRootFactory)`.
- *
- * Resolution order mirrors `defaultThreeAdapterFactory`'s (explicit adapter
- * wins) and then accepts the default-exported component.
  */
 export const r3fRootFactory: AdapterSurfaceFactory = (root, ctx) => {
   const adapter = resolveR3FEntryAdapter(ctx.entryModule, root.id);
   if (adapter) return { kind: 'three', adapter };
   throw new Error(
     `r3fRootFactory: entry module "${root.entry ?? '(none)'}" for root "${root.id}" must ` +
-      'default-export a React component (`export default function World() { … }`) — or export ' +
-      'an `adapter` for full control.',
+      'default-export a React component (`export default function World() { … }`).',
   );
 };