@rohal12/spindle 0.37.1 → 0.38.1

package/package.json

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

package/src/components/macros/ExprDisplay.tsx

@@ -0,0 +1,39 @@
+import { useContext } from 'preact/hooks';
+import { useStoryStore } from '../../store';
+import { evaluate } from '../../expression';
+import { LocalsValuesContext } from '../../markup/render';
+import { useInterpolate } from '../../hooks/use-interpolate';
+
+interface ExprDisplayProps {
+  expression: string;
+  className?: string;
+  id?: string;
+}
+
+export function ExprDisplay({ expression, className, id }: ExprDisplayProps) {
+  const resolve = useInterpolate();
+  className = resolve(className);
+  id = resolve(id);
+  const localsValues = useContext(LocalsValuesContext);
+  const variables = useStoryStore((s) => s.variables);
+  const temporary = useStoryStore((s) => s.temporary);
+
+  let display: string;
+  try {
+    const value = evaluate(expression, variables, temporary, localsValues);
+    display = value == null ? '' : String(value);
+  } catch {
+    display = `{error: ${expression}}`;
+  }
+
+  if (className || id)
+    return (
+      <span
+        id={id}
+        class={className}
+      >
+        {display}
+      </span>
+    );
+  return <>{display}</>;
+}

package/src/components/macros/PassageDisplay.tsx

