@volter/game-editor 0.5.65

package/template/src/lib/static-batch/mutation-watch.ts

@@ -0,0 +1,149 @@
+/**
+ * THE TRIPWIRE for the one rule `<Frozen>` cannot enforce: its children must
+ * be MOUNT-STATIC.
+ *
+ * A freeze draws the batched products and hides the originals. React still
+ * owns those originals, so nothing stops a game from moving one, re-colouring
+ * it, or un-hiding it — and nothing HAPPENS when it does. The mesh is
+ * invisible; the picture comes from the product; the edit is simply lost. That
+ * is the worst possible failure shape: silent, and indistinguishable from the
+ * mechanic being wrong. An author who animates a door under a `<Frozen>` will
+ * spend an afternoon in the wrong file.
+ *
+ * The contract used to live in a docblock. A docblock describes intent; only a
+ * measurement describes status. So the hidden originals are SAMPLED — the
+ * cheapest reading that catches all three drifts:
+ *   - `matrixWorld`, hashed: it moved, was scaled, or was re-parented;
+ *   - `material.version`, which three bumps on `needsUpdate`: it was re-styled;
+ *   - `visible`, restored to `true` by the game: it thinks it is showing.
+ *
+ * ── COST, AND WHY IT IS A TIMER ─────────────────────────────────────────────
+ * ~1 Hz, and only under {@link devBuildEnabled}. A per-frame check would be a
+ * real cost added by a feature whose entire job is removing cost; a `Proxy` or
+ * accessor trap over every node would change the objects the game is holding.
+ * A second of latency on a diagnostic nobody is waiting for is free, and 4,000
+ * hashes once a second is a rounding error against one frame of the draw calls
+ * this replaced.
+ *
+ * It fires ONCE. The first drift is the finding; a mechanic that runs every
+ * frame would otherwise fill the console with the same line, and the watch
+ * stops itself rather than becoming the noise it exists to prevent.
+ *
+ * ── RESOURCE OWNERSHIP, STATED ONCE ─────────────────────────────────────────
+ * OWNER: the handle {@link watchFrozenMutations} returns, which owns exactly
+ * one interval. SHARERS: none — `Frozen.tsx` holds it and nothing else sees
+ * it. TEARDOWN: that handle's `stop()`, the ONE path that clears the interval,
+ * called from the wrapper's own effect cleanup and by the watch itself after
+ * it warns. Idempotent.
+ */
+
+import { devBuildEnabled } from '@volter/game-runtime/runtime/dev-build';
+import type * as THREE from 'three';
+import type { FrozenBatch } from './freeze';
+
+/** Samples per second. See the module note for why this is a timer at all. */
+export const MUTATION_SAMPLE_MS = 1000;
+
+interface Sample {
+  matrix: number;
+  materialVersions: string;
+  visible: boolean;
+}
+
+/** A cheap order-sensitive fold of the 16 world-matrix elements. Collisions
+ *  are possible in principle and irrelevant in practice: this compares a value
+ *  against ITS OWN previous value, not against another node's. */
+function hashMatrix(mesh: THREE.Object3D): number {
+  const elements = mesh.matrixWorld.elements;
+  let hash = 0;
+  for (let i = 0; i < 16; i++) hash = (hash * 31 + (elements[i] ?? 0)) % 1e12;
+  return hash;
+}
+
+function sample(mesh: THREE.Mesh): Sample {
+  const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+  return {
+    matrix: hashMatrix(mesh),
+    materialVersions: materials.map((material) => material?.version ?? -1).join(','),
+    visible: mesh.visible,
+  };
+}
+
+/** What changed, in the words of the thing that changed it. */
+function drift(before: Sample, after: Sample): string | null {
+  if (after.visible !== before.visible) return 'was made visible again';
+  if (after.matrix !== before.matrix) return 'moved (its world matrix changed)';
+  if (after.materialVersions !== before.materialVersions) return 'had its material changed';
+  return null;
+}
+
+export interface FrozenMutationWatch {
+  /** See the ownership note — the ONE path that ends the watch. Idempotent. */
+  stop(): void;
+}
+
+function warnOnConsole(message: string): void {
+  // biome-ignore lint/suspicious/noConsole: console is this tripwire's vgai-status channel.
+  console.warn(message);
+}
+
+/**
+ * Watch a freeze's hidden originals for the mutations the contract forbids,
+ * and say so once. A no-op outside a dev context, and a no-op when the freeze
+ * hid nothing.
+ */
+export function watchFrozenMutations(
+  batch: FrozenBatch,
+  options: {
+    /** Injectable so the tripwire is provable without a console. */
+    readonly warn?: (message: string) => void;
+    /** Injectable so a test can step time instead of waiting a second. */
+    readonly schedule?: (tick: () => void) => () => void;
+    /** Overrides the dev gate — a headless test passes `true`. */
+    readonly dev?: boolean;
+  } = {},
+): FrozenMutationWatch {
+  const warn = options.warn ?? warnOnConsole;
+  if (!devBuildEnabled(options.dev) || batch.sources.length === 0) {
+    return { stop: () => {} };
+  }
+
+  const baseline = batch.sources.map((source) => sample(source.mesh));
+  let stopped = false;
+  let release: (() => void) | null = null;
+
+  const stop = (): void => {
+    if (stopped) return;
+    stopped = true;
+    release?.();
+    release = null;
+  };
+
+  const tick = (): void => {
+    if (stopped) return;
+    for (let i = 0; i < batch.sources.length; i++) {
+      const source = batch.sources[i];
+      const before = baseline[i];
+      if (!source || !before) continue;
+      const change = drift(before, sample(source.mesh));
+      if (!change) continue;
+      const node = source.mesh.name || '(unnamed)';
+      warn(
+        `[static-batch] "${node}" ${change} while frozen under <Frozen name="${batch.name}"> — ` +
+          'the change will never be visible, because the picture comes from the batched copy ' +
+          'and the original is hidden. Everything under a <Frozen> must be mount-static: move ' +
+          'this node OUT of the wrapper, or mark its subtree userData={{ staticBatch: false }}.',
+      );
+      stop();
+      return;
+    }
+  };
+
+  if (options.schedule) {
+    release = options.schedule(tick);
+  } else {
+    const timer = setInterval(tick, MUTATION_SAMPLE_MS);
+    release = () => clearInterval(timer);
+  }
+  return { stop };
+}

