@rohal12/spindle 0.51.2 → 0.51.4

package/src/markup/tokenizer.ts

@@ -231,9 +231,13 @@ function parseHtmlAttributes(
     const attrName = input.slice(attrStart, j);
     if (!attrName) break;
 
-    // Check for = value
-    if (input[j] === '=') {
-      j++; // skip =
+    // Check for = value. HTML allows whitespace on either side of the =
+    // (`id = "x"`); whitespace not followed by = ends a boolean attribute.
+    let eqIdx = j;
+    while (eqIdx < input.length && /\s/.test(input[eqIdx]!)) eqIdx++;
+    if (input[eqIdx] === '=') {
+      j = eqIdx + 1; // skip =
+      while (j < input.length && /\s/.test(input[j]!)) j++;
       if (input[j] === '"' || input[j] === "'") {
         const quote = input[j]!;
         j++; // skip opening quote
@@ -395,12 +399,22 @@ export function tokenize(input: string): Token[] {
   }
 
   while (i < input.length) {
-    // Handle escaped braces: \{ and \}
-    if (input[i] === '\\' && (input[i + 1] === '{' || input[i + 1] === '}')) {
-      flushText(i);
-      tokens.push({ type: 'text', value: input[i + 1]!, start: i, end: i + 2 });
-      i += 2;
-      textStart = i;
+    // Escaped braces: \{ and \}. Count the whole backslash run so \\{ is a
+    // backslash pair before a live brace. In an odd run the last backslash
+    // escapes the brace; the even rest stays text, which markdown collapses
+    // pair by pair like any other \\ in the passage.
+    if (input[i] === '\\') {
+      let k = i + 1;
+      while (input[k] === '\\') k++;
+      const next = input[k];
+      if ((next === '{' || next === '}') && (k - i) % 2 === 1) {
+        flushText(k - 1);
+        tokens.push({ type: 'text', value: next, start: k - 1, end: k + 1 });
+        i = k + 1;
+        textStart = i;
+        continue;
+      }
+      i = k;
       continue;
     }
 

package/src/saves/save-manager.ts

@@ -71,12 +71,19 @@ export async function initSaveSystem(): Promise<void> {
 
 // --- Playthroughs ---
 
-export async function startNewPlaythrough(ifid: string): Promise<string> {
+/**
+ * Store a new playthrough and make it the story's current one. Pass `id` when
+ * the caller has already switched to the playthrough (restart() does, so
+ * saves issued before this resolves are tagged with it).
+ */
+export async function startNewPlaythrough(
+  ifid: string,
+  id: string = crypto.randomUUID(),
+): Promise<string> {
   const backend = await getBackend();
   const existing = await backend.getPlaythroughsByIfid(ifid);
   const num = existing.length + 1;
 
-  const id = crypto.randomUUID();
   const record: PlaythroughRecord = {
     id,
     ifid,
@@ -99,9 +106,13 @@ export async function getCurrentPlaythroughId(
 
 /**
  * Run a save through the `beforesave` / `aftersave` hooks. `beforesave` fires
- * before `getPayload()` captures the state, so data a hook sets is part of the
- * save; `aftersave` fires once `write` has stored it. Every user-facing save
- * path goes through here.
+ * before the payload is captured, so data a hook sets is part of the save;
+ * `aftersave` fires once `write` has stored it. Every user-facing save path
+ * goes through here.
+ *
+ * `beginCapture` is called just before the hooks and returns the function
+ * that captures the payload after them, so the capture can tell which
+ * variables the hooks changed (the store's `beginSave`).
  *
  * The hook and capture run synchronously, but an error they throw (a failing
  * hook, an unserializable payload) rejects the returned promise like a failed
@@ -110,12 +121,13 @@ export async function getCurrentPlaythroughId(
 export function saveWithHooks<T>(
   slot: string | undefined,
   custom: Record<string, unknown> | undefined,
-  getPayload: () => SavePayload,
+  beginCapture: () => () => SavePayload,
   write: (payload: SavePayload) => Promise<T>,
 ): Promise<T> {
   try {
+    const capture = beginCapture();
     emit('beforesave', slot, custom);
-    const payload = getPayload();
+    const payload = capture();
     return write(payload).then((result) => {
       emit('aftersave', slot);
       return result;
@@ -157,10 +169,26 @@ export async function createSave(
   return record;
 }
 
+/**
+ * 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
+ * grouped and deleted with it rather than with the playthrough that first
+ * created the save.
+ *
+ * Metadata describing the content follows the new payload: `passage`,
+ * `updatedAt` and the title. A generated title (SaveTitle passage, title
+ * generator or the default "passage - time") is generated again, exactly as
+ * for a fresh save, so it never names a passage or state the save no longer
+ * holds. A title the player gave the save (renameSave) is kept: it names the
+ * save itself rather than describing its content. `custom` is merged, as
+ * before, so slot keys and metadata not passed again are kept.
+ */
 export async function overwriteSave(
   saveId: string,
   payload: SavePayload,
   custom?: Record<string, unknown>,
+  playthroughId?: string,
 ): Promise<SaveRecord | undefined> {
   const backend = await getBackend();
   const existing = await backend.getSave(saveId);
@@ -175,7 +203,12 @@ export async function overwriteSave(
   const updated: SaveRecord = {
     meta: {
       ...existing.meta,
+      ...(playthroughId ? { playthroughId } : {}),
       updatedAt: new Date().toISOString(),
+      title:
+        existing.meta.userTitle === true
+          ? existing.meta.title
+          : generateTitle(payload),
       passage: payload.passage,
       ...(custom != null
         ? { custom: { ...existing.meta.custom, ...custom } }
@@ -246,6 +279,7 @@ export async function renameSave(
     meta: {
       ...record.meta,
       title: newTitle,
+      userTitle: true,
       updatedAt: new Date().toISOString(),
     },
   };
@@ -426,7 +460,12 @@ export function quickSave(
     const existingId = await backend.getMeta<string>(metaKey);
 
     if (existingId) {
-      const updated = await overwriteSave(existingId, payload, custom);
+      const updated = await overwriteSave(
+        existingId,
+        payload,
+        custom,
+        playthroughId,
+      );
       if (updated) return updated;
     }
 

package/src/saves/storage.ts

@@ -154,6 +154,14 @@ export function createLocalStorageBackend(): StorageBackend {
 
     async putSave(record: SaveRecord): Promise<void> {
       const id = record.meta.id;
+      // A save rewritten under another playthrough (an overwrite after a
+      // restart) leaves its old playthrough's index
+      const previous = lsGet<SaveRecord>(`${LS_SAVE_PREFIX}${id}`);
+      if (previous && previous.meta.playthroughId !== record.meta.playthroughId)
+        lsIndexRemove(
+          `${LS_IDX_SAVES_PT_PREFIX}${previous.meta.playthroughId}`,
+          id,
+        );
       lsSet(`${LS_SAVE_PREFIX}${id}`, record);
       lsIndexAdd(`${LS_IDX_SAVES_PREFIX}${record.meta.ifid}`, id);
       lsIndexAdd(`${LS_IDX_SAVES_PT_PREFIX}${record.meta.playthroughId}`, id);

package/src/saves/types.ts

@@ -1,4 +1,5 @@
 import type { PRNGSnapshot } from '../prng';
+import { isDeserializable } from '../class-registry';
 
 /** History moment as persisted in saves (full variable snapshots). */
 export interface SaveHistoryMoment {
@@ -25,6 +26,11 @@ export interface SaveMeta {
   createdAt: string;
   updatedAt: string;
   title: string;
+  /**
+   * True once the player has named the save (renameSave). Overwriting the
+   * save keeps such a title; a generated one is generated anew.
+   */
+  userTitle?: boolean;
   passage: string;
   custom: Record<string, unknown>;
   estimatedBytes?: number;
@@ -97,11 +103,16 @@ function isOptionalPRNGSnapshot(value: unknown): boolean {
   );
 }
 
+/** A variable container whose values deserialize() can restore. */
+function isSerializedVariables(value: unknown): boolean {
+  return isRecord(value) && isDeserializable(value);
+}
+
 function isSaveHistoryMoment(value: unknown): value is SaveHistoryMoment {
   return (
     isRecord(value) &&
     typeof value.passage === 'string' &&
-    isRecord(value.variables) &&
+    isSerializedVariables(value.variables) &&
     typeof value.timestamp === 'number' &&
     isOptionalPRNGSnapshot(value.prng)
   );
@@ -109,14 +120,16 @@ function isSaveHistoryMoment(value: unknown): value is SaveHistoryMoment {
 
 /**
  * Full check of a payload from outside the running story (an imported save):
- * every history moment is well formed, and `historyIndex` is an integer that
- * points at a moment of the payload's passage. Anything that passes can be
- * stored and later loaded.
+ * every history moment is well formed, `historyIndex` is an integer that
+ * points at a moment of the payload's passage, and the encoded values (Map,
+ * Set, Date, RegExp, class instances) in the live variables and every
+ * moment's variables have the shape deserialize() expects. Anything that
+ * passes can be stored and later loaded.
  */
 function isImportablePayload(value: unknown): value is SavePayload {
   if (!isRecord(value)) return false;
   if (typeof value.passage !== 'string') return false;
-  if (!isRecord(value.variables)) return false;
+  if (!isSerializedVariables(value.variables)) return false;
 
   const { history, historyIndex } = value;
   if (!Array.isArray(history) || history.length === 0) return false;

package/src/store.ts

@@ -234,6 +234,34 @@ export function recordStoryInitState(): void {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Playthrough setup
+// ---------------------------------------------------------------------------
+
+/**
+ * Settles once the latest playthrough setup (init's lookup or creation, or a
+ * restart's creation) is stored, with that setup's playthrough ID ('' if
+ * init could not establish one). Each setup chains on the previous one, so
+ * playthroughs are created and numbered in the order the game started them.
+ */
+let playthroughSetup: Promise<string> = Promise.resolve('');
+
+/** Bumped by every init()/restart(); a stale init must not adopt its ID. */
+let playthroughGeneration = 0;
+
+/**
+ * The playthrough a save issued now belongs to, once its record is stored.
+ * Read synchronously at the call: restart() switches the store's
+ * `playthroughId` at once, so a save issued after it (even before the new
+ * playthrough is stored) belongs to the new playthrough, and a later restart
+ * doesn't move it. Before init() has looked up the stored playthrough the
+ * store's ID is '', and the save takes the one init establishes.
+ */
+export function resolvePlaythroughId(): Promise<string> {
+  const current = useStoryStore.getState().playthroughId;
+  return playthroughSetup.then((established) => current || established);
+}
+
 // ---------------------------------------------------------------------------
 // Runtime handler cleanup (auto-unsub on restart)
 // ---------------------------------------------------------------------------
@@ -297,6 +325,33 @@ function loadedEntryMoment(
   return moment;
 }
 
+/**
+ * Copy the variables that changed between `before` and `after` (the live
+ * variables around 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 payload's copy changes: the live
+ * history keeps the recorded snapshot (#159). Store updates are immutable, so
+ * a value a hook did not touch keeps its identity.
+ */
+function keepHookWrites(
+  payload: SavePayload,
+  before: Record<string, unknown>,
+  after: Record<string, unknown>,
+): void {
+  const moment = payload.history[payload.historyIndex];
+  if (!moment) return;
+  const has = (vars: Record<string, unknown>, key: string) =>
+    Object.prototype.hasOwnProperty.call(vars, key);
+  for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+    if (!has(after, key)) {
+      delete moment.variables[key];
+    } else if (!has(before, key) || after[key] !== before[key]) {
+      moment.variables[key] = deepClone(after[key]);
+    }
+  }
+}
+
 /** Restore or reset PRNG from a history moment's snapshot. */
 function restorePRNGFromMoment(moment: HistoryMoment | undefined): void {
   if (moment?.prng) {
@@ -384,6 +439,12 @@ export interface StoryState {
   clearAllData: () => void;
   deletePlaythrough: (playthroughId: string) => void;
   getSavePayload: () => SavePayload;
+  /**
+   * Start capturing a save, before the `beforesave` hooks run. The returned
+   * function builds the payload after them, and keeps the variables the
+   * hooks changed in the saved moment's snapshot, so a load restores them.
+   */
+  beginSave: () => () => SavePayload;
   /**
    * Replace the game state with a live (deserialized) payload. `slot` is
    * passed to the `beforeload`/`afterload` events.
@@ -469,6 +530,8 @@ export const useStoryStore = create<StoryState>()(
 
       set((state) => {
         state.storyData = storyData as StoryData;
+        // Unknown until the save system has looked it up (below)
+        state.playthroughId = '';
         state.currentPassage = startPassage.name;
         state.navigationId++;
         state.variables = initialVars;
@@ -490,19 +553,20 @@ export const useStoryStore = create<StoryState>()(
       // Update lastNavigationVars to the Immer-produced reference
       lastNavigationVars = get().variables;
 
-      // Init save system (fire-and-forget — DB will be ready before user opens dialog)
+      // Init save system in the background. Saves issued meanwhile wait for
+      // it (see resolvePlaythroughId), so they are tagged with the
+      // playthrough it establishes and recorded after the known saves.
       const ifid = storyData.ifid;
-      initSaveSystem()
+      const generation = ++playthroughGeneration;
+      playthroughSetup = initSaveSystem()
         .then(async () => {
-          const existingId = await getCurrentPlaythroughId(ifid);
-          if (existingId) {
-            set((state) => {
-              state.playthroughId = existingId;
-            });
-          } else {
-            const newId = await startNewPlaythrough(ifid);
+          const id =
+            (await getCurrentPlaythroughId(ifid)) ??
+            (await startNewPlaythrough(ifid));
+          // A restart issued meanwhile has already switched playthroughs
+          if (generation === playthroughGeneration) {
             set((state) => {
-              state.playthroughId = newId;
+              state.playthroughId = id;
             });
           }
 
@@ -513,10 +577,12 @@ export const useStoryStore = create<StoryState>()(
               state.knownSaves = saves;
             });
           }
+          return id;
         })
-        .catch((err) =>
-          console.error('spindle: failed to init save system', err),
-        );
+        .catch((err) => {
+          console.error('spindle: failed to init save system', err);
+          return '';
+        });
     },
 
     navigate: (passageName: string) => {
@@ -741,6 +807,26 @@ export const useStoryStore = create<StoryState>()(
 
       emit('beforerestart');
 
+      // Switch to the new playthrough now, after beforerestart (whose saves
+      // belong to the game being left) and before StoryInit, so every save
+      // issued from here on belongs to the new game. Storing its record is
+      // queued after the previous playthrough setup.
+      const newPlaythroughId = crypto.randomUUID();
+      ++playthroughGeneration;
+      set((state) => {
+        state.playthroughId = newPlaythroughId;
+      });
+      const ifid = storyData.ifid;
+      playthroughSetup = playthroughSetup
+        .then(() => startNewPlaythrough(ifid, newPlaythroughId))
+        .then(
+          () => newPlaythroughId,
+          (err) => {
+            console.error('spindle: failed to start new playthrough', err);
+            return newPlaythroughId;
+          },
+        );
+
       const keepDeferred = get().renderDeferred;
 
       // Clean up all runtime-phase handlers (after beforerestart has fired)
@@ -781,47 +867,28 @@ export const useStoryStore = create<StoryState>()(
       emit('storyinit');
       // The storyinit handlers' changes belong to the start moment too
       recordStoryInitState();
-
-      // Start a new playthrough on restart
-      startNewPlaythrough(storyData.ifid)
-        .then((newId) => {
-          set((state) => {
-            state.playthroughId = newId;
-          });
-        })
-        .catch((err) =>
-          console.error('spindle: failed to start new playthrough', err),
-        );
     },
 
     save: (slot?: string, custom?: Record<string, unknown>) => {
-      const { storyData, playthroughId } = get();
+      const { storyData } = get();
       if (!storyData) return Promise.resolve();
+      // The playthrough current now, not when the write runs
+      const playthrough = resolvePlaythroughId();
 
       return handled(
-        saveWithHooks(
-          slot,
-          custom,
-          () => get().getSavePayload(),
-          async (payload) => {
-            set((state) => {
-              state.saveError = null;
-            });
-            await quickSave(
-              storyData.ifid,
-              playthroughId,
-              payload,
-              slot,
-              custom,
-            );
-            set((state) => {
-              state.knownSaves = {
-                ...state.knownSaves,
-                [slot ?? '']: true,
-              };
-            });
-          },
-        ).catch((err) => {
+        saveWithHooks(slot, custom, get().beginSave, async (payload) => {
+          set((state) => {
+            state.saveError = null;
+          });
+          const playthroughId = await playthrough;
+          await quickSave(storyData.ifid, playthroughId, payload, slot, custom);
+          set((state) => {
+            state.knownSaves = {
+              ...state.knownSaves,
+              [slot ?? '']: true,
+            };
+          });
+        }).catch((err) => {
           console.error('spindle: failed to save', err);
           set((state) => {
             state.saveError =
@@ -997,6 +1064,15 @@ export const useStoryStore = create<StoryState>()(
       };
     },
 
+    beginSave: () => {
+      const before = get().variables;
+      return () => {
+        const payload = get().getSavePayload();
+        keepHookWrites(payload, before, get().variables);
+        return payload;
+      };
+    },
+
     loadFromPayload: (payload: SavePayload, slot?: string) => {
       if (payload.history.length === 0) {
         console.warn('loadFromPayload: rejecting payload with empty history');

package/src/story-api.ts

@@ -25,6 +25,13 @@ import {
 } from './saves/save-manager';
 import { getBackendType } from './saves/storage';
 import { registerClass } from './class-registry';
+import {
+  frozenCopy,
+  getActiveMutationScope,
+  mirrorWriteToActiveScopes,
+  runWithCommittedMutations,
+} from './execute-mutation';
+import { getByPath, setByPath } from './utils/object-path';
 import { defineMacro } from './define-macro';
 import type { MacroDefinition } from './define-macro';
 import { getMacroRegistry as _getMacroRegistry } from './registry';
@@ -116,37 +123,6 @@ function ensureVariableChangedSubscription(): void {
   });
 }
 
-/** Traverse a dot-delimited path on an object and return the value. */
-function getByPath(obj: Record<string, unknown>, path: string): unknown {
-  const segments = path.split('.');
-  let current: unknown = obj[segments[0]!];
-  for (let i = 1; i < segments.length; i++) {
-    if (current == null) return undefined;
-    current = (current as Record<string, unknown>)[segments[i]!];
-  }
-  return current;
-}
-
-/** Set a value at a dot-delimited path on an object (must be an Immer draft for mutation). */
-function setByPath(
-  obj: Record<string, unknown>,
-  path: string,
-  value: unknown,
-): void {
-  const segments = path.split('.');
-  let current: Record<string, unknown> = obj;
-  for (let i = 0; i < segments.length - 1; i++) {
-    const next = current[segments[i]!];
-    if (next == null || typeof next !== 'object') {
-      throw new TypeError(
-        `spindle: Cannot set property "${segments[i + 1]}" on ${typeof next} (at "${segments.slice(0, i + 1).join('.')}")`,
-      );
-    }
-    current = next as Record<string, unknown>;
-  }
-  current[segments[segments.length - 1]!] = value;
-}
-
 export interface StoryAPI {
   get(name: string): unknown;
   set(name: string, value: unknown): void;
@@ -292,7 +268,7 @@ function setOne(draft: VariableNamespaces, name: string, value: unknown): void {
   const namespace = isTransient ? draft.transient : draft.variables;
 
   if (key.includes('.')) {
-    setByPath(namespace, key, value);
+    setByPath(namespace, key.split('.'), value);
   } else {
     namespace[key] = value;
   }
@@ -302,49 +278,74 @@ function createStoryAPI(): StoryAPI {
   return {
     get(name: string): unknown {
       const { isTransient, key } = parseName(name);
-      const store = isTransient
-        ? useStoryStore.getState().transient
-        : useStoryStore.getState().variables;
-      return key.includes('.') ? getByPath(store, key) : store[key];
+      // Mutation code running now ({do}, ctx.mutate, watcher run actions)
+      // has pending writes in its working copy: read that, so the code sees
+      // its own changes. The value is a frozen copy, like the frozen store
+      // values returned otherwise, so writing to it cannot change the
+      // pending state outside the code's own assignments.
+      const scope = getActiveMutationScope();
+      const source = scope ?? useStoryStore.getState();
+      const namespace = isTransient ? source.transient : source.variables;
+      const value = key.includes('.')
+        ? getByPath(namespace, key.split('.'))
+        : namespace[key];
+      return scope ? frozenCopy(value) : value;
     },
 
     set(nameOrVars: string | Record<string, unknown>, value?: unknown): void {
-      const names =
-        typeof nameOrVars === 'string' ? [nameOrVars] : Object.keys(nameOrVars);
-      for (const name of names) {
+      const entries: [string, unknown][] =
+        typeof nameOrVars === 'string'
+          ? [[nameOrVars, value]]
+          : Object.entries(nameOrVars);
+      for (const [name] of entries) {
         const { isTransient, key } = parseName(name);
         warnIfUndeclared(isTransient, key);
       }
       // One store update for all keys, so watchers see them together
       useStoryStore.getState().updateVariables((draft) => {
-        if (typeof nameOrVars === 'string') {
-          setOne(draft, nameOrVars, value);
-        } else {
-          for (const [k, v] of Object.entries(nameOrVars)) {
-            setOne(draft, k, v);
-          }
+        for (const [k, v] of entries) setOne(draft, k, v);
+        // Mutation code running now ({do}, ctx.mutate, watcher run actions)
+        // works on copies of the namespaces and commits the paths it changed
+        // when it finishes. Apply the write to those copies too, so the code
+        // sees it and its commit keeps it in program order (#215). This runs
+        // inside the update, before watchers it triggers write.
+        for (const [k, v] of entries) {
+          const { isTransient, key } = parseName(k);
+          mirrorWriteToActiveScopes(
+            draft,
+            isTransient ? 'transient' : 'variables',
+            key.split('.'),
+            v,
+          );
         }
       });
     },
 
+    // Called from running mutation code, these commit the code's writes so
+    // far before they record, replace or save state, and the code goes on
+    // from the state they leave (see runWithCommittedMutations).
     goto(passageName: string): void {
-      useStoryStore.getState().navigate(passageName);
+      runWithCommittedMutations(() =>
+        useStoryStore.getState().navigate(passageName),
+      );
     },
 
     back(): void {
-      useStoryStore.getState().goBack();
+      runWithCommittedMutations(() => useStoryStore.getState().goBack());
     },
 
     forward(): void {
-      useStoryStore.getState().goForward();
+      runWithCommittedMutations(() => useStoryStore.getState().goForward());
     },
 
     restart(): void {
-      useStoryStore.getState().restart();
+      runWithCommittedMutations(() => useStoryStore.getState().restart());
     },
 
     save(slot?: string, custom?: Record<string, unknown>): Promise<void> {
-      return useStoryStore.getState().save(slot, custom);
+      return runWithCommittedMutations(() =>
+        useStoryStore.getState().save(slot, custom),
+      );
     },
 
     load(slot?: string): Promise<void> {

package/src/triggers.ts

@@ -1,5 +1,5 @@
 import { evaluate } from './expression';
-import { executeMutation } from './execute-mutation';
+import { executeMutation, runWithCommittedMutations } from './execute-mutation';
 import { useStoryStore } from './store';
 
 export interface WatchOptions {
@@ -149,7 +149,10 @@ function fireTrigger(trigger: Trigger): void {
   }
 
   if (options.goto) {
-    useStoryStore.getState().navigate(options.goto);
+    // A watcher fired by a Story.set in running code navigates after that
+    // code's writes so far, so they are part of the moment it leaves.
+    const passage = options.goto;
+    runWithCommittedMutations(() => useStoryStore.getState().navigate(passage));
   }
 }