@rohal12/spindle 0.3.2 → 0.4.0

package/src/settings.ts

@@ -26,6 +26,7 @@ export type SettingDef =
 
 const definitions = new Map<string, SettingDef>();
 let values: Record<string, unknown> = {};
+let storageLoaded = false;
 
 function storageKey(): string {
   const storyData = useStoryStore.getState().storyData;
@@ -38,10 +39,19 @@ function persist(): void {
 }
 
 function loadFromStorage(): void {
+  if (storageLoaded) return;
+  storageLoaded = true;
   try {
     const raw = localStorage.getItem(storageKey());
     if (raw) {
-      values = { ...values, ...JSON.parse(raw) };
+      const parsed = JSON.parse(raw);
+      if (
+        typeof parsed === 'object' &&
+        parsed !== null &&
+        !Array.isArray(parsed)
+      ) {
+        values = { ...values, ...parsed };
+      }
     }
   } catch {
     // ignore corrupted data
@@ -77,6 +87,21 @@ export const settings = {
     return values[name];
   },
 
+  getToggle(name: string): boolean {
+    const v = values[name];
+    return typeof v === 'boolean' ? v : false;
+  },
+
+  getList(name: string): string {
+    const v = values[name];
+    return typeof v === 'string' ? v : '';
+  },
+
+  getRange(name: string): number {
+    const v = values[name];
+    return typeof v === 'number' ? v : 0;
+  },
+
   set(name: string, value: unknown): void {
     values[name] = value;
     persist();

package/src/store.ts

@@ -11,11 +11,27 @@ import {
   loadQuickSave,
 } from './saves/save-manager';
 import { deepClone, deserialize } from './class-registry';
+import {
+  snapshotPRNG,
+  restorePRNG,
+  resetPRNG,
+  type PRNGSnapshot,
+} from './prng';
+
+/** Restore or reset PRNG from a history moment's snapshot. */
+function restorePRNGFromMoment(moment: HistoryMoment | undefined): void {
+  if (moment?.prng) {
+    restorePRNG(moment.prng.seed, moment.prng.pull);
+  } else if (moment) {
+    resetPRNG();
+  }
+}
 
 export interface HistoryMoment {
   passage: string;
   variables: Record<string, unknown>;
   timestamp: number;
+  prng?: PRNGSnapshot | null;
 }
 
 export interface StoryState {
@@ -30,6 +46,8 @@ export interface StoryState {
   renderCounts: Record<string, number>;
   saveVersion: number;
   playthroughId: string;
+  saveError: string | null;
+  loadError: string | null;
 
   init: (
     storyData: StoryData,
@@ -64,6 +82,8 @@ export const useStoryStore = create<StoryState>()(
     renderCounts: {},
     saveVersion: 0,
     playthroughId: '',
+    saveError: null,
+    loadError: null,
 
     init: (
       storyData: StoryData,
@@ -98,19 +118,23 @@ export const useStoryStore = create<StoryState>()(
 
       // Init save system (fire-and-forget — DB will be ready before user opens dialog)
       const ifid = storyData.ifid;
-      initSaveSystem().then(async () => {
-        const existingId = await getCurrentPlaythroughId(ifid);
-        if (existingId) {
-          set((state) => {
-            state.playthroughId = existingId;
-          });
-        } else {
-          const newId = await startNewPlaythrough(ifid);
-          set((state) => {
-            state.playthroughId = newId;
-          });
-        }
-      });
+      initSaveSystem()
+        .then(async () => {
+          const existingId = await getCurrentPlaythroughId(ifid);
+          if (existingId) {
+            set((state) => {
+              state.playthroughId = existingId;
+            });
+          } else {
+            const newId = await startNewPlaythrough(ifid);
+            set((state) => {
+              state.playthroughId = newId;
+            });
+          }
+        })
+        .catch((err) =>
+          console.error('spindle: failed to init save system', err),
+        );
     },
 
     navigate: (passageName: string) => {
@@ -133,6 +157,7 @@ export const useStoryStore = create<StoryState>()(
           passage: passageName,
           variables: deepClone(state.variables),
           timestamp: Date.now(),
+          prng: snapshotPRNG(),
         });
         state.historyIndex = state.history.length - 1;
         state.visitCounts[passageName] =
@@ -146,22 +171,24 @@ export const useStoryStore = create<StoryState>()(
       set((state) => {
         if (state.historyIndex <= 0) return;
         state.historyIndex--;
-        const moment = state.history[state.historyIndex];
+        const moment = state.history[state.historyIndex]!;
         state.currentPassage = moment.passage;
         state.variables = deepClone(moment.variables);
         state.temporary = {};
       });
+      restorePRNGFromMoment(get().history[get().historyIndex]);
     },
 
     goForward: () => {
       set((state) => {
         if (state.historyIndex >= state.history.length - 1) return;
         state.historyIndex++;
-        const moment = state.history[state.historyIndex];
+        const moment = state.history[state.historyIndex]!;
         state.currentPassage = moment.passage;
         state.variables = deepClone(moment.variables);
         state.temporary = {};
       });
+      restorePRNGFromMoment(get().history[get().historyIndex]);
     },
 
     setVariable: (name: string, value: unknown) => {
@@ -202,6 +229,7 @@ export const useStoryStore = create<StoryState>()(
       const startPassage = storyData.passagesById.get(storyData.startNode);
       if (!startPassage) return;
 
+      resetPRNG();
       const initialVars = deepClone(variableDefaults);
 
       set((state) => {
@@ -223,11 +251,15 @@ export const useStoryStore = create<StoryState>()(
       executeStoryInit();
 
       // Start a new playthrough on restart
-      startNewPlaythrough(storyData.ifid).then((newId) => {
-        set((state) => {
-          state.playthroughId = newId;
-        });
-      });
+      startNewPlaythrough(storyData.ifid)
+        .then((newId) => {
+          set((state) => {
+            state.playthroughId = newId;
+          });
+        })
+        .catch((err) =>
+          console.error('spindle: failed to start new playthrough', err),
+        );
     },
 
     save: () => {
@@ -250,31 +282,59 @@ export const useStoryStore = create<StoryState>()(
         historyIndex,
         visitCounts: { ...visitCounts },
         renderCounts: { ...renderCounts },
+        prng: snapshotPRNG(),
       };
 
-      quickSave(storyData.ifid, playthroughId, payload).then(() => {
-        set((state) => {
-          state.saveVersion++;
-        });
+      set((state) => {
+        state.saveError = null;
       });
+      quickSave(storyData.ifid, playthroughId, payload)
+        .then(() => {
+          set((state) => {
+            state.saveVersion++;
+          });
+        })
+        .catch((err) => {
+          console.error('spindle: failed to quick save', err);
+          set((state) => {
+            state.saveError =
+              err instanceof Error ? err.message : 'Failed to save';
+          });
+        });
     },
 
     load: () => {
       const { storyData } = get();
       if (!storyData) return;
 
-      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 = {};
-        });
+      set((state) => {
+        state.loadError = null;
       });
+      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();
+          }
+        })
+        .catch((err) => {
+          console.error('spindle: failed to load quick save', err);
+          set((state) => {
+            state.loadError =
+              err instanceof Error ? err.message : 'Failed to load';
+          });
+        });
     },
 
     hasSave: () => {
@@ -300,6 +360,7 @@ export const useStoryStore = create<StoryState>()(
         historyIndex,
         visitCounts: { ...visitCounts },
         renderCounts: { ...renderCounts },
+        prng: snapshotPRNG(),
       };
     },
 
@@ -316,6 +377,11 @@ export const useStoryStore = create<StoryState>()(
         state.renderCounts = payload.renderCounts ?? {};
         state.temporary = {};
       });
+      if (payload.prng) {
+        restorePRNG(payload.prng.seed, payload.prng.pull);
+      } else {
+        resetPRNG();
+      }
     },
   })),
 );

package/src/story-api.ts

@@ -1,4 +1,5 @@
 import { useStoryStore } from './store';
+import type { Passage } from './parser';
 import { settings } from './settings';
 import type { SavePayload } from './saves/types';
 import { setTitleGenerator } from './saves/save-manager';
@@ -9,6 +10,15 @@ import {
   onActionsChanged,
   type StoryAction,
 } from './action-registry';
+import {
+  initPRNG,
+  isPRNGEnabled,
+  getPRNGSeed,
+  getPRNGPull,
+  random,
+  randomInt,
+  snapshotPRNG,
+} from './prng';
 
 export type { StoryAction };
 
@@ -37,6 +47,8 @@ export interface StoryAPI {
   hasRendered(name: string): boolean;
   hasRenderedAny(...names: string[]): boolean;
   hasRenderedAll(...names: string[]): boolean;
+  currentPassage(): Passage | undefined;
+  previousPassage(): Passage | undefined;
   readonly title: string;
   readonly passage: string;
   readonly settings: typeof settings;
@@ -50,6 +62,14 @@ export interface StoryAPI {
   on(event: 'actionsChanged', callback: ActionsChangedCallback): () => void;
   on(event: 'variableChanged', callback: VariableChangedCallback): () => void;
   waitForActions(): Promise<StoryAction[]>;
+  random(): number;
+  randomInt(min: number, max: number): number;
+  readonly prng: {
+    init(seed?: string, useEntropy?: boolean): void;
+    isEnabled(): boolean;
+    readonly seed: string;
+    readonly pull: number;
+  };
 }
 
 function createStoryAPI(): StoryAPI {
@@ -133,6 +153,18 @@ function createStoryAPI(): StoryAPI {
       return names.every((n) => (renderCounts[n] ?? 0) > 0);
     },
 
+    currentPassage(): Passage | undefined {
+      const state = useStoryStore.getState();
+      return state.storyData?.passages.get(state.currentPassage);
+    },
+
+    previousPassage(): Passage | undefined {
+      const state = useStoryStore.getState();
+      if (state.historyIndex <= 0) return undefined;
+      const prevName = state.history[state.historyIndex - 1]?.passage;
+      return prevName ? state.storyData?.passages.get(prevName) : undefined;
+    },
+
     get title(): string {
       return useStoryStore.getState().storyData?.name || '';
     },
@@ -218,6 +250,37 @@ function createStoryAPI(): StoryAPI {
         });
       });
     },
+
+    random(): number {
+      return random();
+    },
+
+    randomInt(min: number, max: number): number {
+      return randomInt(min, max);
+    },
+
+    prng: {
+      init(seed?: string, useEntropy?: boolean): void {
+        initPRNG(seed, useEntropy);
+        // Update current history moment's snapshot via immer
+        const { historyIndex } = useStoryStore.getState();
+        useStoryStore.setState((state) => {
+          const moment = state.history[historyIndex];
+          if (moment) {
+            moment.prng = snapshotPRNG();
+          }
+        });
+      },
+      isEnabled(): boolean {
+        return isPRNGEnabled();
+      },
+      get seed(): string {
+        return getPRNGSeed();
+      },
+      get pull(): number {
+        return getPRNGPull();
+      },
+    },
   };
 }
 

