@rohal12/spindle 0.18.1 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.18.1",
+  "version": "0.19.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/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/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';

package/src/store.ts

@@ -9,6 +9,7 @@ import {
 import type { StoryData } from './parser';
 import type { SavePayload, SaveHistoryMoment } from './saves/types';
 import { executeStoryInit } from './story-init';
+import { resetTriggers } from './triggers';
 import {
   initSaveSystem,
   startNewPlaythrough,
@@ -441,6 +442,7 @@ export const useStoryStore = create<StoryState>()(
       if (!startPassage) return;
 
       resetPRNG();
+      resetTriggers();
       const initialVars = deepClone(variableDefaults);
       resetModuleState(deepClone(initialVars));
 

package/src/story-api.ts

@@ -21,6 +21,8 @@ import {
   randomInt,
   snapshotPRNG,
 } from './prng';
+import { addTrigger, removeTrigger } from './triggers';
+import type { WatchOptions } from './triggers';
 
 export type { StoryAction };
 
@@ -65,6 +67,11 @@ export interface StoryAPI {
   on(event: 'actionsChanged', callback: ActionsChangedCallback): () => void;
   on(event: 'variableChanged', callback: VariableChangedCallback): () => void;
   waitForActions(): Promise<StoryAction[]>;
+  watch(
+    condition: string,
+    callbackOrOptions: (() => void) | WatchOptions,
+  ): () => void;
+  unwatch(name: string): void;
   random(): number;
   randomInt(min: number, max: number): number;
   readonly config: {
@@ -263,6 +270,17 @@ function createStoryAPI(): StoryAPI {
       });
     },
 
+    watch(
+      condition: string,
+      callbackOrOptions: (() => void) | WatchOptions,
+    ): () => void {
+      return addTrigger(condition, callbackOrOptions);
+    },
+
+    unwatch(name: string): void {
+      removeTrigger(name);
+    },
+
     random(): number {
       return random();
     },

package/src/story-init.ts

@@ -1,63 +1,30 @@
+import { h, render } from 'preact';
 import { useStoryStore } from './store';
 import { tokenize } from './markup/tokenizer';
 import { buildAST } from './markup/ast';
-import { execute } from './expression';
-import type { ASTNode } from './markup/ast';
+import { renderNodes } from './markup/render';
 import { setSaveTitlePassage } from './saves/save-manager';
-import { deepClone } from './class-registry';
 
 /**
- * Walk AST nodes from StoryInit and execute {set} and {do} imperatively
- * (no Preact rendering needed for initialization).
- */
-function walkAndExecute(
-  nodes: ASTNode[],
-  vars: Record<string, unknown>,
-  temps: Record<string, unknown>,
-) {
-  for (const node of nodes) {
-    if (node.type !== 'macro') continue;
-
-    if (node.name === 'set') {
-      execute(node.rawArgs, vars, temps);
-    } else if (node.name === 'do') {
-      const code = node.children
-        .map((n) => (n.type === 'text' ? n.value : ''))
-        .join('');
-      execute(code, vars, temps);
-    }
-  }
-}
-
-/**
- * Execute the StoryInit passage: tokenize, parse, and run all {set}/{do} macros.
- * Called during boot and after restart() to ensure variables are initialized.
+ * Execute the StoryInit passage: tokenize, parse, and render all macros
+ * into a detached DOM node so their side effects fire through the normal
+ * Preact pipeline. This is macro-agnostic — any macro works in StoryInit.
  */
 export function executeStoryInit() {
   const state = useStoryStore.getState();
   if (!state.storyData) return;
 
   const storyInit = state.storyData.passages.get('StoryInit');
-  if (!storyInit) return;
-
-  const tokens = tokenize(storyInit.content);
-  const ast = buildAST(tokens);
-
-  const vars = deepClone(state.variables);
-  const temps = deepClone(state.temporary);
-
-  walkAndExecute(ast, vars, temps);
-
-  // Apply all changes to the store
-  for (const key of Object.keys(vars)) {
-    if (vars[key] !== state.variables[key]) {
-      state.setVariable(key, vars[key]);
-    }
-  }
-  for (const key of Object.keys(temps)) {
-    if (temps[key] !== state.temporary[key]) {
-      state.setTemporary(key, temps[key]);
-    }
+  if (storyInit) {
+    const tokens = tokenize(storyInit.content);
+    const ast = buildAST(tokens);
+
+    const container = document.createElement('div');
+    render(
+      h(() => renderNodes(ast) as any, null),
+      container,
+    );
+    render(null, container);
   }
 
   // Register SaveTitle passage if it exists

package/src/triggers.ts

@@ -0,0 +1,161 @@
+import { evaluate, execute } from './expression';
+import { useStoryStore } from './store';
+
+export interface WatchOptions {
+  goto?: string;
+  dialog?: string;
+  run?: string;
+  once?: boolean;
+  name?: string;
+  priority?: number;
+}
+
+interface Trigger {
+  id: number;
+  name?: string;
+  condition: string;
+  callback?: () => void;
+  options?: WatchOptions;
+  lastResult: boolean;
+  priority: number;
+}
+
+let nextId = 0;
+let triggers: Trigger[] = [];
+let checking = false;
+
+type DialogCallback = () => void;
+let dialogQueue: string[] = [];
+let dialogNotify: DialogCallback | null = null;
+
+function evalCondition(condition: string): boolean {
+  const state = useStoryStore.getState();
+  try {
+    return !!evaluate(condition, state.variables, state.temporary);
+  } catch {
+    return false;
+  }
+}
+
+export function addTrigger(
+  condition: string,
+  callbackOrOptions: (() => void) | WatchOptions,
+): () => void {
+  const id = nextId++;
+  const isCallback = typeof callbackOrOptions === 'function';
+  const options = isCallback ? undefined : callbackOrOptions;
+  const callback = isCallback ? callbackOrOptions : undefined;
+
+  const trigger: Trigger = {
+    id,
+    name: options?.name,
+    condition,
+    callback,
+    options,
+    lastResult: evalCondition(condition),
+    priority: options?.priority ?? 0,
+  };
+
+  triggers.push(trigger);
+  triggers.sort((a, b) => b.priority - a.priority);
+
+  return () => {
+    triggers = triggers.filter((t) => t.id !== id);
+  };
+}
+
+export function removeTrigger(name: string): void {
+  triggers = triggers.filter((t) => t.name !== name);
+}
+
+function fireTrigger(trigger: Trigger): void {
+  const { callback, options } = trigger;
+
+  if (callback) {
+    callback();
+    return;
+  }
+
+  if (!options) return;
+
+  if (options.run) {
+    const state = useStoryStore.getState();
+    execute(options.run, state.variables, state.temporary);
+  }
+
+  if (options.dialog) {
+    dialogQueue.push(options.dialog);
+    dialogNotify?.();
+  }
+
+  if (options.goto) {
+    useStoryStore.getState().navigate(options.goto);
+  }
+}
+
+const MAX_RECHECK_DEPTH = 10;
+
+export function checkTriggers(): void {
+  if (checking) return;
+  checking = true;
+
+  try {
+    for (let depth = 0; depth < MAX_RECHECK_DEPTH; depth++) {
+      let anyFired = false;
+
+      // Snapshot triggers list — firing may remove `once` triggers
+      const current = [...triggers];
+      for (const trigger of current) {
+        // Skip if removed during this cycle
+        if (!triggers.includes(trigger)) continue;
+
+        const result = evalCondition(trigger.condition);
+        const wasFalse = !trigger.lastResult;
+        trigger.lastResult = result;
+
+        if (result && wasFalse) {
+          anyFired = true;
+
+          if (trigger.options?.once) {
+            triggers = triggers.filter((t) => t.id !== trigger.id);
+          }
+
+          fireTrigger(trigger);
+        }
+      }
+
+      if (!anyFired) break;
+    }
+  } finally {
+    checking = false;
+  }
+}
+
+export function reinitTriggerState(): void {
+  for (const trigger of triggers) {
+    trigger.lastResult = evalCondition(trigger.condition);
+  }
+}
+
+export function resetTriggers(): void {
+  triggers = [];
+  dialogQueue = [];
+  nextId = 0;
+}
+
+export function subscribeTriggerDialogs(cb: () => void): () => void {
+  dialogNotify = cb;
+  // Flush any queued dialogs
+  if (dialogQueue.length > 0) cb();
+  return () => {
+    if (dialogNotify === cb) dialogNotify = null;
+  };
+}
+
+export function shiftDialogQueue(): string | undefined {
+  return dialogQueue.shift();
+}
+
+export function dialogQueueLength(): number {
+  return dialogQueue.length;
+}