@jgengine/editor 0.10.0

package/skills/jgengine/reference-systems.md

@@ -0,0 +1,60 @@
+# Composable systems (`defineSystem`)
+
+Single public authoring path: `defineGame({ systems, loop?, … })` from `@jgengine/shell/defineGame` (or core). Systems are meaningful capabilities — not micro-ticks.
+
+## API
+
+```ts
+import { defineSystem } from "@jgengine/core/game/defineSystem";
+import { compileSystemSchedule, DEFAULT_FIXED_STAGES, DEFAULT_FRAME_STAGES } from "@jgengine/core/game/systemSchedule";
+import { composeGameLoop, installSystems } from "@jgengine/core/game/systemRuntime";
+
+export const combat = defineSystem({
+  id: "combat",
+  feature: "quest", // optional — enables ctx.game.quest without features: { quest: true }
+  dependsOn: ["movement"], // optional — must also be in systems[]
+  tick: {
+    type: "fixed", // | "frame" | "interval" | "manual"
+    rate: 60,      // fixed only (Hz); default 60
+    every: 1,      // interval only (game-seconds)
+    stage: "combat",
+    after: "movement", // optional local order within the stage
+    before: "cleanup",
+  },
+  create(ctx) {},
+  start(ctx) {},
+  update(ctx, dt) {},
+  events: {
+    "entity.died"(ctx, event) {},
+  },
+  save: { key: "combat", snapshot: () => state, hydrate: (data) => { state = data; } },
+  replicate: (ctx) => ({ key: "combat-pub", snapshot: () => pub, hydrate: (d) => { pub = d; } }),
+  reset(ctx) {},
+  dispose(ctx) {},
+});
+```
+
+`defineGame` OR-merges `feature` flags, then `composeGameLoop(systems, loop)` so systems install on `onInit` and tick before residual `loop.onTick`. Classic games migrate by moving fan-out out of `onTick` into systems while keeping boot in `loop`.
+
+## Timing channels
+
+| `tick.type` | When it runs |
+|-------------|--------------|
+| `fixed` | Accumulator at `rate` Hz (default 60); multi-subscribe OK |
+| `frame` | Once per `onTick` with the frame's game `dt` |
+| `interval` | Every `every` game-seconds (own accumulator per system) |
+| `manual` | Installed only; call `systemsOf(ctx)?.runManual(ctx, id)` |
+| *(omit)* | Event-only — handlers in `events` |
+
+Multiple systems may share a channel. Order is stage tables + optional `before`/`after` — **never import order**. `compileSystemSchedule` validates unique ids, `dependsOn`, and cycles.
+
+Default stages: fixed `input → movement → combat → ai → activities → cleanup`; frame includes those plus `animation → camera → effects`.
+
+## Cartridge path
+
+Cartridge remains a convenience wrapper. Express the same shape as ordinary systems (`runFlow`, wave director, combat) under `defineGame({ systems })` when you outgrow the cartridge schema — one authoring model, no rewrite cliff.
+
+## Ownership
+
+- **Save / replicate** — system modules register via `ctx.game.registerSave` / `registerReplicate` at install.
+- **Reset / dispose** — `loop.onReset` / `loop.onDispose` (composed) run system hooks.

package/skills/jgengine-editor/SKILL.md

@@ -0,0 +1,382 @@
+---
+name: jgengine-editor
+description: Open the scene editor to place spawns, zones, and ranges visually.
+---
+
+# JGengine Editor
+
+## When to use
+
+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.
+
+## Open (human / agent browser)
+
+```
+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>]
+```
+
+`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):
+
+```tsx
+import { StandaloneEditor, createBlankPlayable, blankWorld, downloadSaver } from "@jgengine/editor";
+
+// Turn-key: blank world, built-in pickers, Save → dev-server endpoint or a browser download.
+<StandaloneEditor sceneId="my-scene" save={downloadSaver("scene.json")} />;
+
+// Or build the gameless host yourself and mount EditorApp over it:
+const playable = createBlankPlayable({ assets: [{ id: "tree", url: "/models/tree.glb" }], world: blankWorld("seed") });
+```
+
+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
+
+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.
+
+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}}'
+```
+
+## Core APIs (`editor/`)
+
+- `@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)
+
+## Do not
+
+- 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)