@volter/game-editor 0.5.65

package/template/src/components/environment/Ground.tsx

@@ -0,0 +1,129 @@
+import type { ThreeElements } from '@react-three/fiber';
+import { useEffect, useMemo } from 'react';
+import * as THREE from 'three';
+import { mergeGeometries } from 'three/addons/utils/BufferGeometryUtils.js';
+
+export type GroundProps = Omit<ThreeElements['group'], 'children'> & {
+  size?: number;
+  gridSize?: number;
+  gridDivisions?: number;
+  showGrid?: boolean;
+};
+
+/** World-units-per-cell at which a grid line counts as MAJOR (one per 5 cells at defaults). */
+const MAJOR_LINE_EVERY = 10;
+
+/** One merged geometry holding every X- and Z-aligned line of one weight tier. */
+function buildGridLines(coordinates: number[], thickness: number, length: number) {
+  // An empty class of lines (every line major, or none) must still be a
+  // geometry: `mergeGeometries([])` reads the first entry's index and throws,
+  // which took the whole world down from an inspector edit and persisted the
+  // crash into source — a reload failed the same way (runhuman pass 48).
+  if (coordinates.length === 0) return new THREE.BufferGeometry();
+  const boxes: THREE.BufferGeometry[] = [];
+  for (const coordinate of coordinates) {
+    const alongZ = new THREE.BoxGeometry(thickness, 0.006, length);
+    alongZ.translate(coordinate, 0, 0);
+    const alongX = new THREE.BoxGeometry(length, 0.006, thickness);
+    alongX.translate(0, 0, coordinate);
+    boxes.push(alongZ, alongX);
+  }
+  const merged = mergeGeometries(boxes);
+  for (const box of boxes) box.dispose();
+  return merged;
+}
+
+/** Radial white→black gradient; as the surface's alphaMap it melts the floor's
+ *  edge into the sky the way distance fog used to — but view-independently, so
+ *  the soft horizon survives the Scene view's fog-neutral draw policy. */
+function buildEdgeFadeTexture() {
+  const size = 256;
+  const canvas = document.createElement('canvas');
+  canvas.width = size;
+  canvas.height = size;
+  const context = canvas.getContext('2d');
+  if (context) {
+    const gradient = context.createRadialGradient(
+      size / 2,
+      size / 2,
+      (size / 2) * 0.5,
+      size / 2,
+      size / 2,
+      (size / 2) * 0.94,
+    );
+    gradient.addColorStop(0, '#ffffff');
+    gradient.addColorStop(1, '#000000');
+    context.fillStyle = gradient;
+    context.fillRect(0, 0, size, size);
+  }
+  return new THREE.CanvasTexture(canvas);
+}
+
+/** The starter scene's floor assembly. It is scene support, not a placeable prefab. */
+export function Ground({
+  name = 'Ground',
+  size = 180,
+  gridSize = 80,
+  gridDivisions = 40,
+  showGrid = true,
+  ...props
+}: GroundProps) {
+  const edgeFade = useMemo(() => buildEdgeFadeTexture(), []);
+  useEffect(() => () => edgeFade.dispose(), [edgeFade]);
+
+  // Every value here is authorable from the Inspector, including mid-edit
+  // states (0, blank, negative): clamp to what a grid can be instead of
+  // letting NaN or Infinity reach the geometry.
+  const safeSize = Number.isFinite(size) && size > 0 ? size : 0.01;
+  const safeGridSize = Number.isFinite(gridSize) && gridSize > 0 ? gridSize : 0.01;
+  const safeDivisions =
+    Number.isFinite(gridDivisions) && gridDivisions >= 1
+      ? Math.min(Math.floor(gridDivisions), 400)
+      : 1;
+  const gridGeometries = useMemo(() => {
+    const half = safeGridSize / 2;
+    const spacing = safeGridSize / safeDivisions;
+    const coordinates = Array.from({ length: safeDivisions + 1 }, (_, i) => -half + i * spacing);
+    const isMajor = (c: number) => Math.abs(c % MAJOR_LINE_EVERY) < spacing / 2;
+    return {
+      major: buildGridLines(coordinates.filter(isMajor), 0.028, safeGridSize),
+      minor: buildGridLines(
+        coordinates.filter((c) => !isMajor(c)),
+        0.014,
+        safeGridSize,
+      ),
+    };
+  }, [safeGridSize, safeDivisions]);
+  useEffect(
+    () => () => {
+      gridGeometries.major.dispose();
+      gridGeometries.minor.dispose();
+    },
+    [gridGeometries],
+  );
+
+  return (
+    <group name={name} {...props}>
+      <mesh name="Surface" rotation={[-Math.PI / 2, 0, 0]} receiveShadow>
+        <circleGeometry args={[safeSize / 2, 96]} />
+        <meshStandardMaterial
+          color="#d2d0c6"
+          roughness={0.86}
+          metalness={0.02}
+          transparent
+          alphaMap={edgeFade}
+        />
+      </mesh>
+      {showGrid && (
+        <group name="Construction Grid" position={[0, 0.018, 0]}>
+          <mesh name="Major Lines" geometry={gridGeometries.major}>
+            <meshBasicMaterial color="#587785" transparent opacity={0.23} depthWrite={false} />
+          </mesh>
+          <mesh name="Minor Lines" geometry={gridGeometries.minor}>
+            <meshBasicMaterial color="#587785" transparent opacity={0.115} depthWrite={false} />
+          </mesh>
+        </group>
+      )}
+    </group>
+  );
+}

