@vgai/editor 0.2.0

package/template/src/data/tuning.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "boxSpinSpeed": {
+      "default": 0.8,
+      "description": "Demo box spin speed, radians/sec — edit tuning.data.json while playing to see live tuning",
+      "type": "number",
+      "minimum": -5,
+      "maximum": 5
+    },
+    "boxColor": {
+      "default": "#4488ff",
+      "description": "Demo box color (hex)",
+      "type": "string"
+    },
+    "$schema": {
+      "type": "string"
+    }
+  }
+}

package/template/src/data/tuning.schema.ts

@@ -0,0 +1,34 @@
+/**
+ * Tuning schema — the engineer-owned half of a data asset
+ * (docs/DATA-TOOLS-DESIGN.md §2.1).
+ *
+ * Every data asset is a trio in this folder:
+ *
+ *   tuning.schema.ts     ← this file: the Zod schema. Code owns the shape.
+ *   tuning.schema.json   ← EMITTED artifact (`npm run emit-schemas`) — gives
+ *                          VS Code validation/autocomplete on the data file.
+ *   tuning.data.json     ← the VALUES. Designer/editor/agent-owned; its first
+ *                          line `"$schema": "./tuning.schema.json"` wires the
+ *                          two together with no dev server running.
+ *
+ * Annotate every field with `.min/.max/.default/.describe` — the same
+ * annotations `GameComponent.static schema` uses. They document the file,
+ * constrain edits, and (W2+) become editor widgets.
+ *
+ * Rule of thumb (project CLAUDE.md carries the doctrine): if a designer
+ * should be able to change it, it belongs here — NOT as a constant in a
+ * component. Per-entity placement config stays on component schemas.
+ */
+import { z } from 'zod';
+
+export const TuningSchema = z.object({
+  boxSpinSpeed: z
+    .number()
+    .min(-5)
+    .max(5)
+    .default(0.8)
+    .describe('Demo box spin speed, radians/sec — edit tuning.data.json while playing to see live tuning'),
+  boxColor: z.string().default('#4488ff').describe('Demo box color (hex)'),
+});
+
+export type Tuning = z.infer<typeof TuningSchema>;

package/template/src/data/tuning.ts

@@ -0,0 +1,24 @@
+/**
+ * The live handle for the `tuning` data asset — the blessed consumption shape
+ * (docs/DATA-TOOLS-DESIGN.md §2.3, engine `@engine/data/data-asset`).
+ *
+ * Three lines is the whole wiring:
+ *  1. statically import the JSON (bundler-friendly, works in dev and build),
+ *  2. `defineData` — Zod parse-on-load (fails loud naming file + field),
+ *     returning `get()`/`subscribe()`,
+ *  3. the `import.meta.hot` line — Vite HMR needs the literal dep path in
+ *     THIS module, so an edit to tuning.data.json (VS Code, an agent, the
+ *     future editor Data tab) hot-swaps values into the RUNNING game, no
+ *     remount, no reload.
+ *
+ * Consume with `tuning.get()` INSIDE your update loop every frame (never
+ * cache fields across frames, or live tuning silently stops working for that
+ * field) — see `src/scripts/components/data-spinner.ts` for the worked use.
+ */
+import { defineData } from '@engine/data/data-asset';
+import raw from './tuning.data.json';
+import { TuningSchema } from './tuning.schema';
+
+export const tuning = defineData(TuningSchema, raw, 'src/data/tuning.data.json');
+
+import.meta.hot?.accept('./tuning.data.json', (m) => tuning.hotSwap(m?.['default']));

package/template/src/main.ts

