@rohal12/spindle 0.40.1 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.40.1",
+  "version": "0.42.0",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",

package/src/action-registry.ts

@@ -1,3 +1,5 @@
+import { emit } from './event-emitter';
+
 export type ActionType =
   | 'link'
   | 'button'
@@ -28,7 +30,6 @@ export interface StoryAction {
 }
 
 const actions = new Map<string, StoryAction>();
-const listeners = new Set<() => void>();
 const idCounters = new Map<string, number>();
 
 export function generateActionId(
@@ -79,15 +80,6 @@ export function resetIdCounters(): void {
   idCounters.clear();
 }
 
-export function onActionsChanged(fn: () => void): () => void {
-  listeners.add(fn);
-  return () => {
-    listeners.delete(fn);
-  };
-}
-
 function notify(): void {
-  for (const fn of listeners) {
-    fn();
-  }
+  emit('actionsChanged');
 }

package/src/event-emitter.ts

@@ -0,0 +1,71 @@
+type EventMap = {
+  storyinit: () => void;
+  beforerestart: () => void;
+  actionsChanged: () => void;
+  variableChanged: (
+    changed: Record<string, { from: unknown; to: unknown }>,
+  ) => void;
+  beforesave: (
+    slot: string | undefined,
+    custom: Record<string, unknown> | undefined,
+  ) => void;
+  aftersave: (slot: string | undefined) => void;
+  beforeload: (slot: string | undefined) => void;
+  afterload: (slot: string | undefined) => void;
+  beforenavigate: (passageName: string) => void;
+  afternavigate: (to: string, from: string) => void;
+};
+
+export type StoryEvent = keyof EventMap;
+export type StoryEventCallback<E extends StoryEvent> = EventMap[E];
+
+const VALID_EVENTS = new Set<string>([
+  'storyinit',
+  'beforerestart',
+  'actionsChanged',
+  'variableChanged',
+  'beforesave',
+  'aftersave',
+  'beforeload',
+  'afterload',
+  'beforenavigate',
+  'afternavigate',
+]);
+
+// Each event key maps to a Set of callbacks.
+let listeners = new Map<string, Set<Function>>();
+
+export function on<E extends StoryEvent>(
+  event: E,
+  cb: EventMap[E],
+): () => void {
+  if (!VALID_EVENTS.has(event)) {
+    throw new Error(`spindle: Unknown event "${event}".`);
+  }
+  let set = listeners.get(event);
+  if (!set) {
+    set = new Set();
+    listeners.set(event, set);
+  }
+  set.add(cb);
+  return () => {
+    set!.delete(cb);
+  };
+}
+
+export function emit<E extends StoryEvent>(
+  event: E,
+  ...args: Parameters<EventMap[E]>
+): void {
+  const set = listeners.get(event);
+  if (!set) return;
+  // Snapshot to tolerate unsubscription during iteration
+  for (const cb of [...set]) {
+    (cb as Function)(...args);
+  }
+}
+
+/** Test-only: clear all listeners. */
+export function resetEmitter(): void {
+  listeners = new Map();
+}

package/src/index.tsx

@@ -1,7 +1,8 @@
 import { render } from 'preact';
 import { App } from './components/App';
 import { parseStoryData } from './parser';
-import { useStoryStore, fireStoryInit, enterRuntimePhase } from './store';
+import { useStoryStore, enterRuntimePhase } from './store';
+import { emit } from './event-emitter';
 import { installStoryAPI, getReadyPromise } from './story-api';
 import { resetIdCounters } from './action-registry';
 import { executeStoryInit } from './story-init';
@@ -112,7 +113,7 @@ function boot() {
   }
 
   // Fire storyinit after all state is settled (defaults + StoryInit + session)
-  fireStoryInit();
+  emit('storyinit');
 
   // Pass 1: Pre-scan all widget passages to discover block widgets.
   // Register them as block macros BEFORE any tokenize/buildAST calls,

package/src/store.ts

@@ -10,6 +10,7 @@ import type { StoryData } from './parser';
 import type { TransitionConfig } from './transition';
 import type { SavePayload, SaveHistoryMoment, SaveInfo } from './saves/types';
 import { executeStoryInit } from './story-init';
+import { emit } from './event-emitter';
 import { resetTriggers } from './triggers';
 import {
   initSaveSystem,
@@ -212,45 +213,6 @@ export function _resetRuntimePhase(): void {
   inRuntimePhase = false;
 }
 
-// ---------------------------------------------------------------------------
-// storyinit callbacks (direct invocation — avoids Zustand subscription issues)
-// ---------------------------------------------------------------------------
-
-type StoryInitListener = () => void;
-let storyInitListeners: StoryInitListener[] = [];
-
-/** Register a callback to run after StoryInit completes (boot + every restart). */
-export function onStoryInit(cb: StoryInitListener): () => void {
-  storyInitListeners.push(cb);
-  return () => {
-    storyInitListeners = storyInitListeners.filter((l) => l !== cb);
-  };
-}
-
-/** Fire all storyinit listeners. Called after all state resets are complete. */
-export function fireStoryInit(): void {
-  for (const cb of storyInitListeners) cb();
-}
-
-// ---------------------------------------------------------------------------
-// beforerestart callbacks
-// ---------------------------------------------------------------------------
-
-type BeforeRestartListener = () => void;
-let beforeRestartListeners: BeforeRestartListener[] = [];
-
-/** Register a callback to run before restart resets any state. */
-export function onBeforeRestart(cb: BeforeRestartListener): () => void {
-  beforeRestartListeners.push(cb);
-  return () => {
-    beforeRestartListeners = beforeRestartListeners.filter((l) => l !== cb);
-  };
-}
-
-function fireBeforeRestart(): void {
-  for (const cb of beforeRestartListeners) cb();
-}
-
 // ---------------------------------------------------------------------------
 // Store
 // ---------------------------------------------------------------------------
@@ -429,6 +391,9 @@ export const useStoryStore = create<StoryState>()(
         return;
       }
 
+      const previousPassage = get().currentPassage;
+      emit('beforenavigate', passageName);
+
       // Compute variable delta before Immer set()
       const patchEntry = computeVarPatches(lastNavigationVars, currVars);
 
@@ -469,12 +434,18 @@ export const useStoryStore = create<StoryState>()(
 
       lastNavigationVars = get().variables;
       persistSession(get);
+
+      emit('afternavigate', passageName, previousPassage);
     },
 
     goBack: () => {
       const { historyIndex, variables } = get();
       if (historyIndex <= 0) return;
 
+      const previousPassage = get().currentPassage;
+      const targetPassage = get().history[historyIndex - 1]!.passage;
+      emit('beforenavigate', targetPassage);
+
       // Apply inverse transition: moment historyIndex → historyIndex−1
       const restoredVars = deepClone(
         applyPatches(variables, patchEntries[historyIndex - 1]!.inverse),
@@ -490,12 +461,18 @@ export const useStoryStore = create<StoryState>()(
       lastNavigationVars = get().variables;
       restorePRNGFromMoment(get().history[get().historyIndex]);
       persistSession(get);
+
+      emit('afternavigate', targetPassage, previousPassage);
     },
 
     goForward: () => {
       const { historyIndex, history: hist, variables } = get();
       if (historyIndex >= hist.length - 1) return;
 
+      const previousPassage = get().currentPassage;
+      const targetPassage = hist[historyIndex + 1]!.passage;
+      emit('beforenavigate', targetPassage);
+
       // Apply forward transition: moment historyIndex → historyIndex+1
       const restoredVars = deepClone(
         applyPatches(variables, patchEntries[historyIndex]!.forward),
@@ -511,6 +488,8 @@ export const useStoryStore = create<StoryState>()(
       lastNavigationVars = get().variables;
       restorePRNGFromMoment(get().history[get().historyIndex]);
       persistSession(get);
+
+      emit('afternavigate', targetPassage, previousPassage);
     },
 
     setVariable: (name: string, value: unknown) => {
@@ -557,7 +536,7 @@ export const useStoryStore = create<StoryState>()(
         state.renderDeferred = false;
       });
 
-      fireBeforeRestart();
+      emit('beforerestart');
 
       const keepDeferred = get().renderDeferred;
 
@@ -594,7 +573,7 @@ export const useStoryStore = create<StoryState>()(
 
       executeStoryInit();
       clearSession(storyData.ifid);
-      fireStoryInit();
+      emit('storyinit');
 
       // Start a new playthrough on restart
       startNewPlaythrough(storyData.ifid)
@@ -612,6 +591,8 @@ export const useStoryStore = create<StoryState>()(
       const { storyData, playthroughId } = get();
       if (!storyData) return;
 
+      emit('beforesave', slot, custom);
+
       const payload = get().getSavePayload();
 
       set((state) => {
@@ -625,6 +606,7 @@ export const useStoryStore = create<StoryState>()(
               [slot ?? '']: true,
             };
           });
+          emit('aftersave', slot);
         })
         .catch((err) => {
           console.error('spindle: failed to save', err);
@@ -780,6 +762,9 @@ export const useStoryStore = create<StoryState>()(
         console.warn('loadFromPayload: rejecting payload with empty history');
         return;
       }
+
+      emit('beforeload', undefined);
+
       // Convert full snapshots to patch entries
       const base = deserialize(payload.history[0]?.variables ?? {}) as Record<
         string,
@@ -828,6 +813,8 @@ export const useStoryStore = create<StoryState>()(
       } else {
         resetPRNG();
       }
+
+      emit('afterload', undefined);
     },
 
     getHistoryVariables: (index: number): Record<string, unknown> => {

package/src/story-api.ts

@@ -1,9 +1,10 @@
+import { useStoryStore, trackRuntimeUnsub } from './store';
 import {
-  useStoryStore,
-  onStoryInit,
-  onBeforeRestart,
-  trackRuntimeUnsub,
-} from './store';
+  on as emitterOn,
+  emit,
+  type StoryEvent,
+  type StoryEventCallback,
+} from './event-emitter';
 import type { Passage } from './parser';
 import { settings } from './settings';
 import type {
@@ -26,12 +27,7 @@ import { defineMacro } from './define-macro';
 import type { MacroDefinition } from './define-macro';
 import { getMacroRegistry as _getMacroRegistry } from './registry';
 import type { MacroMetadata } from './registry';
-import {
-  getActions,
-  getAction,
-  onActionsChanged,
-  type StoryAction,
-} from './action-registry';
+import { getActions, getAction, type StoryAction } from './action-registry';
 import {
   initPRNG,
   isPRNGEnabled,
@@ -73,13 +69,32 @@ export function _resetReadyState(): void {
   readyPromise = null;
 }
 
-type NavigateCallback = (to: string, from: string) => void;
-type StoryInitCallback = () => void;
-type BeforeRestartCallback = () => void;
-type ActionsChangedCallback = () => void;
-type VariableChangedCallback = (
-  changed: Record<string, { from: unknown; to: unknown }>,
-) => void;
+/** Lazily created shared Zustand subscription for variableChanged. */
+let variableChangedSubActive = false;
+
+function ensureVariableChangedSubscription(): void {
+  if (variableChangedSubActive) return;
+  variableChangedSubActive = true;
+  let prevVars = { ...useStoryStore.getState().variables };
+  useStoryStore.subscribe((state) => {
+    const changed: Record<string, { from: unknown; to: unknown }> = {};
+    let hasChanges = false;
+    const allKeys = new Set([
+      ...Object.keys(prevVars),
+      ...Object.keys(state.variables),
+    ]);
+    for (const key of allKeys) {
+      if (state.variables[key] !== prevVars[key]) {
+        changed[key] = { from: prevVars[key], to: state.variables[key] };
+        hasChanges = true;
+      }
+    }
+    prevVars = { ...state.variables };
+    if (hasChanges) {
+      emit('variableChanged', changed);
+    }
+  });
+}
 
 export interface StoryAPI {
   get(name: string): unknown;
@@ -124,11 +139,10 @@ export interface StoryAPI {
   };
   getActions(): StoryAction[];
   performAction(id: string, value?: unknown): void;
-  on(event: 'navigate', callback: NavigateCallback): () => void;
-  on(event: 'beforerestart', callback: BeforeRestartCallback): () => void;
-  on(event: 'storyinit', callback: StoryInitCallback): () => void;
-  on(event: 'actionsChanged', callback: ActionsChangedCallback): () => void;
-  on(event: 'variableChanged', callback: VariableChangedCallback): () => void;
+  on<E extends StoryEvent>(
+    event: E,
+    callback: StoryEventCallback<E>,
+  ): () => void;
   waitForActions(): Promise<StoryAction[]>;
   watch(
     condition: string,
@@ -373,63 +387,16 @@ function createStoryAPI(): StoryAPI {
       action.perform(value);
     },
 
-    on(event: string, callback: (...args: any[]) => void): () => void {
-      if (event === 'navigate') {
-        let prev = useStoryStore.getState().currentPassage;
-        const unsub = useStoryStore.subscribe((state) => {
-          if (state.currentPassage !== prev) {
-            const from = prev;
-            prev = state.currentPassage;
-            (callback as NavigateCallback)(state.currentPassage, from);
-          }
-        });
-        trackRuntimeUnsub(unsub);
-        return unsub;
-      }
-
-      if (event === 'beforerestart') {
-        const unsub = onBeforeRestart(callback as BeforeRestartCallback);
-        trackRuntimeUnsub(unsub);
-        return unsub;
-      }
-
-      if (event === 'storyinit') {
-        const unsub = onStoryInit(callback as StoryInitCallback);
-        trackRuntimeUnsub(unsub);
-        return unsub;
-      }
-
-      if (event === 'actionsChanged') {
-        const unsub = onActionsChanged(callback as ActionsChangedCallback);
-        trackRuntimeUnsub(unsub);
-        return unsub;
-      }
-
+    on<E extends StoryEvent>(
+      event: E,
+      callback: StoryEventCallback<E>,
+    ): () => void {
       if (event === 'variableChanged') {
-        let prevVars = { ...useStoryStore.getState().variables };
-        const unsub = useStoryStore.subscribe((state) => {
-          const changed: Record<string, { from: unknown; to: unknown }> = {};
-          let hasChanges = false;
-          const allKeys = new Set([
-            ...Object.keys(prevVars),
-            ...Object.keys(state.variables),
-          ]);
-          for (const key of allKeys) {
-            if (state.variables[key] !== prevVars[key]) {
-              changed[key] = { from: prevVars[key], to: state.variables[key] };
-              hasChanges = true;
-            }
-          }
-          prevVars = { ...state.variables };
-          if (hasChanges) {
-            (callback as VariableChangedCallback)(changed);
-          }
-        });
-        trackRuntimeUnsub(unsub);
-        return unsub;
+        ensureVariableChangedSubscription();
       }
-
-      throw new Error(`spindle: Unknown event "${event}".`);
+      const unsub = emitterOn(event, callback);
+      trackRuntimeUnsub(unsub);
+      return unsub;
     },
 
     waitForActions(): Promise<StoryAction[]> {

package/src/types-drift-check.ts

@@ -0,0 +1,15 @@
+/**
+ * Compile-time check: the hand-written types/index.d.ts must stay in sync
+ * with the source StoryAPI interface.  If this file fails to compile,
+ * the published types have drifted from the implementation.
+ *
+ * Run: npx tsc --noEmit
+ */
+import type { StoryAPI as SourceAPI } from './story-api';
+import type { StoryAPI as PublishedAPI } from '../types/index';
+
+// Both directions — if either fails, the types have drifted.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _sourceToPublished: PublishedAPI = {} as SourceAPI;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _publishedToSource: SourceAPI = {} as PublishedAPI;