@jgengine/editor 0.10.0 → 0.11.0

package/skills/jgengine/api.md

@@ -6,32 +6,50 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.10.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.11.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
 - `ActionCodesMap` (type): type ActionCodesMap<TAction extends string = string, TCode extends string = string> = Record< TAction, ActionCodes<TCode> > — Maps each game action name to the input codes (hold/toggle keys, repeat rate) that trigger it.
+- `AuthoredProvenance` (interface): interface AuthoredProvenance — A first-class entry in the scene document — the editor fully owns and persists it.
 - `Drop` (interface): interface Drop — A resolved loot outcome — one item or currency grant with its rolled count.
 - `GameDefinition` (interface): interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> — Fully-resolved game description produced by {@link defineGame} — assets, scene, and opted-in subsystems.
 - `GameDefinitionConfig` (type): type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene" | "assets"> & { assets?: AssetCatalog<TAssetRef>; } — Input to {@link defineGame} — a `GameDefinition` with `scene` derived and `assets` optional.
 - `GameLoop` (interface): interface GameLoop<TContext = unknown> — Lifecycle hooks a game implements to drive init, per-tick simulation, and player join/leave.
 - `GameServerConfig` (type): type GameServerConfig = "persistent" | { mode: string; [key: string]: unknown } — Hosting mode for a game's multiplayer server: `"persistent"`, or a custom mode with its own options.
+- `GeneratedProvenance` (interface): interface GeneratedProvenance — An object derived from an authored document object — instances scattered from a painted layer, walls extruded from an authored footprint. Edits belong on the source object, not the generated instance.
 - `InventoryDeclaration` (interface): interface InventoryDeclaration — Shape of one named inventory a game declares — slot count, accepted item types, HUD binding.
 - `LootEntry` (interface): interface LootEntry — One possible drop in a {@link LootTableDef} — an item, currency, or generated item, its count range, and its odds.
 - `LootTableDef` (interface): interface LootTableDef — A named, validated loot table — its roll count, weighted-vs-independent mode, and candidate entries.
+- `OwnershipDecision` (type): type OwnershipDecision = "expose" | "bake" | "reject" — The boundary's resolution for one object.
+- `OwnershipDiagnostic` (interface): interface OwnershipDiagnostic — One boundary problem found while auditing a set of declarations.
+- `OwnershipVerdict` (interface): interface OwnershipVerdict — The full verdict for one object: its decision plus the flags and diagnostic the editor needs to act on it.
 - `PhysicsConfig` (interface): interface PhysicsConfig — World gravity and jump tuning, plus scene-object collision opt-ins, for the game's physics step.
+- `ProviderCapabilities` (interface): interface ProviderCapabilities — What a provider lets the editor do with one of its objects. Absent flags default to `false`.
+- `RuntimeProvenance` (interface): interface RuntimeProvenance — An object owned entirely by runtime or procedural code with no document entry. Not authorable unless its provider can bake it into schema-valid authored data.
+- `SCENE_OWNERSHIP_MANIFEST_VERSION` (const): const SCENE_OWNERSHIP_MANIFEST_VERSION: 1 — Current {@link SceneOwnershipManifest} schema version.
+- `SceneOwnershipDeclaration` (interface): interface SceneOwnershipDeclaration — A provider's explicit ownership declaration for one editor-visible object.
+- `SceneOwnershipManifest` (interface): interface SceneOwnershipManifest — Serializable record of a world's ownership declarations — persisted next to the scene document or shipped by a game.
+- `SceneProvenance` (type): type SceneProvenance = | AuthoredProvenance | GeneratedProvenance | RuntimeProvenance | TransientProvenance — The provenance of one editor-visible object — authored, generated, runtime, or transient.
+- `SceneProvenanceKind` (type): type SceneProvenanceKind = "authored" | "generated" | "runtime" | "transient" — Scene ownership boundary — gives every editor-visible object an explicit provenance and a single verdict (expose / bake / reject) so the editor never presents unauthored content as broken authored content.
 - `SpawnPointDistanceBias` (type): type SpawnPointDistanceBias = "near" | "far" | "none" — Preference for picking a spawn point relative to `avoid` positions: closer, farther, or unweighted.
 - `SpawnPointSelectionOptions` (interface): interface SpawnPointSelectionOptions — Semantic options for selecting a spawn point without exposing weighting internals.
+- `TransientProvenance` (interface): interface TransientProvenance — An ephemeral simulation object — a spawned agent, projectile, or particle that never persists.
 - `WorldFeature` (type): type WorldFeature = | ({ kind: "biomes" } & BiomesWorldConfig) | ({ kind: "voxel" } & VoxelWorldConfig) | ({ kind: "plots" } & PlotsWorldConfig) | ({ kind: "tilemap" } & TilemapWorldConfig) | EnvironmentWorldFeature | { kind: "flat" } — A declared world shape — biomes, voxel grid, plots, tilemap, environment, or flat — passed to `defineGame`.
+- `auditManifest` (function): function auditManifest(manifest: SceneOwnershipManifest): OwnershipDiagnostic[] — Audit every declaration in a manifest, keying diagnostics by each object's provenance id. An empty result means the manifest declares all of its content cleanly — every object is authored, generated, bakeable, or a reasoned runtime/transient object.
 - `biomes` (function): function biomes(config: BiomesWorldConfig): WorldFeature — Declares a biome-painted world — the whole-world alternative to a single `environment()` terrain.
 - `building` (function): function building(config: BuildingEnvironmentConfig = {}): BuildingEnvironmentDescriptor — Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style.
