@daltonr/pathwrite-core 0.6.3 → 0.8.0

package/src/index.ts

@@ -1,7 +1,7 @@
 export type PathData = Record<string, unknown>;
 
 /**
- * The return type of a `fieldMessages` hook. Each key is a field ID; the value
+ * The return type of a `fieldErrors` hook. Each key is a field ID; the value
  * is an error string, or `undefined` / omitted to indicate no error for that field.
  *
  * Use `"_"` as a key for form-level errors that don't belong to a specific field:
@@ -18,12 +18,16 @@ export interface SerializedPathState {
   data: PathData;
   visitedStepIds: string[];
   subPathMeta?: Record<string, unknown>;
+  stepEntryData?: PathData;
+  stepEnteredAt?: number;
   pathStack: Array<{
     pathId: string;
     currentStepIndex: number;
     data: PathData;
     visitedStepIds: string[];
     subPathMeta?: Record<string, unknown>;
+    stepEntryData?: PathData;
+    stepEnteredAt?: number;
   }>;
   _isNavigating: boolean;
 }
@@ -56,6 +60,46 @@ export interface PathStepContext<TData extends PathData = PathData> {
   readonly isFirstEntry: boolean;
 }
 
+/**
+ * A conditional step selection placed in a path's `steps` array in place of a
+ * single `PathStep`. When the engine reaches a `StepChoice` it calls `select`
+ * to decide which of the bundled `steps` to activate. The chosen step is then
+ * treated exactly like any other step — its hooks, guards, and validation all
+ * apply normally.
+ *
+ * `StepChoice` has its own `id` (used for progress tracking and `goToStep`)
+ * while `formId` on the snapshot exposes which inner step was selected, so the
+ * UI can render the right component.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   id: "contact-details",
+ *   select: ({ data }) => data.accountType === "company" ? "company" : "individual",
+ *   steps: [
+ *     {
+ *       id: "individual",
+ *       fieldErrors: ({ data }) => ({ name: !data.name ? "Required." : undefined }),
+ *     },
+ *     {
+ *       id: "company",
+ *       fieldErrors: ({ data }) => ({ companyName: !data.companyName ? "Required." : undefined }),
+ *     },
+ *   ],
+ * }
+ * ```
+ */
+export interface StepChoice<TData extends PathData = PathData> {
+  id: string;
+  title?: string;
+  meta?: Record<string, unknown>;
+  /** Called on step entry. Return the `id` of the step to activate. Throws if the returned id is not found in `steps`. */
+  select: (ctx: PathStepContext<TData>) => string;
+  steps: PathStep<TData>[];
+  /** When `true`, the engine skips this choice slot entirely (same semantics as `PathStep.shouldSkip`). */
+  shouldSkip?: (ctx: PathStepContext<TData>) => boolean | Promise<boolean>;
+}
+
 export interface PathStep<TData extends PathData = PathData> {
   id: string;
   title?: string;
@@ -69,7 +113,7 @@ export interface PathStep<TData extends PathData = PathData> {
    * by field name) so consumers do not need to duplicate validation logic in
    * the template. Return `undefined` for a field to indicate no error.
    *
-   * When `fieldMessages` is provided and `canMoveNext` is **not**, the engine
+   * When `fieldErrors` is provided and `canMoveNext` is **not**, the engine
    * automatically derives `canMoveNext` as `true` when all values are `undefined`
    * (i.e. no messages), eliminating the need to express the same logic twice.
    *
@@ -77,13 +121,29 @@ export interface PathStep<TData extends PathData = PathData> {
    *
    * @example
    * ```typescript
-   * fieldMessages: ({ data }) => ({
+   * fieldErrors: ({ data }) => ({
    *   name:  !data.name?.trim()        ? "Required."             : undefined,
    *   email: !isValidEmail(data.email) ? "Invalid email address." : undefined,
    * })
    * ```
    */
-  fieldMessages?: (ctx: PathStepContext<TData>) => FieldErrors;
+  fieldErrors?: (ctx: PathStepContext<TData>) => FieldErrors;
+  /**
+   * Returns a map of field ID → warning message for non-blocking advisories.
+   * Same shape as `fieldErrors`, but warnings never affect `canMoveNext` —
+   * they are purely informational. Shells render them in amber/yellow instead
+   * of red.
+   *
+   * Evaluated synchronously on every snapshot; async functions default to `{}`.
+   *
+   * @example
+   * ```typescript
+   * fieldWarnings: ({ data }) => ({
+   *   email: looksLikeTypo(data.email) ? "Did you mean gmail.com?" : undefined,
+   * })
+   * ```
+   */
+  fieldWarnings?: (ctx: PathStepContext<TData>) => FieldErrors;
   onEnter?: (ctx: PathStepContext<TData>) => Partial<TData> | void | Promise<Partial<TData> | void>;
   onLeave?: (ctx: PathStepContext<TData>) => Partial<TData> | void | Promise<Partial<TData> | void>;
   /**
@@ -117,7 +177,20 @@ export interface PathStep<TData extends PathData = PathData> {
 export interface PathDefinition<TData extends PathData = PathData> {
   id: string;
   title?: string;
-  steps: PathStep<TData>[];
+  steps: (PathStep<TData> | StepChoice<TData>)[];
+  /**
+   * Optional callback invoked when this path completes (i.e. the user
+   * reaches the end of the last step). Receives the final path data.
+   * Only called for top-level paths — sub-path completion is handled by
+   * the parent step's `onSubPathComplete` hook.
+   */
+  onComplete?: (data: TData) => void | Promise<void>;
+  /**
+   * Optional callback invoked when this path is cancelled. Receives the
+   * path data at the time of cancellation. Only called for top-level paths —
+   * sub-path cancellation is handled by the parent step's `onSubPathCancel` hook.
+   */
+  onCancel?: (data: TData) => void | Promise<void>;
 }
 
 export type StepStatus = "completed" | "current" | "upcoming";
@@ -129,11 +202,44 @@ export interface StepSummary {
   status: StepStatus;
 }
 
+/**
+ * Controls how the shell renders progress bars when a sub-path is active.
+ *
+ * | Value          | Behaviour                                                              |
+ * |----------------|------------------------------------------------------------------------|
+ * | `"merged"`     | Root and sub-path bars in one card (default)                           |
+ * | `"split"`      | Root and sub-path bars as separate cards                               |
+ * | `"rootOnly"`   | Only the root bar — sub-path bar hidden                                |
+ * | `"activeOnly"` | Only the active (sub-path) bar — root bar hidden (pre-v0.7 behaviour) |
+ */
+export type ProgressLayout = "merged" | "split" | "rootOnly" | "activeOnly";
+
+/**
+ * Summary of the root (top-level) path's progress. Present on `PathSnapshot`
+ * only when `nestingLevel > 0` — i.e. a sub-path is active.
+ *
+ * Shells use this to keep the top-level progress bar visible while navigating
+ * a sub-path, so users never lose sight of where they are in the main flow.
+ */
+export interface RootProgress {
+  pathId: string;
+  stepIndex: number;
+  stepCount: number;
+  progress: number;
+  steps: StepSummary[];
+}
+
 export interface PathSnapshot<TData extends PathData = PathData> {
   pathId: string;
   stepId: string;
   stepTitle?: string;
   stepMeta?: Record<string, unknown>;
+  /**
+   * The `id` of the selected inner `PathStep` when the current position in
+   * the path is a `StepChoice`. `undefined` for ordinary steps.
+   * Use this to decide which form component to render.
+   */
+  formId?: string;
   stepIndex: number;
   stepCount: number;
   progress: number;
@@ -141,9 +247,15 @@ export interface PathSnapshot<TData extends PathData = PathData> {
   isFirstStep: boolean;
   isLastStep: boolean;
   nestingLevel: number;
+  /**
+   * Progress summary of the root (top-level) path. Only present when
+   * `nestingLevel > 0`. Shells use this to render a persistent top-level
+   * 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;
-  /** Whether the current step's `canMoveNext` guard allows advancing. Async guards default to `true`. Auto-derived as `true` when `fieldMessages` is defined and returns no messages, and `canMoveNext` is not explicitly defined. */
+  /** 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`. */
   canMovePrevious: boolean;
@@ -156,22 +268,58 @@ export interface PathSnapshot<TData extends PathData = PathData> {
    * render and only appear after the user has attempted to proceed:
    *
    * ```svelte
-   * {#if snapshot.hasAttemptedNext && snapshot.fieldMessages.email}
-   *   <span class="error">{snapshot.fieldMessages.email}</span>
+   * {#if snapshot.hasAttemptedNext && snapshot.fieldErrors.email}
+   *   <span class="error">{snapshot.fieldErrors.email}</span>
    * {/if}
    * ```
    *
-   * The shell itself uses this flag to gate its own automatic `fieldMessages`
+   * The shell itself uses this flag to gate its own automatic `fieldErrors`
    * summary rendering — errors are never shown before the first Next attempt.
    */
   hasAttemptedNext: boolean;
+  /**
+   * True if any data has changed since entering this step. Automatically computed
+   * by comparing the current data to the snapshot taken on step entry. Resets to
+   * `false` when navigating to a new step or calling `resetStep()`.
+   *
+   * Useful for "unsaved changes" warnings, disabling Save buttons until changes
+   * are made, or styling forms to indicate modifications.
+   *
+   * ```typescript
+   * {#if snapshot.isDirty}
+   *   <span class="warning">You have unsaved changes</span>
+   * {/if}
+   * ```
+   */
+  isDirty: boolean;
+  /**
+   * Timestamp (from `Date.now()`) captured when the current step was entered.
+   * Useful for analytics, timeout warnings, or computing how long a user has
+   * been on a step.
+   *
+   * ```typescript
+   * const durationMs = Date.now() - snapshot.stepEnteredAt;
+   * const durationSec = Math.floor(durationMs / 1000);
+   * ```
+   *
+   * Resets to a new timestamp each time the step is entered (including when
+   * navigating back to a previously visited step).
+   */
+  stepEnteredAt: number;
   /**
    * 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.fieldMessages['email']`.
+   * Use in step templates to render inline per-field errors: `snapshot.fieldErrors['email']`.
    * The shell also renders these automatically in a labeled summary box.
    * Use `"_"` as a key for form-level (non-field-specific) errors.
    */
-  fieldMessages: Record<string, string>;
+  fieldErrors: Record<string, string>;
+  /**
+   * Field-keyed warning messages for the current step. Empty object when there are none.
+   * Same shape as `fieldErrors` but purely informational — warnings never block navigation.
+   * Shells render these in amber/yellow instead of red.
+   * Use `"_"` as a key for form-level (non-field-specific) warnings.
+   */
+  fieldWarnings: Record<string, string>;
   data: TData;
 }
 
@@ -185,6 +333,7 @@ export type StateChangeCause =
   | "goToStep"
   | "goToStepChecked"
   | "setData"
+  | "resetStep"
   | "cancel"
   | "restart";
 
@@ -283,6 +432,16 @@ interface ActivePath {
   data: PathData;
   visitedStepIds: Set<string>;
   subPathMeta?: Record<string, unknown>;
+  /** Snapshot of data taken when the current step was entered. Used by resetStep(). */
+  stepEntryData: PathData;
+  /** Timestamp (Date.now()) captured when the current step was entered. */
+  stepEnteredAt: number;
+  /** The selected inner step when the current slot is a StepChoice. Cached on entry. */
+  resolvedChoiceStep?: PathStep;
+}
+
+function isStepChoice(item: PathStep | StepChoice): item is StepChoice {
+  return "select" in item && "steps" in item;
 }
 
 export class PathEngine {
@@ -341,7 +500,9 @@ export class PathEngine {
         currentStepIndex: stackItem.currentStepIndex,
         data: { ...stackItem.data },
         visitedStepIds: new Set(stackItem.visitedStepIds),
-        subPathMeta: stackItem.subPathMeta ? { ...stackItem.subPathMeta } : undefined
+        subPathMeta: stackItem.subPathMeta ? { ...stackItem.subPathMeta } : undefined,
+        stepEntryData: stackItem.stepEntryData ? { ...stackItem.stepEntryData } : { ...stackItem.data },
+        stepEnteredAt: stackItem.stepEnteredAt ?? Date.now()
       });
     }
 
@@ -360,11 +521,20 @@ export class PathEngine {
       visitedStepIds: new Set(state.visitedStepIds),
       // 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
+      subPathMeta: undefined,
+      stepEntryData: state.stepEntryData ? { ...state.stepEntryData } : { ...state.data },
+      stepEnteredAt: state.stepEnteredAt ?? Date.now()
     };
 
     engine._isNavigating = state._isNavigating;
 
+    // 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) {
+      engine.cacheResolvedChoiceStep(stackItem);
+    }
+    engine.cacheResolvedChoiceStep(engine.activePath);
+
     return engine;
   }
 
