@rohal12/spindle 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",
@@ -40,6 +40,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "typecheck": "tsc --noEmit",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "docs:dev": "vitepress dev docs",
@@ -57,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",
-    "tweenode": "^0.3.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/class-registry.ts

@@ -0,0 +1,189 @@
+// Class registry for preserving class instances across clone/save/load cycles.
+
+type Constructor = new (...args: any[]) => any;
+
+const registry = new Map<string, Constructor>();
+const ctorToName = new Map<Constructor, string>();
+
+export function registerClass(name: string, ctor: Constructor): void {
+  registry.set(name, ctor);
+  ctorToName.set(ctor, name);
+}
+
+export function getClassName(ctor: Constructor): string | undefined {
+  return ctorToName.get(ctor);
+}
+
+export function clearRegistry(): void {
+  registry.clear();
+  ctorToName.clear();
+}
+
+// --- Deep Clone ---
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+export function deepClone<T>(value: T): T {
+  const seen = new Map<object, object>();
+
+  function clone(val: unknown): unknown {
+    if (val === null || typeof val !== 'object') return val;
+
+    const obj = val as object;
+    if (seen.has(obj)) return seen.get(obj);
+
+    if (val instanceof Date) return new Date(val.getTime()) as unknown;
+    if (val instanceof RegExp)
+      return new RegExp(val.source, val.flags) as unknown;
+
+    if (Array.isArray(val)) {
+      const arr: unknown[] = [];
+      seen.set(obj, arr);
+      for (let i = 0; i < val.length; i++) {
+        arr[i] = clone(val[i]);
+      }
+      return arr;
+    }
+
+    // Registered class instance
+    const ctor = obj.constructor as Constructor;
+    const name = ctorToName.get(ctor);
+    if (name !== undefined) {
+      const copy = Object.create(Object.getPrototypeOf(obj)) as Record<
+        string,
+        unknown
+      >;
+      seen.set(obj, copy);
+      for (const key of Object.keys(obj)) {
+        copy[key] = clone((obj as Record<string, unknown>)[key]);
+      }
+      return copy;
+    }
+
+    // Plain object (or unregistered class — treat as plain)
+    if (isPlainObject(val) || typeof val === 'object') {
+      const copy: Record<string, unknown> = {};
+      seen.set(obj, copy);
+      for (const key of Object.keys(obj)) {
+        copy[key] = clone((obj as Record<string, unknown>)[key]);
+      }
+      return copy;
+    }
+
+    return val;
+  }
+
+  return clone(value) as T;
+}
+
+// --- Serialize ---
+
+const CLASS_TAG = '__spindle_class__';
+const DATA_TAG = '__spindle_data__';
+
+export function serialize<T>(value: T): T {
+  const seen = new Set<object>();
+
+  function ser(val: unknown): unknown {
+    if (val === null || typeof val !== 'object') return val;
+
+    const obj = val as object;
+    if (seen.has(obj)) {
+      throw new Error('spindle: Cannot serialize circular references');
+    }
+    seen.add(obj);
+
+    if (val instanceof Date) {
+      seen.delete(obj);
+      return val.toISOString();
+    }
+
+    if (val instanceof RegExp) {
+      seen.delete(obj);
+      return val.toString();
+    }
+
+    if (Array.isArray(val)) {
+      const result = val.map((item) => ser(item));
+      seen.delete(obj);
+      return result;
+    }
+
+    // Registered class instance
+    const ctor = obj.constructor as Constructor;
+    const name = ctorToName.get(ctor);
+    if (name !== undefined) {
+      const data: Record<string, unknown> = {};
+      for (const key of Object.keys(obj)) {
+        data[key] = ser((obj as Record<string, unknown>)[key]);
+      }
+      seen.delete(obj);
+      return { [CLASS_TAG]: name, [DATA_TAG]: data };
+    }
+
+    // Plain object
+    const result: Record<string, unknown> = {};
+    for (const key of Object.keys(obj)) {
+      result[key] = ser((obj as Record<string, unknown>)[key]);
+    }
+    seen.delete(obj);
+    return result;
+  }
+
+  return ser(value) as T;
+}
+
+// --- Deserialize ---
+
+export function deserialize<T>(value: T): T {
+  function deser(val: unknown): unknown {
+    if (val === null || typeof val !== 'object') return val;
+
+    if (Array.isArray(val)) {
+      return val.map((item) => deser(item));
+    }
+
+    const obj = val as Record<string, unknown>;
+
+    // Tagged class instance (from serialized data)
+    if (CLASS_TAG in obj && DATA_TAG in obj) {
+      const name = obj[CLASS_TAG] as string;
+      const data = obj[DATA_TAG] as Record<string, unknown>;
+      const ctor = registry.get(name);
+      if (!ctor) {
+        console.warn(
+          `spindle: Class "${name}" not registered. Falling back to plain object.`,
+        );
+        const plain: Record<string, unknown> = {};
+        for (const key of Object.keys(data)) {
+          plain[key] = deser(data[key]);
+        }
+        return plain;
+      }
+      const instance = Object.create(ctor.prototype) as Record<string, unknown>;
+      for (const key of Object.keys(data)) {
+        instance[key] = deser(data[key]);
+      }
+      return instance;
+    }
+
+    // Already-live registered class instance — pass through as-is
+    const ctor = (obj as object).constructor as Constructor;
+    if (ctorToName.has(ctor)) {
+      return val;
+    }
+
+    // Plain object
+    const result: Record<string, unknown> = {};
+    for (const key of Object.keys(obj)) {
+      result[key] = deser(obj[key]);
+    }
+    return result;
+  }
+
+  return deser(value) as T;
+}

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/StoryInterface.tsx

