@vgai/editor 0.2.0

package/template/src/ui/Button.tsx

@@ -0,0 +1,27 @@
+interface ButtonProps {
+  label: string;
+  onClick: () => void;
+  disabled?: boolean;
+}
+
+export function Button({ label, onClick, disabled = false }: ButtonProps) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      style={{
+        background: disabled ? '#222' : '#2a3a4a',
+        color: disabled ? '#555' : '#9cf',
+        border: '1px solid #445',
+        borderRadius: 3,
+        padding: '3px 10px',
+        fontFamily: 'monospace',
+        fontSize: 12,
+        cursor: disabled ? 'not-allowed' : 'pointer',
+      }}
+    >
+      {label}
+    </button>
+  );
+}

package/template/src/ui/DefaultHud.tsx

@@ -0,0 +1,40 @@
+import { useState } from 'react';
+import { Button } from './Button';
+import { Panel } from './Panel';
+
+export interface DefaultHudProps {
+  /** Panel title — plain prop, no VGAI binding-expression language. */
+  title: string;
+}
+
+/**
+ * The template's default game HUD (C1,
+ * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §9 "Make React the
+ * Template Default" / §5.1 React UI Contract): ordinary React — a plain
+ * `.tsx` component driven by props and a `useState` hook, normal inline
+ * styling (no CSS files), no `UINode`/Scene UI binding language.
+ *
+ * Mounted through the existing overlay seam — `mountUI(ctx.uiContainer, ...)`
+ * — by `mount-default-hud.tsx`, called from `../scripts/main.ts`'s `setup()`.
+ * Replace or delete this component freely; it exists to prove (and
+ * demonstrate) the React-HUD-by-default path, not to be load-bearing
+ * gameplay UI.
+ */
+export function DefaultHud({ title }: DefaultHudProps) {
+  const [paused, setPaused] = useState(false);
+
+  return (
+    <Panel title={title} position="top-left">
+      <div
+        data-testid="default-hud-status"
+        style={{ color: paused ? '#dd3d3d' : '#3ddc65', fontSize: 12 }}
+      >
+        {paused ? 'Paused' : 'Running'}
+      </div>
+      <Button
+        label={paused ? 'Resume' : 'Pause'}
+        onClick={() => setPaused((wasPaused) => !wasPaused)}
+      />
+    </Panel>
+  );
+}

package/template/src/ui/KeyHint.tsx

@@ -0,0 +1,25 @@
+interface KeyHintProps {
+  keys: string;
+  label?: string;
+}
+
+export function KeyHint({ keys, label }: KeyHintProps) {
+  return (
+    <span style={{ display: 'flex', alignItems: 'center', gap: 4, color: '#888' }}>
+      <kbd
+        style={{
+          background: '#333',
+          border: '1px solid #555',
+          borderRadius: 3,
+          padding: '1px 5px',
+          fontFamily: 'monospace',
+          fontSize: 11,
+          color: '#ccc',
+        }}
+      >
+        {keys}
+      </kbd>
+      {label && <span>{label}</span>}
+    </span>
+  );
+}

package/template/src/ui/Panel.tsx

@@ -0,0 +1,52 @@
+import type { ReactNode } from 'react';
+
+type Position = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+interface PanelProps {
+  title: string;
+  position?: Position;
+  children: ReactNode;
+}
+
+const positionStyles: Record<Position, React.CSSProperties> = {
+  'top-left': { top: 8, left: 8 },
+  'top-right': { top: 8, right: 8 },
+  'bottom-left': { bottom: 8, left: 8 },
+  'bottom-right': { bottom: 8, right: 8 },
+};
+
+export function Panel({ title, position = 'bottom-left', children }: PanelProps) {
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        ...positionStyles[position],
+        background: 'rgba(18,18,18,0.88)',
+        border: '1px solid #444',
+        borderRadius: 4,
+        padding: '8px 12px',
+        fontFamily: 'monospace',
+        fontSize: 12,
+        color: '#ddd',
+        minWidth: 180,
+        pointerEvents: 'auto',
+        userSelect: 'none',
+      }}
+    >
+      <div
+        style={{
+          color: '#aaa',
+          fontSize: 10,
+          textTransform: 'uppercase',
+          letterSpacing: 1,
+          marginBottom: 8,
+          borderBottom: '1px solid #333',
+          paddingBottom: 4,
+        }}
+      >
+        {title}
+      </div>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>{children}</div>
+    </div>
+  );
+}

package/template/src/ui/RebindPanel.tsx

