@daltonr/pathwrite-svelte 0.8.0 → 0.10.0

package/README.md

@@ -168,7 +168,7 @@ Create the engine yourself with `restoreOrStart()` and pass it via `engine`. Pat
 
 ```svelte
 <script>
-  import { HttpStore, restoreOrStart, httpPersistence } from '@daltonr/pathwrite-store-http';
+  import { HttpStore, restoreOrStart, persistence } from '@daltonr/pathwrite-store';
 
   let engine = $state(null);
 
@@ -179,7 +179,7 @@ Create the engine yourself with `restoreOrStart()` and pass it via `engine`. Pat
       path: signupPath,
       initialData: { name: '' },
       observers: [
-        httpPersistence({ store, key: 'user:onboarding', strategy: 'onNext' })
+        persistence({ store, key: 'user:onboarding', strategy: 'onNext' })
       ]
     });
     engine = result.engine;
@@ -467,13 +467,13 @@ const myPath = {
 
 ## Persistence
 
-Use with [@daltonr/pathwrite-store-http](../store-http) for automatic state persistence:
+Use with [@daltonr/pathwrite-store](../store) for automatic state persistence:
 
 ```svelte
 <script lang="ts">
   import { onMount } from 'svelte';
   import { PathShell } from '@daltonr/pathwrite-svelte';
-  import { HttpStore, restoreOrStart, httpPersistence } from '@daltonr/pathwrite-store-http';
+  import { HttpStore, restoreOrStart, persistence } from '@daltonr/pathwrite-store';
   import DetailsForm from './DetailsForm.svelte';
   import ReviewPanel from './ReviewPanel.svelte';
   
@@ -490,7 +490,7 @@ Use with [@daltonr/pathwrite-store-http](../store-http) for automatic state pers
       path: signupPath,
       initialData: { name: '', email: '' },
       observers: [
-        httpPersistence({ store, key, strategy: 'onNext' })
+        persistence({ store, key, strategy: 'onNext' })
       ]
     });
     engine = result.engine;
@@ -537,7 +537,7 @@ MIT — © 2026 Devjoy Ltd.
 ## See Also
 
 - [@daltonr/pathwrite-core](../core) - Core engine
-- [@daltonr/pathwrite-store-http](../store-http) - HTTP persistence
+- [@daltonr/pathwrite-store](../store) - HTTP persistence
 - [Documentation](../../docs/guides/DEVELOPER_GUIDE.md)
 
 

package/dist/PathShell.svelte

@@ -1,13 +1,9 @@
 <script lang="ts">
   import { onMount } from 'svelte';
-  import { usePath, setPathContext } from './index.svelte.js';
+  import { usePath, setPathContext, formatFieldKey, errorPhaseMessage } from './index.svelte.js';
   import type { PathDefinition, PathData, PathEngine, PathSnapshot, ProgressLayout } from './index.svelte.js';
-  import type { Snippet } from 'svelte';
+  import type { Snippet, Component } from 'svelte';
 
-  /** Converts a camelCase or lowercase field key to a display label. */
-  function formatFieldKey(key: string): string {
-    return key.replace(/([A-Z])/g, ' $1').replace(/^./, c => c.toUpperCase()).trim();
-  }
 
   interface Props {
     path?: PathDefinition<any>;
@@ -17,6 +13,7 @@
     backLabel?: string;
     nextLabel?: string;
     completeLabel?: string;
+    loadingLabel?: string;
     cancelLabel?: string;
     hideCancel?: boolean;
     hideProgress?: boolean;
@@ -42,6 +39,11 @@
      * - "activeOnly": Only the active (sub-path) bar — root bar hidden.
      */
     progressLayout?: ProgressLayout;
+    /**
+     * Services object passed through context to all step components.
+     * Step components access it via `usePathContext<TData, TServices>()`.
+     */
+    services?: unknown;
     // Callback props replace event dispatching in Svelte 5
     oncomplete?: (data: PathData) => void;
     oncancel?: (data: PathData) => void;
@@ -49,8 +51,8 @@
     // Optional override snippets for header and footer
     header?: Snippet<[PathSnapshot<any>]>;
     footer?: Snippet<[PathSnapshot<any>, object]>;
-    // All other props treated as step snippets keyed by step ID
-    [key: string]: Snippet | any;
+    // All other props treated as step components keyed by step ID
+    [key: string]: Component<any> | any;
   }
 
   let {
@@ -61,12 +63,14 @@
     backLabel = 'Previous',
     nextLabel = 'Next',
     completeLabel = 'Complete',
+    loadingLabel = undefined,
     cancelLabel = 'Cancel',
     hideCancel = false,
     hideProgress = false,
     footerLayout = 'auto',
-    validationDisplay = 'inline',
+    validationDisplay = 'summary',
     progressLayout = 'merged',
+    services = null,
     oncomplete,
     oncancel,
     onevent,
@@ -77,7 +81,7 @@
 
   // Initialize path engine
   const pathReturn = usePath({
-    engine: engineProp,
+    get engine() { return engineProp; },
     onEvent: (event) => {
       onevent?.(event);
       if (event.type === 'completed') oncomplete?.(event.data);
@@ -85,7 +89,7 @@
     }
   });
 
-  const { start, next, previous, cancel, goToStep, goToStepChecked, setData, restart: restartFn } = pathReturn;
+  const { start, next, previous, cancel, goToStep, goToStepChecked, setData, restart: restartFn, retry, suspend } = pathReturn;
 
   // Provide context for child step components
   setPathContext({
@@ -96,7 +100,10 @@
     goToStep,
     goToStepChecked,
     setData,
-    restart: () => restartFn(path, initialData)
+    restart: () => restartFn(path, initialData),
+    retry,
+    suspend,
+    get services() { return services; },
   });
 
   // Auto-start the path when no external engine is provided
@@ -109,7 +116,7 @@
   });
 
   let snap = $derived(pathReturn.snapshot);
