@relu-interactives/spatial-ecs 0.2.17 → 0.2.20

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, m as ComponentClass, n as ParentLookup, o as EcsEntityKind, O as ObjectManagementSystem } from './System-BeuJ1xt5.cjs';
-export { A as AssetInput, p as CheckboxInput, q as ColorInput, r as ComponentFactory, s as ComponentInput, t as ComponentKind, u as DropdownInput, v as DropdownOption, w as EcsComponentFactoryKind, x as EcsEntityEditorKind, y as EntityId, z as EntityInput, F as FloatInput, I as InputSystem, B as IntersectionResult, K as KeyboardKey, G as KeyboardKeys, M as MouseButton, R as RenderSystem, S as SelectionListener, H as SliderInput, J as TextInput, L as ToggleInput, N as TransformSyncSystem, Q as Vec3, U as Vector2Input, X as Vector3Input } from './System-BeuJ1xt5.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 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 * as THREE from 'three';
-import { O as Object3DRef } from './Video-D4B-z74P.cjs';
-export { a2 as AnimationStateCallbacks, a3 as AnimationStateMachine, a4 as AnimationStateManager, a5 as StateMachine } from './Video-D4B-z74P.cjs';
-export { i as CoreComponents } from './index-BfoOC2CG.cjs';
+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';
 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';
@@ -136,6 +136,31 @@ declare class Behaviour implements CustomEcsSystem {
      * @param world - The owning world at disposal time.
      */
     dispose?(world: World): void;
+    /**
+     * Instantiate a prefab asset into the world at runtime.
+     *
+     * `source` is typically an `AssetInput` field from this script's `data`
+     * (drag a `.prefab` from the asset browser onto the field in the editor),
+     * a URL string, or a pre-loaded `PrefabAsset`. Resolves with the new root
+     * entity id.
+     *
+     * ```ts
+     * data = { enemyPrefab: { path: "", type: "prefab" } };
+     * async onUpdate() {
+     *   if (shouldSpawn) {
+     *     const id = await this.spawnPrefab(this.data.enemyPrefab, {
+     *       position: { x: 0, y: 0, z: -5 },
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    spawnPrefab(source: SpawnPrefabSource, options?: SpawnPrefabOptions): Promise<number>;
+    /**
+     * Remove a spawned prefab instance (the root entity and all descendants).
+     * Returns the number of entities removed.
+     */
+    despawn(rootEntityId: number): number;
     /**
      * Returns the entity's world-space position as a new `THREE.Vector3`, or
      * `null` if the entity has no scene presence.
@@ -260,6 +285,32 @@ declare class Behaviour implements CustomEcsSystem {
     onTargetLost(target: WorldEntityView): void;
 }
 
+type ComponentValueMaps = {
+    object3DRefValues: Map<number, unknown>;
+    nameValues: Map<number, unknown>;
+    transformValues: Map<number, unknown>;
+    modelValues: Map<number, unknown>;
+    imageValues: Map<number, unknown>;
+    spriteValues: Map<number, unknown>;
+    videoValues: Map<number, unknown>;
+    cameraValues: Map<number, unknown>;
+    environmentValues: Map<number, unknown>;
+    postprocessingValues: Map<number, unknown>;
+    audioValues: Map<number, unknown>;
+    imageTargetValues: Map<number, unknown>;
+    lightValues: Map<number, unknown>;
+    materialValues: Map<number, unknown>;
+    meshGeometryValues: Map<number, unknown>;
+    selectableValues: Map<number, unknown>;
+    physicsValues: Map<number, unknown>;
+    animationValues: Map<number, unknown>;
+    imageTargetAnchorValues: Map<number, unknown>;
+    scriptValues: Map<number, unknown>;
+    instancedMeshValues: Map<number, unknown>;
+    instanceSlotValues: Map<number, unknown>;
+    prefabNodeValues: Map<number, unknown>;
+    prefabInstanceValues: Map<number, unknown>;
+};
 type EcsWorldComponentSnapshot = {
     component: string;
     entries: Array<{
@@ -275,12 +326,40 @@ type EcsWorldStateSnapshotLike = {
 type HydrateWorldFromSnapshotResult = {
     restoredCount: number;
     selectedEntityId: number | null;
+    /** Snapshot entity id → created live entity id for every hydrated entity. */
+    idMap: Map<number, number>;
+};
+/**
+ * Optional behavior tweaks for {@link hydrateWorldFromSnapshotDetailed}.
+ * Defaults preserve the historical full-world-load behavior; prefab/subtree
+ * instantiation passes stricter options.
+ */
+type HydrateOptions = {
+    /**
+     * When false, no camera in the snapshot is promoted to the world camera.
+     * Defaults to true (full scene loads want their default camera active);
+     * prefab spawns pass false so a spawned camera never hijacks the view.
+     */
+    assignPrimaryCamera?: boolean;
+    /**
+     * "world" (default) re-applies local transforms for every entity in the
+     * world after parent links restore — correct for full scene loads.
+     * "created" limits the pass to entities created by THIS hydrate call, so
+     * mid-session spawns don't touch unrelated live entities.
+     */
+    applyTransformsScope?: "world" | "created";
 };
 declare const HYDRATABLE_ENTITY_KINDS: Set<EcsEntityKind>;
 
