@rohal12/spindle 0.52.0 → 0.52.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.52.0",
+  "version": "0.52.2",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",
@@ -56,6 +56,7 @@
     "typecheck": "tsc --noEmit && tsc --noEmit -p test",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "duplication": "bun scripts/duplication.ts jscpd && bun scripts/duplication.ts cpd && bun scripts/duplication.ts fallow",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
@@ -82,10 +83,12 @@
     "@types/react": "^19.2.14",
     "@vitest/coverage-v8": "^4.1.2",
     "fake-indexeddb": "^6.2.5",
+    "fallow": "3.31.0",
     "fast-check": "^4.10.2",
     "happy-dom": "^20.8.9",
     "husky": "^9.1.7",
     "js-yaml": "^4.1.1",
+    "jscpd": "5.4.0",
     "lint-staged": "^16.4.0",
     "playwright": "^1.58.2",
     "prettier": "^3.8.1",

package/src/action-registry.ts

@@ -29,9 +29,35 @@ export interface StoryAction {
   perform: (value?: unknown) => void;
 }
 
-const actions = new Map<string, StoryAction>();
+/** A mounted control's hold on its action ID. */
+export interface ActionRegistration {
+  /**
+   * Replace what the action exposes, in place: one `actionsChanged`
+   * notification, and it keeps its position in getActions().
+   */
+  update(action: StoryAction): void;
+  /** Remove this registration, and nothing that has taken its ID since. */
+  unregister(): void;
+}
+
+interface Entry {
+  action: StoryAction;
+}
+
+/**
+ * The registrations holding each ID, oldest first; the newest is the one
+ * listed. Generated IDs don't collide, but author IDs can, and one control's
+ * cleanup must not remove another control holding the same ID (#233).
+ */
+const actions = new Map<string, Entry[]>();
 const idCounters = new Map<string, number>();
 
