@relu-interactives/spatial-ecs 0.2.20 → 0.2.21

package/dist/components/index.d.cts

@@ -1,5 +1,5 @@
-export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as defaultMaterialValue, a2 as normalizePhysicsState } from '../Video-B8yVI1tF.cjs';
-export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-BjwOBx81.cjs';
-export { P as PrefabInstance, a as PrefabNode } from '../index-LHLKpJhZ.cjs';
+export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as defaultMaterialValue, a2 as normalizePhysicsState } from '../Video-U9hAnf9y.cjs';
+export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-me3iAcMF.cjs';
+export { P as PrefabInstance, a as PrefabNode } from '../index-CZo5I5Gs.cjs';
 import 'three';
 import '@dimforge/rapier3d-compat';

package/dist/components/index.d.ts

@@ -1,5 +1,5 @@
-export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as defaultMaterialValue, a2 as normalizePhysicsState } from '../Video-B9z5AtIf.js';
-export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-BjwOBx81.js';
-export { P as PrefabInstance, a as PrefabNode } from '../index-BBI2YdCu.js';
+export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as defaultMaterialValue, a2 as normalizePhysicsState } from '../Video-DHnxjGhW.js';
+export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-me3iAcMF.js';
+export { P as PrefabInstance, a as PrefabNode } from '../index-D7FSg0Au.js';
 import 'three';
 import '@dimforge/rapier3d-compat';

package/dist/components/index.js

@@ -1,4 +1,4 @@
-export { AnimationComponent, AudioComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_STATE, DEFAULT_INSTANCED_MESH_PARAMETERS, DEFAULT_INSTANCE_TRANSFORM, DEFAULT_MESH_GEOMETRY_PARAMETERS, DEFAULT_PHYSICS_STATE, DEFAULT_POSTPROCESSING_STATE, DEFAULT_RIGIDBODY_STATE, EntityType, Environment, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, Object3DRef, ParentId, PhysicsComponent, Postprocessing, PrefabInstance, PrefabNode, ScriptComponent, Selectable, SelectionTransformState, SpriteComponent, TransformComponent, VideoComponent, defaultMaterialValue, normalizePhysicsState } from '../chunk-Z6OMYEXU.js';
+export { AnimationComponent, AudioComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_STATE, DEFAULT_INSTANCED_MESH_PARAMETERS, DEFAULT_INSTANCE_TRANSFORM, DEFAULT_MESH_GEOMETRY_PARAMETERS, DEFAULT_PHYSICS_STATE, DEFAULT_POSTPROCESSING_STATE, DEFAULT_RIGIDBODY_STATE, EntityType, Environment, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, Object3DRef, ParentId, PhysicsComponent, Postprocessing, PrefabInstance, PrefabNode, ScriptComponent, Selectable, SelectionTransformState, SpriteComponent, TransformComponent, VideoComponent, defaultMaterialValue, normalizePhysicsState } from '../chunk-V7BNVTJW.js';
 import '../chunk-OY7ZODZP.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/docs/guide/prefabs.md

@@ -55,15 +55,34 @@ keep their per-instance values while everything else syncs from the file.
 Always per-instance (never synced): the instance **root's** position /
 rotation / scale, name, and place in the scene hierarchy.
 
-v1 rules of thumb:
+Rules of thumb:
 
 - Components or children you *add* to an instance are yours — prefab
   updates never remove them.
 - Components or children you *delete* from an instance come back on the
