@rohal12/spindle 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",
@@ -38,6 +38,7 @@
     "compile": "bun run scripts/compile-story.ts",
     "preview": "bun run build && bun run compile",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "typecheck": "tsc --noEmit",
@@ -64,6 +65,7 @@
     "@preact/preset-vite": "^2.10.3",
     "@rohal12/twee-ts": "^1.1.2",
     "@types/js-yaml": "^4.0.9",
+    "@types/react": "^18.3.28",
     "@vitest/coverage-v8": "^4.0.18",
     "happy-dom": "^20.8.3",
     "husky": "^9.1.7",

package/src/components/macros/Button.tsx

@@ -1,9 +1,11 @@
+import { useContext } from 'preact/hooks';
 import { useStoryStore } from '../../store';
 import { execute } from '../../expression';
-import { renderInlineNodes } from '../../markup/render';
+import { renderInlineNodes, LocalsContext } from '../../markup/render';
 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 type { ASTNode } from '../../markup/ast';
 
 interface ButtonProps {
@@ -14,13 +16,17 @@ interface ButtonProps {
 }
 
 export function Button({ rawArgs, children, className, id }: ButtonProps) {
+  const scope = useContext(LocalsContext);
+  const [, , mergedLocals] = useMergedLocals();
+
   const handleClick = () => {
     const state = useStoryStore.getState();
     const vars = deepClone(state.variables);
     const temps = deepClone(state.temporary);
+    const localsClone = { ...mergedLocals };
 
     try {
-      execute(rawArgs, vars, temps);
+      execute(rawArgs, vars, temps, localsClone);
     } catch (err) {
       console.error(`spindle: Error in {button ${rawArgs}}:`, err);
       return;
@@ -36,6 +42,11 @@ export function Button({ rawArgs, children, className, id }: ButtonProps) {
         state.setTemporary(key, temps[key]);
       }
     }
+    for (const key of Object.keys(localsClone)) {
+      if (localsClone[key] !== mergedLocals[key]) {
+        scope.update(`@${key}`, localsClone[key]);
+      }
+    }
   };
 
   useAction({

package/src/components/macros/Computed.tsx

@@ -59,7 +59,7 @@ function valuesEqual(a: unknown, b: unknown): boolean {
 }
 
 export function Computed({ rawArgs }: ComputedProps) {
-  const [mergedVars, mergedTemps] = useMergedLocals();
+  const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
 
   let target: string;
   let expr: string;
@@ -84,7 +84,7 @@ export function Computed({ rawArgs }: ComputedProps) {
 
     let newValue: unknown;
     try {
-      newValue = evaluate(expr, mergedVars, mergedTemps);
+      newValue = evaluate(expr, mergedVars, mergedTemps, mergedLocals);
     } catch (err) {
       console.error(`spindle: Error in {computed ${rawArgs}}:`, err);
       return;

package/src/components/macros/Do.tsx

@@ -1,8 +1,10 @@
-import { useLayoutEffect } from 'preact/hooks';
+import { useLayoutEffect, useContext } from 'preact/hooks';
 import { useStoryStore } from '../../store';
 import { execute } from '../../expression';
 import type { ASTNode } from '../../markup/ast';
 import { deepClone } from '../../class-registry';
+import { LocalsContext } from '../../markup/render';
+import { useMergedLocals } from '../../hooks/use-merged-locals';
 
 interface DoProps {
   children: ASTNode[];
@@ -17,14 +19,17 @@ function collectText(nodes: ASTNode[]): string {
 
 export function Do({ children }: DoProps) {
   const code = collectText(children);
+  const scope = useContext(LocalsContext);
+  const [, , mergedLocals] = useMergedLocals();
 
   useLayoutEffect(() => {
     const state = useStoryStore.getState();
     const vars = deepClone(state.variables);
     const temps = deepClone(state.temporary);
+    const localsClone = { ...mergedLocals };
 
     try {
-      execute(code, vars, temps);
+      execute(code, vars, temps, localsClone);
     } catch (err) {
       console.error(`spindle: Error in {do}:`, err);
       return;
@@ -41,6 +46,11 @@ export function Do({ children }: DoProps) {
         state.setTemporary(key, temps[key]);
       }
     }
+    for (const key of Object.keys(localsClone)) {
+      if (localsClone[key] !== mergedLocals[key]) {
+        scope.update(`@${key}`, localsClone[key]);
+      }
+    }
   }, []);
 
   return null;

package/src/components/macros/For.tsx

@@ -1,6 +1,7 @@
-import { useContext } from 'preact/hooks';
+import { useContext, useState, useCallback } from 'preact/hooks';
 import { evaluate } from '../../expression';
 import { LocalsContext, renderNodes } from '../../markup/render';
+import type { LocalsScope } from '../../markup/render';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
 import type { ASTNode } from '../../markup/ast';
 
@@ -12,7 +13,7 @@ interface ForProps {
 }
 
 /**
- * Parse for-loop args: "$item, $i of $list" or "$item of $list"
+ * Parse for-loop args: "@item, @i of $list" or "@item of $list"
  */
 function parseForArgs(rawArgs: string): {
   itemVar: string;
@@ -31,12 +32,51 @@ function parseForArgs(rawArgs: string): {
   const itemVar = vars[0]!;
   const indexVar = vars.length > 1 ? vars[1]! : null;
 
+  if (!itemVar.startsWith('@')) {
+    throw new Error(`{for} loop variable must use @ prefix: got "${itemVar}"`);
+  }
+  if (indexVar && !indexVar.startsWith('@')) {
+    throw new Error(
+      `{for} index variable must use @ prefix: got "${indexVar}"`,
+    );
+  }
+
   return { itemVar, indexVar, listExpr };
 }
 
+function ForIteration({
+  parentValues,
+  ownKeys,
+  initialValues,
+  children,
+}: {
+  parentValues: Record<string, unknown>;
+  ownKeys: Record<string, unknown>;
+  initialValues: Record<string, unknown>;
+  children: ASTNode[];
+}) {
+  const [localState, setLocalState] = useState<Record<string, unknown>>(() => ({
+    ...parentValues,
+    ...ownKeys,
+    ...initialValues,
+  }));
+
+  const update = useCallback((key: string, value: unknown) => {
+    setLocalState((prev) => ({ ...prev, [key]: value }));
+  }, []);
+
+  const scope: LocalsScope = { values: localState, update };
+
+  return (
+    <LocalsContext.Provider value={scope}>
+      {renderNodes(children)}
+    </LocalsContext.Provider>
+  );
+}
+
 export function For({ rawArgs, children, className, id }: ForProps) {
-  const parentLocals = useContext(LocalsContext);
-  const [mergedVars, mergedTemps] = useMergedLocals();
+  const parentScope = useContext(LocalsContext);
+  const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
 
   let parsed: ReturnType<typeof parseForArgs>;
   try {
@@ -56,7 +96,7 @@ export function For({ rawArgs, children, className, id }: ForProps) {
 
   let list: unknown[];
   try {
-    const result = evaluate(listExpr, mergedVars, mergedTemps);
+    const result = evaluate(listExpr, mergedVars, mergedTemps, mergedLocals);
     if (!Array.isArray(result)) {
       return (
         <span class="error">
@@ -77,19 +117,19 @@ export function For({ rawArgs, children, className, id }: ForProps) {
   }
 
   const content = list.map((item, i) => {
-    const locals = {
-      ...parentLocals,
+    const ownKeys: Record<string, unknown> = {
       [itemVar]: item,
       ...(indexVar ? { [indexVar]: i } : undefined),
     };
 
     return (
-      <LocalsContext.Provider
+      <ForIteration
         key={i}
-        value={locals}
-      >
-        {renderNodes(children)}
-      </LocalsContext.Provider>
+        parentValues={parentScope.values}
+        ownKeys={ownKeys}
+        initialValues={{}}
+        children={children}
+      />
     );
   });
 

package/src/components/macros/Goto.tsx

@@ -1,22 +1,24 @@
 import { useLayoutEffect } from 'preact/hooks';
 import { useStoryStore } from '../../store';
 import { evaluate } from '../../expression';
+import { useMergedLocals } from '../../hooks/use-merged-locals';
 
 interface GotoProps {
   rawArgs: string;
 }
 
 export function Goto({ rawArgs }: GotoProps) {
+  const [variables, temporary, locals] = useMergedLocals();
+
   useLayoutEffect(() => {
-    const state = useStoryStore.getState();
     let passageName: string;
     try {
-      const result = evaluate(rawArgs, state.variables, state.temporary);
+      const result = evaluate(rawArgs, variables, temporary, locals);
       passageName = String(result);
     } catch {
       passageName = rawArgs.replace(/^["']|["']$/g, '');
     }
-    state.navigate(passageName);
+    useStoryStore.getState().navigate(passageName);
   }, []);
 
   return null;

package/src/components/macros/If.tsx

@@ -8,7 +8,7 @@ interface IfProps {
 }
 
 export function If({ branches }: IfProps) {
-  const [mergedVars, mergedTemps] = useMergedLocals();
+  const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
 
   function renderBranch(branch: Branch) {
     const children = renderNodes(branch.children);
@@ -31,7 +31,12 @@ export function If({ branches }: IfProps) {
     }
 
     try {
-      const result = evaluate(branch.rawArgs, mergedVars, mergedTemps);
+      const result = evaluate(
+        branch.rawArgs,
+        mergedVars,
+        mergedTemps,
+        mergedLocals,
+      );
       if (result) {
         return renderBranch(branch);
       }

package/src/components/macros/Include.tsx

@@ -3,6 +3,7 @@ import { evaluate } from '../../expression';
 import { tokenize } from '../../markup/tokenizer';
 import { buildAST } from '../../markup/ast';
 import { renderNodes } from '../../markup/render';
+import { useMergedLocals } from '../../hooks/use-merged-locals';
 
 interface IncludeProps {
   rawArgs: string;
@@ -12,14 +13,13 @@ interface IncludeProps {
 
 export function Include({ rawArgs, className, id }: IncludeProps) {
   const storyData = useStoryStore((s) => s.storyData);
-  const variables = useStoryStore((s) => s.variables);
-  const temporary = useStoryStore((s) => s.temporary);
+  const [variables, temporary, locals] = useMergedLocals();
 
   if (!storyData) return null;
 
   let passageName: string;
   try {
-    const result = evaluate(rawArgs, variables, temporary);
+    const result = evaluate(rawArgs, variables, temporary, locals);
     passageName = String(result);
   } catch {
     passageName = rawArgs.replace(/^["']|["']$/g, '');

package/src/components/macros/MacroLink.tsx

@@ -1,7 +1,10 @@
+import { useContext } from 'preact/hooks';
 import { useStoryStore } from '../../store';
 import { execute } from '../../expression';
 import type { ASTNode } from '../../markup/ast';
 import { deepClone } from '../../class-registry';
+import { LocalsContext } from '../../markup/render';
+import { useMergedLocals } from '../../hooks/use-merged-locals';
 
 interface MacroLinkProps {
   rawArgs: string;
@@ -37,23 +40,28 @@ import { useAction } from '../../hooks/use-action';
 /**
  * Execute the children imperatively: walk AST for {set} and {do} macros.
  */
-function executeChildren(children: ASTNode[]) {
+function executeChildren(
+  children: ASTNode[],
+  mergedLocals: Record<string, unknown>,
+  scopeUpdate: (key: string, value: unknown) => void,
+) {
   const state = useStoryStore.getState();
   const vars = deepClone(state.variables);
   const temps = deepClone(state.temporary);
+  const localsClone = { ...mergedLocals };
 
   for (const node of children) {
     if (node.type !== 'macro') continue;
     if (node.name === 'set') {
       try {
-        execute(node.rawArgs, vars, temps);
+        execute(node.rawArgs, vars, temps, localsClone);
       } catch (err) {
         console.error(`spindle: Error in {link} child {set}:`, err);
       }
     } else if (node.name === 'do') {
       const code = collectText(node.children);
       try {
-        execute(code, vars, temps);
+        execute(code, vars, temps, localsClone);
       } catch (err) {
         console.error(`spindle: Error in {link} child {do}:`, err);
       }
@@ -71,6 +79,11 @@ function executeChildren(children: ASTNode[]) {
       state.setTemporary(key, temps[key]);
     }
   }
+  for (const key of Object.keys(localsClone)) {
+    if (localsClone[key] !== mergedLocals[key]) {
+      scopeUpdate(`@${key}`, localsClone[key]);
+    }
+  }
 }
 
 export function MacroLink({
@@ -80,10 +93,12 @@ export function MacroLink({
   id,
 }: MacroLinkProps) {
   const { display, passage } = parseArgs(rawArgs);
+  const scope = useContext(LocalsContext);
+  const [, , mergedLocals] = useMergedLocals();
 
   const handleClick = (e: Event) => {
     e.preventDefault();
-    executeChildren(children);
+    executeChildren(children, mergedLocals, scope.update);
     if (passage) {
       useStoryStore.getState().navigate(passage);
     }
@@ -96,7 +111,7 @@ export function MacroLink({
     label: display,
     target: passage ?? undefined,
     perform: () => {
-      executeChildren(children);
+      executeChildren(children, mergedLocals, scope.update);
       if (passage) {
         useStoryStore.getState().navigate(passage);
       }

package/src/components/macros/Meter.tsx

@@ -83,12 +83,16 @@ function formatLabel(
 }
 
 export function Meter({ rawArgs, className, id }: MeterProps) {
-  const [mergedVars, mergedTemps] = useMergedLocals();
+  const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
 
   try {
     const { currentExpr, maxExpr, labelMode } = parseArgs(rawArgs);
-    const current = Number(evaluate(currentExpr, mergedVars, mergedTemps));
-    const max = Number(evaluate(maxExpr, mergedVars, mergedTemps));
+    const current = Number(
+      evaluate(currentExpr, mergedVars, mergedTemps, mergedLocals),
+    );
+    const max = Number(
+      evaluate(maxExpr, mergedVars, mergedTemps, mergedLocals),
+    );
     const pct =
       max === 0 ? 0 : Math.max(0, Math.min(100, (current / max) * 100));
     const label = formatLabel(current, max, labelMode);

package/src/components/macros/Print.tsx

@@ -8,10 +8,10 @@ interface PrintProps {
 }
 
 export function Print({ rawArgs, className, id }: PrintProps) {
-  const [mergedVars, mergedTemps] = useMergedLocals();
+  const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
 
   try {
-    const result = evaluate(rawArgs, mergedVars, mergedTemps);
+    const result = evaluate(rawArgs, mergedVars, mergedTemps, mergedLocals);
     const display = result == null ? '' : String(result);
     if (className || id)
       return (

package/src/components/macros/Set.tsx

@@ -1,26 +1,32 @@
-import { useLayoutEffect } from 'preact/hooks';
+import { useLayoutEffect, useContext } from 'preact/hooks';
 import { useStoryStore } from '../../store';
 import { execute } from '../../expression';
 import { deepClone } from '../../class-registry';
+import { LocalsContext } from '../../markup/render';
+import { useMergedLocals } from '../../hooks/use-merged-locals';
 
 interface SetProps {
   rawArgs: string;
 }
 
 export function Set({ rawArgs }: SetProps) {
+  const scope = useContext(LocalsContext);
+  const [, , mergedLocals] = useMergedLocals();
+
   useLayoutEffect(() => {
     const state = useStoryStore.getState();
     const vars = deepClone(state.variables);
     const temps = deepClone(state.temporary);
+    const localsClone = { ...mergedLocals };
 
     try {
-      execute(rawArgs, vars, temps);
+      execute(rawArgs, vars, temps, localsClone);
     } catch (err) {
       console.error(`spindle: Error in {set ${rawArgs}}:`, err);
       return;
     }
 
-    // Diff and apply changes
+    // Diff and apply store changes
     for (const key of Object.keys(vars)) {
       if (vars[key] !== state.variables[key]) {
         state.setVariable(key, vars[key]);
@@ -31,6 +37,13 @@ export function Set({ rawArgs }: SetProps) {
         state.setTemporary(key, temps[key]);
       }
     }
+
+    // Diff and apply locals changes
+    for (const key of Object.keys(localsClone)) {
+      if (localsClone[key] !== mergedLocals[key]) {
+        scope.update(`@${key}`, localsClone[key]);
+      }
+    }
   }, []);
 
   return null;

package/src/components/macros/Switch.tsx

@@ -9,11 +9,11 @@ interface SwitchProps {
 }
 
 export function Switch({ rawArgs, branches }: SwitchProps) {
-  const [mergedVars, mergedTemps] = useMergedLocals();
+  const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
 
   let switchValue: unknown;
   try {
-    switchValue = evaluate(rawArgs, mergedVars, mergedTemps);
+    switchValue = evaluate(rawArgs, mergedVars, mergedTemps, mergedLocals);
   } catch (err) {
     return (
       <span
@@ -26,8 +26,10 @@ export function Switch({ rawArgs, branches }: SwitchProps) {
   }
 
   // Find matching {case} branch or {default}
+  // Skip first branch (index 0) — it holds the switch expression, not a case
   let defaultBranch: Branch | null = null;
-  for (const branch of branches) {
+  for (let i = 1; i < branches.length; i++) {
+    const branch = branches[i]!;
     // {default} has empty rawArgs
     if (branch.rawArgs === '') {
       defaultBranch = branch;
@@ -35,7 +37,12 @@ export function Switch({ rawArgs, branches }: SwitchProps) {
     }
 
     try {
-      const caseValue = evaluate(branch.rawArgs, mergedVars, mergedTemps);
+      const caseValue = evaluate(
+        branch.rawArgs,
+        mergedVars,
+        mergedTemps,
+        mergedLocals,
+      );
       if (switchValue === caseValue) {
         return <>{renderNodes(branch.children)}</>;
       }

package/src/components/macros/VarDisplay.tsx

@@ -4,22 +4,30 @@ import { LocalsContext } from '../../markup/render';
 
 interface VarDisplayProps {
   name: string;
-  scope: 'variable' | 'temporary';
+  scope: 'variable' | 'temporary' | 'local';
   className?: string;
   id?: string;
 }
 
 export function VarDisplay({ name, scope, className, id }: VarDisplayProps) {
-  const locals = useContext(LocalsContext);
+  const localsScope = useContext(LocalsContext);
   const parts = name.split('.');
   const root = parts[0]!;
   const storeValue = useStoryStore((s) =>
-    scope === 'variable' ? s.variables[root] : s.temporary[root],
+    scope === 'variable'
+      ? s.variables[root]
+      : scope === 'temporary'
+        ? s.temporary[root]
+        : undefined,
   );
 
-  // Locals (from for-loops) override store values
-  const key = scope === 'variable' ? `$${root}` : `_${root}`;
-  let value = key in locals ? locals[key] : storeValue;
+  let value: unknown;
+  if (scope === 'local') {
+    const key = `@${root}`;
+    value = key in localsScope.values ? localsScope.values[key] : undefined;
+  } else {
+    value = storeValue;
+  }
 
   // Resolve dot path (e.g. "character.name" → character['name'])
   for (let i = 1; i < parts.length; i++) {

package/src/components/macros/Widget.tsx

@@ -13,9 +13,7 @@ interface WidgetProps {
 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('$') || t.startsWith('_'));
+  const params = tokens.slice(1).filter((t) => t.startsWith('@'));
   return { name, params };
 }
 

package/src/components/macros/WidgetInvocation.tsx

@@ -1,5 +1,6 @@
-import { useContext } from 'preact/hooks';
+import { useContext, useState, useCallback } from 'preact/hooks';
 import { LocalsContext, renderNodes } from '../../markup/render';
+import type { LocalsScope } from '../../markup/render';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
 import { evaluate } from '../../expression';
 import type { ASTNode } from '../../markup/ast';
@@ -60,20 +61,47 @@ function splitArgs(raw: string): string[] {
   return args;
 }
 
+function WidgetBody({
+  body,
+  parentValues,
+  ownKeys,
+}: {
+  body: ASTNode[];
+  parentValues: Record<string, unknown>;
+  ownKeys: Record<string, unknown>;
+}) {
+  const [localState, setLocalState] = useState<Record<string, unknown>>(() => ({
+    ...parentValues,
+    ...ownKeys,
+  }));
+
+  const update = useCallback((key: string, value: unknown) => {
+    setLocalState((prev) => ({ ...prev, [key]: value }));
+  }, []);
+
+  const scope: LocalsScope = { values: localState, update };
+
+  return (
+    <LocalsContext.Provider value={scope}>
+      {renderNodes(body)}
+    </LocalsContext.Provider>
+  );
+}
+
 export function WidgetInvocation({
   body,
   params,
   rawArgs,
 }: WidgetInvocationProps) {
-  const parentLocals = useContext(LocalsContext);
-  const [mergedVars, mergedTemps] = useMergedLocals();
+  const parentScope = useContext(LocalsContext);
+  const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
 
   if (params.length === 0 || !rawArgs) {
     return <>{renderNodes(body)}</>;
   }
 
   const argExprs = splitArgs(rawArgs);
-  const locals: Record<string, unknown> = { ...parentLocals };
+  const ownKeys: Record<string, unknown> = {};
 
   for (let i = 0; i < params.length; i++) {
     const param = params[i]!;
@@ -81,17 +109,19 @@ export function WidgetInvocation({
     let value: unknown;
     if (expr !== undefined) {
       try {
-        value = evaluate(expr, mergedVars, mergedTemps);
+        value = evaluate(expr, mergedVars, mergedTemps, mergedLocals);
       } catch {
         value = undefined;
       }
     }
-    locals[param] = value;
+    ownKeys[param] = value;
   }
 
   return (
-    <LocalsContext.Provider value={locals}>
-      {renderNodes(body)}
-    </LocalsContext.Provider>
+    <WidgetBody
+      body={body}
+      parentValues={parentScope.values}
+      ownKeys={ownKeys}
+    />
   );
 }