@rohal12/spindle 0.39.0 → 0.40.0

package/package.json

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

package/src/index.tsx

@@ -1,7 +1,7 @@
 import { render } from 'preact';
 import { App } from './components/App';
 import { parseStoryData } from './parser';
-import { useStoryStore, fireStoryInit } from './store';
+import { useStoryStore, fireStoryInit, enterRuntimePhase } from './store';
 import { installStoryAPI, getReadyPromise } from './story-api';
 import { resetIdCounters } from './action-registry';
 import { executeStoryInit } from './story-init';
@@ -99,6 +99,9 @@ function boot() {
 
   useStoryStore.getState().init(storyData, defaults);
 
+  // Enter runtime phase — handlers registered from here on are cleaned on restart
+  enterRuntimePhase();
+
   // Execute StoryInit passage if it exists
   executeStoryInit();
 

package/src/store.ts

@@ -177,6 +177,41 @@ function resetModuleState(base: Record<string, unknown>): void {
   serializedHistory = [];
 }
 
+// ---------------------------------------------------------------------------
+// Runtime handler cleanup (auto-unsub on restart)
+// ---------------------------------------------------------------------------
+
+let runtimeUnsubs: Array<() => void> = [];
+let inRuntimePhase = false;
+
+/**
+ * Track an unsubscribe function for automatic cleanup on restart.
+ * No-op if called during the startup phase (before enterRuntimePhase).
+ */
+export function trackRuntimeUnsub(unsub: () => void): void {
+  if (inRuntimePhase) {
+    runtimeUnsubs.push(unsub);
+  }
+}
+
+/** Mark the start of the runtime phase. Called before executeStoryInit(). */
+export function enterRuntimePhase(): void {
+  inRuntimePhase = true;
+}
+
+/** Call all tracked unsubs and reset the runtime phase. */
+function cleanupRuntimeHandlers(): void {
+  for (const unsub of runtimeUnsubs) unsub();
+  runtimeUnsubs = [];
+  inRuntimePhase = false;
+}
+
+/** Test-only: reset runtime phase state between tests. */
+export function _resetRuntimePhase(): void {
+  runtimeUnsubs = [];
+  inRuntimePhase = false;
+}
+
 // ---------------------------------------------------------------------------
 // storyinit callbacks (direct invocation — avoids Zustand subscription issues)
 // ---------------------------------------------------------------------------
@@ -516,7 +551,19 @@ export const useStoryStore = create<StoryState>()(
       const startPassage = storyData.passagesById.get(storyData.startNode);
       if (!startPassage) return;
 
+      // Reset renderDeferred before firing beforerestart so we can detect
+      // if a handler called deferRender() during the callback.
+      set((state) => {
+        state.renderDeferred = false;
+      });
+
       fireBeforeRestart();
+
+      const keepDeferred = get().renderDeferred;
+
+      // Clean up all runtime-phase handlers (after beforerestart has fired)
+      cleanupRuntimeHandlers();
+
       resetPRNG();
       resetTriggers();
       const initialVars = deepClone(variableDefaults);
@@ -535,10 +582,16 @@ export const useStoryStore = create<StoryState>()(
         state.historyIndex = 0;
         state.visitCounts = { [startPassage.name]: 1 };
         state.renderCounts = { [startPassage.name]: 1 };
-        state.renderDeferred = false;
+        if (!keepDeferred) {
+          state.renderDeferred = false;
+        }
       });
 
       lastNavigationVars = get().variables;
+
+      // Re-enter runtime phase before StoryInit so new handlers are tracked
+      enterRuntimePhase();
+
       executeStoryInit();
       clearSession(storyData.ifid);
       fireStoryInit();

package/src/story-api.ts

@@ -1,4 +1,9 @@
-import { useStoryStore, onStoryInit, onBeforeRestart } from './store';
+import {
+  useStoryStore,
+  onStoryInit,
+  onBeforeRestart,
+  trackRuntimeUnsub,
+} from './store';
 import type { Passage } from './parser';
 import { settings } from './settings';
 import type {
@@ -371,30 +376,38 @@ function createStoryAPI(): StoryAPI {
     on(event: string, callback: (...args: any[]) => void): () => void {
       if (event === 'navigate') {
         let prev = useStoryStore.getState().currentPassage;
-        return useStoryStore.subscribe((state) => {
+        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') {
-        return onBeforeRestart(callback as BeforeRestartCallback);
+        const unsub = onBeforeRestart(callback as BeforeRestartCallback);
+        trackRuntimeUnsub(unsub);
+        return unsub;
       }
 
       if (event === 'storyinit') {
-        return onStoryInit(callback as StoryInitCallback);
+        const unsub = onStoryInit(callback as StoryInitCallback);
+        trackRuntimeUnsub(unsub);
+        return unsub;
       }
 
       if (event === 'actionsChanged') {
-        return onActionsChanged(callback as ActionsChangedCallback);
+        const unsub = onActionsChanged(callback as ActionsChangedCallback);
+        trackRuntimeUnsub(unsub);
+        return unsub;
       }
 
       if (event === 'variableChanged') {
         let prevVars = { ...useStoryStore.getState().variables };
-        return useStoryStore.subscribe((state) => {
+        const unsub = useStoryStore.subscribe((state) => {
           const changed: Record<string, { from: unknown; to: unknown }> = {};
           let hasChanges = false;
           const allKeys = new Set([
@@ -412,6 +425,8 @@ function createStoryAPI(): StoryAPI {
             (callback as VariableChangedCallback)(changed);
           }
         });
+        trackRuntimeUnsub(unsub);
+        return unsub;
       }
 
       throw new Error(`spindle: Unknown event "${event}".`);