@daltonr/pathwrite-core 0.9.0 → 0.10.0

package/src/index.ts

@@ -11,6 +11,25 @@ export type PathData = Record<string, unknown>;
  */
 export type FieldErrors = Record<string, string | undefined>;
 
+/**
+ * The return type of a `canMoveNext` or `canMovePrevious` guard.
+ *
+ * - `true` — allow navigation
+ * - `{ allowed: false }` — block silently (no message)
+ * - `{ allowed: false, reason: "..." }` — block with a message; the shell surfaces
+ *   this as `snapshot.blockingError` between the step content and the nav buttons
+ *
+ * @example
+ * ```typescript
+ * canMoveNext: async ({ data }) => {
+ *   const result = await checkEligibility(data.applicantId);
+ *   if (!result.eligible) return { allowed: false, reason: result.reason };
+ *   return true;
+ * }
+ * ```
+ */
+export type GuardResult = true | { allowed: false; reason?: string };
+
 export interface SerializedPathState {
   version: 1;
   pathId: string;
@@ -29,7 +48,7 @@ export interface SerializedPathState {
     stepEntryData?: PathData;
     stepEnteredAt?: number;
   }>;
-  _isNavigating: boolean;
+  _status: PathStatus;
 }
 
 /**
@@ -105,8 +124,8 @@ export interface PathStep<TData extends PathData = PathData> {
   title?: string;
   meta?: Record<string, unknown>;
   shouldSkip?: (ctx: PathStepContext<TData>) => boolean | Promise<boolean>;
-  canMoveNext?: (ctx: PathStepContext<TData>) => boolean | Promise<boolean>;
-  canMovePrevious?: (ctx: PathStepContext<TData>) => boolean | Promise<boolean>;
+  canMoveNext?: (ctx: PathStepContext<TData>) => GuardResult | Promise<GuardResult>;
+  canMovePrevious?: (ctx: PathStepContext<TData>) => GuardResult | Promise<GuardResult>;
   /**
    * Returns a map of field ID → error message explaining why the step is not
    * yet valid. The shell displays these messages below the step content (labeled
@@ -195,6 +214,32 @@ export interface PathDefinition<TData extends PathData = PathData> {
 
 export type StepStatus = "completed" | "current" | "upcoming";
 
+/**
+ * The engine's current operational state. Exposed as `snapshot.status`.
+ *
+ * | Status        | Meaning                                                      |
+ * |---------------|--------------------------------------------------------------|
+ * | `idle`        | On a step, waiting for user input                            |
+ * | `entering`    | `onEnter` hook is running                                    |
+ * | `validating`  | `canMoveNext` / `canMovePrevious` guard is running           |
+ * | `leaving`     | `onLeave` hook is running                                    |
+ * | `completing`  | `PathDefinition.onComplete` is running                       |
+ * | `error`       | An async operation failed — see `snapshot.error` for details |
+ */
+export type PathStatus =
+  | "idle"
+  | "entering"
+  | "validating"
+  | "leaving"
+  | "completing"
+  | "error";
+
+/**
+ * The subset of `PathStatus` values that identify which phase was active
+ * when an error occurred. Used by `snapshot.error.phase`.
+ */
+export type ErrorPhase = Exclude<PathStatus, "idle" | "error">;
+
 export interface StepSummary {
   id: string;
   title?: string;
@@ -253,8 +298,32 @@ export interface PathSnapshot<TData extends PathData = PathData> {
    * progress bar above the sub-path's own progress bar.
    */
   rootProgress?: RootProgress;
-  /** True while an async guard or hook is executing. Use to disable navigation controls. */
-  isNavigating: boolean;
+  /**
+   * The engine's current operational state. Use this instead of multiple boolean flags.
+   *
+   * Common patterns:
+   * - `status !== "idle"` — disable all navigation buttons (engine is busy or errored)
+   * - `status === "entering"` — show a skeleton/spinner inside the step area
+   * - `status === "validating"` — show "Checking…" on the Next button
+   * - `status === "error"` — show the retry / suspend error UI
+   */
+  status: PathStatus;
+  /**
+   * Structured error set when an engine-invoked async operation throws. `null` when no error is active.
+   *
+   * `phase` identifies which operation failed so shells can adapt the message.
+   * `retryCount` counts how many times the user has explicitly called `retry()` — starts at 0 on
+   * first failure, increments on each retry. Use this to escalate from "Try again" to "Come back later".
+   *
+   * Cleared automatically when navigation succeeds or when `retry()` is called.
+   */
+  error: { message: string; phase: ErrorPhase; retryCount: number } | null;
+  /**
+   * `true` when a `PathStore` is attached via `PathEngineOptions.hasPersistence`.
+   * Shells use this to decide whether to promise the user that progress is saved
+   * when showing the "come back later" escalation message.
+   */
+  hasPersistence: boolean;
   /** Whether the current step's `canMoveNext` guard allows advancing. Async guards default to `true`. Auto-derived as `true` when `fieldErrors` is defined and returns no messages, and `canMoveNext` is not explicitly defined. */
   canMoveNext: boolean;
   /** Whether the current step's `canMovePrevious` guard allows going back. Async guards default to `true`. */
@@ -306,6 +375,15 @@ export interface PathSnapshot<TData extends PathData = PathData> {
    * navigating back to a previously visited step).
    */
   stepEnteredAt: number;
+  /**
+   * A guard-level blocking message set when `canMoveNext` returns
+   * `{ allowed: false, reason: "..." }`. `null` when there is no blocking message.
+   *
+   * Distinct from `fieldErrors` (field-attached) and `error` (async crash).
+   * Shells render this between the step content and the navigation buttons.
+   * Cleared automatically when the user successfully navigates to a new step.
+   */
+  blockingError: string | null;
   /**
    * Field-keyed validation messages for the current step. Empty object when there are none.
    * Use in step templates to render inline per-field errors: `snapshot.fieldErrors['email']`.
@@ -335,12 +413,15 @@ export type StateChangeCause =
   | "setData"
   | "resetStep"
   | "cancel"
-  | "restart";
+  | "restart"
+  | "retry"
+  | "suspend";
 
 export type PathEvent =
   | { type: "stateChanged"; cause: StateChangeCause; snapshot: PathSnapshot }
   | { type: "completed"; pathId: string; data: PathData }
   | { type: "cancelled"; pathId: string; data: PathData }
+  | { type: "suspended"; pathId: string; data: PathData }
   | {
       type: "resumed";
       resumedPathId: string;
@@ -396,14 +477,15 @@ export type ObserverStrategy =
 export function matchesStrategy(strategy: ObserverStrategy, event: PathEvent): boolean {
   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":
@@ -424,6 +506,12 @@ export interface PathEngineOptions {
    * listeners use `engine.subscribe()`.
    */
   observers?: PathObserver[];
+  /**
+   * Set to `true` when a `PathStore` is attached and will persist path state.
+   * Exposed as `snapshot.hasPersistence` so shells can honestly tell the user
+   * their progress is saved when showing the "come back later" escalation message.
+   */
+  hasPersistence?: boolean;
 }
 
 interface ActivePath {
@@ -438,22 +526,61 @@ interface ActivePath {
   stepEnteredAt: number;
   /** The selected inner step when the current slot is a StepChoice. Cached on entry. */
   resolvedChoiceStep?: PathStep;
+  /** Step IDs that have been confirmed skipped via shouldSkip during navigation. Used for accurate stepCount / progress in snapshots. */
+  resolvedSkips: Set<string>;
 }
 
 function isStepChoice(item: PathStep | StepChoice): item is StepChoice {
   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: string): string {
+  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: string): string {
+  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 {
   private activePath: ActivePath | null = null;
   private readonly pathStack: ActivePath[] = [];
   private readonly listeners = new Set<(event: PathEvent) => void>();
-  private _isNavigating = false;
+  private _status: PathStatus = "idle";
   /** True after the user has called next() on the current step at least once. Resets on step entry. */
   private _hasAttemptedNext = false;
+  /** Blocking message from canMoveNext returning { allowed: false, reason }. Cleared on step entry. */
+  private _blockingError: string | null = null;
   /** The path and initial data from the most recent top-level start() call. Used by restart(). */
   private _rootPath: PathDefinition<any> | null = null;
   private _rootInitialData: PathData = {};
+  /** Structured error from the most recent failed async operation. Null when no error is active. */
+  private _error: { message: string; phase: ErrorPhase; retryCount: number } | null = null;
+  /** Stored retry function. Null when no error is pending. */
+  private _pendingRetry: (() => Promise<void>) | null = null;
+  /**
+   * Counts how many times `retry()` has been called for the current error sequence.
+   * Reset to 0 by `next()` (fresh navigation). Incremented by `retry()`.
+   */
+  private _retryCount = 0;
+  private _hasPersistence = false;
+  private _hasWarnedAsyncShouldSkip = false;
 
   constructor(options?: PathEngineOptions) {
     if (options?.observers) {
@@ -462,6 +589,9 @@ export class PathEngine {
         this.listeners.add((event) => observer(event, this));
       }
     }
+    if (options?.hasPersistence) {
+      this._hasPersistence = true;
+    }
   }
 
   /**
@@ -503,6 +633,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()
@@ -522,6 +653,7 @@ 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,
@@ -529,7 +661,7 @@ export class PathEngine {
       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).
@@ -572,7 +704,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 });
@@ -597,6 +730,14 @@ export class PathEngine {
 
   public next(): Promise<void> {
     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);
   }
 
@@ -605,12 +746,54 @@ export class PathEngine {
     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.
+   */
+  public retry(): Promise<void> {
+    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.
+   */
+  public suspend(): Promise<void> {
+    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. */
   public async cancel(): Promise<void> {
     const active = this.requireActivePath();
-    if (this._isNavigating) return;
+    if (this._status !== "idle") return;
 
     const cancelledPathId = active.definition.id;
     const cancelledData = { ...active.data };
@@ -690,25 +873,34 @@ 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: RootProgress | undefined;
     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" as const
-            : i === root.currentStepIndex ? "current" as const
+          status: i < rootEffectiveIndex ? "completed" as const
+            : i === rootEffectiveIndex ? "current" as const
             : "upcoming" as const
         }))
       };
@@ -720,25 +912,28 @@ 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" as const
-          : i === active.currentStepIndex ? "current" as const
+        status: i < effectiveStepIndex ? "completed" as const
+          : i === effectiveStepIndex ? "current" as const
           : "upcoming" as const
       })),
