@rohal12/spindle 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",
@@ -58,11 +58,13 @@
   },
   "devDependencies": {
     "@preact/preset-vite": "^2.9.0",
+    "@rohal12/twee-ts": "^1.0.0",
+    "@types/js-yaml": "^4.0.9",
     "@vitest/coverage-v8": "^4.0.18",
     "happy-dom": "^20.7.0",
+    "js-yaml": "^4.1.1",
     "playwright": "^1.58.2",
     "prettier": "^3.8.1",
-    "@rohal12/twee-ts": "^1.0.0",
     "typescript": "^5.7.0",
     "vite": "^6.0.0",
     "vite-plugin-singlefile": "^2.0.0",

package/src/action-registry.ts

@@ -0,0 +1,83 @@
+export type ActionType =
+  | 'link'
+  | 'button'
+  | 'cycle'
+  | 'textbox'
+  | 'numberbox'
+  | 'textarea'
+  | 'checkbox'
+  | 'radiobutton'
+  | 'listbox'
+  | 'back'
+  | 'forward'
+  | 'restart'
+  | 'save'
+  | 'load';
+
+export interface StoryAction {
+  id: string;
+  type: ActionType;
+  label: string;
+  target?: string;
+  variable?: string;
+  options?: string[];
+  value?: unknown;
+  disabled?: boolean;
+  perform: (value?: unknown) => void;
+}
+
+const actions = new Map<string, StoryAction>();
+const listeners = new Set<() => void>();
+const idCounters = new Map<string, number>();
+
+export function generateActionId(
+  type: ActionType,
+  key: string,
+  authorId?: string,
+): string {
+  if (authorId) return authorId;
+
+  const base = `${type}:${key}`;
+  const count = (idCounters.get(base) ?? 0) + 1;
+  idCounters.set(base, count);
+  return count === 1 ? base : `${base}:${count}`;
+}
+
+export function registerAction(action: StoryAction): () => void {
+  actions.set(action.id, action);
+  notify();
+  return () => {
+    actions.delete(action.id);
+    notify();
+  };
+}
+
+export function getActions(): StoryAction[] {
+  return Array.from(actions.values());
+}
+
+export function getAction(id: string): StoryAction | undefined {
+  return actions.get(id);
+}
+
+export function clearActions(): void {
+  actions.clear();
+  notify();
+}
+
+export function resetIdCounters(): void {
+  idCounters.clear();
+}
+
+export function onActionsChanged(fn: () => void): () => void {
+  listeners.add(fn);
+  return () => {
+    listeners.delete(fn);
+  };
+}
+
+function notify(): void {
+  for (const fn of listeners) {
+    fn();
+  }
+}

package/src/automation/index.ts

@@ -0,0 +1,11 @@
+export { runAutomation } from './runner';
+export type { RunOptions } from './runner';
+export { parseAutomationYaml } from './load-yaml';
+export type {
+  AutomationScript,
+  AutomationStep,
+  AssertStep,
+  ActionMatcher,
+  RunResult,
+  StepError,
+} from './types';

package/src/automation/load-yaml.ts

@@ -0,0 +1,20 @@
+import yaml from 'js-yaml';
+import type { AutomationScript } from './types';
+
+export function parseAutomationYaml(yamlContent: string): AutomationScript {
+  const doc = yaml.load(yamlContent) as Record<string, unknown>;
+
+  if (!doc || typeof doc !== 'object') {
+    throw new Error('Invalid YAML: expected an object');
+  }
+
+  if (typeof doc.name !== 'string') {
+    throw new Error('Invalid automation script: missing "name" field');
+  }
+
+  if (!Array.isArray(doc.steps)) {
+    throw new Error('Invalid automation script: missing "steps" array');
+  }
+
+  return doc as unknown as AutomationScript;
+}

package/src/automation/runner.ts

@@ -0,0 +1,139 @@
+import type {
+  AutomationScript,
+  AutomationStep,
+  RunResult,
+  StepError,
+  ActionMatcher,
+} from './types';
+import type { StoryAPI } from '../story-api';
+import type { StoryAction } from '../action-registry';
+
+export interface RunOptions {
+  onStep?: (stepIndex: number, step: AutomationStep) => void;
+}
+
+export async function runAutomation(
+  story: StoryAPI,
+  script: AutomationScript,
+  options: RunOptions = {},
+): Promise<RunResult> {
+  const errors: StepError[] = [];
+  let stepsRun = 0;
+
+  // Navigate to start passage if specified
+  if (script.start) {
+    story.goto(script.start);
+    await story.waitForActions();
+  }
+
+  for (let i = 0; i < script.steps.length; i++) {
+    const step = script.steps[i];
+    options.onStep?.(i, step);
+
+    try {
+      await executeStep(story, step, i, errors);
+    } catch (err) {
+      errors.push({
+        step: i,
+        message: err instanceof Error ? err.message : String(err),
+      });
+      break;
+    }
+
+    stepsRun = i + 1;
+  }
+
+  return {
+    success: errors.length === 0,
+    stepsRun,
+    errors,
+  };
+}
+
+async function executeStep(
+  story: StoryAPI,
+  step: AutomationStep,
+  index: number,
+  errors: StepError[],
+): Promise<void> {
+  if (step.set) {
+    story.set(step.set);
+  }
+
+  if (step.action !== undefined) {
+    const id = typeof step.action === 'string' ? step.action : step.action.id;
+    const value =
+      typeof step.action === 'string' ? undefined : step.action.value;
+    story.performAction(id, value);
+    await story.waitForActions();
+  }
+
+  if (step.wait !== undefined) {
+    await new Promise((resolve) => setTimeout(resolve, step.wait));
+  }
+
+  if (step.assert) {
+    const { assert } = step;
+
+    if (assert.passage !== undefined) {
+      if (story.passage !== assert.passage) {
+        errors.push({
+          step: index,
+          message: `Expected passage "${assert.passage}", got "${story.passage}"`,
+        });
+      }
+    }
+
+    if (assert.variables) {
+      for (const [key, expected] of Object.entries(assert.variables)) {
+        const actual = story.get(key);
+        if (actual !== expected) {
+          errors.push({
+            step: index,
+            message: `Variable "${key}": expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`,
+          });
+        }
+      }
+    }
+
+    if (assert.actionCount !== undefined) {
+      const actions = story.getActions();
+      if (actions.length !== assert.actionCount) {
+        errors.push({
+          step: index,
+          message: `Expected ${assert.actionCount} actions, got ${actions.length}`,
+        });
+      }
+    }
+
+    if (assert.actions) {
+      const actions = story.getActions();
+      for (const matcher of assert.actions) {
+        if (!findMatchingAction(actions, matcher)) {
+          errors.push({
+            step: index,
+            message: `No action matching ${JSON.stringify(matcher)}`,
+          });
+        }
+      }
+    }
+  }
+}
+
+function findMatchingAction(
+  actions: StoryAction[],
+  matcher: ActionMatcher,
+): StoryAction | undefined {
+  return actions.find((action) => {
+    if (matcher.id !== undefined && action.id !== matcher.id) return false;
+    if (matcher.type !== undefined && action.type !== matcher.type)
+      return false;
+    if (matcher.target !== undefined && action.target !== matcher.target)
+      return false;
+    if (matcher.variable !== undefined && action.variable !== matcher.variable)
+      return false;
+    if (matcher.label !== undefined && action.label !== matcher.label)
+      return false;
+    return true;
+  });
+}

package/src/automation/types.ts

@@ -0,0 +1,38 @@
+export interface ActionMatcher {
+  type?: string;
+  id?: string;
+  target?: string;
+  variable?: string;
+  label?: string;
+}
+
+export interface AssertStep {
+  passage?: string;
+  variables?: Record<string, unknown>;
+  actions?: ActionMatcher[];
+  actionCount?: number;
+}
+
+export interface AutomationStep {
+  action?: string | { id: string; value?: unknown };
+  assert?: AssertStep;
+  wait?: number;
+  set?: Record<string, unknown>;
+}
+
+export interface AutomationScript {
+  name: string;
+  start?: string;
+  steps: AutomationStep[];
+}
+
+export interface StepError {
+  step: number;
+  message: string;
+}
+
+export interface RunResult {
+  success: boolean;
+  stepsRun: number;
+  errors: StepError[];
+}

package/src/components/PassageLink.tsx

@@ -1,4 +1,5 @@
 import { useStoryStore } from '../store';
+import { useAction } from '../hooks/use-action';
 
 interface PassageLinkProps {
   target: string;
@@ -20,6 +21,15 @@ export function PassageLink({
     navigate(target);
   };
 
+  useAction({
+    type: 'link',
+    key: target,
+    authorId: id,
+    label: typeof children === 'string' ? children : target,
+    target,
+    perform: () => navigate(target),
+  });
+
   const cls = className ? `passage-link ${className}` : 'passage-link';
 
   return (

package/src/components/macros/Back.tsx

@@ -1,4 +1,5 @@
 import { useStoryStore } from '../../store';
+import { useAction } from '../../hooks/use-action';
 
 interface BackProps {
   className?: string;
@@ -10,6 +11,15 @@ export function Back({ className, id }: BackProps) {
   const canGoBack = useStoryStore((s) => s.historyIndex > 0);
   const cls = className ? `menubar-button ${className}` : 'menubar-button';
 
+  useAction({
+    type: 'back',
+    key: 'back',
+    authorId: id,
+    label: 'Back',
+    disabled: !canGoBack,
+    perform: () => goBack(),
+  });
+
   return (
     <button
       id={id}

package/src/components/macros/Button.tsx

@@ -2,6 +2,8 @@ import { useStoryStore } from '../../store';
 import { execute } from '../../expression';
 import { renderInlineNodes } from '../../markup/render';
 import { deepClone } from '../../class-registry';
+import { collectText } from '../../utils/extract-text';
+import { useAction } from '../../hooks/use-action';
 import type { ASTNode } from '../../markup/ast';
 
 interface ButtonProps {
@@ -36,6 +38,14 @@ export function Button({ rawArgs, children, className, id }: ButtonProps) {
     }
   };
 
+  useAction({
+    type: 'button',
+    key: rawArgs,
+    authorId: id,
+    label: collectText(children) || rawArgs,
+    perform: handleClick,
+  });
+
   const cls = className ? `macro-button ${className}` : 'macro-button';
 
   return (

package/src/components/macros/Checkbox.tsx

@@ -1,4 +1,5 @@
 import { useStoryStore } from '../../store';
+import { useAction } from '../../hooks/use-action';
 
 interface CheckboxProps {
   rawArgs: string;
@@ -23,6 +24,16 @@ export function Checkbox({ rawArgs, className, id }: CheckboxProps) {
   const value = useStoryStore((s) => s.variables[name]);
   const setVariable = useStoryStore((s) => s.setVariable);
 
+  useAction({
+    type: 'checkbox',
+    key: `$${name}`,
+    authorId: id,
+    label: label || name,
+    variable: name,
+    value: !!value,
+    perform: (v) => setVariable(name, v !== undefined ? !!v : !value),
+  });
+
   const cls = className ? `macro-checkbox ${className}` : 'macro-checkbox';
 
   return (

package/src/components/macros/Cycle.tsx

@@ -1,5 +1,6 @@
 import { useStoryStore } from '../../store';
 import { extractOptions } from './option-utils';
+import { useAction } from '../../hooks/use-action';
 import type { ASTNode } from '../../markup/ast';
 
 interface CycleProps {
@@ -25,6 +26,23 @@ export function Cycle({ rawArgs, children, className, id }: CycleProps) {
     setVariable(name, options[nextIndex]);
   };
 
+  useAction({
+    type: 'cycle',
+    key: `$${name}`,
+    authorId: id,
+    label: value == null ? options[0] || '' : String(value),
+    variable: name,
+    options,
+    value,
+    perform: (v) => {
+      if (v !== undefined) {
+        setVariable(name, v);
+      } else {
+        handleClick();
+      }
+    },
+  });
+
   const cls = className ? `macro-cycle ${className}` : 'macro-cycle';
 
   return (

package/src/components/macros/Forward.tsx

@@ -1,4 +1,5 @@
 import { useStoryStore } from '../../store';
+import { useAction } from '../../hooks/use-action';
 
 interface ForwardProps {
   className?: string;
@@ -12,6 +13,15 @@ export function Forward({ className, id }: ForwardProps) {
   );
   const cls = className ? `menubar-button ${className}` : 'menubar-button';
 
+  useAction({
+    type: 'forward',
+    key: 'forward',
+    authorId: id,
+    label: 'Forward',
+    disabled: !canGoForward,
+    perform: () => goForward(),
+  });
+
   return (
     <button
       id={id}

package/src/components/macros/Listbox.tsx

@@ -1,5 +1,6 @@
 import { useStoryStore } from '../../store';
 import { extractOptions } from './option-utils';
+import { useAction } from '../../hooks/use-action';
 import type { ASTNode } from '../../markup/ast';
 
 interface ListboxProps {
@@ -18,6 +19,19 @@ export function Listbox({ rawArgs, children, className, id }: ListboxProps) {
 
   const options = extractOptions(children);
 
+  useAction({
+    type: 'listbox',
+    key: `$${name}`,
+    authorId: id,
+    label: name,
+    variable: name,
+    options,
+    value,
+    perform: (v) => {
+      if (v !== undefined) setVariable(name, String(v));
+    },
+  });
+
   const cls = className ? `macro-listbox ${className}` : 'macro-listbox';
 
   return (

package/src/components/macros/MacroLink.tsx

@@ -31,12 +31,8 @@ function parseArgs(rawArgs: string): {
   return { display: rawArgs.trim(), passage: null };
 }
 
-/**
- * Collect text from AST nodes for imperative execution (like Do.tsx).
- */
-function collectText(nodes: ASTNode[]): string {
-  return nodes.map((n) => (n.type === 'text' ? n.value : '')).join('');
-}
+import { collectText } from '../../utils/extract-text';
+import { useAction } from '../../hooks/use-action';
 
 /**
  * Execute the children imperatively: walk AST for {set} and {do} macros.
@@ -93,6 +89,20 @@ export function MacroLink({
     }
   };
 
+  useAction({
+    type: 'link',
+    key: passage || display,
+    authorId: id,
+    label: display,
+    target: passage ?? undefined,
+    perform: () => {
+      executeChildren(children);
+      if (passage) {
+        useStoryStore.getState().navigate(passage);
+      }
+    },
+  });
+
   const cls = className ? `macro-link ${className}` : 'macro-link';
 
   return (

package/src/components/macros/Numberbox.tsx

@@ -1,4 +1,5 @@
 import { useStoryStore } from '../../store';
+import { useAction } from '../../hooks/use-action';
 
 interface NumberboxProps {
   rawArgs: string;
@@ -23,6 +24,16 @@ export function Numberbox({ rawArgs, className, id }: NumberboxProps) {
   const value = useStoryStore((s) => s.variables[name]);
   const setVariable = useStoryStore((s) => s.setVariable);
 
+  useAction({
+    type: 'numberbox',
+    key: `$${name}`,
+    authorId: id,
+    label: placeholder || name,
+    variable: name,
+    value,
+    perform: (v) => setVariable(name, v !== undefined ? Number(v) : 0),
+  });
+
   const cls = className ? `macro-numberbox ${className}` : 'macro-numberbox';
 
   return (

package/src/components/macros/QuickLoad.tsx

@@ -1,4 +1,5 @@
 import { useStoryStore } from '../../store';
+import { useAction } from '../../hooks/use-action';
 
 interface QuickLoadProps {
   className?: string;
@@ -19,6 +20,15 @@ export function QuickLoad({ className, id }: QuickLoadProps) {
     }
   };
 
+  useAction({
+    type: 'load',
+    key: 'quickload',
+    authorId: id,
+    label: 'QuickLoad',
+    disabled,
+    perform: () => load(),
+  });
+
   return (
     <button
       id={id}

package/src/components/macros/QuickSave.tsx

@@ -1,4 +1,5 @@
 import { useStoryStore } from '../../store';
+import { useAction } from '../../hooks/use-action';
 
 interface QuickSaveProps {
   className?: string;
@@ -9,6 +10,14 @@ export function QuickSave({ className, id }: QuickSaveProps) {
   const save = useStoryStore((s) => s.save);
   const cls = className ? `menubar-button ${className}` : 'menubar-button';
 
+  useAction({
+    type: 'save',
+    key: 'quicksave',
+    authorId: id,
+    label: 'QuickSave',
+    perform: () => save(),
+  });
+
   return (
     <button
       id={id}

package/src/components/macros/Radiobutton.tsx

@@ -1,4 +1,5 @@
 import { useStoryStore } from '../../store';
+import { useAction } from '../../hooks/use-action';
 
 interface RadiobuttonProps {
   rawArgs: string;
@@ -38,6 +39,16 @@ export function Radiobutton({ rawArgs, className, id }: RadiobuttonProps) {
   const currentValue = useStoryStore((s) => s.variables[name]);
   const setVariable = useStoryStore((s) => s.setVariable);
 
+  useAction({
+    type: 'radiobutton',
+    key: `$${name}:${radioValue}`,
+    authorId: id,
+    label: label || radioValue,
+    variable: name,
+    value: currentValue,
+    perform: () => setVariable(name, radioValue),
+  });
+
   const cls = className
     ? `macro-radiobutton ${className}`
     : 'macro-radiobutton';

package/src/components/macros/Restart.tsx

@@ -1,4 +1,5 @@
 import { useStoryStore } from '../../store';
+import { useAction } from '../../hooks/use-action';
 
 interface RestartProps {
   className?: string;
@@ -15,6 +16,14 @@ export function Restart({ className, id }: RestartProps) {
     }
   };
 
+  useAction({
+    type: 'restart',
+    key: 'restart',
+    authorId: id,
+    label: 'Restart',
+    perform: () => restart(),
+  });
+
   return (
     <button
       id={id}

package/src/components/macros/Textarea.tsx

@@ -1,4 +1,5 @@
 import { useStoryStore } from '../../store';
+import { useAction } from '../../hooks/use-action';
 
 interface TextareaProps {
   rawArgs: string;
@@ -23,6 +24,16 @@ export function Textarea({ rawArgs, className, id }: TextareaProps) {
   const value = useStoryStore((s) => s.variables[name]);
   const setVariable = useStoryStore((s) => s.setVariable);
 
+  useAction({
+    type: 'textarea',
+    key: `$${name}`,
+    authorId: id,
+    label: placeholder || name,
+    variable: name,
+    value,
+    perform: (v) => setVariable(name, v !== undefined ? String(v) : ''),
+  });
+
   const cls = className ? `macro-textarea ${className}` : 'macro-textarea';
 
   return (

package/src/components/macros/Textbox.tsx

@@ -1,4 +1,5 @@
 import { useStoryStore } from '../../store';
+import { useAction } from '../../hooks/use-action';
 
 interface TextboxProps {
   rawArgs: string;
@@ -23,6 +24,16 @@ export function Textbox({ rawArgs, className, id }: TextboxProps) {
   const value = useStoryStore((s) => s.variables[name]);
   const setVariable = useStoryStore((s) => s.setVariable);
 
+  useAction({
+    type: 'textbox',
+    key: `$${name}`,
+    authorId: id,
+    label: placeholder || name,
+    variable: name,
+    value,
+    perform: (v) => setVariable(name, v !== undefined ? String(v) : ''),
+  });
+
   const cls = className ? `macro-textbox ${className}` : 'macro-textbox';
 
   return (