@rohal12/spindle 0.3.2 → 0.4.0

package/src/expression.ts

@@ -1,35 +1,88 @@
 import type { StoryState } from './store';
 import { useStoryStore } from './store';
+import type { Passage } from './parser';
+import { random, randomInt } from './prng';
 
-const fnCache = new Map<string, Function>();
+interface ExpressionFns {
+  currentPassage: () => Passage | undefined;
+  previousPassage: () => Passage | undefined;
+  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;
+  random: () => number;
+  randomInt: (min: number, max: number) => number;
+}
+
+type CompiledExpression = (
+  variables: Record<string, unknown>,
+  temporary: Record<string, unknown>,
+  __fns: ExpressionFns,
+) => unknown;
+
+const FN_CACHE_MAX = 500;
+const fnCache = new Map<string, CompiledExpression>();
 
 /**
  * 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).
  */
+const VAR_RE = /\$(\w+)/g;
+const TEMP_RE = /\b_(\w+)/g;
+
 function transform(expr: string): string {
   return expr
-    .replace(/\$(\w+)/g, 'variables["$1"]')
-    .replace(/\b_(\w+)/g, 'temporary["$1"]');
+    .replace(VAR_RE, 'variables["$1"]')
+    .replace(TEMP_RE, 'temporary["$1"]');
 }
 
 const preamble =
-  'const {visited,hasVisited,hasVisitedAny,hasVisitedAll,rendered,hasRendered,hasRenderedAny,hasRenderedAll}=__fns;';
+  'const {currentPassage,previousPassage,visited,hasVisited,hasVisitedAny,hasVisitedAll,rendered,hasRendered,hasRenderedAny,hasRenderedAll,random,randomInt}=__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);
+function getOrCompile(key: string, body: string): CompiledExpression {
+  const cached = fnCache.get(key);
+  if (cached) {
+    // Move to end for LRU ordering (Map preserves insertion order)
+    fnCache.delete(key);
+    fnCache.set(key, cached);
+    return cached;
+  }
+  const fn = new Function(
+    'variables',
+    'temporary',
+    '__fns',
+    preamble + body,
+  ) as CompiledExpression;
+  fnCache.set(key, fn);
+  if (fnCache.size > FN_CACHE_MAX) {
+    // Evict oldest entry
+    const oldest = fnCache.keys().next().value;
+    if (oldest !== undefined) fnCache.delete(oldest);
   }
   return fn;
 }
 
