@rohal12/spindle 0.51.4 → 0.52.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/dist/pkg/format.js +1 -1
  2. package/dist/pkg/headless.js +4313 -1640
  3. package/dist/pkg/macro-registry.json +7 -7
  4. package/dist/pkg/story-variables.js +1636 -177
  5. package/package.json +5 -2
  6. package/src/automation/runner.ts +2 -1
  7. package/src/class-registry.ts +214 -103
  8. package/src/components/Passage.tsx +2 -2
  9. package/src/components/PassageDialog.tsx +2 -5
  10. package/src/components/StoryInterface.tsx +2 -4
  11. package/src/components/macros/Button.tsx +5 -31
  12. package/src/components/macros/Checkbox.tsx +7 -4
  13. package/src/components/macros/Computed.tsx +19 -13
  14. package/src/components/macros/For.tsx +29 -3
  15. package/src/components/macros/If.tsx +8 -0
  16. package/src/components/macros/Include.tsx +7 -6
  17. package/src/components/macros/MacroError.tsx +2 -1
  18. package/src/components/macros/MacroLink.tsx +12 -45
  19. package/src/components/macros/Meter.tsx +11 -3
  20. package/src/components/macros/Nobr.tsx +1 -0
  21. package/src/components/macros/PassageDisplay.tsx +3 -0
  22. package/src/components/macros/Print.tsx +4 -0
  23. package/src/components/macros/Radiobutton.tsx +5 -2
  24. package/src/components/macros/SaveManager.tsx +25 -8
  25. package/src/components/macros/Span.tsx +1 -0
  26. package/src/components/macros/StoryTitle.tsx +1 -0
  27. package/src/components/macros/Switch.tsx +13 -0
  28. package/src/components/macros/Unset.tsx +30 -10
  29. package/src/components/macros/VarDisplay.tsx +21 -4
  30. package/src/components/macros/Widget.tsx +20 -1
  31. package/src/components/macros/WidgetInvocation.tsx +17 -75
  32. package/src/components/macros/arg-utils.ts +107 -1
  33. package/src/components/macros/detached-body.tsx +68 -0
  34. package/src/components/macros/option-utils.ts +3 -2
  35. package/src/define-macro.ts +32 -5
  36. package/src/execute-mutation.ts +270 -67
  37. package/src/expression.ts +86 -55
  38. package/src/hooks/use-action.ts +18 -3
  39. package/src/hooks/use-interpolate.ts +36 -5
  40. package/src/index.tsx +10 -1
  41. package/src/interpolation.ts +394 -96
  42. package/src/js-lexer.ts +1231 -97
  43. package/src/markup/code-attributes.ts +64 -0
  44. package/src/markup/markdown.ts +188 -9
  45. package/src/markup/render.tsx +430 -49
  46. package/src/markup/tokenizer.ts +578 -110
  47. package/src/prng.ts +8 -8
  48. package/src/registry.ts +35 -0
  49. package/src/saves/save-manager.ts +339 -158
  50. package/src/saves/storage.ts +16 -7
  51. package/src/saves/types.ts +2 -1
  52. package/src/store.ts +521 -154
  53. package/src/story-api.ts +31 -67
  54. package/src/story-init.ts +1 -1
  55. package/src/story-variables.ts +98 -102
  56. package/src/triggers.ts +6 -5
  57. package/src/utils/error-message.ts +12 -0
  58. package/src/utils/live-locals.ts +10 -3
  59. package/src/utils/namespace.ts +71 -0
  60. package/src/utils/object-path.ts +99 -14
  61. package/src/utils/stable-key.ts +14 -9
  62. package/src/widgets/widget-registry.ts +9 -0
  63. package/types/index.d.ts +43 -7
  64. package/types/tooling.d.ts +1 -0
@@ -69,6 +69,30 @@ export async function initSaveSystem(): Promise<void> {
69
69
  initialized = true;
70
70
  }
71
71
 
