@rohal12/spindle 0.49.1 → 0.50.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.49.1",
+  "version": "0.50.1",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",
@@ -29,12 +29,17 @@
     "./tooling": {
       "types": "./types/tooling.d.ts",
       "import": "./dist/pkg/tooling.js"
+    },
+    "./headless": {
+      "types": "./types/headless.d.ts",
+      "import": "./dist/pkg/headless.js"
     }
   },
   "files": [
     "dist/pkg/index.js",
     "dist/pkg/format.js",
     "dist/pkg/tooling.js",
+    "dist/pkg/headless.js",
     "dist/pkg/story-variables.js",
     "dist/pkg/macro-registry.json",
     "types",

package/src/class-registry.ts

@@ -224,6 +224,17 @@ export function deserialize<T>(value: T): T {
       return instance;
     }
 
+    // Already-live built-in — pass through as-is, so deserializing an
+    // already-deserialized value is a no-op instead of flattening it to {}
+    if (
+      val instanceof Date ||
+      val instanceof RegExp ||
+      val instanceof Map ||
+      val instanceof Set
+    ) {
+      return val;
+    }
+
     // Already-live registered class instance — pass through as-is
     const ctor = (obj as object).constructor as Constructor;
     if (ctorToName.has(ctor)) {

package/src/components/Passage.tsx

@@ -6,16 +6,35 @@ import {
   useState,
 } from 'preact/hooks';
 import { tokenize } from '../markup/tokenizer';
-import { buildAST } from '../markup/ast';
+import { buildAST, type ASTNode } from '../markup/ast';
 import { renderNodes, NobrContext } from '../markup/render';
 import { useStoryStore } from '../store';
 import type { Passage as PassageData } from '../parser';
 import { sourceLocationOf } from '../utils/source-location';
 import { emitFromRender } from '../event-emitter';
+import { markPassageRendered } from '../passage-render-state';
+
+/**
+ * Parsed AST per passage. The renderer keys children by AST node identity,
+ * so re-rendering a passage (e.g. PassageReady on every PassageDisplay
+ * render) must reuse its AST — a fresh parse would remount every macro in
+ * it and re-run its {set}/{do} side effects (#175).
+ */
+const astCache = new WeakMap<
+  PassageData,
+  { content: string; ast: ASTNode[] }
+>();
+
+function parsePassage(passage: PassageData): ASTNode[] {
+  const cached = astCache.get(passage);
+  if (cached && cached.content === passage.content) return cached.ast;
+  const ast = buildAST(tokenize(passage.content));
+  astCache.set(passage, { content: passage.content, ast });
+  return ast;
+}
 
 export function renderPassageContent(passage: PassageData) {
-  const tokens = tokenize(passage.content);
-  const ast = buildAST(tokens);
+  const ast = parsePassage(passage);
   const nobr = passage.tags.includes('nobr');
   return renderNodes(ast, nobr ? { nobr: true } : undefined);
 }
@@ -102,6 +121,7 @@ export function Passage({ passage, dataTransition }: PassageProps) {
   // Passage so every navigation that shows a passage mounts a new one.
   const elRef = useRef<HTMLDivElement>(null);
   useLayoutEffect(() => {
+    markPassageRendered(passage.name);
     if (elRef.current) {
       emitFromRender('passagerender', passage.name, elRef.current);
     }

package/src/components/macros/Button.tsx

@@ -7,6 +7,7 @@ import {
   LocalsValuesContext,
   NobrContext,
 } from '../../markup/render';
+import { liveLocalsView } from '../../utils/live-locals';
 
 defineMacro({
   name: 'button',
@@ -29,7 +30,7 @@ defineMacro({
           { value: { update: ctx.update, getValues: ctx.getValues } },
           h(
             LocalsValuesContext.Provider,
-            { value: ctx.getValues() },
+            { value: liveLocalsView(ctx.getValues) },
             renderNodes(children),
           ),
         ),

package/src/components/macros/Do.tsx

@@ -4,6 +4,7 @@ defineMacro({
   name: 'do',
   block: true,
   render({ children = [] }, ctx) {
+    // The tokenizer keeps the body verbatim as a single text node
     const code = ctx.collectText(children);
 
     ctx.hooks.useLayoutEffect(() => {

package/src/components/macros/For.tsx

@@ -88,6 +88,10 @@ function ForIteration({
 
   const getValues = useCallback(() => valuesRef.current, []);
   const update = useCallback((key: string, value: unknown) => {
+    // Apply synchronously so later macros in the same render pass (e.g. a
+    // second {set}) read the new value via getValues(); the state update
+    // then re-renders consumers of LocalsValuesContext.
+    valuesRef.current = { ...valuesRef.current, [key]: value };
     setLocalMutations((prev) => ({ ...prev, [key]: value }));
   }, []);
   const updater = useMemo(() => ({ update, getValues }), [update, getValues]);

package/src/components/macros/Include.tsx

@@ -11,8 +11,6 @@ defineMacro({
   render({ rawArgs }, ctx) {
     const storyData = useStoryStore((s) => s.storyData);
 
-    if (!storyData) return null;
-
     const inline = /\binline\b/.test(rawArgs);
     const nameExpr = rawArgs.replace(/\binline\b/, '').trim();
 
@@ -24,19 +22,28 @@ defineMacro({
       passageName = nameExpr.replace(/^["']|["']$/g, '');
     }
 
-    const passage = storyData.passages.get(passageName);
+    const passage = storyData?.passages.get(passageName);
+    // Parse once per included passage: the renderer keys children by AST
+    // node identity, so a fresh AST is what remounts the content when the
+    // included passage changes, while re-renders of the same passage keep
+    // its macros mounted (#175).
+    const ast = ctx.hooks.useMemo(
+      () => (passage ? buildAST(tokenize(passage.content)) : null),
+      [passage],
+    );
+
+    if (!storyData) return null;
+
     if (passage) {
       useStoryStore.getState().trackRender(passageName);
     }
-    if (!passage) {
+    if (!passage || !ast) {
       return (
         <span class="error">{`{include${ctx.sourceLocation()}: passage "${passageName}" not found}`}</span>
       );
     }
 
     const nobr = passage.tags.includes('nobr');
-    const tokens = tokenize(passage.content);
-    const ast = buildAST(tokens);
     const content = inline
       ? ctx.renderInlineNodes(ast)
       : ctx.renderNodes(ast, nobr ? { nobr: true } : undefined);

package/src/components/macros/MacroLink.tsx

@@ -8,6 +8,7 @@ import {
   NobrContext,
 } from '../../markup/render';
 import { defineMacro } from '../../define-macro';
+import { liveLocalsView } from '../../utils/live-locals';
 
 function parseArgs(rawArgs: string): {
   display: string;
@@ -45,7 +46,7 @@ function renderChildrenDetached(
       { value: { update, getValues } },
       h(
         LocalsValuesContext.Provider,
-        { value: getValues() },
+        { value: liveLocalsView(getValues) },
         renderNodes(children),
       ),
     ),

package/src/components/macros/PassageDisplay.tsx

@@ -70,13 +70,21 @@ defineMacro({
   interpolate: true,
   render(_props, ctx) {
     const currentPassage = useStoryStore((s) => s.currentPassage);
+    const navigationId = useStoryStore((s) => s.navigationId);
     const storyData = useStoryStore((s) => s.storyData);
     const renderDeferred = useStoryStore((s) => s.renderDeferred);
 
-    // Render-gating: displayedPassage controls which passage is visually shown.
+    // Render-gating: displayed 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);
+    // transition state machine. Identity is the navigation id, not the passage
+    // name, so revisiting/restarting/loading the same passage remounts it.
+    const [displayed, setDisplayed] = useState({
+      passage: currentPassage,
+      id: navigationId,
+    });
+    const displayedPassage = displayed.passage;
+    const setDisplayedPassage = (passage: string) =>
+      setDisplayed({ passage, id: navigationId });
 
     // Track the resolved transition type for the data-transition prop
     const resolvedTypeRef = useRef<string>('fade');
@@ -97,7 +105,7 @@ defineMacro({
       cleanupSnapshots(containerRef.current);
     }, []);
 
-    // State machine effect — triggers on passage change
+    // State machine effect — triggers on every navigation
     useEffect(() => {
       const store = useStoryStore.getState();
       const { history, historyIndex, transitionConfig } = store;
@@ -118,9 +126,8 @@ defineMacro({
         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
+      // Already showing this navigation (initial render)
+      if (navigationId === displayed.id) {
         return;
       }
 
@@ -244,7 +251,7 @@ defineMacro({
       // Fallback: unknown type, just mount
       setDisplayedPassage(currentPassage);
       // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [currentPassage]);
+    }, [navigationId]);
 
     // When render is deferred, show StoryLoading passage or nothing
     const effectivePassage = renderDeferred
@@ -270,7 +277,7 @@ defineMacro({
       >
         {!renderDeferred && readyPassage && (
           <div
-            key={`ready-${currentPassage}`}
+            key={`ready-${navigationId}`}
             hidden
           >
             {renderPassageContent(readyPassage)}
@@ -283,7 +290,7 @@ defineMacro({
           {effectivePassage && (
             <Passage
               passage={effectivePassage}
-              key={renderDeferred ? 'loading' : displayedPassage}
+              key={renderDeferred ? 'loading' : `nav-${displayed.id}`}
               dataTransition={renderDeferred ? 'none' : resolvedTypeRef.current}
             />
           )}

package/src/components/macros/SaveManager.tsx

@@ -15,6 +15,8 @@ import {
   renameSave,
   exportSave,
   importSave,
+  deserializePayload,
+  saveWithHooks,
   type PlaythroughGroup,
 } from '../../saves/save-manager';
 import { DialogCloseContext } from '../PassageDialog';
@@ -101,11 +103,13 @@ export function SaveManagerContent() {
     });
   };
 
+  // Dialog saves are not slot saves, so the save hooks get no slot.
   const handleNewSave = async () => {
     if (!ifid || !playthroughId) return;
     try {
-      const payload = getSavePayload();
-      await createSave(ifid, playthroughId, payload);
+      await saveWithHooks(undefined, undefined, getSavePayload, (payload) =>
+        createSave(ifid, playthroughId, payload),
+      );
       showStatus('Save created');
       await refresh();
     } catch {
@@ -115,8 +119,16 @@ export function SaveManagerContent() {
 
   const handleOverwrite = async (saveId: string) => {
     try {
-      const payload = getSavePayload();
-      await overwriteSave(saveId, payload);
+      await saveWithHooks(
+        undefined,
+        undefined,
+        getSavePayload,
+        async (payload) => {
+          if (!(await overwriteSave(saveId, payload))) {
+            throw new Error('Save not found');
+          }
+        },
+      );
       showStatus('Save overwritten');
       await refresh();
     } catch {
@@ -126,7 +138,8 @@ export function SaveManagerContent() {
 
   const handleLoad = async (save: SaveRecord) => {
     try {
-      loadFromPayload(save.payload);
+      // Stored records hold serialized variables; the store expects live ones
+      loadFromPayload(deserializePayload(save.payload));
       showStatus('Game loaded');
       if (closeDialog) setTimeout(closeDialog, 500);
     } catch {

package/src/components/macros/Watch.tsx

@@ -1,5 +1,5 @@
 import { defineMacro } from '../../define-macro';
-import { addTrigger, removeTrigger } from '../../triggers';
+import { addMacroTrigger, removeTrigger } from '../../triggers';
 import type { WatchOptions } from '../../triggers';
 
 defineMacro({
@@ -48,10 +48,11 @@ defineMacro({
 
     // Register during render (like {set}) — triggers survive navigation
     // and are cleaned up via resetTriggers() on restart or {unwatch}.
+    // Remounts (revisits, re-rendered branches) keep the registered watcher.
     const registered = hooks.useRef(false);
     if (!registered.current) {
       registered.current = true;
-      addTrigger(condition, options);
+      addMacroTrigger(condition, options);
     }
 
     return null;

package/src/components/macros/WidgetInvocation.tsx

@@ -200,6 +200,10 @@ function WidgetBody({
 
   const getValues = useCallback(() => valuesRef.current, []);
   const update = useCallback((key: string, value: unknown) => {
+    // Apply synchronously so later macros in the same render pass (e.g. a
+    // second {set}) read the new value via getValues(); the state update
+    // then re-renders consumers of LocalsValuesContext.
+    valuesRef.current = { ...valuesRef.current, [key]: value };
     setLocalMutations((prev) => ({ ...prev, [key]: value }));
   }, []);
   const updater = useMemo(() => ({ update, getValues }), [update, getValues]);

package/src/execute-mutation.ts

@@ -2,6 +2,79 @@ import { useStoryStore } from './store';
 import { execute } from './expression';
 import { deepClone } from './class-registry';
 
+/**
+ * Structural equality for a deepClone() copy against its source. Lets
+ * executeMutation write back only the variables the code actually changed,
+ * so untouched clones don't overwrite updates made during execution
+ * (e.g. Story.set called from inside {do}).
+ */
+function deepEqual(
+  a: unknown,
+  b: unknown,
+  seen: Map<object, object> = new Map(),
+): boolean {
+  if (Object.is(a, b)) return true;
+  if (
+    a === null ||
+    b === null ||
+    typeof a !== 'object' ||
+    typeof b !== 'object'
+  ) {
+    return false;
+  }
+  if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) return false;
+  if (seen.get(a) === b) return true;
+  seen.set(a, b);
+
+  if (a instanceof Date) return a.getTime() === (b as Date).getTime();
+  if (a instanceof RegExp) return String(a) === String(b);
+  if (a instanceof Map || a instanceof Set) {
+    const bc = b as Map<unknown, unknown> | Set<unknown>;
+    if (a.size !== bc.size) return false;
+    const ai = a.entries();
+    const bi = bc.entries();
+    for (
+      let x = ai.next(), y = bi.next();
+      !x.done;
+      x = ai.next(), y = bi.next()
+    ) {
+      if (!deepEqual(x.value, y.value, seen)) return false;
+    }
+    return true;
+  }
+
+  const ao = a as Record<string, unknown>;
+  const bo = b as Record<string, unknown>;
+  const keys = Object.keys(ao);
+  if (keys.length !== Object.keys(bo).length) return false;
+  for (const key of keys) {
+    if (!(key in bo) || !deepEqual(ao[key], bo[key], seen)) return false;
+  }
+  return true;
+}
+
+/**
+ * Write the keys `code` changed (`clone` vs the pre-execution `before`) into
+ * an Immer draft of the same namespace, and delete the keys it removed.
+ * Untouched keys are left alone, so updates made during execution survive.
+ */
+function commitNamespace(
+  draft: Record<string, unknown>,
+  clone: Record<string, unknown>,
+  before: Record<string, unknown>,
+): void {
+  for (const key of Object.keys(clone)) {
+    if (!deepEqual(clone[key], before[key])) {
+      draft[key] = clone[key];
+    }
+  }
+  for (const key of Object.keys(before)) {
+    if (!(key in clone)) {
+      delete draft[key];
+    }
+  }
+}
+
 export function executeMutation(
   code: string,
   mergedLocals: Record<string, unknown>,
@@ -15,43 +88,22 @@ export function executeMutation(
 
   execute(code, vars, temps, localsClone, trans);
 
-  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]);
-    }
-  }
-  for (const key of Object.keys(trans)) {
-    if (trans[key] !== state.transient[key]) {
-      state.setTransient(key, trans[key]);
-    }
-  }
+  // Commit every store change in one update: watchers must see the whole
+  // mutation, and a watcher's run action must not be overwritten by keys
+  // this commit writes after it fired.
+  state.updateVariables((draft) => {
+    commitNamespace(draft.variables, vars, state.variables);
+    commitNamespace(draft.temporary, temps, state.temporary);
+    commitNamespace(draft.transient, trans, state.transient);
+  });
+
   for (const key of Object.keys(localsClone)) {
     if (localsClone[key] !== mergedLocals[key]) {
       scopeUpdate(key, localsClone[key]);
     }
   }
 
-  // Detect deleted keys
-  for (const key of Object.keys(state.variables)) {
-    if (!(key in vars)) {
-      state.deleteVariable(key);
-    }
-  }
-  for (const key of Object.keys(state.temporary)) {
-    if (!(key in temps)) {
-      state.deleteTemporary(key);
-    }
-  }
-  for (const key of Object.keys(state.transient)) {
-    if (!(key in trans)) {
-      state.deleteTransient(key);
-    }
-  }
+  // Detect deleted locals
   for (const key of Object.keys(mergedLocals)) {
     if (!(key in localsClone)) {
       scopeUpdate(key, undefined);

package/src/headless.ts

@@ -0,0 +1,87 @@
+/**
+ * Node entry point (`@rohal12/spindle/headless`): boot a compiled story in
+ * the DOM the caller provides (a vitest `happy-dom`/`jsdom` environment, or
+ * a global registrator), so the automation API works without a browser.
+ *
+ * DOM shims don't execute the story format's `<script type="module">`, so
+ * loading the compiled HTML alone never starts Spindle. This entry runs the
+ * same boot sequence directly.
+ */
+import { boot } from './index';
+import { useStoryStore } from './store';
+import type { StoryAPI } from './story-api';
+
+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;
+}
+
+let booted = false;
+
+/**
+ * Boot the story in the current `document` and resolve with the `Story` API
+ * once the first passage is shown (`:storyready`; after `Story.ready()` if
+ * the story defers rendering).
+ *
+ * The document body is replaced by the story's `<tw-storydata>` element and a
+ * `<div id="root">`. Spindle keeps its state in module scope, so a module
+ * instance can boot one story; use a separate test file (vitest isolates
+ * modules per file) for each fresh story.
+ */
+export function bootStory(options: BootStoryOptions): Promise<StoryAPI> {
+  if (typeof document === 'undefined') {
+    return Promise.reject(
+      new Error(
+        'spindle: bootStory() needs a DOM. Run it in a happy-dom or jsdom environment.',
+      ),
+    );
+  }
+  if (booted) {
+    return Promise.reject(
+      new Error(
+        'spindle: bootStory() was already called in this module instance; boot each story in its own test file.',
+      ),
+    );
+  }
+
+  const parsed = new DOMParser().parseFromString(options.html, 'text/html');
+  const storyData = parsed.querySelector('tw-storydata');
+  if (!storyData) {
+    return Promise.reject(
+      new Error('spindle: bootStory() found no <tw-storydata> in the HTML.'),
+    );
+  }
+  booted = true;
+
+  if (!options.transitions) {
+    useStoryStore.getState().setTransition({ type: 'none' });
+  }
+
+  const root = document.createElement('div');
+  root.id = 'root';
+  document.body.replaceChildren(document.importNode(storyData, true), root);
+
+  return new Promise<StoryAPI>((resolve, reject) => {
+    document.addEventListener(':storyready', () => resolve(window.Story), {
+      once: true,
+    });
+    try {
+      boot();
+    } catch (err) {
+      reject(err);
+    }
+  });
+}
+
+export type { StoryAPI };

package/src/index.tsx

@@ -10,13 +10,14 @@ import {
 } from './story-api';
 import { resetIdCounters } from './action-registry';
 import { executeStoryInit } from './story-init';
-import { checkTriggers, reinitTriggerState } from './triggers';
+import { connectTriggersToStore } from './triggers';
 import { loadSession } from './saves/save-manager';
 import {
   parseStoryVariables,
   validatePassages,
   extractDefaults,
 } from './story-variables';
+import { getMacroRegistry } from './registry';
 import { tokenize } from './markup/tokenizer';
 import { buildAST, registerBlockMacro } from './markup/ast';
 import { registerWidget } from './widgets/widget-registry';
@@ -45,7 +46,14 @@ function renderErrors(root: HTMLElement, errors: string[]) {
   root.appendChild(container);
 }
 
-function boot() {
+/**
+ * Boot Spindle in the current document: parse `<tw-storydata>`, install the
+ * `Story` API, run author JavaScript, validate `StoryVariables`, run
+ * `StoryInit`, and render into `#root`. Dispatches `:storyready` when the
+ * first passage is shown. Call once per page (module state is global).
+ * The browser story format calls it from `main.tsx`.
+ */
+export function boot() {
   const storyData = parseStoryData();
 
   // Inject built-in styles with an id so they can be disabled at runtime
@@ -90,7 +98,11 @@ function boot() {
   }
 
   const schema = parseStoryVariables(storyVarsPassage.content);
-  const errors = validatePassages(storyData.passages, schema);
+  // Include input macros registered by author JS, which ran above.
+  const storeVarMacros = getMacroRegistry()
+    .filter((m) => m.storeVar)
+    .map((m) => m.name);
+  const errors = validatePassages(storyData.passages, schema, storeVarMacros);
 
   // Parse StoryTransients (optional — no error if missing)
   let transientDefaults: Record<string, unknown> = {};
@@ -187,29 +199,18 @@ function boot() {
     }
   }
 
-  // Reset action ID counters on passage change
-  let prevPassage = '';
+  // Reset action ID counters on every navigation (the passage remounts even
+  // when its name is unchanged)
+  let prevNavigationId = useStoryStore.getState().navigationId;
   useStoryStore.subscribe((state) => {
-    if (state.currentPassage !== prevPassage) {
-      prevPassage = state.currentPassage;
+    if (state.navigationId !== prevNavigationId) {
+      prevNavigationId = state.navigationId;
       resetIdCounters();
     }
   });
 
   // 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;
-  });
+  connectTriggersToStore();
 
   // Warn if StoryInterface passage exists but doesn't contain {passage}
   const storyInterfacePassage = storyData.passages.get('StoryInterface');
@@ -239,9 +240,3 @@ function boot() {
     document.dispatchEvent(new CustomEvent(':storyready'));
   }
 }
-
-if (document.readyState === 'loading') {
-  document.addEventListener('DOMContentLoaded', boot);
-} else {
-  boot();
-}