@rohal12/spindle 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",

package/src/components/PassageLink.tsx

@@ -1,5 +1,6 @@
 import { useStoryStore } from '../store';
 import { useAction } from '../hooks/use-action';
+import { useInterpolate } from '../hooks/use-interpolate';
 
 interface PassageLinkProps {
   target: string;
@@ -15,6 +16,9 @@ export function PassageLink({
   children,
 }: PassageLinkProps) {
   const navigate = useStoryStore((s) => s.navigate);
+  const resolve = useInterpolate();
+  className = resolve(className);
+  id = resolve(id);
 
   const handleClick = (e: MouseEvent) => {
     e.preventDefault();

package/src/components/macros/Button.tsx

@@ -6,6 +6,7 @@ import { deepClone } from '../../class-registry';
 import { collectText } from '../../utils/extract-text';
 import { useAction } from '../../hooks/use-action';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
+import { useInterpolate } from '../../hooks/use-interpolate';
 import { currentSourceLocation } from '../../utils/source-location';
 import type { ASTNode } from '../../markup/ast';
 
@@ -17,6 +18,9 @@ interface ButtonProps {
 }
 
 export function Button({ rawArgs, children, className, id }: ButtonProps) {
+  const resolve = useInterpolate();
+  className = resolve(className);
+  id = resolve(id);
   const scope = useContext(LocalsContext);
   const [, , mergedLocals] = useMergedLocals();
 

package/src/components/macros/Computed.tsx

@@ -1,4 +1,4 @@
-import { useLayoutEffect } from 'preact/hooks';
+import { useLayoutEffect, useRef } from 'preact/hooks';
 import { useStoryStore } from '../../store';
 import { evaluate } from '../../expression';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
@@ -59,6 +59,34 @@ function valuesEqual(a: unknown, b: unknown): boolean {
   return false;
 }
 
+function computeAndApply(
+  expr: string,
+  name: string,
+  isTemp: boolean,
+  variables: Record<string, unknown>,
+  temporary: Record<string, unknown>,
+  locals: Record<string, unknown>,
+  rawArgs: string,
+): void {
+  const state = useStoryStore.getState();
+  let newValue: unknown;
+  try {
+    newValue = evaluate(expr, variables, temporary, locals);
+  } catch (err) {
+    console.error(
+      `spindle: Error in {computed ${rawArgs}}${currentSourceLocation()}:`,
+      err,
+    );
+    return;
+  }
+
+  const current = isTemp ? state.temporary[name] : state.variables[name];
+  if (!valuesEqual(current, newValue)) {
+    if (isTemp) state.setTemporary(name, newValue);
+    else state.setVariable(name, newValue);
+  }
+}
+
 export function Computed({ rawArgs }: ComputedProps) {
   const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
 
@@ -79,31 +107,34 @@ export function Computed({ rawArgs }: ComputedProps) {
   const isTemp = target.startsWith('_');
   const name = target.slice(1);
 
-  // Evaluate in useLayoutEffect so preceding {set} effects have already run
-  useLayoutEffect(() => {
+  // Synchronous first evaluation — sees preceding synchronous {set} mutations
+  const ran = useRef(false);
+  if (!ran.current) {
+    ran.current = true;
     const state = useStoryStore.getState();
+    computeAndApply(
+      expr,
+      name,
+      isTemp,
+      state.variables,
+      state.temporary,
+      mergedLocals,
+      rawArgs,
+    );
+  }
 
-    let newValue: unknown;
-    try {
-      newValue = evaluate(expr, mergedVars, mergedTemps, mergedLocals);
-    } catch (err) {
-      console.error(
-        `spindle: Error in {computed ${rawArgs}}${currentSourceLocation()}:`,
-        err,
-      );
-      return;
-    }
-
-    const current = isTemp ? state.temporary[name] : state.variables[name];
-
-    if (!valuesEqual(current, newValue)) {
-      if (isTemp) {
-        state.setTemporary(name, newValue);
-      } else {
-        state.setVariable(name, newValue);
-      }
-    }
-  });
+  // Reactive re-evaluation when dependencies change (via useMergedLocals subscription)
+  useLayoutEffect(() => {
+    computeAndApply(
+      expr,
+      name,
+      isTemp,
+      mergedVars,
+      mergedTemps,
+      mergedLocals,
+      rawArgs,
+    );
+  }, [mergedVars, mergedTemps, mergedLocals]);
 
   return null;
 }

package/src/components/macros/For.tsx

@@ -3,6 +3,7 @@ import { evaluate } from '../../expression';
 import { LocalsContext, renderNodes } from '../../markup/render';
 import type { LocalsScope } from '../../markup/render';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
+import { useInterpolate } from '../../hooks/use-interpolate';
 import { currentSourceLocation } from '../../utils/source-location';
 import type { ASTNode } from '../../markup/ast';
 
@@ -76,6 +77,9 @@ function ForIteration({
 }
 
 export function For({ rawArgs, children, className, id }: ForProps) {
+  const resolve = useInterpolate();
+  className = resolve(className);
+  id = resolve(id);
   const parentScope = useContext(LocalsContext);
   const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
 

package/src/components/macros/If.tsx

@@ -1,6 +1,7 @@
 import { evaluate } from '../../expression';
 import { renderNodes } from '../../markup/render';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
+import { useInterpolate } from '../../hooks/use-interpolate';
 import { currentSourceLocation } from '../../utils/source-location';
 import type { Branch } from '../../markup/ast';
 
@@ -9,15 +10,18 @@ interface IfProps {
 }
 
 export function If({ branches }: IfProps) {
+  const resolve = useInterpolate();
   const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
 
   function renderBranch(branch: Branch) {
     const children = renderNodes(branch.children);
-    if (branch.className || branch.id)
+    const cls = resolve(branch.className);
+    const branchId = resolve(branch.id);
+    if (cls || branchId)
       return (
         <span
-          id={branch.id}
-          class={branch.className}
+          id={branchId}
+          class={cls}
         >
           {children}
         </span>

package/src/components/macros/Include.tsx

@@ -4,6 +4,7 @@ import { tokenize } from '../../markup/tokenizer';
 import { buildAST } from '../../markup/ast';
 import { renderNodes } from '../../markup/render';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
+import { useInterpolate } from '../../hooks/use-interpolate';
 import { currentSourceLocation } from '../../utils/source-location';
 
 interface IncludeProps {
@@ -13,6 +14,9 @@ interface IncludeProps {
 }
 
 export function Include({ rawArgs, className, id }: IncludeProps) {
+  const resolve = useInterpolate();
+  className = resolve(className);
+  id = resolve(id);
   const storyData = useStoryStore((s) => s.storyData);
   const [variables, temporary, locals] = useMergedLocals();
 

package/src/components/macros/MacroLink.tsx

@@ -5,6 +5,7 @@ import type { ASTNode } from '../../markup/ast';
 import { deepClone } from '../../class-registry';
 import { LocalsContext } from '../../markup/render';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
+import { useInterpolate } from '../../hooks/use-interpolate';
 import { currentSourceLocation } from '../../utils/source-location';
 
 interface MacroLinkProps {
@@ -99,6 +100,9 @@ export function MacroLink({
   className,
   id,
 }: MacroLinkProps) {
+  const resolve = useInterpolate();
+  className = resolve(className);
+  id = resolve(id);
   const { display, passage } = parseArgs(rawArgs);
   const scope = useContext(LocalsContext);
   const [, , mergedLocals] = useMergedLocals();

package/src/components/macros/Meter.tsx

@@ -1,5 +1,6 @@
 import { evaluate } from '../../expression';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
+import { useInterpolate } from '../../hooks/use-interpolate';
 
 interface MeterProps {
   rawArgs: string;
@@ -83,6 +84,9 @@ function formatLabel(
 }
 
 export function Meter({ rawArgs, className, id }: MeterProps) {
+  const resolve = useInterpolate();
+  className = resolve(className);
+  id = resolve(id);
   const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
 
   try {

package/src/components/macros/PassageDisplay.tsx

@@ -1,5 +1,6 @@
 import { useStoryStore } from '../../store';
 import { Passage } from '../Passage';
+import { useInterpolate } from '../../hooks/use-interpolate';
 
 interface PassageDisplayProps {
   className?: string;
@@ -7,6 +8,9 @@ interface PassageDisplayProps {
 }
 
 export function PassageDisplay({ className, id }: PassageDisplayProps) {
+  const resolve = useInterpolate();
+  className = resolve(className);
+  id = resolve(id);
   const currentPassage = useStoryStore((s) => s.currentPassage);
   const storyData = useStoryStore((s) => s.storyData);
 

package/src/components/macros/Print.tsx

@@ -1,5 +1,6 @@
 import { evaluate } from '../../expression';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
+import { useInterpolate } from '../../hooks/use-interpolate';
 import { currentSourceLocation } from '../../utils/source-location';
 
 interface PrintProps {
@@ -9,6 +10,9 @@ interface PrintProps {
 }
 
 export function Print({ rawArgs, className, id }: PrintProps) {
+  const resolve = useInterpolate();
+  className = resolve(className);
+  id = resolve(id);
   const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
 
   try {

package/src/components/macros/Repeat.tsx

@@ -1,7 +1,9 @@
 import { createContext } from 'preact';
-import { useState, useEffect, useCallback } from 'preact/hooks';
+import { useState, useEffect, useCallback, useMemo } from 'preact/hooks';
 import { renderNodes } from '../../markup/render';
 import { parseDelay } from '../../utils/parse-delay';
+import { hasInterpolation, interpolate } from '../../interpolation';
+import { useStoryStore } from '../../store';
 import type { ASTNode } from '../../markup/ast';
 
 export const RepeatContext = createContext<{ stop: () => void }>({
@@ -15,7 +17,21 @@ interface RepeatProps {
   id?: string;
 }
 
-export function Repeat({ rawArgs, children, className, id }: RepeatProps) {
+export function Repeat({
+  rawArgs,
+  children,
+  className: rawClassName,
+  id: rawId,
+}: RepeatProps) {
+  const [className, id] = useMemo(() => {
+    const resolveOnce = (s: string | undefined) => {
+      if (!s || !hasInterpolation(s)) return s;
+      const st = useStoryStore.getState();
+      return interpolate(s, st.variables, st.temporary, {});
+    };
+    return [resolveOnce(rawClassName), resolveOnce(rawId)];
+  }, [rawClassName, rawId]);
+
   const delay = parseDelay(rawArgs);
   const [count, setCount] = useState(0);
   const [stopped, setStopped] = useState(false);
@@ -36,7 +52,7 @@ export function Repeat({ rawArgs, children, className, id }: RepeatProps) {
 
   const content = (
     <RepeatContext.Provider value={{ stop }}>
-      {renderNodes(children)}
+      <span key={count}>{renderNodes(children)}</span>
     </RepeatContext.Provider>
   );
 

package/src/components/macros/Set.tsx

@@ -1,4 +1,4 @@
-import { useLayoutEffect, useContext } from 'preact/hooks';
+import { useRef, useContext } from 'preact/hooks';
 import { useStoryStore } from '../../store';
 import { execute } from '../../expression';
 import { deepClone } from '../../class-registry';
@@ -13,8 +13,10 @@ interface SetProps {
 export function Set({ rawArgs }: SetProps) {
   const scope = useContext(LocalsContext);
   const [, , mergedLocals] = useMergedLocals();
+  const ran = useRef(false);
 
-  useLayoutEffect(() => {
+  if (!ran.current) {
+    ran.current = true;
     const state = useStoryStore.getState();
     const vars = deepClone(state.variables);
     const temps = deepClone(state.temporary);
@@ -27,7 +29,7 @@ export function Set({ rawArgs }: SetProps) {
         `spindle: Error in {set ${rawArgs}}${currentSourceLocation()}:`,
         err,
       );
-      return;
+      return null;
     }
 
     // Diff and apply store changes
@@ -48,7 +50,7 @@ export function Set({ rawArgs }: SetProps) {
         scope.update(`@${key}`, localsClone[key]);
       }
     }
-  }, []);
+  }
 
   return null;
 }

package/src/components/macros/Timed.tsx

@@ -1,6 +1,7 @@
 import { useState, useEffect, useMemo } from 'preact/hooks';
 import { renderNodes } from '../../markup/render';
 import { parseDelay } from '../../utils/parse-delay';
+import { useInterpolate } from '../../hooks/use-interpolate';
 import type { ASTNode, Branch } from '../../markup/ast';
 
 interface TimedProps {
@@ -18,6 +19,9 @@ export function Timed({
   className,
   id,
 }: TimedProps) {
+  const resolve = useInterpolate();
+  className = resolve(className);
+  id = resolve(id);
   // Section 0 = initial children, sections 1..N = {next} branches
   // Each section has its own delay
   const sections = useMemo(() => {

package/src/components/macros/Type.tsx

@@ -1,6 +1,7 @@
 import { useState, useEffect, useRef } from 'preact/hooks';
 import { renderInlineNodes } from '../../markup/render';
 import { parseDelay } from '../../utils/parse-delay';
+import { useInterpolate } from '../../hooks/use-interpolate';
 import type { ASTNode } from '../../markup/ast';
 
 interface TypeProps {
@@ -11,6 +12,9 @@ interface TypeProps {
 }
 
 export function Type({ rawArgs, children, className, id }: TypeProps) {
+  const resolve = useInterpolate();
+  className = resolve(className);
+  id = resolve(id);
   const speed = parseDelay(rawArgs);
   const containerRef = useRef<HTMLSpanElement>(null);
   const [totalChars, setTotalChars] = useState(0);

package/src/components/macros/Unset.tsx

@@ -1,4 +1,4 @@
-import { useLayoutEffect } from 'preact/hooks';
+import { useRef } from 'preact/hooks';
 import { useStoryStore } from '../../store';
 
 interface UnsetProps {
@@ -6,7 +6,10 @@ interface UnsetProps {
 }
 
 export function Unset({ rawArgs }: UnsetProps) {
-  useLayoutEffect(() => {
+  const ran = useRef(false);
+
+  if (!ran.current) {
+    ran.current = true;
     const state = useStoryStore.getState();
     const name = rawArgs.trim();
 
@@ -19,7 +22,7 @@ export function Unset({ rawArgs }: UnsetProps) {
         `spindle: {unset} expects a variable ($name or _name), got "${name}"`,
       );
     }
-  }, []);
+  }
 
   return null;
 }

package/src/components/macros/VarDisplay.tsx

@@ -1,6 +1,7 @@
 import { useStoryStore } from '../../store';
 import { useContext } from 'preact/hooks';
 import { LocalsContext } from '../../markup/render';
+import { useInterpolate } from '../../hooks/use-interpolate';
 
 interface VarDisplayProps {
   name: string;
@@ -10,6 +11,9 @@ interface VarDisplayProps {
 }
 
 export function VarDisplay({ name, scope, className, id }: VarDisplayProps) {
+  const resolve = useInterpolate();
+  className = resolve(className);
+  id = resolve(id);
   const localsScope = useContext(LocalsContext);
   const parts = name.split('.');
   const root = parts[0]!;

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

@@ -7,7 +7,10 @@ export function extractOptions(children: ASTNode[]): string[] {
   const options: string[] = [];
   for (const node of children) {
     if (node.type === 'macro' && node.name === 'option') {
-      options.push(node.rawArgs.trim());
+      const raw = node.rawArgs.trim();
+      // Strip surrounding quotes so {option "Long Sword"} gives "Long Sword"
+      const stripped = raw.replace(/^(["'])(.+)\1$/, '$2');
+      options.push(stripped);
     }
   }
   return options;

package/src/expression.ts

@@ -37,13 +37,117 @@ const VAR_RE = /\$(\w+)/g;
 const TEMP_RE = /\b_(\w+)/g;
 const LOCAL_RE = /@(\w+)/g;
 
-function transform(expr: string): string {
-  return expr
+function transformSegment(segment: string): string {
+  return segment
     .replace(VAR_RE, 'variables["$1"]')
     .replace(TEMP_RE, 'temporary["$1"]')
     .replace(LOCAL_RE, 'locals["$1"]');
 }
 
+/**
+ * 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.
+ */
+function transform(expr: string): string {
+  let result = '';
+  let code = ''; // accumulates code characters to be transformed
+  let i = 0;
+
+  function flushCode() {
+    if (code) {
+      result += transformSegment(code);
+      code = '';
+    }
+  }
+
+  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;
+      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 {
+              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++;
+        }
+      }
+      continue;
+    }
+
+    // Regular code character
+    code += ch;
+    i++;
+  }
+  flushCode();
+  return result;
+}
+
 const preamble =
   'const {currentPassage,previousPassage,visited,hasVisited,hasVisitedAny,hasVisitedAll,rendered,hasRendered,hasRenderedAny,hasRenderedAll,random,randomInt}=__fns;';
 

package/src/hooks/use-interpolate.ts

@@ -0,0 +1,17 @@
+import { useCallback } from 'preact/hooks';
+import { useMergedLocals } from './use-merged-locals';
+import { hasInterpolation, interpolate } from '../interpolation';
+
+export function useInterpolate(): (
+  s: string | undefined,
+) => string | undefined {
+  const [variables, temporary, locals] = useMergedLocals();
+
+  return useCallback(
+    (s: string | undefined): string | undefined => {
+      if (s === undefined || !hasInterpolation(s)) return s;
+      return interpolate(s, variables, temporary, locals);
+    },
+    [variables, temporary, locals],
+  );
+}

package/src/index.tsx

@@ -99,7 +99,10 @@ function boot() {
           const widgetName = tokens2[0]!.replace(/["']/g, '');
           const params = tokens2
             .slice(1)
-            .filter((t) => t.startsWith('$') || t.startsWith('_'));
+            .filter(
+              (t) =>
+                t.startsWith('$') || t.startsWith('_') || t.startsWith('@'),
+            );
           registerWidget(widgetName, node.children as ASTNode[], params);
         }
       }

package/src/interpolation.ts

@@ -0,0 +1,44 @@
+const INTERP_RE = /\{(\$[\w.]+|_[\w.]+|@[\w.]+)\}/g;
+const INTERP_TEST = /\{[\$_@][\w.]+\}/;
+
+export function hasInterpolation(s: string): boolean {
+  return INTERP_TEST.test(s);
+}
+
+function resolveDotPath(root: unknown, parts: string[]): unknown {
+  let value = root;
+  for (let i = 1; i < parts.length; i++) {
+    if (value == null || typeof value !== 'object') return undefined;
+    value = (value as Record<string, unknown>)[parts[i]!];
+  }
+  return value;
+}
+
+export function interpolate(
+  template: string,
+  variables: Record<string, unknown>,
+  temporary: Record<string, unknown>,
+  locals: Record<string, unknown>,
+): string {
+  return template.replace(INTERP_RE, (_match, ref: string) => {
+    const prefix = ref[0]!;
+    const path = ref.slice(1);
+    const parts = path.split('.');
+    const root = parts[0]!;
+
+    let value: unknown;
+    if (prefix === '$') {
+      value = variables[root];
+    } else if (prefix === '_') {
+      value = temporary[root];
+    } else {
+      value = locals[root];
+    }
+
+    if (parts.length > 1) {
+      value = resolveDotPath(value, parts);
+    }
+
+    return value == null ? '' : String(value);
+  });
+}