@rohal12/spindle 0.42.0 → 0.43.1

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;

package/src/story-api.ts

@@ -76,20 +76,37 @@ function ensureVariableChangedSubscription(): void {
   if (variableChangedSubActive) return;
   variableChangedSubActive = true;
   let prevVars = { ...useStoryStore.getState().variables };
+  let prevTrans = { ...useStoryStore.getState().transient };
   useStoryStore.subscribe((state) => {
     const changed: Record<string, { from: unknown; to: unknown }> = {};
     let hasChanges = false;
-    const allKeys = new Set([
+
+    // Check $variables
+    const allVarKeys = new Set([
       ...Object.keys(prevVars),
       ...Object.keys(state.variables),
     ]);
-    for (const key of allKeys) {
+    for (const key of allVarKeys) {
       if (state.variables[key] !== prevVars[key]) {
         changed[key] = { from: prevVars[key], to: state.variables[key] };
         hasChanges = true;
       }
     }
+
+    // Check %transient
+    const allTransKeys = new Set([
+      ...Object.keys(prevTrans),
+      ...Object.keys(state.transient),
+    ]);
+    for (const key of allTransKeys) {
+      if (state.transient[key] !== prevTrans[key]) {
+        changed[`%${key}`] = { from: prevTrans[key], to: state.transient[key] };
+        hasChanges = true;
+      }
+    }
+
     prevVars = { ...state.variables };
+    prevTrans = { ...state.transient };
     if (hasChanges) {
       emit('variableChanged', changed);
     }
@@ -178,16 +195,27 @@ export interface StoryAPI {
 function createStoryAPI(): StoryAPI {
   return {
     get(name: string): unknown {
+      if (name.startsWith('%')) {
+        return useStoryStore.getState().transient[name.slice(1)];
+      }
       return useStoryStore.getState().variables[name];
     },
 
     set(nameOrVars: string | Record<string, unknown>, value?: unknown): void {
       const state = useStoryStore.getState();
       if (typeof nameOrVars === 'string') {
-        state.setVariable(nameOrVars, value);
+        if (nameOrVars.startsWith('%')) {
+          state.setTransient(nameOrVars.slice(1), value);
+        } else {
+          state.setVariable(nameOrVars, value);
+        }
       } else {
         for (const [k, v] of Object.entries(nameOrVars)) {
-          state.setVariable(k, v);
+          if (k.startsWith('%')) {
+            state.setTransient(k.slice(1), v);
+          } else {
+            state.setVariable(k, v);
+          }
         }
       }
     },

package/src/story-variables.ts

@@ -12,7 +12,10 @@ export interface VariableSchema extends FieldSchema {
   default: unknown;
 }
 
-const DECLARATION_RE = /^\$(\w+)\s*=\s*(.+)$/;
+function declarationRegex(sigil: string): RegExp {
+  const escaped = sigil.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`^${escaped}(\\w+)\\s*=\\s*(.+)$`);
+}
 const VAR_REF_RE = /\$(\w+(?:\.\w+)*)/g;
 const FOR_LOCAL_RE = /\{for\s+@(\w+)(?:\s*,\s*@(\w+))?\s+of\b/g;
 
@@ -32,20 +35,23 @@ function inferSchema(value: unknown): FieldSchema {
   const jsType = typeof value;
   if (!VALID_VAR_TYPES.has(jsType)) {
     throw new Error(
-      `StoryVariables: Unsupported type "${jsType}" for value ${String(value)}. Expected number, string, boolean, array, or object.`,
+      `Unsupported type "${jsType}" for value ${String(value)}. Expected number, string, boolean, array, or object.`,
     );
   }
   return { type: jsType as VarType };
 }
 
 /**
- * Parse a StoryVariables passage content into a schema map.
- * Each line: `$varName = expression`
+ * Parse a StoryVariables or StoryTransients passage content into a schema map.
+ * Each line: `$varName = expression` (or `%varName = expression` for transients)
  */
 export function parseStoryVariables(
   content: string,
+  sigil: '$' | '%' = '$',
 ): Map<string, VariableSchema> {
   const schema = new Map<string, VariableSchema>();
+  const DECLARATION_RE = declarationRegex(sigil);
+  const passageName = sigil === '%' ? 'StoryTransients' : 'StoryVariables';
 
   for (const rawLine of content.split('\n')) {
     const line = rawLine.trim();
@@ -54,7 +60,7 @@ export function parseStoryVariables(
     const match = line.match(DECLARATION_RE);
     if (!match) {
       throw new Error(
-        `StoryVariables: Invalid declaration: "${line}". Expected: $name = value`,
+        `${passageName}: Invalid declaration: "${line}". Expected: ${sigil}name = value`,
       );
     }
 
@@ -64,11 +70,18 @@ export function parseStoryVariables(
       value = new Function('return (' + expr + ')')();
     } catch (err) {
       throw new Error(
-        `StoryVariables: Failed to evaluate "$${name} = ${expr}": ${err instanceof Error ? err.message : err}`,
+        `${passageName}: Failed to evaluate "${sigil}${name} = ${expr}": ${err instanceof Error ? err.message : err}`,
       );
     }
 
-    const fieldSchema = inferSchema(value);
+    let fieldSchema: FieldSchema;
+    try {
+      fieldSchema = inferSchema(value);
+    } catch (err) {
+      throw new Error(
+        `${passageName}: ${err instanceof Error ? err.message : err}`,
+      );
+    }
     schema.set(name, { ...fieldSchema, name, default: value });
   }
 
@@ -146,8 +159,8 @@ export function validatePassages(
   const errors: string[] = [];
 
   for (const [name, passage] of passages) {
-    // Don't validate the StoryVariables passage itself
-    if (name === 'StoryVariables') continue;
+    // Don't validate the StoryVariables/StoryTransients passages themselves
+    if (name === 'StoryVariables' || name === 'StoryTransients') continue;
 
     const forLocals = extractForLocals(passage.content);
 

package/src/triggers.ts

@@ -45,7 +45,13 @@ let dialogHostCallbacks: DialogHostCallbacks | null = null;
 function evalCondition(condition: string): boolean {
   const state = useStoryStore.getState();
   try {
-    return !!evaluate(condition, state.variables, state.temporary);
+    return !!evaluate(
+      condition,
+      state.variables,
+      state.temporary,
+      {},
+      state.transient,
+    );
   } catch {
     return false;
   }

package/types/index.d.ts

@@ -294,6 +294,7 @@ export interface MacroContext {
     Record<string, unknown>,
     Record<string, unknown>,
     Record<string, unknown>,
+    Record<string, unknown>,
   ];
   varName?: string;
   value?: unknown;
@@ -364,12 +365,20 @@ export interface SaveInfo {
  * @see {@link ../../src/story-api.ts} for the implementation.
  */
 export interface StoryAPI {
-  /** Get the value of a story variable. */
+  /**
+   * Get a variable value. Use '%name' prefix for transient variables.
+   * @example Story.get('health') // $health
+   * @example Story.get('%npcList') // %npcList (transient)
+   */
   get(name: string): unknown;
 
-  /** Set a single story variable. */
+  /**
+   * Set one or more variables. Use '%name' prefix for transient variables.
+   * @example Story.set('health', 100)
+   * @example Story.set('%npcList', [...])
+   * @example Story.set({ health: 100, '%npcList': [...] })
+   */
   set(name: string, value: unknown): void;
-  /** Set multiple story variables at once. */
   set(vars: Record<string, unknown>): void;
 
   /** Navigate to a passage by name. */