@holoscript/engine 6.0.3 → 6.0.4

package/dist/chunk-RNWOZ6WQ.js

@@ -0,0 +1,913 @@
+import {
+  __export
+} from "./chunk-AKLW2MUS.js";
+
+// src/scene/index.ts
+var scene_exports = {};
+__export(scene_exports, {
+  CURRENT_SCHEMA_VERSION: () => CURRENT_SCHEMA_VERSION,
+  ProjectManager: () => ProjectManager,
+  SceneDeserializer: () => SceneDeserializer,
+  SceneManager: () => SceneManager,
+  SceneNode: () => SceneNode,
+  SceneQuery: () => SceneQuery,
+  SceneSerializer: () => SceneSerializer,
+  StateSnapshotCapture: () => StateSnapshotCapture,
+  VersionMigration: () => VersionMigration
+});
+
+// src/scene/ProjectManager.ts
+var ProjectManager = class _ProjectManager {
+  project;
+  constructor(name, version = "1.0.0") {
+    this.project = {
+      name,
+      version,
+      createdAt: Date.now(),
+      modifiedAt: Date.now(),
+      scenes: [],
+      assets: [],
+      buildConfig: {
+        target: "development",
+        optimizeAssets: false,
+        minifyScripts: false,
+        bundleAssets: false,
+        outputDir: "./dist"
+      },
+      settings: {}
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Scene Management
+  // ---------------------------------------------------------------------------
+  addScene(ref) {
+    this.project.scenes.push({ ...ref, lastModified: Date.now() });
+    this.project.modifiedAt = Date.now();
+  }
+  removeScene(sceneId) {
+    const idx = this.project.scenes.findIndex((s) => s.id === sceneId);
+    if (idx < 0) return false;
+    this.project.scenes.splice(idx, 1);
+    for (const asset of this.project.assets) {
+      asset.usedByScenes = asset.usedByScenes.filter((id) => id !== sceneId);
+    }
+    this.project.modifiedAt = Date.now();
+    return true;
+  }
+  getScene(sceneId) {
+    return this.project.scenes.find((s) => s.id === sceneId);
+  }
+  getScenes() {
+    return [...this.project.scenes];
+  }
+  getStartScene() {
+    return this.project.scenes.find((s) => s.isStartScene);
+  }
+  setStartScene(sceneId) {
+    for (const s of this.project.scenes) {
+      s.isStartScene = s.id === sceneId;
+    }
+    return this.project.scenes.some((s) => s.id === sceneId);
+  }
+  // ---------------------------------------------------------------------------
+  // Asset Management
+  // ---------------------------------------------------------------------------
+  addAsset(ref) {
+    this.project.assets.push(ref);
+    this.project.modifiedAt = Date.now();
+  }
+  removeAsset(assetId) {
+    const idx = this.project.assets.findIndex((a) => a.id === assetId);
+    if (idx < 0) return false;
+    this.project.assets.splice(idx, 1);
+    this.project.modifiedAt = Date.now();
+    return true;
+  }
+  getAsset(assetId) {
+    return this.project.assets.find((a) => a.id === assetId);
+  }
+  getAssets() {
+    return [...this.project.assets];
+  }
+  /**
+   * Find unused assets (not referenced by any scene).
+   */
+  findUnusedAssets() {
+    return this.project.assets.filter((a) => a.usedByScenes.length === 0);
+  }
+  /**
+   * Get total project size in bytes.
+   */
+  getTotalAssetSize() {
+    return this.project.assets.reduce((sum, a) => sum + a.sizeBytes, 0);
+  }
+  // ---------------------------------------------------------------------------
+  // Build Config
+  // ---------------------------------------------------------------------------
+  setBuildConfig(config) {
+    Object.assign(this.project.buildConfig, config);
+    this.project.modifiedAt = Date.now();
+  }
+  getBuildConfig() {
+    return { ...this.project.buildConfig };
+  }
+  // ---------------------------------------------------------------------------
+  // Settings
+  // ---------------------------------------------------------------------------
+  setSetting(key, value) {
+    this.project.settings[key] = value;
+    this.project.modifiedAt = Date.now();
+  }
+  getSetting(key) {
+    return this.project.settings[key];
+  }
+  // ---------------------------------------------------------------------------
+  // Serialization
+  // ---------------------------------------------------------------------------
+  serialize() {
+    return JSON.stringify(this.project, null, 2);
+  }
+  static deserialize(json) {
+    const data = JSON.parse(json);
+    const pm = new _ProjectManager(data.name, data.version);
+    pm.project = data;
+    return pm;
+  }
+  getProjectFile() {
+    return { ...this.project };
+  }
+};
+
+// src/scene/SceneDeserializer.ts
+var SceneDeserializer = class {
+  /**
+   * Deserialize from a SerializedScene object.
+   */
+  deserialize(scene) {
+    return this.rebuildNode(scene.root);
+  }
+  /**
+   * Deserialize from a JSON string.
+   */
+  fromJSON(json) {
+    const scene = JSON.parse(json);
+    if (scene.version !== 1) {
+      console.warn(`Unknown version ${scene.version}, attempting load`);
+    }
+    return {
+      node: this.rebuildNode(scene.root),
+      name: scene.name,
+      metadata: scene.metadata
+    };
+  }
+  rebuildNode(serialized) {
+    if (serialized.type === "ref") {
+      return {
+        id: serialized.id,
+        type: "entity",
+        properties: { _isRef: true },
+        traits: /* @__PURE__ */ new Map(),
+        children: []
+      };
+    }
+    const traits = /* @__PURE__ */ new Map();
+    if (serialized.traits) {
+      for (const [key, value] of Object.entries(serialized.traits)) {
+        traits.set(key, value);
+      }
+    }
+    const children = (serialized.children || []).map((child) => this.rebuildNode(child));
+    return {
+      id: serialized.id,
+      type: serialized.type,
+      properties: { ...serialized.properties },
+      traits,
+      children
+    };
+  }
+};
+
+// src/scene/SceneSerializer.ts
+var SceneSerializer = class {
+  world;
+  visitedIds = /* @__PURE__ */ new Set();
+  constructor(world) {
+    this.world = world;
+  }
+  /**
+   * Serialize a scene.
+   * Overload 1: serialize(root: HSPlusNode, name?, metadata?) — from node tree
+   * Overload 2: serialize(name?, metadata?) — from World entities
+   */
+  serialize(rootOrName, sceneNameOrMeta, metadata) {
+    if (rootOrName && typeof rootOrName === "object" && "type" in rootOrName) {
+      const root = rootOrName;
+      const sceneName2 = typeof sceneNameOrMeta === "string" ? sceneNameOrMeta : "untitled";
+      const meta2 = typeof sceneNameOrMeta === "string" ? metadata : sceneNameOrMeta;
+      return this.serializeFromNode(root, sceneName2, meta2);
+    }
+    const sceneName = typeof rootOrName === "string" ? rootOrName : "untitled";
+    const meta = typeof sceneNameOrMeta === "object" ? sceneNameOrMeta : metadata;
+    if (!this.world) {
+      return {
+        version: 1,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        name: sceneName,
+        root: { id: "scene_root", type: "root", properties: {}, traits: {}, children: [] },
+        metadata: meta
+      };
+    }
+    const entities = this.world.getAllEntities();
+    const childEntities = /* @__PURE__ */ new Set();
+    entities.forEach((e) => {
+      const t = this.world.getComponent(e, "Transform");
+      if (t && t.parent !== void 0) childEntities.add(e);
+    });
+    const roots = entities.filter((e) => !childEntities.has(e));
+    const validRoots = roots.filter(
+      (e) => !this.world.hasTag(e, "NoSelect") && !this.world.hasTag(e, "Gizmo")
+    );
+    const serializedRoots = validRoots.map((e) => this.serializeEntity(e));
+    return {
+      version: 1,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      name: sceneName,
+      root: {
+        id: "scene_root",
+        type: "root",
+        properties: {},
+        traits: {},
+        children: serializedRoots
+      },
+      metadata: meta
+    };
+  }
+  /**
+   * Node-based serialization helper.
+   */
+  serializeFromNode(root, sceneName, metadata) {
+    this.visitedIds.clear();
+    return {
+      version: 1,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      name: sceneName,
+      root: this.serializeNode(root),
+      metadata
+    };
+  }
+  serializeEntity(entity) {
+    const id = `e_${entity}`;
+    const properties = {};
+    const traits = {};
+    const compTypes = this.world.getComponentTypes(entity);
+    compTypes.forEach((type) => {
+      const data = this.world.getComponent(entity, type);
+      if (!data) return;
+      if (type === "Transform") {
+        const pos = data.position || { x: data.x || 0, y: data.y || 0, z: data.z || 0 };
+        const rot = data.rotation || {
+          x: data.rx || 0,
+          y: data.ry || 0,
+          z: data.rz || 0,
+          w: data.rw || 1
+        };
+        const scl = data.scale || { x: data.sx || 1, y: data.sy || 1, z: data.sz || 1 };
+        properties.position = pos;
+        properties.rotation = rot;
+        properties.scale = scl;
+      } else if (type === "Text") {
+        properties.text = data.content;
+      } else if (type === "Render") {
+        traits["render"] = data;
+      } else if (type === "Collider") {
+        traits["collider"] = data;
+      } else if (type === "Pressable") {
+        traits["pressable"] = data;
+      } else {
+        const traitName = type.charAt(0).toLowerCase() + type.slice(1);
+        traits[traitName] = data;
+      }
+    });
+    const children = [];
+    const all = this.world.getAllEntities();
+    all.forEach((other) => {
+      const t = this.world.getComponent(other, "Transform");
+      if (t && t.parent === entity) {
+        if (!this.world.hasTag(other, "NoSelect")) {
+          children.push(this.serializeEntity(other));
+        }
+      }
+    });
+    return {
+      id,
+      type: "entity",
+      properties: this.sanitizeProperties(properties),
+      traits: this.sanitizeValue(traits),
+      children
+    };
+  }
+  /**
+   * Legacy/Utility: Serialize a HSPlusNode tree
+   */
+  serializeNode(node) {
+    const id = node.id || "unknown";
+    if (this.visitedIds.has(id)) {
+      return { id, type: "ref", properties: {}, traits: {}, children: [] };
+    }
+    this.visitedIds.add(id);
+    const traits = {};
+    if (node.traits instanceof Map) {
+      for (const [key, value] of node.traits) {
+        traits[key] = this.sanitizeValue(value);
+      }
+    } else if (node.traits && typeof node.traits === "object") {
+      for (const [key, value] of Object.entries(node.traits)) {
+        traits[key] = this.sanitizeValue(value);
+      }
+    }
+    const properties = this.sanitizeProperties(node.properties || {});
+    const children = (node.children || []).map((child) => this.serializeNode(child));
+    return { id, type: node.type || "entity", properties, traits, children };
+  }
+  /**
+   * Serialize a node tree to a JSON string.
+   */
+  toJSON(root, sceneName = "untitled") {
+    const scene = this.serializeFromNode(root, sceneName);
+    return JSON.stringify(scene, null, 2);
+  }
+  sanitizeProperties(props) {
+    const result = {};
+    for (const [key, value] of Object.entries(props)) {
+      if (key.startsWith("_")) continue;
+      if (key === "__holo_id") continue;
+      result[key] = this.sanitizeValue(value);
+    }
+    return result;
+  }
+  sanitizeValue(value) {
+    if (value === null || value === void 0) return value;
+    if (typeof value === "function") return void 0;
+    if (value instanceof Map) {
+      const obj = {};
+      for (const [k, v] of value) {
+        obj[String(k)] = this.sanitizeValue(v);
+      }
+      return obj;
+    }
+    if (value instanceof Set) {
+      return Array.from(value).map((v) => this.sanitizeValue(v));
+    }
+    if (Array.isArray(value)) {
+      return value.map((v) => this.sanitizeValue(v));
+    }
+    if (typeof value === "object") {
+      const result = {};
+      for (const [k, v] of Object.entries(value)) {
+        if (k.startsWith("_")) continue;
+        const sanitized = this.sanitizeValue(v);
+        if (sanitized !== void 0) {
+          result[k] = sanitized;
+        }
+      }
+      return result;
+    }
+    return value;
+  }
+};
+
+// src/scene/StateSnapshot.ts
+var StateSnapshotCapture = class {
+  /**
+   * Create a snapshot of the current runtime state.
+   * Subsystem references are passed in to avoid coupling.
+   */
+  capture(options) {
+    const { animationEngine, particleSystems, keyboardSystem, scrollOffsets, custom } = options;
+    return {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      animation: {
+        activeClipIds: animationEngine?.getActiveIds() || [],
+        springValues: {}
+      },
+      particles: (particleSystems || []).map((ps) => ({
+        emitterId: ps.id,
+        isEmitting: ps.isEmitting(),
+        activeCount: ps.getActiveCount()
+      })),
+      ui: {
+        focusedInputId: keyboardSystem?.focusedInputId || null,
+        cursorIndex: keyboardSystem?.cursorIndex || 0,
+        scrollOffsets: scrollOffsets || {}
+      },
+      custom: custom || {}
+    };
+  }
+};
+
+// src/scene/SceneManager.ts
+var SceneManager = class {
+  serializer = new SceneSerializer();
+  deserializer = new SceneDeserializer();
+  stateCapture = new StateSnapshotCapture();
+  storage = /* @__PURE__ */ new Map();
+  /**
+   * Save a scene to the internal store.
+   */
+  save(name, root, stateOptions, metadata) {
+    const scene = this.serializer.serialize(root, name, metadata);
+    const state = stateOptions ? this.stateCapture.capture(stateOptions) : void 0;
+    const saved = { scene, state };
+    this.storage.set(name, saved);
+    return saved;
+  }
+  /**
+   * Load a scene by name.
+   */
+  load(name) {
+    const saved = this.storage.get(name);
+    if (!saved) return null;
+    const node = this.deserializer.deserialize(saved.scene);
+    return { node, state: saved.state };
+  }
+  /**
+   * Check if a scene exists.
+   */
+  has(name) {
+    return this.storage.has(name);
+  }
+  /**
+   * Delete a saved scene.
+   */
+  delete(name) {
+    return this.storage.delete(name);
+  }
+  /**
+   * List all saved scenes.
+   */
+  list() {
+    const entries = [];
+    for (const [name, saved] of this.storage) {
+      entries.push({
+        name,
+        timestamp: saved.scene.timestamp,
+        nodeCount: this.countNodes(saved.scene.root)
+      });
+    }
+    return entries;
+  }
+  /**
+   * Export a scene to JSON string.
+   */
+  exportJSON(name) {
+    const saved = this.storage.get(name);
+    if (!saved) return null;
+    return JSON.stringify(saved, null, 2);
+  }
+  /**
+   * Import a scene from JSON string.
+   */
+  importJSON(json) {
+    const saved = JSON.parse(json);
+    const name = saved.scene.name;
+    this.storage.set(name, saved);
+    return name;
+  }
+  /**
+   * Get count of saved scenes.
+   */
+  get count() {
+    return this.storage.size;
+  }
+  countNodes(node) {
+    let count = 1;
+    if (node.children) {
+      for (const child of node.children) {
+        count += this.countNodes(child);
+      }
+    }
+    return count;
+  }
+};
+
+// src/scene/SceneNode.ts
+var SceneNode = class {
+  id;
+  name;
+  tags = /* @__PURE__ */ new Set();
+  layer = 0;
+  visible = true;
+  local;
+  worldMatrix;
+  dirty = true;
+  parent = null;
+  children = [];
+  constructor(id, name = "") {
+    this.id = id;
+    this.name = name || id;
+    this.local = {
+      position: [0, 0, 0],
+      rotation: { x: 0, y: 0, z: 0 },
+      scale: { x: 1, y: 1, z: 1 }
+    };
+    this.worldMatrix = new Float64Array(16);
+    this.setIdentity(this.worldMatrix);
+  }
+  // ---------------------------------------------------------------------------
+  // Transform
+  // ---------------------------------------------------------------------------
+  setPosition(x, y, z) {
+    this.local.position = [x, y, z];
+    this.markDirty();
+  }
+  setRotation(x, y, z) {
+    this.local.rotation = { x, y, z };
+    this.markDirty();
+  }
+  setScale(x, y, z) {
+    this.local.scale = { x, y, z };
+    this.markDirty();
+  }
+  getLocalTransform() {
+    return {
+      ...this.local,
+      position: { ...this.local.position },
+      rotation: { ...this.local.rotation },
+      scale: { ...this.local.scale }
+    };
+  }
+  getWorldPosition() {
+    this.updateWorldMatrix();
+    return { x: this.worldMatrix[12], y: this.worldMatrix[13], z: this.worldMatrix[14] };
+  }
+  getWorldMatrix() {
+    this.updateWorldMatrix();
+    return new Float64Array(this.worldMatrix);
+  }
+  // ---------------------------------------------------------------------------
+  // Hierarchy
+  // ---------------------------------------------------------------------------
+  addChild(child) {
+    if (child.parent) child.parent.removeChild(child);
+    child.parent = this;
+    this.children.push(child);
+    child.markDirty();
+  }
+  removeChild(child) {
+    const idx = this.children.indexOf(child);
+    if (idx >= 0) {
+      this.children.splice(idx, 1);
+      child.parent = null;
+      child.markDirty();
+    }
+  }
+  getParent() {
+    return this.parent;
+  }
+  getChildren() {
+    return [...this.children];
+  }
+  getChildCount() {
+    return this.children.length;
+  }
+  // Depth-first traversal
+  traverse(callback, depth = 0) {
+    callback(this, depth);
+    for (const child of this.children) child.traverse(callback, depth + 1);
+  }
+  // ---------------------------------------------------------------------------
+  // Dirty Propagation & World Matrix
+  // ---------------------------------------------------------------------------
+  markDirty() {
+    this.dirty = true;
+    for (const child of this.children) child.markDirty();
+  }
+  updateWorldMatrix() {
+    if (!this.dirty) return;
+    const localMat = this.computeLocalMatrix();
+    if (this.parent) {
+      this.parent.updateWorldMatrix();
+      this.multiply(this.parent.worldMatrix, localMat, this.worldMatrix);
+    } else {
+      this.worldMatrix.set(localMat);
+    }
+    this.dirty = false;
+  }
+  computeLocalMatrix() {
+    const m = new Float64Array(16);
+    const { position: p, rotation: r, scale: s } = this.local;
+    const cx = Math.cos(r.x), sx = Math.sin(r.x);
+    const cy = Math.cos(r.y), sy = Math.sin(r.y);
+    const cz = Math.cos(r.z), sz = Math.sin(r.z);
+    m[0] = (cy * cz + sy * sx * sz) * s.x;
+    m[1] = cx * sz;
+    m[2] = (-sy * cz + cy * sx * sz) * s.x;
+    m[3] = 0;
+    m[4] = (cy * -sz + sy * sx * cz) * s.y;
+    m[5] = cx * cz;
+    m[6] = (sy * sz + cy * sx * cz) * s.y;
+    m[7] = 0;
+    m[8] = sy * cx * s.z;
+    m[9] = -sx;
+    m[10] = cy * cx * s.z;
+    m[11] = 0;
+    m[12] = p[0];
+    m[13] = p[1];
+    m[14] = p[2];
+    m[15] = 1;
+    return m;
+  }
+  // ---------------------------------------------------------------------------
+  // Matrix Math Helpers
+  // ---------------------------------------------------------------------------
+  setIdentity(m) {
+    m.fill(0);
+    m[0] = 1;
+    m[5] = 1;
+    m[10] = 1;
+    m[15] = 1;
+  }
+  multiply(a, b, out) {
+    for (let col = 0; col < 4; col++) {
+      for (let row = 0; row < 4; row++) {
+        out[col * 4 + row] = a[row] * b[col * 4] + a[4 + row] * b[col * 4 + 1] + a[8 + row] * b[col * 4 + 2] + a[12 + row] * b[col * 4 + 3];
+      }
+    }
+  }
+  isDirty() {
+    return this.dirty;
+  }
+};
+
+// src/scene/SceneQuery.ts
+var SceneQuery = class _SceneQuery {
+  // ---------------------------------------------------------------------------
+  // Tag/Layer Filtering
+  // ---------------------------------------------------------------------------
+  static findByTag(root, tag) {
+    const results = [];
+    root.traverse((node) => {
+      if (node.tags.has(tag)) results.push(node);
+    });
+    return results;
+  }
+  static findByLayer(root, layer) {
+    const results = [];
+    root.traverse((node) => {
+      if (node.layer === layer) results.push(node);
+    });
+    return results;
+  }
+  static findByName(root, name) {
+    let found = null;
+    root.traverse((node) => {
+      if (node.name === name) found = node;
+    });
+    return found;
+  }
+  // ---------------------------------------------------------------------------
+  // Spatial Queries
+  // ---------------------------------------------------------------------------
+  static findInRadius(root, center, radius) {
+    const results = [];
+    root.traverse((node) => {
+      const wp = node.getWorldPosition();
+      const dx = wp.x - center.x, dy = wp.y - center.y, dz = wp.z - center.z;
+      if (Math.sqrt(dx * dx + dy * dy + dz * dz) <= radius) results.push(node);
+    });
+    return results;
+  }
+  // ---------------------------------------------------------------------------
+  // Frustum Culling (simplified cone check)
+  // ---------------------------------------------------------------------------
+  static frustumCull(root, frustum) {
+    const results = [];
+    const dir = _SceneQuery.normalize(frustum.direction);
+    const halfFovRad = frustum.fov / 2 * Math.PI / 180;
+    const cosHalfFov = Math.cos(halfFovRad);
+    root.traverse((node) => {
+      if (!node.visible) return;
+      const wp = node.getWorldPosition();
+      const dx = wp[0] - frustum.position[0];
+      const dy = wp[1] - frustum.position[1];
+      const dz = wp[2] - frustum.position[2];
+      const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+      if (dist < frustum.near || dist > frustum.far) return;
+      if (dist > 0) {
+        const dot = (dx * dir.x + dy * dir.y + dz * dir.z) / dist;
+        if (dot >= cosHalfFov) results.push(node);
+      }
+    });
+    return results;
+  }
+  // ---------------------------------------------------------------------------
+  // Visitor Pattern
+  // ---------------------------------------------------------------------------
+  static visit(root, visitor) {
+    const queue = [root];
+    while (queue.length > 0) {
+      const node = queue.shift();
+      const cont = visitor(node);
+      if (cont === false) return;
+      queue.push(...node.getChildren());
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------
+  static normalize(v) {
+    const len = Math.sqrt(v.x * v.x + v.y * v.y + v.z * v.z) || 1;
+    return { x: v.x / len, y: v.y / len, z: v.z / len };
+  }
+};
+
+// src/scene/VersionMigration.ts
+var CURRENT_SCHEMA_VERSION = 5;
+var VersionMigration = class {
+  migrations = [];
+  logs = [];
+  constructor() {
+    this.registerBuiltIns();
+  }
+  // ---------------------------------------------------------------------------
+  // Migration Registration
+  // ---------------------------------------------------------------------------
+  register(step) {
+    this.migrations.push(step);
+    this.migrations.sort((a, b) => a.fromVersion - b.fromVersion);
+  }
+  getMigrations() {
+    return [...this.migrations];
+  }
+  getMigrationCount() {
+    return this.migrations.length;
+  }
+  // ---------------------------------------------------------------------------
+  // Migration Execution
+  // ---------------------------------------------------------------------------
+  /**
+   * Migrate data from its current version to the target version.
+   */
+  migrate(data, targetVersion = CURRENT_SCHEMA_VERSION) {
+    const currentVersion = data.version ?? 0;
+    const stepsApplied = [];
+    const warnings = [];
+    if (currentVersion >= targetVersion) {
+      return {
+        success: true,
+        fromVersion: currentVersion,
+        toVersion: currentVersion,
+        stepsApplied,
+        warnings,
+        data
+      };
+    }
+    let workingData = { ...data };
+    let version = currentVersion;
+    while (version < targetVersion) {
+      const step = this.migrations.find((m) => m.fromVersion === version);
+      if (!step) {
+        warnings.push(`No migration step from v${version}, attempting skip to v${version + 1}`);
+        version++;
+        continue;
+      }
+      try {
+        workingData = step.migrate(workingData);
+        stepsApplied.push(step.name);
+        version = step.toVersion;
+        workingData.version = version;
+      } catch (err) {
+        return {
+          success: false,
+          fromVersion: currentVersion,
+          toVersion: version,
+          stepsApplied,
+          warnings: [
+            ...warnings,
+            `Migration failed at step "${step.name}": ${err.message}`
+          ],
+          data: workingData
+        };
+      }
+    }
+    this.logs.push({
+      timestamp: Date.now(),
+      fromVersion: currentVersion,
+      toVersion: targetVersion,
+      stepsApplied,
+      dataHash: this.simpleHash(JSON.stringify(workingData))
+    });
+    return {
+      success: true,
+      fromVersion: currentVersion,
+      toVersion: targetVersion,
+      stepsApplied,
+      warnings,
+      data: workingData
+    };
+  }
+  /**
+   * Check if data needs migration.
+   */
+  needsMigration(data) {
+    const version = data.version ?? 0;
+    return version < CURRENT_SCHEMA_VERSION;
+  }
+  /**
+   * Get the version of the given data.
+   */
+  getDataVersion(data) {
+    return data.version ?? 0;
+  }
+  // ---------------------------------------------------------------------------
+  // Logs
+  // ---------------------------------------------------------------------------
+  getLogs() {
+    return [...this.logs];
+  }
+  clearLogs() {
+    this.logs = [];
+  }
+  // ---------------------------------------------------------------------------
+  // Built-in migrations
+  // ---------------------------------------------------------------------------
+  registerBuiltIns() {
+    this.register({
+      fromVersion: 0,
+      toVersion: 1,
+      name: "add_metadata",
+      migrate: (data) => ({
+        ...data,
+        metadata: data.metadata ?? {}
+      })
+    });
+    this.register({
+      fromVersion: 1,
+      toVersion: 2,
+      name: "normalize_entity_ids",
+      migrate: (data) => {
+        const entities = data.entities ?? [];
+        for (const e of entities) {
+          e.id = String(e.id);
+        }
+        return { ...data, entities };
+      }
+    });
+    this.register({
+      fromVersion: 2,
+      toVersion: 3,
+      name: "add_entity_active_flag",
+      migrate: (data) => {
+        const entities = data.entities ?? [];
+        for (const e of entities) {
+          if (e.active === void 0) e.active = true;
+        }
+        return { ...data, entities };
+      }
+    });
+    this.register({
+      fromVersion: 3,
+      toVersion: 4,
+      name: "add_globals",
+      migrate: (data) => ({
+        ...data,
+        globals: data.globals ?? {}
+      })
+    });
+    this.register({
+      fromVersion: 4,
+      toVersion: 5,
+      name: "add_entity_tags",
+      migrate: (data) => {
+        const entities = data.entities ?? [];
+        for (const e of entities) {
+          if (!Array.isArray(e.tags)) e.tags = [];
+        }
+        return { ...data, entities };
+      }
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------
+  simpleHash(str) {
+    let h = 0;
+    for (let i = 0; i < str.length; i++) {
+      h = (h << 5) - h + str.charCodeAt(i) | 0;
+    }
+    return Math.abs(h).toString(16);
+  }
+};
+
+export {
+  ProjectManager,
+  SceneDeserializer,
+  SceneSerializer,
+  StateSnapshotCapture,
+  SceneManager,
+  SceneNode,
+  SceneQuery,
+  CURRENT_SCHEMA_VERSION,
+  VersionMigration,
+  scene_exports
+};