@unseenco/theatre-core 0.1.9 → 0.1.10

package/README.md

@@ -40,6 +40,34 @@ Join us on [Discord](https://discord.gg/bm9f8F9Y9N), follow the updates on [twit
 
 Theatre.js comes in two packages: `@unseenco/theatre-core` (the library) and `@unseenco/theatre-studio` (the editor). This package is the core library.
 
+### Listing and unloading sheets / objects
+
+Runtime helpers for tearing down loaded sheets and objects (for example when switching scenes). These drop in-memory instances so Studio stops showing them, but **do not** clear persisted project state. Recreating the same `sheetId` / object `key` restores prior prop overrides and sequence data.
+
+```ts
+import {getProject} from '@unseenco/theatre-core'
+
+const project = getProject('My project')
+const sheet = project.sheet('Scene')
+sheet.object('Box', {x: 0, y: 0})
+
+// List what is currently loaded
+project.getSheets() // ISheet[]
+sheet.getObjects() // ISheetObject[]
+
+// Detach one object (sheet stays loaded)
+sheet.detachObject('Box')
+
+// Unload this sheet instance (all of its objects, then the sheet)
+sheet.unload()
+
+// Or from the project:
+project.unloadSheet('Scene') // optional second arg: instanceId
+project.unloadSheets() // unload every loaded sheet
+```
+
+Try the interactive demo in the playground: `/shared/unload-sheets/`.
+
 ## Bundle size
 
 `@unseenco/theatre-core` is currently around 20KiB compressed with all its dependencies.

package/dist/index.js

@@ -6520,6 +6520,12 @@ var TheatreSheet = class {
     }
     internal2.deleteObject(sanitizedPath);
   }
