@rohal12/spindle 0.37.1 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.37.1",
+  "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

@@ -2,7 +2,7 @@ import { render } from 'preact';
 import { App } from './components/App';
 import { parseStoryData } from './parser';
 import { useStoryStore, fireStoryInit } from './store';
-import { installStoryAPI } from './story-api';
+import { installStoryAPI, getReadyPromise } from './story-api';
 import { resetIdCounters } from './action-registry';
 import { executeStoryInit } from './story-init';
 import { checkTriggers, reinitTriggerState } from './triggers';
@@ -200,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',
@@ -233,6 +234,7 @@ export interface StoryState {
   transitionConfig: TransitionConfig | null;
   nextTransition: TransitionConfig | null;
   nobr: boolean;
+  renderDeferred: boolean;
 
   setMaxHistory: (limit: number) => void;
   init: (
@@ -263,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>()(
@@ -284,6 +288,7 @@ export const useStoryStore = create<StoryState>()(
     transitionConfig: null,
     nextTransition: null,
     nobr: false,
+    renderDeferred: false,
 
     setMaxHistory: (limit: number) => {
       set((state) => {
@@ -510,6 +515,7 @@ export const useStoryStore = create<StoryState>()(
         state.historyIndex = 0;
         state.visitCounts = { [startPassage.name]: 1 };
         state.renderCounts = { [startPassage.name]: 1 };
+        state.renderDeferred = false;
       });
 
       lastNavigationVars = get().variables;
@@ -776,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

@@ -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: {
@@ -452,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();
     },