@jgengine/editor 0.10.0 → 0.12.0

package/skills/jgengine/recipes/minimal-game.md

@@ -0,0 +1,88 @@
+# Recipe — minimal game (scaffold → authored scene → win)
+
+**What this wires:** the default end-to-end path from nothing to a complete, genre-free
+walk/interact/win game: a scaffold, one `defineGame` config off the happy-path kit, an
+authored scene edited in the browser, one system, one store slot, an empty-canvas HUD,
+and a win condition. Every new game starts here; add combat, multiplayer, or deeper
+world features only after this loop plays.
+
+## 1. Scaffold
+
+`npx jgengine create <name>` (inside the engine monorepo: `bun run new:game "<id-or-title>"`).
+The file set is thin and already runs:
+
+- `src/main.tsx` — mounts `GameHost` with `editor={() => import("@jgengine/editor")}`; the
+  host owns the F2+E / `?mode=editor` editor summon and the dev save endpoint.
+- `src/game.config.ts` — the whole game definition (below).
+- `src/editor.scene.json` + `src/editorLayers.ts` — the authored scene document, normalized
+  with `normalizeEditorLayers`. All placement lives here, never as coordinates in code.
+- `src/loop.ts` and `src/game/ui/GameUI.tsx` — systems and HUD.
+
+## 2. Define the game — one import surface
+
+```ts
+// game.config.ts — everything below comes from the kit; deeper paths are for outgrowing it.
+import { defineGame } from "@jgengine/shell/gameKit";
+
+import { editorLayers } from "./editorLayers";
+import { GameUI } from "./game/ui/GameUI";
+import { onNewPlayer, systems } from "./loop";
+
+export const game = defineGame({
+  name: "my-game",
+  // Binding movement actions makes the shell drive the walk controller — the game walks day one.
+  input: { moveForward: ["KeyW"], moveBack: ["KeyS"], moveLeft: ["KeyA"], moveRight: ["KeyD"], interact: ["KeyE"] },
+  systems,
+  loop: { onNewPlayer },
+  GameUI,
+  editorLayers, // the authored scene auto-mounts; the player spawns at its player_spawn marker
+});
+// Solo game: omit `multiplayer` entirely — offline is the shell default.
+```
+
+**World is optional and thin.** Omitting `world` is valid — a pure UI/rules game is not a
+spatial place. When the game *is* a place, declare only substrate + laws with `world()` from
+`@jgengine/core/world/place` (e.g. `{ id, ground: { mode: "flat", size: { x: Infinity, z: Infinity } }, physics: { gravity: -24 } }`,
+or `mode: "board"` for 2D). Never seed, sky, or vegetation in `world` — the engine renders its
+default sky until you author one in the editor, and foliage is editor scatter over the ground.
+
+
+```ts
+// loop.ts — one store slot for run state, one system for the rules tick.
+import { defineStore, defineSystem, authoredSpawnPosition, type GameContext } from "@jgengine/shell/gameKit";
+
+import { editorLayers } from "./editorLayers";
+
+export const run = defineStore("run", { collected: 0, won: false });
+
+export const systems = [
+  defineSystem({
+    id: "rules",
+    tick: { type: "fixed" },
+    update(ctx: GameContext) {
+      // System-check win alternative: read/update `run` here (e.g. win at collected >= 3).
+      if (run.read(ctx).collected >= 3) run.update(ctx, (s) => ({ ...s, won: true }));
+    },
+  }),
+];
+
+export function onNewPlayer(ctx: GameContext): void {
+  ctx.scene.entity.spawn("player", { id: ctx.player.userId, position: authoredSpawnPosition(editorLayers) ?? [0, 0, 0] });
+}
+```
+
+`GameUI` starts as an empty `HudCanvas` (`useHudLayout` + `HudCanvas` from the kit). That is
+intentional: **every game owns its UI**. Write a short UI art direction, then build custom
+panels for this pitch — do not ship stock drop-in widgets (`StatBar`, `Hotbar`, `Coins`, glass
+frames) as the product face. Reach for engine pieces only as headless data, layout, or
+interaction models under game-owned chrome (see `jgengine-ui`).
+
+## 3. Author, play, win
+
+1. `bun dev`, then F2+E opens the editor on `editor.scene.json` — move the spawn, place
+   props and trigger markers, Ctrl+S saves back to the document.
+2. The starter scene ships a goal marker with `{ on: "enter", action: "win" }` — walking
+   into it wins with zero game code. Author more rules the same way (triggers in the
+   editor), or read volumes yourself via the kit's `collectAuthoredTriggers(editorLayers)`.
+3. Prove it: `bun test` asserts the document (spawn, goal), and `jgengine-verify` covers
+   screenshot and gameplay evidence before any "it works" claim.

package/skills/jgengine-editor/SKILL.md

@@ -1,382 +1,49 @@
 ---
 name: jgengine-editor
-description: Open the scene editor to place spawns, zones, and ranges visually.
+description: Author scene content and assets through the JGengine editor.
 ---
 
