@rohal12/spindle 0.52.9 → 0.53.0

package/src/components/macros/Do.tsx

@@ -9,10 +9,12 @@ defineMacro({
     const code = ctx.collectText(children);
 
     ctx.hooks.useLayoutEffect(() => {
+      // Before the code runs: it may navigate away from this passage
+      const location = ctx.sourceLocation();
       try {
         ctx.mutate(code);
       } catch (err) {
-        logMacroError('do', err);
+        logMacroError('do', err, location);
       }
     }, []);
 

package/src/components/macros/Goto.tsx

@@ -1,6 +1,7 @@
 import { useStoryStore } from '../../store';
 import { defineMacro } from '../../define-macro';
 import { evaluatePassageName } from './macro-args';
+import { logMacroError } from './MacroError';
 
 defineMacro({
   name: 'goto',
@@ -8,9 +9,18 @@ defineMacro({
   parameters: [{ name: 'passage', type: 'expression', required: true }],
   render(_props, ctx) {
     ctx.hooks.useLayoutEffect(() => {
-      useStoryStore
-        .getState()
-        .navigate(evaluatePassageName(ctx.args.passage, ctx.evaluate!));
+      // Reported like an error in {do}: thrown out of an effect, it would
+      // abort the rest of the render's effects (e.g. the session could not
+      // be written because the state holds a function). The location is
+      // this passage's, taken before navigating away from it
+      const location = ctx.sourceLocation();
+      try {
+        useStoryStore
+          .getState()
+          .navigate(evaluatePassageName(ctx.args.passage, ctx.evaluate!));
+      } catch (err) {
+        logMacroError('goto', err, location);
+      }
     }, []);
 
     return null;

package/src/components/macros/MacroError.tsx

@@ -19,12 +19,18 @@ export function MacroError({
   );
 }
 
-/** Log an error in the macro `{label}` (its name, or name and arguments). */
-export function logMacroError(label: string, error: unknown): void {
-  console.error(
-    `spindle: Error in {${label}}${currentSourceLocation()}:`,
-    error,
-  );
+/**
+ * Log an error in the macro `{label}` (its name, or name and arguments) at
+ * `location`, the source location of the macro's passage. Take it before
+ * running the code that failed (see currentSourceLocation): code that
+ * navigates changes the current passage.
+ */
+export function logMacroError(
+  label: string,
+  error: unknown,
+  location: string = currentSourceLocation(),
+): void {
+  console.error(`spindle: Error in {${label}}${location}:`, error);
 }
 
 /**
@@ -38,11 +44,12 @@ export function useRunOnce(macro: string, rawArgs: string, effect: () => void) {
   const failure = useRef<{ error: unknown } | null>();
   if (failure.current === undefined) {
     failure.current = null;
+    const location = currentSourceLocation();
     try {
       effect();
     } catch (error) {
       failure.current = { error };
-      logMacroError(`${macro} ${rawArgs}`, error);
+      logMacroError(`${macro} ${rawArgs}`, error, location);
     }
   }
 

package/src/components/macros/SaveManager.tsx

@@ -17,7 +17,7 @@ import {
   renameSave,
   exportSave,
   importSave,
-  deserializePayload,
+  decodeSavePayload,
   saveWithHooks,
   type PlaythroughGroup,
 } from '../../saves/save-manager';
@@ -160,7 +160,7 @@ export function SaveManagerContent() {
       // Stored records hold serialized variables; the store expects live
       // ones. The game moves to the save's playthrough.
       loadFromPayload(
-        deserializePayload(save.payload),
+        decodeSavePayload(save.payload),
         undefined,
         save.meta.playthroughId,
       );

package/src/runtime-errors.ts

@@ -0,0 +1,65 @@
+// Runtime errors shown to the player on the page (see RuntimeErrors), for
+// errors that would otherwise only reach the browser console.
+
+import { errorMessage } from './utils/error-message';
+
+/** A runtime error shown on the page until the player dismisses it. */
+export interface RuntimeError {
+  /** Identifies the entry, for dismissing it. */
+  id: number;
+  /** What failed, for the player (e.g. "Could not save the game…"). */
+  context: string;
+  /** The error message, without the "spindle: " prefix. */
+  message: string;
+  /** How often the same error happened since it was shown. */
+  count: number;
+}
+
+let errors: readonly RuntimeError[] = [];
+let nextId = 1;
+const listeners = new Set<() => void>();
+
+function update(next: readonly RuntimeError[]): void {
+  errors = next;
+  for (const listener of listeners) listener();
+}
+
+/**
+ * Show `error` on the page, after `context` (what failed). The same error
+ * again, while it is shown, counts up instead of adding an entry. Logging
+ * it to the console is up to the caller.
+ */
+export function showRuntimeError(context: string, error: unknown): void {
+  const message = errorMessage(error).replace(/^spindle: /, '');
+  const same = errors.find(
+    (e) => e.context === context && e.message === message,
+  );
+  update(
+    same
+      ? errors.map((e) => (e === same ? { ...e, count: e.count + 1 } : e))
+      : [...errors, { id: nextId++, context, message, count: 1 }],
+  );
+}
+
+/** Remove the shown error `id`. */
+export function dismissRuntimeError(id: number): void {
+  update(errors.filter((e) => e.id !== id));
+}
+
+/** Remove every shown error. */
+export function clearRuntimeErrors(): void {
+  if (errors.length) update([]);
+}
+
+/** The errors shown now, oldest first. */
+export function getRuntimeErrors(): readonly RuntimeError[] {
+  return errors;
+}
+
+/** Call `listener` whenever the shown errors change; returns unsubscribe. */
+export function subscribeRuntimeErrors(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}

package/src/saves/format.ts

@@ -0,0 +1,199 @@
+// The stored form of a save payload: what saves, exports and the session
+// hold, and the version of that form.
+
+import { deserialize, serialize } from '../class-registry';
+import { createCounts } from '../utils/namespace';
+import type { SavePayload } from './types';
+
+/**
+ * The version of the save format this build writes. Saves, exports and the
+ * session carry it. Bump it when the stored form changes, and add a
+ * migration from the previous version to MIGRATIONS.
+ */
+export const SAVE_FORMAT_VERSION = 1;
+
+/**
+ * A payload as stored: `data` is the payload serialized in one piece (see
+ * serialize() in class-registry.ts), so values the history moments share
+ * are stored once, and cycles survive.
+ */
+export interface EncodedPayload {
+  formatVersion: number;
+  data: string;
+}
+
+/** A save, export or session from a version of Spindle this one cannot read. */
+export class IncompatibleSaveError extends Error {
+  constructor() {
+    super('This save was made by an incompatible version of Spindle');
+    this.name = 'IncompatibleSaveError';
+  }
+}
+
+/**
+ * Migrations of the stored data: MIGRATIONS[v] turns the `data` of format
+ * version v into that of version v + 1. Version 1 is the first versioned
+ * format; data from before it has no version and is refused.
+ */
+const MIGRATIONS: Readonly<Record<number, (data: string) => string>> = {};
+
+/** Throw an IncompatibleSaveError unless this build reads format `version`. */
+export function checkFormatVersion(
+  version: unknown,
+): asserts version is number {
+  if (
+    typeof version !== 'number' ||
+    !Number.isInteger(version) ||
+    version < 1 ||
+    version > SAVE_FORMAT_VERSION
+  ) {
+    throw new IncompatibleSaveError();
+  }
+}
+
+/** Bring `data` of format `version` up to SAVE_FORMAT_VERSION. */
+export function migrate(version: number, data: string): string {
+  checkFormatVersion(version);
+  let current = data;
+  for (let v = version; v < SAVE_FORMAT_VERSION; v++) {
+    const step = MIGRATIONS[v];
+    if (!step) throw new IncompatibleSaveError();
+    current = step(current);
+  }
+  return current;
+}
+
+/**
+ * The passage counters as a Map: a passage may be named "__proto__", which
+ * serialize() refuses as an object key (as every story-state key).
+ */
+const countsToMap = (counts: Record<string, number> | undefined) =>
+  counts && new Map(Object.entries(counts));
+
+/**
+ * The error of serialize() with its path told as a story variable:
+ * `(at .variables.inv[0])` becomes `(at $inv[0])`, and a value only an
+ * earlier history moment holds `(at $inv[0] in history moment 3)`.
+ */
+function variablePathError(err: unknown): unknown {
+  if (!(err instanceof TypeError)) return err;
+  const message = err.message
+    .replace(/\(at \.variables(?=[.[]|\))/, '(at $')
+    .replace(
+      /\(at \.history\[(\d+)\]\.variables(.*)\)$/,
+      (_, i: string, path: string) => `(at $${path} in history moment ${i})`,
+    )
+    .replace(/\(at \$\.?/, '(at $');
+  return message === err.message ? err : new TypeError(message);
+}
+
+/**
+ * The stored form of `payload`. Throws, naming the variable, when the
+ * payload holds a value a save cannot (see serialize()).
+ */
+export function encodePayload(payload: SavePayload): EncodedPayload {
+  try {
+    return {
+      formatVersion: SAVE_FORMAT_VERSION,
+      data: serialize({
+        ...payload,
+        visitCounts: countsToMap(payload.visitCounts),
+        renderCounts: countsToMap(payload.renderCounts),
+      }),
+    };
+  } catch (err) {
+    throw variablePathError(err);
+  }
+}
+
+/** Thrown for stored data that is not a payload this format can hold. */
+const invalid = () => new Error('Invalid save data');
+
+/** A plain object or one without a prototype (a variable namespace). */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) return false;
+  const proto = Object.getPrototypeOf(value) as object | null;
+  return proto === Object.prototype || proto === null;
+}
+
+/** Absent, null, or a `{ seed, pull }` PRNG snapshot. */
+function isOptionalPRNGSnapshot(value: unknown): boolean {
+  if (value == null) return true;
+  return (
+    isRecord(value) &&
+    typeof value.seed === 'string' &&
+    typeof value.pull === 'number' &&
+    Number.isInteger(value.pull) &&
+    value.pull >= 0
+  );
+}
+
+const isMoment = (value: unknown): boolean =>
+  isRecord(value) &&
+  typeof value.passage === 'string' &&
+  isRecord(value.variables) &&
+  typeof value.timestamp === 'number' &&
+  isOptionalPRNGSnapshot(value.prng);
+
+const isCountsMap = (value: unknown): boolean =>
+  value === undefined ||
+  (value instanceof Map &&
+    [...value.keys()].every((k) => typeof k === 'string'));
+
+/**
+ * Whether a deserialized payload is well formed: every history moment is,
+ * and `historyIndex` is an integer that points at a moment of the payload's
+ * passage.
+ */
+function isPayload(value: unknown): value is Record<string, unknown> {
+  if (!isRecord(value)) return false;
+  if (typeof value.passage !== 'string' || !isRecord(value.variables)) {
+    return false;
+  }
+  const { history, historyIndex } = value;
+  // Array.from: every() skips the holes of a sparse array
+  if (!Array.isArray(history) || history.length === 0) return false;
+  if (!Array.from(history).every(isMoment)) return false;
+  if (
+    typeof historyIndex !== 'number' ||
+    !Number.isInteger(historyIndex) ||
+    historyIndex < 0 ||
+    historyIndex >= history.length ||
+    (history[historyIndex] as { passage: string }).passage !== value.passage
+  ) {
+    return false;
+  }
+  return (
+    isCountsMap(value.visitCounts) &&
+    isCountsMap(value.renderCounts) &&
+    isOptionalPRNGSnapshot(value.prng)
+  );
+}
+
+const mapToCounts = (counts: unknown) =>
+  counts instanceof Map
+    ? createCounts(Object.fromEntries(counts as Map<string, unknown>))
+    : undefined;
+
+/**
+ * The live payload of a stored one: class instances and built-ins
+ * restored. Throws an IncompatibleSaveError when `encoded` has no format
+ * version or one this build cannot read (saves from before versioning, or
+ * from a newer Spindle), and an error when its data is malformed.
+ */
+export function decodePayload(encoded: unknown): SavePayload {
+  if (typeof encoded !== 'object' || encoded === null) throw invalid();
+  const { formatVersion, data } = encoded as Record<string, unknown>;
+  checkFormatVersion(formatVersion);
+  if (typeof data !== 'string') throw invalid();
+  const body = deserialize(migrate(formatVersion, data));
+  if (!isPayload(body)) throw invalid();
+  const payload = {
+    ...body,
+    visitCounts: mapToCounts(body.visitCounts),
+    renderCounts: mapToCounts(body.renderCounts),
+  } as SavePayload;
+  if (payload.visitCounts === undefined) delete payload.visitCounts;
+  if (payload.renderCounts === undefined) delete payload.renderCounts;
+  return payload;
+}

package/src/saves/save-manager.ts

@@ -7,9 +7,14 @@ import type {
   SaveExport,
   StorageInfo,
 } from './types';
-import { estimatePayloadBytes, isSaveExport, isSavePayload } from './types';
+import { checkSaveExport, estimatePayloadBytes } from './types';
+import {
+  decodePayload,
+  encodePayload,
+  IncompatibleSaveError,
+  SAVE_FORMAT_VERSION,
+} from './format';
 import { getBackend, resetBackend } from './storage';
-import { serialize, deserialize } from '../class-registry';
 import { deepClone } from '../structural';
 import { emit } from '../event-emitter';
 import { withoutDraws } from '../prng';
@@ -272,30 +277,12 @@ export function saveWithHooks<T>(
 
 // --- Save CRUD ---
 
-/**
- * `payload` with `convert` applied to its live variables and to those of
- * every history moment.
- */
-function mapVariables(
-  payload: SavePayload,
-  convert: (variables: Record<string, unknown>) => Record<string, unknown>,
-): SavePayload {
-  return {
-    ...payload,
-    variables: convert(payload.variables),
-    history: payload.history.map((m) => ({
-      ...m,
-      variables: convert(m.variables),
-    })),
-  };
-}
-
-/** The record to store for a save: `payload` serialized, and its size. */
+/** The record to store for a save: `payload` encoded, and its size. */
 function storedRecord(meta: SaveMeta, payload: SavePayload): SaveRecord {
-  const serialized = mapVariables(deepClone(payload), serialize);
+  const encoded = encodePayload(payload);
   return {
-    meta: { ...meta, estimatedBytes: estimatePayloadBytes(serialized) },
-    payload: serialized,
+    meta: { ...meta, estimatedBytes: estimatePayloadBytes(encoded) },
+    payload: encoded,
   };
 }
 
@@ -372,17 +359,16 @@ async function overwriteSaveNow(
 }
 
 /**
- * Turn a stored (serialized) payload into a live one, restoring class
- * instances and built-ins. Returns a new payload; the stored one is left
- * untouched. Payloads handed to the store's `loadFromPayload()` must be live.
+ * The live payload of a stored save, if there is one (see decodePayload:
+ * throws for a save of an incompatible format). Payloads handed to the
+ * store's `loadFromPayload()` must be live.
  */
-export function deserializePayload(payload: SavePayload): SavePayload {
-  return mapVariables(payload, deserialize);
-}
-
-/** The live payload of a stored save, if there is one. */
 const livePayload = (record: SaveRecord | undefined) =>
-  record && deserializePayload(record.payload);
+  record && decodePayload(record.payload);
+
+/** The live payload of a stored record's payload (see decodePayload). */
+export const decodeSavePayload = (payload: SaveRecord['payload']) =>
+  decodePayload(payload);
 
 export const loadSave = readingSave(livePayload);
 
@@ -650,7 +636,7 @@ export function loadSlotSave(
   return inOrder(async () => {
     const record = await slotRecord(ifid, slot);
     if (!record) return undefined;
-    const payload = deserializePayload(record.payload);
+    const payload = decodePayload(record.payload);
     const { playthroughId } = record.meta;
     if (playthroughId) await adoptPlaythroughNow(ifid, playthroughId);
     return { payload, playthroughId };
@@ -715,28 +701,35 @@ export const deleteSlotSave = queued(async (ifid: string, slot?: string) => {
 const SESSION_KEY_PREFIX = 'spindle.session.';
 
 /**
- * Write a pre-serialized session payload to sessionStorage.
- * Callers are responsible for serializing variables (see persistSession in store.ts).
+ * Write the session payload to sessionStorage, encoded like a save (see
+ * encodePayload). Throws, like a save, when the state holds a value a save
+ * cannot (a function, an instance of an unregistered class, a unique
+ * symbol); the session then keeps its previous copy.
  */
-export function saveSession(ifid: string, data: unknown): void {
+export function saveSession(ifid: string, payload: SavePayload): void {
+  const text = JSON.stringify(encodePayload(payload));
   try {
-    sessionStorage.setItem(
-      `${SESSION_KEY_PREFIX}${ifid}`,
-      JSON.stringify(data),
-    );
+    sessionStorage.setItem(`${SESSION_KEY_PREFIX}${ifid}`, text);
   } catch {
     // sessionStorage unavailable or full — silently ignore
   }
 }
 
+/**
+ * The live payload of the stored session, if there is one that loads. A
+ * session written by an incompatible version of Spindle is dropped with a
+ * warning, and the story starts fresh.
+ */
 export function loadSession(ifid: string): SavePayload | undefined {
   try {
     const raw = sessionStorage.getItem(`${SESSION_KEY_PREFIX}${ifid}`);
     if (!raw) return undefined;
-    const parsed: unknown = JSON.parse(raw);
-    if (!isSavePayload(parsed)) return undefined;
-    return deserializePayload(parsed);
-  } catch {
+    return decodePayload(JSON.parse(raw));
+  } catch (err) {
+    if (err instanceof IncompatibleSaveError) {
+      console.warn(`spindle: ${err.message}; the session was not restored.`);
+      clearSession(ifid);
+    }
     return undefined;
   }
 }
@@ -755,7 +748,7 @@ export function clearSession(ifid: string): void {
 function toExport(record: SaveRecord | undefined): SaveExport | undefined {
   if (!record) return undefined;
   return {
-    version: 1,
+    formatVersion: SAVE_FORMAT_VERSION,
     ifid: record.meta.ifid,
     exportedAt: new Date().toISOString(),
     save: record,
@@ -769,23 +762,15 @@ export const exportSave = readingSave(toExport);
  * a fresh save ID, and the playthrough record created if it doesn't exist yet.
  * The returned record is not stored yet.
  */
-async function prepareImport(
-  data: SaveExport,
-  ifid: string,
-): Promise<SaveRecord> {
-  if (data.version !== 1) {
-    throw new Error(`Unsupported save version: ${data.version}`);
-  }
+async function prepareImport(data: unknown, ifid: string): Promise<SaveRecord> {
+  // Callers may pass parsed JSON; check the format version and the full
+  // structure before anything is stored or replaced
+  checkSaveExport(data);
   if (data.ifid !== ifid) {
     throw new Error(
       `Save is from a different story (expected IFID ${ifid}, got ${data.ifid})`,
     );
   }
-  // Callers may pass parsed JSON; check the full structure before anything
-  // is stored or replaced
-  if (!isSaveExport(data)) {
-    throw new Error('Invalid save file format');
-  }
 
   // Re-assign a new ID to avoid collisions
   const record = deepClone(data.save);
@@ -804,10 +789,7 @@ async function prepareImport(
   return record;
 }
 
-export function importSave(
-  data: SaveExport,
-  ifid: string,
-): Promise<SaveRecord> {
+export function importSave(data: unknown, ifid: string): Promise<SaveRecord> {
   return inOrder(async () => {
     const record = await prepareImport(data, ifid);
     await (await getBackend()).putSave(record);
@@ -828,7 +810,7 @@ export const exportSlotSave = readingSlot(toExport);
  * and slot index consistent.
  */
 export function importSlotSave(
-  data: SaveExport,
+  data: unknown,
   ifid: string,
   slot?: string,
 ): Promise<SaveInfo> {