@rohal12/spindle 0.6.0 → 0.8.0

package/src/components/macros/WidgetInvocation.tsx

@@ -0,0 +1,127 @@
+import { useContext, useState, useCallback } from 'preact/hooks';
+import { LocalsContext, renderNodes } from '../../markup/render';
+import type { LocalsScope } from '../../markup/render';
+import { useMergedLocals } from '../../hooks/use-merged-locals';
+import { evaluate } from '../../expression';
+import type { ASTNode } from '../../markup/ast';
+
+interface WidgetInvocationProps {
+  body: ASTNode[];
+  params: string[];
+  rawArgs?: string;
+}
+
+/**
+ * Split rawArgs by commas, respecting parentheses, brackets, braces, and strings.
+ */
+function splitArgs(raw: string): string[] {
+  const args: string[] = [];
+  let current = '';
+  let depth = 0;
+  let inString: string | null = null;
+
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i]!;
+
+    if (inString) {
+      current += ch;
+      if (ch === inString && raw[i - 1] !== '\\') inString = null;
+      continue;
+    }
+
+    if (ch === '"' || ch === "'" || ch === '`') {
+      inString = ch;
+      current += ch;
+      continue;
+    }
+
+    if (ch === '(' || ch === '[' || ch === '{') {
+      depth++;
+      current += ch;
+      continue;
+    }
+
+    if (ch === ')' || ch === ']' || ch === '}') {
+      depth--;
+      current += ch;
+      continue;
+    }
+
+    if (ch === ',' && depth === 0) {
+      args.push(current.trim());
+      current = '';
+      continue;
+    }
+
+    current += ch;
+  }
+
+  const last = current.trim();
+  if (last) args.push(last);
+  return args;
+}
+
+function WidgetBody({
+  body,
+  parentValues,
+  ownKeys,
+}: {
+  body: ASTNode[];
+  parentValues: Record<string, unknown>;
+  ownKeys: Record<string, unknown>;
+}) {
+  const [localState, setLocalState] = useState<Record<string, unknown>>(() => ({
+    ...parentValues,
+    ...ownKeys,
+  }));
+
+  const update = useCallback((key: string, value: unknown) => {
+    setLocalState((prev) => ({ ...prev, [key]: value }));
+  }, []);
+
+  const scope: LocalsScope = { values: localState, update };
+
+  return (
+    <LocalsContext.Provider value={scope}>
+      {renderNodes(body)}
+    </LocalsContext.Provider>
+  );
+}
+
+export function WidgetInvocation({
+  body,
+  params,
+  rawArgs,
+}: WidgetInvocationProps) {
+  const parentScope = useContext(LocalsContext);
+  const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
+
+  if (params.length === 0 || !rawArgs) {
+    return <>{renderNodes(body)}</>;
+  }
+
+  const argExprs = splitArgs(rawArgs);
+  const ownKeys: Record<string, 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);
+      } catch {
+        value = undefined;
+      }
+    }
+    ownKeys[param] = value;
+  }
+
+  return (
+    <WidgetBody
+      body={body}
+      parentValues={parentScope.values}
+      ownKeys={ownKeys}
+    />
+  );
+}

package/src/expression.ts