@@ -0,0 +1,157 @@
+/**
+ * Standalone entry point.
+ *
+ * One `mountGameFromManifest` call (E4, docs/unified-world-editor/
+ * 27-visual-react-editing.md §7 E4 — the S-D composer): mounts every world
+ * `vgai.game.json` declares — just the one `default`-adapter threejs world
+ * for a plain scaffold — through the engine's `registerWorldKind` registry,
+ * no example switcher, no HUD dropdown, no discovery glob (that in-app
+ * gallery machinery has been deleted), and no hand-built `WorldMountSpec[]`.
+ * The default scene is the simple box from `src/scripts/main.ts`.
+ *
+ * `registerWorldKind('threejs', defaultThreeKindFactory)` opts into the
+ * engine's stock threejs resolution (entry module's `adapter`/`setup` export,
+ * or a scene-driven world) — see `mount-game.ts`'s doc comment for why this
+ * is a plain function the CALLER registers rather than something the engine
+ * wires up for you (pixijs/react worlds need the SAME one-line registration
+ * with your own factory; see `examples/tri-world/src/main.ts`).
+ *
+ * `host.loadEntryModule` resolves a manifest-declared `entry` path to an
+ * ALREADY-IMPORTED module — a static lookup table keyed by that exact path
+ * string, not a runtime `import(path)` (a static bundler can't resolve a
+ * computed specifier for a real `dist/` build; see `mount-game.ts`'s
+ * `ManifestHost.loadEntryModule` doc comment).
+ *
+ * No Scene UI setup here (C1, docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md
+ * §9): a plain scaffold's default game UI is ordinary React, mounted via
+ * `mountUI(ctx.uiContainer, ...)` from `./scripts/main.ts`'s `setup()` (see
+ * `./ui/mount-default-hud.tsx`) — no `@vgai/scene-ui` import, no `.vscn`
+ * `ui` field. A project that opts INTO the (still-supported, being retired
+ * under C5) Scene UI data-language authoring path can wire
+ * `registerSceneUIRenderer()` back in itself; the template no longer does
+ * it by default.
+ */
+
+import type { ManifestHost } from '@engine/runtime/mount-game';
+import {
+  defaultThreeKindFactory,
+  isWorldKindRegistered,
+  mountGameFromManifest,
+  registerWorldKind,
+} from '@engine/runtime/mount-game';
+import manifest from '../vgai.game.json';
+import * as mainScript from './scripts/main';
+
+const DEFAULT_SIGNALING_URL = 'https://vgai-p2p-colyseus.aaron-0ed.workers.dev';
+
+// The manifest's `entry`-declaring worlds' modules, statically imported and
+// keyed by the EXACT `entry` path each world declares in `vgai.game.json` —
+// see this file's header comment for why this is a static table, not a
+// dynamic `import(path)`. Add an entry here if you add another entry-driven
+// world to the manifest.
+const ENTRY_MODULES: Readonly<Record<string, unknown>> = {
+  'src/scripts/main.ts': mainScript,
+};
+
+// Reopen fix (E4.R1): `registerWorldKind` throws on a double-registration of
+// the same kind (an accidental duplicate is far more likely than an
+// intentional swap — see its own doc comment) — but this module's top level
+// re-runs whenever a hot-accept boundary re-executes it WITHOUT a full page
+// reload, which would otherwise turn a live-reload edit into a hard crash.
+// Guard so a re-execution is a no-op instead of bricking the reload.
+if (!isWorldKindRegistered('threejs')) {
+  registerWorldKind('threejs', defaultThreeKindFactory);
+}
+
+async function main() {
+  try {
+    const res = await fetch('project.json');
+    if (res.ok) {
+      const cfg = await res.json();
+      if (cfg.name) document.title = cfg.name;
+    }
+  } catch {
+    /* keep default title */
+  }
+
+  await configureNetworkModeFromUrl();
+
+  const container = document.getElementById('game-canvas') as HTMLElement;
+  const host: ManifestHost = {
+    container,
+    async loadEntryModule(path) {
+      const mod = ENTRY_MODULES[path];
+      if (!mod) {
+        throw new Error(
+          `main.ts: unknown entry module "${path}" declared by vgai.game.json — add it to ` +
+            'ENTRY_MODULES above.',
+        );
+      }
+      return mod;
+    },
+  };
+  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);
+
+async function configureNetworkModeFromUrl(): Promise<void> {
+  const params = new URLSearchParams(window.location.search);
+  const mode = params.get('net');
+  if (mode !== 'p2p-host' && mode !== 'p2p-join') return;
+
+  const sdk = (await import('@colyseus/sdk')) as unknown as {
+    configureP2PColyseusClient?: (options: {
+      mode:
+        | {
+            kind: 'p2p-host';
+            signalingUrl: string;
+            iceServers: RTCIceServer[];
+            forceRelay?: boolean;
+          }
+        | {
+            kind: 'p2p-join';
+            signalingUrl: string;
+            roomId?: string;
+            iceServers: RTCIceServer[];
+            forceRelay?: boolean;
+          };
+      rooms?: Record<string, unknown>;
+      maxLocalClientsPerRoom?: number;
+    }) => void;
+  };
+  if (!sdk.configureP2PColyseusClient) return;
+
+  const signalingUrl = params.get('signal') ?? DEFAULT_SIGNALING_URL;
+  const forceRelay = params.get('relay') === '1';
+  const iceServers: RTCIceServer[] = [{ urls: 'stun:stun.l.google.com:19302' }];
+
+  if (mode === 'p2p-host') {
+    const { rooms } = (await import('../server/rooms')) as {
+      rooms: Array<{ name: string; handler: unknown }>;
+    };
+    sdk.configureP2PColyseusClient({
+      mode: { kind: 'p2p-host', signalingUrl, iceServers, forceRelay },
+      rooms: Object.fromEntries(rooms.map((room) => [room.name, room.handler])),
+      ...(forceRelay ? { maxLocalClientsPerRoom: 1 } : {}),
+    });
+    return;
+  }
+
+  const roomId = params.get('roomId') ?? params.get('room');
+  sdk.configureP2PColyseusClient({
+    mode: {
+      kind: 'p2p-join',
+      signalingUrl,
+      ...(roomId !== null ? { roomId } : {}),
+      iceServers,
+      forceRelay,
+    },
+    maxLocalClientsPerRoom: 1,
+  });
+}

