@jgengine/editor 0.11.0 → 0.12.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.12.0
+
+### Migrate
+
+- **Author games through `defineGame` from `@jgengine/shell`** — it is the single public authoring entry (and carries the define-game capability tag). Core's constructor was renamed `defineGame` → `defineGameDefinition` (`@jgengine/core/game/defineGame`); only hosts and tooling call it. If you imported `defineGame` from core, switch the import to `@jgengine/shell`. `GamePlayer`/`GamePlayerShell` are `@internal` now — `GameHost` is the documented mount, and it owns the editor summon (`?mode=editor`, F2+E, dev save endpoint), so delete any per-game editor bootstrap.
+- **Declare your world with `world()`** (`@jgengine/core/world/place`): `world({ id, ground: { mode, size, surface? }, physics? })` with `flat` / `round` / `voxel` / `board` ground. New scaffolds emit a thin infinite flat place instead of the old 96 m meadow. `environment()` still works but is demoted to the legacy consumption path for editor-written scene data — **nothing required** for existing games; new worlds should use `world()` and author all dressing in the editor.
+- Everything else is additive — stat pools, minimap marker sources, auction house, city/path generation, editor workspaces require no changes to existing games.
+
+### Added
+
+- **World = place: `world()` API** (#1178) — a world is substrate + laws, not a coded diorama. `@jgengine/core/world/place` ships `world({ id, ground: { mode, size, surface?, generator? }, physics? })`; size is discriminated by mode (flat `{x,z}` with `Infinity` axes, round `{radius}`, voxel generator domain, board `{x,y}` cells — TS and runtime both reject mismatches). `ground.surface` carries matter/feel laws (metal vs slime vs felt) read by the same rule systems; per-place `physics` resolves over the game default; multiple worlds per game are first-class. The shell renders place substrates (`PlaceScene`) under the engine default sky; seeds derive from world id + save via `seedForPlace`.
+- **`@jgengine/shell/gameKit`** — happy-path authoring surface: authoring, mount, stores, systems, authored-scene helpers, HUD primitives, seeded rng in one import.
+- **Portable generic stat pools** — `@jgengine/core/stats/statPool`: bounded named pools (health, energy, heat, ammo…) with the entity-stats integration rebuilt on them; recipe in skill `jgengine-combat`.
+- **Auction-house economy primitives** (#1086) — `@jgengine/core/economy/auctionBook` (timed bid auctions, escrowed bids, outbid refunds, optional buyout, anti-snipe close extension, seller settlement minus house cut) plus market price history.
+- **Portable minimap marker sources** — core world seam feeding game minimaps; recipe in skill `jgengine-ui`.
+- **Unified seed-driven path network + city generation v2** (#1103, #1106) — streets/blocks/buildings with grid-ness, curviness, branching and block-size dials; zone bands, weighted building-class mixes, massing pieces, balance presets, junction-centered clustering, road-derived block polygons and parcels. Shell renders realistic roads: real intersections, curbs, lane lines, tunnels, and roads riding bridge decks.
+- **Physical fidelity** — mesh-accurate hitboxes (shots pass through holes in concave models, #1075), auto-fit entity/object colliders from measured model bounds (#1072), movement obstruction reading fitted boxes + compound-box openings (#1077).
+- **Editor overhaul** (#1110) — materials / lighting / scripting / animation-timeline / multiplayer workspaces, command palette, minimap bake wired end-to-end (#1036), real offscreen GLB thumbnails in the content browser, hierarchy drag-drop + keyboard + context menus + per-object visibility/lock, multi-select inspector, console RPC, asset drag-place, ortho projection, pivot modes, play chrome.
+- **Editor authoring pipeline** — author entity definitions and starter catalogs (#1012), author catalogs/schema fields in the Data tab (#1043), promote an authored scene folder into a runnable game (#1011), authored triggers promoted to a shared primitive with goal/win rules (#1013), asset import rewrites the game's `game/assets.ts` (#1042).
+- **Skills** — research-backed `game-design` and `level-design` skills (#962); every-game-owns-custom-UI invariant codified (#1148).
+
+### Changed
+
+- `npx jgengine create` scaffolds a thin infinite flat `world()` place; the editor `blankWorld` no longer pre-bakes seeded grass. Dressing belongs in `editor.scene.json`.
+- Environment studio visual-quality pass — turf tufts, depth-aware water, relief soil, weathered poles; grass fields no longer rebuild geometry per frame (#1090).
+
 ## 0.11.0
 
 ### Migrate

package/README.md

@@ -0,0 +1,12 @@
+# @jgengine/editor
+
+Browser-based 3D scene editor for [JGengine](https://github.com/Noisemaker111/jgengine) — author `editor.scene.json` (placement, terrain, paths, zones, foliage, triggers, catalogs) through a Blender/Unity-style GUI or the agent RPC bridge.
+
+Usually reached through the CLI rather than imported directly:
+
+```sh
+npx jgengine editor            # open the editor on the current folder
+npx jgengine editor ./world --assets ./models
+```
+
+Inside a scaffolded game the editor is engine-summoned (`?mode=editor`, F2+E); the game consumes the authored document at runtime via `@jgengine/core` / `@jgengine/shell`. Agents drive it headlessly with `npx jgengine editor-mcp` (document RPC over localhost).

package/dist/AssetBrowser.d.ts

@@ -6,8 +6,17 @@ export interface EditorAssetEntry {
     kind: "model" | "catalog" | "marker";
     url?: string;
 }
-/** Custom drag mime carrying a material id — read by `OutlinerPanel` rows and the viewport drop zone. */
+/** 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";
+/**
+ * Custom drag mime for placeable catalog assets. Payload is JSON
+ * `{ id, label, kind }` so the viewport can call `place_asset` without a registry round-trip.
+ */
+export declare const ASSET_DRAG_MIME = "application/x-jgengine-editor-asset";
+/** Serializes a placeable asset for HTML5 drag into the viewport. @internal */
+export declare function encodeAssetDragPayload(entry: EditorAssetEntry): string;
+/** Parses an asset drag payload; returns null when the data is missing or malformed. @internal */
+export declare function decodeAssetDragPayload(raw: string): EditorAssetEntry | null;
 /** Searchable panel for placing catalog assets or an empty marker into the scene. */
 export declare function AssetBrowser({ assets, session, onPlace, }: {
     assets: readonly EditorAssetEntry[];
@@ -18,3 +27,19 @@ export declare function AssetBrowser({ assets, session, onPlace, }: {
 export declare function assetsFromCatalog(ids: readonly string[], resolve?: (id: string) => {
     url?: string;
 } | null): EditorAssetEntry[];
+/**
+ * Converts a durable/ephemeral standalone import into a Content Browser entry.
+ * Imported models are always kind `"model"` so place_asset stamps a catalogId for mesh resolution.
+ * @internal
+ */
+export declare function editorAssetFromImport(asset: {
+    id: string;
+    url: string;
+    label?: string;
+}): EditorAssetEntry;
+/**
+ * Merges imported model entries into the live browser list, replacing any prior entry that shares
+ * an id (re-import stays a single catalog row).
+ * @internal
+ */
+export declare function mergeEditorAssets(current: readonly EditorAssetEntry[], next: readonly EditorAssetEntry[]): EditorAssetEntry[];

package/dist/AssetBrowser.js

@@ -1,8 +1,35 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useState } from "react";
 import { TERRAIN_MATERIALS } from "./uiStore.js";
-/** Custom drag mime carrying a material id — read by `OutlinerPanel` rows and the viewport drop zone. */
+/** 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";
+/**
+ * Custom drag mime for placeable catalog assets. Payload is JSON
+ * `{ id, label, kind }` so the viewport can call `place_asset` without a registry round-trip.
+ */
+export const ASSET_DRAG_MIME = "application/x-jgengine-editor-asset";
+/** Serializes a placeable asset for HTML5 drag into the viewport. @internal */
+export function encodeAssetDragPayload(entry) {
+    return JSON.stringify({ id: entry.id, label: entry.label, kind: entry.kind });
+}
+/** Parses an asset drag payload; returns null when the data is missing or malformed. @internal */
+export function decodeAssetDragPayload(raw) {
+    if (raw.length === 0)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.id !== "string" || parsed.id.length === 0)
+            return null;
+        if (typeof parsed.label !== "string")
+            return null;
+        if (parsed.kind !== "model" && parsed.kind !== "catalog" && parsed.kind !== "marker")
+            return null;
+        return { id: parsed.id, label: parsed.label, kind: parsed.kind };
+    }
+    catch {
+        return null;
+    }
+}
 /** Materials palette: drag a chip onto an outliner row (assign to that object) or the viewport (paint terrain / assign to the object under the cursor). */
 function MaterialsPalette() {
     return (_jsx("div", { className: "flex flex-wrap gap-1 border-b border-white/[0.08] pb-2", children: TERRAIN_MATERIALS.map((material) => (_jsxs("div", { draggable: true, onDragStart: (event) => {
@@ -47,3 +74,29 @@ export function assetsFromCatalog(ids, resolve) {
         };
     });
 }
+/**
+ * Converts a durable/ephemeral standalone import into a Content Browser entry.
+ * Imported models are always kind `"model"` so place_asset stamps a catalogId for mesh resolution.
+ * @internal
+ */
+export function editorAssetFromImport(asset) {
+    return {
+        id: asset.id,
+        label: asset.label ?? asset.id,
+        kind: "model",
+        url: asset.url,
+    };
+}
+/**
+ * Merges imported model entries into the live browser list, replacing any prior entry that shares
+ * an id (re-import stays a single catalog row).
+ * @internal
+ */
+export function mergeEditorAssets(current, next) {
+    if (next.length === 0)
+        return [...current];
+    const byId = new Map(current.map((asset) => [asset.id, asset]));
+    for (const asset of next)
+        byId.set(asset.id, asset);
+    return Array.from(byId.values());
+}

package/dist/AssetDropZone.d.ts

@@ -0,0 +1,9 @@
+import type { EditorHostApi } from "./session.js";
+/**
+ * Viewport drop target for content-browser assets. Drops call `place_asset` at the ground hit
+ * (or the host focus target when the ray misses). No-op when the payload is not an asset drag.
+ * @internal — mounted by `EditorApp`'s world overlay.
+ */
+export declare const AssetDropZone: import("react").MemoExoticComponent<({ api }: {
+    api: EditorHostApi;
+}) => null>;

package/dist/AssetDropZone.js

@@ -0,0 +1,65 @@
+import { useThree } from "@react-three/fiber";
+import { memo, useEffect } from "react";
+import * as THREE from "three";
+import { ASSET_DRAG_MIME, decodeAssetDragPayload } from "./AssetBrowser.js";
+const GROUND_PLANE = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
+/**
+ * Viewport drop target for content-browser assets. Drops call `place_asset` at the ground hit
+ * (or the host focus target when the ray misses). No-op when the payload is not an asset drag.
+ * @internal — mounted by `EditorApp`'s world overlay.
+ */
+export const AssetDropZone = memo(function AssetDropZone({ api }) {
+    const gl = useThree((state) => state.gl);
+    const camera = useThree((state) => state.camera);
+    const scene = useThree((state) => state.scene);
+    useEffect(() => {
+        const canvas = gl.domElement;
+        const raycaster = new THREE.Raycaster();
+        const ndc = new THREE.Vector2();
+        const planeHit = new THREE.Vector3();
+        const onDragOver = (event) => {
+            if (event.dataTransfer === null || !event.dataTransfer.types.includes(ASSET_DRAG_MIME))
+                return;
+            event.preventDefault();
+            event.dataTransfer.dropEffect = "copy";
+        };
+        const groundAt = (clientX, clientY) => {
+            const rect = canvas.getBoundingClientRect();
+            ndc.set(((clientX - rect.left) / rect.width) * 2 - 1, -((clientY - rect.top) / rect.height) * 2 + 1);
+            raycaster.setFromCamera(ndc, camera);
+            for (const hit of raycaster.intersectObjects(scene.children, true)) {
+                if (!hit.object.isMesh || hit.object.visible === false)
+                    continue;
+                if (hit.object.type.startsWith("TransformControls"))
+                    continue;
+                return { x: hit.point.x, y: hit.point.y, z: hit.point.z };
+            }
+            if (raycaster.ray.intersectPlane(GROUND_PLANE, planeHit) !== null) {
+                return { x: planeHit.x, y: planeHit.y, z: planeHit.z };
+            }
+            return api.getFocusTarget() ?? { x: 0, y: 0, z: 0 };
+        };
+        const onDrop = (event) => {
+            const entry = decodeAssetDragPayload(event.dataTransfer?.getData(ASSET_DRAG_MIME) ?? "");
+            if (entry === null)
+                return;
+            event.preventDefault();
+            const position = groundAt(event.clientX, event.clientY);
+            api.handle({
+                method: "place_asset",
+                id: entry.id,
+                kind: entry.kind === "model" ? "prop" : entry.kind,
+                x: position.x,
+                y: position.y,
+                z: position.z,
+            });
+        };
+        canvas.addEventListener("dragover", onDragOver);
+        canvas.addEventListener("drop", onDrop);
+        return () => {
+            canvas.removeEventListener("dragover", onDragOver);
+            canvas.removeEventListener("drop", onDrop);
+        };
+    }, [gl, camera, scene, api]);
+    return null;
+});

package/dist/CatalogsPanel.d.ts

@@ -1,7 +1,9 @@
 import type { EditorCatalogDefinition, EditorSession } from "@jgengine/core/editor/index";
 /**
- * Gameplay data catalogs panel — lists game-exported catalogs and edits entries via SchemaInspector.
- * Values persist on `document.catalogs` and undo with the same coalesce keys as meta patches.
+ * Gameplay data catalogs panel — lists merged (game-exported + document-authored) catalogs, lets an
+ * author create a brand-new document catalog, author its schema fields, and edit rows via
+ * SchemaInspector. Row values and (for document catalogs) the schema itself persist on
+ * `document.catalogs` and undo with the same coalesce keys as meta patches.
  * @internal — mounted by `EditorChrome` as a left-aside tab.
  */
 export declare function CatalogsPanel({ session, definitions, }: {

package/dist/CatalogsPanel.js

@@ -1,36 +1,189 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useState } from "react";
 import { findEditorCatalog, findEditorCatalogEntry } from "@jgengine/core/editor/index";
+import { parseParams } from "@jgengine/core/scene/sceneKinds";
 import { SchemaInspector } from "./SchemaInspector.js";
+import { BORDER, CONTROL, FOCUS_RING, INPUT_CLS, MICRO_LABEL } from "./shell/theme.js";
 import { useStoreSelector } from "./useStoreSelector.js";
+function slugifyEntryId(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+/** The field types the document schema editor can author. */
+const FIELD_TYPES = [
+    "range",
+    "number",
+    "bool",
+    "select",
+    "color",
+    "text",
+    "seed",
+    "weightedList",
+    "action",
+];
+/**
+ * Rebuilds a valid {@link ParamField} for a new `type`, preserving `key`/`label` and reusing prior
+ * numeric bounds/default where the target type still carries them. Every type gets a schema-valid
+ * default so `parseParams` (which drives the reclamp on `setCatalogSchema`) always has a value to read.
+ */
+function coerceField(prev, type) {
+    const key = prev.key;
+    const label = prev.label;
+    const prevNumber = "default" in prev && typeof prev.default === "number" ? prev.default : 0;
+    const prevMin = "min" in prev && typeof prev.min === "number" ? prev.min : undefined;
+    const prevMax = "max" in prev && typeof prev.max === "number" ? prev.max : undefined;
+    const prevString = "default" in prev && typeof prev.default === "string" ? prev.default : "";
+    switch (type) {
+        case "range":
+            return { key, label, type: "range", min: prevMin ?? 0, max: prevMax ?? 10, default: prevNumber };
+        case "number":
+            return { key, label, type: "number", default: prevNumber, ...(prevMin === undefined ? {} : { min: prevMin }), ...(prevMax === undefined ? {} : { max: prevMax }) };
+        case "bool":
+            return { key, label, type: "bool", default: false };
+        case "select":
+            return { key, label, type: "select", options: [], default: prevString };
+        case "color":
+            return { key, label, type: "color", default: prevString || "#888888" };
+        case "text":
+            return { key, label, type: "text", default: prevString };
+        case "seed":
+            return { key, label, type: "seed", default: prevString };
+        case "weightedList":
+            return { key, label, type: "weightedList", default: [] };
+        case "action":
+            return { key, label, type: "action", action: "randomize" };
+    }
+}
+const INPUT = `min-w-0 px-2 py-1 text-[11px] ${INPUT_CLS}`;
+const BTN = `${CONTROL} px-2 py-1 text-[11px] font-medium disabled:opacity-40`;
 /**
- * Gameplay data catalogs panel — lists game-exported catalogs and edits entries via SchemaInspector.
- * Values persist on `document.catalogs` and undo with the same coalesce keys as meta patches.
+ * Gameplay data catalogs panel — lists merged (game-exported + document-authored) catalogs, lets an
+ * author create a brand-new document catalog, author its schema fields, and edit rows via
+ * SchemaInspector. Row values and (for document catalogs) the schema itself persist on
+ * `document.catalogs` and undo with the same coalesce keys as meta patches.
  * @internal — mounted by `EditorChrome` as a left-aside tab.
  */
 export function CatalogsPanel({ session, definitions, }) {
     const document = useStoreSelector(session, (state) => state.document);
     const [catalogId, setCatalogId] = useState(definitions[0]?.id ?? "");
     const [entryId, setEntryId] = useState(definitions[0]?.entries[0]?.id ?? "");
+    const [newRowId, setNewRowId] = useState("");
+    const [newCatalogId, setNewCatalogId] = useState("");
+    const [newCatalogLabel, setNewCatalogLabel] = useState("");
     const definition = useMemo(() => definitions.find((catalog) => catalog.id === catalogId) ?? definitions[0], [definitions, catalogId]);
+    const addCatalog = () => {
+        const id = slugifyEntryId(newCatalogId);
+        if (id.length === 0)
+            return;
+        const label = newCatalogLabel.trim();
+        session.dispatch({
+            type: "addCatalog",
+            id,
+            ...(label.length === 0 ? {} : { label }),
+            schema: { fields: [] },
+        });
+        setNewCatalogId("");
+        setNewCatalogLabel("");
+        setCatalogId(id);
+        setEntryId("");
+    };
+    const newCatalogForm = (_jsxs("form", { className: `flex flex-col gap-1 rounded-[6px] border ${BORDER} bg-white/[0.02] p-2`, onSubmit: (event) => {
+            event.preventDefault();
+            addCatalog();
+        }, children: [_jsx("span", { className: MICRO_LABEL, children: "New catalog" }), _jsxs("div", { className: "flex items-center gap-1", children: [_jsx("input", { className: `flex-1 ${INPUT}`, value: newCatalogId, placeholder: "catalog id (e.g. towers)", onChange: (event) => setNewCatalogId(event.target.value) }), _jsx("input", { className: `flex-1 ${INPUT}`, value: newCatalogLabel, placeholder: "label (optional)", onChange: (event) => setNewCatalogLabel(event.target.value) }), _jsx("button", { type: "submit", disabled: slugifyEntryId(newCatalogId).length === 0, className: BTN, children: "\uFF0B New catalog" })] })] }));
     if (definitions.length === 0) {
-        return (_jsx("div", { className: "flex min-h-0 flex-1 flex-col gap-2 p-2 text-[10px] text-neutral-500", children: "No gameplay catalogs. Export `editorCatalogs` from the game (ParamSchema + default entries)." }));
+        return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col gap-2 p-2", children: [_jsx("div", { className: "text-[10px] text-neutral-500", children: "No gameplay catalogs yet. Create one below, or export `editorCatalogs` from the game (ParamSchema + default entries)." }), newCatalogForm] }));
     }
     const activeDefinition = definition ?? definitions[0];
     const data = findEditorCatalog(document, activeDefinition.id);
     const entries = data?.entries ?? activeDefinition.entries;
     const activeEntryId = entries.some((entry) => entry.id === entryId) ? entryId : entries[0]?.id ?? "";
     const entry = findEditorCatalogEntry(document, activeDefinition.id, activeEntryId);
-    return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col gap-2 p-2", children: [_jsxs("label", { className: "flex items-center gap-2 text-[10px] text-neutral-400", children: [_jsx("span", { className: "shrink-0 uppercase tracking-wider text-neutral-500", children: "Catalog" }), _jsx("select", { className: "min-w-0 flex-1 rounded-md border border-white/10 bg-black/40 px-2 py-1 outline-none focus:border-cyan-400/60", value: activeDefinition.id, onChange: (event) => {
+    // A document-authored catalog carries its own schema — only those are schema-editable here.
+    // Game-exported catalogs keep their schema in code and stay read-only.
+    const documentSchema = data?.schema;
+    const addRow = () => {
+        const id = slugifyEntryId(newRowId);
+        if (id.length === 0)
+            return;
+        // Seed the new row from the schema defaults so it is immediately editable and schema-valid.
+        const meta = parseParams(activeDefinition.schema, undefined);
+        session.dispatch({ type: "addCatalogEntry", catalogId: activeDefinition.id, entry: { id, meta } });
+        setNewRowId("");
+        setEntryId(id);
+    };
+    const removeRow = (id) => {
+        session.dispatch({ type: "removeCatalogEntry", catalogId: activeDefinition.id, entryId: id });
+        if (entryId === id)
+            setEntryId("");
+    };
+    // Rebuilds the whole `fields` array and dispatches ONE setCatalogSchema; the reducer reclamps every
+    // row so the row list + SchemaInspector re-render against clamped values.
+    const commitFields = (fields) => {
+        if (documentSchema === undefined)
+            return;
+        const schema = { fields, ...(documentSchema.groups === undefined ? {} : { groups: documentSchema.groups }) };
+        session.dispatch({ type: "setCatalogSchema", id: activeDefinition.id, schema });
+    };
+    const schemaFields = documentSchema?.fields ?? [];
+    const patchField = (index, next) => {
+        commitFields(schemaFields.map((field, i) => (i === index ? next : field)));
+    };
+    const addField = () => {
+        let key = "field";
+        let n = 2;
+        const taken = new Set(schemaFields.map((field) => field.key));
+        while (taken.has(key)) {
+            key = `field_${n}`;
+            n += 1;
+        }
+        commitFields([...schemaFields, { key, type: "number", default: 0 }]);
+    };
+    const removeField = (index) => {
+        commitFields(schemaFields.filter((_, i) => i !== index));
+    };
+    return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col gap-2 p-2", children: [newCatalogForm, _jsxs("label", { className: "flex items-center gap-2 text-[10px] text-neutral-400", children: [_jsx("span", { className: "shrink-0 uppercase tracking-wider text-neutral-500", children: "Catalog" }), _jsx("select", { className: `min-w-0 flex-1 px-2 py-1 ${INPUT_CLS}`, value: activeDefinition.id, onChange: (event) => {
                             const next = definitions.find((catalog) => catalog.id === event.target.value);
                             setCatalogId(event.target.value);
                             setEntryId(next?.entries[0]?.id ?? "");
-                        }, children: definitions.map((catalog) => (_jsx("option", { value: catalog.id, children: catalog.label }, catalog.id))) })] }), _jsx("div", { className: "min-h-0 flex-1 space-y-1 overflow-auto pr-1", children: entries.map((row) => {
+                        }, children: definitions.map((catalog) => (_jsx("option", { value: catalog.id, children: catalog.label }, catalog.id))) }), documentSchema !== undefined ? (_jsx("button", { type: "button", className: `shrink-0 rounded-[5px] px-1.5 py-1 text-[11px] text-neutral-500 transition-colors hover:bg-rose-500/20 hover:text-rose-200 ${FOCUS_RING}`, title: `Remove catalog ${activeDefinition.id}`, "aria-label": `Remove catalog ${activeDefinition.id}`, onClick: () => {
+                            session.dispatch({ type: "removeCatalog", id: activeDefinition.id });
+                            setCatalogId("");
+                            setEntryId("");
+                        }, children: "\u00D7" })) : null] }), documentSchema !== undefined ? (_jsxs("div", { className: `flex flex-col gap-1 rounded-[6px] border ${BORDER} bg-white/[0.02] p-2`, children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: "Schema fields" }), schemaFields.map((field, index) => {
+                        const hasBounds = field.type === "range" || field.type === "number";
+                        const numberDefault = "default" in field && typeof field.default === "number" ? field.default : undefined;
+                        const min = "min" in field && typeof field.min === "number" ? field.min : undefined;
+                        const max = "max" in field && typeof field.max === "number" ? field.max : undefined;
+                        return (_jsxs("div", { className: "flex flex-wrap items-center gap-1", children: [_jsx("input", { className: `w-24 ${INPUT}`, value: field.key, placeholder: "key", onChange: (event) => patchField(index, { ...field, key: event.target.value }) }), _jsx("select", { className: `w-24 ${INPUT}`, value: field.type, onChange: (event) => patchField(index, coerceField(field, event.target.value)), children: FIELD_TYPES.map((type) => (_jsx("option", { value: type, children: type }, type))) }), numberDefault !== undefined ? (_jsx("input", { type: "number", className: `w-16 ${INPUT}`, value: numberDefault, title: "default", onChange: (event) => patchField(index, { ...field, default: Number(event.target.value) }) })) : field.type === "bool" ? (_jsx("input", { type: "checkbox", className: "accent-emerald-400", checked: field.default, title: "default", onChange: (event) => patchField(index, { ...field, default: event.target.checked }) })) : "default" in field && typeof field.default === "string" ? (_jsx("input", { className: `w-16 ${INPUT}`, value: field.default, title: "default", onChange: (event) => patchField(index, { ...field, default: event.target.value }) })) : null, hasBounds ? (_jsxs(_Fragment, { children: [_jsx("input", { type: "number", className: `w-14 ${INPUT}`, value: min ?? "", placeholder: "min", title: "min", onChange: (event) => {
+                                                const value = event.target.value;
+                                                const next = { ...field };
+                                                if (value === "")
+                                                    delete next.min;
+                                                else
+                                                    next.min = Number(value);
+                                                patchField(index, next);
+                                            } }), _jsx("input", { type: "number", className: `w-14 ${INPUT}`, value: max ?? "", placeholder: "max", title: "max", onChange: (event) => {
+                                                const value = event.target.value;
+                                                const next = { ...field };
+                                                if (value === "")
+                                                    delete next.max;
+                                                else
+                                                    next.max = Number(value);
+                                                patchField(index, next);
+                                            } })] })) : null, _jsx("button", { type: "button", className: `shrink-0 rounded-[5px] px-1.5 py-1 text-[11px] text-neutral-500 transition-colors hover:bg-rose-500/20 hover:text-rose-200 ${FOCUS_RING}`, title: `Remove field ${field.key}`, "aria-label": `Remove field ${field.key}`, onClick: () => removeField(index), children: "\u00D7" })] }, index));
+                    }), _jsx("button", { type: "button", className: BTN, onClick: addField, children: "+ Field" })] })) : null, _jsx("div", { className: "min-h-0 flex-1 space-y-1 overflow-auto pr-1", children: entries.map((row) => {
                     const selected = row.id === activeEntryId;
-                    return (_jsxs("button", { type: "button", className: `flex w-full items-center justify-between rounded-md px-2 py-1.5 text-left text-[11px] ring-1 ring-inset transition-colors ${selected
+                    return (_jsxs("div", { className: `flex items-center gap-1 rounded-md ring-1 ring-inset transition-colors ${selected
                             ? "bg-amber-500/15 text-amber-100 ring-amber-400/30"
-                            : "bg-white/[0.03] text-neutral-300 ring-white/[0.06] hover:bg-white/[0.06]"}`, onClick: () => setEntryId(row.id), children: [_jsx("span", { className: "truncate font-medium", children: row.label ?? row.id }), _jsx("span", { className: "ml-2 shrink-0 text-[9px] text-neutral-500", children: row.id })] }, row.id));
-                }) }), entry !== undefined ? (_jsx(SchemaInspector, { schema: activeDefinition.schema, label: entry.label ?? entry.id, accent: "#fbbf24", meta: entry.meta, onMeta: (patch, coalesce) => {
+                            : "bg-white/[0.03] text-neutral-300 ring-white/[0.06] hover:bg-white/[0.06]"}`, children: [_jsxs("button", { type: "button", className: "flex min-w-0 flex-1 items-center justify-between px-2 py-1.5 text-left text-[11px]", onClick: () => setEntryId(row.id), children: [_jsx("span", { className: "truncate font-medium", children: row.label ?? row.id }), _jsx("span", { className: "ml-2 shrink-0 text-[9px] text-neutral-500", children: row.id })] }), _jsx("button", { type: "button", className: `shrink-0 rounded-[5px] px-1.5 py-1 text-[11px] text-neutral-500 transition-colors hover:bg-rose-500/20 hover:text-rose-200 ${FOCUS_RING}`, title: `Remove ${row.id}`, "aria-label": `Remove ${row.id}`, onClick: () => removeRow(row.id), children: "\u00D7" })] }, row.id));
+                }) }), _jsxs("form", { className: "flex items-center gap-1", onSubmit: (event) => {
+                    event.preventDefault();
+                    addRow();
+                }, children: [_jsx("input", { className: `min-w-0 flex-1 px-2 py-1 text-[11px] ${INPUT_CLS}`, value: newRowId, placeholder: "new row id (e.g. goblin)", onChange: (event) => setNewRowId(event.target.value) }), _jsx("button", { type: "submit", disabled: slugifyEntryId(newRowId).length === 0, className: BTN, children: "+ Row" })] }), entry !== undefined ? (_jsx(SchemaInspector, { schema: activeDefinition.schema, label: entry.label ?? entry.id, accent: "#fbbf24", meta: entry.meta, onMeta: (patch, coalesce) => {
                     session.dispatch({
                         type: "setCatalogEntry",
                         catalogId: activeDefinition.id,

package/dist/CityPreview.d.ts

@@ -0,0 +1,11 @@
+import type { EditorHostApi } from "./session.js";
+/**
+ * Live edit-mode preview of every `city` district volume, so slider drags (grid-ness, curviness,
+ * branching, block size, …) re-synthesize streets/buildings/parks in the viewport without entering
+ * play mode. Mounts the exact runtime renderer the shell registers for the kind — the preview IS the
+ * game's rendering, grounded on the sculpt terrain (or the game's ground) like {@link ScatterPreview}.
+ * @internal — mounted by `EditorApp`; not a game-author entry point.
+ */
+export declare const CityPreview: import("react").MemoExoticComponent<({ api }: {
+    api: EditorHostApi;
+}) => import("react").JSX.Element | null>;

package/dist/CityPreview.js

@@ -0,0 +1,45 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { memo, useMemo } from "react";
+import { CITY_KIND } from "@jgengine/core/world/cityKind";
+import { editableTerrainFromSnapshot } from "@jgengine/core/world/terraform";
+import { useGameContext } from "@jgengine/react/provider";
+import { registerBuiltinSceneKindRenderers } from "@jgengine/shell/scene/builtinSceneKindRenderers";
+import { getSceneKindRenderer } from "@jgengine/shell/scene/sceneKindRenderers";
+import { useStoreSelector } from "./useStoreSelector.js";
+/**
+ * Live edit-mode preview of every `city` district volume, so slider drags (grid-ness, curviness,
+ * branching, block size, …) re-synthesize streets/buildings/parks in the viewport without entering
+ * play mode. Mounts the exact runtime renderer the shell registers for the kind — the preview IS the
+ * game's rendering, grounded on the sculpt terrain (or the game's ground) like {@link ScatterPreview}.
+ * @internal — mounted by `EditorApp`; not a game-author entry point.
+ */
+export const CityPreview = memo(function CityPreview({ api }) {
+    registerBuiltinSceneKindRenderers();
+    const ctx = useGameContext();
+    const session = api.getSession();
+    const volumes = useStoreSelector(session, (state) => state.document.volumes);
+    const snapshot = useStoreSelector(session, (state) => state.document.terrain ?? null);
+    const baseGround = ctx.world.ground;
+    const field = useMemo(() => {
+        if (snapshot !== null) {
+            const editable = editableTerrainFromSnapshot(snapshot, baseGround);
+            return { ...baseGround, sampleHeight: editable.sampleHeight, sampleNormal: editable.sampleNormal };
+        }
+        return baseGround;
+    }, [snapshot, baseGround]);
+    const objects = useMemo(() => volumes
+        .filter((volume) => volume.kind === CITY_KIND)
+        .map((volume) => ({
+        id: volume.id,
+        kind: volume.kind,
+        center: volume.center,
+        ...(volume.halfExtents === undefined ? {} : { halfExtents: volume.halfExtents }),
+        ...(volume.radius === undefined ? {} : { radius: volume.radius }),
+        ...(volume.meta === undefined ? {} : { meta: volume.meta }),
+    })), [volumes]);
+    const renderer = getSceneKindRenderer(CITY_KIND);
+    const document = useStoreSelector(session, (state) => state.document);
+    if (renderer === undefined || objects.length === 0)
+        return null;
+    return _jsx(_Fragment, { children: renderer({ objects, context: { document, field } }) });
+});

package/dist/CollectionsPanel.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
+import { CONTROL, FOCUS_RING, INPUT_CLS, MICRO_LABEL } from "./shell/theme.js";
 import { shallowArrayEqual, useStoreSelector } from "./useStoreSelector.js";
-const INPUT = "rounded-md border border-white/10 bg-black/40 px-2 py-1 outline-none transition-colors placeholder:text-neutral-600 focus:border-cyan-400/60 focus:bg-black/60";
-const BTN = "rounded-md bg-white/[0.04] 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";
-const CHIP_BTN = "rounded-md px-1.5 py-0.5 text-[10px] ring-1 ring-inset transition-colors";
+const BTN = `${CONTROL} px-2 py-1 text-[11px] disabled:opacity-40`;
+const CHIP_BTN = `rounded-[4px] px-1.5 py-0.5 text-[10px] ring-1 ring-inset transition-colors ${FOCUS_RING}`;
 function newCollectionId() {
     return `col_${Date.now().toString(36)}_${Math.floor(Math.random() * 1296).toString(36)}`;
 }
@@ -25,11 +25,11 @@ export function CollectionsPanel({ session }) {
         session.dispatch({ type: "createCollection", id: newCollectionId(), name: trimmed, memberIds: selection });
         setName("");
     };
-    return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col gap-2 p-2", children: [_jsxs("div", { className: "flex gap-1", children: [_jsx("input", { className: `min-w-0 flex-1 ${INPUT}`, placeholder: "New collection name\u2026", value: name, onChange: (event) => setName(event.target.value), onKeyDown: (event) => {
+    return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col gap-2 p-2", children: [_jsx("div", { className: MICRO_LABEL, children: "Collections" }), _jsxs("div", { className: "flex gap-1", children: [_jsx("input", { className: `h-7 min-w-0 flex-1 px-2 ${INPUT_CLS}`, placeholder: "New collection name\u2026", value: name, onChange: (event) => setName(event.target.value), onKeyDown: (event) => {
                             if (event.key === "Enter")
                                 createFromSelection();
                         } }), _jsx("button", { type: "button", className: BTN, disabled: selection.length === 0 || name.trim().length === 0, onClick: createFromSelection, children: "From selection" })] }), selection.length === 0 ? (_jsx("div", { className: "text-[10px] text-neutral-500", children: "Select objects first, then name and save a set." })) : null, _jsx("div", { className: "min-h-0 flex-1 space-y-1 overflow-auto pr-1", children: collections.length === 0 ? (_jsx("div", { className: "text-neutral-600", children: "No collections yet." })) : (collections.map((collection) => (_jsx(CollectionRow, { session: session, collection: collection, selection: selection }, collection.id)))) })] }));
 }
 function CollectionRow({ session, collection, selection, }) {
-    return (_jsxs("div", { className: "space-y-1 rounded-md bg-white/[0.03] p-1.5 ring-1 ring-inset ring-white/[0.06]", children: [_jsxs("div", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "h-2.5 w-2.5 shrink-0 rounded-full ring-1 ring-inset ring-white/20", style: { backgroundColor: collection.color ?? "#64748b" } }), _jsx("button", { type: "button", className: "min-w-0 flex-1 truncate text-left text-neutral-200 hover:text-cyan-200", title: "Restore selection", onClick: () => session.dispatch({ type: "selectCollection", id: collection.id }), children: collection.name }), _jsx("span", { className: "text-neutral-500", children: collection.memberIds.length })] }), _jsxs("div", { className: "flex flex-wrap gap-1", children: [_jsx("button", { type: "button", className: `${CHIP_BTN} ${collection.locked === true ? "bg-amber-500/20 text-amber-200 ring-amber-400/30" : "bg-black/30 text-neutral-400 ring-white/[0.06] hover:text-neutral-200"}`, onClick: () => session.dispatch({ type: "setCollectionFlags", id: collection.id, patch: { locked: collection.locked !== true } }), children: collection.locked === true ? "🔒 locked" : "🔓 lock" }), _jsx("button", { type: "button", className: `${CHIP_BTN} ${collection.visible === false ? "bg-black/30 text-neutral-500 ring-white/[0.06]" : "bg-cyan-500/15 text-cyan-200 ring-cyan-400/25"}`, onClick: () => session.dispatch({ type: "setCollectionFlags", id: collection.id, patch: { visible: collection.visible === false } }), children: collection.visible === false ? "hidden" : "visible" }), _jsx("label", { className: "flex items-center gap-1 rounded-md bg-black/30 px-1.5 py-0.5 ring-1 ring-inset ring-white/[0.06]", children: _jsx("input", { type: "color", className: "h-3 w-4 cursor-pointer border-none bg-transparent p-0", value: collection.color ?? "#64748b", onChange: (event) => session.dispatch({ type: "setCollectionFlags", id: collection.id, patch: { color: event.target.value } }) }) }), _jsx("button", { type: "button", className: `${CHIP_BTN} bg-black/30 text-neutral-400 ring-white/[0.06] hover:text-neutral-200 disabled:opacity-30`, disabled: selection.length === 0, onClick: () => session.dispatch({ type: "addToCollection", id: collection.id, ids: selection }), children: "+ add selected" }), _jsx("button", { type: "button", className: `${CHIP_BTN} bg-black/30 text-neutral-400 ring-white/[0.06] hover:text-neutral-200 disabled:opacity-30`, disabled: selection.length === 0, onClick: () => session.dispatch({ type: "removeFromCollection", id: collection.id, ids: selection }), children: "\u2212 remove selected" }), _jsx("button", { type: "button", className: `${CHIP_BTN} ml-auto bg-rose-500/15 text-rose-200 ring-rose-400/25 hover:bg-rose-500/25`, onClick: () => session.dispatch({ type: "deleteCollection", id: collection.id }), children: "Delete" })] })] }));
+    return (_jsxs("div", { className: "space-y-1.5 rounded-[6px] border border-white/[0.07] bg-white/[0.02] p-2", children: [_jsxs("div", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "h-2.5 w-2.5 shrink-0 rounded-full ring-1 ring-inset ring-white/20", style: { backgroundColor: collection.color ?? "#64748b" } }), _jsx("button", { type: "button", className: `min-w-0 flex-1 truncate text-left text-[12px] text-neutral-200 hover:text-cyan-200 ${FOCUS_RING}`, title: "Restore selection", onClick: () => session.dispatch({ type: "selectCollection", id: collection.id }), children: collection.name }), _jsx("span", { className: "text-[10px] tabular-nums text-neutral-500", children: collection.memberIds.length })] }), _jsxs("div", { className: "flex flex-wrap gap-1", children: [_jsx("button", { type: "button", className: `${CHIP_BTN} ${collection.locked === true ? "bg-amber-500/20 text-amber-200 ring-amber-400/30" : "bg-black/30 text-neutral-400 ring-white/[0.06] hover:text-neutral-200"}`, onClick: () => session.dispatch({ type: "setCollectionFlags", id: collection.id, patch: { locked: collection.locked !== true } }), children: collection.locked === true ? "🔒 locked" : "🔓 lock" }), _jsx("button", { type: "button", className: `${CHIP_BTN} ${collection.visible === false ? "bg-black/30 text-neutral-500 ring-white/[0.06]" : "bg-cyan-500/15 text-cyan-200 ring-cyan-400/25"}`, onClick: () => session.dispatch({ type: "setCollectionFlags", id: collection.id, patch: { visible: collection.visible === false } }), children: collection.visible === false ? "hidden" : "visible" }), _jsx("label", { className: "flex items-center gap-1 rounded-md bg-black/30 px-1.5 py-0.5 ring-1 ring-inset ring-white/[0.06]", children: _jsx("input", { type: "color", className: "h-3 w-4 cursor-pointer border-none bg-transparent p-0", value: collection.color ?? "#64748b", onChange: (event) => session.dispatch({ type: "setCollectionFlags", id: collection.id, patch: { color: event.target.value } }) }) }), _jsx("button", { type: "button", className: `${CHIP_BTN} bg-black/30 text-neutral-400 ring-white/[0.06] hover:text-neutral-200 disabled:opacity-30`, disabled: selection.length === 0, onClick: () => session.dispatch({ type: "addToCollection", id: collection.id, ids: selection }), children: "+ add selected" }), _jsx("button", { type: "button", className: `${CHIP_BTN} bg-black/30 text-neutral-400 ring-white/[0.06] hover:text-neutral-200 disabled:opacity-30`, disabled: selection.length === 0, onClick: () => session.dispatch({ type: "removeFromCollection", id: collection.id, ids: selection }), children: "\u2212 remove selected" }), _jsx("button", { type: "button", className: `${CHIP_BTN} ml-auto bg-rose-500/15 text-rose-200 ring-rose-400/25 hover:bg-rose-500/25`, onClick: () => session.dispatch({ type: "deleteCollection", id: collection.id }), children: "Delete" })] })] }));
 }

package/dist/DebugDraw.d.ts

@@ -4,10 +4,12 @@ export declare function PathDraftPreview({ points }: {
     points: readonly EditorVec3[];
 }): import("react").JSX.Element;
 /** Renders every visible marker, volume, path, and note from a document as in-scene 3D gizmos. */
-export declare function EditorLayerOverlays({ document, visibility, selection, onSelect, activePathPoint, groundHeightAt, }: {
+export declare function EditorLayerOverlays({ document, visibility, selection, hoverId, onSelect, activePathPoint, groundHeightAt, }: {
     document: EditorDocument;
     visibility: EditorKindVisibility;
     selection: readonly string[];
+    /** Pre-selection hover id from viewport pointer pick; ignored when already selected. */
+    hoverId?: string | null;
     onSelect: (id: string) => void;
     activePathPoint?: {
         pathId: string;