package/src/story-variables.ts

@@ -16,6 +16,8 @@ const DECLARATION_RE = /^\$(\w+)\s*=\s*(.+)$/;
 const VAR_REF_RE = /\$(\w+(?:\.\w+)*)/g;
 const FOR_LOCAL_RE = /\{for\s+(\$\w+)(?:\s*,\s*(\$\w+))?\s+of\b/g;
 
+const VALID_VAR_TYPES = new Set<string>(['number', 'string', 'boolean']);
+
 function inferSchema(value: unknown): FieldSchema {
   if (Array.isArray(value)) {
     return { type: 'array' };
@@ -27,7 +29,13 @@ function inferSchema(value: unknown): FieldSchema {
     }
     return { type: 'object', fields };
   }
-  return { type: typeof value as VarType };
+  const jsType = typeof value;
+  if (!VALID_VAR_TYPES.has(jsType)) {
+    throw new Error(
+      `StoryVariables: Unsupported type "${jsType}" for value ${String(value)}. Expected number, string, boolean, array, or object.`,
+    );
+  }
+  return { type: jsType as VarType };
 }
 
 /**
@@ -50,7 +58,7 @@ export function parseStoryVariables(
       );
     }
 
-    const [, name, expr] = match;
+    const [, name, expr] = match as [string, string, string];
     let value: unknown;
     try {
       value = new Function('return (' + expr + ')')();
@@ -77,8 +85,8 @@ function extractForLocals(content: string): Set<string> {
   let match: RegExpExecArray | null;
   FOR_LOCAL_RE.lastIndex = 0;
   while ((match = FOR_LOCAL_RE.exec(content)) !== null) {
-    locals.add(match[1].slice(1)); // strip $
-    if (match[2]) locals.add(match[2].slice(1));
+    locals.add(match[1]!.slice(1)); // strip $
+    if (match[2]) locals.add(match[2]!.slice(1));
   }
   return locals;
 }
@@ -93,7 +101,7 @@ function validateRef(
   forLocals: Set<string>,
 ): string | null {
   const parts = ref.split('.');
-  const rootName = parts[0];
+  const rootName = parts[0]!;
 
   // Skip for-loop locals
   if (forLocals.has(rootName)) return null;
@@ -107,12 +115,13 @@ function validateRef(
   let current: FieldSchema = rootSchema;
   for (let i = 1; i < parts.length; i++) {
     // Arrays have a .length property
-    if (current.type === 'array' && parts[i] === 'length') return null;
+    const part = parts[i] as string;
+    if (current.type === 'array' && part === 'length') return null;
 
     if (current.type !== 'object' || !current.fields) {
-      return `Cannot access field "${parts[i]}" on $${parts.slice(0, i).join('.')} (type: ${current.type})`;
+      return `Cannot access field "${part}" on $${parts.slice(0, i).join('.')} (type: ${current.type})`;
     }
-    const fieldSchema = current.fields.get(parts[i]);
+    const fieldSchema = current.fields.get(part);
     if (!fieldSchema) {
       // Unknown fields on objects are allowed — classes registered via
       // Story.registerClass() can add methods/getters not in the defaults.
@@ -143,7 +152,7 @@ export function validatePassages(
     let match: RegExpExecArray | null;
     VAR_REF_RE.lastIndex = 0;
     while ((match = VAR_REF_RE.exec(passage.content)) !== null) {
-      const ref = match[1];
+      const ref = match[1]!;
       const error = validateRef(ref, schema, forLocals);
       if (error) {
         errors.push(`Passage "${name}": ${error}`);