@jgengine/core 0.19.0 → 0.22.0

package/dist/editor/commands.js

@@ -1,6 +1,248 @@
+import { parseStaticPrefabBake } from "./staticPrefab.js";
 import { applyDeltaToSnapshot, applySurfaceDeltaToSnapshot, applyWeightDeltaToSnapshot, revertDeltaFromSnapshot, revertSurfaceDeltaFromSnapshot, revertWeightDeltaFromSnapshot, } from "../world/terraform.js";
-import { cloneEditorDocument, findEditorMarker, findEditorVolume, } from "./document.js";
+import { cloneEditorDocument, decodeEditorDocument, findEditorMarker, findEditorVolume, isEditorObjectLocked, wouldCreateCycle, } from "./document.js";
 import { applyMutating, isStructural } from "./commandApply.js";
+function transactionCommandError(document, command) {
+    if (command.type === "undo" || command.type === "redo")
+        return "history commands cannot run inside a transaction";
+    const placeables = [...document.markers, ...document.volumes, ...document.paths, ...document.annotations];
+    const requireObjects = (ids, allowLocked = false) => {
+        if (!Array.isArray(ids) || ids.length === 0)
+            return "expected at least one object id";
+        for (const id of ids) {
+            if (typeof id !== "string" || !placeables.some((item) => item.id === id))
+                return `object not found: ${String(id)}`;
+            if (!allowLocked && isEditorObjectLocked(document, id))
+                return `object is locked: ${id}`;
+        }
+        return null;
+    };
+    switch (command.type) {
+        case "setMarker":
+        case "setVolume":
+        case "setPath":
+        case "setNote": {
+            const list = command.type === "setMarker" ? document.markers : command.type === "setVolume" ? document.volumes : command.type === "setPath" ? document.paths : document.annotations;
+            if (!list.some((item) => item.id === command.id))
+                return `${command.type} target not found: ${command.id}`;
+            return requireObjects([command.id]);
+        }
+        case "setTransform":
+            return [...document.markers, ...document.volumes, ...document.annotations].some((item) => item.id === command.id) ? requireObjects([command.id]) : `transform target not found: ${command.id}`;
+        case "remove": return requireObjects([command.id]);
+        case "translate":
+        case "removeMany":
+        case "batchSetProperties":
+        case "assignMaterial":
+            return requireObjects(command.ids);
+        case "assignMaterialAsset":
+        case "clearMaterialAssets":
+            for (const id of command.ids)
+                if (!document.markers.some((marker) => marker.id === id))
+                    return `material target is not a marker: ${id}`;
+            return requireObjects(command.ids);
+        case "duplicate": return requireObjects(command.ids, true);
+        case "select": return command.ids.length === 0 ? null : requireObjects(command.ids, true);
+        case "setObjectFlags": return requireObjects(command.ids, true);
+        case "setParent": {
+            const error = requireObjects(command.ids);
+            if (error !== null)
+                return error;
+            if (command.parentId !== null && !placeables.some((item) => item.id === command.parentId))
+                return `parent not found: ${command.parentId}`;
+            for (const id of command.ids) {
+                if (wouldCreateCycle(document, id, command.parentId))
+                    return `parent cycle: ${id}`;
+            }
+            return null;
+        }
+        case "addMarker":
+        case "addVolume":
+        case "addPath":
+        case "addNote": {
+            const item = command.type === "addMarker" ? command.marker : command.type === "addVolume" ? command.volume : command.type === "addPath" ? command.path : command.note;
+            if (typeof item.id !== "string" || item.id.trim().length === 0)
+                return "expected a nonempty object id";
+            const own = command.type === "addMarker" ? document.markers : command.type === "addVolume" ? document.volumes : command.type === "addPath" ? document.paths : document.annotations;
+            if (placeables.some((entry) => entry.id === item.id) && !own.some((entry) => entry.id === item.id))
+                return `object id collision: ${item.id}`;
+            return own.some((entry) => entry.id === item.id) ? requireObjects([item.id]) : null;
+        }
+        case "createPrefab": return requireObjects(command.ids, true);
+        case "setPrefabStaticBake":
+            if (command.bake !== null)
+                parseStaticPrefabBake(command.bake);
+            return document.prefabs.some((item) => item.id === command.prefabId) ? null : `prefab not found: ${command.prefabId}`;
+        case "insertPrefab":
+        case "deletePrefab":
+            return document.prefabs.some((item) => item.id === command.prefabId) ? null : `prefab not found: ${command.prefabId}`;
+        case "detachPrefabInstance":
+            return placeables.some((item) => item.meta?.prefabInstanceId === command.instanceId) ? null : `prefab instance not found: ${command.instanceId}`;
+        case "createCollection":
+            return command.memberIds === undefined || command.memberIds.length === 0 ? null : requireObjects(command.memberIds, true);
+        case "renameCollection":
+        case "deleteCollection":
+        case "setCollectionFlags":
+        case "selectCollection":
+            return document.collections.some((item) => item.id === command.id) ? null : `collection not found: ${command.id}`;
+        case "setCollectionMembers":
+        case "addToCollection":
+        case "removeFromCollection": {
+            if (!document.collections.some((item) => item.id === command.id))
+                return `collection not found: ${command.id}`;
+            const ids = command.type === "setCollectionMembers" ? command.memberIds : command.ids;
+            return ids.length === 0 ? null : requireObjects(ids, true);
+        }
+        case "setCatalogEntry":
+        case "removeCatalogEntry": {
+            const catalog = document.catalogs.find((item) => item.id === command.catalogId);
+            return catalog?.entries.some((item) => item.id === command.entryId) ? null : `catalog entry not found: ${command.catalogId}/${command.entryId}`;
+        }
+        case "addCatalogEntry":
+            return document.catalogs.find((item) => item.id === command.catalogId)?.entries.some((item) => item.id === command.entry.id) ? `catalog entry id collision: ${command.entry.id}` : null;
+        case "removeCatalog":
+        case "setCatalogSchema":
+            return document.catalogs.some((item) => item.id === command.id) ? null : `catalog not found: ${command.id}`;
+        case "removeGridLayer":
+        case "setGridLayer":
+        case "paintGridCells":
+        case "fillGridRect":
+        case "floodFillGrid":
+        case "resizeGridLayer":
+            return document.grids?.some((item) => item.id === command.id) ? null : `grid not found: ${command.id}`;
+        case "convertScatterToObjects":
+            return document.paths.some((item) => item.id === command.pathId) ? requireObjects([command.pathId]) : `path not found: ${command.pathId}`;
+        case "sculptTerrain":
+        case "paintTerrain":
+        case "blendTerrain":
+        case "setTerrainLayers":
+        case "clearTerrain":
+            return document.terrain === undefined ? "terrain not found" : null;
+        default: return null;
+    }
+}
+function assertTransactionValue(value, path = "$", ancestors = new Set()) {
+    if (value === undefined || value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number" && Number.isFinite(value))
+        return;
+    if (typeof value !== "object")
+        throw new Error(`${path}: expected serializable finite values`);
+    if (ancestors.has(value))
+        throw new Error(`${path}: cyclic value`);
+    if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+        throw new Error(`${path}: expected a plain object`);
+    ancestors.add(value);
+    for (const [key, child] of Object.entries(value))
+        assertTransactionValue(child, `${path}.${key}`, ancestors);
+    ancestors.delete(value);
+}
+function assertObjectFields(value, nullableParent = false) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("expected an object payload");
+    const fields = value;
+    for (const key of ["id", "kind", "color", "label", "catalogId", "parentId", "text", "name", "materialId"]) {
+        if (key === "parentId" && nullableParent && fields[key] === null)
+            continue;
+        if (fields[key] !== undefined && typeof fields[key] !== "string")
+            throw new Error(`${key}: expected a string`);
+    }
+    for (const key of ["rotationY", "radius", "height", "width", "cellSize", "cols", "rows"]) {
+        if (fields[key] !== undefined && typeof fields[key] !== "number")
+            throw new Error(`${key}: expected a number`);
+    }
+    for (const key of ["locked", "hidden", "visible"]) {
+        if (fields[key] !== undefined && typeof fields[key] !== "boolean")
+            throw new Error(`${key}: expected a boolean`);
+    }
+    for (const key of ["position", "center", "halfExtents", "offset", "at"]) {
+        const vector = fields[key];
+        if (vector !== undefined && (vector === null || typeof vector !== "object" || !["x", "y", "z"].every((axis) => typeof vector[axis] === "number")))
+            throw new Error(`${key}: expected {x,y,z} numbers`);
+    }
+    for (const key of ["ids", "memberIds"]) {
+        if (fields[key] !== undefined && (!Array.isArray(fields[key]) || fields[key].some((id) => typeof id !== "string")))
+            throw new Error(`${key}: expected string ids`);
+    }
+}
+const transactionFields = {
+    select: "ids", clearSelection: "", setTransform: "id ?position ?rotationY", translate: "ids delta", setParent: "ids parentId",
+    addMarker: "marker", addVolume: "volume", addPath: "path", addNote: "note",
+    setMarker: "id patch", setVolume: "id patch", setPath: "id patch", setNote: "id patch",
+    setCatalogEntry: "catalogId entryId patch", addCatalogEntry: "catalogId entry", removeCatalogEntry: "catalogId entryId",
+    addCatalog: "id ?label ?schema", removeCatalog: "id", setCatalogSchema: "id schema ?label",
+    remove: "id", removeMany: "ids", duplicate: "ids ?offset", addFragment: "fragment ?offset",
+    importDocument: "document", importJson: "json", replaceDocument: "document", setTerrain: "terrain",
+    sculptTerrain: "delta", paintTerrain: "delta", blendTerrain: "delta", setTerrainLayers: "layers", clearTerrain: "",
+    setMinimapBake: "minimap", setBake: "bake", setEnvironment: "?environment", setSimulation: "?simulation", convertScatterToObjects: "pathId markers",
+    setPrefabStaticBake: "prefabId bake", createPrefab: "id name ids", insertPrefab: "prefabId at ?instanceId", detachPrefabInstance: "instanceId", deletePrefab: "prefabId",
+    createCollection: "id name ?memberIds", renameCollection: "id name", deleteCollection: "id",
+    setCollectionMembers: "id memberIds", addToCollection: "id ids", removeFromCollection: "id ids", setCollectionFlags: "id patch",
+    setObjectFlags: "ids patch", selectCollection: "id", batchSetProperties: "ids patch", assignMaterial: "ids materialId",
+    upsertMaterialAsset: "asset", removeMaterialAsset: "id", assignMaterialAsset: "ids materialId selector", clearMaterialAssets: "ids",
+    addGridLayer: "layer", removeGridLayer: "id", setGridLayer: "id patch", paintGridCells: "id cells",
+    fillGridRect: "id col0 row0 col1 row1 value", floodFillGrid: "id col row value", resizeGridLayer: "id cols rows",
+    setUiPanel: "id patch", removeUiPanel: "id", setUi: "?ui", undo: "", redo: "",
+};
+const placeableFields = {
+    marker: "id kind position rotationY color label catalogId parentId locked hidden meta",
+    volume: "id kind shape center radius height halfExtents color label parentId locked hidden meta",
+    path: "id kind points width color label parentId locked hidden meta",
+    note: "id text position color parentId locked hidden meta",
+};
+function assertPlacementFields(command, key, payload) {
+    const kind = command.type === "addMarker" || command.type === "setMarker" ? "marker"
+        : command.type === "addVolume" || command.type === "setVolume" ? "volume"
+            : command.type === "addPath" || command.type === "setPath" ? "path"
+                : command.type === "addNote" || command.type === "setNote" ? "note" : null;
+    if (kind === null || (key !== kind && key !== "patch"))
+        return;
+    const allowed = new Set(placeableFields[kind].split(" "));
+    if (key === "patch")
+        allowed.delete("id");
+    for (const field of Object.keys(payload)) {
+        if (!allowed.has(field))
+            throw new Error(`unknown ${key} field: ${field}`);
+    }
+}
+function assertCommandFields(command) {
+    const spec = transactionFields[command.type];
+    if (spec === undefined)
+        throw new Error(`unknown command: ${String(command.type)}`);
+    const fields = spec.split(" ").filter(Boolean);
+    const allowed = new Set(["type", ...fields.map((field) => field.replace(/^\?/, ""))]);
+    const record = command;
+    for (const key of Object.keys(record)) {
+        if (!allowed.has(key))
+            throw new Error(`unknown command field: ${key}`);
+    }
+    for (const field of fields) {
+        if (!field.startsWith("?") && record[field] === undefined)
+            throw new Error(`missing command field: ${field}`);
+    }
+}
+function sameTransactionValue(left, right) {
+    if (left === right)
+        return true;
+    if (left === null || right === null || typeof left !== "object" || typeof right !== "object")
+        return false;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return Array.isArray(left) && Array.isArray(right) && left.length === right.length && left.every((value, index) => sameTransactionValue(value, right[index]));
+    }
+    const a = left;
+    const b = right;
+    const keys = Object.keys(a).filter((key) => a[key] !== undefined);
+    return keys.length === Object.keys(b).filter((key) => b[key] !== undefined).length && keys.every((key) => sameTransactionValue(a[key], b[key]));
+}
+function isUnchangedPlacement(document, command) {
+    switch (command.type) {
+        case "addMarker": return sameTransactionValue(document.markers.find((item) => item.id === command.marker.id), command.marker);
+        case "addVolume": return sameTransactionValue(document.volumes.find((item) => item.id === command.volume.id), command.volume);
+        case "addPath": return sameTransactionValue(document.paths.find((item) => item.id === command.path.id), command.path);
+        case "addNote": return sameTransactionValue(document.annotations.find((item) => item.id === command.note.id), command.note);
+        default: return false;
+    }
+}
 function snapshotState(state) {
     return {
         document: cloneEditorDocument(state.document),
@@ -23,9 +265,11 @@ const terrainStrokeKind = {
     blendTerrain: "blend",
 };
 /** Creates an editor session with undo/redo history seeded from an initial document.
+ * Environment commands validate and copy their candidate bag before publishing state or history.
  * @internal
  */
-export function createEditorSession(initial, historyLimit = 100) {
+export function createEditorSession(initial, historyLimit = 100, validateDocument) {
+    validateDocument?.(initial);
     let state = {
         document: cloneEditorDocument(initial),
         selection: [],
@@ -46,12 +290,14 @@ export function createEditorSession(initial, historyLimit = 100) {
         return { document: { ...state.document, terrain: next }, selection };
     };
     const pushTerrainStroke = (entry) => {
+        const next = applyStroke(entry, "apply", entry.selection);
+        validateDocument?.(next.document);
         past.push(entry);
         if (past.length > historyLimit)
             past.shift();
         future.length = 0;
         lastCoalesce = null;
-        state = applyStroke(entry, "apply", entry.selection);
+        state = next;
     };
     return {
         getState: () => state,
@@ -63,8 +309,74 @@ export function createEditorSession(initial, historyLimit = 100) {
         },
         canUndo: () => past.length > 0,
         canRedo: () => future.length > 0,
+        transaction(commands) {
+            if (!Array.isArray(commands) || commands.length === 0)
+                return { ok: false, error: "commands transaction is empty" };
+            let staged = snapshotState(state);
+            for (let commandIndex = 0; commandIndex < commands.length; commandIndex += 1) {
+                try {
+                    const input = commands[commandIndex];
+                    assertTransactionValue(input);
+                    assertObjectFields(input, input.type === "setParent");
+                    assertCommandFields(input);
+                    if (input.type === "translate")
+                        assertObjectFields({ position: input.delta });
+                    const command = JSON.parse(JSON.stringify(input));
+                    for (const key of ["marker", "volume", "path", "note", "patch", "entry", "layer"]) {
+                        const payload = command[key];
+                        if (payload !== undefined) {
+                            assertObjectFields(payload);
+                            assertPlacementFields(command, key, payload);
+                            if (key === "patch" && ["setMarker", "setVolume", "setPath", "setNote", "setGridLayer"].includes(command.type) && "id" in payload)
+                                throw new Error("patch cannot change a stable id");
+                        }
+                    }
+                    const error = transactionCommandError(staged.document, command);
+                    if (error !== null)
+                        throw new Error(error);
+                    if (isUnchangedPlacement(staged.document, command))
+                        continue;
+                    const next = applyMutating(staged, command);
+                    if (next === null)
+                        throw new Error(`${command.type} rejected`);
+                    const decoded = decodeEditorDocument(next.document);
+                    if (!decoded.ok)
+                        throw new Error(decoded.errors.map((diagnostic) => `${diagnostic.path} ${diagnostic.message}`).join("; "));
+                    validateDocument?.(next.document);
+                    for (const item of [...next.document.markers, ...next.document.volumes, ...next.document.paths, ...next.document.annotations]) {
+                        if (item.parentId !== undefined && wouldCreateCycle(next.document, item.id, item.parentId))
+                            throw new Error(`parent cycle: ${item.id}`);
+                    }
+                    staged = next;
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    return { ok: false, commandIndex, error: `commands[${commandIndex}]: ${message}` };
+                }
+            }
+            const documentChanged = !sameTransactionValue(staged.document, state.document);
+            const selectionChanged = !sameTransactionValue(staged.selection, state.selection);
+            if (!documentChanged && !selectionChanged)
+                return { ok: true, state, changed: false };
+            if (documentChanged) {
+                past.push({ kind: "snapshot", state: snapshotState(state) });
+                if (past.length > historyLimit)
+                    past.shift();
+                future.length = 0;
+                lastCoalesce = null;
+            }
+            else {
+                staged.document = state.document;
+            }
+            state = staged;
+            emit();
+            return { ok: true, state, changed: true };
+        },
         dispatch(command, options) {
             if (command.type === "undo") {
+                const candidate = past[past.length - 1];
+                if (candidate !== undefined)
+                    validateDocument?.(candidate.kind === "snapshot" ? candidate.state.document : applyStroke(candidate, "revert", candidate.selection).document);
                 const entry = past.pop();
                 if (entry === undefined)
                     return state;
@@ -81,6 +393,9 @@ export function createEditorSession(initial, historyLimit = 100) {
                 return state;
             }
             if (command.type === "redo") {
+                const candidate = future[future.length - 1];
+                if (candidate !== undefined)
+                    validateDocument?.(candidate.kind === "snapshot" ? candidate.state.document : applyStroke(candidate, "apply", candidate.selection).document);
                 const entry = future.pop();
                 if (entry === undefined)
                     return state;
@@ -110,6 +425,8 @@ export function createEditorSession(initial, historyLimit = 100) {
             const next = applyMutating(state, command);
             if (next === null)
                 return state;
+            if (next.document !== state.document)
+                validateDocument?.(next.document);
             if (isStructural(command)) {
                 const coalesce = options?.coalesce;
                 const merge = coalesce !== undefined && coalesce === lastCoalesce && past.length > 0;

package/dist/editor/creatorStorage.d.ts

@@ -0,0 +1,59 @@
+import type { KeyValueStorage } from "../game/keyValueStore.js";
+import type { EditorDocument } from "./types.js";
+/** Bounds and catalog permissions for player-authored documents. */
+export interface CreatorPolicy {
+    maxDocuments: number;
+    maxBytes: number;
+    maxObjects: number;
+    maxPathPoints: number;
+    maxGridCells: number;
+    maxTerrainVertices: number;
+    allowedKinds: readonly string[];
+    allowedAssets: readonly string[];
+    allowedCatalogIds?: readonly string[];
+    /** Total standing/weather pools plus capacity for 32 concurrent collision child bursts. */
+    maxSimulationParticles?: number;
+    maxFireCells?: number;
+    maxPopulation?: number;
+    maxForceFields?: number;
+    /** Additional game-specific constraints; throw to reject the candidate atomically. */
+    validate?: (document: EditorDocument) => void;
+}
+/** A named scene save with a storage-format version and optimistic revision. */
+export interface CreatorDocument {
+    version: 1;
+    id: string;
+    name: string;
+    revision: number;
+    document: EditorDocument;
+}
+/** Injected durable storage. Save rejects stale revisions; null creates a new id. */
+export interface CreatorDocumentStorage {
+    list(): Promise<readonly Omit<CreatorDocument, "document">[]>;
+    load(id: string): Promise<CreatorDocument | null>;
+    save(value: CreatorDocument, expectedRevision: number | null): Promise<CreatorDocument>;
+}
+/** Creator configuration shared by a host and its lazily loaded editor. */
+export interface CreatorConfig<TPlayable> {
+    storage: CreatorDocumentStorage;
+    policy: CreatorPolicy;
+    initialDocument: () => EditorDocument;
+    createPlayable: (document: EditorDocument) => TPlayable;
+    createId?: () => string;
+}
+/** Validates schema, finite work budgets, and approved catalog references before cloning. */
+export declare function validateCreatorDocument(value: unknown, policy: CreatorPolicy): EditorDocument;
+/** Imports scene JSON using the same validation as commands and durable saves. */
+export declare function importCreatorDocument(json: string, policy: CreatorPolicy): EditorDocument;
+/** Exports validated, schema-versioned scene JSON.
+ * @capability creator-export export validated player scenes with approved catalogs and finite budgets
+ */
+export declare function exportCreatorDocument(document: EditorDocument, policy: CreatorPolicy): string;
+/** Durable browser-compatible adapter over injected key/value storage; one atomic catalog write.
+ * @capability creator-storage save and reopen named versioned player creations through injected durable storage
+ */
+export declare function createCreatorDocumentStorage(config: {
+    storage: KeyValueStorage;
+    key: string;
+    policy: CreatorPolicy;
+}): CreatorDocumentStorage;

package/dist/editor/creatorStorage.js

@@ -0,0 +1,164 @@
+import { cloneEditorDocument, decodeEditorDocument, editorDocumentSize } from "./document.js";
+import { isScatterPath } from "../world/scatterRegion.js";
+function byteSize(value) {
+    return new TextEncoder().encode(value).length;
+}
+/** Validates schema, finite work budgets, and approved catalog references before cloning. */
+export function validateCreatorDocument(value, policy) {
+    if (value === null || typeof value !== "object" || value.version !== 1)
+        throw new Error("Unsupported creator scene version");
+    for (const key of ["maxDocuments", "maxBytes", "maxObjects", "maxPathPoints", "maxGridCells", "maxTerrainVertices"]) {
+        if (!Number.isSafeInteger(policy[key]) || policy[key] < 0)
+            throw new Error(`Invalid creator limit: ${key}`);
+    }
+    const json = JSON.stringify(value, null, 2);
+    if (json === undefined || byteSize(json) > policy.maxBytes)
+        throw new Error("Scene exceeds byte budget");
+    const decoded = decodeEditorDocument(value);
+    if (!decoded.ok)
+        throw new Error(decoded.errors.map((error) => `${error.path} ${error.message}`).join("; "));
+    const document = decoded.document;
+    if (editorDocumentSize(document) > policy.maxObjects)
+        throw new Error("Scene exceeds object budget");
+    const kinds = new Set(policy.allowedKinds);
+    const assets = new Set(policy.allowedAssets);
+    const catalogs = new Set(policy.allowedCatalogIds ?? []);
+    const nodes = [...document.markers, ...document.volumes, ...document.paths];
+    for (const node of nodes)
+        if (!kinds.has(node.kind))
+            throw new Error(`Unavailable scene kind: ${node.kind}`);
+    if (document.paths.some(isScatterPath))
+        throw new Error("Creator documents require explicit placements instead of scatter paths");
+    if (document.paths.reduce((count, path) => count + path.points.length, 0) > policy.maxPathPoints)
+        throw new Error("Scene exceeds path point budget");
+    let gridCells = 0;
+    for (const grid of document.grids ?? []) {
+        if (!kinds.has(grid.kind))
+            throw new Error(`Unavailable scene kind: ${grid.kind}`);
+        gridCells += grid.cols * grid.rows;
+    }
+    if (!Number.isSafeInteger(gridCells) || gridCells > policy.maxGridCells)
+        throw new Error("Scene exceeds grid budget");
+    if (document.terrain !== undefined && document.terrain.cols * document.terrain.rows > policy.maxTerrainVertices)
+        throw new Error("Scene exceeds terrain budget");
+    // Procedural directives and prefab duplication can expand a tiny save into unbounded runtime work.
+    if ((document.directives?.length ?? 0) > 0 || document.prefabs.length > 0)
+        throw new Error("Creator documents require explicit placements");
+    for (const key of ["maxSimulationParticles", "maxFireCells", "maxPopulation", "maxForceFields"]) {
+        if (policy[key] !== undefined && (!Number.isSafeInteger(policy[key]) || policy[key] < 0))
+            throw new Error(`Invalid creator limit: ${key}`);
+    }
+    const simulation = document.simulation;
+    if (simulation !== undefined) {
+        if ((simulation.forces?.length ?? 0) > (policy.maxForceFields ?? 0))
+            throw new Error("Scene exceeds force field budget");
+        // Default precipitation pools plus the supported 256-slot rain-impact maximum.
+        const weatherParticles = simulation.weather === undefined ? 0 : 5556;
+        let maxChildParticles = 0;
+        const emitterParticles = (simulation.emitters ?? []).reduce((total, emitter) => {
+            const child = emitter.options?.collisionEffect;
+            if (child !== undefined)
+                maxChildParticles = Math.max(maxChildParticles, Math.min(child.count, child.config.max ?? child.count));
+            return total + (emitter.config.max ?? 512);
+        }, 0);
+        // The renderer retains up to 32 concurrent child bursts, shared by all standing emitters.
+        if (weatherParticles + emitterParticles + 32 * maxChildParticles > (policy.maxSimulationParticles ?? 0))
+            throw new Error("Scene exceeds particle budget");
+        if ((simulation.fires ?? []).reduce((total, fire) => total + fire.config.cols * fire.config.rows, 0) > (policy.maxFireCells ?? 0))
+            throw new Error("Scene exceeds fire budget");
+        if ((simulation.habitats ?? []).reduce((total, habitat) => total + habitat.count, 0) > (policy.maxPopulation ?? 0))
+            throw new Error("Scene exceeds population budget");
+    }
+    const inspect = (item) => {
+        if (Array.isArray(item)) {
+            for (const child of item)
+                inspect(child);
+            return;
+        }
+        if (item === null || typeof item !== "object")
+            return;
+        for (const [key, child] of Object.entries(item)) {
+            if (["url", "modelUrl", "textureUrl", "urls"].includes(key))
+                throw new Error("Creator documents cannot import external asset URLs");
+            if (["assetId", "modelId", "materialId"].includes(key) && (typeof child !== "string" || !assets.has(child)))
+                throw new Error(`Unavailable asset: ${String(child)}`);
+            if (key === "catalogId" && (typeof child !== "string" || !catalogs.has(child)))
+                throw new Error(`Unavailable catalog entry: ${String(child)}`);
+            inspect(child);
+        }
+    };
+    inspect(document);
+    policy.validate?.(document);
+    return cloneEditorDocument(document);
+}
+/** Imports scene JSON using the same validation as commands and durable saves. */
+export function importCreatorDocument(json, policy) {
+    if (byteSize(json) > policy.maxBytes)
+        throw new Error("Scene exceeds byte budget");
+    return validateCreatorDocument(JSON.parse(json), policy);
+}
+/** Exports validated, schema-versioned scene JSON.
+ * @capability creator-export export validated player scenes with approved catalogs and finite budgets
+ */
+export function exportCreatorDocument(document, policy) {
+    return JSON.stringify(validateCreatorDocument(document, policy), null, 2);
+}
+function identity(value) {
+    if (value.version !== 1)
+        throw new Error("Unsupported creator save version");
+    if (!/^[a-zA-Z0-9_-]{1,80}$/.test(value.id))
+        throw new Error("Invalid scene id");
+    if (typeof value.name !== "string" || value.name.trim().length === 0 || value.name.length > 80)
+        throw new Error("Scene name must contain 1–80 characters");
+    if (!Number.isSafeInteger(value.revision) || value.revision < 0)
+        throw new Error("Invalid scene revision");
+}
+/** Durable browser-compatible adapter over injected key/value storage; one atomic catalog write.
+ * @capability creator-storage save and reopen named versioned player creations through injected durable storage
+ */
+export function createCreatorDocumentStorage(config) {
+    const read = () => {
+        const json = config.storage.getItem(config.key);
+        if (json === null)
+            return [];
+        if (byteSize(json) > config.policy.maxDocuments * (config.policy.maxBytes + 1024) + 128)
+            throw new Error("Creator catalog exceeds byte budget");
+        const value = JSON.parse(json);
+        if (value === null || typeof value !== "object" || value.version !== 1)
+            throw new Error("Unsupported creator catalog version");
+        const documents = value.documents;
+        if (!Array.isArray(documents) || documents.length > config.policy.maxDocuments)
+            throw new Error("Creator catalog exceeds document budget");
+        const ids = new Set();
+        return documents.map((item) => {
+            identity(item);
+            if (ids.has(item.id))
+                throw new Error("Duplicate scene id");
+            ids.add(item.id);
+            return { ...item, document: validateCreatorDocument(item.document, config.policy) };
+        });
+    };
+    return {
+        async list() { return read().map(({ document: _document, ...summary }) => summary); },
+        async load(id) { return read().find((item) => item.id === id) ?? null; },
+        async save(value, expectedRevision) {
+            identity(value);
+            const document = validateCreatorDocument(value.document, config.policy);
+            const documents = read();
+            const index = documents.findIndex((item) => item.id === value.id);
+            const previous = documents[index];
+            if ((previous?.revision ?? null) !== expectedRevision)
+                throw new Error("Scene changed in storage; reopen it before saving");
+            if (previous === undefined && documents.length >= config.policy.maxDocuments)
+                throw new Error("Creator catalog is full");
+            const next = { version: 1, id: value.id, name: value.name.trim(), revision: (previous?.revision ?? 0) + 1, document };
+            identity(next);
+            if (index < 0)
+                documents.push(next);
+            else
+                documents[index] = next;
+            config.storage.setItem(config.key, JSON.stringify({ version: 1, documents }));
+            return { ...next, document: cloneEditorDocument(document) };
+        },
+    };
+}

package/dist/editor/document.d.ts

@@ -1,7 +1,10 @@
+import { type EditorSimulation } from "./simulation.js";
+import { type MaterialAsset } from "../material/materialAsset.js";
 import { type EditorGridLayer } from "./grid.js";
 import type { EditorCatalogData, EditorBake, EditorCatalogDefinition, EditorCatalogEntry, EditorCollection, EditorDirective, EditorDocument, EditorEnvironment, EditorFragmentContent, EditorLayersInput, EditorMarker, EditorMinimapBake, EditorNote, EditorPath, EditorPrefab, EditorTerrain, EditorVolume } from "./types.js";
 /** Spread-ready non-placeable fields preserved across document rebuilds. @internal */
 export declare function editorDocumentExtras(doc: EditorDocument): {
+    materialAssets?: MaterialAsset[];
     prefabs: EditorPrefab[];
     collections: EditorCollection[];
     catalogs: EditorCatalogData[];
@@ -12,6 +15,7 @@ export declare function editorDocumentExtras(doc: EditorDocument): {
     minimap?: EditorMinimapBake;
     bakes?: EditorBake[];
     environment?: EditorEnvironment;
+    simulation?: EditorSimulation;
 };
 /** Builds a fresh, empty editor document to start authoring a scene from scratch.
  * @internal