@@ -71,6 +71,7 @@ defineMacro({
   render(_props, ctx) {
     const currentPassage = useStoryStore((s) => s.currentPassage);
     const storyData = useStoryStore((s) => s.storyData);
+    const renderDeferred = useStoryStore((s) => s.renderDeferred);
 
     // Render-gating: displayedPassage controls which passage is visually shown.
     // The store updates immediately, but the visual swap is deferred by the
@@ -245,12 +246,14 @@ defineMacro({
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [currentPassage]);
 
-    // Resolve the passage to display (or show nothing during outgoing phase)
-    const passage = displayedPassage
-      ? storyData?.passages.get(displayedPassage)
-      : null;
+    // When render is deferred, show StoryLoading passage or nothing
+    const effectivePassage = renderDeferred
+      ? (storyData?.passages.get('StoryLoading') ?? null)
+      : displayedPassage
+        ? storyData?.passages.get(displayedPassage)
+        : null;
 
-    if (!passage && displayedPassage) {
+    if (!effectivePassage && displayedPassage && !renderDeferred) {
       return (
         <div class="error">
           Error: Passage &ldquo;{displayedPassage}&rdquo; not found.
@@ -265,7 +268,7 @@ defineMacro({
         id={ctx.id ?? 'story'}
         class={ctx.className ?? 'story'}
       >
-        {readyPassage && (
+        {!renderDeferred && readyPassage && (
           <div
             key={`ready-${currentPassage}`}
             hidden
@@ -277,11 +280,11 @@ defineMacro({
           class="passage-container"
           ref={containerRef}
         >
-          {passage && (
+          {effectivePassage && (
             <Passage
-              passage={passage}
-              key={displayedPassage}
-              dataTransition={resolvedTypeRef.current}
+              passage={effectivePassage}
+              key={renderDeferred ? 'loading' : displayedPassage}
+              dataTransition={renderDeferred ? 'none' : resolvedTypeRef.current}
             />
           )}
         </div>

package/src/index.tsx

@@ -2,7 +2,7 @@ import { render } from 'preact';
 import { App } from './components/App';
 import { parseStoryData } from './parser';
 import { useStoryStore, fireStoryInit } from './store';
-import { installStoryAPI } from './story-api';
+import { installStoryAPI, getReadyPromise } from './story-api';
 import { resetIdCounters } from './action-registry';
 import { executeStoryInit } from './story-init';
 import { checkTriggers, reinitTriggerState } from './triggers';
@@ -200,7 +200,14 @@ function boot() {
 
   render(<App />, root);
 
-  document.dispatchEvent(new CustomEvent(':storyready'));
+  const pending = getReadyPromise();
+  if (pending) {
+    pending.then(() => {
+      document.dispatchEvent(new CustomEvent(':storyready'));
+    });
+  } else {
+    document.dispatchEvent(new CustomEvent(':storyready'));
+  }
 }
 
 if (document.readyState === 'loading') {

package/src/interpolation.ts

@@ -1,5 +1,7 @@
-const INTERP_RE = /\{(\$[\w.]+|_[\w.]+|@[\w.]+)\}/g;
-const INTERP_TEST = /\{[\$_@][\w.]+\}/;
+import { evaluate } from './expression';
+
+/** Detects any {…} block that starts with a sigil ($, _, @). */
+const INTERP_TEST = /\{[\$_@]\w/;
 
 export function hasInterpolation(s: string): boolean {
   return INTERP_TEST.test(s);
@@ -14,31 +16,107 @@ function resolveDotPath(root: unknown, parts: string[]): unknown {
   return value;
 }
 
+/**
+ * Evaluate an expression string and return its stringified result.
+ * Uses the full expression evaluator from expression.ts.
+ */
+export function interpolateExpression(
+  expr: string,
+  variables: Record<string, unknown>,
+  temporary: Record<string, unknown>,
+  locals: Record<string, unknown>,
+): string {
+  const value = evaluate(expr, variables, temporary, locals);
+  return value == null ? '' : String(value);
+}
+
+function resolveSimple(
+  ref: string,
+  variables: Record<string, unknown>,
+  temporary: Record<string, unknown>,
+  locals: Record<string, unknown>,
+): string {
+  const prefix = ref[0]!;
+  const path = ref.slice(1);
+  const parts = path.split('.');
+  const root = parts[0]!;
+
+  let value: unknown;
+  if (prefix === '$') {
+    value = variables[root];
+  } else if (prefix === '_') {
+    value = temporary[root];
+  } else {
+    value = locals[root];
+  }
+
+  if (parts.length > 1) {
+    value = resolveDotPath(value, parts);
+  }
+
+  return value == null ? '' : String(value);
+}
+
 export function interpolate(
   template: string,
   variables: Record<string, unknown>,
   temporary: Record<string, unknown>,
   locals: Record<string, unknown>,
 ): string {
-  return template.replace(INTERP_RE, (_match, ref: string) => {
-    const prefix = ref[0]!;
-    const path = ref.slice(1);
-    const parts = path.split('.');
-    const root = parts[0]!;
-
-    let value: unknown;
-    if (prefix === '$') {
-      value = variables[root];
-    } else if (prefix === '_') {
-      value = temporary[root];
-    } else {
-      value = locals[root];
+  // Manual scan: process {…} blocks containing sigils.
+  // Simple dot-path refs use the fast resolver; everything else falls back
+  // to the full expression evaluator.
+  let result = '';
+  let i = 0;
+
+  while (i < template.length) {
+    if (template[i] !== '{') {
+      // Accumulate plain text
+      const nextBrace = template.indexOf('{', i);
+      if (nextBrace === -1) {
+        result += template.slice(i);
+        break;
+      }
+      result += template.slice(i, nextBrace);
+      i = nextBrace;
+      continue;
+    }
+
+    // Found { — check if it starts a sigil expression
+    i++; // skip {
+
+    const sigil = template[i];
+    if (sigil !== '$' && sigil !== '_' && sigil !== '@') {
+      // Not an interpolation — emit the { as text
+      result += '{';
+      continue;
     }
 
-    if (parts.length > 1) {
-      value = resolveDotPath(value, parts);
+    // Scan for balanced closing }
+    let depth = 1;
+    let j = i;
+    while (j < template.length && depth > 0) {
+      j++;
+      if (template[j] === '{') depth++;
+      else if (template[j] === '}') depth--;
     }
 
-    return value == null ? '' : String(value);
-  });
+    if (depth !== 0) {
+      // Unbalanced — emit as text
+      result += '{';
+      continue;
+    }
+
+    const inner = template.slice(i, j);
+    i = j + 1; // skip past closing }
+
+    // Try simple dot-path match first
+    if (/^[\$_@][\w.]+$/.test(inner)) {
+      result += resolveSimple(inner, variables, temporary, locals);
+    } else {
+      result += interpolateExpression(inner, variables, temporary, locals);
+    }
+  }
+
+  return result;
 }

package/src/markup/ast.ts

@@ -13,6 +13,13 @@ export interface VariableNode {
   id?: string;
 }
 
+export interface ExpressionNode {
+  type: 'expression';
+  expression: string;
+  className?: string;
+  id?: string;
+}
+
 export interface Branch {
   rawArgs: string;
   className?: string;
@@ -37,7 +44,12 @@ export interface HtmlNode {
   children: ASTNode[];
 }
 
-export type ASTNode = TextNode | VariableNode | MacroNode | HtmlNode;
+export type ASTNode =
+  | TextNode
+  | VariableNode
+  | ExpressionNode
+  | MacroNode
+  | HtmlNode;
 
 /** Macros that require a closing tag and can contain children */
 const BLOCK_MACROS = new Set([
@@ -131,6 +143,17 @@ export function buildAST(tokens: Token[]): ASTNode[] {
         break;
       }
 
+      case 'expression': {
+        const exprNode: ExpressionNode = {
+          type: 'expression',
+          expression: token.expression,
+        };
+        if (token.className) exprNode.className = token.className;
+        if (token.id) exprNode.id = token.id;
+        current().push(exprNode);
+        break;
+      }
+
       case 'html': {
         if (token.isSelfClose) {
           // Self-closing HTML tag (br, hr, img, etc.)

package/src/markup/render.tsx

@@ -1,6 +1,7 @@
 import { createContext } from 'preact';
 import { useContext } from 'preact/hooks';
 import { VarDisplay } from '../components/macros/VarDisplay';
+import { ExprDisplay } from '../components/macros/ExprDisplay';
 import { WidgetInvocation } from '../components/macros/WidgetInvocation';
 import { getWidget } from '../widgets/widget-registry';
 import { getMacro, isSubMacro } from '../registry';
@@ -181,6 +182,16 @@ function renderSingleNode(
         />
       );
 
+    case 'expression':
+      return (
+        <ExprDisplay
+          key={key}
+          expression={node.expression}
+          className={node.className}
+          id={node.id}
+        />
+      );
+
     case 'macro':
       return renderMacro(node, key);
 

package/src/markup/tokenizer.ts

@@ -36,6 +36,15 @@ export interface VariableToken {
   end: number;
 }
 
+export interface ExpressionToken {
+  type: 'expression';
+  expression: string;
+  className?: string;
+  id?: string;
+  start: number;
+  end: number;
+}
+
 export interface HtmlToken {
   type: 'html';
   tag: string;
@@ -51,6 +60,7 @@ export type Token =
   | LinkToken
   | MacroToken
   | VariableToken
+  | ExpressionToken
   | HtmlToken;
 
 /** Tag name must start with a letter (covers standard and custom elements). */
@@ -233,6 +243,20 @@ function parseHtmlAttributes(
   return { attributes, endIdx: j };
 }
 
+/**
+ * Scan for the balanced closing } starting at position i (just past the {).
+ * Returns the index of the closing } or -1 if unbalanced.
+ */
+function scanBalancedBrace(input: string, i: number): number {
+  let depth = 1;
+  while (i < input.length && depth > 0) {
+    if (input[i] === '{') depth++;
+    else if (input[i] === '}') depth--;
+    if (depth > 0) i++;
+  }
+  return depth === 0 ? i : -1;
+}
+
 /**
  * Single-pass tokenizer for Twine passage content.
  * Recognizes: [[links]], {$variable}, {_temporary}, {macroName args}
@@ -341,7 +365,7 @@ export function tokenize(input: string): Token[] {
         const charAfter = input[afterSelectors];
 
         if (charAfter === '$') {
-          // {.class#id $variable.field}
+          // {.class#id $variable.field} or {.class $expr[...]}
           i = afterSelectors + 1;
           const nameStart = i;
           while (i < input.length && /[\w.]/.test(input[i]!)) i++;
@@ -362,14 +386,31 @@ export function tokenize(input: string): Token[] {
             textStart = i;
             continue;
           }
-          // Not valid — treat as text
+          // Complex expression — scan for balanced closing }
+          const closeIdx$ = scanBalancedBrace(input, nameStart);
+          if (closeIdx$ !== -1) {
+            const expression = input.slice(afterSelectors, closeIdx$);
+            i = closeIdx$ + 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 === '_') {
-          // {.class#id _temporary.field}
+          // {.class#id _temporary.field} or {.class _expr[...]}
           i = afterSelectors + 1;
           const nameStart = i;
           while (i < input.length && /[\w.]/.test(input[i]!)) i++;
@@ -390,14 +431,31 @@ export function tokenize(input: string): Token[] {
             textStart = i;
             continue;
           }
-          // Not valid — treat as text
+          // Complex expression — scan for balanced closing }
+          const closeIdx_ = scanBalancedBrace(input, nameStart);
+          if (closeIdx_ !== -1) {
+            const expression = input.slice(afterSelectors, closeIdx_);
+            i = closeIdx_ + 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 === '@') {
-          // {.class#id @local.field}
+          // {.class#id @local.field} or {.class @expr[...]}
           i = afterSelectors + 1;
           const nameStart = i;
           while (i < input.length && /[\w.]/.test(input[i]!)) i++;
@@ -418,7 +476,24 @@ export function tokenize(input: string): Token[] {
             textStart = i;
             continue;
           }
-          // Not valid — treat as text
+          // Complex expression — scan for balanced closing }
+          const closeIdx_at = scanBalancedBrace(input, nameStart);
+          if (closeIdx_at !== -1) {
+            const expression = input.slice(afterSelectors, closeIdx_at);
+            i = closeIdx_at + 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;
@@ -468,7 +543,7 @@ export function tokenize(input: string): Token[] {
         continue;
       }
 
-      // {$variable} or {$variable.field.subfield}
+      // {$variable} or {$variable.field.subfield} or {$expr[...]}
       if (nextChar === '$') {
         flushText(i);
         i += 2;
@@ -488,13 +563,27 @@ export function tokenize(input: string): Token[] {
           textStart = i;
           continue;
         }
-        // Not a valid variable token — treat as text
+        // 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;
       }
 
-      // {_temporary.field}
+      // {_temporary.field} or {_expr[...]}
       if (nextChar === '_') {
         flushText(i);
         i += 2;
@@ -514,13 +603,27 @@ export function tokenize(input: string): Token[] {
           textStart = i;
           continue;
         }
-        // Not a valid temporary token — treat as text
+        // 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;
       }
 
-      // {@local.field}
+      // {@local.field} or {@expr[...]}
       if (nextChar === '@') {
         flushText(i);
         i += 2;
@@ -540,7 +643,21 @@ export function tokenize(input: string): Token[] {
           textStart = i;
           continue;
         }
-        // Not a valid local token — treat as text
+        // 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;

package/src/store.ts

@@ -41,6 +41,7 @@ const SPECIAL_PASSAGES = new Set([
   'StoryInit',
   'StoryInterface',
   'StoryVariables',
+  'StoryLoading',
   'SaveTitle',
   'PassageReady',
   'PassageHeader',
@@ -233,6 +234,7 @@ export interface StoryState {
   transitionConfig: TransitionConfig | null;
   nextTransition: TransitionConfig | null;
   nobr: boolean;
+  renderDeferred: boolean;
 
   setMaxHistory: (limit: number) => void;
   init: (
@@ -263,6 +265,8 @@ export interface StoryState {
   setTransition: (config: TransitionConfig | null) => void;
   setNextTransition: (config: TransitionConfig | null) => void;
   consumeNextTransition: () => TransitionConfig | null;
+  deferRender: () => void;
+  clearDeferredRender: () => void;
 }
 
 export const useStoryStore = create<StoryState>()(
@@ -284,6 +288,7 @@ export const useStoryStore = create<StoryState>()(
     transitionConfig: null,
     nextTransition: null,
     nobr: false,
+    renderDeferred: false,
 
     setMaxHistory: (limit: number) => {
       set((state) => {
@@ -510,6 +515,7 @@ export const useStoryStore = create<StoryState>()(
         state.historyIndex = 0;
         state.visitCounts = { [startPassage.name]: 1 };
         state.renderCounts = { [startPassage.name]: 1 };
+        state.renderDeferred = false;
       });
 
       lastNavigationVars = get().variables;
@@ -776,5 +782,17 @@ export const useStoryStore = create<StoryState>()(
       }
       return current;
     },
+
+    deferRender: () => {
+      set((state) => {
+        state.renderDeferred = true;
+      });
+    },
+
+    clearDeferredRender: () => {
+      set((state) => {
+        state.renderDeferred = false;
+      });
+    },
   })),
 );

package/src/story-api.ts

@@ -50,6 +50,24 @@ import type { TransitionConfig } from './transition';
 export type { StoryAction };
 export type { MacroMetadata };
 
+// Deferred-render promise lifecycle.
+// deferRender() creates a promise; ready() resolves it.
+// index.tsx reads getReadyPromise() AFTER render(), which is after both
+// author JS and storyinit have run, so it always gets the final promise.
+let readyResolve: (() => void) | null = null;
+let readyPromise: Promise<void> | null = null;
+
+/** Returns the current deferred-render promise, or null if not deferred. */
+export function getReadyPromise(): Promise<void> | null {
+  return readyPromise;
+}
+
+/** Test-only: reset module-level promise state. */
+export function _resetReadyState(): void {
+  readyResolve = null;
+  readyPromise = null;
+}
+
 type NavigateCallback = (to: string, from: string) => void;
 type StoryInitCallback = () => void;
 type ActionsChangedCallback = () => void;
@@ -121,6 +139,8 @@ export interface StoryAPI {
   setCSS(enabled: boolean): void;
   setTransition(config: TransitionConfig | null): void;
   setNextTransition(config: TransitionConfig | null): void;
+  deferRender(): void;
+  ready(): void;
   random(): number;
   randomInt(min: number, max: number): number;
   readonly config: {
@@ -452,6 +472,21 @@ function createStoryAPI(): StoryAPI {
       useStoryStore.getState().setNextTransition(config);
     },
 
+    deferRender(): void {
+      useStoryStore.getState().deferRender();
+      readyPromise = new Promise<void>((resolve) => {
+        readyResolve = resolve;
+      });
+    },
+
+    ready(): void {
+      if (!readyResolve) return;
+      useStoryStore.getState().clearDeferredRender();
+      readyResolve();
+      readyResolve = null;
+      readyPromise = null;
+    },
+
     random(): number {
       return random();
     },