@rohal12/spindle 0.51.4 → 0.52.1

package/src/prng.ts

@@ -9,11 +9,13 @@
 // Core algorithm
 // ---------------------------------------------------------------------------
 
+const MULBERRY_STEP = 0x6d2b79f5;
+
 /** Mulberry32: fast, high-quality 32-bit PRNG. */
 function mulberry32(seed: number): () => number {
   let t = seed | 0;
   return () => {
-    t = (t + 0x6d2b79f5) | 0;
+    t = (t + MULBERRY_STEP) | 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;
@@ -38,6 +40,8 @@ let enabled = false;
 let currentSeed = '';
 let currentPull = 0;
 let generator: (() => number) | null = null;
+/** Incremented whenever the generator is replaced (init, restore, reset). */
+let generation = 0;
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -69,6 +73,7 @@ export function initPRNG(seed?: string, useEntropy = true): void {
   currentPull = 0;
   generator = mulberry32(hashSeed(resolvedSeed));
   enabled = true;
+  generation++;
 }
 
 /**
@@ -76,26 +81,54 @@ export function initPRNG(seed?: string, useEntropy = true): void {
  * Recreates the generator from the seed and fast-forwards to the saved pull count.
  */
 export function restorePRNG(seed: string, pull: number): void {
+  generation++;
+  moveTo(seed, pull);
+}
+
+/** Recreate the generator at `pull` pulls from `seed`. */
+function moveTo(seed: string, pull: number): void {
   currentSeed = seed;
-  currentPull = 0;
-  generator = mulberry32(hashSeed(seed));
+  // Fast-forward in constant time: each pull adds MULBERRY_STEP to the
+  // 32-bit state, so `pull` pulls add pull × MULBERRY_STEP (mod 2^32). A
+  // loop would hang on the large counts an imported save may hold.
+  const steps = Math.imul(pull % 0x100000000, MULBERRY_STEP);
+  generator = mulberry32((hashSeed(seed) + steps) | 0);
   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 {
+  generation++;
   enabled = false;
   currentSeed = '';
   currentPull = 0;
   generator = null;
 }
 
+/**
+ * Run `fn` without its draws advancing the sequence: the draws it makes are
+ * taken back afterwards (also when it throws), so the next draws return the
+ * same values again. Save and load event handlers run like this, so that
+ * saving or loading never shifts the story's random sequence (a load replays
+ * the saved passage from its entry state, without the save's handlers). A
+ * generator `fn` replaced (a restart or load it started) is kept.
+ */
+export function withoutDraws<T>(fn: () => T): T {
+  const start = { generation, seed: currentSeed, pull: currentPull };
+  try {
+    return fn();
+  } finally {
+    if (
+      enabled &&
+      generation === start.generation &&
+      currentPull !== start.pull
+    ) {
+      moveTo(start.seed, start.pull);
+    }
+  }
+}
+
 /** Returns the current PRNG state for snapshotting, or null if disabled. */
 export function snapshotPRNG(): PRNGSnapshot | null {
   if (!enabled) return null;

package/src/registry.ts

@@ -22,6 +22,41 @@ export function getMacro(name: string): ComponentType<MacroProps> | undefined {
   return registry.get(name.toLowerCase());
 }
 
+/**
+ * What a macro's text form gets: see MacroDefinition.text. Evaluation runs
+ * in the scope of the attribute (or label) being resolved.
+ */
+export interface MacroTextContext {
+  /** Evaluate an expression in the current scope. */
+  evaluate: (expr: string) => unknown;
+  /**
+   * The text of AST nodes (a body or branch) in the current scope, with
+   * `locals` (keys without `@`) added on top of the current locals.
+   */
+  renderText: (nodes: ASTNode[], locals?: Record<string, unknown>) => string;
+}
+
+/** A macro's text form: the string it stands for in text-only markup. */
+export type MacroTextRenderer = (
+  props: MacroProps,
+  ctx: MacroTextContext,
+) => string;
+
+const textRegistry = new Map<string, MacroTextRenderer>();
+
+/** Register (or, with undefined, remove) the text form of a macro. */
+export function registerMacroText(
+  name: string,
+  text: MacroTextRenderer | undefined,
+): void {
+  if (text) textRegistry.set(name.toLowerCase(), text);
+  else textRegistry.delete(name.toLowerCase());
+}
+
+export function getMacroText(name: string): MacroTextRenderer | undefined {
+  return textRegistry.get(name.toLowerCase());
+}
+
 const subMacros = new Set<string>();
 
 export function registerSubMacro(name: string): void {