@jgengine/core 0.11.0 → 0.12.0

package/dist/editor/document.js

@@ -1,6 +1,47 @@
 import { cloneEditorUiDocument, decodeEditorUiDocument } from "../ui/hudDocument.js";
 import { migrateTerrainSnapshot } from "../world/terraform.js";
 import { cloneGridLayer, migrateGridLayer, } from "./grid.js";
+/** Copies a baked minimap so a document's PNG + bounds are never shared by reference across rebuilds. */
+function cloneMinimapBake(minimap) {
+    return { background: minimap.background, bounds: { ...minimap.bounds } };
+}
+/** Deep-copies scene-document environment/lighting so edits never mutate history snapshots. */
+function cloneEnvironment(environment) {
+    return {
+        ...(environment.preset === undefined ? {} : { preset: environment.preset }),
+        ...(environment.timeOfDay === undefined ? {} : { timeOfDay: environment.timeOfDay }),
+        ...(environment.horizonColor === undefined ? {} : { horizonColor: environment.horizonColor }),
+        ...(environment.zenithColor === undefined ? {} : { zenithColor: environment.zenithColor }),
+        ...(environment.sunIntensity === undefined ? {} : { sunIntensity: environment.sunIntensity }),
+        ...(environment.ambientIntensity === undefined ? {} : { ambientIntensity: environment.ambientIntensity }),
+        ...(environment.fog === undefined ? {} : { fog: { ...environment.fog } }),
+    };
+}
+function cloneDirective(directive) {
+    const area = directive.area === undefined
+        ? undefined
+        : { min: [...directive.area.min], max: [...directive.area.max] };
+    const base = {
+        id: directive.id,
+        ...(directive.region === undefined ? {} : { region: directive.region }),
+        ...(area === undefined ? {} : { area }),
+        ...(directive.seed === undefined ? {} : { seed: directive.seed }),
+        ...(directive.meta === undefined ? {} : { meta: { ...directive.meta } }),
+    };
+    if (directive.kind === "scatter") {
+        return { ...base, kind: "scatter", asset: directive.asset, density: directive.density,
+            ...(directive.minSpacing === undefined ? {} : { minSpacing: directive.minSpacing }),
+            ...(directive.jitter === undefined ? {} : { jitter: directive.jitter }),
+            ...(directive.minScale === undefined ? {} : { minScale: directive.minScale }),
+            ...(directive.maxScale === undefined ? {} : { maxScale: directive.maxScale }),
+            ...(directive.minYaw === undefined ? {} : { minYaw: directive.minYaw }),
+            ...(directive.maxYaw === undefined ? {} : { maxYaw: directive.maxYaw }) };
+    }
+    return { ...base, kind: "population", species: directive.species.map((s) => ({ ...s })) };
+}
+function cloneDirectives(directives) {
+    return directives === undefined ? undefined : directives.map(cloneDirective);
+}
 function migrateGrids(grids) {
     return grids === undefined ? undefined : grids.map(migrateGridLayer);
 }
