@daltonr/pathwrite-core 0.3.0 → 0.5.0

package/README.md

@@ -2,6 +2,39 @@
 
 Headless path engine with zero dependencies. Manages step navigation, navigation guards, lifecycle hooks, and stack-based sub-path orchestration. Works equally well driving a UI wizard or a backend document lifecycle — no framework required.
 
+## Quick Reference: Common Patterns
+
+### ✅ Write Defensive Guards
+```typescript
+// Guards run BEFORE onEnter - always handle undefined data
+canMoveNext: (ctx) => (ctx.data.name ?? "").trim().length > 0  // ✅ Safe
+canMoveNext: (ctx) => ctx.data.name.trim().length > 0          // ❌ Crashes!
+```
+
+### ✅ Use `isFirstEntry` to Prevent Data Reset
+```typescript
+onEnter: (ctx) => {
+  if (ctx.isFirstEntry) {
+    return { items: [], status: "pending" };  // Initialize only on first visit
+  }
+  // Don't reset when user navigates back
+}
+```
+
+### ✅ Correlate Sub-Paths with `meta`
+```typescript
+// Starting sub-path
+engine.startSubPath(subPath, initialData, { itemIndex: i });
+
+// In parent step
+onSubPathComplete: (_id, subData, ctx, meta) => {
+  const index = meta?.itemIndex;  // Correlate back to collection item
+  // ...
+}
+```
+
+---
+
 ## Key types
 
 ```typescript
@@ -30,15 +63,22 @@ const path: PathDefinition<CourseData> = {
 | `PathStep<TData>` | A single step: guards, lifecycle hooks. |
 | `PathStepContext<TData>` | Passed to every hook and guard. `data` is a **readonly snapshot copy** — return a patch to update state. |
 | `PathSnapshot<TData>` | Point-in-time read of the engine: step ID, index, count, flags, and a copy of data. |
-| `PathEvent` | Union of `stateChanged`, `completed`, `cancelled`, and `resumed`. |
+| `PathEvent` | Union of `stateChanged` (includes `cause`), `completed`, `cancelled`, and `resumed`. |
+| `StateChangeCause` | Identifies the method that triggered a `stateChanged` event: `"start"` \| `"next"` \| `"previous"` \| `"goToStep"` \| `"goToStepChecked"` \| `"setData"` \| `"cancel"` \| `"restart"`. |
+| `PathObserver` | `(event: PathEvent, engine: PathEngine) => void` — a function registered at construction time that receives every event for the engine's lifetime. |
+| `PathEngineOptions` | `{ observers?: PathObserver[] }` — options accepted by the `PathEngine` constructor and `PathEngine.fromState()`. |
+| `ObserverStrategy` | Union type for the five built-in trigger strategies: `"onEveryChange" \| "onNext" \| "onSubPathComplete" \| "onComplete" \| "manual"`. Import and use in your own observer factories. |
+| `matchesStrategy` | `(strategy: ObserverStrategy, event: PathEvent) => boolean` — returns `true` when an event should trigger an observer under the given strategy. Shared by every observer so none re-implement the same "when do I fire?" logic. |
 
 ## PathEngine API
 
 ```typescript
-const engine = new PathEngine();
+// Observers are wired before the first event fires
+const engine = new PathEngine({ observers: [myObserver, anotherObserver] });
 
 engine.start(definition, initialData?);    // start or re-start a path
-engine.startSubPath(definition, data?);    // push sub-path onto the stack (requires active path)
+engine.restart(definition, initialData?);  // tear down stack and start fresh (no hooks, no cancelled event)
+engine.startSubPath(definition, data?, meta?); // push sub-path onto the stack (requires active path)
 engine.next();
 engine.previous();
 engine.cancel();
@@ -47,11 +87,58 @@ engine.goToStep(stepId);                   // jump to step by ID; bypasses guard
 engine.goToStepChecked(stepId);            // jump to step by ID; checks canMoveNext / canMovePrevious first
 engine.snapshot();                         // returns PathSnapshot | null
 
