@relu-interactives/spatial-ecs 0.2.20 → 0.2.22

package/dist/{chunk-67MFQDHX.js → chunk-GZ2NKSMV.js}

@@ -1,5 +1,5 @@
-import { resolveDracoDecoderPath, applyTransform } from './chunk-DY4ETMP2.js';
-import { AnimationComponent, ModelComponent, CameraComponent, Object3DRef, Environment, Postprocessing, TransformComponent, PhysicsComponent, LightComponent, MaterialComponent, DEFAULT_MESH_GEOMETRY_PARAMETERS, MeshGeometryComponent, InstancedMeshComponent, ParentId, ScriptComponent, InstanceSlotComponent, Name, ImageComponent, SpriteComponent, VideoComponent, AudioComponent, ImageTarget, Selectable, PrefabNode, PrefabInstance } from './chunk-Z6OMYEXU.js';
+import { resolveDracoDecoderPath, applyTransform, SHARED_MODEL_RESOURCE_FLAG } from './chunk-WKGCC7YL.js';
+import { AnimationComponent, ModelComponent, CameraComponent, Object3DRef, Environment, Postprocessing, TransformComponent, PhysicsComponent, LightComponent, MaterialComponent, DEFAULT_MESH_GEOMETRY_PARAMETERS, MeshGeometryComponent, InstancedMeshComponent, ParentId, ScriptComponent, ScriptObjectComponent, InstanceSlotComponent, Name, ImageComponent, SpriteComponent, VideoComponent, AudioComponent, ImageTarget, Selectable, PrefabNode, PrefabInstance } from './chunk-JHCPRVBC.js';
 import { __name } from './chunk-OY7ZODZP.js';
 import * as THREE7 from 'three';
 import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
@@ -2741,6 +2741,10 @@ function buildComponentValueMaps(snapshot) {
     animationValues: readByComponent(snapshot.components, "AnimationComponent"),
     imageTargetAnchorValues: readByComponent(snapshot.components, "ImageTargetAnchor"),
     scriptValues: readByComponent(snapshot.components, "ScriptComponent"),
+    scriptObjectValues: readByComponent(
+      snapshot.components,
+      "ScriptObjectComponent"
+    ),
     instancedMeshValues: readByComponent(snapshot.components, "InstancedMeshComponent"),
     instanceSlotValues: readByComponent(snapshot.components, "InstanceSlotComponent"),
     prefabNodeValues: readByComponent(snapshot.components, "PrefabNode"),
@@ -2858,6 +2862,14 @@ function restorePostCreateComponents(world, objectManagementSystem, targetEntity
       new ScriptComponent(entries)
     );
   }
+  const sourceScriptObject = asRecord(values.scriptObjectValues.get(sourceEntityId));
+  if (sourceScriptObject) {
+    const soc = world.getComponent(targetEntityId, ScriptObjectComponent);
+    const data = asRecord(sourceScriptObject.data);
+    if (soc && data) {
+      soc.data = remapEntityRefsInScriptData(data, idMap);
+    }
+  }
   {
     const imComponent = world.getComponent(targetEntityId, InstancedMeshComponent);
     if (imComponent && imComponent.instanceEntityIds.length > 0) {
@@ -3410,7 +3422,13 @@ function restoreComponentState(world, objectManagementSystem, targetEntityId, so
       ) : [];
       world.addComponent(
         targetEntityId,
-        new PrefabInstance(sourcePrefabInstance.url, overrides)
+        new PrefabInstance(
+          sourcePrefabInstance.url,
+          overrides,
+          // Preserve the placement identity; the constructor generates a
+          // fresh one for legacy snapshots that predate instanceId.
+          typeof sourcePrefabInstance.instanceId === "string" && sourcePrefabInstance.instanceId.length > 0 ? sourcePrefabInstance.instanceId : void 0
+        )
       );
     }
   }
@@ -3438,7 +3456,8 @@ var HYDRATABLE_ENTITY_KINDS = /* @__PURE__ */ new Set([
   "spotLight",
   "areaLight",
   "instancedMesh",
-  "instanceSlot"
+  "instanceSlot",
+  "scriptObject"
 ]);
 
 // core/hydration/hydrateWorld.ts
@@ -3540,6 +3559,16 @@ function buildEntityCreationPayload(sourceEntityId, kind, componentValues) {
       };
     }
   }
+  if (kind === "scriptObject") {
+    const so = asRecord(componentValues.scriptObjectValues.get(sourceEntityId));
+    if (so) {
+      payload.options = {
+        scriptUrl: typeof so.scriptUrl === "string" ? so.scriptUrl : null,
+        className: typeof so.className === "string" ? so.className : null,
+        enabled: typeof so.enabled === "boolean" ? so.enabled : true
+      };
+    }
+  }
   return payload;
 }
 __name(buildEntityCreationPayload, "buildEntityCreationPayload");
@@ -3657,6 +3686,148 @@ function hydrateWorldFromSnapshot(snapshot, world, objectManagementSystem) {
 }
 __name(hydrateWorldFromSnapshot, "hydrateWorldFromSnapshot");
 