package/template/src/lib/static-batch/shadow-cache.ts

@@ -0,0 +1,171 @@
+/** Reuse directional shadow maps only while every caster is declared mount-static. */
+
+import type * as THREE from 'three';
+import { activeFrozenBatches, type FrozenBatch } from './freeze';
+
+export interface FrozenDirectionalShadowController {
+  update(): void;
+  dispose(): void;
+}
+
+function belongsTo(node: THREE.Object3D, ancestor: THREE.Object3D): boolean {
+  for (let cursor: THREE.Object3D | null = node; cursor !== null; cursor = cursor.parent) {
+    if (cursor === ancestor) return true;
+  }
+  return false;
+}
+
+function matrixChanged(
+  node: THREE.Object3D,
+  snapshots: Map<THREE.Object3D, THREE.Matrix4>,
+): boolean {
+  node.updateWorldMatrix(true, false);
+  const previous = snapshots.get(node);
+  if (previous?.equals(node.matrixWorld)) return false;
+  if (previous === undefined) snapshots.set(node, node.matrixWorld.clone());
+  else previous.copy(node.matrixWorld);
+  return true;
+}
+
+function projectionChanged(
+  camera: THREE.Camera,
+  snapshots: Map<THREE.Camera, THREE.Matrix4>,
+): boolean {
+  const projectable = camera as THREE.Camera & { updateProjectionMatrix?: () => void };
+  projectable.updateProjectionMatrix?.();
+  const previous = snapshots.get(camera);
+  if (previous?.equals(camera.projectionMatrix)) return false;
+  if (previous === undefined) snapshots.set(camera, camera.projectionMatrix.clone());
+  else previous.copy(camera.projectionMatrix);
+  return true;
+}
+
+function collectDirectionalShadowLights(
+  root: THREE.Object3D,
+  lights: Set<THREE.DirectionalLight>,
+): void {
+  root.traverseVisible((node) => {
+    const light = node as THREE.DirectionalLight;
+    if (light.isDirectionalLight && light.castShadow) lights.add(light);
+  });
+}
+
+function inspectOutsideFrozen(
+  node: THREE.Object3D,
+  frozenRoots: ReadonlySet<THREE.Object3D>,
+  lights: Set<THREE.DirectionalLight>,
+): boolean {
+  if (!node.visible || frozenRoots.has(node)) return false;
+  const light = node as THREE.DirectionalLight;
+  if (light.isDirectionalLight && light.castShadow) lights.add(light);
+  let caster = (node as THREE.Mesh).isMesh === true && (node as THREE.Mesh).castShadow;
+  for (const child of node.children) {
+    caster = inspectOutsideFrozen(child, frozenRoots, lights) || caster;
+  }
+  return caster;
+}
+
+function sceneBatches(scene: THREE.Object3D): readonly FrozenBatch[] {
+  return activeFrozenBatches().filter((batch) => belongsTo(batch.root, scene));
+}
+
+interface ShadowControllerState {
+  readonly objectMatrices: Map<THREE.Object3D, THREE.Matrix4>;
+  readonly cameraProjections: Map<THREE.Camera, THREE.Matrix4>;
+  readonly controlledLights: Set<THREE.DirectionalLight>;
+  readonly frozenLights: Set<THREE.DirectionalLight>;
+  previousBatches: Set<FrozenBatch>;
+  hadOutsideCaster: boolean;
+}
+
+function batchesChanged(batches: readonly FrozenBatch[], previous: ReadonlySet<FrozenBatch>) {
+  return batches.length !== previous.size || batches.some((batch) => !previous.has(batch));
+}
+
+function updateLight(
+  light: THREE.DirectionalLight,
+  external: boolean,
+  staticInputChanged: boolean,
+  state: ShadowControllerState,
+): void {
+  state.controlledLights.add(light);
+  if (external) {
+    light.shadow.autoUpdate = true;
+    light.shadow.needsUpdate = true;
+    return;
+  }
+  // Snapshot every input on the first invalidation. A short-circuit expression here would
+  // discover one previously unseen input per frame and redraw the same initial map four times.
+  const lightMoved = matrixChanged(light, state.objectMatrices);
+  const targetMoved = matrixChanged(light.target, state.objectMatrices);
+  const projectionMoved = projectionChanged(light.shadow.camera, state.cameraProjections);
+  light.shadow.autoUpdate = false;
+  if (staticInputChanged || lightMoved || targetMoved || projectionMoved) {
+    light.shadow.needsUpdate = true;
+  }
+}
+
+function updateController(scene: THREE.Object3D, state: ShadowControllerState): void {
+  const batches = sceneBatches(scene);
+  const roots = new Set(batches.map((batch) => batch.root));
+  const batchSetChanged = batchesChanged(batches, state.previousBatches);
+  state.previousBatches = new Set(batches);
+
+  if (batchSetChanged) {
+    state.frozenLights.clear();
+    for (const root of roots) collectDirectionalShadowLights(root, state.frozenLights);
+  }
+  const nextLights = new Set(state.frozenLights);
+  const outsideCaster = inspectOutsideFrozen(scene, roots, nextLights);
+  const external = batches.length === 0 || outsideCaster;
+  let staticInputChanged = batchSetChanged || external !== state.hadOutsideCaster;
+  state.hadOutsideCaster = external;
+  for (const root of roots) {
+    staticInputChanged = matrixChanged(root, state.objectMatrices) || staticInputChanged;
+  }
+  for (const light of nextLights) updateLight(light, external, staticInputChanged, state);
+
+  for (const light of state.controlledLights) {
+    if (nextLights.has(light)) continue;
+    light.shadow.autoUpdate = true;
+    light.shadow.needsUpdate = true;
+    state.controlledLights.delete(light);
+  }
+}
+
+/**
+ * Three redraws every directional shadow map every frame by default. A mounted `Frozen` subtree
+ * promises that its descendants do not change, so a scene whose ENTIRE caster set is covered by
+ * those declarations can reuse its depth map until a wrapper, light, target, or shadow camera
+ * changes. A caster anywhere outside a Frozen root immediately restores Three's ordinary
+ * per-frame path; reactive content is never guessed to be static.
+ */
+export function createFrozenDirectionalShadowController(
+  scene: THREE.Object3D,
+): FrozenDirectionalShadowController {
+  const state: ShadowControllerState = {
+    objectMatrices: new Map(),
+    cameraProjections: new Map(),
+    controlledLights: new Set(),
+    frozenLights: new Set(),
+    previousBatches: new Set(),
+    hadOutsideCaster: true,
+  };
+
+  return {
+    update(): void {
+      updateController(scene, state);
+    },
+    dispose(): void {
+      for (const light of state.controlledLights) {
+        light.shadow.autoUpdate = true;
+        light.shadow.needsUpdate = true;
+      }
+      state.controlledLights.clear();
+      state.frozenLights.clear();
+      state.objectMatrices.clear();
+      state.cameraProjections.clear();
+      state.previousBatches.clear();
+    },
+  };
+}