-# JGengine Editor
+# JGengine editor
 
-## When to use
+## Ownership
 
-Authoring or inspecting spatial game data: terrain context, player/mob/boss spawns, zone disks, aggro/leash/discover radii, corridor paths. Prefer this over guessing `x,y,z` in TS tables.
+This skill owns scene-document authoring: objects, spawns, markers, terrain, paths, zones, foliage, materials, and asset placement. `editor.scene.json` is the source of truth consumed by runtime and gameplay. Use `jgengine-world` for rendering and querying authored data.
 
-## Open (human / agent browser)
+Never replace authorable scene content with hardcoded meshes, coordinate arrays, or game-specific placement code. If the document or editor lacks a required kind, file a `[FEATURE]` issue before a code fallback and record the gap in the PR.
 
-```
-bun run dev:runner
-# http://localhost:<port>/?game=the-robots&mode=editor
-# http://localhost:<port>/?game=vice-isle&mode=editor
-```
-
-The editor ships everywhere as a **lazy chunk** — production `/play` (and the public `/games/<id>` pages) download it only when summoned with F2+E or `?mode=editor`. In the dev runner, **Save (Ctrl+S)** writes the scene straight to `Games/<id>/src/editor.scene.json` through the dev server's `/__jgengine/save` endpoint; the file auto-loads on the next editor open as an overlay (same-id objects win over the game's derived `editorLayers`, new objects append) and is plain JSON a game can import as runtime data. Fold long-lived edits back into source tables when they stabilize. Outside the dev server (production pages) the Save button hides and Export JSON remains the only exit. The F2+D Tune tab has the same seam: **Save to source** rewrites changed tunable literals directly in `Games/<id>/src/*.ts`.
-
-## Standalone games ship the editor too
-
-`npx jgengine create` scaffolds all of this outside the monorepo: the game's `main.tsx` summons the editor on F2+E or `?mode=editor` as a lazy `@jgengine/editor` chunk, and `vite.config.ts` mounts the published save middleware so Save (Ctrl+S) writes `src/editor.scene.json` and Tune's Save-to-source rewrites literals:
-
-```ts
-import { standaloneSavePlugin } from "@jgengine/node/devSavePlugin";
-export default defineConfig({ plugins: [react(), tailwindcss(), standaloneSavePlugin()] });
-```
-
-Monorepo-shaped hosts use the general form — `devSavePlugin((gameId) => srcDirFor(gameId))` — and `handleSaveRequest` is the transport-free core for a non-Vite dev server.
-
-## Standalone — the editor without a game (any project)
-
-The same editor runs **gameless**, on any folder, for people who aren't building a jgengine game. Two zero-config entry points, one shared seam:
-
-```
-npx jgengine editor [dir]     # open the 3D editor on a folder (default cwd); Ctrl+S writes dir/editor.scene.json
-                              # [--assets <dir>] pick the model folder · [--port <n>] · [--out <workspace>]
-```
+## Scene ownership boundary
 
-`jgengine editor` scaffolds a tiny Vite workspace (`.jgengine-editor/`) and serves the target folder: its `editor.scene.json` opens as the scene and every `.glb`/`.gltf` under it (or `--assets`) becomes a placeable asset. The **desktop app** exposes the identical editor at `?mode=editor` — no game loaded, blank world. Both mount `@jgengine/editor`'s `StandaloneEditor`, which drops the editor over a blank flat world instead of a game (a slim strip also lets you **📂 Open scene** / **🧊 Add assets** at runtime):
+Every editor-visible object has an explicit provenance — `authored`, `generated`, `runtime`, or `transient` — and a single verdict from `classifyOwnership` (`@jgengine/core/scene/sceneOwnership`): **expose** (authorable), **bake** (offer import to the document when the provider can emit schema-valid data), or **reject** (read-only runtime content). Runtime/transient content with neither a `bake` capability nor a declared `reason` is a boundary violation — content bypassing the document with no authored home. Genuinely runtime-only or geometry-free content is declared with a serializable `SceneOwnershipManifest` (`scene-ownership.json`), which `check-content-gate` validates — the replacement for game-name exemptions.
 