package/template/src/components/environment/SceneAtmosphere.tsx

@@ -0,0 +1,14 @@
+import { createPortal, useThree } from '@react-three/fiber';
+
+/** Native Fiber scene attachments. Their constructor literals remain the
+ * project's source of truth and are directly tunable in the World Inspector. */
+export function SceneAtmosphere() {
+  const scene = useThree((state) => state.scene);
+  return createPortal(
+    <>
+      <color attach="background" args={['#a9d8f2']} />
+      <fog attach="fog" args={['#c8e3ef', 32, 105]} />
+    </>,
+    scene,
+  );
+}

package/template/src/components/environment/SoftGroundShadow.tsx

@@ -0,0 +1,62 @@
+import type { ThreeElements } from '@react-three/fiber';
+import { useFrame } from '@react-three/fiber';
+import { useRef } from 'react';
+import type * as THREE from 'three';
+
+/**
+ * The starter camera's authored orbit distance (|position − target| of the
+ * scene's camera rig). Factor 1 of the fit below — at the shipped framing the
+ * plane reproduces the exact decor the starter always had, by construction.
+ */
+const STARTER_VIEW_DISTANCE = 11.3;
+
+/**
+ * A lightweight contact shadow with no render-target or asset dependency.
+ *
+ * SCALE-HONEST like `SunShadowFit` (the WORK.md cm-scale defect, measured
+ * 2026-08-29): the plane used to hardcode 4.8×3.2 m at y = 0.028 m, which
+ * SLICES through any object under ~10 cm — a 96 mm mug scene wore the decor
+ * plane through its middle. A starter must not encode a scale, so the
+ * plane's size and hover height are now derived per frame from how far the
+ * camera is from what it orbits, exactly the way the sun's shadow box reads
+ * its extents from the view. Frame a mug from 26 cm and the plane is ~11 cm
+ * wide floating 0.6 mm off the ground; the shipped meter-scale look is
+ * unchanged (factor 1 at the authored camera). Authored `position`/`scale`
+ * props are deliberately not honored — the fit overwrites them every frame
+ * (the SunShadowFit contract); replace the component to author decor by hand.
+ */
+export function SoftGroundShadow({ name = 'Soft Ground Shadow', ...props }: ThreeElements['mesh']) {
+  const mesh = useRef<THREE.Mesh>(null);
+  useFrame(({ camera, controls }) => {
+    const m = mesh.current;
+    if (!m) return;
+    const target = (controls as { target?: THREE.Vector3 } | null)?.target;
+    const factor = target ? camera.position.distanceTo(target) / STARTER_VIEW_DISTANCE : 1;
+    m.scale.set(4.8 * factor, 3.2 * factor, 1);
+    m.position.set(-0.55 * factor, 0.028 * factor, -0.48 * factor);
+  });
+  return (
+    <mesh ref={mesh} name={name} rotation={[-Math.PI / 2, 0, -0.18]} {...props}>
+      <planeGeometry args={[1, 1]} />
+      <shaderMaterial
+        transparent
+        depthWrite={false}
+        vertexShader={`
+          varying vec2 vUv;
+          void main() {
+            vUv = uv;
+            gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+          }
+        `}
+        fragmentShader={`
+          varying vec2 vUv;
+          void main() {
+            vec2 delta = (vUv - 0.5) * 2.0;
+            float falloff = 1.0 - smoothstep(0.05, 1.0, dot(delta, delta));
+            gl_FragColor = vec4(0.19, 0.26, 0.29, falloff * falloff * 0.19);
+          }
+        `}
+      />
+    </mesh>
+  );
+}