@@ -432,9 +602,9 @@ export class PathEngine {
   /** 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 cancel(): Promise<void> {
+  public async cancel(): Promise<void> {
     const active = this.requireActivePath();
-    if (this._isNavigating) return Promise.resolve();
+    if (this._isNavigating) return;
 
     const cancelledPathId = active.definition.id;
     const cancelledData = { ...active.data };
@@ -446,9 +616,12 @@ export class PathEngine {
       return this._cancelSubPathAsync(cancelledPathId, cancelledData, cancelledMeta);
     }
 
+    // Top-level path cancelled — call onCancel hook if defined
     this.activePath = null;
     this.emit({ type: "cancelled", pathId: cancelledPathId, data: cancelledData });
-    return Promise.resolve();
+    if (active.definition.onCancel) {
+      await active.definition.onCancel(cancelledData);
+    }
   }
 
   public setData(key: string, value: unknown): Promise<void> {
@@ -458,6 +631,20 @@ export class PathEngine {
     return Promise.resolve();
   }
 
+  /**
+   * Resets the current step's data to what it was when the step was entered.
+   * Useful for "Clear" or "Reset" buttons that undo changes within a step.
+   * Emits a `stateChanged` event with cause `"resetStep"`.
+   * Throws if no path is active.
+   */
+  public resetStep(): Promise<void> {
+    const active = this.requireActivePath();
+    // Restore data from the snapshot taken when this step was entered
+    active.data = { ...active.stepEntryData };
+    this.emitStateChanged("resetStep");
+    return Promise.resolve();
+  }
+
   /** Jumps directly to the step with the given ID. Does not check guards or shouldSkip. */
   public goToStep(stepId: string): Promise<void> {
     const active = this.requireActivePath();
@@ -494,15 +681,39 @@ export class PathEngine {
     }
 
     const active = this.activePath;
-    const step = this.getCurrentStep(active);
+    const item = this.getCurrentItem(active);
+    const effectiveStep = this.getEffectiveStep(active);
     const { steps } = active.definition;
     const stepCount = steps.length;
 
+    // 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;
+      rootProgress = {
+        pathId: root.definition.id,
+        stepIndex: root.currentStepIndex,
+        stepCount: rootStepCount,
+        progress: rootStepCount <= 1 ? 1 : root.currentStepIndex / (rootStepCount - 1),
+        steps: rootSteps.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
+            : "upcoming" as const
+        }))
+      };
+    }
+
     return {
       pathId: active.definition.id,
-      stepId: step.id,
-      stepTitle: step.title,
-      stepMeta: step.meta,
+      stepId: item.id,
+      stepTitle: effectiveStep.title ?? item.title,
+      stepMeta: effectiveStep.meta ?? item.meta,
+      formId: isStepChoice(item) ? effectiveStep.id : undefined,
       stepIndex: active.currentStepIndex,
       stepCount,
       progress: stepCount <= 1 ? 1 : active.currentStepIndex / (stepCount - 1),
@@ -519,11 +730,15 @@ export class PathEngine {
         active.currentStepIndex === stepCount - 1 &&
         this.pathStack.length === 0,
       nestingLevel: this.pathStack.length,
+      rootProgress,
       isNavigating: this._isNavigating,
       hasAttemptedNext: this._hasAttemptedNext,
-      canMoveNext: this.evaluateCanMoveNextSync(step, active),
-      canMovePrevious: this.evaluateGuardSync(step.canMovePrevious, active),
-      fieldMessages: this.evaluateFieldMessagesSync(step.fieldMessages, active),
+      canMoveNext: this.evaluateCanMoveNextSync(effectiveStep, active),
+      canMovePrevious: this.evaluateGuardSync(effectiveStep.canMovePrevious, active),
+      fieldErrors: this.evaluateFieldMessagesSync(effectiveStep.fieldErrors, active),
+      fieldWarnings: this.evaluateFieldMessagesSync(effectiveStep.fieldWarnings, active),
+      isDirty: this.computeIsDirty(active),
+      stepEnteredAt: active.stepEnteredAt,
       data: { ...active.data }
     };
   }
