@vgai/editor 0.2.0

package/src/widgets/index.ts

@@ -0,0 +1,73 @@
+/**
+ * `@editor/widgets` — the editor's widget kit + design tokens, promoted to a
+ * public export for PROJECT tools (W3 of `docs/DATA-TOOLS-DESIGN.md`, §3.4:
+ * "tools are editor citizens"). The same reference-implementation-becomes-
+ * shipped-API move as the R3F bridge: these are the editor's OWN widgets —
+ * the exact components its inspector renders — so a project tool built from
+ * them looks native to the editor and re-skins with it.
+ *
+ * Import it from a `src/tools/*.tool.tsx` file:
+ *
+ * ```tsx
+ * import { NumberInput, SectionHeader, THEME } from '@editor/widgets';
+ * ```
+ *
+ * What's here:
+ * - **Tokens**: `THEME` (editor dark-panel palette), `FONT` / `FONT_MONO`,
+ *   and the shared style helpers (`inputStyle`, `rowStyle`,
+ *   `miniButtonStyle`, `toggleButtonStyle`).
+ * - **Structure**: `Panel` (titled panel container), `SectionHeader`
+ *   (collapsible section title row), `Tooltip`.
+ * - **Inputs**: `NumberInput` (scrub-or-type), `Vec3Input`, `ColorInput`,
+ *   `ScrubbableInput`, `ColorPicker`/`ColorSwatch`, `GradientEditor`,
+ *   `FontPicker`, `AlignmentGrid`, `BorderEditor`, `ShadowEditor`,
+ *   `FilterEditor`, `ToggleButton`.
+ *
+ * Contract notes:
+ * - The rich widgets share one change contract, `ChangeHandlers<T>`
+ *   (`value` + `onChange` per interaction tick + optional `onChangeEnd`
+ *   commit — see its doc comment).
+ * - Everything else a tool needs — layout, state, charts — is deliberately
+ *   NOT API (§3.3): plain React, the project's choice.
+ * - This barrel is the ONLY sanctioned deep-import into editor source from
+ *   project code. Its dependency closure is kept deliberately shallow
+ *   (react + the widget files themselves) so a scaffolded project's `tsc`
+ *   never drags the editor's internals along; `interactive-edit-scope.ts`
+ *   exists precisely to keep `NumberInput`/`ColorInput` off `EditorContext`.
+ *   Don't add re-exports here that import the editor store, adapters, or
+ *   server code.
+ */
+
+// --- Rich inspector widgets (spec 27 §5 C1 kit) ------------------------------
+export * from '../components/inspector-widgets/AlignmentGrid';
+export * from '../components/inspector-widgets/BorderEditor';
+export * from '../components/inspector-widgets/ColorPicker';
+export type { ColorFormat } from '../components/inspector-widgets/color-utils';
+export * from '../components/inspector-widgets/FilterEditor';
+export * from '../components/inspector-widgets/FontPicker';
+export * from '../components/inspector-widgets/GradientEditor';
+export * from '../components/inspector-widgets/ScrubbableInput';
+export * from '../components/inspector-widgets/ShadowEditor';
+// --- Tokens + shared helpers (the widget kit's design system) --------------
+export {
+  type ChangeHandlers,
+  FONT,
+  FONT_MONO,
+  fireChange,
+  fireEnd,
+  inputStyle,
+  miniButtonStyle,
+  parseNumericValue,
+  rowStyle,
+  THEME,
+  ToggleButton,
+  toggleButtonStyle,
+} from '../components/inspector-widgets/shared';
+// --- Simple inputs (the primitives the built-in inspector uses) -------------
+export { ColorInput } from '../components/primitives/ColorInput';
+export { NumberInput } from '../components/primitives/NumberInput';
+// --- Structure --------------------------------------------------------------
+export { Panel } from '../components/primitives/Panel';
+export { SectionHeader } from '../components/primitives/SectionHeader';
+export { Tooltip } from '../components/primitives/Tooltip';
+export { Vec3Input } from '../components/primitives/Vec3Input';

package/template/.claude/skills/editor/SKILL.md

