@jgengine/core 0.19.0 → 0.22.0

package/dist/combat/regenShield.d.ts

@@ -31,6 +31,14 @@ export interface RegenShieldConfig {
      */
     pool?: RegenShieldPool;
 }
+/** Complete mutable shield state, including pending external damage detection. */
+export interface RegenShieldState {
+    max: number;
+    current: number;
+    sinceDamageMs: number;
+    activeDelayMs: number;
+    observed: number | null;
+}
 /**
  * A shield pool that stops regenerating for `regenDelayMs` after every hit, then refills at
  * `regenPerSecond` — the delayed-regen primitive that replaces snapshot-comparing stat values per
@@ -38,6 +46,10 @@ export interface RegenShieldConfig {
  * regenerates once it elapses.
  */
 export interface RegenShield {
+    /** Detached pool value, bounds, and regen timing. */
+    state(): RegenShieldState;
+    /** Restore state; returns false without mutation when an external pool's max differs. */
+    restore(next: RegenShieldState): boolean;
     current(): number;
     max(): number;
     setMax(value: number): void;
@@ -49,6 +61,8 @@ export interface RegenShield {
     /** Absorb `amount` and reset the regen grace timer; returns damage that got through (0 while the shield holds). */
     damage(amount: number): number;
     /** Add `amount` without touching the regen timer (a pickup or scripted refill). */
+    refill(amount: number): void;
+    /** @deprecated Use `refill(amount)` for pickups; `restore(state)` loads persisted state. */
     restore(amount: number): void;
     set(value: number): void;
     /**

package/dist/combat/regenShield.js

@@ -39,7 +39,30 @@ export function createRegenShield(config) {
             sinceDamageMs = 0;
         observed = live;
     }
+    function refill(amount) {
+        if (amount <= 0)
+            return;
+        syncExternal();
+        write(readCurrent() + amount);
+        observed = pool === undefined ? observed : readCurrent();
+    }
+    function restore(next) {
+        if (typeof next === "number")
+            return refill(next);
+        if (pool !== undefined && readMax() !== next.max)
+            return false;
+        if (pool === undefined)
+            ownMax = Math.max(0, next.max);
+        write(next.current);
+        sinceDamageMs = Math.max(0, next.sinceDamageMs);
+        activeDelayMs = Math.max(0, next.activeDelayMs);
+        observed = pool === undefined ? null : next.observed;
+        return true;
+    }
     return {
+        state: () => ({ max: readMax(), current: readCurrent(), sinceDamageMs, activeDelayMs, observed }),
+        restore,
+        refill,
         current: readCurrent,
         max: readMax,
         setMax(value) {
@@ -65,13 +88,6 @@ export function createRegenShield(config) {
             observed = pool === undefined ? observed : readCurrent();
             return overflow;
         },
-        restore(amount) {
-            if (amount <= 0)
-                return;
-            syncExternal();
-            write(readCurrent() + amount);
-            observed = pool === undefined ? observed : readCurrent();
-        },
         set(value) {
             write(value);
             observed = pool === undefined ? observed : readCurrent();

package/dist/crafting/recipeCatalog.d.ts

@@ -0,0 +1,16 @@
+import type { ContentIssue } from "../game/contentValidation.js";
+import type { RecipeDef } from "./recipe.js";
+/** Caller catalogs for native crafting references; omission leaves that namespace unchecked. */
+export interface RecipeCatalogValidationOptions {
+    hasReference?(kind: "item" | "station" | "unlock", id: string): boolean;
+}
+/**
+ * Validate native recipes before registration: ids, counts, timing and caller-catalog references.
+ * Empty outputs are valid for game-owned benefits; fractional and zero counts are allowed.
+ * Negative/nonfinite counts, durations and ranges reject. Duplicate input rows reject because the
+ * crafting input check does not aggregate them; consolidate their counts into one row.
+ * No price, scarcity, story or cycle policy is imposed. O(recipes + item rows + requirements).
+ *
+ * @capability recipe-catalog-validation locate broken crafting item/station/unlock references, duplicate inputs and invalid authored quantities with repair guidance
+ */
+export declare function validateRecipeCatalog(recipes: readonly RecipeDef[], options?: RecipeCatalogValidationOptions): ContentIssue[];

package/dist/crafting/recipeCatalog.js

@@ -0,0 +1,55 @@
+/**
+ * Validate native recipes before registration: ids, counts, timing and caller-catalog references.
+ * Empty outputs are valid for game-owned benefits; fractional and zero counts are allowed.
+ * Negative/nonfinite counts, durations and ranges reject. Duplicate input rows reject because the
+ * crafting input check does not aggregate them; consolidate their counts into one row.
+ * No price, scarcity, story or cycle policy is imposed. O(recipes + item rows + requirements).
+ *
+ * @capability recipe-catalog-validation locate broken crafting item/station/unlock references, duplicate inputs and invalid authored quantities with repair guidance
+ */
+export function validateRecipeCatalog(recipes, options = {}) {
+    const issues = [];
+    const ids = new Set();
+    for (let index = 0; index < recipes.length; index++) {
+        const recipe = recipes[index];
+        const path = `/${index}`;
+        const add = (code, field, message, repair, referenceId) => {
+            issues.push({ code, severity: "error", path: `${path}/${field}`, contentId: recipe.id,
+                ...(referenceId === undefined ? {} : { referenceId }), message, repair });
+        };
+        const reference = (kind, id, field) => {
+            if (options.hasReference?.(kind, id) === false) {
+                add("unknown-reference", field, `Recipe "${recipe.id}" references unknown ${kind} "${id}".`, `Correct this reference or declare "${id}" in the ${kind} catalog.`, id);
+            }
+        };
+        if (ids.has(recipe.id))
+            add("duplicate-recipe", "id", `Recipe id "${recipe.id}" repeats.`, "Give recipes distinct ids and update their references, or remove the duplicate.", recipe.id);
+        ids.add(recipe.id);
+        for (const direction of ["inputs", "outputs"]) {
+            const inputs = new Set();
+            for (let row = 0; row < recipe[direction].length; row++) {
+                const item = recipe[direction][row];
+                const field = `${direction}/${row}`;
+                reference("item", item.itemId, `${field}/itemId`);
+                if (!Number.isFinite(item.count) || item.count < 0) {
+                    add("invalid-count", `${field}/count`, "Recipe count must be finite and nonnegative.", "Use a finite nonnegative count; enforce any stricter discrete-unit policy in the game.");
+                }
+                if (direction === "inputs" && inputs.has(item.itemId)) {
+                    add("duplicate-input", `${field}/itemId`, `Recipe "${recipe.id}" repeats input "${item.itemId}".`, "Combine this item's input counts into one row so the crafting check sees the total.", item.itemId);
+                }
+                inputs.add(item.itemId);
+            }
+        }
+        if (recipe.station !== undefined)
+            reference("station", recipe.station, "station");
+        for (const [row, id] of (recipe.requires ?? []).entries())
+            reference("unlock", id, `requires/${row}`);
+        for (const field of ["seconds", "stationRange"]) {
+            const value = recipe[field];
+            if (value !== undefined && (!Number.isFinite(value) || value < 0)) {
+                add("invalid-number", field, `Recipe ${field} must be finite and nonnegative.`, "Use a finite nonnegative value, or omit the optional field.");
+            }
+        }
+    }
+    return issues;
+}

package/dist/economy/auctionBook.d.ts

@@ -44,7 +44,7 @@ export interface PostAuctionInput {
     now: number;
 }
 /** Why {@link AuctionBook.post} refused an auction. */
-export type PostAuctionReason = "invalid-count" | "invalid-price" | "invalid-increment" | "invalid-buyout" | "auction-cap-reached";
+export type PostAuctionReason = "invalid-count" | "invalid-price" | "invalid-increment" | "invalid-buyout" | "auction-cap-reached" | "duplicate-id";
 /** Result of {@link AuctionBook.post}. */
 export type PostAuctionResult = {
     status: "ok";

package/dist/economy/auctionBook.js

@@ -92,7 +92,15 @@ export function createAuctionBook(config) {
             if (countOf(input.sellerId) >= config.maxAuctionsPerSeller) {
                 return { status: "rejected", reason: "auction-cap-reached" };
             }
-            const id = input.id ?? `auction_${(counter += 1)}`;
+            let id = input.id;
+            if (id === undefined) {
+                do {
+                    id = `auction_${(counter += 1)}`;
+                } while (auctions.has(id));
+            }
+            else if (auctions.has(id)) {
+                return { status: "rejected", reason: "duplicate-id" };
+            }
             const state = {
                 id,
                 sellerId: input.sellerId,
@@ -196,6 +204,8 @@ export function createAuctionBook(config) {
             return claimed;
         },
         claimItem(playerId, itemId, count) {
+            if (!Number.isInteger(count) || count < 1)
+                return false;
             const box = boxOf(playerId);
             const index = box.items.findIndex((stack) => stack.itemId === itemId);
             if (index === -1)

package/dist/economy/listingBook.d.ts

@@ -29,7 +29,7 @@ export interface PostListingInput {
     now: number;
 }
 /** Why {@link ListingBook.post} refused a listing. */
-export type PostListingReason = "invalid-count" | "invalid-price" | "price-too-low" | "price-too-high" | "listing-cap-reached";
+export type PostListingReason = "invalid-count" | "invalid-price" | "price-too-low" | "price-too-high" | "listing-cap-reached" | "duplicate-id";
 /** Result of {@link ListingBook.post}. */
 export type PostListingResult = {
     status: "ok";

package/dist/economy/listingBook.js

@@ -55,7 +55,15 @@ export function createListingBook(config) {
             if (countOf(input.sellerId) >= config.maxListingsPerSeller) {
                 return { status: "rejected", reason: "listing-cap-reached" };
             }
-            const id = input.id ?? `listing_${(counter += 1)}`;
+            let id = input.id;
+            if (id === undefined) {
+                do {
+                    id = `listing_${(counter += 1)}`;
+                } while (listings.has(id));
+            }
+            else if (listings.has(id)) {
+                return { status: "rejected", reason: "duplicate-id" };
+            }
             const listing = {
                 id,
                 sellerId: input.sellerId,
@@ -127,6 +135,8 @@ export function createListingBook(config) {
             return claimed;
         },
         claimItem(sellerId, itemId, count) {
+            if (!Number.isInteger(count) || count < 0)
+                return false;
             const box = boxOf(sellerId);
             const index = box.items.findIndex((stack) => stack.itemId === itemId);
             if (index === -1)

package/dist/economy/resourceLedger.js

@@ -116,7 +116,7 @@ export function advanceLedger(ledger, toSeconds, options = {}) {
             const catchUp = rule.catchUp ?? "each";
             // Reserve-capped nominal amount per candidate cycle, in chronological order.
             const nominal = reserveCappedAmounts(dueCount, rule.amount, cursor.reserveRemaining);
-            const depleted = cursor.reserveRemaining !== undefined && nominal.remaining <= EPSILON;
+            const depleted = cursor.reserveRemaining !== undefined && nominal.remaining <= 0;
             const cycles = buildCycles(catchUp, nominal.amounts, firstDue, rule.everySeconds, perRuleLimit, maxCycles);
             if (wasFirstFire && cycles.settled.length > 0) {
                 events.push({ kind: "started", ruleId: id, atSeconds: cycles.settled[0].atSeconds, detail: 0 });
@@ -200,12 +200,12 @@ function reserveCappedAmounts(count, amount, reserveRemaining) {
     }
     const amounts = [];
     let remaining = reserveRemaining;
-    for (let i = 0; i < count && remaining > EPSILON; i += 1) {
+    for (let i = 0; i < count && remaining > 0; i += 1) {
         const take = Math.min(amount, remaining);
         amounts.push(take);
         remaining -= take;
     }
-    if (remaining < EPSILON)
+    if (remaining < 0)
         remaining = 0;
     return { amounts, remaining, consumed: reserveRemaining - remaining };
 }

package/dist/economy/shopStock.js

@@ -53,17 +53,17 @@ function validateEntry(entry) {
  */
 export function createShopStock(config = {}) {
     // Insertion-ordered map of live records (Map preserves insertion order for list()/snapshot()).
-    const entries = new Map();
+    let entries = new Map();
     const listeners = new Set();
     function notify() {
         for (const listener of listeners)
             listener();
     }
-    function ingest(entry) {
+    function ingest(entry, target = entries) {
         validateEntry(entry);
-        if (entries.has(entry.id))
+        if (target.has(entry.id))
             throw new Error(`duplicate shop entry id: ${entry.id}`);
-        entries.set(entry.id, cloneEntry(entry));
+        target.set(entry.id, cloneEntry(entry));
     }
     for (const entry of config.entries ?? [])
         ingest(entry);
@@ -148,9 +148,10 @@ export function createShopStock(config = {}) {
             return { entries: Array.from(entries.values(), cloneEntry) };
         },
         restore(snapshot) {
-            entries.clear();
+            const next = new Map();
             for (const entry of snapshot.entries)
-                ingest(entry);
+                ingest(entry, next);
+            entries = next;
             notify();
         },
     };

package/dist/economy/techTree.js

@@ -50,15 +50,16 @@ export function createTechTree(defs = []) {
     const nodes = new Map();
     for (const def of defs)
         nodes.set(def.id, def);
-    const unlocks = createUnlocks(defs.map((d) => ({ id: d.id, category: d.category })));
+    const definitions = Array.from(nodes.values());
+    const unlocks = createUnlocks(definitions.map((d) => ({ id: d.id, category: d.category })));
     function stateOf(userId) {
         return unlocks.list(userId);
     }
     return {
         has: (userId, id) => unlocks.has(userId, id),
-        canUnlock: (userId, id) => canUnlockTech(defs, stateOf(userId), id),
+        canUnlock: (userId, id) => canUnlockTech(definitions, stateOf(userId), id),
         unlock(userId, id) {
-            const check = canUnlockTech(defs, stateOf(userId), id);
+            const check = canUnlockTech(definitions, stateOf(userId), id);
             if (!check.ok)
                 return check;
             const node = nodes.get(id);
@@ -67,10 +68,10 @@ export function createTechTree(defs = []) {
                 unlocks.grant(userId, extra);
             return { ok: true };
         },
-        available: (userId) => availableTech(defs, stateOf(userId)),
-        recipes: (userId) => unlockedRecipes(defs, stateOf(userId)),
+        available: (userId) => availableTech(definitions, stateOf(userId)),
+        recipes: (userId) => unlockedRecipes(definitions, stateOf(userId)),
         list: (userId) => unlocks.list(userId),
-        tree: (categoryId) => unlockTree(defs, categoryId),
+        tree: (categoryId) => unlockTree(definitions, categoryId),
         node: (id) => nodes.get(id) ?? null,
         snapshot: (userId) => unlocks.snapshot(userId),
         hydrate: (userId, ids) => unlocks.hydrate(userId, ids),

package/dist/economy/unlockPoints.js

@@ -21,8 +21,8 @@ export function createUnlockPoints(config = {}) {
         unlocked.clear();
         earned = sanitizeAmount(state.earned);
         for (const [id, cost] of Object.entries(state.unlocked)) {
-            const paid = Number.isFinite(cost) && cost >= 0 ? cost : 0;
-            unlocked.set(id, paid);
+            if (Number.isFinite(cost) && cost >= 0)
+                unlocked.set(id, cost);
         }
     };
     if (config.state !== undefined) {
@@ -91,10 +91,7 @@ export function createUnlockPoints(config = {}) {
             return refunded;
         },
         snapshot() {
-            const map = {};
-            for (const [id, cost] of unlocked)
-                map[id] = cost;
-            return { earned, unlocked: map };
+            return { earned, unlocked: Object.fromEntries(unlocked) };
         },
         hydrate(state) {
             load(state);

package/dist/editor/commandApply.js

@@ -1,6 +1,10 @@
-import { applyDeltaToSnapshot, applySurfaceDeltaToSnapshot, applyWeightDeltaToSnapshot, } from "../world/terraform.js";
+import { decodeEditorSimulation } from "./simulation.js";
+import { parseEditorMaterialAsset, authoredMaterialAssignments, sameMaterialSelector } from "./materialAuthoring.js";
+import { parseMaterialAssignments, validateMaterialAssignments } from "../material/materialAsset.js";
+import { parseStaticPrefabBake } from "./staticPrefab.js";
+import { applyDeltaToSnapshot, applySurfaceDeltaToSnapshot, applyWeightDeltaToSnapshot, editableTerrainFromSnapshot, } from "../world/terraform.js";
 import { patchUiPanel, removeUiPanel } from "../ui/hudDocument.js";
-import { cloneEditorDocument, collectDescendants, createPrefabFragment, editorDocumentExtras, ensureUniqueEditorId, extractEditorFragment, findEditorCollection, findEditorMarker, findEditorPrefab, findEditorVolume, importEditorDocumentJson, isEditorObjectLocked, wouldCreateCycle, } from "./document.js";
+import { cloneEditorDocument, collectDescendants, createEmptyEditorDocument, createPrefabFragment, decodeEditorDocument, editorDocumentExtras, ensureUniqueEditorId, extractEditorFragment, findEditorCollection, findEditorMarker, findEditorPrefab, findEditorVolume, importEditorDocumentJson, isEditorObjectLocked, wouldCreateCycle, } from "./document.js";
 import { fillGridRect, floodFillGrid, migrateGridLayer, paintGridCells, resizeGridLayer, } from "./grid.js";
 import { parseParams } from "../scene/sceneKinds.js";
 /** Pure document mutation helpers + exhaustive EditorCommand apply table. */
@@ -80,6 +84,11 @@ function insertFragment(state, fragment, offset, renameAll) {
     const volumes = clones.volumes.map((volume) => withId({ ...volume, center: shifted(volume.center, offset) }));
     const paths = clones.paths.map((path) => withId({ ...path, points: path.points.map((point) => shifted(point, offset)) }));
     const annotations = clones.annotations.map((note) => withId({ ...note, position: shifted(note.position, offset) }));
+    for (const asset of clones.materialAssets ?? []) {
+        const existing = doc.materialAssets?.find((item) => item.id === asset.id);
+        if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(asset))
+            throw new TypeError(`Material ID conflict: ${asset.id}; rename the imported material before insertion.`);
+    }
     if (newIds.length === 0)
         return state;
     return {
@@ -90,6 +99,7 @@ function insertFragment(state, fragment, offset, renameAll) {
             paths: [...doc.paths, ...paths],
             annotations: [...doc.annotations, ...annotations],
             ...editorDocumentExtras(doc),
+            ...(doc.materialAssets === undefined && clones.materialAssets === undefined ? {} : { materialAssets: [...(doc.materialAssets ?? []), ...(clones.materialAssets ?? []).filter((asset) => !doc.materialAssets?.some((item) => item.id === asset.id))] }),
         },
         selection: newIds,
     };
@@ -97,6 +107,7 @@ function insertFragment(state, fragment, offset, renameAll) {
 function fragmentAsDocument(fragment) {
     return {
         version: 1,
+        ...(fragment.materialAssets === undefined ? {} : { materialAssets: structuredClone(fragment.materialAssets) }),
         markers: [...fragment.markers],
         volumes: [...fragment.volumes],
         paths: [...fragment.paths],
@@ -448,13 +459,25 @@ const mutationHandlers = {
     setTerrain: (state, command) => ({ ...state, document: { ...state.document, terrain: command.terrain } }),
     setMinimapBake: (state, command) => ({ ...state, document: { ...state.document, minimap: command.minimap } }),
     setBake: (state, command) => ({ ...state, document: { ...state.document, bakes: [...(state.document.bakes ?? []).filter((bake) => bake.id !== command.bake.id), command.bake] } }),
+    setSimulation: (state, command) => {
+        if (command.simulation === undefined) {
+            const { simulation: _removed, ...document } = state.document;
+            void _removed;
+            return { ...state, document };
+        }
+        return { ...state, document: { ...state.document, simulation: decodeEditorSimulation(command.simulation, state.document) } };
+    },
     setEnvironment: (state, command) => {
         if (command.environment === undefined) {
             const { environment: _removed, ...rest } = state.document;
             void _removed;
             return { ...state, document: rest };
         }
-        return { ...state, document: { ...state.document, environment: command.environment } };
+        const decoded = decodeEditorDocument({ ...createEmptyEditorDocument(), environment: command.environment });
+        if (!decoded.ok) {
+            throw new Error(`invalid editor environment: ${decoded.errors.map((error) => `${error.path} ${error.message}`).join("; ")}`);
+        }
+        return { ...state, document: { ...state.document, environment: decoded.document.environment } };
     },
     clearTerrain: (state) => {
         const nextDoc = {
@@ -470,6 +493,7 @@ const mutationHandlers = {
             ...(state.document.ui === undefined ? {} : { ui: state.document.ui }),
             ...(state.document.directives === undefined ? {} : { directives: state.document.directives }),
             ...(state.document.minimap === undefined ? {} : { minimap: state.document.minimap }),
+            ...(state.document.simulation === undefined ? {} : { simulation: structuredClone(state.document.simulation) }),
             ...(state.document.environment === undefined ? {} : { environment: state.document.environment }),
         };
         return { ...state, document: nextDoc };
@@ -522,19 +546,9 @@ const mutationHandlers = {
     setTerrainLayers: (state, command) => {
         if (state.document.terrain === undefined)
             return state;
-        const terrain = state.document.terrain;
-        const layers = command.layers.map((layer) => ({ ...layer }));
-        const before = terrain.layers ?? [];
-        // Keep hand-painted weights only when the layer id sequence is unchanged (a params-only edit).
-        const sameSequence = before.length === layers.length && before.every((layer, i) => layer.id === layers[i].id);
-        const next = sameSequence
-            ? { ...terrain, layers }
-            : (() => {
-                const copy = { ...terrain, layers };
-                delete copy.weights;
-                return copy;
-            })();
-        return { ...state, document: { ...state.document, terrain: next } };
+        const terrain = editableTerrainFromSnapshot(state.document.terrain);
+        terrain.setLayers(command.layers);
+        return { ...state, document: { ...state.document, terrain: terrain.snapshot() } };
     },
     convertScatterToObjects: (state, command) => {
         const path = state.document.paths.find((entry) => entry.id === command.pathId);
@@ -570,6 +584,17 @@ const mutationHandlers = {
             },
         };
     },
+    setPrefabStaticBake: (state, command) => {
+        if (findEditorPrefab(state.document, command.prefabId) === undefined)
+            return null;
+        const bake = command.bake === null ? undefined : parseStaticPrefabBake(command.bake);
+        return { ...state, document: { ...state.document, prefabs: state.document.prefabs.map((prefab) => {
+                    if (prefab.id !== command.prefabId)
+                        return prefab;
+                    const { staticBake: previous, ...source } = prefab;
+                    return { ...source, ...(bake === undefined ? {} : { staticBake: bake }) };
+                }) } };
+    },
     deletePrefab: (state, command) => ({
         ...state,
         document: {
@@ -584,6 +609,7 @@ const mutationHandlers = {
         const instanceId = command.instanceId ??
             `${prefab.id}_inst_${Date.now().toString(36)}_${Math.floor(Math.random() * 1_296_000).toString(36)}`;
         const tagged = fragmentAsDocument({
+            ...(prefab.fragment.materialAssets === undefined ? {} : { materialAssets: prefab.fragment.materialAssets }),
             markers: prefab.fragment.markers.map((marker) => tagWithInstance(marker, prefab.id, instanceId)),
             volumes: prefab.fragment.volumes.map((volume) => tagWithInstance(volume, prefab.id, instanceId)),
             paths: prefab.fragment.paths.map((path) => tagWithInstance(path, prefab.id, instanceId)),
@@ -738,6 +764,53 @@ const mutationHandlers = {
         const stamp = (item) => ids.has(item.id) ? { ...item, meta: { ...item.meta, materialId: command.materialId } } : item;
         return { ...state, document: { ...state.document, ...mapPlaceables(state.document, stamp) } };
     },
+    upsertMaterialAsset: (state, command) => {
+        const asset = parseEditorMaterialAsset(command.asset);
+        return { ...state, document: { ...state.document, materialAssets: [...(state.document.materialAssets ?? []).filter((item) => item.id !== asset.id), asset] } };
+    },
+    removeMaterialAsset: (state, command) => {
+        const used = state.document.markers.some((marker) => authoredMaterialAssignments(marker.meta).some((assignment) => assignment.materialId === command.id))
+            || state.document.prefabs.some((prefab) => prefab.fragment.markers.some((marker) => authoredMaterialAssignments(marker.meta).some((assignment) => assignment.materialId === command.id)));
+        if (used)
+            throw new TypeError(`Material ${command.id} is assigned; clear its references before removal.`);
+        if (!state.document.materialAssets?.some((asset) => asset.id === command.id))
+            throw new TypeError(`Material not found: ${command.id}`);
+        return { ...state, document: { ...state.document, materialAssets: state.document.materialAssets.filter((asset) => asset.id !== command.id) } };
+    },
+    assignMaterialAsset: (state, command) => {
+        const assignment = parseMaterialAssignments([{ materialId: command.materialId, selector: command.selector }])[0];
+        const errors = validateMaterialAssignments([assignment], state.document.materialAssets ?? []).filter((item) => item.severity === "error");
+        if (errors.length > 0)
+            throw new TypeError(errors.map((item) => item.message).join("; "));
+        const ids = new Set(command.ids);
+        for (const id of ids) {
+            if (!state.document.markers.some((marker) => marker.id === id))
+                throw new TypeError(`material target is not a marker: ${id}`);
+            if (isEditorObjectLocked(state.document, id))
+                throw new TypeError(`object is locked: ${id}`);
+        }
+        const markers = state.document.markers.map((marker) => {
+            if (!ids.has(marker.id))
+                return marker;
+            const assignments = authoredMaterialAssignments(marker.meta).filter((item) => !sameMaterialSelector(item.selector, assignment.selector));
+            return { ...marker, meta: { ...marker.meta, materialAssignments: [...assignments, structuredClone(assignment)] } };
+        });
+        return { ...state, document: { ...state.document, markers } };
+    },
+    clearMaterialAssets: (state, command) => {
+        const ids = new Set(command.ids);
+        for (const id of ids)
+            if (isEditorObjectLocked(state.document, id))
+                throw new TypeError(`object is locked: ${id}`);
+        const markers = state.document.markers.map((marker) => {
+            if (!ids.has(marker.id) || marker.meta?.materialAssignments === undefined)
+                return marker;
+            const meta = { ...marker.meta };
+            delete meta.materialAssignments;
+            return { ...marker, meta };
+        });
+        return { ...state, document: { ...state.document, markers } };
+    },
     undo: () => null,
     redo: () => null,
 };

package/dist/editor/commands.d.ts

@@ -1,3 +1,6 @@
+import type { EditorSimulation } from "./simulation.js";
+import type { MaterialAsset, MaterialSelector } from "../material/materialAsset.js";
+import { type StaticPrefabBake } from "./staticPrefab.js";
 import { type SurfaceDelta, type TerraformDelta, type TerrainMaterialLayer, type WeightDelta } from "../world/terraform.js";
 import type { EditorUiDocument, EditorUiPanelLayout } from "../ui/hudDocument.js";
 import type { EditorGridCellEdit, EditorGridLayer } from "./grid.js";
@@ -134,6 +137,9 @@ export type EditorCommand = {
  | {
     type: "setEnvironment";
     environment: EditorEnvironment | undefined;
+} | {
+    type: "setSimulation";
+    simulation: EditorSimulation | undefined;
 } | {
     type: "convertScatterToObjects";
     pathId: string;
@@ -154,6 +160,10 @@ export type EditorCommand = {
 } | {
     type: "deletePrefab";
     prefabId: string;
+} | {
+    type: "setPrefabStaticBake";
+    prefabId: string;
+    bake: StaticPrefabBake | null;
 } | {
     type: "createCollection";
     id: string;
@@ -208,6 +218,20 @@ export type EditorCommand = {
         label?: string;
         meta?: Record<string, unknown>;
     };
+} | {
+    type: "upsertMaterialAsset";
+    asset: MaterialAsset;
+} | {
+    type: "removeMaterialAsset";
+    id: string;
+} | {
+    type: "assignMaterialAsset";
+    ids: readonly string[];
+    materialId: string;
+    selector: MaterialSelector;
+} | {
+    type: "clearMaterialAssets";
+    ids: readonly string[];
 } | {
     type: "assignMaterial";
     ids: readonly string[];
@@ -274,14 +298,27 @@ export interface EditorSession {
     getState(): EditorSessionState;
     subscribe(listener: (state: EditorSessionState) => void): () => void;
     dispatch(command: EditorCommand, options?: EditorDispatchOptions): EditorSessionState;
+    /** Stage a command batch, then commit one undo step and notification; failures leave all state intact. */
+    transaction(commands: readonly EditorCommand[]): EditorTransactionResult;
     exportJson(pretty?: boolean): string;
     canUndo(): boolean;
     canRedo(): boolean;
 }
+/** Atomic command-batch outcome; a failure identifies the zero-based command index. */
+export type EditorTransactionResult = {
+    ok: true;
+    state: EditorSessionState;
+    changed: boolean;
+} | {
+    ok: false;
+    error: string;
+    commandIndex?: number;
+};
 /** 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 declare function createEditorSession(initial: EditorDocument, historyLimit?: number): EditorSession;
+export declare function createEditorSession(initial: EditorDocument, historyLimit?: number, validateDocument?: (document: EditorDocument) => void): EditorSession;
 /** Compact snapshot of a session state — counts, selection, and the selected object.
  * @internal
  */