@jgengine/core 0.18.1 → 0.21.0

package/dist/editor/document.js

@@ -1,3 +1,7 @@
+import { decodeEditorSimulation } from "./simulation.js";
+import { parseMaterialAssignments, validateMaterialAsset, validateMaterialAssignments } from "../material/materialAsset.js";
+import { authoredHiddenNodes } from "./modelNodeVisibility.js";
+import { parseStaticPrefabBake } from "./staticPrefab.js";
 import { cloneEditorUiDocument, decodeEditorUiDocument } from "../ui/hudDocument.js";
 import { migrateTerrainSnapshot } from "../world/terraform.js";
 import { cloneGridLayer, migrateGridLayer, } from "./grid.js";
@@ -19,6 +23,8 @@ function cloneEnvironment(environment) {
         ...(environment.zenithColor === undefined ? {} : { zenithColor: environment.zenithColor }),
         ...(environment.sunIntensity === undefined ? {} : { sunIntensity: environment.sunIntensity }),
         ...(environment.ambientIntensity === undefined ? {} : { ambientIntensity: environment.ambientIntensity }),
+        ...(environment.sunAzimuth === undefined ? {} : { sunAzimuth: environment.sunAzimuth }),
+        ...(environment.sunElevation === undefined ? {} : { sunElevation: environment.sunElevation }),
         ...(environment.fog === undefined ? {} : { fog: { ...environment.fog } }),
     };
 }