@@ -552,12 +767,16 @@ export class PathEngine {
       currentStepIndex: active.currentStepIndex,
       data: { ...active.data },
       visitedStepIds: Array.from(active.visitedStepIds),
+      stepEntryData: { ...active.stepEntryData },
+      stepEnteredAt: active.stepEnteredAt,
       pathStack: this.pathStack.map((p) => ({
         pathId: p.definition.id,
         currentStepIndex: p.currentStepIndex,
         data: { ...p.data },
         visitedStepIds: Array.from(p.visitedStepIds),
-        subPathMeta: p.subPathMeta ? { ...p.subPathMeta } : undefined
+        subPathMeta: p.subPathMeta ? { ...p.subPathMeta } : undefined,
+        stepEntryData: { ...p.stepEntryData },
+        stepEnteredAt: p.stepEnteredAt
       })),
       _isNavigating: this._isNavigating
     };
@@ -584,7 +803,9 @@ export class PathEngine {
       currentStepIndex: 0,
       data: { ...initialData },
       visitedStepIds: new Set(),
-      subPathMeta: undefined
+      subPathMeta: undefined,
+      stepEntryData: { ...initialData },  // Will be updated in enterCurrentStep
+      stepEnteredAt: 0  // Will be set in enterCurrentStep
     };
 
     this._isNavigating = true;
