@rohal12/spindle 0.1.0

package/src/store.ts

@@ -0,0 +1,317 @@
+import { create } from 'zustand';
+import { immer } from 'zustand/middleware/immer';
+import type { StoryData } from './parser';
+import type { SavePayload } from './saves/types';
+import { executeStoryInit } from './story-init';
+import {
+  initSaveSystem,
+  startNewPlaythrough,
+  getCurrentPlaythroughId,
+  quickSave,
+  loadQuickSave,
+} from './saves/save-manager';
+
+export interface HistoryMoment {
+  passage: string;
+  variables: Record<string, unknown>;
+  timestamp: number;
+}
+
+export interface StoryState {
+  storyData: StoryData | null;
+  currentPassage: string;
+  variables: Record<string, unknown>;
+  variableDefaults: Record<string, unknown>;
+  temporary: Record<string, unknown>;
+  history: HistoryMoment[];
+  historyIndex: number;
+  visitCounts: Record<string, number>;
+  renderCounts: Record<string, number>;
+  saveVersion: number;
+  playthroughId: string;
+
+  init: (
+    storyData: StoryData,
+    variableDefaults?: Record<string, unknown>,
+  ) => void;
+  navigate: (passageName: string) => void;
+  goBack: () => void;
+  goForward: () => void;
+  setVariable: (name: string, value: unknown) => void;
+  setTemporary: (name: string, value: unknown) => void;
+  deleteVariable: (name: string) => void;
+  deleteTemporary: (name: string) => void;
+  trackRender: (passageName: string) => void;
+  restart: () => void;
+  save: (slot?: string) => void;
+  load: (slot?: string) => void;
+  hasSave: (slot?: string) => boolean;
+  getSavePayload: () => SavePayload;
+  loadFromPayload: (payload: SavePayload) => void;
+}
+
+export const useStoryStore = create<StoryState>()(
+  immer((set, get) => ({
+    storyData: null,
+    currentPassage: '',
+    variables: {},
+    variableDefaults: {},
+    temporary: {},
+    history: [],
+    historyIndex: -1,
+    visitCounts: {},
+    renderCounts: {},
+    saveVersion: 0,
+    playthroughId: '',
+
+    init: (
+      storyData: StoryData,
+      variableDefaults: Record<string, unknown> = {},
+    ) => {
+      const startPassage = storyData.passagesById.get(storyData.startNode);
+      if (!startPassage) {
+        throw new Error(
+          `spindle: Start passage (pid=${storyData.startNode}) not found.`,
+        );
+      }
+
+      const initialVars = structuredClone(variableDefaults);
+
+      set((state) => {
+        state.storyData = storyData as StoryData;
+        state.currentPassage = startPassage.name;
+        state.variables = initialVars;
+        state.variableDefaults = variableDefaults;
+        state.temporary = {};
+        state.history = [
+          {
+            passage: startPassage.name,
+            variables: structuredClone(initialVars),
+            timestamp: Date.now(),
+          },
+        ];
+        state.historyIndex = 0;
+        state.visitCounts = { [startPassage.name]: 1 };
+        state.renderCounts = { [startPassage.name]: 1 };
+      });
+
+      // Init save system (fire-and-forget — DB will be ready before user opens dialog)
+      const ifid = storyData.ifid;
+      initSaveSystem().then(async () => {
+        const existingId = await getCurrentPlaythroughId(ifid);
+        if (existingId) {
+          set((state) => {
+            state.playthroughId = existingId;
+          });
+        } else {
+          const newId = await startNewPlaythrough(ifid);
+          set((state) => {
+            state.playthroughId = newId;
+          });
+        }
+      });
+    },
+
+    navigate: (passageName: string) => {
+      const { storyData } = get();
+      if (!storyData) return;
+
+      if (!storyData.passages.has(passageName)) {
+        console.error(`spindle: Passage "${passageName}" not found.`);
+        return;
+      }
+
+      set((state) => {
+        state.temporary = {};
+        state.currentPassage = passageName;
+
+        // Truncate forward history if we navigated back then chose a new path
+        state.history = state.history.slice(0, state.historyIndex + 1);
+
+        state.history.push({
+          passage: passageName,
+          variables: { ...state.variables },
+          timestamp: Date.now(),
+        });
+        state.historyIndex = state.history.length - 1;
+        state.visitCounts[passageName] =
+          (state.visitCounts[passageName] ?? 0) + 1;
+        state.renderCounts[passageName] =
+          (state.renderCounts[passageName] ?? 0) + 1;
+      });
+    },
+
+    goBack: () => {
+      set((state) => {
+        if (state.historyIndex <= 0) return;
+        state.historyIndex--;
+        const moment = state.history[state.historyIndex];
+        state.currentPassage = moment.passage;
+        state.variables = { ...moment.variables };
+        state.temporary = {};
+      });
+    },
+
+    goForward: () => {
+      set((state) => {
+        if (state.historyIndex >= state.history.length - 1) return;
+        state.historyIndex++;
+        const moment = state.history[state.historyIndex];
+        state.currentPassage = moment.passage;
+        state.variables = { ...moment.variables };
+        state.temporary = {};
+      });
+    },
+
+    setVariable: (name: string, value: unknown) => {
+      set((state) => {
+        state.variables[name] = value;
+      });
+    },
+
+    setTemporary: (name: string, value: unknown) => {
+      set((state) => {
+        state.temporary[name] = value;
+      });
+    },
+
+    deleteVariable: (name: string) => {
+      set((state) => {
+        delete state.variables[name];
+      });
+    },
+
+    deleteTemporary: (name: string) => {
+      set((state) => {
+        delete state.temporary[name];
+      });
+    },
+
+    trackRender: (passageName: string) => {
+      set((state) => {
+        state.renderCounts[passageName] =
+          (state.renderCounts[passageName] ?? 0) + 1;
+      });
+    },
+
+    restart: () => {
+      const { storyData, variableDefaults } = get();
+      if (!storyData) return;
+
+      const startPassage = storyData.passagesById.get(storyData.startNode);
+      if (!startPassage) return;
+
+      const initialVars = structuredClone(variableDefaults);
+
+      set((state) => {
+        state.currentPassage = startPassage.name;
+        state.variables = initialVars;
+        state.temporary = {};
+        state.history = [
+          {
+            passage: startPassage.name,
+            variables: structuredClone(initialVars),
+            timestamp: Date.now(),
+          },
+        ];
+        state.historyIndex = 0;
+        state.visitCounts = { [startPassage.name]: 1 };
+        state.renderCounts = { [startPassage.name]: 1 };
+      });
+
+      executeStoryInit();
+
+      // Start a new playthrough on restart
+      startNewPlaythrough(storyData.ifid).then((newId) => {
+        set((state) => {
+          state.playthroughId = newId;
+        });
+      });
+    },
+
+    save: () => {
+      const {
+        storyData,
+        playthroughId,
+        currentPassage,
+        variables,
+        history,
+        historyIndex,
+        visitCounts,
+        renderCounts,
+      } = get();
+      if (!storyData) return;
+
+      const payload: SavePayload = {
+        passage: currentPassage,
+        variables: structuredClone(variables),
+        history: structuredClone(history),
+        historyIndex,
+        visitCounts: { ...visitCounts },
+        renderCounts: { ...renderCounts },
+      };
+
+      quickSave(storyData.ifid, playthroughId, payload).then(() => {
+        set((state) => {
+          state.saveVersion++;
+        });
+      });
+    },
+
+    load: () => {
+      const { storyData } = get();
+      if (!storyData) return;
+
+      loadQuickSave(storyData.ifid).then((payload) => {
+        if (!payload) return;
+        set((state) => {
+          state.currentPassage = payload.passage;
+          state.variables = payload.variables;
+          state.history = payload.history;
+          state.historyIndex = payload.historyIndex;
+          state.visitCounts = payload.visitCounts ?? {};
+          state.renderCounts = payload.renderCounts ?? {};
+          state.temporary = {};
+        });
+      });
+    },
+
+    hasSave: () => {
+      // Synchronous: return true if a save has been made this session
+      const { storyData, saveVersion } = get();
+      if (!storyData) return false;
+      return saveVersion > 0;
+    },
+
+    getSavePayload: (): SavePayload => {
+      const {
+        currentPassage,
+        variables,
+        history,
+        historyIndex,
+        visitCounts,
+        renderCounts,
+      } = get();
+      return {
+        passage: currentPassage,
+        variables: structuredClone(variables),
+        history: structuredClone(history),
+        historyIndex,
+        visitCounts: { ...visitCounts },
+        renderCounts: { ...renderCounts },
+      };
+    },
+
+    loadFromPayload: (payload: SavePayload) => {
+      set((state) => {
+        state.currentPassage = payload.passage;
+        state.variables = payload.variables;
+        state.history = payload.history;
+        state.historyIndex = payload.historyIndex;
+        state.visitCounts = payload.visitCounts ?? {};
+        state.renderCounts = payload.renderCounts ?? {};
+        state.temporary = {};
+      });
+    },
+  })),
+);