package/template/src/main.ts

@@ -0,0 +1,63 @@
+/**
+ * Standalone entry point.
+ *
+ * One `mountGameFromManifest` call mounts every explicit adapter root in the
+ * v2 `vgai.project.json`. Roots are required; the default scaffold declares
+ * one Three.js world, while composition templates may rewrite that list.
+ * The selected built-in adapter owns each root's document and lifecycle.
+ *
+ * `host.loadEntryModule` resolves an explicitly declared `entry` through a
+ * Vite-generated virtual module containing exactly the manifest's entry
+ * paths. The manifest remains the sole source of truth—filenames are
+ * arbitrary, while the bundler still sees static imports.
+ *
+ */
+
+import { manifestEntryModules } from 'virtual:vgai-manifest-entries';
+import type { ManifestHost } from '@volter/game-runtime/runtime/mount-game';
+import {
+  isAdapterRegistered,
+  mountGameFromManifest,
+  registerAdapter,
+} from '@volter/game-runtime/runtime/mount-game';
+import { r3fRootFactory } from '@volter/game-runtime/world3d-react';
+import manifest from '../vgai.project.json';
+import { registerReactAdapter } from './lib/react-root';
+
+// Three roots resolve through `r3fRootFactory`: the world entry module
+// DEFAULT-EXPORTS its React component (src/world.tsx), the same contract dom
+// roots already use. An `adapter` export still wins if a world needs full
+// control over its own RootAdapter.
+if (!isAdapterRegistered('three')) {
+  registerAdapter('three', r3fRootFactory);
+}
+
+// Keep the optional DOM adapter available for a project that later adds a UI
+// root; the neutral scaffold itself declares only the Three world.
+registerReactAdapter();
+
+async function main() {
+  document.title = manifest.name;
+
+  const container = document.getElementById('game-canvas') as HTMLElement;
+  const host: ManifestHost = {
+    container,
+    async loadEntryModule(path) {
+      const entryModule = manifestEntryModules[path];
+      if (!entryModule) {
+        throw new Error(
+          `main.ts: entry module "${path}" was not generated from vgai.project.json.`,
+        );
+      }
+      return entryModule;
+    },
+  };
+  const session = await mountGameFromManifest(manifest, host);
+  session.resize(window.innerWidth, window.innerHeight);
+
+  window.addEventListener('resize', () => {
+    session.resize(window.innerWidth, window.innerHeight);
+  });
+}
+
+main().catch(console.error);