-  let actions = $derived({ next, previous, cancel, goToStep, goToStepChecked, setData, restart: () => restartFn(path, initialData) });
+  let actions = $derived({ next, previous, cancel, goToStep, goToStepChecked, setData, restart: () => restartFn(path, initialData), retry, suspend });
 
   // Auto-detect footer layout: single-step top-level paths use "form", everything else uses "wizard"
   let resolvedFooterLayout = $derived(
@@ -190,9 +197,11 @@
          register snippets by inner step ids directly. -->
     <div class="pw-shell__body">
       {#if snap.formId && stepSnippets[snap.formId]}
-        {@render stepSnippets[snap.formId]()}
+        {@const StepComponent = stepSnippets[snap.formId]}
+        <StepComponent />
       {:else if stepSnippets[snap.stepId]}
-        {@render stepSnippets[snap.stepId]()}
+        {@const StepComponent = stepSnippets[snap.stepId]}
+        <StepComponent />
       {:else}
         <p>No content for step "{snap.stepId}"</p>
       {/if}
@@ -220,8 +229,36 @@
       </ul>
     {/if}
 
+    <!-- Blocking error — guard returned { allowed: false, reason } -->
+    {#if validationDisplay !== 'inline' && snap.hasAttemptedNext && snap.blockingError}
+      <p class="pw-shell__blocking-error">{snap.blockingError}</p>
+    {/if}
+
+    <!-- Error panel: replaces footer when an async operation has failed -->
+    {#if snap.status === "error" && snap.error}
+      {@const err = snap.error}
+      {@const escalated = err.retryCount >= 2}
+      <div class="pw-shell__error">
+        <div class="pw-shell__error-title">{escalated ? "Still having trouble." : "Something went wrong."}</div>
+        <div class="pw-shell__error-message">{errorPhaseMessage(err.phase)}{err.message ? ` ${err.message}` : ""}</div>
+        <div class="pw-shell__error-actions">
+          {#if !escalated}
+            <button type="button" class="pw-shell__btn pw-shell__btn--retry" onclick={retry}>Try again</button>
+          {/if}
+          {#if snap.hasPersistence}
+            <button
+              type="button"
+              class="pw-shell__btn {escalated ? 'pw-shell__btn--retry' : 'pw-shell__btn--suspend'}"
+              onclick={suspend}
+            >Save and come back later</button>
+          {/if}
+          {#if escalated && !snap.hasPersistence}
+            <button type="button" class="pw-shell__btn pw-shell__btn--retry" onclick={retry}>Try again</button>
+          {/if}
+        </div>
+      </div>
     <!-- Footer: navigation buttons (overridable via footer snippet) -->
-    {#if footer}
+    {:else if footer}
       {@render footer(snap, actions)}
     {:else}
       <div class="pw-shell__footer">
@@ -231,7 +268,7 @@
             <button
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
-              disabled={snap.isNavigating}
+              disabled={snap.status !== "idle"}
               onclick={cancel}
             >
               {cancelLabel}
@@ -241,7 +278,7 @@
             <button
               type="button"
               class="pw-shell__btn pw-shell__btn--back"
-              disabled={snap.isNavigating || !snap.canMovePrevious}
+              disabled={snap.status !== "idle" || !snap.canMovePrevious}
               onclick={previous}
             >
               {backLabel}
@@ -254,7 +291,7 @@
             <button
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
-              disabled={snap.isNavigating}
+              disabled={snap.status !== "idle"}
               onclick={cancel}
             >
               {cancelLabel}
@@ -264,10 +301,11 @@
           <button
             type="button"
             class="pw-shell__btn pw-shell__btn--next"
-            disabled={snap.isNavigating}
+            class:pw-shell__btn--loading={snap.status !== "idle"}
+            disabled={snap.status !== "idle"}
             onclick={next}
           >
-            {snap.isLastStep ? completeLabel : nextLabel}
+            {snap.status !== 'idle' && loadingLabel ? loadingLabel : snap.isLastStep ? completeLabel : nextLabel}
           </button>
         </div>
       </div>

package/dist/PathShell.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { PathDefinition, PathData, PathEngine, PathSnapshot, ProgressLayout } from './index.svelte.js';
-import type { Snippet } from 'svelte';
+import type { Snippet, Component } from 'svelte';
 interface Props {
     path?: PathDefinition<any>;
     engine?: PathEngine;
@@ -8,6 +8,7 @@ interface Props {
     backLabel?: string;
     nextLabel?: string;
     completeLabel?: string;
+    loadingLabel?: string;
     cancelLabel?: string;
     hideCancel?: boolean;
     hideProgress?: boolean;
@@ -33,14 +34,19 @@ interface Props {
      * - "activeOnly": Only the active (sub-path) bar — root bar hidden.
      */
     progressLayout?: ProgressLayout;
+    /**
+     * Services object passed through context to all step components.
+     * Step components access it via `usePathContext<TData, TServices>()`.
+     */
+    services?: unknown;
     oncomplete?: (data: PathData) => void;
     oncancel?: (data: PathData) => void;
     onevent?: (event: any) => void;
     header?: Snippet<[PathSnapshot<any>]>;
     footer?: Snippet<[PathSnapshot<any>, object]>;
-    [key: string]: Snippet | any;
+    [key: string]: Component<any> | any;
 }
-declare const PathShell: import("svelte").Component<Props, {
+declare const PathShell: Component<Props, {
     restart: () => Promise<void>;
 }, "">;
 type PathShell = ReturnType<typeof PathShell>;

package/dist/PathShell.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PathShell.svelte.d.ts","sourceRoot":"","sources":["../src/PathShell.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC5G,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAGpC,UAAU,KAAK;IACb,IAAI,CAAC,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IAC1C;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClD;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACpC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;IAE/B,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAE9C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,GAAG,CAAC;CAC9B;AAyNH,QAAA,MAAM,SAAS;mBAlIQ,QAAQ,IAAI,CAAC;MAkImB,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}
+{"version":3,"file":"PathShell.svelte.d.ts","sourceRoot":"","sources":["../src/PathShell.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC5G,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAI/C,UAAU,KAAK;IACb,IAAI,CAAC,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IAC1C;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClD;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACpC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;IAE/B,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAE9C,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;CACrC;AAmPH,QAAA,MAAM,SAAS;mBA5JQ,QAAQ,IAAI,CAAC;MA4JmB,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}

package/dist/index.css

@@ -285,6 +285,16 @@
   content: ":";
 }
 
+/* ------------------------------------------------------------------ */
+/* Blocking error (guard-level message, not field-attached)           */
+/* ------------------------------------------------------------------ */
+.pw-shell__blocking-error {
+  margin: 0;
+  padding: 8px 16px;
+  font-size: 13px;
+  color: var(--pw-color-error);
+}
+
 /* ------------------------------------------------------------------ */
 /* Warning messages                                                    */
 /* ------------------------------------------------------------------ */
@@ -361,6 +371,7 @@
   background: var(--pw-color-primary);
   border-color: var(--pw-color-primary);
   color: #fff;
+  position: relative;
 }
 
 .pw-shell__btn--next:hover:not(:disabled) {
@@ -368,6 +379,29 @@
   border-color: #1d4ed8;
 }
 
+@keyframes pw-spin {
+  to { transform: rotate(360deg); }
+}
+
+.pw-shell__btn--next.pw-shell__btn--loading {
+  color: transparent;
+  pointer-events: none;
+}
+
+.pw-shell__btn--next.pw-shell__btn--loading::after {
+  content: "";
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 14px;
+  height: 14px;
+  margin: -7px 0 0 -7px;
+  border: 2px solid rgba(255, 255, 255, 0.35);
+  border-top-color: #fff;
+  border-radius: 50%;
+  animation: pw-spin 0.6s linear infinite;
+}
+
 .pw-shell__btn--back {
   background: transparent;
   border-color: var(--pw-color-primary);
@@ -388,3 +422,55 @@
   background: var(--pw-color-primary-light);
 }
 
+/* ------------------------------------------------------------------ */
+/* Error panel — replaces footer when status === "error"              */
+/* ------------------------------------------------------------------ */
+.pw-shell__error {
+  background: var(--pw-color-error-bg);
+  border: 1px solid var(--pw-color-error-border);
+  border-radius: var(--pw-shell-radius);
+  padding: 16px 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.pw-shell__error-title {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--pw-color-error);
+}
+
+.pw-shell__error-message {
+  font-size: 13px;
+  color: var(--pw-color-muted);
+}
+
+.pw-shell__error-actions {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  margin-top: 2px;
+}
+
+.pw-shell__btn--retry {
+  background: var(--pw-color-error);
+  border-color: var(--pw-color-error);
+  color: #fff;
+}
+
+.pw-shell__btn--retry:hover:not(:disabled) {
+  opacity: 0.9;
+}
+
+.pw-shell__btn--suspend {
+  color: var(--pw-color-muted);
+  border-color: transparent;
+  background: transparent;
+  font-size: 13px;
+}
+
+.pw-shell__btn--suspend:hover:not(:disabled) {
+  background: var(--pw-color-primary-light);
+}
+

package/dist/index.svelte.d.ts

@@ -1,9 +1,10 @@
 import type { PathData, PathDefinition, PathEngine, PathEvent, PathSnapshot } from "@daltonr/pathwrite-core";
+export { formatFieldKey, errorPhaseMessage } from "@daltonr/pathwrite-core";
 export type { PathData, FieldErrors, PathDefinition, PathEngine, PathEvent, PathSnapshot, PathStep, PathStepContext, ProgressLayout, RootProgress, SerializedPathState } from "@daltonr/pathwrite-core";
 export interface UsePathOptions {
     /**
      * An externally-managed `PathEngine` to subscribe to — for example, the engine
-     * returned by `restoreOrStart()` from `@daltonr/pathwrite-store-http`.
+     * returned by `restoreOrStart()` from `@daltonr/pathwrite-store`.
      *
      * When provided:
      * - `usePath` will **not** create its own engine.
@@ -16,7 +17,12 @@ export interface UsePathOptions {
     onEvent?: (event: PathEvent) => void;
 }
 export interface UsePathReturn<TData extends PathData = PathData> {
-    /** Current path snapshot, or `null` when no path is active. Reactive via `$state`. */
+    /**
+     * Current path snapshot, or `null` when no path is active. Reactive via `$state`.
+     *
+     * ⚠️ **Do not destructure.** `const { snapshot } = usePath()` captures the value
+     * once and loses reactivity. Always access as `path.snapshot`.
+     */
     readonly snapshot: PathSnapshot<TData> | null;
     /** Start (or restart) a path. */
     start: (path: PathDefinition<any>, initialData?: PathData) => Promise<void>;
@@ -41,15 +47,46 @@ export interface UsePathReturn<TData extends PathData = PathData> {
      * 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) => Promise<void>;
+    restart: () => Promise<void>;
+    /** Re-runs the operation that set `snapshot.error`. Increments `retryCount` on repeated failure. No-op when there is no pending error. */
+    retry: () => Promise<void>;
+    /** Pauses the path with intent to return. Emits `suspended`. All state is preserved. */
+    suspend: () => Promise<void>;
 }
 /**
  * Create a Pathwrite engine with Svelte 5 runes-based reactivity.
  * Call this from inside a Svelte component to get a reactive snapshot.
  * Cleanup is automatic via onDestroy.
  *
- * **Note:** `snapshot` is a reactive getter — access it via the returned
- * object (e.g. `path.snapshot`). Destructuring `snapshot` will lose reactivity.
+ * ---
+ *
+ * ⚠️ **Do not destructure `snapshot`.**
+ *
+ * `snapshot` is a reactive getter. Destructuring it copies the value once
+ * and severs the reactive connection — your component will stop updating.
+ *
+ * ```svelte
+ * // ❌ Broken — snapshot is captured once and never updates
+ * const { snapshot, next } = usePath();
+ *
+ * // ✅ Correct — snapshot is read through the live object on every render
+ * const path = usePath();
+ * // use path.snapshot in your template
+ * ```
+ *
+ * Other properties (`next`, `previous`, `setData`, etc.) are plain functions
+ * and are safe to destructure.
+ *
+ * If you need a local variable that stays reactive, use `$derived`:
+ * ```svelte
+ * const path = usePath();
+ * const snapshot = $derived(path.snapshot);
+ * ```
+ *
+ * This is expected Svelte 5 behaviour — see the
+ * [Svelte $state docs](https://svelte.dev/docs/svelte/$state) for details.
+ *
+ * ---
  *
  * @example
  * ```svelte
@@ -71,8 +108,8 @@ export interface UsePathReturn<TData extends PathData = PathData> {
  * ```
  */
 export declare function usePath<TData extends PathData = PathData>(options?: UsePathOptions): UsePathReturn<TData>;
-export interface PathContext<TData extends PathData = PathData> {
-    readonly snapshot: PathSnapshot<TData> | null;
+export interface PathContext<TData extends PathData = PathData, TServices = unknown> {
+    readonly snapshot: PathSnapshot<TData>;
     next: () => Promise<void>;
     previous: () => Promise<void>;
     cancel: () => Promise<void>;
@@ -81,17 +118,29 @@ export interface PathContext<TData extends PathData = PathData> {
     setData: <K extends string & keyof TData>(key: K, value: TData[K]) => Promise<void>;
     resetStep: () => Promise<void>;
     restart: () => Promise<void>;
+    /** Re-run the operation that set `snapshot.error`. */
+    retry: () => Promise<void>;
+    /** Pause with intent to return, preserving all state. Emits `suspended`. */
+    suspend: () => Promise<void>;
+    /**
+     * Services object passed through context from `PathShell`.
+     * Typed as `TServices` when `usePathContext<TData, TServices>()` is used.
+     */
+    services: TServices;
 }
 /**
- * Get the PathContext from a parent PathShell component.
+ * Access the nearest `PathShell`'s path instance and optional services object.
  * Use this inside step components to access the path engine.
  *
+ * - `TData` narrows `ctx.snapshot?.data`
+ * - `TServices` types the `services` value — must match what was passed to `PathShell`
+ *
  * @example
  * ```svelte
  * <script lang="ts">
- *   import { getPathContext } from '@daltonr/pathwrite-svelte';
+ *   import { usePathContext } from '@daltonr/pathwrite-svelte';
  *
- *   const ctx = getPathContext();
+ *   const ctx = usePathContext();
  * </script>
  *
  * <input value={ctx.snapshot?.data.name}
@@ -99,12 +148,12 @@ export interface PathContext<TData extends PathData = PathData> {
  * <button onclick={ctx.next}>Next</button>
  * ```
  */
-export declare function getPathContext<TData extends PathData = PathData>(): PathContext<TData>;
+export declare function usePathContext<TData extends PathData = PathData, TServices = unknown>(): PathContext<TData, TServices>;
 /**
  * Internal: Set the PathContext for child components.
  * Used by PathShell component.
  */
-export declare function setPathContext<TData extends PathData = PathData>(ctx: PathContext<TData>): void;
+export declare function setPathContext<TData extends PathData = PathData, TServices = unknown>(ctx: PathContext<TData, TServices>): void;
 /**
  * Create a two-way binding helper for form inputs.
  * Returns an object with a reactive `value` property.

package/dist/index.svelte.d.ts.map

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

package/dist/index.svelte.js

@@ -1,5 +1,7 @@
 import { onDestroy, getContext, setContext } from "svelte";
 import { PathEngine as PathEngineClass } from "@daltonr/pathwrite-core";
+// Re-export core utilities and types for convenience
+export { formatFieldKey, errorPhaseMessage } from "@daltonr/pathwrite-core";
 // ---------------------------------------------------------------------------
 // usePath - Runes-based API for Svelte 5
 // ---------------------------------------------------------------------------
@@ -8,8 +10,35 @@ import { PathEngine as PathEngineClass } from "@daltonr/pathwrite-core";
  * Call this from inside a Svelte component to get a reactive snapshot.
  * Cleanup is automatic via onDestroy.
  *
- * **Note:** `snapshot` is a reactive getter — access it via the returned
- * object (e.g. `path.snapshot`). Destructuring `snapshot` will lose reactivity.
+ * ---
+ *
+ * ⚠️ **Do not destructure `snapshot`.**
+ *
+ * `snapshot` is a reactive getter. Destructuring it copies the value once
+ * and severs the reactive connection — your component will stop updating.
+ *
+ * ```svelte
+ * // ❌ Broken — snapshot is captured once and never updates
+ * const { snapshot, next } = usePath();
+ *
+ * // ✅ Correct — snapshot is read through the live object on every render
+ * const path = usePath();
+ * // use path.snapshot in your template
+ * ```
+ *
+ * Other properties (`next`, `previous`, `setData`, etc.) are plain functions
+ * and are safe to destructure.
+ *
+ * If you need a local variable that stays reactive, use `$derived`:
+ * ```svelte
+ * const path = usePath();
+ * const snapshot = $derived(path.snapshot);
+ * ```
+ *
+ * This is expected Svelte 5 behaviour — see the
+ * [Svelte $state docs](https://svelte.dev/docs/svelte/$state) for details.
+ *
+ * ---
  *
  * @example
  * ```svelte
@@ -55,7 +84,9 @@ export function usePath(options) {
     const goToStepChecked = (stepId) => engine.goToStepChecked(stepId);
     const setData = ((key, value) => engine.setData(key, value));
     const resetStep = () => engine.resetStep();
-    const restart = (path, initialData = {}) => engine.restart(path, initialData);
+    const restart = () => engine.restart();
+    const retry = () => engine.retry();
+    const suspend = () => engine.suspend();
     return {
         get snapshot() { return _snapshot; },
         start,
@@ -67,7 +98,9 @@ export function usePath(options) {
         goToStepChecked,
         setData,
         resetStep,
-        restart
+        restart,
+        retry,
+        suspend
     };
 }
 // ---------------------------------------------------------------------------
@@ -75,15 +108,18 @@ export function usePath(options) {
 // ---------------------------------------------------------------------------
 const PATH_CONTEXT_KEY = Symbol("pathwrite-context");
 /**
- * Get the PathContext from a parent PathShell component.
+ * Access the nearest `PathShell`'s path instance and optional services object.
  * Use this inside step components to access the path engine.
  *
+ * - `TData` narrows `ctx.snapshot?.data`
+ * - `TServices` types the `services` value — must match what was passed to `PathShell`
+ *
  * @example
  * ```svelte
  * <script lang="ts">
- *   import { getPathContext } from '@daltonr/pathwrite-svelte';
+ *   import { usePathContext } from '@daltonr/pathwrite-svelte';
  *
- *   const ctx = getPathContext();
+ *   const ctx = usePathContext();
  * </script>
  *
  * <input value={ctx.snapshot?.data.name}
@@ -91,10 +127,10 @@ const PATH_CONTEXT_KEY = Symbol("pathwrite-context");
  * <button onclick={ctx.next}>Next</button>
  * ```
  */
-export function getPathContext() {
+export function usePathContext() {
     const ctx = getContext(PATH_CONTEXT_KEY);
     if (!ctx) {
-        throw new Error("getPathContext() must be called from a component inside a <PathShell>. " +
+        throw new Error("usePathContext() must be called from a component inside a <PathShell>. " +
             "Ensure the PathShell component is a parent in the component tree.");
     }
     return ctx;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daltonr/pathwrite-svelte",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "license": "MIT",
   "description": "Svelte 5 adapter for @daltonr/pathwrite-core — runes-based reactive bindings and optional PathShell component.",
@@ -52,7 +52,7 @@
     "svelte": ">=5.0.0"
   },
   "dependencies": {
-    "@daltonr/pathwrite-core": "^0.8.0"
+    "@daltonr/pathwrite-core": "^0.10.0"
   },
   "devDependencies": {
     "@sveltejs/package": "^2.5.7",

package/src/PathShell.svelte

@@ -1,13 +1,9 @@
 <script lang="ts">
   import { onMount } from 'svelte';
-  import { usePath, setPathContext } from './index.svelte.js';
+  import { usePath, setPathContext, formatFieldKey, errorPhaseMessage } from './index.svelte.js';
   import type { PathDefinition, PathData, PathEngine, PathSnapshot, ProgressLayout } from './index.svelte.js';
-  import type { Snippet } from 'svelte';
+  import type { Snippet, Component } from 'svelte';
 
-  /** Converts a camelCase or lowercase field key to a display label. */
-  function formatFieldKey(key: string): string {
-    return key.replace(/([A-Z])/g, ' $1').replace(/^./, c => c.toUpperCase()).trim();
-  }
 
   interface Props {
     path?: PathDefinition<any>;
@@ -17,6 +13,7 @@
     backLabel?: string;
     nextLabel?: string;
     completeLabel?: string;
+    loadingLabel?: string;
     cancelLabel?: string;
     hideCancel?: boolean;
     hideProgress?: boolean;
@@ -42,6 +39,11 @@
      * - "activeOnly": Only the active (sub-path) bar — root bar hidden.
      */
     progressLayout?: ProgressLayout;
+    /**
+     * Services object passed through context to all step components.
+     * Step components access it via `usePathContext<TData, TServices>()`.
+     */
+    services?: unknown;
     // Callback props replace event dispatching in Svelte 5
     oncomplete?: (data: PathData) => void;
     oncancel?: (data: PathData) => void;
@@ -49,8 +51,8 @@
     // Optional override snippets for header and footer
     header?: Snippet<[PathSnapshot<any>]>;
     footer?: Snippet<[PathSnapshot<any>, object]>;
-    // All other props treated as step snippets keyed by step ID
-    [key: string]: Snippet | any;
+    // All other props treated as step components keyed by step ID
+    [key: string]: Component<any> | any;
   }
 
   let {
@@ -61,12 +63,14 @@
     backLabel = 'Previous',
     nextLabel = 'Next',
     completeLabel = 'Complete',
+    loadingLabel = undefined,
     cancelLabel = 'Cancel',
     hideCancel = false,
     hideProgress = false,
     footerLayout = 'auto',
-    validationDisplay = 'inline',
+    validationDisplay = 'summary',
     progressLayout = 'merged',
+    services = null,
     oncomplete,
     oncancel,
     onevent,
@@ -77,7 +81,7 @@
 
   // Initialize path engine
   const pathReturn = usePath({
-    engine: engineProp,
+    get engine() { return engineProp; },
     onEvent: (event) => {
       onevent?.(event);
       if (event.type === 'completed') oncomplete?.(event.data);
@@ -85,7 +89,7 @@
     }
   });
 
-  const { start, next, previous, cancel, goToStep, goToStepChecked, setData, restart: restartFn } = pathReturn;
+  const { start, next, previous, cancel, goToStep, goToStepChecked, setData, restart: restartFn, retry, suspend } = pathReturn;
 
   // Provide context for child step components
   setPathContext({
@@ -96,7 +100,10 @@
     goToStep,
     goToStepChecked,
     setData,
-    restart: () => restartFn(path, initialData)
+    restart: () => restartFn(path, initialData),
+    retry,
+    suspend,
+    get services() { return services; },
   });
 
   // Auto-start the path when no external engine is provided
@@ -109,7 +116,7 @@
   });
 
   let snap = $derived(pathReturn.snapshot);
-  let actions = $derived({ next, previous, cancel, goToStep, goToStepChecked, setData, restart: () => restartFn(path, initialData) });
+  let actions = $derived({ next, previous, cancel, goToStep, goToStepChecked, setData, restart: () => restartFn(path, initialData), retry, suspend });
 
   // Auto-detect footer layout: single-step top-level paths use "form", everything else uses "wizard"
   let resolvedFooterLayout = $derived(
@@ -190,9 +197,11 @@
          register snippets by inner step ids directly. -->
     <div class="pw-shell__body">
       {#if snap.formId && stepSnippets[snap.formId]}
-        {@render stepSnippets[snap.formId]()}
+        {@const StepComponent = stepSnippets[snap.formId]}
+        <StepComponent />
       {:else if stepSnippets[snap.stepId]}
-        {@render stepSnippets[snap.stepId]()}
+        {@const StepComponent = stepSnippets[snap.stepId]}
+        <StepComponent />
       {:else}
         <p>No content for step "{snap.stepId}"</p>
       {/if}
@@ -220,8 +229,36 @@
       </ul>
     {/if}
 
+    <!-- Blocking error — guard returned { allowed: false, reason } -->
+    {#if validationDisplay !== 'inline' && snap.hasAttemptedNext && snap.blockingError}
+      <p class="pw-shell__blocking-error">{snap.blockingError}</p>
+    {/if}
+
+    <!-- Error panel: replaces footer when an async operation has failed -->
+    {#if snap.status === "error" && snap.error}
+      {@const err = snap.error}
+      {@const escalated = err.retryCount >= 2}
+      <div class="pw-shell__error">
+        <div class="pw-shell__error-title">{escalated ? "Still having trouble." : "Something went wrong."}</div>
+        <div class="pw-shell__error-message">{errorPhaseMessage(err.phase)}{err.message ? ` ${err.message}` : ""}</div>
+        <div class="pw-shell__error-actions">
+          {#if !escalated}
+            <button type="button" class="pw-shell__btn pw-shell__btn--retry" onclick={retry}>Try again</button>
+          {/if}
+          {#if snap.hasPersistence}
+            <button
+              type="button"
+              class="pw-shell__btn {escalated ? 'pw-shell__btn--retry' : 'pw-shell__btn--suspend'}"
+              onclick={suspend}
+            >Save and come back later</button>
+          {/if}
+          {#if escalated && !snap.hasPersistence}
+            <button type="button" class="pw-shell__btn pw-shell__btn--retry" onclick={retry}>Try again</button>
+          {/if}
+        </div>
+      </div>
     <!-- Footer: navigation buttons (overridable via footer snippet) -->
-    {#if footer}
+    {:else if footer}
       {@render footer(snap, actions)}
     {:else}
       <div class="pw-shell__footer">
@@ -231,7 +268,7 @@
             <button
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
-              disabled={snap.isNavigating}
+              disabled={snap.status !== "idle"}
               onclick={cancel}
             >
               {cancelLabel}
@@ -241,7 +278,7 @@
             <button
               type="button"
               class="pw-shell__btn pw-shell__btn--back"
-              disabled={snap.isNavigating || !snap.canMovePrevious}
+              disabled={snap.status !== "idle" || !snap.canMovePrevious}
               onclick={previous}
             >
               {backLabel}
@@ -254,7 +291,7 @@
             <button
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
-              disabled={snap.isNavigating}
+              disabled={snap.status !== "idle"}
               onclick={cancel}
             >
               {cancelLabel}
@@ -264,10 +301,11 @@
           <button
             type="button"
             class="pw-shell__btn pw-shell__btn--next"
-            disabled={snap.isNavigating}
+            class:pw-shell__btn--loading={snap.status !== "idle"}
+            disabled={snap.status !== "idle"}
             onclick={next}
           >
-            {snap.isLastStep ? completeLabel : nextLabel}
+            {snap.status !== 'idle' && loadingLabel ? loadingLabel : snap.isLastStep ? completeLabel : nextLabel}
           </button>
         </div>
       </div>

package/src/index.svelte.ts

@@ -8,7 +8,8 @@ import type {
 } from "@daltonr/pathwrite-core";
 import { PathEngine as PathEngineClass } from "@daltonr/pathwrite-core";
 
-// Re-export core types for convenience
+// Re-export core utilities and types for convenience
+export { formatFieldKey, errorPhaseMessage } from "@daltonr/pathwrite-core";
 export type {
   PathData,
   FieldErrors,
@@ -30,7 +31,7 @@ export type {
 export interface UsePathOptions {
   /**
    * An externally-managed `PathEngine` to subscribe to — for example, the engine
-   * returned by `restoreOrStart()` from `@daltonr/pathwrite-store-http`.
+   * returned by `restoreOrStart()` from `@daltonr/pathwrite-store`.
    *
    * When provided:
    * - `usePath` will **not** create its own engine.
@@ -44,7 +45,12 @@ export interface UsePathOptions {
 }
 
 export interface UsePathReturn<TData extends PathData = PathData> {
-  /** Current path snapshot, or `null` when no path is active. Reactive via `$state`. */
+  /**
+   * Current path snapshot, or `null` when no path is active. Reactive via `$state`.
+   *
+   * ⚠️ **Do not destructure.** `const { snapshot } = usePath()` captures the value
+   * once and loses reactivity. Always access as `path.snapshot`.
+   */
   readonly snapshot: PathSnapshot<TData> | null;
   /** Start (or restart) a path. */
   start: (path: PathDefinition<any>, initialData?: PathData) => Promise<void>;
@@ -69,7 +75,11 @@ export interface UsePathReturn<TData extends PathData = PathData> {
    * 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) => Promise<void>;
+  restart: () => Promise<void>;
+  /** Re-runs the operation that set `snapshot.error`. Increments `retryCount` on repeated failure. No-op when there is no pending error. */
+  retry: () => Promise<void>;
+  /** Pauses the path with intent to return. Emits `suspended`. All state is preserved. */
+  suspend: () => Promise<void>;
 }
 
 // ---------------------------------------------------------------------------
@@ -81,8 +91,35 @@ export interface UsePathReturn<TData extends PathData = PathData> {
  * Call this from inside a Svelte component to get a reactive snapshot.
  * Cleanup is automatic via onDestroy.
  *
- * **Note:** `snapshot` is a reactive getter — access it via the returned
- * object (e.g. `path.snapshot`). Destructuring `snapshot` will lose reactivity.
+ * ---
+ *
+ * ⚠️ **Do not destructure `snapshot`.**
+ *
+ * `snapshot` is a reactive getter. Destructuring it copies the value once
+ * and severs the reactive connection — your component will stop updating.
+ *
+ * ```svelte
+ * // ❌ Broken — snapshot is captured once and never updates
+ * const { snapshot, next } = usePath();
+ *
+ * // ✅ Correct — snapshot is read through the live object on every render
+ * const path = usePath();
+ * // use path.snapshot in your template
+ * ```
+ *
+ * Other properties (`next`, `previous`, `setData`, etc.) are plain functions
+ * and are safe to destructure.
+ *
+ * If you need a local variable that stays reactive, use `$derived`:
+ * ```svelte
+ * const path = usePath();
+ * const snapshot = $derived(path.snapshot);
+ * ```
+ *
+ * This is expected Svelte 5 behaviour — see the
+ * [Svelte $state docs](https://svelte.dev/docs/svelte/$state) for details.
+ *
+ * ---
  *
  * @example
  * ```svelte
@@ -147,8 +184,9 @@ export function usePath<TData extends PathData = PathData>(
 
   const resetStep = (): Promise<void> => engine.resetStep();
 
-  const restart = (path: PathDefinition<any>, initialData: PathData = {}): Promise<void> =>
-    engine.restart(path, initialData);
+  const restart = (): Promise<void> => engine.restart();
+  const retry = (): Promise<void> => engine.retry();
+  const suspend = (): Promise<void> => engine.suspend();
 
   return {
     get snapshot() { return _snapshot; },
@@ -161,7 +199,9 @@ export function usePath<TData extends PathData = PathData>(
     goToStepChecked,
     setData,
     resetStep,
-    restart
+    restart,
+    retry,
+    suspend
   };
 }
 
@@ -171,8 +211,8 @@ export function usePath<TData extends PathData = PathData>(
 
 const PATH_CONTEXT_KEY = Symbol("pathwrite-context");
 
-export interface PathContext<TData extends PathData = PathData> {
-  readonly snapshot: PathSnapshot<TData> | null;
+export interface PathContext<TData extends PathData = PathData, TServices = unknown> {
+  readonly snapshot: PathSnapshot<TData>;
   next: () => Promise<void>;
   previous: () => Promise<void>;
   cancel: () => Promise<void>;
@@ -181,18 +221,30 @@ export interface PathContext<TData extends PathData = PathData> {
   setData: <K extends string & keyof TData>(key: K, value: TData[K]) => Promise<void>;
   resetStep: () => Promise<void>;
   restart: () => Promise<void>;
+  /** Re-run the operation that set `snapshot.error`. */
+  retry: () => Promise<void>;
+  /** Pause with intent to return, preserving all state. Emits `suspended`. */
+  suspend: () => Promise<void>;
+  /**
+   * Services object passed through context from `PathShell`.
+   * Typed as `TServices` when `usePathContext<TData, TServices>()` is used.
+   */
+  services: TServices;
 }
 
 /**
- * Get the PathContext from a parent PathShell component.
+ * Access the nearest `PathShell`'s path instance and optional services object.
  * Use this inside step components to access the path engine.
  *
+ * - `TData` narrows `ctx.snapshot?.data`
+ * - `TServices` types the `services` value — must match what was passed to `PathShell`
+ *
  * @example
  * ```svelte
  * <script lang="ts">
- *   import { getPathContext } from '@daltonr/pathwrite-svelte';
+ *   import { usePathContext } from '@daltonr/pathwrite-svelte';
  *
- *   const ctx = getPathContext();
+ *   const ctx = usePathContext();
  * </script>
  *
  * <input value={ctx.snapshot?.data.name}
@@ -200,11 +252,11 @@ export interface PathContext<TData extends PathData = PathData> {
  * <button onclick={ctx.next}>Next</button>
  * ```
  */
-export function getPathContext<TData extends PathData = PathData>(): PathContext<TData> {
-  const ctx = getContext<PathContext<TData>>(PATH_CONTEXT_KEY);
+export function usePathContext<TData extends PathData = PathData, TServices = unknown>(): PathContext<TData, TServices> {
+  const ctx = getContext<PathContext<TData, TServices>>(PATH_CONTEXT_KEY);
   if (!ctx) {
     throw new Error(
-      "getPathContext() must be called from a component inside a <PathShell>. " +
+      "usePathContext() must be called from a component inside a <PathShell>. " +
         "Ensure the PathShell component is a parent in the component tree."
     );
   }
@@ -215,7 +267,7 @@ export function getPathContext<TData extends PathData = PathData>(): PathContext
  * Internal: Set the PathContext for child components.
  * Used by PathShell component.
  */
-export function setPathContext<TData extends PathData = PathData>(ctx: PathContext<TData>): void {
+export function setPathContext<TData extends PathData = PathData, TServices = unknown>(ctx: PathContext<TData, TServices>): void {
   setContext(PATH_CONTEXT_KEY, ctx);
 }