+- `classifyOwnership` (function): function classifyOwnership(declaration: SceneOwnershipDeclaration): OwnershipVerdict — Resolve one declaration into a single boundary verdict.
+- `collectOwnershipDiagnostics` (function): function collectOwnershipDiagnostics(entries: Iterable<readonly [string, SceneOwnershipDeclaration]>): OwnershipDiagnostic[] — Audit a keyed set of declarations and return one diagnostic per object that breaks the boundary contract (a `reject` verdict carrying a `violation`). Deterministic: diagnostics come back in the iteration order of `entries`.
 - `contextVerb` (function): function contextVerb(label: string, command: string, args?: Record<string, unknown>): ContextVerb — Builds a {@link ContextVerb} for a right-click menu entry.
 - `defineGame` (function): function defineGame<TAssetRef extends ModelAssetRef, TMultiplayer>(config: GameDefinitionConfig<TAssetRef, TMultiplayer>): GameDefinition<TAssetRef, TMultiplayer> — Task-first entry point for authoring a game: fills in `scene` and default `assets`, validates `name`, OR-merges `features` from installed systems, and composes `loop` from `systems` + any classic hooks.
 - `environment` (function): function environment(config: EnvironmentWorldConfig = {}): EnvironmentWorldFeature — Composes an `environment()` world feature from terrain, sky, weather, vegetation, water, structures, roads, and pads.
 - `flat` (function): function flat(): WorldFeature — Declares an empty flat world — the minimal `WorldFeature` for games with no terrain of their own.
 - `grass` (function): function grass(config: GrassEnvironmentConfig = {}): GrassEnvironmentDescriptor — Declares a grass vegetation patch for `environment()` — area, blade sizing, density, and colors.
+- `isSceneOwnershipManifest` (function): function isSceneOwnershipManifest(value: unknown): value is SceneOwnershipManifest — Narrow unknown parsed JSON to a {@link SceneOwnershipManifest}. Structural only — verifies the version, the declarations array, and each declaration's provenance shape; it does not judge whether declarations satisfy the boundary (use {@link auditManifest} for that).
 - `lootTable` (function): function lootTable(def: LootTableDef): LootTableDef — Validates a loot table definition and returns it unchanged, for use with {@link createLootRegistry}.
 - `ocean` (function): function ocean(config: OceanEnvironmentConfig = {}): OceanEnvironmentDescriptor — Declares an ocean water body for `environment()` — bounds, level, and wave tuning.
+- `ownershipKey` (function): function ownershipKey(provenance: SceneProvenance): string — Stable identity string for a provenance (e.g. `runtime:town/building-3`), suitable for keying an object in an editor tree or a diagnostics table.
 - `plots` (function): function plots(config: PlotsWorldConfig = {}): WorldFeature — Declares a subdivided-plots world — farming, base-building, and other parcel-based layouts.
 - `rain` (function): function rain(config: RainEnvironmentConfig = {}): RainEnvironmentDescriptor — Declares a rainfall weather effect for `environment()` — area, density, speed, wind, and drop width/opacity.
 - `road` (function): function road(config: RoadEnvironmentConfig): RoadEnvironmentDescriptor — Declare a road ribbon for an `environment()` world; the shell drapes and renders it over the terrain.
@@ -136,7 +154,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.10.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.11.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine/capabilities.md

@@ -19,3 +19,11 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 ## runtime-save — save/load the whole game world through a pluggable backend, autosave or save points
 
 - `createRuntimeSave` (function) · `import { createRuntimeSave } from "@jgengine/core/runtime/runtimeSave"`
+
+## scene-ownership — audit a whole ownership manifest for boundary violations
+
+- `auditManifest` (function) · `import { auditManifest } from "@jgengine/core/authoring"`
+- `classifyOwnership` (function) · `import { classifyOwnership } from "@jgengine/core/authoring"`
+- `collectOwnershipDiagnostics` (function) · `import { collectOwnershipDiagnostics } from "@jgengine/core/authoring"`
+- `isSceneOwnershipManifest` (function) · `import { isSceneOwnershipManifest } from "@jgengine/core/authoring"`
+- `ownershipKey` (function) · `import { ownershipKey } from "@jgengine/core/authoring"`

package/skills/jgengine-editor/SKILL.md

@@ -1,382 +1,34 @@
 ---
 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
-```
+## Scene ownership boundary
 
-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`.
+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.
 
-## Standalone games ship the editor too
+## Canonical workflow
 
-`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:
+1. Inspect the current scene and available editor capabilities.
+2. Make authoring changes through the GUI or `bun packages/editor/src/mcp/cli.ts`; do not hand-edit the JSON.
+3. Save the scene document and verify the intended objects/layers are present.
+4. Make gameplay reference stable authored ids, path kinds, markers, or zones rather than copying coordinates.
+5. Render through shared authored-scene primitives and verify with `jgengine-verify`.
 
-```ts
-import { standaloneSavePlugin } from "@jgengine/node/devSavePlugin";
-export default defineConfig({ plugins: [react(), tailwindcss(), standaloneSavePlugin()] });
-```
+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.
 
-Monorepo-shaped hosts use the general form — `devSavePlugin((gameId) => srcDirFor(gameId))` — and `handleSaveRequest` is the transport-free core for a non-Vite dev server.
+## Traps
 
-## 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)
+- 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.