@rohal12/spindle 0.59.5 → 0.59.7

package/package.json

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

package/src/class-registry.ts

@@ -110,11 +110,22 @@ const defineData = (target: object, key: string, value: unknown): void => {
   });
 };
 
+/**
+ * A reducer extracts string keys, so devalue never sees the symbol keys of
+ * the original object: refuse them here, as it does for a plain object.
+ */
+function refuseSymbolKeys(value: object): void {
+  if (Object.getOwnPropertySymbols(value).length > 0) {
+    throw new TypeError('spindle: Cannot save an object with symbol keys');
+  }
+}
+
 /**
  * Own enumerable keys of `value`, as a plain object; for an error also its
  * message, cause and (AggregateError) errors, which are not enumerable.
  */
 function ownData(value: object): Record<string, unknown> {
+  refuseSymbolKeys(value);
   const data: Record<string, unknown> = {};
   if (value instanceof Error) {
     for (const key of ERROR_HIDDEN_KEYS) {
@@ -163,6 +174,7 @@ function reducers(): Record<string, (value: unknown) => unknown> {
       }
       const keys = Object.keys(v);
       if (!keys.some(isEscapedOneCharKey)) return false;
+      refuseSymbolKeys(v);
       if (keys.includes('__proto__')) {
         throw new TypeError(
           'spindle: Cannot save a property named "__proto__"',

package/src/components/App.tsx

@@ -41,9 +41,7 @@ export function App() {
     </>
   );
 
-  return nobr ? (
-    <NobrContext.Provider value={true}>{content}</NobrContext.Provider>
-  ) : (
-    content
-  );
+  // One provider whatever `nobr` is: a changing tree shape would remount the
+  // passage and run its mount-only macros again
+  return <NobrContext.Provider value={nobr}>{content}</NobrContext.Provider>;
 }

package/src/components/macros/Computed.tsx

@@ -1,7 +1,7 @@
 import { useStoryStore } from '../../store';
 import { evaluate } from '../../expression';
 import { readState } from '../../execute-mutation';
-import { deepEqual } from '../../structural';
+import { deepEqualStrict } from '../../structural';
 import { defineMacro } from '../../define-macro';
 import { MacroError, logMacroError } from './MacroError';
 import { currentSourceLocation } from '../../utils/source-location';
@@ -67,7 +67,8 @@ function computeAndApply(
     return;
   }
 
-  if (!deepEqual(prevRef.current, newValue)) {
+  // Strict: a change of only the aliases inside the result is a change
+  if (!deepEqualStrict(prevRef.current, newValue)) {
     prevRef.current = newValue;
     if (isLocal) {
       try {

package/src/components/macros/PassageDisplay.tsx

@@ -131,9 +131,6 @@ defineMacro({
       const store = useStoryStore.getState();
       const { history, historyIndex, transitionConfig } = store;
 
-      // Always consume the next transition (one-shot), regardless of what we do
-      const next = store.consumeNextTransition();
-
       // Determine if this is a first load, restart, or save-load
       const prevLen = prevHistoryLenRef.current;
       prevHistoryLenRef.current = history.length;
@@ -152,6 +149,10 @@ defineMacro({
         return;
       }
 
+      // One-shot, used up by the first navigation, whatever we do with it
+      // (not by the initial render, which no navigation caused)
+      const next = store.consumeNextTransition();
+
       // Cancel any in-progress transition
       cancelTransition();
 

package/src/components/macros/SaveManager.tsx

@@ -127,9 +127,8 @@ export function SaveManagerContent() {
     const playthrough = resolvePlaythroughId();
     try {
       await saveWithHooks(undefined, undefined, beginSave, async (payload) => {
-        const ptId = await playthrough;
-        if (!ptId) throw new Error('No playthrough');
-        return createSave(ifid, ptId, payload);
+        // Queued now, in call order with other storage operations
+        return createSave(ifid, playthrough, payload);
       });
       showStatus('Save created');
       await refresh();
@@ -143,8 +142,7 @@ export function SaveManagerContent() {
     try {
       await saveWithHooks(undefined, undefined, beginSave, async (payload) => {
         // Only the current playthrough's saves offer "Save Here"
-        const ptId = (await playthrough) || undefined;
-        if (!(await overwriteSave(saveId, payload, undefined, ptId))) {
+        if (!(await overwriteSave(saveId, payload, undefined, playthrough))) {
           throw new Error('Save not found');
         }
       });

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/execute-mutation.ts

@@ -13,12 +13,13 @@ import {
   changesBetween,
   applyChange,
   deepClone,
-  deepEqual,
   existingObjects,
+  getByEntryPath,
+  isEntryKey,
   isApplied,
   isMergeable,
   locateObjects,
-  mergeKeys,
+  relinkPath,
   pathKey,
   sharedPaths,
   type PathChange,
@@ -94,18 +95,23 @@ function clonerFor(
   paths?: ReadonlyMap<object, string[]>,
 ): Cloner {
   const seen = paths ? existingObjects(paths, target) : new Map();
-  // Immer does not finalize a draft held as a Map key, 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 mapKey = (copy: object, original: object): object => {
+  // 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;
-    setByPath(target as Record<string, unknown>, path, plain);
+    // 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, mapKey });
+  return (value) => deepClone(value, { keepUnregistered: true, seen, settle });
 }
 
 /** One cloner per target copy, made when first used. */
@@ -358,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
     }
@@ -375,9 +381,9 @@ function relink(
 function cloneNamespaces(from: VariableNamespaces): VariableNamespaces {
   const seen = new Map<object, object>();
   return {
-    variables: deepClone(from.variables, { seen }),
-    temporary: deepClone(from.temporary, { seen }),
-    transient: deepClone(from.transient, { seen }),
+    variables: deepClone(from.variables, { keepUnregistered: true, seen }),
+    temporary: deepClone(from.temporary, { keepUnregistered: true, seen }),
+    transient: deepClone(from.transient, { keepUnregistered: true, seen }),
   };
 }
 
@@ -506,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);
 }
@@ -611,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/index.tsx

@@ -62,6 +62,21 @@ function stopWithErrors(errors: string[]): never {
   );
 }
 
+/**
+ * The undeclared variables the passages refer to, with the macros known now:
+ * the input macros that bind a variable (registered by author JS or
+ * StoryInit) and the roles of their parameters decide what is a reference.
+ */
+function variableErrors(
+  storyData: StoryData,
+  schema: Parameters<typeof validatePassages>[1],
+): string[] {
+  const storeVarMacros = getMacroRegistry()
+    .filter((m) => m.storeVar)
+    .map((m) => m.name);
+  return validatePassages(storyData.passages, schema, storeVarMacros);
+}
+
 /**
  * The markup errors (malformed markup, unknown macros, syntax errors in
  * code) of the passages for which `only` holds, with the macros and widgets
@@ -134,10 +149,6 @@ export function boot() {
   }
 
   const schema = parseStoryVariables(storyVarsPassage.content);
-  // Include input macros registered by author JS, which ran above.
-  const storeVarMacros = getMacroRegistry()
-    .filter((m) => m.storeVar)
-    .map((m) => m.name);
   // Pass 1: Register the block widgets as block macros BEFORE any passage
   // is parsed (validation and StoryInit included), so that passages
   // invoking block widgets and widget bodies using other block widgets
@@ -146,7 +157,7 @@ export function boot() {
     registerBlockMacro(name);
   }
 
-  const errors = validatePassages(storyData.passages, schema, storeVarMacros);
+  const errors = variableErrors(storyData, schema);
   // StoryInit's markup must be valid before it runs; the other passages are
   // validated once it has run, as it may define macros (see below).
   errors.push(...markupErrors(storyData, (p) => p.name === 'StoryInit'));
@@ -186,8 +197,12 @@ export function boot() {
   // storyinit after all state is settled (defaults + StoryInit + session)
   initializeStory(loadSession(storyData.ifid));
 
-  // Every other passage's markup, now that StoryInit may have defined macros
-  const markup = markupErrors(storyData, (p) => p.name !== 'StoryInit');
+  // Every other passage's markup, now that StoryInit may have defined macros;
+  // so are the variable references, which macros' parameters decide
+  const markup = [
+    ...variableErrors(storyData, schema),
+    ...markupErrors(storyData, (p) => p.name !== 'StoryInit'),
+  ];
   if (markup.length > 0) stopWithErrors(markup);
 
   // Pass 2: Full parse and register widgets from passages tagged "widget"

package/src/saves/save-manager.ts

@@ -291,10 +291,12 @@ export const createSave = queued(createSaveNow);
 
 async function createSaveNow(
   ifid: string,
-  playthroughId: string,
+  playthroughPromise: string | PromiseLike<string>,
   payload: SavePayload,
   custom: Record<string, unknown> = {},
 ): Promise<SaveRecord> {
+  const playthroughId = await playthroughPromise;
+  if (!playthroughId) throw new Error('No playthrough');
   const now = new Date().toISOString();
   const meta: SaveMeta = {
     id: randomUUID(),
@@ -313,6 +315,10 @@ async function createSaveNow(
 }
 
 /**
+ * A playthrough passed as a promise (see resolvePlaythroughId) is awaited
+ * inside the operation, so the call takes its place in the order of
+ * operations when it is made.
+ *
  * Replace the payload of an existing save, keeping its ID and `createdAt`.
  * Pass the current `playthroughId` when the new payload comes from the
  * running game: the save then holds that playthrough's state, so it is
@@ -333,8 +339,9 @@ async function overwriteSaveNow(
   saveId: string,
   payload: SavePayload,
   custom?: Record<string, unknown>,
-  playthroughId?: string,
+  playthroughPromise?: string | PromiseLike<string>,
 ): Promise<SaveRecord | undefined> {
+  const playthroughId = await playthroughPromise;
   const backend = await getBackend();
   const existing = await backend.getSave(saveId);
   if (!existing) return undefined;

package/src/store.ts

@@ -765,28 +765,39 @@ function writeHookChange(
     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, false, own(held));
+      writeKey(holder, key, own(held));
       return;
     }
     holder = child as Record<string, unknown>;
   }
   const key = path[depth]!;
-  if (change.deleted) writeKey(holder, key, true, undefined);
-  else writeKey(holder, key, false, own(change.value), change.appended);
+  if (change.deleted) writeKey(holder, key, undefined, change);
+  else writeKey(holder, key, own(change.value), change);
 }
 
 function writeKey(
   holder: Record<string, unknown>,
   key: string,
-  deleted: boolean,
   value: unknown,
-  appended?: boolean,
+  change?: PathChange,
 ): void {
+  const deleted = change?.deleted ?? false;
   if (Array.isArray(holder)) {
     const index = Number(key);
-    if (deleted) holder.length = Math.min(holder.length, index);
-    else if (appended) holder.push(value);
-    else if (index < holder.length) holder[index] = value;
+    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 {