@rohal12/spindle 0.59.7 → 0.59.9

package/src/hooks/use-modal-focus.ts

@@ -13,9 +13,23 @@ const FOCUSABLE = [
   '[tabindex]:not([tabindex="-1"])',
 ].join(',');
 
+/**
+ * Whether CSS leaves `el` in the tab sequence: not `visibility: hidden`
+ * (inherited, so the computed value covers ancestors) and not inside a
+ * `display: none` element.
+ */
+function isRendered(el: HTMLElement): boolean {
+  const { visibility } = getComputedStyle(el);
+  if (visibility === 'hidden' || visibility === 'collapse') return false;
+  for (let e: HTMLElement | null = el; e; e = e.parentElement) {
+    if (getComputedStyle(e).display === 'none') return false;
+  }
+  return true;
+}
+
 function focusables(root: HTMLElement): HTMLElement[] {
   return Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(
-    (el) => !el.hidden && !el.closest('[hidden], [inert]'),
+    (el) => !el.hidden && !el.closest('[hidden], [inert]') && isRendered(el),
   );
 }
 

package/src/quick-actions.ts

@@ -0,0 +1,23 @@
+import { useStoryStore } from './store';
+import { showRuntimeError } from './runtime-errors';
+
+/**
+ * QuickSave and QuickLoad as the built-in buttons and hotkeys perform them:
+ * a failure is shown on the page (the Story API's save() and load() only
+ * reject, for the code that awaits them).
+ */
+export async function quickSave(): Promise<void> {
+  try {
+    await useStoryStore.getState().save();
+  } catch (error) {
+    showRuntimeError('The game could not be saved:', error);
+  }
+}
+
+export async function quickLoad(): Promise<void> {
+  try {
+    await useStoryStore.getState().load();
+  } catch (error) {
+    showRuntimeError('The saved game could not be loaded:', error);
+  }
+}

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,17 +134,18 @@ 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);
   return id;
 }
@@ -503,15 +504,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. */
@@ -713,14 +750,22 @@ const SESSION_KEY_PREFIX = 'spindle.session.';
  * 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.
+ *
+ * A storage that is unavailable or full is returned, not thrown: the session
+ * keeps its previous copy then too, but the story can go on, so the caller
+ * decides how to tell the player.
  */