package/src/story-api.ts

@@ -0,0 +1,129 @@
+import { useStoryStore } from './store';
+import { settings } from './settings';
+import type { SavePayload } from './saves/types';
+import { setTitleGenerator } from './saves/save-manager';
+
+export interface StoryAPI {
+  get(name: string): unknown;
+  set(name: string, value: unknown): void;
+  set(vars: Record<string, unknown>): void;
+  goto(passageName: string): void;
+  back(): void;
+  forward(): void;
+  restart(): void;
+  save(slot?: string): void;
+  load(slot?: string): void;
+  hasSave(slot?: string): boolean;
+  visited(name: string): number;
+  hasVisited(name: string): boolean;
+  hasVisitedAny(...names: string[]): boolean;
+  hasVisitedAll(...names: string[]): boolean;
+  rendered(name: string): number;
+  hasRendered(name: string): boolean;
+  hasRenderedAny(...names: string[]): boolean;
+  hasRenderedAll(...names: string[]): boolean;
+  readonly title: string;
+  readonly settings: typeof settings;
+  readonly saves: {
+    setTitleGenerator(fn: (payload: SavePayload) => string): void;
+  };
+}
+
+function createStoryAPI(): StoryAPI {
+  return {
+    get(name: string): unknown {
+      return useStoryStore.getState().variables[name];
+    },
+
+    set(nameOrVars: string | Record<string, unknown>, value?: unknown): void {
+      const state = useStoryStore.getState();
+      if (typeof nameOrVars === 'string') {
+        state.setVariable(nameOrVars, value);
+      } else {
+        for (const [k, v] of Object.entries(nameOrVars)) {
+          state.setVariable(k, v);
+        }
+      }
+    },
+
+    goto(passageName: string): void {
+      useStoryStore.getState().navigate(passageName);
+    },
+
+    back(): void {
+      useStoryStore.getState().goBack();
+    },
+
+    forward(): void {
+      useStoryStore.getState().goForward();
+    },
+
+    restart(): void {
+      useStoryStore.getState().restart();
+    },
+
+    save(slot?: string): void {
+      useStoryStore.getState().save(slot);
+    },
+
+    load(slot?: string): void {
+      useStoryStore.getState().load(slot);
+    },
+
+    hasSave(slot?: string): boolean {
+      return useStoryStore.getState().hasSave(slot);
+    },
+
+    visited(name: string): number {
+      return useStoryStore.getState().visitCounts[name] ?? 0;
+    },
+
+    hasVisited(name: string): boolean {
+      return (useStoryStore.getState().visitCounts[name] ?? 0) > 0;
+    },
+
+    hasVisitedAny(...names: string[]): boolean {
+      const { visitCounts } = useStoryStore.getState();
+      return names.some((n) => (visitCounts[n] ?? 0) > 0);
+    },
+
+    hasVisitedAll(...names: string[]): boolean {
+      const { visitCounts } = useStoryStore.getState();
+      return names.every((n) => (visitCounts[n] ?? 0) > 0);
+    },
+
+    rendered(name: string): number {
+      return useStoryStore.getState().renderCounts[name] ?? 0;
+    },
+
+    hasRendered(name: string): boolean {
+      return (useStoryStore.getState().renderCounts[name] ?? 0) > 0;
+    },
+
+    hasRenderedAny(...names: string[]): boolean {
+      const { renderCounts } = useStoryStore.getState();
+      return names.some((n) => (renderCounts[n] ?? 0) > 0);
+    },
+
+    hasRenderedAll(...names: string[]): boolean {
+      const { renderCounts } = useStoryStore.getState();
+      return names.every((n) => (renderCounts[n] ?? 0) > 0);
+    },
+
+    get title(): string {
+      return useStoryStore.getState().storyData?.name || '';
+    },
+
+    settings,
+
+    saves: {
+      setTitleGenerator(fn: (payload: SavePayload) => string): void {
+        setTitleGenerator(fn);
+      },
+    },
+  };
+}
+
+export function installStoryAPI(): void {
+  (window as any).Story = createStoryAPI();
+}

