@rohal12/spindle 0.52.5 → 0.52.6

package/src/components/macros/For.tsx

@@ -1,47 +1,29 @@
-import {
-  useContext,
-  useState,
-  useCallback,
-  useRef,
-  useMemo,
-} from 'preact/hooks';
-import {
-  LocalsValuesContext,
-  LocalsUpdateContext,
-  NobrContext,
-  InlineContext,
-  RawTextContext,
-  renderNodes,
-} from '../../markup/render';
+import { useContext, useMemo } from 'preact/hooks';
+import { LocalsValuesContext } from '../../markup/render';
 import { defineMacro } from '../../define-macro';
 import { MacroError } from './MacroError';
 import { stableKey } from '../../utils/stable-key';
 import type { ASTNode } from '../../markup/ast';
-import {
-  checkVariableName,
-  createNamespace,
-  withEntry,
-} from '../../utils/namespace';
+import { checkVariableName } from '../../utils/namespace';
+import { LocalsScope } from './locals-scope';
 
 /**
- * Parse for-loop args: "@item, @i of $list" or "@item of $list"
+ * Check the arguments of "@item, @i of $list" or "@item of $list".
  */
-function parseForArgs(rawArgs: string): {
+function loopArgs(
+  rawArgs: string,
+  args: { variables?: string[]; of: boolean; list?: string },
+): {
   itemVar: string;
   indexVar: string | null;
   listExpr: string;
 } {
-  const ofIdx = rawArgs.indexOf(' of ');
-  if (ofIdx === -1) {
+  if (!args.of) {
     throw new Error(`{for} requires "of" keyword: {for ${rawArgs}}`);
   }
 
-  const varsPart = rawArgs.slice(0, ofIdx).trim();
-  const listExpr = rawArgs.slice(ofIdx + 4).trim();
-
-  const vars = varsPart.split(',').map((v) => v.trim());
-  const itemVar = vars[0]!;
-  const indexVar = vars.length > 1 ? vars[1]! : null;
+  const [itemVar = '', indexVar = null] = args.variables ?? [];
+  const listExpr = args.list ?? '';
 
   if (!itemVar.startsWith('@')) {
     throw new Error(`{for} loop variable must use @ prefix: got "${itemVar}"`);
@@ -77,10 +59,6 @@ function ForIteration({
   indexValue: number;
   children: ASTNode[];
 }) {
-  const [localMutations, setLocalMutations] = useState<Record<string, unknown>>(
-    () => ({}),
-  );
-
   const ownKeys = useMemo(
     () => ({
       [itemVar]: itemValue,
@@ -89,35 +67,12 @@ function ForIteration({
     [itemVar, itemValue, indexVar, indexValue],
   );
 
-  const localState = useMemo(
-    () => createNamespace(parentValues, ownKeys, localMutations),
-    [parentValues, ownKeys, localMutations],
-  );
-
-  const valuesRef = useRef(localState);
-  valuesRef.current = localState;
-
-  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.
-    checkVariableName(key, `@${key}`);
-    valuesRef.current = withEntry(valuesRef.current, key, value);
-    setLocalMutations((prev) => ({ ...prev, [key]: value }));
-  }, []);
-  const updater = useMemo(() => ({ update, getValues }), [update, getValues]);
-
-  const nobr = useContext(NobrContext);
-  const inline = useContext(InlineContext);
-  const raw = useContext(RawTextContext);
-
   return (
-    <LocalsUpdateContext.Provider value={updater}>
-      <LocalsValuesContext.Provider value={localState}>
-        {renderNodes(children, { nobr, inline, raw, locals: localState })}
-      </LocalsValuesContext.Provider>
-    </LocalsUpdateContext.Provider>
+    <LocalsScope
+      body={children}
+      parentValues={parentValues}
+      ownKeys={ownKeys}
+    />
   );
 }
 
@@ -126,26 +81,19 @@ defineMacro({
   block: true,
   interpolate: true,
   merged: true,
+  parameters: [
+    { name: 'variables', type: 'names', required: true },
+    { name: 'of', type: 'separator' },
+    { name: 'list', type: 'expression', required: true },
+  ],
   render({ rawArgs, children = [] }, ctx) {
     const parentValues = useContext(LocalsValuesContext);
 
-    let parsed: ReturnType<typeof parseForArgs>;
-    try {
-      parsed = parseForArgs(rawArgs);
-    } catch (err) {
-      return (
-        <MacroError
-          macro="for"
-          error={err}
-        />
-      );
-    }
-
-    const { itemVar, indexVar, listExpr } = parsed;
-
+    let loop: ReturnType<typeof loopArgs>;
     let list: unknown[];
     try {
-      const result = ctx.evaluate!(listExpr);
+      loop = loopArgs(rawArgs, ctx.args);
+      const result = ctx.evaluate!(loop.listExpr);
       if (!Array.isArray(result)) {
         return (
           <span class="error">
@@ -163,6 +111,7 @@ defineMacro({
       );
     }
 
+    const { itemVar, indexVar } = loop;
     const content = list.map((item, i) => (
       <ForIteration
         key={`${i}-${stableKey(item)}`}
@@ -178,7 +127,7 @@ defineMacro({
     return ctx.wrap(content);
   },
   text({ rawArgs, children = [] }, ctx) {
-    const { itemVar, indexVar, listExpr } = parseForArgs(rawArgs);
+    const { itemVar, indexVar, listExpr } = loopArgs(rawArgs, ctx.args);
     const list = ctx.evaluate(listExpr);
     if (!Array.isArray(list)) {
       throw new Error('expression did not evaluate to an array');

package/src/components/macros/Goto.tsx

@@ -1,19 +1,16 @@
 import { useStoryStore } from '../../store';
 import { defineMacro } from '../../define-macro';
+import { evaluatePassageName } from './macro-args';
 
 defineMacro({
   name: 'goto',
   merged: true,
-  render({ rawArgs }, ctx) {
+  parameters: [{ name: 'passage', type: 'expression', required: true }],
+  render(_props, ctx) {
     ctx.hooks.useLayoutEffect(() => {
-      let passageName: string;
-      try {
-        const result = ctx.evaluate!(rawArgs);
-        passageName = String(result);
-      } catch {
-        passageName = rawArgs.replace(/^["']|["']$/g, '');
-      }
-      useStoryStore.getState().navigate(passageName);
+      useStoryStore
+        .getState()
+        .navigate(evaluatePassageName(ctx.args.passage, ctx.evaluate!));
     }, []);
 
     return null;

package/src/components/macros/Include.tsx

@@ -3,70 +3,23 @@ import { tokenize } from '../../markup/tokenizer';
 import { buildAST } from '../../markup/ast';
 import { NobrContext } from '../../markup/render';
 import { defineMacro } from '../../define-macro';
-import { endsWithOperator, isWhitespace, topLevelIndices } from './arg-utils';
-
-const FLAG = 'inline';
-
-/**
- * Split a standalone `inline` flag off the start or end of the include
- * arguments. The flag only counts outside quotes, brackets, parentheses and
- * braces, separated by whitespace from the target expression, so passage
- * names and expressions containing the word stay intact (#201).
- */
-export function parseIncludeArgs(rawArgs: string): {
-  nameExpr: string;
-  inline: boolean;
-} {
-  const trimmed = rawArgs.trim();
-
-  // First and last whitespace runs at depth 0, as [start, end) offsets.
-  const spaces = topLevelIndices(trimmed, isWhitespace);
-  let first: [number, number] | null = null;
-  let last: [number, number] | null = null;
-  if (spaces.length > 0) {
-    let s = 0;
-    while (s + 1 < spaces.length && spaces[s + 1] === spaces[s]! + 1) s++;
-    first = [spaces[0]!, spaces[s]! + 1];
-    let e = spaces.length - 1;
-    while (e > 0 && spaces[e - 1] === spaces[e]! - 1) e--;
-    last = [spaces[e]!, spaces[spaces.length - 1]! + 1];
-  }
-
-  // Next to a binary operator the word is an operand (`"a" + inline`);
-  // the closing `/` of a regex literal is not one.
-  if (
-    last &&
-    last[1] === trimmed.length - FLAG.length &&
-    trimmed.endsWith(FLAG)
-  ) {
-    const rest = trimmed.slice(0, last[0]);
-    if (!endsWithOperator(rest)) return { nameExpr: rest, inline: true };
-  }
-  if (first && first[0] === FLAG.length && trimmed.startsWith(FLAG)) {
-    const rest = trimmed.slice(first[1]);
-    // `inline %name` reads a transient variable; `inline % 2` is modulo.
-    if (!/^(?:[-+*/&|^=<>?:,.]|%(?![A-Za-z_]))/.test(rest))
-      return { nameExpr: rest, inline: true };
-  }
-  return { nameExpr: trimmed, inline: false };
-}
+import { evaluatePassageName } from './macro-args';
 
 defineMacro({
   name: 'include',
   interpolate: true,
   merged: true,
-  render({ rawArgs }, ctx) {
+  // A standalone `inline` flag only counts outside quotes and brackets, so
+  // passage names and expressions containing the word stay intact (#201).
+  parameters: [
+    { name: 'inline', type: 'flag' },
+    { name: 'passage', type: 'expression', required: true },
+  ],
+  render(_props, ctx) {
     const storyData = useStoryStore((s) => s.storyData);
 
-    const { nameExpr, inline } = parseIncludeArgs(rawArgs);
-
-    let passageName: string;
-    try {
-      const result = ctx.evaluate!(nameExpr);
-      passageName = String(result);
-    } catch {
-      passageName = nameExpr.replace(/^["']|["']$/g, '');
-    }
+    const { inline } = ctx.args;
+    const passageName = evaluatePassageName(ctx.args.passage, ctx.evaluate!);
 
     const passage = storyData?.passages.get(passageName);
     // Parse once per included passage: the renderer keys children by AST

package/src/components/macros/Listbox.tsx

@@ -4,6 +4,7 @@ defineMacro({
   name: 'listbox',
   subMacros: ['option'],
   storeVar: true,
+  parameters: [{ name: 'variable', type: 'variable', required: true }],
   render({ children = [] }, ctx) {
     const options = ctx.extractOptions(children);
 

package/src/components/macros/MacroError.tsx

@@ -1,3 +1,4 @@
+import { useRef } from 'preact/hooks';
 import { currentSourceLocation } from '../../utils/source-location';
 import { errorMessage } from '../../utils/error-message';
 
@@ -17,3 +18,39 @@ export function MacroError({
     </span>
   );
 }
+
+/** Log an error in the macro `{label}` (its name, or name and arguments). */
+export function logMacroError(label: string, error: unknown): void {
+  console.error(
+    `spindle: Error in {${label}}${currentSourceLocation()}:`,
+    error,
+  );
+}
+
+/**
+ * Run `effect` once, during the macro's first render. If it throws, the
+ * error is logged under `{macro rawArgs}` and shown in place of the macro
+ * from then on; otherwise the macro renders nothing.
+ */
+export function useRunOnce(macro: string, rawArgs: string, effect: () => void) {
+  // Unset until the effect has run. Boxed: anything can be thrown,
+  // including null and other falsy values.
+  const failure = useRef<{ error: unknown } | null>();
+  if (failure.current === undefined) {
+    failure.current = null;
+    try {
+      effect();
+    } catch (error) {
+      failure.current = { error };
+      logMacroError(`${macro} ${rawArgs}`, error);
+    }
+  }
+
+  if (!failure.current) return null;
+  return (
+    <MacroError
+      macro={macro}
+      error={failure.current.error}
+    />
+  );
+}

package/src/components/macros/MacroLink.tsx

@@ -1,36 +1,21 @@
 import { useStoryStore } from '../../store';
 import { defineMacro } from '../../define-macro';
-import { unescapeQuoted } from './arg-utils';
 import { useDetachedBody } from './detached-body';
 
-export function parseLinkArgs(rawArgs: string): {
-  display: string;
-  passage: string | null;
-} {
-  // {link "text" "Passage"} or {link "text"}. A backslash escapes a quote
-  // or another backslash inside a quoted argument (#200).
-  const parts: string[] = [];
-  const re = /(["'])((?:\\[^]|(?!\1)[^\\])*)\1/g;
-  let m;
-  while ((m = re.exec(rawArgs)) !== null) {
-    parts.push(unescapeQuoted(m[2]!));
-  }
-  if (parts.length >= 2) {
-    return { display: parts[0]!, passage: parts[1]! };
-  }
-  if (parts.length === 1) {
-    return { display: parts[0]!, passage: null };
-  }
-  // Fallback: treat entire rawArgs as display text
-  return { display: rawArgs.trim(), passage: null };
-}
-
 defineMacro({
   name: 'link',
   block: true,
   interpolate: true,
+  // {link "text" "Passage"} or {link "text"}; unquoted, the whole arguments
+  // are the text.
+  parameters: [
+    { name: 'text', type: 'string', required: true },
+    { name: 'passage', type: 'string' },
+  ],
   render({ rawArgs, children = [] }, ctx) {
-    const { display, passage } = parseLinkArgs(rawArgs);
+    const { text } = ctx.args;
+    const display = text ?? rawArgs.trim();
+    const passage = text === undefined ? null : (ctx.args.passage ?? null);
     const runBody = useDetachedBody();
 
     const perform = () => {

package/src/components/macros/Meter.tsx

@@ -1,46 +1,21 @@
 import { defineMacro } from '../../define-macro';
 import { MacroError } from './MacroError';
-import {
-  endsWithOperator,
-  isWhitespace,
-  readWholeQuoted,
-  splitTopLevel,
-} from './arg-utils';
 
-/**
- * Parse `{meter currentExpr maxExpr ["label"]}`. Arguments are separated by
- * whitespace outside string and template literals and bracket pairs; a
- * trailing standalone `"…"` or `'…'` string is the label mode, with `\"`,
- * `\'` and `\\` escapes. A string after an operator (`$a ?? "5"`) is an
- * operand of the max expression, not the label.
- */
-export function parseMeterArgs(rawArgs: string): {
-  currentExpr: string;
-  maxExpr: string;
-  labelMode: string;
-} {
-  const tokens = splitTopLevel(rawArgs.trim(), isWhitespace).filter(Boolean);
-
-  let labelMode = '';
-  const label =
-    tokens.length >= 2 && !endsWithOperator(tokens.slice(0, -1).join(' '))
-      ? readWholeQuoted(tokens[tokens.length - 1]!)
-      : null;
-  if (label !== null) {
-    labelMode = label;
-    tokens.pop();
-  }
-
-  if (tokens.length < 2) {
+/** Check the arguments of `{meter currentExpr maxExpr ["label"]}`. */
+export function meterArgs(args: {
+  current?: string;
+  max?: string;
+  label?: string;
+}): { currentExpr: string; maxExpr: string; labelMode: string } {
+  if (args.current === undefined || args.max === undefined) {
     throw new Error(
       'meter requires two arguments: {meter currentExpr maxExpr}',
     );
   }
-
   return {
-    currentExpr: tokens[0]!,
-    maxExpr: tokens.slice(1).join(' '),
-    labelMode,
+    currentExpr: args.current,
+    maxExpr: args.max,
+    labelMode: args.label ?? '',
   };
 }
 
@@ -60,9 +35,16 @@ defineMacro({
   name: 'meter',
   interpolate: true,
   merged: true,
-  render({ rawArgs }, ctx) {
+  // {meter currentExpr maxExpr ["label"]}. A string after an operator
+  // (`$a ?? "5"`) is an operand of the max expression, not the label.
+  parameters: [
+    { name: 'current', type: 'expression', required: true },
+    { name: 'max', type: 'expression', required: true },
+    { name: 'label', type: 'string' },
+  ],
+  render(_props, ctx) {
     try {
-      const { currentExpr, maxExpr, labelMode } = parseMeterArgs(rawArgs);
+      const { currentExpr, maxExpr, labelMode } = meterArgs(ctx.args);
       const current = Number(ctx.evaluate!(currentExpr));
       const max = Number(ctx.evaluate!(maxExpr));
       const pct =

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);