@rohal12/spindle 0.42.0 → 0.43.1

package/package.json

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

package/src/components/macros/Computed.tsx

@@ -61,11 +61,13 @@ function computeAndApply(
   variables: Record<string, unknown>,
   temporary: Record<string, unknown>,
   locals: Record<string, unknown>,
+  transient: Record<string, unknown>,
   rawArgs: string,
+  prevRef: { current: unknown },
 ): void {
   let newValue: unknown;
   try {
-    newValue = evaluate(expr, variables, temporary, locals);
+    newValue = evaluate(expr, variables, temporary, locals, transient);
   } catch (err) {
     console.error(
       `spindle: Error in {computed ${rawArgs}}${currentSourceLocation()}:`,
@@ -74,8 +76,8 @@ function computeAndApply(
     return;
   }
 
-  const current = isTemp ? temporary[name] : variables[name];
-  if (!valuesEqual(current, newValue)) {
+  if (!valuesEqual(prevRef.current, newValue)) {
+    prevRef.current = newValue;
     const state = useStoryStore.getState();
     if (isTemp) state.setTemporary(name, newValue);
     else state.setVariable(name, newValue);
@@ -86,7 +88,7 @@ defineMacro({
   name: 'computed',
   merged: true,
   render({ rawArgs }, ctx) {
-    const [mergedVars, mergedTemps, mergedLocals] = ctx.merged!;
+    const [mergedVars, mergedTemps, mergedLocals, mergedTrans] = ctx.merged!;
 
     let target: string;
     let expr: string;
@@ -103,6 +105,8 @@ defineMacro({
     const isTemp = target.startsWith('_');
     const name = target.slice(1);
 
+    const prevOutput = ctx.hooks.useRef<unknown>(undefined);
+
     const ran = ctx.hooks.useRef(false);
     if (!ran.current) {
       ran.current = true;
@@ -113,7 +117,9 @@ defineMacro({
         mergedVars,
         mergedTemps,
         mergedLocals,
+        mergedTrans,
         rawArgs,
+        prevOutput,
       );
     }
 
@@ -125,9 +131,11 @@ defineMacro({
         mergedVars,
         mergedTemps,
         mergedLocals,
+        mergedTrans,
         rawArgs,
+        prevOutput,
       );
-    }, [mergedVars, mergedTemps, mergedLocals]);
+    }, [mergedVars, mergedTemps, mergedLocals, mergedTrans]);
 
     return null;
   },

package/src/components/macros/ExprDisplay.tsx

@@ -17,10 +17,17 @@ export function ExprDisplay({ expression, className, id }: ExprDisplayProps) {
   const localsValues = useContext(LocalsValuesContext);
   const variables = useStoryStore((s) => s.variables);
   const temporary = useStoryStore((s) => s.temporary);
+  const transient = useStoryStore((s) => s.transient);
 
   let display: string;
   try {
-    const value = evaluate(expression, variables, temporary, localsValues);
+    const value = evaluate(
+      expression,
+      variables,
+      temporary,
+      localsValues,
+      transient,
+    );
     display = value == null ? '' : String(value);
   } catch {
     display = `{error: ${expression}}`;

package/src/components/macros/For.tsx

@@ -53,21 +53,35 @@ function parseForArgs(rawArgs: string): {
 
 function ForIteration({
   parentValues,
-  ownKeys,
-  initialValues,
+  itemVar,
+  itemValue,
+  indexVar,
+  indexValue,
   children,
 }: {
   parentValues: Record<string, unknown>;
-  ownKeys: Record<string, unknown>;
-  initialValues: Record<string, unknown>;
+  itemVar: string;
+  itemValue: unknown;
+  indexVar: string | null;
+  indexValue: number;
   children: ASTNode[];
 }) {
   const [localMutations, setLocalMutations] = useState<Record<string, unknown>>(
-    () => ({ ...initialValues }),
+    () => ({}),
   );
 
-  // Recomputed every render — picks up new parentValues/ownKeys from parent
-  const localState = { ...parentValues, ...ownKeys, ...localMutations };
+  const ownKeys = useMemo(
+    () => ({
+      [itemVar]: itemValue,
+      ...(indexVar ? { [indexVar]: indexValue } : undefined),
+    }),
+    [itemVar, itemValue, indexVar, indexValue],
+  );
+
+  const localState = useMemo(
+    () => ({ ...parentValues, ...ownKeys, ...localMutations }),
+    [parentValues, ownKeys, localMutations],
+  );
 
   const valuesRef = useRef(localState);
   valuesRef.current = localState;
@@ -131,22 +145,17 @@ defineMacro({
       );
     }
 
-    const content = list.map((item, i) => {
-      const ownKeys: Record<string, unknown> = {
-        [itemVar]: item,
-        ...(indexVar ? { [indexVar]: i } : undefined),
-      };
-
-      return (
-        <ForIteration
-          key={`${i}-${JSON.stringify(item)}`}
-          parentValues={parentValues}
-          ownKeys={ownKeys}
-          initialValues={{}}
-          children={children}
-        />
-      );
-    });
+    const content = list.map((item, i) => (
+      <ForIteration
+        key={`${i}-${JSON.stringify(item)}`}
+        parentValues={parentValues}
+        itemVar={itemVar}
+        itemValue={item}
+        indexVar={indexVar}
+        indexValue={i}
+        children={children}
+      />
+    ));
 
     return ctx.wrap(content);
   },

package/src/components/macros/Unset.tsx

@@ -15,11 +15,13 @@ defineMacro({
         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 {
         console.error(
-          `spindle: {unset} expects a variable ($name, _name, or @name), got "${name}"`,
+          `spindle: {unset} expects a variable ($name, _name, %name, or @name), got "${name}"`,
         );
       }
     }

package/src/components/macros/VarDisplay.tsx

@@ -5,7 +5,7 @@ import { useInterpolate } from '../../hooks/use-interpolate';
 
 interface VarDisplayProps {
   name: string;
-  scope: 'variable' | 'temporary' | 'local';
+  scope: 'variable' | 'temporary' | 'local' | 'transient';
   className?: string;
   id?: string;
 }
@@ -22,7 +22,9 @@ export function VarDisplay({ name, scope, className, id }: VarDisplayProps) {
       ? s.variables[root]
       : scope === 'temporary'
         ? s.temporary[root]
-        : undefined,
+        : scope === 'transient'
+          ? s.transient[root]
+          : undefined,
   );
 
   let value: unknown;

package/src/components/macros/WidgetInvocation.tsx

@@ -32,7 +32,8 @@ function isStandaloneValue(token: string): boolean {
   // Quoted string
   if (first === '"' || first === "'" || first === '`') return true;
   // Variable ($var, _var, @var)
-  if (first === '$' || first === '_' || first === '@') return true;
+  if (first === '$' || first === '_' || first === '@' || first === '%')
+    return true;
   // Number literal
   if (/\d/.test(first)) return true;
   // Signed number (-1, +2)
@@ -189,8 +190,10 @@ function WidgetBody({
     {},
   );
 
-  // Recomputed every render — picks up new ownKeys from parent
-  const localState = { ...parentValues, ...ownKeys, ...localMutations };
+  const localState = useMemo(
+    () => ({ ...parentValues, ...ownKeys, ...localMutations }),
+    [parentValues, ownKeys, localMutations],
+  );
 
   const valuesRef = useRef(localState);
   valuesRef.current = localState;
@@ -218,7 +221,8 @@ export function WidgetInvocation({
 }: WidgetInvocationProps) {
   const parentValues = useContext(LocalsValuesContext);
   const nobr = useContext(NobrContext);
-  const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
+  const [mergedVars, mergedTemps, mergedLocals, mergedTrans] =
+    useMergedLocals();
 
   const childrenValue = invocationChildren?.length ? invocationChildren : null;
 
@@ -231,22 +235,38 @@ export function WidgetInvocation({
   }
 
   const argExprs = splitArgs(rawArgs);
-  const ownKeys: Record<string, unknown> = {};
+  const values: unknown[] = [];
 
   for (let i = 0; i < params.length; i++) {
-    const param = params[i]!;
     const expr = argExprs[i];
     let value: unknown;
     if (expr !== undefined) {
       try {
-        value = evaluate(expr, mergedVars, mergedTemps, mergedLocals);
+        value = evaluate(
+          expr,
+          mergedVars,
+          mergedTemps,
+          mergedLocals,
+          mergedTrans,
+        );
       } catch {
         value = undefined;
       }
     }
-    ownKeys[param.startsWith('@') ? param.slice(1) : param] = value;
+    values.push(value);
   }
 
+  const ownKeys = useMemo(() => {
+    const keys: Record<string, unknown> = {};
+    for (let i = 0; i < params.length; i++) {
+      keys[params[i]!.startsWith('@') ? params[i]!.slice(1) : params[i]!] =
+        values[i];
+    }
+    return keys;
+    // params is stable per widget instance; values tracks evaluated args
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, values);
+
   return (
     <WidgetChildrenContext.Provider value={childrenValue}>
       <WidgetBody

package/src/define-macro.ts

@@ -52,6 +52,7 @@ export interface MacroContext {
     Record<string, unknown>,
     Record<string, unknown>,
     Record<string, unknown>,
+    Record<string, unknown>,
   ];
   varName?: string;
   value?: unknown;
@@ -178,12 +179,21 @@ export function defineMacro(
       ctx.merged = useMergedLocals();
       const merged = ctx.merged;
       ctx.evaluate = (expr: string) =>
-        evaluate(expr, merged[0], merged[1], merged[2]);
+        evaluate(expr, merged[0], merged[1], merged[2], merged[3]);
     }
 
     if (config.storeVar) {
       const firstToken =
         props.rawArgs.trim().split(/\s+/)[0]?.replace(/["']/g, '') ?? '';
+
+      if (firstToken.startsWith('%')) {
+        return h(
+          'span',
+          { class: 'error' },
+          `{${config.name}}: transient variables (%${firstToken.slice(1)}) cannot be bound to input macros`,
+        );
+      }
+
       const varExpr = firstToken.replace(/["']/g, '').replace(/^\$/, '');
       const segments = varExpr.split('.');
       ctx.varName = varExpr;

package/src/execute-mutation.ts

@@ -10,9 +10,10 @@ export function executeMutation(
   const state = useStoryStore.getState();
   const vars = deepClone(state.variables);
   const temps = deepClone(state.temporary);
+  const trans = deepClone(state.transient);
   const localsClone = { ...mergedLocals };
 
-  execute(code, vars, temps, localsClone);
+  execute(code, vars, temps, localsClone, trans);
 
   for (const key of Object.keys(vars)) {
     if (vars[key] !== state.variables[key]) {
@@ -24,6 +25,11 @@ export function executeMutation(
       state.setTemporary(key, temps[key]);
     }
   }
+  for (const key of Object.keys(trans)) {
+    if (trans[key] !== state.transient[key]) {
+      state.setTransient(key, trans[key]);
+    }
+  }
   for (const key of Object.keys(localsClone)) {
     if (localsClone[key] !== mergedLocals[key]) {
       scopeUpdate(key, localsClone[key]);
@@ -41,6 +47,11 @@ export function executeMutation(
       state.deleteTemporary(key);
     }
   }
+  for (const key of Object.keys(state.transient)) {
+    if (!(key in trans)) {
+      state.deleteTransient(key);
+    }
+  }
   for (const key of Object.keys(mergedLocals)) {
     if (!(key in localsClone)) {
       scopeUpdate(key, undefined);

package/src/expression.ts

@@ -23,30 +23,34 @@ type CompiledExpression = (
   temporary: Record<string, unknown>,
   locals: Record<string, unknown>,
   __fns: ExpressionFns,
+  transient: Record<string, unknown>,
 ) => unknown;
 
 const FN_CACHE_MAX = 500;
 const fnCache = new Map<string, CompiledExpression>();
 
 /**
- * Transform expression: $var → variables["var"], _var → temporary["var"]
- * Only transforms when $ or _ appears as a word boundary (not inside strings naively,
+ * Transform expression: $var → variables["var"], _var → temporary["var"],
+ * @var → locals["var"], %var → transient["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).
  */
 const VAR_RE = /\$(\w+)/g;
 const TEMP_RE = /(?<![.\w])_(\w+)/g;
 const LOCAL_RE = /@(\w+)/g;
+const TRANS_RE = /(?<!\w)%(\w+)/g;
 
 function transformSegment(segment: string): string {
   return segment
     .replace(VAR_RE, 'variables["$1"]')
     .replace(TEMP_RE, 'temporary["$1"]')
-    .replace(LOCAL_RE, 'locals["$1"]');
+    .replace(LOCAL_RE, 'locals["$1"]')
+    .replace(TRANS_RE, 'transient["$1"]');
 }
 
 /**
  * String-aware expression transformer. Walks the expression character by
- * character so that variable sigils ($, _, @) inside string literals are
+ * character so that variable sigils ($, _, @, %) inside string literals are
  * left untouched while code — including expressions inside template-literal
  * `${…}` interpolations — is transformed.
  */
@@ -215,6 +219,7 @@ function getOrCompile(key: string, body: string): CompiledExpression {
     'temporary',
     'locals',
     '__fns',
+    'transient',
     preamble + body,
   ) as CompiledExpression;
   fnCache.set(key, fn);
@@ -298,11 +303,12 @@ export function evaluate(
   variables: Record<string, unknown>,
   temporary: Record<string, unknown>,
   locals: Record<string, unknown> = {},
+  transient: Record<string, unknown> = {},
 ): unknown {
   const transformed = transform(expr);
   const body = `return (${transformed});`;
   const fn = getOrCompile(body, body);
-  return fn(variables, temporary, locals, buildExpressionFns());
+  return fn(variables, temporary, locals, buildExpressionFns(), transient);
 }
 
 /**
@@ -314,10 +320,11 @@ export function execute(
   variables: Record<string, unknown>,
   temporary: Record<string, unknown>,
   locals: Record<string, unknown> = {},
+  transient: Record<string, unknown> = {},
 ): void {
   const transformed = transform(code);
   const fn = getOrCompile('exec:' + transformed, transformed);
-  fn(variables, temporary, locals, buildExpressionFns());
+  fn(variables, temporary, locals, buildExpressionFns(), transient);
 }
 
 /**
@@ -332,5 +339,5 @@ export function clearExpressionCache(): void {
 }
 
 export function evaluateWithState(expr: string, state: StoryState): unknown {
-  return evaluate(expr, state.variables, state.temporary, {});
+  return evaluate(expr, state.variables, state.temporary, {}, state.transient);
 }

package/src/hooks/use-interpolate.ts

@@ -5,13 +5,13 @@ import { hasInterpolation, interpolate } from '../interpolation';
 export function useInterpolate(): (
   s: string | undefined,
 ) => string | undefined {
-  const [variables, temporary, locals] = useMergedLocals();
+  const [variables, temporary, locals, transient] = useMergedLocals();
 
   return useCallback(
     (s: string | undefined): string | undefined => {
       if (s === undefined || !hasInterpolation(s)) return s;
-      return interpolate(s, variables, temporary, locals);
+      return interpolate(s, variables, temporary, locals, transient);
     },
-    [variables, temporary, locals],
+    [variables, temporary, locals, transient],
   );
 }

package/src/hooks/use-merged-locals.ts

@@ -3,19 +3,21 @@ import { useStoryStore } from '../store';
 import { LocalsValuesContext } from '../markup/render';
 
 /**
- * Return store variables, temporary, and locals from context.
- * All three dicts use unprefixed keys suitable for evaluate/execute.
+ * Return store variables, temporary, locals from context, and transient.
+ * All four dicts use unprefixed keys suitable for evaluate/execute.
  */
 export function useMergedLocals(): readonly [
   Record<string, unknown>,
   Record<string, unknown>,
   Record<string, unknown>,
+  Record<string, unknown>,
 ] {
   const variables = useStoryStore((s) => s.variables);
   const temporary = useStoryStore((s) => s.temporary);
+  const transient = useStoryStore((s) => s.transient);
   const localsValues = useContext(LocalsValuesContext);
 
   return useMemo(() => {
-    return [variables, temporary, localsValues] as const;
-  }, [variables, temporary, localsValues]);
+    return [variables, temporary, localsValues, transient] as const;
+  }, [variables, temporary, localsValues, transient]);
 }

package/src/index.tsx

@@ -88,6 +88,27 @@ function boot() {
   const schema = parseStoryVariables(storyVarsPassage.content);
   const errors = validatePassages(storyData.passages, schema);
 
+  // Parse StoryTransients (optional — no error if missing)
+  let transientDefaults: Record<string, unknown> = {};
+  const storyTransientsPassage = storyData.passages.get('StoryTransients');
+  if (storyTransientsPassage) {
+    const transientSchema = parseStoryVariables(
+      storyTransientsPassage.content,
+      '%',
+    );
+
+    // Check for cross-scope name collisions
+    for (const name of transientSchema.keys()) {
+      if (schema.has(name)) {
+        errors.push(
+          `StoryTransients: Variable "${name}" is already declared in StoryVariables. Names must be unique across scopes.`,
+        );
+      }
+    }
+
+    transientDefaults = extractDefaults(transientSchema);
+  }
+
   if (errors.length > 0) {
     const root = document.getElementById('root');
     if (root) renderErrors(root, errors);
@@ -98,7 +119,7 @@ function boot() {
 
   defaults = extractDefaults(schema);
 
-  useStoryStore.getState().init(storyData, defaults);
+  useStoryStore.getState().init(storyData, defaults, transientDefaults);
 
   // Enter runtime phase — handlers registered from here on are cleaned on restart
   enterRuntimePhase();

package/src/interpolation.ts

@@ -1,7 +1,7 @@
 import { evaluate } from './expression';
 
-/** Detects any {…} block that starts with a sigil ($, _, @). */
-const INTERP_TEST = /\{[\$_@]\w/;
+/** Detects any {…} block that starts with a sigil ($, _, @, %). */
+const INTERP_TEST = /\{[\$_@%]\w/;
 
 export function hasInterpolation(s: string): boolean {
   return INTERP_TEST.test(s);
@@ -25,8 +25,9 @@ export function interpolateExpression(
   variables: Record<string, unknown>,
   temporary: Record<string, unknown>,
   locals: Record<string, unknown>,
+  transient: Record<string, unknown> = {},
 ): string {
-  const value = evaluate(expr, variables, temporary, locals);
+  const value = evaluate(expr, variables, temporary, locals, transient);
   return value == null ? '' : String(value);
 }
 
@@ -35,6 +36,7 @@ function resolveSimple(
   variables: Record<string, unknown>,
   temporary: Record<string, unknown>,
   locals: Record<string, unknown>,
+  transient: Record<string, unknown>,
 ): string {
   const prefix = ref[0]!;
   const path = ref.slice(1);
@@ -46,6 +48,8 @@ function resolveSimple(
     value = variables[root];
   } else if (prefix === '_') {
     value = temporary[root];
+  } else if (prefix === '%') {
+    value = transient[root];
   } else {
     value = locals[root];
   }
@@ -62,6 +66,7 @@ export function interpolate(
   variables: Record<string, unknown>,
   temporary: Record<string, unknown>,
   locals: Record<string, unknown>,
+  transient: Record<string, unknown> = {},
 ): string {
   // Manual scan: process {…} blocks containing sigils.
   // Simple dot-path refs use the fast resolver; everything else falls back
@@ -86,7 +91,7 @@ export function interpolate(
     i++; // skip {
 
     const sigil = template[i];
-    if (sigil !== '$' && sigil !== '_' && sigil !== '@') {
+    if (sigil !== '$' && sigil !== '_' && sigil !== '@' && sigil !== '%') {
       // Not an interpolation — emit the { as text
       result += '{';
       continue;
@@ -111,10 +116,16 @@ export function interpolate(
     i = j + 1; // skip past closing }
 
     // Try simple dot-path match first
-    if (/^[\$_@][\w.]+$/.test(inner)) {
-      result += resolveSimple(inner, variables, temporary, locals);
+    if (/^[\$_@%][\w.]+$/.test(inner)) {
+      result += resolveSimple(inner, variables, temporary, locals, transient);
     } else {
-      result += interpolateExpression(inner, variables, temporary, locals);
+      result += interpolateExpression(
+        inner,
+        variables,
+        temporary,
+        locals,
+        transient,
+      );
     }
   }
 

package/src/markup/ast.ts

@@ -8,7 +8,7 @@ export interface TextNode {
 export interface VariableNode {
   type: 'variable';
   name: string;
-  scope: 'variable' | 'temporary' | 'local';
+  scope: 'variable' | 'temporary' | 'local' | 'transient';
   className?: string;
   id?: string;
 }

package/src/markup/render.tsx

@@ -243,6 +243,7 @@ function getVariableTextValue(
   let value: unknown;
   if (node.scope === 'variable') value = state.variables[root];
   else if (node.scope === 'temporary') value = state.temporary[root];
+  else if (node.scope === 'transient') value = state.transient[root];
   else value = locals[root];
 
   for (let i = 1; i < parts.length; i++) {