@rohal12/spindle 0.16.1 → 0.18.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.16.1",
+  "version": "0.18.1",
   "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/action-registry.ts

@@ -12,7 +12,8 @@ export type ActionType =
   | 'forward'
   | 'restart'
   | 'save'
-  | 'load';
+  | 'load'
+  | 'dialog';
 
 export interface StoryAction {
   id: string;

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/PassageDialog.tsx

@@ -0,0 +1,69 @@
+import { createContext } from 'preact';
+import { useMemo } from 'preact/hooks';
+import { tokenize } from '../markup/tokenizer';
+import { buildAST } from '../markup/ast';
+import { renderNodes } from '../markup/render';
+import { useStoryStore } from '../store';
+
+export const DialogCloseContext = createContext<(() => void) | null>(null);
+
+interface PassageDialogProps {
+  passageName?: string;
+  fallbackMarkup?: string;
+  panelClass?: string;
+  onClose: () => void;
+}
+
+export function PassageDialog({
+  passageName,
+  fallbackMarkup,
+  panelClass,
+  onClose,
+}: PassageDialogProps) {
+  const storyData = useStoryStore((s) => s.storyData);
+
+  const passage = passageName
+    ? storyData?.passages.get(passageName)
+    : undefined;
+  const markup = passage?.content ?? fallbackMarkup;
+
+  const content = useMemo(() => {
+    if (!markup) {
+      return <div class="error">Dialog: no content available</div>;
+    }
+    try {
+      const tokens = tokenize(markup);
+      const ast = buildAST(tokens);
+      return renderNodes(ast);
+    } catch (err) {
+      return <div class="error">Error in dialog: {(err as Error).message}</div>;
+    }
+  }, [markup]);
+
+  const handleBackdrop = (e: MouseEvent) => {
+    if ((e.target as HTMLElement).classList.contains('dialog-overlay')) {
+      onClose();
+    }
+  };
+
+  const cls = panelClass ? `dialog-panel ${panelClass}` : 'dialog-panel';
+
+  return (
+    <DialogCloseContext.Provider value={onClose}>
+      <div
+        class="dialog-overlay"
+        onClick={handleBackdrop}
+      >
+        <div class={cls}>
+          <button
+            class="dialog-close"
+            onClick={onClose}
+          >
+            ✕
+          </button>
+          <div class="dialog-body">{content}</div>
+        </div>
+      </div>
+    </DialogCloseContext.Provider>
+  );
+}

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/macros/Button.tsx

@@ -1,49 +1,36 @@
-import { useContext } from 'preact/hooks';
-import { renderInlineNodes, LocalsUpdateContext } from '../../markup/render';
-import { collectText } from '../../utils/extract-text';
-import { useAction } from '../../hooks/use-action';
-import { useInterpolate } from '../../hooks/use-interpolate';
-import { executeMutation } from '../../execute-mutation';
-import { currentSourceLocation } from '../../utils/source-location';
-import { registerMacro } from '../../registry';
-import type { MacroProps } from '../../registry';
+import { defineMacro } from '../../define-macro';
 
-export function Button({ rawArgs, children = [], className, id }: MacroProps) {
-  const resolve = useInterpolate();
-  className = resolve(className);
-  id = resolve(id);
-  const { update, getValues } = useContext(LocalsUpdateContext);
+defineMacro({
+  name: 'button',
+  interpolate: true,
+  render({ rawArgs, children = [] }, ctx) {
+    const handleClick = () => {
+      try {
+        ctx.mutate(rawArgs);
+      } catch (err) {
+        console.error(
+          `spindle: Error in {button ${rawArgs}}${ctx.sourceLocation()}:`,
+          err,
+        );
+      }
+    };
 
-  const handleClick = () => {
-    try {
-      executeMutation(rawArgs, getValues(), update);
-    } catch (err) {
-      console.error(
-        `spindle: Error in {button ${rawArgs}}${currentSourceLocation()}:`,
-        err,
-      );
-    }
-  };
+    ctx.useAction({
+      type: 'button',
+      key: rawArgs,
+      authorId: ctx.id,
+      label: ctx.collectText(children) || rawArgs,
+      perform: handleClick,
+    });
 
-  useAction({
-    type: 'button',
-    key: rawArgs,
-    authorId: id,
-    label: collectText(children) || rawArgs,
-    perform: handleClick,
-  });
-
-  const cls = className ? `macro-button ${className}` : 'macro-button';
-
-  return (
-    <button
-      id={id}
-      class={cls}
-      onClick={handleClick}
-    >
-      {renderInlineNodes(children)}
-    </button>
-  );
-}
-
-registerMacro('button', Button);
+    return (
+      <button
+        id={ctx.id}
+        class={ctx.cls}
+        onClick={handleClick}
+      >
+        {ctx.renderInlineNodes(children)}
+      </button>
+    );
+  },
+});

package/src/components/macros/Checkbox.tsx

@@ -1,7 +1,5 @@
 import { useStoryStore } from '../../store';
-import { useAction } from '../../hooks/use-action';
-import { registerMacro } from '../../registry';
-import type { MacroProps } from '../../registry';
+import { defineMacro } from '../../define-macro';
 
 function parseArgs(rawArgs: string): { varName: string; label: string } {
   const match = rawArgs.match(/^\s*(["']?\$\w+["']?)\s+["']?(.+?)["']?\s*$/);
@@ -13,38 +11,37 @@ function parseArgs(rawArgs: string): { varName: string; label: string } {
   return { varName, label };
 }
 
-export function Checkbox({ rawArgs, className, id }: MacroProps) {
-  const { varName, label } = parseArgs(rawArgs);
-  const name = varName.startsWith('$') ? varName.slice(1) : varName;
+defineMacro({
+  name: 'checkbox',
+  render({ rawArgs }, ctx) {
+    const { varName, label } = parseArgs(rawArgs);
+    const name = varName.startsWith('$') ? varName.slice(1) : varName;
 
-  const value = useStoryStore((s) => s.variables[name]);
-  const setVariable = useStoryStore((s) => s.setVariable);
+    const value = useStoryStore((s) => s.variables[name]);
+    const setVariable = useStoryStore((s) => s.setVariable);
 
-  useAction({
-    type: 'checkbox',
-    key: `$${name}`,
-    authorId: id,
-    label: label || name,
-    variable: name,
-    value: !!value,
-    perform: (v) => setVariable(name, v !== undefined ? !!v : !value),
-  });
+    ctx.useAction({
+      type: 'checkbox',
+      key: `$${name}`,
+      authorId: ctx.id,
+      label: label || name,
+      variable: name,
+      value: !!value,
+      perform: (v) => setVariable(name, v !== undefined ? !!v : !value),
+    });
 
-  const cls = className ? `macro-checkbox ${className}` : 'macro-checkbox';
-
-  return (
-    <label
-      id={id}
-      class={cls}
-    >
-      <input
-        type="checkbox"
-        checked={!!value}
-        onChange={() => setVariable(name, !value)}
-      />
-      {label ? ` ${label}` : null}
-    </label>
-  );
-}
-
-registerMacro('checkbox', Checkbox);
+    return (
+      <label
+        id={ctx.id}
+        class={ctx.cls}
+      >
+        <input
+          type="checkbox"
+          checked={!!value}
+          onChange={() => setVariable(name, !value)}
+        />
+        {label ? ` ${label}` : null}
+      </label>
+    );
+  },
+});

package/src/components/macros/Computed.tsx

@@ -1,15 +1,12 @@
-import { useLayoutEffect, useRef } from 'preact/hooks';
 import { useStoryStore } from '../../store';
 import { evaluate } from '../../expression';
-import { useMergedLocals } from '../../hooks/use-merged-locals';
 import { currentSourceLocation } from '../../utils/source-location';
-import { registerMacro } from '../../registry';
-import type { MacroProps } from '../../registry';
+import { defineMacro } from '../../define-macro';
+import { MacroError } from './MacroError';
 
 function parseComputedArgs(rawArgs: string): { target: string; expr: string } {
   const trimmed = rawArgs.trim();
 
-  // Find the first '=' that isn't part of '==' or '!='
   let depth = 0;
   for (let i = 0; i < trimmed.length; i++) {
     const ch = trimmed[i];
@@ -85,56 +82,54 @@ function computeAndApply(
   }
 }
 
-export function Computed({ rawArgs }: MacroProps) {
-  const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
+defineMacro({
+  name: 'computed',
+  merged: true,
+  render({ rawArgs }, ctx) {
+    const [mergedVars, mergedTemps, mergedLocals] = ctx.merged!;
 
-  let target: string;
-  let expr: string;
-  try {
-    ({ target, expr } = parseComputedArgs(rawArgs));
-  } catch (err) {
-    return (
-      <span
-        class="error"
-        title={String(err)}
-      >
-        {`{computed error${currentSourceLocation()}: ${err instanceof Error ? err.message : String(err)}}`}
-      </span>
-    );
-  }
-  const isTemp = target.startsWith('_');
-  const name = target.slice(1);
-
-  // Synchronous first evaluation — sees preceding synchronous {set} mutations
-  const ran = useRef(false);
-  if (!ran.current) {
-    ran.current = true;
-    const state = useStoryStore.getState();
-    computeAndApply(
-      expr,
-      name,
-      isTemp,
-      state.variables,
-      state.temporary,
-      mergedLocals,
-      rawArgs,
-    );
-  }
+    let target: string;
+    let expr: string;
+    try {
+      ({ target, expr } = parseComputedArgs(rawArgs));
+    } catch (err) {
+      return (
+        <MacroError
+          macro="computed"
+          error={err}
+        />
+      );
+    }
+    const isTemp = target.startsWith('_');
+    const name = target.slice(1);
 
-  // Reactive re-evaluation when dependencies change (via useMergedLocals subscription)
-  useLayoutEffect(() => {
-    computeAndApply(
-      expr,
-      name,
-      isTemp,
-      mergedVars,
-      mergedTemps,
-      mergedLocals,
-      rawArgs,
-    );
-  }, [mergedVars, mergedTemps, mergedLocals]);
+    const ran = ctx.hooks.useRef(false);
+    if (!ran.current) {
+      ran.current = true;
+      const state = useStoryStore.getState();
+      computeAndApply(
+        expr,
+        name,
+        isTemp,
+        state.variables,
+        state.temporary,
+        mergedLocals,
+        rawArgs,
+      );
+    }
 
-  return null;
-}
+    ctx.hooks.useLayoutEffect(() => {
+      computeAndApply(
+        expr,
+        name,
+        isTemp,
+        mergedVars,
+        mergedTemps,
+        mergedLocals,
+        rawArgs,
+      );
+    }, [mergedVars, mergedTemps, mergedLocals]);
 
-registerMacro('computed', Computed);
+    return null;
+  },
+});

package/src/components/macros/Cycle.tsx

@@ -1,53 +1,43 @@
-import { useStoryStore } from '../../store';
-import { extractOptions } from './option-utils';
-import { useAction } from '../../hooks/use-action';
-import { registerMacro } from '../../registry';
-import type { MacroProps } from '../../registry';
-
-export function Cycle({ rawArgs, children = [], className, id }: MacroProps) {
-  const varName = rawArgs.trim().replace(/["']/g, '');
-  const name = varName.startsWith('$') ? varName.slice(1) : varName;
-
-  const value = useStoryStore((s) => s.variables[name]);
-  const setVariable = useStoryStore((s) => s.setVariable);
-
-  const options = extractOptions(children);
-
-  const handleClick = () => {
-    if (options.length === 0) return;
-    const currentIndex = options.indexOf(String(value));
-    const nextIndex = (currentIndex + 1) % options.length;
-    setVariable(name, options[nextIndex]);
-  };
-
-  useAction({
-    type: 'cycle',
-    key: `$${name}`,
-    authorId: id,
-    label: value == null ? options[0] || '' : String(value),
-    variable: name,
-    options,
-    value,
-    perform: (v) => {
-      if (v !== undefined) {
-        setVariable(name, v);
-      } else {
-        handleClick();
-      }
-    },
-  });
-
-  const cls = className ? `macro-cycle ${className}` : 'macro-cycle';
-
-  return (
-    <button
-      id={id}
-      class={cls}
-      onClick={handleClick}
-    >
-      {value == null ? options[0] || '' : String(value)}
-    </button>
-  );
-}
-
-registerMacro('cycle', Cycle);
+import { defineMacro } from '../../define-macro';
+
+defineMacro({
+  name: 'cycle',
+  storeVar: true,
+  render({ children = [] }, ctx) {
+    const options = ctx.extractOptions(children);
+
+    const handleClick = () => {
+      if (options.length === 0) return;
+      const currentIndex = options.indexOf(String(ctx.value));
+      const nextIndex = (currentIndex + 1) % options.length;
+      ctx.setValue!(options[nextIndex]);
+    };
+
+    ctx.useAction({
+      type: 'cycle',
+      key: `$${ctx.varName}`,
+      authorId: ctx.id,
+      label: ctx.value == null ? options[0] || '' : String(ctx.value),
+      variable: ctx.varName,
+      options,
+      value: ctx.value,
+      perform: (v) => {
+        if (v !== undefined) {
+          ctx.setValue!(v);
+        } else {
+          handleClick();
+        }
+      },
+    });
+
+    return (
+      <button
+        id={ctx.id}
+        class={ctx.cls}
+        onClick={handleClick}
+      >
+        {ctx.value == null ? options[0] || '' : String(ctx.value)}
+      </button>
+    );
+  },
+});

package/src/components/macros/Dialog.tsx

@@ -0,0 +1,40 @@
+import { defineMacro } from '../../define-macro';
+import { PassageDialog } from '../PassageDialog';
+
+defineMacro({
+  name: 'dialog',
+  merged: 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;
+
+    return (
+      <>
+        <button
+          id={ctx.id}
+          class={ctx.cls}
+          onClick={() => setOpen(true)}
+        >
+          {label}
+        </button>
+        {open && (
+          <PassageDialog
+            passageName={passageName}
+            onClose={() => setOpen(false)}
+          />
+        )}
+      </>
+    );
+  },
+});