@rohal12/spindle 0.19.0 → 0.20.0

package/package.json

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

package/src/components/Passage.tsx

@@ -14,6 +14,7 @@ export function renderPassageContent(passage: PassageData) {
 
 interface PassageProps {
   passage: PassageData;
+  dataTransition?: string;
 }
 
 const CODE_PASSAGES = new Set([
@@ -23,7 +24,7 @@ const CODE_PASSAGES = new Set([
   'PassageDone',
 ]);
 
-export function Passage({ passage }: PassageProps) {
+export function Passage({ passage, dataTransition }: PassageProps) {
   const storyData = useStoryStore((s) => s.storyData);
   const isCodePassage = CODE_PASSAGES.has(passage.name);
   const [doneReady, setDoneReady] = useState(false);
@@ -92,6 +93,7 @@ export function Passage({ passage }: PassageProps) {
       class="passage"
       data-passage={passage.name}
       data-tags={passage.tags.join(' ')}
+      data-transition={dataTransition}
     >
       {headerContent && <div class="passage-header">{headerContent}</div>}
       {content}

package/src/components/macros/PassageDisplay.tsx

@@ -1,6 +1,69 @@
+import { useRef, useEffect, useCallback, useState } from 'preact/hooks';
 import { useStoryStore } from '../../store';
 import { Passage, renderPassageContent } from '../Passage';
 import { defineMacro } from '../../define-macro';
+import { resolveTransition, type ResolvedTransition } from '../../transition';
+
+/**
+ * Create a snapshot clone of a .passage element for outgoing transitions.
+ * - Strips `id` attributes from the clone tree
+ * - Disables interaction (pointer-events, user-select)
+ * - Pauses/mutes any <audio>/<video>
+ * - Adds `.passage-snapshot` class and `data-transition` attribute
+ */
+function createSnapshot(
+  passageEl: Element,
+  transitionType: string,
+): HTMLElement {
+  const clone = passageEl.cloneNode(true) as HTMLElement;
+
+  // Strip id attributes to avoid duplicates
+  clone.removeAttribute('id');
+  const idEls = clone.querySelectorAll('[id]');
+  for (let i = 0; i < idEls.length; i++) {
+    idEls[i]!.removeAttribute('id');
+  }
+
+  // Disable interaction
+  clone.style.pointerEvents = 'none';
+  clone.style.userSelect = 'none';
+
+  // Pause/mute media
+  const mediaEls = clone.querySelectorAll('audio, video');
+  for (let i = 0; i < mediaEls.length; i++) {
+    const media = mediaEls[i] as HTMLMediaElement;
+    media.pause?.();
+    media.muted = true;
+  }
+
+  // Mark as snapshot
+  clone.classList.remove('passage');
+  clone.classList.add('passage-snapshot');
+  clone.setAttribute('data-transition', transitionType);
+
+  return clone;
+}
+
+/**
+ * Set CSS custom properties for transition durations on the container element.
+ */
+function setCSSProperties(el: HTMLElement, config: ResolvedTransition): void {
+  el.style.setProperty('--passage-in-duration', `${config.duration / 1000}s`);
+  el.style.setProperty('--passage-out-duration', `${config.duration / 1000}s`);
+  el.style.setProperty('--passage-pause', `${config.pause / 1000}s`);
+}
+
+/**
+ * Remove all snapshot elements and crossfading class from a container.
+ */
+function cleanupSnapshots(containerEl: Element | null): void {
+  if (!containerEl) return;
+  containerEl.classList.remove('passage-container--crossfading');
+  const snapshots = containerEl.querySelectorAll('.passage-snapshot');
+  for (let i = 0; i < snapshots.length; i++) {
+    snapshots[i]!.remove();
+  }
+}
 
 defineMacro({
   name: 'passage',
@@ -9,11 +72,188 @@ defineMacro({
     const currentPassage = useStoryStore((s) => s.currentPassage);
     const storyData = useStoryStore((s) => s.storyData);
 
-    const passage = storyData?.passages.get(currentPassage);
-    if (!passage) {
+    // Render-gating: displayedPassage controls which passage is visually shown.
+    // The store updates immediately, but the visual swap is deferred by the
+    // transition state machine.
+    const [displayedPassage, setDisplayedPassage] = useState(currentPassage);
+
+    // Track the resolved transition type for the data-transition prop
+    const resolvedTypeRef = useRef<string>('fade');
+
+    // Track previous history length to detect restart/load
+    const prevHistoryLenRef = useRef(0);
+
+    // Container ref for snapshot insertion
+    const containerRef = useRef<HTMLDivElement>(null);
+
+    // Track in-progress transition timeouts for cancellation
+    const timeoutsRef = useRef<ReturnType<typeof setTimeout>[]>([]);
+
+    /** Cancel any in-progress transition. */
+    const cancelTransition = useCallback(() => {
+      for (const t of timeoutsRef.current) clearTimeout(t);
+      timeoutsRef.current = [];
+      cleanupSnapshots(containerRef.current);
+    }, []);
+
+    // State machine effect — triggers on passage change
+    useEffect(() => {
+      const store = useStoryStore.getState();
+      const { history, historyIndex, transitionConfig } = store;
+
+      // Always consume the next transition (one-shot), regardless of what we do
+      const next = store.consumeNextTransition();
+
+      // Determine if this is a first load, restart, or save-load
+      const prevLen = prevHistoryLenRef.current;
+      prevHistoryLenRef.current = history.length;
+
+      const isFirstLoad = !displayedPassage;
+      const isRestart =
+        history.length === 1 && historyIndex === 0 && prevLen > 1;
+      const isLoad =
+        history.length > 1 &&
+        historyIndex === history.length - 1 &&
+        prevLen > 1 &&
+        Math.abs(history.length - prevLen) > 1;
+
+      // If this is the same passage (initial render), just set it
+      if (currentPassage === displayedPassage) {
+        // Update prevHistoryLen on initial render
+        return;
+      }
+
+      // Cancel any in-progress transition
+      cancelTransition();
+
+      // Get the target passage
+      const targetPassage = storyData?.passages.get(currentPassage);
+      if (!targetPassage) {
+        // Passage not found — show immediately
+        resolvedTypeRef.current = 'none';
+        setDisplayedPassage(currentPassage);
+        return;
+      }
+
+      // First load, restart, or load → use simple fade (no outgoing phase)
+      if (isFirstLoad || isRestart || isLoad) {
+        resolvedTypeRef.current = 'fade';
+        setDisplayedPassage(currentPassage);
+        return;
+      }
+
+      // Resolve transition from tags → nextTransition → store default → built-in
+      const config = resolveTransition(
+        targetPassage.tags,
+        next,
+        transitionConfig,
+      );
+
+      resolvedTypeRef.current = config.type;
+
+      const containerEl = containerRef.current;
+
+      // ---- State machine by type ----
+
+      if (config.type === 'none') {
+        // idle → mount new (no animation) → idle
+        setDisplayedPassage(currentPassage);
+        return;
+      }
+
+      if (config.type === 'fade') {
+        // idle → mount new → incoming (CSS fade in) → idle
+        if (containerEl) setCSSProperties(containerEl, config);
+        setDisplayedPassage(currentPassage);
+        return;
+      }
+
+      if (config.type === 'fade-through') {
+        // idle → outgoing (fade out snapshot) → paused → incoming (mount new, fade in) → idle
+        if (!containerEl) {
+          setDisplayedPassage(currentPassage);
+          return;
+        }
+
+        setCSSProperties(containerEl, config);
+
+        // Take snapshot of current passage
+        const passageEl = containerEl.querySelector('.passage');
+        if (!passageEl) {
+          setDisplayedPassage(currentPassage);
+          return;
+        }
+
+        const snapshot = createSnapshot(passageEl, config.type);
+        containerEl.appendChild(snapshot);
+
+        // Hide the current passage during outgoing phase by setting empty key
+        setDisplayedPassage('');
+
+        // After outgoing duration + pause, mount the new passage
+        const incomingDelay = config.duration + config.pause;
+        const t1 = setTimeout(() => {
+          setDisplayedPassage(currentPassage);
+        }, incomingDelay);
+
+        // After full transition, clean up snapshot
+        const cleanupDelay = incomingDelay + config.duration;
+        const t2 = setTimeout(() => {
+          cleanupSnapshots(containerEl);
+        }, cleanupDelay);
+
+        timeoutsRef.current = [t1, t2];
+        return;
+      }
+
+      if (config.type === 'crossfade') {
+        // idle → crossfading (mount new + fade in, simultaneously fade out snapshot) → idle
+        if (!containerEl) {
+          setDisplayedPassage(currentPassage);
+          return;
+        }
+
+        setCSSProperties(containerEl, config);
+
+        // Take snapshot of current passage
+        const passageEl = containerEl.querySelector('.passage');
+        if (!passageEl) {
+          setDisplayedPassage(currentPassage);
+          return;
+        }
+
+        const snapshot = createSnapshot(passageEl, config.type);
+
+        // Use CSS grid stacking for crossfade
+        containerEl.classList.add('passage-container--crossfading');
+        containerEl.appendChild(snapshot);
+
+        // Mount new passage immediately alongside snapshot
+        setDisplayedPassage(currentPassage);
+
+        // After duration, clean up snapshot and remove crossfading class
+        const t1 = setTimeout(() => {
+          cleanupSnapshots(containerEl);
+        }, config.duration);
+
+        timeoutsRef.current = [t1];
+        return;
+      }
+
+      // Fallback: unknown type, just mount
+      setDisplayedPassage(currentPassage);
+      // 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;
+
+    if (!passage && displayedPassage) {
       return (
         <div class="error">
-          Error: Passage &ldquo;{currentPassage}&rdquo; not found.
+          Error: Passage &ldquo;{displayedPassage}&rdquo; not found.
         </div>
       );
     }
@@ -33,10 +273,18 @@ defineMacro({
             {renderPassageContent(readyPassage)}
           </div>
         )}
-        <Passage
-          passage={passage}
-          key={currentPassage}
-        />
+        <div
+          class="passage-container"
+          ref={containerRef}
+        >
+          {passage && (
+            <Passage
+              passage={passage}
+              key={displayedPassage}
+              dataTransition={resolvedTypeRef.current}
+            />
+          )}
+        </div>
       </div>
     );
   },

package/src/store.ts

@@ -7,6 +7,7 @@ import {
   type Patch,
 } from 'immer';
 import type { StoryData } from './parser';
+import type { TransitionConfig } from './transition';
 import type { SavePayload, SaveHistoryMoment } from './saves/types';
 import { executeStoryInit } from './story-init';
 import { resetTriggers } from './triggers';
@@ -202,6 +203,8 @@ export interface StoryState {
   maxHistory: number;
   saveError: string | null;
   loadError: string | null;
+  transitionConfig: TransitionConfig | null;
+  nextTransition: TransitionConfig | null;
 
   setMaxHistory: (limit: number) => void;
   init: (
@@ -223,6 +226,9 @@ export interface StoryState {
   getSavePayload: () => SavePayload;
   loadFromPayload: (payload: SavePayload) => void;
   getHistoryVariables: (index: number) => Record<string, unknown>;
+  setTransition: (config: TransitionConfig | null) => void;
+  setNextTransition: (config: TransitionConfig | null) => void;
+  consumeNextTransition: () => TransitionConfig | null;
 }
 
 export const useStoryStore = create<StoryState>()(
@@ -241,6 +247,8 @@ export const useStoryStore = create<StoryState>()(
     maxHistory: 40,
     saveError: null,
     loadError: null,
+    transitionConfig: null,
+    nextTransition: null,
 
     setMaxHistory: (limit: number) => {
       set((state) => {
@@ -616,5 +624,27 @@ export const useStoryStore = create<StoryState>()(
     getHistoryVariables: (index: number): Record<string, unknown> => {
       return deepClone(reconstructVarsAt(index));
     },
+
+    setTransition: (config: TransitionConfig | null) => {
+      set((state) => {
+        state.transitionConfig = config as TransitionConfig | null;
+      });
+    },
+
+    setNextTransition: (config: TransitionConfig | null) => {
+      set((state) => {
+        state.nextTransition = config as TransitionConfig | null;
+      });
+    },
+
+    consumeNextTransition: (): TransitionConfig | null => {
+      const current = get().nextTransition;
+      if (current !== null) {
+        set((state) => {
+          state.nextTransition = null;
+        });
+      }
+      return current;
+    },
   })),
 );

package/src/story-api.ts

@@ -23,6 +23,7 @@ import {
 } from './prng';
 import { addTrigger, removeTrigger } from './triggers';
 import type { WatchOptions } from './triggers';
+import type { TransitionConfig } from './transition';
 
 export type { StoryAction };
 
@@ -72,6 +73,8 @@ export interface StoryAPI {
     callbackOrOptions: (() => void) | WatchOptions,
   ): () => void;
   unwatch(name: string): void;
+  setTransition(config: TransitionConfig | null): void;
+  setNextTransition(config: TransitionConfig | null): void;
   random(): number;
   randomInt(min: number, max: number): number;
   readonly config: {
@@ -281,6 +284,14 @@ function createStoryAPI(): StoryAPI {
       removeTrigger(name);
     },
 
+    setTransition(config: TransitionConfig | null): void {
+      useStoryStore.getState().setTransition(config);
+    },
+
+    setNextTransition(config: TransitionConfig | null): void {
+      useStoryStore.getState().setNextTransition(config);
+    },
+
     random(): number {
       return random();
     },

package/src/styles.css

@@ -29,8 +29,32 @@ tw-storydata {
   padding: 2em 1.5em;
 }
 
+/* Passage transitions */
+
+.passage-container {
+  position: relative;
+}
+
+.passage-container--crossfading {
+  display: grid;
+}
+
+.passage-container--crossfading > * {
+  grid-area: 1 / 1;
+}
+
 .passage {
-  animation: passage-fade-in 0.3s ease-in;
+  animation: passage-fade-in var(--passage-in-duration, 0.3s) ease;
+}
+
+.passage[data-transition='none'] {
+  animation: none;
+}
+
+.passage-snapshot {
+  animation: passage-fade-out var(--passage-out-duration, 0.3s) ease forwards;
+  pointer-events: none;
+  user-select: none;
 }
 
 @keyframes passage-fade-in {
@@ -44,6 +68,24 @@ tw-storydata {
   }
 }
 
+@keyframes passage-fade-out {
+  from {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateY(-8px);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .passage,
+  .passage-snapshot {
+    animation-duration: 0.01s !important;
+  }
+}
+
 .macro-button {
   background: rgba(100, 181, 246, 0.15);
   color: #64b5f6;

package/src/transition.ts

@@ -0,0 +1,69 @@
+export type TransitionType = 'none' | 'fade' | 'fade-through' | 'crossfade';
+
+export interface TransitionConfig {
+  type: TransitionType;
+  duration?: number;
+  pause?: number;
+}
+
+export type ResolvedTransition = Required<TransitionConfig>;
+
+const TRANSITION_TYPES = new Set<TransitionType>([
+  'none',
+  'fade',
+  'fade-through',
+  'crossfade',
+]);
+
+export const BUILT_IN_DEFAULT: ResolvedTransition = {
+  type: 'fade-through',
+  duration: 300,
+  pause: 50,
+};
+
+export function resolveTransitionFromTags(
+  tags: string[],
+): TransitionConfig | null {
+  const typeTag = tags.find((t) => t.startsWith('transition:'));
+  if (!typeTag) return null;
+
+  const rawType = typeTag.slice('transition:'.length);
+  if (!TRANSITION_TYPES.has(rawType as TransitionType)) {
+    console.warn(`Unknown transition type: "${rawType}"`);
+    return null;
+  }
+
+  const config: TransitionConfig = { type: rawType as TransitionType };
+
+  for (const tag of tags) {
+    if (tag.startsWith('duration:')) {
+      const n = Number(tag.slice('duration:'.length));
+      if (!Number.isNaN(n)) config.duration = n;
+    } else if (tag.startsWith('pause:')) {
+      const n = Number(tag.slice('pause:'.length));
+      if (!Number.isNaN(n)) config.pause = n;
+    }
+  }
+
+  return config;
+}
+
+export function fillDefaults(partial: TransitionConfig): ResolvedTransition {
+  return {
+    type: partial.type,
+    duration: partial.duration ?? BUILT_IN_DEFAULT.duration,
+    pause: partial.pause ?? BUILT_IN_DEFAULT.pause,
+  };
+}
+
+export function resolveTransition(
+  targetTags: string[],
+  nextTransition: TransitionConfig | null,
+  storeDefault: TransitionConfig | null,
+): ResolvedTransition {
+  const fromTags = resolveTransitionFromTags(targetTags);
+  if (fromTags) return fillDefaults(fromTags);
+  if (nextTransition) return fillDefaults(nextTransition);
+  if (storeDefault) return fillDefaults(storeDefault);
+  return { ...BUILT_IN_DEFAULT };
+}