@rohal12/spindle 0.28.2 → 0.28.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.28.2",
+  "version": "0.28.4",
   "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

@@ -100,7 +100,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>
   );
@@ -116,7 +116,7 @@ export function WidgetInvocation({
   const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
 
   if (params.length === 0 || !rawArgs) {
-    return <>{renderNodes(body, nobr ? { nobr: true } : undefined)}</>;
+    return <>{renderNodes(body, { nobr, locals: parentValues })}</>;
   }
 
   const argExprs = splitArgs(rawArgs);

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/markup/render.tsx

@@ -83,6 +83,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,7 +92,7 @@ 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,
   );
 }
@@ -193,7 +194,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 +205,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 +228,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 +241,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 +249,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/parser.ts

@@ -18,10 +18,25 @@ export interface StoryData {
   userScript: string;
 }
 
+/**
+ * Decode the HTML entities that browsers use when serializing innerHTML.
+ * &amp; is decoded last to avoid double-decoding (e.g. &amp;lt; → &lt;, not <).
+ */
+function decodeHtmlEntities(html: string): string {
+  return html
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
 /**
  * Parse <tw-storydata> and all <tw-passagedata> elements from the DOM.
- * The browser auto-decodes HTML entities when building the DOM, so
- * textContent gives us the original passage text.
+ *
+ * Uses innerHTML + entity decoding instead of textContent so that HTML
+ * tags inside passage markup (e.g. <div> inside {button}) are preserved
+ * regardless of whether the compiler HTML-encoded them.
  */
 export function parseStoryData(): StoryData {
   const storyEl = document.querySelector('tw-storydata');
@@ -52,7 +67,7 @@ export function parseStoryData(): StoryData {
     const tags = (el.getAttribute('tags') || '')
       .split(/\s+/)
       .filter((t) => t.length > 0);
-    const content = el.textContent || '';
+    const content = decodeHtmlEntities(el.innerHTML);
 
     const metadata: Record<string, string> = {};
     const skipAttrs = new Set(['pid', 'name', 'tags']);

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 = {};