feat: expose save metadata via Story API (#97) (#99)

## Summary

- **`save(slot?, custom?)`**: Extended to accept custom metadata (e.g.
`{ day: 3, phase: 'morning' }`) that is stored alongside the save and
merged on overwrite
- **`getSaveInfo(slot?)`**: New async method returning `SaveInfo` (slot,
title, passage, createdAt, updatedAt, custom) for a specific slot
- **`listSaves()`**: New async method returning `SaveInfo[]` for all
known saves (default + named)
- **`deleteSave(slot?)`**: New method to delete a save and update
`knownSaves` cache
- **`SaveInfo`** type added to `types/index.d.ts` and
`pkg/types/index.d.ts`

Games building custom save/load UIs can now display slot metadata like
"Day 12 — Work Phase — saved 3:42 PM" without maintaining a parallel
persistence layer.

## Test plan

- [x] All 891 tests pass (12 new, no regressions)
- [x] New tests: getSlotSaveInfo (null/default/named/custom),
listSlotSaves (empty/all), deleteSlotSave
(named/default/populate-cleanup/no-op), quickSave custom metadata
(new/merge)
- [x] TypeScript compiles cleanly (`tsc --noEmit`)

Closes #97
release-npm
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: rohal12

docs/story-api.md

@@ -174,13 +174,14 @@ Set a one-shot transition for the next navigation only. Consumed automatically w
 {/do}
 ```
 
-### `Story.save(slot?)`
+### `Story.save(slot?, custom?)`
 
-Perform a quick save. When `slot` is provided, saves to a named slot instead of the default autosave slot.
+Perform a save. When `slot` is provided, saves to a named slot instead of the default autosave slot. Pass `custom` to attach metadata that can be retrieved later via `getSaveInfo()`.
 
 ```javascript
-Story.save(); // save to default slot
-Story.save('my-slot'); // save to named slot
+Story.save(); // default slot
+Story.save('my-slot'); // named slot
+Story.save('day-3', { day: 3, phase: 'morning' }); // with custom metadata
 ```
 
 ### `Story.load(slot?)`
@@ -201,6 +202,42 @@ Story.hasSave(); // check default slot
 Story.hasSave('my-slot'); // check named slot
 ```
 
+### `Story.getSaveInfo(slot?)`
+
+Returns a `Promise<SaveInfo | null>` with metadata for the given save slot.
+
+```javascript
+const info = await Story.getSaveInfo('my-slot');
+if (info) {
+  console.log(info.title); // "Room - 3:42 PM"
+  console.log(info.passage); // "Room"
+  console.log(info.updatedAt); // "2026-03-22T15:42:00.000Z"
+  console.log(info.custom); // { day: 3, phase: "morning" }
+}
+```
+
+The `SaveInfo` object contains: `slot`, `title`, `passage`, `createdAt`, `updatedAt`, `custom`.
+
+### `Story.listSaves()`
+
+Returns a `Promise<SaveInfo[]>` listing all known saves (default + named slots).
+
+```javascript
+const saves = await Story.listSaves();
+for (const save of saves) {
+  console.log(`${save.slot || 'autosave'}: ${save.title}`);
+}
+```
+
+### `Story.deleteSave(slot?)`
+
+Delete a save by slot name. Omit `slot` to delete the default autosave.
+
+```javascript
+Story.deleteSave(); // delete default save
+Story.deleteSave('my-slot'); // delete named slot
+```
+
 ### `Story.defineMacro(config)`
 
 Register a custom macro. See [Custom Macros](custom-macros.md) for full details.

pkg/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,15 +147,24 @@ 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;
 
   /** 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;
 

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,19 +280,21 @@ 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;
   }
 
   // Create new save
   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.';

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;

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,

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;