@daltonr/pathwrite-core 0.9.0 → 0.10.0

package/dist/index.js

@@ -14,14 +14,15 @@
 export function matchesStrategy(strategy, event) {
     switch (strategy) {
         case "onEveryChange":
-            // Only react once navigation has settled — stateChanged fires twice per
-            // navigation (isNavigating:true then false).
-            return (event.type === "stateChanged" && !event.snapshot.isNavigating)
+            // Only react once the engine has settled — stateChanged fires on every
+            // phase transition; only "idle" and "error" are settled states.
+            return (event.type === "stateChanged" &&
+                (event.snapshot.status === "idle" || event.snapshot.status === "error"))
                 || event.type === "resumed";
         case "onNext":
             return event.type === "stateChanged"
                 && event.cause === "next"
-                && !event.snapshot.isNavigating;
+                && (event.snapshot.status === "idle" || event.snapshot.status === "error");
         case "onSubPathComplete":
             return event.type === "resumed";
         case "onComplete":
@@ -33,16 +34,51 @@ export function matchesStrategy(strategy, event) {
 function isStepChoice(item) {
     return "select" in item && "steps" in item;
 }
+/**
+ * Converts a camelCase or lowercase field key to a display label.
+ * `"firstName"` → `"First Name"`, `"email"` → `"Email"`.
+ * Used by shells to render labeled field-error summaries.
+ */
+export function formatFieldKey(key) {
+    return key.replace(/([A-Z])/g, " $1").replace(/^./, c => c.toUpperCase()).trim();
+}
+/**
+ * Returns a human-readable description of which operation failed, keyed by
+ * the `ErrorPhase` value on `snapshot.error.phase`. Used by shells to render
+ * the error panel message.
+ */
+export function errorPhaseMessage(phase) {
+    switch (phase) {
+        case "entering": return "Failed to load this step.";
+        case "validating": return "The check could not be completed.";
+        case "leaving": return "Failed to save your progress.";
+        case "completing": return "Your submission could not be sent.";
+        default: return "An unexpected error occurred.";
+    }
+}
 export class PathEngine {
     activePath = null;
     pathStack = [];
     listeners = new Set();
-    _isNavigating = false;
+    _status = "idle";
     /** True after the user has called next() on the current step at least once. Resets on step entry. */
     _hasAttemptedNext = false;
+    /** Blocking message from canMoveNext returning { allowed: false, reason }. Cleared on step entry. */
+    _blockingError = null;
     /** The path and initial data from the most recent top-level start() call. Used by restart(). */
     _rootPath = null;
     _rootInitialData = {};
+    /** Structured error from the most recent failed async operation. Null when no error is active. */
+    _error = null;
+    /** Stored retry function. Null when no error is pending. */
+    _pendingRetry = null;
+    /**
+     * Counts how many times `retry()` has been called for the current error sequence.
+     * Reset to 0 by `next()` (fresh navigation). Incremented by `retry()`.
+     */
+    _retryCount = 0;
+    _hasPersistence = false;
+    _hasWarnedAsyncShouldSkip = false;
     constructor(options) {
         if (options?.observers) {
             for (const observer of options.observers) {
@@ -50,6 +86,9 @@ export class PathEngine {
                 this.listeners.add((event) => observer(event, this));
             }
         }
+        if (options?.hasPersistence) {
+            this._hasPersistence = true;
+        }
     }
     /**
      * Restores a PathEngine from previously exported state.
@@ -82,6 +121,7 @@ export class PathEngine {
                 currentStepIndex: stackItem.currentStepIndex,
                 data: { ...stackItem.data },
                 visitedStepIds: new Set(stackItem.visitedStepIds),
+                resolvedSkips: new Set(),
                 subPathMeta: stackItem.subPathMeta ? { ...stackItem.subPathMeta } : undefined,
                 stepEntryData: stackItem.stepEntryData ? { ...stackItem.stepEntryData } : { ...stackItem.data },
                 stepEnteredAt: stackItem.stepEnteredAt ?? Date.now()
@@ -97,13 +137,14 @@ export class PathEngine {
             currentStepIndex: state.currentStepIndex,
             data: { ...state.data },
             visitedStepIds: new Set(state.visitedStepIds),
+            resolvedSkips: new Set(),
             // Active path's subPathMeta is not serialized (it's transient metadata
             // from the parent when this path was started). On restore, it's undefined.
             subPathMeta: undefined,
             stepEntryData: state.stepEntryData ? { ...state.stepEntryData } : { ...state.data },
             stepEnteredAt: state.stepEnteredAt ?? Date.now()
         };
-        engine._isNavigating = state._isNavigating;
+        engine._status = state._status ?? "idle";
         // Re-derive the selected inner step for any StepChoice slots (not serialized —
         // always recomputed from current data on restore).
         for (const stackItem of engine.pathStack) {
@@ -140,7 +181,8 @@ export class PathEngine {
         if (!this._rootPath) {
             throw new Error("Cannot restart: engine has not been started. Call start() first.");
         }
-        this._isNavigating = false;
+        this._status = "idle";
+        this._blockingError = null;
         this.activePath = null;
         this.pathStack.length = 0;
         return this._startAsync(this._rootPath, { ...this._rootInitialData });
@@ -163,18 +205,68 @@ export class PathEngine {
     }
     next() {
         const active = this.requireActivePath();
+        // Reset the retry sequence. If we're recovering from an error the user
+        // explicitly clicked Next again — clear the error and reset to idle so
+        // _nextAsync's entry guard passes. For any other non-idle status (busy)
+        // the guard in _nextAsync will drop this call.
+        this._retryCount = 0;
+        this._error = null;
+        this._pendingRetry = null;
+        if (this._status === "error")
+            this._status = "idle";
         return this._nextAsync(active);
     }
     previous() {
         const active = this.requireActivePath();
         return this._previousAsync(active);
     }
+    /**
+     * Re-runs the operation that caused the most recent `snapshot.error`.
+     * Increments `snapshot.error.retryCount` so shells can escalate from
+     * "Try again" to "Come back later" after repeated failures.
+     *
+     * No-op if there is no pending error or if navigation is in progress.
+     */
+    retry() {
+        if (!this._pendingRetry || this._status !== "error")
+            return Promise.resolve();
+        this._retryCount++;
+        const fn = this._pendingRetry;
+        this._pendingRetry = null;
+        this._error = null;
+        this._status = "idle"; // allow the retry fn's entry guard to pass
+        return fn();
+    }
+    /**
+     * Pauses the path with intent to return. Preserves all state and data.
+     *
+     * - Clears any active error state
+     * - Emits a `suspended` event that the application can listen for to dismiss
+     *   the wizard UI (close a modal, navigate away, etc.)
+     * - The engine remains in its current state — call `start()` / `restoreOrStart()`
+     *   to resume when the user returns
+     *
+     * Use in the "Come back later" escalation path when `snapshot.error.retryCount`
+     * has crossed `retryThreshold`. The `suspended` event signals the app to dismiss
+     * the UI; Pathwrite's persistence layer handles saving progress automatically via
+     * the configured store and observer strategy.
+     */
+    suspend() {
+        const active = this.activePath;
+        const pathId = active?.definition.id ?? "";
+        const data = active ? { ...active.data } : {};
+        this._error = null;
+        this._pendingRetry = null;
+        this._status = "idle";
+        this.emit({ type: "suspended", pathId, data });
+        return Promise.resolve();
+    }
     /** Cancel is synchronous for top-level paths (no hooks). Sub-path cancellation
      *  is async when an `onSubPathCancel` hook is present. Returns a Promise for
      *  API consistency. */
     async cancel() {
         const active = this.requireActivePath();
-        if (this._isNavigating)
+        if (this._status !== "idle")
             return;
         const cancelledPathId = active.definition.id;
         const cancelledData = { ...active.data };
@@ -247,24 +339,32 @@ export class PathEngine {
         const item = this.getCurrentItem(active);
         const effectiveStep = this.getEffectiveStep(active);
         const { steps } = active.definition;
-        const stepCount = steps.length;
+        // Filter out steps confirmed as skipped during navigation. Steps not yet
+        // evaluated (e.g. on first render) are included optimistically.
+        const visibleSteps = steps.filter(s => !active.resolvedSkips.has(s.id));
+        const stepCount = visibleSteps.length;
+        const visibleIndex = visibleSteps.findIndex(s => s.id === item.id);
+        // Fall back to raw index if not found (should not happen in normal use)
+        const effectiveStepIndex = visibleIndex >= 0 ? visibleIndex : active.currentStepIndex;
         // Build rootProgress from the bottom of the stack (the top-level path)
         let rootProgress;
         if (this.pathStack.length > 0) {
             const root = this.pathStack[0];
-            const rootSteps = root.definition.steps;
-            const rootStepCount = rootSteps.length;
+            const rootVisibleSteps = root.definition.steps.filter(s => !root.resolvedSkips.has(s.id));
+            const rootStepCount = rootVisibleSteps.length;
+            const rootVisibleIndex = rootVisibleSteps.findIndex(s => s.id === root.definition.steps[root.currentStepIndex]?.id);
+            const rootEffectiveIndex = rootVisibleIndex >= 0 ? rootVisibleIndex : root.currentStepIndex;
             rootProgress = {
                 pathId: root.definition.id,
-                stepIndex: root.currentStepIndex,
+                stepIndex: rootEffectiveIndex,
                 stepCount: rootStepCount,
-                progress: rootStepCount <= 1 ? 1 : root.currentStepIndex / (rootStepCount - 1),
-                steps: rootSteps.map((s, i) => ({
+                progress: rootStepCount <= 1 ? 1 : rootEffectiveIndex / (rootStepCount - 1),
+                steps: rootVisibleSteps.map((s, i) => ({
                     id: s.id,
                     title: s.title,
                     meta: s.meta,
-                    status: i < root.currentStepIndex ? "completed"
-                        : i === root.currentStepIndex ? "current"
+                    status: i < rootEffectiveIndex ? "completed"
+                        : i === rootEffectiveIndex ? "current"
                             : "upcoming"
                 }))
             };
@@ -275,24 +375,27 @@ export class PathEngine {
             stepTitle: effectiveStep.title ?? item.title,
             stepMeta: effectiveStep.meta ?? item.meta,
             formId: isStepChoice(item) ? effectiveStep.id : undefined,
-            stepIndex: active.currentStepIndex,
+            stepIndex: effectiveStepIndex,
             stepCount,
-            progress: stepCount <= 1 ? 1 : active.currentStepIndex / (stepCount - 1),
-            steps: steps.map((s, i) => ({
+            progress: stepCount <= 1 ? 1 : effectiveStepIndex / (stepCount - 1),
+            steps: visibleSteps.map((s, i) => ({
                 id: s.id,
                 title: s.title,
                 meta: s.meta,
-                status: i < active.currentStepIndex ? "completed"
-                    : i === active.currentStepIndex ? "current"
+                status: i < effectiveStepIndex ? "completed"
+                    : i === effectiveStepIndex ? "current"
                         : "upcoming"
             })),
-            isFirstStep: active.currentStepIndex === 0,
-            isLastStep: active.currentStepIndex === stepCount - 1 &&
+            isFirstStep: effectiveStepIndex === 0,
+            isLastStep: effectiveStepIndex === stepCount - 1 &&
                 this.pathStack.length === 0,
             nestingLevel: this.pathStack.length,
             rootProgress,
-            isNavigating: this._isNavigating,
+            status: this._status,
+            error: this._error,
+            hasPersistence: this._hasPersistence,
             hasAttemptedNext: this._hasAttemptedNext,
+            blockingError: this._blockingError,
             canMoveNext: this.evaluateCanMoveNextSync(effectiveStep, active),
             canMovePrevious: this.evaluateGuardSync(effectiveStep.canMovePrevious, active),
             fieldErrors: this.evaluateFieldMessagesSync(effectiveStep.fieldErrors, active),
@@ -335,14 +438,14 @@ export class PathEngine {
                 stepEntryData: { ...p.stepEntryData },
                 stepEnteredAt: p.stepEnteredAt
             })),
-            _isNavigating: this._isNavigating
+            _status: this._status
         };
     }
     // ---------------------------------------------------------------------------
     // Private async helpers
     // ---------------------------------------------------------------------------
     async _startAsync(path, initialData, subPathMeta) {
-        if (this._isNavigating)
+        if (this._status !== "idle")
             return;
         if (this.activePath !== null) {
             // Store the meta on the parent before pushing to stack
@@ -357,131 +460,147 @@ export class PathEngine {
             currentStepIndex: 0,
             data: { ...initialData },
             visitedStepIds: new Set(),
+            resolvedSkips: new Set(),
             subPathMeta: undefined,
             stepEntryData: { ...initialData }, // Will be updated in enterCurrentStep
             stepEnteredAt: 0 // Will be set in enterCurrentStep
         };
-        this._isNavigating = true;
         await this.skipSteps(1);
         if (this.activePath.currentStepIndex >= path.steps.length) {
-            this._isNavigating = false;
-            await this.finishActivePath();
+            await this._finishActivePathWithErrorHandling();
             return;
         }
+        this._status = "entering";
         this.emitStateChanged("start");
-        try {
-            this.applyPatch(await this.enterCurrentStep());
-            this._isNavigating = false;
-            this.emitStateChanged("start");
-        }
-        catch (err) {
-            this._isNavigating = false;
-            this.emitStateChanged("start");
-            throw err;
-        }
+        await this._enterCurrentStepWithErrorHandling("start");
     }
     async _nextAsync(active) {
-        if (this._isNavigating)
+        if (this._status !== "idle")
             return;
         // Record that the user has attempted to advance — used by shells and step
         // templates to gate error display ("punish late, reward early").
         this._hasAttemptedNext = true;
-        this._isNavigating = true;
+        // Phase: validating — canMoveNext guard
+        this._status = "validating";
         this.emitStateChanged("next");
+        let guardResult;
         try {
-            const step = this.getEffectiveStep(active);
-            if (await this.canMoveNext(active, step)) {
-                this.applyPatch(await this.leaveCurrentStep(active, step));
-                active.currentStepIndex += 1;
-                await this.skipSteps(1);
-                if (active.currentStepIndex >= active.definition.steps.length) {
-                    this._isNavigating = false;
-                    await this.finishActivePath();
-                    return;
-                }
-                this.applyPatch(await this.enterCurrentStep());
-            }
-            this._isNavigating = false;
-            this.emitStateChanged("next");
+            guardResult = await this.canMoveNext(active, this.getEffectiveStep(active));
         }
         catch (err) {
-            this._isNavigating = false;
+            this._error = { message: PathEngine.errorMessage(err), phase: "validating", retryCount: this._retryCount };
+            this._pendingRetry = () => this._nextAsync(active);
+            this._status = "error";
             this.emitStateChanged("next");
-            throw err;
+            return;
+        }
+        if (guardResult.allowed) {
+            // Phase: leaving — onLeave hook
+            this._status = "leaving";
+            this.emitStateChanged("next");
+            try {
+                this.applyPatch(await this.leaveCurrentStep(active, this.getEffectiveStep(active)));
+            }
+            catch (err) {
+                this._error = { message: PathEngine.errorMessage(err), phase: "leaving", retryCount: this._retryCount };
+                this._pendingRetry = () => this._nextAsync(active);
+                this._status = "error";
+                this.emitStateChanged("next");
+                return;
+            }
+            active.currentStepIndex += 1;
+            await this.skipSteps(1);
+            if (active.currentStepIndex >= active.definition.steps.length) {
+                // Phase: completing — PathDefinition.onComplete
+                await this._finishActivePathWithErrorHandling();
+                return;
+            }
+            // Phase: entering — onEnter hook on the new step
+            await this._enterCurrentStepWithErrorHandling("next");
+            return;
         }
+        this._blockingError = guardResult.reason;
+        this._status = "idle";
+        this.emitStateChanged("next");
     }
     async _previousAsync(active) {
-        if (this._isNavigating)
+        if (this._status !== "idle")
             return;
         // No-op when already on the first step of a top-level path.
         // Sub-paths still cancel/pop back to the parent when previous() is called
         // on their first step (the currentStepIndex < 0 branch below handles that).
         if (active.currentStepIndex === 0 && this.pathStack.length === 0)
             return;
-        this._isNavigating = true;
+        this._status = "leaving";
         this.emitStateChanged("previous");
         try {
             const step = this.getEffectiveStep(active);
-            if (await this.canMovePrevious(active, step)) {
+            const prevGuard = await this.canMovePrevious(active, step);
+            if (!prevGuard.allowed)
+                this._blockingError = prevGuard.reason;
+            if (prevGuard.allowed) {
                 this.applyPatch(await this.leaveCurrentStep(active, step));
                 active.currentStepIndex -= 1;
                 await this.skipSteps(-1);
                 if (active.currentStepIndex < 0) {
-                    this._isNavigating = false;
+                    this._status = "idle";
                     await this.cancel();
                     return;
                 }
                 this.applyPatch(await this.enterCurrentStep());
             }
-            this._isNavigating = false;
+            this._status = "idle";
             this.emitStateChanged("previous");
         }
         catch (err) {
-            this._isNavigating = false;
+            this._status = "idle";
             this.emitStateChanged("previous");
             throw err;
         }
     }
     async _goToStepAsync(active, targetIndex) {
-        if (this._isNavigating)
+        if (this._status !== "idle")
             return;
-        this._isNavigating = true;
+        this._status = "leaving";
         this.emitStateChanged("goToStep");
         try {
             const currentStep = this.getEffectiveStep(active);
             this.applyPatch(await this.leaveCurrentStep(active, currentStep));
             active.currentStepIndex = targetIndex;
             this.applyPatch(await this.enterCurrentStep());
-            this._isNavigating = false;
+            this._status = "idle";
             this.emitStateChanged("goToStep");
         }
         catch (err) {
-            this._isNavigating = false;
+            this._status = "idle";
             this.emitStateChanged("goToStep");
             throw err;
         }
     }
     async _goToStepCheckedAsync(active, targetIndex) {
-        if (this._isNavigating)
+        if (this._status !== "idle")
             return;
-        this._isNavigating = true;
+        this._status = "validating";
         this.emitStateChanged("goToStepChecked");
         try {
             const currentStep = this.getEffectiveStep(active);
             const goingForward = targetIndex > active.currentStepIndex;
-            const allowed = goingForward
+            const guardResult = goingForward
                 ? await this.canMoveNext(active, currentStep)
                 : await this.canMovePrevious(active, currentStep);
-            if (allowed) {
+            if (!guardResult.allowed)
+                this._blockingError = guardResult.reason;
+            if (guardResult.allowed) {
+                this._status = "leaving";
                 this.applyPatch(await this.leaveCurrentStep(active, currentStep));
                 active.currentStepIndex = targetIndex;
                 this.applyPatch(await this.enterCurrentStep());
             }
-            this._isNavigating = false;
+            this._status = "idle";
             this.emitStateChanged("goToStepChecked");
         }
         catch (err) {
-            this._isNavigating = false;
+            this._status = "idle";
             this.emitStateChanged("goToStepChecked");
             throw err;
         }
@@ -491,7 +610,7 @@ export class PathEngine {
         // path (which has a valid currentStepIndex) rather than the cancelled
         // sub-path (which may have currentStepIndex = -1).
         this.activePath = this.pathStack.pop() ?? null;
-        this._isNavigating = true;
+        this._status = "leaving";
         this.emitStateChanged("cancel");
         try {
             const parent = this.activePath;
@@ -508,11 +627,11 @@ export class PathEngine {
                     this.applyPatch(await parentStep.onSubPathCancel(cancelledPathId, cancelledData, ctx, cancelledMeta));
                 }
             }
-            this._isNavigating = false;
+            this._status = "idle";
             this.emitStateChanged("cancel");
         }
         catch (err) {
-            this._isNavigating = false;
+            this._status = "idle";
             this.emitStateChanged("cancel");
             throw err;
         }
@@ -545,17 +664,75 @@ export class PathEngine {
             });
         }
         else {
-            // Top-level path completed — call onComplete hook if defined
-            this.activePath = null;
-            this.emit({ type: "completed", pathId: finishedPathId, data: finishedData });
+            // Top-level path completed — call onComplete before clearing activePath so
+            // that if it throws the engine remains on the final step and can retry.
             if (finished.definition.onComplete) {
                 await finished.definition.onComplete(finishedData);
             }
+            this.activePath = null;
+            this.emit({ type: "completed", pathId: finishedPathId, data: finishedData });
+        }
+    }
+    /**
+     * Wraps `finishActivePath` with error handling for the `completing` phase.
+     * On failure: sets `_error`, stores a retry that re-calls `finishActivePath`,
+     * resets status to `"error"`, and emits `stateChanged`.
+     * On success: resets status to `"idle"` (finishActivePath sets activePath = null,
+     * so no stateChanged is needed — the `completed` event is the terminal signal).
+     */
+    async _finishActivePathWithErrorHandling() {
+        const active = this.activePath;
+        this._status = "completing";
+        try {
+            await this.finishActivePath();
+            this._status = "idle";
+            // No stateChanged here — finishActivePath emits "completed" or "resumed"
+        }
+        catch (err) {
+            this._error = { message: PathEngine.errorMessage(err), phase: "completing", retryCount: this._retryCount };
+            // Retry: call finishActivePath again (activePath is still set because onComplete
+            // throws before this.activePath = null in the restructured finishActivePath)
+            this._pendingRetry = () => this._finishActivePathWithErrorHandling();
+            this._status = "error";
+            if (active) {
+                // Restore activePath if it was cleared mid-throw (defensive)
+                if (!this.activePath)
+                    this.activePath = active;
+                // Back up to the last valid step so snapshot() can render it while error is shown
+                if (this.activePath.currentStepIndex >= this.activePath.definition.steps.length) {
+                    this.activePath.currentStepIndex = this.activePath.definition.steps.length - 1;
+                }
+                this.emitStateChanged("next");
+            }
+        }
+    }
+    /**
+     * Wraps `enterCurrentStep` with error handling for the `entering` phase.
+     * Called by both `_startAsync` and `_nextAsync` after advancing to a new step.
+     * On failure: sets `_error`, stores a retry that re-calls this method,
+     * resets status to `"error"`, and emits `stateChanged` with the given `cause`.
+     */
+    async _enterCurrentStepWithErrorHandling(cause) {
+        this._status = "entering";
+        try {
+            this.applyPatch(await this.enterCurrentStep());
+            this._status = "idle";
+            this.emitStateChanged(cause);
+        }
+        catch (err) {
+            this._error = { message: PathEngine.errorMessage(err), phase: "entering", retryCount: this._retryCount };
+            // Retry: re-enter the current step (don't repeat guards/leave)
+            this._pendingRetry = () => this._enterCurrentStepWithErrorHandling(cause);
+            this._status = "error";
+            this.emitStateChanged(cause);
         }
     }
     // ---------------------------------------------------------------------------
     // Private helpers
     // ---------------------------------------------------------------------------
+    static errorMessage(err) {
+        return err instanceof Error ? err.message : String(err);
+    }
     requireActivePath() {
         if (this.activePath === null) {
             throw new Error("No active path.");
@@ -642,23 +819,41 @@ export class PathEngine {
         while (active.currentStepIndex >= 0 &&
             active.currentStepIndex < active.definition.steps.length) {
             const item = active.definition.steps[active.currentStepIndex];
-            if (!item.shouldSkip)
+            if (!item.shouldSkip) {
+                // This step has no shouldSkip — it is definitely visible. Remove it from
+                // the cache in case a previous navigation had marked it as skipped.
+                active.resolvedSkips.delete(item.id);
                 break;
+            }
             const ctx = {
                 pathId: active.definition.id,
                 stepId: item.id,
                 data: { ...active.data },
                 isFirstEntry: !active.visitedStepIds.has(item.id)
             };
-            const skip = await item.shouldSkip(ctx);
-            if (!skip)
+            const rawResult = item.shouldSkip(ctx);
+            if (rawResult && typeof rawResult.then === "function") {
+                if (!this._hasWarnedAsyncShouldSkip) {
+                    this._hasWarnedAsyncShouldSkip = true;
+                    console.warn(`[Pathwrite] Step "${item.id}" has an async shouldSkip. ` +
+                        `snapshot().stepCount and progress may be approximate until after the first navigation.`);
+                }
+            }
+            const skip = await rawResult;
+            if (!skip) {
+                // This step resolved as NOT skipped — remove from cache in case it was
+                // previously skipped (data changed since last navigation).
+                active.resolvedSkips.delete(item.id);
                 break;
+            }
+            active.resolvedSkips.add(item.id);
             active.currentStepIndex += direction;
         }
     }
     async enterCurrentStep() {
         // Each step starts fresh — errors are not shown until the user attempts to proceed.
         this._hasAttemptedNext = false;
+        this._blockingError = null;
         const active = this.activePath;
         if (!active)
             return;
@@ -703,23 +898,31 @@ export class PathEngine {
                 data: { ...active.data },
                 isFirstEntry: !active.visitedStepIds.has(step.id)
             };
-            return step.canMoveNext(ctx);
+            const result = await step.canMoveNext(ctx);
+            return PathEngine.normaliseGuardResult(result);
         }
         if (step.fieldErrors) {
-            return Object.keys(this.evaluateFieldMessagesSync(step.fieldErrors, active)).length === 0;
+            const allowed = Object.keys(this.evaluateFieldMessagesSync(step.fieldErrors, active)).length === 0;
+            return { allowed, reason: null };
         }
-        return true;
+        return { allowed: true, reason: null };
     }
     async canMovePrevious(active, step) {
         if (!step.canMovePrevious)
-            return true;
+            return { allowed: true, reason: null };
         const ctx = {
             pathId: active.definition.id,
             stepId: step.id,
             data: { ...active.data },
             isFirstEntry: !active.visitedStepIds.has(step.id)
         };
-        return step.canMovePrevious(ctx);
+        const result = await step.canMovePrevious(ctx);
+        return PathEngine.normaliseGuardResult(result);
+    }
+    static normaliseGuardResult(result) {
+        if (result === true)
+            return { allowed: true, reason: null };
+        return { allowed: false, reason: result.reason ?? null };
     }
     /**
      * Evaluates a guard function synchronously for inclusion in the snapshot.
@@ -747,16 +950,19 @@ export class PathEngine {
         };
         try {
             const result = guard(ctx);
-            if (typeof result === "boolean")
-                return result;
-            // Async guard detected - warn and return optimistic default
+            if (result === true)
+                return true;
             if (result && typeof result.then === "function") {
+                // Async guard detected - suppress the unhandled rejection, warn, return optimistic default
+                result.catch(() => { });
                 console.warn(`[pathwrite] Async guard detected on step "${item.id}". ` +
                     `Guards in snapshots must be synchronous. ` +
                     `Returning true (optimistic) as default. ` +
                     `The async guard will still be enforced during actual navigation.`);
+                return true;
             }
-            return true;
+            // { allowed: false, reason? } object returned synchronously
+            return false;
         }
         catch (err) {
             console.warn(`[pathwrite] Guard on step "${item.id}" threw an error during snapshot evaluation. ` +