@rohal12/spindle 0.44.0 → 0.45.0

package/dist/pkg/story-variables.js

@@ -0,0 +1,125 @@
+//#region src/story-variables.ts
+function declarationRegex(sigil) {
+	const escaped = sigil.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	return new RegExp(`^${escaped}(\\w+)\\s*=\\s*(.+)$`);
+}
+var VAR_REF_RE = /\$(\w+(?:\.\w+)*)/g;
+var FOR_LOCAL_RE = /\{for\s+@(\w+)(?:\s*,\s*@(\w+))?\s+of\b/g;
+var VALID_VAR_TYPES = new Set([
+	"number",
+	"string",
+	"boolean"
+]);
+function inferSchema(value) {
+	if (Array.isArray(value)) return { type: "array" };
+	if (value !== null && typeof value === "object") {
+		const fields = /* @__PURE__ */ new Map();
+		for (const [key, val] of Object.entries(value)) fields.set(key, inferSchema(val));
+		return {
+			type: "object",
+			fields
+		};
+	}
+	const jsType = typeof value;
+	if (!VALID_VAR_TYPES.has(jsType)) throw new Error(`Unsupported type "${jsType}" for value ${String(value)}. Expected number, string, boolean, array, or object.`);
+	return { type: jsType };
+}
+/**
+* Parse a StoryVariables or StoryTransients passage content into a schema map.
+* Each line: `$varName = expression` (or `%varName = expression` for transients)
+*/
+function parseStoryVariables(content, sigil = "$") {
+	const schema = /* @__PURE__ */ new Map();
+	const DECLARATION_RE = declarationRegex(sigil);
+	const passageName = sigil === "%" ? "StoryTransients" : "StoryVariables";
+	for (const rawLine of content.split("\n")) {
+		const line = rawLine.trim();
+		if (!line) continue;
+		const match = line.match(DECLARATION_RE);
+		if (!match) throw new Error(`${passageName}: Invalid declaration: "${line}". Expected: ${sigil}name = value`);
+		const [, name, expr] = match;
+		let value;
+		try {
+			value = new Function("return (" + expr + ")")();
+		} catch (err) {
+			throw new Error(`${passageName}: Failed to evaluate "${sigil}${name} = ${expr}": ${err instanceof Error ? err.message : err}`);
+		}
+		let fieldSchema;
+		try {
+			fieldSchema = inferSchema(value);
+		} catch (err) {
+			throw new Error(`${passageName}: ${err instanceof Error ? err.message : err}`);
+		}
+		schema.set(name, {
+			...fieldSchema,
+			name,
+			default: value
+		});
+	}
+	return schema;
+}
+/**
+* Extract for-loop local variable names from passage content.
+* `{for @item of ...}` → "item"
+* `{for @index, @item of ...}` → "index", "item"
+*/
+function extractForLocals(content) {
+	const locals = /* @__PURE__ */ new Set();
+	let match;
+	FOR_LOCAL_RE.lastIndex = 0;
+	while ((match = FOR_LOCAL_RE.exec(content)) !== null) {
+		locals.add(match[1]);
+		if (match[2]) locals.add(match[2]);
+	}
+	return locals;
+}
+/**
+* Validate a single variable reference path (e.g. "player.health") against
+* the schema. Returns an error message or null if valid.
+*/
+function validateRef(ref, schema, forLocals) {
+	const parts = ref.split(".");
+	const rootName = parts[0];
+	if (forLocals.has(rootName)) return null;
+	const rootSchema = schema.get(rootName);
+	if (!rootSchema) return `Undeclared variable: $${ref}`;
+	let current = rootSchema;
+	for (let i = 1; i < parts.length; i++) {
+		const part = parts[i];
+		if (current.type === "array") return null;
+		if (current.type !== "object" || !current.fields) return `Cannot access field "${part}" on $${parts.slice(0, i).join(".")} (type: ${current.type})`;
+		const fieldSchema = current.fields.get(part);
+		if (!fieldSchema) return null;
+		current = fieldSchema;
+	}
+	return null;
+}
+/**
+* Scan all passages for $var references, check against schema.
+* Returns list of error messages (empty = valid).
+*/
+function validatePassages(passages, schema) {
+	const errors = [];
+	for (const [name, passage] of passages) {
+		if (name === "StoryVariables" || name === "StoryTransients") continue;
+		const forLocals = extractForLocals(passage.content);
+		let match;
+		VAR_REF_RE.lastIndex = 0;
+		while ((match = VAR_REF_RE.exec(passage.content)) !== null) {
+			const ref = match[1];
+			const error = validateRef(ref, schema, forLocals);
+			if (error) errors.push(`Passage "${name}": ${error}`);
+		}
+	}
+	return errors;
+}
+/**
+* Extract default values from the schema as a plain object.
+*/
+function extractDefaults(schema) {
+	const defaults = {};
+	for (const [name, varSchema] of schema) defaults[name] = varSchema.default;
+	return defaults;
+}
+//#endregion
+export { extractDefaults, parseStoryVariables, validatePassages };

package/dist/pkg/tooling.js

@@ -2,6 +2,8 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+export { parseStoryVariables } from './story-variables.js';
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 // Load built-in macro metadata generated at build time

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",
@@ -35,6 +35,7 @@
     "dist/pkg/index.js",
     "dist/pkg/format.js",
     "dist/pkg/tooling.js",
+    "dist/pkg/story-variables.js",
     "dist/pkg/macro-registry.json",
     "types",
     "src"

package/src/components/App.tsx

@@ -11,12 +11,14 @@ export function App() {
 
   useEffect(() => {
     const onKeyDown = (e: KeyboardEvent) => {
-      if (e.key === 'F6') {
+      const { quickSaveKey, quickLoadKey, save, load } =
+        useStoryStore.getState();
+      if (quickSaveKey !== null && e.key === quickSaveKey) {
         e.preventDefault();
-        useStoryStore.getState().save();
-      } else if (e.key === 'F9') {
+        save();
+      } else if (quickLoadKey !== null && e.key === quickLoadKey) {
         e.preventDefault();
-        useStoryStore.getState().load();
+        load();
       }
     };
     document.addEventListener('keydown', onKeyDown);

package/src/components/PassageDialog.tsx

@@ -12,7 +12,14 @@ interface PassageDialogProps {
   fallbackMarkup?: string;
   panelClass?: string;
   onClose: () => void;
+  /** Show the default `✕` button. Defaults to `dismissible`. */
   showCloseButton?: boolean;
+  /**
+   * When `false`, the player cannot dismiss the dialog: backdrop clicks are
+   * ignored and the `✕` button is hidden (unless `showCloseButton` is set
+   * explicitly). The dialog can still be closed programmatically.
+   */
+  dismissible?: boolean;
 }
 
 export function PassageDialog({
@@ -20,7 +27,8 @@ export function PassageDialog({
   fallbackMarkup,
   panelClass,
   onClose,
-  showCloseButton = true,
+  dismissible = true,
+  showCloseButton = dismissible,
 }: PassageDialogProps) {
   // Stabilize onClose so DialogCloseContext value doesn't change identity
   const onCloseRef = useRef(onClose);
@@ -52,6 +60,7 @@ export function PassageDialog({
   }, [markup]);
 
   const handleBackdrop = (e: MouseEvent) => {
+    if (!dismissible) return;
     if ((e.target as HTMLElement).classList.contains('dialog-overlay')) {
       stableOnClose();
     }

package/src/components/TriggerDialogHost.tsx

@@ -59,6 +59,7 @@ export function TriggerDialogHost() {
           panelClass={dialog.panelClass}
           onClose={handleClose}
           showCloseButton={dialog.showCloseButton}
+          dismissible={dialog.dismissible}
         />
       ))}
     </>

package/src/components/macros/MenubarButtons.tsx

@@ -13,7 +13,7 @@ interface MenubarActionConfig {
   title?: string;
   confirm?: string;
   hidden?: () => boolean;
-  setup?: () => { perform: () => void; disabled?: boolean };
+  setup?: () => { perform: () => void; disabled?: boolean; title?: string };
   dialog?: {
     passageName: string;
     fallbackMarkup?: string;
@@ -22,6 +22,10 @@ interface MenubarActionConfig {
   };
 }
 
+function hotkeyTitle(label: string, key: string | null): string {
+  return key ? `${label} (${key})` : label;
+}
+
 export function defineMenubarAction(config: MenubarActionConfig) {
   defineMacro({
     name: config.name,
@@ -31,7 +35,7 @@ export function defineMenubarAction(config: MenubarActionConfig) {
       const [dialogOpen, setDialogOpen] = useState(false);
 
       const setup = config.setup?.() ?? { perform: () => {} };
-      const { disabled } = setup;
+      const { disabled, title = config.title } = setup;
 
       const cls = ctx.className
         ? `menubar-button ${ctx.className}`
@@ -61,7 +65,7 @@ export function defineMenubarAction(config: MenubarActionConfig) {
             class={cls}
             onClick={perform}
             disabled={disabled}
-            title={config.title}
+            title={title}
           >
             {config.label}
           </button>
@@ -104,9 +108,12 @@ defineMenubarAction({
   name: 'quicksave',
   label: 'QuickSave',
   actionType: 'save',
-  title: 'Quick Save (F6)',
   setup: () => ({
     perform: useStoryStore((s) => s.save),
+    title: hotkeyTitle(
+      'Quick Save',
+      useStoryStore((s) => s.quickSaveKey),
+    ),
   }),
 });
 
@@ -114,13 +121,17 @@ defineMenubarAction({
   name: 'quickload',
   label: 'QuickLoad',
   actionType: 'load',
-  title: 'Quick Load (F9)',
   confirm: 'Load saved game? Current progress will be lost.',
   setup: () => {
     const load = useStoryStore((s) => s.load);
     const hasSave = useStoryStore((s) => s.hasSave);
+    const key = useStoryStore((s) => s.quickLoadKey);
     useStoryStore((s) => s.knownSaves);
-    return { perform: () => load(), disabled: !hasSave() };
+    return {
+      perform: () => load(),
+      disabled: !hasSave(),
+      title: hotkeyTitle('Quick Load', key),
+    };
   },
 });
 

package/src/saves/save-manager.ts

@@ -273,6 +273,28 @@ function slotMetaKey(ifid: string, slot?: string): string {
     : `${AUTOSAVE_KEY_PREFIX}${ifid}`;
 }
 
+/** Record a named slot in the per-story slot index (no-op for the default slot). */
+async function addToSlotIndex(ifid: string, slot?: string): Promise<void> {
+  if (slot == null) return;
+  const backend = await getBackend();
+  const indexKey = `${SLOT_INDEX_KEY_PREFIX}${ifid}`;
+  const existing = (await backend.getMeta<string[]>(indexKey)) ?? [];
+  if (!existing.includes(slot)) {
+    await backend.setMeta(indexKey, [...existing, slot]);
+  }
+}
+
+function toSaveInfo(record: SaveRecord, slot?: string): SaveInfo {
+  return {
+    slot: slot ?? '',
+    title: record.meta.title,
+    passage: record.meta.passage,
+    createdAt: record.meta.createdAt,
+    updatedAt: record.meta.updatedAt,
+    custom: record.meta.custom ?? {},
+  };
+}
+
 export async function quickSave(
   ifid: string,
   playthroughId: string,
@@ -296,15 +318,7 @@ export async function quickSave(
     ...custom,
   });
   await backend.setMeta(metaKey, record.meta.id);
-
-  // Track named slots in the index
-  if (slot != null) {
-    const indexKey = `${SLOT_INDEX_KEY_PREFIX}${ifid}`;
-    const existing = (await backend.getMeta<string[]>(indexKey)) ?? [];
-    if (!existing.includes(slot)) {
-      await backend.setMeta(indexKey, [...existing, slot]);
-    }
-  }
+  await addToSlotIndex(ifid, slot);
 
   return record;
 }
@@ -371,14 +385,7 @@ export async function getSlotSaveInfo(
   if (!existingId) return null;
   const record = await backend.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 ?? {},
-  };
+  return toSaveInfo(record, slot);
 }
 
 /**
@@ -487,7 +494,12 @@ export async function exportSave(
   };
 }
 
-export async function importSave(
+/**
+ * Validate an export against the running story and build the record to store:
+ * a fresh save ID, and the playthrough record created if it doesn't exist yet.
+ * The returned record is not stored yet.
+ */
+async function prepareImport(
   data: SaveExport,
   ifid: string,
 ): Promise<SaveRecord> {
@@ -521,10 +533,67 @@ export async function importSave(
     await backend.putPlaythrough(pt);
   }
 
-  await backend.putSave(record);
   return record;
 }
 
+export async function importSave(
+  data: SaveExport,
+  ifid: string,
+): Promise<SaveRecord> {
+  const record = await prepareImport(data, ifid);
+  await (await getBackend()).putSave(record);
+  return record;
+}
+
+/**
+ * Export the save held in a slot (default autosave slot when `slot` is omitted).
+ * Returns undefined if the slot is empty.
+ */
+export async function exportSlotSave(
+  ifid: string,
+  slot?: string,
+): Promise<SaveExport | undefined> {
+  const saveId = await (
+    await getBackend()
+  ).getMeta<string>(slotMetaKey(ifid, slot));
+  if (!saveId) return undefined;
+  return exportSave(saveId);
+}
+
+/**
+ * Import an exported save into a slot (default autosave slot when `slot` is
+ * omitted), replacing any save already in that slot. Applies the same
+ * validation as `importSave` (version, IFID) and keeps the playthrough record
+ * and slot index consistent.
+ */
+export async function importSlotSave(
+  data: SaveExport,
+  ifid: string,
+  slot?: string,
+): Promise<SaveInfo> {
+  const record = await prepareImport(data, ifid);
+
+  // The slot keys in `custom` describe where the save lives, so they follow
+  // the target slot rather than the slot the save was exported from.
+  const { slot: _exportedSlot, ...custom } = record.meta.custom ?? {};
+  record.meta.custom = {
+    ...custom,
+    isAutosave: !slot,
+    ...(slot != null ? { slot } : {}),
+  };
+
+  const backend = await getBackend();
+  const metaKey = slotMetaKey(ifid, slot);
+  const previousId = await backend.getMeta<string>(metaKey);
+
+  await backend.putSave(record);
+  await backend.setMeta(metaKey, record.meta.id);
+  await addToSlotIndex(ifid, slot);
+  if (previousId) await backend.deleteSave(previousId);
+
+  return toSaveInfo(record, slot);
+}
+
 // --- Storage Management ---
 
 export async function getStorageInfo(ifid: string): Promise<StorageInfo> {

package/src/store.ts

@@ -8,7 +8,13 @@ import {
 } from 'immer';
 import type { StoryData } from './parser';
 import type { TransitionConfig } from './transition';
-import type { SavePayload, SaveHistoryMoment, SaveInfo } from './saves/types';
+import type {
+  SavePayload,
+  SaveHistoryMoment,
+  SaveInfo,
+  SaveExport,
+} from './saves/types';
+import { isSaveExport } from './saves/types';
 import { executeStoryInit } from './story-init';
 import { emit } from './event-emitter';
 import { resetTriggers } from './triggers';
@@ -22,6 +28,8 @@ import {
   getSlotSaveInfo,
   listSlotSaves,
   deleteSlotSave,
+  exportSlotSave,
+  importSlotSave,
   saveSession,
   clearSession,
   clearGameData as smClearGameData,
@@ -218,6 +226,11 @@ export function _resetRuntimePhase(): void {
 // Store
 // ---------------------------------------------------------------------------
 
+/** A hotkey is a `KeyboardEvent.key` value; anything else disables it. */
+function normalizeHotkey(key: unknown): string | null {
+  return typeof key === 'string' && key !== '' ? key : null;
+}
+
 /** Restore or reset PRNG from a history moment's snapshot. */
 function restorePRNGFromMoment(moment: HistoryMoment | undefined): void {
   if (moment?.prng) {
@@ -248,6 +261,8 @@ export interface StoryState {
   knownSaves: Record<string, true>;
   playthroughId: string;
   maxHistory: number;
+  quickSaveKey: string | null;
+  quickLoadKey: string | null;
   saveError: string | null;
   loadError: string | null;
   transitionConfig: TransitionConfig | null;
@@ -256,6 +271,8 @@ export interface StoryState {
   renderDeferred: boolean;
 
   setMaxHistory: (limit: number) => void;
+  setQuickSaveKey: (key: string | null) => void;
+  setQuickLoadKey: (key: string | null) => void;
   init: (
     storyData: StoryData,
     variableDefaults?: Record<string, unknown>,
@@ -278,6 +295,8 @@ export interface StoryState {
   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>;
   clearGameData: () => void;
   clearAllData: () => void;
   deletePlaythrough: (playthroughId: string) => void;
@@ -307,6 +326,8 @@ export const useStoryStore = create<StoryState>()(
     knownSaves: {},
     playthroughId: '',
     maxHistory: 40,
+    quickSaveKey: 'F6',
+    quickLoadKey: 'F9',
     saveError: null,
     loadError: null,
     transitionConfig: null,
@@ -320,6 +341,18 @@ export const useStoryStore = create<StoryState>()(
       });
     },
 
+    setQuickSaveKey: (key: string | null) => {
+      set((state) => {
+        state.quickSaveKey = normalizeHotkey(key);
+      });
+    },
+
+    setQuickLoadKey: (key: string | null) => {
+      set((state) => {
+        state.quickLoadKey = normalizeHotkey(key);
+      });
+    },
+
     init: (
       storyData: StoryData,
       variableDefaults: Record<string, unknown> = {},
@@ -697,6 +730,24 @@ export const useStoryStore = create<StoryState>()(
         });
     },
 
+    exportSave: async (slot?: string): Promise<SaveExport | null> => {
+      const { storyData } = get();
+      if (!storyData) return null;
+      return (await exportSlotSave(storyData.ifid, slot)) ?? null;
+    },
+
+    importSave: async (data: unknown, slot?: string): Promise<SaveInfo> => {
+      const { storyData } = get();
+      if (!storyData) throw new Error('spindle: Story is not initialized.');
+      if (!isSaveExport(data)) throw new Error('Invalid save file format');
+
+      const info = await importSlotSave(data, storyData.ifid, slot);
+      set((state) => {
+        state.knownSaves = { ...state.knownSaves, [slot ?? '']: true };
+      });
+      return info;
+    },
+
     clearGameData: () => {
       const { storyData } = get();
       if (!storyData) return;

package/src/story-api.ts

@@ -10,6 +10,7 @@ import { settings } from './settings';
 import type {
   SavePayload,
   SaveInfo,
+  SaveExport,
   StorageInfo,
   StorageQuota,
 } from './saves/types';
@@ -158,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;
@@ -199,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;
@@ -214,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;
@@ -304,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;
@@ -494,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,
       });
     },
 
@@ -562,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;