+// Serialization API (for persistence)
+const state = engine.exportState();        // returns SerializedPathState | null
+const restoredEngine = PathEngine.fromState(state, pathDefinitions, { observers: [...] });
+
+// Removable one-off listener (use subscribe when you need to unsubscribe)
 const unsubscribe = engine.subscribe((event) => { ... });
-unsubscribe(); // remove the listener
+unsubscribe();
+```
+
+## Observers
+
+Observers are functions registered at construction time. They receive every event for the engine's lifetime and cannot be removed — for removable listeners use `subscribe()`.
+
+```typescript
+// A logger observer
+const logger: PathObserver = (event) =>
+  console.log(`[${event.type}]`, 'cause' in event ? event.cause : '');
+
+// A persistence observer using matchesStrategy from core
+import { matchesStrategy } from "@daltonr/pathwrite-core";
+
+const persist: PathObserver = (event, engine) => {
+  if (matchesStrategy("onNext", event)) {
+    myStore.save(engine.exportState());
+  }
+};
+
+const engine = new PathEngine({ observers: [logger, persist] });
+
+// Observers are also passed through fromState — so restored engines are fully observed
+const restoredEngine = PathEngine.fromState(saved, pathDefs, { observers: [logger, persist] });
 ```
 
-## Lifecycle hooks
+The second argument to each observer is the engine itself, which lets observers call `engine.exportState()`, `engine.snapshot()`, etc. without needing a separate reference.
+
+### Building your own observer factory
+
+`ObserverStrategy` and `matchesStrategy` are exported from core so any observer — not just HTTP persistence — can share the same strategy logic without reimplementing it:
+
+```typescript
+import { type ObserverStrategy, matchesStrategy, type PathObserver } from "@daltonr/pathwrite-core";
+
+function myObserver(strategy: ObserverStrategy): PathObserver {
+  return (event, engine) => {
+    if (matchesStrategy(strategy, event)) {
+      // react — save to MongoDB, write to a log, fire analytics, etc.
+    }
+  };
+}
+```
+
+
 
 All hooks are optional. Hooks that want to update data **return a partial patch** — the engine applies it automatically. Direct mutation of `ctx.data` is a no-op; the context receives a copy.
 
@@ -60,46 +147,375 @@ All hooks are optional. Hooks that want to update data **return a partial patch*
 | `onEnter` | On arrival at a step (start, next, previous, resume) | ✅ |
 | `onLeave` | On departure from a step (only when the guard allows) | ✅ |
 | `onSubPathComplete` | On the parent step when a sub-path finishes | ✅ |
+| `onSubPathCancel` | On the parent step when a sub-path is cancelled | ✅ |
 | `canMoveNext` | Before advancing — return `false` to block | — |
 | `canMovePrevious` | Before going back — return `false` to block | — |
 | `validationMessages` | On every snapshot — return `string[]` explaining why the step is not yet valid | — |
 
+### Using `isFirstEntry` to Avoid Data Reset
+
+**Problem:** `onEnter` fires EVERY time you enter a step, including when navigating backward. If you initialize data in `onEnter`, you'll overwrite user input when they return to the step.
+
+**Solution:** Use `ctx.isFirstEntry` to distinguish first visit from re-entry:
+
+```typescript
+{
+  id: "user-details",
+  onEnter: (ctx) => {
+    // Only initialize on first entry, not on re-entry
+    if (ctx.isFirstEntry) {
+      return {
+        name: "",
+        email: "",
+        preferences: { newsletter: true }
+      };
+    }
+    // On re-entry (e.g., user pressed Back), keep existing data
+  }
+}
+```
+
+**Common Patterns:**
+
+```typescript
+// Initialize empty collection on first entry only
+onEnter: (ctx) => {
+  if (ctx.isFirstEntry) {
+    return { approvals: [], comments: [] };
+  }
+}
+
+// Fetch data from API only once
+onEnter: async (ctx) => {
+  if (ctx.isFirstEntry) {
+    const userData = await fetchUserProfile(ctx.data.userId);
+    return { ...userData };
+  }
+}
+
+// Set defaults but preserve user changes on re-entry
+onEnter: (ctx) => {
+  if (ctx.isFirstEntry) {
+    return {
+      reviewStatus: "pending",
+      lastModified: new Date().toISOString()
+    };
+  }
+}
+```
+
 ### Snapshot guard booleans
 
 The snapshot includes `canMoveNext` and `canMovePrevious` booleans — the evaluated results of the current step's guards. Use them to proactively disable navigation buttons. Sync guards reflect their real value; async guards default to `true` (optimistic). Both update automatically when data changes via `setData`.
 
-### Example — sub-path result merged into parent data
+### ⚠️ IMPORTANT: Guards Run Before `onEnter`
+
+**Guards are evaluated BEFORE `onEnter` runs on first entry.** This is critical to understand:
+
+1. When a path starts, the engine creates the first snapshot immediately
+2. Guards (`canMoveNext`, `validationMessages`) are evaluated to populate that snapshot
+3. Only THEN does `onEnter` run to initialize data
+
+**This means guards see `initialData`, not data that `onEnter` would set.**
+
+#### Defensive Guard Patterns
+
+Always write guards defensively to handle undefined/missing data:
 
 ```typescript