package/template/src/components/environment/SunShadowFit.tsx

@@ -0,0 +1,141 @@
+import { useFrame } from '@react-three/fiber';
+import { fitDirectionalShadowToCamera } from '@volter/threejs-runtime/render/directional-shadow-fit';
+import { type RefObject, useEffect } from 'react';
+import * as THREE from 'three';
+
+/** Frame scratch. Read and dropped inside one synchronous callback, so one set serves every instance. */
+const _lightOrientation = new THREE.Quaternion();
+const _parentInverse = new THREE.Matrix4();
+const _authoredAim = new THREE.Vector3();
+const _origin = new THREE.Vector3();
+
+/**
+ * How much farther than the framed subject the shadow box reaches. 1.0 would
+ * stop the slice exactly at what the camera orbits; this covers the ground the
+ * subject's shadow falls on and whatever stands just behind it, and at the
+ * authored camera it reproduces the box the starter used to hardcode
+ * (`shadow-camera-left/right/top/bottom = ±12`) to within a few percent — the
+ * meter-scale look is unchanged by construction.
+ */
+const VIEW_DEPTH_FACTOR = 1.35;
+
+/** Shadow-map texels of offset along the surface normal. The standard cure for
+ *  self-shadow acne on curved casters, and the reason it is derived from the
+ *  fit rather than authored: a constant would be wrong by exactly the factor
+ *  the box changed size. */
+const NORMAL_BIAS_TEXELS = 1.5;
+
+/** Depth range, as a multiple of the box radius, either side of the light. The
+ *  fit puts the light AT the box centre, so casters stand on both sides of it
+ *  and the range is symmetric. */
+const DEPTH_RANGE_FACTOR = 3;
+
+/**
+ * Size the sun's shadow box to WHAT THE CAMERA IS LOOKING AT, so shadows are
+ * correct at whatever scale this game turns out to be.
+ *
+ * THE DEFECT THIS CLOSES (measured 2026-08-29). `DirectionalLightShadow` is an
+ * orthographic camera with authored extents, and the starter authored ±12
+ * units over a 2048 map — 11.7 mm of world per shadow texel. That is invisible
+ * on the 2.55 m focal cube this scene ships with, and ruinous the moment a game
+ * is built at another scale: on a 96 mm ceramic mug one texel spans an eighth
+ * of the whole object, so the cast shadow disappears into quantization and the
+ * glaze wears diagonal acne stripes. No amount of `shadow-bias` fixes it,
+ * because the resolution — not the offset — is what is wrong. A starter scene
+ * must not encode a scale, and ±12 is a scale.
+ *
+ * `fitDirectionalShadowToCamera` (engine) supplies the geometry: the bounding
+ * sphere of the camera's frustum slice, with the centre quantized to whole
+ * shadow texels so a moving camera cannot make shadow edges crawl. Its method
+ * is transcribed from `top-down-strategy`'s `CameraFittedShadow`, which fits
+ * the same light to a panning camera. What is THIS scene's:
+ *
+ *  - **the view depth is read, not authored.** The strategy scene knows its own
+ *    map is worth 45 units of shadow; a starter knows nothing about the game
+ *    that will grow out of it, so the depth comes from how far the camera is
+ *    from what it orbits ({@link VIEW_DEPTH_FACTOR}). Frame a mug from 26 cm
+ *    and the texel is a third of a millimetre; frame a hillside from 200 m and
+ *    it is centimetres. That IS the scale-honesty.
+ *  - **the depth range and `normalBias` are fitted too.** A range in world
+ *    units is as much a hardcoded scale as the lateral extents, and
+ *    `shadow.bias` is normalized against it — so both are derived from the
+ *    fitted radius, and the light's authored `shadow-bias` keeps its meaning at
+ *    every scale.
+ *
+ * The light's authored `position` stays the sun's DIRECTION; this moves the
+ * node so the box is centred on the view, and re-anchors the aim onto a target
+ * parented to the light so moving it cannot rotate the sun.
+ */
+export function SunShadowFit({
+  light,
+}: {
+  /** The sun to fit. Its authored transform stays the sun's DIRECTION. */
+  light: RefObject<THREE.DirectionalLight | null>;
+}) {
+  useEffect(() => {
+    const sun = light.current;
+    if (!sun) return;
+    const authoredPosition = sun.position.clone();
+    const authoredTarget = sun.target;
+    sun.updateWorldMatrix(true, false);
+    authoredTarget.updateWorldMatrix(true, false);
+    // Aim by a target parented to the light, so moving the light translates
+    // both and the direction is unchanged by definition.
+    const travellingTarget = new THREE.Object3D();
+    travellingTarget.position.copy(
+      sun.worldToLocal(_authoredAim.setFromMatrixPosition(authoredTarget.matrixWorld)),
+    );
+    sun.add(travellingTarget);
+    sun.target = travellingTarget;
+    return () => {
+      sun.remove(travellingTarget);
+      sun.target = authoredTarget;
+      sun.position.copy(authoredPosition);
+    };
+  }, [light]);
+
+  useFrame((state) => {
+    const sun = light.current;
+    const shadow = sun?.shadow;
+    if (!sun || !shadow || sun.parent === null) return;
+    const camera = state.camera;
+    camera.updateWorldMatrix(true, false);
+    sun.updateWorldMatrix(true, false);
+    sun.getWorldQuaternion(_lightOrientation);
+
+    // What the camera is looking at: the default controls' orbit target when
+    // there are controls (the starter's OrbitControls declares `makeDefault`),
+    // else the world origin — the point a scene with no controls is composed
+    // around. Either way it is a POINT IN THE WORLD, so its distance from the
+    // camera is in the game's own units and carries the game's own scale.
+    const target = (state.controls as unknown as { target?: unknown } | null)?.target;
+    const framed = target instanceof THREE.Vector3 ? target : _origin.set(0, 0, 0);
+    const viewDepth = camera.position.distanceTo(framed) * VIEW_DEPTH_FACTOR;
+
+    const fit = fitDirectionalShadowToCamera(
+      camera,
+      _lightOrientation,
+      viewDepth,
+      shadow.mapSize.x,
+    );
+    const box = shadow.camera;
+    box.left = -fit.radius;
+    box.right = fit.radius;
+    box.top = fit.radius;
+    box.bottom = -fit.radius;
+    // Symmetric, because the light sits at the box centre with casters on both
+    // sides of it. Authored `shadow-bias` is a fraction of THIS range, so it
+    // stays a fixed fraction of the scene rather than a fixed world distance.
+    box.far = fit.radius * DEPTH_RANGE_FACTOR;
+    box.near = -box.far;
+    box.updateProjectionMatrix();
+    shadow.normalBias = fit.texelWorldSize * NORMAL_BIAS_TEXELS;
+    // `position` is parent-local; the fitted centre is in world space.
+    sun.parent.updateWorldMatrix(true, false);
+    sun.position.copy(
+      fit.center.applyMatrix4(_parentInverse.copy(sun.parent.matrixWorld).invert()),
+    );
+  });
+
+  return null;
+}

