@jgengine/editor 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -12,6 +12,32 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
+## 0.13.0
+
+### Migrate
+
+- **Nothing required** — this release is additive fixes, defaults, and new drop-in primitives. Bump `@jgengine/*` pins to `^0.13.0` (CLI `jgengine` is 0.10.0; `@jgengine/github` unchanged at 0.1.0) and rebuild.
+- Two defaults changed in the player's favor, both overridable: **offline games now persist to localStorage automatically** (#1207) and **rigged catalog assets animate by default** via clip metadata + semantic clip roles (#1209). If a game relied on rigged models staying frozen or on saves being memory-only, opt out explicitly; otherwise you get better behavior for free.
+
+### Added
+
+- **Drop-in inventory grid, window manager, and character sheet** (#1220) — `@jgengine/react` ships `InventoryGrid` (real drag/stack/split), a toggleable-window system (`panels`: bag, character sheet, spellbook-style windows with `@jgengine/core/ui/panelModel` state), and a `CharacterSheet` paperdoll, all HudTheme-skinnable — wire in a line or two instead of re-deriving from raw divs.
+- **Serializable runtime snapshots** (#1179) — capture/restore of live runtime state, including magazine state (`@jgengine/core/combat/magazine`) and stat modifiers, for saves and replication.
+- **Portable weapon plumbing** (#1211) — `@jgengine/core/combat/weaponFire` composes trigger → magazine → spread → projectile/hitscan as data, no game-local glue.
+- **Portable leveling** (#1206) and **portable damage-pool access** (#1208) — progression and damage pools exposed as genre-agnostic seams on the game context.
+- **Named combat VFX presets** (#1204) — `@jgengine/core/combat/vfxPresets`: a visible attack is one line.
+- **Runtime-measured render-bounds hitboxes** (#1227) — colliders wrap what the shell actually mounts, not the raw asset bounds.
+- **Character motion feel** — procedural part motion for rig-less part-composed characters (#1222) plus squash & stretch and death splat (#1229).
+- **City fabric** (#1191) — `streetGenerator` + `cityGenerator`, editor bake verb, street-aware lots, road junctions, grounding, and a web playground.
+- **`jgengine recipe` CLI** (#1214, #1231) — vetted wired compositions, compile-pinned against the SDK, listed and copied from the CLI.
+- **Editor/debug modes mirror to the URL** with a proper editor exit (#1203); game template ships a dependency-free WebGL screenshot script (#1202).
+
+### Changed
+
+- Offline games persist to localStorage by default (#1207); rigged assets animate by default (#1209).
+- RTS camera pan inversion fixed (#1228); sprite raycast warning silenced and duplicate nameplate health bars removed (#1194); scaffolded F2+E editor Tailwind `@source` renders its theme (#1195).
+- Outside-game DX: stat-pool no-op stability, camera-transparent decor, cleaner install/version output, headless UI-intent seam (#1223); new-game briefs direct engine bugs/gaps upstream (#1200).
+
 ## 0.12.0
 
 ### Migrate

package/dist/AssetBrowser.d.ts

@@ -5,7 +5,13 @@ export interface EditorAssetEntry {
     label: string;
     kind: "model" | "catalog" | "marker";
     url?: string;
+    /** Animation clip names from the asset index — present on rigged catalog assets. */
+    clips?: readonly string[];
 }
+/** "idle · walk · run" summary of a rigged asset's detected animation roles for the browser row badge.
+ * @internal
+ */
+export declare function describeClipRoles(clips: readonly string[]): string;
 /** Custom drag mime carrying a material id — read by hierarchy rows and the viewport drop zone. */
 export declare const MATERIAL_DRAG_MIME = "application/x-jgengine-material";
 /**
@@ -26,6 +32,7 @@ export declare function AssetBrowser({ assets, session, onPlace, }: {
 /** Turns a game's asset catalog ids into editor asset entries for the browser panel. */
 export declare function assetsFromCatalog(ids: readonly string[], resolve?: (id: string) => {
     url?: string;
+    clips?: readonly string[];
 } | null): EditorAssetEntry[];
 /**
  * Converts a durable/ephemeral standalone import into a Content Browser entry.

package/dist/AssetBrowser.js

@@ -1,6 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useState } from "react";
+import { rolesFromClips } from "@jgengine/core/game/clipRoles";
 import { TERRAIN_MATERIALS } from "./uiStore.js";
+/** "idle · walk · run" summary of a rigged asset's detected animation roles for the browser row badge.
+ * @internal
+ */
+export function describeClipRoles(clips) {
+    const roles = Object.keys(rolesFromClips(clips));
+    return roles.length === 0 ? "no roles detected" : roles.join(" · ");
+}
 /** Custom drag mime carrying a material id — read by hierarchy rows and the viewport drop zone. */
 export const MATERIAL_DRAG_MIME = "application/x-jgengine-material";
 /**
@@ -46,7 +54,7 @@ export function AssetBrowser({ assets, session, onPlace, }) {
             return assets;
         return assets.filter((entry) => entry.id.toLowerCase().includes(needle) || entry.label.toLowerCase().includes(needle));
     }, [assets, query]);
-    return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col gap-1", children: [_jsx(MaterialsPalette, {}), _jsx("input", { type: "search", placeholder: "Search assets\u2026", value: query, onChange: (event) => setQuery(event.target.value), className: "rounded-md border border-white/10 bg-black/40 px-2.5 py-1.5 text-neutral-100 outline-none transition-colors placeholder:text-neutral-600 focus:border-cyan-400/60 focus:bg-black/60" }), _jsxs("div", { className: "min-h-0 flex-1 space-y-0.5 overflow-auto pr-1", children: [filtered.map((entry) => (_jsxs("div", { className: "group flex items-center gap-2 rounded-md px-1.5 py-1 transition-colors hover:bg-white/[0.06]", children: [_jsxs("div", { className: "min-w-0 flex-1 truncate", children: [_jsx("div", { className: "truncate text-neutral-100", children: entry.label }), _jsxs("div", { className: "truncate text-[10px] text-neutral-500", children: [entry.kind, " \u00B7 ", entry.id] })] }), _jsx("button", { type: "button", className: "shrink-0 rounded-md bg-cyan-500/20 px-2 py-0.5 text-cyan-200 opacity-0 ring-1 ring-inset ring-cyan-400/30 transition-all hover:bg-cyan-500/30 focus-visible:opacity-100 group-hover:opacity-100", onClick: () => onPlace(entry), children: "Place" })] }, entry.id))), filtered.length === 0 ? _jsx("div", { className: "text-neutral-500", children: "No assets match." }) : null] }), _jsx("button", { type: "button", className: "rounded-md bg-white/[0.05] px-2 py-1 text-neutral-300 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/10 hover:text-neutral-100", onClick: () => {
+    return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col gap-1", children: [_jsx(MaterialsPalette, {}), _jsx("input", { type: "search", placeholder: "Search assets\u2026", value: query, onChange: (event) => setQuery(event.target.value), className: "rounded-md border border-white/10 bg-black/40 px-2.5 py-1.5 text-neutral-100 outline-none transition-colors placeholder:text-neutral-600 focus:border-cyan-400/60 focus:bg-black/60" }), _jsxs("div", { className: "min-h-0 flex-1 space-y-0.5 overflow-auto pr-1", children: [filtered.map((entry) => (_jsxs("div", { className: "group flex items-center gap-2 rounded-md px-1.5 py-1 transition-colors hover:bg-white/[0.06]", children: [_jsxs("div", { className: "min-w-0 flex-1 truncate", children: [_jsx("div", { className: "truncate text-neutral-100", children: entry.label }), _jsxs("div", { className: "truncate text-[10px] text-neutral-500", children: [entry.kind, " \u00B7 ", entry.id] }), entry.clips !== undefined && entry.clips.length > 0 ? (_jsxs("div", { className: "truncate text-[10px] text-emerald-400/80", title: `${entry.clips.length} animation clips (auto-animates when placed):\n${entry.clips.join("\n")}`, children: ["\u25B6 ", entry.clips.length, " clips \u00B7 ", describeClipRoles(entry.clips)] })) : null] }), _jsx("button", { type: "button", className: "shrink-0 rounded-md bg-cyan-500/20 px-2 py-0.5 text-cyan-200 opacity-0 ring-1 ring-inset ring-cyan-400/30 transition-all hover:bg-cyan-500/30 focus-visible:opacity-100 group-hover:opacity-100", onClick: () => onPlace(entry), children: "Place" })] }, entry.id))), filtered.length === 0 ? _jsx("div", { className: "text-neutral-500", children: "No assets match." }) : null] }), _jsx("button", { type: "button", className: "rounded-md bg-white/[0.05] px-2 py-1 text-neutral-300 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/10 hover:text-neutral-100", onClick: () => {
                     const id = `marker_${Date.now().toString(36)}`;
                     const focus = null;
                     void focus;
@@ -71,6 +79,7 @@ export function assetsFromCatalog(ids, resolve) {
             label: id,
             kind: "model",
             ...(resolved?.url === undefined ? {} : { url: resolved.url }),
+            ...(resolved?.clips === undefined ? {} : { clips: resolved.clips }),
         };
     });
 }

package/dist/EditorApp.d.ts

@@ -23,6 +23,12 @@ export interface EditorAppProps {
      * session identity and presence rows. Omit when the host has nothing live — the panel stays honest.
      */
     networkPresence?: EditorNetworkPresenceInput;
+    /**
+     * Called to close the editor and return to the game. Passed by `GameHost` when the editor was
+     * summoned over a running game; when set, the chrome shows an "Exit to game" control. Omit for the
+     * standalone editor, which has no game to return to.
+     */
+    onExitEditor?: () => void;
 }
 /** Persists an exported document JSON; resolves with where it landed or why it failed. */
 export type EditorSaveFn = (json: string) => Promise<{
@@ -31,4 +37,4 @@ export type EditorSaveFn = (json: string) => Promise<{
     error?: string;
 }>;
 /** Top-level scene editor: author spawns/zones/paths/notes visually over edit, walk, or play modes. */
-export declare function EditorApp({ gameId, playable, layers, catalogs, save, modeChip, networkPresence }: EditorAppProps): import("react").JSX.Element;
+export declare function EditorApp({ gameId, playable, layers, catalogs, save, modeChip, networkPresence, onExitEditor }: EditorAppProps): import("react").JSX.Element;

package/dist/EditorApp.js

@@ -244,7 +244,7 @@ function resolveEditorCamera(document) {
     };
 }
 /** Top-level scene editor: author spawns/zones/paths/notes visually over edit, walk, or play modes. */
-export function EditorApp({ gameId, playable, layers, catalogs, save, modeChip, networkPresence }) {
+export function EditorApp({ gameId, playable, layers, catalogs, save, modeChip, networkPresence, onExitEditor }) {
     const resolvedModeChip = modeChip === undefined ? EditorModeChip : modeChip;
     const saveFn = useMemo(() => save ?? endpointSaver(gameId), [save, gameId]);
     const networkSnapshot = useMemo(() => buildEditorNetworkSnapshot({
@@ -483,7 +483,7 @@ export function EditorApp({ gameId, playable, layers, catalogs, save, modeChip,
             }
         };
         const GameUI = function EditorUi() {
-            return (_jsx(EditorChrome, { gameId: gameId, session: host.api.getSession(), api: host.api, assets: catalogAssets, ui: ui, baselineDocument: host.baselineDocument, save: saveFn, networkSnapshot: networkSnapshot, onRegisterAsset: registerImportedAsset }));
+            return (_jsx(EditorChrome, { gameId: gameId, session: host.api.getSession(), api: host.api, assets: catalogAssets, ui: ui, baselineDocument: host.baselineDocument, save: saveFn, networkSnapshot: networkSnapshot, onRegisterAsset: registerImportedAsset, onExitEditor: onExitEditor }));
         };
         return {
             ...playable,
@@ -495,7 +495,7 @@ export function EditorApp({ gameId, playable, layers, catalogs, save, modeChip,
             // WorldOverlay above is the editor layers, not PandoraViewmodel.
             camera: inspectionCamera,
         };
-    }, [playable, host, gameId, initialCamera, cameraProjection, catalogAssets, ui, readout, mode, saveFn, resolvedModeChip, networkSnapshot]);
+    }, [playable, host, gameId, initialCamera, cameraProjection, catalogAssets, ui, readout, mode, saveFn, resolvedModeChip, networkSnapshot, onExitEditor]);
     const showElevation = useStoreSelector(ui, (s) => s.showElevation);
     const onPanelCommit = useCallback((id, panel) => {
         host.session.dispatch({ type: "setUiPanel", id, patch: panel });

package/dist/EditorChrome.d.ts

@@ -10,7 +10,7 @@ import type { EditorNetworkSnapshot } from "./networkSnapshot.js";
  * assistant), viewport overlays, and status bar — wired to the session, UI store, layout store,
  * and host RPC. Mounted by `EditorApp`; not a game-author entry point.
  */
-export declare function EditorChrome({ gameId, session, api, assets, ui, baselineDocument, save, networkSnapshot, importAsset, onRegisterAsset, }: {
+export declare function EditorChrome({ gameId, session, api, assets, ui, baselineDocument, save, networkSnapshot, importAsset, onRegisterAsset, onExitEditor, }: {
     gameId: string;
     session: EditorSession;
     api: EditorHostApi;
@@ -23,6 +23,8 @@ export declare function EditorChrome({ gameId, session, api, assets, ui, baselin
         path?: string;
         error?: string;
     }>;
+    /** Closes the editor and returns to the game; set only when summoned over a game. Shows "Exit to game". */
+    onExitEditor?: () => void;
     /**
      * Network workspace inspection payload (adapter config + optional host presence).
      * Built by `EditorApp` from the game definition; live presence rows only when the host injects them.

package/dist/EditorChrome.js

@@ -111,7 +111,7 @@ const LEFT_PAGES = [
  * assistant), viewport overlays, and status bar — wired to the session, UI store, layout store,
  * and host RPC. Mounted by `EditorApp`; not a game-author entry point.
  */
-export function EditorChrome({ gameId, session, api, assets, ui, baselineDocument, save, networkSnapshot, importAsset = importAssetToHost, onRegisterAsset, }) {
+export function EditorChrome({ gameId, session, api, assets, ui, baselineDocument, save, networkSnapshot, importAsset = importAssetToHost, onRegisterAsset, onExitEditor, }) {
     const [, setTick] = useState(0);
     const layoutRef = useRef(null);
     layoutRef.current ??= createShellLayoutStore(gameId);
@@ -169,6 +169,8 @@ export function EditorChrome({ gameId, session, api, assets, ui, baselineDocumen
         return { objects, foliage };
     }, [state.document]);
     useF2Chord("KeyE", () => api.setMode("play"));
+    // F2+Q leaves the editor entirely (back to the game) — only meaningful when summoned over one.
+    useF2Chord("KeyQ", useCallback(() => onExitEditor?.(), [onExitEditor]));
     useEffect(() => session.subscribe(() => setTick((value) => value + 1)), [session]);
     useEffect(() => ui.subscribe(() => setTick((value) => value + 1)), [ui]);
     useEffect(() => layout.subscribe(() => setTick((value) => value + 1)), [layout]);
@@ -672,7 +674,9 @@ export function EditorChrome({ gameId, session, api, assets, ui, baselineDocumen
             ? `Drawing ${placement.kind}: click to add points (${uiState.pathDraft.length}) · Enter finish · Esc cancel`
             : `Placing ${placement.tool === "note" ? "note" : placement.kind}: click the world · Shift-click places more · Esc cancel`;
     const railActive = uiState.tool === "terrain" ? "terrain" : layoutState.workspace;
-    return (_jsxs("div", { className: "pointer-events-none absolute inset-0 z-50 flex flex-col text-xs text-neutral-100", children: [_jsx(TopAppBar, { gameId: gameId, dirty: dirty, saveState: docSave.saveState, lastSavedAt: docSave.lastSavedAt, saveAvailable: docSave.available, saveError: docSave.saveError, canUndo: session.canUndo(), canRedo: session.canRedo(), onUndo: () => session.dispatch({ type: "undo" }), onRedo: () => session.dispatch({ type: "redo" }), onSave: docSave.doSave, onPlay: () => api.setMode("play"), onWalk: () => api.setMode("walk"), onHud: () => api.setMode("hud"), onImport: () => importInputRef.current?.click(), onExport: exportJson, onCopyJson: copyExportJson, onOpenPalette: () => setPaletteQuery(""), onToggleHelp: () => setHelpOpen((value) => !value), onResetLayout: () => layout.reset() }), _jsx("input", { ref: importInputRef, type: "file", accept: "application/json,.json", className: "hidden", onChange: (event) => {
+    // Only advertise the exit chord when there is a game to return to.
+    const shortcuts = onExitEditor !== undefined ? [...SHORTCUTS, { keys: "F2+Q", action: "Exit editor to game" }] : SHORTCUTS;
+    return (_jsxs("div", { className: "pointer-events-none absolute inset-0 z-50 flex flex-col text-xs text-neutral-100", children: [_jsx(TopAppBar, { gameId: gameId, onExitToGame: onExitEditor, dirty: dirty, saveState: docSave.saveState, lastSavedAt: docSave.lastSavedAt, saveAvailable: docSave.available, saveError: docSave.saveError, canUndo: session.canUndo(), canRedo: session.canRedo(), onUndo: () => session.dispatch({ type: "undo" }), onRedo: () => session.dispatch({ type: "redo" }), onSave: docSave.doSave, onPlay: () => api.setMode("play"), onWalk: () => api.setMode("walk"), onHud: () => api.setMode("hud"), onImport: () => importInputRef.current?.click(), onExport: exportJson, onCopyJson: copyExportJson, onOpenPalette: () => setPaletteQuery(""), onToggleHelp: () => setHelpOpen((value) => !value), onResetLayout: () => layout.reset() }), _jsx("input", { ref: importInputRef, type: "file", accept: "application/json,.json", className: "hidden", onChange: (event) => {
                     const file = event.target.files?.[0];
                     if (file !== undefined)
                         importFile(file);
@@ -747,5 +751,5 @@ export function EditorChrome({ gameId, session, api, assets, ui, baselineDocumen
                                         ["profiler", "Profiler"],
                                         ["animation", "Animation"],
                                         ["assistant", "AI Assistant"],
-                                    ].map(([id, label]) => (_jsx("button", { type: "button", onClick: () => openBottomTab(id), className: `rounded-[4px] px-2 py-0.5 text-[10px] text-neutral-500 transition-colors hover:bg-white/[0.05] hover:text-neutral-300 ${FOCUS_RING}`, children: label }, id))), _jsx("span", { className: "ml-auto text-[9px] text-neutral-600", children: "Ctrl+B opens the content browser" })] }))] }), layoutState.rightOpen ? (_jsxs(_Fragment, { children: [_jsx(PanelResizer, { orientation: "vertical", label: "Resize inspector panel", sign: -1, onResize: (delta) => layout.resize("rightWidth", delta) }), _jsx("aside", { className: `pointer-events-auto hidden min-h-0 flex-col overflow-hidden border-l ${BORDER} bg-[#111318] md:flex`, style: { width: layoutState.rightWidth }, "aria-label": "Inspector dock", children: _jsx(InspectorPanel, { session: session, ui: ui, api: api, tab: layoutState.inspectorTab, onSelectTab: (tab) => layout.patch({ inspectorTab: tab }), collapsed: layoutState.collapsed, onToggleSection: (id) => layout.toggleSection(id), onClose: () => layout.patch({ rightOpen: false }) }) })] })) : null] }), _jsx(StatusBar, { api: api, history: perfHistory, objects: sceneStats.objects, foliage: sceneStats.foliage, selectionCount: state.selection.length, autosave: true }), paletteQuery !== null ? (_jsx(CommandPalette, { commands: paletteCommands, initialQuery: paletteQuery, onClose: () => setPaletteQuery(null) })) : null, helpOpen ? (_jsx("div", { className: "pointer-events-auto absolute inset-0 z-[70] flex items-center justify-center bg-black/50 backdrop-blur-[2px]", onClick: () => setHelpOpen(false), children: _jsxs("div", { className: "w-[28rem] max-w-[90vw] rounded-[10px] border border-white/10 bg-[#14171d] p-5 shadow-2xl shadow-black/60", onClick: (event) => event.stopPropagation(), role: "dialog", "aria-label": "Keyboard shortcuts", children: [_jsxs("div", { className: "mb-3 flex items-center", children: [_jsxs("div", { className: "flex items-center gap-2 text-sm font-semibold tracking-wide text-neutral-100", children: [_jsx(Icon, { name: "command", size: 15, className: "text-cyan-300" }), "Keyboard shortcuts"] }), _jsx(IconButton, { icon: "close", label: "Close shortcuts", tone: "ghost", className: "ml-auto", onClick: () => setHelpOpen(false) })] }), _jsx("div", { className: "grid max-h-[60vh] grid-cols-[auto_1fr] items-center gap-x-4 gap-y-1.5 overflow-auto", children: SHORTCUTS.map((entry) => (_jsxs("div", { className: "contents", children: [_jsx("span", { className: "justify-self-start", children: _jsx(Kbd, { children: entry.keys }) }), _jsx("span", { className: "text-neutral-300", children: entry.action })] }, entry.keys))) })] }) })) : null] }));
+                                    ].map(([id, label]) => (_jsx("button", { type: "button", onClick: () => openBottomTab(id), className: `rounded-[4px] px-2 py-0.5 text-[10px] text-neutral-500 transition-colors hover:bg-white/[0.05] hover:text-neutral-300 ${FOCUS_RING}`, children: label }, id))), _jsx("span", { className: "ml-auto text-[9px] text-neutral-600", children: "Ctrl+B opens the content browser" })] }))] }), layoutState.rightOpen ? (_jsxs(_Fragment, { children: [_jsx(PanelResizer, { orientation: "vertical", label: "Resize inspector panel", sign: -1, onResize: (delta) => layout.resize("rightWidth", delta) }), _jsx("aside", { className: `pointer-events-auto hidden min-h-0 flex-col overflow-hidden border-l ${BORDER} bg-[#111318] md:flex`, style: { width: layoutState.rightWidth }, "aria-label": "Inspector dock", children: _jsx(InspectorPanel, { session: session, ui: ui, api: api, tab: layoutState.inspectorTab, onSelectTab: (tab) => layout.patch({ inspectorTab: tab }), collapsed: layoutState.collapsed, onToggleSection: (id) => layout.toggleSection(id), onClose: () => layout.patch({ rightOpen: false }) }) })] })) : null] }), _jsx(StatusBar, { api: api, history: perfHistory, objects: sceneStats.objects, foliage: sceneStats.foliage, selectionCount: state.selection.length, autosave: true }), paletteQuery !== null ? (_jsx(CommandPalette, { commands: paletteCommands, initialQuery: paletteQuery, onClose: () => setPaletteQuery(null) })) : null, helpOpen ? (_jsx("div", { className: "pointer-events-auto absolute inset-0 z-[70] flex items-center justify-center bg-black/50 backdrop-blur-[2px]", onClick: () => setHelpOpen(false), children: _jsxs("div", { className: "w-[28rem] max-w-[90vw] rounded-[10px] border border-white/10 bg-[#14171d] p-5 shadow-2xl shadow-black/60", onClick: (event) => event.stopPropagation(), role: "dialog", "aria-label": "Keyboard shortcuts", children: [_jsxs("div", { className: "mb-3 flex items-center", children: [_jsxs("div", { className: "flex items-center gap-2 text-sm font-semibold tracking-wide text-neutral-100", children: [_jsx(Icon, { name: "command", size: 15, className: "text-cyan-300" }), "Keyboard shortcuts"] }), _jsx(IconButton, { icon: "close", label: "Close shortcuts", tone: "ghost", className: "ml-auto", onClick: () => setHelpOpen(false) })] }), _jsx("div", { className: "grid max-h-[60vh] grid-cols-[auto_1fr] items-center gap-x-4 gap-y-1.5 overflow-auto", children: shortcuts.map((entry) => (_jsxs("div", { className: "contents", children: [_jsx("span", { className: "justify-self-start", children: _jsx(Kbd, { children: entry.keys }) }), _jsx("span", { className: "text-neutral-300", children: entry.action })] }, entry.keys))) })] }) })) : null] }));
 }

package/dist/handlers/index.js

@@ -4,6 +4,7 @@ import { documentHandlers } from "./document.js";
 import { gridHandlers } from "./grids.js";
 import { hierarchyHandlers } from "./hierarchy.js";
 import { minimapHandlers } from "./minimap.js";
+import { streetsHandlers } from "./streets.js";
 import { runtimeHandlers } from "./runtime.js";
 import { terrainHandlers } from "./terrain.js";
 /**
@@ -16,6 +17,7 @@ export const EDITOR_RPC_HANDLERS = {
     ...catalogHandlers,
     ...terrainHandlers,
     ...minimapHandlers,
+    ...streetsHandlers,
     ...hierarchyHandlers,
     ...collectionHandlers,
     ...gridHandlers,

package/dist/handlers/streets.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerTable } from "./context.js";
+/** Document, selection, camera, mode, asset placement, and status verbs. */
+export declare const streetsHandlers: Pick<HandlerTable, "generate_streets">;

package/dist/handlers/streets.js

@@ -0,0 +1,159 @@
+import { generateStreets } from "@jgengine/core/world/streetGenerator";
+/** Fully-defaulted slider preset for an open street net (resolves to `net` in `streetNetworkMode`). */
+const NET_DEFAULTS = {
+    gridness: 0.9,
+    loopiness: 0.2,
+    connectivity: 0.35,
+    branching: 0.3,
+    deadEnds: 0.5,
+    segmentLength: 48,
+    aspect: 1,
+    winding: 0.2,
+    minCurveRadius: 30,
+    minTurnAngle: 0,
+    maxTurnAngle: 120,
+    width: 7,
+    boulevards: 0.3,
+};
+/** Fully-defaulted slider preset for a closed race circuit (resolves to `circuit` in `streetNetworkMode`). */
+const CIRCUIT_DEFAULTS = {
+    gridness: 0.1,
+    loopiness: 1,
+    connectivity: 0,
+    branching: 0,
+    deadEnds: 0,
+    segmentLength: 60,
+    aspect: 1,
+    winding: 0.5,
+    minCurveRadius: 24,
+    minTurnAngle: 0,
+    maxTurnAngle: 70,
+    width: 12,
+    boulevards: 0,
+};
+/** The numeric slider keys a caller may overlay onto the mode preset via `params`. */
+const RULE_KEYS = [
+    "gridness",
+    "loopiness",
+    "connectivity",
+    "branching",
+    "deadEnds",
+    "segmentLength",
+    "aspect",
+    "winding",
+    "minCurveRadius",
+    "minTurnAngle",
+    "maxTurnAngle",
+    "width",
+    "boulevards",
+];
+/** The tag every baked path carries in `meta.generator`, so a re-run can find and replace its own output. */
+const GENERATOR_TAG = "streetGenerator";
+/** Stable id prefix for a seed's baked paths — the idempotency key for replace-on-re-run. */
+function genPrefix(seed) {
+    return `gen-${seed}-`;
+}
+/** True when a path was baked by this generator for `seed` (matches id prefix OR the meta tag). */
+function isGeneratedForSeed(path, seed) {
+    if (path.id.startsWith(genPrefix(seed)))
+        return true;
+    const meta = path.meta;
+    return meta !== undefined && meta.generator === GENERATOR_TAG && meta.seed === seed;
+}
+/** Half-extents (hx, hz) and world origin a volume fills, so the generator grows inside its footprint. */
+function volumeFootprint(volume) {
+    if (volume.shape === "box" && volume.halfExtents !== undefined) {
+        return { hx: Math.max(1, volume.halfExtents.x), hz: Math.max(1, volume.halfExtents.z), origin: volume.center };
+    }
+    // sphere / cylinder (or a box missing halfExtents): a radius is symmetric in x/z.
+    const r = Math.max(1, volume.radius ?? 0);
+    return { hx: r, hz: r, origin: volume.center };
+}
+/** Document, selection, camera, mode, asset placement, and status verbs. */
+export const streetsHandlers = {
+    generate_streets: (ctx, request) => {
+        const doc = ctx.session.getState().document;
+        const seed = request.seed ?? "path";
+        const requestedMode = request.mode === "circuit" ? "circuit" : "net";
+        // Resolve the footprint + world origin from a named volume or from explicit bounds.
+        let hx;
+        let hz;
+        let origin;
+        if (request.volumeId !== undefined) {
+            const volume = doc.volumes.find((v) => v.id === request.volumeId);
+            if (volume === undefined)
+                return { ok: false, error: `volume not found: ${request.volumeId}` };
+            ({ hx, hz, origin } = volumeFootprint(volume));
+        }
+        else {
+            const center = request.center ?? { x: 0, y: 0, z: 0 };
+            if (request.halfX === undefined || request.halfZ === undefined) {
+                return { ok: false, error: "generate_streets requires volumeId, or center + halfX + halfZ" };
+            }
+            hx = Math.max(1, request.halfX);
+            hz = Math.max(1, request.halfZ);
+            origin = center;
+        }
+        // Build rules: mode preset, overlaid with any numeric slider overrides from `params`.
+        const preset = requestedMode === "circuit" ? CIRCUIT_DEFAULTS : NET_DEFAULTS;
+        const rules = { seed, ...preset };
+        const params = request.params;
+        if (params !== undefined) {
+            for (const key of RULE_KEYS) {
+                const value = params[key];
+                if (typeof value === "number" && Number.isFinite(value)) {
+                    rules[key] = value;
+                }
+            }
+        }
+        const network = generateStreets(rules, hx, hz);
+        // The generator resolves the ACTUAL topology from the rules; use it for the default path kind so a
+        // circuit bakes `route`s and a net bakes `road`s even when the caller's sliders cross the boundary.
+        const kind = request.kind ?? (network.mode === "circuit" ? "route" : "road");
+        const baseY = origin.y;
+        const toWorld = (street) => street.points.map(([lx, lz]) => ({ x: origin.x + lx, y: baseY, z: origin.z + lz }));
+        // Through-streets → one path each (a circuit's ring is a single closed loop street: first ≈ last).
+        const newPaths = [];
+        network.streets.forEach((street, index) => {
+            const points = toWorld(street);
+            if (points.length < 2)
+                return;
+            newPaths.push({
+                id: `${genPrefix(seed)}${index}`,
+                kind,
+                points,
+                width: street.width,
+                label: `${kind} ${index}`,
+                meta: {
+                    generator: GENERATOR_TAG,
+                    seed,
+                    mode: network.mode,
+                    level: street.level,
+                    loop: street.loop,
+                },
+            });
+        });
+        // Idempotent replace: drop this seed's prior baked paths, keep everything else, append the fresh set —
+        // all as ONE undoable structural edit via replaceDocument.
+        const kept = doc.paths.filter((p) => !isGeneratedForSeed(p, seed));
+        const nextDoc = { ...doc, paths: [...kept, ...newPaths] };
+        const { applied } = ctx.dispatchGuarded({ type: "replaceDocument", document: nextDoc });
+        if (!applied)
+            return { ok: false, error: "generate_streets: document replace had no effect" };
+        // replaceDocument clears selection; re-select the freshly baked paths for the caller.
+        ctx.session.dispatch({ type: "select", ids: newPaths.map((p) => p.id) });
+        return {
+            ok: true,
+            result: {
+                seed,
+                requestedMode,
+                mode: network.mode,
+                kind,
+                pathCount: newPaths.length,
+                removed: doc.paths.length - kept.length,
+                ids: newPaths.map((p) => p.id),
+                footprint: { hx, hz, origin },
+            },
+        };
+    },
+};

package/dist/mcp/fieldSpec.js

@@ -71,6 +71,7 @@ export const RPC_FIELD_SCHEMAS = {
     set_terrain_layers: [req(oa("layers", [req(s("id")), req(s("surface")), n("roughness"), n("tiling"), b("triplanar"), s("tint"), n("opacity")]))],
     blend_terrain: [req(s("surface")), req(n("x")), req(n("z")), n("radius"), n("strength"), s("shape", SHAPE)],
     convert_scatter: [req(s("pathId"))],
+    generate_streets: [s("volumeId"), v3("center"), n("halfX"), n("halfZ"), s("seed"), s("mode", ["net", "circuit"]), s("kind"), o("params")],
     bake_minimap: [n("padding"), n("resolution"), n("waterLevel")],
     add_foliage: [req(oa("points", [req(n("x")), req(n("z"))])), n("density"), s("item"), s("seed"), n("minSpacing")],
     scatter_summary: [],

package/dist/mcp/tools.js

@@ -64,6 +64,7 @@ const TOOL_DESCRIPTIONS = [
     { name: "set_terrain_layers", description: "Replace the reorderable terrain material layer stack; a params-only edit keeps painted blends." },
     { name: "blend_terrain", description: "Blend-paint a material layer's weight at x/z (weighted multi-layer blend); auto-adds the layer." },
     { name: "convert_scatter", description: "Detach a foliage/scatter region into individually-editable placed prop markers, removing the region." },
+    { name: "generate_streets", description: "Bake the seed-driven street generator into the scene as authorable road/route paths inside a volume (or explicit center+halfX/halfZ). mode net→roads, circuit→closed route; params overlays sliders (gridness/loopiness/connectivity/winding/...). Idempotent: re-running the same seed replaces its own prior output. One undoable edit; round-trips --save." },
     { name: "bake_minimap", description: "Rasterize the authored terrain into a stored minimap PNG on the document (runtime reads it as the Minimap background). Live-editor only — needs the mounted viewport's terrain sampler, not a headless CLI." },
     { name: "add_foliage", description: "Add a foliage/scatter region from a closed polygon (≥3 x/z points) with density and item." },
     { name: "scatter_summary", description: "Count foliage/scatter regions and their total deterministic instance placements." },

package/dist/session.d.ts

@@ -195,6 +195,20 @@ export type EditorBridgeRequest = {
 } | {
     method: "convert_scatter";
     pathId: string;
+} | {
+    method: "generate_streets";
+    volumeId?: string;
+    center?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    halfX?: number;
+    halfZ?: number;
+    seed?: string;
+    mode?: "net" | "circuit";
+    kind?: string;
+    params?: Record<string, unknown>;
 } | {
     method: "bake_minimap";
     padding?: number;

package/dist/shell/TopAppBar.d.ts

@@ -8,8 +8,10 @@ export type TopBarSaveState = "idle" | "saving" | "saved" | "error";
  * edit mode; Play mode mounts {@link PlayModeBar}, which wires the same controls to the
  * runtime pause/step RPCs so mode switches keep shell chrome.
  */
-export declare function TopAppBar({ gameId, dirty, saveState, lastSavedAt, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }: {
+export declare function TopAppBar({ gameId, onExitToGame, dirty, saveState, lastSavedAt, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }: {
     gameId: string;
+    /** When set (editor summoned over a game), renders an "Exit to game" control that closes the editor. */
+    onExitToGame?: () => void;
     dirty: boolean;
     saveState: TopBarSaveState;
     /** Epoch ms of the last successful save this session; omit/null when never saved. */

package/dist/shell/TopAppBar.js

@@ -34,7 +34,7 @@ function SaveStatus({ dirty, saveState, lastSavedAt, }) {
  * edit mode; Play mode mounts {@link PlayModeBar}, which wires the same controls to the
  * runtime pause/step RPCs so mode switches keep shell chrome.
  */
-export function TopAppBar({ gameId, dirty, saveState, lastSavedAt = null, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }) {
+export function TopAppBar({ gameId, onExitToGame, dirty, saveState, lastSavedAt = null, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }) {
     const [menuOpen, setMenuOpen] = useState(false);
     const menuRef = useRef(null);
     useEffect(() => {
@@ -56,7 +56,7 @@ export function TopAppBar({ gameId, dirty, saveState, lastSavedAt = null, saveAv
         };
     }, [menuOpen]);
     const menuItem = `flex w-full items-center gap-2 rounded-[5px] px-2.5 py-1.5 text-left text-[12px] text-neutral-300 transition-colors hover:bg-cyan-500/15 hover:text-cyan-100 ${FOCUS_RING}`;
-    return (_jsxs("header", { className: `pointer-events-auto relative z-[60] flex h-12 shrink-0 items-center gap-2 border-b ${BORDER} bg-[#111318] px-2.5`, children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2.5", children: [_jsx("div", { className: "flex h-7 w-7 shrink-0 items-center justify-center rounded-[6px] bg-gradient-to-br from-cyan-500/30 to-indigo-500/25 text-[11px] font-bold tracking-wide text-cyan-200 ring-1 ring-inset ring-cyan-400/30", "aria-hidden": "true", children: "JG" }), _jsxs("div", { className: "min-w-0 leading-tight", children: [_jsx("div", { className: "truncate text-[13px] font-semibold text-neutral-100", children: gameId }), _jsx("div", { className: "text-[10px] text-neutral-500", children: "Scene Editor" })] }), _jsx("div", { className: "ml-1 hidden md:block", children: _jsx(SaveStatus, { dirty: dirty, saveState: saveState, lastSavedAt: lastSavedAt }) })] }), _jsx("div", { className: "flex flex-1 justify-center px-2", children: _jsxs("button", { type: "button", onClick: onOpenPalette, "aria-label": "Open command palette", className: `flex h-8 w-full max-w-[420px] items-center gap-2 rounded-[6px] border border-white/[0.08] bg-black/30 px-3 text-[12px] text-neutral-500 transition-colors hover:border-white/[0.14] hover:text-neutral-400 ${FOCUS_RING}`, children: [_jsx(Icon, { name: "search", size: 13 }), _jsx("span", { className: "min-w-0 flex-1 truncate text-left", children: "Search or run a command\u2026" }), _jsxs("span", { className: "hidden items-center gap-0.5 sm:flex", children: [_jsx(Kbd, { children: "Ctrl" }), _jsx(Kbd, { children: "K" })] })] }) }), _jsxs("div", { className: "flex shrink-0 items-center gap-1", children: [_jsx(IconButton, { icon: "undo", label: "Undo (Ctrl+Z)", onClick: onUndo, disabled: !canUndo, tone: "ghost" }), _jsx(IconButton, { icon: "redo", label: "Redo (Ctrl+Y)", onClick: onRedo, disabled: !canRedo, tone: "ghost" }), _jsx(ToolbarDivider, {}), _jsxs("button", { type: "button", onClick: onPlay, className: `flex h-8 items-center gap-1.5 rounded-[6px] bg-emerald-600 px-3.5 text-[12px] font-semibold text-white shadow-sm shadow-emerald-950/40 transition-colors hover:bg-emerald-500 ${FOCUS_RING}`, title: "Enter Play mode (F2+E toggles back)", children: [_jsx(Icon, { name: "play", size: 12 }), "Play"] }), _jsx(IconButton, { icon: "pause", label: "Pause \u2014 available in Play mode", disabled: true }), _jsx(IconButton, { icon: "step", label: "Step one frame \u2014 available in Play mode", disabled: true }), _jsx(ToolbarDivider, {}), _jsx(IconButton, { icon: "walk", label: "Walk the world", onClick: onWalk, tone: "ghost" }), _jsx(IconButton, { icon: "panel", label: "Lay out HUD panels", onClick: onHud, tone: "ghost" }), _jsx(ToolbarDivider, {}), saveAvailable ? (_jsxs("button", { type: "button", onClick: onSave, disabled: saveState === "saving", title: saveError ?? "Write the scene to the game's editor.scene.json (Ctrl+S)", className: `flex h-8 items-center gap-1.5 rounded-[6px] px-3 text-[12px] font-medium transition-colors ${FOCUS_RING} ${saveState === "error"
+    return (_jsxs("header", { className: `pointer-events-auto relative z-[60] flex h-12 shrink-0 items-center gap-2 border-b ${BORDER} bg-[#111318] px-2.5`, children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2.5", children: [onExitToGame !== undefined ? (_jsxs("button", { type: "button", onClick: onExitToGame, title: "Close the editor and return to the game (F2+Q)", className: `flex h-8 shrink-0 items-center gap-1.5 rounded-[6px] border border-white/[0.08] bg-black/30 pl-2 pr-2.5 text-[12px] text-neutral-300 transition-colors hover:border-white/[0.16] hover:bg-white/[0.06] hover:text-neutral-100 ${FOCUS_RING}`, children: [_jsx(Icon, { name: "chevronRight", size: 14, className: "rotate-180" }), "Exit to game"] })) : null, _jsx("div", { className: "flex h-7 w-7 shrink-0 items-center justify-center rounded-[6px] bg-gradient-to-br from-cyan-500/30 to-indigo-500/25 text-[11px] font-bold tracking-wide text-cyan-200 ring-1 ring-inset ring-cyan-400/30", "aria-hidden": "true", children: "JG" }), _jsxs("div", { className: "min-w-0 leading-tight", children: [_jsx("div", { className: "truncate text-[13px] font-semibold text-neutral-100", children: gameId }), _jsx("div", { className: "text-[10px] text-neutral-500", children: "Scene Editor" })] }), _jsx("div", { className: "ml-1 hidden md:block", children: _jsx(SaveStatus, { dirty: dirty, saveState: saveState, lastSavedAt: lastSavedAt }) })] }), _jsx("div", { className: "flex flex-1 justify-center px-2", children: _jsxs("button", { type: "button", onClick: onOpenPalette, "aria-label": "Open command palette", className: `flex h-8 w-full max-w-[420px] items-center gap-2 rounded-[6px] border border-white/[0.08] bg-black/30 px-3 text-[12px] text-neutral-500 transition-colors hover:border-white/[0.14] hover:text-neutral-400 ${FOCUS_RING}`, children: [_jsx(Icon, { name: "search", size: 13 }), _jsx("span", { className: "min-w-0 flex-1 truncate text-left", children: "Search or run a command\u2026" }), _jsxs("span", { className: "hidden items-center gap-0.5 sm:flex", children: [_jsx(Kbd, { children: "Ctrl" }), _jsx(Kbd, { children: "K" })] })] }) }), _jsxs("div", { className: "flex shrink-0 items-center gap-1", children: [_jsx(IconButton, { icon: "undo", label: "Undo (Ctrl+Z)", onClick: onUndo, disabled: !canUndo, tone: "ghost" }), _jsx(IconButton, { icon: "redo", label: "Redo (Ctrl+Y)", onClick: onRedo, disabled: !canRedo, tone: "ghost" }), _jsx(ToolbarDivider, {}), _jsxs("button", { type: "button", onClick: onPlay, className: `flex h-8 items-center gap-1.5 rounded-[6px] bg-emerald-600 px-3.5 text-[12px] font-semibold text-white shadow-sm shadow-emerald-950/40 transition-colors hover:bg-emerald-500 ${FOCUS_RING}`, title: "Enter Play mode (F2+E toggles back)", children: [_jsx(Icon, { name: "play", size: 12 }), "Play"] }), _jsx(IconButton, { icon: "pause", label: "Pause \u2014 available in Play mode", disabled: true }), _jsx(IconButton, { icon: "step", label: "Step one frame \u2014 available in Play mode", disabled: true }), _jsx(ToolbarDivider, {}), _jsx(IconButton, { icon: "walk", label: "Walk the world", onClick: onWalk, tone: "ghost" }), _jsx(IconButton, { icon: "panel", label: "Lay out HUD panels", onClick: onHud, tone: "ghost" }), _jsx(ToolbarDivider, {}), saveAvailable ? (_jsxs("button", { type: "button", onClick: onSave, disabled: saveState === "saving", title: saveError ?? "Write the scene to the game's editor.scene.json (Ctrl+S)", className: `flex h-8 items-center gap-1.5 rounded-[6px] px-3 text-[12px] font-medium transition-colors ${FOCUS_RING} ${saveState === "error"
                             ? "bg-rose-600/90 text-white hover:bg-rose-500"
                             : dirty
                                 ? "bg-cyan-600 text-white shadow-sm shadow-cyan-950/40 hover:bg-cyan-500"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/editor",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Scene/world/asset editor for JGengine — loaded lazily by the runner; never import from game entrypoints.",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.12.0",
-    "@jgengine/react": "^0.12.0",
-    "@jgengine/shell": "^0.12.0"
+    "@jgengine/core": "^0.13.0",
+    "@jgengine/react": "^0.13.0",
+    "@jgengine/shell": "^0.13.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/jgengine/SKILL.md

@@ -42,6 +42,7 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 
 Within each selected domain:
 
+0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) for `combat-loop`, `boss-telegraph`, `loot`, `quest`, `coop-presence`, `third-person-camera`; `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
 1. Search `capabilities.md` by intent; it maps needs to imports.
 2. Open `api.md` only when exact signatures or export inventory are needed.
 3. Open the linked reference only for a deeper recipe or trap.

package/skills/jgengine/api.md

@@ -6,7 +6,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.12.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.13.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -38,7 +38,7 @@
 - `WorldFeature` (type): type WorldFeature = | PlaceWorldFeature | ({ kind: "biomes" } & BiomesWorldConfig) | ({ kind: "voxel" } & VoxelWorldConfig) | ({ kind: "plots" } & PlotsWorldConfig) | ({ kind: "tilemap" } & TilemapWorldConfig) | EnvironmentWorldFeature | { kind: "flat" } — A declared world shape passed to `defineGame`. The preferred model is the place feature from `world()` (`@jgengine/core/world/place`): substrate + laws, with all dressing authored in the editor. The remaining members — biomes, voxel grid, plots, tilemap, environment, flat — are the legacy code-declared shapes kept for existing games.
 - `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.
+- `building` (function): function building(config: BuildingEnvironmentConfig = {}): BuildingEnvironmentDescriptor — Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style. Pass `along` to line road frontage instead of gridding around `position`.
 - `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.
@@ -209,11 +209,18 @@
 - `Tunable` (interface): interface Tunable<T> — Typed handle to a registered control, exposing its live value and subscribe/set/reset operations.
 - `TunableAccessor` (interface): interface TunableAccessor — Get/set accessor pair plus initial value used to bind a discovered field to a control.
 
+## @jgengine/core/devtools/urlFlags
+
+- `readUrlFlag` (function): function readUrlFlag(param: string): boolean — True when `param` is present and not an explicit off value (`0`/`false`/`off`/`no`).
+- `readUrlParam` (function): function readUrlParam(param: string): string | null — The current query value of `param`, or null when absent (or no DOM).
+- `subscribeUrlChange` (function): function subscribeUrlChange(listener: () => void): () => void — Fires `listener` whenever the query string may have changed out from under a flag — browser back/forward (`popstate`). Manual address-bar edits reload the page, so initial reads cover those; this keeps in-app state honest across history navigation. Returns an unsubscribe.
+- `writeUrlParam` (function): function writeUrlParam(param: string, value: string | null): void — Sets `param` to `value`, or removes it when `value` is null, rewriting the URL in place with `history.replaceState` so the rest of the query and the hash survive and no history entry is pushed. No-ops without a DOM, and skips the write when the URL already matches.
+
 ## @jgengine/core/meta/changelog
 
 - `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.12.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.13.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -276,7 +283,7 @@
 - `SceneObjectContext` (interface): interface SceneObjectContext extends ObjectStore — ⚠ undocumented
 - `SceneWorldItemContext` (interface): interface SceneWorldItemContext — ⚠ undocumented
 - `TelegraphInput` (interface): interface TelegraphInput — ⚠ undocumented
-- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst; `from`/`to` accept an instance id or a world point, `color` is a `0xRRGGBB` tint, and `durationMs` defaults per `kind`.
+- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst. The easy path is a named `preset` — `vfx({ preset: "arrow", from: caster, to: enemy })` renders a visible bolt with no color or archetype tuning; `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"` and the rest of {@link vfxPresets} likewise just work. `from`/`to` accept an instance id (the shell follows its live pose) or a fixed world point. Anything you also pass — `kind`, `color` (`0xRRGGBB`), `radius`, `durationMs` — overrides the preset; supply `kind` + `color` yourself for a fully custom burst with no preset. `durationMs` defaults per `kind`.
 - `WorldItemPickupResult` (type): type WorldItemPickupResult = | { status: "ok"; record: WorldItemRecord } | { status: "rejected"; reason: string } — ⚠ undocumented
 - `createGameContext` (function): function createGameContext<TAssetRef extends ModelAssetRef, TMultiplayer>(options: GameContextOptions<TAssetRef, TMultiplayer>): GameContext — ⚠ undocumented
 
@@ -307,7 +314,7 @@
 - `SceneObjectContext` (interface): interface SceneObjectContext extends ObjectStore — ⚠ undocumented
 - `SceneWorldItemContext` (interface): interface SceneWorldItemContext — ⚠ undocumented
 - `TelegraphInput` (interface): interface TelegraphInput — ⚠ undocumented
-- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst; `from`/`to` accept an instance id or a world point, `color` is a `0xRRGGBB` tint, and `durationMs` defaults per `kind`.
+- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst. The easy path is a named `preset` — `vfx({ preset: "arrow", from: caster, to: enemy })` renders a visible bolt with no color or archetype tuning; `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"` and the rest of {@link vfxPresets} likewise just work. `from`/`to` accept an instance id (the shell follows its live pose) or a fixed world point. Anything you also pass — `kind`, `color` (`0xRRGGBB`), `radius`, `durationMs` — overrides the preset; supply `kind` + `color` yourself for a fully custom burst with no preset. `durationMs` defaults per `kind`.
 - `WorldItemPickupResult` (type): type WorldItemPickupResult = | { status: "ok"; record: WorldItemRecord } | { status: "rejected"; reason: string } — ⚠ undocumented
 
 ## @jgengine/core/runtime/gameRuntime
@@ -322,6 +329,7 @@
 
 ## @jgengine/core/runtime/headlessRunner
 
+- `HeadlessCommandInterface` (interface): interface HeadlessCommandInterface — Canvas-free command/intent surface for {@link HeadlessRunner} — invoke a game's registered UI commands and read the resulting reactive state off `ctx`.
 - `HeadlessInput` (interface): interface HeadlessInput — One step's worth of player intent handed to {@link HeadlessRunner.step} — the held-action set and pointer state the shell would otherwise publish from the browser each frame.
 - `HeadlessRunner` (interface): interface HeadlessRunner — A renderer-free driver for a game loop: builds a {@link GameContext} from a {@link GameDefinition}, runs the init hooks, then advances the simulation one step at a time from injected input. No React, R3F, or three.js — the whole play path (time, input, `onTick`, behaviour nav, optional player movement) runs from `core` primitives alone, so a non-React host (a server tick, a test, a CLI replay) can play a real game and read its world snapshot. The shell's FrameDriver is one such driver bolted to `useFrame`; this is the same step distilled out of the render tree.
 - `HeadlessRunnerOptions` (interface): interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> — ⚠ undocumented

package/skills/jgengine-editor/api.md

@@ -393,7 +393,7 @@
 - `EDITOR_AGENT_KEY_FALLBACK_ENV` (const): const EDITOR_AGENT_KEY_FALLBACK_ENV: "ANTHROPIC_API_KEY" — Fallback API-key env when `JGENGINE_EDITOR_AGENT_KEY` is unset (`ANTHROPIC_API_KEY`).
 - `EDITOR_AGENT_URL_ENV` (const): const EDITOR_AGENT_URL_ENV: "JGENGINE_EDITOR_AGENT_URL" — Env var name for the remote agent HTTP URL (`JGENGINE_EDITOR_AGENT_URL`).
 - `EDITOR_MCP_TOOLS` (const): const EDITOR_MCP_TOOLS: readonly EditorMcpTool[] — Full set of MCP tools an agent can call to drive the live scene editor.
-- `EditorApp` (function): function EditorApp({ gameId, playable, layers, catalogs, save, modeChip, networkPresence }: EditorAppProps): React.JSX.Element — Top-level scene editor: author spawns/zones/paths/notes visually over edit, walk, or play modes.
+- `EditorApp` (function): function EditorApp({ gameId, playable, layers, catalogs, save, modeChip, networkPresence, onExitEditor }: EditorAppProps): React.JSX.Element — Top-level scene editor: author spawns/zones/paths/notes visually over edit, walk, or play modes.
 - `EditorAppProps` (interface): interface EditorAppProps — Props for mounting the scene editor over a playable game.
 - `EditorAssetEntry` (interface): interface EditorAssetEntry — A searchable, placeable asset shown in the editor's asset browser panel.
 - `EditorAssetInfo` (interface): interface EditorAssetInfo — A placeable asset entry offered in the editor's asset browser.
@@ -402,7 +402,7 @@
 - `EditorBridgeServer` (interface): interface EditorBridgeServer — A running editor bridge server: its bound port, URL, and a stop handle.
 - `EditorBridgeServerOptions` (interface): interface EditorBridgeServerOptions — Options for starting the editor's HTTP bridge server: host api, port, hostname.
 - `EditorCameraDriver` (const): const EditorCameraDriver: React.MemoExoticComponent<({ api }: { api: EditorHostApi; }) => null> — Smoothly pans the orbit camera to the editor host's focus target when it changes.
-- `EditorChrome` (function): function EditorChrome({ gameId, session, api, assets, ui, baselineDocument, save, networkSnapshot, importAsset = importAssetToHost, onRegisterAsset, }: { gameId: string; session: EditorSession; api: EditorHostApi; assets: readonly EditorAssetEntry[]; ui: EditorUiStore; /** The document as loaded — d… — The full editor UI shell — global app bar, contextual scene toolbar, workspace rail, resizable hierarchy/inspector docks, tabbed bottom dock (content browser, console, profiler, AI assistant), viewport overlays, and status bar — wired to the session, UI store, layout store, and host RPC. Mounted by `EditorApp`; not a game-author entry point.
+- `EditorChrome` (function): function EditorChrome({ gameId, session, api, assets, ui, baselineDocument, save, networkSnapshot, importAsset = importAssetToHost, onRegisterAsset, onExitEditor, }: { gameId: string; session: EditorSession; api: EditorHostApi; assets: readonly EditorAssetEntry[]; ui: EditorUiStore; /** The document… — The full editor UI shell — global app bar, contextual scene toolbar, workspace rail, resizable hierarchy/inspector docks, tabbed bottom dock (content browser, console, profiler, AI assistant), viewport overlays, and status bar — wired to the session, UI store, layout store, and host RPC. Mounted by `EditorApp`; not a game-author entry point.
 - `EditorHostApi` (interface): interface EditorHostApi — The live editor's global control surface — session, visibility, camera focus, assets, mode, RPC.
 - `EditorLayerOverlays` (function): function EditorLayerOverlays({ document, visibility, selection, hoverId = null, onSelect, activePathPoint, groundHeightAt, }: { document: EditorDocument; visibility: EditorKindVisibility; selection: readonly string[]; /** Pre-selection hover id from viewport pointer pick; ignored when already select… — Renders every visible marker, volume, path, and note from a document as in-scene 3D gizmos.
 - `EditorMcpTool` (interface): interface EditorMcpTool — One MCP tool descriptor — same verbs as the in-browser host RPC.
@@ -436,7 +436,7 @@
 - `TerrainMode` (type): type TerrainMode = "sculpt" | "paint" — The terrain tool's active sub-mode: reshape the heightfield, or paint material layers onto it.
 - `ViewportSelect` (const): const ViewportSelect: React.MemoExoticComponent<({ api, ui }: { api: EditorHostApi; ui: EditorUiStore; }) => null> — Canvas click-to-select and click-to-place. Document objects pick by screen proximity (registration always matches what you see) with click-cycling through stacked candidates and shift/ctrl additive selection; everything else picks by occlusion-ordered raycast against the tagged scene graph. When a placement tool is armed, clicks author new markers, volumes, notes, or path points at the ground hit instead of selecting.
 - `VirtualWindow` (interface): interface VirtualWindow — The visible slice of a fixed-row-height list: which rows to mount and the spacer geometry.
-- `assetsFromCatalog` (function): function assetsFromCatalog(ids: readonly string[], resolve?: (id: string) => { url?: string } | null): EditorAssetEntry[] — Turns a game's asset catalog ids into editor asset entries for the browser panel.
+- `assetsFromCatalog` (function): function assetsFromCatalog(ids: readonly string[], resolve?: (id: string) => { url?: string; clips?: readonly string[] } | null): EditorAssetEntry[] — Turns a game's asset catalog ids into editor asset entries for the browser panel.
 - `blankWorld` (function): function blankWorld(_seed = "standalone"): EnvironmentWorldFeature — The default flat-ground authoring canvas the standalone editor opens on when the host supplies none. Deliberately thin — bare sculptable ground under a clear default sky. Dressing (sky look, foliage scatter, props) is what the author adds here, written into the scene document; it is never pre-baked into the canvas. The `seed` parameter is legacy and unused.
 - `createBlankPlayable` (function): function createBlankPlayable(options: BlankPlayableOptions = {}): PlayableGame — Builds a minimal gameless `PlayableGame` — a flat world plus an asset catalog — for the editor to mount over.
 - `createDefaultAgentEndpoint` (function): function createDefaultAgentEndpoint(config: AgentEndpointConfig = resolveAgentEndpointConfig()): AgentEndpoint — Picks HTTP endpoint when `JGENGINE_EDITOR_AGENT_URL` (or config.url) is set, otherwise the offline local agent.
@@ -461,7 +461,7 @@
 - `AssetBrowser` (function): function AssetBrowser({ assets, session, onPlace, }: { assets: readonly EditorAssetEntry[]; session: EditorSession; onPlace: (entry: EditorAssetEntry) => void; }): React.JSX.Element — Searchable panel for placing catalog assets or an empty marker into the scene.
 - `EditorAssetEntry` (interface): interface EditorAssetEntry — A searchable, placeable asset shown in the editor's asset browser panel.
 - `MATERIAL_DRAG_MIME` (const): const MATERIAL_DRAG_MIME: "application/x-jgengine-material" — Custom drag mime carrying a material id — read by hierarchy rows and the viewport drop zone.
-- `assetsFromCatalog` (function): function assetsFromCatalog(ids: readonly string[], resolve?: (id: string) => { url?: string } | null): EditorAssetEntry[] — Turns a game's asset catalog ids into editor asset entries for the browser panel.
+- `assetsFromCatalog` (function): function assetsFromCatalog(ids: readonly string[], resolve?: (id: string) => { url?: string; clips?: readonly string[] } | null): EditorAssetEntry[] — Turns a game's asset catalog ids into editor asset entries for the browser panel.
 
 ## @jgengine/editor/DebugDraw
 
@@ -470,7 +470,7 @@
 
 ## @jgengine/editor/EditorApp
 
-- `EditorApp` (function): function EditorApp({ gameId, playable, layers, catalogs, save, modeChip, networkPresence }: EditorAppProps): React.JSX.Element — Top-level scene editor: author spawns/zones/paths/notes visually over edit, walk, or play modes.
+- `EditorApp` (function): function EditorApp({ gameId, playable, layers, catalogs, save, modeChip, networkPresence, onExitEditor }: EditorAppProps): React.JSX.Element — Top-level scene editor: author spawns/zones/paths/notes visually over edit, walk, or play modes.
 - `EditorAppProps` (interface): interface EditorAppProps — Props for mounting the scene editor over a playable game.
 - `EditorSaveFn` (type): type EditorSaveFn = (json: string) => Promise<{ ok: boolean; path?: string; error?: string }> — Persists an exported document JSON; resolves with where it landed or why it failed.
 
@@ -480,7 +480,7 @@
 
 ## @jgengine/editor/EditorChrome
 
-- `EditorChrome` (function): function EditorChrome({ gameId, session, api, assets, ui, baselineDocument, save, networkSnapshot, importAsset = importAssetToHost, onRegisterAsset, }: { gameId: string; session: EditorSession; api: EditorHostApi; assets: readonly EditorAssetEntry[]; ui: EditorUiStore; /** The document as loaded — d… — The full editor UI shell — global app bar, contextual scene toolbar, workspace rail, resizable hierarchy/inspector docks, tabbed bottom dock (content browser, console, profiler, AI assistant), viewport overlays, and status bar — wired to the session, UI store, layout store, and host RPC. Mounted by `EditorApp`; not a game-author entry point.
+- `EditorChrome` (function): function EditorChrome({ gameId, session, api, assets, ui, baselineDocument, save, networkSnapshot, importAsset = importAssetToHost, onRegisterAsset, onExitEditor, }: { gameId: string; session: EditorSession; api: EditorHostApi; assets: readonly EditorAssetEntry[]; ui: EditorUiStore; /** The document… — The full editor UI shell — global app bar, contextual scene toolbar, workspace rail, resizable hierarchy/inspector docks, tabbed bottom dock (content browser, console, profiler, AI assistant), viewport overlays, and status bar — wired to the session, UI store, layout store, and host RPC. Mounted by `EditorApp`; not a game-author entry point.
 
 ## @jgengine/editor/PerfProbe
 
@@ -613,6 +613,10 @@
 
 - `runtimeHandlers` (const): const runtimeHandlers: Pick< HandlerTable, | "push_document_patch" | "pull_document_patches" | "document_revision" | "push_runtime_delta" | "pull_runtime_deltas" | "runtime_snapshot" | "runtime_summary" | "runtime_get" | "runtime_set" | "runtime_pause" | "runtime_resume" | "runtime_step" | "set_runt… — Live-sync document patches, the ephemeral runtime reverse channel, and play-mode poke verbs.
 
+## @jgengine/editor/handlers/streets
+
+- `streetsHandlers` (const): const streetsHandlers: Pick<HandlerTable, "generate_streets"> — Document, selection, camera, mode, asset placement, and status verbs.
+
 ## @jgengine/editor/handlers/terrain
 
 - `terrainHandlers` (const): const terrainHandlers: Pick< HandlerTable, | "create_terrain" | "sculpt_terrain" | "terrain_summary" | "paint_terrain" | "fill_terrain" | "auto_paint" | "terrain_materials" | "terrain_layers" | "set_terrain_layers" | "blend_terrain" | "convert_scatter" | "add_foliage" | "scatter_summary" > — Sculpt heightfield, material painting, terrain layers, and foliage/scatter verbs.
@@ -760,7 +764,7 @@
 
 ## @jgengine/editor/shell/TopAppBar
 
-- `TopAppBar` (function): function TopAppBar({ gameId, dirty, saveState, lastSavedAt = null, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }: { gameId: string; dirty: boolean; saveState: TopBarSaveState; /… — Global application bar: identity + save state on the left, command palette in the center, history / run controls / document actions on the right. Pause and Step stay disabled in edit mode; Play mode mounts {@link PlayModeBar}, which wires the same controls to the runtime pause/step RPCs so mode switches keep shell chrome.
+- `TopAppBar` (function): function TopAppBar({ gameId, onExitToGame, dirty, saveState, lastSavedAt = null, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }: { gameId: string; /** When set (editor summoned o… — Global application bar: identity + save state on the left, command palette in the center, history / run controls / document actions on the right. Pause and Step stay disabled in edit mode; Play mode mounts {@link PlayModeBar}, which wires the same controls to the runtime pause/step RPCs so mode switches keep shell chrome.
 - `TopBarSaveState` (type): type TopBarSaveState = "idle" | "saving" | "saved" | "error" — Document save lifecycle mirrored from `useDocumentSave`.
 
 ## @jgengine/editor/shell/ViewportOverlays