-      isFirstStep: active.currentStepIndex === 0,
+      isFirstStep: effectiveStepIndex === 0,
       isLastStep:
-        active.currentStepIndex === stepCount - 1 &&
+        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),
@@ -784,7 +979,7 @@ export class PathEngine {
         stepEntryData: { ...p.stepEntryData },
         stepEnteredAt: p.stepEnteredAt
       })),
-      _isNavigating: this._isNavigating
+      _status: this._status
     };
   }
 
@@ -793,7 +988,7 @@ export class PathEngine {
   // ---------------------------------------------------------------------------
 
   private async _startAsync(path: PathDefinition, initialData: PathData, subPathMeta?: Record<string, unknown>): Promise<void> {
-    if (this._isNavigating) return;
+    if (this._status !== "idle") return;
 
     if (this.activePath !== null) {
       // Store the meta on the parent before pushing to stack
@@ -809,90 +1004,104 @@ 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");
   }
 
   private async _nextAsync(active: ActivePath): Promise<void> {
-    if (this._isNavigating) return;
+    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: { allowed: boolean; reason: string | null };
     try {
-      const step = this.getEffectiveStep(active);
+      guardResult = await this.canMoveNext(active, this.getEffectiveStep(active));
+    } catch (err) {
+      this._error = { message: PathEngine.errorMessage(err), phase: "validating", retryCount: this._retryCount };
+      this._pendingRetry = () => this._nextAsync(active);
+      this._status = "error";
+      this.emitStateChanged("next");
+      return;
+    }
 
-      if (await this.canMoveNext(active, step)) {
-        this.applyPatch(await this.leaveCurrentStep(active, step));
-        active.currentStepIndex += 1;
-        await this.skipSteps(1);
+    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;
+      }
 
-        if (active.currentStepIndex >= active.definition.steps.length) {
-          this._isNavigating = false;
-          await this.finishActivePath();
-          return;
-        }
+      active.currentStepIndex += 1;
+      await this.skipSteps(1);
 
-        this.applyPatch(await this.enterCurrentStep());
+      if (active.currentStepIndex >= active.definition.steps.length) {
+        // Phase: completing — PathDefinition.onComplete
+        await this._finishActivePathWithErrorHandling();
+        return;
       }
 
-      this._isNavigating = false;
-      this.emitStateChanged("next");
-    } catch (err) {
-      this._isNavigating = false;
-      this.emitStateChanged("next");
-      throw err;
+      // Phase: entering — onEnter hook on the new step
+      await this._enterCurrentStepWithErrorHandling("next");
+      return;
     }
+
+    this._blockingError = guardResult.reason;
+    this._status = "idle";
+    this.emitStateChanged("next");
   }
 
   private async _previousAsync(active: ActivePath): Promise<void> {
-    if (this._isNavigating) return;
+    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;
         }
@@ -900,19 +1109,19 @@ export class PathEngine {
         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;
     }
   }
 
   private async _goToStepAsync(active: ActivePath, targetIndex: number): Promise<void> {
-    if (this._isNavigating) return;
+    if (this._status !== "idle") return;
 
-    this._isNavigating = true;
+    this._status = "leaving";
     this.emitStateChanged("goToStep");
 
     try {
@@ -922,38 +1131,41 @@ export class PathEngine {
       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;
     }
   }
 
   private async _goToStepCheckedAsync(active: ActivePath, targetIndex: number): Promise<void> {
-    if (this._isNavigating) return;
+    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;
     }
@@ -969,7 +1181,7 @@ export class PathEngine {
     // sub-path (which may have currentStepIndex = -1).
     this.activePath = this.pathStack.pop() ?? null;
 
-    this._isNavigating = true;
+    this._status = "leaving";
     this.emitStateChanged("cancel");
 
     try {
@@ -991,10 +1203,10 @@ export class PathEngine {
         }
       }
 
-      this._isNavigating = false;
+      this._status = "idle";
       this.emitStateChanged("cancel");
     } catch (err) {
-      this._isNavigating = false;
+      this._status = "idle";
       this.emitStateChanged("cancel");
       throw err;
     }
@@ -1032,12 +1244,66 @@ export class PathEngine {
         snapshot: this.snapshot()!
       });
     } 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).