+// core/prefab/nodeKeys.ts
+var NODE_KEY_SEPARATOR = "/";
+var ADDED_NODE_MARKER_COMPONENT = "+node";
+var asRecord2 = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null, "asRecord");
+var readBlock = /* @__PURE__ */ __name((snapshot, component) => {
+  const map = /* @__PURE__ */ new Map();
+  const block = snapshot.components.find((b) => b.component === component);
+  for (const entry of block?.entries ?? []) {
+    const record = asRecord2(entry.value);
+    if (record) {
+      map.set(entry.entityId, record);
+    }
+  }
+  return map;
+}, "readBlock");
+var fallbackInstanceId = /* @__PURE__ */ __name((entityId) => `e${entityId}`, "fallbackInstanceId");
+function buildNodeKeyMapsFromSnapshot(snapshot, options) {
+  const parentValues = readBlock(snapshot, "ParentId");
+  const nodeValues = readBlock(snapshot, "PrefabNode");
+  const instanceValues = readBlock(snapshot, "PrefabInstance");
+  const inDocument = new Set(snapshot.entities);
+  const childrenByParent = /* @__PURE__ */ new Map();
+  const rootIds = [];
+  for (const entityId of snapshot.entities) {
+    const parent = parentValues.get(entityId)?.value;
+    if (typeof parent === "number" && inDocument.has(parent)) {
+      const siblings = childrenByParent.get(parent);
+      if (siblings) siblings.push(entityId);
+      else childrenByParent.set(parent, [entityId]);
+    } else {
+      rootIds.push(entityId);
+    }
+  }
+  const scopeRoots = options?.scopeRootEntityId !== void 0 ? [options.scopeRootEntityId] : rootIds;
+  const idToKey = /* @__PURE__ */ new Map();
+  const keyToId = /* @__PURE__ */ new Map();
+  const boundaryIds = /* @__PURE__ */ new Map();
+  const scopeRootSet = new Set(scopeRoots);
+  const queue = scopeRoots.map(
+    (entityId) => ({ entityId, prefix: "" })
+  );
+  while (queue.length > 0) {
+    const { entityId, prefix } = queue.shift();
+    const instance = instanceValues.get(entityId);
+    const isBoundary = Boolean(
+      instance && typeof instance.url === "string" && !scopeRootSet.has(entityId)
+    );
+    let ownPrefix = prefix;
+    let childPrefix = prefix;
+    if (isBoundary && instance) {
+      const instanceId = typeof instance.instanceId === "string" && instance.instanceId.length > 0 ? instance.instanceId : fallbackInstanceId(entityId);
+      childPrefix = `${prefix}${instanceId}${NODE_KEY_SEPARATOR}`;
+      ownPrefix = childPrefix;
+      boundaryIds.set(entityId, {
+        url: instance.url,
+        instanceId
+      });
+    }
+    const nodeId = nodeValues.get(entityId)?.nodeId;
+    if (typeof nodeId === "string" && nodeId.length > 0) {
+      const key = `${ownPrefix}${nodeId}`;
+      idToKey.set(entityId, key);
+      keyToId.set(key, entityId);
+    }
+    for (const child of childrenByParent.get(entityId) ?? []) {
+      queue.push({ entityId: child, prefix: childPrefix });
+    }
+  }
+  const rootEntityId = scopeRoots[0];
+  const rootNodeId = rootEntityId !== void 0 ? nodeValues.get(rootEntityId)?.nodeId : void 0;
+  return {
+    idToKey,
+    keyToId,
+    rootKey: typeof rootNodeId === "string" && rootNodeId.length > 0 ? rootNodeId : null,
+    boundaryIds
+  };
+}
+__name(buildNodeKeyMapsFromSnapshot, "buildNodeKeyMapsFromSnapshot");
+function collectSnapshotSubtreeIds(snapshot, rootEntityId) {
+  const parentValues = readBlock(snapshot, "ParentId");
+  const childrenByParent = /* @__PURE__ */ new Map();
+  for (const entityId of snapshot.entities) {
+    const parent = parentValues.get(entityId)?.value;
+    if (typeof parent === "number") {
+      const siblings = childrenByParent.get(parent);
+      if (siblings) siblings.push(entityId);
+      else childrenByParent.set(parent, [entityId]);
+    }
+  }
+  const ordered = [];
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [rootEntityId];
+  while (queue.length > 0) {
+    const entityId = queue.shift();
+    if (seen.has(entityId)) continue;
+    seen.add(entityId);
+    ordered.push(entityId);
+    queue.push(...childrenByParent.get(entityId) ?? []);
+  }
+  return ordered;
+}
+__name(collectSnapshotSubtreeIds, "collectSnapshotSubtreeIds");
+function findTopLevelNestedRegions(snapshot) {
+  const parentValues = readBlock(snapshot, "ParentId");
+  const instanceValues = readBlock(snapshot, "PrefabInstance");
+  const inDocument = new Set(snapshot.entities);
+  const roots = new Set(
+    snapshot.entities.filter((entityId) => {
+      const parent = parentValues.get(entityId)?.value;
+      return typeof parent !== "number" || !inDocument.has(parent);
+    })
+  );
+  const regions = [];
+  for (const [entityId, instance] of instanceValues) {
+    if (roots.has(entityId)) continue;
+    if (typeof instance.url !== "string" || instance.url.length === 0) continue;
+    let ancestor = parentValues.get(entityId)?.value;
+    let nestedDeeper = false;
+    let hops = 0;
+    while (typeof ancestor === "number" && hops < 512) {
+      if (instanceValues.has(ancestor) && !roots.has(ancestor)) {
+        nestedDeeper = true;
+        break;
+      }
+      ancestor = parentValues.get(ancestor)?.value;
+      hops += 1;
+    }
+    if (nestedDeeper) continue;
+    regions.push({
+      rootEntityId: entityId,
+      url: instance.url,
+      instanceId: typeof instance.instanceId === "string" && instance.instanceId.length > 0 ? instance.instanceId : fallbackInstanceId(entityId),
+      overrides: Array.isArray(instance.overrides) ? instance.overrides.filter(
+        (entry) => typeof entry === "string"
+      ) : []
+    });
+  }
+  regions.sort((a, b) => a.rootEntityId - b.rootEntityId);
+  return regions;
+}
+__name(findTopLevelNestedRegions, "findTopLevelNestedRegions");
+
 // core/prefab/overrides.ts
 var OVERRIDE_DIFF_EXCLUDED_COMPONENTS = /* @__PURE__ */ new Set([
   "PrefabNode",
@@ -3670,10 +3841,10 @@ var OVERRIDE_ROOT_EXCLUDED_COMPONENTS = /* @__PURE__ */ new Set([
   "Name",
   "ParentId"
 ]);
-var asRecord2 = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null, "asRecord");
+var asRecord3 = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null, "asRecord");
 var clone = /* @__PURE__ */ __name((value) => value === void 0 ? value : structuredClone(value), "clone");
 var isNodeRef = /* @__PURE__ */ __name((value) => {
-  const record = asRecord2(value);
+  const record = asRecord3(value);
   return Boolean(
     record && typeof record.$node === "string" && Object.keys(record).length === 1
   );
@@ -3685,7 +3856,7 @@ function findSnapshotRootEntityIds(snapshot) {
   );
   const parentByEntity = /* @__PURE__ */ new Map();
   for (const entry of parentBlock?.entries ?? []) {
-    parentByEntity.set(entry.entityId, asRecord2(entry.value)?.value ?? null);
+    parentByEntity.set(entry.entityId, asRecord3(entry.value)?.value ?? null);
   }
   return snapshot.entities.filter(
     (entityId) => typeof parentByEntity.get(entityId) !== "number"
@@ -3699,7 +3870,7 @@ function buildNodeMapsFromSnapshot(snapshot) {
     (block) => block.component === "PrefabNode"
   );
   for (const entry of nodeBlock?.entries ?? []) {
-    const nodeId = asRecord2(entry.value)?.nodeId;
+    const nodeId = asRecord3(entry.value)?.nodeId;
     if (typeof nodeId === "string" && nodeId.length > 0) {
       idToNode.set(entry.entityId, nodeId);
       nodeToId.set(nodeId, entry.entityId);
@@ -3729,9 +3900,36 @@ var toRefOrRaw = /* @__PURE__ */ __name((id, idToNode) => {
   const nodeId = idToNode.get(id);
   return nodeId !== void 0 ? makeNodeRef(nodeId) : id;
 }, "toRefOrRaw");
+function canonicalizeScriptDataFields(data, idToNode) {
+  const canonicalData = {};
+  for (const [key, fieldValue] of Object.entries(data)) {
+    const field = asRecord3(fieldValue);
+    if (field?.type === "entity" && typeof field.value === "number") {
+      canonicalData[key] = {
+        ...field,
+        value: toRefOrRaw(field.value, idToNode)
+      };
+      continue;
+    }
+    const componentRef = asRecord3(field?.value);
+    if (field?.type === "component" && componentRef && typeof componentRef.entityId === "number") {
+      canonicalData[key] = {
+        ...field,
+        value: {
+          ...componentRef,
+          entityId: toRefOrRaw(componentRef.entityId, idToNode)
+        }
+      };
+      continue;
+    }
+    canonicalData[key] = fieldValue;
+  }
+  return canonicalData;
+}
+__name(canonicalizeScriptDataFields, "canonicalizeScriptDataFields");
 function canonicalizeComponentValue(componentName, value, idToNode) {
   const cloned = clone(value);
-  const record = asRecord2(cloned);
+  const record = asRecord3(cloned);
   if (!record) {
     return cloned;
   }
@@ -3750,43 +3948,27 @@ function canonicalizeComponentValue(componentName, value, idToNode) {
     const entries = Array.isArray(record.entries) ? record.entries : [];
     return {
       entries: entries.map((rawEntry) => {
-        const entry = asRecord2(rawEntry);
+        const entry = asRecord3(rawEntry);
         if (!entry) {
           return rawEntry;
         }
-        const data = asRecord2(entry.data) ?? {};
-        const canonicalData = {};
-        for (const [key, fieldValue] of Object.entries(data)) {
-          const field = asRecord2(fieldValue);
-          if (field?.type === "entity" && typeof field.value === "number") {
-            canonicalData[key] = {
-              ...field,
-              value: toRefOrRaw(field.value, idToNode)
-            };
-            continue;
-          }
-          const componentRef = asRecord2(field?.value);
-          if (field?.type === "component" && componentRef && typeof componentRef.entityId === "number") {
-            canonicalData[key] = {
-              ...field,
-              value: {
-                ...componentRef,
-                entityId: toRefOrRaw(componentRef.entityId, idToNode)
-              }
-            };
-            continue;
-          }
-          canonicalData[key] = fieldValue;
-        }
         return {
           className: typeof entry.className === "string" ? entry.className : "",
           scriptUrl: typeof entry.scriptUrl === "string" ? entry.scriptUrl : "",
           enabled: typeof entry.enabled === "boolean" ? entry.enabled : true,
-          data: canonicalData
+          data: canonicalizeScriptDataFields(asRecord3(entry.data) ?? {}, idToNode)
         };
       })
     };
   }
+  if (componentName === "ScriptObjectComponent") {
+    return {
+      scriptUrl: typeof record.scriptUrl === "string" ? record.scriptUrl : null,
+      className: typeof record.className === "string" ? record.className : null,
+      enabled: typeof record.enabled === "boolean" ? record.enabled : true,
+      data: canonicalizeScriptDataFields(asRecord3(record.data) ?? {}, idToNode)
+    };
+  }
   if (componentName === "InstancedMeshComponent") {
     if (Array.isArray(record.instanceEntityIds)) {
       record.instanceEntityIds = record.instanceEntityIds.map(
@@ -3811,7 +3993,7 @@ function decanonicalizeComponentValue(value, nodeToId) {
   if (Array.isArray(value)) {
     return value.map((item) => decanonicalizeComponentValue(item, nodeToId));
   }
-  const record = asRecord2(value);
+  const record = asRecord3(value);
   if (record) {
     const result = {};
     for (const [key, item] of Object.entries(record)) {
@@ -3914,15 +4096,20 @@ function collectDiffPaths(base, current, prefix = "", out = []) {
   return out;
 }
 __name(collectDiffPaths, "collectDiffPaths");
-function computeInstanceOverrides(baseSnapshot, instanceSnapshot) {
-  const baseMaps = buildNodeMapsFromSnapshot(baseSnapshot);
-  const instanceMaps = buildNodeMapsFromSnapshot(instanceSnapshot);
+function computeInstanceOverrides(baseSnapshot, instanceSnapshot, options) {
+  const baseMaps = buildNodeKeyMapsFromSnapshot(baseSnapshot);
+  const instanceMaps = buildNodeKeyMapsFromSnapshot(instanceSnapshot);
   const baseByEntity = indexSnapshotByEntity(baseSnapshot);
   const instanceByEntity = indexSnapshotByEntity(instanceSnapshot);
   const overrides = [];
-  for (const [nodeId, instanceEntityId] of instanceMaps.nodeToId) {
-    const baseEntityId = baseMaps.nodeToId.get(nodeId);
+  for (const [nodeKey, instanceEntityId] of instanceMaps.keyToId) {
+    const baseEntityId = baseMaps.keyToId.get(nodeKey);
     if (baseEntityId === void 0) {
+      if (options?.emitAdditionMarkers) {
+        overrides.push(
+          encodeOverride(nodeKey, ADDED_NODE_MARKER_COMPONENT, "")
+        );
+      }
       continue;
     }
     const baseComponents = baseByEntity.get(baseEntityId);
@@ -3930,7 +4117,7 @@ function computeInstanceOverrides(baseSnapshot, instanceSnapshot) {
     if (!baseComponents) {
       continue;
     }
-    const isRoot = nodeId === baseMaps.rootNodeId;
+    const isRoot = nodeKey === baseMaps.rootKey;
     for (const [componentName, baseRaw] of baseComponents) {
       if (OVERRIDE_DIFF_EXCLUDED_COMPONENTS.has(componentName)) {
         continue;
@@ -3945,15 +4132,15 @@ function computeInstanceOverrides(baseSnapshot, instanceSnapshot) {
       const baseCanonical = canonicalizeComponentValue(
         componentName,
         baseRaw,
-        baseMaps.idToNode
+        baseMaps.idToKey
       );
       const instanceCanonical = canonicalizeComponentValue(
         componentName,
         instanceRaw,
-        instanceMaps.idToNode
+        instanceMaps.idToKey
       );
       for (const path of collectDiffPaths(baseCanonical, instanceCanonical)) {
-        overrides.push(encodeOverride(nodeId, componentName, path));
+        overrides.push(encodeOverride(nodeKey, componentName, path));
       }
     }
   }
@@ -3967,7 +4154,7 @@ function getAtPath(value, tokens) {
     if (Array.isArray(cursor)) {
       cursor = cursor[Number(token)];
     } else {
-      const record = asRecord2(cursor);
+      const record = asRecord3(cursor);
       if (!record) {
         return void 0;
       }
@@ -3987,7 +4174,7 @@ function setAtPath(target, tokens, value) {
     if (Array.isArray(cursor)) {
       cursor = cursor[Number(token)];
     } else {
-      const record = asRecord2(cursor);
+      const record = asRecord3(cursor);
       if (!record) {
         return;
       }
@@ -4001,7 +4188,7 @@ function setAtPath(target, tokens, value) {
   if (Array.isArray(cursor)) {
     cursor[Number(last)] = value;
   } else {
-    const record = asRecord2(cursor);
+    const record = asRecord3(cursor);
     if (record) {
       if (value === void 0) {
         delete record[last];
@@ -4033,15 +4220,20 @@ __name(mergeComponentValue, "mergeComponentValue");
 var INSTANTIATE_EXCLUDED_COMPONENTS = /* @__PURE__ */ new Set([
   "Environment",
   "Postprocessing",
-  "SelectionTransformState",
-  "PrefabInstance"
+  "SelectionTransformState"
 ]);
 function instantiateSubtree(world, objectManagementSystem, snapshot) {
+  const snapshotRootIds = new Set(findSnapshotRootEntityIds(snapshot));
   const safeSnapshot = {
     entities: snapshot.entities,
-    components: snapshot.components.filter(
-      (block) => !INSTANTIATE_EXCLUDED_COMPONENTS.has(block.component)
-    )
+    components: snapshot.components.filter((block) => !INSTANTIATE_EXCLUDED_COMPONENTS.has(block.component)).map(
+      (block) => block.component === "PrefabInstance" ? {
+        component: block.component,
+        entries: block.entries.filter(
+          (entry) => !snapshotRootIds.has(entry.entityId)
+        )
+      } : block
+    ).filter((block) => block.entries.length > 0)
   };
   const result = hydrateWorldFromSnapshotDetailed(
     safeSnapshot,
@@ -4061,6 +4253,11 @@ __name(instantiateSubtree, "instantiateSubtree");
 
 // core/prefab/types.ts
 var PREFAB_FILE_VERSION = 1;
+var PREFAB_FILE_VERSION_NESTED = 2;
+function prefabFileVersionFor(snapshot) {
+  return findTopLevelNestedRegions(snapshot).length > 0 ? PREFAB_FILE_VERSION_NESTED : PREFAB_FILE_VERSION;
+}
+__name(prefabFileVersionFor, "prefabFileVersionFor");
 var isRecord = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isRecord");
 function parsePrefabAsset(json) {
   if (!isRecord(json)) {
@@ -4474,22 +4671,14 @@ var _Behaviour = class _Behaviour {
   /**
    * 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.
    */
   init() {
   }
   /**
    * 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).
    */
   onUpdate() {
   }
@@ -4528,7 +4717,14 @@ __name(_Behaviour, "Behaviour");
 _Behaviour.__reluBehaviourClass = true;
 var Behaviour = _Behaviour;
 
-// core/systems/ScriptBehaviourSystem.ts
+// core/systems/scriptShared.ts
+async function defaultModuleLoader(scriptUrl) {
+  return await import(
+    /* webpackIgnore: true */
+    scriptUrl
+  );
+}
+__name(defaultModuleLoader, "defaultModuleLoader");
 function toErrorMessage(error) {
   const sanitize = /* @__PURE__ */ __name((value) => value.replace(/localasset:\/\/[^/]+\//g, "localasset://").replace(/\/Users\/[^\s)]+/g, "[local path]"), "sanitize");
   if (error instanceof Error && error.message) {
@@ -4540,26 +4736,22 @@ function toErrorMessage(error) {
   return "Unknown script error.";
 }
 __name(toErrorMessage, "toErrorMessage");
-function buildInstanceKey(entityId, scriptUrl, className) {
-  return `${entityId}:${scriptUrl}:${className}`;
-}
-__name(buildInstanceKey, "buildInstanceKey");
-function resolveBehaviourCtor(moduleValue, className) {
+function resolveScriptCtor(moduleValue, className, options) {
   const named = moduleValue[className];
   const fallback = moduleValue.default;
   const candidate = typeof named === "function" ? named : typeof fallback === "function" ? fallback : null;
   if (!candidate) {
     return null;
   }
-  if (!(candidate.prototype instanceof Behaviour)) {
-    const isBehaviourSubclass = !!candidate.__reluBehaviourClass;
-    if (!isBehaviourSubclass) {
+  if (!(candidate.prototype instanceof options.baseClass)) {
+    const marker = candidate[options.markerKey];
+    if (!marker) {
       return null;
     }
   }
   return candidate;
 }
-__name(resolveBehaviourCtor, "resolveBehaviourCtor");
+__name(resolveScriptCtor, "resolveScriptCtor");
 function normalizeScriptData(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
@@ -4641,8 +4833,8 @@ function resolveInputData(world, rawData) {
   return resolved;
 }
 __name(resolveInputData, "resolveInputData");
-function serializeDataForStorage(rawData, behaviourData) {
-  const result = { ...behaviourData };
+function serializeDataForStorage(rawData, instanceData) {
+  const result = { ...instanceData };
   for (const [key, rawValue] of Object.entries(rawData)) {
     if (isRawEntityInput(rawValue) || isRawComponentInput(rawValue)) {
       result[key] = rawValue;
@@ -4651,13 +4843,25 @@ function serializeDataForStorage(rawData, behaviourData) {
   return result;
 }
 __name(serializeDataForStorage, "serializeDataForStorage");
+
+// core/systems/ScriptBehaviourSystem.ts
+function buildInstanceKey(entityId, scriptUrl, className) {
+  return `${entityId}:${scriptUrl}:${className}`;
+}
+__name(buildInstanceKey, "buildInstanceKey");
+function resolveBehaviourCtor(moduleValue, className) {
+  return resolveScriptCtor(moduleValue, className, {
+    baseClass: Behaviour,
+    markerKey: "__reluBehaviourClass"
+  });
+}
+__name(resolveBehaviourCtor, "resolveBehaviourCtor");
 function normalizeEntry(value, fallbackEntityId) {
   return {
     entityId: typeof value?.entityId === "number" ? value.entityId : fallbackEntityId,
     className: typeof value?.className === "string" ? value.className : "",
     scriptUrl: typeof value?.scriptUrl === "string" ? value.scriptUrl : "",
     enabled: typeof value?.enabled === "boolean" ? value.enabled : true,
-    executeInEditor: typeof value?.executeInEditor === "boolean" ? value.executeInEditor : false,
     data: normalizeScriptData(value?.data),
     runtimeState: value?.runtimeState === "idle" || value?.runtimeState === "loading" || value?.runtimeState === "ready" || value?.runtimeState === "error" ? value.runtimeState : void 0,
     runtimeMessage: typeof value?.runtimeMessage === "string" ? value.runtimeMessage : void 0
@@ -4680,13 +4884,6 @@ function writeScriptEntries(component, entries) {
   }
 }
 __name(writeScriptEntries, "writeScriptEntries");
-async function defaultModuleLoader(scriptUrl) {
-  return await import(
-    /* webpackIgnore: true */
-    scriptUrl
-  );
-}
-__name(defaultModuleLoader, "defaultModuleLoader");
 var _ScriptBehaviourSystem = class _ScriptBehaviourSystem {
   constructor(moduleLoader, selectionContext) {
     this.instances = /* @__PURE__ */ new Map();
@@ -4802,11 +4999,11 @@ var _ScriptBehaviourSystem = class _ScriptBehaviourSystem {
       let hasEnabledScript = false;
       for (let entryIndex = 0; entryIndex < nextEntries.length; entryIndex += 1) {
         const entry = nextEntries[entryIndex];
-        const skipInEditor = world.isEditorMode() && !entry.executeInEditor;
+        const skipInEditor = world.isEditorMode();
         if (!entry.enabled || !entry.scriptUrl || skipInEditor) {
           nextEntries[entryIndex] = {
             ...entry,
-            runtimeState: skipInEditor ? "idle" : "idle",
+            runtimeState: "idle",
             runtimeMessage: void 0
           };
           continue;
@@ -4993,7 +5190,7 @@ var _ScriptBehaviourSystem = class _ScriptBehaviourSystem {
     const mergedData = mergeDataByCurrentDefaults(defaults, currentData);
     const resolvedData = resolveInputData(world, mergedData);
     behaviour.data = resolvedData;
-    if (!world.isEditorMode() || liveEntry.executeInEditor === true) {
+    if (!world.isEditorMode()) {
       behaviour.init();
     }
     liveEntries[entryIndex] = {
@@ -5021,6 +5218,328 @@ __name(_ScriptBehaviourSystem, "ScriptBehaviourSystem");
 _ScriptBehaviourSystem.CLICK_THRESHOLD = 6;
 var ScriptBehaviourSystem = _ScriptBehaviourSystem;
 
+// core/ScriptObject.ts
+var _ScriptObject = class _ScriptObject {
+  /**
+   * 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, entityId, data) {
+    /**
+     * 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.
+     */
+    this.data = {};
+    /**
+     * The Object3D returned by {@link ScriptObject.build}. Assigned by
+     * `ScriptObjectSystem` after `build()` runs; `null` until then.
+     */
+    this.root = null;
+    this.world = world;
+    this.entityId = entityId;
+    if (data) this.data = data;
+  }
+  /**
+   * 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() {
+    throw new Error("ScriptObject subclasses must implement build()");
+  }
+};
+__name(_ScriptObject, "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.
+ */
+_ScriptObject.__reluScriptObjectClass = true;
+var ScriptObject = _ScriptObject;
+
+// core/systems/ScriptObjectSystem.ts
+var SCRIPT_OBJECT_ROOT_FLAG = "__scriptObjectRoot";
+function setInstanceRef(component, value) {
+  Object.defineProperty(component, "instance", {
+    value,
+    writable: true,
+    configurable: true,
+    enumerable: false
+  });
+}
+__name(setInstanceRef, "setInstanceRef");
+function disposeBuiltObject(root) {
+  root.parent?.remove(root);
+  root.traverse((node) => {
+    const mesh = node;
+    const geometry = mesh.geometry;
+    if (geometry?.dispose && !geometry.userData?.[SHARED_MODEL_RESOURCE_FLAG]) {
+      geometry.dispose();
+    }
+    const material = mesh.material;
+    const materials = Array.isArray(material) ? material : material ? [material] : [];
+    for (const mat of materials) {
+      if (mat.userData?.[SHARED_MODEL_RESOURCE_FLAG]) continue;
+      for (const value of Object.values(mat)) {
+        if (value instanceof THREE7.Texture) value.dispose();
+      }
+      mat.dispose?.();
+    }
+  });
+}
+__name(disposeBuiltObject, "disposeBuiltObject");
+var _ScriptObjectSystem = class _ScriptObjectSystem {
+  constructor(moduleLoader) {
+    this.instances = /* @__PURE__ */ new Map();
+    this.loading = /* @__PURE__ */ new Map();
+    /** Bumped by invalidate*() so in-flight loads that predate it are discarded. */
+    this.epoch = 0;
+    this.moduleLoader = moduleLoader ?? defaultModuleLoader;
+  }
+  update(world, deltaTime) {
+    const active = /* @__PURE__ */ new Map();
+    for (const entityId of world.query(ScriptObjectComponent)) {
+      const component = world.getComponent(entityId, ScriptObjectComponent);
+      if (!component) continue;
+      const wantsRun = component.enabled && typeof component.scriptUrl === "string" && typeof component.className === "string";
+      if (!wantsRun) {
+        const record = this.instances.get(entityId);
+        if (record) this.teardownRecord(world, entityId, record, false);
+        this.loading.delete(entityId);
+        if (component.runtimeState !== "idle") {
+          component.runtimeState = "idle";
+          component.runtimeMessage = void 0;
+        }
+        continue;
+      }
+      active.set(entityId, component);
+    }
+    for (const [entityId, record] of this.instances) {
+      const component = active.get(entityId);
+      const identityChanged = !component || record.scriptUrl !== component.scriptUrl || record.className !== component.className;
+      if (!world.hasEntity(entityId) || identityChanged) {
+        this.teardownRecord(world, entityId, record, false);
+      }
+    }
+    for (const [entityId, component] of active) {
+      const record = this.instances.get(entityId);
+      if (!record || record.status !== "ready" || !record.instance) continue;
+      if (!world.isEntityVisible(entityId)) continue;
+      if (component.data !== record.lastWrittenData) {
+        try {
+          const merged = mergeDataByCurrentDefaults(
+            record.rawData,
+            normalizeScriptData(component.data)
+          );
+          record.rawData = merged;
+          record.instance.data = resolveInputData(world, merged);
+          const stored = serializeDataForStorage(merged, merged);
+          component.data = stored;
+          record.lastWrittenData = stored;
+        } catch (error) {
+          this.markError(world, entityId, component, error);
+          continue;
+        }
+      }
+      try {
+        record.instance.update?.(deltaTime);
+      } catch (error) {
+        this.markError(world, entityId, component, error);
+      }
+    }
+    for (const [entityId, component] of active) {
+      if (this.instances.has(entityId) || this.loading.has(entityId)) continue;
+      const scriptUrl = component.scriptUrl;
+      const className = component.className;
+      if (component.runtimeState !== "loading") {
+        component.runtimeState = "loading";
+        component.runtimeMessage = void 0;
+      }
+      const epochAtStart = this.epoch;
+      const key = `${epochAtStart}:${scriptUrl}:${className}`;
+      const promise = this.loadScriptObject(
+        world,
+        entityId,
+        scriptUrl,
+        className,
+        key,
+        epochAtStart
+      ).catch((error) => {
+        this.markError(world, entityId, void 0, error);
+        console.error(
+          `[ScriptObjectSystem] Failed loading ${className} (${scriptUrl})`,
+          error
+        );
+      }).finally(() => {
+        if (this.loading.get(entityId)?.key === key) {
+          this.loading.delete(entityId);
+        }
+      });
+      this.loading.set(entityId, { key, promise });
+    }
+    for (const entityId of this.loading.keys()) {
+      if (!active.has(entityId)) this.loading.delete(entityId);
+    }
+  }
+  async loadScriptObject(world, entityId, scriptUrl, className, key, epochAtStart) {
+    const moduleValue = await this.moduleLoader(scriptUrl);
+    if (this.loading.get(entityId)?.key !== key || epochAtStart !== this.epoch || !world.hasEntity(entityId)) {
+      return;
+    }
+    const component = world.getComponent(entityId, ScriptObjectComponent);
+    if (!component || !component.enabled || component.scriptUrl !== scriptUrl || component.className !== className) {
+      return;
+    }
+    const ctor = resolveScriptCtor(moduleValue, className, {
+      baseClass: ScriptObject,
+      markerKey: "__reluScriptObjectClass"
+    });
+    if (!ctor) {
+      throw new Error(
+        `Missing ScriptObject export '${className}' in ${scriptUrl}`
+      );
+    }
+    const currentData = normalizeScriptData(component.data);
+    let instance;
+    try {
+      instance = new ctor(world, entityId, void 0);
+    } catch {
+      instance = new ctor(world, entityId, currentData);
+    }
+    const defaults = normalizeScriptData(instance.data);
+    const merged = mergeDataByCurrentDefaults(defaults, currentData);
+    instance.data = resolveInputData(world, merged);
+    const parent = world.getComponent(entityId, Object3DRef)?.object;
+    if (!parent) {
+      throw new Error("Script object entity has no Object3D to attach to.");
+    }
+    for (const child of [...parent.children]) {
+      if (child.userData?.[SCRIPT_OBJECT_ROOT_FLAG]) {
+        disposeBuiltObject(child);
+      }
+    }
+    let built;
+    try {
+      built = instance.build();
+    } catch (error) {
+      try {
+        instance.dispose?.();
+      } catch {
+      }
+      throw error;
+    }
+    if (!built || built.isObject3D !== true) {
+      try {
+        instance.dispose?.();
+      } catch {
+      }
+      throw new Error("build() must return a THREE.Object3D.");
+    }
+    built.userData[SCRIPT_OBJECT_ROOT_FLAG] = true;
+    parent.add(built);
+    instance.root = built;
+    const stored = serializeDataForStorage(merged, merged);
+    component.data = stored;
+    component.runtimeState = "ready";
+    component.runtimeMessage = void 0;
+    setInstanceRef(component, instance);
+    this.instances.set(entityId, {
+      entityId,
+      scriptUrl,
+      className,
+      status: "ready",
+      instance,
+      root: built,
+      rawData: merged,
+      lastWrittenData: stored
+    });
+  }
+  /** Dispose a record's instance + built subtree. `keepTombstone` leaves an error marker. */
+  teardownRecord(world, entityId, record, keepTombstone) {
+    try {
+      record.instance?.dispose?.();
+    } catch {
+    }
+    if (record.root) disposeBuiltObject(record.root);
+    const component = world.getComponent(entityId, ScriptObjectComponent);
+    if (component) setInstanceRef(component, null);
+    if (keepTombstone) {
+      this.instances.set(entityId, {
+        ...record,
+        status: "error",
+        instance: null,
+        root: null
+      });
+    } else {
+      this.instances.delete(entityId);
+    }
+  }
+  markError(world, entityId, component, error) {
+    const comp = component ?? world.getComponent(entityId, ScriptObjectComponent) ?? null;
+    if (comp) {
+      comp.runtimeState = "error";
+      comp.runtimeMessage = toErrorMessage(error);
+    }
+    const record = this.instances.get(entityId);
+    if (record) {
+      this.teardownRecord(world, entityId, record, true);
+    } else {
+      this.instances.set(entityId, {
+        entityId,
+        scriptUrl: comp?.scriptUrl ?? "",
+        className: comp?.className ?? "",
+        status: "error",
+        instance: null,
+        root: null,
+        rawData: {},
+        lastWrittenData: null
+      });
+    }
+  }
+  /** Dispose all live instances so the next update() reloads with fresh modules. */
+  invalidateAll() {
+    this.epoch += 1;
+    for (const [entityId, record] of [...this.instances]) {
+      try {
+        record.instance?.dispose?.();
+      } catch {
+      }
+      if (record.root) disposeBuiltObject(record.root);
+      this.instances.delete(entityId);
+    }
+    this.loading.clear();
+  }
+  /** Invalidate only the entities whose script matches `scriptUrl`. */
+  invalidate(scriptUrl) {
+    this.epoch += 1;
+    for (const [entityId, record] of [...this.instances]) {
+      if (record.scriptUrl !== scriptUrl) continue;
+      try {
+        record.instance?.dispose?.();
+      } catch {
+      }
+      if (record.root) disposeBuiltObject(record.root);
+      this.instances.delete(entityId);
+    }
+    for (const [entityId, entry] of [...this.loading]) {
+      if (entry.key.includes(`:${scriptUrl}:`)) this.loading.delete(entityId);
+    }
+  }
+  dispose(world) {
+    for (const [entityId, record] of [...this.instances]) {
+      this.teardownRecord(world, entityId, record, false);
+    }
+    this.instances.clear();
+    this.loading.clear();
+  }
+};
+__name(_ScriptObjectSystem, "ScriptObjectSystem");
+var ScriptObjectSystem = _ScriptObjectSystem;
+
 // core/systems/TransformSyncSystem.ts
 var _TransformSyncSystem = class _TransformSyncSystem {
   update(world) {
@@ -5282,6 +5801,6 @@ var _VideoSystem = class _VideoSystem {
 __name(_VideoSystem, "VideoSystem");
 var VideoSystem = _VideoSystem;
 
-export { AnimationSystem, AudioSystem, Behaviour, CameraSyncSystem, EnvironmentSyncSystem, HYDRATABLE_ENTITY_KINDS, InputSystem, InstancedMeshSystem, KeyboardKeys, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectVisibilitySystem, PREFAB_FILE_VERSION, PhysicsSyncSystem, PostprocessingSyncSystem, RenderSystem, ScriptBehaviourSystem, TransformSyncSystem, VideoSystem, buildComponentValueMaps, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearPrefabCache, collectDiffPaths, collectEntitySubtree, computeInstanceOverrides, decanonicalizeComponentValue, despawnPrefab, encodeOverride, findSnapshotRootEntityIds, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadPrefab, mergeComponentValue, parseOverride, parsePrefabAsset, restoreComponentState, restorePostCreateComponents, setPrefabAssetUrlResolver, spawnPrefab };
-//# sourceMappingURL=chunk-67MFQDHX.js.map
-//# sourceMappingURL=chunk-67MFQDHX.js.map
+export { ADDED_NODE_MARKER_COMPONENT, AnimationSystem, AudioSystem, Behaviour, CameraSyncSystem, EnvironmentSyncSystem, HYDRATABLE_ENTITY_KINDS, InputSystem, InstancedMeshSystem, KeyboardKeys, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, NODE_KEY_SEPARATOR, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectVisibilitySystem, PREFAB_FILE_VERSION, PREFAB_FILE_VERSION_NESTED, PhysicsSyncSystem, PostprocessingSyncSystem, RenderSystem, SCRIPT_OBJECT_ROOT_FLAG, ScriptBehaviourSystem, ScriptObject, ScriptObjectSystem, TransformSyncSystem, VideoSystem, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearPrefabCache, collectDiffPaths, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, decanonicalizeComponentValue, despawnPrefab, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadPrefab, mergeComponentValue, parseOverride, parsePrefabAsset, prefabFileVersionFor, restoreComponentState, restorePostCreateComponents, setPrefabAssetUrlResolver, spawnPrefab };
+//# sourceMappingURL=chunk-GZ2NKSMV.js.map
+//# sourceMappingURL=chunk-GZ2NKSMV.js.map