@@ -620,7 +841,7 @@ export class PathEngine {
     this.emitStateChanged("next");
 
     try {
-      const step = this.getCurrentStep(active);
+      const step = this.getEffectiveStep(active);
 
       if (await this.canMoveNext(active, step)) {
         this.applyPatch(await this.leaveCurrentStep(active, step));
@@ -657,7 +878,7 @@ export class PathEngine {
     this.emitStateChanged("previous");
 
     try {
-      const step = this.getCurrentStep(active);
+      const step = this.getEffectiveStep(active);
 
       if (await this.canMovePrevious(active, step)) {
         this.applyPatch(await this.leaveCurrentStep(active, step));
@@ -689,7 +910,7 @@ export class PathEngine {
     this.emitStateChanged("goToStep");
 
     try {
-      const currentStep = this.getCurrentStep(active);
+      const currentStep = this.getEffectiveStep(active);
       this.applyPatch(await this.leaveCurrentStep(active, currentStep));
 
       active.currentStepIndex = targetIndex;
@@ -711,7 +932,7 @@ export class PathEngine {
     this.emitStateChanged("goToStepChecked");
 
     try {
-      const currentStep = this.getCurrentStep(active);
+      const currentStep = this.getEffectiveStep(active);
       const goingForward = targetIndex > active.currentStepIndex;
       const allowed = goingForward
         ? await this.canMoveNext(active, currentStep)
@@ -749,13 +970,14 @@ export class PathEngine {
       const parent = this.activePath;
 
       if (parent) {
-        const parentStep = this.getCurrentStep(parent);
+        const parentItem = this.getCurrentItem(parent);
+        const parentStep = this.getEffectiveStep(parent);
         if (parentStep.onSubPathCancel) {
           const ctx: PathStepContext = {
             pathId: parent.definition.id,
-            stepId: parentStep.id,
+            stepId: parentItem.id,
             data: { ...parent.data },
-            isFirstEntry: !parent.visitedStepIds.has(parentStep.id)
+            isFirstEntry: !parent.visitedStepIds.has(parentItem.id)
           };
           this.applyPatch(
             await parentStep.onSubPathCancel(cancelledPathId, cancelledData, ctx, cancelledMeta)
@@ -782,14 +1004,15 @@ export class PathEngine {
       // The meta is stored on the parent, not the sub-path
       const finishedMeta = parent.subPathMeta;
       this.activePath = parent;
-      const parentStep = this.getCurrentStep(parent);
+      const parentItem = this.getCurrentItem(parent);
+      const parentStep = this.getEffectiveStep(parent);
 
       if (parentStep.onSubPathComplete) {
         const ctx: PathStepContext = {
           pathId: parent.definition.id,
-          stepId: parentStep.id,
+          stepId: parentItem.id,
           data: { ...parent.data },
-          isFirstEntry: !parent.visitedStepIds.has(parentStep.id)
+          isFirstEntry: !parent.visitedStepIds.has(parentItem.id)
         };
         this.applyPatch(
           await parentStep.onSubPathComplete(finishedPathId, finishedData, ctx, finishedMeta)
@@ -803,8 +1026,12 @@ 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 });
+      if (finished.definition.onComplete) {
+        await finished.definition.onComplete(finishedData);
+      }
     }
   }
 
@@ -835,10 +1062,63 @@ export class PathEngine {
     this.emit({ type: "stateChanged", cause, snapshot: this.snapshot()! });
   }
 
-  private getCurrentStep(active: ActivePath): PathStep {
+  /** Returns the raw item at the current index — either a PathStep or a StepChoice. */
+  private getCurrentItem(active: ActivePath): PathStep | StepChoice {
     return active.definition.steps[active.currentStepIndex];
   }
 
+  /**
+   * Calls `StepChoice.select` and caches the chosen inner step in
+   * `active.resolvedChoiceStep`. Clears the cache when the current item is a
+   * plain `PathStep`. Throws if `select` returns an id not present in `steps`.
+   */
+  private cacheResolvedChoiceStep(active: ActivePath): void {
+    const item = this.getCurrentItem(active);
+    if (!isStepChoice(item)) {
+      active.resolvedChoiceStep = undefined;
+      return;
+    }
+    const ctx: PathStepContext = {
+      pathId: active.definition.id,
+      stepId: item.id,
+      data: { ...active.data },
+      isFirstEntry: !active.visitedStepIds.has(item.id)
+    };
+    let selectedId: string;
+    try {
+      selectedId = item.select(ctx);
+    } catch (err) {
+      throw new Error(
+        `[pathwrite] StepChoice "${item.id}".select() threw an error: ${err}`
+      );
+    }
+    const found = item.steps.find((s) => s.id === selectedId);
+    if (!found) {
+      throw new Error(
+        `[pathwrite] StepChoice "${item.id}".select() returned "${selectedId}" ` +
+        `but no step with that id exists in its steps array.`
+      );
+    }
+    active.resolvedChoiceStep = found;
+  }
+
+  /**
+   * Returns the effective `PathStep` for the current position. When the
+   * current item is a `StepChoice`, returns the cached resolved inner step.
+   * When it is a plain `PathStep`, returns it directly.
+   */
+  private getEffectiveStep(active: ActivePath): PathStep {
+    if (active.resolvedChoiceStep) return active.resolvedChoiceStep;
+    const item = this.getCurrentItem(active);
+    if (isStepChoice(item)) {
+      // resolvedChoiceStep should always be set after enterCurrentStep; this
+      // branch is a defensive fallback (e.g. during fromState restore).
+      this.cacheResolvedChoiceStep(active);
+      return active.resolvedChoiceStep!;
+    }
+    return item;
+  }
+
   private applyPatch(patch: Partial<PathData> | void | null | undefined): void {
     if (patch && typeof patch === "object") {
       const active = this.activePath;
@@ -856,15 +1136,15 @@ export class PathEngine {
       active.currentStepIndex >= 0 &&
       active.currentStepIndex < active.definition.steps.length
     ) {
-      const step = active.definition.steps[active.currentStepIndex];
-      if (!step.shouldSkip) break;
+      const item = active.definition.steps[active.currentStepIndex];
+      if (!item.shouldSkip) break;
       const ctx: PathStepContext = {
         pathId: active.definition.id,
-        stepId: step.id,
+        stepId: item.id,
         data: { ...active.data },
-        isFirstEntry: !active.visitedStepIds.has(step.id)
+        isFirstEntry: !active.visitedStepIds.has(item.id)
       };
-      const skip = await step.shouldSkip(ctx);
+      const skip = await item.shouldSkip(ctx);
       if (!skip) break;
       active.currentStepIndex += direction;
     }
@@ -875,19 +1155,31 @@ export class PathEngine {
     this._hasAttemptedNext = false;
     const active = this.activePath;
     if (!active) return;
-    const step = this.getCurrentStep(active);
-    const isFirstEntry = !active.visitedStepIds.has(step.id);
+
+    // Save a snapshot of the data as it was when entering this step (for resetStep)
+    active.stepEntryData = { ...active.data };
+
+    // Capture the timestamp when entering this step (for analytics, timeout warnings)
+    active.stepEnteredAt = Date.now();
+
+    const item = this.getCurrentItem(active);
+
+    // Resolve the inner step when this slot is a StepChoice
+    this.cacheResolvedChoiceStep(active);
+
+    const effectiveStep = this.getEffectiveStep(active);
+    const isFirstEntry = !active.visitedStepIds.has(item.id);
     // Mark as visited before calling onEnter so re-entrant calls see the
     // correct isFirstEntry value.
-    active.visitedStepIds.add(step.id);
-    if (!step.onEnter) return;
+    active.visitedStepIds.add(item.id);
+    if (!effectiveStep.onEnter) return;
     const ctx: PathStepContext = {
       pathId: active.definition.id,
-      stepId: step.id,
+      stepId: item.id,
       data: { ...active.data },
       isFirstEntry
     };
-    return step.onEnter(ctx);
+    return effectiveStep.onEnter(ctx);
   }
 
   private async leaveCurrentStep(
@@ -917,8 +1209,8 @@ export class PathEngine {
       };
       return step.canMoveNext(ctx);
     }
-    if (step.fieldMessages) {
-      return Object.keys(this.evaluateFieldMessagesSync(step.fieldMessages, active)).length === 0;
+    if (step.fieldErrors) {
+      return Object.keys(this.evaluateFieldMessagesSync(step.fieldErrors, active)).length === 0;
     }
     return true;
   }
@@ -956,12 +1248,12 @@ export class PathEngine {
     active: ActivePath
   ): boolean {
     if (!guard) return true;
-    const step = this.getCurrentStep(active);
+    const item = this.getCurrentItem(active);
     const ctx: PathStepContext = {
       pathId: active.definition.id,
-      stepId: step.id,
+      stepId: item.id,
       data: { ...active.data },
-      isFirstEntry: !active.visitedStepIds.has(step.id)
+      isFirstEntry: !active.visitedStepIds.has(item.id)
     };
     try {
       const result = guard(ctx);
@@ -969,7 +1261,7 @@ export class PathEngine {
       // Async guard detected - warn and return optimistic default
       if (result && typeof result.then === "function") {
         console.warn(
-          `[pathwrite] Async guard detected on step "${step.id}". ` +
+          `[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.`
@@ -978,7 +1270,7 @@ export class PathEngine {
       return true;
     } catch (err) {
       console.warn(
-        `[pathwrite] Guard on step "${step.id}" threw an error during snapshot evaluation. ` +
+        `[pathwrite] Guard on step "${item.id}" threw an error during snapshot evaluation. ` +
         `Returning true (allow navigation) as a safe default. ` +
         `Note: guards are evaluated before onEnter runs on first entry — ` +
         `ensure guards handle missing/undefined data gracefully.`,
@@ -991,24 +1283,24 @@ export class PathEngine {
   /**
    * Evaluates `canMoveNext` synchronously for inclusion in the snapshot.
    * When `canMoveNext` is defined, delegates to `evaluateGuardSync`.
-   * When absent but `fieldMessages` is defined, auto-derives: `true` iff no messages.
+   * When absent but `fieldErrors` is defined, auto-derives: `true` iff no messages.
    * When neither is defined, returns `true`.
    */
   private evaluateCanMoveNextSync(step: PathStep, active: ActivePath): boolean {
     if (step.canMoveNext) return this.evaluateGuardSync(step.canMoveNext, active);
-    if (step.fieldMessages) {
-      return Object.keys(this.evaluateFieldMessagesSync(step.fieldMessages, active)).length === 0;
+    if (step.fieldErrors) {
+      return Object.keys(this.evaluateFieldMessagesSync(step.fieldErrors, active)).length === 0;
     }
     return true;
   }
 
   /**
-   * Evaluates a fieldMessages function synchronously for inclusion in the snapshot.
+   * Evaluates a fieldErrors function synchronously for inclusion in the snapshot.
    * If the hook is absent, returns `{}`.
    * If the hook returns a `Promise`, returns `{}` (async hooks are not supported in snapshots).
    * `undefined` values are stripped from the result — only fields with a defined message are included.
    *
-   * **Note:** Like guards, `fieldMessages` is evaluated before `onEnter` runs on first
+   * **Note:** Like guards, `fieldErrors` is evaluated before `onEnter` runs on first
    * entry. Write it defensively so it does not throw when fields are absent.
    */
   private evaluateFieldMessagesSync(
@@ -1016,12 +1308,12 @@ export class PathEngine {
     active: ActivePath
   ): Record<string, string> {
     if (!fn) return {};
-    const step = this.getCurrentStep(active);
+    const item = this.getCurrentItem(active);
     const ctx: PathStepContext = {
       pathId: active.definition.id,
-      stepId: step.id,
+      stepId: item.id,
       data: { ...active.data },
-      isFirstEntry: !active.visitedStepIds.has(step.id)
+      isFirstEntry: !active.visitedStepIds.has(item.id)
     };
     try {
       const result = fn(ctx);
@@ -1036,22 +1328,45 @@ export class PathEngine {
       }
       if (result && typeof (result as unknown as { then?: unknown }).then === "function") {
         console.warn(
-          `[pathwrite] Async fieldMessages detected on step "${step.id}". ` +
-          `fieldMessages must be synchronous. Returning {} as default. ` +
+          `[pathwrite] Async fieldErrors detected on step "${item.id}". ` +
+          `fieldErrors must be synchronous. Returning {} as default. ` +
           `Use synchronous validation or move async checks to canMoveNext.`
         );
       }
       return {};
     } catch (err) {
       console.warn(
-        `[pathwrite] fieldMessages on step "${step.id}" threw an error during snapshot evaluation. ` +
+        `[pathwrite] fieldErrors on step "${item.id}" threw an error during snapshot evaluation. ` +
         `Returning {} as a safe default. ` +
-        `Note: fieldMessages is evaluated before onEnter runs on first entry — ` +
+        `Note: fieldErrors is evaluated before onEnter runs on first entry — ` +
         `ensure it handles missing/undefined data gracefully.`,
         err
       );
       return {};
     }
   }
+
+  /**
+   * Compares the current step data to the snapshot taken when the step was entered.
+   * Returns `true` if any data value has changed.
+   *
+   * Performs a shallow comparison — only top-level keys are checked. Nested objects
+   * are compared by reference, not by deep equality.
+   */
+  private computeIsDirty(active: ActivePath): boolean {
+    const current = active.data;
+    const entry = active.stepEntryData;
+
+    // Get all unique keys from both objects
+    const allKeys = new Set([...Object.keys(current), ...Object.keys(entry)]);
+
+    for (const key of allKeys) {
+      if (current[key] !== entry[key]) {
+        return true;
+      }
+    }
+
+    return false;
+  }
 }