@rohal12/spindle 0.59.8 → 0.59.10

package/src/hooks/use-story-fields.ts

@@ -1,7 +1,20 @@
-import { useRef } from 'preact/hooks';
+import { createContext } from 'preact';
+import { useContext, useRef } from 'preact/hooks';
 import { shallow } from 'zustand/vanilla/shallow';
 import { useStoryStore, type StoryState } from '../store';
 
+/**
+ * Tells the components below when to keep the state they last rendered with,
+ * given the store's current state: an owner (a click body, see
+ * useDetachedBody; a passage on its way out, see PassageDisplay) provides it
+ * so that a branch skipped earlier cannot run against later state (#351,
+ * #352). It runs inside the store's own notification, before the owner could
+ * re-render, which is why it is a predicate and not a flag.
+ */
+export const FrozenStateContext = createContext<
+  ((state: StoryState) => boolean) | null
+>(null);
+
 /**
  * Story state fields `keys`, re-rendering when any of them changes (as one
  * useStoryStore() selector per field would). The result keeps its identity
@@ -11,7 +24,9 @@ export function useStoryFields<K extends keyof StoryState>(
   ...keys: K[]
 ): Pick<StoryState, K> {
   const prev = useRef<Pick<StoryState, K>>();
+  const freeze = useContext(FrozenStateContext);
   return useStoryStore((s) => {
+    if (prev.current && freeze?.(s)) return prev.current;
     const next = {} as Pick<StoryState, K>;
     for (const key of keys) next[key] = s[key];
     return shallow(prev.current, next) ? prev.current! : (prev.current = next);

package/src/markup/render.tsx

@@ -679,14 +679,21 @@ function nodeKey(node: ASTNode): string {
 function renderMacro(node: MacroNode, key: string) {
   if (isSubMacro(node.name)) return null;
 
+  // What an invocation passes on to a widget and to a built-in macro alike
+  const invocation = {
+    rawArgs: node.rawArgs,
+    className: node.className,
+    id: node.id,
+  };
+
   const widget = getWidget(node.name);
   if (widget) {
     return (
       <WidgetInvocation
         key={key}
+        {...invocation}
         body={widget.body}
         params={widget.params}
-        rawArgs={node.rawArgs}
         invocationChildren={node.children}
       />
     );
@@ -697,9 +704,7 @@ function renderMacro(node: MacroNode, key: string) {
     return (
       <Component
         key={key}
-        rawArgs={node.rawArgs}
-        className={node.className}
-        id={node.id}
+        {...invocation}
         children={node.children}
         branches={node.branches}
       />

package/src/saves/format.ts

@@ -135,6 +135,14 @@ const isMoment = (value: unknown): boolean =>
   typeof value.timestamp === 'number' &&
   isOptionalPRNGSnapshot(value.prng);
 
+const isWatchers = (value: unknown): boolean =>
+  value === undefined ||
+  (Array.isArray(value) &&
+    Array.from(value).every(
+      (w) =>
+        isRecord(w) && typeof w.condition === 'string' && isRecord(w.options),
+    ));
+
 const isCountsMap = (value: unknown): boolean =>
   value === undefined ||
   (value instanceof Map &&
@@ -166,7 +174,8 @@ function isPayload(value: unknown): value is Record<string, unknown> {
   return (
     isCountsMap(value.visitCounts) &&
     isCountsMap(value.renderCounts) &&
-    isOptionalPRNGSnapshot(value.prng)
+    isOptionalPRNGSnapshot(value.prng) &&
+    isWatchers(value.watchers)
   );
 }
 

package/src/saves/save-manager.ts

@@ -134,18 +134,20 @@ async function startNewPlaythroughNow(
   id: string = randomUUID(),
 ): Promise<string> {
   const backend = await getBackend();
-  const num = await nextPlaythroughNumber(ifid);
-
-  const record: PlaythroughRecord = {
-    id,
-    ifid,
-    createdAt: new Date().toISOString(),
-    label: `Playthrough ${num}`,
-  };
-
-  await backend.putPlaythrough(record);
-  await backend.setMeta(playthroughCountKey(ifid), num);
+  // Taking the next number is a read-modify-write other tabs do too
+  await withTabLock(`spindle-playthrough-count:${ifid}`, async () => {
+    const num = await nextPlaythroughNumber(ifid);
+    const record: PlaythroughRecord = {
+      id,
+      ifid,
+      createdAt: new Date().toISOString(),
+      label: `Playthrough ${num}`,
+    };
+    await backend.putPlaythrough(record);
+    await backend.setMeta(playthroughCountKey(ifid), num);
+  });
   await backend.setMeta(currentPlaythroughKey(ifid), id);
+  saveSessionPlaythrough(ifid, id);
   return id;
 }
 
@@ -201,6 +203,7 @@ async function adoptPlaythroughNow(ifid: string, id: string): Promise<void> {
   if ((await backend.getMeta<string>(key)) !== id) {
     await backend.setMeta(key, id);
   }
+  saveSessionPlaythrough(ifid, id);
 }
 
 /**
@@ -230,9 +233,18 @@ export function establishPlaythrough(
 ): Promise<{ id: string; knownSaves: Record<string, true> }> {
   return inOrder(async () => {
     const backend = await getBackend();
-    const id =
-      (await backend.getMeta<string>(currentPlaythroughKey(ifid))) ??
-      (await startNewPlaythroughNow(ifid));
+    // A tab that restores its session continues the session's playthrough;
+    // the shared current one is the default for a visit with no session,
+    // and may belong to what another tab has done since (#356).
+    const own = loadSessionPlaythrough(ifid);
+    const ownExists =
+      own !== undefined &&
+      (await backend.getPlaythroughsByIfid(ifid)).some((p) => p.id === own);
+    const id = ownExists
+      ? own
+      : ((await backend.getMeta<string>(currentPlaythroughKey(ifid))) ??
+        (await startNewPlaythroughNow(ifid)));
+    saveSessionPlaythrough(ifid, id);
     return { id, knownSaves: await populateKnownSavesNow(ifid) };
   });
 }
@@ -503,15 +515,51 @@ function slotMetaKey(ifid: string, slot?: string): string {
 
 const slotIndexKey = (ifid: string) => `${SLOT_INDEX_KEY_PREFIX}${ifid}`;
 
-/** Read-modify-write the per-story slot index. */
+/**
+ * Run `op` holding the browser's lock `name`, so other tabs of the story
+ * (the operation queue only orders this document's operations) wait for it.
+ * Runs `op` without a lock where the browser offers none (or refuses it, as
+ * in a sandboxed frame, which has no other tabs sharing its storage).
+ */
+async function withTabLock<T>(name: string, op: () => Promise<T>): Promise<T> {
+  let locks: LockManager | undefined;
+  try {
+    locks = navigator.locks;
+  } catch {
+    // Access refused: no lock
+  }
+  if (!locks) return op();
+  let started = false;
+  try {
+    return await locks.request(name, () => {
+      started = true;
+      return op();
+    });
+  } catch (err) {
+    // Only a failure to take the lock falls back; op's own errors are its
+    if (started) throw err;
+    return op();
+  }
+}
+
+/**
+ * Read-modify-write the per-story slot index. Under a lock shared by the
+ * story's tabs: two tabs adding a slot at once would both read the old index
+ * and the later write would drop the other's slot.
+ */
 async function updateSlotIndex(
   ifid: string,
   update: (slots: string[]) => string[],
 ): Promise<void> {
   const backend = await getBackend();
-  const existing = (await backend.getMeta<string[]>(slotIndexKey(ifid))) ?? [];
-  const updated = update(existing);
-  if (updated !== existing) await backend.setMeta(slotIndexKey(ifid), updated);
+  await withTabLock(`spindle-slot-index:${ifid}`, async () => {
+    const existing =
+      (await backend.getMeta<string[]>(slotIndexKey(ifid))) ?? [];
+    const updated = update(existing);
+    if (updated !== existing) {
+      await backend.setMeta(slotIndexKey(ifid), updated);
+    }
+  });
 }
 
 /** Every slot: the default one (undefined), then those in the slot index. */