@@ -34,7 +40,7 @@ function cloneDirective(directive) {
         ...(directive.region === undefined ? {} : { region: directive.region }),
         ...(area === undefined ? {} : { area }),
         ...(directive.seed === undefined ? {} : { seed: directive.seed }),
-        ...(directive.meta === undefined ? {} : { meta: { ...directive.meta } }),
+        ...(directive.meta === undefined ? {} : { meta: structuredClone(directive.meta) }),
     };
     if (directive.kind === "scatter") {
         return { ...base, kind: "scatter", asset: directive.asset, density: directive.density,
@@ -66,6 +72,8 @@ function upsertGrids(base, overlay) {
 /** Spread-ready non-placeable fields preserved across document rebuilds. @internal */
 export function editorDocumentExtras(doc) {
     return {
+        ...(doc.simulation === undefined ? {} : { simulation: structuredClone(doc.simulation) }),
+        ...(doc.materialAssets === undefined ? {} : { materialAssets: doc.materialAssets }),
         prefabs: doc.prefabs,
         collections: doc.collections,
         catalogs: doc.catalogs,
@@ -97,14 +105,14 @@ function cloneCatalogEntry(entry) {
     return {
         id: entry.id,
         ...(entry.label === undefined ? {} : { label: entry.label }),
-        ...(entry.meta === undefined ? {} : { meta: { ...entry.meta } }),
+        ...(entry.meta === undefined ? {} : { meta: structuredClone(entry.meta) }),
     };
 }
 function cloneCatalogs(catalogs) {
     return (catalogs ?? []).map((catalog) => ({
         id: catalog.id,
         ...(catalog.label === undefined ? {} : { label: catalog.label }),
-        ...(catalog.schema === undefined ? {} : { schema: catalog.schema }),
+        ...(catalog.schema === undefined ? {} : { schema: structuredClone(catalog.schema) }),
         entries: catalog.entries.map(cloneCatalogEntry),
     }));
 }
@@ -119,38 +127,36 @@ export function cloneEditorDocument(doc) {
     const directives = cloneDirectives(doc.directives);
     return {
         version: 1,
+        ...(doc.simulation === undefined ? {} : { simulation: structuredClone(doc.simulation) }),
         markers: doc.markers.map((marker) => ({
             ...marker,
             position: { ...marker.position },
-            ...(marker.meta === undefined ? {} : { meta: { ...marker.meta } }),
+            ...(marker.meta === undefined ? {} : { meta: structuredClone(marker.meta) }),
         })),
         volumes: doc.volumes.map((volume) => ({
             ...volume,
             center: { ...volume.center },
             ...(volume.halfExtents === undefined ? {} : { halfExtents: { ...volume.halfExtents } }),
-            ...(volume.meta === undefined ? {} : { meta: { ...volume.meta } }),
+            ...(volume.meta === undefined ? {} : { meta: structuredClone(volume.meta) }),
         })),
         paths: doc.paths.map((path) => ({
             ...path,
             points: path.points.map((point) => ({ ...point })),
-            ...(path.meta === undefined ? {} : { meta: { ...path.meta } }),
+            ...(path.meta === undefined ? {} : { meta: structuredClone(path.meta) }),
         })),
         annotations: doc.annotations.map((note) => ({
             ...note,
             position: { ...note.position },
-            ...(note.meta === undefined ? {} : { meta: { ...note.meta } }),
+            ...(note.meta === undefined ? {} : { meta: structuredClone(note.meta) }),
         })),
         prefabs: doc.prefabs.map((prefab) => ({
             ...prefab,
-            fragment: {
-                markers: prefab.fragment.markers.map((marker) => ({ ...marker, position: { ...marker.position } })),
-                volumes: prefab.fragment.volumes.map((volume) => ({ ...volume, center: { ...volume.center } })),
-                paths: prefab.fragment.paths.map((path) => ({ ...path, points: path.points.map((point) => ({ ...point })) })),
-                annotations: prefab.fragment.annotations.map((note) => ({ ...note, position: { ...note.position } })),
-            },
+            ...(prefab.staticBake === undefined ? {} : { staticBake: parseStaticPrefabBake(prefab.staticBake) }),
+            fragment: structuredClone(prefab.fragment),
         })),
         collections: doc.collections.map((collection) => ({ ...collection, memberIds: [...collection.memberIds] })),
         catalogs: cloneCatalogs(doc.catalogs),
+        ...(doc.materialAssets === undefined ? {} : { materialAssets: structuredClone(doc.materialAssets) }),
         ...(doc.grids === undefined ? {} : { grids: doc.grids.map(cloneGridLayer) }),
         ...(doc.terrain === undefined ? {} : { terrain: doc.terrain }),
         ...(ui === undefined ? {} : { ui }),
@@ -172,7 +178,7 @@ function upsertCatalogs(base, overlay) {
         {
             id: catalog.id,
             ...(catalog.label === undefined ? {} : { label: catalog.label }),
-            ...(catalog.schema === undefined ? {} : { schema: catalog.schema }),
+            ...(catalog.schema === undefined ? {} : { schema: structuredClone(catalog.schema) }),
             entries: catalog.entries.map(cloneCatalogEntry),
         },
     ]));
@@ -202,6 +208,7 @@ export function normalizeEditorLayers(input) {
     const directives = cloneDirectives(resolved.directives);
     return {
         version: 1,
+        ...(resolved.simulation === undefined ? {} : { simulation: decodeEditorSimulation(resolved.simulation, { paths: asArray(resolved.paths) }) }),
         markers: asArray(resolved.markers),
         volumes: asArray(resolved.volumes),
         paths: asArray(resolved.paths),
@@ -209,6 +216,7 @@ export function normalizeEditorLayers(input) {
         prefabs: asArray(resolved.prefabs),
         collections: asArray(resolved.collections),
         catalogs: cloneCatalogs(resolved.catalogs),
+        ...(resolved.materialAssets === undefined ? {} : { materialAssets: structuredClone(resolved.materialAssets) }),
         ...(grids === undefined ? {} : { grids }),
         ...(resolved.terrain === undefined ? {} : { terrain: migrateTerrainSnapshot(resolved.terrain) }),
         ...(ui === undefined ? {} : { ui }),
@@ -260,6 +268,8 @@ export function mergeEditorDocuments(...docs) {
         out.prefabs.push(...doc.prefabs);
         out.collections.push(...doc.collections);
         out.catalogs = upsertCatalogs(out.catalogs, doc.catalogs);
+        if (doc.materialAssets !== undefined)
+            out.materialAssets = structuredClone(upsertById(out.materialAssets ?? [], doc.materialAssets));
         const mergedGrids = upsertGrids(out.grids, doc.grids);
         if (mergedGrids !== undefined)
             out.grids = mergedGrids;
@@ -269,6 +279,8 @@ export function mergeEditorDocuments(...docs) {
             out.minimap = cloneMinimapBake(doc.minimap);
         if (doc.environment !== undefined)
             out.environment = cloneEnvironment(doc.environment);
+        if (doc.simulation !== undefined)
+            out.simulation = structuredClone(doc.simulation);
         if (doc.directives !== undefined) {
             out.directives = upsertById(out.directives ?? [], doc.directives);
         }
@@ -290,6 +302,7 @@ export function extractEditorFragment(doc, ids) {
     const wanted = new Set(ids);
     return cloneEditorDocument({
         version: 1,
+        ...(doc.materialAssets === undefined ? {} : { materialAssets: doc.materialAssets.filter((asset) => doc.markers.some((marker) => wanted.has(marker.id) && parseMaterialAssignments(marker.meta?.materialAssignments ?? []).some((item) => item.materialId === asset.id))) }),
         markers: doc.markers.filter((marker) => wanted.has(marker.id)),
         volumes: doc.volumes.filter((volume) => wanted.has(volume.id)),
         paths: doc.paths.filter((path) => wanted.has(path.id)),
@@ -433,6 +446,7 @@ export function createPrefabFragment(doc, ids) {
         z: point.z - origin.z,
     });
     return {
+        ...(extracted.materialAssets === undefined ? {} : { materialAssets: extracted.materialAssets }),
         markers: extracted.markers.map((marker) => ({ ...marker, position: shift(marker.position) })),
         volumes: extracted.volumes.map((volume) => ({ ...volume, center: shift(volume.center) })),
         paths: extracted.paths.map((path) => ({ ...path, points: path.points.map(shift) })),
@@ -606,7 +620,21 @@ function decodeMeta(value, path, errors) {
         errors.push({ path, message: "expected an object" });
         return undefined;
     }
-    return value;
+    if (value.materialAssignments !== undefined) {
+        try {
+            parseMaterialAssignments(value.materialAssignments);
+        }
+        catch (error) {
+            errors.push({ path: `${path}.materialAssignments`, message: String(error) });
+        }
+    }
+    try {
+        authoredHiddenNodes(value);
+    }
+    catch (error) {
+        errors.push({ path: `${path}.hiddenNodes`, message: String(error) });
+    }
+    return structuredClone(value);
 }
 function decodeMarker(item, path, errors) {
     if (!isPlainObject(item)) {
@@ -742,18 +770,55 @@ function decodeNote(item, path, errors) {
         note.meta = meta;
     return note;
 }
+function decodeMaterialAssets(value, path, errors) {
+    if (!Array.isArray(value)) {
+        errors.push({ path, message: "expected material assets" });
+        return [];
+    }
+    const ids = new Set();
+    const assets = [];
+    value.forEach((asset, index) => {
+        const diagnostics = validateMaterialAsset(asset).filter((diagnostic) => diagnostic.severity === "error");
+        for (const diagnostic of diagnostics)
+            errors.push({ path: `${path}[${index}].${diagnostic.path}`, message: diagnostic.message });
+        if (diagnostics.length === 0) {
+            if (ids.has(asset.id))
+                errors.push({ path: `${path}[${index}].id`, message: "duplicate material ID" });
+            ids.add(asset.id);
+            assets.push(structuredClone(asset));
+        }
+    });
+    return assets;
+}
 function decodeFragmentContent(value, path, errors) {
     if (!isPlainObject(value)) {
         errors.push({ path, message: "expected an object" });
         return null;
     }
+    const materialAssets = value.materialAssets === undefined ? undefined : decodeMaterialAssets(value.materialAssets, `${path}.materialAssets`, errors);
+    const markers = decodeArray(value.markers, `${path}.markers`, decodeMarker, errors);
+    validateMarkerMaterialReferences(markers, materialAssets ?? [], path, errors);
     return {
-        markers: decodeArray(value.markers, `${path}.markers`, decodeMarker, errors),
+        ...(materialAssets === undefined ? {} : { materialAssets }),
+        markers,
         volumes: decodeArray(value.volumes, `${path}.volumes`, decodeVolume, errors),
         paths: decodeArray(value.paths, `${path}.paths`, decodePath, errors),
         annotations: decodeArray(value.annotations, `${path}.annotations`, decodeNote, errors),
     };
 }
+function validateMarkerMaterialReferences(markers, assets, path, errors) {
+    for (const [index, marker] of markers.entries()) {
+        if (marker.meta?.materialAssignments === undefined)
+            continue;
+        try {
+            for (const diagnostic of validateMaterialAssignments(parseMaterialAssignments(marker.meta.materialAssignments), assets)) {
+                if (diagnostic.severity === "error")
+                    errors.push({ path: `${path}.markers[${index}].meta.${diagnostic.path}`, message: diagnostic.message });
+            }
+        }
+        catch { }
+    }
+}
 function decodePrefab(item, path, errors) {
     if (!isPlainObject(item)) {
         errors.push({ path, message: "expected an object" });
@@ -766,7 +831,16 @@ function decodePrefab(item, path, errors) {
     const fragment = decodeFragmentContent(item.fragment, `${path}.fragment`, errors);
     if (typeof item.id !== "string" || typeof item.name !== "string" || fragment === null)
         return null;
-    return { id: item.id, name: item.name, fragment };
+    const prefab = { id: item.id, name: item.name, fragment };
+    if (item.staticBake !== undefined) {
+        try {
+            prefab.staticBake = parseStaticPrefabBake(item.staticBake);
+        }
+        catch (error) {
+            errors.push({ path: `${path}.staticBake`, message: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return prefab;
 }
 function decodeCollection(item, path, errors) {
     if (!isPlainObject(item)) {
@@ -1082,7 +1156,7 @@ function decodeEnvironment(value, path, errors) {
             failed = true;
         }
     }
-    for (const key of ["sunIntensity", "ambientIntensity"]) {
+    for (const key of ["sunIntensity", "ambientIntensity", "sunAzimuth", "sunElevation"]) {
         if (value[key] === undefined)
             continue;
         if (typeof value[key] === "number" && Number.isFinite(value[key]))
@@ -1226,6 +1300,7 @@ export function decodeEditorDocument(raw) {
         return { ok: false, errors: [{ path: "$", message: "editor document must be an object" }] };
     }
     const errors = [];
+    const materialAssets = raw.materialAssets === undefined ? undefined : decodeMaterialAssets(raw.materialAssets, "$.materialAssets", errors);
     const markers = decodeArray(raw.markers, "$.markers", decodeMarker, errors);
     const volumes = decodeArray(raw.volumes, "$.volumes", decodeVolume, errors);
     const paths = decodeArray(raw.paths, "$.paths", decodePath, errors);
@@ -1241,6 +1316,15 @@ export function decodeEditorDocument(raw) {
     const minimap = raw.minimap === undefined ? undefined : decodeMinimapBake(raw.minimap, "$.minimap", errors);
     const bakes = raw.bakes === undefined ? undefined : decodeBakes(raw.bakes, "$.bakes", errors);
     const environment = raw.environment === undefined ? undefined : decodeEnvironment(raw.environment, "$.environment", errors);
+    let simulation;
+    if (raw.simulation !== undefined) {
+        try {
+            simulation = decodeEditorSimulation(raw.simulation, { paths });
+        }
+        catch (error) {
+            errors.push({ path: "$.simulation", message: error instanceof Error ? error.message : String(error) });
+        }
+    }
     // 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
@@ -1262,6 +1346,7 @@ export function decodeEditorDocument(raw) {
             }
         });
     }
+    validateMarkerMaterialReferences(markers, materialAssets ?? [], "$", errors);
     if (errors.length > 0)
         return { ok: false, errors };
     const terrain = raw.terrain === undefined ? undefined : migrateTerrainSnapshot(raw.terrain);
@@ -1270,6 +1355,8 @@ export function decodeEditorDocument(raw) {
         ok: true,
         document: {
             version: 1,
+            ...(simulation === undefined ? {} : { simulation }),
+            ...(materialAssets === undefined ? {} : { materialAssets }),
             markers,
             volumes,
             paths,
@@ -1313,6 +1400,7 @@ export function applyEditorDocumentOverlay(base, overlay) {
     const terrain = overlay.terrain ?? base.terrain;
     const minimap = overlay.minimap ?? base.minimap;
     const environment = overlay.environment ?? base.environment;
+    const simulation = overlay.simulation ?? base.simulation;
     const ui = overlay.ui === undefined
         ? cloneEditorUiDocument(base.ui)
         : {
@@ -1324,6 +1412,7 @@ export function applyEditorDocumentOverlay(base, overlay) {
     const grids = upsertGrids(base.grids, overlay.grids);
     return {
         version: 1,
+        ...(simulation === undefined ? {} : { simulation: structuredClone(simulation) }),
         markers: upsertById(base.markers, overlay.markers),
         volumes: upsertById(base.volumes, overlay.volumes),
         paths: upsertById(base.paths, overlay.paths),
@@ -1331,6 +1420,7 @@ export function applyEditorDocumentOverlay(base, overlay) {
         prefabs: upsertById(base.prefabs, overlay.prefabs),
         collections: upsertById(base.collections, overlay.collections),
         catalogs: upsertCatalogs(base.catalogs, overlay.catalogs),
+        ...(base.materialAssets === undefined && overlay.materialAssets === undefined ? {} : { materialAssets: structuredClone(upsertById(base.materialAssets ?? [], overlay.materialAssets ?? [])) }),
         ...(grids === undefined ? {} : { grids }),
         ...(terrain === undefined ? {} : { terrain }),
         ...(ui === undefined ? {} : { ui }),
@@ -1380,6 +1470,17 @@ export function editorDocumentBounds(doc) {
     for (const note of doc.annotations) {
         include(note.position.x, note.position.y, note.position.z);
     }
+    if (doc.terrain !== undefined) {
+        const terrain = doc.terrain;
+        let low = 0;
+        let high = 0;
+        for (const offset of terrain.offsets) {
+            low = Math.min(low, offset);
+            high = Math.max(high, offset);
+        }
+        include(terrain.bounds.minX, low, terrain.bounds.minZ);
+        include(terrain.bounds.maxX, high, terrain.bounds.maxZ);
+    }
     if (!any)
         return null;
     return {

package/dist/editor/environment.js

@@ -25,6 +25,14 @@ export function skyConfigFromEnvironment(env) {
         ...(env.zenithColor === undefined ? {} : { zenithColor: env.zenithColor }),
         ...(env.sunIntensity === undefined ? {} : { sunIntensity: env.sunIntensity }),
         ...(env.ambientIntensity === undefined ? {} : { ambientIntensity: env.ambientIntensity }),
+        ...(env.sunAzimuth === undefined && env.sunElevation === undefined
+            ? {}
+            : {
+                sun: {
+                    ...(env.sunAzimuth === undefined ? {} : { azimuth: env.sunAzimuth }),
+                    ...(env.sunElevation === undefined ? {} : { elevation: env.sunElevation }),
+                },
+            }),
         ...(env.fog === undefined ? {} : { fog: { ...env.fog } }),
     };
 }

package/dist/editor/index.d.ts

@@ -90,6 +90,8 @@ export type { EditorDispatchOptions } from "./commands.js";
 export type { EditorSession } from "./commands.js";
 /** The document plus current selection at a point in editor history. */
 export type { EditorSessionState } from "./commands.js";
+/** Atomic command-batch outcome; a failure identifies the zero-based command index. */
+export type { EditorTransactionResult } from "./commands.js";
 export { applyDocumentPatch, applyRuntimeStateDelta, createDocumentLiveSync, getDocumentLiveSync, installDocumentLiveSync, runtimeEntityWriteBackCommand, subscribeDocumentLiveSyncInstall, } from "./liveSync.js";
 /** Versioned document mutation on the editorΓåöruntime live-sync stream. */
 export type { DocumentPatch, ApplyDocumentPatchResult } from "./liveSync.js";

package/dist/editor/liveSync.d.ts

@@ -4,7 +4,8 @@ import type { EditorDocument, EditorVec3 } from "./types.js";
  * One versioned document mutation on the live-sync stream. `snapshot` replaces the whole
  * document; `commands` replays structural editor commands onto the current document.
  * `baseRevision` must match the receiver's current revision unless `force` is set (document
- * authority from the editor).
+ * authority from the editor). `revision` preserves the authority cursor when replaying: snapshots
+ * may jump forward for reconnect recovery; commands must be the next revision.
  */
 export type DocumentPatch = {
     type: "snapshot";
@@ -26,6 +27,7 @@ export type ApplyDocumentPatchResult = {
 } | {
     ok: false;
     error: string;
+    commandIndex?: number;
 };
 /** One live entity row the runtime may stream to the editor (play-mode inspector feed). */
 export interface RuntimeEntityState {
@@ -92,6 +94,7 @@ export interface DocumentLiveSync {
     }): ApplyDocumentPatchResult;
     /** Document-authoritative full replace (editor session mirror). */
     replaceDocument(document: EditorDocument): DocumentLiveEvent;
+    /** Returns a current snapshot when the requested revision predates retained history. */
     pullPatches(sinceRevision: number): DocumentPatch[];
     subscribeDocument(listener: (event: DocumentLiveEvent) => void): () => void;
     getRuntimeState(): RuntimeStateSnapshot;

package/dist/editor/liveSync.js

@@ -8,6 +8,15 @@ const MAX_RUNTIME_LOG = 128;
  * @capability editor-live-sync apply a versioned document patch onto a live scene document
  */
 export function applyDocumentPatch(document, revision, patch, options) {
+    if (!Number.isSafeInteger(patch.baseRevision) || patch.baseRevision < 0) {
+        return { ok: false, error: "baseRevision must be a nonnegative safe integer" };
+    }
+    if (patch.revision !== undefined && (!Number.isSafeInteger(patch.revision) || patch.revision <= revision)) {
+        return { ok: false, error: "revision must be a safe integer newer than the current revision" };
+    }
+    if (patch.type === "commands" && patch.revision !== undefined && patch.revision !== revision + 1) {
+        return { ok: false, error: "commands revision must immediately follow the current revision" };
+    }
     if (!options?.force && patch.baseRevision !== revision) {
         return {
             ok: false,
@@ -16,7 +25,7 @@ export function applyDocumentPatch(document, revision, patch, options) {
     }
     if (patch.type === "snapshot") {
         const nextDoc = cloneEditorDocument(patch.document);
-        const nextRevision = revision + 1;
+        const nextRevision = patch.revision ?? revision + 1;
         return {
             ok: true,
             document: nextDoc,
@@ -24,15 +33,17 @@ export function applyDocumentPatch(document, revision, patch, options) {
             patch: { ...patch, revision: nextRevision, document: nextDoc },
         };
     }
-    if (patch.commands.length === 0) {
+    if (!Array.isArray(patch.commands) || patch.commands.length === 0) {
         return { ok: false, error: "commands patch is empty" };
     }
-    const session = createEditorSession(cloneEditorDocument(document));
-    for (const command of patch.commands) {
-        session.dispatch(command);
-    }
-    const nextDoc = session.getState().document;
-    const nextRevision = revision + 1;
+    const session = createEditorSession(document);
+    const before = session.getState().document;
+    const result = session.transaction(patch.commands);
+    if (!result.ok)
+        return result;
+    const changed = result.state.document !== before;
+    const nextDoc = changed ? result.state.document : document;
+    const nextRevision = changed ? revision + 1 : revision;
     return {
         ok: true,
         document: nextDoc,
@@ -146,7 +157,8 @@ export function createDocumentLiveSync(initial) {
             const result = applyDocumentPatch(document, revision, patch, options);
             if (!result.ok)
                 return result;
-            commit(result);
+            if (result.revision !== revision)
+                commit(result);
             return result;
         },
         replaceDocument(next) {
@@ -157,7 +169,11 @@ export function createDocumentLiveSync(initial) {
             return commit(result);
         },
         pullPatches(sinceRevision) {
-            return patchLog.filter((patch) => (patch.revision ?? 0) > sinceRevision);
+            const patches = patchLog.filter((patch) => (patch.revision ?? 0) > sinceRevision);
+            if (patches.length > 0 && patches[0].baseRevision !== sinceRevision) {
+                return [{ type: "snapshot", baseRevision: sinceRevision, revision, document: cloneEditorDocument(document) }];
+            }
+            return patches;
         },
         subscribeDocument(listener) {
             documentListeners.add(listener);

package/dist/editor/materialAuthoring.d.ts

@@ -0,0 +1,14 @@
+import type { ModelConfig } from "../game/playableGame.js";
+import { type MaterialAsset, type MaterialAssignment, type MaterialSelector } from "../material/materialAsset.js";
+import type { EditorDocument } from "./types.js";
+/** Validate and copy a material asset at the editor boundary. */
+export declare function parseEditorMaterialAsset(value: unknown): MaterialAsset;
+/**
+ * Read named assignments from authored marker metadata without inferring whole-model overrides.
+ * @capability authored-material-slots read validated material assignments from editor marker metadata
+ */
+export declare function authoredMaterialAssignments(meta: Record<string, unknown> | undefined): MaterialAssignment[];
+/** Compare selector meaning independently of serialized property order. @internal */
+export declare function sameMaterialSelector(a: MaterialSelector, b: MaterialSelector): boolean;
+/** Apply authored references; document assets and selectors override model defaults of the same identity. */
+export declare function modelWithAuthoredMaterials(model: ModelConfig | undefined, document: Pick<EditorDocument, "markers" | "materialAssets">, instanceId: string): ModelConfig | undefined;

package/dist/editor/materialAuthoring.js

@@ -0,0 +1,38 @@
+import { parseMaterialAssignments, validateMaterialAsset, validateMaterialAssignments } from "../material/materialAsset.js";
+/** Validate and copy a material asset at the editor boundary. */
+export function parseEditorMaterialAsset(value) {
+    const errors = validateMaterialAsset(value).filter((item) => item.severity === "error");
+    if (errors.length > 0)
+        throw new TypeError(errors.map((item) => `${item.path}: ${item.message}`).join("; "));
+    return structuredClone(value);
+}
+/**
+ * Read named assignments from authored marker metadata without inferring whole-model overrides.
+ * @capability authored-material-slots read validated material assignments from editor marker metadata
+ */
+export function authoredMaterialAssignments(meta) {
+    return meta?.materialAssignments === undefined ? [] : parseMaterialAssignments(meta.materialAssignments);
+}
+/** Compare selector meaning independently of serialized property order. @internal */
+export function sameMaterialSelector(a, b) {
+    return a.mesh === b.mesh && a.slot === b.slot && a.slotIndex === b.slotIndex;
+}
+/** Apply authored references; document assets and selectors override model defaults of the same identity. */
+export function modelWithAuthoredMaterials(model, document, instanceId) {
+    if (model === undefined)
+        return model;
+    const marker = document.markers.find((item) => item.id === instanceId);
+    const assignments = authoredMaterialAssignments(marker?.meta);
+    const modelAssignments = model.materialAssignments ?? [];
+    if (assignments.length === 0 && modelAssignments.length === 0)
+        return model;
+    const assetsById = new Map((model.materialAssets ?? []).map((asset) => [asset.id, asset]));
+    for (const asset of document.materialAssets ?? [])
+        assetsById.set(asset.id, asset);
+    const assets = [...assetsById.values()];
+    const resolvedAssignments = [...modelAssignments.filter((item) => !assignments.some((authored) => sameMaterialSelector(item.selector, authored.selector))), ...assignments];
+    const errors = validateMaterialAssignments(resolvedAssignments, assets).filter((item) => item.severity === "error");
+    if (errors.length > 0)
+        throw new TypeError(errors.map((item) => `${item.path}: ${item.message}`).join("; "));
+    return { ...model, materialAssets: assets, materialAssignments: resolvedAssignments };
+}

package/dist/editor/modelNodeVisibility.d.ts

@@ -0,0 +1,11 @@
+import type { ModelConfig } from "../game/playableGame.js";
+import type { EditorMarker } from "./types.js";
+/** Validate and copy exact node names; an empty list selects no hidden subtrees. */
+export declare function parseModelHiddenNodes(value: unknown): readonly string[] | undefined;
+/**
+ * Read marker visibility metadata; an empty list clears model defaults.
+ * @capability model-node-visibility read authored per-placement model subtree selections
+ */
+export declare function authoredHiddenNodes(meta: Record<string, unknown> | undefined): readonly string[] | undefined;
+/** Apply a placement's authored visibility without erasing omitted game model defaults. */
+export declare function modelWithAuthoredNodeVisibility(model: ModelConfig | undefined, marker: Pick<EditorMarker, "meta"> | undefined): ModelConfig | undefined;

package/dist/editor/modelNodeVisibility.js

@@ -0,0 +1,29 @@
+/** Validate and copy exact node names; an empty list selects no hidden subtrees. */
+export function parseModelHiddenNodes(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new TypeError("hiddenNodes must be an array of nonblank node names");
+    }
+    for (const name of value) {
+        if (typeof name !== "string" || name.trim().length === 0)
+            throw new TypeError("hiddenNodes must be an array of nonblank node names");
+    }
+    return [...value];
+}
+/**
+ * Read marker visibility metadata; an empty list clears model defaults.
+ * @capability model-node-visibility read authored per-placement model subtree selections
+ */
+export function authoredHiddenNodes(meta) {
+    return parseModelHiddenNodes(meta?.hiddenNodes);
+}
+/** Apply a placement's authored visibility without erasing omitted game model defaults. */
+export function modelWithAuthoredNodeVisibility(model, marker) {
+    if (model === undefined)
+        return undefined;
+    const hiddenNodes = authoredHiddenNodes(marker?.meta);
+    if (hiddenNodes === undefined || (model.hiddenNodes?.length === hiddenNodes.length && hiddenNodes.every((name, index) => model.hiddenNodes[index] === name)))
+        return model;
+    return { ...model, hiddenNodes };
+}

package/dist/editor/movementCatalog.d.ts

@@ -0,0 +1,90 @@
+import type { PlayerMovementConfig } from "../game/playableGame.js";
+import type { PhysicsConfig } from "../game/defineGame.js";
+import type { ParamSchema } from "../scene/sceneKinds.js";
+import type { EditorCatalogData } from "./types.js";
+/** Numeric character controls a game elects to author through its own named catalog rows. */
+export interface AuthoredMovementValues {
+    walkSpeed?: number;
+    gravity?: number;
+    jumpVelocity?: number;
+    stepHeight?: number;
+    /** Optional positive heightfield collision span from feet; independent of model and camera scale. */
+    collisionHeight?: number;
+    /** Optional heightfield rise/run limit; omitted controls retain the game's movement policy. */
+    maxClimbGrade?: number;
+    groundAcceleration?: number;
+    airAcceleration?: number;
+    groundFriction?: number;
+    runMultiplier?: number;
+    crouchMultiplier?: number;
+    jumpBufferMs?: number;
+    coyoteMs?: number;
+    /** Rising speed retained on early jump release, from 0 to 1. */
+    jumpCutFactor?: number;
+    apexGravityScale?: number;
+    apexSpeed?: number;
+    fallGravityScale?: number;
+    landingRecoveryMs?: number;
+    /** Initial landing speed multiplier; values above 1 retain the existing runtime contract. */
+    landingSpeedScale?: number;
+}
+/** Only authored values, ready to overlay on a game's existing movement and physics policy. */
+export interface AuthoredMovementConfig {
+    readonly walkSpeed?: number;
+    readonly physics?: {
+        readonly gravity?: number;
+        readonly jumpVelocity?: number;
+    };
+    readonly movement?: Pick<PlayerMovementConfig, "stepHeight" | "collisionHeight" | "maxClimbGrade" | "feel">;
+}
+/** A persisted movement value rejected before it can replace the game's current setting. */
+export interface AuthoredMovementDiagnostic {
+    readonly path: string;
+    readonly message: string;
+    readonly repair: string;
+}
+/** Valid partial tuning plus located rejected values; absent rows leave game defaults intact. */
+export interface AuthoredMovementResult {
+    readonly config: AuthoredMovementConfig;
+    readonly diagnostics: readonly AuthoredMovementDiagnostic[];
+}
+/** Structural authored catalog input; an immutable EditorDocument satisfies it. */
+export interface MovementCatalogDocumentLike {
+    readonly catalogs: readonly EditorCatalogData[];
+}
+/** Game-owned callbacks, collision and physics settings retained beneath authored numeric controls. */
+export interface AuthoredMovementDefaults {
+    readonly movement?: PlayerMovementConfig;
+    readonly physics?: PhysicsConfig;
+}
+/** Stable runtime objects whose numeric getters resolve the current authored document. */
+export interface AuthoredMovementBinding {
+    readonly movement: PlayerMovementConfig;
+    readonly physics: PhysicsConfig;
+    readonly diagnostics: readonly AuthoredMovementDiagnostic[];
+}
+/**
+ * Creates editor/RPC controls only for the values a game supplies, with those game's defaults.
+ * Gravity retains the game's sign convention; collision height is positive, other controls nonnegative.
+ * Jump release is bounded to 0..1; supplied deeper jump controls share a collapsed response group.
+ * @capability editor-movement author game-chosen character movement controls through ordinary catalog rows
+ */
+export declare function createMovementSchema(defaults: AuthoredMovementValues): ParamSchema;
+/**
+ * Reads one game-named row as partial runtime tuning, retaining game defaults for omitted or invalid
+ * values. Rejected values include their document path and repair; no policy callbacks are replaced.
+ * @capability editor-movement resolve saved movement controls without replacing a game's character rules
+ */
+export declare function readAuthoredMovement(document: MovementCatalogDocumentLike, catalogId: string, entryId: string): AuthoredMovementResult;
+/**
+ * Memoizes movement resolution by immutable document identity; reads the latest document on every
+ * call while catalog lookup and diagnostics run only after authoring changes.
+ * @capability editor-movement consume live saved movement tuning with bounded per-frame work
+ */
+export declare function createAuthoredMovementReader(getDocument: () => MovementCatalogDocumentLike, catalogId: string, entryId: string): () => AuthoredMovementResult;
+/**
+ * Binds live authored numeric controls onto stable runtime objects, preserving the game's callbacks,
+ * collision, backend and other policy. The movement controller reads these getters each step.
+ * @capability editor-movement bind live character tuning while preserving distinctive game policy
+ */
+export declare function bindAuthoredMovement(read: () => AuthoredMovementResult, defaults: AuthoredMovementDefaults): AuthoredMovementBinding;