@rohal12/spindle 0.1.0 → 0.3.0

package/src/markup/tokenizer.ts

@@ -46,16 +46,74 @@ export interface HtmlToken {
   end: number;
 }
 
-export type Token = TextToken | LinkToken | MacroToken | VariableToken | HtmlToken;
+export type Token =
+  | TextToken
+  | LinkToken
+  | MacroToken
+  | VariableToken
+  | HtmlToken;
 
 const HTML_TAGS = new Set([
-  'a', 'article', 'aside', 'b', 'blockquote', 'br', 'caption', 'code',
-  'col', 'colgroup', 'dd', 'del', 'details', 'dfn', 'div', 'dl', 'dt',
-  'em', 'figcaption', 'figure', 'footer', 'h1', 'h2', 'h3', 'h4', 'h5',
-  'h6', 'header', 'hr', 'i', 'img', 'ins', 'kbd', 'li', 'main', 'mark',
-  'nav', 'ol', 'p', 'pre', 'q', 's', 'samp', 'section', 'small', 'span',
-  'strong', 'sub', 'summary', 'sup', 'table', 'tbody', 'td', 'tfoot', 'th',
-  'thead', 'tr', 'u', 'ul', 'wbr',
+  'a',
+  'article',
+  'aside',
+  'b',
+  'blockquote',
+  'br',
+  'caption',
+  'code',
+  'col',
+  'colgroup',
+  'dd',
+  'del',
+  'details',
+  'dfn',
+  'div',
+  'dl',
+  'dt',
+  'em',
+  'figcaption',
+  'figure',
+  'footer',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'header',
+  'hr',
+  'i',
+  'img',
+  'ins',
+  'kbd',
+  'li',
+  'main',
+  'mark',
+  'nav',
+  'ol',
+  'p',
+  'pre',
+  'q',
+  's',
+  'samp',
+  'section',
+  'small',
+  'span',
+  'strong',
+  'sub',
+  'summary',
+  'sup',
+  'table',
+  'tbody',
+  'td',
+  'tfoot',
+  'th',
+  'thead',
+  'tr',
+  'u',
+  'ul',
+  'wbr',
 ]);
 
 const HTML_VOID_TAGS = new Set(['br', 'col', 'hr', 'img', 'wbr']);

package/src/saves/save-manager.ts

@@ -15,6 +15,7 @@ import {
   getMeta,
   setMeta,
 } from './idb';
+import { deepClone, serialize, deserialize } from '../class-registry';
 
 type TitleGenerator = (payload: SavePayload) => string;
 
@@ -118,7 +119,13 @@ export async function createSave(
     custom,
   };
 
-  const record: SaveRecord = { meta, payload: structuredClone(payload) };
+  const serializedPayload = deepClone(payload);
+  serializedPayload.variables = serialize(serializedPayload.variables);
+  serializedPayload.history = serializedPayload.history.map((m) => ({
+    ...m,
+    variables: serialize(m.variables),
+  }));
+  const record: SaveRecord = { meta, payload: serializedPayload };
   await putSave(record);
   return record;
 }
@@ -132,7 +139,13 @@ export async function overwriteSave(
 
   existing.meta.updatedAt = new Date().toISOString();
   existing.meta.passage = payload.passage;
-  existing.payload = structuredClone(payload);
+  const serializedPayload = deepClone(payload);
+  serializedPayload.variables = serialize(serializedPayload.variables);
+  serializedPayload.history = serializedPayload.history.map((m) => ({
+    ...m,
+    variables: serialize(m.variables),
+  }));
+  existing.payload = serializedPayload;
   await putSave(existing);
   return existing;
 }
