@mpgd/tutorial 0.1.0 → 0.1.2

package/dist/director.js

@@ -16,22 +16,114 @@ export function createTutorialDirector(input) {
     let currentScene = input.initialScene ?? definition.initialScene;
     let publishing = false;
     const pendingSnapshots = [];
+    const persistenceQueue = [];
+    let persistenceBusy = false;
+    let persistenceIdle = null;
+    let resolvePersistenceIdle = null;
+    let publicationVersion = 0;
+    let snapshot = createSnapshot(definition, progress, replaying, suspended, currentScene);
     if (stored === null && progress !== null) {
-        persist(progress);
+        void persist(progress);
     }
-    let snapshot = createSnapshot(definition, progress, replaying, suspended, currentScene);
     function now() {
         return clock().toISOString();
     }
-    function persist(next) {
-        if (destroyed || replaying) {
+    function reportError(error) {
+        try {
+            input.onError?.(error);
+        }
+        catch {
+            // Error reporting must not interrupt tutorial state transitions.
+        }
+    }
+    function invokeProgressSave(next) {
+        try {
+            return progressStore.save(next).catch((error) => {
+                reportError(error);
+            });
+        }
+        catch (error) {
+            reportError(error);
+            return null;
+        }
+    }
+    function finishPersistenceCycle() {
+        const resolveIdle = resolvePersistenceIdle;
+        resolvePersistenceIdle = null;
+        persistenceIdle = null;
+        resolveIdle?.();
+    }
+    function pumpPersistence() {
+        if (persistenceBusy) {
             return;
         }
-        void progressStore.save(next).catch((error) => {
-            input.onError?.(error);
+        while (true) {
+            const pending = persistenceQueue.shift();
+            if (pending === undefined) {
+                finishPersistenceCycle();
+                return;
+            }
+            persistenceBusy = true;
+            const operation = invokeProgressSave(pending.progress);
+            if (operation === null) {
+                persistenceBusy = false;
+                pending.resolve();
+                continue;
+            }
+            void operation.then(() => {
+                persistenceBusy = false;
+                pending.resolve();
+                pumpPersistence();
+            });
+            return;
+        }
+    }
+    function enqueuePersistence(next) {
+        const completion = new Promise((resolve) => {
+            persistenceQueue.push({ progress: next, resolve });
         });
+        if (persistenceIdle === null) {
+            const idle = new Promise((resolve) => {
+                resolvePersistenceIdle = resolve;
+            });
+            void (persistenceIdle = idle);
+        }
+        pumpPersistence();
+        return completion;
+    }
+    function persist(next) {
+        if (destroyed || replaying) {
+            return Promise.resolve();
+        }
+        return enqueuePersistence(next);
+    }
+    async function flush() {
+        const pendingPersistence = persistenceIdle;
+        if (pendingPersistence !== null) {
+            await pendingPersistence;
+        }
+        await progressStore.flush();
+    }
+    function persistAndPublish(next) {
+        const versionBeforePersistence = publicationVersion;
+        void persist(next);
+        if (publicationVersion === versionBeforePersistence) {
+            publish();
+        }
+    }
+    function notifyListener(listener, nextSnapshot) {
+        try {
+            listener(nextSnapshot);
+        }
+        catch (error) {
+            reportError(error);
+        }
     }
     function publish() {
+        if (destroyed) {
+            return;
+        }
+        publicationVersion += 1;
         const publishedSnapshot = createSnapshot(definition, progress, replaying, suspended, currentScene);
         pendingSnapshots.push(publishedSnapshot);
         if (publishing) {
@@ -48,7 +140,7 @@ export function createTutorialDirector(input) {
                 const recipients = [...listeners];
                 for (const subscription of recipients) {
                     if (listeners.has(subscription)) {
-                        subscription.listener(pendingSnapshot);
+                        notifyListener(subscription.listener, pendingSnapshot);
                     }
                 }
             }
@@ -99,44 +191,63 @@ export function createTutorialDirector(input) {
             replayRestorePending = false;
             durableBeforeReplay = null;
         }
-        persist(progress);
-        publish();
+        persistAndPublish(progress);
     }
     return {
         acknowledge(stepId) {
+            if (destroyed) {
+                return;
+            }
             const step = getCurrentStep();
             if (step?.id === stepId && step.advance.kind === 'acknowledge') {
                 advanceCurrent();
             }
         },
         destroy() {
+            if (destroyed) {
+                return;
+            }
             destroyed = true;
             listeners.clear();
+            pendingSnapshots.length = 0;
         },
-        flush: () => progressStore.flush(),
+        flush,
         getSnapshot: () => snapshot,
         observeAction(action) {
+            if (destroyed) {
+                return;
+            }
             const step = getCurrentStep();
             if (canAdvance(step) && step.advance.kind === 'action' && step.advance.action === action) {
                 advanceCurrent();
             }
         },
         observeScene(scene) {
+            if (destroyed) {
+                return;
+            }
             currentScene = scene;
             const step = getCurrentStep();
             if (progress?.status === 'active' && step?.scene === scene && progress.checkpoint !== scene) {
                 progress = { ...progress, checkpoint: scene, updatedAt: now() };
-                persist(progress);
+                persistAndPublish(progress);
+                return;
             }
             publish();
         },
         observeSignal(signal) {
+            if (destroyed) {
+                return;
+            }
             const step = getCurrentStep();
             if (canAdvance(step) && step.advance.kind === 'signal' && step.advance.signal === signal) {
                 advanceCurrent();
             }
         },
         async replay(options = {}) {
+            if (destroyed) {
+                return;
+            }
             const replayProgress = options.fromStepId === undefined
                 ? createInitialTutorialProgress(definition, now())
                 : createTutorialProgressAtStep(definition, options.fromStepId, now());
@@ -152,14 +263,14 @@ export function createTutorialDirector(input) {
             publish();
         },
         setSuspended(nextSuspended) {
-            if (suspended === nextSuspended) {
+            if (destroyed || suspended === nextSuspended) {
                 return;
             }
             suspended = nextSuspended;
             publish();
         },
         async skip() {
-            if (progress === null) {
+            if (destroyed || progress === null) {
                 return;
             }
             if (replaying && replayRestorePending) {
@@ -182,6 +293,7 @@ export function createTutorialDirector(input) {
                 status: 'skipped',
                 updatedAt: timestamp,
             };
+            const skippedProgress = progress;
             replaying = false;
             durableBeforeReplay = null;
             replayRestorePending = false;
@@ -192,20 +304,18 @@ export function createTutorialDirector(input) {
             finally {
                 durableFallbackDuringPublish = undefined;
             }
-            if (destroyed || replaying) {
+            if (progress !== skippedProgress || replaying) {
                 return;
             }
-            try {
-                await progressStore.save(progress);
-            }
-            catch (error) {
-                input.onError?.(error);
-            }
+            await enqueuePersistence(skippedProgress);
         },
         subscribe(listener) {
+            if (destroyed) {
+                return () => undefined;
+            }
             const subscription = { listener };
             listeners.add(subscription);
-            listener(snapshot);
+            notifyListener(listener, snapshot);
             return () => listeners.delete(subscription);
         },
     };

package/dist/driver.d.ts

@@ -35,6 +35,7 @@ export interface DriverTutorialPresenter<TStep extends TutorialStep = TutorialSt
 }
 export declare function createDriverTutorialPresenter<TStep extends TutorialStep>(input: DriverTutorialPresenterInput<TStep>): DriverTutorialPresenter<TStep>;
 export declare function resolveVisibleTutorialTarget(input: {
+  readonly preferActivatable?: boolean;
   readonly root?: Document | HTMLElement;
   readonly target: string;
   readonly targetAttribute?: string;