@@ -0,0 +1,129 @@
+import type { InputManager } from '@engine/input/input-manager';
+import { RebindController, type RebindState } from '@engine/input/rebind-controller';
+import { useCallback, useEffect, useReducer, useRef, useState } from 'react';
+import { Button } from './Button';
+import { Panel } from './Panel';
+
+export interface RebindPanelProps {
+  /** The running game's InputManager (`ctx.input`) — this component reads
+   *  and mutates it directly through F3's public rebinding API
+   *  (`getBindings`/`replaceBinding`/`resetBindings`/`getPrompt`), the same
+   *  API a CLI/SDK caller would use at the file level via B2's
+   *  `project.inputMap.*` operations. */
+  input: InputManager;
+  /** Which registered actions to list/rebind (e.g. the game's own
+   *  `input.actionNames()`, or a curated subset for this HUD). */
+  actionNames: string[];
+}
+
+/**
+ * F3 (spec §12 "Add Rebinding and Prompts") — a keyboard rebinding panel,
+ * demonstrating the AC "Rebinding UI is normal React, not Scene UI": this is
+ * an ordinary `.tsx` component (props + `useState`/`useReducer`/`useEffect`,
+ * plain inline styling via the C1 kit's `Panel`/`Button`) with no
+ * `@vgai/scene-ui` import and no `UINode` anywhere — mount it exactly like
+ * `DefaultHud` (`mountUI(ctx.uiContainer, <RebindPanel input={ctx.input}
+ * actionNames={[...]} />)`).
+ *
+ * All the actual rebind LOGIC (listening -> capture -> apply, with a
+ * collision surfaced structurally instead of silently applied) lives in the
+ * framework-free `RebindController` (`@engine/input/rebind-controller`) —
+ * this component is a thin wire-up: it forwards a captured `keydown` to
+ * `controller.capture()` while listening, and renders whatever `RebindState`
+ * comes back. That split is what makes the interaction itself unit-testable
+ * with no DOM (`packages/engine/test/rebind-controller.test.ts`); this file
+ * only needs a structural check
+ * (`packages/engine/test/input-rebind-panel-structural.test.ts`) that it
+ * really does wire up that controller instead of reinventing the state
+ * machine inline.
+ */
+export function RebindPanel({ input, actionNames }: RebindPanelProps) {
+  const controllerRef = useRef<RebindController | null>(null);
+  if (!controllerRef.current) controllerRef.current = new RebindController(input);
+  const controller = controllerRef.current;
+
+  const [rebindState, setRebindState] = useState<RebindState>(() => controller.getState());
+  // Bindings/prompts are read straight off `input` (mutable, not React
+  // state) on every render — this reducer's only job is forcing a re-render
+  // after a mutation (reset/apply) that doesn't itself change `rebindState`
+  // in a way React would otherwise notice.
+  const [, forceRefresh] = useReducer((n: number) => n + 1, 0);
+
+  useEffect(() => {
+    if (rebindState.status !== 'listening') return undefined;
+    const onKeyDown = (e: KeyboardEvent) => {
+      e.preventDefault();
+      setRebindState(controller.capture({ type: 'key', code: e.code }));
+      forceRefresh();
+    };
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [rebindState.status, controller]);
+
+  const startListening = useCallback(
+    (actionName: string) => {
+      controller.listen(actionName, 'replace', 0);
+      setRebindState(controller.getState());
+    },
+    [controller],
+  );
+
+  const cancelListening = useCallback(() => {
+    controller.cancel();
+    setRebindState(controller.getState());
+  }, [controller]);
+
+  const overrideConflict = useCallback(() => {
+    setRebindState(controller.resolveOverride());
+    forceRefresh();
+  }, [controller]);
+
+  const resetAction = useCallback(
+    (actionName: string) => {
+      input.resetBindings(actionName);
+      forceRefresh();
+    },
+    [input],
+  );
+
+  const isListening = rebindState.status === 'listening';
+
+  return (
+    <Panel title="Rebind Controls" position="top-right">
+      {actionNames.map((actionName) => {
+        const listeningForThis = isListening && rebindState.actionName === actionName;
+        const bindings = input.getBindings(actionName);
+        const prompt = input.getPrompt(actionName, 'keyboard');
+        const currentLabel = listeningForThis
+          ? 'Press a key…'
+          : (prompt?.label ?? (bindings.length > 0 ? bindings[0]!.type : 'Unbound'));
+        return (
+          <div key={actionName} style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+            <span style={{ flex: 1, color: '#ccc' }}>{actionName}</span>
+            <span style={{ color: '#9cf', minWidth: 72, textAlign: 'right' }}>{currentLabel}</span>
+            <Button
+              label="Rebind"
+              onClick={() => startListening(actionName)}
+              disabled={isListening}
+            />
+            <Button label="Reset" onClick={() => resetAction(actionName)} disabled={isListening} />
+          </div>
+        );
+      })}
+      {rebindState.status === 'conflict' && (
+        <div style={{ color: '#f66', display: 'flex', flexDirection: 'column', gap: 4 }}>
+          <span>Conflicts with: {rebindState.conflicts.map((c) => c.actionName).join(', ')}</span>
+          <div style={{ display: 'flex', gap: 6 }}>
+            <Button label="Use Anyway" onClick={overrideConflict} />
+            <Button label="Cancel" onClick={cancelListening} />
+          </div>
+        </div>
+      )}
+      {isListening && (
+        <div style={{ display: 'flex' }}>
+          <Button label="Cancel" onClick={cancelListening} />
+        </div>
+      )}
+    </Panel>
+  );
+}

package/template/src/ui/Slider.tsx

@@ -0,0 +1,28 @@
+interface SliderProps {
+  label: string;
+  value: number;
+  min: number;
+  max: number;
+  step?: number;
+  onChange: (value: number) => void;
+}
+
+export function Slider({ label, value, min, max, step = 0.01, onChange }: SliderProps) {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+      <span style={{ minWidth: 90, color: '#ccc' }}>{label}</span>
+      <input
+        type="range"
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        onChange={(e) => onChange(parseFloat(e.target.value))}
+        style={{ flex: 1, accentColor: '#4af', cursor: 'pointer' }}
+      />
+      <span style={{ minWidth: 36, textAlign: 'right', color: '#aaa' }}>
+        {value.toFixed(step < 0.1 ? 2 : 1)}
+      </span>
+    </div>
+  );
+}

