@rohal12/spindle 0.51.3 → 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,
@@ -162,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);
@@ -180,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 } }
@@ -251,6 +279,7 @@ export async function renameSave(
     meta: {
       ...record.meta,
       title: newTitle,
+      userTitle: true,
       updatedAt: new Date().toISOString(),
     },
   };
@@ -431,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)
 // ---------------------------------------------------------------------------
@@ -502,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;
@@ -523,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) {
+          const id =
+            (await getCurrentPlaythroughId(ifid)) ??
+            (await startNewPlaythrough(ifid));
+          // A restart issued meanwhile has already switched playthroughs
+          if (generation === playthroughGeneration) {
             set((state) => {
-              state.playthroughId = existingId;
-            });
-          } else {
-            const newId = await startNewPlaythrough(ifid);
-            set((state) => {
-              state.playthroughId = newId;
+              state.playthroughId = id;
             });
           }
 
@@ -546,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) => {
@@ -774,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)
@@ -814,28 +867,20 @@ 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().beginSave, async (payload) => {
           set((state) => {
             state.saveError = null;
           });
+          const playthroughId = await playthrough;
           await quickSave(storyData.ifid, playthroughId, payload, slot, custom);
           set((state) => {
             state.knownSaves = {

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));
   }
 }
 

package/src/utils/object-path.ts

@@ -0,0 +1,109 @@
+import { isDraft } from 'immer';
+
+/** Traverse dot-path segments on an object and return the nested value. */
+export function getByPath(
+  obj: Record<string, unknown>,
+  segments: readonly string[],
+): unknown {
+  let current: unknown = obj;
+  for (const seg of segments) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[seg];
+  }
+  return current;
+}
+
+/**
+ * Shallow copy that keeps the prototype, so a registered class instance
+ * stays an instance of its class (with the same own keys deepClone copies).
+ */
+function shallowCopy(value: object): Record<string, unknown> {
+  let copy: object;
+  if (Array.isArray(value)) copy = [];
+  else if (value instanceof Map) copy = new Map(value);
+  else if (value instanceof Set) copy = new Set(value);
+  else if (value instanceof Date) copy = new Date(value.getTime());
+  else copy = Object.create(Object.getPrototypeOf(value)) as object;
+  return Object.assign(copy, value) as Record<string, unknown>;
+}
+
+export interface SetByPathOptions {
+  /**
+   * Create a plain object for a missing or non-object intermediate instead
+   * of throwing.
+   */
+  createMissing?: boolean;
+}
+
+/**
+ * Set a value at dot-path `segments` below `root`.
+ *
+ * When `root` is an Immer draft, objects Immer does not draft (registered
+ * class instances and everything below them) are copied on the way down and
+ * the copy is assigned to its parent, so the write produces new references
+ * up to the root. Writing into such an object directly would mutate the
+ * instance shared with the previous state and with history, and subscribers
+ * would see no change. Outside a draft (a private working copy) the path is
+ * written in place.
+ */
+export function setByPath(
+  root: Record<string, unknown>,
+  segments: readonly string[],
+  value: unknown,
+  options: SetByPathOptions = {},
+): void {
+  const parent = walkToParent(root, segments, options.createMissing ?? false);
+  parent[segments[segments.length - 1]!] = value;
+}
+
+/**
+ * Delete the property at dot-path `segments` below `root`, copying
+ * undrafted objects on the way down like setByPath(). Does nothing when an
+ * intermediate is missing or not an object, or the property is absent.
+ */
+export function deleteByPath(
+  root: Record<string, unknown>,
+  segments: readonly string[],
+): void {
+  const last = segments[segments.length - 1]!;
+  // Check first, so a no-op delete copies nothing.
+  const holder = getByPath(root, segments.slice(0, -1));
+  if (holder == null || typeof holder !== 'object' || !(last in holder)) {
+    return;
+  }
+  const parent = walkToParent(root, segments, false);
+  delete parent[last];
+}
+
+/**
+ * Walk to the object holding the last of `segments`, copying undrafted
+ * objects when `root` is an Immer draft (see setByPath). A missing or
+ * non-object intermediate is replaced by a plain object when
+ * `createMissing` is set, and throws a TypeError otherwise.
+ */
+function walkToParent(
+  root: Record<string, unknown>,
+  segments: readonly string[],
+  createMissing: boolean,
+): Record<string, unknown> {
+  const copyOnWrite = isDraft(root);
+  let current: Record<string, unknown> = root;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const seg = segments[i]!;
+    let next = current[seg];
+    if (next == null || typeof next !== 'object') {
+      if (!createMissing) {
+        throw new TypeError(
+          `spindle: Cannot set property "${segments[i + 1]}" on ${next === null ? 'null' : typeof next} (at "${segments.slice(0, i + 1).join('.')}")`,
+        );
+      }
+      next = {};
+      current[seg] = next;
+    } else if (copyOnWrite && !isDraft(next)) {
+      next = shallowCopy(next);
+      current[seg] = next;
+    }
+    current = next as Record<string, unknown>;
+  }
+  return current;
+}