package/template/src/contributions/README.md

@@ -0,0 +1,98 @@
+# `src/contributions/` — what this game adds to the editor
+
+These files are this game's editor plugin. They are ordinary React/TSX, found
+by filename:
+
+- `*.inspector.tsx` — a section on an inspected subject;
+- `*.document.tsx` — a workspace document;
+- `*.utility.tsx` — a compact bottom-drawer instrument;
+- `*.analytics.tsx` — the game-owned body inside the shared Gameplay Session
+  shell.
+
+There is no registry, command vocabulary, generated form, or prescribed panel
+layout. A contribution exports its `point`, its `title`, and its default React
+component. Write the surface this game's studio would actually use, in the
+game's own vocabulary. Import controls from `@volter/editor-sdk/widgets`; use ordinary
+React and CSS for the rest.
+
+A completed contribution is a usable interface: game-specific labels,
+relevant readings and working controls. Raw JSON/object dumps do not fulfill
+the contribution. Verify its actual presentation and controls before removing
+the unfinished-stub warning.
+
+## Live game modules
+
+A live contribution must read the running mount's own module instances through
+[`use-game-modules.ts`](./use-game-modules.ts). Do not directly import a
+gameplay module from a contribution: the editor and game have different import
+graphs, so that creates a second, phantom copy of module state.
+
+```tsx
+import type { ToolInspectorContributionProps } from '@volter/editor-sdk/contributions';
+import { Button } from '@volter/editor-sdk/widgets';
+import { useGameModules } from './use-game-modules';
+
+export const point = 'selection.inspector';
+export const title = 'Cooling QA';
+
+export default function CoolingQa({ play }: ToolInspectorContributionProps) {
+  const { mods, error } = useGameModules(play, {
+    cooling: 'src/sim/cooling.ts',
+  });
+  const cooling = mods?.cooling as
+    | { readCooling?: () => { temperature: number }; setupHeatSpike?: () => void }
+    | undefined;
+  const state = cooling?.readCooling?.();
+
+  return (
+    <div>
+      <div>{error ?? `Temperature: ${state?.temperature ?? '—'}`}</div>
+      <Button onClick={() => cooling?.setupHeatSpike?.()}>Set up heat spike</Button>
+    </div>
+  );
+}
+```
+
+The module owns the mechanic, readout, and setup function. The contribution is
+only its human face. A coding agent reaches the exact same functions through:
+
+```js
+game.run(async ({ modules }) => {
+  const cooling = await modules('src/sim/cooling.ts');
+  return cooling.readCooling();
+})
+```
+
+## The three starter surfaces
+
+These three panels arrive with the `studio` addition (`game-editor create <name> --with
+studio`, or `--template full`). NO preset brings them otherwise — nothing a
+project inherits may error, and these three THROW until they are rewritten
+(orchestrator ruling, 2026-09-19). Asking for `studio` is asking for the TODO.
+
+- `tester.inspector.tsx` is deliberately unfinished. Rewrite it whole as the
+  live QA cockpit for this game: controller ownership, available goals, the
+  active goal's intent/step/target/progress/blocker/decision/outcome, start and
+  redirect controls, stop/handoff, setup cheats, and the live readings needed
+  to judge rare situations. Setup may conjure a situation; the resident tester
+  still exercises the mechanic through normal input at simulation speed.
+- `data.document.tsx` is deliberately unfinished. Render the game's typed
+  literals from `src/data/` with the derived columns and charts collaborators
+  need. Delete the file when the game genuinely has no authored content
+  tables.
+- `analytics.analytics.tsx` is deliberately unfinished. The editor owns the durable Gameplay
+  Session selector, real-time scrub rail, and optional recording preview. Its
+  body receives the selected log and cursor and deliberately receives no live
+  `play` object. Replace the stub with analysis of the selected session that
+  answers this game's development questions. A raw event listing does not
+  fulfill the contribution; never import live simulation state into Analytics.
+
+All three stubs emit `VGAI_STUB_UNIMPLEMENTED`. That warning keeps the live
+console red, and `npm run check-idioms` reports it as unfinished work. Remove
+the sentinel only by replacing the stub with the game's real surface (or by
+honestly deleting the optional Data surface), not by silencing the warning.
+
+There is no committed autoplay route or QA spec. Playtesting is interactive:
+the developer arranges a situation through exported setup functions, directs
+the resident tester toward a goal, advances sim time, reads the play log and
+visible result, and redirects as needed. `logs/play-*.jsonl` is the receipt.