package/template/src/ui/StatusDot.tsx

@@ -0,0 +1,22 @@
+interface StatusDotProps {
+  color: string;
+  label: string;
+}
+
+export function StatusDot({ color, label }: StatusDotProps) {
+  return (
+    <span style={{ display: 'flex', alignItems: 'center', gap: 6, color: '#ccc' }}>
+      <span
+        style={{
+          width: 8,
+          height: 8,
+          borderRadius: '50%',
+          background: color,
+          flexShrink: 0,
+          boxShadow: `0 0 4px ${color}`,
+        }}
+      />
+      {label}
+    </span>
+  );
+}

package/template/src/ui/Toggle.tsx

@@ -0,0 +1,19 @@
+interface ToggleProps {
+  label: string;
+  value: boolean;
+  onChange: (value: boolean) => void;
+}
+
+export function Toggle({ label, value, onChange }: ToggleProps) {
+  return (
+    <label style={{ display: 'flex', alignItems: 'center', gap: 8, cursor: 'pointer' }}>
+      <span style={{ flex: 1, color: '#ccc' }}>{label}</span>
+      <input
+        type="checkbox"
+        checked={value}
+        onChange={(e) => onChange(e.target.checked)}
+        style={{ accentColor: '#4af', width: 14, height: 14, cursor: 'pointer' }}
+      />
+    </label>
+  );
+}

package/template/src/ui/game-state.tsx

@@ -0,0 +1,37 @@
+/**
+ * Thin re-export of the engine-published state bridge (D-Z5,
+ * `docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md` §D-Z5) — `GameProvider`/`useGame`/
+ * `useGameState`/`useWorldObservation` now live canonically at
+ * `@engine/react/game-state` (`packages/engine/src/react/game-state.tsx`,
+ * the spec this file used to BE before D-Z5; see that module's doc comment
+ * for the full implementation and the context-identity rule it documents).
+ *
+ * This file KEEPS EXISTING on purpose — every scaffolded project still has
+ * `src/ui/game-state.tsx`, so:
+ *   - `packages/editor/vite-plugin-react-world-provider.ts`'s virtual module
+ *     (`export { GameProvider } from '/@fs/<root>/src/ui/game-state.tsx'`)
+ *     keeps working byte-for-byte — it re-exports from THIS file, which now
+ *     re-exports from the engine, but the file it points at (and the
+ *     identity `useGame()` resolves against) is unchanged.
+ *   - a react-world entry's own relative `import { useGameState } from
+ *     './ui/game-state'` keeps resolving here too — both routes still
+ *     converge on ONE module instance (this file), which itself resolves the
+ *     engine's `@engine/react/game-state` exactly once, so `createContext()`
+ *     runs exactly once per project. No context split.
+ *
+ * Adoption of the engine module is an OPTION, not a migration: existing
+ * projects that already have their OWN full copy of this file (their own
+ * `createContext`) are untouched by this change — only NEW projects
+ * scaffolded from the template get this canonical re-export. A project that
+ * wants a customized bridge can still replace this file with its own full
+ * implementation, exactly as before.
+ */
+
+export {
+  GameProvider,
+  requireWorldObserver,
+  shallow,
+  useGame,
+  useGameState,
+  useWorldObservation,
+} from '@engine/react/game-state';