package/template/src/scripts/components/data-spinner.ts

@@ -0,0 +1,45 @@
+import { GameComponent } from '@engine/ecs/game-component';
+import type * as THREE from 'three';
+import { z } from 'zod';
+import { tuning } from '../../data/tuning';
+
+/**
+ * The template's worked data-asset consumer (docs/DATA-TOOLS-DESIGN.md §6.2
+ * — the pattern ships working at birth): spins the default scene's Box at
+ * `boxSpinSpeed` and tints it `boxColor`, both read from
+ * `src/data/tuning.data.json` through the `tuning` handle.
+ *
+ * Try it: press ▶, then edit `src/data/tuning.data.json` and save — the box
+ * changes speed/color LIVE (Vite HMR, no reload; see src/data/tuning.ts).
+ *
+ * This component demonstrates BOTH halves of the data-vs-config split
+ * (§3.3/§6.2): `boxSpinSpeed`/`boxColor` are PROJECT-WIDE feel, so they live
+ * in the data asset and read through `tuning.get()` (every frame — cache a
+ * field across frames and live tuning silently stops reaching it). `spinScale`
+ * is THIS entity's own knob — per-entity config authored on the component
+ * itself via `static schema` (the same shape SceneCamera uses), read live by
+ * an inspector tool through `useSelection()` (see `spin.tool.tsx`).
+ */
+export class DataSpinner extends GameComponent {
+  static schema = z.object({
+    spinScale: z
+      .number()
+      .default(1)
+      .describe(
+        'Per-entity multiplier on the shared boxSpinSpeed — the project-wide feel stays in ' +
+          "src/data/tuning.data.json; this is the one knob that is THIS entity's own.",
+      ),
+  });
+
+  spinScale = 1;
+
+  update(dt: number) {
+    const t = tuning.get();
+    this.object3D.rotation.y += t.boxSpinSpeed * this.spinScale * dt;
+
+    const material = (this.object3D as THREE.Mesh).material as
+      | THREE.MeshStandardMaterial
+      | undefined;
+    if (material?.color) material.color.set(t.boxColor);
+  }
+}