package/template/src/manifest-entry-modules.d.ts

@@ -0,0 +1,3 @@
+declare module 'virtual:vgai-manifest-entries' {
+  export const manifestEntryModules: Readonly<Record<string, unknown>>;
+}

package/template/src/prefabs/HeroBox.stories.tsx

@@ -0,0 +1,23 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { HeroBox } from './HeroBox';
+
+const meta = {
+  title: 'Starter/Hero Box',
+  component: HeroBox,
+  // `color` is deliberately NOT pinned here: the story exhibits the
+  // component's own default, so Apply-to-Component changes what the board
+  // shows. A pinned copy of the default masked every applied change (two
+  // humans read the stale exhibit as breakage — runhuman passes 43/44).
+  args: {
+    name: 'Hero Box',
+    rotation: [0, -0.28, 0],
+  },
+} satisfies Meta<typeof HeroBox>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  parameters: { vgai: { default: true } },
+};

package/template/src/prefabs/HeroBox.tsx

@@ -0,0 +1,35 @@
+import { RoundedBoxGeometry } from '@react-three/drei/core/RoundedBox';
+import type { ThreeElements } from '@react-three/fiber';
+
+export type HeroBoxProps = Omit<ThreeElements['mesh'], 'args' | 'children' | 'ref'> & {
+  color?: string;
+};
+
+/**
+ * The neutral focal-object prefab: one independently placeable thing a
+ * designer can find in Content, duplicate, and reuse. Its colocated story is
+ * the registration. Keep construction pieces that only make sense as part of
+ * this object inside this owner; do not promote its geometry or material into
+ * primitive-sized prefabs. Replace the subject, not this distinction.
+ */
+export function HeroBox({ color = '#c8dce1', name = 'Hero Box', ...props }: HeroBoxProps) {
+  return (
+    <mesh name={name} castShadow receiveShadow {...props}>
+      <RoundedBoxGeometry
+        args={[2.55, 2.55, 2.55]}
+        radius={0.14}
+        smoothness={8}
+        bevelSegments={8}
+      />
+      <meshPhysicalMaterial
+        color={color}
+        roughness={0.24}
+        metalness={0.06}
+        clearcoat={0.36}
+        clearcoatRoughness={0.2}
+        sheen={0.18}
+        sheenColor="#d9f2ff"
+      />
+    </mesh>
+  );
+}

