@rohal12/spindle 0.51.4 → 0.52.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.51.4",
+  "version": "0.52.1",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",
@@ -53,7 +53,7 @@
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p test",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "docs:dev": "vitepress dev docs",
@@ -74,12 +74,15 @@
     "*": "prettier --write --ignore-unknown"
   },
   "devDependencies": {
+    "@fast-check/vitest": "^0.5.0",
     "@preact/preset-vite": "^2.10.5",
     "@rohal12/twee-ts": "^1.14.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.5.0",
     "@types/react": "^19.2.14",
     "@vitest/coverage-v8": "^4.1.2",
+    "fake-indexeddb": "^6.2.5",
+    "fast-check": "^4.10.2",
     "happy-dom": "^20.8.9",
     "husky": "^9.1.7",
     "js-yaml": "^4.1.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/automation/runner.ts

@@ -7,6 +7,7 @@ import type {
 } from './types';
 import type { StoryAPI } from '../story-api';
 import type { StoryAction } from '../action-registry';
+import { errorMessage } from '../utils/error-message';
 
 export interface RunOptions {
   onStep?: (stepIndex: number, step: AutomationStep) => void;
@@ -35,7 +36,7 @@ export async function runAutomation(
     } catch (err) {
       errors.push({
         step: i,
-        message: err instanceof Error ? err.message : String(err),
+        message: errorMessage(err),
       });
       break;
     }

package/src/class-registry.ts

@@ -14,6 +14,20 @@ export function getClassName(ctor: Constructor): string | undefined {
   return ctorToName.get(ctor);
 }
 
+/**
+ * The registered name of the class `value` is an instance of, or undefined.
+ * Looks the constructor up on the prototype, so an own property named
+ * "constructor" (plain data) cannot hide or fake the class.
+ */
+export function registeredClassName(value: object): string | undefined {
+  const proto = Object.getPrototypeOf(value) as {
+    constructor?: unknown;
+  } | null;
+  return proto === null
+    ? undefined
+    : ctorToName.get(proto.constructor as Constructor);
+}
+
 export function clearRegistry(): void {
   registry.clear();
   ctorToName.clear();
@@ -27,6 +41,23 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return proto === Object.prototype || proto === null;
 }
 
+/**
+ * Set an own enumerable property. A "__proto__" key is defined as an own
+ * property (as JSON.parse does) instead of replacing the prototype.
+ */
+function setOwn(target: object, key: string, value: unknown): void {
+  if (key === '__proto__') {
+    Object.defineProperty(target, key, {
+      value,
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  } else {
+    (target as Record<string, unknown>)[key] = value;
+  }
+}
+
 export interface DeepCloneOptions {
   /**
    * Return instances of unregistered classes (DOM nodes, promises, other
@@ -77,8 +108,7 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
     }
 
     // Registered class instance
-    const ctor = obj.constructor as Constructor;
-    const name = ctorToName.get(ctor);
+    const name = registeredClassName(obj);
     if (name !== undefined) {
       const copy = Object.create(Object.getPrototypeOf(obj)) as Record<
         string,
@@ -86,23 +116,23 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
       >;
       seen.set(obj, copy);
       for (const key of Object.keys(obj)) {
-        copy[key] = clone((obj as Record<string, unknown>)[key]);
+        setOwn(copy, key, clone((obj as Record<string, unknown>)[key]));
       }
       return copy;
     }
 
-    // Plain object (or unregistered class — treat as plain)
-    if (!isPlainObject(val) && options.keepUnregistered) return val;
-    if (isPlainObject(val) || typeof val === 'object') {
-      const copy: Record<string, unknown> = {};
-      seen.set(obj, copy);
-      for (const key of Object.keys(obj)) {
-        copy[key] = clone((obj as Record<string, unknown>)[key]);
-      }
-      return copy;
+    // Plain object (or unregistered class — treat as plain). A plain object
+    // keeps its prototype, which may be null.
+    const plain = isPlainObject(val);
+    if (!plain && options.keepUnregistered) return val;
+    const copy = (
+      plain ? Object.create(Object.getPrototypeOf(obj) as object | null) : {}
+    ) as Record<string, unknown>;
+    seen.set(obj, copy);
+    for (const key of Object.keys(obj)) {
+      setOwn(copy, key, clone((obj as Record<string, unknown>)[key]));
     }
-
-    return val;
+    return copy;
   }
 
   return clone(value) as T;
@@ -113,12 +143,23 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
 /**
  * Structural equality over the value types deepClone() supports: primitives,
  * arrays, plain objects, class instances, Date, RegExp, Map and Set (nested
- * at any depth). Map and Set entries are compared in insertion order.
+ * at any depth). Map and Set entries are compared in insertion order. Arrays
+ * are compared by length and index, so a hole equals an undefined element
+ * (deepClone() and save/load turn holes into undefined elements).
  */
-export function deepEqual(
+export function deepEqual(a: unknown, b: unknown): boolean {
+  return equal(a, b, new Map());
+}
+
+/**
+ * `assumed` holds the pairs already being compared: meeting one again (a
+ * cycle) assumes it equal. Every object may pair with several others, since
+ * cycles of different lengths can still unfold to the same value.
+ */
+function equal(
   a: unknown,
   b: unknown,
-  seen: Map<object, object> = new Map(),
+  assumed: Map<object, Set<object>>,
 ): boolean {
   if (Object.is(a, b)) return true;
   if (
@@ -130,8 +171,10 @@ export function deepEqual(
     return false;
   }
   if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) return false;
-  if (seen.get(a) === b) return true;
-  seen.set(a, b);
+  const pairs = assumed.get(a);
+  if (pairs?.has(b)) return true;
+  if (pairs) pairs.add(b);
+  else assumed.set(a, new Set([b]));
 
   if (a instanceof Date) return Object.is(a.getTime(), (b as Date).getTime());
   if (a instanceof RegExp) return String(a) === String(b);
@@ -145,7 +188,16 @@ export function deepEqual(
       !x.done;
       x = ai.next(), y = bi.next()
     ) {
-      if (!deepEqual(x.value, y.value, seen)) return false;
+      if (!equal(x.value, y.value, assumed)) return false;
+    }
+    return true;
+  }
+
+  if (Array.isArray(a)) {
+    const bc = b as unknown[];
+    if (a.length !== bc.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!equal(a[i], bc[i], assumed)) return false;
     }
     return true;
   }
@@ -155,81 +207,122 @@ export function deepEqual(
   const keys = Object.keys(ao);
   if (keys.length !== Object.keys(bo).length) return false;
   for (const key of keys) {
-    if (!(key in bo) || !deepEqual(ao[key], bo[key], seen)) return false;
+    if (!hasOwn(bo, key) || !equal(ao[key], bo[key], assumed)) return false;
   }
   return true;
 }
 
+const hasOwn = (obj: object, key: string): boolean =>
+  Object.prototype.hasOwnProperty.call(obj, key);
+
 // --- Serialize ---
 
 const CLASS_TAG = '__spindle_class__';
 const DATA_TAG = '__spindle_data__';
 
+/** A tagged value, as serialize() writes and deserialize() reads it. */
+const tagged = (name: string, data: Record<string, unknown>) => ({
+  [CLASS_TAG]: name,
+  [DATA_TAG]: data,
+});
+
+/** Numbers JSON text cannot hold (it writes null for them, and 0 for -0). */
+const SPECIAL_NUMBERS: Record<string, number> = {
+  NaN: NaN,
+  Infinity: Infinity,
+  '-Infinity': -Infinity,
+  '-0': -0,
+};
+
+function specialNumberName(value: number): string | undefined {
+  if (Number.isNaN(value)) return 'NaN';
+  if (value === Infinity) return 'Infinity';
+  if (value === -Infinity) return '-Infinity';
+  if (Object.is(value, -0)) return '-0';
+  return undefined;
+}
+
+/**
+ * Turn a story value into data that survives JSON text (saves, exports,
+ * the session) and that deserialize() restores. Date, RegExp, Map, Set and
+ * registered class instances become tagged objects, and so do the values
+ * JSON text would drop or change: undefined (also array holes), NaN,
+ * ±Infinity, -0, bigint, invalid dates, and plain objects with a key named
+ * like the class tag. Throws on circular references and on a property
+ * named "__proto__", which story state cannot hold.
+ */
 export function serialize<T>(value: T): T {
   const seen = new Set<object>();
 
   function ser(val: unknown): unknown {
+    if (val === undefined) return tagged('__Undefined__', {});
+    if (typeof val === 'number') {
+      const name = specialNumberName(val);
+      return name === undefined ? val : tagged('__Number__', { value: name });
+    }
+    if (typeof val === 'bigint') {
+      return tagged('__BigInt__', { value: val.toString() });
+    }
     if (val === null || typeof val !== 'object') return val;
 
-    const obj = val as object;
-    if (seen.has(obj)) {
+    if (seen.has(val)) {
       throw new Error('spindle: Cannot serialize circular references');
     }
-    seen.add(obj);
+    seen.add(val);
+    try {
+      return serObject(val);
+    } finally {
+      seen.delete(val);
+    }
+  }
+
+  function serKeys(obj: object): Record<string, unknown> {
+    const data: Record<string, unknown> = {};
+    for (const key of Object.keys(obj)) {
+      // Story state cannot hold one: replaying history (Immer patches)
+      // would turn it into the object's prototype
+      if (key === '__proto__') {
+        throw new Error('spindle: Cannot save a property named "__proto__"');
+      }
+      data[key] = ser((obj as Record<string, unknown>)[key]);
+    }
+    return data;
+  }
 
+  function serObject(val: object): unknown {
     if (val instanceof Date) {
-      seen.delete(obj);
-      return {
-        [CLASS_TAG]: '__Date__',
-        [DATA_TAG]: { iso: val.toISOString() },
-      };
+      const valid = !Number.isNaN(val.getTime());
+      return tagged('__Date__', { iso: valid ? val.toISOString() : null });
     }
 
     if (val instanceof RegExp) {
-      seen.delete(obj);
-      return {
-        [CLASS_TAG]: '__RegExp__',
-        [DATA_TAG]: { source: val.source, flags: val.flags },
-      };
+      return tagged('__RegExp__', { source: val.source, flags: val.flags });
     }
 
     if (Array.isArray(val)) {
-      const result = val.map((item) => ser(item));
-      seen.delete(obj);
+      // Index by index: map() would keep holes, which JSON writes as null
+      const result: unknown[] = [];
+      for (let i = 0; i < val.length; i++) result.push(ser(val[i]));
       return result;
     }
 
     if (val instanceof Map) {
       const entries = [...val].map(([k, v]) => [ser(k), ser(v)]);
-      seen.delete(obj);
-      return { [CLASS_TAG]: '__Map__', [DATA_TAG]: { entries } };
+      return tagged('__Map__', { entries });
     }
 
     if (val instanceof Set) {
-      const entries = [...val].map((v) => ser(v));
-      seen.delete(obj);
-      return { [CLASS_TAG]: '__Set__', [DATA_TAG]: { entries } };
+      return tagged('__Set__', { entries: [...val].map((v) => ser(v)) });
     }
 
     // Registered class instance
-    const ctor = obj.constructor as Constructor;
-    const name = ctorToName.get(ctor);
-    if (name !== undefined) {
-      const data: Record<string, unknown> = {};
-      for (const key of Object.keys(obj)) {
-        data[key] = ser((obj as Record<string, unknown>)[key]);
-      }
-      seen.delete(obj);
-      return { [CLASS_TAG]: name, [DATA_TAG]: data };
-    }
+    const name = registeredClassName(val);
+    if (name !== undefined) return tagged(name, serKeys(val));
 
-    // Plain object
-    const result: Record<string, unknown> = {};
-    for (const key of Object.keys(obj)) {
-      result[key] = ser((obj as Record<string, unknown>)[key]);
-    }
-    seen.delete(obj);
-    return result;
+    // Plain object. One with a key named like the class tag is wrapped, so
+    // that it is not read back as a tagged value.
+    const data = serKeys(val);
+    return hasOwn(val, CLASS_TAG) ? tagged('__Object__', data) : data;
   }
 
   return ser(value) as T;
@@ -238,6 +331,13 @@ export function serialize<T>(value: T): T {
 // --- Deserialize ---
 
 export function deserialize<T>(value: T): T {
+  function deserKeys(target: object, data: Record<string, unknown>): object {
+    for (const key of Object.keys(data)) {
+      setOwn(target, key, deser(data[key]));
+    }
+    return target;
+  }
+
   function deser(val: unknown): unknown {
     if (val === null || typeof val !== 'object') return val;
 
@@ -247,25 +347,31 @@ export function deserialize<T>(value: T): T {
 
     const obj = val as Record<string, unknown>;
 
-    // Tagged class instance (from serialized data)
+    // Tagged value (from serialized data)
     if (CLASS_TAG in obj && DATA_TAG in obj) {
       const name = obj[CLASS_TAG] as string;
       const data = obj[DATA_TAG] as Record<string, unknown>;
 
-      // Built-in types
-      if (name === '__Date__') {
-        return new Date(data.iso as string);
-      }
-      if (name === '__RegExp__') {
-        return new RegExp(data.source as string, data.flags as string);
-      }
-      if (name === '__Map__') {
-        const entries = data.entries as [unknown, unknown][];
-        return new Map(entries.map(([k, v]) => [deser(k), deser(v)]));
-      }
-      if (name === '__Set__') {
-        const entries = data.entries as unknown[];
-        return new Set(entries.map((v) => deser(v)));
+      // Built-in types and values JSON cannot hold
+      switch (name) {
+        case '__Date__':
+          return new Date(data.iso === null ? NaN : (data.iso as string));
+        case '__RegExp__':
+          return new RegExp(data.source as string, data.flags as string);
+        case '__Map__': {
+          const entries = data.entries as [unknown, unknown][];
+          return new Map(entries.map(([k, v]) => [deser(k), deser(v)]));
+        }
+        case '__Set__':
+          return new Set((data.entries as unknown[]).map((v) => deser(v)));
+        case '__Undefined__':
+          return undefined;
+        case '__Number__':
+          return SPECIAL_NUMBERS[data.value as string];
+        case '__BigInt__':
+          return BigInt(data.value as string);
+        case '__Object__':
+          return deserKeys({}, data);
       }
 
       const ctor = registry.get(name);
@@ -273,17 +379,9 @@ export function deserialize<T>(value: T): T {
         console.warn(
           `spindle: Class "${name}" not registered. Falling back to plain object.`,
         );
-        const plain: Record<string, unknown> = {};
-        for (const key of Object.keys(data)) {
-          plain[key] = deser(data[key]);
-        }
-        return plain;
+        return deserKeys({}, data);
       }
-      const instance = Object.create(ctor.prototype) as Record<string, unknown>;
-      for (const key of Object.keys(data)) {
-        instance[key] = deser(data[key]);
-      }
-      return instance;
+      return deserKeys(Object.create(ctor.prototype) as object, data);
     }
 
     // Already-live built-in — pass through as-is, so deserializing an
@@ -298,17 +396,12 @@ export function deserialize<T>(value: T): T {
     }
 
     // Already-live registered class instance — pass through as-is
-    const ctor = (obj as object).constructor as Constructor;
-    if (ctorToName.has(ctor)) {
+    if (registeredClassName(obj) !== undefined) {
       return val;
     }
 
     // Plain object
-    const result: Record<string, unknown> = {};
-    for (const key of Object.keys(obj)) {
-      result[key] = deser(obj[key]);
-    }
-    return result;
+    return deserKeys({}, obj);
   }
 
   return deser(value) as T;
@@ -323,10 +416,12 @@ function isDataRecord(value: unknown): value is Record<string, unknown> {
 /**
  * Whether `value` is serialized data that deserialize() can restore: every
  * tagged value has the shape serialize() writes for its tag (a valid ISO
- * date, a compilable RegExp, Map entries as `[key, value]` pairs, Set
- * entries as an array, class data as an object), at any depth. Use it on
- * data from outside the running story, such as an imported save, before
- * storing it. Tags of unregistered classes pass; they load as plain objects.
+ * date or null, a compilable RegExp, Map entries as `[key, value]` pairs,
+ * Set entries as an array, a special number's name, a bigint in decimal,
+ * class data as an object) and no object has a "__proto__" key, at any
+ * depth. Use it on data from outside the running story, such as an
+ * imported save, before storing it. Tags of unregistered classes pass;
+ * they load as plain objects.
  */
 export function isDeserializable(value: unknown): boolean {
   // Objects on the current path; JSON can't hold cycles, and deserialize()
@@ -342,13 +437,18 @@ export function isDeserializable(value: unknown): boolean {
     return ok;
   }
 
+  // A "__proto__" key is refused: serialize() never writes one, and story
+  // state cannot hold one (see serialize)
+  const checkKeys = (obj: Record<string, unknown>): boolean =>
+    Object.keys(obj).every((key) => key !== '__proto__' && check(obj[key]));
+
   function checkObject(val: object): boolean {
-    if (Array.isArray(val)) return val.every(check);
+    // Array.from: every() skips the holes of a sparse array, which
+    // deserialize() restores as undefined (and a Map cannot take as entries)
+    if (Array.isArray(val)) return Array.from(val).every(check);
 
     const obj = val as Record<string, unknown>;
-    if (!(CLASS_TAG in obj && DATA_TAG in obj)) {
-      return Object.keys(obj).every((key) => check(obj[key]));
-    }
+    if (!(CLASS_TAG in obj && DATA_TAG in obj)) return checkKeys(obj);
 
     const name = obj[CLASS_TAG];
     const data = obj[DATA_TAG];
@@ -357,8 +457,9 @@ export function isDeserializable(value: unknown): boolean {
     switch (name) {
       case '__Date__':
         return (
-          typeof data.iso === 'string' &&
-          !Number.isNaN(new Date(data.iso).getTime())
+          data.iso === null ||
+          (typeof data.iso === 'string' &&
+            !Number.isNaN(new Date(data.iso).getTime()))
         );
       case '__RegExp__':
         if (typeof data.source !== 'string' || typeof data.flags !== 'string')
@@ -372,7 +473,7 @@ export function isDeserializable(value: unknown): boolean {
       case '__Map__':
         return (
           Array.isArray(data.entries) &&
-          data.entries.every(
+          Array.from(data.entries).every(
             (entry: unknown) =>
               Array.isArray(entry) &&
               entry.length === 2 &&
@@ -381,9 +482,19 @@ export function isDeserializable(value: unknown): boolean {
           )
         );
       case '__Set__':
-        return Array.isArray(data.entries) && data.entries.every(check);
+        return (
+          Array.isArray(data.entries) && Array.from(data.entries).every(check)
+        );
+      case '__Undefined__':
+        return true;
+      case '__Number__':
+        return (
+          typeof data.value === 'string' && hasOwn(SPECIAL_NUMBERS, data.value)
+        );
+      case '__BigInt__':
+        return typeof data.value === 'string' && /^-?\d+$/.test(data.value);
       default:
-        return Object.keys(data).every((key) => check(data[key]));
+        return checkKeys(data);
     }
   }
 

package/src/components/Passage.tsx

@@ -13,6 +13,7 @@ import type { Passage as PassageData } from '../parser';
 import { sourceLocationOf } from '../utils/source-location';
 import { emitFromRender } from '../event-emitter';
 import { markPassageRendered } from '../passage-render-state';
+import { errorMessage } from '../utils/error-message';
 
 /**
  * Parsed AST per passage. The renderer keys children by AST node identity,
@@ -69,8 +70,7 @@ export function Passage({
       return (
         <div class="error">
           Error parsing passage &ldquo;{passage.name}&rdquo;
-          {sourceLocationOf(passage)}:{' '}
-          {err instanceof Error ? err.message : String(err)}
+          {sourceLocationOf(passage)}: {errorMessage(err)}
         </div>
       );
     }