-declare function hydrateWorldFromSnapshotDetailed(snapshot: EcsWorldStateSnapshotLike | null | undefined, world: World, objectManagementSystem: ObjectManagementSystem): HydrateWorldFromSnapshotResult;
+declare function hydrateWorldFromSnapshotDetailed(snapshot: EcsWorldStateSnapshotLike | null | undefined, world: World, objectManagementSystem: ObjectManagementSystem, options?: HydrateOptions): HydrateWorldFromSnapshotResult;
 declare function hydrateWorldFromSnapshot(snapshot: EcsWorldStateSnapshotLike | null | undefined, world: World, objectManagementSystem: ObjectManagementSystem): number;
 
+declare function buildComponentValueMaps(snapshot: EcsWorldStateSnapshotLike): ComponentValueMaps;
+
+declare function restoreComponentState(world: World, objectManagementSystem: ObjectManagementSystem, targetEntityId: number, sourceEntityId: number, entityType: string | null, values: ComponentValueMaps): void;
+
+declare function restorePostCreateComponents(world: World, objectManagementSystem: ObjectManagementSystem, targetEntityId: number, sourceEntityId: number, entityType: string | null, values: ComponentValueMaps, idMap: Map<number, number>): void;
+
 /**
  * Override where the DRACO decoder files (draco_wasm_wrapper.js,
  * draco_decoder.wasm, draco_decoder.js) are fetched from. Embedding apps
@@ -311,4 +390,133 @@ declare function loadSharedGltf(url: string, load: () => Promise<GLTF>): Promise
  */
 declare function clearModelCache(url?: string): void;
 