+  getObjects() {
+    return privateAPI(this).getObjects().map((obj) => obj.publicApi);
+  }
+  unload() {
+    privateAPI(this).unload();
+  }
   declareOutlineNamespace(namespacePath, opts) {
     const internal2 = privateAPI(this);
     const parsedPath = parseOutlineNamespacePath(
@@ -6607,12 +6613,36 @@ var Sheet = class {
   getObject(key) {
     return this._objects.get()[key];
   }
+  getObjects() {
+    return Object.values(this._objects.get()).filter(
+      (obj) => !!obj
+    );
+  }
   deleteObject(objectKey) {
+    const obj = this._objects.get()[objectKey];
     this._objects.reduce((state) => {
       const newState = { ...state };
       delete newState[objectKey];
       return newState;
     });
+    if (obj) {
+      this.project._remoteSync.unregisterObject(obj);
+    }
+  }
+  /**
+   * Runtime-only teardown: pause sequences, detach all objects, and remove
+   * this sheet instance from the project. Persisted state is kept.
+   */
+  unload() {
+    for (const sequence of Object.values(this._sequences)) {
+      sequence.pause();
+    }
+    for (const objectKey of Object.keys(
+      this._objects.get()
+    )) {
+      this.deleteObject(objectKey);
+    }
+    this.project._unloadSheetInstance(this);
   }
   getSequence(variant) {
     const variantId = variant ?? (0, import_theatre_dataverse15.val)(this._activeSequenceVariant.pointer);
@@ -6707,6 +6737,21 @@ var SheetTemplate = class {
     }
     return inst;
   }
+  getInstances() {
+    return Object.values(this._instances.get()).filter(
+      (inst) => !!inst
+    );
+  }
+  hasInstance(instanceId) {
+    return !!this._instances.get()[instanceId];
+  }
+  removeInstance(instanceId) {
+    this._instances.reduce((state) => {
+      const next = { ...state };
+      delete next[instanceId];
+      return next;
+    });
+  }
   getObjectTemplate(objectKey, nativeObject, config, actions, transient, staticPropPaths) {
     let template = this._objectTemplates.get()[objectKey];
     if (!template) {
@@ -7240,6 +7285,7 @@ var RemoteSync = class {
     __publicField(this, "channel");
     __publicField(this, "sheets", /* @__PURE__ */ new Map());
     __publicField(this, "objects", /* @__PURE__ */ new Map());
+    __publicField(this, "objectUnsubs", /* @__PURE__ */ new Map());
     __publicField(this, "studio");
     __publicField(this, "activeSheet");
     if (typeof BroadcastChannel === "undefined")
@@ -7277,12 +7323,26 @@ var RemoteSync = class {
   registerSheet(sheet) {
     this.sheets.set(sheet.address.sheetId, sheet);
   }
+  /**
+   * Removes `sheet` from the sync map if it is the currently registered
+   * instance for its `sheetId`. Returns whether it was removed.
+   */
+  unregisterSheet(sheet) {
+    if (this.sheets.get(sheet.address.sheetId) !== sheet) {
+      return false;
+    }
+    this.sheets.delete(sheet.address.sheetId);
+    if (this.activeSheet === sheet) {
+      this.activeSheet = void 0;
+    }
+    return true;
+  }
   registerObject(obj) {
     const id = "".concat(obj.address.sheetId, "_").concat(obj.address.objectKey);
     this.objects.set(id, obj);
     if (this.isEditor && this.channel) {
       const channel = this.channel;
-      obj.onFinalValueChange((values) => {
+      const unsubscribe = obj.onFinalValueChange((values) => {
         const message = {
           event: "updateSheetObject",
           // Some prop values (e.g. rgba colors) are class instances with
@@ -7293,6 +7353,16 @@ var RemoteSync = class {
         };
         channel.postMessage(message);
       });
+      this.objectUnsubs.set(id, unsubscribe);
+    }
+  }
+  unregisterObject(obj) {
+    const id = "".concat(obj.address.sheetId, "_").concat(obj.address.objectKey);
+    this.objects.delete(id);
+    const unsubscribe = this.objectUnsubs.get(id);
+    if (unsubscribe) {
+      unsubscribe();
+      this.objectUnsubs.delete(id);
     }
   }
   attachStudio(studio) {
@@ -7630,6 +7700,61 @@ var Project = class {
     this._remoteSync.registerSheet(sheet);
     return sheet;
   }
+  getSheets() {
+    const sheets = [];
+    for (const template of Object.values(this._sheetTemplates.get())) {
+      if (!template)
+        continue;
+      sheets.push(...template.getInstances());
+    }
+    return sheets;
+  }
+  /**
+   * Runtime-only: unload one or all instances of a sheet. Persisted state is kept.
+   * When `instanceId` is omitted, all loaded instances of `sheetId` are unloaded.
+   */
+  unloadSheet(sheetId, instanceId) {
+    const template = this._sheetTemplates.get()[sheetId];
+    if (!template) {
+      return false;
+    }
+    const instances = instanceId ? template.hasInstance(instanceId) ? [template.getInstance(instanceId)] : [] : template.getInstances();
+    if (instances.length === 0) {
+      return false;
+    }
+    for (const sheet of instances) {
+      sheet.unload();
+    }
+    return true;
+  }
+  unloadSheets() {
+    for (const sheet of this.getSheets()) {
+      sheet.unload();
+    }
+  }
+  /**
+   * Called by {@link Sheet.unload} after objects are detached. Removes the
+   * instance from its template and drops the template when no instances remain.
+   */
+  _unloadSheetInstance(sheet) {
+    const sheetId = sheet.address.sheetId;
+    const template = this._sheetTemplates.get()[sheetId];
+    if (!template || !template.hasInstance(sheet.instanceId)) {
+      return;
+    }
+    template.removeInstance(sheet.instanceId);
+    const wasRegistered = this._remoteSync.unregisterSheet(sheet);
+    const remaining = template.getInstances();
+    if (remaining.length === 0) {
+      this._sheetTemplates.reduce((state) => {
+        const next = { ...state };
+        delete next[sheetId];
+        return next;
+      });
+    } else if (wasRegistered) {
+      this._remoteSync.registerSheet(remaining[0]);
+    }
+  }
   _commitOutlineNamespaceConfig(sheetId, namespacePathKey, config) {
     this._mutateCoreAhistoric((ahistoric) => {
       var _a;
@@ -7890,6 +8015,43 @@ var TheatreProject = class {
       sheetOpts
     ).publicApi;
   }
+  getSheets() {
+    return privateAPI(this).getSheets().map((sheet) => sheet.publicApi);
+  }
+  unloadSheet(sheetId, instanceId) {
+    const sanitizedPath = validateAndSanitiseSlashedPathOrThrow(
+      sheetId,
+      "project.unloadSheet"
+    );
+    let sanitizedInstanceId;
+    if (instanceId !== void 0) {
+      if (process.env.NODE_ENV !== "production") {
+        validateInstanceId(
+          instanceId,
+          "instanceId in project.unloadSheet(sheetId, instanceId)",
+          true
+        );
+      }
+      sanitizedInstanceId = instanceId;
+    }
+    const unloaded = privateAPI(this).unloadSheet(
+      sanitizedPath,
+      sanitizedInstanceId
+    );
+    if (!unloaded) {
+      const instanceHint = instanceId !== void 0 ? ' (instance "'.concat(instanceId, '")') : "";
+      notify.warning(
+        "Couldn't unload sheet \"".concat(sanitizedPath, '"').concat(instanceHint),
+        'There is no loaded sheet with id "'.concat(sanitizedPath, '"').concat(instanceHint, ".\n\nTo fix this, make sure you are calling `project.unloadSheet` with a sheet that was previously created via `project.sheet(...)`.")
+      );
+      console.warn(
+        'Sheet "'.concat(sanitizedPath, '"').concat(instanceHint, " is not currently loaded.")
+      );
+    }
+  }
+  unloadSheets() {
+    privateAPI(this).unloadSheets();
+  }
 };
 
 // core/src/coreExports.ts
@@ -7990,7 +8152,7 @@ var CoreBundle = class {
     return "Theatre_CoreBundle";
   }
   get version() {
-    return "0.1.9";
+    return "0.1.10";
   }
   getBitsForStudio(studio, callback) {
     if (this._studio) {