package/template/src/ui/index.ts

@@ -0,0 +1,7 @@
+export { Button } from './Button';
+export { KeyHint } from './KeyHint';
+export { Panel } from './Panel';
+export { RebindPanel } from './RebindPanel';
+export { Slider } from './Slider';
+export { StatusDot } from './StatusDot';
+export { Toggle } from './Toggle';

package/template/src/ui/mount-default-hud.tsx

@@ -0,0 +1,19 @@
+import { DefaultHud } from './DefaultHud';
+import { mountUI } from './mount-ui';
+
+/**
+ * Mounts the template's default React HUD into the shared UI overlay
+ * (`ctx.uiContainer` — `pointer-events:none`; `Panel`/`Button` inside opt
+ * back in via `pointer-events:auto`, so the game canvas keeps receiving
+ * pointer events everywhere except the HUD's own controls) and returns an
+ * unmount function. Kept as its own `.tsx` module so `../scripts/main.ts` —
+ * the game SETUP script, not a component — never needs JSX syntax itself.
+ *
+ * Usage (see `../scripts/main.ts`):
+ *   const unmountHud = mountDefaultHud(ctx.uiContainer);
+ *   // ... later, in the returned GameCleanup:
+ *   //   dispose() { unmountHud(); sceneInstance.dispose(); }
+ */
+export function mountDefaultHud(container: HTMLDivElement): () => void {
+  return mountUI(container, <DefaultHud title="Game Status" />);
+}

package/template/src/ui/mount-ui.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+import { createRoot } from 'react-dom/client';
+
+/**
+ * Mount a React element into a container div and return a cleanup function.
+ *
+ * Usage in example dispose():
+ *   const unmount = mountUI(ctx.uiContainer, <MyHUD />);
+ *   return { dispose: unmount };
+ */
+export function mountUI(container: HTMLDivElement, element: ReactNode): () => void {
+  const root = createRoot(container);
+  root.render(element);
+  return () => root.unmount();
+}

package/template/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "exactOptionalPropertyTypes": true,
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "verbatimModuleSyntax": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "types": ["vite/client"],
+    "baseUrl": ".",
+    "paths": {
+      "@engine/*": ["../../engine/src/*"],
+      "@editor/*": ["../src/*"]
+    }
+  },
+  "files": [
+    "../../engine/src/types-n8ao.d.ts",
+    "../../engine/src/types-realism-effects.d.ts"
+  ],
+  "include": ["src"]
+}

package/template/validate-asset-content.ts