-export { Behaviour, Component, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, HYDRATABLE_ENTITY_KINDS, type HydrateWorldFromSnapshotResult, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, World, WorldEntityView, clearModelCache, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, loadSharedGltf, resolveDracoDecoderPath, setDracoDecoderPath };
+/**
+ * Collect the given roots plus every descendant, BFS parent-first, using the
+ * `ParentId` component edges. Parent-first ordering matters: serialization
+ * renumbers ids in this order and instantiation creates entities in file
+ * order, so parents always exist before their children are linked.
+ */
+declare function collectEntitySubtree(world: World, rootIds: EntityId[]): EntityId[];
+
+type InstantiateSubtreeResult = {
+    /** Live entity id of the subtree root, or null when nothing hydrated. */
+    rootId: EntityId | null;
+    /** Snapshot entity id → live entity id. */
+    idMap: Map<number, number>;
+};
+/**
+ * Hydrate a self-contained subtree snapshot (a prefab file's `snapshot`)
+ * into a LIVE world: fresh entity ids, internal references remapped, no
+ * camera promotion, transform pass scoped to the created entities.
+ */
+declare function instantiateSubtree(world: World, objectManagementSystem: ObjectManagementSystem, snapshot: SubtreeSnapshot): InstantiateSubtreeResult;
+
+/**
+ * Per-property prefab override model — pure JSON-space functions shared by
+ * the editor (diff/merge at apply time) and future `.scene` tooling.
+ *
+ * The core problem: an instance's entity ids differ from the prefab file's
+ * ids by construction, so raw values can't be compared. Both sides are first
+ * CANONICALIZED into nodeId-space: every entity-id-bearing field (kept in
+ * sync with `snapshotIdUtils.ts`) becomes `{ $node: "<nodeId>" }` when the id
+ * maps to a node inside the same document, or stays a raw id when external.
+ * Two canonical values are equal iff they describe the same state relative
+ * to their own subtree.
+ *
+ * Override encoding (stored in `PrefabInstance.overrides`):
+ *   "<nodeId>|<ComponentName>|<slash/separated/path>"
+ *   "<nodeId>|<ComponentName>|"    // empty path = whole component overridden
+ */
+
+/** Components that never participate in override diffing/merging. */
+declare const OVERRIDE_DIFF_EXCLUDED_COMPONENTS: Set<string>;
+/**
+ * Components excluded ONLY on the instance ROOT node — these are per-instance
+ * by definition (where the instance sits in the scene and what it's called).
+ */
+declare const OVERRIDE_ROOT_EXCLUDED_COMPONENTS: Set<string>;
+type NodeMaps = {
+    idToNode: Map<number, string>;
+    nodeToId: Map<string, number>;
+    /** nodeId of the subtree root (entity whose ParentId is null/absent). */
+    rootNodeId: string | null;
+};
+/** Entity ids of entities whose ParentId is null or absent. */
+declare function findSnapshotRootEntityIds(snapshot: SubtreeSnapshot): number[];
+declare function buildNodeMapsFromSnapshot(snapshot: SubtreeSnapshot): NodeMaps;
+/** Invert the columnar snapshot into entityId → (componentName → value). */
+declare function indexSnapshotByEntity(snapshot: SubtreeSnapshot): Map<number, Map<string, unknown>>;
+/**
+ * Canonicalize a serialized component value into nodeId-space:
+ * - entity-id fields → `{$node}` (internal) or raw id (external)
+ * - ScriptComponent entries keep only `{className, scriptUrl, enabled, data}`
+ *   (entityId/runtimeState/runtimeMessage are per-instance transients)
+ * - Object3DRef keeps only `{visibility}` (the rest is a live object ref)
+ *
+ * Keep the id-bearing field list in sync with `snapshotIdUtils.ts`.
+ */
+declare function canonicalizeComponentValue(componentName: string, value: unknown, idToNode: Map<number, string>): unknown;
+/**
+ * Replace every `{$node}` marker (at any depth) with the mapped entity id
+ * from `nodeToId`, or null when the node no longer exists. Exact inverse of
+ * canonicalization for the id-bearing positions.
+ */
+declare function decanonicalizeComponentValue(value: unknown, nodeToId: Map<string, number>): unknown;
+declare const encodeOverride: (nodeId: string, componentName: string, path: string) => string;
+declare function parseOverride(encoded: string): {
+    nodeId: string;
+    componentName: string;
+    path: string;
+} | null;
+/** nodeId → componentName → set of overridden paths. */
+declare function groupOverridePaths(overrides: string[]): Map<string, Map<string, Set<string>>>;
+/**
+ * Collect leaf paths where two canonical values differ. Semantics:
+ * - `{$node}` refs compare atomically by nodeId
+ * - arrays of differing length are ONE atomic override (the array path);
+ *   equal lengths recurse per index
+ * - object key present on one side only marks that key's path
+ * - type mismatches mark the current path
+ * An empty-string path means the values differ at the top level.
+ */
+declare function collectDiffPaths(base: unknown, current: unknown, prefix?: string, out?: string[]): string[];
+/**
+ * Diff a live instance subtree against its prefab base (both as serialized
+ * 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).
+ */
+declare function computeInstanceOverrides(baseSnapshot: SubtreeSnapshot, instanceSnapshot: SubtreeSnapshot): 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
+ * path ("") means the whole component is overridden → instance wins.
+ */
+declare function mergeComponentValue(newFileCanonical: unknown, instanceCanonical: unknown, overridePaths: Set<string> | undefined): unknown;
+
+type SerializeEntitySubtreeResult = {
+    snapshot: SubtreeSnapshot;
+    /**
+     * References that pointed OUTSIDE the subtree and were nulled out
+     * (ids are LIVE world ids so callers can name the offending entities).
+     * The root's own external parent link is nulled silently — it is expected.
+     */
+    warnings: ExternalRefWarning[];
+    /** Component types stripped because they are scene singletons. */
+    strippedComponents: string[];
+};
+/**
+ * Serialize `rootId` + all descendants into a self-contained snapshot:
+ * entity ids renumbered 1..N in BFS parent-first order, all internal id
+ * references remapped, external references nulled + reported, root ParentId
+ * forced to null. The result is directly consumable by
+ * `hydrateWorldFromSnapshotDetailed` / `instantiateSubtree`.
+ */
+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 };

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, m as ComponentClass, n as ParentLookup, o as EcsEntityKind, O as ObjectManagementSystem } from './System-BeuJ1xt5.js';
-export { A as AssetInput, p as CheckboxInput, q as ColorInput, r as ComponentFactory, s as ComponentInput, t as ComponentKind, u as DropdownInput, v as DropdownOption, w as EcsComponentFactoryKind, x as EcsEntityEditorKind, y as EntityId, z as EntityInput, F as FloatInput, I as InputSystem, B as IntersectionResult, K as KeyboardKey, G as KeyboardKeys, M as MouseButton, R as RenderSystem, S as SelectionListener, H as SliderInput, J as TextInput, L as ToggleInput, N as TransformSyncSystem, Q as Vec3, U as Vector2Input, X as Vector3Input } from './System-BeuJ1xt5.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 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 * as THREE from 'three';
-import { O as Object3DRef } from './Video-Cym2C52L.js';
-export { a2 as AnimationStateCallbacks, a3 as AnimationStateMachine, a4 as AnimationStateManager, a5 as StateMachine } from './Video-Cym2C52L.js';
-export { i as CoreComponents } from './index-BoJ3_6a3.js';
+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';
 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';