@@ -0,0 +1,252 @@
+# Skill: Editor Control
+
+Use the `vgai` CLI to create projects, launch the editor, and control it programmatically. The editor is a browser-based WebGL app; the CLI sends commands to it over HTTP.
+
+## Installation
+
+The CLI lives in the vgai monorepo checkout this project was scaffolded from
+(the same checkout `@vgai/engine` symlinks back into). Build it once — plain
+npm, no bun required (make sure the checkout root has had `npm install`):
+
+```bash
+cd <vgai-checkout>/packages/vgai-cli && npm run build
+```
+
+Then invoke the built bundle with node — from any directory, including your
+project (the CLI locates the engine checkout from its own file location, not
+your cwd):
+
+```bash
+node <vgai-checkout>/packages/vgai-cli/dist/index.js <command>
+```
+
+For a `vgai` command, add a shell alias:
+
+```bash
+alias vgai="node <vgai-checkout>/packages/vgai-cli/dist/index.js"
+```
+
+Do **not** use `npm link`/`bun link`: invoked through a symlink the CLI's
+entry-point check fails and the command exits silently doing nothing. Direct
+`node dist/index.js` invocation (or the alias above) is the supported path.
+
+## Quick Start
+
+```bash
+vgai create "My Game"            # Scaffold a new project in ./my-game
+cd my-game
+vgai edit                        # Launch editor + open browser
+vgai play                        # Enter play mode
+vgai status                      # Check editor state
+```
+
+**Port cross-talk:** the default editor port (5173) is shared across every
+vgai project on the machine. `vgai edit` never silently retargets a
+DIFFERENT project's already-running editor — if one is already open
+elsewhere, this one starts a second instance on a fresh free port and prints
+that URL instead (use `--switch` to retarget the existing one on purpose).
+If you might have another vgai project's tab open in the browser already,
+don't assume it's this project: read the URL `vgai edit` actually prints
+(check `vgai sessions` to see every live session's port → project), or pass
+`vgai edit --port <n>` to pin an explicit port for this project so a stale
+tab from a different project can't be mistaken for this session.
+
+## Precondition: most verbs need a connected browser tab, not just `vgai edit` running
+
+`vgai edit` starts the dev server and prints a URL — it does **not** by
+itself give the CLI anything to talk to. Every control verb (`play`,
+`select`, `focus`, `show`, `status`, ...) is relayed over HTTP/SSE to an
+actual browser tab that has the editor page open and running; the dev
+server just serves that page. Running `vgai edit` (or `vgai edit --no-open`,
+the flag meant for headless/agent use) and then immediately calling `vgai
+status` with **no tab ever opened** does not error — it returns the last
+**cached** state from a previous session (or an empty default), and prints
+a `⚠ No editor connected` warning to stderr. Read that warning: it means
+the JSON below it is stale, not live. Before trusting `vgai status` (or
+issuing `play`/`select`/etc. and expecting them to do anything), make sure
+a tab is actually open on the printed URL — a real browser, or a
+Playwright/Puppeteer page you navigated to it yourself.
+
+**Driving the editor headlessly (e.g. from an agent or CI):**
+
+```bash
+vgai edit --no-open   # start the dev server without launching a real browser
+```
+
+```ts
+// then, in a Playwright script, open a page against the printed URL —
+// use 'load', NOT 'networkidle': the editor dev server keeps a
+// long-lived SSE/websocket connection open for live commands, so the
+// network never goes idle and `waitUntil: 'networkidle'` hangs forever.
+await page.goto('http://localhost:5173', { waitUntil: 'load' });
+```
+
+Once that page has loaded, it registers as a connected client and `vgai
+status`/`vgai play`/etc. from another shell will reach it for real.
+
+## When to Use This Skill
+
+- **`create` / `edit`** — bootstrap and launch projects
+- **`play` / `stop` / `select` / `focus` / etc.** — show things to the user, control play mode
+- You do NOT need the CLI for entity/asset/scene changes — those are just file edits (`.vscn.json` files in `public/`)
+
+## CLI Reference
+
+### Project Management (no running editor needed)
+
+```bash
+vgai create <name> [location]              # Create project (default location: ./)
+vgai create <name> [location] --template empty  # Minimal empty project
+vgai edit [project-path]                   # Launch editor for project (default: cwd).
+                                           # Reuses the session already serving THIS
+                                           # project; otherwise starts a NEW instance on
+                                           # a free port rather than silently retargeting
+                                           # a different project's editor (see the port
+                                           # cross-talk note above).
+                                           #   --switch    retarget an existing instance
+                                           #               instead of starting a new one
+                                           #   --port <n>  force a port for a fresh instance
+vgai sessions                              # List live editor sessions (port -> project)
+```
+
+### Scene & Project Info (needs running editor)
+
+```bash
+vgai scene <path>                # Open a scene file (e.g. scenes/default.vscn.json)
+vgai open <path>                 # Switch project in running editor
+vgai project                     # Show current project info
+vgai projects                    # List recent projects
+```
+
+### Play Control
+
+```bash
+vgai play                        # Enter play mode
+vgai stop                        # Exit play mode
+vgai pause                       # Pause (while playing)
+vgai resume                      # Resume (while paused)
+vgai step                        # Advance one frame (while paused)
+```
+
+### Navigation
+
+```bash
+vgai select <entityId>           # Select an entity by ID
+vgai select --all                # Select all entities
+vgai deselect                    # Clear selection
+vgai focus <entityId>            # Focus camera on a specific entity
+vgai focus                       # Focus camera on current selection
+vgai view top                    # Top-down camera
+vgai view front                  # Front camera
+vgai view right                  # Right camera
+vgai view perspective            # Default perspective camera
+```
+
+### Panels
+
+```bash
+vgai show viewport scene         # Switch to Scene tab
+vgai show viewport game          # Switch to Game tab
+vgai show inspector              # Show the inspector panel
+vgai show console                # Toggle the console panel
+vgai show build                  # Show the build panel
+vgai open-asset <path> <kind>    # Open an asset tab (kind: model|image|audio|scene|prefab|material|json|animation)
+```
+
+### Display Modes
+
+```bash
+vgai grid on                     # Show grid
+vgai grid off                    # Hide grid
+vgai helpers on                  # Show all helpers (lights, cameras, colliders, etc.)
+vgai helpers off                 # Hide all helpers
+vgai stats on                    # Show performance stats overlay
+vgai stats off                   # Hide stats
+vgai shading solid               # Standard shading
+vgai shading wireframe           # Wireframe mode
+vgai shading unlit               # Unlit/flat shading
+```
+
+### State
+
+```bash
+vgai status                      # Print full editor state as JSON
+```
+
+The `status` command returns:
+- `playState` — `stopped`, `playing`, or `paused`
+- `selectedEntityId` / `selectedEntityIds` — current selection
+- `activeViewportTab` — `scene` or `game`
+- `showGrid`, `showHelpers`, `showStats`, `shadingMode` — display state
+- `transformMode`, `transformSpace`, `snapEnabled` — tool state
+- `entityCount` — number of entities in the scene
+- `savePath` — path to the currently open scene file
+- `connected` — whether an editor browser tab is live right now; if
+  `false`, everything else in the payload is a cached snapshot (see the
+  precondition note above)
+
+### Global Options
+
+```bash
+--url <url>                      # Editor URL (default: http://localhost:5173)
+                                 # Also: VGAI_EDITOR_URL env var
+```
+
+## Entity IDs
+
+Entity IDs are UUIDs stored in `.vscn.json` scene files. To find an entity's ID:
+
+1. Read the scene file (e.g., `public/scenes/default.vscn.json`)
+2. Each entity object has an `"id"` field
+3. Use that ID with `vgai select <id>` or `vgai focus <id>`
+
+## Typical Workflows
+
+### Start a new project from scratch
+
+```bash
+vgai create "My Platformer"
+cd my-platformer
+vgai edit
+```
+
+### Show the user an entity you just created/modified
+
+```bash
+# After editing a .vscn.json file:
+vgai select <entity-id>
+vgai focus <entity-id>
+```
+
+### Test gameplay
+
+```bash
+vgai play
+# ... observe behavior ...
+vgai stop
+```
+
+### Debug a specific view angle
+
+```bash
+vgai view top
+vgai shading wireframe
+vgai helpers on
+```
+
+## SDK (Programmatic Access)
+
+For TypeScript automation, use `@vgai/editor-sdk` directly:
+
+```typescript
+import { EditorClient } from '@vgai/editor-sdk';
+
+const editor = new EditorClient(); // default: http://localhost:5173
+await editor.play();
+const state = await editor.getState();
+await editor.select(state.selectedEntityId);
+await editor.focusSelection();
+await editor.stop();
+```
+
+The `EditorClient` has the same methods as the CLI: `play()`, `stop()`, `pause()`, `resume()`, `step()`, `select()`, `selectAll()`, `focusEntity()`, `focusSelection()`, `viewPreset()`, `showViewport()`, `showInspector()`, `setGrid()`, `setHelpers()`, `setShadingMode()`, `getState()`, `waitForState()`, `createProject()`, `openProject()`, `getProject()`, `listRecentProjects()`, etc.