-  next prefab apply (deletion tracking is not part of v1).
-- "Unpack" in the inspector detaches an instance permanently — it becomes
-  ordinary objects with no link.
-- Nested prefabs (a prefab inside another prefab) are not supported in v1.
+  next prefab apply (deletion tracking is not supported).
+- "Unpack" in the inspector detaches ONE level — the objects lose their
+  link but any nested instances inside survive as standalone instances.
+
+## Nested prefabs
+
+Prefabs can contain other prefab instances: drag a prefab into an open
+prefab (Prefab Mode), or create a prefab from a subtree that contains whole
+instances. Node identity is scoped per placement, so a prefab may nest two
+copies of the same child prefab and each keeps independent overrides.
+
+- Editing a child prefab **cascades**: every prefab file that nests it is
+  patched (overrides preserved), and every scene instance updates when you
+  close the editor — transitively through any depth of nesting.
+- A prefab can never contain itself, directly or through another prefab
+  (the editor rejects the drop).
+- Only *whole* instances nest — a partial slice of an instance can't become
+  a prefab.
+- In the scene, content can't be re-parented across a nested instance
+  boundary (its identity would change); open the host prefab to
+  restructure.
+- Runtime spawning is unaffected: files are fully materialized, so
+  `spawnPrefab` needs no resolution regardless of nesting depth.
 
 ## Spawning at runtime
 

package/dist/factories/index.d.cts

@@ -1,5 +1,5 @@
-import { A as AnimationComponent, b as AudioComponent, c as CameraComponentOptions, C as CameraComponent, S as RigidbodyState, g as ColliderState, P as PhysicsComponent, n as EntityType, I as ImageComponent, p as ImageTargetAnchor, o as ImageTarget, L as LightComponent, M as MaterialComponent, z as MeshComponent, B as MeshGeometryComponent, H as ModelComponent, N as Name, O as Object3DRef, V as ScriptEntry, U as ScriptComponent, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, v as InstancedMeshKind, F as MeshGeometryParameters, u as InstancedMeshComponent, s as InstanceSlotComponent, a0 as VideoComponent } from '../Video-B8yVI1tF.cjs';
-import { l as World, g as EnvironmentState, E as Environment, P as ParentId, i as PostprocessingState, h as Postprocessing, T as TransformComponent, O as ObjectManagementSystem } from '../System-BjwOBx81.cjs';
+import { A as AnimationComponent, b as AudioComponent, c as CameraComponentOptions, C as CameraComponent, S as RigidbodyState, g as ColliderState, P as PhysicsComponent, n as EntityType, I as ImageComponent, p as ImageTargetAnchor, o as ImageTarget, L as LightComponent, M as MaterialComponent, z as MeshComponent, B as MeshGeometryComponent, H as ModelComponent, N as Name, O as Object3DRef, V as ScriptEntry, U as ScriptComponent, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, v as InstancedMeshKind, F as MeshGeometryParameters, u as InstancedMeshComponent, s as InstanceSlotComponent, a0 as VideoComponent } from '../Video-U9hAnf9y.cjs';
+import { l as World, g as EnvironmentState, E as Environment, P as ParentId, i as PostprocessingState, h as Postprocessing, T as TransformComponent, O as ObjectManagementSystem } from '../System-me3iAcMF.cjs';
 import * as THREE from 'three';
 import '@dimforge/rapier3d-compat';
 

package/dist/factories/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AnimationComponent, b as AudioComponent, c as CameraComponentOptions, C as CameraComponent, S as RigidbodyState, g as ColliderState, P as PhysicsComponent, n as EntityType, I as ImageComponent, p as ImageTargetAnchor, o as ImageTarget, L as LightComponent, M as MaterialComponent, z as MeshComponent, B as MeshGeometryComponent, H as ModelComponent, N as Name, O as Object3DRef, V as ScriptEntry, U as ScriptComponent, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, v as InstancedMeshKind, F as MeshGeometryParameters, u as InstancedMeshComponent, s as InstanceSlotComponent, a0 as VideoComponent } from '../Video-B9z5AtIf.js';
-import { l as World, g as EnvironmentState, E as Environment, P as ParentId, i as PostprocessingState, h as Postprocessing, T as TransformComponent, O as ObjectManagementSystem } from '../System-BjwOBx81.js';
+import { A as AnimationComponent, b as AudioComponent, c as CameraComponentOptions, C as CameraComponent, S as RigidbodyState, g as ColliderState, P as PhysicsComponent, n as EntityType, I as ImageComponent, p as ImageTargetAnchor, o as ImageTarget, L as LightComponent, M as MaterialComponent, z as MeshComponent, B as MeshGeometryComponent, H as ModelComponent, N as Name, O as Object3DRef, V as ScriptEntry, U as ScriptComponent, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, v as InstancedMeshKind, F as MeshGeometryParameters, u as InstancedMeshComponent, s as InstanceSlotComponent, a0 as VideoComponent } from '../Video-DHnxjGhW.js';
+import { l as World, g as EnvironmentState, E as Environment, P as ParentId, i as PostprocessingState, h as Postprocessing, T as TransformComponent, O as ObjectManagementSystem } from '../System-me3iAcMF.js';
 import * as THREE from 'three';
 import '@dimforge/rapier3d-compat';
 

