@rohal12/spindle 0.59.4 → 0.59.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.59.4",
+  "version": "0.59.6",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",

package/src/components/macros/Unset.tsx

@@ -10,7 +10,11 @@ defineMacro({
       const state = useStoryStore.getState();
       const name = ctx.args.variable ?? '';
 
-      if (name.startsWith('$')) {
+      if (/^[$_%@][^.]*\./.test(name)) {
+        // A field of a variable: delete it as mutation code does, which
+        // resolves the path in every namespace
+        ctx.mutate(`delete ${name}`);
+      } else if (name.startsWith('$')) {
         state.deleteVariable(name.slice(1));
       } else if (name.startsWith('_')) {
         state.deleteTemporary(name.slice(1));

package/src/define-macro.ts

@@ -18,7 +18,7 @@ import {
   renderInlineNodes,
 } from './markup/render';
 import type { ASTNode } from './markup/ast';
-import { executeMutation, readState } from './execute-mutation';
+import { executeMutation, mutateState, readState } from './execute-mutation';
 import { evaluate } from './expression';
 import { useStoryStore } from './store';
 import { getByPath, setByPath } from './utils/object-path';
@@ -228,8 +228,11 @@ export function defineMacro<const P extends readonly ParameterDef[] = []>(
       // In program order, also when mutation code performs the input
       ctx.getValue = () => getByPath(readState().variables, segments);
       ctx.setValue = (value: unknown) => {
-        useStoryStore.setState((state) => {
-          setByPath(state.variables, segments, value, {
+        // The commit mutation code uses, which keeps the references among
+        // variables: a write to a draft copies only the path written, and
+        // other variables sharing the object would keep the old one.
+        mutateState((work, adopt) => {
+          setByPath(work.variables, segments, adopt(value), {
             createMissing: true,
           });
         });

package/src/execute-mutation.ts

@@ -10,19 +10,18 @@ import { useStoryStore } from './store';
 import type { StoryState, VariableNamespaces } from './store';
 import { execute } from './expression';
 import {
-  aliasChanges,
+  changesBetween,
   applyChange,
   deepClone,
-  deepEqual,
-  diffPaths,
   existingObjects,
+  getByEntryPath,
+  isEntryKey,
   isApplied,
   isMergeable,
   locateObjects,
-  mergeKeys,
+  relinkPath,
   pathKey,
   sharedPaths,
-  underChange,
   type PathChange,
 } from './structural';
 import { getByPath, setByPath } from './utils/object-path';
@@ -96,7 +95,23 @@ function clonerFor(
   paths?: ReadonlyMap<object, string[]>,
 ): Cloner {
   const seen = paths ? existingObjects(paths, target) : new Map();
-  return (value) => deepClone(value, { keepUnregistered: true, seen });
+  // Immer does not finalize a draft held as a Map key or Set member, so an
+  // existing object met there is put in the draft as the object itself: its
+  // base while the code did not change it, which other references to it then
+  // agree with.
+  const settle = (copy: object, original: object): object => {
+    const path = paths?.get(original);
+    if (!path || !isDraft(copy)) return copy;
+    const plain = currentDraft(copy) as object;
+    // Where the object is in an entry of a Map or Set the path cannot be
+    // written (see getByEntryPath): that entry keeps its own
+    if (!path.some(isEntryKey)) {
+      setByPath(target as Record<string, unknown>, path, plain);
+    }
+    seen.set(original, plain);
+    return plain;
+  };
+  return (value) => deepClone(value, { keepUnregistered: true, seen, settle });
 }
 
 /** One cloner per target copy, made when first used. */
@@ -292,8 +307,10 @@ export function routeStoreUpdate<S extends VariableNamespaces>(
         )
       : [];
   });
-  // Each target takes its own copies, which share what the written values do
-  const cloners = clonersFor();
+  // Each target takes its own copies, which share what the written values do,
+  // and an object the code holds elsewhere stays that one (`Story.set('b', $a)`)
+  const held = locateObjects(namespacesOf(inner.work), changes);
+  const cloners = clonersFor(() => held);
   const owned = (change: PathChange, target: object): PathChange =>
     change.deleted
       ? change
@@ -347,10 +364,10 @@ function relink(
     const prefixes = [first!, ...others].map((p) => pathKey(p).slice(0, -1));
     if (!written.some((w) => prefixes.some((p) => w.startsWith(p)))) continue;
     try {
-      const object = getByPath(draft, first!);
+      const object = getByEntryPath(draft, first!);
       if (object === null || typeof object !== 'object') continue;
       for (const path of others)
-        setByPath(draft as unknown as Record<string, unknown>, path, object);
+        relinkPath(draft as unknown as Record<string, unknown>, path, object);
     } catch {
       // A path the store does not hold: the code's view is not the store's
     }
@@ -370,6 +387,13 @@ function cloneNamespaces(from: VariableNamespaces): VariableNamespaces {
   };
 }
 
+/** The three variable namespaces of `state`, as an object to walk. */
+const namespacesOf = (state: VariableNamespaces): VariableNamespaces => ({
+  variables: state.variables,
+  temporary: state.temporary,
+  transient: state.transient,
+});
+
 /** A mutation to commit, and whether its code goes on running after. */
 interface Commit {
   scope: MutationScope;
@@ -470,28 +494,16 @@ function commitScopes(commits: readonly Commit[]): void {
 
 /**
  * The changes of the code to the namespaces, as paths below them (`['variables',
- * 'a']`): the property paths that differ (see diffPaths), and those that hold
- * equal content but another object than they did (see aliasChanges), those
- * first. Compared as one object, so an object the namespaces share is one
- * object, whichever of them it is reached through.
+ * 'a']`; see changesBetween).
  */
-function changesOf(
+const changesOf = (
   base: VariableNamespaces,
   work: VariableNamespaces,
-): PathChange[] {
-  const before = base as unknown as Record<string, unknown>;
-  const after = work as unknown as Record<string, unknown>;
-  const written = diffPaths(before, after);
-  const keys = new Set(written.map((c) => pathKey(c.path)));
-  const aliases: PathChange[] = [];
-  for (const change of aliasChanges(before, after)) {
-    // Written whole by a change at it or above it
-    if (underChange(change.path, keys)) continue;
-    keys.add(pathKey(change.path));
-    aliases.push(change);
-  }
-  return [...aliases, ...written];
-}
+): PathChange[] =>
+  changesBetween(
+    base as unknown as Record<string, unknown>,
+    work as unknown as Record<string, unknown>,
+  );
 
 /** Every running mutation, to commit with its code going on. */
 const running = (): Commit[] =>
@@ -500,14 +512,31 @@ const running = (): Commit[] =>
 /**
  * Bring a suspended mutation's copies up to the store after an action
  * replaced or changed state under it (navigation clears temporaries, back
- * and restart replace variables). Roots that still match keep the objects
- * the code may hold.
+ * and restart replace variables). What the action changed (see
+ * changesBetween) is written into the code's working copy, which keeps the
+ * objects the code may hold where nothing changed, and the references among
+ * the values written, and to the objects it holds already, as a commit does.
  */
 function resync(scope: MutationScope): void {
   const state = useStoryStore.getState();
-  for (const ns of NAMESPACES) {
-    // Root by root: a root that differs is replaced with a copy of the store's
-    mergeKeys(scope.work[ns], scope.work[ns], state[ns]);
+  const now = namespacesOf(state);
+  const changes = changesBetween(
+    scope.base as unknown as Record<string, unknown>,
+    now as unknown as Record<string, unknown>,
+  );
+  const copy = clonerFor(scope.work, locateObjects(now, changes));
+  for (const change of changes) {
+    try {
+      applyChange(
+        scope.work,
+        change.deleted ? change : { ...change, value: copy(change.value) },
+      );
+    } catch {
+      // A path the working copy does not hold: replace its root instead
+      const [ns, root] = change.path as [NamespaceName, string];
+      if (hasOwn(now[ns], root)) scope.work[ns][root] = copy(now[ns][root]);
+      else delete scope.work[ns][root];
+    }
   }
   scope.base = cloneNamespaces(state);
 }
@@ -537,13 +566,23 @@ export function runWithCommittedMutations<T>(action: () => T): T {
  * between values are kept, which a store update made on a draft does not do.
  * Nothing is committed when `run` throws.
  */
-export function mutateState(run: (work: VariableNamespaces) => void): void {
+export function mutateState(
+  run: (work: VariableNamespaces, adopt: Cloner) => void,
+): void {
   // The writes of the code this runs inside come first, and stay even if
   // `run` throws
   commitScopes(running());
+  // Where the objects `run` may be handed are: in the state it continues from
+  const held = locateObjects(
+    namespacesOf(getActiveMutationScope() ?? useStoryStore.getState()),
+    [],
+  );
   const scope = startScope();
+  // Copies values into the working copy, an object it holds already staying
+  // that one, and what the values share staying shared
+  const adopt = clonerFor(scope.work, held);
   try {
-    run(scope.work);
+    run(scope.work, adopt);
   } finally {
     activeScopes.pop();
   }
@@ -595,11 +634,26 @@ export function executeMutation(
   // came before its own
   commitScopes([...running(), { scope, keepRunning: false }]);
 
-  for (const key of Object.keys(localsClone)) {
-    if (!deepEqual(localsClone[key], mergedLocals[key])) {
-      scopeUpdate(key, localsClone[key]);
+  // Locals the code changed, as content or as the objects they refer to
+  // (`@a = @b` over an equal object), and the locals that share an object
+  // with one of those: the updater takes each one's value, so they must all
+  // be written for the scope to hold one object again
+  const changed = new Set(
+    changesBetween(mergedLocals, localsClone, true).map((c) => c.path[0]!),
+  );
+  for (const group of sharedPaths(localsClone)) {
+    if (group.some((path) => changed.has(path[0]!))) {
+      // Not a value kept by reference (an unregistered class instance)
+      for (const path of group) {
+        if (localsClone[path[0]!] !== mergedLocals[path[0]!]) {
+          changed.add(path[0]!);
+        }
+      }
     }
   }
+  for (const key of Object.keys(localsClone)) {
+    if (changed.has(key)) scopeUpdate(key, localsClone[key]);
+  }
 
   // Detect deleted locals
   for (const key of Object.keys(mergedLocals)) {

package/src/store.ts

@@ -44,8 +44,16 @@ import {
   deletePlaythroughData as smDeletePlaythroughData,
 } from './saves/save-manager';
 
-import { deepClone, mergeKeys, mergesWith, shareEqual } from './structural';
-import { shallowCopy } from './utils/object-path';
+import {
+  changesBetween,
+  deepClone,
+  existingObjects,
+  locateObjects,
+  mergesWith,
+  shareEqual,
+  type PathChange,
+} from './structural';
+import { getByPath } from './utils/object-path';
 import { noPassageError, showRuntimeError } from './runtime-errors';
 import {
   snapshotPRNG,
@@ -708,11 +716,13 @@ function loadedEntryMoment(
  * the `beforesave` hooks) into the payload's snapshot of the saved moment. A
  * load restores that snapshot, the state on entering the passage, and runs
  * the passage again, so data a hook adds to a save would otherwise be lost
- * on load (#227). Only the property paths the hooks changed are written (into
- * copies of the objects on those paths, the rest staying shared): a
- * whole variable would bring along what the passage did to the rest of it,
- * which the passage then does again on load (#232). Only the payload's copy
- * changes: the live history keeps the recorded snapshot (#159).
+ * on load (#227). Only the property paths the hooks changed are written (see
+ * changesBetween): a whole variable would bring along what the passage did
+ * to the rest of it, which the passage then does again on load (#232). The
+ * references the hooks made stay: an object they put in two variables is one
+ * object in the snapshot, and one they made another variable refer to is the
+ * snapshot's own object of it (#302). Only the payload's copy changes: the
+ * live history keeps the recorded snapshot (#159).
  */
 function keepHookWrites(
   payload: SavePayload,
@@ -721,41 +731,78 @@ function keepHookWrites(
 ): void {
   const moment = payload.history[payload.historyIndex];
   if (!moment) return;
-  mergeHookWrites(moment.variables, before, after, new Set());
+  const changes = changesBetween(before, after, true);
+  if (changes.length === 0) return;
+  // A copy of its own, so the writes keep the snapshot's references (which
+  // the history shares with other moments) as they are
+  const work = deepClone(moment.variables);
+  const seen = existingObjects(locateObjects(after, changes), work);
+  const own = <T>(value: T): T => deepClone(value, { seen });
+  for (const change of changes) writeHookChange(work, after, change, own);
+  moment.variables = shareEqual(moment.variables, work);
 }
 
 /**
- * Apply the hooks' changes between `before` and `after`, two objects or two
- * arrays, to the snapshot's copy of them, `target` (see mergeKeys: array
- * elements merge by index). A changed value is merged key by key where the
- * snapshot holds the same kind of value. Where it lacks the key or holds
- * another kind (the passage created or replaced it), the hooks' whole value
- * is written.
+ * Write `change` (of the hooks, to `after`) into `work`. The value goes in at
+ * the first place `work` lacks the objects on the path of one of the kind
+ * `after` holds (the passage created or replaced it): there, the hooks' whole
+ * value of it is written. Into an array, elements removed from the end are
+ * removed at the same indices and elements added are appended; changes at
+ * indices the array lacks are dropped (it was resized, so its indices do not
+ * line up with the live ones).
  */
-function mergeHookWrites(
-  target: Record<string, unknown>,
-  before: Record<string, unknown>,
+function writeHookChange(
+  work: Record<string, unknown>,
   after: Record<string, unknown>,
-  ancestors: Set<object>,
+  change: PathChange,
+  own: <T>(value: T) => T,
 ): void {
-  ancestors.add(after);
-  mergeKeys(target, before, after, (key, b, a) => {
-    if (
-      !hasOwn(target, key) ||
-      !mergesWith(a, target[key], true) ||
-      // Stop at cycles: deepEqual() and deepClone() handle them
-      ancestors.has(a)
-    ) {
-      return false;
+  const { path } = change;
+  let holder: Record<string, unknown> = work;
+  let depth = 0;
+  for (; depth < path.length - 1; depth++) {
+    const key = path[depth]!;
+    const child = hasOwn(holder, key) ? holder[key] : undefined;
+    const held = getByPath(after, path.slice(0, depth + 1));
+    if (!mergesWith(child, held, true)) {
+      writeKey(holder, key, own(held));
+      return;
     }
-    // The snapshot's values are the history's own (immutable, see
-    // plainCopy): merge into a copy, made along the merged path only
-    const copy = shallowCopy(target[key] as object);
-    target[key] = copy;
-    mergeHookWrites(copy, b, a, ancestors);
-    return true;
-  });
-  ancestors.delete(after);
+    holder = child as Record<string, unknown>;
+  }
+  const key = path[depth]!;
+  if (change.deleted) writeKey(holder, key, undefined, change);
+  else writeKey(holder, key, own(change.value), change);
+}
+
+function writeKey(
+  holder: Record<string, unknown>,
+  key: string,
+  value: unknown,
+  change?: PathChange,
+): void {
+  const deleted = change?.deleted ?? false;
+  if (Array.isArray(holder)) {
+    const index = Number(key);
+    if (deleted) {
+      // A hole stays where it was; anything else was cut off
+      if (change && 'hole' in change) delete holder[index];
+      else holder.length = Math.min(holder.length, index);
+    } else if (change && 'appended' in change) {
+      // After the holes it followed
+      holder.length += change.gap ?? 0;
+      holder.push(value);
+    } else if (key === 'length' && change) {
+      // Holes added at the end
+      holder.length += value as number;
+    } else if (index < holder.length) {
+      holder[index] = value;
+    }
+  } else if (deleted) {
+    delete holder[key];
+  } else {
+    setOwn(holder, key, value);
+  }
 }
 
 /** Restore the PRNG from a snapshot, or reset it without one. */

package/src/story-api.ts

@@ -307,8 +307,8 @@ function createStoryAPI(): StoryAPI {
         // uses (nested in the running code, if any: it continues from the
         // code's pending writes, and they are committed first): an update of a draft would give the written path new
         // objects and leave the other references to the old ones (#295).
-        mutateState((work) => {
-          for (const [k, v] of entries) setOne(work, k, v);
+        mutateState((work, adopt) => {
+          for (const [k, v] of entries) setOne(work, k, adopt(v));
         });
         return;
       }