@rohal12/spindle 0.31.2 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.31.2",
+  "version": "0.32.0",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",

package/src/components/macros/MenubarButtons.tsx

@@ -119,7 +119,7 @@ defineMenubarAction({
   setup: () => {
     const load = useStoryStore((s) => s.load);
     const hasSave = useStoryStore((s) => s.hasSave);
-    useStoryStore((s) => s.saveVersion);
+    useStoryStore((s) => s.knownSaves);
     return { perform: () => load(), disabled: !hasSave() };
   },
 });

package/src/saves/save-manager.ts

@@ -2,6 +2,7 @@ import type {
   SavePayload,
   SaveMeta,
   SaveRecord,
+  SaveInfo,
   PlaythroughRecord,
   SaveExport,
 } from './types';
@@ -134,6 +135,7 @@ export async function createSave(
 export async function overwriteSave(
   saveId: string,
   payload: SavePayload,
+  custom?: Record<string, unknown>,
 ): Promise<SaveRecord | undefined> {
   const existing = await getSave(saveId);
   if (!existing) return undefined;
@@ -149,6 +151,9 @@ export async function overwriteSave(
       ...existing.meta,
       updatedAt: new Date().toISOString(),
       passage: payload.passage,
+      ...(custom != null
+        ? { custom: { ...existing.meta.custom, ...custom } }
+        : {}),
     },
     payload: serializedPayload,
   };
@@ -258,33 +263,58 @@ export async function getSavesGrouped(
   return result;
 }
 
-// --- Quick Save ---
+// --- Quick Save / Slot Save ---
 
 const AUTOSAVE_KEY_PREFIX = 'autosave.';
+const SLOT_KEY_PREFIX = 'slot.';
+const SLOT_INDEX_KEY_PREFIX = 'slotIndex.';
+
+function slotMetaKey(ifid: string, slot?: string): string {
+  return slot != null
+    ? `${SLOT_KEY_PREFIX}${slot}.${ifid}`
+    : `${AUTOSAVE_KEY_PREFIX}${ifid}`;
+}
 
 export async function quickSave(
   ifid: string,
   playthroughId: string,
   payload: SavePayload,
+  slot?: string,
+  custom?: Record<string, unknown>,
 ): Promise<SaveRecord> {
-  const metaKey = `${AUTOSAVE_KEY_PREFIX}${ifid}`;
+  const metaKey = slotMetaKey(ifid, slot);
   const existingId = await getMeta<string>(metaKey);
 
   if (existingId) {
-    const updated = await overwriteSave(existingId, payload);
+    const updated = await overwriteSave(existingId, payload, custom);
     if (updated) return updated;
   }
 
-  // Create new autosave
+  // Create new save
   const record = await createSave(ifid, playthroughId, payload, {
-    isAutosave: true,
+    isAutosave: !slot,
+    ...(slot != null ? { slot } : {}),
+    ...custom,
   });
   await setMeta(metaKey, record.meta.id);
+
+  // Track named slots in the index
+  if (slot != null) {
+    const indexKey = `${SLOT_INDEX_KEY_PREFIX}${ifid}`;
+    const existing = (await getMeta<string[]>(indexKey)) ?? [];
+    if (!existing.includes(slot)) {
+      await setMeta(indexKey, [...existing, slot]);
+    }
+  }
+
   return record;
 }
 
-export async function hasQuickSave(ifid: string): Promise<boolean> {
-  const metaKey = `${AUTOSAVE_KEY_PREFIX}${ifid}`;
+export async function hasQuickSave(
+  ifid: string,
+  slot?: string,
+): Promise<boolean> {
+  const metaKey = slotMetaKey(ifid, slot);
   const existingId = await getMeta<string>(metaKey);
   if (!existingId) return false;
   const record = await getSave(existingId);
@@ -293,13 +323,107 @@ export async function hasQuickSave(ifid: string): Promise<boolean> {
 
 export async function loadQuickSave(
   ifid: string,
+  slot?: string,
 ): Promise<SavePayload | undefined> {
-  const metaKey = `${AUTOSAVE_KEY_PREFIX}${ifid}`;
+  const metaKey = slotMetaKey(ifid, slot);
   const existingId = await getMeta<string>(metaKey);
   if (!existingId) return undefined;
   return loadSave(existingId);
 }
 
+/**
+ * Check IDB for all known saves and return a map of slot keys to true.
+ * The default (autosave) slot uses empty string as key.
+ */
+export async function populateKnownSaves(
+  ifid: string,
+): Promise<Record<string, true>> {
+  const result: Record<string, true> = {};
+
+  // Check default autosave
+  if (await hasQuickSave(ifid)) {
+    result[''] = true;
+  }
+
+  // Check named slots from the index
+  const indexKey = `${SLOT_INDEX_KEY_PREFIX}${ifid}`;
+  const slots = (await getMeta<string[]>(indexKey)) ?? [];
+  for (const slot of slots) {
+    if (await hasQuickSave(ifid, slot)) {
+      result[slot] = true;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get metadata for a specific save slot.
+ * Returns null if no save exists for that slot.
+ */
+export async function getSlotSaveInfo(
+  ifid: string,
+  slot?: string,
+): Promise<SaveInfo | null> {
+  const metaKey = slotMetaKey(ifid, slot);
+  const existingId = await getMeta<string>(metaKey);
+  if (!existingId) return null;
+  const record = await getSave(existingId);
+  if (!record) return null;
+  return {
+    slot: slot ?? '',
+    title: record.meta.title,
+    passage: record.meta.passage,
+    createdAt: record.meta.createdAt,
+    updatedAt: record.meta.updatedAt,
+    custom: record.meta.custom ?? {},
+  };
+}
+
+/**
+ * List metadata for all known save slots (default + named).
+ */
+export async function listSlotSaves(ifid: string): Promise<SaveInfo[]> {
+  const result: SaveInfo[] = [];
+
+  // Check default autosave
+  const defaultInfo = await getSlotSaveInfo(ifid);
+  if (defaultInfo) result.push(defaultInfo);
+
+  // Check named slots from the index
+  const indexKey = `${SLOT_INDEX_KEY_PREFIX}${ifid}`;
+  const slots = (await getMeta<string[]>(indexKey)) ?? [];
+  for (const slot of slots) {
+    const info = await getSlotSaveInfo(ifid, slot);
+    if (info) result.push(info);
+  }
+
+  return result;
+}
+
+/**
+ * Delete a save by slot name. Removes from slot index if named.
+ */
+export async function deleteSlotSave(
+  ifid: string,
+  slot?: string,
+): Promise<void> {
+  const metaKey = slotMetaKey(ifid, slot);
+  const existingId = await getMeta<string>(metaKey);
+  if (!existingId) return;
+
+  await idbDeleteSave(existingId);
+  await setMeta(metaKey, undefined);
+
+  // Remove from slot index if named
+  if (slot != null) {
+    const indexKey = `${SLOT_INDEX_KEY_PREFIX}${ifid}`;
+    const existing = (await getMeta<string[]>(indexKey)) ?? [];
+    const updated = existing.filter((s) => s !== slot);
+    await setMeta(indexKey, updated);
+  }
+}
+
 // --- Session Persistence (survives F5, cleared on tab close) ---
 
 const SESSION_KEY_PREFIX = 'spindle.session.';

package/src/saves/types.ts

@@ -41,6 +41,16 @@ export interface PlaythroughRecord {
   label: string;
 }
 
+/** Public-facing save metadata for the Story API. */
+export interface SaveInfo {
+  slot: string;
+  title: string;
+  passage: string;
+  createdAt: string;
+  updatedAt: string;
+  custom: Record<string, unknown>;
+}
+
 export interface SaveExport {
   version: 1;
   ifid: string;

package/src/store.ts

@@ -8,7 +8,7 @@ import {
 } from 'immer';
 import type { StoryData } from './parser';
 import type { TransitionConfig } from './transition';
-import type { SavePayload, SaveHistoryMoment } from './saves/types';
+import type { SavePayload, SaveHistoryMoment, SaveInfo } from './saves/types';
 import { executeStoryInit } from './story-init';
 import { resetTriggers } from './triggers';
 import {
@@ -17,6 +17,10 @@ import {
   getCurrentPlaythroughId,
   quickSave,
   loadQuickSave,
+  populateKnownSaves,
+  getSlotSaveInfo,
+  listSlotSaves,
+  deleteSlotSave,
   saveSession,
   clearSession,
 } from './saves/save-manager';
@@ -198,7 +202,7 @@ export interface StoryState {
   historyIndex: number;
   visitCounts: Record<string, number>;
   renderCounts: Record<string, number>;
-  saveVersion: number;
+  knownSaves: Record<string, true>;
   playthroughId: string;
   maxHistory: number;
   saveError: string | null;
@@ -221,9 +225,12 @@ export interface StoryState {
   deleteTemporary: (name: string) => void;
   trackRender: (passageName: string) => void;
   restart: () => void;
-  save: (slot?: string) => void;
+  save: (slot?: string, custom?: Record<string, unknown>) => void;
   load: (slot?: string) => void;
   hasSave: (slot?: string) => boolean;
+  getSaveInfo: (slot?: string) => Promise<SaveInfo | null>;
+  listSaves: () => Promise<SaveInfo[]>;
+  deleteSave: (slot?: string) => void;
   getSavePayload: () => SavePayload;
   loadFromPayload: (payload: SavePayload) => void;
   getHistoryVariables: (index: number) => Record<string, unknown>;
@@ -243,7 +250,7 @@ export const useStoryStore = create<StoryState>()(
     historyIndex: -1,
     visitCounts: {},
     renderCounts: {},
-    saveVersion: 0,
+    knownSaves: {},
     playthroughId: '',
     maxHistory: 40,
     saveError: null,
@@ -307,6 +314,14 @@ export const useStoryStore = create<StoryState>()(
               state.playthroughId = newId;
             });
           }
+
+          // Populate knownSaves from IDB so hasSave() works after reload
+          const saves = await populateKnownSaves(ifid);
+          if (Object.keys(saves).length > 0) {
+            set((state) => {
+              state.knownSaves = saves;
+            });
+          }
         })
         .catch((err) =>
           console.error('spindle: failed to init save system', err),
@@ -487,7 +502,7 @@ export const useStoryStore = create<StoryState>()(
         );
     },
 
-    save: () => {
+    save: (slot?: string, custom?: Record<string, unknown>) => {
       const { storyData, playthroughId } = get();
       if (!storyData) return;
 
@@ -496,14 +511,17 @@ export const useStoryStore = create<StoryState>()(
       set((state) => {
         state.saveError = null;
       });
-      quickSave(storyData.ifid, playthroughId, payload)
+      quickSave(storyData.ifid, playthroughId, payload, slot, custom)
         .then(() => {
           set((state) => {
-            state.saveVersion++;
+            state.knownSaves = {
+              ...state.knownSaves,
+              [slot ?? '']: true,
+            };
           });
         })
         .catch((err) => {
-          console.error('spindle: failed to quick save', err);
+          console.error('spindle: failed to save', err);
           set((state) => {
             state.saveError =
               err instanceof Error ? err.message : 'Failed to save';
@@ -511,20 +529,20 @@ export const useStoryStore = create<StoryState>()(
         });
     },
 
-    load: () => {
+    load: (slot?: string) => {
       const { storyData } = get();
       if (!storyData) return;
 
       set((state) => {
         state.loadError = null;
       });
-      loadQuickSave(storyData.ifid)
+      loadQuickSave(storyData.ifid, slot)
         .then((payload) => {
           if (!payload) return;
           get().loadFromPayload(payload);
         })
         .catch((err) => {
-          console.error('spindle: failed to load quick save', err);
+          console.error('spindle: failed to load save', err);
           set((state) => {
             state.loadError =
               err instanceof Error ? err.message : 'Failed to load';
@@ -532,11 +550,39 @@ export const useStoryStore = create<StoryState>()(
         });
     },
 
-    hasSave: () => {
-      // Synchronous: return true if a save has been made this session
-      const { storyData, saveVersion } = get();
+    hasSave: (slot?: string) => {
+      const { storyData, knownSaves } = get();
       if (!storyData) return false;
-      return saveVersion > 0;
+      return (slot ?? '') in knownSaves;
+    },
+
+    getSaveInfo: async (slot?: string): Promise<SaveInfo | null> => {
+      const { storyData } = get();
+      if (!storyData) return null;
+      return getSlotSaveInfo(storyData.ifid, slot);
+    },
+
+    listSaves: async (): Promise<SaveInfo[]> => {
+      const { storyData } = get();
+      if (!storyData) return [];
+      return listSlotSaves(storyData.ifid);
+    },
+
+    deleteSave: (slot?: string) => {
+      const { storyData } = get();
+      if (!storyData) return;
+
+      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);
+        });
     },
 
     getSavePayload: (): SavePayload => {

package/src/story-api.ts

@@ -1,7 +1,7 @@
 import { useStoryStore } from './store';
 import type { Passage } from './parser';
 import { settings } from './settings';
-import type { SavePayload } from './saves/types';
+import type { SavePayload, SaveInfo } from './saves/types';
 import { setTitleGenerator } from './saves/save-manager';
 import { registerClass } from './class-registry';
 import { defineMacro } from './define-macro';
@@ -48,9 +48,12 @@ export interface StoryAPI {
   back(): void;
   forward(): void;
   restart(): void;
-  save(slot?: string): void;
+  save(slot?: string, custom?: Record<string, unknown>): void;
   load(slot?: string): void;
   hasSave(slot?: string): boolean;
+  getSaveInfo(slot?: string): Promise<SaveInfo | null>;
+  listSaves(): Promise<SaveInfo[]>;
+  deleteSave(slot?: string): void;
   visited(name?: string): number;
   hasVisited(name?: string): boolean;
   hasVisitedAny(...names: string[]): boolean;
@@ -137,8 +140,8 @@ function createStoryAPI(): StoryAPI {
       useStoryStore.getState().restart();
     },
 
-    save(slot?: string): void {
-      useStoryStore.getState().save(slot);
+    save(slot?: string, custom?: Record<string, unknown>): void {
+      useStoryStore.getState().save(slot, custom);
     },
 
     load(slot?: string): void {
@@ -149,6 +152,18 @@ function createStoryAPI(): StoryAPI {
       return useStoryStore.getState().hasSave(slot);
     },
 
+    getSaveInfo(slot?: string): Promise<SaveInfo | null> {
+      return useStoryStore.getState().getSaveInfo(slot);
+    },
+
+    listSaves(): Promise<SaveInfo[]> {
+      return useStoryStore.getState().listSaves();
+    },
+
+    deleteSave(slot?: string): void {
+      useStoryStore.getState().deleteSave(slot);
+    },
+
     visited(name?: string): number {
       const state = useStoryStore.getState();
       return state.visitCounts[name ?? state.currentPassage] ?? 0;

package/types/index.d.ts

@@ -102,6 +102,25 @@ export interface Passage {
   content: string;
 }
 
+/**
+ * Metadata about a save slot, returned by `getSaveInfo()` and `listSaves()`.
+ * @see {@link ../../src/saves/types.ts} for the implementation.
+ */
+export interface SaveInfo {
+  /** Slot name (empty string for the default autosave slot). */
+  slot: string;
+  /** Save title (generated or custom). */
+  title: string;
+  /** Passage name at the time of saving. */
+  passage: string;
+  /** ISO 8601 timestamp when the save was first created. */
+  createdAt: string;
+  /** ISO 8601 timestamp when the save was last updated. */
+  updatedAt: string;
+  /** Custom metadata passed when saving. */
+  custom: Record<string, unknown>;
+}
+
 /**
  * The main Story API available as `window.Story` at runtime.
  * Provides access to variables, navigation, save/load, and visit tracking.
@@ -128,8 +147,8 @@ export interface StoryAPI {
   /** Restart the story from the beginning. */
   restart(): void;
 
-  /** Save the current state (quick save). */
-  save(slot?: string): void;
+  /** Save the current state. Pass `slot` for a named save, `custom` for metadata. */
+  save(slot?: string, custom?: Record<string, unknown>): void;
 
   /** Load a saved state (quick load). */
   load(slot?: string): void;
@@ -137,6 +156,15 @@ export interface StoryAPI {
   /** Check whether a save exists. */
   hasSave(slot?: string): boolean;
 
+  /** Get metadata for a specific save slot. Returns null if no save exists. */
+  getSaveInfo(slot?: string): Promise<SaveInfo | null>;
+
+  /** List metadata for all known save slots. */
+  listSaves(): Promise<SaveInfo[]>;
+
+  /** Delete a save by slot name. */
+  deleteSave(slot?: string): void;
+
   /** Return the number of times a passage has been visited. */
   visited(name: string): number;