@rohal12/spindle 0.52.5 → 0.52.7

package/src/components/macros/Computed.tsx

@@ -2,9 +2,8 @@ import { useStoryStore } from '../../store';
 import { evaluate } from '../../expression';
 import { readState } from '../../execute-mutation';
 import { deepEqual } from '../../class-registry';
-import { currentSourceLocation } from '../../utils/source-location';
 import { defineMacro } from '../../define-macro';
-import { MacroError } from './MacroError';
+import { MacroError, logMacroError } from './MacroError';
 import { checkVariableName } from '../../utils/namespace';
 
 /**
@@ -14,38 +13,26 @@ import { checkVariableName } from '../../utils/namespace';
  */
 const UNSET: unique symbol = Symbol('unset');
 
-function parseComputedArgs(rawArgs: string): { target: string; expr: string } {
-  const trimmed = rawArgs.trim();
-
-  let depth = 0;
-  for (let i = 0; i < trimmed.length; i++) {
-    const ch = trimmed[i];
-    if (ch === '(' || ch === '[' || ch === '{') depth++;
-    else if (ch === ')' || ch === ']' || ch === '}') depth--;
-    else if (ch === '=' && depth === 0) {
-      if (trimmed[i + 1] === '=') {
-        i++;
-        continue;
-      }
-      if (i > 0 && trimmed[i - 1] === '!') continue;
-
-      const target = trimmed.slice(0, i).trim();
-      const expr = trimmed.slice(i + 1).trim();
-
-      if (!target.match(/^[$_@]\w+$/)) {
-        throw new Error(
-          `{computed}: target must be $name, _name, or @name, got "${target}"`,
-        );
-      }
+/** Check the arguments of "target = expression". */
+function assignmentArgs(
+  rawArgs: string,
+  args: { target?: string; '=': boolean; expression?: string },
+): { target: string; expr: string } {
+  if (!args['=']) {
+    throw new Error(
+      `{computed}: expected "target = expression", got "${rawArgs}"`,
+    );
+  }
 
-      checkVariableName(target.slice(1), target);
-      return { target, expr };
-    }
+  const { target = '', expression: expr = '' } = args;
+  if (!target.match(/^[$_@]\w+$/)) {
+    throw new Error(
+      `{computed}: target must be $name, _name, or @name, got "${target}"`,
+    );
   }
 
-  throw new Error(
-    `{computed}: expected "target = expression", got "${rawArgs}"`,
-  );
+  checkVariableName(target.slice(1), target);
+  return { target, expr };
 }
 
 /**
@@ -73,10 +60,7 @@ function computeAndApply(
     const { variables, temporary, transient } = readState();
     newValue = evaluate(expr, variables, temporary, getLocals(), transient);
   } catch (err) {
-    console.error(
-      `spindle: Error in {computed ${rawArgs}}${currentSourceLocation()}:`,
-      err,
-    );
+    logMacroError(`computed ${rawArgs}`, err);
     return;
   }
 
@@ -86,10 +70,7 @@ function computeAndApply(
       try {
         localsUpdate!(name, newValue);
       } catch (err) {
-        console.error(
-          `spindle: Error in {computed ${rawArgs}}${currentSourceLocation()}:`,
-          err,
-        );
+        logMacroError(`computed ${rawArgs}`, err);
       }
     } else {
       const state = useStoryStore.getState();
@@ -102,13 +83,18 @@ function computeAndApply(
 defineMacro({
   name: 'computed',
   merged: true,
+  parameters: [
+    { name: 'target', type: 'variable', required: true },
+    { name: '=', type: 'separator' },
+    { name: 'expression', type: 'expression', required: true },
+  ],
   render({ rawArgs }, ctx) {
     const [mergedVars, mergedTemps, mergedLocals, mergedTrans] = ctx.merged!;
 
     let target: string;
     let expr: string;
     try {
-      ({ target, expr } = parseComputedArgs(rawArgs));
+      ({ target, expr } = assignmentArgs(rawArgs, ctx.args));
     } catch (err) {
       return (
         <MacroError
@@ -124,9 +110,7 @@ defineMacro({
 
     const prevOutput = ctx.hooks.useRef<unknown>(UNSET);
 
-    const ran = ctx.hooks.useRef(false);
-    if (!ran.current) {
-      ran.current = true;
+    const compute = () =>
       computeAndApply(
         expr,
         name,
@@ -137,22 +121,21 @@ defineMacro({
         prevOutput,
         localsUpdate,
       );
+
+    const ran = ctx.hooks.useRef(false);
+    if (!ran.current) {
+      ran.current = true;
+      compute();
     }
 
     // The merged values only decide when to recompute; computeAndApply reads
     // the current ones.
-    ctx.hooks.useLayoutEffect(() => {
-      computeAndApply(
-        expr,
-        name,
-        isTemp,
-        isLocal,
-        ctx.getValues,
-        rawArgs,
-        prevOutput,
-        localsUpdate,
-      );
-    }, [mergedVars, mergedTemps, mergedLocals, mergedTrans]);
+    ctx.hooks.useLayoutEffect(compute, [
+      mergedVars,
+      mergedTemps,
+      mergedLocals,
+      mergedTrans,
+    ]);
 
     return null;
   },

package/src/components/macros/Cycle.tsx

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

package/src/components/macros/Dialog.tsx

@@ -1,20 +1,19 @@
 import { defineMacro } from '../../define-macro';
 import { PassageDialog } from '../PassageDialog';
-import { readWholeQuoted } from './arg-utils';
 
 defineMacro({
   name: 'dialog',
   block: true,
   interpolate: true,
-  render({ rawArgs, children = [] }, ctx) {
+  parameters: [
+    { name: 'label', type: 'text', required: true },
+    { name: 'noclose', type: 'flag' },
+  ],
+  render({ children = [] }, ctx) {
     const [open, setOpen] = ctx.hooks.useState(false);
 
-    const noclose = /\bnoclose\s*$/.test(rawArgs);
-    const labelRaw = rawArgs.replace(/\bnoclose\s*$/, '').trim();
-    const label =
-      ctx.resolve?.(
-        readWholeQuoted(labelRaw) ?? labelRaw.replace(/^["']|["']$/g, ''),
-      ) ?? labelRaw;
+    const { noclose } = ctx.args;
+    const label = ctx.resolve!(ctx.args.label ?? '');
     const passageName = ctx
       .collectText(children)
       .trim()

package/src/components/macros/Do.tsx

@@ -1,4 +1,5 @@
 import { defineMacro } from '../../define-macro';
+import { logMacroError } from './MacroError';
 
 defineMacro({
   name: 'do',
@@ -11,7 +12,7 @@ defineMacro({
       try {
         ctx.mutate(code);
       } catch (err) {
-        console.error(`spindle: Error in {do}${ctx.sourceLocation()}:`, err);
+        logMacroError('do', err);
       }
     }, []);
 

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 =