@rohal12/spindle 0.43.7 → 0.45.0

package/src/story-api.ts

@@ -10,6 +10,7 @@ import { settings } from './settings';
 import type {
   SavePayload,
   SaveInfo,
+  SaveExport,
   StorageInfo,
   StorageQuota,
 } from './saves/types';
@@ -113,6 +114,37 @@ function ensureVariableChangedSubscription(): void {
   });
 }
 
+/** Traverse a dot-delimited path on an object and return the value. */
+function getByPath(obj: Record<string, unknown>, path: string): unknown {
+  const segments = path.split('.');
+  let current: unknown = obj[segments[0]!];
+  for (let i = 1; i < segments.length; i++) {
+    if (current == null) return undefined;
+    current = (current as Record<string, unknown>)[segments[i]!];
+  }
+  return current;
+}
+
+/** Set a value at a dot-delimited path on an object (must be an Immer draft for mutation). */
+function setByPath(
+  obj: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): void {
+  const segments = path.split('.');
+  let current: Record<string, unknown> = obj;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const next = current[segments[i]!];
+    if (next == null || typeof next !== 'object') {
+      throw new TypeError(
+        `spindle: Cannot set property "${segments[i + 1]}" on ${typeof next} (at "${segments.slice(0, i + 1).join('.')}")`,
+      );
+    }
+    current = next as Record<string, unknown>;
+  }
+  current[segments[segments.length - 1]!] = value;
+}
+
 export interface StoryAPI {
   get(name: string): unknown;
   set(name: string, value: unknown): void;
@@ -127,6 +159,8 @@ export interface StoryAPI {
   getSaveInfo(slot?: string): Promise<SaveInfo | null>;
   listSaves(): Promise<SaveInfo[]>;
   deleteSave(slot?: string): void;
+  exportSave(slot?: string): Promise<SaveExport | null>;
+  importSave(data: unknown, slot?: string): Promise<SaveInfo>;
   visited(name?: string): number;
   hasVisited(name?: string): boolean;
   hasVisitedAny(...names: string[]): boolean;
@@ -168,7 +202,11 @@ export interface StoryAPI {
   unwatch(name: string): void;
   openDialog(
     passageName: string,
-    options?: { panelClass?: string; showCloseButton?: boolean },
+    options?: {
+      panelClass?: string;
+      showCloseButton?: boolean;
+      dismissible?: boolean;
+    },
   ): void;
   closeDialog(): void;
   closeAllDialogs(): void;
@@ -183,6 +221,8 @@ export interface StoryAPI {
   randomInt(min: number, max: number): number;
   readonly config: {
     maxHistory: number;
+    quickSaveKey: string | null;
+    quickLoadKey: string | null;
   };
   readonly prng: {
     init(seed?: string, useEntropy?: boolean): void;
@@ -192,30 +232,43 @@ export interface StoryAPI {
   };
 }
 
+/** Set a single variable, resolving dot-paths if present. */
+function setOne(name: string, value: unknown): void {
+  const isTransient = name.startsWith('%');
+  const key = isTransient ? name.slice(1) : name;
+  const namespace = isTransient ? 'transient' : 'variables';
+
+  if (key.includes('.')) {
+    useStoryStore.setState((state) => {
+      setByPath(state[namespace] as Record<string, unknown>, key, value);
+    });
+  } else {
+    const state = useStoryStore.getState();
+    if (isTransient) {
+      state.setTransient(key, value);
+    } else {
+      state.setVariable(key, value);
+    }
+  }
+}
+
 function createStoryAPI(): StoryAPI {
   return {
     get(name: string): unknown {
-      if (name.startsWith('%')) {
-        return useStoryStore.getState().transient[name.slice(1)];
-      }
-      return useStoryStore.getState().variables[name];
+      const isTransient = name.startsWith('%');
+      const key = isTransient ? name.slice(1) : name;
+      const store = isTransient
+        ? useStoryStore.getState().transient
+        : useStoryStore.getState().variables;
+      return key.includes('.') ? getByPath(store, key) : store[key];
     },
 
     set(nameOrVars: string | Record<string, unknown>, value?: unknown): void {
-      const state = useStoryStore.getState();
       if (typeof nameOrVars === 'string') {
-        if (nameOrVars.startsWith('%')) {
-          state.setTransient(nameOrVars.slice(1), value);
-        } else {
-          state.setVariable(nameOrVars, value);
-        }
+        setOne(nameOrVars, value);
       } else {
         for (const [k, v] of Object.entries(nameOrVars)) {
-          if (k.startsWith('%')) {
-            state.setTransient(k.slice(1), v);
-          } else {
-            state.setVariable(k, v);
-          }
+          setOne(k, v);
         }
       }
     },
@@ -260,6 +313,14 @@ function createStoryAPI(): StoryAPI {
       useStoryStore.getState().deleteSave(slot);
     },
 
+    exportSave(slot?: string): Promise<SaveExport | null> {
+      return useStoryStore.getState().exportSave(slot);
+    },
+
+    importSave(data: unknown, slot?: string): Promise<SaveInfo> {
+      return useStoryStore.getState().importSave(data, slot);
+    },
+
     visited(name?: string): number {
       const state = useStoryStore.getState();
       return state.visitCounts[name ?? state.currentPassage] ?? 0;
@@ -450,12 +511,17 @@ function createStoryAPI(): StoryAPI {
 
     openDialog(
       passageName: string,
-      options?: { panelClass?: string; showCloseButton?: boolean },
+      options?: {
+        panelClass?: string;
+        showCloseButton?: boolean;
+        dismissible?: boolean;
+      },
     ): void {
       pushDialog({
         passageName,
         panelClass: options?.panelClass,
         showCloseButton: options?.showCloseButton,
+        dismissible: options?.dismissible,
       });
     },
 
@@ -518,6 +584,18 @@ function createStoryAPI(): StoryAPI {
       set maxHistory(limit: number) {
         useStoryStore.getState().setMaxHistory(limit);
       },
+      get quickSaveKey(): string | null {
+        return useStoryStore.getState().quickSaveKey;
+      },
+      set quickSaveKey(key: string | null) {
+        useStoryStore.getState().setQuickSaveKey(key);
+      },
+      get quickLoadKey(): string | null {
+        return useStoryStore.getState().quickLoadKey;
+      },
+      set quickLoadKey(key: string | null) {
+        useStoryStore.getState().setQuickLoadKey(key);
+      },
     },
 
     prng: {

package/src/triggers.ts

@@ -14,6 +14,7 @@ export interface QueuedDialog {
   passageName: string;
   panelClass?: string;
   showCloseButton?: boolean;
+  dismissible?: boolean;
 }
 
 interface Trigger {

package/src/types-drift-check.ts

@@ -13,3 +13,13 @@ import type { StoryAPI as PublishedAPI } from '../types/index';
 const _sourceToPublished: PublishedAPI = {} as SourceAPI;
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 const _publishedToSource: SourceAPI = {} as PublishedAPI;
+
+// Tooling entry point (`@rohal12/spindle/tooling`): types/tooling.d.ts must
+// match the parser that dist/pkg/tooling.js re-exports.
+import type { parseStoryVariables as SourceParse } from './story-variables';
+import type { parseStoryVariables as PublishedParse } from '../types/tooling';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _parseSourceToPublished: typeof PublishedParse = {} as typeof SourceParse;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _parsePublishedToSource: typeof SourceParse = {} as typeof PublishedParse;

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>;