@rohal12/spindle 0.44.0 → 0.45.0

package/types/index.d.ts

@@ -359,6 +359,54 @@ export interface SaveInfo {
   custom: Record<string, unknown>;
 }
 
+/**
+ * Metadata stored with each save record.
+ * @see {@link ../../src/saves/types.ts} for the implementation.
+ */
+export interface SaveMeta {
+  /** Unique save ID. */
+  id: string;
+  /** IFID of the story that created the save. */
+  ifid: string;
+  /** Playthrough the save belongs to. */
+  playthroughId: string;
+  /** ISO 8601 timestamp when the save was first created. */
+  createdAt: string;
+  /** ISO 8601 timestamp when the save was last updated. */
+  updatedAt: string;
+  /** Save title (generated or custom). */
+  title: string;
+  /** Passage name at the time of saving. */
+  passage: string;
+  /** Custom metadata passed when saving. */
+  custom: Record<string, unknown>;
+  /** Estimated size of the stored payload in bytes. */
+  estimatedBytes?: number;
+}
+
+/**
+ * A stored save: metadata plus the serialized payload.
+ * @see {@link ../../src/saves/types.ts} for the implementation.
+ */
+export interface SaveRecord {
+  meta: SaveMeta;
+  payload: SavePayload;
+}
+
+/**
+ * Portable save file produced by `exportSave()` and accepted by `importSave()`.
+ * Plain JSON: `JSON.stringify` it to write a file, `JSON.parse` to read one back.
+ * @see {@link ../../src/saves/types.ts} for the implementation.
+ */
+export interface SaveExport {
+  version: 1;
+  /** IFID of the story the save belongs to. Imports into other stories are rejected. */
+  ifid: string;
+  /** ISO 8601 timestamp of the export. */
+  exportedAt: string;
+  save: SaveRecord;
+}
+
 /**
  * The main Story API available as `window.Story` at runtime.
  * Provides access to variables, navigation, save/load, and visit tracking.
@@ -411,6 +459,21 @@ export interface StoryAPI {
   /** Delete a save by slot name. */
   deleteSave(slot?: string): void;
 
+  /**
+   * Export the save in a slot as a portable object (plain JSON).
+   * Resolves to null if the slot is empty.
+   * @example const data = await Story.exportSave('slot-1'); // JSON.stringify(data) to download
+   */
+  exportSave(slot?: string): Promise<SaveExport | null>;
+
+  /**
+   * Import an exported save into a slot, replacing whatever the slot held.
+   * Rejects if `data` is not a save export or belongs to a different story (IFID).
+   * Resolves to the slot's new metadata.
+   * @example await Story.importSave(JSON.parse(text), 'slot-2')
+   */
+  importSave(data: unknown, slot?: string): Promise<SaveInfo>;
+
   /** Return the number of times a passage has been visited. */
   visited(name?: string): number;
 
@@ -460,10 +523,18 @@ export interface StoryAPI {
    * Open a dialog rendering the given passage.
    * @param passageName - The passage to render inside the dialog.
    * @param options - Optional configuration for the dialog panel.
+   * @param options.panelClass - CSS class added to the dialog panel.
+   * @param options.showCloseButton - Show the default `✕` button (defaults to `dismissible`).
+   * @param options.dismissible - When `false`, backdrop clicks are ignored and the
+   *   `✕` button is hidden; close the dialog with `closeDialog()`. Default: `true`.
    */
   openDialog(
     passageName: string,
-    options?: { panelClass?: string; showCloseButton?: boolean },
+    options?: {
+      panelClass?: string;
+      showCloseButton?: boolean;
+      dismissible?: boolean;
+    },
   ): void;
 
   /** Close the topmost open dialog. */
@@ -552,6 +623,16 @@ export interface StoryAPI {
   readonly config: {
     /** Maximum number of history moments to retain. */
     maxHistory: number;
+    /**
+     * Key that triggers a quick save (`KeyboardEvent.key`, default `'F6'`).
+     * Set to `null` to disable the shortcut.
+     */
+    quickSaveKey: string | null;
+    /**
+     * Key that triggers a quick load (`KeyboardEvent.key`, default `'F9'`).
+     * Set to `null` to disable the shortcut.
+     */
+    quickLoadKey: string | null;
   };
 
   /** Seedable pseudo-random number generator. */

package/types/tooling.d.ts

@@ -0,0 +1,68 @@
+export interface ParameterDef {
+  name: string;
+  required?: boolean;
+  description?: string;
+}
+
+export interface MacroMetadata {
+  name: string;
+  block: boolean;
+  subMacros: string[];
+  storeVar?: boolean;
+  interpolate?: boolean;
+  merged?: boolean;
+  source: 'builtin' | 'user';
+  description?: string;
+  parameters?: ParameterDef[];
+}
+
+export interface MacroDefinition {
+  name: string;
+  subMacros?: string[];
+  block?: boolean;
+  interpolate?: boolean;
+  merged?: boolean;
+  storeVar?: boolean;
+  description?: string;
+  parameters?: ParameterDef[];
+  render: (...args: any[]) => any;
+}
+
+/**
+ * Metadata-only defineMacro for tooling.
+ * Captures macro metadata without creating Preact components.
+ * LSP servers call this to register user-defined macros discovered in story scripts.
+ */
+export declare function defineMacro(config: MacroDefinition): void;
+
+/**
+ * Return metadata for all registered macros (built-in + user-defined).
+ */
+export declare function getMacroRegistry(): MacroMetadata[];
+
+/** Variable type inferred from a StoryVariables/StoryTransients default value. */
+export type VarType = 'number' | 'string' | 'boolean' | 'array' | 'object';
+
+/** Inferred shape of a declared variable (or one of its object fields). */
+export interface FieldSchema {
+  type: VarType;
+  /** Field schemas, only present for objects. */
+  fields?: Map<string, FieldSchema>;
+}
+
+/** A declared variable: its inferred schema plus its default value. */
+export interface VariableSchema extends FieldSchema {
+  name: string;
+  default: unknown;
+}
+
+/**
+ * Parse the content of a `StoryVariables` (`$name = value`) or
+ * `StoryTransients` (`%name = value`, pass `sigil: '%'`) passage into a
+ * schema map, exactly as Spindle does at boot.
+ * Throws on invalid declarations or unsupported value types (e.g. `null`).
+ */
+export declare function parseStoryVariables(
+  content: string,
+  sigil?: '$' | '%',
+): Map<string, VariableSchema>;