+// ❌ WRONG - Crashes on first snapshot when initialData = {}
 {
-  id: "subjects-list",
-  onSubPathComplete: (_id, subData, ctx) => ({
-    subjects: [...(ctx.data.subjects ?? []), { name: subData.name, teacher: subData.teacher }]
-  })
+  id: "user-details",
+  canMoveNext: (ctx) => ctx.data.name.trim().length > 0,  // TypeError!
+  onEnter: () => ({ name: "" })  // Too late - guard already ran
+}
+
+// ✅ CORRECT - Use nullish coalescing
+{
+  id: "user-details",
+  canMoveNext: (ctx) => (ctx.data.name ?? "").trim().length > 0,
+  onEnter: () => ({ name: "" })
+}
+
+// ✅ ALSO CORRECT - Provide initialData so fields exist from the start
+engine.start(path, { name: "", email: "" });
+```
+
+#### More Defensive Patterns
+
+```typescript
+// Arrays
+canMoveNext: (ctx) => (ctx.data.items ?? []).length > 0
+
+// Numbers
+canMoveNext: (ctx) => (ctx.data.age ?? 0) >= 18
+
+// Complex objects
+canMoveNext: (ctx) => {
+  const address = ctx.data.address ?? {};
+  return (address.street ?? "").length > 0 && (address.city ?? "").length > 0;
+}
+
+// Validation messages
+validationMessages: (ctx) => {
+  const messages = [];
+  if (!(ctx.data.email ?? "").includes("@")) {
+    messages.push("Please enter a valid email");
+  }
+  return messages;
 }
 ```
 
-## Sub-path flow
+#### Error Handling
+
+If a guard or `validationMessages` hook throws, Pathwrite catches the error, emits a `console.warn` (with the step ID and thrown value), and returns the safe default (`true` / `[]`) so the UI remains operable. However, **relying on error handling is not recommended** — write defensive guards instead.
 
+### Sub-path example with meta correlation
+
+```typescript
+{
+  id: "subjects-list",
+  onSubPathComplete: (_id, subData, ctx, meta) => {
+    // meta contains the correlation object passed to startSubPath
+    const index = meta?.index as number;
+    return {
+      subjects: [...(ctx.data.subjects ?? []), { 
+        index,
+        name: subData.name, 
+        teacher: subData.teacher 
+      }]
+    };
+  },
+  onSubPathCancel: (_id, ctx, meta) => {
+    // Called when user cancels sub-path (e.g., Back on first step)
+    const index = meta?.index as number;
+    console.log(`User skipped subject ${index}`);
+    // Return patch to record the skip, or return nothing to ignore
+  }
+}
 ```
+
+## Sub-Paths: Comprehensive Guide
+
+Sub-paths let you nest workflows — for example, running a mini-wizard for each item in a collection.
+
+### Basic Flow
+
+```typescript
 engine.start(mainPath)          → stack: []         active: main
 engine.startSubPath(subPath)    → stack: [main]     active: sub
 engine.next()  // sub finishes
   → onSubPathComplete fires on the parent step
