Feature: expose save metadata (timestamp, passage, custom fields) via Story API

[rohal12]

Summary

The save-manager internally tracks rich metadata per save (SaveMeta — timestamp, passage name, custom fields), but none of this is exposed through the Story API. Games that build custom save/load UIs (rather than using the built-in menubar) have no way to display slot info like "Day 12 — Work Phase — saved 3:42 PM" without maintaining a parallel metadata store in localStorage.

Current state

SaveMeta in src/saves/types.ts already has:

interface SaveMeta {
  id: string;
  ifid: string;
  playthroughId: string;
  createdAt: string;
  updatedAt: string;
  title: string;
  passage: string;
  custom: Record<string, unknown>;
}

And createSave() accepts a custom parameter. But the public API surface is:

save(slot?: string): void;
load(slot?: string): void;
hasSave(slot?: string): boolean;

There's no way to:

• List existing saves or slots
• Read metadata (timestamp, passage, title, custom fields) for a save
• Pass custom metadata when saving (e.g. game day, phase, player name)
• Delete a specific save

Proposed API additions

// List saves with metadata (for rendering save/load UIs)
Story.listSaves(): Promise<SaveInfo[]>
// or for named slots:
Story.getSaveInfo(slot?: string): Promise<SaveInfo | null>

interface SaveInfo {
  slot: string;
  title: string;
  passage: string;
  createdAt: string;
  updatedAt: string;
  custom: Record<string, unknown>;
}

// Save with custom metadata
Story.save(slot?: string, custom?: Record<string, unknown>): void

// Delete a save
Story.deleteSave(slot?: string): void

The custom field is particularly valuable — games can stash their own display data (day number, phase, character name, playtime) at save time and read it back for the UI without maintaining a separate persistence layer.

Current workaround

Games must maintain a parallel metadata store (e.g. localStorage keyed by slot name) and keep it in sync with Spindle saves manually. This works but is fragile — the metadata can drift from the actual save state if one write succeeds and the other fails, or if saves are cleared through Spindle's own UI.

Related

• Story.save/load/hasSave ignore the slot parameter; hasSave uses session counter #96 — slot parameter is currently ignored in save/load/hasSave; fixing that is a prerequisite for slot-aware metadata