@@ -136,6 +136,31 @@ declare class Behaviour implements CustomEcsSystem {
      * @param world - The owning world at disposal time.
      */
     dispose?(world: World): void;
+    /**
+     * Instantiate a prefab asset into the world at runtime.
+     *
+     * `source` is typically an `AssetInput` field from this script's `data`
+     * (drag a `.prefab` from the asset browser onto the field in the editor),
+     * a URL string, or a pre-loaded `PrefabAsset`. Resolves with the new root
+     * entity id.
+     *
+     * ```ts
+     * data = { enemyPrefab: { path: "", type: "prefab" } };
+     * async onUpdate() {
+     *   if (shouldSpawn) {
+     *     const id = await this.spawnPrefab(this.data.enemyPrefab, {
+     *       position: { x: 0, y: 0, z: -5 },
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    spawnPrefab(source: SpawnPrefabSource, options?: SpawnPrefabOptions): Promise<number>;
+    /**
+     * Remove a spawned prefab instance (the root entity and all descendants).
+     * Returns the number of entities removed.
+     */
+    despawn(rootEntityId: number): number;
     /**
      * Returns the entity's world-space position as a new `THREE.Vector3`, or
      * `null` if the entity has no scene presence.
@@ -260,6 +285,32 @@ declare class Behaviour implements CustomEcsSystem {
     onTargetLost(target: WorldEntityView): void;
 }
 
+type ComponentValueMaps = {
+    object3DRefValues: Map<number, unknown>;
+    nameValues: Map<number, unknown>;
+    transformValues: Map<number, unknown>;
+    modelValues: Map<number, unknown>;
+    imageValues: Map<number, unknown>;
+    spriteValues: Map<number, unknown>;
+    videoValues: Map<number, unknown>;
+    cameraValues: Map<number, unknown>;
+    environmentValues: Map<number, unknown>;
+    postprocessingValues: Map<number, unknown>;
+    audioValues: Map<number, unknown>;
+    imageTargetValues: Map<number, unknown>;
+    lightValues: Map<number, unknown>;
+    materialValues: Map<number, unknown>;
+    meshGeometryValues: Map<number, unknown>;
+    selectableValues: Map<number, unknown>;
+    physicsValues: Map<number, unknown>;
+    animationValues: Map<number, unknown>;
+    imageTargetAnchorValues: Map<number, unknown>;
+    scriptValues: Map<number, unknown>;
+    instancedMeshValues: Map<number, unknown>;
+    instanceSlotValues: Map<number, unknown>;
+    prefabNodeValues: Map<number, unknown>;
+    prefabInstanceValues: Map<number, unknown>;
+};
 type EcsWorldComponentSnapshot = {
     component: string;
     entries: Array<{
@@ -275,12 +326,40 @@ type EcsWorldStateSnapshotLike = {
 type HydrateWorldFromSnapshotResult = {
     restoredCount: number;
     selectedEntityId: number | null;
+    /** Snapshot entity id → created live entity id for every hydrated entity. */
+    idMap: Map<number, number>;
+};
+/**
+ * Optional behavior tweaks for {@link hydrateWorldFromSnapshotDetailed}.
+ * Defaults preserve the historical full-world-load behavior; prefab/subtree
+ * instantiation passes stricter options.
+ */
+type HydrateOptions = {
+    /**
+     * When false, no camera in the snapshot is promoted to the world camera.
+     * Defaults to true (full scene loads want their default camera active);
+     * prefab spawns pass false so a spawned camera never hijacks the view.
+     */
+    assignPrimaryCamera?: boolean;
+    /**
+     * "world" (default) re-applies local transforms for every entity in the
+     * world after parent links restore — correct for full scene loads.
+     * "created" limits the pass to entities created by THIS hydrate call, so
+     * mid-session spawns don't touch unrelated live entities.
+     */
+    applyTransformsScope?: "world" | "created";
 };
 declare const HYDRATABLE_ENTITY_KINDS: Set<EcsEntityKind>;
 
