@rohal12/spindle 0.41.0 → 0.43.0

package/package.json

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

package/src/components/macros/Computed.tsx

@@ -61,11 +61,12 @@ function computeAndApply(
   variables: Record<string, unknown>,
   temporary: Record<string, unknown>,
   locals: Record<string, unknown>,
+  transient: Record<string, unknown>,
   rawArgs: string,
 ): 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()}:`,
@@ -86,7 +87,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;
@@ -113,6 +114,7 @@ defineMacro({
         mergedVars,
         mergedTemps,
         mergedLocals,
+        mergedTrans,
         rawArgs,
       );
     }
@@ -125,9 +127,10 @@ defineMacro({
         mergedVars,
         mergedTemps,
         mergedLocals,
+        mergedTrans,
         rawArgs,
       );
-    }, [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/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)
@@ -218,7 +219,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;
 
@@ -239,7 +241,13 @@ export function WidgetInvocation({
     let value: unknown;
     if (expr !== undefined) {
       try {
-        value = evaluate(expr, mergedVars, mergedTemps, mergedLocals);
+        value = evaluate(
+          expr,
+          mergedVars,
+          mergedTemps,
+          mergedLocals,
+          mergedTrans,
+        );
       } catch {
         value = undefined;
       }

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++) {

package/src/markup/tokenizer.ts

@@ -29,7 +29,7 @@ export interface MacroToken {
 export interface VariableToken {
   type: 'variable';
   name: string;
-  scope: 'variable' | 'temporary' | 'local';
+  scope: 'variable' | 'temporary' | 'local' | 'transient';
   className?: string;
   id?: string;
   start: number;
@@ -499,6 +499,51 @@ export function tokenize(input: string): Token[] {
           continue;
         }
 
+        if (charAfter === '%') {
+          // {.class#id %transient.field} or {.class %expr[...]}
+          i = afterSelectors + 1;
+          const nameStart = i;
+          while (i < input.length && /[\w.]/.test(input[i]!)) i++;
+          const name = input.slice(nameStart, i);
+
+          if (input[i] === '}') {
+            i++; // skip }
+            const token: VariableToken = {
+              type: 'variable',
+              name,
+              scope: 'transient',
+              start,
+              end: i,
+            };
+            if (className) token.className = className;
+            if (id) token.id = id;
+            tokens.push(token);
+            textStart = i;
+            continue;
+          }
+          // Complex expression — scan for balanced closing }
+          const closeIdx_pct = scanBalancedBrace(input, nameStart);
+          if (closeIdx_pct !== -1) {
+            const expression = input.slice(afterSelectors, closeIdx_pct);
+            i = closeIdx_pct + 1;
+            const token: ExpressionToken = {
+              type: 'expression',
+              expression,
+              start,
+              end: i,
+            };
+            if (className) token.className = className;
+            if (id) token.id = id;
+            tokens.push(token);
+            textStart = i;
+            continue;
+          }
+          // Unbalanced — treat as text
+          i = start + 1;
+          textStart = start;
+          continue;
+        }
+
         if (charAfter !== undefined && /[a-zA-Z]/.test(charAfter)) {
           // {.class#id macroName args}
           i = afterSelectors;
@@ -663,6 +708,46 @@ export function tokenize(input: string): Token[] {
         continue;
       }
 
+      // {%transient.field} or {%expr[...]}
+      if (nextChar === '%') {
+        flushText(i);
+        i += 2;
+        const nameStart = i;
+        while (i < input.length && /[\w.]/.test(input[i]!)) i++;
+        const name = input.slice(nameStart, i);
+
+        if (input[i] === '}') {
+          i++; // skip }
+          tokens.push({
+            type: 'variable',
+            name,
+            scope: 'transient',
+            start,
+            end: i,
+          });
+          textStart = i;
+          continue;
+        }
+        // Complex expression — scan for balanced closing }
+        const closeIdx = scanBalancedBrace(input, nameStart);
+        if (closeIdx !== -1) {
+          const expression = input.slice(start + 1, closeIdx);
+          i = closeIdx + 1;
+          tokens.push({
+            type: 'expression',
+            expression,
+            start,
+            end: i,
+          });
+          textStart = i;
+          continue;
+        }
+        // Unbalanced — treat as text
+        i = start + 1;
+        textStart = start;
+        continue;
+      }
+
       // {macro ...} or {/macro} — but not bare { that's just text
       // Must start with a letter or /
       if (

package/src/store.ts

@@ -42,6 +42,7 @@ const SPECIAL_PASSAGES = new Set([
   'StoryInit',
   'StoryInterface',
   'StoryVariables',
+  'StoryTransients',
   'StoryLoading',
   'SaveTitle',
   'PassageReady',
@@ -237,6 +238,8 @@ export interface StoryState {
   currentPassage: string;
   variables: Record<string, unknown>;
   variableDefaults: Record<string, unknown>;
+  transient: Record<string, unknown>;
+  transientDefaults: Record<string, unknown>;
   temporary: Record<string, unknown>;
   history: HistoryMoment[];
   historyIndex: number;
@@ -256,6 +259,7 @@ export interface StoryState {
   init: (
     storyData: StoryData,
     variableDefaults?: Record<string, unknown>,
+    transientDefaults?: Record<string, unknown>,
   ) => void;
   navigate: (passageName: string) => void;
   goBack: () => void;
@@ -264,6 +268,8 @@ export interface StoryState {
   setTemporary: (name: string, value: unknown) => void;
   deleteVariable: (name: string) => void;
   deleteTemporary: (name: string) => void;
+  setTransient: (name: string, value: unknown) => void;
+  deleteTransient: (name: string) => void;
   trackRender: (passageName: string) => void;
   restart: () => void;
   save: (slot?: string, custom?: Record<string, unknown>) => void;
@@ -291,6 +297,8 @@ export const useStoryStore = create<StoryState>()(
     currentPassage: '',
     variables: {},
     variableDefaults: {},
+    transient: {},
+    transientDefaults: {},
     temporary: {},
     history: [],
     historyIndex: -1,
@@ -315,6 +323,7 @@ export const useStoryStore = create<StoryState>()(
     init: (
       storyData: StoryData,
       variableDefaults: Record<string, unknown> = {},
+      transientDefaults: Record<string, unknown> = {},
     ) => {
       const startPassage = storyData.passagesById.get(storyData.startNode);
       if (!startPassage) {
@@ -331,6 +340,8 @@ export const useStoryStore = create<StoryState>()(
         state.currentPassage = startPassage.name;
         state.variables = initialVars;
         state.variableDefaults = variableDefaults;
+        state.transient = deepClone(transientDefaults);
+        state.transientDefaults = transientDefaults;
         state.temporary = {};
         state.history = [
           {
@@ -516,6 +527,18 @@ export const useStoryStore = create<StoryState>()(
       });
     },
 
+    setTransient: (name: string, value: unknown) => {
+      set((state) => {
+        state.transient[name] = value;
+      });
+    },
+
+    deleteTransient: (name: string) => {
+      set((state) => {
+        delete state.transient[name];
+      });
+    },
+
     trackRender: (passageName: string) => {
       set((state) => {
         state.renderCounts[passageName] =
@@ -524,7 +547,7 @@ export const useStoryStore = create<StoryState>()(
     },
 
     restart: () => {
-      const { storyData, variableDefaults } = get();
+      const { storyData, variableDefaults, transientDefaults } = get();
       if (!storyData) return;
 
       const startPassage = storyData.passagesById.get(storyData.startNode);
@@ -551,6 +574,7 @@ export const useStoryStore = create<StoryState>()(
       set((state) => {
         state.currentPassage = startPassage.name;
         state.variables = initialVars;
+        state.transient = deepClone(transientDefaults);
         state.temporary = {};
         state.history = [
           {
@@ -804,6 +828,7 @@ export const useStoryStore = create<StoryState>()(
         state.visitCounts = payload.visitCounts ?? {};
         state.renderCounts = payload.renderCounts ?? {};
         state.temporary = {};
+        state.transient = deepClone(get().transientDefaults);
       });
 
       lastNavigationVars = get().variables;