+/**
+ * The counters reset on every navigation, so a passage's controls get the
+ * same IDs each time it is shown. Controls that stay mounted across
+ * navigations (e.g. in StoryInterface) keep theirs, so allocation skips every
+ * ID still registered (#233).
+ */
 export function generateActionId(
   type: ActionType,
   key: string,
@@ -40,35 +66,61 @@ export function generateActionId(
   if (authorId) return authorId;
 
   const base = `${type}:${key}`;
-  const count = (idCounters.get(base) ?? 0) + 1;
+  let count = idCounters.get(base) ?? 0;
+  let id: string;
+  do {
+    count++;
+    id = count === 1 ? base : `${base}:${count}`;
+  } while (actions.has(id));
   idCounters.set(base, count);
-  return count === 1 ? base : `${base}:${count}`;
+  return id;
 }
 
-export function registerAction(action: StoryAction): () => void {
-  actions.set(action.id, action);
+export function registerAction(action: StoryAction): ActionRegistration {
+  const id = action.id;
+  const entry: Entry = { action };
+  const entries = actions.get(id);
+  if (entries) {
+    console.warn(
+      `spindle: two mounted controls share the action ID "${id}"; ` +
+        'Story.getActions() lists only the newer one.',
+    );
+    entries.push(entry);
+  } else {
+    actions.set(id, [entry]);
+  }
   notify();
-  return () => {
-    actions.delete(action.id);
-    notify();
-  };
-}
 
-export function updateAction(action: StoryAction): () => void {
-  actions.set(action.id, action);
-  notify();
-  return () => {
-    actions.delete(action.id);
-    notify();
+  return {
+    update(next) {
+      const current = actions.get(id);
+      if (!current?.includes(entry)) return;
+      entry.action = next;
+      // An older registration of a shared ID isn't listed
+      if (current[current.length - 1] === entry) notify();
+    },
+    unregister() {
+      const current = actions.get(id);
+      const index = current ? current.indexOf(entry) : -1;
+      if (!current || index === -1) return;
+      current.splice(index, 1);
+      if (current.length === 0) actions.delete(id);
+      if (index === current.length) notify(); // it was the listed one
+    },
   };
 }
 
 export function getActions(): StoryAction[] {
-  return Array.from(actions.values());
+  return Array.from(actions.values(), listed);
 }
 
 export function getAction(id: string): StoryAction | undefined {
-  return actions.get(id);
+  const entries = actions.get(id);
+  return entries && listed(entries);
+}
+
+function listed(entries: Entry[]): StoryAction {
+  return entries[entries.length - 1]!.action;
 }
 
 export function clearActions(): void {

package/src/components/macros/Computed.tsx

@@ -7,6 +7,13 @@ import { defineMacro } from '../../define-macro';
 import { MacroError } from './MacroError';
 import { checkVariableName } from '../../utils/namespace';
 
+/**
+ * The previous output before the first successful evaluation. Distinct from
+ * every value an expression can produce, so the first result is always
+ * applied, even `undefined`; a first evaluation that throws leaves it unset.
+ */
+const UNSET: unique symbol = Symbol('unset');
+
 function parseComputedArgs(rawArgs: string): { target: string; expr: string } {
   const trimmed = rawArgs.trim();
 
@@ -44,10 +51,11 @@ function parseComputedArgs(rawArgs: string): { target: string; expr: string } {
 /**
  * Evaluate `expr` against the current values — the store's state and the
  * enclosing locals scope's live values (`getLocals`) — and write the result
- * to the target if it changed. Reading live values rather than the render's
- * snapshot means the first computation sees a local a preceding {set} just
- * assigned (the scope's context value only catches up on its re-render), and
- * the first computation and later recomputations read the same source.
+ * to the target if it differs from the previous output (always, the first
+ * time). Reading live values rather than the render's snapshot means the
+ * first computation sees a local a preceding {set} just assigned (the scope's
+ * context value only catches up on its re-render), and the first computation
+ * and later recomputations read the same source.
  */
 function computeAndApply(
   expr: string,
@@ -114,7 +122,7 @@ defineMacro({
     const name = target.slice(1);
     const localsUpdate = isLocal ? ctx.update : null;
 
-    const prevOutput = ctx.hooks.useRef<unknown>(undefined);
+    const prevOutput = ctx.hooks.useRef<unknown>(UNSET);
 
     const ran = ctx.hooks.useRef(false);
     if (!ran.current) {

package/src/components/macros/Set.tsx

@@ -5,7 +5,8 @@ defineMacro({
   name: 'set',
   render({ rawArgs }, ctx) {
     const ran = ctx.hooks.useRef(false);
-    const error = ctx.hooks.useRef<unknown>(null);
+    // Boxed: anything can be thrown, including null and other falsy values
+    const failure = ctx.hooks.useRef<{ error: unknown } | null>(null);
 
     if (!ran.current) {
       ran.current = true;
@@ -13,7 +14,7 @@ defineMacro({
       try {
         ctx.mutate(rawArgs);
       } catch (err) {
-        error.current = err;
+        failure.current = { error: err };
         console.error(
           `spindle: Error in {set ${rawArgs}}${ctx.sourceLocation()}:`,
           err,
@@ -21,11 +22,11 @@ defineMacro({
       }
     }
 
-    if (error.current) {
+    if (failure.current) {
       return (
         <MacroError
           macro="set"
-          error={error.current}
+          error={failure.current.error}
         />
       );
     }

package/src/components/macros/Unset.tsx

@@ -6,7 +6,8 @@ defineMacro({
   name: 'unset',
   render({ rawArgs }, ctx) {
     const ran = ctx.hooks.useRef(false);
-    const error = ctx.hooks.useRef<unknown>(null);
+    // Boxed: anything can be thrown, including null and other falsy values
+    const failure = ctx.hooks.useRef<{ error: unknown } | null>(null);
 
     if (!ran.current) {
       ran.current = true;
@@ -29,7 +30,7 @@ defineMacro({
           );
         }
       } catch (err) {
-        error.current = err;
+        failure.current = { error: err };
         console.error(
           `spindle: Error in {unset ${rawArgs}}${ctx.sourceLocation()}:`,
           err,
@@ -37,11 +38,11 @@ defineMacro({
       }
     }
 
-    if (error.current) {
+    if (failure.current) {
       return (
         <MacroError
           macro="unset"
-          error={error.current}
+          error={failure.current.error}
         />
       );
     }

package/src/execute-mutation.ts

@@ -82,7 +82,7 @@ export function frozenCopy<T>(value: T): T {
  * replaced as a whole, since their elements have no stable identity to
  * merge by (a shift moves every index).
  */
-function isMergeable(value: unknown): value is Record<string, unknown> {
+export function isMergeable(value: unknown): value is Record<string, unknown> {
   return (
     typeof value === 'object' &&
     value !== null &&

package/src/expression.ts

@@ -10,6 +10,7 @@ import {
   isNamespace,
   type Namespace,
 } from './utils/namespace';
+import { countOf, type Counts } from './utils/counts';
 
 interface ExpressionFns {
   currentPassage: () => Passage | undefined;
@@ -116,8 +117,8 @@ function getOrCompile(key: string, body: string): CompiledExpression {
 }
 
 let cachedFns: ExpressionFns | null = null;
-let cachedVisitCounts: Record<string, number> | null = null;
-let cachedRenderCounts: Record<string, number> | null = null;
+let cachedVisitCounts: Counts | null = null;
+let cachedRenderCounts: Counts | null = null;
 
 export function buildExpressionFns() {
   const state = useStoryStore.getState();
@@ -132,7 +133,7 @@ export function buildExpressionFns() {
   }
 
   const visited = (name?: string): number =>
-    visitCounts[name ?? useStoryStore.getState().currentPassage] ?? 0;
+    countOf(visitCounts, name ?? useStoryStore.getState().currentPassage);
   const hasVisited = (name?: string): boolean => visited(name) > 0;
   const hasVisitedAny = (...names: string[]): boolean =>
     names.some((n) => visited(n) > 0);
@@ -140,7 +141,7 @@ export function buildExpressionFns() {
     names.every((n) => visited(n) > 0);
 
   const rendered = (name?: string): number =>
-    renderCounts[name ?? useStoryStore.getState().currentPassage] ?? 0;
+    countOf(renderCounts, name ?? useStoryStore.getState().currentPassage);
   const hasRendered = (name?: string): boolean => rendered(name) > 0;
   const hasRenderedAny = (...names: string[]): boolean =>
     names.some((n) => rendered(n) > 0);

package/src/hooks/use-action.ts

@@ -1,8 +1,8 @@
 import { useLayoutEffect, useRef } from 'preact/hooks';
 import {
   registerAction,
-  updateAction,
   generateActionId,
+  type ActionRegistration,
   type ActionType,
   type StoryAction,
 } from '../action-registry';
@@ -47,8 +47,14 @@ export function useAction(opts: UseActionOptions): string {
     return action;
   };
 
-  // Registered for the component's lifetime.
-  useLayoutEffect(() => registerAction(buildAction()), [id]);
+  // Registered for the component's lifetime. Unregistering removes only this
+  // registration, never another control's holding the same ID (#233).
+  const registration = useRef<ActionRegistration | null>(null);
+  useLayoutEffect(() => {
+    const own = registerAction(buildAction());
+    registration.current = own;
+    return () => own.unregister();
+  }, [id]);
 
   // When what the action exposes changes (e.g. an input's value), replace it
   // in place: one `actionsChanged` notification, and it keeps its position in
@@ -60,7 +66,7 @@ export function useAction(opts: UseActionOptions): string {
       registered.current = true; // the registration above is current
       return;
     }
-    updateAction(buildAction());
+    registration.current?.update(buildAction());
   }, [
     opts.type,
     opts.label,

package/src/index.tsx

@@ -201,7 +201,8 @@ export function boot() {
   }
 
   // Reset action ID counters on every navigation (the passage remounts even
-  // when its name is unchanged)
+  // when its name is unchanged). Controls that stay mounted, e.g. in
+  // StoryInterface, keep their IDs: allocation skips IDs still registered.
   let prevNavigationId = useStoryStore.getState().navigationId;
   useStoryStore.subscribe((state) => {
     if (state.navigationId !== prevNavigationId) {

package/src/markup/ast.ts

@@ -242,8 +242,13 @@ export function buildAST(tokens: Token[]): ASTNode[] {
         }
 
         // Handle branch macros (elseif/else, case/default, next)
-        if (BRANCH_PARENT[name]) {
-          const expectedParent = BRANCH_PARENT[name]!;
+        const expectedParent = Object.prototype.hasOwnProperty.call(
+          BRANCH_PARENT,
+          name,
+        )
+          ? BRANCH_PARENT[name]
+          : undefined;
+        if (expectedParent) {
           const topNode =
             stack.length > 0 ? stack[stack.length - 1]!.node : null;
           if (

package/src/prng.ts

@@ -40,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
@@ -71,6 +73,7 @@ export function initPRNG(seed?: string, useEntropy = true): void {
   currentPull = 0;
   generator = mulberry32(hashSeed(resolvedSeed));
   enabled = true;
+  generation++;
 }
 
 /**
@@ -78,6 +81,12 @@ 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;
   // 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
@@ -90,12 +99,36 @@ export function restorePRNG(seed: string, pull: number): void {
 
 /** 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/saves/save-manager.ts

@@ -11,6 +11,7 @@ import { isSaveExport, isSavePayload } from './types';
 import { getBackend, resetBackend } from './storage';
 import { deepClone, serialize, deserialize } from '../class-registry';
 import { emit } from '../event-emitter';
+import { withoutDraws } from '../prng';
 
 type TitleGenerator = (payload: SavePayload) => string;
 
@@ -220,6 +221,10 @@ export function establishPlaythrough(
  * that captures the payload after them, so the capture can tell which
  * variables the hooks changed (the store's `beginSave`).
  *
+ * Random numbers the hooks draw do not advance the story's PRNG (see
+ * withoutDraws()): the game goes on with the sequence a load of the save
+ * continues with, which replays the saved passage without the hooks.
+ *
  * The hook and capture run synchronously, but an error they throw (a failing
  * hook, an unserializable payload) rejects the returned promise like a failed
  * write rather than escaping to the caller.
@@ -232,10 +237,10 @@ export function saveWithHooks<T>(
 ): Promise<T> {
   try {
     const capture = beginCapture();
-    emit('beforesave', slot, custom);
+    withoutDraws(() => emit('beforesave', slot, custom));
     const payload = capture();
     return write(payload).then((result) => {
-      emit('aftersave', slot);
+      withoutDraws(() => emit('aftersave', slot));
       return result;
     });
   } catch (err) {

package/src/settings.ts

@@ -1,4 +1,5 @@
 import { useStoryStore } from './store';
+import { createNamespace, ownValue } from './utils/namespace';
 
 export interface ToggleConfig {
   label: string;
@@ -25,7 +26,9 @@ export type SettingDef =
   | { type: 'range'; config: RangeConfig };
 
 const definitions = new Map<string, SettingDef>();
-let values: Record<string, unknown> = {};
+// No prototype, so a setting may be named `constructor` or `__proto__`:
+// every name is plain storage (see utils/namespace.ts)
+let values: Record<string, unknown> = createNamespace();
 let storageLoaded = false;
 let unsubscribeStoryData: (() => void) | null = null;
 
@@ -65,7 +68,7 @@ function loadFromStorage(): void {
         parsed !== null &&
         !Array.isArray(parsed)
       ) {
-        values = { ...values, ...parsed };
+        values = createNamespace(values, parsed);
       }
     }
   } catch {
@@ -76,7 +79,7 @@ function loadFromStorage(): void {
 export const settings = {
   addToggle(name: string, config: ToggleConfig): void {
     definitions.set(name, { type: 'toggle', config });
-    if (!(name in values)) {
+    if (!Object.prototype.hasOwnProperty.call(values, name)) {
       values[name] = config.default;
     }
     loadFromStorage();
@@ -84,7 +87,7 @@ export const settings = {
 
   addList(name: string, config: ListConfig): void {
     definitions.set(name, { type: 'list', config });
-    if (!(name in values)) {
+    if (!Object.prototype.hasOwnProperty.call(values, name)) {
       values[name] = config.default;
     }
     loadFromStorage();
@@ -92,28 +95,28 @@ export const settings = {
 
   addRange(name: string, config: RangeConfig): void {
     definitions.set(name, { type: 'range', config });
-    if (!(name in values)) {
+    if (!Object.prototype.hasOwnProperty.call(values, name)) {
       values[name] = config.default;
     }
     loadFromStorage();
   },
 
   get(name: string): unknown {
-    return values[name];
+    return ownValue(values, name);
   },
 
   getToggle(name: string): boolean {
-    const v = values[name];
+    const v = ownValue(values, name);
     return typeof v === 'boolean' ? v : false;
   },
 
   getList(name: string): string {
-    const v = values[name];
+    const v = ownValue(values, name);
     return typeof v === 'string' ? v : '';
   },
 
   getRange(name: string): number {
-    const v = values[name];
+    const v = ownValue(values, name);
     return typeof v === 'number' ? v : 0;
   },