package/template/src/scripts/components/scene-camera.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { GameComponent } from '@engine/ecs/game-component';
+import type { GameContext } from '@engine/runtime/types';
+
+/**
+ * Positions the runtime camera on init.
+ *
+ * Configure x/y/z (camera position) and lookAtX/lookAtY/lookAtZ (look-at
+ * target) in the scene JSON. Runs in preRender phase so it can adjust the
+ * camera before rendering. One-time framing in init() only — this is the
+ * blessed "static scene setup" camera-via-component shape (not a per-frame
+ * follow), same category as the one-time `ctx.camera.position.set(...)` calls
+ * example `setup()` functions make directly.
+ */
+export class SceneCamera extends GameComponent {
+  static phase = 'preRender' as const;
+
+  static schema = z.object({
+    x: z.number().default(3).describe('Camera position X'),
+    y: z.number().default(3).describe('Camera position Y'),
+    z: z.number().default(3).describe('Camera position Z'),
+    lookAtX: z.number().default(0).describe('Look-at target X'),
+    lookAtY: z.number().default(0.5).describe('Look-at target Y'),
+    lookAtZ: z.number().default(0).describe('Look-at target Z'),
+  });
+
+  x = 3;
+  y = 3;
+  z = 3;
+  lookAtX = 0;
+  lookAtY = 0.5;
+  lookAtZ = 0;
+
+  init(ctx: GameContext) {
+    ctx.camera.position.set(this.x, this.y, this.z);
+    ctx.camera.lookAt(this.lookAtX, this.lookAtY, this.lookAtZ);
+  }
+
+  update() {}
+}

package/template/src/scripts/main.ts

@@ -0,0 +1,94 @@
+/**
+ * Default game script.
+ *
+ * When launched from the editor, loads the scene the user is editing.
+ * When running standalone, loads the default scene from disk.
+ *
+ * If the scene matches a known example, delegates to that example's setup
+ * function so gameplay systems (movement, camera, AI, etc.) are registered.
+ */
+
+import type { GameAdapter } from '@engine/adapter';
+import { fromSetup } from '@engine/adapter';
+import type { EditorPreview, GameCleanup, GameContext } from '@engine/runtime/types';
+import { loadScene, loadSceneFromData } from '@engine/scene/scene-loader';
+import { applyScenePostProcessing } from '@engine/setup/setup-renderer';
+import { mountDefaultHud } from '../ui/mount-default-hud';
+import { componentRegistry, gameComponents } from './registry';
+
+const DEFAULT_SCENE = 'scenes/default.vscn.json';
+
+/** Exported for true HMR — play-mode swaps prototypes on live instances. */
+export const components = gameComponents;
+
+// HMR boundary — play-mode.ts handles script hot-reloading via custom events.
+// This prevents Vite from triggering full page reloads when component files change.
+if (import.meta.hot) {
+  import.meta.hot.accept();
+}
+
+export async function setup(ctx: GameContext, editor?: EditorPreview): Promise<GameCleanup> {
+  // Generic fallback: load the scene with the full component registry
+  // so ECS components are applied, but no gameplay systems are registered.
+  const loadOpts = {
+    scene: ctx.scene,
+    rapierWorld: ctx.rapierWorld,
+    rapier: ctx.rapier,
+    physics: ctx.physics,
+    audioListener: ctx.audio.listener,
+    componentRegistry,
+    componentManager: ctx.components,
+    // Required for runtime fidelity (P1.4): particles need the batched renderer,
+    // skybox/IBL needs the WebGLRenderer for PMREM.
+    particleRenderer: ctx.particles.batchedRenderer,
+    renderer: ctx.composer.getRenderer(),
+  };
+
+  // Set the INITIAL camera viewpoint BEFORE loading the scene, so that any
+  // scene-defined camera or SceneCamera component (which run during loadScene)
+  // takes precedence over the editor viewport camera. Generic scenes with no
+  // camera component keep this viewpoint.
+  if (editor?.viewportCamera) {
+    ctx.camera.position.fromArray(editor.viewportCamera.position);
+    ctx.camera.quaternion.fromArray(editor.viewportCamera.quaternion);
+  } else {
+    ctx.camera.position.set(3, 3, 3);
+    ctx.camera.lookAt(0, 0.5, 0);
+  }
+
+  const sceneInstance = editor
+    ? await loadSceneFromData(editor.sceneData, loadOpts)
+    : await loadScene(DEFAULT_SCENE, loadOpts);
+
+  // Apply scene-defined post-processing (bloom, vignette, DoF, …) if present.
+  if (sceneInstance.environment?.postProcessing) {
+    applyScenePostProcessing(
+      ctx.composer,
+      ctx.composer.getRenderer(),
+      ctx.scene,
+      ctx.camera,
+      sceneInstance.environment,
+    );
+  }
+
+  // Tick scene animations (GLTF mixers, etc.)
+  ctx.systems.add('postPhysics', (dt) => sceneInstance.update(dt));
+
+  // Default game HUD (C1, docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §9):
+  // ordinary React mounted through the existing `mountUI(ctx.uiContainer, ...)`
+  // overlay seam — see `../ui/DefaultHud.tsx`. Delete this line (and the HUD
+  // files under `../ui/`) if your game doesn't want it; it is not required by
+  // anything else in the template.
+  const unmountHud = mountDefaultHud(ctx.uiContainer);
+
+  return {
+    dispose() {
+      unmountHud();
+      sceneInstance.dispose();
+    },
+  };
+}
+
+/** This example as a {@link GameAdapter} — first-party is one implementer of
+ *  the same interface an external game implements (no change to setup's body). */
+export const adapter: GameAdapter = fromSetup('default', setup);