-declare function hydrateWorldFromSnapshotDetailed(snapshot: EcsWorldStateSnapshotLike | null | undefined, world: World, objectManagementSystem: ObjectManagementSystem): HydrateWorldFromSnapshotResult;
+declare function hydrateWorldFromSnapshotDetailed(snapshot: EcsWorldStateSnapshotLike | null | undefined, world: World, objectManagementSystem: ObjectManagementSystem, options?: HydrateOptions): HydrateWorldFromSnapshotResult;
 declare function hydrateWorldFromSnapshot(snapshot: EcsWorldStateSnapshotLike | null | undefined, world: World, objectManagementSystem: ObjectManagementSystem): number;
 
+declare function buildComponentValueMaps(snapshot: EcsWorldStateSnapshotLike): ComponentValueMaps;
+
+declare function restoreComponentState(world: World, objectManagementSystem: ObjectManagementSystem, targetEntityId: number, sourceEntityId: number, entityType: string | null, values: ComponentValueMaps): void;
+
+declare function restorePostCreateComponents(world: World, objectManagementSystem: ObjectManagementSystem, targetEntityId: number, sourceEntityId: number, entityType: string | null, values: ComponentValueMaps, idMap: Map<number, number>): void;
+
 /**
  * Override where the DRACO decoder files (draco_wasm_wrapper.js,
  * draco_decoder.wasm, draco_decoder.js) are fetched from. Embedding apps
@@ -311,4 +390,133 @@ declare function loadSharedGltf(url: string, load: () => Promise<GLTF>): Promise
  */
 declare function clearModelCache(url?: string): void;
 
