@rohal12/spindle 0.28.3 → 0.29.0

package/package.json

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

package/src/automation/load-yaml.ts

@@ -1,5 +1,37 @@
 import yaml from 'js-yaml';
-import type { AutomationScript } from './types';
+import type { AutomationScript, AutomationStep } from './types';
+
+function validateStep(step: unknown, index: number): AutomationStep {
+  if (typeof step !== 'object' || step === null) {
+    throw new Error(`Invalid automation step ${index + 1}: expected an object`);
+  }
+  const s = step as Record<string, unknown>;
+
+  const hasAction = 'action' in s;
+  const hasAssert = 'assert' in s;
+  const hasWait = 'wait' in s;
+  const hasSet = 'set' in s;
+
+  if (!hasAction && !hasAssert && !hasWait && !hasSet) {
+    throw new Error(
+      `Invalid automation step ${index + 1}: must have at least one of action, assert, wait, set`,
+    );
+  }
+
+  if (hasWait && typeof s.wait !== 'number') {
+    throw new Error(
+      `Invalid automation step ${index + 1}: "wait" must be a number`,
+    );
+  }
+
+  if (hasSet && (typeof s.set !== 'object' || s.set === null)) {
+    throw new Error(
+      `Invalid automation step ${index + 1}: "set" must be an object`,
+    );
+  }
+
+  return s as AutomationStep;
+}
 
 export function parseAutomationYaml(yamlContent: string): AutomationScript {
   const doc = yaml.load(yamlContent) as Record<string, unknown>;
@@ -16,5 +48,11 @@ export function parseAutomationYaml(yamlContent: string): AutomationScript {
     throw new Error('Invalid automation script: missing "steps" array');
   }
 
-  return doc as unknown as AutomationScript;
+  const steps = doc.steps.map((step, i) => validateStep(step, i));
+
+  return {
+    name: doc.name,
+    start: typeof doc.start === 'string' ? doc.start : undefined,
+    steps,
+  };
 }

package/src/components/StoryInterface.tsx

@@ -1,3 +1,4 @@
+import { useMemo } from 'preact/hooks';
 import { useStoryStore } from '../store';
 import { tokenize } from '../markup/tokenizer';
 import { buildAST } from '../markup/ast';
@@ -14,20 +15,24 @@ export function StoryInterface() {
     overridePassage !== undefined ? overridePassage.content : DEFAULT_MARKUP;
   const nobr = overridePassage?.tags.includes('nobr') ?? false;
 
-  try {
-    const tokens = tokenize(markup);
-    const ast = buildAST(tokens);
-    const rendered = <>{renderInlineNodes(ast)}</>;
-    return nobr ? (
-      <NobrContext.Provider value={true}>{rendered}</NobrContext.Provider>
-    ) : (
-      rendered
-    );
-  } catch (err) {
-    return (
-      <span class="error">
-        Error in StoryInterface: {(err as Error).message}
-      </span>
-    );
-  }
+  const rendered = useMemo(() => {
+    try {
+      const tokens = tokenize(markup);
+      const ast = buildAST(tokens);
+      return <>{renderInlineNodes(ast)}</>;
+    } catch (err) {
+      return (
+        <span class="error">
+          Error in StoryInterface:{' '}
+          {err instanceof Error ? err.message : String(err)}
+        </span>
+      );
+    }
+  }, [markup]);
+
+  return nobr ? (
+    <NobrContext.Provider value={true}>{rendered}</NobrContext.Provider>
+  ) : (
+    rendered
+  );
 }

package/src/components/macros/Checkbox.tsx

@@ -1,33 +1,24 @@
-import { useStoryStore } from '../../store';
 import { defineMacro } from '../../define-macro';
 
