@relu-interactives/spatial-ecs 0.2.20 → 0.2.22

package/dist/index.d.cts

@@ -1,11 +1,11 @@
-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-CYWZ_Zx5.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-CYWZ_Zx5.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';
-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 { O as Object3DRef } from './Video-ppAXaKt0.cjs';
+export { a6 as AnimationStateCallbacks, a7 as AnimationStateMachine, a8 as AnimationStateManager, a9 as StateMachine } from './Video-ppAXaKt0.cjs';
+export { i as CoreComponents } from './index-Cu2Pt7wN.cjs';
+export { AnimationSystem, AudioSystem, CameraSyncSystem, EnvironmentSyncSystem, InstancedMeshSystem, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, ModuleLoader, ObjectVisibilitySystem, PhysicsSyncSystem, PostprocessingSyncSystem, SCRIPT_OBJECT_ROOT_FLAG, ScriptBehaviourSystem, ScriptObjectSystem, 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, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.cjs';
 import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import '@dimforge/rapier3d-compat';
 
@@ -25,15 +25,10 @@ interface CustomEcsSystem extends EcsSystem {
  * Override {@link Behaviour.onUpdate} for per-frame logic — never override
  * {@link Behaviour.update}, which is the engine-managed entry point.
  *
- * **Editor scripts**: By default, `Behaviour` subclasses do not run inside the
- * editor. Set `executeInEditor: true` on the script entry in the inspector to
- * enable the full lifecycle (`init` → `onUpdate` → `dispose`) while the editor
- * is open. This gives direct access to the Three.js scene, camera, and renderer
- * via {@link World.getScene}, {@link World.getCamera}, and
- * {@link World.getRenderer} — useful for custom shaders, procedural geometry,
- * grass, and any Three.js feature the editor's object palette does not expose.
- * Avoid mutating ECS component state every frame in editor mode, as it creates
- * undo history entries on every tick.
+ * **Editor vs runtime**: `Behaviour` subclasses run ONLY at preview/runtime —
+ * they never execute in the editor. For a visual that must render and animate
+ * inside the editor (custom shaders, procedural geometry, grass, anything the
+ * object palette can't produce), use {@link ScriptObject} instead.
  *
  * The runtime recognizes a script by its **default export** plus the
  * inherited static marker `__reluBehaviourClass`. Do not override the marker.
@@ -248,21 +243,13 @@ declare class Behaviour implements CustomEcsSystem {
     /**
      * Called once before the first {@link Behaviour.onUpdate}. Override to
      * default and validate {@link Behaviour.data}, cache references, or set
-     * initial state.
-     *
-     * @remarks
-     * Also called in editor mode when `executeInEditor` is `true` on the script
-     * entry.
+     * initial state. Runs at preview/runtime only — never in the editor.
      */
     protected init(): void;
     /**
      * Called every frame while the script is enabled. Override with the
-     * script's main per-frame logic.
-     *
-     * @remarks
-     * Also called every frame in editor mode when `executeInEditor` is `true`.
-     * Access the Three.js scene with `this.world.getScene()` for editor-only
-     * rendering work such as custom shaders or procedural geometry.
+     * script's main per-frame logic. Runs at preview/runtime only — never in the
+     * editor (use {@link ScriptObject} for editor-visible visuals).
      */
     protected onUpdate(): void;
     /** Called when the editor selects this entity. Optional UX hook. */
@@ -285,6 +272,105 @@ declare class Behaviour implements CustomEcsSystem {
     onTargetLost(target: WorldEntityView): void;
 }
 
+/**
+ * Base class for **script objects** — entities whose THREE.js visual is built
+ * entirely by user code (procedural geometry, shaders, particle systems,
+ * anything the editor can't author natively).
+ *
+ * The critical difference from {@link Behaviour}: a `ScriptObject` runs in the
+ * **editor AND at runtime** — `build()` and `update()` execute identically in
+ * both. `ScriptObjectSystem` loads the module, instantiates the class, calls
+ * `build()` to get the visual, attaches it under the entity's Object3D, and
+ * ticks `update()` every frame. **Do NOT gate anything on
+ * `world.isEditorMode()`** — running everywhere is the whole point. Use
+ * {@link Behaviour} for gameplay logic that must NOT run in the editor.
+ *
+ * Subclasses are resolved by the inherited static marker
+ * `__reluScriptObjectClass` (survives bundler identity splits). Do not override
+ * the marker.
+ *
+ * @example
+ * ```ts
+ * import { ScriptObject, type ColorInput } from "@relu-interactives/spatial-ecs";
+ * import * as THREE from "three";
+ *
+ * export default class GlowOrb extends ScriptObject {
+ *   declare data: { color: ColorInput };
+ *   private mat!: THREE.MeshStandardMaterial;
+ *
+ *   build(): THREE.Object3D {
+ *     this.data.color ??= { type: "color", value: "#66ccff" };
+ *     this.mat = new THREE.MeshStandardMaterial({
+ *       color: this.data.color.value,
+ *       emissive: this.data.color.value,
+ *     });
+ *     return new THREE.Mesh(new THREE.SphereGeometry(0.5, 32, 32), this.mat);
+ *   }
+ *
+ *   update(dt: number): void {
+ *     this.mat.emissiveIntensity = 0.5 + 0.5 * Math.sin(performance.now() * 0.002);
+ *   }
+ *
+ *   dispose(): void {
+ *     this.mat.dispose();
+ *   }
+ * }
+ * ```
+ *
+ * @category Scripting
+ */
+declare class ScriptObject {
+    /**
+     * Static marker used by `ScriptObjectSystem` to detect `ScriptObject`
+     * subclasses even when a bundler ships a second copy of the package into the
+     * script blob (breaking `instanceof`). Do NOT override.
+     */
+    static readonly __reluScriptObjectClass: true;
+    /**
+     * The script's data payload (the `ScriptObjectComponent.data`). Declare a
+     * concrete shape on subclasses with `declare data: MyShape` for type safety.
+     * Use the same typed input envelopes as Behaviours (`ColorInput`,
+     * `SliderInput`, `EntityInput`, …) to get inspector fields.
+     */
+    data: Record<string, unknown>;
+    /** The owning ECS world. */
+    world: World;
+    /** The entity this script object is bound to. */
+    entityId: number;
+    /**
+     * The Object3D returned by {@link ScriptObject.build}. Assigned by
+     * `ScriptObjectSystem` after `build()` runs; `null` until then.
+     */
+    root: THREE.Object3D | null;
+    /**
+     * Engine-managed constructor. `ScriptObjectSystem` instantiates subclasses
+     * with the owning world, the entity id, and the component's `data`. User code
+     * should not call this directly.
+     */
+    constructor(world: World, entityId: number, data?: Record<string, unknown>);
+    /**
+     * REQUIRED — build and return the visual root. Called once by
+     * `ScriptObjectSystem` after construction. The returned object is attached
+     * under the entity's Object3D (so it inherits the entity transform, selection
+     * and visibility). Subclasses MUST override.
+     */
+    build(): THREE.Object3D;
+    /**
+     * OPTIONAL — per-frame hook. Runs in the editor AND at runtime (e.g. advance
+     * a shader time uniform, procedural animation). Keep per-frame work on local
+     * THREE state / uniforms — do NOT write ECS components every frame (that
+     * churns the editor's undo history).
+     */
+    update?(deltaTime: number): void;
+    /**
+     * OPTIONAL — free any GPU resources this script created (geometries,
+     * materials, textures, render targets). Called by `ScriptObjectSystem` when
+     * the object is removed, disabled, or reloaded. THREE `dispose()` is
+     * idempotent, so double-dispose is safe.
+     */
+    dispose?(): void;
+}
+
 type ComponentValueMaps = {
     object3DRefValues: Map<number, unknown>;
     nameValues: Map<number, unknown>;
@@ -306,6 +392,7 @@ type ComponentValueMaps = {
     animationValues: Map<number, unknown>;
     imageTargetAnchorValues: Map<number, unknown>;
     scriptValues: Map<number, unknown>;
+    scriptObjectValues: Map<number, unknown>;
     instancedMeshValues: Map<number, unknown>;
     instanceSlotValues: Map<number, unknown>;
     prefabNodeValues: Map<number, unknown>;
@@ -390,6 +477,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 +509,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;
@@ -451,6 +627,8 @@ declare function indexSnapshotByEntity(snapshot: SubtreeSnapshot): Map<number, M
  * - entity-id fields → `{$node}` (internal) or raw id (external)
  * - ScriptComponent entries keep only `{className, scriptUrl, enabled, data}`
  *   (entityId/runtimeState/runtimeMessage are per-instance transients)
+ * - ScriptObjectComponent keeps only `{scriptUrl, className, enabled, data}`
+ *   (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`.
@@ -485,11 +663,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 +706,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, ScriptObject, 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,11 +1,11 @@
-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-CYWZ_Zx5.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-CYWZ_Zx5.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';
-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 { O as Object3DRef } from './Video-C1IOat7L.js';
+export { a6 as AnimationStateCallbacks, a7 as AnimationStateMachine, a8 as AnimationStateManager, a9 as StateMachine } from './Video-C1IOat7L.js';
+export { i as CoreComponents } from './index-DdiWu1b6.js';
+export { AnimationSystem, AudioSystem, CameraSyncSystem, EnvironmentSyncSystem, InstancedMeshSystem, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, ModuleLoader, ObjectVisibilitySystem, PhysicsSyncSystem, PostprocessingSyncSystem, SCRIPT_OBJECT_ROOT_FLAG, ScriptBehaviourSystem, ScriptObjectSystem, 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, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVideoComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.js';
 import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import '@dimforge/rapier3d-compat';
 
@@ -25,15 +25,10 @@ interface CustomEcsSystem extends EcsSystem {
  * Override {@link Behaviour.onUpdate} for per-frame logic — never override
  * {@link Behaviour.update}, which is the engine-managed entry point.
  *
- * **Editor scripts**: By default, `Behaviour` subclasses do not run inside the
- * editor. Set `executeInEditor: true` on the script entry in the inspector to
- * enable the full lifecycle (`init` → `onUpdate` → `dispose`) while the editor
- * is open. This gives direct access to the Three.js scene, camera, and renderer
- * via {@link World.getScene}, {@link World.getCamera}, and
- * {@link World.getRenderer} — useful for custom shaders, procedural geometry,
- * grass, and any Three.js feature the editor's object palette does not expose.
- * Avoid mutating ECS component state every frame in editor mode, as it creates
- * undo history entries on every tick.
+ * **Editor vs runtime**: `Behaviour` subclasses run ONLY at preview/runtime —
+ * they never execute in the editor. For a visual that must render and animate
+ * inside the editor (custom shaders, procedural geometry, grass, anything the
+ * object palette can't produce), use {@link ScriptObject} instead.
  *
  * The runtime recognizes a script by its **default export** plus the
  * inherited static marker `__reluBehaviourClass`. Do not override the marker.
@@ -248,21 +243,13 @@ declare class Behaviour implements CustomEcsSystem {
     /**
      * Called once before the first {@link Behaviour.onUpdate}. Override to
      * default and validate {@link Behaviour.data}, cache references, or set
-     * initial state.
-     *
-     * @remarks
-     * Also called in editor mode when `executeInEditor` is `true` on the script
-     * entry.
+     * initial state. Runs at preview/runtime only — never in the editor.
      */
     protected init(): void;
     /**
      * Called every frame while the script is enabled. Override with the
-     * script's main per-frame logic.
-     *
-     * @remarks
-     * Also called every frame in editor mode when `executeInEditor` is `true`.
-     * Access the Three.js scene with `this.world.getScene()` for editor-only
-     * rendering work such as custom shaders or procedural geometry.
+     * script's main per-frame logic. Runs at preview/runtime only — never in the
+     * editor (use {@link ScriptObject} for editor-visible visuals).
      */
     protected onUpdate(): void;
     /** Called when the editor selects this entity. Optional UX hook. */
@@ -285,6 +272,105 @@ declare class Behaviour implements CustomEcsSystem {
     onTargetLost(target: WorldEntityView): void;
 }
 
+/**
+ * Base class for **script objects** — entities whose THREE.js visual is built
+ * entirely by user code (procedural geometry, shaders, particle systems,
+ * anything the editor can't author natively).
+ *
+ * The critical difference from {@link Behaviour}: a `ScriptObject` runs in the
+ * **editor AND at runtime** — `build()` and `update()` execute identically in
+ * both. `ScriptObjectSystem` loads the module, instantiates the class, calls
+ * `build()` to get the visual, attaches it under the entity's Object3D, and
+ * ticks `update()` every frame. **Do NOT gate anything on
+ * `world.isEditorMode()`** — running everywhere is the whole point. Use
+ * {@link Behaviour} for gameplay logic that must NOT run in the editor.
+ *
+ * Subclasses are resolved by the inherited static marker
+ * `__reluScriptObjectClass` (survives bundler identity splits). Do not override
+ * the marker.
+ *
+ * @example
+ * ```ts
+ * import { ScriptObject, type ColorInput } from "@relu-interactives/spatial-ecs";
+ * import * as THREE from "three";
+ *
+ * export default class GlowOrb extends ScriptObject {
+ *   declare data: { color: ColorInput };
+ *   private mat!: THREE.MeshStandardMaterial;
+ *
+ *   build(): THREE.Object3D {
+ *     this.data.color ??= { type: "color", value: "#66ccff" };
+ *     this.mat = new THREE.MeshStandardMaterial({
+ *       color: this.data.color.value,
+ *       emissive: this.data.color.value,
+ *     });
+ *     return new THREE.Mesh(new THREE.SphereGeometry(0.5, 32, 32), this.mat);
+ *   }
+ *
+ *   update(dt: number): void {
+ *     this.mat.emissiveIntensity = 0.5 + 0.5 * Math.sin(performance.now() * 0.002);
+ *   }
+ *
+ *   dispose(): void {
+ *     this.mat.dispose();
+ *   }
+ * }
+ * ```
+ *
+ * @category Scripting
+ */
+declare class ScriptObject {
+    /**
+     * Static marker used by `ScriptObjectSystem` to detect `ScriptObject`
+     * subclasses even when a bundler ships a second copy of the package into the
+     * script blob (breaking `instanceof`). Do NOT override.
+     */
+    static readonly __reluScriptObjectClass: true;
+    /**
+     * The script's data payload (the `ScriptObjectComponent.data`). Declare a
+     * concrete shape on subclasses with `declare data: MyShape` for type safety.
+     * Use the same typed input envelopes as Behaviours (`ColorInput`,
+     * `SliderInput`, `EntityInput`, …) to get inspector fields.
+     */
+    data: Record<string, unknown>;
+    /** The owning ECS world. */
+    world: World;
+    /** The entity this script object is bound to. */
+    entityId: number;
+    /**
+     * The Object3D returned by {@link ScriptObject.build}. Assigned by
+     * `ScriptObjectSystem` after `build()` runs; `null` until then.
+     */
+    root: THREE.Object3D | null;
+    /**
+     * Engine-managed constructor. `ScriptObjectSystem` instantiates subclasses
+     * with the owning world, the entity id, and the component's `data`. User code
+     * should not call this directly.
+     */
+    constructor(world: World, entityId: number, data?: Record<string, unknown>);
+    /**
+     * REQUIRED — build and return the visual root. Called once by
+     * `ScriptObjectSystem` after construction. The returned object is attached
+     * under the entity's Object3D (so it inherits the entity transform, selection
+     * and visibility). Subclasses MUST override.
+     */
+    build(): THREE.Object3D;
+    /**
+     * OPTIONAL — per-frame hook. Runs in the editor AND at runtime (e.g. advance
+     * a shader time uniform, procedural animation). Keep per-frame work on local
+     * THREE state / uniforms — do NOT write ECS components every frame (that
+     * churns the editor's undo history).
+     */
+    update?(deltaTime: number): void;
+    /**
+     * OPTIONAL — free any GPU resources this script created (geometries,
+     * materials, textures, render targets). Called by `ScriptObjectSystem` when
+     * the object is removed, disabled, or reloaded. THREE `dispose()` is
+     * idempotent, so double-dispose is safe.
+     */
+    dispose?(): void;
+}
+
 type ComponentValueMaps = {
     object3DRefValues: Map<number, unknown>;
     nameValues: Map<number, unknown>;
@@ -306,6 +392,7 @@ type ComponentValueMaps = {
     animationValues: Map<number, unknown>;
     imageTargetAnchorValues: Map<number, unknown>;
     scriptValues: Map<number, unknown>;
+    scriptObjectValues: Map<number, unknown>;
     instancedMeshValues: Map<number, unknown>;
     instanceSlotValues: Map<number, unknown>;
     prefabNodeValues: Map<number, unknown>;
@@ -390,6 +477,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 +509,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;
@@ -451,6 +627,8 @@ declare function indexSnapshotByEntity(snapshot: SubtreeSnapshot): Map<number, M
  * - entity-id fields → `{$node}` (internal) or raw id (external)
  * - ScriptComponent entries keep only `{className, scriptUrl, enabled, data}`
  *   (entityId/runtimeState/runtimeMessage are per-instance transients)
+ * - ScriptObjectComponent keeps only `{scriptUrl, className, enabled, data}`
+ *   (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`.
@@ -485,11 +663,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 +706,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, ScriptObject, 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 };