@daltonr/pathwrite-react 0.3.0 → 0.5.0

package/README.md

@@ -2,6 +2,35 @@
 
 React hooks over `@daltonr/pathwrite-core`. Exposes path state as reactive React state via `useSyncExternalStore`, with stable action callbacks and an optional context provider.
 
+## Installation
+
+```bash
+npm install @daltonr/pathwrite-core @daltonr/pathwrite-react
+```
+
+## Exported Types
+
+For convenience, this package re-exports core types so you don't need to import from `@daltonr/pathwrite-core`:
+
+```typescript
+import { 
+  PathShell,            // React-specific
+  usePath,              // React-specific
+  usePathContext,       // React-specific
+  PathProvider,         // React-specific
+  PathEngine,           // Re-exported from core (value + type)
+  PathData,             // Re-exported from core
+  PathDefinition,       // Re-exported from core
+  PathEvent,            // Re-exported from core
+  PathSnapshot,         // Re-exported from core
+  PathStep,             // Re-exported from core
+  PathStepContext,      // Re-exported from core
+  SerializedPathState   // Re-exported from core
+} from "@daltonr/pathwrite-react";
+```
+
+---
+
 ## Setup
 
 ### Option A — `usePath` hook (component-scoped)
@@ -26,7 +55,7 @@ function MyPathHost() {
           <p>Step {snapshot.stepIndex + 1} of {snapshot.stepCount}</p>
           <button onClick={previous} disabled={snapshot.isNavigating}>Back</button>
           <button onClick={next}     disabled={snapshot.isNavigating}>
-            {snapshot.isLastStep ? "Finish" : "Next"}
+            {snapshot.isLastStep ? "Complete" : "Next"}
           </button>
           <button onClick={cancel}>Cancel</button>
         </>
@@ -78,6 +107,7 @@ function NavButtons() {
 
 | Option | Type | Description |
 |--------|------|-------------|
+| `engine` | `PathEngine` | An externally-managed engine (e.g. from `createPersistedEngine()`). When provided, `usePath` subscribes to it instead of creating a new one; snapshot is seeded immediately from the engine's current state. The caller is responsible for the engine's lifecycle. Must be a stable reference. |
 | `onEvent` | `(event: PathEvent) => void` | Called for every engine event. The callback ref is kept current — changing it does **not** re-subscribe to the engine. |
 
 ### Return value
@@ -93,6 +123,7 @@ function NavButtons() {
 | `goToStep(stepId)` | `function` | Jump directly to a step by ID. Calls `onLeave` / `onEnter` but bypasses guards and `shouldSkip`. |
 | `goToStepChecked(stepId)` | `function` | Jump to a step by ID, checking `canMoveNext` (forward) or `canMovePrevious` (backward) first. Navigation is blocked if the guard returns false. |
 | `setData(key, value)` | `function` | Update a single data value; triggers re-render via `stateChanged`. When `TData` is specified, `key` and `value` are type-checked against your data shape. |
+| `restart(definition, data?)` | `function` | Tear down any active path (without firing hooks) and start the given path fresh. Safe to call at any time. Use for "Start over" / retry flows. |
 
 All action callbacks are **referentially stable** — safe to pass as props or include in dependency arrays without causing unnecessary re-renders.
 
@@ -163,15 +194,16 @@ import { PathShell } from "@daltonr/pathwrite-react";
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `path` | `PathDefinition` | *required* | The path to run. |
+| `engine` | `PathEngine` | — | An externally-managed engine. When provided, `PathShell` skips its own `start()` and drives the UI from this engine. |
 | `steps` | `Record<string, ReactNode>` | *required* | Map of step ID → content to render. |
 | `initialData` | `PathData` | `{}` | Initial data passed to `engine.start()`. |
 | `autoStart` | `boolean` | `true` | Start the path automatically on mount. |
 | `onComplete` | `(data: PathData) => void` | — | Called when the path completes. |
 | `onCancel` | `(data: PathData) => void` | — | Called when the path is cancelled. |
 | `onEvent` | `(event: PathEvent) => void` | — | Called for every engine event. |
-| `backLabel` | `string` | `"Back"` | Back button label. |
+| `backLabel` | `string` | `"Previous"` | Previous button label. |
 | `nextLabel` | `string` | `"Next"` | Next button label. |
-| `finishLabel` | `string` | `"Finish"` | Finish button label (last step). |
+| `completeLabel` | `string` | `"Complete"` | Complete button label (last step). |
 | `cancelLabel` | `string` | `"Cancel"` | Cancel button label. |
 | `hideCancel` | `boolean` | `false` | Hide the Cancel button. |
 | `hideProgress` | `boolean` | `false` | Hide the progress indicator. |
@@ -194,14 +226,14 @@ Use `renderHeader` and `renderFooter` to replace the built-in progress bar or na
     <div>
       <button onClick={actions.previous} disabled={snapshot.isFirstStep}>Back</button>
       <button onClick={actions.next}     disabled={!snapshot.canMoveNext}>
-        {snapshot.isLastStep ? "Finish" : "Next"}
+        {snapshot.isLastStep ? "Complete" : "Next"}
       </button>
     </div>
   )}
 />
 ```
 
-`PathShellActions` contains: `next`, `previous`, `cancel`, `goToStep`, `goToStepChecked`, `setData`.
+`PathShellActions` contains: `next`, `previous`, `cancel`, `goToStep`, `goToStepChecked`, `setData`, `restart`.
 
 ### Context sharing
 
@@ -245,11 +277,259 @@ All visual values are CSS custom properties (`--pw-*`), so you can theme without
 }
 ```
 
+### Available CSS Custom Properties
+
+**Layout:**
+- `--pw-shell-max-width` — Maximum width of the shell (default: `720px`)
+- `--pw-shell-padding` — Internal padding (default: `24px`)
+- `--pw-shell-gap` — Gap between header, body, footer (default: `20px`)
+- `--pw-shell-radius` — Border radius for cards (default: `10px`)
+
+**Colors:**
+- `--pw-color-bg` — Background color (default: `#ffffff`)
+- `--pw-color-border` — Border color (default: `#dbe4f0`)
+- `--pw-color-text` — Primary text color (default: `#1f2937`)
+- `--pw-color-muted` — Muted text color (default: `#5b677a`)
+- `--pw-color-primary` — Primary/accent color (default: `#2563eb`)
+- `--pw-color-primary-light` — Light primary for backgrounds (default: `rgba(37, 99, 235, 0.12)`)
+- `--pw-color-btn-bg` — Button background (default: `#f8fbff`)
+- `--pw-color-btn-border` — Button border (default: `#c2d0e5`)
+
+**Validation:**
+- `--pw-color-error` — Error text color (default: `#dc2626`)
+- `--pw-color-error-bg` — Error background (default: `#fef2f2`)
+- `--pw-color-error-border` — Error border (default: `#fecaca`)
+
+**Progress Indicator:**
+- `--pw-dot-size` — Step dot size (default: `32px`)
+- `--pw-dot-font-size` — Font size inside dots (default: `13px`)
+- `--pw-track-height` — Progress track height (default: `4px`)
+
+**Buttons:**
+- `--pw-btn-padding` — Button padding (default: `8px 16px`)
+- `--pw-btn-radius` — Button border radius (default: `6px`)
+
 ---
 
-## Design notes
+## Sub-Paths
+
+Sub-paths allow you to nest multi-step workflows. Common use cases include:
+- Running a child workflow per collection item (e.g., approve each document)
+- Conditional drill-down flows (e.g., "Add payment method" modal)
+- Reusable wizard components
+
+### Basic Sub-Path Flow
+
+When a sub-path is active:
+- The shell switches to show the sub-path's steps
+- The progress bar displays sub-path steps (not main path steps)
+- Pressing Back on the first sub-path step **cancels** the sub-path and returns to the parent
+- `usePathContext()` returns the **sub-path** snapshot, not the parent's
+
+### Complete Example: Approver Collection
+
+```tsx
+import type { PathData, PathDefinition } from "@daltonr/pathwrite-core";
+
+// Sub-path data shape
+interface ApproverReviewData extends PathData {
+  decision: "approve" | "reject" | "";
+  comments: string;
+}
+
+// Main path data shape
+interface ApprovalWorkflowData extends PathData {
+  documentTitle: string;
+  approvers: string[];
+  approvals: Array<{ approver: string; decision: string; comments: string }>;
+}
+
+// Define the sub-path (approver review wizard)
+const approverReviewPath: PathDefinition<ApproverReviewData> = {
+  id: "approver-review",
+  steps: [
+    { id: "review", title: "Review Document" },
+    {
+      id: "decision",
+      title: "Make Decision",
+      canMoveNext: ({ data }) =>
+        data.decision === "approve" || data.decision === "reject",
+      validationMessages: ({ data }) =>
+        !data.decision ? ["Please select Approve or Reject"] : []
+    },
+    { id: "comments", title: "Add Comments" }
+  ]
+};
+
+// Define the main path
+const approvalWorkflowPath: PathDefinition<ApprovalWorkflowData> = {
+  id: "approval-workflow",
+  steps: [
+    {
+      id: "setup",
+      title: "Setup Approval",
+      canMoveNext: ({ data }) =>
+        (data.documentTitle ?? "").trim().length > 0 &&
+        data.approvers.length > 0
+    },
+    {
+      id: "run-approvals",
+      title: "Collect Approvals",
+      // Block "Next" until all approvers have completed their reviews
+      canMoveNext: ({ data }) =>
+        data.approvals.length === data.approvers.length,
+      validationMessages: ({ data }) => {
+        const remaining = data.approvers.length - data.approvals.length;
+        return remaining > 0
+          ? [`${remaining} approver(s) pending review`]
+          : [];
+      },
+      // When an approver finishes their sub-path, record the result
+      onSubPathComplete(subPathId, subPathData, ctx, meta) {
+        const approverName = meta?.approverName as string;
+        const result = subPathData as ApproverReviewData;
+        return {
+          approvals: [
+            ...ctx.data.approvals,
+            {
+              approver: approverName,
+              decision: result.decision,
+              comments: result.comments
+            }
+          ]
+        };
+      },
+      // If an approver cancels (presses Back on first step), you can track it
+      onSubPathCancel(subPathId, subPathData, ctx, meta) {
+        console.log(`${meta?.approverName} cancelled their review`);
+        // Optionally return data changes, or just log
+      }
+    },
+    { id: "summary", title: "Summary" }
+  ]
+};
+
+// Component
+function ApprovalWorkflow() {
+  const { startSubPath } = usePathContext<ApprovalWorkflowData>();
+
+  function launchReviewForApprover(approverName: string, index: number) {
+    // Pass correlation data via `meta` — it's echoed back to onSubPathComplete
+    startSubPath(
+      approverReviewPath,
+      { decision: "", comments: "" },
+      { approverName, approverIndex: index }
+    );
+  }
+
+  return (
+    <PathShell
+      path={approvalWorkflowPath}
+      initialData={{ documentTitle: "", approvers: [], approvals: [] }}
+      steps={{
+        setup: <SetupStep />,
+        "run-approvals": <RunApprovalsStep onLaunchReview={launchReviewForApprover} />,
+        summary: <SummaryStep />,
+        // Sub-path steps (must be co-located in the same steps map)
+        review: <ReviewDocumentStep />,
+        decision: <MakeDecisionStep />,
+        comments: <AddCommentsStep />
+      }}
+    />
+  );
+}
+```
+
+### Key Notes
+
+**1. Sub-path steps must be co-located with main path steps**  
+All step content (main path + sub-path steps) lives in the same `steps` prop. When a sub-path is active, the shell renders the sub-path's step content. This means:
+- Parent and sub-path step IDs **must not collide** (e.g., don't use `summary` in both)
+- Sub-path step components can access parent data by referencing the parent path definition, but `usePathContext()` returns the **sub-path** snapshot
+
+**2. The `meta` correlation field**  
+`startSubPath` accepts an optional third argument (`meta`) that is returned unchanged to `onSubPathComplete` and `onSubPathCancel`. Use it to correlate which collection item triggered the sub-path:
+
+```tsx
+startSubPath(subPath, initialData, { itemIndex: 3, itemId: "abc" });
+
+// In the parent step:
+onSubPathComplete(subPathId, subPathData, ctx, meta) {
+  const itemIndex = meta?.itemIndex; // 3
+}
+```
+
+**3. Progress bar switches during sub-paths**  
+When `snapshot.nestingLevel > 0`, you're in a sub-path. The `steps` array in the snapshot contains the sub-path's steps, not the main path's. The default PathShell progress bar shows sub-path progress. You can check `nestingLevel` to show a breadcrumb or "back to main flow" indicator.
 
-- **`useSyncExternalStore`** — the hook subscribes to the core `PathEngine` using React 18's `useSyncExternalStore`, giving tear-free reads with no `useEffect` timing gaps.
-- **Ref-based callback** — `onEvent` is stored in a ref so that a new closure on every render does not cause a re-subscription.
-- **No RxJS** — unlike the Angular adapter, there is no RxJS dependency. The hook is pure React.
+**4. Accessing parent path data from sub-path components**  
+There is currently no `useParentPathContext()` hook. If a sub-path step needs parent data (e.g., the document title), pass it via `initialData` when calling `startSubPath`:
+
+```tsx
+startSubPath(approverReviewPath, {
+  decision: "",
+  comments: "",
+  documentTitle: snapshot.data.documentTitle // copy from parent
+});
+```
+
+---
+
+## Guards and Lifecycle Hooks
+
+### Defensive Guards (Important!)
+
+**Guards and `validationMessages` are evaluated *before* `onEnter` runs on first entry.**
+
+If you access fields in a guard that `onEnter` is supposed to initialize, the guard will throw a `TypeError` on startup. Write guards defensively using nullish coalescing:
+
+```ts
+// ✗ Unsafe — crashes if data.name is undefined
+canMoveNext: ({ data }) => data.name.trim().length > 0
+
+// ✓ Safe — handles undefined gracefully
+canMoveNext: ({ data }) => (data.name ?? "").trim().length > 0
+```
+
+Alternatively, pass `initialData` to `start()` / `<PathShell>` so all fields are present from the first snapshot:
+
+```tsx
+<PathShell path={myPath} initialData={{ name: "", age: 0 }} />
+```
+
+If a guard throws, the engine catches it, logs a warning, and returns `true` (allow navigation) as a safe default.
+
+### Async Guards and Validation Messages
+
+Guards and `validationMessages` must be **synchronous** for inclusion in snapshots. Async functions are detected and warned about:
+- Async `canMoveNext` / `canMovePrevious` default to `true` (optimistic)
+- Async `validationMessages` default to `[]`
+
+The async version is still enforced during actual navigation (when you call `next()` / `previous()`), but the snapshot won't reflect the pending state. If you need async validation, perform it in the guard and store the result in `data` so the guard can read it synchronously.
+
+### `isFirstEntry` Flag
+
+The `PathStepContext` passed to all hooks includes an `isFirstEntry: boolean` flag. It's `true` the first time a step is visited, `false` on re-entry (e.g., after navigating back then forward again).
+
+Use it to distinguish initialization from re-entry:
+
+```ts
+{
+  id: "details",
+  onEnter: ({ isFirstEntry, data }) => {
+    if (isFirstEntry) {
+      // Only pre-fill on first visit, not when returning via Back
+      return { name: "Default Name" };
+    }
+  }
+}
+```
+
+**Important:** `onEnter` fires every time you enter the step. If you want "initialize once" behavior, either:
+1. Use `isFirstEntry` to conditionally return data
+2. Provide `initialData` to `start()` instead of using `onEnter`
+
+---
+
+## Design notes
 

package/dist/index.d.ts

@@ -1,7 +1,18 @@
 import type { PropsWithChildren, ReactElement, ReactNode } from "react";
-import { PathData, PathDefinition, PathEvent, PathSnapshot } from "@daltonr/pathwrite-core";
+import { PathData, PathDefinition, PathEngine, PathEvent, PathSnapshot } from "@daltonr/pathwrite-core";
 export interface UsePathOptions {
-    /** Called for every engine event (stateChanged, completed, cancelled, resumed). */
+    /**
+     * An externally-managed `PathEngine` to subscribe to — for example, the engine
+     * returned by `createPersistedEngine()` from `@daltonr/pathwrite-store-http`.
+     *
+     * When provided:
+     * - `usePath` will **not** create its own engine.
+     * - The snapshot is seeded immediately from the engine's current state.
+     * - The engine lifecycle (start / cleanup) is the **caller's responsibility**.
+     * - `PathShell` will skip its own `autoStart` call.
+     */
+    engine?: PathEngine;
+    /** Called for every engine event (stateChanged, completed, cancelled, resumed). The callback ref is kept current — changing it does **not** re-subscribe to the engine. */
     onEvent?: (event: PathEvent) => void;
 }
 export interface UsePathReturn<TData extends PathData = PathData> {
@@ -23,6 +34,12 @@ export interface UsePathReturn<TData extends PathData = PathData> {
     goToStepChecked: (stepId: string) => void;
     /** Update a single data value; triggers a re-render via stateChanged. When `TData` is specified, `key` and `value` are type-checked against your data shape. */
     setData: <K extends string & keyof TData>(key: K, value: TData[K]) => void;
+    /**
+     * Tear down any active path (without firing hooks) and immediately start the
+     * given path fresh. Safe to call whether or not a path is currently active.
+     * Use for "Start over" / retry flows without remounting the component.
+     */
+    restart: (path: PathDefinition<any>, initialData?: PathData) => void;
 }
 export type PathProviderProps = PropsWithChildren<{
     /** Forwarded to the internal usePath hook. */
@@ -45,6 +62,12 @@ export declare function usePathContext<TData extends PathData = PathData>(): Use
 export interface PathShellProps {
     /** The path definition to drive. */
     path: PathDefinition<any>;
+    /**
+     * An externally-managed engine — for example, the engine returned by
+     * `createPersistedEngine()`. When supplied, `PathShell` will skip its own
+     * `start()` call and drive the UI from the provided engine instead.
+     */
+    engine?: PathEngine;
     /** Map of step ID → content. The shell renders `steps[snapshot.stepId]` for the current step. */
     steps: Record<string, ReactNode>;
     /** Initial data passed to `engine.start()`. */
@@ -57,12 +80,12 @@ export interface PathShellProps {
     onCancel?: (data: PathData) => void;
     /** Called for every engine event. */
     onEvent?: (event: PathEvent) => void;
-    /** Label for the Back button. Defaults to `"Back"`. */
+    /** Label for the Previous button. Defaults to `"Previous"`. */
     backLabel?: string;
     /** Label for the Next button. Defaults to `"Next"`. */
     nextLabel?: string;
-    /** Label for the Finish button (shown on the last step). Defaults to `"Finish"`. */
-    finishLabel?: string;
+    /** Label for the Complete button (shown on the last step). Defaults to `"Complete"`. */
+    completeLabel?: string;
     /** Label for the Cancel button. Defaults to `"Cancel"`. */
     cancelLabel?: string;
     /** If true, hide the Cancel button. Defaults to `false`. */
@@ -83,6 +106,8 @@ export interface PathShellActions {
     goToStep: (stepId: string) => void;
     goToStepChecked: (stepId: string) => void;
     setData: (key: string, value: unknown) => void;
+    /** Restart the shell's current path with its current `initialData`. */
+    restart: () => void;
 }
 /**
  * Default UI shell that renders a progress indicator, step content, and navigation
@@ -100,4 +125,6 @@ export interface PathShellActions {
  * />
  * ```
  */
-export declare function PathShell({ path: pathDef, steps, initialData, autoStart, onComplete, onCancel, onEvent, backLabel, nextLabel, finishLabel, cancelLabel, hideCancel, hideProgress, className, renderHeader, renderFooter, }: PathShellProps): ReactElement;
+export declare function PathShell({ path: pathDef, engine: externalEngine, steps, initialData, autoStart, onComplete, onCancel, onEvent, backLabel, nextLabel, completeLabel, cancelLabel, hideCancel, hideProgress, className, renderHeader, renderFooter, }: PathShellProps): ReactElement;
+export type { PathData, PathDefinition, PathEvent, PathSnapshot, PathStep, PathStepContext, SerializedPathState } from "@daltonr/pathwrite-core";
+export { PathEngine } from "@daltonr/pathwrite-core";

package/dist/index.js

@@ -4,17 +4,31 @@ import { PathEngine } from "@daltonr/pathwrite-core";
 // usePath hook
 // ---------------------------------------------------------------------------
 export function usePath(options) {
-    // Stable engine instance for the lifetime of the hook
+    // Use provided engine or create a stable new one for this hook's lifetime.
+    // options.engine must be a stable reference (don't recreate on every render).
     const engineRef = useRef(null);
     if (engineRef.current === null) {
-        engineRef.current = new PathEngine();
+        engineRef.current = options?.engine ?? new PathEngine();
     }
     const engine = engineRef.current;
     // Keep the onEvent callback current without changing the subscribe identity
     const onEventRef = useRef(options?.onEvent);
     onEventRef.current = options?.onEvent;
-    // Cached snapshot — updated only inside the subscribe callback
+    // Seed immediately from existing engine state — essential when restoring a
+    // persisted path (the engine is already started before usePath is called).
+    // We track whether we've seeded to avoid calling engine.snapshot() on every
+    // re-render (React evaluates useRef's argument each time).
+    const seededRef = useRef(false);
     const snapshotRef = useRef(null);
+    if (!seededRef.current) {
+        seededRef.current = true;
+        try {
+            snapshotRef.current = engine.snapshot();
+        }
+        catch {
+            snapshotRef.current = null;
+        }
+    }
     const subscribe = useCallback((callback) => engine.subscribe((event) => {
         if (event.type === "stateChanged" || event.type === "resumed") {
             snapshotRef.current = event.snapshot;
@@ -36,7 +50,8 @@ export function usePath(options) {
     const goToStep = useCallback((stepId) => engine.goToStep(stepId), [engine]);
     const goToStepChecked = useCallback((stepId) => engine.goToStepChecked(stepId), [engine]);
     const setData = useCallback((key, value) => engine.setData(key, value), [engine]);
-    return { snapshot, start, startSubPath, next, previous, cancel, goToStep, goToStepChecked, setData };
+    const restart = useCallback((path, initialData = {}) => engine.restart(path, initialData), [engine]);
+    return { snapshot, start, startSubPath, next, previous, cancel, goToStep, goToStepChecked, setData, restart };
 }
 // ---------------------------------------------------------------------------
 // Context + Provider
@@ -80,8 +95,9 @@ export function usePathContext() {
  * />
  * ```
  */
-export function PathShell({ path: pathDef, steps, initialData = {}, autoStart = true, onComplete, onCancel, onEvent, backLabel = "Back", nextLabel = "Next", finishLabel = "Finish", cancelLabel = "Cancel", hideCancel = false, hideProgress = false, className, renderHeader, renderFooter, }) {
+export function PathShell({ path: pathDef, engine: externalEngine, steps, initialData = {}, autoStart = true, onComplete, onCancel, onEvent, backLabel = "Previous", nextLabel = "Next", completeLabel = "Complete", cancelLabel = "Cancel", hideCancel = false, hideProgress = false, className, renderHeader, renderFooter, }) {
     const pathReturn = usePath({
+        engine: externalEngine,
         onEvent(event) {
             onEvent?.(event);
             if (event.type === "completed")
@@ -90,11 +106,12 @@ export function PathShell({ path: pathDef, steps, initialData = {}, autoStart =
                 onCancel?.(event.data);
         }
     });
-    const { snapshot, start, next, previous, cancel, goToStep, goToStepChecked, setData } = pathReturn;
-    // Auto-start on mount
+    const { snapshot, start, next, previous, cancel, goToStep, goToStepChecked, setData, restart } = pathReturn;
+    // Auto-start on mount — skipped when an external engine is provided since
+    // the caller is responsible for starting it (e.g. via createPersistedEngine).
     const startedRef = useRef(false);
     useEffect(() => {
-        if (autoStart && !startedRef.current) {
+        if (autoStart && !startedRef.current && !externalEngine) {
             startedRef.current = true;
             start(pathDef, initialData);
         }
@@ -109,7 +126,10 @@ export function PathShell({ path: pathDef, steps, initialData = {}, autoStart =
             onClick: () => start(pathDef, initialData)
         }, "Start"))));
     }
-    const actions = { next, previous, cancel, goToStep, goToStepChecked, setData };
+    const actions = {
+        next, previous, cancel, goToStep, goToStepChecked, setData,
+        restart: () => restart(pathDef, initialData)
+    };
     return createElement(PathContext.Provider, { value: pathReturn }, createElement("div", { className: cls("pw-shell", className) }, 
     // Header — progress indicator
     !hideProgress && (renderHeader
@@ -123,7 +143,7 @@ export function PathShell({ path: pathDef, steps, initialData = {}, autoStart =
     renderFooter
         ? renderFooter(snapshot, actions)
         : defaultFooter(snapshot, actions, {
-            backLabel, nextLabel, finishLabel, cancelLabel, hideCancel
+            backLabel, nextLabel, completeLabel, cancelLabel, hideCancel
         })));
 }
 // ---------------------------------------------------------------------------
@@ -154,7 +174,7 @@ function defaultFooter(snapshot, actions, labels) {
         className: "pw-shell__btn pw-shell__btn--next",
         disabled: snapshot.isNavigating || !snapshot.canMoveNext,
         onClick: actions.next
-    }, snapshot.isLastStep ? labels.finishLabel : labels.nextLabel)));
+    }, snapshot.isLastStep ? labels.completeLabel : labels.nextLabel)));
 }
 // ---------------------------------------------------------------------------
 // Helpers
@@ -162,4 +182,5 @@ function defaultFooter(snapshot, actions, labels) {
 function cls(...parts) {
     return parts.filter(Boolean).join(" ");
 }
+export { PathEngine } from "@daltonr/pathwrite-core";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daltonr/pathwrite-react",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "license": "MIT",
   "description": "React adapter for @daltonr/pathwrite-core — hooks, context provider, and optional <PathShell> default UI.",
@@ -45,7 +45,7 @@
     "react": ">=18.0.0"
   },
   "dependencies": {
-    "@daltonr/pathwrite-core": "^0.3.0"
+    "@daltonr/pathwrite-core": "^0.5.0"
   },
   "devDependencies": {
     "react": "^18.3.1",

package/src/index.ts

@@ -21,7 +21,18 @@ import {
 // ---------------------------------------------------------------------------
 
 export interface UsePathOptions {
-  /** Called for every engine event (stateChanged, completed, cancelled, resumed). */
+  /**
+   * An externally-managed `PathEngine` to subscribe to — for example, the engine
+   * returned by `createPersistedEngine()` from `@daltonr/pathwrite-store-http`.
+   *
+   * When provided:
+   * - `usePath` will **not** create its own engine.
+   * - The snapshot is seeded immediately from the engine's current state.
+   * - The engine lifecycle (start / cleanup) is the **caller's responsibility**.
+   * - `PathShell` will skip its own `autoStart` call.
+   */
+  engine?: PathEngine;
+  /** Called for every engine event (stateChanged, completed, cancelled, resumed). The callback ref is kept current — changing it does **not** re-subscribe to the engine. */
   onEvent?: (event: PathEvent) => void;
 }
 
@@ -44,6 +55,12 @@ export interface UsePathReturn<TData extends PathData = PathData> {
   goToStepChecked: (stepId: string) => void;
   /** Update a single data value; triggers a re-render via stateChanged. When `TData` is specified, `key` and `value` are type-checked against your data shape. */
   setData: <K extends string & keyof TData>(key: K, value: TData[K]) => void;
+  /**
+   * Tear down any active path (without firing hooks) and immediately start the
+   * given path fresh. Safe to call whether or not a path is currently active.
+   * Use for "Start over" / retry flows without remounting the component.
+   */
+  restart: (path: PathDefinition<any>, initialData?: PathData) => void;
 }
 
 export type PathProviderProps = PropsWithChildren<{
@@ -56,10 +73,11 @@ export type PathProviderProps = PropsWithChildren<{
 // ---------------------------------------------------------------------------
 
 export function usePath<TData extends PathData = PathData>(options?: UsePathOptions): UsePathReturn<TData> {
-  // Stable engine instance for the lifetime of the hook
+  // Use provided engine or create a stable new one for this hook's lifetime.
+  // options.engine must be a stable reference (don't recreate on every render).
   const engineRef = useRef<PathEngine | null>(null);
   if (engineRef.current === null) {
-    engineRef.current = new PathEngine();
+    engineRef.current = options?.engine ?? new PathEngine();
   }
   const engine = engineRef.current;
 
@@ -67,8 +85,20 @@ export function usePath<TData extends PathData = PathData>(options?: UsePathOpti
   const onEventRef = useRef(options?.onEvent);
   onEventRef.current = options?.onEvent;
 
-  // Cached snapshot — updated only inside the subscribe callback
+  // Seed immediately from existing engine state — essential when restoring a
+  // persisted path (the engine is already started before usePath is called).
+  // We track whether we've seeded to avoid calling engine.snapshot() on every
+  // re-render (React evaluates useRef's argument each time).
+  const seededRef = useRef(false);
   const snapshotRef = useRef<PathSnapshot<TData> | null>(null);
+  if (!seededRef.current) {
+    seededRef.current = true;
+    try {
+      snapshotRef.current = engine.snapshot() as PathSnapshot<TData> | null;
+    } catch {
+      snapshotRef.current = null;
+    }
+  }
 
   const subscribe = useCallback(
     (callback: () => void) =>
@@ -120,7 +150,13 @@ export function usePath<TData extends PathData = PathData>(options?: UsePathOpti
     [engine]
   ) as UsePathReturn<TData>["setData"];
 
-  return { snapshot, start, startSubPath, next, previous, cancel, goToStep, goToStepChecked, setData };
+  const restart = useCallback(
+    (path: PathDefinition<any>, initialData: PathData = {}) =>
+      engine.restart(path, initialData),
+    [engine]
+  );
+
+  return { snapshot, start, startSubPath, next, previous, cancel, goToStep, goToStepChecked, setData, restart };
 }
 
 // ---------------------------------------------------------------------------
@@ -160,6 +196,12 @@ export function usePathContext<TData extends PathData = PathData>(): UsePathRetu
 export interface PathShellProps {
   /** The path definition to drive. */
   path: PathDefinition<any>;
+  /**
+   * An externally-managed engine — for example, the engine returned by
+   * `createPersistedEngine()`. When supplied, `PathShell` will skip its own
+   * `start()` call and drive the UI from the provided engine instead.
+   */
+  engine?: PathEngine;
   /** Map of step ID → content. The shell renders `steps[snapshot.stepId]` for the current step. */
   steps: Record<string, ReactNode>;
   /** Initial data passed to `engine.start()`. */
@@ -172,12 +214,12 @@ export interface PathShellProps {
   onCancel?: (data: PathData) => void;
   /** Called for every engine event. */
   onEvent?: (event: PathEvent) => void;
-  /** Label for the Back button. Defaults to `"Back"`. */
+  /** Label for the Previous button. Defaults to `"Previous"`. */
   backLabel?: string;
   /** Label for the Next button. Defaults to `"Next"`. */
   nextLabel?: string;
-  /** Label for the Finish button (shown on the last step). Defaults to `"Finish"`. */
-  finishLabel?: string;
+  /** Label for the Complete button (shown on the last step). Defaults to `"Complete"`. */
+  completeLabel?: string;
   /** Label for the Cancel button. Defaults to `"Cancel"`. */
   cancelLabel?: string;
   /** If true, hide the Cancel button. Defaults to `false`. */
@@ -199,6 +241,8 @@ export interface PathShellActions {
   goToStep: (stepId: string) => void;
   goToStepChecked: (stepId: string) => void;
   setData: (key: string, value: unknown) => void;
+  /** Restart the shell's current path with its current `initialData`. */
+  restart: () => void;
 }
 
 /**
@@ -219,15 +263,16 @@ export interface PathShellActions {
  */
 export function PathShell({
   path: pathDef,
+  engine: externalEngine,
   steps,
   initialData = {},
   autoStart = true,
   onComplete,
   onCancel,
   onEvent,
-  backLabel = "Back",
+  backLabel = "Previous",
   nextLabel = "Next",
-  finishLabel = "Finish",
+  completeLabel = "Complete",
   cancelLabel = "Cancel",
   hideCancel = false,
   hideProgress = false,
@@ -236,6 +281,7 @@ export function PathShell({
   renderFooter,
 }: PathShellProps): ReactElement {
   const pathReturn = usePath({
+    engine: externalEngine,
     onEvent(event) {
       onEvent?.(event);
       if (event.type === "completed") onComplete?.(event.data);
@@ -243,12 +289,13 @@ export function PathShell({
     }
   });
 
-  const { snapshot, start, next, previous, cancel, goToStep, goToStepChecked, setData } = pathReturn;
+  const { snapshot, start, next, previous, cancel, goToStep, goToStepChecked, setData, restart } = pathReturn;
 
-  // Auto-start on mount
+  // Auto-start on mount — skipped when an external engine is provided since
+  // the caller is responsible for starting it (e.g. via createPersistedEngine).
   const startedRef = useRef(false);
   useEffect(() => {
-    if (autoStart && !startedRef.current) {
+    if (autoStart && !startedRef.current && !externalEngine) {
       startedRef.current = true;
       start(pathDef, initialData);
     }
@@ -273,7 +320,10 @@ export function PathShell({
     );
   }
 
-  const actions: PathShellActions = { next, previous, cancel, goToStep, goToStepChecked, setData };
+  const actions: PathShellActions = {
+    next, previous, cancel, goToStep, goToStepChecked, setData,
+    restart: () => restart(pathDef, initialData)
+  };
 
   return createElement(PathContext.Provider, { value: pathReturn },
     createElement("div", { className: cls("pw-shell", className) },
@@ -293,7 +343,7 @@ export function PathShell({
       renderFooter
         ? renderFooter(snapshot, actions)
         : defaultFooter(snapshot, actions, {
-            backLabel, nextLabel, finishLabel, cancelLabel, hideCancel
+            backLabel, nextLabel, completeLabel, cancelLabel, hideCancel
           })
     )
   );
@@ -336,7 +386,7 @@ function defaultHeader(snapshot: PathSnapshot): ReactElement {
 interface FooterLabels {
   backLabel: string;
   nextLabel: string;
-  finishLabel: string;
+  completeLabel: string;
   cancelLabel: string;
   hideCancel: boolean;
 }
@@ -367,7 +417,7 @@ function defaultFooter(
         className: "pw-shell__btn pw-shell__btn--next",
         disabled: snapshot.isNavigating || !snapshot.canMoveNext,
         onClick: actions.next
-      }, snapshot.isLastStep ? labels.finishLabel : labels.nextLabel)
+      }, snapshot.isLastStep ? labels.completeLabel : labels.nextLabel)
     )
   );
 }
@@ -376,7 +426,23 @@ function defaultFooter(
 // Helpers
 // ---------------------------------------------------------------------------
 
-
 function cls(...parts: (string | undefined | false | null)[]): string {
   return parts.filter(Boolean).join(" ");
 }
+
+// ---------------------------------------------------------------------------
+// Re-export core types for convenience
+// ---------------------------------------------------------------------------
+
+export type {
+  PathData,
+  PathDefinition,
+  PathEvent,
+  PathSnapshot,
+  PathStep,
+  PathStepContext,
+  SerializedPathState
+} from "@daltonr/pathwrite-core";
+
+export { PathEngine } from "@daltonr/pathwrite-core";
+