@rohal12/spindle 0.50.1 → 0.51.1

package/src/preact-store.ts

@@ -0,0 +1,50 @@
+/**
+ * Zustand's `create()` for Preact.
+ *
+ * Zustand's default entry (`zustand` / `zustand/react`) imports `react`, which
+ * Spindle doesn't depend on. Bundlers that alias `react` to `preact/compat`
+ * hide that, but the published headless entry keeps Zustand external and runs
+ * under plain Node resolution, where `react` doesn't exist. Building on the
+ * vanilla store and Preact's own hooks keeps `react` out of the module graph.
+ */
+import { useSyncExternalStore } from 'preact/compat';
+import { useCallback } from 'preact/hooks';
+import {
+  createStore,
+  type ExtractState,
+  type Mutate,
+  type StateCreator,
+  type StoreApi,
+  type StoreMutatorIdentifier,
+} from 'zustand/vanilla';
+
+/** A store API that is also a selector hook, like Zustand's bound stores. */
+export type UseBoundStore<S extends StoreApi<unknown>> = S & {
+  (): ExtractState<S>;
+  <U>(selector: (state: ExtractState<S>) => U): U;
+};
+
+const identity = <T>(value: T): T => value;
+
+function bindPreact<S extends StoreApi<unknown>>(api: S): UseBoundStore<S> {
+  function useBoundStore<U>(
+    selector: (state: ExtractState<S>) => U = identity as (
+      state: ExtractState<S>,
+    ) => U,
+  ): U {
+    const getSnapshot = useCallback(
+      () => selector(api.getState() as ExtractState<S>),
+      [selector],
+    );
+    return useSyncExternalStore(api.subscribe, getSnapshot);
+  }
+  return Object.assign(useBoundStore, api) as UseBoundStore<S>;
+}
+
+/** Curried `create<State>()(initializer)`, as in Zustand. */
+export function create<T>() {
+  return <Mos extends [StoreMutatorIdentifier, unknown][] = []>(
+    initializer: StateCreator<T, [], Mos>,
+  ): UseBoundStore<Mutate<StoreApi<T>, Mos>> =>
+    bindPreact(createStore<T>()(initializer));
+}

package/src/saves/save-manager.ts

@@ -7,7 +7,7 @@ import type {
   SaveExport,
   StorageInfo,
 } from './types';
-import { isSavePayload } from './types';
+import { isSaveExport, isSavePayload } from './types';
 import { getBackend, resetBackend } from './storage';
 import { deepClone, serialize, deserialize } from '../class-registry';
 import { emit } from '../event-emitter';