@@ -0,0 +1,78 @@
+import { readFileSync } from 'node:fs';
+import { InputMapFileSchema } from '@vgai/engine/input/schema';
+import { parseInstancesFile, parseMaterialFile, SceneParseError } from '@vgai/engine/scene/parse';
+
+// ---------------------------------------------------------------------------
+// Content validation for the fetched-asset formats (`.mat.json` /
+// `.inputmap.json` / `.instances.json`), through the SAME
+// engine Zod schemas the runtime rejects them with at fetch time. Used by
+// `validate-scenes.ts` (the `npm run validate-scenes` command —
+// previously these formats were only existence-checked when a scene
+// referenced them, so a present-but-malformed asset passed the command and
+// failed at load) and directly unit-testable against a tmpdir
+// (`packages/editor/test/validate-asset-content.test.ts`) so broken fixtures
+// never need to live inside the template.
+//
+// Separate module (rather than inline in validate-scenes.ts) because
+// validate-scenes.ts is a top-level script — importing it executes it.
+// ---------------------------------------------------------------------------
+
+/** The asset formats this module content-validates (engine Zod schemas). */
+export const ASSET_CONTENT_EXTENSIONS = ['.mat.json', '.inputmap.json', '.instances.json'] as const;
+
+/**
+ * Content-parse one asset file through its engine Zod schema. Returns error
+ * strings in validate-scenes' established `${file}: ${path}: ${message}`
+ * format (empty array = valid). Throws only on a programming error (a path
+ * that isn't one of the three supported formats).
+ */
+export function validateAssetContentFile(path: string): string[] {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf-8'));
+  } catch (e) {
+    return [`${path}: invalid JSON — ${e instanceof Error ? e.message : String(e)}`];
+  }
+
+  const errors: string[] = [];
+  if (path.endsWith('.mat.json')) {
+    // The engine has a ready-made SceneParseError-throwing wrapper for
+    // materials — reuse it (same function the runtime's fetch path uses).
+    try {
+      parseMaterialFile(raw, path);
+    } catch (e) {
+      if (e instanceof SceneParseError) {
+        for (const issue of e.issues) {
+          errors.push(`${path}: ${issue.path.join('.')}: ${issue.message}`);
+        }
+      } else {
+        errors.push(`${path}: ${e}`);
+      }
+    }
+  } else if (path.endsWith('.inputmap.json')) {
+    const result = InputMapFileSchema.safeParse(raw);
+    if (!result.success) {
+      for (const issue of result.error.issues) {
+        errors.push(`${path}: ${issue.path.join('.')}: ${issue.message}`);
+      }
+    }
+  } else if (path.endsWith('.instances.json')) {
+    // Same ready-made SceneParseError-throwing wrapper pattern as .mat.json (F3).
+    try {
+      parseInstancesFile(raw, path);
+    } catch (e) {
+      if (e instanceof SceneParseError) {
+        for (const issue of e.issues) {
+          errors.push(`${path}: ${issue.path.join('.')}: ${issue.message}`);
+        }
+      } else {
+        errors.push(`${path}: ${e}`);
+      }
+    }
+  } else {
+    throw new Error(
+      `validateAssetContentFile: "${path}" is not one of the supported formats (${ASSET_CONTENT_EXTENSIONS.join(', ')})`,
+    );
+  }
+  return errors;
+}

package/template/validate-manifest.ts

@@ -0,0 +1,55 @@
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadGameManifestFile } from '@vgai/engine/manifest/load-file';
+
+// ---------------------------------------------------------------------------
+// Usage: npx tsx validate-manifest.ts [manifestPath...]
+//
+// Single source of truth for game-manifest validation, shipped IN the
+// project template (mirrors validate-scenes.ts) so every scaffolded game
+// gets a working `npm run validate-manifest`. Validates each given
+// `vgai.game.json` path via `loadGameManifestFile` (parse -> cross-field
+// checks -> resolution, see docs/GAME-MANIFEST-DESIGN.md §5) and prints the
+// resolved world list (id, kind, resolved adapter identity, per-context
+// capability tiers) on success. Any failure prints a descriptive error and
+// exits 1.
+//
+// Defaults to THIS template's own manifest (`vgai.game.json`, a sibling of
+// this script) when no path is given, so `npm run validate-manifest` works
+// out of the box both from the monorepo root and from a scaffolded project.
+// ---------------------------------------------------------------------------
+
+const defaultManifestPath = fileURLToPath(new URL('./vgai.game.json', import.meta.url));
+
+const args = process.argv.slice(2);
+const manifestPaths = args.length > 0 ? args.map((p) => resolve(p)) : [defaultManifestPath];
+
+let hadError = false;
+
+for (const manifestPath of manifestPaths) {
+  try {
+    const resolved = loadGameManifestFile(manifestPath);
+    console.log(
+      `${manifestPath}: OK — "${resolved.name}" v${resolved.version} (engine ${resolved.engine.version})`,
+    );
+    for (const world of resolved.worlds) {
+      const { adapter } = world;
+      const adapterLabel =
+        adapter.type === 'ingest' ? `${adapter.identity} (${adapter.strategy})` : adapter.identity;
+      console.log(
+        `  world "${world.id}" kind=${world.kind} adapter=${adapterLabel} ` +
+          `tiers={local: ${world.capabilities.local}, hosted: ${world.capabilities.hosted}}`,
+      );
+    }
+  } catch (e) {
+    hadError = true;
+    console.error(`${manifestPath}: FAILED`);
+    console.error(`  ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+
+if (hadError) {
+  process.exit(1);
+} else {
+  console.log(`Validated ${manifestPaths.length} manifest(s) — all OK`);
+}