@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

package/src/react/game-state.tsx

@@ -1,8 +1,9 @@
 /**
- * Engine-PUBLISHED `GameProvider`/`useGame`/`useGameState`/`useWorldObservation`
- * (D-Z5, `docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md` §D-Z5) — the canonical,
- * opt-in react entry for the T7.4 state bridge (`docs/REACT-STATE-BRIDGE.md`
- * §3). This is a SEPARATE, react-value-importing module under
+ * Canonical `GameProvider`/`useGame`/`useGameState`/`useWorldObservation`
+ * entry for React adapter roots. Also home to `useDebugProvider` and
+ * `useDebugCommand`/`useDebugEmit`, the React-facing debug seam.
+ *
+ * This is a SEPARATE, react-value-importing module under
  * `packages/engine/src/react/` — colocated per REACT-STATE-BRIDGE §3's own
  * "colocate the react-facing hooks with the HUD seam, not the react-free
  * core" rule, just now living IN the engine package rather than only in the
@@ -11,34 +12,26 @@
  * invariant is proved by `packages/engine/test/react-core-import-ban.test.ts`
  * (AC-F1).
  *
- * This module is the SPEC others port faithfully: it was originally authored
- * as `packages/editor/template/src/ui/game-state.tsx` (T7.4); that file is
- * now a thin re-export of this one (D-Z5 step 3) so every NEW scaffolded
- * project gets ONE canonical context, while existing projects with their own
- * full copy (their own `createContext`) keep working untouched — adoption of
- * THIS module is an option, never a forced migration (D-Z5).
- *
- * Context-identity landmine (unchanged from the template file's own history,
- * still the reason `loadProjectGameProvider`/the virtual-module plugin exist
- * in `packages/editor/src/adapter-resolver.ts` /
- * `packages/editor/vite-plugin-react-world-provider.ts`): `<GameProvider>`
- * and `useGame()` must resolve against the SAME `createContext()` call. A
- * project that ships its OWN `src/ui/game-state.tsx` (its own
- * `createContext`) must be wrapped by ITS OWN `GameProvider` — wrapping it
- * with THIS module's `GameProvider` instead would split context and
- * `useGame()` would throw "no Game in context" even though a `<GameProvider>`
- * genuinely wraps the tree (proved by
- * `packages/editor/test/game-state-context-split.test.tsx`, AC-F1). This is
- * exactly why the engine-published fallback (`resolveIngestReactAdapter`'s
- * D-Y3 upgrade, `default-react`'s optional fallback) only ever fires when the
- * project's OWN `src/ui/game-state.tsx` is ABSENT — an unmodified foreign
- * entry that imports no vgai hooks has no context to split.
+ * Every host and game imports this one module, so provider and hooks share
+ * one `createContext()` identity. The engine core outside `src/react/`
+ * remains React-free, enforced by `react-core-import-ban.test.ts`.
  */
 
-import { createContext, type ReactNode, useContext, useRef, useSyncExternalStore } from 'react';
+import {
+  createContext,
+  type PropsWithChildren,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useSyncExternalStore,
+} from 'react';
+import type { z } from 'zod';
 import type { WorldStateObserver } from '../adapter';
+import { getDebugRegistry } from '../runtime/debug-registry';
 import { createFrameSelectorCache, type Equals, shallow } from '../runtime/frame-selector-cache';
 import type { Game } from '../runtime/game';
+import type { DebugCommandArgs } from '../runtime/types';
 
 /** Re-exported for convenience — the opt-in equality for selectors that
  *  return a fresh object/array/tuple every call (default is `Object.is`). */
