@rohal12/spindle 0.49.1 → 0.50.1

package/src/story-init.ts

@@ -1,16 +1,33 @@
 import { h, render } from 'preact';
-import { useStoryStore } from './store';
+import { useStoryStore, recordStoryInitState } from './store';
 import { tokenize } from './markup/tokenizer';
 import { buildAST } from './markup/ast';
 import { renderNodes } from './markup/render';
 import { setSaveTitlePassage } from './saves/save-manager';
 
+/** Hidden container holding the currently mounted StoryInit tree. */
+let storyInitContainer: HTMLElement | null = null;
+
+/**
+ * Unmount the current StoryInit tree (running its effect cleanups, e.g.
+ * pending {timed}/{repeat} timers) and remove its container.
+ */
+function unmountStoryInit(): void {
+  if (!storyInitContainer) return;
+  render(null, storyInitContainer);
+  storyInitContainer.remove();
+  storyInitContainer = null;
+}
+
 /**
  * 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.
+ * Re-executing (on restart) first unmounts the previous StoryInit tree.
  */
 export function executeStoryInit() {
+  unmountStoryInit();
+
   const state = useStoryStore.getState();
   if (!state.storyData) return;
 
@@ -19,16 +36,22 @@ export function executeStoryInit() {
     const tokens = tokenize(storyInit.content);
     const ast = buildAST(tokens);
 
-    // Mount into a persistent hidden container. We intentionally do NOT
-    // unmount — this lets async effects (useEffect, setTimeout, etc.)
-    // inside StoryInit macros fire through the normal Preact pipeline.
+    // Mount into a persistent hidden container. It stays mounted until the
+    // next execution (restart) — this lets async effects (useEffect,
+    // setTimeout, etc.) inside StoryInit macros fire through the normal
+    // Preact pipeline.
     const container = document.createElement('div');
     container.style.display = 'none';
     document.body.appendChild(container);
+    storyInitContainer = container;
     render(
       h(() => renderNodes(ast) as any, null),
       container,
     );
+
+    // The start moment was recorded before StoryInit ran; its synchronous
+    // changes ({set}, {do}) belong to it.
+    recordStoryInitState();
   }
 
   // Register SaveTitle passage if it exists

package/src/story-variables.ts

@@ -1,4 +1,5 @@
 import type { Passage } from './parser';
+import { tokenize } from './markup/tokenizer';
 
 export type VarType = 'number' | 'string' | 'boolean' | 'array' | 'object';
 
@@ -17,6 +18,10 @@ function declarationRegex(sigil: string): RegExp {
   return new RegExp(`^${escaped}(\\w+)\\s*=\\s*(.+)$`);
 }
 const VAR_REF_RE = /\$(\w+(?:\.\w+)*)/g;
+/** `{` followed by a sigil starts an interpolation block inside literal text. */
+const INTERP_START_RE = /^[$_@%]\w/;
+/** Quoted first argument of an input macro naming a story variable. */
+const QUOTED_VAR_ARG_RE = /^["']\$(\w+(?:\.\w+)*)["']?$/;
 const FOR_LOCAL_RE = /\{for\s+@(\w+)(?:\s*,\s*@(\w+))?\s+of\b/g;
 
 const VALID_VAR_TYPES = new Set<string>(['number', 'string', 'boolean']);
@@ -148,15 +153,190 @@ function validateRef(
   return null;
 }
 
+/**
+ * Built-in input macros whose first argument names the bound story variable,
+ * quoted or not (e.g. `{textbox "$name"}`).
+ */
+const BUILTIN_STORE_VAR_MACROS: readonly string[] = [
+  'checkbox',
+  'cycle',
+  'listbox',
+  'numberbox',
+  'radiobutton',
+  'textarea',
+  'textbox',
+];
+
+type RefCallback = (ref: string) => void;
+
+/** Report every `$var.path` in a code segment free of strings/comments. */
+function scanRefs(segment: string, onRef: RefCallback): void {
+  for (const match of segment.matchAll(VAR_REF_RE)) onRef(match[1]!);
+}
+
+/** Index of the quote closing the string opened at `start` (or the end). */
+function findClosingQuote(code: string, start: number): number {
+  const quote = code[start];
+  let i = start + 1;
+  while (i < code.length && code[i] !== quote) {
+    i += code[i] === '\\' ? 2 : 1;
+  }
+  return Math.min(i, code.length);
+}
+
+/**
+ * Scan literal text (string contents, HTML attribute values) for `{$…}`
+ * interpolation blocks, which interpolating macros and HTML attributes
+ * resolve at runtime. A bare `$word` in literal text is not a reference.
+ */
+function scanInterpolations(text: string, onRef: RefCallback): void {
+  let i = text.indexOf('{');
+  while (i !== -1) {
+    const next = INTERP_START_RE.test(text.slice(i + 1, i + 3))
+      ? scanCode(text, i + 1, onRef, true)
+      : i + 1;
+    i = text.indexOf('{', next);
+  }
+}
+
+/**
+ * Scan a template literal starting just after its opening backtick: literal
+ * parts are text, `${…}` parts are code. Returns the index just past the
+ * closing backtick.
+ */
+function scanTemplate(code: string, start: number, onRef: RefCallback): number {
+  let i = start;
+  let textStart = start;
+  while (i < code.length) {
+    const ch = code[i];
+    if (ch === '\\') {
+      i += 2;
+    } else if (ch === '`') {
+      scanInterpolations(code.slice(textStart, i), onRef);
+      return i + 1;
+    } else if (ch === '$' && code[i + 1] === '{') {
+      scanInterpolations(code.slice(textStart, i), onRef);
+      i = textStart = scanCode(code, i + 2, onRef, true);
+    } else {
+      i++;
+    }
+  }
+  scanInterpolations(code.slice(textStart), onRef);
+  return code.length;
+}
+
+/**
+ * Report `$var` references in JavaScript code. Like the string-aware
+ * expression transformer, sigils inside string literals are left alone while
+ * template-literal `${…}` parts are code; comments are skipped too. When
+ * `nested`, stops at the `}` closing the enclosing block and returns the index
+ * just past it.
+ */
+function scanCode(
+  code: string,
+  start: number,
+  onRef: RefCallback,
+  nested = false,
+): number {
+  let i = start;
+  let segStart = start;
+  let depth = 0;
+  while (i < code.length) {
+    const ch = code[i];
+    const next = code[i + 1];
+    const isComment = ch === '/' && (next === '/' || next === '*');
+    if (ch === '"' || ch === "'" || ch === '`' || isComment) {
+      scanRefs(code.slice(segStart, i), onRef);
+      if (ch === '`') {
+        i = scanTemplate(code, i + 1, onRef);
+      } else if (isComment) {
+        const close = code.indexOf(next === '/' ? '\n' : '*/', i + 2);
+        i = close === -1 ? code.length : next === '/' ? close : close + 2;
+      } else {
+        const close = findClosingQuote(code, i);
+        scanInterpolations(code.slice(i + 1, close), onRef);
+        i = Math.min(close + 1, code.length);
+      }
+      segStart = i;
+      continue;
+    }
+    if (nested && ch === '{') {
+      depth++;
+    } else if (nested && ch === '}' && depth-- === 0) {
+      scanRefs(code.slice(segStart, i), onRef);
+      return i + 1;
+    }
+    i++;
+  }
+  scanRefs(code.slice(segStart), onRef);
+  return code.length;
+}
+
+/**
+ * Report the `$var` references a passage evaluates at runtime: `{$var}`
+ * displays, `{$expr}` expressions, macro arguments and `{do}` bodies (as
+ * code), quoted variable names bound by input macros, and `{$…}`
+ * interpolations in HTML attributes. Prose is literal text and not scanned.
+ */
+function collectPassageRefs(
+  content: string,
+  storeVarMacros: ReadonlySet<string>,
+  onRef: RefCallback,
+): void {
+  const tokens = tokenize(content);
+  for (let t = 0; t < tokens.length; t++) {
+    const token = tokens[t]!;
+    if (token.type === 'variable') {
+      if (token.scope === 'variable' && token.name) onRef(token.name);
+    } else if (token.type === 'expression') {
+      scanCode(token.expression, 0, onRef);
+    } else if (token.type === 'html') {
+      for (const value of Object.values(token.attributes)) {
+        scanInterpolations(value, onRef);
+      }
+    } else if (token.type === 'macro' && !token.isClose) {
+      scanCode(token.rawArgs, 0, onRef);
+
+      if (storeVarMacros.has(token.name.toLowerCase())) {
+        const first = token.rawArgs.trim().split(/\s+/)[0] ?? '';
+        const quoted = QUOTED_VAR_ARG_RE.exec(first);
+        if (quoted) onRef(quoted[1]!);
+      }
+
+      if (token.name === 'do') {
+        // A {do} body is JavaScript: scan its source text as code, however
+        // the markup tokenizer split it up.
+        let close = t + 1;
+        while (close < tokens.length) {
+          const c = tokens[close]!;
+          if (c.type === 'macro' && c.isClose && c.name === 'do') break;
+          close++;
+        }
+        if (close < tokens.length) {
+          scanCode(content.slice(token.end, tokens[close]!.start), 0, onRef);
+          t = close;
+        }
+      }
+    }
+  }
+}
+
 /**
  * Scan all passages for $var references, check against schema.
  * Returns list of error messages (empty = valid).
+ *
+ * `storeVarMacros` lists the input macros whose first argument names a bound
+ * variable; it defaults to the built-in ones.
  */
 export function validatePassages(
   passages: Map<string, Passage>,
   schema: Map<string, VariableSchema>,
+  storeVarMacros: Iterable<string> = BUILTIN_STORE_VAR_MACROS,
 ): string[] {
   const errors: string[] = [];
+  const storeVarSet = new Set(
+    Array.from(storeVarMacros, (m) => m.toLowerCase()),
+  );
 
   for (const [name, passage] of passages) {
     // Don't validate the StoryVariables/StoryTransients passages themselves
@@ -164,15 +344,12 @@ export function validatePassages(
 
     const forLocals = extractForLocals(passage.content);
 
-    let match: RegExpExecArray | null;
-    VAR_REF_RE.lastIndex = 0;
-    while ((match = VAR_REF_RE.exec(passage.content)) !== null) {
-      const ref = match[1]!;
+    collectPassageRefs(passage.content, storeVarSet, (ref) => {
       const error = validateRef(ref, schema, forLocals);
       if (error) {
         errors.push(`Passage "${name}": ${error}`);
       }
-    }
+    });
   }
 
   return errors;

package/src/triggers.ts

@@ -1,4 +1,5 @@
-import { evaluate, execute } from './expression';
+import { evaluate } from './expression';
+import { executeMutation } from './execute-mutation';
 import { useStoryStore } from './store';
 
 export interface WatchOptions {
@@ -25,6 +26,8 @@ interface Trigger {
   options?: WatchOptions;
   lastResult: boolean;
   priority: number;
+  /** Identity of a {watch} macro's watcher (see addMacroTrigger). */
+  macroKey?: string;
 }
 
 let nextId = 0;
@@ -58,9 +61,10 @@ function evalCondition(condition: string): boolean {
   }
 }
 
-export function addTrigger(
+function registerTrigger(
   condition: string,
   callbackOrOptions: (() => void) | WatchOptions,
+  macroKey?: string,
 ): () => void {
   const id = nextId++;
   const isCallback = typeof callbackOrOptions === 'function';
@@ -75,6 +79,7 @@ export function addTrigger(
     options,
     lastResult: evalCondition(condition),
     priority: options?.priority ?? 0,
+    macroKey,
   };
 
   triggers.push(trigger);
@@ -85,6 +90,32 @@ export function addTrigger(
   };
 }
 
+export function addTrigger(
+  condition: string,
+  callbackOrOptions: (() => void) | WatchOptions,
+): () => void {
+  return registerTrigger(condition, callbackOrOptions);
+}
+
+/**
+ * Register the watcher of a {watch} macro. Watchers outlive the passage
+ * that declared them, and that passage mounts its macros again on every
+ * visit (and on re-renders that remount them), so an identical watcher
+ * (same condition and options) that is still registered is kept instead
+ * of being added a second time.
+ */
+export function addMacroTrigger(
+  condition: string,
+  options: WatchOptions,
+): void {
+  const sortedOptions = Object.fromEntries(
+    Object.entries(options).sort(([a], [b]) => (a < b ? -1 : 1)),
+  );
+  const macroKey = JSON.stringify([condition, sortedOptions]);
+  if (triggers.some((t) => t.macroKey === macroKey)) return;
+  registerTrigger(condition, options, macroKey);
+}
+
 export function removeTrigger(name: string): void {
   triggers = triggers.filter((t) => t.name !== name);
 }
@@ -100,8 +131,16 @@ function fireTrigger(trigger: Trigger): void {
   if (!options) return;
 
   if (options.run) {
-    const state = useStoryStore.getState();
-    execute(options.run, state.variables, state.temporary);
+    // Store state is frozen; go through the mutation pipeline so the run
+    // action works on clones and its changes are committed to the store.
+    try {
+      executeMutation(options.run, {}, () => {});
+    } catch (err) {
+      console.error(
+        `spindle: Error in watch run action for "${trigger.condition}":`,
+        err,
+      );
+    }
   }
 
   if (options.dialog) {
@@ -116,42 +155,105 @@ function fireTrigger(trigger: Trigger): void {
 
 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;
+function runCheckLoop(): void {
+  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;
+    // 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;
+      const result = evalCondition(trigger.condition);
+      const wasFalse = !trigger.lastResult;
+      trigger.lastResult = result;
 
-        if (result && wasFalse) {
-          anyFired = true;
+      if (result && wasFalse) {
+        anyFired = true;
 
-          if (trigger.options?.once) {
-            triggers = triggers.filter((t) => t.id !== trigger.id);
-          }
-
-          fireTrigger(trigger);
+        if (trigger.options?.once) {
+          triggers = triggers.filter((t) => t.id !== trigger.id);
         }
-      }
 
-      if (!anyFired) break;
+        fireTrigger(trigger);
+      }
     }
+
+    if (!anyFired) break;
+  }
+}
+
+export function checkTriggers(): void {
+  if (checking) return;
+  checking = true;
+
+  try {
+    runCheckLoop();
   } finally {
     checking = false;
   }
 }
 
+/** Number of live connectTriggersToStore() subscriptions. */
+let connections = 0;
+
+/**
+ * Check watchers against a navigation that navigate() has just completed.
+ * Called by the store before it records the entered moment, so run actions
+ * become part of that moment. Runs even when the navigation itself came
+ * from a watcher (a check already in progress), since that check started
+ * before the navigation and cannot see it.
+ */
+export function checkTriggersOnNavigation(): void {
+  if (connections === 0) return;
+  const wasChecking = checking;
+  checking = true;
+
+  try {
+    runCheckLoop();
+  } finally {
+    checking = wasChecking;
+  }
+}
+
+/**
+ * Re-evaluate watchers whenever a namespace their conditions can read
+ * ($variables, _temporary, %transient) changes. Navigation is left to the
+ * store: navigate() checks watchers once the new moment is complete
+ * (checkTriggersOnNavigation), while history traversal and loads
+ * reinitialize watcher state instead of firing.
+ */
+export function connectTriggersToStore(): () => void {
+  let prev = useStoryStore.getState();
+  connections++;
+  const unsubscribe = useStoryStore.subscribe((state) => {
+    const before = prev;
+    // Update before checking: run/goto actions re-enter this listener.
+    prev = state;
+
+    if (state.navigationId !== before.navigationId) return;
+
+    if (
+      state.variables === before.variables &&
+      state.temporary === before.temporary &&
+      state.transient === before.transient
+    ) {
+      return;
+    }
+
+    checkTriggers();
+  });
+
+  let connected = true;
+  return () => {
+    if (!connected) return;
+    connected = false;
+    connections--;
+    unsubscribe();
+  };
+}
+
 export function reinitTriggerState(): void {
   for (const trigger of triggers) {
     trigger.lastResult = evalCondition(trigger.condition);

package/src/types-drift-check.ts

@@ -91,3 +91,15 @@ const _exampleMacro: PublishedMacroDefinition = {
     );
   },
 };
+
+// Headless entry point (`@rohal12/spindle/headless`): types/headless.d.ts must
+// match src/headless.ts.
+import type { bootStory as SourceBootStory } from './headless';
+import type { bootStory as PublishedBootStory } from '../types/headless';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _bootSourceToPublished: typeof PublishedBootStory =
+  {} as typeof SourceBootStory;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _bootPublishedToSource: typeof SourceBootStory =
+  {} as typeof PublishedBootStory;

package/src/utils/live-locals.ts

@@ -0,0 +1,22 @@
+/**
+ * Read-only view of a locals scope that always reflects its current values.
+ *
+ * Used as the LocalsValuesContext value for one-shot detached renders
+ * ({button}/{link} bodies). Those trees are unmounted right after rendering,
+ * so the owning scope's re-render never reaches them; reading through
+ * getValues() lets a macro see a local assigned earlier in the same body.
+ */
+export function liveLocalsView(
+  getValues: () => Record<string, unknown>,
+): Record<string, unknown> {
+  return new Proxy({} as Record<string, unknown>, {
+    get: (_, key) => (typeof key === 'string' ? getValues()[key] : undefined),
+    has: (_, key) => key in getValues(),
+    ownKeys: () => Reflect.ownKeys(getValues()),
+    getOwnPropertyDescriptor: (_, key) => {
+      const desc = Object.getOwnPropertyDescriptor(getValues(), key);
+      // Keys don't exist on the proxy target, so they must be configurable.
+      return desc ? { ...desc, configurable: true } : undefined;
+    },
+  });
+}

package/types/headless.d.ts

@@ -0,0 +1,27 @@
+import type { StoryAPI } from './index';
+
+/** Options for {@link bootStory}. */
+export interface BootStoryOptions {
+  /**
+   * A compiled story: a full HTML file produced by Twine/twee-ts with the
+   * Spindle format, or any HTML containing its `<tw-storydata>` element.
+   */
+  html: string;
+  /**
+   * Keep passage transitions. Default `false`: the default transition is set
+   * to `none` before boot, because headless runs have nothing to animate and
+   * `fade-through` delays mounting the next passage (and its actions) by its
+   * duration. Passage `[transition:…]` tags and the story's own
+   * `Story.setTransition()` calls still apply.
+   */
+  transitions?: boolean;
+}
+
+/**
+ * Boot a compiled story in the current `document` (provided by happy-dom,
+ * jsdom, ...) and resolve with the `Story` API once the first passage is
+ * shown. One story per module instance: boot each story in its own test file.
+ */
+export function bootStory(options: BootStoryOptions): Promise<StoryAPI>;
+
+export type { StoryAPI };