package/src/story-init.ts

@@ -0,0 +1,67 @@
+import { useStoryStore } from './store';
+import { tokenize } from './markup/tokenizer';
+import { buildAST } from './markup/ast';
+import { execute } from './expression';
+import type { ASTNode } from './markup/ast';
+import { setSaveTitlePassage } from './saves/save-manager';
+
+/**
+ * Walk AST nodes from StoryInit and execute {set} and {do} imperatively
+ * (no Preact rendering needed for initialization).
+ */
+function walkAndExecute(
+  nodes: ASTNode[],
+  vars: Record<string, unknown>,
+  temps: Record<string, unknown>,
+) {
+  for (const node of nodes) {
+    if (node.type !== 'macro') continue;
+
+    if (node.name === 'set') {
+      execute(node.rawArgs, vars, temps);
+    } else if (node.name === 'do') {
+      const code = node.children
+        .map((n) => (n.type === 'text' ? n.value : ''))
+        .join('');
+      execute(code, vars, temps);
+    }
+  }
+}
+
+/**
+ * Execute the StoryInit passage: tokenize, parse, and run all {set}/{do} macros.
+ * Called during boot and after restart() to ensure variables are initialized.
+ */
+export function executeStoryInit() {
+  const state = useStoryStore.getState();
+  if (!state.storyData) return;
+
+  const storyInit = state.storyData.passages.get('StoryInit');
+  if (!storyInit) return;
+
+  const tokens = tokenize(storyInit.content);
+  const ast = buildAST(tokens);
+
+  const vars = { ...state.variables };
+  const temps = { ...state.temporary };
+
+  walkAndExecute(ast, vars, temps);
+
+  // Apply all changes to the store
+  for (const key of Object.keys(vars)) {
+    if (vars[key] !== state.variables[key]) {
+      state.setVariable(key, vars[key]);
+    }
+  }
+  for (const key of Object.keys(temps)) {
+    if (temps[key] !== state.temporary[key]) {
+      state.setTemporary(key, temps[key]);
+    }
+  }
+
+  // Register SaveTitle passage if it exists
+  const saveTitlePassage = state.storyData.passages.get('SaveTitle');
+  if (saveTitlePassage) {
+    setSaveTitlePassage(saveTitlePassage.content);
+  }
+}

