@rohal12/spindle 0.17.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",
@@ -47,7 +47,7 @@
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
-    "prepublishOnly": "bun run test && bun run build",
+    "prepublishOnly": "bun run build && bun run test",
     "prepare": "husky"
   },
   "dependencies": {

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

@@ -1,20 +1,36 @@
-import { useMemo } from 'preact/hooks';
+import { useMemo, useEffect, useState } from 'preact/hooks';
 import { tokenize } from '../markup/tokenizer';
 import { buildAST } from '../markup/ast';
 import { renderNodes } from '../markup/render';
+import { useStoryStore } from '../store';
 import type { Passage as PassageData } from '../parser';
 import { sourceLocationOf } from '../utils/source-location';
 
+export function renderPassageContent(passage: PassageData) {
+  const tokens = tokenize(passage.content);
+  const ast = buildAST(tokens);
+  return renderNodes(ast);
+}
+
 interface PassageProps {
   passage: PassageData;
 }
 
+const CODE_PASSAGES = new Set([
+  'PassageReady',
+  'PassageHeader',
+  'PassageFooter',
+  'PassageDone',
+]);
+
 export function Passage({ passage }: PassageProps) {
+  const storyData = useStoryStore((s) => s.storyData);
+  const isCodePassage = CODE_PASSAGES.has(passage.name);
+  const [doneReady, setDoneReady] = useState(false);
+
   const content = useMemo(() => {
     try {
-      const tokens = tokenize(passage.content);
-      const ast = buildAST(tokens);
-      return renderNodes(ast);
+      return renderPassageContent(passage);
     } catch (err) {
       return (
         <div class="error">
@@ -25,13 +41,62 @@ export function Passage({ passage }: PassageProps) {
     }
   }, [passage.content, passage.name]);
 
+  const headerPassage = isCodePassage
+    ? undefined
+    : storyData?.passages.get('PassageHeader');
+  const footerPassage = isCodePassage
+    ? undefined
+    : storyData?.passages.get('PassageFooter');
+  const donePassage = isCodePassage
+    ? undefined
+    : storyData?.passages.get('PassageDone');
+
+  const headerContent = useMemo(() => {
+    if (!headerPassage) return null;
+    try {
+      return renderPassageContent(headerPassage);
+    } catch (err) {
+      console.error('spindle: Error in PassageHeader:', err);
+      return null;
+    }
+  }, [headerPassage?.content]);
+
+  const footerContent = useMemo(() => {
+    if (!footerPassage) return null;
+    try {
+      return renderPassageContent(footerPassage);
+    } catch (err) {
+      console.error('spindle: Error in PassageFooter:', err);
+      return null;
+    }
+  }, [footerPassage?.content]);
+
+  // Defer PassageDone to after DOM commit
+  useEffect(() => {
+    if (donePassage) setDoneReady(true);
+    return () => setDoneReady(false);
+  }, [passage.name]);
+
+  const doneContent = useMemo(() => {
+    if (!doneReady || !donePassage) return null;
+    try {
+      return renderPassageContent(donePassage);
+    } catch (err) {
+      console.error('spindle: Error in PassageDone:', err);
+      return null;
+    }
+  }, [doneReady, donePassage?.content]);
+
   return (
     <div
       class="passage"
       data-passage={passage.name}
       data-tags={passage.tags.join(' ')}
     >
+      {headerContent && <div class="passage-header">{headerContent}</div>}
       {content}
+      {footerContent && <div class="passage-footer">{footerContent}</div>}
+      {doneContent && <div hidden>{doneContent}</div>}
     </div>
   );
 }

package/src/components/StoryInterface.tsx

@@ -1,7 +1,7 @@
 import { useStoryStore } from '../store';
 import { tokenize } from '../markup/tokenizer';
 import { buildAST } from '../markup/ast';
-import { renderNodes } from '../markup/render';
+import { renderInlineNodes } from '../markup/render';
 
 const DEFAULT_MARKUP =
   '<header class="story-menubar">{story-title}{back}{forward}{restart}{quicksave}{quickload}{saves}{settings}</header>\n{passage}';
@@ -16,7 +16,7 @@ export function StoryInterface() {
   try {
     const tokens = tokenize(markup);
     const ast = buildAST(tokens);
-    return <>{renderNodes(ast)}</>;
+    return <>{renderInlineNodes(ast)}</>;
   } catch (err) {
     return (
       <span class="error">

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): {
@@ -11,10 +13,10 @@ function parseArgs(rawArgs: string): {
 } {
   // {link "text" "Passage"} or {link "text"}
   const parts: string[] = [];
-  const re = /["']([^"']+)["']/g;
+  const re = /(["'])(.*?)\1/g;
   let m;
   while ((m = re.exec(rawArgs)) !== null) {
-    parts.push(m[1]!);
+    parts.push(m[2]!);
   }
   if (parts.length >= 2) {
     return { display: parts[0]!, passage: parts[1]! };
@@ -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,5 +1,5 @@
 import { useStoryStore } from '../../store';
-import { Passage } from '../Passage';
+import { Passage, renderPassageContent } from '../Passage';
 import { defineMacro } from '../../define-macro';
 
 defineMacro({
@@ -18,11 +18,21 @@ defineMacro({
       );
     }
 
+    const readyPassage = storyData?.passages.get('PassageReady');
+
     return (
       <div
         id={ctx.id ?? 'story'}
         class={ctx.className ?? 'story'}
       >
+        {readyPassage && (
+          <div
+            key={`ready-${currentPassage}`}
+            hidden
+          >
+            {renderPassageContent(readyPassage)}
+          </div>
+        )}
         <Passage
           passage={passage}
           key={currentPassage}

package/src/components/macros/Span.tsx

@@ -0,0 +1,8 @@
+import { defineMacro } from '../../define-macro';
+
+defineMacro({
+  name: 'span',
+  render({ children = [] }, ctx) {
+    return ctx.wrap(ctx.renderNodes(children));
+  },
+});

package/src/components/macros/Timed.tsx

@@ -32,22 +32,24 @@ defineMacro({
       return () => clearTimeout(timer);
     }, [visibleIndex, sections]);
 
-    if (visibleIndex < 0) return null;
+    if (visibleIndex < 0) return ctx.wrap(null);
 
     const section = sections[visibleIndex]!;
     const content = ctx.renderNodes(section.nodes);
     const sectionClass = ctx.resolve!(section.className);
     const sectionId = ctx.resolve!(section.id);
 
-    if (sectionClass || sectionId)
-      return (
+    const inner =
+      sectionClass || sectionId ? (
         <span
           id={sectionId}
           class={sectionClass}
         >
           {content}
         </span>
+      ) : (
+        content
       );
-    return <>{content}</>;
+    return ctx.wrap(inner);
   },
 });

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/expression.ts

@@ -6,12 +6,12 @@ import { random, randomInt } from './prng';
 interface ExpressionFns {
   currentPassage: () => Passage | undefined;
   previousPassage: () => Passage | undefined;
-  visited: (name: string) => number;
-  hasVisited: (name: string) => boolean;
+  visited: (name?: string) => number;
+  hasVisited: (name?: string) => boolean;
   hasVisitedAny: (...names: string[]) => boolean;
   hasVisitedAll: (...names: string[]) => boolean;
-  rendered: (name: string) => number;
-  hasRendered: (name: string) => boolean;
+  rendered: (name?: string) => number;
+  hasRendered: (name?: string) => boolean;
   hasRenderedAny: (...names: string[]) => boolean;
   hasRenderedAll: (...names: string[]) => boolean;
   random: () => number;
@@ -191,15 +191,17 @@ export function buildExpressionFns() {
     return cachedFns;
   }
 
-  const visited = (name: string): number => visitCounts[name] ?? 0;
-  const hasVisited = (name: string): boolean => visited(name) > 0;
+  const visited = (name?: string): number =>
+    visitCounts[name ?? useStoryStore.getState().currentPassage] ?? 0;
+  const hasVisited = (name?: string): boolean => visited(name) > 0;
   const hasVisitedAny = (...names: string[]): boolean =>
     names.some((n) => visited(n) > 0);
   const hasVisitedAll = (...names: string[]): boolean =>
     names.every((n) => visited(n) > 0);
 
-  const rendered = (name: string): number => renderCounts[name] ?? 0;
-  const hasRendered = (name: string): boolean => rendered(name) > 0;
+  const rendered = (name?: string): number =>
+    renderCounts[name ?? useStoryStore.getState().currentPassage] ?? 0;
+  const hasRendered = (name?: string): boolean => rendered(name) > 0;
   const hasRenderedAny = (...names: string[]): boolean =>
     names.some((n) => rendered(n) > 0);
   const hasRenderedAll = (...names: string[]): boolean =>

package/src/index.tsx

@@ -5,6 +5,8 @@ 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,
   validatePassages,
@@ -89,6 +91,12 @@ function boot() {
   // Execute StoryInit passage if it exists
   executeStoryInit();
 
+  // Restore session state if the page was refreshed
+  const sessionPayload = loadSession(storyData.ifid);
+  if (sessionPayload) {
+    useStoryStore.getState().loadFromPayload(sessionPayload);
+  }
+
   // Register widgets from passages tagged "widget"
   for (const [, passage] of storyData.passages) {
     if (passage.tags.includes('widget')) {
@@ -119,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

@@ -29,4 +29,6 @@ import '../components/macros/Checkbox';
 import '../components/macros/Radiobutton';
 import '../components/macros/Listbox';
 import '../components/macros/Cycle';
+import '../components/macros/Span';
 import '../components/macros/PassageDisplay';
+import '../components/macros/Watch';

package/src/markup/ast.ts

@@ -53,6 +53,7 @@ const BLOCK_MACROS = new Set([
   'repeat',
   'type',
   'widget',
+  'span',
 ]);
 
 /** Map from branch macro name → required parent macro name */