package/template/src/contributions/analytics.analytics.tsx

@@ -0,0 +1,26 @@
+/**
+ * NOT IMPLEMENTED — this game's Analytics contribution.
+ *
+ * Replace this stub with analysis that answers this game's development
+ * questions. Choose its metrics and presentation from the game's needs.
+ * A raw event listing does not fulfill this contribution.
+ *
+ * The editor already supplies the Gameplay Session picker, playback/scrub
+ * controls and optional recording preview. Keep those shared facilities;
+ * derive this contribution's analysis from the selected session and cursor
+ * supplied through gameplaySessions, never from live simulation state.
+ */
+import type { ToolAnalyticsContributionProps } from '@volter/editor-sdk/contributions';
+
+export const point = 'workspace.analytics';
+export const title = 'Analytics';
+
+const unfinished =
+  'VGAI_STUB_UNIMPLEMENTED: src/contributions/analytics.analytics.tsx — replace this stub with game-specific analysis of recorded Gameplay Sessions; playback is provided by the editor.';
+
+// biome-ignore lint/suspicious/noConsole: unopened starter obligations remain visible in the editor console
+console.error(unfinished);
+
+export default function AnalyticsStub(_props: ToolAnalyticsContributionProps): never {
+  throw new Error(unfinished);
+}

