@rohal12/spindle 0.18.1 → 0.20.0

package/package.json

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

package/src/components/App.tsx

@@ -1,6 +1,7 @@
 import { useEffect } from 'preact/hooks';
 import { useStoryStore } from '../store';
 import { StoryInterface } from './StoryInterface';
+import { TriggerDialogHost } from './TriggerDialogHost';
 
 export function App() {
   const storyData = useStoryStore((s) => s.storyData);
@@ -24,5 +25,10 @@ export function App() {
     return <div class="loading">Loading...</div>;
   }
 
-  return <StoryInterface />;
+  return (
+    <>
+      <StoryInterface />
+      <TriggerDialogHost />
+    </>
+  );
 }

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/TriggerDialogHost.tsx

@@ -0,0 +1,42 @@
+import { useState, useEffect, useCallback } from 'preact/hooks';
+import { PassageDialog } from './PassageDialog';
+import {
+  subscribeTriggerDialogs,
+  shiftDialogQueue,
+  dialogQueueLength,
+} from '../triggers';
+
+export function TriggerDialogHost() {
+  const [current, setCurrent] = useState<string | null>(null);
+
+  const advance = useCallback(() => {
+    const next = shiftDialogQueue();
+    setCurrent(next ?? null);
+  }, []);
+
+  useEffect(() => {
+    return subscribeTriggerDialogs(() => {
+      setCurrent((prev) => {
+        if (prev !== null) return prev; // already showing one
+        return shiftDialogQueue() ?? null;
+      });
+    });
+  }, []);
+
+  const handleClose = useCallback(() => {
+    setCurrent(null);
+    // Show next queued dialog after a tick
+    if (dialogQueueLength() > 0) {
+      requestAnimationFrame(advance);
+    }
+  }, [advance]);
+
+  if (!current) return null;
+
+  return (
+    <PassageDialog
+      passageName={current}
+      onClose={handleClose}
+    />
+  );
+}

package/src/components/macros/Button.tsx

@@ -1,25 +1,40 @@
+import { h, render } from 'preact';
 import { defineMacro } from '../../define-macro';