72
+ // --- Operation order ---
73
+
74
+ /** Tail of the queue every storage operation runs through. */
75
+ let operationQueue: Promise<unknown> = Promise.resolve();
76
+
77
+ /**
78
+ * Run a storage operation once every operation issued before it has
79
+ * finished, so operations take effect in the order they are called. Each
80
+ * one reads and writes several records (a slot's pointer, the save, the
81
+ * slot index, playthrough records) as a unit; run concurrently they would
82
+ * interleave: a delete issued after a save could run before it, a rename
83
+ * could write a save's old payload back over an overwrite, or a playthrough
84
+ * deletion could miss a save being written.
85
+ *
86
+ * Exported operations queue themselves; the `...Now` helpers they share run
87
+ * inside an operation and must not be called from outside one. An operation
88
+ * must never wait for another operation queued after it.
89
+ */
90
+ function inOrder<T>(op: () => Promise<T>): Promise<T> {
91
+ const run = operationQueue.then(op);
92
+ operationQueue = run.catch(() => {});
93
+ return run;
94
+ }
95
+
72
96
  // --- Playthroughs ---
73
97
 
74
98
  /**
@@ -76,13 +100,19 @@ export async function initSaveSystem(): Promise<void> {
76
100
  * the caller has already switched to the playthrough (restart() does, so
77
101
  * saves issued before this resolves are tagged with it).
78
102
  */