package/template/src/contributions/data.document.tsx

@@ -0,0 +1,35 @@
+/**
+ * NOT IMPLEMENTED — this game's DATA surface.
+ *
+ * An OBLIGATION, not an implementation: the game's numbers and content
+ * tables (`src/data/` — plain typed TS literals) must be viewable, with
+ * their derived picture, by the humans collaborating on this game. How is
+ * yours. REWRITE THIS FILE WHOLE; the error below holds `vgai console`
+ * red until you do.
+ *
+ * The method: render the data modules as tables (a plain `<table>` until a
+ * table earns a grid — then `react-data-grid`) with the DERIVED columns a
+ * studio spreadsheet would compute ($/unit, payback, crossover points —
+ * plain functions beside the data), and graphs from a common charting
+ * library (e.g. Recharts). Import the data modules directly — for inert
+ * data that is file truth, which is what a data view shows. The worked
+ * reference: datacenter-tycoon's data document.
+ *
+ * A game with genuinely NO content tables deletes this file — the
+ * deletion, visible in git, is the honest declaration.
+ */
+import type { ToolContributionProps } from '@volter/editor-sdk/contributions';
+
+export const point = 'workspace.document';
+export const title = 'Data';
+
+// Module-scope on purpose — the demand is visible from editor boot.
+const unfinished =
+  "VGAI_STUB_UNIMPLEMENTED: src/contributions/data.document.tsx — render this game's data (src/data/) with its derived columns, or delete this file if the game truly has no content tables (its header says how).";
+
+// biome-ignore lint/suspicious/noConsole: unopened starter obligations remain visible in the editor console
+console.error(unfinished);
+
+export default function DataStub(_props: ToolContributionProps): never {
+  throw new Error(unfinished);
+}

package/template/src/contributions/pages.finder.ts