-  → stack: []                                       active: main
+  → stack: []                   active: main (resumed)
 ```
 
-Cancelling a sub-path pops it off the stack silently — `onSubPathComplete` is **not** called.
+### Complete Example: Document Approval Workflow
+
+```typescript
+interface ApprovalData extends PathData {
+  documentTitle: string;
+  approvers: Array<{ name: string; email: string }>;
+  approvals: Array<{ approverIndex: number; decision: string; comments: string }>;
+}
+
+interface ApproverReviewData extends PathData {
+  documentTitle: string;  // Passed from parent
+  decision?: "approve" | "reject";
+  comments?: string;
+}
+
+// Main path
+const approvalPath: PathDefinition<ApprovalData> = {
+  id: "approval-workflow",
+  steps: [
+    {
+      id: "setup",
+      onEnter: (ctx) => {
+        if (ctx.isFirstEntry) {
+          return { approvers: [], approvals: [] };
+        }
+      }
+    },
+    {
+      id: "run-approvals",
+      // Block next until all approvers have completed
+      canMoveNext: (ctx) => {
+        const approversCount = (ctx.data.approvers ?? []).length;
+        const approvalsCount = (ctx.data.approvals ?? []).length;
+        return approversCount > 0 && approvalsCount === approversCount;
+      },
+      validationMessages: (ctx) => {
+        const approversCount = (ctx.data.approvers ?? []).length;
+        const approvalsCount = (ctx.data.approvals ?? []).length;
+        const remaining = approversCount - approvalsCount;
+        if (remaining > 0) {
+          return [`${remaining} approver(s) still need to complete their review`];
+        }
+        return [];
+      },
+      // Called when each approver sub-path completes
+      onSubPathComplete: (_subPathId, subData, ctx, meta) => {
+        const reviewData = subData as ApproverReviewData;
+        const approverIndex = meta?.approverIndex as number;
+        
+        return {
+          approvals: [
+            ...(ctx.data.approvals ?? []),
+            {
+              approverIndex,
+              decision: reviewData.decision!,
+              comments: reviewData.comments ?? ""
+            }
+          ]
+        };
+      },
+      // Called when approver cancels (presses Back on first step)
+      onSubPathCancel: (_subPathId, ctx, meta) => {
+        const approverIndex = meta?.approverIndex as number;
+        console.log(`Approver ${approverIndex} declined to review`);
+        // Could add to a "skipped" list or just ignore
+      }
+    },
+    { id: "summary" }
+  ]
+};
+
+// Sub-path for each approver
+const approverReviewPath: PathDefinition<ApproverReviewData> = {
+  id: "approver-review",
+  steps: [
+    { id: "review-document" },
+    {
+      id: "make-decision",
+      canMoveNext: (ctx) => ctx.data.decision !== undefined
+    },
+    { id: "add-comments" }
+  ]
+};
+
+// Usage in UI component
+function ReviewStep() {
+  const approvers = snapshot.data.approvers ?? [];
+  const approvals = snapshot.data.approvals ?? [];
+  
+  const startReview = (approverIndex: number) => {
+    const approver = approvers[approverIndex];
+    
+    // Start sub-path with meta correlation
+    engine.startSubPath(
+      approverReviewPath,
+      {
+        documentTitle: snapshot.data.documentTitle,  // Pass context from parent
+        // decision and comments will be filled during sub-path
+      },
+      { approverIndex }  // Meta: correlates completion back to this approver
+    );
+  };
+  
+  return (
+    <div>
+      {approvers.map((approver, i) => (
+        <div key={i}>
+          {approver.name}
+          {approvals.some(a => a.approverIndex === i) ? (
+            <span>✓ Reviewed</span>
+          ) : (
+            <button onClick={() => startReview(i)}>Start Review</button>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Sub-Path Key Concepts
+
+1. **Stack-based**: Sub-paths push onto a stack. Parent is paused while sub-path is active.
+
+2. **Meta correlation**: Pass a `meta` object to `startSubPath()` to identify which collection item triggered the sub-path. It's passed back unchanged to `onSubPathComplete` and `onSubPathCancel`.
+
+3. **Data isolation**: Sub-path data is separate from parent data. Pass needed context (like `documentTitle`) in `initialData`.
+
+4. **Completion vs Cancellation**:
+   - **Complete**: User reaches the last step → `onSubPathComplete` fires
+   - **Cancel**: User presses Back on first step → `onSubPathCancel` fires
+   - `onSubPathComplete` is NOT called on cancellation
+
+5. **Parent remains on same step**: After sub-path completes/cancels, parent resumes at the same step (not advanced automatically).
+
+6. **Guards still apply**: Parent step's `canMoveNext` is evaluated when resuming. Use it to block until all sub-paths complete.
+
+### What the Shell Renders During Sub-Paths
+
+When a sub-path is active:
+- Progress bar shows sub-path steps (parent steps disappear)
+- Back button on sub-path's first step cancels the sub-path
+- Completing the sub-path returns to parent (parent step re-renders)
+
+### Nesting Levels
+
+Sub-paths can themselves start sub-paths (unlimited nesting). Use `snapshot.nestingLevel` to determine depth:
+- `0` = top-level path
+- `1` = first-level sub-path
+- `2+` = deeper nesting
 
 ## Events
 
 ```typescript
 engine.subscribe((event) => {
   switch (event.type) {
-    case "stateChanged": // event.snapshot
+    case "stateChanged": // event.cause ("start" | "next" | "previous" | ...), event.snapshot
     case "completed":    // event.pathId, event.data
     case "cancelled":    // event.pathId, event.data
     case "resumed":      // event.resumedPathId, event.fromSubPathId, event.snapshot
   }
 });
 ```
+
+Every `stateChanged` event includes a `cause` field (`StateChangeCause`) identifying which public method triggered it. Use this to react to specific operations — for example, the `store-http` package uses `event.cause === "next"` to implement the `onNext` persistence strategy.
+
+## State Persistence
+
+The engine supports exporting and restoring state for persistence scenarios (e.g., saving wizard progress to a server or localStorage).
+
+### exportState()
+
+Returns a plain JSON-serializable object (`SerializedPathState`) containing the current state:
+- Current path ID and step index
+- Path data
+- Visited step IDs
+- Sub-path stack (if nested paths are active)
+- Navigation flags
+
+Returns `null` if no path is active.
+
+```typescript
+const state = engine.exportState();
+if (state) {
+  const json = JSON.stringify(state);
+  // Save to localStorage, send to server, etc.
+}
+```
+
+### PathEngine.fromState()
+
+Restores a PathEngine from previously exported state. **Important:** You must provide the same path definitions that were active when the state was exported.
+
+```typescript
+const state = JSON.parse(savedJson);
+const engine = PathEngine.fromState(state, {
+  "main-path": mainPathDefinition,
+  "sub-path": subPathDefinition
+});
+
+// Engine is restored to the exact step and state
+const snapshot = engine.snapshot();
+```
+
+Throws if:
+- State references a path ID not in `pathDefinitions`
+- State version is unsupported
+
+The restored engine is fully functional — you can continue navigation, modify data, complete or cancel paths normally.
+```

package/dist/index.d.ts

@@ -1,4 +1,33 @@
 export type PathData = Record<string, unknown>;
+export interface SerializedPathState {
+    version: 1;
+    pathId: string;
+    currentStepIndex: number;
+    data: PathData;
+    visitedStepIds: string[];
+    subPathMeta?: Record<string, unknown>;
+    pathStack: Array<{
+        pathId: string;
+        currentStepIndex: number;
+        data: PathData;
+        visitedStepIds: string[];
+        subPathMeta?: Record<string, unknown>;
+    }>;
+    _isNavigating: boolean;
+}
+/**
+ * The interface every path state store must implement.
+ *
+ * `HttpStore` from `@daltonr/pathwrite-store-http` is the reference
+ * implementation. Any backend — MongoDB, Redis, localStorage, etc. —
+ * implements this interface and works with `httpPersistence` and
+ * `restoreOrStart` without any other changes.
+ */
+export interface PathStore {
+    save(key: string, state: SerializedPathState): Promise<void>;
+    load(key: string): Promise<SerializedPathState | null>;
+    delete(key: string): Promise<void>;
+}
 export interface PathStepContext<TData extends PathData = PathData> {
     readonly pathId: string;
     readonly stepId: string;
@@ -79,8 +108,13 @@ export interface PathSnapshot<TData extends PathData = PathData> {
     validationMessages: string[];
     data: TData;
 }
+/**
+ * Identifies the public method that triggered a `stateChanged` event.
+ */
+export type StateChangeCause = "start" | "next" | "previous" | "goToStep" | "goToStepChecked" | "setData" | "cancel" | "restart";
 export type PathEvent = {
     type: "stateChanged";
+    cause: StateChangeCause;
     snapshot: PathSnapshot;
 } | {
     type: "completed";
@@ -96,13 +130,93 @@ export type PathEvent = {
     fromSubPathId: string;
     snapshot: PathSnapshot;
 };
+/**
+ * A function called on every engine event. Observers are registered at
+ * construction time and receive every event for the lifetime of the engine.
+ *
+ * The second argument is the engine itself — useful when the observer needs to
+ * read current state (e.g. calling `engine.exportState()` for persistence).
+ *
+ * ```typescript
+ * const logger: PathObserver = (event) => console.log(event.type);
+ * const persist: PathObserver = (event, engine) => { ... };
+ * ```
+ */
+export type PathObserver = (event: PathEvent, engine: PathEngine) => void;
+/**
+ * Determines which engine events an observer should react to.
+ *
+ * | Strategy            | Triggers when                                              |
+ * |---------------------|------------------------------------------------------------|
+ * | `"onEveryChange"`   | Any settled `stateChanged` or `resumed`                    |
+ * | `"onNext"`          | `next()` completes navigation *(default)*                  |
+ * | `"onSubPathComplete"` | Sub-path finishes and the parent resumes                 |
+ * | `"onComplete"`      | The entire path completes                                  |
+ * | `"manual"`          | Never — caller decides when to act                        |
+ */
+export type ObserverStrategy = "onEveryChange" | "onNext" | "onSubPathComplete" | "onComplete" | "manual";
+/**
+ * Returns `true` when `event` matches the trigger condition for `strategy`.
+ *
+ * Use this in any `PathObserver` factory to centralise the
+ * "which events should I react to?" decision so every observer
+ * (HTTP, MongoDB, logger, analytics…) shares the same semantics.
+ *
+ * ```typescript
+ * const observer: PathObserver = (event, engine) => {
+ *   if (matchesStrategy(strategy, event)) doWork(engine);
+ * };
+ * ```
+ */
+export declare function matchesStrategy(strategy: ObserverStrategy, event: PathEvent): boolean;
+/**
+ * Options accepted by the `PathEngine` constructor and `PathEngine.fromState()`.
+ */
+export interface PathEngineOptions {
+    /**
+     * Zero or more observers to register before the first event fires.
+     * Each observer is called synchronously on every engine event for the
+     * lifetime of the engine. Observers cannot be removed; for removable
+     * listeners use `engine.subscribe()`.
+     */
+    observers?: PathObserver[];
+}
 export declare class PathEngine {
     private activePath;
     private readonly pathStack;
     private readonly listeners;
     private _isNavigating;
+    constructor(options?: PathEngineOptions);
+    /**
+     * Restores a PathEngine from previously exported state.
+     *
+     * **Important:** You must provide the same path definitions that were
+     * active when the state was exported. The path IDs in `state` are used
+     * to match against the provided definitions.
+     *
+     * @param state           The serialized state from `exportState()`.
+     * @param pathDefinitions A map of path ID → definition. Must include the
+     *                        active path and any paths in the stack.
+     * @returns A new PathEngine instance with the restored state.
+     * @throws If `state` references a path ID not present in `pathDefinitions`,
+     *         or if the state format is invalid.
+     */
+    static fromState(state: SerializedPathState, pathDefinitions: Record<string, PathDefinition>, options?: PathEngineOptions): PathEngine;
     subscribe(listener: (event: PathEvent) => void): () => void;
     start(path: PathDefinition<any>, initialData?: PathData): Promise<void>;
+    /**
+     * Tears down any active path (and the entire sub-path stack) without firing
+     * lifecycle hooks or emitting `cancelled`, then immediately starts the given
+     * path from scratch.
+     *
+     * Safe to call at any time — whether a path is running, already completed,
+     * or has never been started. Use this to implement a "Start over" button or
+     * to retry a path after completion without remounting the host component.
+     *
+     * @param path        The path definition to (re)start.
+     * @param initialData Data to seed the fresh path with. Defaults to `{}`.
+     */
+    restart(path: PathDefinition<any>, initialData?: PathData): Promise<void>;
     /**
      * Starts a sub-path on top of the currently active path. Throws if no path
      * is running.
@@ -137,6 +251,18 @@ export declare class PathEngine {
      */
     goToStepChecked(stepId: string): Promise<void>;
     snapshot(): PathSnapshot | null;
+    /**
+     * Exports the current engine state as a plain JSON-serializable object.
+     * Use with storage adapters (e.g. `@daltonr/pathwrite-store-http`) to
+     * persist and restore wizard progress.
+     *
+     * Returns `null` if no path is active.
+     *
+     * **Important:** This only exports the _state_ (data, step position, etc.),
+     * not the path definition. When restoring, you must provide the same
+     * `PathDefinition` to `fromState()`.
+     */
+    exportState(): SerializedPathState | null;
     private _startAsync;
     private _nextAsync;
     private _previousAsync;
@@ -159,12 +285,27 @@ export declare class PathEngine {
      * Evaluates a guard function synchronously for inclusion in the snapshot.
      * If the guard is absent, returns `true`.
      * If the guard returns a `Promise`, returns `true` (optimistic default).
+     *
+     * **Note:** Guards are evaluated on every snapshot, including the very first one
+     * emitted at the start of a path — _before_ `onEnter` has run on that step.
+     * This means `data` will still reflect the `initialData` passed to `start()`.
+     * Write guards defensively (e.g. `(data.name ?? "").trim().length > 0`) so they
+     * do not throw when optional fields are absent on first entry.
+     *
+     * If a guard throws, the error is caught, a `console.warn` is emitted, and the
+     * safe default (`true`) is returned so the UI remains operable.
      */
     private evaluateGuardSync;
     /**
      * Evaluates a validationMessages 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).
+     *
+     * **Note:** Like guards, `validationMessages` is evaluated before `onEnter` runs on first
+     * entry. Write it defensively so it does not throw when fields are absent.
+     *
+     * If the function throws, the error is caught, a `console.warn` is emitted, and `[]`
+     * is returned so validation messages do not block the UI unexpectedly.
      */
     private evaluateValidationMessagesSync;
 }