@rohal12/spindle 0.17.0 → 0.19.0

package/src/saves/save-manager.ts

@@ -299,6 +299,49 @@ export async function loadQuickSave(
   return loadSave(existingId);
 }
 
+// --- Session Persistence (survives F5, cleared on tab close) ---
+
+const SESSION_KEY_PREFIX = 'spindle.session.';
+
+/**
+ * Write a pre-serialized session payload to sessionStorage.
+ * Callers are responsible for serializing variables (see persistSession in store.ts).
+ */
+export function saveSession(ifid: string, data: unknown): void {
+  try {
+    sessionStorage.setItem(
+      `${SESSION_KEY_PREFIX}${ifid}`,
+      JSON.stringify(data),
+    );
+  } catch {
+    // sessionStorage unavailable or full — silently ignore
+  }
+}
+
+export function loadSession(ifid: string): SavePayload | undefined {
+  try {
+    const raw = sessionStorage.getItem(`${SESSION_KEY_PREFIX}${ifid}`);
+    if (!raw) return undefined;
+    const payload: SavePayload = JSON.parse(raw);
+    payload.variables = deserialize(payload.variables);
+    payload.history = payload.history.map((m) => ({
+      ...m,
+      variables: deserialize(m.variables),
+    }));
+    return payload;
+  } catch {
+    return undefined;
+  }
+}
+
+export function clearSession(ifid: string): void {
+  try {
+    sessionStorage.removeItem(`${SESSION_KEY_PREFIX}${ifid}`);
+  } catch {
+    // ignore
+  }
+}
+
 // --- Export / Import ---
 
 export async function exportSave(

package/src/saves/types.ts

@@ -1,10 +1,17 @@
-import type { HistoryMoment } from '../store';
 import type { PRNGSnapshot } from '../prng';
 
+/** History moment as persisted in saves (full variable snapshots). */
+export interface SaveHistoryMoment {
+  passage: string;
+  variables: Record<string, unknown>;
+  timestamp: number;
+  prng?: PRNGSnapshot | null;
+}
+
 export interface SavePayload {
   passage: string;
   variables: Record<string, unknown>;
-  history: HistoryMoment[];
+  history: SaveHistoryMoment[];
   historyIndex: number;
   visitCounts?: Record<string, number>;
   renderCounts?: Record<string, number>;

package/src/store.ts

@@ -1,16 +1,25 @@
 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 { resetTriggers } from './triggers';
 import {
   initSaveSystem,
   startNewPlaythrough,
   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 +27,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 +183,6 @@ function restorePRNGFromMoment(moment: HistoryMoment | undefined): void {
 
 export interface HistoryMoment {
   passage: string;
-  variables: Record<string, unknown>;
   timestamp: number;
   prng?: PRNGSnapshot | null;
 }
@@ -46,9 +199,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 +222,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 +238,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 +260,7 @@ export const useStoryStore = create<StoryState>()(
       }
 
       const initialVars = deepClone(variableDefaults);
+      resetModuleState(deepClone(initialVars));
 
       set((state) => {
         state.storyData = storyData as StoryData;
@@ -107,7 +271,6 @@ export const useStoryStore = create<StoryState>()(
         state.history = [
           {
             passage: startPassage.name,
-            variables: deepClone(initialVars),
             timestamp: Date.now(),
           },
         ];
@@ -116,6 +279,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 +304,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) => {
@@ -230,7 +442,9 @@ export const useStoryStore = create<StoryState>()(
       if (!startPassage) return;
 
       resetPRNG();
+      resetTriggers();
       const initialVars = deepClone(variableDefaults);
+      resetModuleState(deepClone(initialVars));
 
       set((state) => {
         state.currentPassage = startPassage.name;
@@ -239,7 +453,6 @@ export const useStoryStore = create<StoryState>()(
         state.history = [
           {
             passage: startPassage.name,
-            variables: deepClone(initialVars),
             timestamp: Date.now(),
           },
         ];
@@ -248,7 +461,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 +478,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 +511,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 +538,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 +566,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

@@ -21,6 +21,8 @@ import {
   randomInt,
   snapshotPRNG,
 } from './prng';
+import { addTrigger, removeTrigger } from './triggers';
+import type { WatchOptions } from './triggers';
 
 export type { StoryAction };
 
@@ -41,12 +43,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;
@@ -65,8 +67,16 @@ export interface StoryAPI {
   on(event: 'actionsChanged', callback: ActionsChangedCallback): () => void;
   on(event: 'variableChanged', callback: VariableChangedCallback): () => void;
   waitForActions(): Promise<StoryAction[]>;
+  watch(
+    condition: string,
+    callbackOrOptions: (() => void) | WatchOptions,
+  ): () => void;
+  unwatch(name: string): void;
   random(): number;
   randomInt(min: number, max: number): number;
+  readonly config: {
+    maxHistory: number;
+  };
   readonly prng: {
     init(seed?: string, useEntropy?: boolean): void;
     isEnabled(): boolean;
@@ -120,12 +130,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 {
@@ -138,12 +149,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 {
@@ -258,6 +270,17 @@ function createStoryAPI(): StoryAPI {
       });
     },
 
+    watch(
+      condition: string,
+      callbackOrOptions: (() => void) | WatchOptions,
+    ): () => void {
+      return addTrigger(condition, callbackOrOptions);
+    },
+
+    unwatch(name: string): void {
+      removeTrigger(name);
+    },
+
     random(): number {
       return random();
     },
@@ -266,6 +289,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);