package/template/src/scripts/registry.ts

@@ -0,0 +1,46 @@
+/**
+ * Project component registry.
+ *
+ * Every component used in .vscn.json files must be registered here. The scene
+ * loader and validator use this to map component names to GameComponent classes.
+ *
+ * This file is copied VERBATIM into every scaffolded project (it lives inside
+ * `packages/editor/template/`) — it must never import anything outside the
+ * template's own tree (no reaching into repo-root `examples/<id>/`, which
+ * doesn't exist once copied elsewhere; a real scaffold's own
+ * `scaffold-typecheck` gate catches this).
+ *
+ * When you delete an example, remove its imports and entries below.
+ */
+
+import type { GameComponentClass } from '@engine/ecs/game-component';
+import type { ComponentRegistry } from '@engine/scene/component-registry';
+import { DataSpinner } from './components/data-spinner';
+import { SceneCamera } from './components/scene-camera';
+
+export const componentRegistry = {
+  // GameComponent classes (OOP components with true HMR)
+  DataSpinner,
+  SceneCamera,
+} satisfies ComponentRegistry;
+
+/**
+ * Union of all registered component names — discoverable + type-checked rather
+ * than stringly-typed. Derived from the registry so it can never drift.
+ */
+export type ComponentName = keyof typeof componentRegistry;
+
+/**
+ * Typed accessor for a registered component class. Prefer this over indexing
+ * `componentRegistry` directly: `name` is constrained to `ComponentName`, so
+ * typos are caught at compile time and editors can autocomplete the options.
+ */
+export function getComponent(name: ComponentName): GameComponentClass {
+  return componentRegistry[name];
+}
+
+/** GameComponent classes for true HMR. Keyed by class name. */
+export const gameComponents: Record<string, GameComponentClass> = {
+  DataSpinner,
+  SceneCamera,
+};

package/template/src/tools/README.md