-```tsx
-import { StandaloneEditor, createBlankPlayable, blankWorld, downloadSaver } from "@jgengine/editor";
+## Headless fast path
 
-// Turn-key: blank world, built-in pickers, Save → dev-server endpoint or a browser download.
-<StandaloneEditor sceneId="my-scene" save={downloadSaver("scene.json")} />;
+Inspect, mutate, and persist a game's scene in single commands — no GUI session and no reference reading needed for basic authoring:
 
-// Or build the gameless host yourself and mount EditorApp over it:
-const playable = createBlankPlayable({ assets: [{ id: "tree", url: "/models/tree.glb" }], world: blankWorld("seed") });
+```sh
+bun packages/editor/src/mcp/cli.ts --game <id> --tools                     # verb inventory with descriptions
+bun packages/editor/src/mcp/cli.ts --game <id> --rpc '{"method":"scene_summary"}'
+bun packages/editor/src/mcp/cli.ts --game <id> \
+  --rpc '{"method":"set_transform","id":"boss","x":10,"y":0,"z":-5}' --save
 ```
 
-The server half is `@jgengine/node/editorHostPlugin` — a Vite plugin that serves the folder's scene + models at `/__jgengine/manifest`, streams model bytes, and writes Save back. `buildEditorManifest(sceneDir, assetsDir)` is its pure core (read the scene, scan the folder); `editorScaffold(engineVersion)` (from `@jgengine/jgengine/templates`) emits the workspace files:
-
-```ts
-import { editorHostPlugin, buildEditorManifest } from "@jgengine/node/editorHostPlugin";
-import { editorScaffold } from "@jgengine/jgengine/templates";
-
-export default defineConfig({ plugins: [react(), editorHostPlugin({ dir: process.cwd() })] });
-const manifest = buildEditorManifest(sceneDir, assetsDir); // { scene, assets: [{ id, url, label }] }
-const files = editorScaffold("0.10.0");                    // index.html, vite.config.ts, src/main.tsx, …
-```
-
-## Modes: edit · walk · play
-
-- **edit** — frozen sim, orbit inspection camera, gizmos and chrome.
-- **walk** — frozen sim, the game's own camera/movement; roam the world with markers drawn in place.
-- **play** — the real game (loop, HUD, camera) with a floating exit chip.
-
-Toolbar buttons, `F2+E` (edit ↔ play, same chord family as F2+D devtools), chip/F2+E returns to edit, or RPC: `{ method: "set_mode", mode: "play" }`. The editor session (document, undo, selection) survives mode switches. **F2+E summons the editor from any running `mode=play` game** — dev runner or the website's `/games/<id>` pages, dev and production alike, no URL change needed.
-
-## Perf: the editor measures itself
-
-- Toolbar shows a live `fps · draws · tris` pill (red under 30fps).
-- `F2+D` opens the engine devtools panel (debug mode) — sim phase bars name the exact lag culprit.
-- Agents: `{ method: "editor_status" }` includes a `perf` sample and current `mode`; `{ method: "perf_report" }` returns the devtools snapshot (fps, sim phases, culprit hints). The perf sample separates **editor-authoring cost** from frame/sim cost — `raycastMs` (viewport picks), `rebuildMs` (preview-mesh rebuilds), `authoringMs` (their sum) — so "the editor feels laggy" resolves to a number. Sculpt/paint rebuilds only the stroke's **dirty region**, not the whole mesh. Never guess at lag — pull the report.
-
-## Game opt-in (optional, thin)
-
-```ts
-// Games/<id>/src/index.tsx — also export editorCatalogs for Data-panel tuning
-export { game } from "./game.config";
-export { editorLayers } from "./editorLayers";
-```
-
-`editorLayers` → doc. Optional `editorCatalogs` seeds `document.catalogs` (`list|get|set_catalog_entry`; `findEditorCatalogEntry`).
-
-## Author the scene, don't hardcode it — render it at runtime
+Repeat `--rpc` to batch several mutations on one session; `--save` then writes the document back to `Games/<id>/src/editor.scene.json` in the same format as the GUI's Ctrl+S, and a failed RPC aborts the batch before anything is saved.
 
-Scene content (paths, foliage, terrain, gameplay spots) belongs in the **editor document**, not in
-bespoke render code with hardcoded coordinates. Author it in the 3D editor, save `editor.scene.json`,
-and render it generically at runtime with **`<AuthoredScene document={doc} field={ctx.world.ground} placeObjects />`**
-from `@jgengine/shell/scene` — draped paths, foliage (`resolveScatter`), studios/generators, and catalog props
-(`resolveAuthoredObjects` → object store / `objectModels`). Or onInit: `placeAuthoredObjects(ctx.scene.object,
-resolveAuthoredObjects(doc), heightAt)` / `placeAuthoredObjectsFromDocument` / `markerCatalogId`.
-`<AuthoredPaths>` / `<AuthoredObjects document field />` for one slice. Terrain: `environment({ sculpt })`.
-Never hand-roll path meshes or `markers.filter(meta.catalogId)` place loops.
+## Canonical workflow
 
-This rule is **gated**: `bun run check-content-gate` (wired into `check-types`) fails a game that hard-codes
-world geometry instead of rendering an editor document, and flags source files dense with hand-placed
-coordinate literals. Two shrinking baselines (`scripts/content-gate-baseline.json`,
-`scripts/coordinate-literal-baseline.json`) list today's offenders so `main` stays green; they may only
-lose entries. After migrating a game to `<AuthoredScene>`, reseed with `bun run check-content-gate --update`
-and commit the trimmed baselines. Legitimately procedural / geometry-free games live in the `EXEMPT` map in
-`scripts/check-content-gate.ts`. The end-to-end editor→`<AuthoredScene>` path this depends on is proven
-browserless by `scripts/editor-mvp.test.ts`.
-
-## The F2 chord family — three modes, all agent-usable headless
-
-- **F2+D — debug mode**: engine devtools overlay (Perf/Tune/Logs/Net/Keys/Col). A plain F2 tap does nothing; F2 is only the chord holder.
-- **F2+C — canvas mode**: HUD layout (`document.ui.panels`) — drag/resize; TSX props fallback-only.
-- **F2+E — editor mode**: this scene editor.
-
-Agents never need a user-launched server: `bun run drive` boots the dev server **and** headless Chromium itself, and every `GamePlayerShell` page installs `window.__jgengineAgent` — one RPC surface covering all three modes (`--rpc` prefers it, falls back to the raw editor host). Unknown verbs delegate to the live editor host, so all editor verbs below work through it too.
-
-```
-bun run drive <id> --rpc '{"method":"agent_status"}'                    # which modes are live
-bun run drive <id> --rpc '{"method":"debug_snapshot"}'                  # lean perf/logs/tunables report
-bun run drive <id> --rpc '{"method":"debug_report"}'                    # full devtools snapshot
-bun run drive <id> --rpc '{"method":"canvas_state"}'                    # HUD panels + placements
-bun run drive <id> --rpc '{"method":"canvas_move_panel","id":"minimap","anchor":"top-right"}' --shot hud
-bun run drive <id> --rpc '{"method":"editor_summon"}' --wait 2000 --rpc '{"method":"scene_summary"}'
-bun run drive <id> --mode editor --rpc '{"method":"set_transform","id":"boss","x":-90,"z":-650}' --rpc '{"method":"export_document"}'
-```
-
-Canvas verbs: `canvas_state`, `canvas_set_editing`, `canvas_move_panel`, `canvas_resize_panel`, `canvas_list_panel_types`, `canvas_reset`. Debug: `debug_open`, `debug_snapshot`, `debug_report`. Editor extras: `save_scene` → `editor.scene.json`. Menu-gated: `--click`/`--key` first. Pure document edits: headless CLI below.
-
-## Agent RPC (same verbs as UI)
-
-**Agent panel** (toolbar): shared GUI/RPC undo — `packAgentContext` / `routeToolCall` / `runAgentTurn` / `undoAgentPatch`; `JGENGINE_EDITOR_AGENT_URL` + `JGENGINE_EDITOR_AGENT_KEY` (see `reference.md`).
-
-Browser console / injected host:
-
-```js
-window.__jgengineEditorHost.handle({ method: "scene_summary" })
-window.__jgengineEditorHost.handle({ method: "camera_goto", id: "boss_warrior" })
-window.__jgengineEditorHost.handle({ method: "set_transform", id: "boss_warrior", x: -90, z: -650 })
-window.__jgengineEditorHost.handle({ method: "export_document" })
-```
-
-Headless (live editor + screenshots, or document-only CLI):
-
-```
-bun run drive the-robots --mode editor --wait 3000 --rpc '{"method":"editor_status"}' --shot check
-bun run drive the-robots --mode editor --rpc '{"method":"set_mode","mode":"play"}' --wait 2000 --shot playing
-bun packages/editor/src/mcp/cli.ts --game the-robots --rpc '{"method":"list_layers"}'
-bun packages/editor/src/mcp/cli.ts --game the-robots --serve   # POST localhost:17373/rpc
-bun packages/editor/src/mcp/cli.ts --game the-robots --stdio   # MCP JSON-RPC on stdin/stdout
-```
-
-The CLI/HTTP bridge validates every RPC payload and a game's `editorLayers` export at load time — malformed JSON, unknown `method`, or wrong-shaped document fields get path-specific diagnostics instead of crashing.
-
-Viewport: click anything to select — editor gizmos hit directly, world geometry snaps to the nearest marker/volume/path/note, repeat-click cycles stacked candidates, shift/ctrl-click multi-selects — then TransformControls (W move / E rotate marker / R scale volume: radius, cylinder height, or box half-extents). Multi-selection drags move every selected object. Snap button cycles ground / grid / off (grid also snaps rotation to 15°); `G` toggles the reference grid. Outliner groups by kind (notes included) with ×N dedup rows; `N` cycles instances of the selected row; ctrl-click adds to selection.
-
-Authoring: **+ Add** menu places markers, volumes (sphere/box/cylinder), notes, and draws paths (click points, Enter finish, Esc cancel; shift-click keeps placing). Select a path, click a vertex sphere to move/insert/delete points. `Ctrl+D` duplicates, `Ctrl+C/X/V` copy/cut/paste (system clipboard gets the JSON fragment too), `Ctrl+A` selects all visible, Delete removes, arrows/PgUp/PgDn nudge by grid step (Shift ×5), `F` frames the selection, `?` opens the shortcut sheet. Inspector edits labels, kind, display color, note text, radius/height/half-extents, and coalesces typed edits into single undo steps. **Import** loads an exported JSON back in (success/error toasts); Export downloads, `⧉` copies the JSON. Edits autosave to a per-game localStorage draft — reopening the editor offers Restore/Discard; the header shows an amber ● while the document differs from the game's authored layers. Layer visibility and snap prefs persist per game in localStorage.
-
-## Vegetation volumes — density is one slider
-
-**+ Add → Vegetation (box/circle)** places a fill area; its inspector section has an **item** field (`grass`, or any render-catalog id like a tree/bush model) and a **density /m² slider** (plus exact number, scale range, spacing, reroll seed) with a live `≈ N placements over M m²` readout. Data rides `volume.meta` in the saved scene — no new schema.
-
-Consume in the game (`@jgengine/core/world/vegetation`):
-
-```ts
-import { grassPatchesFromVegetation, resolveVegetation } from "@jgengine/core/world/vegetation";
-
-grass: grassPatchesFromVegetation(sceneDoc),          // item "grass" → shell blade patches, density = blades/m²
-for (const p of resolveVegetation(sceneDoc))          // everything else → deterministic placements
-  ctx.world.object.place(p.item, p.x, 0, p.z, { rotation: p.rotation, visual: { scale: p.scale } });
-```
-
-Same volume, same seed → same field every run; drag the slider, save, done.
-
-## Terrain sculpting — brushes on the live heightfield
-
-Toolbar **Terrain** (or press `T`) enters the sculpt tool. **Create terrain** lays an editable
-heightfield over the scene; brushes then reshape it with live feedback:
-
-- **Raise / Lower** — push ground up or dig it down · **Smooth** — average toward neighbours ·
-  **Flatten** — level to a sampled or numeric height · **Noise** — fractal roughening (seeded, repeatable) ·
-  **Ramp** — drag low→high to grade a straight slope.
-- Live controls: radius, strength, falloff (smooth/linear/none), shape (circle/square), spacing,
-  invert modifier, flatten height, noise seed. A preview ring tracks the cursor.
-- A whole drag commits as **one** undoable stroke (compact vertex delta — the terrain document is
-  never copied per move). `Ctrl+Z` / `Ctrl+Y` undo/redo strokes like any edit; strokes serialize with
-  the scene under `document.terrain`.
-
-The sculpt engine is the reusable `@jgengine/core/world/terraform` seam — build, edit, and consume it
-outside the editor too:
-
-```ts
-import {
-  createTerrainSnapshot,          // fresh flat heightfield over an Aabb
-  editableTerrainFromSnapshot,    // rebuild a live EditableTerrain over the game's ground
-  beginTerraformStroke,           // batch many stamps into one compact TerraformDelta
-  applyDeltaToSnapshot,           // redo a stroke onto a snapshot (copy-on-write)
-  revertDeltaFromSnapshot,        // undo a stroke onto a snapshot (copy-on-write)
-} from "@jgengine/core/world/terraform";
-
-const snapshot = createTerrainSnapshot({ bounds: { minX: -100, minZ: -100, maxX: 100, maxZ: 100 }, cellSize: 2 });
-const terrain = editableTerrainFromSnapshot(snapshot, ctx.world.ground);
-const stroke = beginTerraformStroke(terrain);
-stroke.stamp({ mode: "raise", center: [0, 0], radius: 12, strength: 1 });
-const delta = stroke.delta();                       // one undoable step
-const next = applyDeltaToSnapshot(snapshot, delta); // serializable, back to document.terrain
-```
-
-### Material painting
-
-The terrain tool's **Paint** sub-mode paints material layers (grass/dirt/rock/sand/mud/snow/road/gravel)
-onto the same heightfield — the surface id is stored per cell in `document.terrain.surfaces` and colors the
-mesh. Click/drag paints the selected material; **Alt-click** samples (eyedropper); **Fill all** / **Clear
-paint** blanket the terrain; **Auto rules** paint by slope ("on steep slopes") or height ("on high ground").
-Each stroke/fill is one undoable `paintTerrain` command (compact `SurfaceDelta`). Consume with
-`beginSurfaceStroke`, `fillSurfaceDelta`, `autoPaintDelta`, and `surfaceAt` from `@jgengine/core/world/terraform`.
-
-### Material layer stack + weighted blend
-
-Beyond one dominant surface per cell, terrain carries a reorderable **material layer stack**
-(`document.terrain.layers: TerrainMaterialLayer[]`), each layer a palette `surface` plus render params
-(`roughness`, `tiling`, `triplanar`, `tint`, `opacity`) — carried as data so a runtime game reads them
-straight off the snapshot. Per-cell **weighted blend** lets a cell mix layers (0.6 grass + 0.4 dirt);
-weights live in `document.terrain.weights` (flat `cols*rows*layers.length`, **lazy** — absent until a blend
-is painted, so single-layer terrains stay compact). Pre-2.0 documents auto-upgrade via
-`migrateTerrainSnapshot` (derives layers from painted surfaces). Undo is compact: `setTerrainLayers`
-(snapshot) and `blendTerrain` (`WeightDelta`). Consume with `setLayers`, `blendPaintDelta`,
-`beginBlendStroke`, `weightsAt`, and `migrateTerrainSnapshot` from `@jgengine/core/world/terraform`.
-
-```ts
-import { editableTerrainFromSnapshot, beginBlendStroke } from "@jgengine/core/world/terraform";
-session.dispatch({ type: "setTerrainLayers", layers: [{ id: "grass", surface: "grass", roughness: 0.9 }, { id: "dirt", surface: "dirt" }] });
-const live = editableTerrainFromSnapshot(session.getState().document.terrain);
-const stroke = beginBlendStroke(live);
-stroke.stamp({ mode: "paint", center: [0, 0], radius: 8, surface: "dirt", strength: 1 });
-session.dispatch({ type: "blendTerrain", delta: stroke.delta() });   // one undoable weighted-blend step
-```
-
-### Runtime consumption — the sculpt seam
-
-An authored heightfield drives a game's live ground through `environment({ sculpt })`: pass the
-`document.terrain` snapshot and its offsets layer over the base terrain in `resolveEnvironmentField`, so
-**both the rendered mesh and player collision** reflect the sculpt through the one field every consumer
-already reads (see `Games/tower-guard`). `sculptedField(base, snapshot)` composes them directly.
-
-## Foliage / scatter regions
-
-**+ Add → Foliage region (lasso)** draws a closed polygon on the terrain (click points, Enter to finish) —
-a scatter path of `kind: "scatter"`. Its inspector drives deterministic, **GPU-instanced** scatter that
-previews live in the viewport as you drag: **density /m²**, spacing, a weighted **species palette**
-(add/remove rows of item id + weight), scale range, **max slope** and **height** masks, **edge fade**
-(feather the border), align-to-slope, and a seed with a reroll button. Same seed → same field. Rules ride
-`path.meta`. **Clearance zones** keep foliage off gameplay — don't hand-carve the polygon around
-spawns/plots/paths. Tag any marker/volume with a **clearance** (m) in its inspector (spawns/objectives
-auto-clear by kind); `resolveScatter` repels foliage from every clearance zone in the document, and the
-region's **auto-avoid gameplay spots** toggle turns it off per region (manual `avoid` discs only). The
-matching terrain half: `environment({ clearings: clearanceZonesFrom(doc) })` flattens the ground under
-those same spots (a level pad even under a mound), so one clearance zone clears foliage *and* levels terrain
-(`Games/tower-guard` scatters one arena-wide region and lets the path + plots carve themselves out).
-Consume in a game with `resolveScatter(doc, terrain, options?)` from `@jgengine/core/world/scatterRegion`
-(`clearanceZonesFrom`, `ClearanceOptions` scope which kinds/ids clear),
-then render the instances with `<InstancedScatter instances={…} />` from `@jgengine/shell/scatter` — real
-per-species proxy models (trunked trees, stacked pines, round bushes, faceted rocks, grass tufts) grouped
-into per-chunk GPU-instanced draws that frustum-cull independently (`chunkScatterInstances`). The same
-renderer powers the editor preview. **Convert to objects**: `convertScatterToObjects` (RPC `convert_scatter`)
-detaches a region into individually-editable placed prop markers.
-
-Headless: `create_terrain`, `sculpt_terrain {mode,x,z,radius,strength,…}`, `paint_terrain {surface,x,z,radius}`,
-`fill_terrain {surface}`, `auto_paint {surface,minSlope,minHeight,…}`, `terrain_materials`, `terrain_layers`,
-`set_terrain_layers {layers}`, `blend_terrain {surface,x,z,radius?}`, `terrain_summary`,
-`add_foliage {points,density,item}`, `convert_scatter {pathId}`, and `scatter_summary` RPC verbs drive and
-assert terrain + foliage authoring without WebGL (`bun packages/editor/src/mcp/cli.ts`).
-
-## Prefabs — reusable object stamps
-
-**Prefabs** tab (left aside) makes reuse across a scene, or across games, a first-class op:
-select objects, name them, **Make prefab** extracts them into a serializable fragment centered
-on its own bounds centroid (so it drops in consistently anywhere). **Insert** stamps a fresh,
-freshly-id'd instance at the camera focus point, tagging every inserted object's
-`meta.prefabId`/`meta.prefabInstanceId`. **Detach** breaks the link (content stays, tags clear)
-without touching anything else. Prefabs live in `document.prefabs` — export/import the document,
-or lift just that array, to reuse a prefab library in another game.
-
-```ts
-import { createPrefabFragment, findEditorPrefab } from "@jgengine/core/editor/index";
-
-session.dispatch({ type: "createPrefab", id: "camp", name: "Camp", ids: ["tent", "fire"] });
-session.dispatch({ type: "insertPrefab", prefabId: "camp", at: { x: 100, y: 0, z: 0 } });
-session.dispatch({ type: "detachPrefabInstance", instanceId }); // breaks the link, keeps content
-session.dispatch({ type: "deletePrefab", prefabId: "camp" });   // library entry only; placed instances unaffected
-```
-
-Headless: `create_prefab {id,name,ids}`, `insert_prefab {prefabId,x?,y?,z?}` (defaults to camera
-focus), `detach_prefab_instance {instanceId}`, `delete_prefab {prefabId}`, `list_prefabs`.
-
-## Collections — named selection sets and locked production groups
-
-**Sets** tab bookmarks the current selection under a name for later restore/add-to/remove-from —
-and doubles as a production group with **lock** (blocks `translate`/`setTransform`/`remove`/
-`removeMany` on its members — moving or deleting a locked group is refused at the session level,
-not just the UI), **color**, and **visible** flags. Collections live in `document.collections` and
-survive export/import; removing a member object prunes it from every collection automatically.
-
-```ts
-import { findEditorCollection, isEditorObjectLocked } from "@jgengine/core/editor/index";
-
-session.dispatch({ type: "createCollection", id: "pack", name: "Wolf pack", memberIds: ["a", "b"] });
-session.dispatch({ type: "setCollectionFlags", id: "pack", patch: { locked: true, color: "#f59e0b" } });
-session.dispatch({ type: "selectCollection", id: "pack" }); // restores the selection
-```
-
-Headless: `list_collections`, `create_collection {id,name,memberIds?}`, `rename_collection`,
-`delete_collection`, `set_collection_members`, `add_to_collection`, `remove_from_collection`,
-`set_collection_flags {id,color?,locked?,visible?}`, `select_collection {id}`.
-
-## Batch property edit and drag-drop material assignment
-
-Multi-select then dispatch `batchSetProperties` to patch color/label/meta across every kind in
-one undo step — the primitive behind "replace selected, edit once":
-
-```ts
-session.dispatch({ type: "batchSetProperties", ids: selection, patch: { color: "#0ff", meta: { tier: 2 } } });
-```
-
-The asset browser's **Materials** palette (top of the Assets panel) is drag-source-only chips —
-drop one onto an outliner row to `assignMaterial` (stamps `meta.materialId`) that object, or drop
-it in the viewport: hits a tagged object → assigns; hits bare terrain → paints that material at
-the drop point (same undoable stroke as the Paint tool). Headless: `batch_set_properties
-{ids,color?,label?,meta?}`, `assign_material {ids,materialId}`.
-
-## Scene hierarchy — parent / child
-
-The outliner has a **By kind** and a **Hierarchy** view (nested tree, expand/collapse). Any object can be
-**parented** under another via the inspector's *parent* dropdown (or the `set_parent` RPC) — moving or
-translating a parent carries its whole subtree by the same delta, and cycles are refused. Parenting rides
-`parentId` on the object itself, so it serializes, undoes, and translates through the existing commands.
-Helpers in `@jgengine/core/editor/index`: `editorRoots`, `editorChildren`, `editorParentOf`,
-`collectDescendants`, `wouldCreateCycle`. Headless: `set_parent {ids, parentId}` and `hierarchy`.
-
-## Responsiveness — selector subscriptions + virtualization
-
-The editor stays smooth on large scenes via two seams (`@jgengine/editor`):
-- `useStoreSelector(store, selector, isEqual?)` subscribes a component to a **slice** of the session/UI
-  store through `useSyncExternalStore`, so it rerenders only when that slice changes — UI-only churn
-  (gizmo mode, snapping, active tool) no longer rerenders the outliner/inspector. `shallowArrayEqual`
-  is the selection-list comparator. Adopters: `OutlinerPanel`, `PrefabsPanel`, `CollectionsPanel`,
-  and `EditorChrome`'s `InspectorPanel`.
-- `virtualWindow(scrollTop, viewportHeight, rowHeight, rowCount, overscan?)` is the pure windowing math
-  behind the outliner's fixed-height virtual list — a scene with thousands of objects only mounts the
-  visible handful of rows. The status bar shows live object + foliage-instance counts next to the fps pill.
-
-## Parametric studios — the editor is an extension seam
-
-The editor is not a fixed tool: **anyone can register a new "studio"** (a parametric asset with a
-slider inspector) with one call and **zero engine edits**. Two seams, one inspector generator.
-
-**Scene kind** — geometry authored as a path / volume / marker. `registerSceneKind` (`@jgengine/core/scene/sceneKinds`) supplies a `schema`, an optional pure `resolve`, and `+ Add` metadata; the editor **auto-generates the whole slider inspector** from the schema (`range | number | bool | select | color | text | seed | weightedList`) — no per-kind JSX. Pair it with `registerSceneKindRenderer` (`@jgengine/shell/scene/sceneKindRenderers`) and `AuthoredScene` renders it. Built-in kinds: `scatter`, `water`, `grass_field`. Generic primitives to compose (never re-roll): `placeAlongPath` (`world/pathInstances`), `sagCurve`/`catenaryCurve` (`world/catenary`), `readNamedSockets` (`scene/modelSockets`).
-
-**Generator asset** — a slider-driven prop placed as a marker. `registerAssetGenerator` (`@jgengine/core/scene/assetGenerator`) turns `(params, seed) → parts`; a placed instance stores only `{ assetId, params, seed }` and `resolveGeneratorAsset` re-resolves it at runtime (never baked). Built-in: `building`. The inspector shows the generator's schema on any marker whose `meta.assetId` names one. Declare the generator's front via `GeneratedAsset.forward` (default +Z, `DEFAULT_FORWARD` in `@jgengine/core/scene/facing`) so a product-shot stage or placement tool can auto-orient it — see `jgengine-ui` → "Cinematic studio shots" (`StudioStage`'s `faceCamera`).
-
-Full copyable walkthrough (pole-line + bookcase, zero engine edits): **`examples/studios/README.md`**; enforced by `scripts/studioSeam.test.ts`.
-
-### Drive studio sliders headlessly (agents)
-
-Parametric params live in `meta`; patch via `set_meta` / `set_path` / `set_marker` / `set_note` (merge + schema validate). Catalogs: same SchemaInspector + coalesce via `list|get|set_catalog_entry`:
-
-```
-bun run drive <id> --mode editor --rpc '{"method":"set_meta","id":"grove","patch":{"density":0.6,"seed":"r2"}}'
-bun packages/editor/src/mcp/cli.ts --game tower-guard --rpc '{"method":"set_catalog_entry","catalogId":"towers","entryId":"tower_archer","patch":{"damage":12}}'
-```
+1. Inspect the current scene and available editor capabilities.
+2. Make authoring changes through the GUI or the headless fast path above; do not hand-edit the JSON.
+3. Save the scene document (`--save` headless, Ctrl+S in the GUI) and verify the intended objects/layers are present.
+4. Make gameplay reference stable authored ids, path kinds, markers, or zones rather than copying coordinates (player spawns read the document's `player_spawn` marker via `authoredSpawnPosition` from `@jgengine/core/world/authoredSpawn`).
+5. Render through shared authored-scene primitives and verify with `jgengine-verify`.
 
-## Core APIs (`editor/`)
+Scaffolded games start editor-wired: `npx jgengine create` (also what `bun run new:game` runs in-repo) uses one template that ships `src/editor.scene.json` + `editorLayers.ts`, passes the document to play mode and F2+E through `defineGame({ editorLayers })` (auto-mounted `AuthoredScene`), and spawns at the authored marker — extend the shipped document instead of re-wiring or hardcoding. To promote a scene authored in the standalone editor (`npx jgengine editor`) into a runnable game, `npx jgengine create "<Name>" --from-scene <folder>` bakes that folder's `editor.scene.json` in as the new game's scene (adding a `player_spawn` at the origin only if the authored scene lacks one), so the built game walks the scene that was just authored. Once promoted, an editor asset import (drop a `.glb`/`.gltf`) no longer scans a model folder: the host detects the typed `src/game/assets.ts` catalog, copies the bytes into the game's `public/<basePath>/imported/`, and rewrites `assets.ts` to add a durable `extras` entry (`buildCatalog({ extras })`), so the shipped game resolves the imported id through its own catalog. The rewrite is idempotent — re-importing the same id collapses to one entry — and falls back to the folder-scan import if `assets.ts` can't be safely rewritten.
 
-- `@jgengine/core/editor/index` — document, session, commands, undo
-- `@jgengine/core/editor/types` — markers, volumes, paths
-- `@jgengine/core/editor/document` — normalize/merge/export
-- `@jgengine/core/editor/commands` — `createEditorSession`
-- `@jgengine/editor` — `EditorApp`, host RPC, bridge server, agent panel (dev-only package)
+Use `capabilities.md` to discover editor/runtime imports and `api.md` for signatures. Open [reference.md](reference.md) for RPC/CLI operations, embedded-agent behavior, scene schema details, and troubleshooting.
 
-## Do not
+## Traps
 
-- Statically import `@jgengine/editor` from `GameHost` or game entry code — summon it only as a lazy chunk (`await import("@jgengine/editor")`)
-- Treat mesh modeling as in-scope (placement/world tools only)
+- Selection and camera state are not authored world data. Terrain-readability guides (contours, surface-draped grid, elevation HUD) are editor visualization built from the live heightfield via headless `@jgengine/core/world/terrainGuides`; their toggles persist as editor prefs, never scene content.
+- Runtime-generated decoration does not become editor-owned merely because it is visual; decide ownership explicitly.
+- Asset-facing, units, pivot, footprint, and placement policy belong in asset/catalog metadata, not corrective game transforms.
+- Paths and markers should drive both rendering and gameplay from the same document.
+- Visual presence summaries prove content exists; only an inspected shot proves composition and finish.