@rohal12/spindle 0.51.4 → 0.52.1

package/src/components/macros/Switch.tsx

@@ -47,4 +47,17 @@ defineMacro({
 
     return null;
   },
+  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) : '';
+  },
 });

package/src/components/macros/Unset.tsx

@@ -1,31 +1,52 @@
 import { useStoryStore } from '../../store';
 import { defineMacro } from '../../define-macro';
+import { MacroError } from './MacroError';
 
 defineMacro({
   name: 'unset',
   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;
       const state = useStoryStore.getState();
       const name = rawArgs.trim();
 
-      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('@')) {
-        ctx.update(name.slice(1), undefined);
-      } else {
+      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: {unset} expects a variable ($name, _name, %name, or @name), got "${name}"`,
+          `spindle: Error in {unset ${rawArgs}}${ctx.sourceLocation()}:`,
+          err,
         );
       }
     }
 
+    if (failure.current) {
+      return (
+        <MacroError
+          macro="unset"
+          error={failure.current.error}
+        />
+      );
+    }
+
     return null;
   },
 });

package/src/components/macros/VarDisplay.tsx

@@ -2,6 +2,14 @@ import { useStoryStore } from '../../store';
 import { useContext } from 'preact/hooks';
 import { LocalsValuesContext } from '../../markup/render';
 import { useInterpolate } from '../../hooks/use-interpolate';
+import { RESERVED_NAME, ownValue } from '../../utils/namespace';
+
+const SIGILS = {
+  variable: '$',
+  temporary: '_',
+  local: '@',
+  transient: '%',
+} as const;
 
 interface VarDisplayProps {
   name: string;
@@ -17,19 +25,28 @@ export function VarDisplay({ name, scope, className, id }: VarDisplayProps) {
   const localsValues = useContext(LocalsValuesContext);
   const parts = name.split('.');
   const root = parts[0]!;
+  // Own entries only, as the expression engine reads them
   const storeValue = useStoryStore((s) =>
     scope === 'variable'
-      ? s.variables[root]
+      ? ownValue(s.variables, root)
       : scope === 'temporary'
-        ? s.temporary[root]
+        ? ownValue(s.temporary, root)
         : scope === 'transient'
-          ? s.transient[root]
+          ? ownValue(s.transient, root)
           : undefined,
   );
 
+  if (root === RESERVED_NAME) {
+    return (
+      <span class="error">
+        {`{${SIGILS[scope]}${name} error: "${SIGILS[scope]}${root}" cannot be used as a variable name (${RESERVED_NAME} is reserved)}`}
+      </span>
+    );
+  }
+
   let value: unknown;
   if (scope === 'local') {
-    value = root in localsValues ? localsValues[root] : undefined;
+    value = ownValue(localsValues, root);
   } else {
     value = storeValue;
   }

package/src/components/macros/Widget.tsx

@@ -2,11 +2,14 @@ import { registerWidget } from '../../widgets/widget-registry';
 import { astContainsChildren } from '../../widgets/ast-scanner';
 import { registerBlockMacro } from '../../markup/ast';
 import { defineMacro } from '../../define-macro';
+import { checkVariableName } from '../../utils/namespace';
+import { MacroError } from './MacroError';
 
 function parseWidgetDef(rawArgs: string): { name: string; params: string[] } {
   const tokens = rawArgs.trim().split(/\s+/);
   const name = tokens[0]!.replace(/["']/g, '');
   const params = tokens.slice(1).filter((t) => t.startsWith('@'));
+  for (const param of params) checkVariableName(param.slice(1), param);
   return { name, params };
 }
 
@@ -14,12 +17,20 @@ defineMacro({
   name: 'widget',
   block: true,
   render({ rawArgs, children = [] }, ctx) {
-    const { name, params } = parseWidgetDef(rawArgs);
+    let parsed: ReturnType<typeof parseWidgetDef> | undefined;
+    let error: unknown;
+    try {
+      parsed = parseWidgetDef(rawArgs);
+    } catch (err) {
+      error = err;
+    }
+    const { name, params } = parsed ?? { name: '', params: [] };
 
     const childrenKey = JSON.stringify(children);
     const paramsKey = params.join(',');
 
     ctx.hooks.useLayoutEffect(() => {
+      if (!parsed) return;
       // Widgets whose body renders {@children} take a closing tag; register
       // them as block macros so passages parsed later nest their content.
       const isBlock = astContainsChildren(children);
@@ -27,6 +38,14 @@ defineMacro({
       if (isBlock) registerBlockMacro(name);
     }, [name, childrenKey, paramsKey]);
 
+    if (error) {
+      return (
+        <MacroError
+          macro="widget"
+          error={error}
+        />
+      );
+    }
     return null;
   },
 });

package/src/components/macros/WidgetInvocation.tsx

@@ -11,12 +11,20 @@ import {
   NobrContext,
   InlineContext,
   WidgetChildrenContext,
+  RawTextContext,
   renderNodes,
 } from '../../markup/render';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
 import { evaluate } from '../../expression';
 import type { ASTNode } from '../../markup/ast';
-import { isWhitespace, splitTopLevel } from './arg-utils';
+import { splitArgs } from './arg-utils';
+import {
+  checkVariableName,
+  createNamespace,
+  withEntry,
+} from '../../utils/namespace';
+
+export { splitArgs };
 
 interface WidgetInvocationProps {
   body: ASTNode[];
@@ -25,75 +33,6 @@ interface WidgetInvocationProps {
   invocationChildren?: ASTNode[];
 }
 
-/**
- * Check whether a whitespace-delimited token looks like a standalone value
- * (not an operator or partial expression).
- */
-function isStandaloneValue(token: string): boolean {
-  const first = token[0]!;
-  // Quoted string
-  if (first === '"' || first === "'" || first === '`') return true;
-  // Variable ($var, _var, @var)
-  if (first === '$' || first === '_' || first === '@' || first === '%')
-    return true;
-  // Number literal
-  if (/\d/.test(first)) return true;
-  // Signed number (-1, +2)
-  if (
-    (first === '-' || first === '+') &&
-    token.length > 1 &&
-    /\d/.test(token[1]!)
-  )
-    return true;
-  // Grouped expression or collection literal
-  if (first === '(' || first === '[' || first === '{') return true;
-  // Boolean / null / undefined
-  if (/^(true|false|null|undefined)$/.test(token)) return true;
-  // Negation (!$flag, !true)
-  if (first === '!' && token.length > 1) return true;
-  return false;
-}
-
-/**
- * Try to split a raw string on whitespace at depth 0 (respecting strings,
- * template literals, parentheses, brackets, and braces). Each resulting token
- * must pass `isStandaloneValue()` or the split is rejected and `null` is
- * returned.
- */
-function trySplitOnWhitespace(raw: string): string[] | null {
-  const args = splitTopLevel(raw, isWhitespace).filter(Boolean);
-
-  // Need 2+ tokens
-  if (args.length < 2) return null;
-
-  // Every token must be a standalone value (not an operator)
-  for (const arg of args) {
-    if (!isStandaloneValue(arg)) return null;
-  }
-
-  return args;
-}
-
-/**
- * Split rawArgs by commas, respecting parentheses, brackets, braces, and
- * strings. When no top-level commas are present, also supports adjacent quoted
- * string literals separated by whitespace (e.g. `"Label" "target"`).
- */
-export function splitArgs(raw: string): string[] {
-  const args = splitTopLevel(raw, (ch) => ch === ',').map((a) => a.trim());
-  const hasComma = args.length > 1;
-  if (args[args.length - 1] === '') args.pop();
-
-  // If no commas were found and we got a single expression, try splitting
-  // on whitespace at depth 0 (e.g. "Label" "target", $var "text", $x $y).
-  if (!hasComma && args.length === 1) {
-    const split = trySplitOnWhitespace(args[0]!);
-    if (split) return split;
-  }
-
-  return args;
-}
-
 function WidgetBody({
   body,
   parentValues,
@@ -105,12 +44,13 @@ function WidgetBody({
 }) {
   const nobr = useContext(NobrContext);
   const inline = useContext(InlineContext);
+  const raw = useContext(RawTextContext);
   const [localMutations, setLocalMutations] = useState<Record<string, unknown>>(
     {},
   );
 
   const localState = useMemo(
-    () => ({ ...parentValues, ...ownKeys, ...localMutations }),
+    () => createNamespace(parentValues, ownKeys, localMutations),
     [parentValues, ownKeys, localMutations],
   );
 
@@ -122,7 +62,8 @@ function WidgetBody({
     // 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.
-    valuesRef.current = { ...valuesRef.current, [key]: value };
+    checkVariableName(key, `@${key}`);
+    valuesRef.current = withEntry(valuesRef.current, key, value);
     setLocalMutations((prev) => ({ ...prev, [key]: value }));
   }, []);
   const updater = useMemo(() => ({ update, getValues }), [update, getValues]);
@@ -130,7 +71,7 @@ function WidgetBody({
   return (
     <LocalsUpdateContext.Provider value={updater}>
       <LocalsValuesContext.Provider value={localState}>
-        {renderNodes(body, { nobr, inline, locals: localState })}
+        {renderNodes(body, { nobr, inline, raw, locals: localState })}
       </LocalsValuesContext.Provider>
     </LocalsUpdateContext.Provider>
   );
@@ -145,6 +86,7 @@ export function WidgetInvocation({
   const parentValues = useContext(LocalsValuesContext);
   const nobr = useContext(NobrContext);
   const inline = useContext(InlineContext);
+  const raw = useContext(RawTextContext);
   const [mergedVars, mergedTemps, mergedLocals, mergedTrans] =
     useMergedLocals();
 
@@ -155,7 +97,7 @@ export function WidgetInvocation({
   if (params.length === 0) {
     return (
       <WidgetChildrenContext.Provider value={childrenValue}>
-        {renderNodes(body, { nobr, inline, locals: parentValues })}
+        {renderNodes(body, { nobr, inline, raw, locals: parentValues })}
       </WidgetChildrenContext.Provider>
     );
   }
@@ -183,7 +125,7 @@ export function WidgetInvocation({
   }
 
   const ownKeys = useMemo(() => {
-    const keys: Record<string, unknown> = {};
+    const keys = createNamespace();
     for (let i = 0; i < params.length; i++) {
       keys[params[i]!.startsWith('@') ? params[i]!.slice(1) : params[i]!] =
         values[i];

package/src/components/macros/arg-utils.ts

@@ -75,7 +75,40 @@ export function readWholeQuoted(src: string): string | null {
  * lenient fallback for labels that are not one well-formed quoted string.
  */
 export function stripLooseQuotes(src: string): string {
-  return /^["']?(.+?)["']?$/.exec(src)?.[1] ?? src;
+  return /^["']?(.+?)["']?$/s.exec(src)?.[1] ?? src;
+}
+
+/** An operator character, or an operator keyword, at the end of code. */
+const TRAILING_OPERATOR_RE =
+  /(?:[-+*/%&|^!~=<>?:,.]|(?:^|[^\w$@.])(?:typeof|void|new|delete|in|instanceof|await|yield))$/;
+
+/**
+ * Whether `src` ends with an operator that still needs an operand (`$a +`,
+ * `$a+`, `$x ==`, `typeof`), so it cannot be a complete value on its own.
+ * Only code counts: the closing `/` of a regex literal is not division, a
+ * variable reference (`$a`, `%name`, ...) is an operand, trailing comments are skipped,
+ * and a postfix `++` or `--` completes its operand.
+ */
+export function endsWithOperator(src: string): boolean {
+  // Index just past the last code token, or -1 when a literal or transient
+  // reference ends the source.
+  let end = -1;
+  lexJs(src, {
+    code(ch, i, nesting) {
+      if (nesting === 0 && !isWhitespace(ch)) end = i + 1;
+    },
+    literal(text, _i, nesting) {
+      const comment = text.startsWith('//') || text.startsWith('/*');
+      if (nesting === 0 && !comment) end = -1;
+    },
+    variable(_sigil, _name, _i, nesting) {
+      if (nesting === 0) end = -1;
+    },
+  });
+  if (end < 0) return false;
+  const code = src.slice(0, end);
+  if (/(?:\+\+|--)$/.test(code)) return false;
+  return TRAILING_OPERATOR_RE.test(code);
 }
 
 /**
@@ -118,3 +151,76 @@ export function splitTopLevel(
   segments.push(src.slice(from));
   return segments;
 }
+
+/**
+ * Check whether a whitespace-delimited token looks like a standalone value
+ * (not an operator or partial expression): it starts like a value and does
+ * not end with an operator still waiting for its operand.
+ */
+function isStandaloneValue(token: string): boolean {
+  return startsLikeValue(token) && !endsWithOperator(token);
+}
+
+function startsLikeValue(token: string): boolean {
+  const first = token[0]!;
+  // Quoted string
+  if (first === '"' || first === "'" || first === '`') return true;
+  // Variable ($var, _var, @var, %var), but not the modulo operator in `$a % 2`
+  if (/^[$_@]\w|^%[A-Za-z_]/.test(token)) return true;
+  // Number literal
+  if (/\d/.test(first)) return true;
+  // Signed number (-1, +2)
+  if (
+    (first === '-' || first === '+') &&
+    token.length > 1 &&
+    /\d/.test(token[1]!)
+  )
+    return true;
+  // Grouped expression or collection literal
+  if (first === '(' || first === '[' || first === '{') return true;
+  // Boolean / null / undefined, alone or leading an expression (true||$x)
+  if (/^(?:true|false|null|undefined)(?![\w$])/.test(token)) return true;
+  // Negation (!$flag, !true), but not the operators != and !==
+  if (first === '!' && token.length > 1 && token[1] !== '=') return true;
+  return false;
+}
+
+/**
+ * Try to split a raw string on whitespace at depth 0 (respecting strings,
+ * template literals, parentheses, brackets, and braces). Each resulting token
+ * must pass `isStandaloneValue()` or the split is rejected and `null` is
+ * returned.
+ */
+function trySplitOnWhitespace(raw: string): string[] | null {
+  const args = splitTopLevel(raw, isWhitespace).filter(Boolean);
+
+  // Need 2+ tokens
+  if (args.length < 2) return null;
+
+  // Every token must be a standalone value (not an operator)
+  for (const arg of args) {
+    if (!isStandaloneValue(arg)) return null;
+  }
+
+  return args;
+}
+
+/**
+ * Split rawArgs by commas, respecting parentheses, brackets, braces, and
+ * strings. When no top-level commas are present, also supports adjacent quoted
+ * string literals separated by whitespace (e.g. `"Label" "target"`).
+ */
+export function splitArgs(raw: string): string[] {
+  const args = splitTopLevel(raw, (ch) => ch === ',').map((a) => a.trim());
+  const hasComma = args.length > 1;
+  if (args[args.length - 1] === '') args.pop();
+
+  // If no commas were found and we got a single expression, try splitting
+  // on whitespace at depth 0 (e.g. "Label" "target", $var "text", $x $y).
+  if (!hasComma && args.length === 1) {
+    const split = trySplitOnWhitespace(args[0]!);
+    if (split) return split;
+  }
+
+  return args;
+}

package/src/components/macros/detached-body.tsx

@@ -0,0 +1,68 @@
+import { render } from 'preact';
+import { useContext } from 'preact/hooks';
+import {
+  renderNodes,
+  LocalsUpdateContext,
+  LocalsValuesContext,
+  NobrContext,
+  InlineContext,
+  WidgetChildrenContext,
+} from '../../markup/render';
+import type { ASTNode } from '../../markup/ast';
+import { liveLocalsView } from '../../utils/live-locals';
+import { runWithCommittedMutations } from '../../execute-mutation';
+import { RepeatContext } from './Repeat';
+import { DialogCloseContext } from '../PassageDialog';
+
+/**
+ * Return a function that runs a macro body once, outside the passage tree:
+ * it renders `children` into a detached node, so the body's macros ({set},
+ * {if}, {goto}, ...) fire their side effects through the normal Preact
+ * pipeline, then unmounts it. Used by {button} and {link} on click.
+ *
+ * A detached render starts with no contexts, so the hook captures the ones
+ * the owning macro sees and provides them again: the locals scope (read
+ * through a live view, so a local assigned earlier in the body is visible),
+ * nobr/inline rendering, the enclosing block widget's {@children}, the
+ * enclosing {repeat}'s {stop} and the enclosing dialog's close callback.
+ * The body then behaves as if it rendered in place.
+ *
+ * The body's macros read story state from the store. Run from mutation code
+ * (Story.performAction, a click the code dispatches), it runs in program
+ * order: the code's writes so far are committed first, so the body sees
+ * them, and the code goes on from the state the body leaves (see
+ * runWithCommittedMutations).
+ */
+export function useDetachedBody(): (children: ASTNode[]) => void {
+  const updater = useContext(LocalsUpdateContext);
+  const nobr = useContext(NobrContext);
+  const inline = useContext(InlineContext);
+  const widgetChildren = useContext(WidgetChildrenContext);
+  const repeat = useContext(RepeatContext);
+  const closeDialog = useContext(DialogCloseContext);
+
+  const run = (children: ASTNode[]) => {
+    const locals = liveLocalsView(updater.getValues);
+    const container = document.createElement('div');
+    render(
+      <LocalsUpdateContext.Provider value={updater}>
+        <LocalsValuesContext.Provider value={locals}>
+          <NobrContext.Provider value={nobr}>
+            <InlineContext.Provider value={inline}>
+              <WidgetChildrenContext.Provider value={widgetChildren}>
+                <RepeatContext.Provider value={repeat}>
+                  <DialogCloseContext.Provider value={closeDialog}>
+                    {renderNodes(children, { nobr, inline, locals })}
+                  </DialogCloseContext.Provider>
+                </RepeatContext.Provider>
+              </WidgetChildrenContext.Provider>
+            </InlineContext.Provider>
+          </NobrContext.Provider>
+        </LocalsValuesContext.Provider>
+      </LocalsUpdateContext.Provider>,
+      container,
+    );
+    render(null, container);
+  };
+  return (children) => runWithCommittedMutations(() => run(children));
+}

package/src/components/macros/option-utils.ts

@@ -5,7 +5,8 @@ export function parseVarArgs(rawArgs: string): {
   varName: string;
   placeholder: string;
 } {
-  const match = rawArgs.match(/^\s*(["']?\$[\w.]+["']?)\s*(["'].*["'])?\s*$/);
+  // `s`: a quoted placeholder may span lines.
+  const match = rawArgs.match(/^\s*(["']?\$[\w.]+["']?)\s*(["'].*["'])?\s*$/s);
   if (!match) {
     return { varName: rawArgs.trim(), placeholder: '' };
   }
@@ -28,7 +29,7 @@ export function extractOptions(children: ASTNode[]): string[] {
       const raw = node.rawArgs.trim();
       // Strip surrounding quotes so {option "Long Sword"} gives "Long Sword"
       const stripped =
-        readWholeQuoted(raw) ?? raw.replace(/^(["'])(.+)\1$/, '$2');
+        readWholeQuoted(raw) ?? raw.replace(/^(["'])(.+)\1$/s, '$2');
       options.push(stripped);
     }
   }

package/src/define-macro.ts

@@ -16,14 +16,16 @@ import {
   LocalsValuesContext,
   NobrContext,
   InlineContext,
+  RawTextContext,
   renderNodes as _renderNodes,
   renderInlineNodes,
 } from './markup/render';
 import type { ASTNode } from './markup/ast';
-import { executeMutation } from './execute-mutation';
+import { executeMutation, readState } from './execute-mutation';
 import { evaluate } from './expression';
 import { useStoryStore } from './store';
 import { getByPath, setByPath } from './utils/object-path';
+import { RESERVED_NAME } from './utils/namespace';
 import { useAction } from './hooks/use-action';
 import type { UseActionOptions } from './hooks/use-action';
 import { collectText } from './utils/extract-text';
@@ -31,12 +33,15 @@ import { currentSourceLocation } from './utils/source-location';
 import { parseVarArgs, extractOptions } from './components/macros/option-utils';
 import {
   registerMacro,
+  registerMacroText,
   registerSubMacro,
   registerMacroMetadata,
 } from './registry';
-import type { MacroProps, ParameterDef } from './registry';
+import type { MacroProps, MacroTextContext, ParameterDef } from './registry';
 import { registerBlockMacro } from './markup/ast';
 
+export type { MacroTextContext };
+
 export function macroClass(type: string, className?: string): string {
   const base = `macro-${type}`;
   return className ? `${base} ${className}` : base;
@@ -91,6 +96,12 @@ export interface MacroDefinition {
   description?: string;
   parameters?: ParameterDef[];
   render: (props: MacroProps, ctx: MacroContext) => ComponentChildren;
+  /**
+   * The macro's text form, used where markup becomes a string: HTML
+   * attribute values, image alt text and link titles, macro labels. Without
+   * one, the macro can't be used there and is reported as an error.
+   */
+  text?: (props: MacroProps, ctx: MacroTextContext) => string;
 }
 
 const sharedHooks = {
@@ -122,6 +133,7 @@ export function defineMacro(
     const { update, getValues } = useContext(LocalsUpdateContext);
     const nobr = useContext(NobrContext);
     const inline = useContext(InlineContext);
+    const raw = useContext(RawTextContext);
     const localsValues = useContext(LocalsValuesContext);
     const renderNodes = (
       nodes: ASTNode[],
@@ -129,9 +141,16 @@ export function defineMacro(
         nobr?: boolean;
         locals?: Record<string, unknown>;
         inline?: boolean;
+        raw?: boolean;
       },
     ) =>
-      _renderNodes(nodes, { nobr, inline, locals: localsValues, ...options });
+      _renderNodes(nodes, {
+        nobr,
+        inline,
+        raw,
+        locals: localsValues,
+        ...options,
+      });
     const ctx: MacroContext = {
       collectText,
       sourceLocation: currentSourceLocation,
@@ -177,10 +196,17 @@ export function defineMacro(
 
       const varExpr = firstToken.replace(/["']/g, '').replace(/^\$/, '');
       const segments = varExpr.split('.');
+      if (segments.includes(RESERVED_NAME)) {
+        return h(
+          'span',
+          { class: 'error' },
+          `{${config.name}}: "$${varExpr}" cannot be bound: ${RESERVED_NAME} is reserved`,
+        );
+      }
       ctx.varName = varExpr;
       ctx.value = useStoryStore((s) => getByPath(s.variables, segments));
-      ctx.getValue = () =>
-        getByPath(useStoryStore.getState().variables, segments);
+      // In program order, also when mutation code performs the input
+      ctx.getValue = () => getByPath(readState().variables, segments);
       ctx.setValue = (value: unknown) => {
         useStoryStore.setState((state) => {
           setByPath(state.variables, segments, value, {
@@ -194,6 +220,7 @@ export function defineMacro(
   }
 
   registerMacro(config.name, Wrapper);
+  registerMacroText(config.name, config.text);
 
   // Store metadata for tooling API
   const isBlock =