package/template/src/scenes/MainScene.tsx

@@ -0,0 +1,77 @@
+import { OrbitControls } from '@react-three/drei/core/OrbitControls';
+import { PerspectiveCamera } from '@react-three/drei/core/PerspectiveCamera';
+import type { ThreeElements } from '@react-three/fiber';
+import { useRef } from 'react';
+import type * as THREE from 'three';
+import { DaylightSky } from '../components/environment/DaylightSky';
+import { Ground } from '../components/environment/Ground';
+import { SceneAtmosphere } from '../components/environment/SceneAtmosphere';
+import { SoftGroundShadow } from '../components/environment/SoftGroundShadow';
+import { SunShadowFit } from '../components/environment/SunShadowFit';
+import { HeroBox } from '../prefabs/HeroBox';
+
+/**
+ * The complete neutral starter composition. A scene arranges environment,
+ * placeable prefabs, and the camera; it is not itself a Content prefab and
+ * should not hide independently placeable entities inside one scenery owner.
+ */
+export function MainScene({ name = 'Main Scene', ...props }: ThreeElements['group']) {
+  const sun = useRef<THREE.DirectionalLight>(null);
+  return (
+    <group name={name} {...props}>
+      <SceneAtmosphere />
+      <group name="Environment">
+        <DaylightSky name="Daylight Sky" />
+        <group name="Light Rig">
+          <hemisphereLight name="Sky Fill" args={['#e9f8ff', '#87958f', 1.55]} />
+          {/* The sun's position is its DIRECTION; `SunShadowFit` moves the node
+              and sizes the shadow box from what the camera frames, so the box
+              carries no hardcoded scale. Authored lateral extents and depth
+              range would be overwritten and are deliberately absent — see that
+              component's header for why ±12 units broke every game built at a
+              scale other than this scene's. `shadow-bias` is a fraction of the
+              fitted depth range, so it stays authored here. */}
+          <directionalLight
+            ref={sun}
+            name="Sun"
+            position={[10, 14, 7]}
+            intensity={2.7}
+            color="#fff4dc"
+            castShadow
+            shadow-mapSize-width={2048}
+            shadow-mapSize-height={2048}
+            shadow-bias={-0.00015}
+          />
+          <SunShadowFit light={sun} />
+          <directionalLight
+            name="Cool Fill"
+            position={[-7, 7, -9]}
+            intensity={0.55}
+            color="#b8dcff"
+          />
+        </group>
+        <Ground name="Ground" />
+        <SoftGroundShadow name="Soft Ground Shadow" />
+      </group>
+
+      <HeroBox name="Hero Box" position={[0, 1.3, 0]} rotation={[0, -0.28, 0]} color="#c8dce1" />
+      <PerspectiveCamera
+        makeDefault
+        name="Camera"
+        position={[7.35, 3.9, 8.15]}
+        fov={41}
+        near={0.1}
+        far={220}
+      />
+      <OrbitControls
+        makeDefault
+        target={[0, 1.15, 0]}
+        enablePan={false}
+        minDistance={6.5}
+        maxDistance={16}
+        minPolarAngle={0.55}
+        maxPolarAngle={1.38}
+      />
+    </group>
+  );
+}

package/template/src/world.tsx