-export function saveSession(ifid: string, payload: SavePayload): void {
+export function saveSession(
+  ifid: string,
+  payload: SavePayload,
+): { error: unknown } | undefined {
   const text = JSON.stringify(encodePayload(payload));
   try {
     sessionStorage.setItem(`${SESSION_KEY_PREFIX}${ifid}`, text);
-  } catch {
-    // sessionStorage unavailable or full — silently ignore
+  } catch (error) {
+    return { error };
   }
+  return undefined;
 }
 
 /**
@@ -889,13 +934,15 @@ async function clearAllDataNow(): Promise<void> {
   resetBackend();
 
   // Clear all Spindle session keys from sessionStorage
-  if (typeof sessionStorage !== 'undefined') {
+  try {
     const toRemove: string[] = [];
     for (let i = 0; i < sessionStorage.length; i++) {
       const key = sessionStorage.key(i);
       if (key?.startsWith('spindle.session.')) toRemove.push(key);
     }
     for (const key of toRemove) sessionStorage.removeItem(key);
+  } catch {
+    // no sessionStorage (or access denied): nothing to clear
   }
 }
 

package/src/saves/storage.ts

@@ -410,8 +410,10 @@ function createIDBBackend(): StorageBackend {
 let _backend: StorageBackend | null = null;
 
 async function detectBackend(): Promise<StorageBackend> {
-  if (typeof indexedDB !== 'undefined') {
-    try {
+  // Even looking up a storage API can throw (a sandboxed frame without
+  // allow-same-origin denies the localStorage property), hence the try.
+  try {
+    if (typeof indexedDB !== 'undefined') {
       await new Promise<void>((resolve, reject) => {
         const req = indexedDB.open('__spindle_probe__', 1);
         req.onsuccess = () => {
@@ -422,21 +424,21 @@ async function detectBackend(): Promise<StorageBackend> {
         req.onerror = () => reject(req.error);
       });
       return createIDBBackend();
-    } catch {
-      // fall through
     }
+  } catch {
+    // fall through
   }
 
-  if (typeof localStorage !== 'undefined') {
-    try {
+  try {
+    if (typeof localStorage !== 'undefined') {
       const probeKey = '__spindle_probe__';
       localStorage.setItem(probeKey, '1');
       const val = localStorage.getItem(probeKey);
       localStorage.removeItem(probeKey);
       if (val === '1') return createLocalStorageBackend();
-    } catch {
-      // fall through
     }
+  } catch {
+    // fall through
   }
 
   return createMemoryBackend();

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/settings.ts

@@ -39,7 +39,11 @@ function storageKey(): string {
 }
 
 function persist(): void {
-  localStorage.setItem(storageKey(), JSON.stringify(values));
+  try {
+    localStorage.setItem(storageKey(), JSON.stringify(values));
+  } catch {
+    // storage unavailable or full: the setting holds for this session only
+  }
 }
 
 function loadFromStorage(): void {

package/src/store.ts

@@ -22,6 +22,8 @@ import { emit } from './event-emitter';
 import {
   resetTriggers,
   checkTriggersOnNavigation,
+  restoreMacroWatchers,
+  savedMacroWatchers,
   reinitTriggerState,
 } from './triggers';
 import {
@@ -259,7 +261,7 @@ let sessionMoments: SaveHistoryMoment[] = [];
  * Write the game to the session: the whole payload, encoded in one piece
  * on every navigation.
  */
-function persistSession(get: () => StoryState): void {
+function persistSession(get: () => StoryState): { error: unknown } | undefined {
   const {
     storyData,
     currentPassage,
@@ -269,7 +271,7 @@ function persistSession(get: () => StoryState): void {
     visitCounts,
     renderCounts,
   } = get();
-  if (!storyData) return;
+  if (!storyData) return undefined;
 
   // Trim cache when history shrank (navigate() drops discarded forward
   // moments itself, since a replacement branch may keep the same length)
@@ -294,7 +296,7 @@ function persistSession(get: () => StoryState): void {
     }
   }
 
-  saveSession(storyData.ifid, {
+  return saveSession(storyData.ifid, {
     passage: currentPassage,
     variables,
     history: sessionMoments,
@@ -302,6 +304,7 @@ function persistSession(get: () => StoryState): void {
     visitCounts,
     renderCounts,
     prng: snapshotPRNG(),
+    watchers: savedMacroWatchers(),
   });
 }
 
@@ -324,7 +327,11 @@ const NAVIGATION_ERROR_CONTEXT = 'The story could not go to another passage:';
 function persistSessionThen(get: () => StoryState, after?: () => void): void {
   let failure: { error: unknown } | undefined;
   try {
-    persistSession(get);
+    const storageFailure = persistSession(get);
+    // The story goes on, but a reload would go back to the last copy
+    if (storageFailure) {
+      showRuntimeError(SESSION_ERROR_CONTEXT, storageFailure.error);
+    }
   } catch (error) {
     failure = { error };
     // The player sees it too: a reload would go back to the last moment
@@ -943,6 +950,21 @@ 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),
+  );
+}
+
 const NAMESPACE_KEYS = ['variables', 'temporary', 'transient'] as const;
 
 type StoryRecipe = (draft: Draft<StoryState>) => void;
@@ -1597,6 +1619,7 @@ export const useStoryStore = create<StoryState>()(
         visitCounts: { ...visitCounts },
         renderCounts: { ...renderCounts },
         prng: snapshotPRNG(),
+        watchers: savedMacroWatchers(),
       };
     },
 
@@ -1614,12 +1637,21 @@ 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
+      const missing = missingPassage(get().storyData, payload);
+      if (missing !== undefined) {
+        throw new Error(
+          `The save refers to the passage "${missing}", which this version of the story does not have`,
+        );
+      }
       latestStateApplied = replacement;
 
       emit('beforeload', slot);
@@ -1680,7 +1712,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

@@ -261,6 +261,11 @@ tw-storydata {
   max-width: 400px;
 }
 
+/* Keep the first control clear of the close button above it */
+.dialog-settings .dialog-body {
+  padding-top: 2.25em;
+}
+
 .dialog-close {
   position: absolute;
   top: 0.75em;
@@ -566,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 {

package/src/widgets/widget-def.ts

@@ -36,7 +36,14 @@ export function parseWidgetDef(rawArgs: string): WidgetDef {
   return widgetDef(parseMacroArgs(rawArgs, WIDGET_PARAMETERS));
 }
 
-const BLOCK_WIDGET = /\{widget\s+["']?(\w+)["']?[^}]*\}([\s\S]*?)\{\/widget\}/g;
+/**
+ * A definition: its arguments (read like a {widget} macro's, see
+ * parseWidgetDef) and its body. Macro names are not case-sensitive.
+ */
+const WIDGET_DEFINITION = /\{widget\s+([^}]*)\}([\s\S]*?)\{\/widget\}/gi;
+
+/** `{@children}`, also with selectors such as `{.highlight @children}`. */
+const CHILDREN_PLACEHOLDER = /\{[^{}]*@children\s*\}/;
 
 /**
  * The names of the block widgets (those whose body renders `{@children}`)
@@ -52,8 +59,13 @@ export function blockWidgetNames(
     if (passage.name !== 'StoryInit' && !passage.tags?.includes('widget')) {
       continue;
     }
-    for (const match of passage.content.matchAll(BLOCK_WIDGET)) {
-      if (/\{@children\}/.test(match[2]!)) names.push(match[1]!);
+    for (const match of passage.content.matchAll(WIDGET_DEFINITION)) {
+      if (!CHILDREN_PLACEHOLDER.test(match[2]!)) continue;
+      try {
+        names.push(parseWidgetDef(match[1]!).name);
+      } catch {
+        // The {widget} macro reports a definition it cannot read
+      }
     }
   }
   return names;