@unseenco/theatre-core 0.1.2 → 0.1.4

package/dist/index.js

@@ -9,6 +9,11 @@ var __getOwnPropSymbols = Object.getOwnPropertySymbols;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __knownSymbol = (name, symbol) => {
+  if (symbol = Symbol[name])
+    return symbol;
+  throw Error("Symbol." + name + " is not defined");
+};
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __spreadValues = (a2, b2) => {
   for (var prop in b2 || (b2 = {}))
@@ -50,6 +55,43 @@ var __publicField = (obj, key, value) => {
   __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
+var __await = function(promise, isYieldStar) {
+  this[0] = promise;
+  this[1] = isYieldStar;
+};
+var __yieldStar = (value) => {
+  var obj = value[__knownSymbol("asyncIterator")];
+  var isAwait = false;
+  var method;
+  var it = {};
+  if (obj == null) {
+    obj = value[__knownSymbol("iterator")]();
+    method = (k2) => it[k2] = (x2) => obj[k2](x2);
+  } else {
+    obj = obj.call(value);
+    method = (k2) => it[k2] = (v2) => {
+      if (isAwait) {
+        isAwait = false;
+        if (k2 === "throw")
+          throw v2;
+        return v2;
+      }
+      isAwait = true;
+      return {
+        done: false,
+        value: new __await(new Promise((resolve) => {
+          var x2 = obj[k2](v2);
+          if (!(x2 instanceof Object))
+            throw TypeError("Object expected");
+          resolve(x2);
+        }), 1)
+      };
+    };
+  }
+  return it[__knownSymbol("iterator")] = () => it, method("next"), "throw" in obj ? method("throw") : it.throw = (x2) => {
+    throw x2;
+  }, "return" in obj && method("return"), it;
+};
 
 // ../node_modules/timing-function/lib/UnitBezier.js
 var require_UnitBezier = __commonJS({
@@ -272,11 +314,12 @@ var src_exports = {};
 __export(src_exports, {
   createRafDriver: () => createRafDriver,
   getProject: () => getProject,
+  isRemoteEditorWindow: () => isRemoteEditorWindow,
   notify: () => notify,
   onChange: () => onChange,
   setCoreRafDriver: () => setCoreRafDriver,
   types: () => propTypes_exports,
-  val: () => val9
+  val: () => val10
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -285,11 +328,12 @@ var coreExports_exports = {};
 __export(coreExports_exports, {
   createRafDriver: () => createRafDriver,
   getProject: () => getProject,
+  isRemoteEditorWindow: () => isRemoteEditorWindow,
   notify: () => notify,
   onChange: () => onChange,
   setCoreRafDriver: () => setCoreRafDriver,
   types: () => propTypes_exports,
-  val: () => val9
+  val: () => val10
 });
 
 // core/src/projects/projectsSingleton.ts
@@ -3154,8 +3198,8 @@ var TheatreSheetObject = class {
     }
     return der.getValue();
   }
-  set initialValue(val10) {
-    privateAPI(this).setInitialValue(val10);
+  set initialValue(val11) {
+    privateAPI(this).setInitialValue(val11);
   }
 };
 
@@ -3170,6 +3214,192 @@ function memoizeFn(producer) {
   };
 }
 
+// shared/src/utils/addresses.ts
+var encodePathToProp = memoizeFn(
+  (p2) => (
+    // we're using JSON.stringify here, but we could use a faster alternative.
+    // If you happen to do that, first make sure no `PathToProp_Encoded` is ever
+    // used in the store, otherwise you'll have to write a migration.
+    JSON.stringify(p2)
+  )
+);
+
+// shared/src/utils/removePathFromObject.ts
+function removePathFromObject(base, path) {
+  if (typeof base !== "object" || base === null)
+    return;
+  if (path.length === 0) {
+    for (const key of Object.keys(base)) {
+      delete base[key];
+    }
+    return;
+  }
+  const keysUpToLastKey = path.slice(0, path.length - 1);
+  let cur = base;
+  const childToParentMapping = /* @__PURE__ */ new WeakMap();
+  for (const key of keysUpToLastKey) {
+    const parent2 = cur;
+    const child = parent2[key];
+    if (typeof child !== "object" || child === null) {
+      return;
+    } else {
+      childToParentMapping.set(child, parent2);
+      cur = child;
+    }
+  }
+  const keysReversed = path.slice().reverse();
+  for (const key of keysReversed) {
+    delete cur[key];
+    if (Object.keys(cur).length > 0) {
+      return;
+    } else {
+      cur = childToParentMapping.get(cur);
+      continue;
+    }
+  }
+}
+
+// shared/src/utils/transientPropPaths.ts
+function parseTransientPropPath(input) {
+  if (typeof input === "string") {
+    if (input.length === 0) {
+      throw new Error(
+        'Transient prop path cannot be an empty string. Use a dot-separated path like "foo.bar".'
+      );
+    }
+    return input.split(".");
+  }
+  return [...input];
+}
+function isPathUnderTransientPrefix(path, prefixes) {
+  for (let i2 = 1; i2 <= path.length; i2++) {
+    const prefix = path.slice(0, i2);
+    if (prefixes.has(encodePathToProp(prefix))) {
+      return true;
+    }
+  }
+  return false;
+}
+function normalizePropPaths(paths, config, objectKeyForError, optionName) {
+  if (!paths || paths.length === 0) {
+    return /* @__PURE__ */ new Set();
+  }
+  const result = /* @__PURE__ */ new Set();
+  for (const rawPath of paths) {
+    const pathToProp = parseTransientPropPath(rawPath);
+    if (process.env.NODE_ENV !== "production") {
+      const propConfig = getPropConfigByPath(config, pathToProp);
+      if (!propConfig) {
+        throw new Error(
+          'sheet.object("'.concat(objectKeyForError, '", ..., { ').concat(optionName, ": [...] }): ") + "path ".concat(JSON.stringify(
+            rawPath
+          ), " does not match any prop in the object's config.")
+        );
+      }
+    }
+    result.add(encodePathToProp(pathToProp));
+  }
+  return result;
+}
+function normalizeTransientPropPaths(paths, config, objectKeyForError) {
+  return normalizePropPaths(paths, config, objectKeyForError, "transient");
+}
+function normalizeStaticPropPaths(paths, config, objectKeyForError) {
+  return normalizePropPaths(paths, config, objectKeyForError, "static");
+}
+function stripTransientPathsFromSerializableMap(map, prefixes) {
+  if (prefixes.size === 0) {
+    return map;
+  }
+  const result = cloneDeep_default(map);
+  for (const encodedPrefix of prefixes) {
+    const path = JSON.parse(encodedPrefix);
+    removePathFromObject(result, path);
+  }
+  return result;
+}
+function stripTransientPathsFromSequenceTracks(sequence, objectKey, prefixes) {
+  var _a;
+  if (!sequence || prefixes.size === 0)
+    return;
+  const objectTracks = (_a = sequence.tracksByObject) == null ? void 0 : _a[objectKey];
+  if (!objectTracks)
+    return;
+  for (const [encodedPath, trackId] of Object.entries(
+    objectTracks.trackIdByPropPath
+  )) {
+    if (typeof trackId !== "string")
+      continue;
+    const path = JSON.parse(encodedPath);
+    if (isPathUnderTransientPrefix(path, prefixes)) {
+      delete objectTracks.trackIdByPropPath[encodedPath];
+      delete objectTracks.trackData[trackId];
+    }
+  }
+  if (objectTracks.unsequencedPropPaths) {
+    objectTracks.unsequencedPropPaths = objectTracks.unsequencedPropPaths.filter(
+      (encodedPath) => !isPathUnderTransientPrefix(
+        JSON.parse(encodedPath),
+        prefixes
+      )
+    );
+  }
+}
+function stripSequenceTracksForPathsFromObjectInSheetState(sheetState, objectKey, prefixes) {
+  if (prefixes.size === 0)
+    return;
+  stripTransientPathsFromSequenceTracks(
+    sheetState.sequence,
+    objectKey,
+    prefixes
+  );
+  if (sheetState.sequencesById) {
+    for (const sequence of Object.values(sheetState.sequencesById)) {
+      stripTransientPathsFromSequenceTracks(sequence, objectKey, prefixes);
+    }
+  }
+}
+function stripTransientPropsFromObjectInSheetState(sheetState, objectKey, prefixes) {
+  if (prefixes.size === 0)
+    return;
+  const staticOverrides = sheetState.staticOverrides.byObject[objectKey];
+  if (staticOverrides) {
+    sheetState.staticOverrides.byObject[objectKey] = stripTransientPathsFromSerializableMap(staticOverrides, prefixes);
+  }
+  if (sheetState.staticOverridesByVariant) {
+    for (const variantOverrides of Object.values(
+      sheetState.staticOverridesByVariant
+    )) {
+      const objOverrides = variantOverrides == null ? void 0 : variantOverrides.byObject[objectKey];
+      if (objOverrides) {
+        variantOverrides.byObject[objectKey] = stripTransientPathsFromSerializableMap(objOverrides, prefixes);
+      }
+    }
+  }
+  stripTransientPathsFromSequenceTracks(
+    sheetState.sequence,
+    objectKey,
+    prefixes
+  );
+  if (sheetState.sequencesById) {
+    for (const sequence of Object.values(sheetState.sequencesById)) {
+      stripTransientPathsFromSequenceTracks(sequence, objectKey, prefixes);
+    }
+  }
+}
+var transientPropPathsRegistry = /* @__PURE__ */ new Map();
+function transientPropPathsRegistryKey(projectId, sheetId, objectKey) {
+  return "".concat(projectId, "\0").concat(sheetId, "\0").concat(objectKey);
+}
+function registerObjectTransientPropPaths(projectId, sheetId, objectKey, paths) {
+  const key = transientPropPathsRegistryKey(projectId, sheetId, objectKey);
+  if (paths.size === 0) {
+    transientPropPathsRegistry.delete(key);
+  } else {
+    transientPropPathsRegistry.set(key, paths);
+  }
+}
+
 // shared/src/propTypes/utils.ts
 function isPropConfigComposite(c2) {
   return c2.type === "compound" || c2.type === "enum";
@@ -3185,6 +3415,25 @@ function getPropConfigByPath(parentConf, path) {
   const sub = parentConf.type === "enum" ? parentConf.cases[key] : parentConf.props[key];
   return getPropConfigByPath(sub, rest);
 }
+function propTypeConfigPersists(conf) {
+  if (conf.type === "image") {
+    return conf.persist !== false;
+  }
+  return true;
+}
+function getNonPersistingPropPathEncodings(config) {
+  const result = /* @__PURE__ */ new Set();
+  for (const { path, conf } of iteratePropType(config, [])) {
+    if (!propTypeConfigPersists(conf)) {
+      result.add(encodePathToProp(path));
+    }
+  }
+  return result;
+}
+function stripNonPersistingPropValuesFromMap(map, config) {
+  const paths = getNonPersistingPropPathEncodings(config);
+  return stripTransientPathsFromSerializableMap(map, paths);
+}
 function isPropConfSequencable(conf) {
   return !isPropConfigComposite(conf);
 }
@@ -3206,6 +3455,61 @@ var compoundHasSimpleDescendants = memoizeFn(
     return false;
   }
 );
+function* iteratePropType(conf, pathPrefix) {
+  if (conf.type === "compound") {
+    for (const key in conf.props) {
+      yield* __yieldStar(iteratePropType(conf.props[key], [
+        ...pathPrefix,
+        key
+      ]));
+    }
+  } else if (conf.type === "enum") {
+    throw new Error("Not implemented yet");
+  } else {
+    return yield { path: pathPrefix, conf };
+  }
+}
+
+// shared/src/utils/updateDeep.ts
+function updateDeep(obj, path, reducer) {
+  if (path.length === 0)
+    return reducer(obj);
+  return hoop(obj, path, reducer);
+}
+var hoop = (s2, path, reducer) => {
+  if (path.length === 0) {
+    return reducer(s2);
+  }
+  if (Array.isArray(s2)) {
+    let [index, ...restOfPath] = path;
+    index = parseInt(String(index), 10);
+    if (isNaN(index))
+      index = 0;
+    const oldVal = s2[index];
+    const newVal = hoop(oldVal, restOfPath, reducer);
+    if (oldVal === newVal)
+      return s2;
+    const newS = [...s2];
+    newS.splice(index, 1, newVal);
+    return newS;
+  } else if (typeof s2 === "object" && s2 !== null) {
+    const [key, ...restOfPath] = path;
+    const oldVal = s2[key];
+    const newVal = hoop(oldVal, restOfPath, reducer);
+    if (oldVal === newVal)
+      return s2;
+    const newS = __spreadProps(__spreadValues({}, s2), { [key]: newVal });
+    return newS;
+  } else {
+    const [key, ...restOfPath] = path;
+    return { [key]: hoop(void 0, restOfPath, reducer) };
+  }
+};
+
+// shared/src/utils/setDeepImmutable.ts
+function setDeepImmutable(obj, path, replace) {
+  return updateDeep(obj, path, () => replace);
+}
 
 // core/src/sequences/sequenceVariants.ts
 var import_theatre_dataverse5 = require("@unseenco/theatre-dataverse");
@@ -3418,6 +3722,11 @@ var SheetObject = class {
      * no-op merge for every app that never uses the remote-sync feature.
      */
     __publicField(this, "_remoteOverride", new import_theatre_dataverse6.Atom({}));
+    /**
+     * Session-only overrides for props with `persist: false`. Not written to
+     * persisted project state and cleared on refresh.
+     */
+    __publicField(this, "_sessionOverrides", new import_theatre_dataverse6.Atom({}));
     __publicField(this, "_cache", new SimpleCache());
     __publicField(this, "_logger");
     __publicField(this, "_internalUtilCtx");
@@ -3491,6 +3800,17 @@ var SheetObject = class {
           const withSeqs = deepMergeWithCache(final, sequenced, withSeqsCache);
           final = withSeqs;
         }
+        const sessionOverrides = (0, import_theatre_dataverse6.val)(this._sessionOverrides.pointer);
+        const withSessionOverridesCache = import_theatre_dataverse6.prism.memo(
+          "withSessionOverridesCache",
+          () => /* @__PURE__ */ new WeakMap(),
+          []
+        );
+        final = deepMergeWithCache(
+          final,
+          sessionOverrides,
+          withSessionOverridesCache
+        );
         const remoteOverride = (0, import_theatre_dataverse6.val)(this._remoteOverride.pointer);
         const withRemoteOverrideCache = import_theatre_dataverse6.prism.memo(
           "withRemoteOverrideCache",
@@ -3540,6 +3860,8 @@ var SheetObject = class {
         () => {
           const untaps = [];
           for (const { trackId, pathToProp, trackVariant } of tracksToProcess) {
+            if (this.template.isNonSequencablePropPath(pathToProp))
+              continue;
             const pr = this._trackIdToPrism(trackId, trackVariant);
             const propConfig = getPropConfigByPath(
               config,
@@ -3602,16 +3924,32 @@ var SheetObject = class {
   }
   validateValue(pointer3, value) {
   }
-  setInitialValue(val10) {
-    this.validateValue(this.propsP, val10);
-    this._initialValue.set(val10);
+  setInitialValue(val11) {
+    this.validateValue(this.propsP, val11);
+    this._initialValue.set(val11);
+  }
+  setSessionOverride(path, value) {
+    const propConfig = getPropConfigByPath(this.template.staticConfig, path);
+    if (!propConfig)
+      return;
+    const sanitized = propConfig.deserializeAndSanitize(value);
+    if (sanitized === void 0)
+      return;
+    this._sessionOverrides.set(
+      setDeepImmutable(this._sessionOverrides.get(), path, sanitized)
+    );
+  }
+  unsetSessionOverride(path) {
+    const next = cloneDeep_default(this._sessionOverrides.get());
+    removePathFromObject(next, path);
+    this._sessionOverrides.set(next);
   }
   /**
    * Internal: called by `RemoteSync` when a value update for this object
    * arrives from a remote editor window. Not exposed on the public API.
    */
-  setRemoteOverride(val10) {
-    this._remoteOverride.set(val10);
+  setRemoteOverride(val11) {
+    this._remoteOverride.set(val11);
   }
   /**
    * Internal: used by `RemoteSync` to subscribe to this object's fully
@@ -4100,7 +4438,7 @@ function isObjectEmpty(obj) {
   return typeof obj === "object" && obj !== null && Object.keys(obj).length === 0;
 }
 var SheetObjectTemplate = class {
-  constructor(sheetTemplate, objectKey, nativeObject, config, _temp_actions) {
+  constructor(sheetTemplate, objectKey, nativeObject, config, _temp_actions, transient, staticPropPaths) {
     this.sheetTemplate = sheetTemplate;
     __publicField(this, "address");
     __publicField(this, "type", "Theatre_SheetObjectTemplate");
@@ -4112,14 +4450,36 @@ var SheetObjectTemplate = class {
     __publicField(this, "pointerToStaticOverrides");
     __publicField(this, "pointerToAhistoricSheetState");
     __publicField(this, "pointerToAhistoricStaticOverrides");
+    __publicField(this, "_transientPropPaths", /* @__PURE__ */ new Set());
+    __publicField(this, "_staticPropPaths", /* @__PURE__ */ new Set());
+    __publicField(this, "_visibleInOutline", true);
     this.address = __spreadProps(__spreadValues({}, sheetTemplate.address), { objectKey });
     this._config = new import_theatre_dataverse7.Atom(config);
     this._temp_actions_atom = new import_theatre_dataverse7.Atom(_temp_actions);
+    this._transientPropPaths = normalizeTransientPropPaths(
+      transient,
+      config,
+      objectKey
+    );
+    this._staticPropPaths = normalizeStaticPropPaths(
+      staticPropPaths,
+      config,
+      objectKey
+    );
     this.project = sheetTemplate.project;
+    registerObjectTransientPropPaths(
+      this.address.projectId,
+      this.address.sheetId,
+      objectKey,
+      this._transientPropPaths
+    );
     this.pointerToSheetState = this.sheetTemplate.project.pointers.historic.sheetsById[this.address.sheetId];
     this.pointerToStaticOverrides = this.pointerToSheetState.staticOverrides.byObject[this.address.objectKey];
     this.pointerToAhistoricSheetState = this.sheetTemplate.project.pointers.ahistoric.sheetsById[this.address.sheetId];
     this.pointerToAhistoricStaticOverrides = this.pointerToAhistoricSheetState.staticOverrides.byObject[this.address.objectKey];
+    this._stripTransientFromHistoricState();
+    this._stripSequencedStaticPathsFromHistoricState();
+    this._stripNonPersistingPropsFromAhistoricState();
   }
   get staticConfig() {
     return this._config.get();
@@ -4133,12 +4493,85 @@ var SheetObjectTemplate = class {
   get _temp_actionsPointer() {
     return this._temp_actions_atom.pointer;
   }
+  _stripNonPersistingPropsFromAhistoricState() {
+    const config = (0, import_theatre_dataverse7.val)(this.configPointer);
+    this.project._stripNonPersistingPropsFromAhistoric(
+      this.address.sheetId,
+      this.address.objectKey,
+      config
+    );
+    this.project._stripNonPersistingPropsFromHistoric(
+      this.address.sheetId,
+      this.address.objectKey,
+      config
+    );
+  }
+  _stripTransientFromHistoricState() {
+    if (this._transientPropPaths.size === 0)
+      return;
+    this.project._stripTransientPropsFromHistoric(
+      this.address.sheetId,
+      this.address.objectKey,
+      this._transientPropPaths
+    );
+  }
+  _stripSequencedStaticPathsFromHistoricState() {
+    if (this._staticPropPaths.size === 0)
+      return;
+    this.project._stripSequenceTracksFromHistoric(
+      this.address.sheetId,
+      this.address.objectKey,
+      this._staticPropPaths
+    );
+  }
   createInstance(sheet, nativeObject, config) {
     this._config.set(config);
     return new SheetObject(sheet, this, nativeObject);
   }
   reconfigure(config) {
     this._config.set(config);
+    this._stripNonPersistingPropsFromAhistoricState();
+  }
+  setTransientPropPaths(transient, config) {
+    this._transientPropPaths = normalizeTransientPropPaths(
+      transient,
+      config,
+      this.address.objectKey
+    );
+    registerObjectTransientPropPaths(
+      this.address.projectId,
+      this.address.sheetId,
+      this.address.objectKey,
+      this._transientPropPaths
+    );
+    this._stripTransientFromHistoricState();
+  }
+  setStaticPropPaths(staticPropPaths, config) {
+    this._staticPropPaths = normalizeStaticPropPaths(
+      staticPropPaths,
+      config,
+      this.address.objectKey
+    );
+    this._stripSequencedStaticPathsFromHistoricState();
+  }
+  isStaticPropPath(path) {
+    return isPathUnderTransientPrefix(path, this._staticPropPaths);
+  }
+  isNonSequencablePropPath(path) {
+    if (this.isTransientPropPath(path) || this.isStaticPropPath(path)) {
+      return true;
+    }
+    const propConfig = getPropConfigByPath(this.staticConfig, path);
+    return propConfig ? !propTypeConfigPersists(propConfig) : false;
+  }
+  getStaticPropPaths() {
+    return this._staticPropPaths;
+  }
+  isTransientPropPath(path) {
+    return isPathUnderTransientPrefix(path, this._transientPropPaths);
+  }
+  getTransientPropPaths() {
+    return this._transientPropPaths;
   }
   /**
    * The `actions` api is temporary until we implement events.
@@ -4146,6 +4579,12 @@ var SheetObjectTemplate = class {
   _temp_setActions(actions) {
     this._temp_actions_atom.set(actions);
   }
+  setVisibleInOutline(visible) {
+    this._visibleInOutline = visible;
+  }
+  isVisibleInOutline() {
+    return this._visibleInOutline;
+  }
   /**
    * Returns the default values (all defaults are read from the config)
    */
@@ -4175,7 +4614,17 @@ var SheetObjectTemplate = class {
         )) != null ? _a : {};
         const config = (0, import_theatre_dataverse7.val)(this.configPointer);
         const deserialized = config.deserializeAndSanitize(json) || {};
-        return deserialized;
+        const withoutNonPersisting = stripNonPersistingPropValuesFromMap(
+          deserialized,
+          config
+        );
+        if (this._transientPropPaths.size > 0) {
+          return stripTransientPathsFromSerializableMap(
+            withoutNonPersisting,
+            this._transientPropPaths
+          );
+        }
+        return withoutNonPersisting;
       })
     );
   }
@@ -4191,7 +4640,7 @@ var SheetObjectTemplate = class {
         const json = (_a = (0, import_theatre_dataverse7.val)(this.pointerToAhistoricStaticOverrides)) != null ? _a : {};
         const config = (0, import_theatre_dataverse7.val)(this.configPointer);
         const deserialized = config.deserializeAndSanitize(json) || {};
-        return deserialized;
+        return stripNonPersistingPropValuesFromMap(deserialized, config);
       })
     );
   }
@@ -4248,6 +4697,8 @@ var SheetObjectTemplate = class {
             const pathToProp = parsePathToProp(pathToPropInString);
             if (!pathToProp)
               continue;
+            if (this.isNonSequencablePropPath(pathToProp))
+              continue;
             const propConfig = getPropConfigByPath(objectConfig, pathToProp);
             const isSequencable = propConfig && isPropConfSequencable(propConfig);
             if (!isSequencable)
@@ -4359,16 +4810,6 @@ function parsePathToProp(pathToPropInString) {
 // core/src/sheets/SheetTemplate.ts
 var import_theatre_dataverse16 = require("@unseenco/theatre-dataverse");
 
-// shared/src/utils/addresses.ts
-var encodePathToProp = memoizeFn(
-  (p2) => (
-    // we're using JSON.stringify here, but we could use a faster alternative.
-    // If you happen to do that, first make sure no `PathToProp_Encoded` is ever
-    // used in the store, otherwise you'll have to write a migration.
-    JSON.stringify(p2)
-  )
-);
-
 // shared/src/utils/didYouMean.ts
 var import_propose = __toESM(require_propose());
 function didYouMean(str, dictionary, prepend = "Did you mean ", append = "?") {
@@ -5599,11 +6040,11 @@ function sanitizeCompoundProps(props) {
         );
       }
     }
-    const val10 = props[key];
-    if (isLonghandPropType(val10)) {
-      sanitizedProps[key] = val10;
+    const val11 = props[key];
+    if (isLonghandPropType(val11)) {
+      sanitizedProps[key] = val11;
     } else {
-      sanitizedProps[key] = toLonghandProp(val10);
+      sanitizedProps[key] = toLonghandProp(val11);
     }
   }
   return sanitizedProps;
@@ -5701,18 +6142,18 @@ var file = (defaultValue, opts = {}) => {
     deserializeAndSanitize: _ensureFile
   };
 };
-var _ensureFile = (val10) => {
-  if (!val10)
+var _ensureFile = (val11) => {
+  if (!val11)
     return void 0;
   let valid = true;
-  if (typeof val10.id !== "string" && ![null, void 0].includes(val10.id)) {
+  if (typeof val11.id !== "string" && ![null, void 0].includes(val11.id)) {
     valid = false;
   }
-  if (val10.type !== "file")
+  if (val11.type !== "file")
     valid = false;
   if (!valid)
     return void 0;
-  return val10;
+  return val11;
 };
 var image = (defaultValue, opts = {}) => {
   if (process.env.NODE_ENV !== "production") {
@@ -5732,22 +6173,23 @@ var image = (defaultValue, opts = {}) => {
     valueType: null,
     [propTypeSymbol]: "TheatrePropType",
     label: opts.label,
+    persist: opts.persist !== false,
     interpolate,
     deserializeAndSanitize: _ensureImage
   };
 };
-var _ensureImage = (val10) => {
-  if (!val10)
+var _ensureImage = (val11) => {
+  if (!val11)
     return void 0;
   let valid = true;
-  if (typeof val10.id !== "string" && ![null, void 0].includes(val10.id)) {
+  if (typeof val11.id !== "string" && ![null, void 0].includes(val11.id)) {
     valid = false;
   }
-  if (val10.type !== "image")
+  if (val11.type !== "image")
     valid = false;
   if (!valid)
     return void 0;
-  return val10;
+  return val11;
 };
 var number = (defaultValue, opts = {}) => {
   var _a;
@@ -5862,12 +6304,12 @@ var rgba = (defaultValue = { r: 0, g: 0, b: 0, a: 1 }, opts = {}) => {
     deserializeAndSanitize: _sanitizeRgba
   };
 };
-var _sanitizeRgba = (val10) => {
-  if (!val10)
+var _sanitizeRgba = (val11) => {
+  if (!val11)
     return void 0;
   let valid = true;
   for (const c2 of ["r", "g", "b", "a"]) {
-    if (!Object.prototype.hasOwnProperty.call(val10, c2) || typeof val10[c2] !== "number") {
+    if (!Object.prototype.hasOwnProperty.call(val11, c2) || typeof val11[c2] !== "number") {
       valid = false;
     }
   }
@@ -5877,7 +6319,7 @@ var _sanitizeRgba = (val10) => {
   for (const c2 of ["r", "g", "b", "a"]) {
     ;
     sanitized[c2] = Math.min(
-      Math.max(val10[c2], 0),
+      Math.max(val11[c2], 0),
       1
     );
   }
@@ -5917,8 +6359,8 @@ var boolean = (defaultValue, opts = {}) => {
     deserializeAndSanitize: _ensureBoolean
   };
 };
-var _ensureBoolean = (val10) => {
-  return typeof val10 === "boolean" ? val10 : void 0;
+var _ensureBoolean = (val11) => {
+  return typeof val11 === "boolean" ? val11 : void 0;
 };
 function leftInterpolate(left) {
   return left;
@@ -6067,6 +6509,18 @@ var TheatreSheet = class {
             if ((opts == null ? void 0 : opts.reconfigure) === true) {
               const sanitizedConfig = compound(config);
               existingObject.template.reconfigure(sanitizedConfig);
+              if (opts.transient !== void 0) {
+                existingObject.template.setTransientPropPaths(
+                  opts.transient,
+                  sanitizedConfig
+                );
+              }
+              if (opts.static !== void 0) {
+                existingObject.template.setStaticPropPaths(
+                  opts.static,
+                  sanitizedConfig
+                );
+              }
               weakMapOfUnsanitizedProps.set(existingObject, config);
               return existingObject.publicApi;
             } else {
@@ -6080,6 +6534,21 @@ var TheatreSheet = class {
       if (actions) {
         existingObject.template._temp_setActions(actions);
       }
+      if ((opts == null ? void 0 : opts.visible) !== void 0) {
+        existingObject.template.setVisibleInOutline(opts.visible);
+      }
+      if ((opts == null ? void 0 : opts.transient) !== void 0) {
+        existingObject.template.setTransientPropPaths(
+          opts.transient,
+          existingObject.template.staticConfig
+        );
+      }
+      if ((opts == null ? void 0 : opts.static) !== void 0) {
+        existingObject.template.setStaticPropPaths(
+          opts.static,
+          existingObject.template.staticConfig
+        );
+      }
       return existingObject.publicApi;
     } else {
       const sanitizedConfig = compound(config);
@@ -6087,7 +6556,10 @@ var TheatreSheet = class {
         sanitizedPath,
         nativeObject,
         sanitizedConfig,
-        actions
+        actions,
+        opts == null ? void 0 : opts.visible,
+        opts == null ? void 0 : opts.transient,
+        opts == null ? void 0 : opts.static
       );
       if (process.env.NODE_ENV !== "production") {
         weakMapOfUnsanitizedProps.set(object, config);
@@ -6196,13 +6668,18 @@ var Sheet = class {
    * @remarks At some point, we have to reconcile the concept of "an object"
    * with that of "an element."
    */
-  createObject(objectKey, nativeObject, config, actions = {}) {
+  createObject(objectKey, nativeObject, config, actions = {}, visibleInOutline, transient, staticPropPaths) {
     const objTemplate = this.template.getObjectTemplate(
       objectKey,
       nativeObject,
       config,
-      actions
+      actions,
+      transient,
+      staticPropPaths
     );
+    if (visibleInOutline !== void 0) {
+      objTemplate.setVisibleInOutline(visibleInOutline);
+    }
     const object = objTemplate.createInstance(this, nativeObject, config);
     this._objects.setByPointer((p2) => p2[objectKey], object);
     this.project._remoteSync.registerObject(object);
@@ -6302,6 +6779,7 @@ var SheetTemplate = class {
     __publicField(this, "objectTemplatesP", this._objectTemplates.pointer);
     __publicField(this, "_pendingOutlineNamespaces", {});
     __publicField(this, "_sequenceVariants", [DEFAULT_SEQUENCE_VARIANT]);
+    __publicField(this, "_visibleInOutline", true);
     this.address = __spreadProps(__spreadValues({}, project.address), { sheetId });
   }
   getInstance(instanceId) {
@@ -6312,7 +6790,7 @@ var SheetTemplate = class {
     }
     return inst;
   }
-  getObjectTemplate(objectKey, nativeObject, config, actions) {
+  getObjectTemplate(objectKey, nativeObject, config, actions, transient, staticPropPaths) {
     let template = this._objectTemplates.get()[objectKey];
     if (!template) {
       template = new SheetObjectTemplate(
@@ -6320,9 +6798,18 @@ var SheetTemplate = class {
         objectKey,
         nativeObject,
         config,
-        actions
+        actions,
+        transient,
+        staticPropPaths
       );
       this._objectTemplates.setByPointer((p2) => p2[objectKey], template);
+    } else {
+      if (transient !== void 0) {
+        template.setTransientPropPaths(transient, config);
+      }
+      if (staticPropPaths !== void 0) {
+        template.setStaticPropPaths(staticPropPaths, config);
+      }
     }
     return template;
   }
@@ -6346,11 +6833,17 @@ var SheetTemplate = class {
       "sheet.declareSequenceVariants"
     );
   }
+  setVisibleInOutline(visible) {
+    this._visibleInOutline = visible;
+  }
+  isVisibleInOutline() {
+    return this._visibleInOutline;
+  }
 };
 
 // core/src/projects/Project.ts
-var import_theatre_dataverse18 = require("@unseenco/theatre-dataverse");
 var import_theatre_dataverse19 = require("@unseenco/theatre-dataverse");
+var import_theatre_dataverse20 = require("@unseenco/theatre-dataverse");
 
 // shared/src/utils/delay.ts
 var delay = (dur) => new Promise((resolve) => setTimeout(resolve, dur));
@@ -6752,13 +7245,13 @@ var globals_default = globals;
 async function initialiseProjectState(studio, project, onDiskState) {
   await delay_default(0);
   studio.transaction(({ drafts }) => {
-    var _a;
+    var _a, _b, _c;
     const projectId = project.address.projectId;
     drafts.ephemeral.coreByProject[projectId] = {
       lastExportedObject: null,
       loadingState: { type: "loading" }
     };
-    drafts.ahistoric.coreByProject[projectId] = {
+    (_b = (_a = drafts.ahistoric.coreByProject)[projectId]) != null ? _b : _a[projectId] = {
       ahistoricStuff: ""
     };
     function useInitialState() {
@@ -6788,7 +7281,7 @@ async function initialiseProjectState(studio, project, onDiskState) {
         onDiskState: onDiskState2
       };
     }
-    const browserState = (_a = e(drafts.historic)) == null ? void 0 : _a.coreByProject[project.address.projectId];
+    const browserState = (_c = e(drafts.historic)) == null ? void 0 : _c.coreByProject[project.address.projectId];
     if (!browserState) {
       if (!onDiskState) {
         useInitialState();
@@ -7008,6 +7501,63 @@ function _coreLogger(config) {
   return internal2.getLogger().named("Theatre");
 }
 
+// shared/src/utils/assets.ts
+var import_theatre_dataverse18 = require("@unseenco/theatre-dataverse");
+
+// shared/src/utils/forEachDeep.ts
+function forEachPropDeep(m, fn2, startingPath = []) {
+  if (typeof m === "object" && m) {
+    if (isImage(m) || isRGBA(m)) {
+      fn2(m, startingPath);
+      return;
+    }
+    for (const [key, value] of Object.entries(m)) {
+      forEachPropDeep(value, fn2, [...startingPath, key]);
+    }
+  } else if (m === void 0 || m === null) {
+    return;
+  } else {
+    fn2(m, startingPath);
+  }
+}
+var isImage = (value) => {
+  return typeof value === "object" && value !== null && Object.hasOwnProperty.call(value, "type") && // @ts-ignore
+  value.type === "image" && Object.hasOwnProperty.call(value, "id") && // @ts-ignore
+  typeof value.id === "string" && // @ts-ignore
+  value.id !== "";
+};
+var isRGBA = (value) => {
+  return typeof value === "object" && value !== null && Object.hasOwnProperty.call(value, "r") && Object.hasOwnProperty.call(value, "g") && Object.hasOwnProperty.call(value, "b") && Object.hasOwnProperty.call(value, "a") && // @ts-ignore
+  typeof value.r === "number" && // @ts-ignore
+  typeof value.g === "number" && // @ts-ignore
+  typeof value.b === "number" && // @ts-ignore
+  typeof value.a === "number";
+};
+
+// shared/src/utils/assets.ts
+function stripImageAssetsFromAhistoricStaticOverrides(ahistoricStaticOverridesByObject) {
+  for (const objectKey of Object.keys(ahistoricStaticOverridesByObject)) {
+    const overrides = ahistoricStaticOverridesByObject[objectKey];
+    if (!overrides)
+      continue;
+    const cloned = cloneDeep_default(overrides);
+    forEachPropDeep(
+      cloned,
+      (value, path) => {
+        if ((value == null ? void 0 : value.type) === "image") {
+          removePathFromObject(cloned, path);
+        }
+      },
+      []
+    );
+    if (Object.keys(cloned).length === 0) {
+      delete ahistoricStaticOverridesByObject[objectKey];
+    } else {
+      ahistoricStaticOverridesByObject[objectKey] = cloned;
+    }
+  }
+}
+
 // core/src/projects/Project.ts
 var Project = class {
   constructor(id, config = {}, publicApi) {
@@ -7019,7 +7569,7 @@ var Project = class {
     __publicField(this, "_studioReadyDeferred");
     __publicField(this, "_assetStorageReadyDeferred");
     __publicField(this, "_readyPromise");
-    __publicField(this, "_sheetTemplates", new import_theatre_dataverse19.Atom({}));
+    __publicField(this, "_sheetTemplates", new import_theatre_dataverse20.Atom({}));
     __publicField(this, "sheetTemplatesP", this._sheetTemplates.pointer);
     __publicField(this, "_studio");
     __publicField(this, "_onDiskStateAtom");
@@ -7033,7 +7583,7 @@ var Project = class {
     this._logger.traceDev("creating project");
     this.address = { projectId: id };
     this._remoteSync = new RemoteSync(this);
-    const onDiskStateAtom = new import_theatre_dataverse19.Atom({
+    const onDiskStateAtom = new import_theatre_dataverse20.Atom({
       ahistoric: {
         ahistoricStuff: ""
       },
@@ -7062,9 +7612,9 @@ var Project = class {
       }
     };
     this._pointerProxies = {
-      historic: new import_theatre_dataverse18.PointerProxy(onDiskStateAtom.pointer.historic),
-      ahistoric: new import_theatre_dataverse18.PointerProxy(onDiskStateAtom.pointer.ahistoric),
-      ephemeral: new import_theatre_dataverse18.PointerProxy(onDiskStateAtom.pointer.ephemeral)
+      historic: new import_theatre_dataverse19.PointerProxy(onDiskStateAtom.pointer.historic),
+      ahistoric: new import_theatre_dataverse19.PointerProxy(onDiskStateAtom.pointer.ahistoric),
+      ephemeral: new import_theatre_dataverse19.PointerProxy(onDiskStateAtom.pointer.ephemeral)
     };
     this.pointers = {
       historic: this._pointerProxies.historic.pointer,
@@ -7131,6 +7681,7 @@ var Project = class {
       this._pointerProxies.ephemeral.setPointer(
         studio.atomP.ephemeral.coreByProject[this.address.projectId]
       );
+      this._stripImageAssetsFromAhistoricState();
       await studio.createAssetStorage(this, (_a = this.config.assets) == null ? void 0 : _a.baseUrl).then((assetStorage) => {
         this.assetStorage = assetStorage;
         this._assetStorageReadyDeferred.resolve(void 0);
@@ -7152,12 +7703,15 @@ var Project = class {
   isReady() {
     return this._studioReadyDeferred.status === "resolved" && this._assetStorageReadyDeferred.status === "resolved";
   }
-  getOrCreateSheet(sheetId, instanceId = "default") {
+  getOrCreateSheet(sheetId, instanceId = "default", opts) {
     let template = this._sheetTemplates.get()[sheetId];
     if (!template) {
       template = new SheetTemplate(this, sheetId);
       this._sheetTemplates.reduce((s2) => __spreadProps(__spreadValues({}, s2), { [sheetId]: template }));
     }
+    if ((opts == null ? void 0 : opts.visible) !== void 0) {
+      template.setVisibleInOutline(opts.visible);
+    }
     const sheet = template.getInstance(instanceId);
     this._remoteSync.registerSheet(sheet);
     return sheet;
@@ -7210,16 +7764,144 @@ var Project = class {
       });
     }
   }
+  _stripImageAssetsFromAhistoricState() {
+    const strip = (ahistoric) => {
+      var _a;
+      for (const sheetState of Object.values((_a = ahistoric.sheetsById) != null ? _a : {})) {
+        if (!sheetState)
+          continue;
+        stripImageAssetsFromAhistoricStaticOverrides(
+          sheetState.staticOverrides.byObject
+        );
+      }
+    };
+    if (this._studio) {
+      this._studio.transaction(({ drafts }) => {
+        const ahistoric = drafts.ahistoric.coreByProject[this.address.projectId];
+        if (ahistoric)
+          strip(ahistoric);
+      });
+    } else {
+      this._mutateCoreAhistoric(strip);
+    }
+  }
+  _stripNonPersistingPropsFromAhistoric(sheetId, objectKey, config) {
+    const paths = getNonPersistingPropPathEncodings(config);
+    if (paths.size === 0)
+      return;
+    const strip = (ahistoric) => {
+      var _a;
+      const sheetState = (_a = ahistoric.sheetsById) == null ? void 0 : _a[sheetId];
+      if (!sheetState)
+        return;
+      const staticOverrides = sheetState.staticOverrides.byObject[objectKey];
+      if (staticOverrides) {
+        sheetState.staticOverrides.byObject[objectKey] = stripTransientPathsFromSerializableMap(staticOverrides, paths);
+      }
+    };
+    if (this._studio) {
+      this._studio.transaction(({ drafts }) => {
+        const ahistoric = drafts.ahistoric.coreByProject[this.address.projectId];
+        if (ahistoric)
+          strip(ahistoric);
+      });
+    } else {
+      this._mutateCoreAhistoric(strip);
+    }
+  }
+  _stripNonPersistingPropsFromHistoric(sheetId, objectKey, config) {
+    const paths = getNonPersistingPropPathEncodings(config);
+    if (paths.size === 0)
+      return;
+    const strip = (historic) => {
+      const sheetState = historic.sheetsById[sheetId];
+      if (!sheetState)
+        return;
+      stripTransientPropsFromObjectInSheetState(sheetState, objectKey, paths);
+      stripSequenceTracksForPathsFromObjectInSheetState(
+        sheetState,
+        objectKey,
+        paths
+      );
+    };
+    if (this._studio) {
+      this._studio.transaction(({ drafts }) => {
+        const historic = drafts.historic.coreByProject[this.address.projectId];
+        if (historic)
+          strip(historic);
+      });
+    } else {
+      this._onDiskStateAtom.reduce((state) => {
+        const historic = __spreadValues({}, state.historic);
+        strip(historic);
+        return __spreadProps(__spreadValues({}, state), { historic });
+      });
+    }
+  }
+  _stripTransientPropsFromHistoric(sheetId, objectKey, transientPaths) {
+    if (transientPaths.size === 0)
+      return;
+    const strip = (historic) => {
+      const sheetState = historic.sheetsById[sheetId];
+      if (!sheetState)
+        return;
+      stripTransientPropsFromObjectInSheetState(
+        sheetState,
+        objectKey,
+        transientPaths
+      );
+    };
+    if (this._studio) {
+      this._studio.transaction(({ drafts }) => {
+        const historic = drafts.historic.coreByProject[this.address.projectId];
+        if (historic)
+          strip(historic);
+      });
+    } else {
+      this._onDiskStateAtom.reduce((state) => {
+        const historic = __spreadValues({}, state.historic);
+        strip(historic);
+        return __spreadProps(__spreadValues({}, state), { historic });
+      });
+    }
+  }
+  _stripSequenceTracksFromHistoric(sheetId, objectKey, propPaths) {
+    if (propPaths.size === 0)
+      return;
+    const strip = (historic) => {
+      const sheetState = historic.sheetsById[sheetId];
+      if (!sheetState)
+        return;
+      stripSequenceTracksForPathsFromObjectInSheetState(
+        sheetState,
+        objectKey,
+        propPaths
+      );
+    };
+    if (this._studio) {
+      this._studio.transaction(({ drafts }) => {
+        const historic = drafts.historic.coreByProject[this.address.projectId];
+        if (historic)
+          strip(historic);
+      });
+    } else {
+      this._onDiskStateAtom.reduce((state) => {
+        const historic = __spreadValues({}, state.historic);
+        strip(historic);
+        return __spreadProps(__spreadValues({}, state), { historic });
+      });
+    }
+  }
 };
 
 // shared/src/utils/sanitizers.ts
-var _validateSym = (val10, thingy, range) => {
-  if (typeof val10 !== "string") {
-    return "".concat(thingy, " must be a string. ").concat(userReadableTypeOfValue_default(val10), " given.");
-  } else if (val10.trim().length !== val10.length) {
-    return "".concat(thingy, " must not have leading or trailing spaces. '").concat(val10, "' given.");
-  } else if (val10.length < range[0] || val10.length > range[1]) {
-    return "".concat(thingy, " must have between ").concat(range[0], " and ").concat(range[1], " characters. '").concat(val10, "' given.");
+var _validateSym = (val11, thingy, range) => {
+  if (typeof val11 !== "string") {
+    return "".concat(thingy, " must be a string. ").concat(userReadableTypeOfValue_default(val11), " given.");
+  } else if (val11.trim().length !== val11.length) {
+    return "".concat(thingy, " must not have leading or trailing spaces. '").concat(val11, "' given.");
+  } else if (val11.length < range[0] || val11.length > range[1]) {
+    return "".concat(thingy, " must have between ").concat(range[0], " and ").concat(range[1], " characters. '").concat(val11, "' given.");
   }
 };
 var validateName = (name, thingy, shouldThrow = false) => {
@@ -7268,11 +7950,19 @@ var TheatreProject = class {
     }
     return asset.id ? privateAPI(this).assetStorage.getAssetUrl(asset.id) : void 0;
   }
-  sheet(sheetId, instanceId = "default") {
+  sheet(sheetId, instanceIdOrOpts = "default", opts) {
     const sanitizedPath = validateAndSanitiseSlashedPathOrThrow(
       sheetId,
       "project.sheet"
     );
+    let instanceId = "default";
+    let sheetOpts;
+    if (typeof instanceIdOrOpts === "string") {
+      instanceId = instanceIdOrOpts;
+      sheetOpts = opts;
+    } else {
+      sheetOpts = instanceIdOrOpts;
+    }
     if (process.env.NODE_ENV !== "production") {
       validateInstanceId(
         instanceId,
@@ -7282,15 +7972,16 @@ var TheatreProject = class {
     }
     return privateAPI(this).getOrCreateSheet(
       sanitizedPath,
-      instanceId
+      instanceId,
+      sheetOpts
     ).publicApi;
   }
 };
 
 // core/src/coreExports.ts
 var import_fast_deep_equal2 = __toESM(require_fast_deep_equal());
-var import_theatre_dataverse20 = require("@unseenco/theatre-dataverse");
 var import_theatre_dataverse21 = require("@unseenco/theatre-dataverse");
+var import_theatre_dataverse22 = require("@unseenco/theatre-dataverse");
 function getProject(id, config = {}) {
   const existingProject = projectsSingleton_default.get(id);
   if (existingProject) {
@@ -7357,10 +8048,10 @@ var validateProjectIdOrThrow = (value) => {
 };
 function onChange(pointer3, callback, rafDriver) {
   const ticker = rafDriver ? privateAPI(rafDriver).ticker : getCoreTicker();
-  if ((0, import_theatre_dataverse20.isPointer)(pointer3)) {
-    const pr = (0, import_theatre_dataverse21.pointerToPrism)(pointer3);
+  if ((0, import_theatre_dataverse21.isPointer)(pointer3)) {
+    const pr = (0, import_theatre_dataverse22.pointerToPrism)(pointer3);
     return pr.onChange(ticker, callback, true);
-  } else if ((0, import_theatre_dataverse21.isPrism)(pointer3)) {
+  } else if ((0, import_theatre_dataverse22.isPrism)(pointer3)) {
     return pointer3.onChange(ticker, callback, true);
   } else {
     throw new Error(
@@ -7368,9 +8059,9 @@ function onChange(pointer3, callback, rafDriver) {
     );
   }
 }
-function val9(pointer3) {
-  if ((0, import_theatre_dataverse20.isPointer)(pointer3)) {
-    return (0, import_theatre_dataverse21.pointerToPrism)(pointer3).getValue();
+function val10(pointer3) {
+  if ((0, import_theatre_dataverse21.isPointer)(pointer3)) {
+    return (0, import_theatre_dataverse22.pointerToPrism)(pointer3).getValue();
   } else {
     throw new Error("Called val(p) where p is not a pointer.");
   }
@@ -7385,7 +8076,7 @@ var CoreBundle = class {
     return "Theatre_CoreBundle";
   }
   get version() {
-    return "0.1.2";
+    return "0.1.4";
   }
   getBitsForStudio(studio, callback) {
     if (this._studio) {