@rohal12/spindle 0.37.0 → 0.38.0

package/package.json

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

package/src/components/macros/PassageDisplay.tsx

@@ -71,6 +71,7 @@ defineMacro({
   render(_props, ctx) {
     const currentPassage = useStoryStore((s) => s.currentPassage);
     const storyData = useStoryStore((s) => s.storyData);
+    const renderDeferred = useStoryStore((s) => s.renderDeferred);
 
     // Render-gating: displayedPassage controls which passage is visually shown.
     // The store updates immediately, but the visual swap is deferred by the
@@ -245,12 +246,14 @@ defineMacro({
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [currentPassage]);
 
-    // Resolve the passage to display (or show nothing during outgoing phase)
-    const passage = displayedPassage
-      ? storyData?.passages.get(displayedPassage)
-      : null;
+    // When render is deferred, show StoryLoading passage or nothing
+    const effectivePassage = renderDeferred
+      ? (storyData?.passages.get('StoryLoading') ?? null)
+      : displayedPassage
+        ? storyData?.passages.get(displayedPassage)
+        : null;
 
-    if (!passage && displayedPassage) {
+    if (!effectivePassage && displayedPassage && !renderDeferred) {
       return (
         <div class="error">
           Error: Passage &ldquo;{displayedPassage}&rdquo; not found.
@@ -265,7 +268,7 @@ defineMacro({
         id={ctx.id ?? 'story'}
         class={ctx.className ?? 'story'}
       >
-        {readyPassage && (
+        {!renderDeferred && readyPassage && (
           <div
             key={`ready-${currentPassage}`}
             hidden
@@ -277,11 +280,11 @@ defineMacro({
           class="passage-container"
           ref={containerRef}
         >
-          {passage && (
+          {effectivePassage && (
             <Passage
-              passage={passage}
-              key={displayedPassage}
-              dataTransition={resolvedTypeRef.current}
+              passage={effectivePassage}
+              key={renderDeferred ? 'loading' : displayedPassage}
+              dataTransition={renderDeferred ? 'none' : resolvedTypeRef.current}
             />
           )}
         </div>

package/src/index.tsx

@@ -1,8 +1,8 @@
 import { render } from 'preact';
 import { App } from './components/App';
 import { parseStoryData } from './parser';
-import { useStoryStore } from './store';
-import { installStoryAPI } from './story-api';
+import { useStoryStore, fireStoryInit } from './store';
+import { installStoryAPI, getReadyPromise } from './story-api';
 import { resetIdCounters } from './action-registry';
 import { executeStoryInit } from './story-init';
 import { checkTriggers, reinitTriggerState } from './triggers';
@@ -101,7 +101,6 @@ function boot() {
 
   // Execute StoryInit passage if it exists
   executeStoryInit();
-  useStoryStore.getState().bumpInitCount();
 
   // Restore session state if the page was refreshed
   const sessionPayload = loadSession(storyData.ifid);
@@ -109,6 +108,9 @@ function boot() {
     useStoryStore.getState().loadFromPayload(sessionPayload);
   }
 
+  // Fire storyinit after all state is settled (defaults + StoryInit + session)
+  fireStoryInit();
+
   // Pass 1: Pre-scan all widget passages to discover block widgets.
   // Register them as block macros BEFORE any tokenize/buildAST calls,
   // so that widget bodies using other block widgets parse correctly
@@ -198,7 +200,14 @@ function boot() {
 
   render(<App />, root);
 
-  document.dispatchEvent(new CustomEvent(':storyready'));
+  const pending = getReadyPromise();
+  if (pending) {
+    pending.then(() => {
+      document.dispatchEvent(new CustomEvent(':storyready'));
+    });
+  } else {
+    document.dispatchEvent(new CustomEvent(':storyready'));
+  }
 }
 
 if (document.readyState === 'loading') {

package/src/store.ts

@@ -41,6 +41,7 @@ const SPECIAL_PASSAGES = new Set([
   'StoryInit',
   'StoryInterface',
   'StoryVariables',
+  'StoryLoading',
   'SaveTitle',
   'PassageReady',
   'PassageHeader',
@@ -176,6 +177,26 @@ function resetModuleState(base: Record<string, unknown>): void {
   serializedHistory = [];
 }
 
+// ---------------------------------------------------------------------------
+// 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();
+}
+
 // ---------------------------------------------------------------------------
 // Store
 // ---------------------------------------------------------------------------
@@ -207,15 +228,14 @@ export interface StoryState {
   renderCounts: Record<string, number>;
   knownSaves: Record<string, true>;
   playthroughId: string;
-  initCount: number;
   maxHistory: number;
   saveError: string | null;
   loadError: string | null;
   transitionConfig: TransitionConfig | null;
   nextTransition: TransitionConfig | null;
   nobr: boolean;
+  renderDeferred: boolean;
 
-  bumpInitCount: () => void;
   setMaxHistory: (limit: number) => void;
   init: (
     storyData: StoryData,
@@ -245,6 +265,8 @@ export interface StoryState {
   setTransition: (config: TransitionConfig | null) => void;
   setNextTransition: (config: TransitionConfig | null) => void;
   consumeNextTransition: () => TransitionConfig | null;
+  deferRender: () => void;
+  clearDeferredRender: () => void;
 }
 
 export const useStoryStore = create<StoryState>()(
@@ -260,19 +282,13 @@ export const useStoryStore = create<StoryState>()(
     renderCounts: {},
     knownSaves: {},
     playthroughId: '',
-    initCount: 0,
     maxHistory: 40,
     saveError: null,
     loadError: null,
     transitionConfig: null,
     nextTransition: null,
     nobr: false,
-
-    bumpInitCount: () => {
-      set((state) => {
-        state.initCount++;
-      });
-    },
+    renderDeferred: false,
 
     setMaxHistory: (limit: number) => {
       set((state) => {
@@ -499,12 +515,13 @@ export const useStoryStore = create<StoryState>()(
         state.historyIndex = 0;
         state.visitCounts = { [startPassage.name]: 1 };
         state.renderCounts = { [startPassage.name]: 1 };
+        state.renderDeferred = false;
       });
 
       lastNavigationVars = get().variables;
       executeStoryInit();
-      get().bumpInitCount();
       clearSession(storyData.ifid);
+      fireStoryInit();
 
       // Start a new playthrough on restart
       startNewPlaythrough(storyData.ifid)
@@ -765,5 +782,17 @@ export const useStoryStore = create<StoryState>()(
       }
       return current;
     },
+
+    deferRender: () => {
+      set((state) => {
+        state.renderDeferred = true;
+      });
+    },
+
+    clearDeferredRender: () => {
+      set((state) => {
+        state.renderDeferred = false;
+      });
+    },
   })),
 );

package/src/story-api.ts

@@ -1,4 +1,4 @@
-import { useStoryStore } from './store';
+import { useStoryStore, onStoryInit } from './store';
 import type { Passage } from './parser';
 import { settings } from './settings';
 import type {
@@ -50,6 +50,24 @@ import type { TransitionConfig } from './transition';
 export type { StoryAction };
 export type { MacroMetadata };
 
+// Deferred-render promise lifecycle.
+// deferRender() creates a promise; ready() resolves it.
+// index.tsx reads getReadyPromise() AFTER render(), which is after both
+// author JS and storyinit have run, so it always gets the final promise.
+let readyResolve: (() => void) | null = null;
+let readyPromise: Promise<void> | null = null;
+
+/** Returns the current deferred-render promise, or null if not deferred. */
+export function getReadyPromise(): Promise<void> | null {
+  return readyPromise;
+}
+
+/** Test-only: reset module-level promise state. */
+export function _resetReadyState(): void {
+  readyResolve = null;
+  readyPromise = null;
+}
+
 type NavigateCallback = (to: string, from: string) => void;
 type StoryInitCallback = () => void;
 type ActionsChangedCallback = () => void;
@@ -121,6 +139,8 @@ export interface StoryAPI {
   setCSS(enabled: boolean): void;
   setTransition(config: TransitionConfig | null): void;
   setNextTransition(config: TransitionConfig | null): void;
+  deferRender(): void;
+  ready(): void;
   random(): number;
   randomInt(min: number, max: number): number;
   readonly config: {
@@ -359,13 +379,7 @@ function createStoryAPI(): StoryAPI {
       }
 
       if (event === 'storyinit') {
-        let prevCount = useStoryStore.getState().initCount;
-        return useStoryStore.subscribe((state) => {
-          if (state.initCount !== prevCount) {
-            prevCount = state.initCount;
-            (callback as StoryInitCallback)();
-          }
-        });
+        return onStoryInit(callback as StoryInitCallback);
       }
 
       if (event === 'actionsChanged') {
@@ -458,6 +472,21 @@ function createStoryAPI(): StoryAPI {
       useStoryStore.getState().setNextTransition(config);
     },
 
+    deferRender(): void {
+      useStoryStore.getState().deferRender();
+      readyPromise = new Promise<void>((resolve) => {
+        readyResolve = resolve;
+      });
+    },
+
+    ready(): void {
+      if (!readyResolve) return;
+      useStoryStore.getState().clearDeferredRender();
+      readyResolve();
+      readyResolve = null;
+      readyPromise = null;
+    },
+
     random(): number {
       return random();
     },