@@ -0,0 +1,61 @@
+/**
+ * The `pagesFromUiModules` FINDER (ARCHITECTURE-CORE §The project model,
+ * "Documents, not scenes"): every project module under the selection's
+ * `include` globs that exports a React component is a `page` document —
+ * what a website is made of, the way a game is made of scenes. Select it
+ * in `vgai.adapter.ts`:
+ *
+ *   documents: { find: [{ finder: 'pagesFromUiModules', include: ['src/ui/**\/*page.tsx'] }] }
+ *
+ * The glob IS the page rule: a project names its pages by where it keeps
+ * them. This module is a plain object the HOST registers; it mounts no UI
+ * and reads the project only through `input.sources`.
+ */
+import { z } from 'zod';
+
+const COMPONENT_EXPORT =
+  /export\s+(?:default\s+)?(?:function\s+[A-Z]\w*\s*\(|const\s+[A-Z]\w*\s*[:=])/;
+
+export const finder = {
+  name: 'pagesFromUiModules',
+  schema: z
+    .object({
+      finder: z.literal('pagesFromUiModules'),
+      include: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe('Project-relative globs of the page modules (`src/ui/**/*page.tsx`)'),
+    })
+    .strict(),
+  run(
+    _selection: { finder: 'pagesFromUiModules'; include: readonly string[] },
+    input: { sources?: readonly { path: string; source: string }[] },
+  ) {
+    const entries = [];
+    const notes: string[] = [];
+    for (const file of input.sources ?? []) {
+      if (!COMPONENT_EXPORT.test(file.source)) {
+        notes.push(`${file.path}: exports no component — not a page`);
+        continue;
+      }
+      const name = (file.path.split('/').pop() ?? file.path)
+        .replace(/\.[cm]?[jt]sx?$/, '')
+        .replace(/[-_.]?page$/i, '');
+      entries.push({
+        id: `page:${file.path}`,
+        label: name || 'page',
+        kind: 'page',
+        region: null,
+        authorable: true,
+        reach: { kind: 'root-mount' as const },
+        source: { path: file.path },
+      });
+    }
+    return {
+      entries,
+      notes,
+      // One page is the page; two is a choice the site's author states.
+      ...(entries.length === 1 ? { default: entries[0]!.id } : {}),
+    };
+  },
+} as const;

package/template/src/contributions/tester.inspector.tsx

@@ -0,0 +1,64 @@
+/**
+ * NOT IMPLEMENTED — this game's TESTER surface.
+ *
+ * This stub is an OBLIGATION, not an implementation. It claims WHAT this
+ * game must make available: a live QA cockpit that helps a human or AI tester
+ * direct the resident tester, understand its goals and decisions, arrange
+ * difficult situations, and judge the mechanic under test. It says nothing
+ * about HOW. REWRITE THIS FILE WHOLE in the game's own vocabulary: rename it,
+ * split it into several faces, and structure it the way THIS game's studio
+ * would. The error below holds `vgai console` red until you do; delete it
+ * with the stub.
+ *
+ * Make the controller's current owner and the tester's repertoire legible.
+ * While a goal runs, expose enough of its mind to explain its intent, current
+ * step and target, progress, blockers, latest observation or decision, and
+ * outcome. Give the operator clear ways to start, direct, redirect, stop, and
+ * hand off the tester. A control's outcome or refusal must be visible,
+ * including a goal that completes before the next paint.
+ * Present these as readable game-specific labels, readings and controls.
+ * A raw JSON/object dump does not fulfill this contribution; keep the
+ * unfinished error until the actual interface meets this requirement.
+ *
+ * Put setup cheats here when honest play would make a QA situation costly or
+ * rare, together with the exact live readings needed to judge it. A cheat may
+ * establish the situation; the tester still exercises the behavior under
+ * judgment through the game's normal input path at simulation speed.
+ * Historical metrics belong in Analytics, and authored content or tuning
+ * belongs in Data.
+ *
+ * Read the RUNNING game's own modules through `useGameModules`
+ * (`./use-game-modules` — a direct import from a contribution is a phantom
+ * second copy); hand-type the slice of each module you read. Human controls
+ * call the same ordinary exported functions an agent reaches through
+ * `game.run(({ modules }) => ...)`. The worked reference is the
+ * datacenter-tycoon game's `src/tools/`.
+ */
+import type {
+  ToolContributionNode,
+  ToolInspectorContributionMatchContext,
+  ToolInspectorContributionProps,
+} from '@volter/editor-sdk/contributions';
+
+export const point = 'selection.inspector';
+export const title = 'Tester';
+
+export function match(
+  node: ToolContributionNode | null,
+  _adapter: unknown,
+  context?: ToolInspectorContributionMatchContext,
+): boolean {
+  return node === null && context?.nullSubjectId === 'game';
+}
+
+// Module-scope on purpose: fires the moment the editor loads this game's
+// contributions, so the demand is visible before anyone opens the panel.
+const unfinished =
+  "VGAI_STUB_UNIMPLEMENTED: src/contributions/tester.inspector.tsx — imagine this game's tester helper surface and rewrite the file whole (its header says how).";
+
+// biome-ignore lint/suspicious/noConsole: unopened starter obligations remain visible in the editor console
+console.error(unfinished);
+
+export default function TesterInspectorStub(_props: ToolInspectorContributionProps): never {
+  throw new Error(unfinished);
+}