@@ -102,6 +102,10 @@ export async function getCurrentPlaythroughId(
  * 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.
+ *
+ * The hook and capture run synchronously, but an error they throw (a failing
+ * hook, an unserializable payload) rejects the returned promise like a failed
+ * write rather than escaping to the caller.
  */
 export function saveWithHooks<T>(
   slot: string | undefined,
@@ -109,12 +113,16 @@ export function saveWithHooks<T>(
   getPayload: () => SavePayload,
   write: (payload: SavePayload) => Promise<T>,
 ): Promise<T> {
-  emit('beforesave', slot, custom);
-  const payload = getPayload();
-  return write(payload).then((result) => {
-    emit('aftersave', slot);
-    return result;
-  });
+  try {
+    emit('beforesave', slot, custom);
+    const payload = getPayload();
+    return write(payload).then((result) => {
+      emit('aftersave', slot);
+      return result;
+    });
+  } catch (err) {
+    return Promise.reject(err);
+  }
 }
 
 // --- Save CRUD ---
@@ -204,8 +212,26 @@ export async function loadSave(
   return deserializePayload(record.payload);
 }
 
+/**
+ * Delete a save record. If the default slot or a named slot holds it, that
+ * slot is cleared as well (pointer and slot index), as `deleteSlotSave` would.
+ */
 export async function deleteSaveById(saveId: string): Promise<void> {
-  await (await getBackend()).deleteSave(saveId);
+  const backend = await getBackend();
+  const record = await backend.getSave(saveId);
+  await backend.deleteSave(saveId);
+  if (!record) return;
+
+  const ifid = record.meta.ifid;
+  const slots = [undefined, ...(await getIndexedSlots(ifid))];
+  for (const slot of slots) {
+    const metaKey = slotMetaKey(ifid, slot);
+    await withSlot(metaKey, async () => {
+      if ((await backend.getMeta<string>(metaKey)) !== saveId) return;
+      await backend.deleteMeta(metaKey);
+      await removeFromSlotIndex(ifid, slot);
+    });
+  }
 }
 
 export async function renameSave(
@@ -314,6 +340,25 @@ function slotMetaKey(ifid: string, slot?: string): string {
     : `${AUTOSAVE_KEY_PREFIX}${ifid}`;
 }
 
+/** Tail of each slot's operation queue, keyed by the slot's meta key. */
+const slotQueues = new Map<string, Promise<unknown>>();
+
+/**
+ * Run a complete operation on one slot (save, import, delete) after the ones
+ * already queued for it. Each operation reads the slot pointer and writes the
+ * record and pointer as a unit, so concurrent operations on the same slot
+ * apply in call order instead of each creating its own record.
+ */
+function withSlot<T>(metaKey: string, op: () => Promise<T>): Promise<T> {
+  const run = (slotQueues.get(metaKey) ?? Promise.resolve()).then(op);
+  const tail = run.catch(() => {});
+  slotQueues.set(metaKey, tail);
+  void tail.then(() => {
+    if (slotQueues.get(metaKey) === tail) slotQueues.delete(metaKey);
+  });
+  return run;
+}
+
 /** Tail of the queue that serializes slot index updates. */
 let slotIndexQueue: Promise<unknown> = Promise.resolve();
 
@@ -368,32 +413,34 @@ function toSaveInfo(record: SaveRecord, slot?: string): SaveInfo {
   };
 }
 
-export async function quickSave(
+export function quickSave(
   ifid: string,
   playthroughId: string,
   payload: SavePayload,
   slot?: string,
   custom?: Record<string, unknown>,
 ): Promise<SaveRecord> {
-  const backend = await getBackend();
   const metaKey = slotMetaKey(ifid, slot);
-  const existingId = await backend.getMeta<string>(metaKey);
+  return withSlot(metaKey, async () => {
+    const backend = await getBackend();
+    const existingId = await backend.getMeta<string>(metaKey);
 
-  if (existingId) {
-    const updated = await overwriteSave(existingId, payload, custom);
-    if (updated) return updated;
-  }
+    if (existingId) {
+      const updated = await overwriteSave(existingId, payload, custom);
+      if (updated) return updated;
+    }
 
-  // Create new save
-  const record = await createSave(ifid, playthroughId, payload, {
-    isAutosave: !isNamedSlot(slot),
-    ...(isNamedSlot(slot) ? { slot } : {}),
-    ...custom,
-  });
-  await backend.setMeta(metaKey, record.meta.id);
-  await addToSlotIndex(ifid, slot);
+    // Create new save
+    const record = await createSave(ifid, playthroughId, payload, {
+      isAutosave: !isNamedSlot(slot),
+      ...(isNamedSlot(slot) ? { slot } : {}),
+      ...custom,
+    });
+    await backend.setMeta(metaKey, record.meta.id);
+    await addToSlotIndex(ifid, slot);
 
-  return record;
+    return record;
+  });
 }
 
 export async function hasQuickSave(
@@ -425,7 +472,8 @@ export async function loadQuickSave(
 export async function populateKnownSaves(
   ifid: string,
 ): Promise<Record<string, true>> {
-  const result: Record<string, true> = {};
+  // No prototype, so a slot named '__proto__' is recorded as an entry
+  const result = Object.create(null) as Record<string, true>;
 
   // Check default autosave
   if (await hasQuickSave(ifid)) {
@@ -481,20 +529,19 @@ export async function listSlotSaves(ifid: string): Promise<SaveInfo[]> {
 /**
  * Delete a save by slot name. Removes from slot index if named.
  */
-export async function deleteSlotSave(
-  ifid: string,
-  slot?: string,
-): Promise<void> {
-  const backend = await getBackend();
+export function deleteSlotSave(ifid: string, slot?: string): Promise<void> {
   const metaKey = slotMetaKey(ifid, slot);
-  const existingId = await backend.getMeta<string>(metaKey);
-  if (!existingId) return;
+  return withSlot(metaKey, async () => {
+    const backend = await getBackend();
+    const existingId = await backend.getMeta<string>(metaKey);
+    if (!existingId) return;
 
-  await backend.deleteSave(existingId);
-  await backend.deleteMeta(metaKey);
+    await backend.deleteSave(existingId);
+    await backend.deleteMeta(metaKey);
 
-  // Remove from slot index if named
-  await removeFromSlotIndex(ifid, slot);
+    // Remove from slot index if named
+    await removeFromSlotIndex(ifid, slot);
+  });
 }
 
 // --- Session Persistence (survives F5, cleared on tab close) ---
@@ -569,6 +616,11 @@ async function prepareImport(
       `Save is from a different story (expected IFID ${ifid}, got ${data.ifid})`,
     );
   }
+  // Callers may pass parsed JSON; check the full structure before anything
+  // is stored or replaced
+  if (!isSaveExport(data)) {
+    throw new Error('Invalid save file format');
+  }
 
   const backend = await getBackend();
 
@@ -624,32 +676,34 @@ export async function exportSlotSave(
  * validation as `importSave` (version, IFID) and keeps the playthrough record
  * and slot index consistent.
  */
-export async function importSlotSave(
+export function importSlotSave(
   data: SaveExport,
   ifid: string,
   slot?: string,
 ): Promise<SaveInfo> {
-  const record = await prepareImport(data, ifid);
-
-  // The slot keys in `custom` describe where the save lives, so they follow
-  // the target slot rather than the slot the save was exported from.
-  const { slot: _exportedSlot, ...custom } = record.meta.custom ?? {};
-  record.meta.custom = {
-    ...custom,
-    isAutosave: !isNamedSlot(slot),
-    ...(isNamedSlot(slot) ? { slot } : {}),
-  };
-
-  const backend = await getBackend();
   const metaKey = slotMetaKey(ifid, slot);
-  const previousId = await backend.getMeta<string>(metaKey);
+  return withSlot(metaKey, async () => {
+    const record = await prepareImport(data, ifid);
+
+    // The slot keys in `custom` describe where the save lives, so they follow
+    // the target slot rather than the slot the save was exported from.
+    const { slot: _exportedSlot, ...custom } = record.meta.custom ?? {};
+    record.meta.custom = {
+      ...custom,
+      isAutosave: !isNamedSlot(slot),
+      ...(isNamedSlot(slot) ? { slot } : {}),
+    };
 
-  await backend.putSave(record);
-  await backend.setMeta(metaKey, record.meta.id);
-  await addToSlotIndex(ifid, slot);
-  if (previousId) await backend.deleteSave(previousId);
+    const backend = await getBackend();
+    const previousId = await backend.getMeta<string>(metaKey);
 
-  return toSaveInfo(record, slot);
+    await backend.putSave(record);
+    await backend.setMeta(metaKey, record.meta.id);
+    await addToSlotIndex(ifid, slot);
+    if (previousId) await backend.deleteSave(previousId);
+
+    return toSaveInfo(record, slot);
+  });
 }
 
 // --- Storage Management ---

package/src/saves/storage.ts

@@ -548,14 +548,28 @@ async function detectBackend(): Promise<StorageBackend> {
   return createMemoryBackend();
 }
 
-export async function getBackend(): Promise<StorageBackend> {
-  if (_backend) return _backend;
-  _backend = await detectBackend();
-  return _backend;
+/**
+ * Detection in flight. Concurrent first callers share it so they all get the
+ * same backend (the memory fallback makes a new, empty store per detection).
+ */
+let _backendPromise: Promise<StorageBackend> | null = null;
+
+export function getBackend(): Promise<StorageBackend> {
+  if (_backend) return Promise.resolve(_backend);
+  if (!_backendPromise) {
+    const pending = detectBackend().then((backend) => {
+      // A reset while detecting discards this result
+      if (_backendPromise === pending) _backend = backend;
+      return backend;
+    });
+    _backendPromise = pending;
+  }
+  return _backendPromise;
 }
 
 export function resetBackend(): void {
   _backend = null;
+  _backendPromise = null;
 }
 
 /**

package/src/saves/types.ts

@@ -78,15 +78,64 @@ export function isSaveExport(value: unknown): value is SaveExport {
   if (typeof meta.updatedAt !== 'string') return false;
   if (typeof meta.title !== 'string') return false;
 
-  const payload = save.payload as Record<string, unknown>;
-  if (typeof payload.passage !== 'string') return false;
-  if (!Array.isArray(payload.history) || payload.history.length === 0)
-    return false;
-  if (typeof payload.historyIndex !== 'number') return false;
-  if (typeof payload.variables !== 'object' || payload.variables === null)
+  return isImportablePayload(save.payload);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Absent, null, or a `{ seed, pull }` PRNG snapshot. */
+function isOptionalPRNGSnapshot(value: unknown): boolean {
+  if (value == null) return true;
+  return (
+    isRecord(value) &&
+    typeof value.seed === 'string' &&
+    typeof value.pull === 'number' &&
+    Number.isInteger(value.pull) &&
+    value.pull >= 0
+  );
+}
+
+function isSaveHistoryMoment(value: unknown): value is SaveHistoryMoment {
+  return (
+    isRecord(value) &&
+    typeof value.passage === 'string' &&
+    isRecord(value.variables) &&
+    typeof value.timestamp === 'number' &&
+    isOptionalPRNGSnapshot(value.prng)
+  );
+}
+
+/**
+ * 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.
+ */
+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;
+
+  const { history, historyIndex } = value;
+  if (!Array.isArray(history) || history.length === 0) return false;
+  if (!history.every(isSaveHistoryMoment)) return false;
+  if (
+    typeof historyIndex !== 'number' ||
+    !Number.isInteger(historyIndex) ||
+    historyIndex < 0 ||
+    historyIndex >= history.length
+  ) {
     return false;
+  }
+  if (history[historyIndex]!.passage !== value.passage) return false;
 
-  return true;
+  if (value.visitCounts !== undefined && !isRecord(value.visitCounts))
+    return false;
+  if (value.renderCounts !== undefined && !isRecord(value.renderCounts))
+    return false;
+  return isOptionalPRNGSnapshot(value.prng);
 }
 
 export function isSavePayload(value: unknown): value is SavePayload {

package/src/store.ts

@@ -1,4 +1,4 @@
-import { create } from 'zustand';
+import { create } from './preact-store';
 import { immer } from 'zustand/middleware/immer';
 import {
   enablePatches,
@@ -214,8 +214,10 @@ function resetModuleState(base: Record<string, unknown>): void {
 /**
  * Record the state StoryInit left behind as the start moment: its variable
  * snapshot (the history base) and PRNG state. Called by executeStoryInit()
- * after the StoryInit passage has rendered; init()/restart() record the
- * start moment before StoryInit runs. A no-op once the story has moved on.
+ * after the StoryInit passage has rendered, and again after the `storyinit`
+ * handlers have run at boot (unless a session was restored) and on restart;
+ * init()/restart() record the start moment before StoryInit runs. A no-op
+ * once the story has moved on.
  */
 export function recordStoryInitState(): void {
   const { history, historyIndex, variables } = useStoryStore.getState();
@@ -370,12 +372,12 @@ export interface StoryState {
   updateVariables: (recipe: (draft: VariableNamespaces) => void) => void;
   trackRender: (passageName: string) => void;
   restart: () => void;
-  save: (slot?: string, custom?: Record<string, unknown>) => void;
-  load: (slot?: string) => void;
+  save: (slot?: string, custom?: Record<string, unknown>) => Promise<void>;
+  load: (slot?: string) => Promise<void>;
   hasSave: (slot?: string) => boolean;
   getSaveInfo: (slot?: string) => Promise<SaveInfo | null>;
   listSaves: () => Promise<SaveInfo[]>;
-  deleteSave: (slot?: string) => void;
+  deleteSave: (slot?: string) => Promise<void>;
   exportSave: (slot?: string) => Promise<SaveExport | null>;
   importSave: (data: unknown, slot?: string) => Promise<SaveInfo>;
   clearGameData: () => void;
@@ -395,6 +397,17 @@ export interface StoryState {
   clearDeferredRender: () => void;
 }
 
+/**
+ * Return `p` marked as handled: a caller that ignores the result of a
+ * fire-and-forget operation (whose failure is already logged) gets no
+ * unhandled-rejection report, while a caller that awaits it still sees the
+ * error.
+ */
+function handled<T>(p: Promise<T>): Promise<T> {
+  p.catch(() => {});
+  return p;
+}
+
 export const useStoryStore = create<StoryState>()(
   immer((set, get) => ({
     storyData: null,
@@ -766,6 +779,8 @@ export const useStoryStore = create<StoryState>()(
       executeStoryInit();
       clearSession(storyData.ifid);
       emit('storyinit');
+      // The storyinit handlers' changes belong to the start moment too
+      recordStoryInitState();
 
       // Start a new playthrough on restart
       startNewPlaythrough(storyData.ifid)
@@ -781,58 +796,71 @@ export const useStoryStore = create<StoryState>()(
 
     save: (slot?: string, custom?: Record<string, unknown>) => {
       const { storyData, playthroughId } = get();
-      if (!storyData) return;
-
-      saveWithHooks(
-        slot,
-        custom,
-        () => get().getSavePayload(),
-        async (payload) => {
-          set((state) => {
-            state.saveError = null;
-          });
-          await quickSave(storyData.ifid, playthroughId, payload, slot, custom);
+      if (!storyData) return Promise.resolve();
+
+      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) => {
+          console.error('spindle: failed to save', err);
           set((state) => {
-            state.knownSaves = {
-              ...state.knownSaves,
-              [slot ?? '']: true,
-            };
+            state.saveError =
+              err instanceof Error ? err.message : 'Failed to save';
           });
-        },
-      ).catch((err) => {
-        console.error('spindle: failed to save', err);
-        set((state) => {
-          state.saveError =
-            err instanceof Error ? err.message : 'Failed to save';
-        });
-      });
+          throw err;
+        }),
+      );
     },
 
     load: (slot?: string) => {
       const { storyData } = get();
-      if (!storyData) return;
+      if (!storyData) return Promise.resolve();
 
       set((state) => {
         state.loadError = null;
       });
-      loadQuickSave(storyData.ifid, slot)
-        .then((payload) => {
-          if (!payload) return;
-          get().loadFromPayload(payload, slot);
-        })
-        .catch((err) => {
-          console.error('spindle: failed to load save', err);
-          set((state) => {
-            state.loadError =
-              err instanceof Error ? err.message : 'Failed to load';
-          });
-        });
+      return handled(
+        loadQuickSave(storyData.ifid, slot)
+          .then((payload) => {
+            if (!payload) return;
+            get().loadFromPayload(payload, slot);
+          })
+          .catch((err) => {
+            console.error('spindle: failed to load save', err);
+            set((state) => {
+              state.loadError =
+                err instanceof Error ? err.message : 'Failed to load';
+            });
+            throw err;
+          }),
+      );
     },
 
     hasSave: (slot?: string) => {
       const { storyData, knownSaves } = get();
       if (!storyData) return false;
-      return (slot ?? '') in knownSaves;
+      // Own entries only: slot names like 'constructor' are not inherited saves
+      return Object.prototype.hasOwnProperty.call(knownSaves, slot ?? '');
     },
 
     getSaveInfo: async (slot?: string): Promise<SaveInfo | null> => {
@@ -849,19 +877,22 @@ export const useStoryStore = create<StoryState>()(
 
     deleteSave: (slot?: string) => {
       const { storyData } = get();
-      if (!storyData) return;
+      if (!storyData) return Promise.resolve();
 
-      deleteSlotSave(storyData.ifid, slot)
-        .then(() => {
-          set((state) => {
-            const key = slot ?? '';
-            const { [key]: _, ...rest } = state.knownSaves;
-            state.knownSaves = rest as Record<string, true>;
-          });
-        })
-        .catch((err) => {
-          console.error('spindle: failed to delete save', err);
-        });
+      return handled(
+        deleteSlotSave(storyData.ifid, slot)
+          .then(() => {
+            set((state) => {
+              const key = slot ?? '';
+              const { [key]: _, ...rest } = state.knownSaves;
+              state.knownSaves = rest as Record<string, true>;
+            });
+          })
+          .catch((err) => {
+            console.error('spindle: failed to delete save', err);
+            throw err;
+          }),
+      );
     },
 
     exportSave: async (slot?: string): Promise<SaveExport | null> => {

package/src/story-api.ts

@@ -155,12 +155,12 @@ export interface StoryAPI {
   back(): void;
   forward(): void;
   restart(): void;
-  save(slot?: string, custom?: Record<string, unknown>): void;
-  load(slot?: string): void;
+  save(slot?: string, custom?: Record<string, unknown>): Promise<void>;
+  load(slot?: string): Promise<void>;
   hasSave(slot?: string): boolean;
   getSaveInfo(slot?: string): Promise<SaveInfo | null>;
   listSaves(): Promise<SaveInfo[]>;
-  deleteSave(slot?: string): void;
+  deleteSave(slot?: string): Promise<void>;
   exportSave(slot?: string): Promise<SaveExport | null>;
   importSave(data: unknown, slot?: string): Promise<SaveInfo>;
   visited(name?: string): number;
@@ -343,12 +343,12 @@ function createStoryAPI(): StoryAPI {
       useStoryStore.getState().restart();
     },
 
-    save(slot?: string, custom?: Record<string, unknown>): void {
-      useStoryStore.getState().save(slot, custom);
+    save(slot?: string, custom?: Record<string, unknown>): Promise<void> {
+      return useStoryStore.getState().save(slot, custom);
     },
 
-    load(slot?: string): void {
-      useStoryStore.getState().load(slot);
+    load(slot?: string): Promise<void> {
+      return useStoryStore.getState().load(slot);
     },
 
     hasSave(slot?: string): boolean {
@@ -363,8 +363,8 @@ function createStoryAPI(): StoryAPI {
       return useStoryStore.getState().listSaves();
     },
 
-    deleteSave(slot?: string): void {
-      useStoryStore.getState().deleteSave(slot);
+    deleteSave(slot?: string): Promise<void> {
+      return useStoryStore.getState().deleteSave(slot);
     },
 
     exportSave(slot?: string): Promise<SaveExport | null> {