package/src/story-variables.ts

@@ -0,0 +1,166 @@
+import type { Passage } from './parser';
+
+export type VarType = 'number' | 'string' | 'boolean' | 'array' | 'object';
+
+export interface FieldSchema {
+  type: VarType;
+  fields?: Map<string, FieldSchema>; // only for objects
+}
+
+export interface VariableSchema extends FieldSchema {
+  name: string;
+  default: unknown;
+}
+
+const DECLARATION_RE = /^\$(\w+)\s*=\s*(.+)$/;
+const VAR_REF_RE = /\$(\w+(?:\.\w+)*)/g;
+const FOR_LOCAL_RE = /\{for\s+(\$\w+)(?:\s*,\s*(\$\w+))?\s+of\b/g;
+
+function inferSchema(value: unknown): FieldSchema {
+  if (Array.isArray(value)) {
+    return { type: 'array' };
+  }
+  if (value !== null && typeof value === 'object') {
+    const fields = new Map<string, FieldSchema>();
+    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+      fields.set(key, inferSchema(val));
+    }
+    return { type: 'object', fields };
+  }
+  return { type: typeof value as VarType };
+}
+
+/**
+ * Parse a StoryVariables passage content into a schema map.
+ * Each line: `$varName = expression`
+ */
+export function parseStoryVariables(
+  content: string,
+): Map<string, VariableSchema> {
+  const schema = new Map<string, VariableSchema>();
+
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+
+    const match = line.match(DECLARATION_RE);
+    if (!match) {
+      throw new Error(
+        `StoryVariables: Invalid declaration: "${line}". Expected: $name = value`,
+      );
+    }
+
+    const [, name, expr] = match;
+    let value: unknown;
+    try {
+      value = new Function('return (' + expr + ')')();
+    } catch (err) {
+      throw new Error(
+        `StoryVariables: Failed to evaluate "$${name} = ${expr}": ${err instanceof Error ? err.message : err}`,
+      );
+    }
+
+    const fieldSchema = inferSchema(value);
+    schema.set(name, { ...fieldSchema, name, default: value });
+  }
+
+  return schema;
+}
+
+/**
+ * Extract for-loop local variable names from passage content.
+ * `{for $item of ...}` → "item"
+ * `{for $index, $item of ...}` → "index", "item"
+ */
+function extractForLocals(content: string): Set<string> {
+  const locals = new Set<string>();
+  let match: RegExpExecArray | null;
+  FOR_LOCAL_RE.lastIndex = 0;
+  while ((match = FOR_LOCAL_RE.exec(content)) !== null) {
+    locals.add(match[1].slice(1)); // strip $
+    if (match[2]) locals.add(match[2].slice(1));
+  }
+  return locals;
+}
+
+/**
+ * Validate a single variable reference path (e.g. "player.health") against
+ * the schema. Returns an error message or null if valid.
+ */
+function validateRef(
+  ref: string,
+  schema: Map<string, VariableSchema>,
+  forLocals: Set<string>,
+): string | null {
+  const parts = ref.split('.');
+  const rootName = parts[0];
+
+  // Skip for-loop locals
+  if (forLocals.has(rootName)) return null;
+
+  const rootSchema = schema.get(rootName);
+  if (!rootSchema) {
+    return `Undeclared variable: $${ref}`;
+  }
+
+  // Walk through field access path
+  let current: FieldSchema = rootSchema;
+  for (let i = 1; i < parts.length; i++) {
+    // Arrays have a .length property
+    if (current.type === 'array' && parts[i] === 'length') return null;
+
+    if (current.type !== 'object' || !current.fields) {
+      return `Cannot access field "${parts[i]}" on $${parts.slice(0, i).join('.')} (type: ${current.type})`;
+    }
+    const fieldSchema = current.fields.get(parts[i]);
+    if (!fieldSchema) {
+      return `Undeclared field: $${parts.slice(0, i + 1).join('.')}`;
+    }
+    current = fieldSchema;
+  }
+
+  return null;
+}
+
+/**
+ * Scan all passages for $var references, check against schema.
+ * Returns list of error messages (empty = valid).
+ */
+export function validatePassages(
+  passages: Map<string, Passage>,
+  schema: Map<string, VariableSchema>,
+): string[] {
+  const errors: string[] = [];
+
+  for (const [name, passage] of passages) {
+    // Don't validate the StoryVariables passage itself
+    if (name === 'StoryVariables') continue;
+
+    const forLocals = extractForLocals(passage.content);
+
+    let match: RegExpExecArray | null;
+    VAR_REF_RE.lastIndex = 0;
+    while ((match = VAR_REF_RE.exec(passage.content)) !== null) {
+      const ref = match[1];
+      const error = validateRef(ref, schema, forLocals);
+      if (error) {
+        errors.push(`Passage "${name}": ${error}`);
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Extract default values from the schema as a plain object.
+ */
+export function extractDefaults(
+  schema: Map<string, VariableSchema>,
+): Record<string, unknown> {
+  const defaults: Record<string, unknown> = {};
+  for (const [name, varSchema] of schema) {
+    defaults[name] = varSchema.default;
+  }
+  return defaults;
+}