@rohal12/spindle 0.1.0

package/src/components/macros/Unset.tsx

@@ -0,0 +1,25 @@
+import { useLayoutEffect } from 'preact/hooks';
+import { useStoryStore } from '../../store';
+
+interface UnsetProps {
+  rawArgs: string;
+}
+
+export function Unset({ rawArgs }: UnsetProps) {
+  useLayoutEffect(() => {
+    const state = useStoryStore.getState();
+    const name = rawArgs.trim();
+
+    if (name.startsWith('$')) {
+      state.deleteVariable(name.slice(1));
+    } else if (name.startsWith('_')) {
+      state.deleteTemporary(name.slice(1));
+    } else {
+      console.error(
+        `spindle: {unset} expects a variable ($name or _name), got "${name}"`,
+      );
+    }
+  }, []);
+
+  return null;
+}

package/src/components/macros/VarDisplay.tsx

@@ -0,0 +1,44 @@
+import { useStoryStore } from '../../store';
+import { useContext } from 'preact/hooks';
+import { LocalsContext } from '../../markup/render';
+
+interface VarDisplayProps {
+  name: string;
+  scope: 'variable' | 'temporary';
+  className?: string;
+  id?: string;
+}
+
+export function VarDisplay({ name, scope, className, id }: VarDisplayProps) {
+  const locals = useContext(LocalsContext);
+  const parts = name.split('.');
+  const root = parts[0];
+  const storeValue = useStoryStore((s) =>
+    scope === 'variable' ? s.variables[root] : s.temporary[root],
+  );
+
+  // Locals (from for-loops) override store values
+  const key = scope === 'variable' ? `$${root}` : `_${root}`;
+  let value = key in locals ? locals[key] : storeValue;
+
+  // Resolve dot path (e.g. "character.name" → character['name'])
+  for (let i = 1; i < parts.length; i++) {
+    if (value == null || typeof value !== 'object') {
+      value = undefined;
+      break;
+    }
+    value = (value as Record<string, unknown>)[parts[i]];
+  }
+
+  const display = value == null ? '' : String(value);
+  if (className || id)
+    return (
+      <span
+        id={id}
+        class={className}
+      >
+        {display}
+      </span>
+    );
+  return <>{display}</>;
+}

package/src/components/macros/Widget.tsx

