@rohal12/spindle 0.52.4 → 0.52.6

package/src/components/macros/Numberbox.tsx

@@ -1,33 +1,6 @@
-import { defineMacro } from '../../define-macro';
+import { defineInputMacro } from './input-macro';
 
-defineMacro({
-  name: 'numberbox',
-  storeVar: true,
-  render({ rawArgs }, ctx) {
-    const { placeholder } = ctx.parseVarArgs(rawArgs);
-
-    ctx.useAction({
-      type: 'numberbox',
-      key: `$${ctx.varName}`,
-      authorId: ctx.id,
-      label: placeholder || ctx.varName!,
-      variable: ctx.varName,
-      value: ctx.value,
-      perform: (v) => ctx.setValue!(v !== undefined ? Number(v) : 0),
-    });
-
-    return (
-      <input
-        type="number"
-        id={ctx.id}
-        class={ctx.cls}
-        value={ctx.value == null ? '' : String(ctx.value)}
-        placeholder={placeholder}
-        onInput={(e) => {
-          const val = (e.target as HTMLInputElement).value;
-          ctx.setValue!(val === '' ? 0 : Number(val));
-        }}
-      />
-    );
-  },
-});
+// An empty input is 0
+defineInputMacro('numberbox', 'number', (v) =>
+  v !== undefined ? Number(v) : 0,
+);

package/src/components/macros/PassageDisplay.tsx

@@ -54,6 +54,20 @@ function setCSSProperties(el: HTMLElement, config: ResolvedTransition): void {
   el.style.setProperty('--passage-pause', `${config.pause / 1000}s`);
 }
 
+/**
+ * Set up `containerEl` for an outgoing transition and snapshot the passage
+ * it shows, or return null if there is no container or passage.
+ */
+function snapshotPassage(
+  containerEl: HTMLElement | null,
+  config: ResolvedTransition,
+): HTMLElement | null {
+  if (!containerEl) return null;
+  setCSSProperties(containerEl, config);
+  const passageEl = containerEl.querySelector('.passage');
+  return passageEl ? createSnapshot(passageEl, config.type) : null;
+}
+
 /**
  * Remove all snapshot elements and crossfading class from a container.
  */