79
- export async function startNewPlaythrough(
103
+ export function startNewPlaythrough(
80
104
  ifid: string,
81
105
  id: string = crypto.randomUUID(),
106
+ ): Promise<string> {
107
+ return inOrder(() => startNewPlaythroughNow(ifid, id));
108
+ }
109
+
110
+ async function startNewPlaythroughNow(
111
+ ifid: string,
112
+ id: string,
82
113
  ): Promise<string> {
83
114
  const backend = await getBackend();
84
- const existing = await backend.getPlaythroughsByIfid(ifid);
85
- const num = existing.length + 1;
115
+ const num = await nextPlaythroughNumber(ifid);
86
116
 
87
117
  const record: PlaythroughRecord = {
88
118
  id,
@@ -92,14 +122,90 @@ export async function startNewPlaythrough(
92
122
  };
93
123
 
94
124
  await backend.putPlaythrough(record);
95
- await backend.setMeta(`currentPlaythroughId.${ifid}`, id);
125
+ await backend.setMeta(playthroughCountKey(ifid), num);
126
+ await backend.setMeta(currentPlaythroughKey(ifid), id);
96
127
  return id;
97
128
  }
98
129
 
99
- export async function getCurrentPlaythroughId(
130
+ const PLAYTHROUGH_LABEL = /^Playthrough (\d+)$/;
131
+
132
+ function playthroughCountKey(ifid: string): string {
133
+ return `playthroughCount.${ifid}`;
134
+ }
135
+
136
+ /**
137
+ * The number of the next playthrough the story starts: one past the highest
138
+ * number given so far. The count is stored, so deleting a playthrough never
139
+ * frees its number for another (two groups labelled alike); the highest
140
+ * existing label covers data stored before the count was. Imported
141
+ * playthroughs take no number.
142
+ */
143
+ async function nextPlaythroughNumber(ifid: string): Promise<number> {
144
+ const backend = await getBackend();
145
+ let highest = (await backend.getMeta<number>(playthroughCountKey(ifid))) ?? 0;
146
+ for (const pt of await backend.getPlaythroughsByIfid(ifid)) {
147
+ const match = PLAYTHROUGH_LABEL.exec(pt.label);
148
+ if (match) highest = Math.max(highest, Number(match[1]));
149
+ }
150
+ return highest + 1;
151
+ }
152
+
153
+ function currentPlaythroughKey(ifid: string): string {
154
+ return `currentPlaythroughId.${ifid}`;
155
+ }
156
+
157
+ export function getCurrentPlaythroughId(
100
158
  ifid: string,
101
159
  ): Promise<string | undefined> {
102
- return (await getBackend()).getMeta<string>(`currentPlaythroughId.${ifid}`);
160
+ return inOrder(async () =>
161
+ (await getBackend()).getMeta<string>(currentPlaythroughKey(ifid)),
162
+ );
163
+ }
164
+
165
+ /**
166
+ * Make `id` the story's current playthrough: the playthrough of a save the
167
+ * game has loaded. A no-op if it already is. A playthrough without a record
168
+ * in this browser (that of an imported save whose record was deleted since,
169
+ * or of a save a dialog still showed after its playthrough was deleted) is
170
+ * recorded again as "Imported", as importing the save would: it was not
171
+ * started here, so it takes no number.
172
+ */
173
+ export function adoptPlaythrough(ifid: string, id: string): Promise<void> {
174
+ return inOrder(() => adoptPlaythroughNow(ifid, id));
175
+ }
176
+
177
+ async function adoptPlaythroughNow(ifid: string, id: string): Promise<void> {
178
+ const backend = await getBackend();
179
+ const playthroughs = await backend.getPlaythroughsByIfid(ifid);
180
+ if (!playthroughs.some((p) => p.id === id)) {
181
+ await backend.putPlaythrough({
182
+ id,
183
+ ifid,
184
+ createdAt: new Date().toISOString(),
185
+ label: 'Imported',
186
+ });
187
+ }
188
+ const key = currentPlaythroughKey(ifid);
189
+ if ((await backend.getMeta<string>(key)) !== id) {
190
+ await backend.setMeta(key, id);
191
+ }
192
+ }
193
+
194
+ /**
195
+ * Set up the save system for a story that boots: the story's current
196
+ * playthrough (a new one if it has none) and the slots holding saves (see
197
+ * populateKnownSaves), looked up together in one operation.
198
+ */
199
+ export function establishPlaythrough(
200
+ ifid: string,
201
+ ): Promise<{ id: string; knownSaves: Record<string, true> }> {
202
+ return inOrder(async () => {
203
+ const backend = await getBackend();
204
+ const id =
205
+ (await backend.getMeta<string>(currentPlaythroughKey(ifid))) ??
206
+ (await startNewPlaythroughNow(ifid, crypto.randomUUID()));
207
+ return { id, knownSaves: await populateKnownSavesNow(ifid) };
208
+ });
103
209
  }
104
210
 
105
211
  // --- Save Hooks ---
@@ -139,11 +245,20 @@ export function saveWithHooks<T>(
139
245
 
140
246
  // --- Save CRUD ---
141
247
 
142
- export async function createSave(
248
+ export function createSave(
143
249
  ifid: string,
144
250
  playthroughId: string,
145
251
  payload: SavePayload,
146
252
  custom: Record<string, unknown> = {},
253
+ ): Promise<SaveRecord> {
254
+ return inOrder(() => createSaveNow(ifid, playthroughId, payload, custom));
255
+ }
256
+
257
+ async function createSaveNow(
258
+ ifid: string,
259
+ playthroughId: string,
260
+ payload: SavePayload,
261
+ custom: Record<string, unknown>,
147
262
  ): Promise<SaveRecord> {
148
263
  const now = new Date().toISOString();
149
264
  const meta: SaveMeta = {
@@ -184,7 +299,18 @@ export async function createSave(
184
299
  * save itself rather than describing its content. `custom` is merged, as
185
300
  * before, so slot keys and metadata not passed again are kept.
186
301
  */
187
- export async function overwriteSave(
302
+ export function overwriteSave(
303
+ saveId: string,
304
+ payload: SavePayload,
305
+ custom?: Record<string, unknown>,
306
+ playthroughId?: string,
307
+ ): Promise<SaveRecord | undefined> {
308
+ return inOrder(() =>
309
+ overwriteSaveNow(saveId, payload, custom, playthroughId),
310
+ );
311
+ }
312
+
313
+ async function overwriteSaveNow(
188
314
  saveId: string,
189
315
  payload: SavePayload,
190
316
  custom?: Record<string, unknown>,
@@ -237,9 +363,11 @@ export function deserializePayload(payload: SavePayload): SavePayload {
237
363
  };
238
364
  }
239
365
 
240
- export async function loadSave(
241
- saveId: string,
242
- ): Promise<SavePayload | undefined> {
366
+ export function loadSave(saveId: string): Promise<SavePayload | undefined> {
367
+ return inOrder(() => loadSaveNow(saveId));
368
+ }
369
+
370
+ async function loadSaveNow(saveId: string): Promise<SavePayload | undefined> {
243
371
  const record = await (await getBackend()).getSave(saveId);
244
372
  if (!record) return undefined;
245
373
  return deserializePayload(record.payload);
@@ -249,41 +377,40 @@ export async function loadSave(
249
377
  * Delete a save record. If the default slot or a named slot holds it, that
250
378
  * slot is cleared as well (pointer and slot index), as `deleteSlotSave` would.
251
379
  */
252
- export async function deleteSaveById(saveId: string): Promise<void> {
253
- const backend = await getBackend();
254
- const record = await backend.getSave(saveId);
255
- await backend.deleteSave(saveId);
256
- if (!record) return;
257
-
258
- const ifid = record.meta.ifid;
259
- const slots = [undefined, ...(await getIndexedSlots(ifid))];
260
- for (const slot of slots) {
261
- const metaKey = slotMetaKey(ifid, slot);
262
- await withSlot(metaKey, async () => {
263
- if ((await backend.getMeta<string>(metaKey)) !== saveId) return;
380
+ export function deleteSaveById(saveId: string): Promise<void> {
381
+ return inOrder(async () => {
382
+ const backend = await getBackend();
383
+ const record = await backend.getSave(saveId);
384
+ await backend.deleteSave(saveId);
385
+ if (!record) return;
386
+
387
+ const ifid = record.meta.ifid;
388
+ const slots = [undefined, ...(await getIndexedSlots(ifid))];
389
+ for (const slot of slots) {
390
+ const metaKey = slotMetaKey(ifid, slot);
391
+ if ((await backend.getMeta<string>(metaKey)) !== saveId) continue;
264
392
  await backend.deleteMeta(metaKey);
265
393
  await removeFromSlotIndex(ifid, slot);
266
- });
267
- }
394
+ }
395
+ });
268
396
  }
269
397
 
270
- export async function renameSave(
271
- saveId: string,
272
- newTitle: string,
273
- ): Promise<void> {
274
- const backend = await getBackend();
275
- const record = await backend.getSave(saveId);
276
- if (!record) return;
277
- const updated: SaveRecord = {
278
- ...record,
279
- meta: {
280
- ...record.meta,
281
- title: newTitle,
282
- userTitle: true,
283
- updatedAt: new Date().toISOString(),
284
- },
285
- };
286
- await backend.putSave(updated);
398
+ export function renameSave(saveId: string, newTitle: string): Promise<void> {
399
+ return inOrder(async () => {
400
+ const backend = await getBackend();
401
+ const record = await backend.getSave(saveId);
402
+ if (!record) return;
403
+ const updated: SaveRecord = {
404
+ ...record,
405
+ meta: {
406
+ ...record.meta,
407
+ title: newTitle,
408
+ userTitle: true,
409
+ updatedAt: new Date().toISOString(),
410
+ },
411
+ };
412
+ await backend.putSave(updated);
413
+ });
287
414
  }
288
415
 
289
416
  // --- Grouped Retrieval ---
@@ -293,9 +420,11 @@ export interface PlaythroughGroup {
293
420
  saves: SaveRecord[];
294
421
  }
295
422
 
296
- export async function getSavesGrouped(
297
- ifid: string,
298
- ): Promise<PlaythroughGroup[]> {
423
+ export function getSavesGrouped(ifid: string): Promise<PlaythroughGroup[]> {
424
+ return inOrder(() => getSavesGroupedNow(ifid));
425
+ }
426
+
427
+ async function getSavesGroupedNow(ifid: string): Promise<PlaythroughGroup[]> {
299
428
  const backend = await getBackend();
300
429
  const [allSaves, allPlaythroughs] = await Promise.all([
301
430
  backend.getSavesByIfid(ifid),
@@ -374,45 +503,16 @@ function slotMetaKey(ifid: string, slot?: string): string {
374
503
  : `${AUTOSAVE_KEY_PREFIX}${ifid}`;
375
504
  }
376
505
 
377
- /** Tail of each slot's operation queue, keyed by the slot's meta key. */
378
- const slotQueues = new Map<string, Promise<unknown>>();
379
-
380
- /**
381
- * Run a complete operation on one slot (save, import, delete) after the ones
382
- * already queued for it. Each operation reads the slot pointer and writes the
383
- * record and pointer as a unit, so concurrent operations on the same slot
384
- * apply in call order instead of each creating its own record.
385
- */
386
- function withSlot<T>(metaKey: string, op: () => Promise<T>): Promise<T> {
387
- const run = (slotQueues.get(metaKey) ?? Promise.resolve()).then(op);
388
- const tail = run.catch(() => {});
389
- slotQueues.set(metaKey, tail);
390
- void tail.then(() => {
391
- if (slotQueues.get(metaKey) === tail) slotQueues.delete(metaKey);
392
- });
393
- return run;
394
- }
395
-
396
- /** Tail of the queue that serializes slot index updates. */
397
- let slotIndexQueue: Promise<unknown> = Promise.resolve();
398
-
399
- /**
400
- * Read-modify-write the per-story slot index. Updates are queued so that
401
- * concurrent saves, imports and deletes can't overwrite each other's change.
402
- */
403
- function updateSlotIndex(
506
+ /** Read-modify-write the per-story slot index. */
507
+ async function updateSlotIndex(
404
508
  ifid: string,
405
509
  update: (slots: string[]) => string[],
406
510
  ): Promise<void> {
407
- const run = slotIndexQueue.then(async () => {
408
- const backend = await getBackend();
409
- const indexKey = `${SLOT_INDEX_KEY_PREFIX}${ifid}`;
410
- const existing = (await backend.getMeta<string[]>(indexKey)) ?? [];
411
- const updated = update(existing);
412
- if (updated !== existing) await backend.setMeta(indexKey, updated);
413
- });
414
- slotIndexQueue = run.catch(() => {});
415
- return run;
511
+ const backend = await getBackend();
512
+ const indexKey = `${SLOT_INDEX_KEY_PREFIX}${ifid}`;
513
+ const existing = (await backend.getMeta<string[]>(indexKey)) ?? [];
514
+ const updated = update(existing);
515
+ if (updated !== existing) await backend.setMeta(indexKey, updated);
416
516
  }
417
517
 
418
518
  /** Record a named slot in the per-story slot index (no-op for the default slot). */
@@ -447,30 +547,32 @@ function toSaveInfo(record: SaveRecord, slot?: string): SaveInfo {
447
547
  };
448
548
  }
449
549
 
550
+ /**
551
+ * Save `payload` to a slot (the default slot when `slot` is omitted),
552
+ * overwriting the save it holds. `playthroughId` may be a promise of the ID
553
+ * (settled by operations issued before this call), so the save takes its
554
+ * place in the order of operations when it is called.
555
+ */
450
556
  export function quickSave(
451
557
  ifid: string,
452
- playthroughId: string,
558
+ playthroughId: string | PromiseLike<string>,
453
559
  payload: SavePayload,
454
560
  slot?: string,
455
561
  custom?: Record<string, unknown>,
456
562
  ): Promise<SaveRecord> {
457
563
  const metaKey = slotMetaKey(ifid, slot);
458
- return withSlot(metaKey, async () => {
564
+ return inOrder(async () => {
565
+ const ptId = await playthroughId;
459
566
  const backend = await getBackend();
460
567
  const existingId = await backend.getMeta<string>(metaKey);
461
568
 
462
569
  if (existingId) {
463
- const updated = await overwriteSave(
464
- existingId,
465
- payload,
466
- custom,
467
- playthroughId,
468
- );
570
+ const updated = await overwriteSaveNow(existingId, payload, custom, ptId);
469
571
  if (updated) return updated;
470
572
  }
471
573
 
472
574
  // Create new save
473
- const record = await createSave(ifid, playthroughId, payload, {
575
+ const record = await createSaveNow(ifid, ptId, payload, {
474
576
  isAutosave: !isNamedSlot(slot),
475
577
  ...(isNamedSlot(slot) ? { slot } : {}),
476
578
  ...custom,
@@ -482,10 +584,11 @@ export function quickSave(
482
584
  });
483
585
  }
484
586
 
485
- export async function hasQuickSave(
486
- ifid: string,
487
- slot?: string,
488
- ): Promise<boolean> {
587
+ export function hasQuickSave(ifid: string, slot?: string): Promise<boolean> {
588
+ return inOrder(() => hasQuickSaveNow(ifid, slot));
589
+ }
590
+
591
+ async function hasQuickSaveNow(ifid: string, slot?: string): Promise<boolean> {
489
592
  const backend = await getBackend();
490
593
  const metaKey = slotMetaKey(ifid, slot);
491
594
  const existingId = await backend.getMeta<string>(metaKey);
@@ -494,34 +597,67 @@ export async function hasQuickSave(
494
597
  return record !== undefined;
495
598
  }
496
599
 
497
- export async function loadQuickSave(
600
+ export function loadQuickSave(
498
601
  ifid: string,
499
602
  slot?: string,
500
603
  ): Promise<SavePayload | undefined> {
604
+ return inOrder(async () => {
605
+ const metaKey = slotMetaKey(ifid, slot);
606
+ const existingId = await (await getBackend()).getMeta<string>(metaKey);
607
+ if (!existingId) return undefined;
608
+ return loadSaveNow(existingId);
609
+ });
610
+ }
611
+
612
+ /**
613
+ * Read the save held in a slot (the default slot when `slot` is omitted) for
614
+ * the running game to load, and make its playthrough the story's current one
615
+ * (see adoptPlaythrough) in the same operation: operations issued after the
616
+ * load take effect in the loaded playthrough. Resolves to the live payload
617
+ * and its playthrough, or undefined if the slot is empty.
618
+ */
619
+ export function loadSlotSave(
620
+ ifid: string,
621
+ slot?: string,
622
+ ): Promise<{ payload: SavePayload; playthroughId: string } | undefined> {
501
623
  const metaKey = slotMetaKey(ifid, slot);
502
- const existingId = await (await getBackend()).getMeta<string>(metaKey);
503
- if (!existingId) return undefined;
504
- return loadSave(existingId);
624
+ return inOrder(async () => {
625
+ const backend = await getBackend();
626
+ const existingId = await backend.getMeta<string>(metaKey);
627
+ if (!existingId) return undefined;
628
+ const record = await backend.getSave(existingId);
629
+ if (!record) return undefined;
630
+ const payload = deserializePayload(record.payload);
631
+ const { playthroughId } = record.meta;
632
+ if (playthroughId) await adoptPlaythroughNow(ifid, playthroughId);
633
+ return { payload, playthroughId };
634
+ });
505
635
  }
506
636
 
507
637
  /**
508
638
  * Check storage for all known saves and return a map of slot keys to true.
509
639
  * The default (autosave) slot uses empty string as key.
510
640
  */
511
- export async function populateKnownSaves(
641
+ export function populateKnownSaves(
642
+ ifid: string,
643
+ ): Promise<Record<string, true>> {
644
+ return inOrder(() => populateKnownSavesNow(ifid));
645
+ }
646
+
647
+ async function populateKnownSavesNow(
512
648
  ifid: string,
513
649
  ): Promise<Record<string, true>> {
514
650
  // No prototype, so a slot named '__proto__' is recorded as an entry
515
651
  const result = Object.create(null) as Record<string, true>;
516
652
 
517
653
  // Check default autosave
518
- if (await hasQuickSave(ifid)) {
654
+ if (await hasQuickSaveNow(ifid)) {
519
655
  result[''] = true;
520
656
  }
521
657
 
522
658
  // Check named slots from the index
523
659
  for (const slot of await getIndexedSlots(ifid)) {
524
- if (await hasQuickSave(ifid, slot)) {
660
+ if (await hasQuickSaveNow(ifid, slot)) {
525
661
  result[slot] = true;
526
662
  }
527
663
  }
@@ -533,7 +669,14 @@ export async function populateKnownSaves(
533
669
  * Get metadata for a specific save slot.
534
670
  * Returns null if no save exists for that slot.
535
671
  */
536
- export async function getSlotSaveInfo(
672
+ export function getSlotSaveInfo(
673
+ ifid: string,
674
+ slot?: string,
675
+ ): Promise<SaveInfo | null> {
676
+ return inOrder(() => getSlotSaveInfoNow(ifid, slot));
677
+ }
678
+
679
+ async function getSlotSaveInfoNow(
537
680
  ifid: string,
538
681
  slot?: string,
539
682
  ): Promise<SaveInfo | null> {
@@ -549,20 +692,22 @@ export async function getSlotSaveInfo(
549
692
  /**
550
693
  * List metadata for all known save slots (default + named).
551
694
  */
552
- export async function listSlotSaves(ifid: string): Promise<SaveInfo[]> {
553
- const result: SaveInfo[] = [];
554
-
555
- // Check default autosave
556
- const defaultInfo = await getSlotSaveInfo(ifid);
557
- if (defaultInfo) result.push(defaultInfo);
558
-
559
- // Check named slots from the index
560
- for (const slot of await getIndexedSlots(ifid)) {
561
- const info = await getSlotSaveInfo(ifid, slot);
562
- if (info) result.push(info);
563
- }
695
+ export function listSlotSaves(ifid: string): Promise<SaveInfo[]> {
696
+ return inOrder(async () => {
697
+ const result: SaveInfo[] = [];
698
+
699
+ // Check default autosave
700
+ const defaultInfo = await getSlotSaveInfoNow(ifid);
701
+ if (defaultInfo) result.push(defaultInfo);
702
+
703
+ // Check named slots from the index
704
+ for (const slot of await getIndexedSlots(ifid)) {
705
+ const info = await getSlotSaveInfoNow(ifid, slot);
706
+ if (info) result.push(info);
707
+ }
564
708
 
565
- return result;
709
+ return result;
710
+ });
566
711
  }
567
712
 
568
713
  /**
@@ -570,7 +715,7 @@ export async function listSlotSaves(ifid: string): Promise<SaveInfo[]> {
570
715
  */
571
716
  export function deleteSlotSave(ifid: string, slot?: string): Promise<void> {
572
717
  const metaKey = slotMetaKey(ifid, slot);
573
- return withSlot(metaKey, async () => {
718
+ return inOrder(async () => {
574
719
  const backend = await getBackend();
575
720
  const existingId = await backend.getMeta<string>(metaKey);
576
721
  if (!existingId) return;
@@ -624,9 +769,11 @@ export function clearSession(ifid: string): void {
624
769
 
625
770
  // --- Export / Import ---
626
771
 
627
- export async function exportSave(
628
- saveId: string,
629
- ): Promise<SaveExport | undefined> {
772
+ export function exportSave(saveId: string): Promise<SaveExport | undefined> {
773
+ return inOrder(() => exportSaveNow(saveId));
774
+ }
775
+
776
+ async function exportSaveNow(saveId: string): Promise<SaveExport | undefined> {
630
777
  const record = await (await getBackend()).getSave(saveId);
631
778
  if (!record) return undefined;
632
779
 
@@ -667,6 +814,9 @@ async function prepareImport(
667
814
  const record = deepClone(data.save);
668
815
  record.meta.id = crypto.randomUUID();
669
816
  record.meta.updatedAt = new Date().toISOString();
817
+ // The save now belongs to this story: it is listed, loaded and cleared
818
+ // with it, whatever its own metadata says
819
+ record.meta.ifid = ifid;
670
820
 
671
821
  // Ensure the playthrough exists
672
822
  const playthroughs = await backend.getPlaythroughsByIfid(ifid);
@@ -685,28 +835,32 @@ async function prepareImport(
685
835
  return record;
686
836
  }
687
837
 
688
- export async function importSave(
838
+ export function importSave(
689
839
  data: SaveExport,
690
840
  ifid: string,
691
841
  ): Promise<SaveRecord> {
692
- const record = await prepareImport(data, ifid);
693
- await (await getBackend()).putSave(record);
694
- return record;
842
+ return inOrder(async () => {
843
+ const record = await prepareImport(data, ifid);
844
+ await (await getBackend()).putSave(record);
845
+ return record;
846
+ });
695
847
  }
696
848
 
697
849
  /**
698
850
  * Export the save held in a slot (default autosave slot when `slot` is omitted).
699
851
  * Returns undefined if the slot is empty.
700
852
  */
701
- export async function exportSlotSave(
853
+ export function exportSlotSave(
702
854
  ifid: string,
703
855
  slot?: string,
704
856
  ): Promise<SaveExport | undefined> {
705
- const saveId = await (
706
- await getBackend()
707
- ).getMeta<string>(slotMetaKey(ifid, slot));
708
- if (!saveId) return undefined;
709
- return exportSave(saveId);
857
+ return inOrder(async () => {
858
+ const saveId = await (
859
+ await getBackend()
860
+ ).getMeta<string>(slotMetaKey(ifid, slot));
861
+ if (!saveId) return undefined;
862
+ return exportSaveNow(saveId);
863
+ });
710
864
  }
711
865
 
712
866
  /**
@@ -721,7 +875,7 @@ export function importSlotSave(
721
875
  slot?: string,
722
876
  ): Promise<SaveInfo> {
723
877
  const metaKey = slotMetaKey(ifid, slot);
724
- return withSlot(metaKey, async () => {
878
+ return inOrder(async () => {
725
879
  const record = await prepareImport(data, ifid);
726
880
 
727
881
  // The slot keys in `custom` describe where the save lives, so they follow
@@ -747,7 +901,11 @@ export function importSlotSave(
747
901
 
748
902
  // --- Storage Management ---
749
903
 
750
- export async function getStorageInfo(ifid: string): Promise<StorageInfo> {
904
+ export function getStorageInfo(ifid: string): Promise<StorageInfo> {
905
+ return inOrder(() => getStorageInfoNow(ifid));
906
+ }
907
+
908
+ async function getStorageInfoNow(ifid: string): Promise<StorageInfo> {
751
909
  const backend = await getBackend();
752
910
  const saves = await backend.getSavesByIfid(ifid);
753
911
  const playthroughs = await backend.getPlaythroughsByIfid(ifid);
@@ -773,15 +931,21 @@ export async function getStorageInfo(ifid: string): Promise<StorageInfo> {
773
931
  };
774
932
  }
775
933
 
776
- export async function clearGameData(ifid: string): Promise<void> {
777
- const backend = await getBackend();
778
- await backend.deleteSavesByIfid(ifid);
779
- await backend.deletePlaythroughsByIfid(ifid);
780
- await backend.deleteMetaByIfid(ifid);
781
- clearSession(ifid);
934
+ export function clearGameData(ifid: string): Promise<void> {
935
+ return inOrder(async () => {
936
+ const backend = await getBackend();
937
+ await backend.deleteSavesByIfid(ifid);
938
+ await backend.deletePlaythroughsByIfid(ifid);
939
+ await backend.deleteMetaByIfid(ifid);
940
+ clearSession(ifid);
941
+ });
782
942
  }
783
943
 
784
- export async function clearAllData(): Promise<void> {
944
+ export function clearAllData(): Promise<void> {
945
+ return inOrder(clearAllDataNow);
946
+ }
947
+
948
+ async function clearAllDataNow(): Promise<void> {
785
949
  const backend = await getBackend();
786
950
  await backend.destroy();
787
951
  resetBackend();
@@ -797,30 +961,47 @@ export async function clearAllData(): Promise<void> {
797
961
  }
798
962
  }
799
963
 
800
- export async function deletePlaythroughData(
964
+ /**
965
+ * Delete a playthrough with its saves, emptying the slots that held them.
966
+ *
967
+ * `replacement` is for deleting the playthrough a running game is in:
968
+ * `current` is (a promise of) that game's playthrough, settled by operations
969
+ * issued before this call. If it is the deleted one, the playthrough
970
+ * `replacement.id` is started in the same operation, before any operation
971
+ * issued later. Resolves to whether it was.
972
+ */
973
+ export function deletePlaythroughData(
801
974
  ifid: string,
802
975
  playthroughId: string,
803
- ): Promise<void> {
804
- const backend = await getBackend();
805
- const deletedSaveIds = await backend.deleteSavesByPlaythrough(playthroughId);
806
- await backend.deletePlaythroughById(playthroughId);
807
-
808
- // Clean up slot/autosave meta keys pointing to deleted saves
809
- const deletedSet = new Set(deletedSaveIds);
810
- const allKeys = await backend.getAllMetaKeys();
811
- for (const key of allKeys) {
812
- if (key.startsWith('slot.') || key.startsWith('autosave.')) {
813
- const value = await backend.getMeta<string>(key);
976
+ replacement?: { current: string | PromiseLike<string>; id: string },
977
+ ): Promise<boolean> {
978
+ return inOrder(async () => {
979
+ const backend = await getBackend();
980
+ const deletedSaveIds =
981
+ await backend.deleteSavesByPlaythrough(playthroughId);
982
+ await backend.deletePlaythroughById(playthroughId);
983
+
984
+ // Clear the slots that held deleted saves (pointer and slot index)
985
+ const deletedSet = new Set(deletedSaveIds);
986
+ for (const slot of [undefined, ...(await getIndexedSlots(ifid))]) {
987
+ const metaKey = slotMetaKey(ifid, slot);
988
+ const value = await backend.getMeta<string>(metaKey);
814
989
  if (value && deletedSet.has(value)) {
815
- await backend.deleteMeta(key);
990
+ await backend.deleteMeta(metaKey);
991
+ await removeFromSlotIndex(ifid, slot);
816
992
  }
817
993
  }
818
- }
819
994
 
820
- // Clear currentPlaythroughId if it was this one
821
- const currentPtKey = `currentPlaythroughId.${ifid}`;
822
- const currentPt = await backend.getMeta<string>(currentPtKey);
823
- if (currentPt === playthroughId) {
824
- await backend.deleteMeta(currentPtKey);
825
- }
995
+ if (replacement && (await replacement.current) === playthroughId) {
996
+ await startNewPlaythroughNow(ifid, replacement.id);
997
+ return true;
998
+ }
999
+
1000
+ // Clear currentPlaythroughId if it was this one
1001
+ const currentPtKey = currentPlaythroughKey(ifid);
1002
+ if ((await backend.getMeta<string>(currentPtKey)) === playthroughId) {
1003
+ await backend.deleteMeta(currentPtKey);
1004
+ }
1005
+ return false;
1006
+ });
826
1007
  }