@@ -141,7 +154,14 @@ export async function loadSave(
   saveId: string,
 ): Promise<SavePayload | undefined> {
   const record = await getSave(saveId);
-  return record?.payload;
+  if (!record) return undefined;
+  const payload = record.payload;
+  payload.variables = deserialize(payload.variables);
+  payload.history = payload.history.map((m) => ({
+    ...m,
+    variables: deserialize(m.variables),
+  }));
+  return payload;
 }
 
 export async function deleteSaveById(saveId: string): Promise<void> {
@@ -294,7 +314,7 @@ export async function importSave(
   }
 
   // Re-assign a new ID to avoid collisions
-  const record = structuredClone(data.save);
+  const record = deepClone(data.save);
   record.meta.id = crypto.randomUUID();
   record.meta.updatedAt = new Date().toISOString();
 

package/src/store.ts

@@ -10,6 +10,7 @@ import {
   quickSave,
   loadQuickSave,
 } from './saves/save-manager';
+import { deepClone, deserialize } from './class-registry';
 
 export interface HistoryMoment {
   passage: string;
@@ -75,7 +76,7 @@ export const useStoryStore = create<StoryState>()(
         );
       }
 
-      const initialVars = structuredClone(variableDefaults);
+      const initialVars = deepClone(variableDefaults);
 
       set((state) => {
         state.storyData = storyData as StoryData;
@@ -86,7 +87,7 @@ export const useStoryStore = create<StoryState>()(
         state.history = [
           {
             passage: startPassage.name,
-            variables: structuredClone(initialVars),
+            variables: deepClone(initialVars),
             timestamp: Date.now(),
           },
         ];
@@ -130,7 +131,7 @@ export const useStoryStore = create<StoryState>()(
 
         state.history.push({
           passage: passageName,
-          variables: { ...state.variables },
+          variables: deepClone(state.variables),
           timestamp: Date.now(),
         });
         state.historyIndex = state.history.length - 1;
@@ -147,7 +148,7 @@ export const useStoryStore = create<StoryState>()(
         state.historyIndex--;
         const moment = state.history[state.historyIndex];
         state.currentPassage = moment.passage;
-        state.variables = { ...moment.variables };
+        state.variables = deepClone(moment.variables);
         state.temporary = {};
       });
     },
@@ -158,7 +159,7 @@ export const useStoryStore = create<StoryState>()(
         state.historyIndex++;
         const moment = state.history[state.historyIndex];
         state.currentPassage = moment.passage;
-        state.variables = { ...moment.variables };
+        state.variables = deepClone(moment.variables);
         state.temporary = {};
       });
     },
@@ -201,7 +202,7 @@ export const useStoryStore = create<StoryState>()(
       const startPassage = storyData.passagesById.get(storyData.startNode);
       if (!startPassage) return;
 
-      const initialVars = structuredClone(variableDefaults);
+      const initialVars = deepClone(variableDefaults);
 
       set((state) => {
         state.currentPassage = startPassage.name;
@@ -210,7 +211,7 @@ export const useStoryStore = create<StoryState>()(
         state.history = [
           {
             passage: startPassage.name,
-            variables: structuredClone(initialVars),
+            variables: deepClone(initialVars),
             timestamp: Date.now(),
           },
         ];
@@ -244,8 +245,8 @@ export const useStoryStore = create<StoryState>()(
 
       const payload: SavePayload = {
         passage: currentPassage,
-        variables: structuredClone(variables),
-        history: structuredClone(history),
+        variables: deepClone(variables),
+        history: deepClone(history),
         historyIndex,
         visitCounts: { ...visitCounts },
         renderCounts: { ...renderCounts },
@@ -294,8 +295,8 @@ export const useStoryStore = create<StoryState>()(
       } = get();
       return {
         passage: currentPassage,
-        variables: structuredClone(variables),
-        history: structuredClone(history),
+        variables: deepClone(variables),
+        history: deepClone(history),
         historyIndex,
         visitCounts: { ...visitCounts },
         renderCounts: { ...renderCounts },
@@ -305,8 +306,11 @@ export const useStoryStore = create<StoryState>()(
     loadFromPayload: (payload: SavePayload) => {
       set((state) => {
         state.currentPassage = payload.passage;
-        state.variables = payload.variables;
-        state.history = payload.history;
+        state.variables = deserialize(payload.variables);
+        state.history = payload.history.map((m) => ({
+          ...m,
+          variables: deserialize(m.variables),
+        }));
         state.historyIndex = payload.historyIndex;
         state.visitCounts = payload.visitCounts ?? {};
         state.renderCounts = payload.renderCounts ?? {};

package/src/story-api.ts

@@ -2,6 +2,21 @@ import { useStoryStore } from './store';
 import { settings } from './settings';
 import type { SavePayload } from './saves/types';
 import { setTitleGenerator } from './saves/save-manager';
+import { registerClass } from './class-registry';
+import {
+  getActions,
+  getAction,
+  onActionsChanged,
+  type StoryAction,
+} from './action-registry';
+
+export type { StoryAction };
+
+type NavigateCallback = (to: string, from: string) => void;
+type ActionsChangedCallback = () => void;
+type VariableChangedCallback = (
+  changed: Record<string, { from: unknown; to: unknown }>,
+) => void;
 
 export interface StoryAPI {
   get(name: string): unknown;
@@ -23,10 +38,18 @@ export interface StoryAPI {
   hasRenderedAny(...names: string[]): boolean;
   hasRenderedAll(...names: string[]): boolean;
   readonly title: string;
+  readonly passage: string;
   readonly settings: typeof settings;
+  registerClass(name: string, ctor: new (...args: any[]) => any): void;
   readonly saves: {
     setTitleGenerator(fn: (payload: SavePayload) => string): void;
   };
+  getActions(): StoryAction[];
+  performAction(id: string, value?: unknown): void;
+  on(event: 'navigate', callback: NavigateCallback): () => void;
+  on(event: 'actionsChanged', callback: ActionsChangedCallback): () => void;
+  on(event: 'variableChanged', callback: VariableChangedCallback): () => void;
+  waitForActions(): Promise<StoryAction[]>;
 }
 
 function createStoryAPI(): StoryAPI {
@@ -114,13 +137,87 @@ function createStoryAPI(): StoryAPI {
       return useStoryStore.getState().storyData?.name || '';
     },
 
+    get passage(): string {
+      return useStoryStore.getState().currentPassage;
+    },
+
     settings,
 
+    registerClass(name: string, ctor: new (...args: any[]) => any): void {
+      registerClass(name, ctor);
+    },
+
     saves: {
       setTitleGenerator(fn: (payload: SavePayload) => string): void {
         setTitleGenerator(fn);
       },
     },
+
+    getActions(): StoryAction[] {
+      return getActions();
+    },
+
+    performAction(id: string, value?: unknown): void {
+      const action = getAction(id);
+      if (!action) {
+        throw new Error(`spindle: Action "${id}" not found.`);
+      }
+      if (action.disabled) {
+        throw new Error(`spindle: Action "${id}" is disabled.`);
+      }
+      action.perform(value);
+    },
+
+    on(event: string, callback: (...args: any[]) => void): () => void {
+      if (event === 'navigate') {
+        let prev = useStoryStore.getState().currentPassage;
+        return useStoryStore.subscribe((state) => {
+          if (state.currentPassage !== prev) {
+            const from = prev;
+            prev = state.currentPassage;
+            (callback as NavigateCallback)(state.currentPassage, from);
+          }
+        });
+      }
+
+      if (event === 'actionsChanged') {
+        return onActionsChanged(callback as ActionsChangedCallback);
+      }
+
+      if (event === 'variableChanged') {
+        let prevVars = { ...useStoryStore.getState().variables };
+        return useStoryStore.subscribe((state) => {
+          const changed: Record<string, { from: unknown; to: unknown }> = {};
+          let hasChanges = false;
+          const allKeys = new Set([
+            ...Object.keys(prevVars),
+            ...Object.keys(state.variables),
+          ]);
+          for (const key of allKeys) {
+            if (state.variables[key] !== prevVars[key]) {
+              changed[key] = { from: prevVars[key], to: state.variables[key] };
+              hasChanges = true;
+            }
+          }
+          prevVars = { ...state.variables };
+          if (hasChanges) {
+            (callback as VariableChangedCallback)(changed);
+          }
+        });
+      }
+
+      throw new Error(`spindle: Unknown event "${event}".`);
+    },
+
+    waitForActions(): Promise<StoryAction[]> {
+      return new Promise((resolve) => {
+        requestAnimationFrame(() => {
+          requestAnimationFrame(() => {
+            resolve(getActions());
+          });
+        });
+      });
+    },
   };
 }
 

package/src/story-init.ts

@@ -4,6 +4,7 @@ import { buildAST } from './markup/ast';
 import { execute } from './expression';
 import type { ASTNode } from './markup/ast';
 import { setSaveTitlePassage } from './saves/save-manager';
+import { deepClone } from './class-registry';
 
 /**
  * Walk AST nodes from StoryInit and execute {set} and {do} imperatively
@@ -42,8 +43,8 @@ export function executeStoryInit() {
   const tokens = tokenize(storyInit.content);
   const ast = buildAST(tokens);
 
-  const vars = { ...state.variables };
-  const temps = { ...state.temporary };
+  const vars = deepClone(state.variables);
+  const temps = deepClone(state.temporary);
 
   walkAndExecute(ast, vars, temps);
 

package/src/story-variables.ts

@@ -114,7 +114,9 @@ function validateRef(
     }
     const fieldSchema = current.fields.get(parts[i]);
     if (!fieldSchema) {
-      return `Undeclared field: $${parts.slice(0, i + 1).join('.')}`;
+      // Unknown fields on objects are allowed — classes registered via
+      // Story.registerClass() can add methods/getters not in the defaults.
+      return null;
     }
     current = fieldSchema;
   }

package/src/styles.css

@@ -629,6 +629,36 @@ tw-storydata {
   border-color: #90caf9;
 }
 
+/* Macro: meter */
+
+.macro-meter {
+  position: relative;
+  width: 100%;
+  height: 1.4em;
+  background: #2a2a3e;
+  border-radius: 0.3em;
+  overflow: hidden;
+  border: 1px solid #444;
+}
+
+.macro-meter-fill {
+  height: 100%;
+  background: #64b5f6;
+  transition: width 0.3s ease;
+}
+
+.macro-meter-label {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 0.85em;
+  color: #e0e0e0;
+  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.8);
+  pointer-events: none;
+}
+
 /* Markdown wrapper — invisible to layout */
 
 .md {
@@ -777,4 +807,4 @@ tw-storydata {
   50% {
     opacity: 0;
   }
-}
+}

package/src/utils/extract-text.ts

@@ -0,0 +1,8 @@
+import type { ASTNode } from '../markup/ast';
+
+/**
+ * Collect plain text from AST nodes, ignoring non-text nodes.
+ */
+export function collectText(nodes: ASTNode[]): string {
+  return nodes.map((n) => (n.type === 'text' ? n.value : '')).join('');
+}