@@ -23,6 +64,9 @@ export function editorDocumentExtras(doc) {
         ...(doc.grids === undefined ? {} : { grids: doc.grids }),
         ...(doc.terrain === undefined ? {} : { terrain: doc.terrain }),
         ...(doc.ui === undefined ? {} : { ui: doc.ui }),
+        ...(doc.directives === undefined ? {} : { directives: doc.directives }),
+        ...(doc.minimap === undefined ? {} : { minimap: doc.minimap }),
+        ...(doc.environment === undefined ? {} : { environment: doc.environment }),
     };
 }
 /** Builds a fresh, empty editor document to start authoring a scene from scratch.
@@ -50,6 +94,8 @@ function cloneCatalogEntry(entry) {
 function cloneCatalogs(catalogs) {
     return (catalogs ?? []).map((catalog) => ({
         id: catalog.id,
+        ...(catalog.label === undefined ? {} : { label: catalog.label }),
+        ...(catalog.schema === undefined ? {} : { schema: catalog.schema }),
         entries: catalog.entries.map(cloneCatalogEntry),
     }));
 }
@@ -61,6 +107,7 @@ function cloneCatalogs(catalogs) {
   */
 export function cloneEditorDocument(doc) {
     const ui = cloneEditorUiDocument(doc.ui);
+    const directives = cloneDirectives(doc.directives);
     return {
         version: 1,
         markers: doc.markers.map((marker) => ({
@@ -98,6 +145,9 @@ export function cloneEditorDocument(doc) {
         ...(doc.grids === undefined ? {} : { grids: doc.grids.map(cloneGridLayer) }),
         ...(doc.terrain === undefined ? {} : { terrain: doc.terrain }),
         ...(ui === undefined ? {} : { ui }),
+        ...(directives === undefined ? {} : { directives }),
+        ...(doc.minimap === undefined ? {} : { minimap: cloneMinimapBake(doc.minimap) }),
+        ...(doc.environment === undefined ? {} : { environment: cloneEnvironment(doc.environment) }),
     };
 }
 function asArray(value) {
@@ -107,11 +157,24 @@ function upsertCatalogEntries(base, overlay) {
     return upsertById(base.map(cloneCatalogEntry), overlay.map(cloneCatalogEntry));
 }
 function upsertCatalogs(base, overlay) {
-    const byId = new Map((base ?? []).map((catalog) => [catalog.id, { id: catalog.id, entries: catalog.entries.map(cloneCatalogEntry) }]));
+    const byId = new Map((base ?? []).map((catalog) => [
+        catalog.id,
+        {
+            id: catalog.id,
+            ...(catalog.label === undefined ? {} : { label: catalog.label }),
+            ...(catalog.schema === undefined ? {} : { schema: catalog.schema }),
+            entries: catalog.entries.map(cloneCatalogEntry),
+        },
+    ]));
     for (const catalog of overlay ?? []) {
         const existing = byId.get(catalog.id);
+        // Overlay schema/label win when present; otherwise keep whatever the base carried.
+        const label = catalog.label ?? existing?.label;
+        const schema = catalog.schema ?? existing?.schema;
         byId.set(catalog.id, {
             id: catalog.id,
+            ...(label === undefined ? {} : { label }),
+            ...(schema === undefined ? {} : { schema }),
             entries: existing === undefined ? catalog.entries.map(cloneCatalogEntry) : upsertCatalogEntries(existing.entries, catalog.entries),
         });
     }
@@ -125,6 +188,8 @@ export function normalizeEditorLayers(input) {
         return createEmptyEditorDocument();
     const resolved = typeof input === "function" ? input() : input;
     const ui = cloneEditorUiDocument(resolved.ui);
+    const grids = migrateGrids(resolved.grids);
+    const directives = cloneDirectives(resolved.directives);
     return {
         version: 1,
         markers: asArray(resolved.markers),
@@ -134,9 +199,12 @@ export function normalizeEditorLayers(input) {
         prefabs: asArray(resolved.prefabs),
         collections: asArray(resolved.collections),
         catalogs: cloneCatalogs(resolved.catalogs),
-        ...(migrateGrids(resolved.grids) === undefined ? {} : { grids: migrateGrids(resolved.grids) }),
+        ...(grids === undefined ? {} : { grids }),
         ...(resolved.terrain === undefined ? {} : { terrain: migrateTerrainSnapshot(resolved.terrain) }),
         ...(ui === undefined ? {} : { ui }),
+        ...(directives === undefined ? {} : { directives }),
+        ...(resolved.minimap === undefined ? {} : { minimap: cloneMinimapBake(resolved.minimap) }),
+        ...(resolved.environment === undefined ? {} : { environment: cloneEnvironment(resolved.environment) }),
     };
 }
 /**
@@ -186,6 +254,13 @@ export function mergeEditorDocuments(...docs) {
             out.grids = mergedGrids;
         if (doc.terrain !== undefined)
             out.terrain = doc.terrain;
+        if (doc.minimap !== undefined)
+            out.minimap = cloneMinimapBake(doc.minimap);
+        if (doc.environment !== undefined)
+            out.environment = cloneEnvironment(doc.environment);
+        if (doc.directives !== undefined) {
+            out.directives = upsertById(out.directives ?? [], doc.directives);
+        }
         if (doc.ui !== undefined) {
             out.ui = {
                 panels: {
@@ -264,6 +339,8 @@ export function seedEditorCatalogs(doc, definitions) {
         }
         const catalog = {
             id: definition.id,
+            ...(existing?.label === undefined ? {} : { label: existing.label }),
+            ...(existing?.schema === undefined ? {} : { schema: existing.schema }),
             entries: [...byId.values()],
         };
         if (existingIndex >= 0)
@@ -273,12 +350,57 @@ export function seedEditorCatalogs(doc, definitions) {
     }
     return { ...doc, catalogs: next };
 }
-/** True when an object id is a member of any locked collection — blocks move/delete on it.
+/**
+ * True when an object carries a per-object `locked` flag (hierarchy lock toggle).
+ * Collection membership is checked separately by {@link isEditorObjectLocked}.
  * @internal
  */
-export function isEditorObjectLocked(doc, id) {
+export function isEditorObjectSelfLocked(doc, id) {
+    const marker = doc.markers.find((entry) => entry.id === id);
+    if (marker !== undefined)
+        return marker.locked === true;
+    const volume = doc.volumes.find((entry) => entry.id === id);
+    if (volume !== undefined)
+        return volume.locked === true;
+    const path = doc.paths.find((entry) => entry.id === id);
+    if (path !== undefined)
+        return path.locked === true;
+    const note = doc.annotations.find((entry) => entry.id === id);
+    return note?.locked === true;
+}
+/**
+ * True when an object is a member of any locked collection (production group lock).
+ * @internal
+ */
+export function isEditorObjectCollectionLocked(doc, id) {
     return doc.collections.some((collection) => collection.locked === true && collection.memberIds.includes(id));
 }
+/**
+ * True when an object id is locked for edit — either its own `locked` flag or membership in a
+ * locked collection. Blocks move/delete via session mutations.
+ * @internal
+ */
+export function isEditorObjectLocked(doc, id) {
+    return isEditorObjectSelfLocked(doc, id) || isEditorObjectCollectionLocked(doc, id);
+}
+/**
+ * True when an object carries `hidden: true` — omitted from editor viewport overlays and picking
+ * while remaining in the hierarchy and document.
+ * @internal
+ */
+export function isEditorObjectHidden(doc, id) {
+    const marker = doc.markers.find((entry) => entry.id === id);
+    if (marker !== undefined)
+        return marker.hidden === true;
+    const volume = doc.volumes.find((entry) => entry.id === id);
+    if (volume !== undefined)
+        return volume.hidden === true;
+    const path = doc.paths.find((entry) => entry.id === id);
+    if (path !== undefined)
+        return path.hidden === true;
+    const note = doc.annotations.find((entry) => entry.id === id);
+    return note?.hidden === true;
+}
 /**
  * Extracts the selected ids into a prefab fragment centered on their own bounds centroid, so the
  * same prefab reinserts consistently regardless of where in the scene (or which game) it lands.
@@ -312,6 +434,29 @@ export function createPrefabFragment(doc, ids) {
 export function findEditorMarker(doc, id) {
     return doc.markers.find((marker) => marker.id === id);
 }
+/** Looks up a marker by id and throws when it is absent — for scene contracts where a
+ * missing marker is an authoring error to surface loudly, not a runtime branch to handle.
+ * @internal
+ */
+export function requireEditorMarker(doc, id) {
+    const marker = findEditorMarker(doc, id);
+    if (marker === undefined) {
+        throw new Error(`editor document has no marker with id "${id}"`);
+    }
+    return marker;
+}
+/** A marker's world position as an `[x, y, z]` tuple — the shared shape gameplay tables read.
+ * @internal
+ */
+export function editorMarkerPosition(marker) {
+    return [marker.position.x, marker.position.y, marker.position.z];
+}
+/** A marker's ground position as an `[x, z]` tuple, dropping the vertical axis.
+ * @internal
+ */
+export function editorMarkerXZ(marker) {
+    return [marker.position.x, marker.position.z];
+}
 /** Looks up a volume by id in an editor document.
  * @internal
  */
@@ -475,6 +620,10 @@ function decodeMarker(item, path, errors) {
         marker.catalogId = item.catalogId;
     if (typeof item.parentId === "string")
         marker.parentId = item.parentId;
+    if (typeof item.locked === "boolean")
+        marker.locked = item.locked;
+    if (typeof item.hidden === "boolean")
+        marker.hidden = item.hidden;
     const meta = decodeMeta(item.meta, `${path}.meta`, errors);
     if (meta !== undefined)
         marker.meta = meta;
@@ -512,6 +661,10 @@ function decodeVolume(item, path, errors) {
         volume.label = item.label;
     if (typeof item.parentId === "string")
         volume.parentId = item.parentId;
+    if (typeof item.locked === "boolean")
+        volume.locked = item.locked;
+    if (typeof item.hidden === "boolean")
+        volume.hidden = item.hidden;
     const meta = decodeMeta(item.meta, `${path}.meta`, errors);
     if (meta !== undefined)
         volume.meta = meta;
@@ -543,6 +696,10 @@ function decodePath(item, path, errors) {
         decodedPath.label = item.label;
     if (typeof item.parentId === "string")
         decodedPath.parentId = item.parentId;
+    if (typeof item.locked === "boolean")
+        decodedPath.locked = item.locked;
+    if (typeof item.hidden === "boolean")
+        decodedPath.hidden = item.hidden;
     const meta = decodeMeta(item.meta, `${path}.meta`, errors);
     if (meta !== undefined)
         decodedPath.meta = meta;
@@ -565,6 +722,10 @@ function decodeNote(item, path, errors) {
         note.color = item.color;
     if (typeof item.parentId === "string")
         note.parentId = item.parentId;
+    if (typeof item.locked === "boolean")
+        note.locked = item.locked;
+    if (typeof item.hidden === "boolean")
+        note.hidden = item.hidden;
     const meta = decodeMeta(item.meta, `${path}.meta`, errors);
     if (meta !== undefined)
         note.meta = meta;
@@ -645,6 +806,30 @@ function decodeCatalogEntry(item, path, errors) {
         entry.meta = meta;
     return entry;
 }
+/**
+ * Decodes a document-carried `ParamSchema` (`{ fields: ParamField[] }`) — modeled on
+ * `loadGameCatalogs`'s `decodeSchema`. Any field that is not a plain object with string `key` and
+ * `type` is dropped with a diagnostic instead of poisoning the whole schema; a non-array `fields`
+ * value drops the schema entirely (undefined). Structural but permissive: field-shape validation
+ * beyond key/type is left to `parseParams`, which defaults anything it cannot read.
+ */
+function decodeParamSchema(raw, path, errors) {
+    if (raw === undefined)
+        return undefined;
+    if (!isPlainObject(raw) || !Array.isArray(raw.fields)) {
+        errors.push({ path, message: "expected { fields: ParamField[] }" });
+        return undefined;
+    }
+    const fields = [];
+    raw.fields.forEach((field, index) => {
+        if (!isPlainObject(field) || typeof field.key !== "string" || typeof field.type !== "string") {
+            errors.push({ path: `${path}.fields[${index}]`, message: "expected a ParamField with string key + type" });
+            return;
+        }
+        fields.push(field);
+    });
+    return { fields, ...(Array.isArray(raw.groups) ? { groups: raw.groups } : {}) };
+}
 function decodeCatalog(item, path, errors) {
     if (!isPlainObject(item)) {
         errors.push({ path, message: "expected an object" });
@@ -655,7 +840,203 @@ function decodeCatalog(item, path, errors) {
         return null;
     }
     const entries = decodeArray(item.entries, `${path}.entries`, decodeCatalogEntry, errors);
-    return { id: item.id, entries };
+    const schema = decodeParamSchema(item.schema, `${path}.schema`, errors);
+    const catalog = { id: item.id, entries };
+    if (typeof item.label === "string")
+        catalog.label = item.label;
+    if (schema !== undefined)
+        catalog.schema = schema;
+    return catalog;
+}
+function decodeDirectiveArea(value, path, errors) {
+    if (value === undefined)
+        return undefined;
+    if (!isPlainObject(value)) {
+        errors.push({ path, message: "expected an object" });
+        return undefined;
+    }
+    const pair = (v, p) => {
+        if (!Array.isArray(v) || v.length !== 2 || typeof v[0] !== "number" || typeof v[1] !== "number") {
+            errors.push({ path: p, message: "expected [number, number]" });
+            return null;
+        }
+        return [v[0], v[1]];
+    };
+    const min = pair(value.min, `${path}.min`);
+    const max = pair(value.max, `${path}.max`);
+    if (min === null || max === null)
+        return undefined;
+    return { min, max };
+}
+function decodeSpecies(item, path, errors) {
+    if (!isPlainObject(item)) {
+        errors.push({ path, message: "expected an object" });
+        return null;
+    }
+    if (typeof item.id !== "string")
+        errors.push({ path: `${path}.id`, message: "expected a string" });
+    if (typeof item.cap !== "number")
+        errors.push({ path: `${path}.cap`, message: "expected a number" });
+    if (typeof item.id !== "string" || typeof item.cap !== "number")
+        return null;
+    const species = { id: item.id, cap: item.cap };
+    if (typeof item.weight === "number")
+        species.weight = item.weight;
+    return species;
+}
+function decodeDirective(item, path, errors) {
+    if (!isPlainObject(item)) {
+        errors.push({ path, message: "expected an object" });
+        return null;
+    }
+    if (typeof item.id !== "string")
+        errors.push({ path: `${path}.id`, message: "expected a string" });
+    const kindOk = item.kind === "scatter" || item.kind === "population";
+    if (!kindOk)
+        errors.push({ path: `${path}.kind`, message: "expected \"scatter\" | \"population\"" });
+    const area = decodeDirectiveArea(item.area, `${path}.area`, errors);
+    if (typeof item.id !== "string" || !kindOk)
+        return null;
+    const base = {
+        id: item.id,
+        ...(typeof item.region === "string" ? { region: item.region } : {}),
+        ...(area === undefined ? {} : { area }),
+        ...(typeof item.seed === "string" || typeof item.seed === "number" ? { seed: item.seed } : {}),
+        ...(isPlainObject(item.meta) ? { meta: item.meta } : {}),
+    };
+    if (item.kind === "scatter") {
+        if (typeof item.asset !== "string")
+            errors.push({ path: `${path}.asset`, message: "expected a string" });
+        if (typeof item.density !== "number")
+            errors.push({ path: `${path}.density`, message: "expected a number" });
+        if (typeof item.asset !== "string" || typeof item.density !== "number")
+            return null;
+        const scatter = { ...base, kind: "scatter", asset: item.asset, density: item.density };
+        for (const key of ["minSpacing", "jitter", "minScale", "maxScale", "minYaw", "maxYaw"]) {
+            if (typeof item[key] === "number")
+                scatter[key] = item[key];
+        }
+        return scatter;
+    }
+    const species = decodeArray(item.species, `${path}.species`, decodeSpecies, errors);
+    return { ...base, kind: "population", species };
+}
+/**
+ * Validates a baked minimap arriving from outside this process: `background` must be a
+ * `data:image/…` URI and `bounds` must be four finite numbers, so a malformed bake is rejected with a
+ * path-specific diagnostic instead of feeding a broken `<image href>` to the runtime minimap.
+ */
+function decodeMinimapBake(value, path, errors) {
+    if (!isPlainObject(value)) {
+        errors.push({ path, message: "expected an object" });
+        return undefined;
+    }
+    const backgroundOk = typeof value.background === "string" && value.background.startsWith("data:image/");
+    if (!backgroundOk) {
+        errors.push({ path: `${path}.background`, message: "expected a data:image/… string" });
+    }
+    const bounds = value.bounds;
+    const boundsOk = isPlainObject(bounds) &&
+        ["minX", "minZ", "maxX", "maxZ"].every((key) => typeof bounds[key] === "number" && Number.isFinite(bounds[key]));
+    if (!boundsOk) {
+        errors.push({ path: `${path}.bounds`, message: "expected {minX,minZ,maxX,maxZ} finite numbers" });
+    }
+    if (!backgroundOk || !boundsOk)
+        return undefined;
+    const b = bounds;
+    return {
+        background: value.background,
+        bounds: { minX: b.minX, minZ: b.minZ, maxX: b.maxX, maxZ: b.maxZ },
+    };
+}
+const SKY_PRESETS = new Set(["day", "dusk", "night"]);
+/**
+ * Validates scene-document environment/lighting. Unknown presets, non-finite intensities, and
+ * malformed fog objects produce path-specific diagnostics; empty valid objects are accepted so a
+ * game can seed `environment: {}` as "use engine defaults, ready to author".
+ */
+function decodeEnvironment(value, path, errors) {
+    if (!isPlainObject(value)) {
+        errors.push({ path, message: "expected an object" });
+        return undefined;
+    }
+    let failed = false;
+    const env = {};
+    if (value.preset !== undefined) {
+        if (typeof value.preset === "string" && SKY_PRESETS.has(value.preset)) {
+            env.preset = value.preset;
+        }
+        else {
+            errors.push({ path: `${path}.preset`, message: 'expected "day" | "dusk" | "night"' });
+            failed = true;
+        }
+    }
+    if (value.timeOfDay !== undefined) {
+        if (typeof value.timeOfDay === "boolean")
+            env.timeOfDay = value.timeOfDay;
+        else {
+            errors.push({ path: `${path}.timeOfDay`, message: "expected a boolean" });
+            failed = true;
+        }
+    }
+    if (value.horizonColor !== undefined) {
+        if (typeof value.horizonColor === "string")
+            env.horizonColor = value.horizonColor;
+        else {
+            errors.push({ path: `${path}.horizonColor`, message: "expected a string" });
+            failed = true;
+        }
+    }
+    if (value.zenithColor !== undefined) {
+        if (typeof value.zenithColor === "string")
+            env.zenithColor = value.zenithColor;
+        else {
+            errors.push({ path: `${path}.zenithColor`, message: "expected a string" });
+            failed = true;
+        }
+    }
+    for (const key of ["sunIntensity", "ambientIntensity"]) {
+        if (value[key] === undefined)
+            continue;
+        if (typeof value[key] === "number" && Number.isFinite(value[key]))
+            env[key] = value[key];
+        else {
+            errors.push({ path: `${path}.${key}`, message: "expected a finite number" });
+            failed = true;
+        }
+    }
+    if (value.fog !== undefined) {
+        if (!isPlainObject(value.fog)) {
+            errors.push({ path: `${path}.fog`, message: "expected an object" });
+            failed = true;
+        }
+        else {
+            const fog = {};
+            if (value.fog.color !== undefined) {
+                if (typeof value.fog.color === "string")
+                    fog.color = value.fog.color;
+                else {
+                    errors.push({ path: `${path}.fog.color`, message: "expected a string" });
+                    failed = true;
+                }
+            }
+            for (const key of ["near", "far"]) {
+                if (value.fog[key] === undefined)
+                    continue;
+                if (typeof value.fog[key] === "number" && Number.isFinite(value.fog[key]))
+                    fog[key] = value.fog[key];
+                else {
+                    errors.push({ path: `${path}.fog.${key}`, message: "expected a finite number" });
+                    failed = true;
+                }
+            }
+            if (Object.keys(fog).length > 0)
+                env.fog = fog;
+        }
+    }
+    if (failed)
+        return undefined;
+    return env;
 }
 const GRID_AXES = new Set(["xz", "xy"]);
 function decodeGridPaletteEntry(item, path, errors) {
@@ -766,9 +1147,33 @@ export function decodeEditorDocument(raw) {
     const collections = decodeArray(raw.collections, "$.collections", decodeCollection, errors);
     const catalogs = decodeArray(raw.catalogs, "$.catalogs", decodeCatalog, errors);
     const grids = raw.grids === undefined ? undefined : decodeArray(raw.grids, "$.grids", decodeGridLayer, errors);
+    const directives = raw.directives === undefined ? undefined : decodeArray(raw.directives, "$.directives", decodeDirective, errors);
     if (raw.terrain !== undefined && !isPlainObject(raw.terrain)) {
         errors.push({ path: "$.terrain", message: "expected an object" });
     }
+    const minimap = raw.minimap === undefined ? undefined : decodeMinimapBake(raw.minimap, "$.minimap", errors);
+    const environment = raw.environment === undefined ? undefined : decodeEnvironment(raw.environment, "$.environment", errors);
+    // Placeable object ids form one document-global namespace (selection, parenting, and removal all
+    // treat them that way), so a document that reuses an id — even across two different collections —
+    // is malformed and rejected here with the offending path, rather than silently loading a scene
+    // where one id shadows another. Combine paths (merge/duplicate/overlay) re-id instead; this is the
+    // single-document decode boundary, where a collision is an authoring error, not something to paper over.
+    const seenIds = new Set();
+    for (const [collection, list] of [
+        ["markers", markers],
+        ["volumes", volumes],
+        ["paths", paths],
+        ["annotations", annotations],
+    ]) {
+        list.forEach((item, index) => {
+            if (seenIds.has(item.id)) {
+                errors.push({ path: `$.${collection}[${index}].id`, message: `duplicate id "${item.id}"` });
+            }
+            else {
+                seenIds.add(item.id);
+            }
+        });
+    }
     if (errors.length > 0)
         return { ok: false, errors };
     const terrain = raw.terrain === undefined ? undefined : migrateTerrainSnapshot(raw.terrain);
@@ -787,6 +1192,9 @@ export function decodeEditorDocument(raw) {
             ...(grids === undefined ? {} : { grids }),
             ...(terrain === undefined ? {} : { terrain }),
             ...(ui === undefined ? {} : { ui }),
+            ...(directives === undefined ? {} : { directives }),
+            ...(minimap === undefined ? {} : { minimap }),
+            ...(environment === undefined ? {} : { environment }),
         },
     };
 }
@@ -814,6 +1222,8 @@ function upsertById(base, overlay) {
   */
 export function applyEditorDocumentOverlay(base, overlay) {
     const terrain = overlay.terrain ?? base.terrain;
+    const minimap = overlay.minimap ?? base.minimap;
+    const environment = overlay.environment ?? base.environment;
     const ui = overlay.ui === undefined
         ? cloneEditorUiDocument(base.ui)
         : {
@@ -822,6 +1232,7 @@ export function applyEditorDocumentOverlay(base, overlay) {
                 ...Object.fromEntries(Object.entries(overlay.ui.panels).map(([id, panel]) => [id, { ...panel }])),
             },
         };
+    const grids = upsertGrids(base.grids, overlay.grids);
     return {
         version: 1,
         markers: upsertById(base.markers, overlay.markers),
@@ -831,9 +1242,14 @@ export function applyEditorDocumentOverlay(base, overlay) {
         prefabs: upsertById(base.prefabs, overlay.prefabs),
         collections: upsertById(base.collections, overlay.collections),
         catalogs: upsertCatalogs(base.catalogs, overlay.catalogs),
-        ...(upsertGrids(base.grids, overlay.grids) === undefined ? {} : { grids: upsertGrids(base.grids, overlay.grids) }),
+        ...(grids === undefined ? {} : { grids }),
         ...(terrain === undefined ? {} : { terrain }),
         ...(ui === undefined ? {} : { ui }),
+        ...(minimap === undefined ? {} : { minimap: cloneMinimapBake(minimap) }),
+        ...(environment === undefined ? {} : { environment: cloneEnvironment(environment) }),
+        ...(base.directives === undefined && overlay.directives === undefined
+            ? {}
+            : { directives: upsertById(base.directives ?? [], overlay.directives ?? []) }),
     };
 }
 /** Computes the world-space min/max bounds spanning every object in a document, or null if empty.

package/dist/editor/entityCatalog.d.ts

@@ -0,0 +1,42 @@
+import type { GameContextEntityEntry } from "../runtime/gameContext.js";
+import { type ParamSchema } from "../scene/sceneKinds.js";
+import type { EditorCatalogData, EditorCatalogDefinition } from "./types.js";
+/**
+ * Well-known catalog id for authored entity definitions. A `mob`/`boss` marker's `catalogId`
+ * references an entry (row) in this catalog, and {@link entityEntryFromCatalog} turns that row into
+ * the runtime {@link GameContextEntityEntry} a spawn consumes — so an entity's stats and speed are
+ * authored in the editor Data tab, not hardcoded in game TS.
+ */
+export declare const ENTITY_CATALOG_ID = "entities";
+/**
+ * The default {@link ParamSchema} for an authored entity definition — role, health, movement speed,
+ * and visual scale. Drives the editor Data-tab inspector for the `entities` catalog and is the shape
+ * {@link entityEntryFromCatalog} reads. A game exports it as an `editorCatalogs` schema; the scaffold
+ * ships a starter one so the tab is never empty.
+ * @capability editor-entities Author entity stats/movement per catalog row instead of hardcoding TS.
+ */
+export declare const entityDefinitionSchema: ParamSchema;
+/** Minimal document shape {@link entityEntryFromCatalog} reads — any `EditorDocument` satisfies it. */
+export interface EntityCatalogDocumentLike {
+    catalogs: readonly EditorCatalogData[];
+}
+/**
+ * Turns an authored entity row into the runtime {@link GameContextEntityEntry} a spawn consumes:
+ * looks up `entityId` in the document's {@link ENTITY_CATALOG_ID} catalog (falling back to the
+ * game-exported `definitions` defaults), parses it against {@link entityDefinitionSchema}, and maps
+ * the fields onto stats/movement/role. Returns `null` when no row defines the entity, so the default
+ * `content.ts` path can chain other resolvers. The single seam that makes "place a mob, tune its
+ * stats/speed in the editor, save — it spawns with those stats" work with zero game code.
+ * @capability editor-entities Consume authored entity definitions from the scene document at runtime.
+ */
+export declare function entityEntryFromCatalog(document: EntityCatalogDocumentLike, entityId: string, definitions?: readonly EditorCatalogDefinition[]): GameContextEntityEntry | null;
+/**
+ * Merges game-exported catalog definitions with editor-authored ones carried on the scene document.
+ * A document catalog that carries its own `schema` and has no matching game definition is synthesized
+ * into a full {@link EditorCatalogDefinition} (label falls back to the id) so the Data panel, the
+ * `list_catalogs` RPC, and the count all see it. A game definition always wins on id collision — its
+ * schema lives in code and is authoritative. Document catalogs without a schema (plain value bags for
+ * a game-declared catalog) are ignored here; they are addressed through their game definition.
+ * @capability editor-catalogs Merge game-exported and editor-authored catalogs into one addressable set.
+ */
+export declare function resolveCatalogDefinitions(document: EntityCatalogDocumentLike, gameDefinitions: readonly EditorCatalogDefinition[]): EditorCatalogDefinition[];