-export { Behaviour, Component, EcsEntityKind, EcsSystem, type EcsWorldComponentSnapshot, type EcsWorldStateSnapshotLike, HYDRATABLE_ENTITY_KINDS, type HydrateWorldFromSnapshotResult, ObjectManagementSystem, ParentLookup, SHARED_MODEL_RESOURCE_FLAG, World, WorldEntityView, clearModelCache, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, loadSharedGltf, resolveDracoDecoderPath, setDracoDecoderPath };
+/**
+ * Collect the given roots plus every descendant, BFS parent-first, using the
+ * `ParentId` component edges. Parent-first ordering matters: serialization
+ * renumbers ids in this order and instantiation creates entities in file
+ * order, so parents always exist before their children are linked.
+ */
+declare function collectEntitySubtree(world: World, rootIds: EntityId[]): EntityId[];
+
+type InstantiateSubtreeResult = {
+    /** Live entity id of the subtree root, or null when nothing hydrated. */
+    rootId: EntityId | null;
+    /** Snapshot entity id → live entity id. */
+    idMap: Map<number, number>;
+};
+/**
+ * Hydrate a self-contained subtree snapshot (a prefab file's `snapshot`)
+ * into a LIVE world: fresh entity ids, internal references remapped, no
+ * camera promotion, transform pass scoped to the created entities.
+ */
+declare function instantiateSubtree(world: World, objectManagementSystem: ObjectManagementSystem, snapshot: SubtreeSnapshot): InstantiateSubtreeResult;
+
+/**
+ * Per-property prefab override model — pure JSON-space functions shared by
+ * the editor (diff/merge at apply time) and future `.scene` tooling.
+ *
+ * The core problem: an instance's entity ids differ from the prefab file's
+ * ids by construction, so raw values can't be compared. Both sides are first
+ * CANONICALIZED into nodeId-space: every entity-id-bearing field (kept in
+ * sync with `snapshotIdUtils.ts`) becomes `{ $node: "<nodeId>" }` when the id
+ * maps to a node inside the same document, or stays a raw id when external.
+ * Two canonical values are equal iff they describe the same state relative
+ * to their own subtree.
+ *
+ * Override encoding (stored in `PrefabInstance.overrides`):
+ *   "<nodeId>|<ComponentName>|<slash/separated/path>"
+ *   "<nodeId>|<ComponentName>|"    // empty path = whole component overridden
+ */
+
+/** Components that never participate in override diffing/merging. */
+declare const OVERRIDE_DIFF_EXCLUDED_COMPONENTS: Set<string>;
+/**
+ * Components excluded ONLY on the instance ROOT node — these are per-instance
+ * by definition (where the instance sits in the scene and what it's called).
+ */
+declare const OVERRIDE_ROOT_EXCLUDED_COMPONENTS: Set<string>;
+type NodeMaps = {
+    idToNode: Map<number, string>;
+    nodeToId: Map<string, number>;
+    /** nodeId of the subtree root (entity whose ParentId is null/absent). */
+    rootNodeId: string | null;
+};
+/** Entity ids of entities whose ParentId is null or absent. */
+declare function findSnapshotRootEntityIds(snapshot: SubtreeSnapshot): number[];
+declare function buildNodeMapsFromSnapshot(snapshot: SubtreeSnapshot): NodeMaps;
+/** Invert the columnar snapshot into entityId → (componentName → value). */
+declare function indexSnapshotByEntity(snapshot: SubtreeSnapshot): Map<number, Map<string, unknown>>;
+/**
+ * Canonicalize a serialized component value into nodeId-space:
+ * - entity-id fields → `{$node}` (internal) or raw id (external)
+ * - ScriptComponent entries keep only `{className, scriptUrl, enabled, data}`
+ *   (entityId/runtimeState/runtimeMessage are per-instance transients)
+ * - Object3DRef keeps only `{visibility}` (the rest is a live object ref)
+ *
+ * Keep the id-bearing field list in sync with `snapshotIdUtils.ts`.
+ */
+declare function canonicalizeComponentValue(componentName: string, value: unknown, idToNode: Map<number, string>): unknown;
+/**
+ * Replace every `{$node}` marker (at any depth) with the mapped entity id
+ * from `nodeToId`, or null when the node no longer exists. Exact inverse of
+ * canonicalization for the id-bearing positions.
+ */
+declare function decanonicalizeComponentValue(value: unknown, nodeToId: Map<string, number>): unknown;
+declare const encodeOverride: (nodeId: string, componentName: string, path: string) => string;
+declare function parseOverride(encoded: string): {
+    nodeId: string;
+    componentName: string;
+    path: string;
+} | null;
+/** nodeId → componentName → set of overridden paths. */
+declare function groupOverridePaths(overrides: string[]): Map<string, Map<string, Set<string>>>;
+/**
+ * Collect leaf paths where two canonical values differ. Semantics:
+ * - `{$node}` refs compare atomically by nodeId
+ * - arrays of differing length are ONE atomic override (the array path);
+ *   equal lengths recurse per index
+ * - object key present on one side only marks that key's path
+ * - type mismatches mark the current path
+ * An empty-string path means the values differ at the top level.
+ */
+declare function collectDiffPaths(base: unknown, current: unknown, prefix?: string, out?: string[]): string[];
+/**
+ * Diff a live instance subtree against its prefab base (both as serialized
+ * 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).
+ */
+declare function computeInstanceOverrides(baseSnapshot: SubtreeSnapshot, instanceSnapshot: SubtreeSnapshot): 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
+ * path ("") means the whole component is overridden → instance wins.
+ */
+declare function mergeComponentValue(newFileCanonical: unknown, instanceCanonical: unknown, overridePaths: Set<string> | undefined): unknown;
+
+type SerializeEntitySubtreeResult = {
+    snapshot: SubtreeSnapshot;
+    /**
+     * References that pointed OUTSIDE the subtree and were nulled out
+     * (ids are LIVE world ids so callers can name the offending entities).
+     * The root's own external parent link is nulled silently — it is expected.
+     */
+    warnings: ExternalRefWarning[];
+    /** Component types stripped because they are scene singletons. */
+    strippedComponents: string[];
+};
+/**
+ * Serialize `rootId` + all descendants into a self-contained snapshot:
+ * entity ids renumbered 1..N in BFS parent-first order, all internal id
+ * references remapped, external references nulled + reported, root ParentId
+ * forced to null. The result is directly consumable by
+ * `hydrateWorldFromSnapshotDetailed` / `instantiateSubtree`.
+ */
+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 };