+   */
+  private async _finishActivePathWithErrorHandling(): Promise<void> {
+    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`.
+   */
+  private async _enterCurrentStepWithErrorHandling(cause: StateChangeCause): Promise<void> {
+    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);
     }
   }
 
@@ -1045,6 +1311,10 @@ export class PathEngine {
   // Private helpers
   // ---------------------------------------------------------------------------
 
+  private static errorMessage(err: unknown): string {
+    return err instanceof Error ? err.message : String(err);
+  }
+
   private requireActivePath(): ActivePath {
     if (this.activePath === null) {
       throw new Error("No active path.");
@@ -1143,15 +1413,36 @@ export class PathEngine {
       active.currentStepIndex < active.definition.steps.length
     ) {
       const item = active.definition.steps[active.currentStepIndex];
-      if (!item.shouldSkip) break;
+      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: PathStepContext = {
         pathId: active.definition.id,
         stepId: item.id,
         data: { ...active.data },
         isFirstEntry: !active.visitedStepIds.has(item.id)
       };
-      const skip = await item.shouldSkip(ctx);
-      if (!skip) break;
+      const rawResult = item.shouldSkip(ctx);
+      if (rawResult && typeof (rawResult as Promise<boolean>).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;
     }
   }
@@ -1159,6 +1450,7 @@ export class PathEngine {
   private async enterCurrentStep(): Promise<Partial<PathData> | void> {
     // 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;
 
@@ -1205,7 +1497,7 @@ export class PathEngine {
   private async canMoveNext(
     active: ActivePath,
     step: PathStep
-  ): Promise<boolean> {
+  ): Promise<{ allowed: boolean; reason: string | null }> {
     if (step.canMoveNext) {
       const ctx: PathStepContext = {
         pathId: active.definition.id,
@@ -1213,26 +1505,34 @@ 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 };
   }
 
   private async canMovePrevious(
     active: ActivePath,
     step: PathStep
-  ): Promise<boolean> {
-    if (!step.canMovePrevious) return true;
+  ): Promise<{ allowed: boolean; reason: string | null }> {
+    if (!step.canMovePrevious) return { allowed: true, reason: null };
     const ctx: PathStepContext = {
       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);
+  }
+
+  private static normaliseGuardResult(result: GuardResult): { allowed: boolean; reason: string | null } {
+    if (result === true) return { allowed: true, reason: null };
+    return { allowed: false, reason: result.reason ?? null };
   }
 
   /**
@@ -1250,7 +1550,7 @@ export class PathEngine {
    * safe default (`true`) is returned so the UI remains operable.
    */
   private evaluateGuardSync(
-    guard: ((ctx: PathStepContext) => boolean | Promise<boolean>) | undefined,
+    guard: ((ctx: PathStepContext) => GuardResult | Promise<GuardResult>) | undefined,
     active: ActivePath
   ): boolean {
     if (!guard) return true;
@@ -1263,17 +1563,20 @@ export class PathEngine {
     };
     try {
       const result = guard(ctx);
-      if (typeof result === "boolean") return result;
-      // Async guard detected - warn and return optimistic default
-      if (result && typeof result.then === "function") {
+      if (result === true) return true;
+      if (result && typeof (result as Promise<unknown>).then === "function") {
+        // Async guard detected - suppress the unhandled rejection, warn, return optimistic default
+        (result as Promise<unknown>).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. ` +