+import {
+  renderNodes,
+  LocalsUpdateContext,
+  LocalsValuesContext,
+} from '../../markup/render';
 
 defineMacro({
   name: 'button',
   interpolate: true,
   render({ rawArgs, children = [] }, ctx) {
+    const label = ctx.resolve?.(rawArgs.replace(/^["']|["']$/g, '')) ?? rawArgs;
+
     const handleClick = () => {
-      try {
-        ctx.mutate(rawArgs);
-      } catch (err) {
-        console.error(
-          `spindle: Error in {button ${rawArgs}}${ctx.sourceLocation()}:`,
-          err,
-        );
-      }
+      // Render children into a detached DOM node — all macro side effects
+      // ({set}, {if}, {unwatch}, etc.) fire through the normal Preact pipeline.
+      // Wrap with locals context so @local variables from for-loops are available.
+      const container = document.createElement('div');
+      const vnode = h(
+        LocalsUpdateContext.Provider,
+        { value: { update: ctx.update, getValues: ctx.getValues } },
+        h(
+          LocalsValuesContext.Provider,
+          { value: ctx.getValues() },
+          renderNodes(children),
+        ),
+      );
+      render(vnode, container);
+      render(null, container);
     };
 
     ctx.useAction({
       type: 'button',
       key: rawArgs,
       authorId: ctx.id,
-      label: ctx.collectText(children) || rawArgs,
+      label,
       perform: handleClick,
     });
 
@@ -29,7 +44,7 @@ defineMacro({
         class={ctx.cls}
         onClick={handleClick}
       >
-        {ctx.renderInlineNodes(children)}
+        {label}
       </button>
     );
   },

package/src/components/macros/Dialog.tsx

@@ -3,21 +3,15 @@ import { PassageDialog } from '../PassageDialog';
 
 defineMacro({
   name: 'dialog',
-  merged: true,
+  interpolate: true,
   render({ rawArgs, children = [] }, ctx) {
     const [open, setOpen] = ctx.hooks.useState(false);
 
-    let passageName: string;
-    try {
-      const result = ctx.evaluate!(rawArgs);
-      passageName = String(result);
-    } catch {
-      passageName = rawArgs.replace(/^["']|["']$/g, '').trim();
-    }
-
-    const label = children.length
-      ? ctx.renderInlineNodes(children)
-      : passageName;
+    const label = ctx.resolve?.(rawArgs.replace(/^["']|["']$/g, '')) ?? rawArgs;
+    const passageName = ctx
+      .collectText(children)
+      .trim()
+      .replace(/^["']|["']$/g, '');
 
     return (
       <>

package/src/components/macros/MacroLink.tsx

@@ -1,8 +1,10 @@
+import { h, render } from 'preact';
 import { useStoryStore } from '../../store';
-import type { ASTNode } from '../../markup/ast';
-import { executeMutation } from '../../execute-mutation';
-import { collectText } from '../../utils/extract-text';
-import { currentSourceLocation } from '../../utils/source-location';
+import {
+  renderNodes,
+  LocalsUpdateContext,
+  LocalsValuesContext,
+} from '../../markup/render';
 import { defineMacro } from '../../define-macro';
 
 function parseArgs(rawArgs: string): {
@@ -26,37 +28,23 @@ function parseArgs(rawArgs: string): {
   return { display: rawArgs.trim(), passage: null };
 }
 
-/**
- * Execute the children imperatively: walk AST for {set} and {do} macros.
- */
-function executeChildren(
-  children: ASTNode[],
-  mergedLocals: Record<string, unknown>,
-  scopeUpdate: (key: string, value: unknown) => void,
+function renderChildrenDetached(
+  children: import('../../markup/ast').ASTNode[],
+  getValues: () => Record<string, unknown>,
+  update: (key: string, value: unknown) => void,
 ) {
-  for (const node of children) {
-    if (node.type !== 'macro') continue;
-    if (node.name === 'set') {
-      try {
-        executeMutation(node.rawArgs, mergedLocals, scopeUpdate);
-      } catch (err) {
-        console.error(
-          `spindle: Error in {link} child {set}${currentSourceLocation()}:`,
-          err,
-        );
-      }
-    } else if (node.name === 'do') {
-      const code = collectText(node.children);
-      try {
-        executeMutation(code, mergedLocals, scopeUpdate);
-      } catch (err) {
-        console.error(
-          `spindle: Error in {link} child {do}${currentSourceLocation()}:`,
-          err,
-        );
-      }
-    }
-  }
+  const container = document.createElement('div');
+  const vnode = h(
+    LocalsUpdateContext.Provider,
+    { value: { update, getValues } },
+    h(
+      LocalsValuesContext.Provider,
+      { value: getValues() },
+      renderNodes(children),
+    ),
+  );
+  render(vnode, container);
+  render(null, container);
 }
 
 defineMacro({
@@ -67,7 +55,7 @@ defineMacro({
 
     const handleClick = (e: Event) => {
       e.preventDefault();
-      executeChildren(children, ctx.getValues(), ctx.update);
+      renderChildrenDetached(children, ctx.getValues, ctx.update);
       if (passage) {
         useStoryStore.getState().navigate(passage);
       }
@@ -80,7 +68,7 @@ defineMacro({
       label: display,
       target: passage ?? undefined,
       perform: () => {
-        executeChildren(children, ctx.getValues(), ctx.update);
+        renderChildrenDetached(children, ctx.getValues, ctx.update);
         if (passage) {
           useStoryStore.getState().navigate(passage);
         }

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/components/macros/Watch.tsx

@@ -0,0 +1,75 @@
+import { defineMacro } from '../../define-macro';
+import { addTrigger, removeTrigger } from '../../triggers';
+import type { WatchOptions } from '../../triggers';
+
+defineMacro({
+  name: 'watch',
+  render(props, ctx) {
+    const { hooks } = ctx;
+
+    // Parse: condition string + keyword options
+    const raw = props.rawArgs.trim();
+    // First quoted string is the condition
+    const condMatch = raw.match(/^(['"])(.*?)\1\s*/);
+    if (!condMatch) return null;
+
+    const condition = condMatch[2]!;
+    const rest = raw.slice(condMatch[0].length);
+
+    const options: WatchOptions = {};
+    // Parse keyword args: goto "X", dialog "X", run "X", once, name "X", priority N
+    const kwRe = /(\w+)\s+(?:"([^"]*?)"|'([^']*?)'|(\d+))|(\w+)/g;
+    let m: RegExpExecArray | null;
+    while ((m = kwRe.exec(rest)) !== null) {
+      const key = m[1] ?? m[5];
+      const val = m[2] ?? m[3] ?? m[4];
+      if (!key) continue;
+      switch (key) {
+        case 'goto':
+          options.goto = val;
+          break;
+        case 'dialog':
+          options.dialog = val;
+          break;
+        case 'run':
+          options.run = val;
+          break;
+        case 'name':
+          options.name = val;
+          break;
+        case 'priority':
+          options.priority = val ? Number(val) : 0;
+          break;
+        case 'once':
+          options.once = true;
+          break;
+      }
+    }
+
+    // Register during render (like {set}) — triggers survive navigation
+    // and are cleaned up via resetTriggers() on restart or {unwatch}.
+    const registered = hooks.useRef(false);
+    if (!registered.current) {
+      registered.current = true;
+      addTrigger(condition, options);
+    }
+
+    return null;
+  },
+});
+
+defineMacro({
+  name: 'unwatch',
+  render(props, ctx) {
+    const raw = props.rawArgs.trim();
+    const name = raw.replace(/^['"]|['"]$/g, '');
+
+    const ran = ctx.hooks.useRef(false);
+    if (!ran.current) {
+      ran.current = true;
+      removeTrigger(name);
+    }
+
+    return null;
+  },
+});

package/src/index.tsx

@@ -5,6 +5,7 @@ import { useStoryStore } from './store';
 import { installStoryAPI } from './story-api';
 import { resetIdCounters } from './action-registry';
 import { executeStoryInit } from './story-init';
+import { checkTriggers, reinitTriggerState } from './triggers';
 import { loadSession } from './saves/save-manager';
 import {
   parseStoryVariables,
@@ -126,6 +127,21 @@ function boot() {
     }
   });
 
+  // Wire up trigger system: check triggers on variable mutations, reinit on history nav/load
+  let prevVars = useStoryStore.getState().variables;
+  let prevHistoryIndex = useStoryStore.getState().historyIndex;
+  useStoryStore.subscribe((state) => {
+    if (state.variables !== prevVars) {
+      if (state.historyIndex === prevHistoryIndex) {
+        checkTriggers();
+      } else {
+        reinitTriggerState();
+      }
+    }
+    prevVars = state.variables;
+    prevHistoryIndex = state.historyIndex;
+  });
+
   // Warn if StoryInterface passage exists but doesn't contain {passage}
   const storyInterfacePassage = storyData.passages.get('StoryInterface');
   if (

package/src/macros/register-builtins.ts

@@ -31,3 +31,4 @@ import '../components/macros/Listbox';
 import '../components/macros/Cycle';
 import '../components/macros/Span';
 import '../components/macros/PassageDisplay';
+import '../components/macros/Watch';