@rohal12/spindle 0.31.3 → 0.32.1

package/package.json

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

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,
   };
@@ -275,12 +280,13 @@ export async function quickSave(
   playthroughId: string,
   payload: SavePayload,
   slot?: string,
+  custom?: Record<string, unknown>,
 ): Promise<SaveRecord> {
   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;
   }
 
@@ -288,6 +294,7 @@ export async function quickSave(
   const record = await createSave(ifid, playthroughId, payload, {
     isAutosave: !slot,
     ...(slot != null ? { slot } : {}),
+    ...custom,
   });
   await setMeta(metaKey, record.meta.id);
 
@@ -350,6 +357,73 @@ export async function populateKnownSaves(
   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 {
@@ -18,6 +18,9 @@ import {
   quickSave,
   loadQuickSave,
   populateKnownSaves,
+  getSlotSaveInfo,
+  listSlotSaves,
+  deleteSlotSave,
   saveSession,
   clearSession,
 } from './saves/save-manager';
@@ -222,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>;
@@ -496,7 +502,7 @@ export const useStoryStore = create<StoryState>()(
         );
     },
 
-    save: (slot?: string) => {
+    save: (slot?: string, custom?: Record<string, unknown>) => {
       const { storyData, playthroughId } = get();
       if (!storyData) return;
 
@@ -505,7 +511,7 @@ export const useStoryStore = create<StoryState>()(
       set((state) => {
         state.saveError = null;
       });
-      quickSave(storyData.ifid, playthroughId, payload, slot)
+      quickSave(storyData.ifid, playthroughId, payload, slot, custom)
         .then(() => {
           set((state) => {
             state.knownSaves = {
@@ -550,6 +556,35 @@ export const useStoryStore = create<StoryState>()(
       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 => {
       const {
         currentPassage,

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;