@rohal12/spindle 0.51.0 → 0.51.2

package/src/interpolation.ts

@@ -11,7 +11,8 @@ export function hasInterpolation(s: string): boolean {
 function resolveDotPath(root: unknown, parts: string[]): unknown {
   let value = root;
   for (let i = 1; i < parts.length; i++) {
-    if (value == null || typeof value !== 'object') return undefined;
+    // Primitives box on access, so `{$name.length}` works too.
+    if (value == null) return undefined;
     value = (value as Record<string, unknown>)[parts[i]!];
   }
   return value;

package/src/markup/ast.ts

@@ -91,6 +91,14 @@ const BRANCH_PARENT: Record<string, string> = {
 /** Block macros that use the branches[] array */
 const BRANCHING_BLOCK_MACROS = new Set(['if', 'switch', 'timed']);
 
+/**
+ * Quote a bracket-link value as a {link} argument, escaping backslashes and
+ * double quotes so MacroLink reads the value back unchanged (#200).
+ */
+function quoteArg(value: string): string {
+  return `"${value.replace(/[\\"]/g, '\\$&')}"`;
+}
+
 /**
  * Build an AST from a token array. Block macros are nested into trees
  * using a stack. Throws on unclosed or mismatched macros.
@@ -118,7 +126,7 @@ export function buildAST(tokens: Token[]): ASTNode[] {
         break;
 
       case 'link': {
-        const rawArgs = `"${token.display}" "${token.target}"`;
+        const rawArgs = `${quoteArg(token.display)} ${quoteArg(token.target)}`;
         const macroNode: MacroNode = {
           type: 'macro',
           name: 'link',

package/src/markup/render.tsx

@@ -339,7 +339,8 @@ function getVariableTextValue(
   else value = locals[root];
 
   for (let i = 1; i < parts.length; i++) {
-    if (value == null || typeof value !== 'object') return '';
+    // Primitives box on access, so `{$name.length}` works too.
+    if (value == null) return '';
     value = (value as Record<string, unknown>)[parts[i]!];
   }
 

package/src/passage-render-state.ts

@@ -1,14 +1,15 @@
 /**
- * Name of the passage most recently mounted by <Passage> (null until the
- * first render, e.g. when the story interface has no {passage}).
- * Lets Story.waitForActions() tell whether the current passage is on screen.
+ * Navigation id (the store's `navigationId`) of the passage most recently
+ * mounted by <Passage> (null until the first render, e.g. when the story
+ * interface has no {passage}). Lets Story.waitForActions() tell whether the
+ * current navigation is on screen, also when it revisits the passage shown.
  */
-let renderedPassage: string | null = null;
+let renderedNavigationId: number | null = null;
 
-export function markPassageRendered(name: string): void {
-  renderedPassage = name;
+export function markPassageRendered(navigationId: number): void {
+  renderedNavigationId = navigationId;
 }
 
-export function getRenderedPassage(): string | null {
-  return renderedPassage;
+export function getRenderedNavigationId(): number | null {
+  return renderedNavigationId;
 }

package/src/preact-store.ts

@@ -0,0 +1,50 @@
+/**
+ * Zustand's `create()` for Preact.
+ *
+ * Zustand's default entry (`zustand` / `zustand/react`) imports `react`, which
+ * Spindle doesn't depend on. Bundlers that alias `react` to `preact/compat`
+ * hide that, but the published headless entry keeps Zustand external and runs
+ * under plain Node resolution, where `react` doesn't exist. Building on the
+ * vanilla store and Preact's own hooks keeps `react` out of the module graph.
+ */
+import { useSyncExternalStore } from 'preact/compat';
+import { useCallback } from 'preact/hooks';
+import {
+  createStore,
+  type ExtractState,
+  type Mutate,
+  type StateCreator,
+  type StoreApi,
+  type StoreMutatorIdentifier,
+} from 'zustand/vanilla';
+
+/** A store API that is also a selector hook, like Zustand's bound stores. */
+export type UseBoundStore<S extends StoreApi<unknown>> = S & {
+  (): ExtractState<S>;
+  <U>(selector: (state: ExtractState<S>) => U): U;
+};
+
+const identity = <T>(value: T): T => value;
+
+function bindPreact<S extends StoreApi<unknown>>(api: S): UseBoundStore<S> {
+  function useBoundStore<U>(
+    selector: (state: ExtractState<S>) => U = identity as (
+      state: ExtractState<S>,
+    ) => U,
+  ): U {
+    const getSnapshot = useCallback(
+      () => selector(api.getState() as ExtractState<S>),
+      [selector],
+    );
+    return useSyncExternalStore(api.subscribe, getSnapshot);
+  }
+  return Object.assign(useBoundStore, api) as UseBoundStore<S>;
+}
+
+/** Curried `create<State>()(initializer)`, as in Zustand. */
+export function create<T>() {
+  return <Mos extends [StoreMutatorIdentifier, unknown][] = []>(
+    initializer: StateCreator<T, [], Mos>,
+  ): UseBoundStore<Mutate<StoreApi<T>, Mos>> =>
+    bindPreact(createStore<T>()(initializer));
+}

package/src/saves/save-manager.ts

@@ -7,7 +7,7 @@ import type {
   SaveExport,
   StorageInfo,
 } from './types';
-import { isSavePayload } from './types';
+import { isSaveExport, isSavePayload } from './types';
 import { getBackend, resetBackend } from './storage';
 import { deepClone, serialize, deserialize } from '../class-registry';
 import { emit } from '../event-emitter';
@@ -102,6 +102,10 @@ export async function getCurrentPlaythroughId(
  * before `getPayload()` captures the state, so data a hook sets is part of the
  * save; `aftersave` fires once `write` has stored it. Every user-facing save
  * path goes through here.
+ *
+ * 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.
  */
 export function saveWithHooks<T>(
   slot: string | undefined,
@@ -109,12 +113,16 @@ export function saveWithHooks<T>(
   getPayload: () => SavePayload,
   write: (payload: SavePayload) => Promise<T>,
 ): Promise<T> {
-  emit('beforesave', slot, custom);
-  const payload = getPayload();
-  return write(payload).then((result) => {
-    emit('aftersave', slot);
-    return result;
-  });
+  try {
+    emit('beforesave', slot, custom);
+    const payload = getPayload();
+    return write(payload).then((result) => {
+      emit('aftersave', slot);
+      return result;
+    });
+  } catch (err) {
+    return Promise.reject(err);
+  }
 }
 
 // --- Save CRUD ---
@@ -204,8 +212,26 @@ export async function loadSave(
   return deserializePayload(record.payload);
 }
 
+/**
+ * Delete a save record. If the default slot or a named slot holds it, that
+ * slot is cleared as well (pointer and slot index), as `deleteSlotSave` would.
+ */
 export async function deleteSaveById(saveId: string): Promise<void> {
-  await (await getBackend()).deleteSave(saveId);
+  const backend = await getBackend();
+  const record = await backend.getSave(saveId);
+  await backend.deleteSave(saveId);
+  if (!record) return;
+
+  const ifid = record.meta.ifid;
+  const slots = [undefined, ...(await getIndexedSlots(ifid))];
+  for (const slot of slots) {
+    const metaKey = slotMetaKey(ifid, slot);
+    await withSlot(metaKey, async () => {
+      if ((await backend.getMeta<string>(metaKey)) !== saveId) return;
+      await backend.deleteMeta(metaKey);
+      await removeFromSlotIndex(ifid, slot);
+    });
+  }
 }
 
 export async function renameSave(
@@ -314,6 +340,25 @@ function slotMetaKey(ifid: string, slot?: string): string {
     : `${AUTOSAVE_KEY_PREFIX}${ifid}`;
 }
 
+/** Tail of each slot's operation queue, keyed by the slot's meta key. */
+const slotQueues = new Map<string, Promise<unknown>>();
+
+/**
+ * Run a complete operation on one slot (save, import, delete) after the ones
+ * already queued for it. Each operation reads the slot pointer and writes the
+ * record and pointer as a unit, so concurrent operations on the same slot
+ * apply in call order instead of each creating its own record.
+ */
+function withSlot<T>(metaKey: string, op: () => Promise<T>): Promise<T> {
+  const run = (slotQueues.get(metaKey) ?? Promise.resolve()).then(op);
+  const tail = run.catch(() => {});
+  slotQueues.set(metaKey, tail);
+  void tail.then(() => {
+    if (slotQueues.get(metaKey) === tail) slotQueues.delete(metaKey);
+  });
+  return run;
+}
+
 /** Tail of the queue that serializes slot index updates. */
 let slotIndexQueue: Promise<unknown> = Promise.resolve();
 
@@ -368,32 +413,34 @@ function toSaveInfo(record: SaveRecord, slot?: string): SaveInfo {
   };
 }
 
-export async function quickSave(
+export function quickSave(
   ifid: string,
   playthroughId: string,
   payload: SavePayload,
   slot?: string,
   custom?: Record<string, unknown>,
 ): Promise<SaveRecord> {
-  const backend = await getBackend();
   const metaKey = slotMetaKey(ifid, slot);
-  const existingId = await backend.getMeta<string>(metaKey);
+  return withSlot(metaKey, async () => {
+    const backend = await getBackend();
+    const existingId = await backend.getMeta<string>(metaKey);
 
-  if (existingId) {
-    const updated = await overwriteSave(existingId, payload, custom);
-    if (updated) return updated;
-  }
+    if (existingId) {
+      const updated = await overwriteSave(existingId, payload, custom);
+      if (updated) return updated;
+    }
 
-  // Create new save
-  const record = await createSave(ifid, playthroughId, payload, {
-    isAutosave: !isNamedSlot(slot),
-    ...(isNamedSlot(slot) ? { slot } : {}),
-    ...custom,
-  });
-  await backend.setMeta(metaKey, record.meta.id);
-  await addToSlotIndex(ifid, slot);
+    // Create new save
+    const record = await createSave(ifid, playthroughId, payload, {
+      isAutosave: !isNamedSlot(slot),
+      ...(isNamedSlot(slot) ? { slot } : {}),
+      ...custom,
+    });
+    await backend.setMeta(metaKey, record.meta.id);
+    await addToSlotIndex(ifid, slot);
 
-  return record;
+    return record;
+  });
 }
 
 export async function hasQuickSave(
@@ -425,7 +472,8 @@ export async function loadQuickSave(
 export async function populateKnownSaves(
   ifid: string,
 ): Promise<Record<string, true>> {
-  const result: Record<string, true> = {};
+  // No prototype, so a slot named '__proto__' is recorded as an entry
+  const result = Object.create(null) as Record<string, true>;
 
   // Check default autosave
   if (await hasQuickSave(ifid)) {
@@ -481,20 +529,19 @@ export async function listSlotSaves(ifid: string): Promise<SaveInfo[]> {
 /**
  * Delete a save by slot name. Removes from slot index if named.
  */
-export async function deleteSlotSave(
-  ifid: string,
-  slot?: string,
-): Promise<void> {
-  const backend = await getBackend();
+export function deleteSlotSave(ifid: string, slot?: string): Promise<void> {
   const metaKey = slotMetaKey(ifid, slot);
-  const existingId = await backend.getMeta<string>(metaKey);
-  if (!existingId) return;
+  return withSlot(metaKey, async () => {
+    const backend = await getBackend();
+    const existingId = await backend.getMeta<string>(metaKey);
+    if (!existingId) return;
 
-  await backend.deleteSave(existingId);
-  await backend.deleteMeta(metaKey);
+    await backend.deleteSave(existingId);
+    await backend.deleteMeta(metaKey);
 
-  // Remove from slot index if named
-  await removeFromSlotIndex(ifid, slot);
+    // Remove from slot index if named
+    await removeFromSlotIndex(ifid, slot);
+  });
 }
 
 // --- Session Persistence (survives F5, cleared on tab close) ---
@@ -569,6 +616,11 @@ async function prepareImport(
       `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');
+  }
 
   const backend = await getBackend();
 
@@ -624,32 +676,34 @@ export async function exportSlotSave(
  * validation as `importSave` (version, IFID) and keeps the playthrough record
  * and slot index consistent.
  */
-export async function importSlotSave(
+export function importSlotSave(
   data: SaveExport,
   ifid: string,
   slot?: string,
 ): Promise<SaveInfo> {
-  const record = await prepareImport(data, ifid);
-
-  // The slot keys in `custom` describe where the save lives, so they follow
-  // the target slot rather than the slot the save was exported from.
-  const { slot: _exportedSlot, ...custom } = record.meta.custom ?? {};
-  record.meta.custom = {
-    ...custom,
-    isAutosave: !isNamedSlot(slot),
-    ...(isNamedSlot(slot) ? { slot } : {}),
-  };
-
-  const backend = await getBackend();
   const metaKey = slotMetaKey(ifid, slot);
-  const previousId = await backend.getMeta<string>(metaKey);
+  return withSlot(metaKey, async () => {
+    const record = await prepareImport(data, ifid);
+
+    // The slot keys in `custom` describe where the save lives, so they follow
+    // the target slot rather than the slot the save was exported from.
+    const { slot: _exportedSlot, ...custom } = record.meta.custom ?? {};
+    record.meta.custom = {
+      ...custom,
+      isAutosave: !isNamedSlot(slot),
+      ...(isNamedSlot(slot) ? { slot } : {}),
+    };
 
-  await backend.putSave(record);
-  await backend.setMeta(metaKey, record.meta.id);
-  await addToSlotIndex(ifid, slot);
-  if (previousId) await backend.deleteSave(previousId);
+    const backend = await getBackend();
+    const previousId = await backend.getMeta<string>(metaKey);
 
-  return toSaveInfo(record, slot);
+    await backend.putSave(record);
+    await backend.setMeta(metaKey, record.meta.id);
+    await addToSlotIndex(ifid, slot);
+    if (previousId) await backend.deleteSave(previousId);
+
+    return toSaveInfo(record, slot);
+  });
 }
 
 // --- Storage Management ---

package/src/saves/storage.ts

@@ -548,14 +548,28 @@ async function detectBackend(): Promise<StorageBackend> {
   return createMemoryBackend();
 }
 
-export async function getBackend(): Promise<StorageBackend> {
-  if (_backend) return _backend;
-  _backend = await detectBackend();
-  return _backend;
+/**
+ * Detection in flight. Concurrent first callers share it so they all get the
+ * same backend (the memory fallback makes a new, empty store per detection).
+ */
+let _backendPromise: Promise<StorageBackend> | null = null;
+
+export function getBackend(): Promise<StorageBackend> {
+  if (_backend) return Promise.resolve(_backend);
+  if (!_backendPromise) {
+    const pending = detectBackend().then((backend) => {
+      // A reset while detecting discards this result
+      if (_backendPromise === pending) _backend = backend;
+      return backend;
+    });
+    _backendPromise = pending;
+  }
+  return _backendPromise;
 }
 
 export function resetBackend(): void {
   _backend = null;
+  _backendPromise = null;
 }
 
 /**

package/src/saves/types.ts

@@ -78,15 +78,64 @@ export function isSaveExport(value: unknown): value is SaveExport {
   if (typeof meta.updatedAt !== 'string') return false;
   if (typeof meta.title !== 'string') return false;
 
-  const payload = save.payload as Record<string, unknown>;
-  if (typeof payload.passage !== 'string') return false;
-  if (!Array.isArray(payload.history) || payload.history.length === 0)
-    return false;
-  if (typeof payload.historyIndex !== 'number') return false;
-  if (typeof payload.variables !== 'object' || payload.variables === null)
+  return isImportablePayload(save.payload);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** 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
+  );
+}
+
+function isSaveHistoryMoment(value: unknown): value is SaveHistoryMoment {
+  return (
+    isRecord(value) &&
+    typeof value.passage === 'string' &&
+    isRecord(value.variables) &&
+    typeof value.timestamp === 'number' &&
+    isOptionalPRNGSnapshot(value.prng)
+  );
+}
+
+/**
+ * Full check of a payload from outside the running story (an imported save):
+ * every history moment is well formed, and `historyIndex` is an integer that
+ * points at a moment of the payload's passage. Anything that passes can be
+ * stored and later loaded.
+ */
+function isImportablePayload(value: unknown): value is SavePayload {
+  if (!isRecord(value)) return false;
+  if (typeof value.passage !== 'string') return false;
+  if (!isRecord(value.variables)) return false;
+
+  const { history, historyIndex } = value;
+  if (!Array.isArray(history) || history.length === 0) return false;
+  if (!history.every(isSaveHistoryMoment)) return false;
+  if (
+    typeof historyIndex !== 'number' ||
+    !Number.isInteger(historyIndex) ||
+    historyIndex < 0 ||
+    historyIndex >= history.length
+  ) {
     return false;
+  }
+  if (history[historyIndex]!.passage !== value.passage) return false;
 
-  return true;
+  if (value.visitCounts !== undefined && !isRecord(value.visitCounts))
+    return false;
+  if (value.renderCounts !== undefined && !isRecord(value.renderCounts))
+    return false;
+  return isOptionalPRNGSnapshot(value.prng);
 }
 
 export function isSavePayload(value: unknown): value is SavePayload {

package/src/store.ts

@@ -1,4 +1,4 @@
-import { create } from 'zustand';
+import { create } from './preact-store';
 import { immer } from 'zustand/middleware/immer';
 import {
   enablePatches,
@@ -214,8 +214,10 @@ function resetModuleState(base: Record<string, unknown>): void {
 /**
  * Record the state StoryInit left behind as the start moment: its variable
  * snapshot (the history base) and PRNG state. Called by executeStoryInit()
- * after the StoryInit passage has rendered; init()/restart() record the
- * start moment before StoryInit runs. A no-op once the story has moved on.
+ * after the StoryInit passage has rendered, and again after the `storyinit`
+ * handlers have run at boot (unless a session was restored) and on restart;
+ * init()/restart() record the start moment before StoryInit runs. A no-op
+ * once the story has moved on.
  */
 export function recordStoryInitState(): void {
   const { history, historyIndex, variables } = useStoryStore.getState();
@@ -777,6 +779,8 @@ export const useStoryStore = create<StoryState>()(
       executeStoryInit();
       clearSession(storyData.ifid);
       emit('storyinit');
+      // The storyinit handlers' changes belong to the start moment too
+      recordStoryInitState();
 
       // Start a new playthrough on restart
       startNewPlaythrough(storyData.ifid)
@@ -855,7 +859,8 @@ export const useStoryStore = create<StoryState>()(
     hasSave: (slot?: string) => {
       const { storyData, knownSaves } = get();
       if (!storyData) return false;
-      return (slot ?? '') in knownSaves;
+      // Own entries only: slot names like 'constructor' are not inherited saves
+      return Object.prototype.hasOwnProperty.call(knownSaves, slot ?? '');
     },
 
     getSaveInfo: async (slot?: string): Promise<SaveInfo | null> => {

package/src/story-api.ts

@@ -30,7 +30,7 @@ import type { MacroDefinition } from './define-macro';
 import { getMacroRegistry as _getMacroRegistry } from './registry';
 import type { MacroMetadata } from './registry';
 import { getActions, getAction, type StoryAction } from './action-registry';
-import { getRenderedPassage } from './passage-render-state';
+import { getRenderedNavigationId } from './passage-render-state';
 import {
   initPRNG,
   isPRNGEnabled,
@@ -548,13 +548,19 @@ function createStoryAPI(): StoryAPI {
       });
       // A navigation can still be rendering: the passage display mounts the
       // new passage from an effect, after a fade-through's outgoing phase.
-      // Its actions exist only once it is mounted, so wait for that.
-      const { currentPassage, renderDeferred } = useStoryStore.getState();
-      const rendered = getRenderedPassage();
-      if (rendered !== null && rendered !== currentPassage && !renderDeferred) {
+      // Its actions exist only once it is mounted, so wait for that. Compare
+      // navigations, not passage names: revisiting the passage shown mounts
+      // it anew (#228).
+      const isRendered = () =>
+        getRenderedNavigationId() === useStoryStore.getState().navigationId;
+      if (
+        getRenderedNavigationId() !== null &&
+        !isRendered() &&
+        !useStoryStore.getState().renderDeferred
+      ) {
         await new Promise<void>((resolve) => {
-          const off = emitterOn('passagerender', (name) => {
-            if (name === useStoryStore.getState().currentPassage) {
+          const off = emitterOn('passagerender', () => {
+            if (isRendered()) {
               off();
               resolve();
             }

package/src/story-init.ts

@@ -4,6 +4,8 @@ import { tokenize } from './markup/tokenizer';
 import { buildAST } from './markup/ast';
 import { renderNodes } from './markup/render';
 import { setSaveTitlePassage } from './saves/save-manager';
+import { emit } from './event-emitter';
+import type { SavePayload } from './saves/types';
 
 /** Hidden container holding the currently mounted StoryInit tree. */
 let storyInitContainer: HTMLElement | null = null;
@@ -60,3 +62,24 @@ export function executeStoryInit() {
     setSaveTitlePassage(saveTitlePassage.content);
   }
 }
+
+/**
+ * Initialize a freshly booted story: run StoryInit, restore `session` (the
+ * state a page refresh left behind) if there is one, then fire `storyinit`
+ * once all state is settled. Without a session, what the `storyinit`
+ * handlers set synchronously belongs to the start moment, like StoryInit's
+ * changes; a restored session keeps the history it recorded.
+ */
+export function initializeStory(session?: SavePayload): void {
+  executeStoryInit();
+
+  if (session) {
+    useStoryStore.getState().loadFromPayload(session);
+  }
+
+  emit('storyinit');
+
+  if (!session) {
+    recordStoryInitState();
+  }
+}

package/src/story-variables.ts

@@ -26,6 +26,13 @@ const FOR_LOCAL_RE = /\{for\s+@(\w+)(?:\s*,\s*@(\w+))?\s+of\b/g;
 
 const VALID_VAR_TYPES = new Set<string>(['number', 'string', 'boolean']);
 
+/** Boxed sample values whose members a primitive of each type can access. */
+const PRIMITIVE_SAMPLES: Partial<Record<VarType, object>> = {
+  string: Object(''),
+  number: Object(0),
+  boolean: Object(false),
+};
+
 function inferSchema(value: unknown): FieldSchema {
   if (Array.isArray(value)) {
     return { type: 'array' };
@@ -138,6 +145,17 @@ function validateRef(
     // so any field access on an array is allowed.
     if (current.type === 'array') return null;
 
+    // Primitives expose their wrapper's built-ins (length, toUpperCase,
+    // toFixed, etc.). Keep validating past properties of primitive type.
+    const sample = PRIMITIVE_SAMPLES[current.type];
+    if (sample && part in sample) {
+      const member: unknown = sample[part as keyof typeof sample];
+      const memberType = typeof member;
+      if (!VALID_VAR_TYPES.has(memberType)) return null;
+      current = { type: memberType as VarType };
+      continue;
+    }
+
     if (current.type !== 'object' || !current.fields) {
       return `Cannot access field "${part}" on $${parts.slice(0, i).join('.')} (type: ${current.type})`;
     }