@@ -4,7 +4,8 @@ import { tokenize } from '../markup/tokenizer';
 import { buildAST } from '../markup/ast';
 import { renderNodes } from '../markup/render';
 
-const DEFAULT_MARKUP = '{story-title}{back}{forward}{restart}{quicksave}{quickload}{saves}{settings}';
+const DEFAULT_MARKUP =
+  '{story-title}{back}{forward}{restart}{quicksave}{quickload}{saves}{settings}';
 
 export function StoryInterface() {
   const storyData = useStoryStore((s) => s.storyData);

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

@@ -1,6 +1,9 @@
 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 {
@@ -13,8 +16,8 @@ interface ButtonProps {
 export function Button({ rawArgs, children, className, id }: ButtonProps) {
   const handleClick = () => {
     const state = useStoryStore.getState();
-    const vars = structuredClone(state.variables);
-    const temps = structuredClone(state.temporary);
+    const vars = deepClone(state.variables);
+    const temps = deepClone(state.temporary);
 
     try {
       execute(rawArgs, vars, temps);
@@ -35,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 (
@@ -33,7 +51,7 @@ export function Cycle({ rawArgs, children, className, id }: CycleProps) {
       class={cls}
       onClick={handleClick}
     >
-      {value == null ? (options[0] || '') : String(value)}
+      {value == null ? options[0] || '' : String(value)}
     </button>
   );
 }

package/src/components/macros/Do.tsx

@@ -2,6 +2,7 @@ import { useLayoutEffect } from 'preact/hooks';
 import { useStoryStore } from '../../store';
 import { execute } from '../../expression';
 import type { ASTNode } from '../../markup/ast';
+import { deepClone } from '../../class-registry';
 
 interface DoProps {
   children: ASTNode[];
@@ -19,8 +20,8 @@ export function Do({ children }: DoProps) {
 
   useLayoutEffect(() => {
     const state = useStoryStore.getState();
-    const vars = { ...state.variables };
-    const temps = { ...state.temporary };
+    const vars = deepClone(state.variables);
+    const temps = deepClone(state.temporary);
 
     try {
       execute(code, vars, temps);