@rohal12/spindle 0.16.1 → 0.18.1

package/src/store.ts

@@ -1,7 +1,13 @@
 import { create } from 'zustand';
 import { immer } from 'zustand/middleware/immer';
+import {
+  enablePatches,
+  produceWithPatches,
+  applyPatches,
+  type Patch,
+} from 'immer';
 import type { StoryData } from './parser';
-import type { SavePayload } from './saves/types';
+import type { SavePayload, SaveHistoryMoment } from './saves/types';
 import { executeStoryInit } from './story-init';
 import {
   initSaveSystem,
@@ -9,8 +15,10 @@ import {
   getCurrentPlaythroughId,
   quickSave,
   loadQuickSave,
+  saveSession,
+  clearSession,
 } from './saves/save-manager';
-import { deepClone, deserialize } from './class-registry';
+import { deepClone, serialize, deserialize } from './class-registry';
 import {
   snapshotPRNG,
   restorePRNG,
@@ -18,6 +26,151 @@ import {
   type PRNGSnapshot,
 } from './prng';
 
+enablePatches();
+
+const SPECIAL_PASSAGES = new Set([
+  'StoryInit',
+  'StoryInterface',
+  'StoryVariables',
+  'SaveTitle',
+  'PassageReady',
+  'PassageHeader',
+  'PassageFooter',
+  'PassageDone',
+]);
+
+// ---------------------------------------------------------------------------
+// Patch-based variable history (module-level, outside Zustand)
+// ---------------------------------------------------------------------------
+
+interface PatchEntry {
+  forward: Patch[];
+  inverse: Patch[];
+}
+
+/** Full variable snapshot at history index 0. */
+let variableBase: Record<string, unknown> = {};
+
+/**
+ * Transitions between consecutive history moments.
+ * patchEntries[i] transforms the variables at moment i into those at moment i+1.
+ * Length is always history.length − 1.
+ */
+let patchEntries: PatchEntry[] = [];
+
+/** Immer-produced reference to variables right after the last navigation. */
+let lastNavigationVars: Record<string, unknown> = {};
+
+/** Deep-clone patch values so they are independent of future mutations. */
+function clonePatches(patches: Patch[]): Patch[] {
+  return patches.map((p) => ({
+    ...p,
+    value: p.value !== undefined ? deepClone(p.value) : undefined,
+  }));
+}
+
+/** Compute forward + inverse patches that transform `prev` into `curr`. */
+function computeVarPatches(
+  prev: Record<string, unknown>,
+  curr: Record<string, unknown>,
+): PatchEntry {
+  const [, forward, inverse] = produceWithPatches(prev, (draft) => {
+    const d = draft as Record<string, unknown>;
+    for (const key of Object.keys(d)) {
+      if (!(key in curr)) delete d[key];
+    }
+    for (const [key, val] of Object.entries(curr)) {
+      d[key] = val;
+    }
+  });
+  return { forward: clonePatches(forward), inverse: clonePatches(inverse) };
+}
+
+/** Reconstruct variables at a given history moment by replaying patches. */
+function reconstructVarsAt(index: number): Record<string, unknown> {
+  let vars: Record<string, unknown> = variableBase;
+  for (let i = 0; i < index; i++) {
+    vars = applyPatches(vars, patchEntries[i]!.forward);
+  }
+  return vars;
+}
+
+// ---------------------------------------------------------------------------
+// Session persistence (sessionStorage — survives F5, cleared on tab close)
+// ---------------------------------------------------------------------------
+
+let serializedHistory: unknown[] = [];
+
+function persistSession(get: () => StoryState): void {
+  const {
+    storyData,
+    currentPassage,
+    variables,
+    history,
+    historyIndex,
+    visitCounts,
+    renderCounts,
+  } = get();
+  if (!storyData) return;
+
+  // Trim cache when history was truncated (goBack then navigate)
+  if (serializedHistory.length > history.length) {
+    serializedHistory.length = history.length;
+  }
+
+  // Append new entries
+  if (serializedHistory.length < history.length) {
+    const gap = history.length - serializedHistory.length;
+    if (gap === 1) {
+      // Common path: one new moment at the end — use current variables directly
+      const i = history.length - 1;
+      serializedHistory[i] = {
+        passage: history[i]!.passage,
+        variables: serialize(variables),
+        timestamp: history[i]!.timestamp,
+        prng: history[i]!.prng,
+      };
+    } else {
+      // Bulk fill (after loadFromPayload) — reconstruct incrementally
+      let vars = variableBase;
+      for (let i = 0; i < history.length; i++) {
+        if (i > 0) vars = applyPatches(vars, patchEntries[i - 1]!.forward);
+        if (i >= serializedHistory.length) {
+          const v = i === history.length - 1 ? variables : vars;
+          serializedHistory[i] = {
+            passage: history[i]!.passage,
+            variables: serialize(v),
+            timestamp: history[i]!.timestamp,
+            prng: history[i]!.prng,
+          };
+        }
+      }
+    }
+  }
+
+  saveSession(storyData.ifid, {
+    passage: currentPassage,
+    variables: serialize(variables),
+    history: serializedHistory,
+    historyIndex,
+    visitCounts,
+    renderCounts,
+    prng: snapshotPRNG(),
+  });
+}
+
+/** Reset all module-level state (called on init, restart, loadFromPayload). */
+function resetModuleState(base: Record<string, unknown>): void {
+  variableBase = base;
+  patchEntries = [];
+  lastNavigationVars = base;
+  serializedHistory = [];
+}
+
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+
 /** Restore or reset PRNG from a history moment's snapshot. */
 function restorePRNGFromMoment(moment: HistoryMoment | undefined): void {
   if (moment?.prng) {
@@ -29,7 +182,6 @@ function restorePRNGFromMoment(moment: HistoryMoment | undefined): void {
 
 export interface HistoryMoment {
   passage: string;
-  variables: Record<string, unknown>;
   timestamp: number;
   prng?: PRNGSnapshot | null;
 }
@@ -46,9 +198,11 @@ export interface StoryState {
   renderCounts: Record<string, number>;
   saveVersion: number;
   playthroughId: string;
+  maxHistory: number;
   saveError: string | null;
   loadError: string | null;
 
+  setMaxHistory: (limit: number) => void;
   init: (
     storyData: StoryData,
     variableDefaults?: Record<string, unknown>,
@@ -67,6 +221,7 @@ export interface StoryState {
   hasSave: (slot?: string) => boolean;
   getSavePayload: () => SavePayload;
   loadFromPayload: (payload: SavePayload) => void;
+  getHistoryVariables: (index: number) => Record<string, unknown>;
 }
 
 export const useStoryStore = create<StoryState>()(
@@ -82,9 +237,16 @@ export const useStoryStore = create<StoryState>()(
     renderCounts: {},
     saveVersion: 0,
     playthroughId: '',
+    maxHistory: 40,
     saveError: null,
     loadError: null,
 
+    setMaxHistory: (limit: number) => {
+      set((state) => {
+        state.maxHistory = Math.max(1, Math.round(limit));
+      });
+    },
+
     init: (
       storyData: StoryData,
       variableDefaults: Record<string, unknown> = {},
@@ -97,6 +259,7 @@ export const useStoryStore = create<StoryState>()(
       }
 
       const initialVars = deepClone(variableDefaults);
+      resetModuleState(deepClone(initialVars));
 
       set((state) => {
         state.storyData = storyData as StoryData;
@@ -107,7 +270,6 @@ export const useStoryStore = create<StoryState>()(
         state.history = [
           {
             passage: startPassage.name,
-            variables: deepClone(initialVars),
             timestamp: Date.now(),
           },
         ];
@@ -116,6 +278,9 @@ export const useStoryStore = create<StoryState>()(
         state.renderCounts = { [startPassage.name]: 1 };
       });
 
+      // Update lastNavigationVars to the Immer-produced reference
+      lastNavigationVars = get().variables;
+
       // Init save system (fire-and-forget — DB will be ready before user opens dialog)
       const ifid = storyData.ifid;
       initSaveSystem()
@@ -138,57 +303,103 @@ export const useStoryStore = create<StoryState>()(
     },
 
     navigate: (passageName: string) => {
-      const { storyData } = get();
+      const { storyData, variables: currVars } = get();
       if (!storyData) return;
 
+      if (SPECIAL_PASSAGES.has(passageName)) {
+        console.error(
+          `spindle: Cannot navigate to special passage "${passageName}".`,
+        );
+        return;
+      }
+
       if (!storyData.passages.has(passageName)) {
         console.error(`spindle: Passage "${passageName}" not found.`);
         return;
       }
 
+      // Compute variable delta before Immer set()
+      const patchEntry = computeVarPatches(lastNavigationVars, currVars);
+
       set((state) => {
         state.temporary = {};
         state.currentPassage = passageName;
 
         // Truncate forward history if we navigated back then chose a new path
         state.history = state.history.slice(0, state.historyIndex + 1);
+        patchEntries.length = state.historyIndex;
 
+        // Push new transition and moment
+        patchEntries.push(patchEntry);
         state.history.push({
           passage: passageName,
-          variables: deepClone(state.variables),
           timestamp: Date.now(),
           prng: snapshotPRNG(),
         });
+
+        // Trim oldest entries if over the limit
+        const overflow = state.history.length - state.maxHistory;
+        if (overflow > 0) {
+          // Advance base through trimmed transitions
+          for (let i = 0; i < overflow; i++) {
+            variableBase = applyPatches(variableBase, patchEntries[i]!.forward);
+          }
+          state.history = state.history.slice(overflow);
+          patchEntries = patchEntries.slice(overflow);
+          serializedHistory = serializedHistory.slice(overflow);
+        }
+
         state.historyIndex = state.history.length - 1;
         state.visitCounts[passageName] =
           (state.visitCounts[passageName] ?? 0) + 1;
         state.renderCounts[passageName] =
           (state.renderCounts[passageName] ?? 0) + 1;
       });
+
+      lastNavigationVars = get().variables;
+      persistSession(get);
     },
 
     goBack: () => {
+      const { historyIndex, variables } = get();
+      if (historyIndex <= 0) return;
+
+      // Apply inverse transition: moment historyIndex → historyIndex−1
+      const restoredVars = deepClone(
+        applyPatches(variables, patchEntries[historyIndex - 1]!.inverse),
+      );
+
       set((state) => {
-        if (state.historyIndex <= 0) return;
         state.historyIndex--;
-        const moment = state.history[state.historyIndex]!;
-        state.currentPassage = moment.passage;
-        state.variables = deepClone(moment.variables);
+        state.currentPassage = state.history[state.historyIndex]!.passage;
+        state.variables = restoredVars;
         state.temporary = {};
       });
+
+      lastNavigationVars = get().variables;
       restorePRNGFromMoment(get().history[get().historyIndex]);
+      persistSession(get);
     },
 
     goForward: () => {
+      const { historyIndex, history: hist, variables } = get();
+      if (historyIndex >= hist.length - 1) return;
+
+      // Apply forward transition: moment historyIndex → historyIndex+1
+      const restoredVars = deepClone(
+        applyPatches(variables, patchEntries[historyIndex]!.forward),
+      );
+
       set((state) => {
-        if (state.historyIndex >= state.history.length - 1) return;
         state.historyIndex++;
-        const moment = state.history[state.historyIndex]!;
-        state.currentPassage = moment.passage;
-        state.variables = deepClone(moment.variables);
+        state.currentPassage = state.history[state.historyIndex]!.passage;
+        state.variables = restoredVars;
         state.temporary = {};
       });
+
+      lastNavigationVars = get().variables;
       restorePRNGFromMoment(get().history[get().historyIndex]);
+      persistSession(get);
     },
 
     setVariable: (name: string, value: unknown) => {
@@ -231,6 +442,7 @@ export const useStoryStore = create<StoryState>()(
 
       resetPRNG();
       const initialVars = deepClone(variableDefaults);
+      resetModuleState(deepClone(initialVars));
 
       set((state) => {
         state.currentPassage = startPassage.name;
@@ -239,7 +451,6 @@ export const useStoryStore = create<StoryState>()(
         state.history = [
           {
             passage: startPassage.name,
-            variables: deepClone(initialVars),
             timestamp: Date.now(),
           },
         ];
@@ -248,7 +459,9 @@ export const useStoryStore = create<StoryState>()(
         state.renderCounts = { [startPassage.name]: 1 };
       });
 
+      lastNavigationVars = get().variables;
       executeStoryInit();
+      clearSession(storyData.ifid);
 
       // Start a new playthrough on restart
       startNewPlaythrough(storyData.ifid)
@@ -263,27 +476,10 @@ export const useStoryStore = create<StoryState>()(
     },
 
     save: () => {
-      const {
-        storyData,
-        playthroughId,
-        currentPassage,
-        variables,
-        history,
-        historyIndex,
-        visitCounts,
-        renderCounts,
-      } = get();
+      const { storyData, playthroughId } = get();
       if (!storyData) return;
 
-      const payload: SavePayload = {
-        passage: currentPassage,
-        variables: deepClone(variables),
-        history: deepClone(history),
-        historyIndex,
-        visitCounts: { ...visitCounts },
-        renderCounts: { ...renderCounts },
-        prng: snapshotPRNG(),
-      };
+      const payload = get().getSavePayload();
 
       set((state) => {
         state.saveError = null;
@@ -313,20 +509,7 @@ export const useStoryStore = create<StoryState>()(
       loadQuickSave(storyData.ifid)
         .then((payload) => {
           if (!payload) return;
-          set((state) => {
-            state.currentPassage = payload.passage;
-            state.variables = payload.variables;
-            state.history = payload.history;
-            state.historyIndex = payload.historyIndex;
-            state.visitCounts = payload.visitCounts ?? {};
-            state.renderCounts = payload.renderCounts ?? {};
-            state.temporary = {};
-          });
-          if (payload.prng) {
-            restorePRNG(payload.prng.seed, payload.prng.pull);
-          } else {
-            resetPRNG();
-          }
+          get().loadFromPayload(payload);
         })
         .catch((err) => {
           console.error('spindle: failed to load quick save', err);
@@ -353,10 +536,26 @@ export const useStoryStore = create<StoryState>()(
         visitCounts,
         renderCounts,
       } = get();
+
+      // Reconstruct full variable snapshots from base + patches
+      const saveHistory: SaveHistoryMoment[] = [];
+      let vars = variableBase;
+      for (let i = 0; i < history.length; i++) {
+        if (i > 0) {
+          vars = applyPatches(vars, patchEntries[i - 1]!.forward);
+        }
+        saveHistory.push({
+          passage: history[i]!.passage,
+          variables: deepClone(vars),
+          timestamp: history[i]!.timestamp,
+          prng: history[i]!.prng,
+        });
+      }
+
       return {
         passage: currentPassage,
         variables: deepClone(variables),
-        history: deepClone(history),
+        history: saveHistory,
         historyIndex,
         visitCounts: { ...visitCounts },
         renderCounts: { ...renderCounts },
@@ -365,23 +564,55 @@ export const useStoryStore = create<StoryState>()(
     },
 
     loadFromPayload: (payload: SavePayload) => {
+      // Convert full snapshots to patch entries
+      const base = deserialize(payload.history[0]?.variables ?? {}) as Record<
+        string,
+        unknown
+      >;
+      const newPatchEntries: PatchEntry[] = [];
+
+      let prevVars: Record<string, unknown> = base;
+      for (let i = 1; i < payload.history.length; i++) {
+        const currVars = deserialize(payload.history[i]!.variables) as Record<
+          string,
+          unknown
+        >;
+        newPatchEntries.push(computeVarPatches(prevVars, currVars));
+        prevVars = currVars;
+      }
+
+      variableBase = deepClone(base);
+      patchEntries = newPatchEntries;
+      serializedHistory = [];
+
       set((state) => {
         state.currentPassage = payload.passage;
-        state.variables = deserialize(payload.variables);
+        state.variables = deserialize(payload.variables) as Record<
+          string,
+          unknown
+        >;
         state.history = payload.history.map((m) => ({
-          ...m,
-          variables: deserialize(m.variables),
+          passage: m.passage,
+          timestamp: m.timestamp,
+          prng: m.prng,
         }));
         state.historyIndex = payload.historyIndex;
         state.visitCounts = payload.visitCounts ?? {};
         state.renderCounts = payload.renderCounts ?? {};
         state.temporary = {};
       });
+
+      lastNavigationVars = get().variables;
+
       if (payload.prng) {
         restorePRNG(payload.prng.seed, payload.prng.pull);
       } else {
         resetPRNG();
       }
     },
+
+    getHistoryVariables: (index: number): Record<string, unknown> => {
+      return deepClone(reconstructVarsAt(index));
+    },
   })),
 );

package/src/story-api.ts

@@ -4,6 +4,8 @@ import { settings } from './settings';
 import type { SavePayload } from './saves/types';
 import { setTitleGenerator } from './saves/save-manager';
 import { registerClass } from './class-registry';
+import { defineMacro } from './define-macro';
+import type { MacroDefinition } from './define-macro';
 import {
   getActions,
   getAction,
@@ -39,12 +41,12 @@ export interface StoryAPI {
   save(slot?: string): void;
   load(slot?: string): void;
   hasSave(slot?: string): boolean;
-  visited(name: string): number;
-  hasVisited(name: string): boolean;
+  visited(name?: string): number;
+  hasVisited(name?: string): boolean;
   hasVisitedAny(...names: string[]): boolean;
   hasVisitedAll(...names: string[]): boolean;
-  rendered(name: string): number;
-  hasRendered(name: string): boolean;
+  rendered(name?: string): number;
+  hasRendered(name?: string): boolean;
   hasRenderedAny(...names: string[]): boolean;
   hasRenderedAll(...names: string[]): boolean;
   currentPassage(): Passage | undefined;
@@ -53,6 +55,7 @@ export interface StoryAPI {
   readonly passage: string;
   readonly settings: typeof settings;
   registerClass(name: string, ctor: new (...args: any[]) => any): void;
+  defineMacro(config: MacroDefinition): void;
   readonly saves: {
     setTitleGenerator(fn: (payload: SavePayload) => string): void;
   };
@@ -64,6 +67,9 @@ export interface StoryAPI {
   waitForActions(): Promise<StoryAction[]>;
   random(): number;
   randomInt(min: number, max: number): number;
+  readonly config: {
+    maxHistory: number;
+  };
   readonly prng: {
     init(seed?: string, useEntropy?: boolean): void;
     isEnabled(): boolean;
@@ -117,12 +123,13 @@ function createStoryAPI(): StoryAPI {
       return useStoryStore.getState().hasSave(slot);
     },
 
-    visited(name: string): number {
-      return useStoryStore.getState().visitCounts[name] ?? 0;
+    visited(name?: string): number {
+      const state = useStoryStore.getState();
+      return state.visitCounts[name ?? state.currentPassage] ?? 0;
     },
 
-    hasVisited(name: string): boolean {
-      return (useStoryStore.getState().visitCounts[name] ?? 0) > 0;
+    hasVisited(name?: string): boolean {
+      return this.visited(name) > 0;
     },
 
     hasVisitedAny(...names: string[]): boolean {
@@ -135,12 +142,13 @@ function createStoryAPI(): StoryAPI {
       return names.every((n) => (visitCounts[n] ?? 0) > 0);
     },
 
-    rendered(name: string): number {
-      return useStoryStore.getState().renderCounts[name] ?? 0;
+    rendered(name?: string): number {
+      const state = useStoryStore.getState();
+      return state.renderCounts[name ?? state.currentPassage] ?? 0;
     },
 
-    hasRendered(name: string): boolean {
-      return (useStoryStore.getState().renderCounts[name] ?? 0) > 0;
+    hasRendered(name?: string): boolean {
+      return this.rendered(name) > 0;
     },
 
     hasRenderedAny(...names: string[]): boolean {
@@ -179,6 +187,10 @@ function createStoryAPI(): StoryAPI {
       registerClass(name, ctor);
     },
 
+    defineMacro(config: MacroDefinition): void {
+      defineMacro(config);
+    },
+
     saves: {
       setTitleGenerator(fn: (payload: SavePayload) => string): void {
         setTitleGenerator(fn);
@@ -259,6 +271,15 @@ function createStoryAPI(): StoryAPI {
       return randomInt(min, max);
     },
 
+    config: {
+      get maxHistory(): number {
+        return useStoryStore.getState().maxHistory;
+      },
+      set maxHistory(limit: number) {
+        useStoryStore.getState().setMaxHistory(limit);
+      },
+    },
+
     prng: {
       init(seed?: string, useEntropy?: boolean): void {
         initPRNG(seed, useEntropy);