@@ -183,23 +197,19 @@ defineMacro({
         return;
       }
 
+      // The outgoing transitions start from a snapshot of the current passage
+      const snapshot =
+        config.type === 'fade-through' || config.type === 'crossfade'
+          ? snapshotPassage(containerEl, config)
+          : null;
+      if (!containerEl || !snapshot) {
+        // Fallback: unknown type or nothing to snapshot, just mount
+        setDisplayedPassage(currentPassage);
+        return;
+      }
+
       if (config.type === 'fade-through') {
         // idle → outgoing (fade out snapshot) → paused → incoming (mount new, fade in) → idle
-        if (!containerEl) {
-          setDisplayedPassage(currentPassage);
-          return;
-        }
-
-        setCSSProperties(containerEl, config);
-
-        // Take snapshot of current passage
-        const passageEl = containerEl.querySelector('.passage');
-        if (!passageEl) {
-          setDisplayedPassage(currentPassage);
-          return;
-        }
-
-        const snapshot = createSnapshot(passageEl, config.type);
         containerEl.appendChild(snapshot);
 
         // Hide the current passage during outgoing phase by setting empty key
@@ -221,42 +231,22 @@ defineMacro({
         return;
       }
 
-      if (config.type === 'crossfade') {
-        // idle → crossfading (mount new + fade in, simultaneously fade out snapshot) → idle
-        if (!containerEl) {
-          setDisplayedPassage(currentPassage);
-          return;
-        }
+      // crossfade: idle → crossfading (mount new + fade in, simultaneously
+      // fade out snapshot) → idle
 
-        setCSSProperties(containerEl, config);
+      // Use CSS grid stacking for crossfade
+      containerEl.classList.add('passage-container--crossfading');
+      containerEl.appendChild(snapshot);
 
-        // Take snapshot of current passage
-        const passageEl = containerEl.querySelector('.passage');
-        if (!passageEl) {
-          setDisplayedPassage(currentPassage);
-          return;
-        }
-
-        const snapshot = createSnapshot(passageEl, config.type);
-
-        // Use CSS grid stacking for crossfade
-        containerEl.classList.add('passage-container--crossfading');
-        containerEl.appendChild(snapshot);
-
-        // Mount new passage immediately alongside snapshot
-        setDisplayedPassage(currentPassage);
-
-        // After duration, clean up snapshot and remove crossfading class
-        const t1 = setTimeout(() => {
-          cleanupSnapshots(containerEl);
-        }, config.duration);
+      // Mount new passage immediately alongside snapshot
+      setDisplayedPassage(currentPassage);
 
-        timeoutsRef.current = [t1];
-        return;
-      }
+      // After duration, clean up snapshot and remove crossfading class
+      const t1 = setTimeout(() => {
+        cleanupSnapshots(containerEl);
+      }, config.duration);
 
-      // Fallback: unknown type, just mount
-      setDisplayedPassage(currentPassage);
+      timeoutsRef.current = [t1];
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [navigationId]);
 

package/src/components/macros/Print.tsx

@@ -3,6 +3,7 @@ import { MacroError } from './MacroError';
 
 defineMacro({
   name: 'print',
+  parameters: [{ name: 'expression', type: 'expression', required: true }],
   interpolate: true,
   merged: true,
   render({ rawArgs }, ctx) {

package/src/components/macros/Radiobutton.tsx

@@ -1,46 +1,16 @@
 import { defineMacro } from '../../define-macro';
-import {
-  isWhitespace,
-  readQuoted,
-  readWholeQuoted,
-  stripLooseQuotes,
-} from './arg-utils';
-
-export function parseRadioArgs(rawArgs: string): {
-  value: string;
-  label: string;
-} {
-  // $var "value" label: a quoted value accepts \" \' and \\ escapes and
-  // may contain the other quote kind.
-  const head = rawArgs.match(/^\s*["']?\$?[\w.]+["']?\s+/);
-  if (head) {
-    const rest = rawArgs.slice(head[0].length).trim();
-    const value = readQuoted(rest, 0);
-    if (
-      value &&
-      (value.end === rest.length || isWhitespace(rest[value.end]!))
-    ) {
-      const labelRaw = rest.slice(value.end).trim();
-      const label = readWholeQuoted(labelRaw) ?? stripLooseQuotes(labelRaw);
-      return { value: value.value, label };
-    }
-  }
-
-  const match = rawArgs.match(
-    /^\s*["']?\$?[\w.]+["']?\s+["'](.+?)["']\s+["']?(.+?)["']?\s*$/s,
-  );
-  if (!match) {
-    const parts = rawArgs.trim().split(/\s+/).slice(1);
-    return { value: parts[0] ?? '', label: parts.slice(1).join(' ') };
-  }
-  return { value: match[1]!, label: match[2]! };
-}
 
 defineMacro({
   name: 'radiobutton',
   storeVar: true,
-  render({ rawArgs }, ctx) {
-    const { value: radioValue, label } = parseRadioArgs(rawArgs);
+  parameters: [
+    { name: 'variable', type: 'variable', required: true },
+    { name: 'value', type: 'text', required: true },
+    { name: 'label', type: 'text' },
+  ],
+  render(_props, ctx) {
+    const radioValue = ctx.args.value ?? '';
+    const label = ctx.args.label ?? '';
 
     ctx.useAction({
       type: 'radiobutton',

package/src/components/macros/Repeat.tsx

@@ -1,5 +1,4 @@
 import { createContext } from 'preact';
-import { parseDelay } from '../../utils/parse-delay';
 import { defineMacro } from '../../define-macro';
 
 export const RepeatContext = createContext<{ stop: () => void }>({
@@ -10,10 +9,11 @@ defineMacro({
   name: 'repeat',
   block: true,
   interpolate: true,
-  render({ rawArgs, children = [] }, ctx) {
+  parameters: [{ name: 'delay', type: 'delay', required: true }],
+  render({ children = [] }, ctx) {
     const { useState, useEffect, useCallback } = ctx.hooks;
 
-    const delay = parseDelay(rawArgs);
+    const delay = ctx.args.delay ?? 0;
     const [count, setCount] = useState(0);
     const [stopped, setStopped] = useState(false);
 

package/src/components/macros/Set.tsx

@@ -1,36 +1,10 @@
 import { defineMacro } from '../../define-macro';
-import { MacroError } from './MacroError';
+import { useRunOnce } from './MacroError';
 
 defineMacro({
   name: 'set',
+  parameters: [{ name: 'code', type: 'expression', required: true }],
   render({ rawArgs }, ctx) {
-    const ran = ctx.hooks.useRef(false);
-    // Boxed: anything can be thrown, including null and other falsy values
-    const failure = ctx.hooks.useRef<{ error: unknown } | null>(null);
-
-    if (!ran.current) {
-      ran.current = true;
-
-      try {
-        ctx.mutate(rawArgs);
-      } catch (err) {
-        failure.current = { error: err };
-        console.error(
-          `spindle: Error in {set ${rawArgs}}${ctx.sourceLocation()}:`,
-          err,
-        );
-      }
-    }
-
-    if (failure.current) {
-      return (
-        <MacroError
-          macro="set"
-          error={failure.current.error}
-        />
-      );
-    }
-
-    return null;
+    return useRunOnce('set', rawArgs, () => ctx.mutate(rawArgs));
   },
 });

package/src/components/macros/Switch.tsx

@@ -1,9 +1,32 @@
 import { defineMacro } from '../../define-macro';
 import { MacroError } from './MacroError';
+import type { Branch } from '../../markup/ast';
+
+/**
+ * The first {case} branch whose value equals `value`, else the {default}
+ * branch, else null. Throws what a case expression throws.
+ */
+function selectBranch(
+  value: unknown,
+  branches: Branch[],
+  evaluate: (expr: string) => unknown,
+): Branch | null {
+  let defaultBranch: Branch | null = null;
+  for (let i = 1; i < branches.length; i++) {
+    const branch = branches[i]!;
+    if (branch.rawArgs === '') {
+      defaultBranch = branch;
+    } else if (value === evaluate(branch.rawArgs)) {
+      return branch;
+    }
+  }
+  return defaultBranch;
+}
 
 defineMacro({
   name: 'switch',
   subMacros: ['case', 'default'],
+  parameters: [{ name: 'expression', type: 'expression', required: true }],
   merged: true,
   render({ rawArgs, branches = [] }, ctx) {
     let switchValue: unknown;
@@ -18,46 +41,22 @@ defineMacro({
       );
     }
 
-    let defaultBranch: (typeof branches)[number] | null = null;
-    for (let i = 1; i < branches.length; i++) {
-      const branch = branches[i]!;
-      if (branch.rawArgs === '') {
-        defaultBranch = branch;
-        continue;
-      }
-
-      try {
-        const caseValue = ctx.evaluate!(branch.rawArgs);
-        if (switchValue === caseValue) {
-          return <>{ctx.renderNodes(branch.children)}</>;
-        }
-      } catch (err) {
-        return (
-          <MacroError
-            macro="case"
-            error={err}
-          />
-        );
-      }
-    }
-
-    if (defaultBranch) {
-      return <>{ctx.renderNodes(defaultBranch.children)}</>;
+    let branch: Branch | null;
+    try {
+      branch = selectBranch(switchValue, branches, ctx.evaluate!);
+    } catch (err) {
+      return (
+        <MacroError
+          macro="case"
+          error={err}
+        />
+      );
     }
 
-    return null;
+    return branch && <>{ctx.renderNodes(branch.children)}</>;
   },
   text({ rawArgs, branches = [] }, ctx) {
-    const switchValue = ctx.evaluate(rawArgs);
-    let defaultBranch: (typeof branches)[number] | null = null;
-    for (let i = 1; i < branches.length; i++) {
-      const branch = branches[i]!;
-      if (branch.rawArgs === '') {
-        defaultBranch = branch;
-      } else if (switchValue === ctx.evaluate(branch.rawArgs)) {
-        return ctx.renderText(branch.children);
-      }
-    }
-    return defaultBranch ? ctx.renderText(defaultBranch.children) : '';
+    const branch = selectBranch(ctx.evaluate(rawArgs), branches, ctx.evaluate);
+    return branch ? ctx.renderText(branch.children) : '';
   },
 });

package/src/components/macros/Textarea.tsx

@@ -1,29 +1,3 @@
-import { defineMacro } from '../../define-macro';
+import { defineInputMacro } from './input-macro';
 
-defineMacro({
-  name: 'textarea',
-  storeVar: true,
-  render({ rawArgs }, ctx) {
-    const { placeholder } = ctx.parseVarArgs(rawArgs);
-
-    ctx.useAction({
-      type: 'textarea',
-      key: `$${ctx.varName}`,
-      authorId: ctx.id,
-      label: placeholder || ctx.varName!,
-      variable: ctx.varName,
-      value: ctx.value,
-      perform: (v) => ctx.setValue!(v !== undefined ? String(v) : ''),
-    });
-
-    return (
-      <textarea
-        id={ctx.id}
-        class={ctx.cls}
-        value={ctx.value == null ? '' : String(ctx.value)}
-        placeholder={placeholder}
-        onInput={(e) => ctx.setValue!((e.target as HTMLTextAreaElement).value)}
-      />
-    );
-  },
-});
+defineInputMacro('textarea');

package/src/components/macros/Textbox.tsx

@@ -1,30 +1,3 @@
-import { defineMacro } from '../../define-macro';
+import { defineInputMacro } from './input-macro';
 
-defineMacro({
-  name: 'textbox',
-  storeVar: true,
-  render({ rawArgs }, ctx) {
-    const { placeholder } = ctx.parseVarArgs(rawArgs);
-
-    ctx.useAction({
-      type: 'textbox',
-      key: `$${ctx.varName}`,
-      authorId: ctx.id,
-      label: placeholder || ctx.varName!,
-      variable: ctx.varName,
-      value: ctx.value,
-      perform: (v) => ctx.setValue!(v !== undefined ? String(v) : ''),
-    });
-
-    return (
-      <input
-        type="text"
-        id={ctx.id}
-        class={ctx.cls}
-        value={ctx.value == null ? '' : String(ctx.value)}
-        placeholder={placeholder}
-        onInput={(e) => ctx.setValue!((e.target as HTMLInputElement).value)}
-      />
-    );
-  },
-});
+defineInputMacro('textbox', 'text');

package/src/components/macros/Type.tsx

@@ -1,13 +1,13 @@
-import { parseDelay } from '../../utils/parse-delay';
 import { defineMacro } from '../../define-macro';
 
 defineMacro({
   name: 'type',
   block: true,
   interpolate: true,
-  render({ rawArgs, children = [] }, ctx) {
+  parameters: [{ name: 'delay', type: 'delay', required: true }],
+  render({ children = [] }, ctx) {
     const { useState, useEffect, useRef } = ctx.hooks;
-    const speed = parseDelay(rawArgs);
+    const speed = ctx.args.delay ?? 0;
     const containerRef = useRef<HTMLSpanElement>(null);
     const [totalChars, setTotalChars] = useState(0);
     const [visibleChars, setVisibleChars] = useState(0);

package/src/components/macros/Unset.tsx

@@ -1,52 +1,29 @@
 import { useStoryStore } from '../../store';
 import { defineMacro } from '../../define-macro';
-import { MacroError } from './MacroError';
+import { useRunOnce } from './MacroError';
 
 defineMacro({
   name: 'unset',
+  parameters: [{ name: 'variable', type: 'variable', required: true }],
   render({ rawArgs }, ctx) {
-    const ran = ctx.hooks.useRef(false);
-    // Boxed: anything can be thrown, including null and other falsy values
-    const failure = ctx.hooks.useRef<{ error: unknown } | null>(null);
-
-    if (!ran.current) {
-      ran.current = true;
+    return useRunOnce('unset', rawArgs, () => {
       const state = useStoryStore.getState();
-      const name = rawArgs.trim();
+      const name = ctx.args.variable ?? '';
 
-      try {
-        if (name.startsWith('$')) {
-          state.deleteVariable(name.slice(1));
-        } else if (name.startsWith('_')) {
-          state.deleteTemporary(name.slice(1));
-        } else if (name.startsWith('%')) {
-          state.deleteTransient(name.slice(1));
-        } else if (name.startsWith('@')) {
-          // Throws outside a locals scope ({for}, widget, {link}, {button})
-          ctx.update(name.slice(1), undefined);
-        } else {
-          throw new Error(
-            `{unset} expects a variable ($name, _name, %name, or @name), got "${name}"`,
-          );
-        }
-      } catch (err) {
-        failure.current = { error: err };
-        console.error(
-          `spindle: Error in {unset ${rawArgs}}${ctx.sourceLocation()}:`,
-          err,
+      if (name.startsWith('$')) {
+        state.deleteVariable(name.slice(1));
+      } else if (name.startsWith('_')) {
+        state.deleteTemporary(name.slice(1));
+      } else if (name.startsWith('%')) {
+        state.deleteTransient(name.slice(1));
+      } else if (name.startsWith('@')) {
+        // Throws outside a locals scope ({for}, widget, {link}, {button})
+        ctx.update(name.slice(1), undefined);
+      } else {
+        throw new Error(
+          `{unset} expects a variable ($name, _name, %name, or @name), got "${name}"`,
         );
       }
-    }
-
-    if (failure.current) {
-      return (
-        <MacroError
-          macro="unset"
-          error={failure.current.error}
-        />
-      );
-    }
-
-    return null;
+    });
   },
 });

package/src/components/macros/Watch.tsx

@@ -1,99 +1,30 @@
 import { defineMacro } from '../../define-macro';
 import { addMacroTrigger, removeTrigger } from '../../triggers';
-import type { WatchOptions } from '../../triggers';
-import { isWhitespace, readQuoted, readWholeQuoted } from './arg-utils';
-
-const WORD_RE = /\w+/y;
-const DIGITS_RE = /\d+/y;
-
-/** Match the sticky regex `re` at `pos`, returning the matched text. */
-function matchAt(re: RegExp, src: string, pos: number): string | null {
-  re.lastIndex = pos;
-  return re.exec(src)?.[0] ?? null;
-}
-
-/**
- * Parse `{watch "condition" keyword value …}`: a quoted condition followed
- * by keyword options (`goto "X"`, `dialog "X"`, `run "X"`, `name "X"`,
- * `priority N`, `once`). Quoted strings accept `\"`, `\'` and `\\` escapes.
- * Returns `null` when the arguments do not start with a quoted condition.
- */
-export function parseWatchArgs(
-  rawArgs: string,
-): { condition: string; options: WatchOptions } | null {
-  const raw = rawArgs.trim();
-  const cond = readQuoted(raw, 0);
-  if (!cond) return null;
-
-  const options: WatchOptions = {};
-  let i = cond.end;
-  while (i < raw.length) {
-    const key = matchAt(WORD_RE, raw, i);
-    if (!key) {
-      // Skip whitespace and stray characters, or a stray quoted string.
-      i = readQuoted(raw, i)?.end ?? i + 1;
-      continue;
-    }
-    i += key.length;
-
-    // A value is a quoted string or a digit run, after whitespace.
-    let val: string | undefined;
-    let j = i;
-    while (j < raw.length && isWhitespace(raw[j]!)) j++;
-    if (j > i) {
-      const quoted = readQuoted(raw, j);
-      const digits = quoted ? null : matchAt(DIGITS_RE, raw, j);
-      if (quoted) {
-        val = quoted.value;
-        i = quoted.end;
-      } else if (digits) {
-        val = digits;
-        i = j + digits.length;
-      }
-    }
-
-    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;
-    }
-  }
-
-  return { condition: cond.value, options };
-}
-
-/**
- * Parse the watcher name of `{unwatch "name"}`: a quoted string, with the
- * same escapes as `{watch}`, or a bare name.
- */
-export function parseUnwatchName(rawArgs: string): string {
-  const raw = rawArgs.trim();
-  return readWholeQuoted(raw) ?? raw.replace(/^['"]|['"]$/g, '');
-}
 
 defineMacro({
   name: 'watch',
-  render(props, ctx) {
+  // {watch "condition" goto "X" dialog "X" run "X" name "X" priority N once}
+  parameters: [
+    { name: 'condition', type: 'string', required: true },
+    {
+      name: 'options',
+      type: 'options',
+      parameters: [
+        { name: 'goto', type: 'string' },
+        { name: 'dialog', type: 'string' },
+        { name: 'run', type: 'string' },
+        { name: 'name', type: 'string' },
+        { name: 'priority', type: 'number' },
+        { name: 'once', type: 'flag' },
+      ],
+    },
+  ],
+  render(_props, ctx) {
     const { hooks } = ctx;
 
-    const parsed = parseWatchArgs(props.rawArgs);
-    if (!parsed) return null;
-    const { condition, options } = parsed;
+    // Without a quoted condition there is nothing to watch.
+    const { condition, options } = ctx.args;
+    if (condition === undefined) return null;
 
     // Register during render (like {set}) — triggers survive navigation
     // and are cleaned up via resetTriggers() on restart or {unwatch}.
@@ -110,8 +41,9 @@ defineMacro({
 
 defineMacro({
   name: 'unwatch',
-  render(props, ctx) {
-    const name = parseUnwatchName(props.rawArgs);
+  parameters: [{ name: 'name', type: 'text', required: true }],
+  render(_props, ctx) {
+    const name = ctx.args.name ?? '';
 
     const ran = ctx.hooks.useRef(false);
     if (!ran.current) {