@relu-interactives/spatial-ecs 0.2.20 → 0.2.21

package/dist/index.d.cts

@@ -1,9 +1,9 @@
-import { k as EcsSystem, C as Component, W as WorldEntityView, T as TransformComponent, l as World, S as SpawnPrefabSource, m as SpawnPrefabOptions, n as ComponentClass, o as ParentLookup, p as EcsEntityKind, O as ObjectManagementSystem, q as EntityId, r as SubtreeSnapshot, s as ExternalRefWarning } from './System-BjwOBx81.cjs';
-export { A as AssetInput, t as CheckboxInput, u as ColorInput, v as ComponentFactory, w as ComponentInput, x as ComponentKind, y as DropdownInput, z as DropdownOption, B as EcsComponentFactoryKind, F as EcsEntityEditorKind, G as EntityInput, H as FloatInput, I as InputSystem, J as IntersectionResult, K as KeyboardKey, L as KeyboardKeys, M as MouseButton, N as PREFAB_FILE_VERSION, Q as PrefabAsset, R as RemapSnapshotOptions, U as RenderSystem, X as SelectionListener, Y as SliderInput, Z as TextInput, _ as ToggleInput, $ as TransformSyncSystem, a0 as Vec3, a1 as Vector2Input, a2 as Vector3Input, a3 as clearPrefabCache, a4 as despawnPrefab, a5 as loadPrefab, a6 as parsePrefabAsset, a7 as remapSnapshotEntityIds, a8 as setPrefabAssetUrlResolver, a9 as spawnPrefab } from './System-BjwOBx81.cjs';
+import { k as EcsSystem, C as Component, W as WorldEntityView, T as TransformComponent, l as World, S as SpawnPrefabSource, m as SpawnPrefabOptions, n as ComponentClass, o as ParentLookup, p as EcsEntityKind, O as ObjectManagementSystem, q as SubtreeSnapshot, r as EntityId, s as ExternalRefWarning } from './System-me3iAcMF.cjs';
+export { A as AssetInput, t as CheckboxInput, u as ColorInput, v as ComponentFactory, w as ComponentInput, x as ComponentKind, y as DropdownInput, z as DropdownOption, B as EcsComponentFactoryKind, F as EcsEntityEditorKind, G as EntityInput, H as FloatInput, I as InputSystem, J as IntersectionResult, K as KeyboardKey, L as KeyboardKeys, M as MouseButton, N as PREFAB_FILE_VERSION, Q as PREFAB_FILE_VERSION_NESTED, R as PrefabAsset, U as RemapSnapshotOptions, X as RenderSystem, Y as SelectionListener, Z as SliderInput, _ as TextInput, $ as ToggleInput, a0 as TransformSyncSystem, a1 as Vec3, a2 as Vector2Input, a3 as Vector3Input, a4 as clearPrefabCache, a5 as despawnPrefab, a6 as loadPrefab, a7 as parsePrefabAsset, a8 as prefabFileVersionFor, a9 as remapSnapshotEntityIds, aa as setPrefabAssetUrlResolver, ab as spawnPrefab } from './System-me3iAcMF.cjs';
 import * as THREE from 'three';
-import { O as Object3DRef } from './Video-B8yVI1tF.cjs';
-export { a3 as AnimationStateCallbacks, a4 as AnimationStateMachine, a5 as AnimationStateManager, a6 as StateMachine } from './Video-B8yVI1tF.cjs';
-export { i as CoreComponents } from './index-LHLKpJhZ.cjs';
+import { O as Object3DRef } from './Video-U9hAnf9y.cjs';
+export { a3 as AnimationStateCallbacks, a4 as AnimationStateMachine, a5 as AnimationStateManager, a6 as StateMachine } from './Video-U9hAnf9y.cjs';
+export { i as CoreComponents } from './index-CZo5I5Gs.cjs';
 export { AnimationSystem, AudioSystem, CameraSyncSystem, EnvironmentSyncSystem, InstancedMeshSystem, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, ObjectVisibilitySystem, PhysicsSyncSystem, PostprocessingSyncSystem, ScriptBehaviourSystem, SelectionContext, VideoSystem } from './systems/index.cjs';
 export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.cjs';
 import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
@@ -390,6 +390,30 @@ declare function loadSharedGltf(url: string, load: () => Promise<GLTF>): Promise
  */
 declare function clearModelCache(url?: string): void;
 
+/**
+ * Pure JSON-space prefab patching: apply a nested prefab's NEW definition to
+ * every top-level-relative instance region inside a HOST document snapshot,
+ * honoring the region's stored per-property overrides. This is how edits to
+ * a child prefab cascade through the `.prefab` files that nest it (no live
+ * world exists for files). Reused later by `.scene` assets.
+ *
+ * Trust model: the region's stored override list (refreshed at every host
+ * save with `+node` addition markers) IS the user state — no old base is
+ * needed. Consequently the operation is idempotent: re-applying the same
+ * definition yields `changed: false`.
+ */
+
+type ApplyPrefabToSnapshotResult = {
+    snapshot: SubtreeSnapshot;
+    changed: boolean;
+};
+/**
+ * Patch every top-level-relative nested instance of `nestedUrl` inside
+ * `hostSnapshot` with `newNestedSnapshot`. Deeper nesting (B inside C inside
+ * A) is NOT touched here — it cascades through C's own file.
+ */
+declare function applyPrefabToSnapshotInstances(hostSnapshot: SubtreeSnapshot, nestedUrl: string, newNestedSnapshot: SubtreeSnapshot): ApplyPrefabToSnapshotResult;
+
 /**
  * Collect the given roots plus every descendant, BFS parent-first, using the
  * `ParentId` component edges. Parent-first ordering matters: serialization
@@ -398,6 +422,71 @@ declare function clearModelCache(url?: string): void;
  */
 declare function collectEntitySubtree(world: World, rootIds: EntityId[]): EntityId[];
 