@@ -636,15 +684,20 @@ export const loadQuickSave = readingSlot(livePayload);
  * (see adoptPlaythrough) in the same operation: operations issued after the
  * load take effect in the loaded playthrough. Resolves to the live payload
  * and its playthrough, or undefined if the slot is empty.
+ *
+ * `check` is run on the payload first: when it throws, the load rejects and
+ * the game stays in its playthrough (#357).
  */
 export function loadSlotSave(
   ifid: string,
   slot?: string,
+  check?: (payload: SavePayload) => void,
 ): Promise<{ payload: SavePayload; playthroughId: string } | undefined> {
   return inOrder(async () => {
     const record = await slotRecord(ifid, slot);
     if (!record) return undefined;
     const payload = decodePayload(record.payload);
+    check?.(payload);
     const { playthroughId } = record.meta;
     if (playthroughId) await adoptPlaythroughNow(ifid, playthroughId);
     return { payload, playthroughId };
@@ -758,6 +811,34 @@ export function clearSession(ifid: string): void {
   }
 }
 
+/**
+ * The playthrough this tab's game is in, kept with its session: the shared
+ * current playthrough (a stored meta value) can be changed by another tab.
+ * Written where this tab's storage operations set the current playthrough,
+ * so it follows them in call order. Under the session prefix, so clearing
+ * all data clears it.
+ */
+const SESSION_PLAYTHROUGH_PREFIX = `${SESSION_KEY_PREFIX}playthrough.`;
+
+function saveSessionPlaythrough(ifid: string, id: string): void {
+  try {
+    sessionStorage.setItem(`${SESSION_PLAYTHROUGH_PREFIX}${ifid}`, id);
+  } catch {
+    // the session cannot be stored: a reload takes the shared playthrough
+  }
+}
+
+function loadSessionPlaythrough(ifid: string): string | undefined {
+  try {
+    return (
+      sessionStorage.getItem(`${SESSION_PLAYTHROUGH_PREFIX}${ifid}`) ||
+      undefined
+    );
+  } catch {
+    return undefined;
+  }
+}
+
 // --- Export / Import ---
 
 /** The export of a stored save, if there is one. */

package/src/saves/types.ts

@@ -1,4 +1,5 @@
 import type { PRNGSnapshot } from '../prng';
+import type { SavedWatcher } from '../triggers';
 import { hasOwn } from '../utils/namespace';
 import {
   checkFormatVersion,
@@ -25,6 +26,8 @@ export interface SavePayload {
   visitCounts?: Record<string, number>;
   renderCounts?: Record<string, number>;
   prng?: PRNGSnapshot | null;
+  /** The {watch} macro watchers registered (absent in older saves). */
+  watchers?: SavedWatcher[];
 }
 
 export interface SaveMeta {

package/src/store.ts

@@ -22,6 +22,8 @@ import { emit } from './event-emitter';
 import {
   resetTriggers,
   checkTriggersOnNavigation,
+  restoreMacroWatchers,
+  savedMacroWatchers,
   reinitTriggerState,
 } from './triggers';
 import {
@@ -302,6 +304,7 @@ function persistSession(get: () => StoryState): { error: unknown } | undefined {
     visitCounts,
     renderCounts,
     prng: snapshotPRNG(),
+    watchers: savedMacroWatchers(),
   });
 }
 
@@ -947,6 +950,34 @@ export interface StoryState {
   clearDeferredRender: () => void;
 }
 
+/**
+ * The first passage of `payload` (its current passage, then its history)
+ * that `storyData` does not have, as when the story was updated since the
+ * save; undefined if the story has them all (or is not loaded).
+ */
+export function missingPassage(
+  storyData: StoryData | null | undefined,
+  payload: SavePayload,
+): string | undefined {
+  if (!storyData) return undefined;
+  return [payload.passage, ...payload.history.map((m) => m.passage)].find(
+    (name) => !storyData.passages.has(name),
+  );
+}
+
+/** Throw if `payload` refers to a passage `storyData` does not have. */
+function assertPassagesExist(
+  storyData: StoryData | null | undefined,
+  payload: SavePayload,
+): void {
+  const missing = missingPassage(storyData, payload);
+  if (missing !== undefined) {
+    throw new Error(
+      `The save refers to the passage "${missing}", which this version of the story does not have`,
+    );
+  }
+}
+
 const NAMESPACE_KEYS = ['variables', 'temporary', 'transient'] as const;
 
 type StoryRecipe = (draft: Draft<StoryState>) => void;
@@ -1431,7 +1462,9 @@ export const useStoryStore = create<StoryState>()(
       // the game on, as usual). An empty slot leaves the playthrough as it
       // is.
       const previous = resolvePlaythroughId();
-      const read = loadSlotSave(storyData.ifid, slot);
+      const read = loadSlotSave(storyData.ifid, slot, (payload) =>
+        assertPassagesExist(storyData, payload),
+      );
       const switched = switchToLookedUpPlaythrough(
         Promise.all([previous, read.catch(() => undefined)]).then(
           ([prev, loaded]) => loaded?.playthroughId || prev,
@@ -1601,6 +1634,7 @@ export const useStoryStore = create<StoryState>()(
         visitCounts: { ...visitCounts },
         renderCounts: { ...renderCounts },
         prng: snapshotPRNG(),
+        watchers: savedMacroWatchers(),
       };
     },
 
@@ -1618,12 +1652,16 @@ export const useStoryStore = create<StoryState>()(
       slot?: string,
       playthroughId?: string,
     ) => {
-      const replacement = slotLoadApplying ?? ++stateReplacementsIssued;
+      const applying = slotLoadApplying;
       slotLoadApplying = null;
+      const replacement = applying ?? ++stateReplacementsIssued;
       if (payload.history.length === 0) {
         console.warn('loadFromPayload: rejecting payload with empty history');
         return;
       }
+      // Before anything is replaced: an incompatible payload leaves the
+      // running game as it is
+      assertPassagesExist(get().storyData, payload);
       latestStateApplied = replacement;
 
       emit('beforeload', slot);
@@ -1684,7 +1722,10 @@ export const useStoryStore = create<StoryState>()(
         state.transient = createNamespace(deepClone(get().transientDefaults));
       });
 
-      // Loaded state is not a change watchers react to
+      // The watchers of the loaded game (a payload without any, from an
+      // older version, leaves the registered ones), then: loaded state is
+      // not a change watchers react to
+      if (payload.watchers) restoreMacroWatchers(payload.watchers);
       reinitTriggerState();
 
       // The next navigate() diffs from the snapshot recorded for the current

package/src/story-init.ts

@@ -1,5 +1,5 @@
 import { h, render } from 'preact';
-import { useStoryStore, recordStoryInitState } from './store';
+import { useStoryStore, recordStoryInitState, missingPassage } from './store';
 import { parseMarkup } from './markup/parse';
 import { renderNodes } from './markup/render';
 import { setSaveTitlePassage } from './saves/save-manager';
@@ -71,6 +71,18 @@ export function executeStoryInit() {
 export function initializeStory(session?: SavePayload): void {
   executeStoryInit();
 
+  // A session that refers to a passage the story no longer has (it was
+  // updated since) is dropped: the game starts from the beginning
+  const missing = session
+    ? missingPassage(useStoryStore.getState().storyData, session)
+    : undefined;
+  if (missing !== undefined) {
+    console.warn(
+      `spindle: discarding the saved session: the story no longer has the passage "${missing}"`,
+    );
+    session = undefined;
+  }
+
   if (session) {
     useStoryStore.getState().loadFromPayload(session);
   }

package/src/structural.ts

@@ -85,7 +85,9 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
   function cloneBuiltin(val: object): object | undefined {
     if (val instanceof Date) return keep(val, new Date(val.getTime()));
     if (val instanceof RegExp) {
-      return keep(val, new RegExp(val.source, val.flags));
+      const copy = new RegExp(val.source, val.flags);
+      copy.lastIndex = val.lastIndex; // the scanning cursor of g/y patterns
+      return keep(val, copy);
     }
     if (val instanceof ArrayBuffer) return keep(val, val.slice(0));
     if (ArrayBuffer.isView(val)) {
@@ -343,7 +345,9 @@ function equalBuiltin(
   assumed: Pairs,
 ): boolean | undefined {
   if (a instanceof Date) return Object.is(a.getTime(), (b as Date).getTime());
-  if (a instanceof RegExp) return String(a) === String(b);
+  if (a instanceof RegExp) {
+    return String(a) === String(b) && a.lastIndex === (b as RegExp).lastIndex;
+  }
   if (ArrayBuffer.isView(a)) {
     // A view is its place in its backing buffer, and the whole buffer (which
     // other views can share): equal only if both match.

package/src/styles.css

@@ -571,6 +571,15 @@ tw-storydata {
   background: rgba(100, 181, 246, 0.05);
 }
 
+.saves-notice {
+  padding: 0.5em 1.25em;
+  font-size: 0.8em;
+  color: #ffb74d;
+  border-bottom: 1px solid rgba(255, 183, 77, 0.3);
+  background: rgba(255, 183, 77, 0.08);
+  flex-shrink: 0;
+}
+
 .saves-status {
   padding: 0.5em 1.25em;
   font-size: 0.8em;

package/src/triggers.ts

@@ -115,6 +115,36 @@ export function addMacroTrigger(
   registerTrigger(condition, options, macroKey);
 }
 
+/** A {watch} macro's watcher as a save and the session hold it. */
+export interface SavedWatcher {
+  condition: string;
+  options: WatchOptions;
+}
+
+/**
+ * The {watch} macro watchers now registered, for a save or the session:
+ * watchers outlive the passage that declared them, so a game restored
+ * where it stopped needs the ones its earlier passages registered (and
+ * not the ones {unwatch} or `once` removed).
+ */
+export function savedMacroWatchers(): SavedWatcher[] {
+  return triggers
+    .filter((t) => t.macroKey !== undefined && t.options)
+    .map((t) => ({ condition: t.condition, options: { ...t.options } }));
+}
+
+/**
+ * Make the {watch} macro watchers those of a loaded game: the ones of
+ * `watchers` replace the registered ones (watchers added by Story.watch
+ * code stay). The passage shown mounts its own {watch} macros again.
+ */
+export function restoreMacroWatchers(watchers: readonly SavedWatcher[]): void {
+  triggers = triggers.filter((t) => t.macroKey === undefined);
+  for (const { condition, options } of watchers) {
+    addMacroTrigger(condition, options);
+  }
+}
+
 export function removeTrigger(name: string): void {
   triggers = triggers.filter((t) => t.name !== name);
 }

package/src/utils/stable-key.ts

@@ -49,7 +49,7 @@ function keyOf(val: unknown, ancestors: object[]): string {
   if (depth !== -1) return `<cycle ${ancestors.length - depth}>`;
 
   if (val instanceof Date) return `Date(${val.getTime()})`;
-  if (val instanceof RegExp) return `RegExp(${String(val)})`;
+  if (val instanceof RegExp) return `RegExp(${String(val)}@${val.lastIndex})`;
 
   ancestors.push(obj);
   try {