+let cachedFns: ExpressionFns | null = null;
+let cachedVisitCounts: Record<string, number> | null = null;
+let cachedRenderCounts: Record<string, number> | null = null;
+
 export function buildExpressionFns() {
   const state = useStoryStore.getState();
   const { visitCounts, renderCounts } = state;
 
+  if (
+    cachedFns &&
+    cachedVisitCounts === visitCounts &&
+    cachedRenderCounts === renderCounts
+  ) {
+    return cachedFns;
+  }
+
   const visited = (name: string): number => visitCounts[name] ?? 0;
   const hasVisited = (name: string): boolean => visited(name) > 0;
   const hasVisitedAny = (...names: string[]): boolean =>
@@ -44,7 +97,20 @@ export function buildExpressionFns() {
   const hasRenderedAll = (...names: string[]): boolean =>
     names.every((n) => rendered(n) > 0);
 
-  return {
+  const currentPassage = (): Passage | undefined => {
+    const s = useStoryStore.getState();
+    return s.storyData?.passages.get(s.currentPassage);
+  };
+  const previousPassage = (): Passage | undefined => {
+    const s = useStoryStore.getState();
+    if (s.historyIndex <= 0) return undefined;
+    const prevName = s.history[s.historyIndex - 1]?.passage;
+    return prevName ? s.storyData?.passages.get(prevName) : undefined;
+  };
+
+  cachedFns = {
+    currentPassage,
+    previousPassage,
     visited,
     hasVisited,
     hasVisitedAny,
@@ -53,7 +119,13 @@ export function buildExpressionFns() {
     hasRendered,
     hasRenderedAny,
     hasRenderedAll,
+    random,
+    randomInt,
   };
+  cachedVisitCounts = visitCounts;
+  cachedRenderCounts = renderCounts;
+
+  return cachedFns;
 }
 
 /**

package/src/hooks/use-merged-locals.ts

@@ -0,0 +1,26 @@
+import { useContext, useMemo } from 'preact/hooks';
+import { useStoryStore } from '../store';
+import { LocalsContext } from '../markup/render';
+
+/**
+ * Merge store variables/temporary with LocalsContext values.
+ * Locals prefixed with `$` go into variables, `_` into temporary.
+ */
+export function useMergedLocals(): readonly [
+  Record<string, unknown>,
+  Record<string, unknown>,
+] {
+  const variables = useStoryStore((s) => s.variables);
+  const temporary = useStoryStore((s) => s.temporary);
+  const locals = useContext(LocalsContext);
+
+  return useMemo(() => {
+    const vars = { ...variables };
+    const temps = { ...temporary };
+    for (const [key, val] of Object.entries(locals)) {
+      if (key.startsWith('$')) vars[key.slice(1)] = val;
+      else if (key.startsWith('_')) temps[key.slice(1)] = val;
+    }
+    return [vars, temps] as const;
+  }, [variables, temporary, locals]);
+}

package/src/markup/ast.ts

@@ -87,10 +87,10 @@ export function buildAST(tokens: Token[]): ASTNode[] {
 
   function current(): ASTNode[] {
     if (stack.length === 0) return root;
-    const top = stack[stack.length - 1].node;
+    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.branches[top.branches.length - 1]!.children;
     }
     return top.children;
   }
@@ -145,7 +145,7 @@ export function buildAST(tokens: Token[]): ASTNode[] {
             );
           }
 
-          const top = stack[stack.length - 1];
+          const top = stack[stack.length - 1]!;
           if (top.node.type !== 'html' || top.node.tag !== token.tag) {
             const expected =
               top.node.type === 'html'
@@ -181,7 +181,7 @@ export function buildAST(tokens: Token[]): ASTNode[] {
             );
           }
 
-          const top = stack[stack.length - 1];
+          const top = stack[stack.length - 1]!;
           if (top.node.type !== 'macro' || top.node.name !== token.name) {
             const expected =
               top.node.type === 'macro'
@@ -199,9 +199,9 @@ export function buildAST(tokens: Token[]): ASTNode[] {
 
         // Handle branch macros (elseif/else, case/default, next)
         if (BRANCH_PARENT[token.name]) {
-          const expectedParent = BRANCH_PARENT[token.name];
+          const expectedParent = BRANCH_PARENT[token.name]!;
           const topNode =
-            stack.length > 0 ? stack[stack.length - 1].node : null;
+            stack.length > 0 ? stack[stack.length - 1]!.node : null;
           if (
             !topNode ||
             topNode.type !== 'macro' ||
@@ -263,11 +263,16 @@ export function buildAST(tokens: Token[]): ASTNode[] {
         }
         break;
       }
+
+      default: {
+        const _exhaustive: never = token;
+        throw new Error(`Unknown token type: ${(_exhaustive as Token).type}`);
+      }
     }
   }
 
   if (stack.length > 0) {
-    const unclosed = stack[stack.length - 1];
+    const unclosed = stack[stack.length - 1]!;
     const label =
       unclosed.node.type === 'html'
         ? `<${unclosed.node.tag}>`

package/src/markup/render.tsx

@@ -38,10 +38,12 @@ import { getWidget } from '../widgets/widget-registry';
 import { getMacro } from '../registry';
 import { markdownToHtml } from './markdown';
 import { h } from 'preact';
-import type { ASTNode, MacroNode } from './ast';
+import type { ASTNode, Branch, MacroNode } from './ast';
 
 export const LocalsContext = createContext<Record<string, unknown>>({});
 
+const EMPTY_BRANCHES: Branch[] = [];
+
 /**
  * Convert an HTML string (from micromark) to Preact VNodes,
  * replacing <span data-tw="N"> placeholder elements with pre-rendered components.
@@ -77,7 +79,7 @@ function convertDomNode(
     }
 
     // Convert attributes
-    const props: Record<string, any> = { key };
+    const props: Record<string, string | number> = { key };
     for (const attr of Array.from(el.attributes)) {
       props[attr.name] = attr.value;
     }
@@ -134,7 +136,7 @@ function renderMacro(node: MacroNode, key: number) {
       return (
         <If
           key={key}
-          branches={node.branches!}
+          branches={node.branches ?? EMPTY_BRANCHES}
         />
       );
 
@@ -354,7 +356,7 @@ function renderMacro(node: MacroNode, key: number) {
         <Switch
           key={key}
           rawArgs={node.rawArgs}
-          branches={node.branches!}
+          branches={node.branches ?? EMPTY_BRANCHES}
         />
       );
 
@@ -364,7 +366,7 @@ function renderMacro(node: MacroNode, key: number) {
           key={key}
           rawArgs={node.rawArgs}
           children={node.children}
-          branches={node.branches!}
+          branches={node.branches ?? EMPTY_BRANCHES}
           className={node.className}
           id={node.id}
         />
@@ -488,6 +490,11 @@ function renderSingleNode(
         { key, ...node.attributes },
         node.children.length > 0 ? renderNodes(node.children) : undefined,
       );
+
+    default: {
+      const _exhaustive: never = node;
+      return _exhaustive;
+    }
   }
 }
 
@@ -526,7 +533,7 @@ export function renderNodes(nodes: ASTNode[]): preact.ComponentChildren {
   let combined = '';
 
   for (let i = 0; i < nodes.length; i++) {
-    const node = nodes[i];
+    const node = nodes[i]!;
     if (node.type === 'text') {
       combined += node.value;
     } else {

package/src/markup/tokenizer.ts

@@ -196,10 +196,10 @@ function parseSelectors(
   let i = startIdx;
 
   while (i < input.length && (input[i] === '.' || input[i] === '#')) {
-    const prefix = input[i];
+    const prefix = input[i]!;
     i++; // skip the . or #
     const nameStart = i;
-    while (i < input.length && /[a-zA-Z0-9_-]/.test(input[i])) i++;
+    while (i < input.length && /[a-zA-Z0-9_-]/.test(input[i]!)) i++;
     if (i > nameStart) {
       const name = input.slice(nameStart, i);
       if (prefix === '.') {
@@ -225,7 +225,7 @@ function parseHtmlAttributes(
 
   while (j < input.length) {
     // Skip whitespace
-    while (j < input.length && /\s/.test(input[j])) j++;
+    while (j < input.length && /\s/.test(input[j]!)) j++;
     // End of tag?
     if (
       j >= input.length ||
@@ -236,7 +236,7 @@ function parseHtmlAttributes(
 
     // Read attribute name
     const attrStart = j;
-    while (j < input.length && /[a-zA-Z0-9_-]/.test(input[j])) j++;
+    while (j < input.length && /[a-zA-Z0-9_-]/.test(input[j]!)) j++;
     const attrName = input.slice(attrStart, j);
     if (!attrName) break;
 
@@ -244,7 +244,7 @@ function parseHtmlAttributes(
     if (input[j] === '=') {
       j++; // skip =
       if (input[j] === '"' || input[j] === "'") {
-        const quote = input[j];
+        const quote = input[j]!;
         j++; // skip opening quote
         const valStart = j;
         while (j < input.length && input[j] !== quote) j++;
@@ -253,7 +253,7 @@ function parseHtmlAttributes(
       } else {
         // Unquoted value
         const valStart = j;
-        while (j < input.length && /[^\s>]/.test(input[j])) j++;
+        while (j < input.length && /[^\s>]/.test(input[j]!)) j++;
         attributes[attrName] = input.slice(valStart, j);
       }
     } else {
@@ -367,7 +367,7 @@ export function tokenize(input: string): Token[] {
           // {.class#id $variable.field}
           i = afterSelectors + 1;
           const nameStart = i;
-          while (i < input.length && /[\w.]/.test(input[i])) i++;
+          while (i < input.length && /[\w.]/.test(input[i]!)) i++;
           const name = input.slice(nameStart, i);
 
           if (input[i] === '}') {
@@ -395,7 +395,7 @@ export function tokenize(input: string): Token[] {
           // {.class#id _temporary.field}
           i = afterSelectors + 1;
           const nameStart = i;
-          while (i < input.length && /[\w.]/.test(input[i])) i++;
+          while (i < input.length && /[\w.]/.test(input[i]!)) i++;
           const name = input.slice(nameStart, i);
 
           if (input[i] === '}') {
@@ -468,7 +468,7 @@ export function tokenize(input: string): Token[] {
         flushText(i);
         i += 2;
         const nameStart = i;
-        while (i < input.length && /[\w.]/.test(input[i])) i++;
+        while (i < input.length && /[\w.]/.test(input[i]!)) i++;
         const name = input.slice(nameStart, i);
 
         if (input[i] === '}') {
@@ -494,7 +494,7 @@ export function tokenize(input: string): Token[] {
         flushText(i);
         i += 2;
         const nameStart = i;
-        while (i < input.length && /[\w.]/.test(input[i])) i++;
+        while (i < input.length && /[\w.]/.test(input[i]!)) i++;
         const name = input.slice(nameStart, i);
 
         if (input[i] === '}') {
@@ -572,14 +572,14 @@ export function tokenize(input: string): Token[] {
 
       // Read tag name
       const tagStart = j;
-      while (j < input.length && /[a-zA-Z0-9]/.test(input[j])) j++;
+      while (j < input.length && /[a-zA-Z0-9]/.test(input[j]!)) j++;
       const tag = input.slice(tagStart, j).toLowerCase();
 
       // Only handle known HTML tags
       if (tag && HTML_TAGS.has(tag)) {
         if (isClose) {
           // Closing tag: skip whitespace, expect >
-          while (j < input.length && /\s/.test(input[j])) j++;
+          while (j < input.length && /\s/.test(input[j]!)) j++;
           if (input[j] === '>') {
             j++;
             flushText(start);

package/src/parser.ts

@@ -2,6 +2,7 @@ export interface Passage {
   pid: number;
   name: string;
   tags: string[];
+  metadata: Record<string, string>;
   content: string;
 }
 
@@ -53,7 +54,21 @@ export function parseStoryData(): StoryData {
       .filter((t) => t.length > 0);
     const content = el.textContent || '';
 
-    const passage: Passage = { pid, name: passageName, tags, content };
+    const metadata: Record<string, string> = {};
+    const skipAttrs = new Set(['pid', 'name', 'tags']);
+    for (const attr of el.attributes) {
+      if (!skipAttrs.has(attr.name)) {
+        metadata[attr.name] = attr.value;
+      }
+    }
+
+    const passage: Passage = {
+      pid,
+      name: passageName,
+      tags,
+      metadata,
+      content,
+    };
     passages.set(passageName, passage);
     passagesById.set(pid, passage);
   }

package/src/prng.ts

@@ -0,0 +1,128 @@
+/**
+ * Seedable PRNG for Spindle — Mulberry32 algorithm.
+ *
+ * Provides deterministic random number generation that survives save/load
+ * cycles via a pull-counter approach: recreate from seed, fast-forward N pulls.
+ */
+
+// ---------------------------------------------------------------------------
+// Core algorithm
+// ---------------------------------------------------------------------------
+
+/** Mulberry32: fast, high-quality 32-bit PRNG. */
+function mulberry32(seed: number): () => number {
+  let t = seed | 0;
+  return () => {
+    t = (t + 0x6d2b79f5) | 0;
+    let r = Math.imul(t ^ (t >>> 15), t | 1);
+    r ^= r + Math.imul(r ^ (r >>> 7), r | 61);
+    return ((r ^ (r >>> 14)) >>> 0) / 0x100000000;
+  };
+}
+
+/** FNV-1a hash — converts a string seed to a 32-bit integer. */
+function hashSeed(seed: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < seed.length; i++) {
+    h ^= seed.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h;
+}
+
+// ---------------------------------------------------------------------------
+// Module state
+// ---------------------------------------------------------------------------
+
+let enabled = false;
+let currentSeed = '';
+let currentPull = 0;
+let generator: (() => number) | null = null;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface PRNGSnapshot {
+  readonly seed: string;
+  readonly pull: number;
+}
+
+/**
+ * Initialize the PRNG.
+ * @param seed   Optional seed string. If omitted, a random seed is generated.
+ * @param useEntropy  If true (default), mix `Date.now()` and `Math.random()`
+ *                    into the seed for uniqueness across playthroughs.
+ *                    Set to false for fully deterministic sequences.
+ */
+export function initPRNG(seed?: string, useEntropy = true): void {
+  let resolvedSeed: string;
+  if (seed === undefined) {
+    resolvedSeed = String(Date.now()) + String(Math.random());
+  } else if (useEntropy) {
+    resolvedSeed = seed + '|' + Date.now() + '|' + Math.random();
+  } else {
+    resolvedSeed = seed;
+  }
+
+  currentSeed = resolvedSeed;
+  currentPull = 0;
+  generator = mulberry32(hashSeed(resolvedSeed));
+  enabled = true;
+}
+
+/**
+ * Restore PRNG state from a snapshot (used on save/load).
+ * Recreates the generator from the seed and fast-forwards to the saved pull count.
+ */
+export function restorePRNG(seed: string, pull: number): void {
+  currentSeed = seed;
+  currentPull = 0;
+  generator = mulberry32(hashSeed(seed));
+  enabled = true;
+
+  // Fast-forward
+  for (let i = 0; i < pull; i++) {
+    generator();
+  }
+  currentPull = pull;
+}
+
+/** Disable the PRNG (used on restart before StoryInit re-enables it). */
+export function resetPRNG(): void {
+  enabled = false;
+  currentSeed = '';
+  currentPull = 0;
+  generator = null;
+}
+
+/** Returns the current PRNG state for snapshotting, or null if disabled. */
+export function snapshotPRNG(): PRNGSnapshot | null {
+  if (!enabled) return null;
+  return { seed: currentSeed, pull: currentPull };
+}
+
+/** Returns a seeded random number [0, 1), or falls back to Math.random(). */
+export function random(): number {
+  if (!enabled || !generator) return Math.random();
+  currentPull++;
+  return generator();
+}
+
+/** Returns a random integer between min and max (inclusive). */
+export function randomInt(min: number, max: number): number {
+  if (min > max) [min, max] = [max, min];
+  return Math.floor(random() * (max - min + 1)) + min;
+}
+
+export function isPRNGEnabled(): boolean {
+  return enabled;
+}
+
+export function getPRNGSeed(): string {
+  return currentSeed;
+}
+
+export function getPRNGPull(): number {
+  return currentPull;
+}

package/src/saves/save-manager.ts

@@ -137,17 +137,22 @@ export async function overwriteSave(
   const existing = await getSave(saveId);
   if (!existing) return undefined;
 
-  existing.meta.updatedAt = new Date().toISOString();
-  existing.meta.passage = payload.passage;
   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;
+  const updated: SaveRecord = {
+    meta: {
+      ...existing.meta,
+      updatedAt: new Date().toISOString(),
+      passage: payload.passage,
+    },
+    payload: serializedPayload,
+  };
+  await putSave(updated);
+  return updated;
 }
 
 export async function loadSave(
@@ -174,9 +179,15 @@ export async function renameSave(
 ): Promise<void> {
   const record = await getSave(saveId);
   if (!record) return;
-  record.meta.title = newTitle;
-  record.meta.updatedAt = new Date().toISOString();
-  await putSave(record);
+  const updated: SaveRecord = {
+    ...record,
+    meta: {
+      ...record.meta,
+      title: newTitle,
+      updatedAt: new Date().toISOString(),
+    },
+  };
+  await putSave(updated);
 }
 
 // --- Grouped Retrieval ---
@@ -200,8 +211,12 @@ export async function getSavesGrouped(
   const groups = new Map<string, SaveRecord[]>();
   for (const save of allSaves) {
     const pid = save.meta.playthroughId;
-    if (!groups.has(pid)) groups.set(pid, []);
-    groups.get(pid)!.push(save);
+    const existing = groups.get(pid);
+    if (existing) {
+      existing.push(save);
+    } else {
+      groups.set(pid, [save]);
+    }
   }
 
   // Sort saves within each group newest-first

package/src/saves/types.ts

@@ -1,4 +1,5 @@
 import type { HistoryMoment } from '../store';
+import type { PRNGSnapshot } from '../prng';
 
 export interface SavePayload {
   passage: string;
@@ -7,6 +8,7 @@ export interface SavePayload {
   historyIndex: number;
   visitCounts?: Record<string, number>;
   renderCounts?: Record<string, number>;
+  prng?: PRNGSnapshot | null;
 }
 
 export interface SaveMeta {
@@ -38,3 +40,32 @@ export interface SaveExport {
   exportedAt: string;
   save: SaveRecord;
 }
+
+export function isSaveExport(value: unknown): value is SaveExport {
+  if (typeof value !== 'object' || value === null) return false;
+  const obj = value as Record<string, unknown>;
+  if (obj.version !== 1 || typeof obj.ifid !== 'string') return false;
+  if (typeof obj.save !== 'object' || obj.save === null) return false;
+
+  const save = obj.save as Record<string, unknown>;
+  if (typeof save.meta !== 'object' || save.meta === null) return false;
+  if (typeof save.payload !== 'object' || save.payload === null) return false;
+
+  const meta = save.meta as Record<string, unknown>;
+  if (typeof meta.id !== 'string' || typeof meta.passage !== 'string')
+    return false;
+  if (typeof meta.ifid !== 'string') return false;
+  if (typeof meta.playthroughId !== 'string') return false;
+  if (typeof meta.createdAt !== 'string') return false;
+  if (typeof meta.updatedAt !== 'string') return false;
+  if (typeof meta.title !== 'string') return false;
+
+  const payload = save.payload as Record<string, unknown>;
+  if (typeof payload.passage !== 'string') return false;
+  if (!Array.isArray(payload.history)) return false;
+  if (typeof payload.historyIndex !== 'number') return false;
+  if (typeof payload.variables !== 'object' || payload.variables === null)
+    return false;
+
+  return true;
+}