-function parseArgs(rawArgs: string): { varName: string; label: string } {
-  const match = rawArgs.match(/^\s*(["']?\$\w+["']?)\s+["']?(.+?)["']?\s*$/);
-  if (!match) {
-    return { varName: rawArgs.trim(), label: '' };
-  }
-  const varName = match[1]!.replace(/["']/g, '');
-  const label = match[2]!;
-  return { varName, label };
+function parseLabel(rawArgs: string): string {
+  const match = rawArgs.match(/^\s*["']?\$?\w+["']?\s+["']?(.+?)["']?\s*$/);
+  return match?.[1] ?? '';
 }
 
 defineMacro({
   name: 'checkbox',
+  storeVar: true,
   render({ rawArgs }, ctx) {
-    const { varName, label } = parseArgs(rawArgs);
-    const name = varName.startsWith('$') ? varName.slice(1) : varName;
-
-    const value = useStoryStore((s) => s.variables[name]);
-    const setVariable = useStoryStore((s) => s.setVariable);
+    const label = parseLabel(rawArgs);
 
     ctx.useAction({
       type: 'checkbox',
-      key: `$${name}`,
+      key: `$${ctx.varName}`,
       authorId: ctx.id,
-      label: label || name,
-      variable: name,
-      value: !!value,
-      perform: (v) => setVariable(name, v !== undefined ? !!v : !value),
+      label: label || ctx.varName || '',
+      variable: ctx.varName,
+      value: !!ctx.value,
+      perform: (v) => ctx.setValue!(v !== undefined ? !!v : !ctx.value),
     });
 
     return (
@@ -37,8 +28,8 @@ defineMacro({
       >
         <input
           type="checkbox"
-          checked={!!value}
-          onChange={() => setVariable(name, !value)}
+          checked={!!ctx.value}
+          onChange={() => ctx.setValue!(!ctx.value)}
         />
         {label ? ` ${label}` : null}
       </label>

package/src/components/macros/Cycle.tsx

@@ -1,3 +1,4 @@
+import { useStoryStore } from '../../store';
 import { defineMacro } from '../../define-macro';
 
 defineMacro({
@@ -8,7 +9,8 @@ defineMacro({
 
     const handleClick = () => {
       if (options.length === 0) return;
-      const currentIndex = options.indexOf(String(ctx.value));
+      const current = useStoryStore.getState().variables[ctx.varName!];
+      const currentIndex = options.indexOf(String(current));
       const nextIndex = (currentIndex + 1) % options.length;
       ctx.setValue!(options[nextIndex]);
     };

package/src/components/macros/For.tsx

@@ -82,7 +82,7 @@ function ForIteration({
   return (
     <LocalsUpdateContext.Provider value={updater}>
       <LocalsValuesContext.Provider value={localState}>
-        {renderNodes(children, nobr ? { nobr: true } : undefined)}
+        {renderNodes(children, { nobr, locals: localState })}
       </LocalsValuesContext.Provider>
     </LocalsUpdateContext.Provider>
   );

package/src/components/macros/MenubarButtons.tsx

@@ -28,9 +28,7 @@ export function defineMenubarAction(config: MenubarActionConfig) {
     render(_, ctx) {
       if (config.hidden?.()) return null;
 
-      const [dialogOpen, setDialogOpen] = config.dialog
-        ? useState(false)
-        : [false, undefined as never];
+      const [dialogOpen, setDialogOpen] = useState(false);
 
       const setup = config.setup?.() ?? { perform: () => {} };
       const { disabled } = setup;

package/src/components/macros/Radiobutton.tsx

@@ -1,48 +1,30 @@
-import { useStoryStore } from '../../store';
 import { defineMacro } from '../../define-macro';
 
-function parseArgs(rawArgs: string): {
-  varName: string;
-  value: string;
-  label: string;
-} {
-  // {radiobutton "$var" "value" "Label text"}
+function parseRadioArgs(rawArgs: string): { value: string; label: string } {
   const match = rawArgs.match(
-    /^\s*(["']?\$\w+["']?)\s+["'](.+?)["']\s+["']?(.+?)["']?\s*$/,
+    /^\s*["']?\$?\w+["']?\s+["'](.+?)["']\s+["']?(.+?)["']?\s*$/,
   );
   if (!match) {
-    // Try simpler: $var value label
-    const parts = rawArgs.trim().split(/\s+/);
-    return {
-      varName: (parts[0] ?? '').replace(/["']/g, ''),
-      value: parts[1] ?? '',
-      label: parts.slice(2).join(' '),
-    };
+    const parts = rawArgs.trim().split(/\s+/).slice(1);
+    return { value: parts[0] ?? '', label: parts.slice(1).join(' ') };
   }
-  return {
-    varName: match[1]!.replace(/["']/g, ''),
-    value: match[2]!,
-    label: match[3]!,
-  };
+  return { value: match[1]!, label: match[2]! };
 }
 
 defineMacro({
   name: 'radiobutton',
+  storeVar: true,
   render({ rawArgs }, ctx) {
-    const { varName, value: radioValue, label } = parseArgs(rawArgs);
-    const name = varName.startsWith('$') ? varName.slice(1) : varName;
-
-    const currentValue = useStoryStore((s) => s.variables[name]);
-    const setVariable = useStoryStore((s) => s.setVariable);
+    const { value: radioValue, label } = parseRadioArgs(rawArgs);
 
     ctx.useAction({
       type: 'radiobutton',
-      key: `$${name}:${radioValue}`,
+      key: `$${ctx.varName}:${radioValue}`,
       authorId: ctx.id,
       label: label || radioValue,
-      variable: name,
-      value: currentValue,
-      perform: () => setVariable(name, radioValue),
+      variable: ctx.varName,
+      value: ctx.value,
+      perform: () => ctx.setValue!(radioValue),
     });
 
     return (
@@ -52,9 +34,9 @@ defineMacro({
       >
         <input
           type="radio"
-          name={`radio-${name}`}
-          checked={currentValue === radioValue}
-          onChange={() => setVariable(name, radioValue)}
+          name={`radio-${ctx.varName}`}
+          checked={ctx.value === radioValue}
+          onChange={() => ctx.setValue!(radioValue)}
         />
         {label ? ` ${label}` : null}
       </label>

package/src/components/macros/Repeat.tsx

@@ -1,7 +1,5 @@
 import { createContext } from 'preact';
 import { parseDelay } from '../../utils/parse-delay';
-import { hasInterpolation, interpolate } from '../../interpolation';
-import { useStoryStore } from '../../store';
 import { defineMacro } from '../../define-macro';
 
 export const RepeatContext = createContext<{ stop: () => void }>({
@@ -10,17 +8,9 @@ export const RepeatContext = createContext<{ stop: () => void }>({
 
 defineMacro({
   name: 'repeat',
-  render({ rawArgs, children = [], className: rawClassName, id: rawId }, ctx) {
-    const { useState, useEffect, useCallback, useMemo } = ctx.hooks;
-
-    const [className, id] = useMemo(() => {
-      const resolveOnce = (s: string | undefined) => {
-        if (!s || !hasInterpolation(s)) return s;
-        const st = useStoryStore.getState();
-        return interpolate(s, st.variables, st.temporary, {});
-      };
-      return [resolveOnce(rawClassName), resolveOnce(rawId)];
-    }, [rawClassName, rawId]);
+  interpolate: true,
+  render({ rawArgs, children = [] }, ctx) {
+    const { useState, useEffect, useCallback } = ctx.hooks;
 
     const delay = parseDelay(rawArgs);
     const [count, setCount] = useState(0);
@@ -38,19 +28,17 @@ defineMacro({
 
     if (count === 0 && !stopped) return null;
 
-    const cls = className ? `macro-repeat ${className}` : undefined;
-
     const content = (
       <RepeatContext.Provider value={{ stop }}>
         <span key={count}>{ctx.renderNodes(children)}</span>
       </RepeatContext.Provider>
     );
 
-    if (cls || id)
+    if (ctx.className || ctx.id)
       return (
         <span
-          id={id}
-          class={cls}
+          id={ctx.id}
+          class={ctx.cls}
         >
           {content}
         </span>

package/src/components/macros/WidgetInvocation.tsx

@@ -9,6 +9,7 @@ import {
   LocalsValuesContext,
   LocalsUpdateContext,
   NobrContext,
+  WidgetChildrenContext,
   renderNodes,
 } from '../../markup/render';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
@@ -19,6 +20,7 @@ interface WidgetInvocationProps {
   body: ASTNode[];
   params: string[];
   rawArgs?: string;
+  invocationChildren?: ASTNode[];
 }
 
 /**
@@ -100,7 +102,7 @@ function WidgetBody({
   return (
     <LocalsUpdateContext.Provider value={updater}>
       <LocalsValuesContext.Provider value={localState}>
-        {renderNodes(body, nobr ? { nobr: true } : undefined)}
+        {renderNodes(body, { nobr, locals: localState })}
       </LocalsValuesContext.Provider>
     </LocalsUpdateContext.Provider>
   );
@@ -110,13 +112,20 @@ export function WidgetInvocation({
   body,
   params,
   rawArgs,
+  invocationChildren,
 }: WidgetInvocationProps) {
   const parentValues = useContext(LocalsValuesContext);
   const nobr = useContext(NobrContext);
   const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
 
+  const childrenValue = invocationChildren?.length ? invocationChildren : null;
+
   if (params.length === 0 || !rawArgs) {
-    return <>{renderNodes(body, nobr ? { nobr: true } : undefined)}</>;
+    return (
+      <WidgetChildrenContext.Provider value={childrenValue}>
+        {renderNodes(body, { nobr, locals: parentValues })}
+      </WidgetChildrenContext.Provider>
+    );
   }
 
   const argExprs = splitArgs(rawArgs);
@@ -137,10 +146,12 @@ export function WidgetInvocation({
   }
 
   return (
-    <WidgetBody
-      body={body}
-      parentValues={parentValues}
-      ownKeys={ownKeys}
-    />
+    <WidgetChildrenContext.Provider value={childrenValue}>
+      <WidgetBody
+        body={body}
+        parentValues={parentValues}
+        ownKeys={ownKeys}
+      />
+    </WidgetChildrenContext.Provider>
   );
 }

package/src/define-macro.ts

@@ -13,6 +13,7 @@ import { useInterpolate } from './hooks/use-interpolate';
 import { useMergedLocals } from './hooks/use-merged-locals';
 import {
   LocalsUpdateContext,
+  LocalsValuesContext,
   NobrContext,
   renderNodes as _renderNodes,
   renderInlineNodes,
@@ -107,10 +108,11 @@ export function defineMacro(config: MacroDefinition): void {
     // Always-on: cssClass + mutation
     const { update, getValues } = useContext(LocalsUpdateContext);
     const nobr = useContext(NobrContext);
-    const renderNodes = nobr
-      ? (nodes: ASTNode[], options?: { nobr?: boolean }) =>
-          _renderNodes(nodes, { nobr: true, ...options })
-      : _renderNodes;
+    const localsValues = useContext(LocalsValuesContext);
+    const renderNodes = (
+      nodes: ASTNode[],
+      options?: { nobr?: boolean; locals?: Record<string, unknown> },
+    ) => _renderNodes(nodes, { nobr, locals: localsValues, ...options });
     const ctx: MacroContext = {
       collectText,
       sourceLocation: currentSourceLocation,

package/src/execute-mutation.ts

@@ -29,4 +29,21 @@ export function executeMutation(
       scopeUpdate(key, localsClone[key]);
     }
   }
+
+  // Detect deleted keys
+  for (const key of Object.keys(state.variables)) {
+    if (!(key in vars)) {
+      state.deleteVariable(key);
+    }
+  }
+  for (const key of Object.keys(state.temporary)) {
+    if (!(key in temps)) {
+      state.deleteTemporary(key);
+    }
+  }
+  for (const key of Object.keys(mergedLocals)) {
+    if (!(key in localsClone)) {
+      scopeUpdate(key, undefined);
+    }
+  }
 }

package/src/expression.ts

@@ -34,7 +34,7 @@ const fnCache = new Map<string, CompiledExpression>();
  * but authors already have full JS access so this is acceptable).
  */
 const VAR_RE = /\$(\w+)/g;
-const TEMP_RE = /\b_(\w+)/g;
+const TEMP_RE = /(?<![.\w])_(\w+)/g;
 const LOCAL_RE = /@(\w+)/g;
 
 function transformSegment(segment: string): string {

package/src/index.tsx

@@ -13,8 +13,9 @@ import {
   extractDefaults,
 } from './story-variables';
 import { tokenize } from './markup/tokenizer';
-import { buildAST } from './markup/ast';
+import { buildAST, registerBlockMacro } from './markup/ast';
 import { registerWidget } from './widgets/widget-registry';
+import { astContainsChildren } from './widgets/ast-scanner';
 import type { ASTNode } from './markup/ast';
 import './macros/register-builtins';
 import builtinCSS from './styles.css?inline';
@@ -122,7 +123,12 @@ function boot() {
               (t) =>
                 t.startsWith('$') || t.startsWith('_') || t.startsWith('@'),
             );
-          registerWidget(widgetName, node.children as ASTNode[], params);
+          const children = node.children as ASTNode[];
+          const isBlock = astContainsChildren(children);
+          registerWidget(widgetName, children, params, isBlock);
+          if (isBlock) {
+            registerBlockMacro(widgetName);
+          }
         }
       }
     }

package/src/markup/render.tsx

@@ -23,6 +23,7 @@ const defaultUpdater: LocalsUpdater = {
 export const LocalsValuesContext = createContext<Record<string, unknown>>({});
 export const LocalsUpdateContext = createContext<LocalsUpdater>(defaultUpdater);
 export const NobrContext = createContext(false);
+export const WidgetChildrenContext = createContext<ASTNode[] | null>(null);
 
 /**
  * Convert an HTML string (from micromark) to Preact VNodes,
@@ -83,6 +84,7 @@ function convertDomNode(
 function HtmlNodeRenderer({ node }: { node: HtmlNode }) {
   const resolve = useInterpolate();
   const nobr = useContext(NobrContext);
+  const locals = useContext(LocalsValuesContext);
   const attrs: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(node.attributes)) {
     attrs[k] = resolve(v) ?? v;
@@ -91,11 +93,19 @@ function HtmlNodeRenderer({ node }: { node: HtmlNode }) {
     node.tag,
     attrs,
     node.children.length > 0
-      ? renderNodes(node.children, nobr ? { nobr: true } : undefined)
+      ? renderNodes(node.children, { nobr, locals })
       : undefined,
   );
 }
 
+function ChildrenSlot() {
+  const childrenAST = useContext(WidgetChildrenContext);
+  const nobr = useContext(NobrContext);
+  const locals = useContext(LocalsValuesContext);
+  if (!childrenAST || childrenAST.length === 0) return null;
+  return <>{renderNodes(childrenAST, { nobr, locals })}</>;
+}
+
 function renderMacro(node: MacroNode, key: number) {
   if (isSubMacro(node.name)) return null;
 
@@ -107,6 +117,7 @@ function renderMacro(node: MacroNode, key: number) {
         body={widget.body}
         params={widget.params}
         rawArgs={node.rawArgs}
+        invocationChildren={node.children}
       />
     );
   }
@@ -147,6 +158,9 @@ function renderSingleNode(
       return node.value;
 
     case 'variable':
+      if (node.scope === 'local' && node.name === 'children') {
+        return <ChildrenSlot key={key} />;
+      }
       return (
         <VarDisplay
           key={key}
@@ -193,7 +207,10 @@ function hasUnclosedBacktick(s: string): boolean {
   return count % 2 === 1;
 }
 
-function getVariableTextValue(node: VariableNode): string {
+function getVariableTextValue(
+  node: VariableNode,
+  locals: Record<string, unknown>,
+): string {
   const state = useStoryStore.getState();
   const parts = node.name.split('.');
   const root = parts[0]!;
@@ -201,6 +218,7 @@ function getVariableTextValue(node: VariableNode): string {
   let value: unknown;
   if (node.scope === 'variable') value = state.variables[root];
   else if (node.scope === 'temporary') value = state.temporary[root];
+  else value = locals[root];
 
   for (let i = 1; i < parts.length; i++) {
     if (value == null || typeof value !== 'object') return '';
@@ -223,7 +241,7 @@ function getVariableTextValue(node: VariableNode): string {
  */
 export function renderNodes(
   nodes: ASTNode[],
-  options?: { nobr?: boolean },
+  options?: { nobr?: boolean; locals?: Record<string, unknown> },
 ): preact.ComponentChildren {
   if (nodes.length === 0) return null;
 
@@ -236,6 +254,7 @@ export function renderNodes(
   // Build combined markdown string with placeholders for non-text nodes
   const components: preact.ComponentChildren[] = [];
   let combined = '';
+  const locals = options?.locals ?? {};
 
   for (let i = 0; i < nodes.length; i++) {
     const node = nodes[i]!;
@@ -243,7 +262,7 @@ export function renderNodes(
       combined += node.value.replace(/^[ \t]{4,}/gm, ' ');
     } else if (node.type === 'variable' && hasUnclosedBacktick(combined)) {
       // Inline variable value to avoid placeholder inside code span
-      combined += getVariableTextValue(node);
+      combined += getVariableTextValue(node, locals);
     } else {
       const phIdx = components.length;
       components.push(renderSingleNode(node, i));

package/src/saves/save-manager.ts

@@ -5,6 +5,7 @@ import type {
   PlaythroughRecord,
   SaveExport,
 } from './types';
+import { isSavePayload } from './types';
 import {
   putSave,
   getSave,
@@ -322,7 +323,9 @@ export function loadSession(ifid: string): SavePayload | undefined {
   try {
     const raw = sessionStorage.getItem(`${SESSION_KEY_PREFIX}${ifid}`);
     if (!raw) return undefined;
-    const payload: SavePayload = JSON.parse(raw);
+    const parsed: unknown = JSON.parse(raw);
+    if (!isSavePayload(parsed)) return undefined;
+    const payload = parsed;
     payload.variables = deserialize(payload.variables);
     payload.history = payload.history.map((m) => ({
       ...m,

package/src/saves/types.ts

@@ -76,3 +76,13 @@ export function isSaveExport(value: unknown): value is SaveExport {
 
   return true;
 }
+
+export function isSavePayload(value: unknown): value is SavePayload {
+  if (typeof value !== 'object' || value === null) return false;
+  const obj = value as Record<string, unknown>;
+  if (typeof obj.passage !== 'string') return false;
+  if (typeof obj.variables !== 'object' || obj.variables === null) return false;
+  if (!Array.isArray(obj.history)) return false;
+  if (typeof obj.historyIndex !== 'number') return false;
+  return true;
+}

package/src/store.ts

@@ -608,7 +608,10 @@ export const useStoryStore = create<StoryState>()(
           timestamp: m.timestamp,
           prng: m.prng,
         }));
-        state.historyIndex = payload.historyIndex;
+        state.historyIndex = Math.max(
+          0,
+          Math.min(payload.historyIndex, state.history.length - 1),
+        );
         state.visitCounts = payload.visitCounts ?? {};
         state.renderCounts = payload.renderCounts ?? {};
         state.temporary = {};

package/src/widgets/ast-scanner.ts

@@ -0,0 +1,29 @@
+import type { ASTNode } from '../markup/ast';
+
+/**
+ * Recursively scan an AST node array for a VariableNode
+ * with scope 'local' and name 'children' (@children).
+ */
+export function astContainsChildren(nodes: ASTNode[]): boolean {
+  for (const node of nodes) {
+    if (
+      node.type === 'variable' &&
+      node.scope === 'local' &&
+      node.name === 'children'
+    ) {
+      return true;
+    }
+    if (node.type === 'html' && astContainsChildren(node.children)) {
+      return true;
+    }
+    if (node.type === 'macro') {
+      if (astContainsChildren(node.children)) return true;
+      if (node.branches) {
+        for (const branch of node.branches) {
+          if (astContainsChildren(branch.children)) return true;
+        }
+      }
+    }
+  }
+  return false;
+}