@vgai/editor 0.4.0 → 0.4.1

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

@@ -1,86 +0,0 @@
-import { GameComponent } from '@engine/ecs/game-component';
-import type { GameContext } from '@engine/runtime/types';
-import type * as THREE from 'three';
-import { z } from 'zod';
-import { tuning } from '../../data/tuning';
-import { advanceLap } from './spin-lap-math';
-
-/**
- * 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`).
- *
- * It's also the template's worked debug-seam consumer (`ctx.debug`,
- * `docs/SYNTHETIC-PLAYER-SPEC.md`/`docs/ACCEPTANCE-DRIVER-SPEC.md`, Task
- * 4.2): holding the `attack` action (see `public/inputmaps/default.inputmap.json`)
- * boosts the spin, and each completed lap emits a `spin-lap` event —
- * `tests/acceptance/example.spec.ts` drives `attack` through the HONEST input
- * path and asserts on the resulting `spinner` state/events; `spinner.reset`
- * is a declared fixture, never a substitute for that proof (D16).
- */
-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;
-  private rotationSinceLap = 0;
-  private lapsCompleted = 0;
-
-  init(ctx: GameContext) {
-    ctx.debug?.registerStateProvider(
-      'spinner',
-      () => ({ lapsCompleted: this.lapsCompleted, spinScale: this.spinScale }),
-      { tier: 'observable' },
-    );
-    // Fixture, never a proof (D16): lets a test jump straight to a known
-    // lapsCompleted instead of waiting out real spin time. The acceptance
-    // spec's actual PROOF is driving 'attack' through game.input.hold and
-    // asserting on the observable 'spinner' state/'spin-lap' events below.
-    ctx.debug?.registerCommand(
-      'spinner.reset',
-      { description: 'Reset lapsCompleted to 0.', locus: 'client' },
-      () => {
-        this.lapsCompleted = 0;
-        this.rotationSinceLap = 0;
-      },
-    );
-  }
-
-  update(dt: number, ctx: GameContext) {
-    const t = tuning.get();
-    const boost = ctx.input.isPressed('attack') ? 4 : 1;
-    const delta = t.boxSpinSpeed * this.spinScale * boost * dt;
-    this.object3D.rotation.y += delta;
-
-    const progress = advanceLap(this.rotationSinceLap, delta);
-    this.rotationSinceLap = progress.rotationSinceLap;
-    if (progress.lapsCompleted > 0) {
-      this.lapsCompleted += progress.lapsCompleted;
-      ctx.debug?.emit('spin-lap', { lapsCompleted: this.lapsCompleted });
-    }
-
-    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/spin-lap-math.ts

@@ -1,27 +0,0 @@
-/**
- * Pure lap-counting math for `DataSpinner` (`data-spinner.ts`) — factored out
- * into its own zero-dependency module so `tests/logic/example.test.ts` can
- * exercise the actual rule the component ships with, with no `@engine`/DOM/
- * Playwright dependency: the L1 layer (`docs/ACCEPTANCE-DRIVER-SPEC.md` §0 —
- * "never debug a pure-model bug through the browser").
- */
-
-const FULL_ROTATION = Math.PI * 2;
-
-export interface LapProgress {
-  /** Radians accumulated since the last completed lap, always in `[0, 2π)`. */
-  rotationSinceLap: number;
-  /** How many full 2π rotations `delta` pushed past on this call (0, 1, 2, ...). */
-  lapsCompleted: number;
-}
-
-/** Advance `rotationSinceLap` by `delta` radians, rolling over into completed laps. */
-export function advanceLap(rotationSinceLap: number, delta: number): LapProgress {
-  let next = rotationSinceLap + delta;
-  let lapsCompleted = 0;
-  while (next >= FULL_ROTATION) {
-    next -= FULL_ROTATION;
-    lapsCompleted++;
-  }
-  return { rotationSinceLap: next, lapsCompleted };
-}

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

@@ -1,97 +0,0 @@
-/**
- * Example project tool (a center-document tool) — the worked 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 it's gone) and opens it as a CENTER
- * workspace document via the command palette's `Open Tool: Tuning` action
- * (`placement: 'document'`; the older `placement: 'dock'` spelling preserves
- * its historical bottom-panel placement; a `placement: 'utility'` tool also
- * renders as a bottom utility). 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 document; `title` is the tab/action label;
- *  `'document'` is the project-global placement — it opens as a center
- *  document (for the selection-scoped `'inspector'` placement, see
- *  `spin.tool.tsx`; transient output panels declare `'utility'` and render
- *  as a bottom tab). `'dock'` is a deprecated compatibility spelling for a
- *  bottom utility — supported so existing tools keep their behavior. */
-export const tool = defineTool({
-  id: 'tuning',
-  title: 'Tuning',
-  placement: 'document',
-});
-
-/** 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

@@ -1,101 +0,0 @@
-/**
- * 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>
-  );
-}

package/template/tests/logic/example.test.ts

@@ -1,31 +0,0 @@
-/**
- * L1 — logic layer (`docs/ACCEPTANCE-DRIVER-SPEC.md` §0): pure rules/math in
- * plain Node tests, seconds per run, never through a browser. This exercises
- * the ACTUAL lap-counting rule `DataSpinner` (`src/scripts/components/
- * data-spinner.ts`) ships with — imported from its real module, not
- * reimplemented here — so a regression in the rule fails here first, not in
- * the slower L2 acceptance spec (`tests/acceptance/example.spec.ts`).
- */
-
-import { describe, expect, it } from 'vitest';
-import { advanceLap } from '../../src/scripts/components/spin-lap-math';
-
-describe('advanceLap', () => {
-  it('accumulates rotation without completing a lap below 2π', () => {
-    const result = advanceLap(0, 1);
-    expect(result.lapsCompleted).toBe(0);
-    expect(result.rotationSinceLap).toBeCloseTo(1, 10);
-  });
-
-  it('completes exactly one lap and carries the remainder', () => {
-    const result = advanceLap(0, Math.PI * 2 + 1);
-    expect(result.lapsCompleted).toBe(1);
-    expect(result.rotationSinceLap).toBeCloseTo(1, 10);
-  });
-
-  it('completes multiple laps in a single large step', () => {
-    const result = advanceLap(0, Math.PI * 2 * 3.5);
-    expect(result.lapsCompleted).toBe(3);
-    expect(result.rotationSinceLap).toBeCloseTo(Math.PI, 10);
-  });
-});