@@ -0,0 +1,14 @@
+# src/tools — project tools
+
+Editor-docked dev/tuning panels live here: `<name>.tool.tsx` exporting
+`tool = defineTool({...})` plus a default React component — the editor
+discovers them automatically. Two placements: `'dock'` (⚙ tab after the
+built-in bottom tabs — `example.tool.tsx`, the shipped worked example) and
+`'inspector'` (⚙ section in the Inspector when its `match(node, adapter)`
+accepts the selection, e.g. `adapter.components?.list(node.id)` —
+`spin.tool.tsx`). Inside an inspector tool, `useSelection()` (from
+`@engine/react/use-selection`) returns the selected node, its attached
+components, and each component's own authored config, live. Build panels
+from `@editor/widgets` (the editor's own widget kit + tokens) so they look
+native. Editor-only: `npm run build` never bundles this folder — see
+`docs/DATA-TOOLS-DESIGN.md` §3–§4 in the engine checkout.

package/template/src/tools/example.tool.tsx

@@ -0,0 +1,91 @@
+/**
+ * Example dock tool — the worked project-tool pattern
+ * (docs/DATA-TOOLS-DESIGN.md §3, in the engine checkout). Slightly
+ * over-commented on purpose: this file is read far more than it runs.
+ *
+ * A tool is ONE file, `src/tools/<name>.tool.tsx`, exporting exactly two
+ * things:
+ *   1. `tool` — metadata via `defineTool` (id, tab title, placement),
+ *   2. a default-exported plain React component.
+ * The editor discovers it automatically (folder scan — no registration
+ * anywhere; delete the file and the tab is gone) and docks it as a ⚙ tab
+ * after the built-in bottom tabs. It stays interactive during play mode, so
+ * you tune while the game runs.
+ *
+ * Tools are EDITOR-ONLY dev surfaces: nothing in game code imports
+ * `src/tools/`, so `npm run build` never bundles this file — cheats and
+ * tuning panels can't leak into a shipped game. Keep game logic out of here.
+ *
+ * This example closes the full live-tuning loop on the `tuning` data asset
+ * (`src/data/` — the trio this project ships working):
+ *
+ *   slider → writeData() → src/data/tuning.data.json written on disk
+ *          → Vite HMR → tuning.hotSwap() → useData re-renders this panel
+ *          → and the RUNNING game (DataSpinner reads tuning.get() per frame)
+ *            picks the value up the same instant, no reload.
+ *
+ * That's the whole architecture: the file is the document; the editor, this
+ * panel, VS Code, and the game are all just views of it.
+ */
+
+import { useData, writeData } from '@engine/react/use-data';
+import { defineTool } from '@engine/tools/define-tool';
+// A tool imports the project's OWN data handles — the same ones the game
+// reads. One handle, every surface agrees on the values.
+import { tuning } from '../data/tuning';
+
+/** The editor reads this export to place the tool (docs/DATA-TOOLS-DESIGN.md
+ *  §3.1). `id` keys the tab (test id `bottom-tab-tool-tuning`); `title` is
+ *  the label; `'dock'` is the project-global bottom-tab placement (for the
+ *  selection-scoped `'inspector'` placement, see `spin.tool.tsx`). */
+export const tool = defineTool({
+  id: 'tuning',
+  title: 'Tuning',
+  placement: 'dock',
+});
+
+/** The panel itself: plain React, inline styles (editor chrome around it is
+ *  editor-styled; what's inside is yours). No providers needed. */
+export default function TuningTool() {
+  // useData = live values: re-renders once per accepted edit of the data
+  // file, whoever made it (this slider, the editor's Data tab, VS Code, an
+  // agent). Read it every render — never copy fields into component state.
+  const values = useData(tuning);
+
+  return (
+    <div style={{ padding: 12, fontSize: 12, fontFamily: 'ui-monospace, monospace' }}>
+      {/* Live readout — proves the round trip: drag the slider (or edit the
+          JSON anywhere else) and watch these values follow the file. */}
+      <div style={{ marginBottom: 10, color: '#8c8c8c' }}>
+        src/data/tuning.data.json (live):
+        <pre style={{ margin: '4px 0 0', color: 'inherit' }}>{JSON.stringify(values, null, 2)}</pre>
+      </div>
+
+      <label style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+        boxSpinSpeed
+        <input
+          type="range"
+          min={-5}
+          max={5}
+          step={0.1}
+          data-testid="tool-slider-boxSpinSpeed"
+          // Uncontrolled (defaultValue) on purpose: the authoritative value
+          // round-trips through the FILE (write → HMR → useData), which can
+          // lag a beat behind the pointer — controlling the thumb from that
+          // would make it fight the drag. The readout above is the live view.
+          defaultValue={values.boxSpinSpeed}
+          // writeData writes the WHOLE file through the editor dev server
+          // (only src/data/**/*.data.json is accepted): spread the current
+          // values, replace one field. It's async — fire and forget here.
+          onChange={(e) =>
+            void writeData('src/data/tuning.data.json', {
+              ...values,
+              boxSpinSpeed: Number(e.target.value),
+            })
+          }
+        />
+        <span>{values.boxSpinSpeed}</span>
+      </label>
+    </div>
+  );
+}

package/template/src/tools/spin.tool.tsx

@@ -0,0 +1,101 @@
+/**
+ * Example INSPECTOR tool — the selection-scoped project-tool pattern
+ * (docs/DATA-TOOLS-DESIGN.md §3, W3/W3.1, in the engine checkout). Slightly
+ * over-commented on purpose: this file is read far more than it runs.
+ *
+ * Same one-file physics as the dock example (`example.tool.tsx`), different
+ * placement: `placement: 'inspector'` + a `match` predicate. Instead of a
+ * bottom-dock tab, the editor renders this as a ⚙-marked SECTION in the
+ * Inspector rail whenever the current selection satisfies `match` — select
+ * the Box (it has a `DataSpinner`) and it appears under the built-in
+ * sections; select the Ground (a mesh, but no `DataSpinner`) or a light and
+ * it's gone. It stays live during play mode, so you tune while the game runs.
+ *
+ * Three things this file demonstrates beyond the dock example:
+ *
+ * 1. `match(node, adapter)` — the selection predicate, now COMPONENT-based
+ *    rather than shape-based: it asks `adapter.components?.list(node.id)`
+ *    for the attached component types instead of guessing from `node.kind`.
+ *    Keep it cheap and pure, it runs on every inspector render.
+ * 2. `useSelection()` (`@engine/react/use-selection`, W3.1) — inside the
+ *    component, this returns the selected node PLUS its attached components
+ *    and each one's own authored config (`ComponentsProvider.config`). Here
+ *    it reads `DataSpinner`'s per-entity `spinScale` — read-only in v1;
+ *    per-entity WRITE-from-tool is future `useTunable`/inspector-set
+ *    territory. `useSelection` only works inside an inspector tool (it
+ *    throws a teaching error from a dock tool — there is no selection there).
+ * 3. `@editor/widgets` — the editor's OWN widget kit + design tokens,
+ *    public for project tools (§3.4 "tools are editor citizens"): panels
+ *    built from it sit flush with the built-in inspector sections and
+ *    re-skin with the editor. `NumberInput` here is the exact
+ *    scrub-or-type field the built-in Transform section uses.
+ *
+ * The component receives `{ node, nodeId }` as props (see
+ * `InspectorToolProps` in `@engine/tools/define-tool`) — unchanged by W3.1;
+ * richer data arrives through `useSelection()`, not more props. Like every
+ * tool, it's editor-only: `npm run build` never bundles this file.
+ */
+
+import { NumberInput, THEME } from '@editor/widgets';
+import { useData, writeData } from '@engine/react/use-data';
+import { useSelection } from '@engine/react/use-selection';
+import { defineTool, type InspectorToolProps } from '@engine/tools/define-tool';
+// The same project data handle the game (DataSpinner) and the dock example
+// read — one handle, every surface agrees on the values.
+import { tuning } from '../data/tuning';
+
+export const tool = defineTool({
+  id: 'spin',
+  title: 'Spin tuning',
+  placement: 'inspector',
+  // Show this section only on an entity with a DataSpinner attached — the
+  // component-based idiom (rather than guessing from `node.kind`). `node` is
+  // null in the no-selection state — return false to stay out of the panel.
+  match: (node, adapter) =>
+    node !== null &&
+    (adapter.components?.list(node.id) ?? []).some((c) => c.type === 'DataSpinner'),
+});
+
+export default function SpinInspector({ node }: InspectorToolProps) {
+  // Live values: re-renders on every accepted edit of the data file,
+  // whoever made it (this field, the dock tool, the DATA tab, VS Code).
+  const values = useData(tuning);
+
+  // The selected entity's own components + their authored config, live
+  // (W3.1) — distinct from `values` above: `tuning` is project-wide feel,
+  // `spinScale` here is THIS entity's own per-entity knob.
+  const { components } = useSelection();
+  const spinner = components.find((c) => c.type === 'DataSpinner');
+  const spinScale =
+    typeof spinner?.config?.['spinScale'] === 'number'
+      ? (spinner.config['spinScale'] as number)
+      : 1;
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 6, fontSize: 11 }}>
+      <div style={{ color: THEME.textMuted }}>
+        {node ? `Selected: ${node.label}` : 'Nothing selected'} — boxSpinSpeed drives the Box's
+        DataSpinner (src/data/tuning.data.json, live)
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+        <span style={{ color: THEME.textMuted, width: 90 }}>boxSpinSpeed</span>
+        {/* The editor's own scrub-or-type number field (@editor/widgets):
+            drag horizontally to scrub, click to type. writeData writes the
+            whole data file through the dev server; HMR flows it back into
+            useData above AND the running game. */}
+        <NumberInput
+          value={values.boxSpinSpeed}
+          step={0.1}
+          testId="spin-tool-speed"
+          style={{ flex: 1 }}
+          onChange={(v) =>
+            void writeData('src/data/tuning.data.json', { ...values, boxSpinSpeed: v })
+          }
+        />
+      </div>
+      <div style={{ color: THEME.textMuted }} data-testid="spin-tool-entity-scale">
+        this entity's spinScale: {spinScale} ×
+      </div>
+    </div>
+  );
+}