@rohal12/spindle 0.51.3 → 0.52.0

package/src/expression.ts

@@ -2,6 +2,14 @@ import type { StoryState } from './store';
 import { useStoryStore } from './store';
 import type { Passage } from './parser';
 import { random, randomInt } from './prng';
+import { lexJs, type JsGoal, type Sigil } from './js-lexer';
+import {
+  EMPTY_NAMESPACE,
+  RESERVED_NAME,
+  asNamespace,
+  isNamespace,
+  type Namespace,
+} from './utils/namespace';
 
 interface ExpressionFns {
   currentPassage: () => Passage | undefined;
@@ -29,272 +37,53 @@ type CompiledExpression = (
 const FN_CACHE_MAX = 500;
 const fnCache = new Map<string, CompiledExpression>();
 
-/**
- * Transform expression: $var → variables["var"], _var → temporary["var"],
- * @var → locals["var"]
- * Only transforms when sigils appear as a word boundary (not inside strings naively,
- * but authors already have full JS access so this is acceptable).
- * `%var` → transient["var"] is handled by `transform` itself, because `%` is
- * also the modulo operator and only an operand position makes it a sigil.
- */
-const VAR_RE = /\$(\w+)/g;
-const TEMP_RE = /(?<![.\w])_(\w+)/g;
-const LOCAL_RE = /@(\w+)/g;
-/** Transient name after `%`: an identifier, so `%3` is never a reference. */
-const TRANS_NAME_RE = /[A-Za-z_]\w*/y;
-/** Characters of identifiers, numbers and sigil variable references. */
-const WORD_CHAR_RE = /[\w$@]/;
-const SPACE_RE = /\s/;
-/** Keywords followed by an operand rather than an operator. */
-const OPERAND_KEYWORDS = new Set([
-  'await',
-  'case',
-  'delete',
-  'do',
-  'else',
-  'in',
-  'instanceof',
-  'new',
-  'of',
-  'return',
-  'throw',
-  'typeof',
-  'void',
-  'yield',
-]);
-/** Keywords whose parenthesised header is followed by a statement. */
-const HEADER_KEYWORDS = new Set(['for', 'if', 'while', 'with']);
+const NAMESPACES: Record<Sigil, string> = {
+  $: 'variables',
+  _: 'temporary',
+  '@': 'locals',
+  '%': 'transient',
+};
 
-function transformSegment(segment: string): string {
-  return segment
-    .replace(VAR_RE, 'variables["$1"]')
-    .replace(TEMP_RE, 'temporary["$1"]')
-    .replace(LOCAL_RE, 'locals["$1"]');
-}
+/** Ends with an identifier character. */
+const IDENT_END_RE = /[\p{ID_Continue}$\u200c\u200d]$/u;
 
 /**
- * String-aware expression transformer. Walks the expression character by
- * character so that variable sigils ($, _, @, %) inside string literals are
- * left untouched while code — including expressions inside template-literal
- * `${…}` interpolations — is transformed.
- *
- * It also tracks whether the next token is an operand or an operator, so that
- * `%name` in operand position is a transient reference while `%` after an
- * operand — `($n)%3`, `$a[i] %2`, `$a%$b` — stays the modulo operator.
+ * Transform expression: $var → variables["var"], _var → temporary["var"],
+ * @var → locals["var"], %var → transient["var"].
+ * The lexer (`lexJs`) finds the references: only in code (string, template
+ * and regex literal text and comments are left untouched), only where an
+ * identifier starts (not in `a$b`, nor as the property name in `obj._x`),
+ * and `%var` only where an operand is expected, since `%` is also the
+ * modulo operator. `goal` tells whether `expr` is an expression or a list of
+ * statements, as that decides whether a leading `{` opens an object literal
+ * or a block. A reference to a variable named `__proto__` throws a
+ * SyntaxError: no namespace can hold one (see utils/namespace.ts).
+ * Exported for tests.
  */
-function transform(expr: string): string {
+export function transform(expr: string, goal: JsGoal = 'expression'): string {
   let result = '';
-  let code = ''; // accumulates code characters to be transformed
-  let i = 0;
-
-  let operandNext = true; // an operand (not an operator) comes next
-  let word = ''; // identifier/number currently being read
-  let afterDot = false; // `word` is a property name, never a keyword
-  let afterHeaderKeyword = false; // last token was if/while/for/with
-  let lastPunct = '';
-  const parenIsHeader: boolean[] = []; // per open `(`: closes a header?
-
-  function flushCode() {
-    if (code) {
-      result += transformSegment(code);
-      code = '';
-    }
-  }
-
-  function endWord() {
-    if (!word) return;
-    operandNext = !afterDot && OPERAND_KEYWORDS.has(word);
-    afterHeaderKeyword = !afterDot && HEADER_KEYWORDS.has(word);
-    afterDot = false;
-    lastPunct = '';
-    word = '';
-  }
-
-  /** A string or template literal, or a transient reference, just ended. */
-  function endOperand() {
-    endWord();
-    operandNext = false;
-    afterHeaderKeyword = false;
-    afterDot = false;
-    lastPunct = '';
-  }
-
-  function trackCode(c: string) {
-    if (WORD_CHAR_RE.test(c)) {
-      word += c;
-      return;
-    }
-    endWord();
-    // A line may start a new statement such as `%x = 1`.
-    if (c === '\n') operandNext = true;
-    if (SPACE_RE.test(c)) return;
-    if (c === '(') parenIsHeader.push(afterHeaderKeyword);
-    if (c === ')') {
-      // `if (…) %x = 1` vs `($n)%3`
-      operandNext = parenIsHeader.pop() ?? false;
-    } else if (c === '.') {
-      // Property access, unless it is the spread `...`
-      operandNext = lastPunct === '.';
-    } else {
-      // `]` ends an operand; `}` closes a block, so a statement may follow.
-      operandNext = c !== ']';
-    }
-    afterDot = c === '.';
-    afterHeaderKeyword = false;
-    lastPunct = c;
-  }
-
-  while (i < expr.length) {
-    const ch = expr.charAt(i);
-
-    // Single or double quoted string — skip entirely
-    if (ch === '"' || ch === "'") {
-      flushCode();
-      const quote = ch;
-      let str = quote;
-      i++;
-      while (i < expr.length) {
-        const c = expr.charAt(i);
-        if (c === '\\' && i + 1 < expr.length) {
-          str += c + expr.charAt(i + 1);
-          i += 2;
-        } else if (c === quote) {
-          str += quote;
-          i++;
-          break;
-        } else {
-          str += c;
-          i++;
-        }
-      }
-      result += str;
-      endOperand();
-      continue;
-    }
-
-    // Template literal — preserve literal parts, transform interpolations
-    if (ch === '`') {
-      flushCode();
-      result += '`';
-      i++;
-      while (i < expr.length) {
-        const c = expr.charAt(i);
-        if (c === '\\' && i + 1 < expr.length) {
-          result += c + expr.charAt(i + 1);
-          i += 2;
-        } else if (c === '$' && expr.charAt(i + 1) === '{') {
-          // Template interpolation — collect the inner expression and
-          // recursively transform it
-          result += '${';
-          i += 2;
-          let depth = 1;
-          let inner = '';
-          while (i < expr.length && depth > 0) {
-            const ic = expr.charAt(i);
-            if (ic === '{') {
-              depth++;
-              inner += ic;
-            } else if (ic === '}') {
-              depth--;
-              if (depth === 0) break;
-              inner += ic;
-            } else if (ic === '\\' && i + 1 < expr.length) {
-              inner += ic + expr.charAt(i + 1);
-              i++;
-            } else if (ic === '"' || ic === "'") {
-              // Skip quoted strings — braces inside are not depth-relevant
-              inner += ic;
-              i++;
-              while (i < expr.length) {
-                const sc = expr.charAt(i);
-                if (sc === '\\' && i + 1 < expr.length) {
-                  inner += sc + expr.charAt(i + 1);
-                  i += 2;
-                } else if (sc === ic) {
-                  inner += sc;
-                  i++;
-                  break;
-                } else {
-                  inner += sc;
-                  i++;
-                }
-              }
-              continue; // skip the i++ at the end
-            } else if (ic === '`') {
-              // Nested template literal — consume entirely
-              inner += ic;
-              i++;
-              while (i < expr.length) {
-                const tc = expr.charAt(i);
-                if (tc === '\\' && i + 1 < expr.length) {
-                  inner += tc + expr.charAt(i + 1);
-                  i += 2;
-                } else if (tc === '$' && expr.charAt(i + 1) === '{') {
-                  // Nested interpolation — track brace depth
-                  inner += '${';
-                  i += 2;
-                  let nestedDepth = 1;
-                  while (i < expr.length && nestedDepth > 0) {
-                    const nc = expr.charAt(i);
-                    if (nc === '{') nestedDepth++;
-                    else if (nc === '}') nestedDepth--;
-                    if (nestedDepth > 0) inner += nc;
-                    i++;
-                  }
-                  inner += '}';
-                } else if (tc === '`') {
-                  inner += tc;
-                  i++;
-                  break;
-                } else {
-                  inner += tc;
-                  i++;
-                }
-              }
-              continue; // skip the i++ at the end
-            } else {
-              inner += ic;
-            }
-            i++;
-          }
-          result += transform(inner); // recursive transform
-          if (i < expr.length && expr.charAt(i) === '}') {
-            result += '}';
-            i++;
-          }
-        } else if (c === '`') {
-          result += '`';
-          i++;
-          break;
-        } else {
-          result += c;
-          i++;
+  lexJs(
+    expr,
+    {
+      code(ch) {
+        result += ch;
+      },
+      literal(text) {
+        result += text;
+      },
+      variable(sigil, name) {
+        if (name === RESERVED_NAME) {
+          throw new SyntaxError(
+            `spindle: "${sigil}${name}" cannot be used as a variable name (${RESERVED_NAME} is reserved)`,
+          );
         }
-      }
-      endOperand();
-      continue;
-    }
-
-    // Transient reference — only where an operand is expected
-    if (ch === '%') {
-      endWord();
-      TRANS_NAME_RE.lastIndex = i + 1;
-      const name = operandNext ? TRANS_NAME_RE.exec(expr)?.[0] : undefined;
-      if (name) {
-        flushCode();
-        result += `transient["${name}"]`;
-        i += 1 + name.length;
-        endOperand();
-        continue;
-      }
-    }
-
-    // Regular code character
-    trackCode(ch);
-    code += ch;
-    i++;
-  }
-  flushCode();
+        // `typeof%x` needs a space once `%x` turns into an identifier.
+        if (IDENT_END_RE.test(result.slice(-2))) result += ' ';
+        result += `${NAMESPACES[sigil]}["${name}"]`;
+      },
+    },
+    goal,
+  );
   return result;
 }
 
@@ -389,21 +178,42 @@ export function buildExpressionFns() {
   return cachedFns;
 }
 
+/**
+ * The namespaces compiled code reads and writes are records without a
+ * prototype (story state keeps them that way, see utils/namespace.ts), so
+ * `$toString` is the variable, not the method. One that has a prototype
+ * loses it, in place so that writes still reach it; one that cannot change
+ * is passed as a copy (writes to it are lost either way).
+ */
+function namespaceArg(ns: Namespace): Namespace {
+  if (isNamespace(ns)) return ns;
+  if (!Object.isExtensible(ns)) return asNamespace(ns);
+  Object.setPrototypeOf(ns, null);
+  return ns;
+}
+
 /**
  * Evaluate an expression and return its value.
  * e.g. evaluate("$health + 10", variables, temporary) → number
  */
 export function evaluate(
   expr: string,
-  variables: Record<string, unknown>,
-  temporary: Record<string, unknown>,
-  locals: Record<string, unknown> = {},
-  transient: Record<string, unknown> = {},
+  variables: Namespace,
+  temporary: Namespace,
+  locals: Namespace = EMPTY_NAMESPACE,
+  transient: Namespace = EMPTY_NAMESPACE,
 ): unknown {
   const transformed = transform(expr);
-  const body = `return (${transformed});`;
+  // The line break keeps a trailing `// comment` from swallowing the `)`.
+  const body = `return (${transformed}\n);`;
   const fn = getOrCompile(body, body);
-  return fn(variables, temporary, locals, buildExpressionFns(), transient);
+  return fn(
+    namespaceArg(variables),
+    namespaceArg(temporary),
+    namespaceArg(locals),
+    buildExpressionFns(),
+    namespaceArg(transient),
+  );
 }
 
 /**
@@ -412,14 +222,20 @@ export function evaluate(
  */
 export function execute(
   code: string,
-  variables: Record<string, unknown>,
-  temporary: Record<string, unknown>,
-  locals: Record<string, unknown> = {},
-  transient: Record<string, unknown> = {},
+  variables: Namespace,
+  temporary: Namespace,
+  locals: Namespace = EMPTY_NAMESPACE,
+  transient: Namespace = EMPTY_NAMESPACE,
 ): void {
-  const transformed = transform(code);
+  const transformed = transform(code, 'statements');
   const fn = getOrCompile('exec:' + transformed, transformed);
-  fn(variables, temporary, locals, buildExpressionFns(), transient);
+  fn(
+    namespaceArg(variables),
+    namespaceArg(temporary),
+    namespaceArg(locals),
+    buildExpressionFns(),
+    namespaceArg(transient),
+  );
 }
 
 /**

package/src/hooks/use-action.ts

@@ -1,6 +1,7 @@
 import { useLayoutEffect, useRef } from 'preact/hooks';
 import {
   registerAction,
+  updateAction,
   generateActionId,
   type ActionType,
   type StoryAction,
@@ -31,7 +32,7 @@ export function useAction(opts: UseActionOptions): string {
 
   const id = idRef.current;
 
-  useLayoutEffect(() => {
+  const buildAction = (): StoryAction => {
     const action: StoryAction = {
       id,
       type: opts.type,
@@ -43,10 +44,24 @@ export function useAction(opts: UseActionOptions): string {
     if (opts.options !== undefined) action.options = opts.options;
     if (opts.value !== undefined) action.value = opts.value;
     if (opts.disabled !== undefined) action.disabled = opts.disabled;
+    return action;
+  };
+
+  // Registered for the component's lifetime.
+  useLayoutEffect(() => registerAction(buildAction()), [id]);
 
-    return registerAction(action);
+  // When what the action exposes changes (e.g. an input's value), replace it
+  // in place: one `actionsChanged` notification, and it keeps its position in
+  // getActions(). Unregistering and registering again would notify twice and
+  // move it to the end.
+  const registered = useRef(false);
+  useLayoutEffect(() => {
+    if (!registered.current) {
+      registered.current = true; // the registration above is current
+      return;
+    }
+    updateAction(buildAction());
   }, [
-    id,
     opts.type,
     opts.label,
     opts.target,

package/src/hooks/use-interpolate.ts

@@ -1,17 +1,48 @@
-import { useCallback } from 'preact/hooks';
+import { useCallback, useContext, useMemo } from 'preact/hooks';
 import { useMergedLocals } from './use-merged-locals';
-import { hasInterpolation, interpolate } from '../interpolation';
+import { WidgetChildrenContext } from '../markup/render';
+import {
+  hasInterpolation,
+  interpolateText,
+  type TextScope,
+} from '../interpolation';
+import { errorMessage } from '../utils/error-message';
 
+/**
+ * The scope text-only markup (attribute values, labels) is evaluated in:
+ * store variables, locals and the enclosing block widget's children. The
+ * caller re-renders whenever one of them changes.
+ */
+export function useTextScope(): TextScope {
+  const [variables, temporary, locals, transient] = useMergedLocals();
+  const widgetChildren = useContext(WidgetChildrenContext);
+  return useMemo(
+    () => ({ variables, temporary, locals, transient, widgetChildren }),
+    [variables, temporary, locals, transient, widgetChildren],
+  );
+}
+
+/**
+ * Return a function resolving the markup in a string (a macro label, class
+ * or id) to text. Errors (a macro with no text form, a failing expression)
+ * are logged, and their part of the string is left empty.
+ */
 export function useInterpolate(): (
   s: string | undefined,
 ) => string | undefined {
-  const [variables, temporary, locals, transient] = useMergedLocals();
+  const scope = useTextScope();
 
   return useCallback(
     (s: string | undefined): string | undefined => {
       if (s === undefined || !hasInterpolation(s)) return s;
-      return interpolate(s, variables, temporary, locals, transient);
+      const { text, errors } = interpolateText(s, scope);
+      for (const { macro, error } of errors) {
+        console.error(
+          `spindle: {${macro}} error in "${s}": ${errorMessage(error)}`,
+        );
+      }
+      return text;
     },
-    [variables, temporary, locals, transient],
+    [scope],
   );
 }

package/src/index.tsx

@@ -21,6 +21,7 @@ import { tokenize } from './markup/tokenizer';
 import { buildAST, registerBlockMacro } from './markup/ast';
 import { registerWidget } from './widgets/widget-registry';
 import { astContainsChildren } from './widgets/ast-scanner';
+import { errorMessage } from './utils/error-message';
 import type { ASTNode } from './markup/ast';
 import './macros/register-builtins';
 import builtinCSS from './styles.css?inline';
@@ -182,7 +183,15 @@ export function boot() {
             );
           const children = node.children as ASTNode[];
           const isBlock = astContainsChildren(children);
-          registerWidget(widgetName, children, params, isBlock);
+          try {
+            registerWidget(widgetName, children, params, isBlock);
+          } catch (err) {
+            // As the {widget} macro refuses it: the others still register
+            console.error(
+              `spindle: widget "${widgetName}" in passage "${passage.name}" was not registered: ${errorMessage(err)}`,
+            );
+            continue;
+          }
           if (isBlock) {
             registerBlockMacro(widgetName);
           }