@rohal12/spindle 0.49.1 → 0.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.49.1",
+  "version": "0.50.0",
   "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/components/Passage.tsx

@@ -12,6 +12,7 @@ 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';
 
 export function renderPassageContent(passage: PassageData) {
   const tokens = tokenize(passage.content);
@@ -102,6 +103,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/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

@@ -45,7 +45,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
@@ -239,9 +246,3 @@ function boot() {
     document.dispatchEvent(new CustomEvent(':storyready'));
   }
 }
-
-if (document.readyState === 'loading') {
-  document.addEventListener('DOMContentLoaded', boot);
-} else {
-  boot();
-}

package/src/main.tsx

@@ -0,0 +1,8 @@
+// Browser entry point of the story format: boot once the DOM is ready.
+import { boot } from './index';
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', boot);
+} else {
+  boot();
+}

package/src/passage-render-state.ts

@@ -0,0 +1,14 @@
+/**
+ * Name of the passage most recently mounted by <Passage> (null until the
+ * first render, e.g. when the story interface has no {passage}).
+ * Lets Story.waitForActions() tell whether the current passage is on screen.
+ */
+let renderedPassage: string | null = null;
+
+export function markPassageRendered(name: string): void {
+  renderedPassage = name;
+}
+
+export function getRenderedPassage(): string | null {
+  return renderedPassage;
+}

package/src/story-api.ts

@@ -29,6 +29,7 @@ import type { MacroDefinition } from './define-macro';
 import { getMacroRegistry as _getMacroRegistry } from './registry';
 import type { MacroMetadata } from './registry';
 import { getActions, getAction, type StoryAction } from './action-registry';
+import { getRenderedPassage } from './passage-render-state';
 import {
   initPRNG,
   isPRNGEnabled,
@@ -539,14 +540,26 @@ function createStoryAPI(): StoryAPI {
       return unsub;
     },
 
-    waitForActions(): Promise<StoryAction[]> {
-      return new Promise((resolve) => {
-        requestAnimationFrame(() => {
-          requestAnimationFrame(() => {
-            resolve(getActions());
+    async waitForActions(): Promise<StoryAction[]> {
+      await new Promise<void>((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+      });
+      // A navigation can still be rendering: the passage display mounts the
+      // new passage from an effect, after a fade-through's outgoing phase.
+      // Its actions exist only once it is mounted, so wait for that.
+      const { currentPassage, renderDeferred } = useStoryStore.getState();
+      const rendered = getRenderedPassage();
+      if (rendered !== null && rendered !== currentPassage && !renderDeferred) {
+        await new Promise<void>((resolve) => {
+          const off = emitterOn('passagerender', (name) => {
+            if (name === useStoryStore.getState().currentPassage) {
+              off();
+              resolve();
+            }
           });
         });
-      });
+      }
+      return getActions();
     },
 
     watch(

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/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 };