@@ -21,6 +21,7 @@ interface ExpressionFns {
 type CompiledExpression = (
   variables: Record<string, unknown>,
   temporary: Record<string, unknown>,
+  locals: Record<string, unknown>,
   __fns: ExpressionFns,
 ) => unknown;
 
@@ -34,11 +35,13 @@ const fnCache = new Map<string, CompiledExpression>();
  */
 const VAR_RE = /\$(\w+)/g;
 const TEMP_RE = /\b_(\w+)/g;
+const LOCAL_RE = /@(\w+)/g;
 
 function transform(expr: string): string {
   return expr
     .replace(VAR_RE, 'variables["$1"]')
-    .replace(TEMP_RE, 'temporary["$1"]');
+    .replace(TEMP_RE, 'temporary["$1"]')
+    .replace(LOCAL_RE, 'locals["$1"]');
 }
 
 const preamble =
@@ -55,6 +58,7 @@ function getOrCompile(key: string, body: string): CompiledExpression {
   const fn = new Function(
     'variables',
     'temporary',
+    'locals',
     '__fns',
     preamble + body,
   ) as CompiledExpression;
@@ -136,11 +140,12 @@ export function evaluate(
   expr: string,
   variables: Record<string, unknown>,
   temporary: Record<string, unknown>,
+  locals: Record<string, unknown> = {},
 ): unknown {
   const transformed = transform(expr);
   const body = `return (${transformed});`;
   const fn = getOrCompile(body, body);
-  return fn(variables, temporary, buildExpressionFns());
+  return fn(variables, temporary, locals, buildExpressionFns());
 }
 
 /**
@@ -151,15 +156,16 @@ export function execute(
   code: string,
   variables: Record<string, unknown>,
   temporary: Record<string, unknown>,
+  locals: Record<string, unknown> = {},
 ): void {
   const transformed = transform(code);
   const fn = getOrCompile('exec:' + transformed, transformed);
-  fn(variables, temporary, buildExpressionFns());
+  fn(variables, temporary, locals, buildExpressionFns());
 }
 
 /**
  * Convenience: evaluate using store state directly.
  */
 export function evaluateWithState(expr: string, state: StoryState): unknown {
-  return evaluate(expr, state.variables, state.temporary);
+  return evaluate(expr, state.variables, state.temporary, {});
 }

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

@@ -3,24 +3,26 @@ import { useStoryStore } from '../store';
 import { LocalsContext } from '../markup/render';
 
 /**
- * Merge store variables/temporary with LocalsContext values.
- * Locals prefixed with `$` go into variables, `_` into temporary.
+ * Return store variables, temporary, and @-prefixed locals from context.
+ * Locals use `@` prefix keys internally; the returned locals dict has
+ * the prefix stripped so it can be passed directly to evaluate/execute.
  */
 export function useMergedLocals(): readonly [
   Record<string, unknown>,
   Record<string, unknown>,
+  Record<string, unknown>,
 ] {
   const variables = useStoryStore((s) => s.variables);
   const temporary = useStoryStore((s) => s.temporary);
-  const locals = useContext(LocalsContext);
+  const scope = useContext(LocalsContext);
 
   return useMemo(() => {
-    const vars = { ...variables };
-    const temps = { ...temporary };
-    for (const [key, val] of Object.entries(locals)) {
-      if (key.startsWith('$')) vars[key.slice(1)] = val;
-      else if (key.startsWith('_')) temps[key.slice(1)] = val;
+    const locals: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(scope.values)) {
+      if (key.startsWith('@')) {
+        locals[key.slice(1)] = val;
+      }
     }
-    return [vars, temps] as const;
-  }, [variables, temporary, locals]);
+    return [variables, temporary, locals] as const;
+  }, [variables, temporary, scope.values]);
 }

package/src/index.tsx

