@rohal12/spindle 0.42.0 → 0.43.0

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. */