+/**
+ * Direct (top-level-relative) prefab urls a document depends on — the edges
+ * of the nesting graph. Deeper nesting is reached transitively through each
+ * dependency's own file, never directly.
+ */
+declare function collectDirectPrefabDependencies(snapshot: SubtreeSnapshot): string[];
+
+/**
+ * Scoped node identity for (possibly nested) prefab documents.
+ *
+ * A nodeKey identifies an entity within one prefab document even when the
+ * document contains nested instances of other prefabs (whose nodeIds repeat
+ * per instance). Formula (parent-first walk from the scope root, inherited
+ * `prefix`; the scope root's prefix is "" even if it carries PrefabInstance):
+ *
+ * - entity WITHOUT PrefabInstance:  key = prefix + nodeId, children inherit
+ *   the same prefix;
+ * - entity WITH PrefabInstance (non-scope-root): childPrefix = prefix +
+ *   instanceId + "/";  key = childPrefix + nodeId (self-inclusive — sibling
+ *   instances of the SAME prefab get distinct keys); children inherit
+ *   childPrefix.
+ *
+ * Documents with no nested instances degenerate to bare nodeIds, so v1 files
+ * and override lists keep their exact meaning.
+ */
+
+declare const NODE_KEY_SEPARATOR = "/";
+/**
+ * Reserved override "component" marking a node ADDED by the host document
+ * inside a nested instance region (`"<nodeKey>|+node|"`). File patching
+ * trusts stored overrides (the old base is unavailable), so without the
+ * marker a host-authored node inside the region would be indistinguishable
+ * from a node the child prefab removed — and get deleted.
+ */
+declare const ADDED_NODE_MARKER_COMPONENT = "+node";
+type NodeKeyMaps = {
+    idToKey: Map<number, string>;
+    keyToId: Map<string, number>;
+    /** nodeKey of the scope root (bare nodeId), or null when it has none. */
+    rootKey: string | null;
+    /** Entity ids of NESTED instance roots (non-scope-root PrefabInstance). */
+    boundaryIds: Map<number, {
+        url: string;
+        instanceId: string;
+    }>;
+};
+declare function buildNodeKeyMapsFromSnapshot(snapshot: SubtreeSnapshot, options?: {
+    scopeRootEntityId?: number;
+}): NodeKeyMaps;
+/** JSON-space subtree ids (root first, BFS) via ParentId edges. */
+declare function collectSnapshotSubtreeIds(snapshot: SubtreeSnapshot, rootEntityId: number): number[];
+type NestedRegion = {
+    rootEntityId: number;
+    url: string;
+    instanceId: string;
+    overrides: string[];
+};
+/**
+ * TOP-LEVEL-RELATIVE nested instance regions of a document: instance roots
+ * that are not the scope root and not themselves inside another region.
+ * Deeper nesting is reached by cascading through the intermediate prefab's
+ * own file, never directly.
+ */
+declare function findTopLevelNestedRegions(snapshot: SubtreeSnapshot): NestedRegion[];
+
 type InstantiateSubtreeResult = {
     /** Live entity id of the subtree root, or null when nothing hydrated. */
     rootId: EntityId | null;
@@ -485,11 +574,20 @@ declare function collectDiffPaths(base: unknown, current: unknown, prefix?: stri
  * subtree snapshots carrying PrefabNode identity) and return the encoded
  * override list: every path where the instance deviates from the base.
  *
- * v1 policies: components missing on the instance produce no override
- * (apply re-adds them); components/nodes only on the instance are local
- * additions and produce no override (apply never touches them).
+ * Identity is nodeKey-scoped ({@link buildNodeKeyMapsFromSnapshot}), so
+ * nested instance regions diff correctly; for nested-free documents the
+ * keys degenerate to bare nodeIds (v1 behavior unchanged).
+ *
+ * Policies: components missing on the instance produce no override (apply
+ * re-adds them); components/nodes only on the instance are local additions
+ * and produce no override — EXCEPT when `emitAdditionMarkers` is set
+ * (file-space callers), which records `"<key>|+node|"` for instance nodes
+ * absent from the base so pure-JSON patching never deletes host-authored
+ * nodes inside nested regions.
  */
-declare function computeInstanceOverrides(baseSnapshot: SubtreeSnapshot, instanceSnapshot: SubtreeSnapshot): string[];
+declare function computeInstanceOverrides(baseSnapshot: SubtreeSnapshot, instanceSnapshot: SubtreeSnapshot, options?: {
+    emitAdditionMarkers?: boolean;
+}): string[];
 /**
  * Merge a component's NEW canonical file value with an instance's canonical
  * value, preserving the instance side at every overridden path. An empty
@@ -519,4 +617,4 @@ declare function serializeEntitySubtree(world: World, rootId: EntityId, options?
     maxDepth?: number;
 }): SerializeEntitySubtreeResult;
 
-export { Behaviour, Component, type ComponentValueMaps, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, EntityId, ExternalRefWarning, HYDRATABLE_ENTITY_KINDS, type HydrateOptions, type HydrateWorldFromSnapshotResult, type InstantiateSubtreeResult, type NodeMaps, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, type SerializeEntitySubtreeResult, SpawnPrefabOptions, SpawnPrefabSource, SubtreeSnapshot, World, WorldEntityView, buildComponentValueMaps, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearModelCache, collectDiffPaths, collectEntitySubtree, computeInstanceOverrides, decanonicalizeComponentValue, encodeOverride, findSnapshotRootEntityIds, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadSharedGltf, mergeComponentValue, parseOverride, resolveDracoDecoderPath, restoreComponentState, restorePostCreateComponents, serializeEntitySubtree, setDracoDecoderPath };
+export { ADDED_NODE_MARKER_COMPONENT, type ApplyPrefabToSnapshotResult, Behaviour, Component, type ComponentValueMaps, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, EntityId, ExternalRefWarning, HYDRATABLE_ENTITY_KINDS, type HydrateOptions, type HydrateWorldFromSnapshotResult, type InstantiateSubtreeResult, NODE_KEY_SEPARATOR, type NestedRegion, type NodeKeyMaps, type NodeMaps, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, type SerializeEntitySubtreeResult, SpawnPrefabOptions, SpawnPrefabSource, SubtreeSnapshot, World, WorldEntityView, applyPrefabToSnapshotInstances, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearModelCache, collectDiffPaths, collectDirectPrefabDependencies, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, decanonicalizeComponentValue, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadSharedGltf, mergeComponentValue, parseOverride, resolveDracoDecoderPath, restoreComponentState, restorePostCreateComponents, serializeEntitySubtree, setDracoDecoderPath };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { k as EcsSystem, C as Component, W as WorldEntityView, T as TransformComponent, l as World, S as SpawnPrefabSource, m as SpawnPrefabOptions, n as ComponentClass, o as ParentLookup, p as EcsEntityKind, O as ObjectManagementSystem, q as EntityId, r as SubtreeSnapshot, s as ExternalRefWarning } from './System-BjwOBx81.js';
-export { A as AssetInput, t as CheckboxInput, u as ColorInput, v as ComponentFactory, w as ComponentInput, x as ComponentKind, y as DropdownInput, z as DropdownOption, B as EcsComponentFactoryKind, F as EcsEntityEditorKind, G as EntityInput, H as FloatInput, I as InputSystem, J as IntersectionResult, K as KeyboardKey, L as KeyboardKeys, M as MouseButton, N as PREFAB_FILE_VERSION, Q as PrefabAsset, R as RemapSnapshotOptions, U as RenderSystem, X as SelectionListener, Y as SliderInput, Z as TextInput, _ as ToggleInput, $ as TransformSyncSystem, a0 as Vec3, a1 as Vector2Input, a2 as Vector3Input, a3 as clearPrefabCache, a4 as despawnPrefab, a5 as loadPrefab, a6 as parsePrefabAsset, a7 as remapSnapshotEntityIds, a8 as setPrefabAssetUrlResolver, a9 as spawnPrefab } from './System-BjwOBx81.js';
+import { k as EcsSystem, C as Component, W as WorldEntityView, T as TransformComponent, l as World, S as SpawnPrefabSource, m as SpawnPrefabOptions, n as ComponentClass, o as ParentLookup, p as EcsEntityKind, O as ObjectManagementSystem, q as SubtreeSnapshot, r as EntityId, s as ExternalRefWarning } from './System-me3iAcMF.js';
+export { A as AssetInput, t as CheckboxInput, u as ColorInput, v as ComponentFactory, w as ComponentInput, x as ComponentKind, y as DropdownInput, z as DropdownOption, B as EcsComponentFactoryKind, F as EcsEntityEditorKind, G as EntityInput, H as FloatInput, I as InputSystem, J as IntersectionResult, K as KeyboardKey, L as KeyboardKeys, M as MouseButton, N as PREFAB_FILE_VERSION, Q as PREFAB_FILE_VERSION_NESTED, R as PrefabAsset, U as RemapSnapshotOptions, X as RenderSystem, Y as SelectionListener, Z as SliderInput, _ as TextInput, $ as ToggleInput, a0 as TransformSyncSystem, a1 as Vec3, a2 as Vector2Input, a3 as Vector3Input, a4 as clearPrefabCache, a5 as despawnPrefab, a6 as loadPrefab, a7 as parsePrefabAsset, a8 as prefabFileVersionFor, a9 as remapSnapshotEntityIds, aa as setPrefabAssetUrlResolver, ab as spawnPrefab } from './System-me3iAcMF.js';
 import * as THREE from 'three';
-import { O as Object3DRef } from './Video-B9z5AtIf.js';
-export { a3 as AnimationStateCallbacks, a4 as AnimationStateMachine, a5 as AnimationStateManager, a6 as StateMachine } from './Video-B9z5AtIf.js';
-export { i as CoreComponents } from './index-BBI2YdCu.js';
+import { O as Object3DRef } from './Video-DHnxjGhW.js';
+export { a3 as AnimationStateCallbacks, a4 as AnimationStateMachine, a5 as AnimationStateManager, a6 as StateMachine } from './Video-DHnxjGhW.js';
+export { i as CoreComponents } from './index-D7FSg0Au.js';
 export { AnimationSystem, AudioSystem, CameraSyncSystem, EnvironmentSyncSystem, InstancedMeshSystem, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, ObjectVisibilitySystem, PhysicsSyncSystem, PostprocessingSyncSystem, ScriptBehaviourSystem, SelectionContext, VideoSystem } from './systems/index.js';
 export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.js';
 import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
@@ -390,6 +390,30 @@ declare function loadSharedGltf(url: string, load: () => Promise<GLTF>): Promise
  */
 declare function clearModelCache(url?: string): void;
 
+/**
+ * Pure JSON-space prefab patching: apply a nested prefab's NEW definition to
+ * every top-level-relative instance region inside a HOST document snapshot,
+ * honoring the region's stored per-property overrides. This is how edits to
+ * a child prefab cascade through the `.prefab` files that nest it (no live
+ * world exists for files). Reused later by `.scene` assets.
+ *
+ * Trust model: the region's stored override list (refreshed at every host
+ * save with `+node` addition markers) IS the user state — no old base is
+ * needed. Consequently the operation is idempotent: re-applying the same
+ * definition yields `changed: false`.
+ */
+
+type ApplyPrefabToSnapshotResult = {
+    snapshot: SubtreeSnapshot;
+    changed: boolean;
+};
+/**
+ * Patch every top-level-relative nested instance of `nestedUrl` inside
+ * `hostSnapshot` with `newNestedSnapshot`. Deeper nesting (B inside C inside
+ * A) is NOT touched here — it cascades through C's own file.
+ */
+declare function applyPrefabToSnapshotInstances(hostSnapshot: SubtreeSnapshot, nestedUrl: string, newNestedSnapshot: SubtreeSnapshot): ApplyPrefabToSnapshotResult;
+
 /**
  * Collect the given roots plus every descendant, BFS parent-first, using the
  * `ParentId` component edges. Parent-first ordering matters: serialization
@@ -398,6 +422,71 @@ declare function clearModelCache(url?: string): void;
  */
 declare function collectEntitySubtree(world: World, rootIds: EntityId[]): EntityId[];
 
+/**
+ * Direct (top-level-relative) prefab urls a document depends on — the edges
+ * of the nesting graph. Deeper nesting is reached transitively through each
+ * dependency's own file, never directly.
+ */
+declare function collectDirectPrefabDependencies(snapshot: SubtreeSnapshot): string[];
+
+/**
+ * Scoped node identity for (possibly nested) prefab documents.
+ *
+ * A nodeKey identifies an entity within one prefab document even when the
+ * document contains nested instances of other prefabs (whose nodeIds repeat
+ * per instance). Formula (parent-first walk from the scope root, inherited
+ * `prefix`; the scope root's prefix is "" even if it carries PrefabInstance):
+ *
+ * - entity WITHOUT PrefabInstance:  key = prefix + nodeId, children inherit
+ *   the same prefix;
+ * - entity WITH PrefabInstance (non-scope-root): childPrefix = prefix +
+ *   instanceId + "/";  key = childPrefix + nodeId (self-inclusive — sibling
+ *   instances of the SAME prefab get distinct keys); children inherit
+ *   childPrefix.
+ *
+ * Documents with no nested instances degenerate to bare nodeIds, so v1 files
+ * and override lists keep their exact meaning.
+ */
+
+declare const NODE_KEY_SEPARATOR = "/";
+/**
+ * Reserved override "component" marking a node ADDED by the host document
+ * inside a nested instance region (`"<nodeKey>|+node|"`). File patching
+ * trusts stored overrides (the old base is unavailable), so without the
+ * marker a host-authored node inside the region would be indistinguishable
+ * from a node the child prefab removed — and get deleted.
+ */
+declare const ADDED_NODE_MARKER_COMPONENT = "+node";
+type NodeKeyMaps = {
+    idToKey: Map<number, string>;
+    keyToId: Map<string, number>;
+    /** nodeKey of the scope root (bare nodeId), or null when it has none. */
+    rootKey: string | null;
+    /** Entity ids of NESTED instance roots (non-scope-root PrefabInstance). */
+    boundaryIds: Map<number, {
+        url: string;
+        instanceId: string;
+    }>;
+};
+declare function buildNodeKeyMapsFromSnapshot(snapshot: SubtreeSnapshot, options?: {
+    scopeRootEntityId?: number;
+}): NodeKeyMaps;
+/** JSON-space subtree ids (root first, BFS) via ParentId edges. */
+declare function collectSnapshotSubtreeIds(snapshot: SubtreeSnapshot, rootEntityId: number): number[];
+type NestedRegion = {
+    rootEntityId: number;
+    url: string;
+    instanceId: string;
+    overrides: string[];
+};
+/**
+ * TOP-LEVEL-RELATIVE nested instance regions of a document: instance roots
+ * that are not the scope root and not themselves inside another region.
+ * Deeper nesting is reached by cascading through the intermediate prefab's
+ * own file, never directly.
+ */
+declare function findTopLevelNestedRegions(snapshot: SubtreeSnapshot): NestedRegion[];
+
 type InstantiateSubtreeResult = {
     /** Live entity id of the subtree root, or null when nothing hydrated. */
     rootId: EntityId | null;
@@ -485,11 +574,20 @@ declare function collectDiffPaths(base: unknown, current: unknown, prefix?: stri
  * subtree snapshots carrying PrefabNode identity) and return the encoded
  * override list: every path where the instance deviates from the base.
  *
- * v1 policies: components missing on the instance produce no override
- * (apply re-adds them); components/nodes only on the instance are local
- * additions and produce no override (apply never touches them).
+ * Identity is nodeKey-scoped ({@link buildNodeKeyMapsFromSnapshot}), so
+ * nested instance regions diff correctly; for nested-free documents the
+ * keys degenerate to bare nodeIds (v1 behavior unchanged).
+ *
+ * Policies: components missing on the instance produce no override (apply
+ * re-adds them); components/nodes only on the instance are local additions
+ * and produce no override — EXCEPT when `emitAdditionMarkers` is set
+ * (file-space callers), which records `"<key>|+node|"` for instance nodes
+ * absent from the base so pure-JSON patching never deletes host-authored
+ * nodes inside nested regions.
  */
-declare function computeInstanceOverrides(baseSnapshot: SubtreeSnapshot, instanceSnapshot: SubtreeSnapshot): string[];
+declare function computeInstanceOverrides(baseSnapshot: SubtreeSnapshot, instanceSnapshot: SubtreeSnapshot, options?: {
+    emitAdditionMarkers?: boolean;
+}): string[];
 /**
  * Merge a component's NEW canonical file value with an instance's canonical
  * value, preserving the instance side at every overridden path. An empty
@@ -519,4 +617,4 @@ declare function serializeEntitySubtree(world: World, rootId: EntityId, options?
     maxDepth?: number;
 }): SerializeEntitySubtreeResult;
 
-export { Behaviour, Component, type ComponentValueMaps, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, EntityId, ExternalRefWarning, HYDRATABLE_ENTITY_KINDS, type HydrateOptions, type HydrateWorldFromSnapshotResult, type InstantiateSubtreeResult, type NodeMaps, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, type SerializeEntitySubtreeResult, SpawnPrefabOptions, SpawnPrefabSource, SubtreeSnapshot, World, WorldEntityView, buildComponentValueMaps, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearModelCache, collectDiffPaths, collectEntitySubtree, computeInstanceOverrides, decanonicalizeComponentValue, encodeOverride, findSnapshotRootEntityIds, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadSharedGltf, mergeComponentValue, parseOverride, resolveDracoDecoderPath, restoreComponentState, restorePostCreateComponents, serializeEntitySubtree, setDracoDecoderPath };
+export { ADDED_NODE_MARKER_COMPONENT, type ApplyPrefabToSnapshotResult, Behaviour, Component, type ComponentValueMaps, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, EntityId, ExternalRefWarning, HYDRATABLE_ENTITY_KINDS, type HydrateOptions, type HydrateWorldFromSnapshotResult, type InstantiateSubtreeResult, NODE_KEY_SEPARATOR, type NestedRegion, type NodeKeyMaps, type NodeMaps, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, type SerializeEntitySubtreeResult, SpawnPrefabOptions, SpawnPrefabSource, SubtreeSnapshot, World, WorldEntityView, applyPrefabToSnapshotInstances, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearModelCache, collectDiffPaths, collectDirectPrefabDependencies, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, decanonicalizeComponentValue, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadSharedGltf, mergeComponentValue, parseOverride, resolveDracoDecoderPath, restoreComponentState, restorePostCreateComponents, serializeEntitySubtree, setDracoDecoderPath };

package/dist/index.js

@@ -1,11 +1,11 @@
-import { MeshGeometrySystem, InstancedMeshSystem, EnvironmentSyncSystem, PostprocessingSyncSystem, LightSyncSystem, MaterialSyncSystem, PhysicsSyncSystem, AnimationSystem, AudioSystem, VideoSystem, CameraSyncSystem, TransformSyncSystem, ObjectVisibilitySystem, RenderSystem, spawnPrefab, despawnPrefab, collectEntitySubtree } from './chunk-67MFQDHX.js';
-export { AnimationSystem, AudioSystem, Behaviour, CameraSyncSystem, EnvironmentSyncSystem, HYDRATABLE_ENTITY_KINDS, InputSystem, InstancedMeshSystem, KeyboardKeys, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectVisibilitySystem, PREFAB_FILE_VERSION, PhysicsSyncSystem, PostprocessingSyncSystem, RenderSystem, ScriptBehaviourSystem, TransformSyncSystem, VideoSystem, buildComponentValueMaps, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearPrefabCache, collectDiffPaths, collectEntitySubtree, computeInstanceOverrides, decanonicalizeComponentValue, despawnPrefab, encodeOverride, findSnapshotRootEntityIds, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadPrefab, mergeComponentValue, parseOverride, parsePrefabAsset, restoreComponentState, restorePostCreateComponents, setPrefabAssetUrlResolver, spawnPrefab } from './chunk-67MFQDHX.js';
-import { registerDefaultFactories } from './chunk-HUHN6IFD.js';
-export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories } from './chunk-HUHN6IFD.js';
-import { ObjectManagementSystem } from './chunk-DY4ETMP2.js';
-export { ObjectManagementSystem, SHARED_MODEL_RESOURCE_FLAG, clearModelCache, loadSharedGltf, resolveDracoDecoderPath, setDracoDecoderPath } from './chunk-DY4ETMP2.js';
-import { SelectionTransformState, Object3DRef, Name, EntityType, ParentId, Environment, Postprocessing, ScriptComponent } from './chunk-Z6OMYEXU.js';
-export { AnimationStateMachine, AnimationStateManager, components_exports as CoreComponents } from './chunk-Z6OMYEXU.js';
+import { MeshGeometrySystem, InstancedMeshSystem, EnvironmentSyncSystem, PostprocessingSyncSystem, LightSyncSystem, MaterialSyncSystem, PhysicsSyncSystem, AnimationSystem, AudioSystem, VideoSystem, CameraSyncSystem, TransformSyncSystem, ObjectVisibilitySystem, RenderSystem, spawnPrefab, despawnPrefab, buildNodeKeyMapsFromSnapshot, indexSnapshotByEntity, findTopLevelNestedRegions, collectSnapshotSubtreeIds, groupOverridePaths, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, canonicalizeComponentValue, mergeComponentValue, decanonicalizeComponentValue, computeInstanceOverrides, collectEntitySubtree, ADDED_NODE_MARKER_COMPONENT } from './chunk-5U3YS4JD.js';
+export { ADDED_NODE_MARKER_COMPONENT, AnimationSystem, AudioSystem, Behaviour, CameraSyncSystem, EnvironmentSyncSystem, HYDRATABLE_ENTITY_KINDS, InputSystem, InstancedMeshSystem, KeyboardKeys, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, NODE_KEY_SEPARATOR, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectVisibilitySystem, PREFAB_FILE_VERSION, PREFAB_FILE_VERSION_NESTED, PhysicsSyncSystem, PostprocessingSyncSystem, RenderSystem, ScriptBehaviourSystem, TransformSyncSystem, VideoSystem, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearPrefabCache, collectDiffPaths, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, decanonicalizeComponentValue, despawnPrefab, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadPrefab, mergeComponentValue, parseOverride, parsePrefabAsset, prefabFileVersionFor, restoreComponentState, restorePostCreateComponents, setPrefabAssetUrlResolver, spawnPrefab } from './chunk-5U3YS4JD.js';
+import { registerDefaultFactories } from './chunk-K6KMKKJ6.js';
+export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories } from './chunk-K6KMKKJ6.js';
+import { ObjectManagementSystem } from './chunk-AXRCGF63.js';
+export { ObjectManagementSystem, SHARED_MODEL_RESOURCE_FLAG, clearModelCache, loadSharedGltf, resolveDracoDecoderPath, setDracoDecoderPath } from './chunk-AXRCGF63.js';
+import { SelectionTransformState, Object3DRef, Name, EntityType, ParentId, Environment, Postprocessing, ScriptComponent } from './chunk-V7BNVTJW.js';
+export { AnimationStateMachine, AnimationStateManager, components_exports as CoreComponents } from './chunk-V7BNVTJW.js';
 import './chunk-QHILSPT4.js';
 import { normalizeDebugValue, DEBUG_CHANGE_IGNORED_SYSTEMS, cloneHistoryValue } from './chunk-ZXGHKX7N.js';
 import { __name } from './chunk-OY7ZODZP.js';
@@ -1078,12 +1078,237 @@ function remapSnapshotEntityIds(snapshot, idMap, options) {
 }
 __name(remapSnapshotEntityIds, "remapSnapshotEntityIds");
 
+// core/prefab/applyPrefabToSnapshot.ts
+var asRecord2 = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null, "asRecord");
+var clone = /* @__PURE__ */ __name((value) => structuredClone(value), "clone");
+var stableStringify = /* @__PURE__ */ __name((value) => {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "";
+  }
+}, "stableStringify");
+function getBlock(snapshot, component) {
+  let block = snapshot.components.find((b) => b.component === component);
+  if (!block) {
+    block = { component, entries: [] };
+    snapshot.components.push(block);
+  }
+  return block;
+}
+__name(getBlock, "getBlock");
+function setEntry(snapshot, component, entityId, value) {
+  const block = getBlock(snapshot, component);
+  const entry = block.entries.find((e) => e.entityId === entityId);
+  if (entry) {
+    entry.value = value;
+  } else {
+    block.entries.push({ entityId, value });
+    block.entries.sort((a, b) => a.entityId - b.entityId);
+  }
+}
+__name(setEntry, "setEntry");
+function deleteEntities(snapshot, entityIds) {
+  snapshot.entities = snapshot.entities.filter((id) => !entityIds.has(id));
+  snapshot.components = snapshot.components.map((block) => ({
+    component: block.component,
+    entries: block.entries.filter((e) => !entityIds.has(e.entityId))
+  })).filter((block) => block.entries.length > 0);
+}
+__name(deleteEntities, "deleteEntities");
+function extractRegionDoc(hostSnapshot, regionIds) {
+  const idSet = new Set(regionIds);
+  return {
+    entities: regionIds.slice(),
+    components: hostSnapshot.components.map((block) => ({
+      component: block.component,
+      entries: block.entries.filter((e) => idSet.has(e.entityId))
+    })).filter((block) => block.entries.length > 0)
+  };
+}
+__name(extractRegionDoc, "extractRegionDoc");
+function applyPrefabToSnapshotInstances(hostSnapshot, nestedUrl, newNestedSnapshot) {
+  const host = clone(hostSnapshot);
+  const newMaps = buildNodeKeyMapsFromSnapshot(newNestedSnapshot);
+  const newByEntity = indexSnapshotByEntity(newNestedSnapshot);
+  if (!newMaps.rootKey) {
+    return { snapshot: host, changed: false };
+  }
+  let changed = false;
+  const regions = findTopLevelNestedRegions(host).filter(
+    (region) => region.url === nestedUrl
+  );
+  for (const region of regions) {
+    const before = stableStringify(
+      extractRegionDoc(host, collectSnapshotSubtreeIds(host, region.rootEntityId))
+    );
+    patchRegion(host, region.rootEntityId, region.overrides, {
+      newSnapshot: newNestedSnapshot,
+      newMaps,
+      newByEntity
+    });
+    const after = stableStringify(
+      extractRegionDoc(host, collectSnapshotSubtreeIds(host, region.rootEntityId))
+    );
+    if (before !== after) {
+      changed = true;
+    }
+  }
+  return { snapshot: host, changed };
+}
+__name(applyPrefabToSnapshotInstances, "applyPrefabToSnapshotInstances");
+function patchRegion(host, regionRootId, storedOverrides, file) {
+  const { newSnapshot, newMaps, newByEntity } = file;
+  const regionIds = collectSnapshotSubtreeIds(host, regionRootId);
+  const regionDoc = extractRegionDoc(host, regionIds);
+  const regionMaps = buildNodeKeyMapsFromSnapshot(regionDoc, {
+    scopeRootEntityId: regionRootId
+  });
+  const regionByEntity = indexSnapshotByEntity(regionDoc);
+  const grouped = groupOverridePaths(storedOverrides);
+  const overridePathsFor = /* @__PURE__ */ __name((key, component) => grouped.get(key)?.get(component), "overridePathsFor");
+  const isMarkedAddition = /* @__PURE__ */ __name((key) => Boolean(grouped.get(key)?.get(ADDED_NODE_MARKER_COMPONENT)), "isMarkedAddition");
+  const parentBlockNew = newSnapshot.components.find(
+    (b) => b.component === "ParentId"
+  );
+  const keyToHostId = /* @__PURE__ */ new Map();
+  for (const [hostId, key] of regionMaps.idToKey) {
+    keyToHostId.set(key, hostId);
+  }
+  const addedFileIds = [...newMaps.keyToId.entries()].filter(([key]) => !keyToHostId.has(key)).map(([, fileId]) => fileId);
+  if (addedFileIds.length > 0) {
+    let nextHostId = Math.max(0, ...host.entities) + 1;
+    const addedSet = new Set(addedFileIds);
+    const idMap = /* @__PURE__ */ new Map();
+    for (const [key, fileId] of newMaps.keyToId) {
+      const hostId = keyToHostId.get(key);
+      if (hostId !== void 0) {
+        idMap.set(fileId, hostId);
+      }
+    }
+    for (const fileId of addedFileIds) {
+      idMap.set(fileId, nextHostId);
+      nextHostId += 1;
+    }
+    const addedSub = {
+      entities: newSnapshot.entities.filter((id) => addedSet.has(id)),
+      components: newSnapshot.components.map((block) => ({
+        component: block.component,
+        entries: block.entries.filter((e) => addedSet.has(e.entityId))
+      })).filter((block) => block.entries.length > 0)
+    };
+    const { snapshot: remapped } = remapSnapshotEntityIds(addedSub, idMap, {
+      externalRefPolicy: "null"
+    });
+    host.entities = [...host.entities, ...remapped.entities];
+    for (const block of remapped.components) {
+      for (const entry of block.entries) {
+        setEntry(host, block.component, entry.entityId, entry.value);
+      }
+    }
+    for (const fileId of addedFileIds) {
+      const hostId = idMap.get(fileId);
+      const parentValue = asRecord2(
+        parentBlockNew?.entries.find((e) => e.entityId === fileId)?.value
+      )?.value;
+      if (typeof parentValue === "number" && !addedSet.has(parentValue)) {
+        const parentKey = newMaps.idToKey.get(parentValue);
+        const parentHost = parentKey ? keyToHostId.get(parentKey) : void 0;
+        setEntry(host, "ParentId", hostId, {
+          __type: "ParentId",
+          value: parentHost ?? regionRootId
+        });
+      }
+      const key = newMaps.idToKey.get(fileId);
+      if (key) {
+        keyToHostId.set(key, hostId);
+      }
+    }
+  }
+  for (const [key, fileId] of newMaps.keyToId) {
+    const hostId = keyToHostId.get(key);
+    if (hostId === void 0) continue;
+    const isRegionRoot = key === newMaps.rootKey;
+    const fileComponents = newByEntity.get(fileId);
+    if (!fileComponents) continue;
+    const regionEntityComponents = regionByEntity.get(hostId);
+    for (const [componentName, fileRaw] of fileComponents) {
+      if (OVERRIDE_DIFF_EXCLUDED_COMPONENTS.has(componentName)) continue;
+      if (isRegionRoot && OVERRIDE_ROOT_EXCLUDED_COMPONENTS.has(componentName))
+        continue;
+      const fileCanonical = canonicalizeComponentValue(
+        componentName,
+        fileRaw,
+        newMaps.idToKey
+      );
+      const regionRaw = regionEntityComponents?.get(componentName);
+      const regionCanonical = regionRaw === void 0 ? void 0 : canonicalizeComponentValue(
+        componentName,
+        regionRaw,
+        regionMaps.idToKey
+      );
+      const merged = regionCanonical === void 0 ? fileCanonical : mergeComponentValue(
+        fileCanonical,
+        regionCanonical,
+        overridePathsFor(key, componentName)
+      );
+      if (regionCanonical !== void 0 && stableStringify(merged) === stableStringify(regionCanonical)) {
+        continue;
+      }
+      const hostValue = decanonicalizeComponentValue(merged, keyToHostId);
+      setEntry(host, componentName, hostId, hostValue);
+    }
+  }
+  const removedHostIds = /* @__PURE__ */ new Set();
+  for (const [key, hostId] of keyToHostId) {
+    if (newMaps.keyToId.has(key)) continue;
+    if (isMarkedAddition(key)) continue;
+    removedHostIds.add(hostId);
+  }
+  if (removedHostIds.size > 0) {
+    const regionIdSet = new Set(regionIds);
+    const parentBlockHost = host.components.find(
+      (b) => b.component === "ParentId"
+    );
+    for (const entry of parentBlockHost?.entries ?? []) {
+      const record = asRecord2(entry.value);
+      if (!removedHostIds.has(entry.entityId) && regionIdSet.has(entry.entityId) && record && typeof record.value === "number" && removedHostIds.has(record.value)) {
+        record.value = regionRootId;
+      }
+    }
+    deleteEntities(host, removedHostIds);
+  }
+  const refreshedRegionIds = collectSnapshotSubtreeIds(host, regionRootId);
+  const refreshedDoc = extractRegionDoc(host, refreshedRegionIds);
+  const refreshedOverrides = computeInstanceOverrides(
+    newSnapshot,
+    refreshedDoc,
+    { emitAdditionMarkers: true }
+  );
+  const instanceEntry = asRecord2(
+    host.components.find((b) => b.component === "PrefabInstance")?.entries.find((e) => e.entityId === regionRootId)?.value
+  );
+  if (instanceEntry) {
+    instanceEntry.overrides = refreshedOverrides;
+  }
+}
+__name(patchRegion, "patchRegion");
+
+// core/prefab/dependencies.ts
+function collectDirectPrefabDependencies(snapshot) {
+  const urls = /* @__PURE__ */ new Set();
+  for (const region of findTopLevelNestedRegions(snapshot)) {
+    urls.add(region.url);
+  }
+  return [...urls];
+}
+__name(collectDirectPrefabDependencies, "collectDirectPrefabDependencies");
+
 // core/prefab/serializeEntitySubtree.ts
 var SUBTREE_EXCLUDED_COMPONENTS = /* @__PURE__ */ new Set([
   "Environment",
   "Postprocessing",
-  "SelectionTransformState",
-  "PrefabInstance"
+  "SelectionTransformState"
 ]);
 function serializeEntitySubtree(world, rootId, options) {
   const orderedIds = collectEntitySubtree(world, [rootId]);
@@ -1115,6 +1340,19 @@ function serializeEntitySubtree(world, rootId, options) {
   if (rootParentEntry && rootParentEntry.value !== null && typeof rootParentEntry.value === "object") {
     rootParentEntry.value.value = null;
   }
+  const prefabInstanceBlock = snapshot.components.find(
+    (block) => block.component === "PrefabInstance"
+  );
+  if (prefabInstanceBlock) {
+    prefabInstanceBlock.entries = prefabInstanceBlock.entries.filter(
+      (entry) => entry.entityId !== rootFileId
+    );
+    if (prefabInstanceBlock.entries.length === 0) {
+      snapshot.components = snapshot.components.filter(
+        (block) => block !== prefabInstanceBlock
+      );
+    }
+  }
   const filteredWarnings = warnings.filter(
     (warning) => !(warning.component === "ParentId" && warning.entityId === rootId)
   );
@@ -1122,6 +1360,6 @@ function serializeEntitySubtree(world, rootId, options) {
 }
 __name(serializeEntitySubtree, "serializeEntitySubtree");
 
-export { World, remapSnapshotEntityIds, serializeEntitySubtree };
+export { World, applyPrefabToSnapshotInstances, collectDirectPrefabDependencies, remapSnapshotEntityIds, serializeEntitySubtree };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map