package/dist/factories/index.js

@@ -1,6 +1,6 @@
-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 '../chunk-DY4ETMP2.js';
-import '../chunk-Z6OMYEXU.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 '../chunk-AXRCGF63.js';
+import '../chunk-V7BNVTJW.js';
 import '../chunk-OY7ZODZP.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{index-LHLKpJhZ.d.cts → index-CZo5I5Gs.d.cts}

@@ -1,26 +1,36 @@
-import { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as defaultMaterialValue, a2 as normalizePhysicsState } from './Video-B8yVI1tF.cjs';
-import { C as Component, D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from './System-BjwOBx81.cjs';
+import { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as defaultMaterialValue, a2 as normalizePhysicsState } from './Video-U9hAnf9y.cjs';
+import { C as Component, D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from './System-me3iAcMF.cjs';
 
 /**
  * Marks the ROOT entity of a prefab instance and records its link to the
  * source `.prefab` asset plus the instance's per-property overrides.
  *
+ * Instances may appear in a scene OR nested inside another prefab's file
+ * (nested prefabs): the nested root keeps the child prefab's `PrefabNode`
+ * identity AND this link. `instanceId` is a per-placement uuid that scopes
+ * node identity across nesting — two nested instances of the same prefab
+ * share nodeIds but never instanceIds, so override keys stay unambiguous.
+ *
  * `overrides` is a flat list of encoded strings so it survives snapshot
  * serialization at any depth:
  *
  * ```
- * "<nodeId>|<ComponentName>|<slash/separated/path>"
- * "<nodeId>|<ComponentName>|"        // empty path = whole component overridden
+ * "<nodeKey>|<ComponentName>|<slash/separated/path>"
+ * "<nodeKey>|<ComponentName>|"   // empty path = whole component overridden
+ * "<nodeKey>|+node|"             // marker: node added by the HOST document
+ *                                // inside a nested region (never deleted by
+ *                                // file patching)
  * ```
  *
- * e.g. `"9f2c…|MaterialComponent|values/0/color"`.
- *
- * Overridden paths keep their per-instance values when the prefab asset is
- * re-applied; everything else syncs from the file. The instance root's
- * Transform, Name, and ParentId are implicitly per-instance and never appear
- * here. Overrides are an editor-side concern — the runtime never resolves
- * them (scene-placed instances are fully materialized; runtime spawns are
- * fresh copies of the file).
+ * where `<nodeKey>` is the entity's `PrefabNode.nodeId` prefixed by the
+ * `instanceId` chain of any nested instance roots between the scope root and
+ * the entity (e.g. `"9f2c…"` for direct children, `"<iB>/<bNode>"` inside a
+ * nested instance). Overridden paths keep their per-instance values when the
+ * prefab asset is re-applied; everything else syncs from the file. The
+ * instance root's Transform, Name, and ParentId are implicitly per-instance
+ * and never appear here. Overrides are an editor-side concern — the runtime
+ * never resolves them (scene-placed instances are fully materialized;
+ * runtime spawns are fresh copies of the file).
  *
  * @category Components
  */
@@ -29,7 +39,13 @@ declare class PrefabInstance extends Component {
     url: string;
     /** Encoded override paths — see class docs for the format. */
     overrides: string[];
-    constructor(url: string, overrides?: string[]);
+    /**
+     * Per-placement uuid scoping node identity across nesting. Stable for the
+     * lifetime of the placement (persisted; survives applies) so override keys
+     * referencing nested content stay valid.
+     */
+    instanceId: string;
+    constructor(url: string, overrides?: string[], instanceId?: string);
 }
 
 /**

package/dist/{index-BBI2YdCu.d.ts → index-D7FSg0Au.d.ts}

@@ -1,26 +1,36 @@
-import { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as defaultMaterialValue, a2 as normalizePhysicsState } from './Video-B9z5AtIf.js';
-import { C as Component, D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from './System-BjwOBx81.js';
+import { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as defaultMaterialValue, a2 as normalizePhysicsState } from './Video-DHnxjGhW.js';
+import { C as Component, D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from './System-me3iAcMF.js';
 
 /**
  * Marks the ROOT entity of a prefab instance and records its link to the
  * source `.prefab` asset plus the instance's per-property overrides.
  *
+ * Instances may appear in a scene OR nested inside another prefab's file
+ * (nested prefabs): the nested root keeps the child prefab's `PrefabNode`
+ * identity AND this link. `instanceId` is a per-placement uuid that scopes
+ * node identity across nesting — two nested instances of the same prefab
+ * share nodeIds but never instanceIds, so override keys stay unambiguous.
+ *
  * `overrides` is a flat list of encoded strings so it survives snapshot
  * serialization at any depth:
  *
  * ```
- * "<nodeId>|<ComponentName>|<slash/separated/path>"
- * "<nodeId>|<ComponentName>|"        // empty path = whole component overridden
+ * "<nodeKey>|<ComponentName>|<slash/separated/path>"
+ * "<nodeKey>|<ComponentName>|"   // empty path = whole component overridden
+ * "<nodeKey>|+node|"             // marker: node added by the HOST document
+ *                                // inside a nested region (never deleted by
+ *                                // file patching)
  * ```
  *
- * e.g. `"9f2c…|MaterialComponent|values/0/color"`.
- *
- * Overridden paths keep their per-instance values when the prefab asset is
- * re-applied; everything else syncs from the file. The instance root's
- * Transform, Name, and ParentId are implicitly per-instance and never appear
- * here. Overrides are an editor-side concern — the runtime never resolves
- * them (scene-placed instances are fully materialized; runtime spawns are
- * fresh copies of the file).
+ * where `<nodeKey>` is the entity's `PrefabNode.nodeId` prefixed by the
+ * `instanceId` chain of any nested instance roots between the scope root and
+ * the entity (e.g. `"9f2c…"` for direct children, `"<iB>/<bNode>"` inside a
+ * nested instance). Overridden paths keep their per-instance values when the
+ * prefab asset is re-applied; everything else syncs from the file. The
+ * instance root's Transform, Name, and ParentId are implicitly per-instance
+ * and never appear here. Overrides are an editor-side concern — the runtime
+ * never resolves them (scene-placed instances are fully materialized;
+ * runtime spawns are fresh copies of the file).
  *
  * @category Components
  */
@@ -29,7 +39,13 @@ declare class PrefabInstance extends Component {
     url: string;
     /** Encoded override paths — see class docs for the format. */
     overrides: string[];
-    constructor(url: string, overrides?: string[]);
+    /**
+     * Per-placement uuid scoping node identity across nesting. Stable for the
+     * lifetime of the placement (persisted; survives applies) so override keys
+     * referencing nested content stay valid.
+     */
+    instanceId: string;
+    constructor(url: string, overrides?: string[], instanceId?: string);
 }
 
 /**