@@ -95,8 +95,12 @@ function boot() {
       const widgetAST = buildAST(widgetTokens);
       for (const node of widgetAST) {
         if (node.type === 'macro' && node.name === 'widget' && node.rawArgs) {
-          const widgetName = node.rawArgs.trim().replace(/["']/g, '');
-          registerWidget(widgetName, node.children as ASTNode[]);
+          const tokens2 = node.rawArgs.trim().split(/\s+/);
+          const widgetName = tokens2[0]!.replace(/["']/g, '');
+          const params = tokens2
+            .slice(1)
+            .filter((t) => t.startsWith('$') || t.startsWith('_'));
+          registerWidget(widgetName, node.children as ASTNode[], params);
         }
       }
     }
@@ -111,6 +115,18 @@ function boot() {
     }
   });
 
+  // Warn if StoryInterface passage exists but doesn't contain {passage}
+  const storyInterfacePassage = storyData.passages.get('StoryInterface');
+  if (
+    storyInterfacePassage &&
+    !storyInterfacePassage.content.includes('{passage}')
+  ) {
+    console.warn(
+      'spindle: StoryInterface passage does not contain {passage}. ' +
+        'The current passage will not be displayed.',
+    );
+  }
+
   const root = document.getElementById('root');
   if (!root) {
     throw new Error('spindle: No <div id="root"> element found.');

package/src/markup/ast.ts

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

package/src/markup/render.tsx

@@ -32,15 +32,27 @@ import { Repeat } from '../components/macros/Repeat';
 import { Stop } from '../components/macros/Stop';
 import { Type } from '../components/macros/Type';
 import { Widget } from '../components/macros/Widget';
+import { WidgetInvocation } from '../components/macros/WidgetInvocation';
 import { Computed } from '../components/macros/Computed';
 import { Meter } from '../components/macros/Meter';
+import { PassageDisplay } from '../components/macros/PassageDisplay';
 import { getWidget } from '../widgets/widget-registry';
 import { getMacro } from '../registry';
 import { markdownToHtml } from './markdown';
 import { h } from 'preact';
 import type { ASTNode, Branch, MacroNode } from './ast';
 
-export const LocalsContext = createContext<Record<string, unknown>>({});
+export interface LocalsScope {
+  values: Record<string, unknown>;
+  update: (key: string, value: unknown) => void;
+}
+
+const defaultLocalsScope: LocalsScope = {
+  values: {},
+  update: () => {},
+};
+
+export const LocalsContext = createContext<LocalsScope>(defaultLocalsScope);
 
 const EMPTY_BRANCHES: Branch[] = [];
 
@@ -132,6 +144,15 @@ function renderMacro(node: MacroNode, key: number) {
         />
       );
 
+    case 'passage':
+      return (
+        <PassageDisplay
+          key={key}
+          className={node.className}
+          id={node.id}
+        />
+      );
+
     case 'if':
       return (
         <If
@@ -415,9 +436,16 @@ function renderMacro(node: MacroNode, key: number) {
 
     default: {
       // Check widget registry for user-defined widgets
-      const widgetAST = getWidget(node.name);
-      if (widgetAST) {
-        return <>{renderNodes(widgetAST)}</>;
+      const widget = getWidget(node.name);
+      if (widget) {
+        return (
+          <WidgetInvocation
+            key={key}
+            body={widget.body}
+            params={widget.params}
+            rawArgs={node.rawArgs}
+          />
+        );
       }
 
       // Check component registry for custom macros

package/src/markup/tokenizer.ts

@@ -29,7 +29,7 @@ export interface MacroToken {
 export interface VariableToken {
   type: 'variable';
   name: string;
-  scope: 'variable' | 'temporary';
+  scope: 'variable' | 'temporary' | 'local';
   className?: string;
   id?: string;
   start: number;
@@ -419,6 +419,34 @@ export function tokenize(input: string): Token[] {
           continue;
         }
 
+        if (charAfter === '@') {
+          // {.class#id @local.field}
+          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: 'local',
+              start,
+              end: i,
+            };
+            if (className) token.className = className;
+            if (id) token.id = id;
+            tokens.push(token);
+            textStart = i;
+            continue;
+          }
+          // Not valid — treat as text
+          i = start + 1;
+          textStart = start;
+          continue;
+        }
+
         if (charAfter !== undefined && /[a-zA-Z]/.test(charAfter)) {
           // {.class#id macroName args}
           i = afterSelectors;
@@ -515,6 +543,32 @@ export function tokenize(input: string): Token[] {
         continue;
       }
 
+      // {@local.field}
+      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: 'local',
+            start,
+            end: i,
+          });
+          textStart = i;
+          continue;
+        }
+        // Not a valid local token — 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/story-variables.ts

@@ -14,7 +14,7 @@ export interface VariableSchema extends FieldSchema {
 
 const DECLARATION_RE = /^\$(\w+)\s*=\s*(.+)$/;
 const VAR_REF_RE = /\$(\w+(?:\.\w+)*)/g;
-const FOR_LOCAL_RE = /\{for\s+(\$\w+)(?:\s*,\s*(\$\w+))?\s+of\b/g;
+const FOR_LOCAL_RE = /\{for\s+@(\w+)(?:\s*,\s*@(\w+))?\s+of\b/g;
 
 const VALID_VAR_TYPES = new Set<string>(['number', 'string', 'boolean']);
 
@@ -77,16 +77,16 @@ export function parseStoryVariables(
 
 /**
  * Extract for-loop local variable names from passage content.
- * `{for $item of ...}` → "item"
- * `{for $index, $item of ...}` → "index", "item"
+ * `{for @item of ...}` → "item"
+ * `{for @index, @item of ...}` → "index", "item"
  */
 function extractForLocals(content: string): Set<string> {
   const locals = new Set<string>();
   let match: RegExpExecArray | null;
   FOR_LOCAL_RE.lastIndex = 0;
   while ((match = FOR_LOCAL_RE.exec(content)) !== null) {
-    locals.add(match[1]!.slice(1)); // strip $
-    if (match[2]) locals.add(match[2]!.slice(1));
+    locals.add(match[1]!);
+    if (match[2]) locals.add(match[2]!);
   }
   return locals;
 }

package/src/widgets/widget-registry.ts

@@ -1,12 +1,21 @@
 import type { ASTNode } from '../markup/ast';
 
-const widgets = new Map<string, ASTNode[]>();
+interface WidgetEntry {
+  body: ASTNode[];
+  params: string[];
+}
+
+const widgets = new Map<string, WidgetEntry>();
 
-export function registerWidget(name: string, bodyAST: ASTNode[]): void {
-  widgets.set(name.toLowerCase(), bodyAST);
+export function registerWidget(
+  name: string,
+  bodyAST: ASTNode[],
+  params: string[],
+): void {
+  widgets.set(name.toLowerCase(), { body: bodyAST, params });
 }
 
-export function getWidget(name: string): ASTNode[] | undefined {
+export function getWidget(name: string): WidgetEntry | undefined {
   return widgets.get(name.toLowerCase());
 }