@@ -0,0 +1,18 @@
+import { useLayoutEffect } from 'preact/hooks';
+import { registerWidget } from '../../widgets/widget-registry';
+import type { ASTNode } from '../../markup/ast';
+
+interface WidgetProps {
+  rawArgs: string;
+  children: ASTNode[];
+}
+
+export function Widget({ rawArgs, children }: WidgetProps) {
+  const name = rawArgs.trim().replace(/["']/g, '');
+
+  useLayoutEffect(() => {
+    registerWidget(name, children);
+  }, []);
+
+  return null;
+}

package/src/components/macros/option-utils.ts

@@ -0,0 +1,14 @@
+import type { ASTNode } from '../../markup/ast';
+
+/**
+ * Walk AST children to find {option} macro nodes, returning their rawArgs as values.
+ */
+export function extractOptions(children: ASTNode[]): string[] {
+  const options: string[] = [];
+  for (const node of children) {
+    if (node.type === 'macro' && node.name === 'option') {
+      options.push(node.rawArgs.trim());
+    }
+  }
+  return options;
+}

package/src/expression.ts

@@ -0,0 +1,93 @@
+import type { StoryState } from './store';
+import { useStoryStore } from './store';
+
+const fnCache = new Map<string, Function>();
+
+/**
+ * Transform expression: $var → variables["var"], _var → temporary["var"]
+ * Only transforms when $ or _ appears as a word boundary (not inside strings naively,
+ * but authors already have full JS access so this is acceptable).
+ */
+function transform(expr: string): string {
+  return expr
+    .replace(/\$(\w+)/g, 'variables["$1"]')
+    .replace(/\b_(\w+)/g, 'temporary["$1"]');
+}
+
+const preamble =
+  'const {visited,hasVisited,hasVisitedAny,hasVisitedAll,rendered,hasRendered,hasRenderedAny,hasRenderedAll}=__fns;';
+
+function getOrCompile(key: string, body: string): Function {
+  let fn = fnCache.get(key);
+  if (!fn) {
+    fn = new Function('variables', 'temporary', '__fns', preamble + body);
+    fnCache.set(key, fn);
+  }
+  return fn;
+}
+
+export function buildExpressionFns() {
+  const state = useStoryStore.getState();
+  const { visitCounts, renderCounts } = state;
+
+  const visited = (name: string): number => visitCounts[name] ?? 0;
+  const hasVisited = (name: string): boolean => visited(name) > 0;
+  const hasVisitedAny = (...names: string[]): boolean =>
+    names.some((n) => visited(n) > 0);
+  const hasVisitedAll = (...names: string[]): boolean =>
+    names.every((n) => visited(n) > 0);
+
+  const rendered = (name: string): number => renderCounts[name] ?? 0;
+  const hasRendered = (name: string): boolean => rendered(name) > 0;
+  const hasRenderedAny = (...names: string[]): boolean =>
+    names.some((n) => rendered(n) > 0);
+  const hasRenderedAll = (...names: string[]): boolean =>
+    names.every((n) => rendered(n) > 0);
+
+  return {
+    visited,
+    hasVisited,
+    hasVisitedAny,
+    hasVisitedAll,
+    rendered,
+    hasRendered,
+    hasRenderedAny,
+    hasRenderedAll,
+  };
+}
+
+/**
+ * Evaluate an expression and return its value.
+ * e.g. evaluate("$health + 10", variables, temporary) → number
+ */
+export function evaluate(
+  expr: string,
+  variables: Record<string, unknown>,
+  temporary: Record<string, unknown>,
+): unknown {
+  const transformed = transform(expr);
+  const body = `return (${transformed});`;
+  const fn = getOrCompile(body, body);
+  return fn(variables, temporary, buildExpressionFns());
+}
+
+/**
+ * Execute statements (no return value).
+ * e.g. execute("$health = 100; $name = 'Hero'", variables, temporary)
+ */
+export function execute(
+  code: string,
+  variables: Record<string, unknown>,
+  temporary: Record<string, unknown>,
+): void {
+  const transformed = transform(code);
+  const fn = getOrCompile('exec:' + transformed, transformed);
+  fn(variables, temporary, buildExpressionFns());
+}
+
+/**
+ * Convenience: evaluate using store state directly.
+ */
+export function evaluateWithState(expr: string, state: StoryState): unknown {
+  return evaluate(expr, state.variables, state.temporary);
+}

package/src/index.tsx

@@ -0,0 +1,120 @@
+import { render } from 'preact';
+import { App } from './components/App';
+import { parseStoryData } from './parser';
+import { useStoryStore } from './store';
+import { installStoryAPI } from './story-api';
+import { executeStoryInit } from './story-init';
+import {
+  parseStoryVariables,
+  validatePassages,
+  extractDefaults,
+} from './story-variables';
+import { tokenize } from './markup/tokenizer';
+import { buildAST } from './markup/ast';
+import { registerWidget } from './widgets/widget-registry';
+import type { ASTNode } from './markup/ast';
+import './styles.css';
+
+function renderErrors(root: HTMLElement, errors: string[]) {
+  root.innerHTML = '';
+  const container = document.createElement('div');
+  container.style.cssText =
+    'font-family:monospace;padding:2rem;max-width:60rem;margin:0 auto';
+  const heading = document.createElement('h1');
+  heading.style.color = '#c00';
+  heading.textContent = 'Story Validation Errors';
+  container.appendChild(heading);
+  const list = document.createElement('ul');
+  list.style.cssText = 'line-height:1.6';
+  for (const msg of errors) {
+    const li = document.createElement('li');
+    li.textContent = msg;
+    list.appendChild(li);
+  }
+  container.appendChild(list);
+  root.appendChild(container);
+}
+
+function boot() {
+  const storyData = parseStoryData();
+
+  // Install Story API before author script runs
+  installStoryAPI();
+
+  // Apply author CSS
+  if (storyData.userCSS) {
+    const style = document.createElement('style');
+    style.textContent = storyData.userCSS;
+    document.head.appendChild(style);
+  }
+
+  // Execute author JavaScript
+  if (storyData.userScript) {
+    try {
+      new Function(storyData.userScript)();
+    } catch (err) {
+      console.error('spindle: Error in story JavaScript:', err);
+    }
+  }
+
+  // Parse StoryVariables and validate all passages
+  let defaults: Record<string, unknown> = {};
+  const storyVarsPassage = storyData.passages.get('StoryVariables');
+
+  if (!storyVarsPassage) {
+    const msg =
+      'Missing StoryVariables passage. Add a :: StoryVariables passage to declare your variables.';
+    const root = document.getElementById('root');
+    if (root) renderErrors(root, [msg]);
+    throw new Error(`spindle: ${msg}`);
+  }
+
+  const schema = parseStoryVariables(storyVarsPassage.content);
+  const errors = validatePassages(storyData.passages, schema);
+
+  if (errors.length > 0) {
+    const root = document.getElementById('root');
+    if (root) renderErrors(root, errors);
+    throw new Error(
+      `spindle: ${errors.length} validation error(s):\n${errors.join('\n')}`,
+    );
+  }
+
+  defaults = extractDefaults(schema);
+
+  useStoryStore.getState().init(storyData, defaults);
+
+  // Execute StoryInit passage if it exists
+  executeStoryInit();
+
+  // Register widgets from passages tagged "widget"
+  for (const [, passage] of storyData.passages) {
+    if (passage.tags.includes('widget')) {
+      const widgetTokens = tokenize(passage.content);
+      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 root = document.getElementById('root');
+  if (!root) {
+    throw new Error('spindle: No <div id="root"> element found.');
+  }
+
+  render(<App />, root);
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', boot);
+} else {
+  boot();
+}

package/src/markup/ast.ts

@@ -0,0 +1,284 @@
+import type { Token } from './tokenizer';
+
+export interface TextNode {
+  type: 'text';
+  value: string;
+}
+
+export interface LinkNode {
+  type: 'link';
+  display: string;
+  target: string;
+  className?: string;
+  id?: string;
+}
+
+export interface VariableNode {
+  type: 'variable';
+  name: string;
+  scope: 'variable' | 'temporary';
+  className?: string;
+  id?: string;
+}
+
+export interface Branch {
+  rawArgs: string;
+  className?: string;
+  id?: string;
+  children: ASTNode[];
+}
+
+export interface MacroNode {
+  type: 'macro';
+  name: string;
+  rawArgs: string;
+  children: ASTNode[];
+  branches?: Branch[];
+  className?: string;
+  id?: string;
+}
+
+export interface HtmlNode {
+  type: 'html';
+  tag: string;
+  attributes: Record<string, string>;
+  children: ASTNode[];
+}
+
+export type ASTNode = TextNode | LinkNode | VariableNode | MacroNode | HtmlNode;
+
+/** Macros that require a closing tag and can contain children */
+const BLOCK_MACROS = new Set([
+  'if',
+  'for',
+  'do',
+  'button',
+  'link',
+  'listbox',
+  'cycle',
+  'switch',
+  'timed',
+  'repeat',
+  'type',
+  'widget',
+]);
+
+/** Map from branch macro name → required parent macro name */
+const BRANCH_PARENT: Record<string, string> = {
+  elseif: 'if',
+  else: 'if',
+  case: 'switch',
+  default: 'switch',
+  next: 'timed',
+};
+
+/** Block macros that use the branches[] array */
+const BRANCHING_BLOCK_MACROS = new Set(['if', 'switch', 'timed']);
+
+/**
+ * Build an AST from a token array. Block macros are nested into trees
+ * using a stack. Throws on unclosed or mismatched macros.
+ */
+export function buildAST(tokens: Token[]): ASTNode[] {
+  const root: ASTNode[] = [];
+
+  // Stack entries: the node being built and its token start position
+  const stack: { node: MacroNode | HtmlNode; start: number }[] = [];
+
+  function current(): ASTNode[] {
+    if (stack.length === 0) return root;
+    const top = stack[stack.length - 1].node;
+    // For if-blocks, append to the last branch's children
+    if (
+      top.type === 'macro' &&
+      top.branches &&
+      top.branches.length > 0
+    ) {
+      return top.branches[top.branches.length - 1].children;
+    }
+    return top.children;
+  }
+
+  for (const token of tokens) {
+    switch (token.type) {
+      case 'text':
+        current().push({ type: 'text', value: token.value });
+        break;
+
+      case 'link': {
+        const linkNode: LinkNode = {
+          type: 'link',
+          display: token.display,
+          target: token.target,
+        };
+        if (token.className) linkNode.className = token.className;
+        if (token.id) linkNode.id = token.id;
+        current().push(linkNode);
+        break;
+      }
+
+      case 'variable': {
+        const varNode: VariableNode = {
+          type: 'variable',
+          name: token.name,
+          scope: token.scope,
+        };
+        if (token.className) varNode.className = token.className;
+        if (token.id) varNode.id = token.id;
+        current().push(varNode);
+        break;
+      }
+
+      case 'html': {
+        if (token.isSelfClose) {
+          // Self-closing HTML tag (br, hr, img, etc.)
+          current().push({
+            type: 'html',
+            tag: token.tag,
+            attributes: token.attributes,
+            children: [],
+          });
+          break;
+        }
+
+        if (token.isClose) {
+          // Closing HTML tag — pop from stack
+          if (stack.length === 0) {
+            throw new Error(
+              `Unexpected closing </${token.tag}> (at character ${token.start})`,
+            );
+          }
+
+          const top = stack[stack.length - 1];
+          if (top.node.type !== 'html' || top.node.tag !== token.tag) {
+            const expected =
+              top.node.type === 'html'
+                ? `</${top.node.tag}>`
+                : `{/${top.node.name}}`;
+            throw new Error(
+              `Expected ${expected} but found </${token.tag}> (at character ${token.start})`,
+            );
+          }
+
+          stack.pop();
+          current().push(top.node);
+          break;
+        }
+
+        // Opening HTML tag — push onto stack
+        const htmlNode: HtmlNode = {
+          type: 'html',
+          tag: token.tag,
+          attributes: token.attributes,
+          children: [],
+        };
+        stack.push({ node: htmlNode, start: token.start });
+        break;
+      }
+
+      case 'macro': {
+        if (token.isClose) {
+          // Closing tag — pop from stack
+          if (stack.length === 0) {
+            throw new Error(
+              `Unexpected closing {/${token.name}} (at character ${token.start})`,
+            );
+          }
+
+          const top = stack[stack.length - 1];
+          if (top.node.type !== 'macro' || top.node.name !== token.name) {
+            const expected =
+              top.node.type === 'macro'
+                ? `{/${top.node.name}}`
+                : `</${top.node.tag}>`;
+            throw new Error(
+              `Expected ${expected} but found {/${token.name}} (at character ${token.start})`,
+            );
+          }
+
+          stack.pop();
+          current().push(top.node);
+          break;
+        }
+
+        // Handle branch macros (elseif/else, case/default, next)
+        if (BRANCH_PARENT[token.name]) {
+          const expectedParent = BRANCH_PARENT[token.name];
+          const topNode = stack.length > 0 ? stack[stack.length - 1].node : null;
+          if (
+            !topNode ||
+            topNode.type !== 'macro' ||
+            topNode.name !== expectedParent
+          ) {
+            throw new Error(
+              `{${token.name}} without matching {${expectedParent}} (at character ${token.start})`,
+            );
+          }
+
+          const branch: Branch = {
+            rawArgs: token.rawArgs,
+            children: [],
+          };
+          if (token.className) branch.className = token.className;
+          if (token.id) branch.id = token.id;
+          topNode.branches!.push(branch);
+          break;
+        }
+
+        // Block macro — push onto stack
+        if (BLOCK_MACROS.has(token.name)) {
+          const node: MacroNode = {
+            type: 'macro',
+            name: token.name,
+            rawArgs: token.rawArgs,
+            children: [],
+          };
+
+          // Branching blocks: className/id goes on the first branch, not the node
+          if (BRANCHING_BLOCK_MACROS.has(token.name)) {
+            const firstBranch: Branch = {
+              rawArgs: token.rawArgs,
+              children: [],
+            };
+            if (token.className) firstBranch.className = token.className;
+            if (token.id) firstBranch.id = token.id;
+            node.branches = [firstBranch];
+          } else {
+            if (token.className) node.className = token.className;
+            if (token.id) node.id = token.id;
+          }
+
+          stack.push({ node, start: token.start });
+          break;
+        }
+
+        // Self-closing macro (set, print, etc.)
+        {
+          const macroNode: MacroNode = {
+            type: 'macro',
+            name: token.name,
+            rawArgs: token.rawArgs,
+            children: [],
+          };
+          if (token.className) macroNode.className = token.className;
+          if (token.id) macroNode.id = token.id;
+          current().push(macroNode);
+        }
+        break;
+      }
+    }
+  }
+
+  if (stack.length > 0) {
+    const unclosed = stack[stack.length - 1];
+    const label =
+      unclosed.node.type === 'html'
+        ? `<${unclosed.node.tag}>`
+        : `{${unclosed.node.name}} macro`;
+    throw new Error(
+      `Unclosed ${label} (opened at character ${unclosed.start})`,
+    );
+  }
+
+  return root;
+}

package/src/markup/markdown.ts

@@ -0,0 +1,21 @@
+import { micromark } from 'micromark';
+import {
+  gfmTable,
+  gfmTableHtml,
+} from 'micromark-extension-gfm-table';
+import {
+  gfmStrikethrough,
+  gfmStrikethroughHtml,
+} from 'micromark-extension-gfm-strikethrough';
+
+/**
+ * Parse a text string as CommonMark markdown and return an HTML string.
+ * Includes GFM table and strikethrough extensions.
+ */
+export function markdownToHtml(text: string): string {
+  return micromark(text, {
+    allowDangerousHtml: true,
+    extensions: [gfmTable(), gfmStrikethrough()],
+    htmlExtensions: [gfmTableHtml(), gfmStrikethroughHtml()],
+  });
+}