@@ -0,0 +1,87 @@
+/**
+ * The Three root's thin entrypoint. Complete replaceable compositions live in
+ * `src/scenes/`; story-backed placeable assets live in `src/prefabs/`; and
+ * extracted non-placeable implementation lives in `src/components/`. Folder
+ * names describe what a file IS, never merely where it is used.
+ *
+ * `scenes` is the app's ordinary composition table and `activeScene` selects
+ * the component rendered at the root. Add another composition to
+ * `src/scenes/`, import it here, and give it a key in the table.
+ */
+
+import { useThree } from '@react-three/fiber';
+import { useEffect } from 'react';
+import * as THREE from 'three';
+import { QaTester } from './bot/QaTester';
+import { attachKeyboard } from './input';
+import { sfxAudioSystem } from './lib/audio/sfx';
+import { MainScene } from './scenes/MainScene';
+
+/** Renderer finish is project-owned state, restored when this world unmounts. */
+function RenderFinish() {
+  const renderer = useThree((state) => state.gl);
+
+  useEffect(() => {
+    const previousToneMapping = renderer.toneMapping;
+    const previousExposure = renderer.toneMappingExposure;
+    const previousShadowsEnabled = renderer.shadowMap?.enabled;
+    const previousShadowType = renderer.shadowMap?.type;
+
+    renderer.toneMapping = THREE.ACESFilmicToneMapping;
+    renderer.toneMappingExposure = 0.96;
+    if (renderer.shadowMap) {
+      renderer.shadowMap.enabled = true;
+      renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+    }
+
+    return () => {
+      renderer.toneMapping = previousToneMapping;
+      renderer.toneMappingExposure = previousExposure;
+      if (renderer.shadowMap && previousShadowType !== undefined) {
+        renderer.shadowMap.enabled = previousShadowsEnabled ?? false;
+        renderer.shadowMap.type = previousShadowType;
+      }
+    };
+  }, [renderer]);
+
+  return null;
+}
+
+/**
+ * The physical keyboard half of `src/input.ts`, owned by the world that reads
+ * it. The effect's cleanup detaches on unmount, so a Play→stop cycle leaves no
+ * window listener behind — the editor's realm audit warns about any that
+ * survive, and a listener attached at module load can never be released.
+ */
+function GameKeyboard() {
+  useEffect(() => attachKeyboard(window), []);
+  return null;
+}
+
+/** This world's swap slot — every composition it can mount, by id. */
+const scenes = {
+  main: MainScene,
+};
+
+/** The composition mounted at the slot right now. */
+const activeScene: keyof typeof scenes = 'main';
+
+function World() {
+  const Scene = scenes[activeScene];
+  return (
+    <>
+      <RenderFinish />
+      <GameKeyboard />
+      {/* The resident QA tester's hands on the frame — everything else about
+          the playtesting loop (the seat, the repertoire, pause/handoff) is
+          plain application code in src/bot/, reached from `vgai eval` via
+          `game.run(({ modules }) => …)` like every other module. */}
+      <QaTester />
+      <Scene name="Main Scene" />
+    </>
+  );
+}
+
+export const systems = { audio: sfxAudioSystem() };
+
+export default World;

package/template/tsconfig.json

@@ -0,0 +1,35 @@
+{
+  "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": {
+      "@volter/editor-project/*": ["node_modules/@volter/editor-project/src/*"],
+      "@volter/threejs-runtime/*": ["node_modules/@volter/threejs-runtime/src/*"],
+      "@volter/game-runtime/*": ["node_modules/@volter/game-runtime/src/*"],
+      "@editor/*": ["node_modules/@volter/editor-core/src/*"]
+    }
+  },
+  "include": ["src", "vgai.adapter.ts"],
+  "exclude": ["src/tools", "src/contributions"]
+}

package/template/tsconfig.node.json

@@ -0,0 +1,32 @@
+{
+  // This project's BUILD-TIME Node program — `vite.config.ts` and the
+  // config-relative modules it imports (`manifest-entry-modules-plugin.ts`).
+  //
+  // Why it is its own program rather than an entry in the base config's
+  // `include`: the base config types the BROWSER (`types: ["vite/client"]`,
+  // no node), which is the same reason `src/tools` needed
+  // `tsconfig.tools.json`. `vite.config.ts` reads `process.env` and
+  // `__dirname`, so it needs `node` in `types` — and it must not be able to
+  // reach browser-only globals by accident either way round.
+  //
+  // What it closes: before this, NO program in this project's `typecheck`
+  // script (nor in the engine repo's `npm run typecheck` graph) included
+  // `vite.config.ts`. It was compiled only by Vite's own esbuild, which
+  // strips types without checking them — so the file could and did drift
+  // out of `ServerOptions`, and the strictness this project sets everywhere
+  // else (`noPropertyAccessFromIndexSignature`,
+  // `exactOptionalPropertyTypes`) never applied to the one file that
+  // decides how the project builds and serves.
+  //
+  // `exclude` MUST be reset here for the same reason `tsconfig.tools.json`
+  // documents: `extends` inherits the base `exclude: ["src/tools"]`, and
+  // while that particular pattern cannot match anything in this `include`,
+  // leaving inherited excludes in place is how a program silently compiles
+  // ZERO files and still exits 0.
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["vite/client", "node"]
+  },
+  "include": ["vite.config.ts", "manifest-entry-modules-plugin.ts"],
+  "exclude": []
+}