@@ -47,10 +40,21 @@ export { shallow };
 const GameContext = createContext<Game | null>(null);
 
 /** Provide the `Game` to `useGameState`/`useGame` for everything mounted
- *  beneath it. Compose it around whatever renders your tree (`mountUI`, a
- *  react world's `createRoot(...).render(...)`, etc.) — see the module doc
- *  comment above for the context-identity rule this hook family depends on. */
-export function GameProvider({ game, children }: { game: Game; children: ReactNode }) {
+ *  beneath it. Adapter-root hosts install this provider automatically — see the module doc
+ *  comment above for the context-identity rule this hook family depends on.
+ *
+ *  Props use `PropsWithChildren` (children optional in the TYPE, not
+ *  runtime-optional in practice — you always want children mounted under
+ *  the provider) rather than a bare `{ children: ReactNode }` field: a
+ *  required `children` in `P` makes TS's `createElement<P>(type, props?:
+ *  Attributes & P, ...children)` overload reject the plain 3-arg call
+ *  `React.createElement(GameProvider, { game }, child)` (no JSX transform,
+ *  e.g. a `.ts` main composing a sibling `.tsx` HUD) with "Property
+ *  'children' is missing" even though the 3rd arg supplies it — issue #97.
+ *  Making `children` optional in the type lets that overload resolve; the
+ *  rest-arg children are still wired through to `children` at runtime by
+ *  React itself, unchanged. See `test/game-state-create-element-types.test.tsx`. */
+export function GameProvider({ game, children }: PropsWithChildren<{ game: Game }>) {
   return <GameContext.Provider value={game}>{children}</GameContext.Provider>;
 }
 
@@ -109,7 +113,7 @@ export function requireWorldObserver(game: Game, worldId: string): WorldStateObs
   const world = game.world(worldId);
   if (!world) {
     throw new Error(
-      `useWorldObservation: no world registered with id "${worldId}" — check game.worlds for the ` +
+      `useWorldObservation: no world registered with id "${worldId}" — check game.roots for the ` +
         'ids actually registered.',
     );
   }
@@ -170,3 +174,102 @@ export function useWorldObservation<T>(
     () => cacheRef.current!.get(versionRef.current, () => selector(observer.snapshot())),
   );
 }
+
+/**
+ * The debug seam's react-world registration door (Task 1.5,
+ * `docs/SYNTHETIC-PLAYER-SPEC.md` §3.1): react roots have no `setup()`/
+ * `ctx.debug` of their own, so this hook registers a named state provider
+ * into the SAME game-scoped registry every `GameComponent`'s `ctx.debug`
+ * feeds (`getDebugRegistry(game)`, `runtime/debug-registry.ts`), readable
+ * through `game.systemAdapters.debug.state(name)` exactly like a
+ * `ctx.debug.registerStateProvider` call.
+ *
+ * Registers ONCE per mount (keyed on `name`) and unregisters on unmount —
+ * silently, like hot-reload's `strip()`. Re-renders never re-register or
+ * re-warn: `fn` is kept in a ref updated every render, so the registered
+ * closure always calls the CURRENT `fn` without touching the registry.
+ * Outside a `<GameProvider>` (or against a bare test `Game` built without a
+ * registry) this is an inert no-op — it never throws, matching the "no seam
+ * without a consumer" degrade every optional `ctx.*` surface follows.
+ */
+export function useDebugProvider(
+  name: string,
+  fn: () => unknown,
+  opts?: { tier?: 'observable' | 'assisted' },
+): void {
+  const game = useContext(GameContext);
+  const fnRef = useRef(fn);
+  fnRef.current = fn;
+  const tier = opts?.tier;
+
+  useEffect(() => {
+    const registry = game && getDebugRegistry(game);
+    if (!registry) return;
+    return registry.registerReactProvider(name, () => fnRef.current(), { tier });
+    // `tier` is deliberately NOT a dep (same reasoning as `useDebugCommand`'s
+    // `spec`) — captured once at mount, so it never forces re-registration.
+  }, [game, name]);
+}
+
+/**
+ * The command-side counterpart of {@link useDebugProvider} — registers an
+ * invokable debug command into the same game-scoped registry, readable
+ * through `game.systemAdapters.debug.commands()`/`invoke(name, args)`.
+ *
+ * Same mount/unmount/ref-latest contract as {@link useDebugProvider}: `spec`
+ * (description/args/locus) is captured at registration time, `fn` always
+ * calls through to the latest render's closure via a ref, and the hook is an
+ * inert no-op with no `<GameProvider>` in scope.
+ *
+ * Generic over the declared `args` Zod tuple, same as
+ * `DebugCtxSurface.registerCommand` ({@link DebugCommandArgs}, dry-run
+ * finding — `docs/ACCEPTANCE-DRIVER-BUILD-PLAN.md` Wave 6 ledger): declaring
+ * `args: z.tuple([z.number(), z.string()])` types `fn`'s parameters as
+ * `(n: number, s: string) => ...` with no `unknown[]` cast; omitting `args`
+ * keeps `fn` typed `(...args: unknown[]) => ...` as before.
+ */
+export function useDebugCommand<T extends z.ZodTuple | undefined = undefined>(
+  name: string,
+  spec: { description?: string; args?: T; locus?: 'client' | 'server' },
+  fn: (...args: DebugCommandArgs<T>) => unknown | Promise<unknown>,
+): void {
+  const game = useContext(GameContext);
+  const fnRef = useRef(fn);
+  fnRef.current = fn;
+
+  useEffect(() => {
+    const registry = game && getDebugRegistry(game);
+    if (!registry) return;
+    return registry.registerReactCommand(name, spec, (...args: DebugCommandArgs<T>) =>
+      fnRef.current(...args),
+    );
+    // `spec` is deliberately NOT a dep (like `equals` above) — captured once
+    // at mount, so a fresh inline object literal every render never forces
+    // re-registration.
+  }, [game, name]);
+}
+
+/**
+ * The event-side counterpart of {@link useDebugProvider} and
+ * {@link useDebugCommand}. Returns a stable callback that writes a
+ * tick-stamped event to the game-scoped debug flight recorder:
+ *
+ * ```tsx
+ * const emit = useDebugEmit();
+ * emit('score-changed', { score });
+ * ```
+ *
+ * It is an inert no-op outside a `<GameProvider>`, matching the optional
+ * behavior of the other React debug hooks. Games never need to import the
+ * debug registry or know its internal React provenance id.
+ */
+export function useDebugEmit(): (event: string, detail?: unknown) => void {
+  const game = useContext(GameContext);
+  return useCallback(
+    (event: string, detail?: unknown) => {
+      if (!game) return;
+      getDebugRegistry(game)?.emitReact(event, detail);
+    },
+    [game],
+  );
+}

package/src/react/root-adapter.tsx

@@ -0,0 +1,49 @@
+import { type ComponentType, createElement } from 'react';
+import { flushSync } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+import type { MountedReactGame, ReactRootAdapter, ReactWorldHost } from '../runtime/create-runtime';
+import { isAdapterRegistered, registerAdapter } from '../runtime/mount-game';
+import { GameProvider } from './game-state';
+
+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: ReactWorldHost): Promise<MountedReactGame> {
+      if (!host.game) throw new Error(`React root "${id}" requires a Game host.`);
+      const reactRoot = createRoot(host.container);
+      flushSync(() => {
+        reactRoot.render(createElement(GameProvider, { game: host.game! }, createElement(Entry)));
+      });
+      return {
+        kind: 'react',
+        container: host.container,
+        drivesOwnLoop: false,
+        dispose: () => reactRoot.unmount(),
+      };
+    },
+  };
+}
+
+/**
+ * Register the engine's React adapter-root factory. This module is an
+ * explicit optional React entry point: engine core never imports it, while a
+ * React game host imports it once and receives the canonical root lifecycle.
+ */
+export function registerReactAdapter(): void {
+  if (isAdapterRegistered('react')) return;
+  registerAdapter('react', (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: 'react', adapter: createReactRootAdapter(root.id, Entry) };
+  });
+}

package/src/react/unmanaged-root-detector.ts

@@ -0,0 +1,66 @@
+export interface UnmanagedReactRootFinding {
+  readonly file: string;
+  readonly line: number;
+  readonly api: 'createRoot' | 'hydrateRoot' | 'ReactDOM.render';
+}
+
+function lineAt(source: string, offset: number): number {
+  return source.slice(0, offset).split('\n').length;
+}
+
+/**
+ * Find project-owned React DOM root creation. VGAI hosts React through
+ * manifest adapter roots, so any of these calls in game source creates an
+ * unmanaged second lifecycle and is a hard validation error.
+ */
+export function detectUnmanagedReactRoots(
+  source: string,
+  file: string,
+): UnmanagedReactRootFinding[] {
+  const findings: UnmanagedReactRootFinding[] = [];
+  const aliases = new Map<string, 'createRoot' | 'hydrateRoot'>();
+
+  for (const match of source.matchAll(/import\s*\{([^}]*)\}\s*from\s*['"]react-dom\/client['"]/g)) {
+    for (const member of (match[1] ?? '').split(',')) {
+      const parsed = member.trim().match(/^(createRoot|hydrateRoot)(?:\s+as\s+([\w$]+))?$/);
+      if (parsed) aliases.set(parsed[2] ?? parsed[1]!, parsed[1] as 'createRoot' | 'hydrateRoot');
+    }
+  }
+
+  for (const [alias, api] of aliases) {
+    const call = new RegExp(`\\b${alias.replace(/[$]/g, '\\$&')}\\s*\\(`, 'g');
+    for (const match of source.matchAll(call)) {
+      findings.push({ file, line: lineAt(source, match.index ?? 0), api });
+    }
+  }
+
+  const namespaceNames = new Set<string>();
+  for (const match of source.matchAll(
+    /import\s+(?:\*\s+as\s+|)([\w$]+)\s+from\s*['"]react-dom(?:\/client)?['"]/g,
+  )) {
+    namespaceNames.add(match[1]!);
+  }
+  namespaceNames.add('ReactDOM');
+  for (const name of namespaceNames) {
+    for (const api of ['createRoot', 'hydrateRoot', 'render'] as const) {
+      const call = new RegExp(`\\b${name}\\.${api}\\s*\\(`, 'g');
+      for (const match of source.matchAll(call)) {
+        findings.push({
+          file,
+          line: lineAt(source, match.index ?? 0),
+          api: api === 'render' ? 'ReactDOM.render' : api,
+        });
+      }
+    }
+  }
+
+  return findings.filter(
+    (finding, index) =>
+      findings.findIndex(
+        (candidate) =>
+          candidate.file === finding.file &&
+          candidate.line === finding.line &&
+          candidate.api === finding.api,
+      ) === index,
+  );
+}

package/src/react/use-data.ts

@@ -5,11 +5,11 @@
  * Lives under `packages/engine/src/react/` deliberately: this is the ONE
  * directory of the engine allowed to value-import react (colocated with
  * `game-state.tsx` per the react-free-core rule proved by
- * `test/react-core-import-ban.test.ts`). Game worlds that aren't react keep
+ * `test/react-core-import-ban.test.ts`). Game roots that aren't react keep
  * using `DataHandle.get()`/`subscribe()` directly (§2.3).
  *
  * - {@link useData} — subscribe a component to any W1 `DataHandle`; works in
- *   project tools, react worlds, and HUD overlays alike.
+ *   project tools, react roots, and HUD overlays alike.
  * - {@link writeData} — EDITOR-TOOL plumbing: write a whole `.data.json`
  *   back through the editor dev server, closing the live-tuning loop
  *   (widget → file write → Vite HMR → `hotSwap` → {@link useData} re-render
@@ -89,6 +89,16 @@ export async function writeData(
       ?.replace(/\.data\.json$/, '')}.schema.json`;
   const content = `${JSON.stringify({ $schema: schemaRef, ...rest }, null, 2)}\n`;
 
+  const transactionalWriter = (
+    globalThis as typeof globalThis & {
+      __vgaiHistoryWriteData?: (path: string, content: string) => Promise<void>;
+    }
+  ).__vgaiHistoryWriteData;
+  if (transactionalWriter) {
+    await transactionalWriter(projectRelativePath, content);
+    return;
+  }
+
   let res: Response;
   try {
     res = await fetch('/__editor/data-file', {