@daltonr/pathwrite-svelte 0.7.0 → 0.9.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

@@ -2,7 +2,7 @@
   import { onMount } from 'svelte';
   import { usePath, setPathContext } 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 {
@@ -49,8 +49,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 {
@@ -65,7 +65,7 @@
     hideCancel = false,
     hideProgress = false,
     footerLayout = 'auto',
-    validationDisplay = 'inline',
+    validationDisplay = 'summary',
     progressLayout = 'merged',
     oncomplete,
     oncancel,
@@ -185,19 +185,23 @@
       {/if}
     {/if}
 
-    <!-- Body: current step rendered via named snippet -->
+    <!-- Body: current step rendered via named snippet.
+         Prefer formId (inner step id of a StepChoice) so consumers can
+         register snippets by inner step ids directly. -->
     <div class="pw-shell__body">
-      {#if stepSnippets[snap.stepId]}
-        {@render stepSnippets[snap.stepId]()}
+      {#if snap.formId && stepSnippets[snap.formId]}
+        <svelte:component this={stepSnippets[snap.formId]} />
+      {:else if stepSnippets[snap.stepId]}
+        <svelte:component this={stepSnippets[snap.stepId]} />
       {:else}
         <p>No content for step "{snap.stepId}"</p>
       {/if}
     </div>
 
     <!-- Validation messages — suppressed when validationDisplay="inline" -->
-    {#if validationDisplay !== 'inline' && snap.hasAttemptedNext && Object.keys(snap.fieldMessages).length > 0}
+    {#if validationDisplay !== 'inline' && snap.hasAttemptedNext && Object.keys(snap.fieldErrors).length > 0}
       <ul class="pw-shell__validation">
-        {#each Object.entries(snap.fieldMessages) as [key, msg]}
+        {#each Object.entries(snap.fieldErrors) as [key, msg]}
           <li class="pw-shell__validation-item">
             {#if key !== '_'}<span class="pw-shell__validation-label">{formatFieldKey(key)}</span>{/if}{msg}
           </li>
@@ -205,6 +209,17 @@
       </ul>
     {/if}
 
+    <!-- Warning messages — non-blocking, shown immediately (no hasAttemptedNext gate) -->
+    {#if validationDisplay !== 'inline' && Object.keys(snap.fieldWarnings).length > 0}
+      <ul class="pw-shell__warnings">
+        {#each Object.entries(snap.fieldWarnings) as [key, msg]}
+          <li class="pw-shell__warnings-item">
+            {#if key !== '_'}<span class="pw-shell__warnings-label">{formatFieldKey(key)}</span>{/if}{msg}
+          </li>
+        {/each}
+      </ul>
+    {/if}
+
     <!-- Footer: navigation buttons (overridable via footer snippet) -->
     {#if footer}
       {@render footer(snap, actions)}

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;
@@ -38,9 +38,9 @@ interface Props {
     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;AA4MH,QAAA,MAAM,SAAS;mBArHQ,QAAQ,IAAI,CAAC;MAqHmB,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;AAG/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,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,SAAS,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;CACrC;AAyNH,QAAA,MAAM,SAAS;mBAlIQ,QAAQ,IAAI,CAAC;MAkImB,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}

package/dist/index.css

@@ -246,6 +246,9 @@
   --pw-color-error: #dc2626;
   --pw-color-error-bg: #fef2f2;
   --pw-color-error-border: #fecaca;
+  --pw-color-warning: #d97706;
+  --pw-color-warning-bg: #fffbeb;
+  --pw-color-warning-border: #fde68a;
 }
 
 .pw-shell__validation {
@@ -282,6 +285,43 @@
   content: ":";
 }
 
+/* ------------------------------------------------------------------ */
+/* Warning messages                                                    */
+/* ------------------------------------------------------------------ */
+.pw-shell__warnings {
+  list-style: none;
+  margin: 0;
+  padding: 12px 16px;
+  background: var(--pw-color-warning-bg);
+  border: 1px solid var(--pw-color-warning-border);
+  border-radius: var(--pw-shell-radius);
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.pw-shell__warnings-item {
+  font-size: 13px;
+  color: var(--pw-color-warning);
+  padding-left: 16px;
+  position: relative;
+}
+
+.pw-shell__warnings-item::before {
+  content: "•";
+  position: absolute;
+  left: 4px;
+}
+
+.pw-shell__warnings-label {
+  font-weight: 600;
+  margin-right: 3px;
+}
+
+.pw-shell__warnings-label::after {
+  content: ":";
+}
+
 /* ------------------------------------------------------------------ */
 /* Footer — navigation buttons                                        */
 /* ------------------------------------------------------------------ */

package/dist/index.svelte.d.ts

@@ -3,7 +3,7 @@ export type { PathData, FieldErrors, PathDefinition, PathEngine, PathEvent, Path
 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 +16,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>;
@@ -34,20 +39,49 @@ export interface UsePathReturn<TData extends PathData = PathData> {
     goToStepChecked: (stepId: string) => Promise<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]) => Promise<void>;
+    /** Reset the current step's data to what it was when the step was entered. Useful for "Clear" or "Reset" buttons. */
+    resetStep: () => Promise<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) => Promise<void>;
+    restart: () => 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
@@ -70,13 +104,14 @@ 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;
+    readonly snapshot: PathSnapshot<TData>;
     next: () => Promise<void>;
     previous: () => Promise<void>;
     cancel: () => Promise<void>;
     goToStep: (stepId: string) => Promise<void>;
     goToStepChecked: (stepId: string) => Promise<void>;
     setData: <K extends string & keyof TData>(key: K, value: TData[K]) => Promise<void>;
+    resetStep: () => Promise<void>;
     restart: () => Promise<void>;
 }
 /**

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

@@ -8,8 +8,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
@@ -54,7 +81,8 @@ export function usePath(options) {
     const goToStep = (stepId) => engine.goToStep(stepId);
     const goToStepChecked = (stepId) => engine.goToStepChecked(stepId);
     const setData = ((key, value) => engine.setData(key, value));
-    const restart = (path, initialData = {}) => engine.restart(path, initialData);
+    const resetStep = () => engine.resetStep();
+    const restart = () => engine.restart();
     return {
         get snapshot() { return _snapshot; },
         start,
@@ -65,6 +93,7 @@ export function usePath(options) {
         goToStep,
         goToStepChecked,
         setData,
+        resetStep,
         restart
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daltonr/pathwrite-svelte",
-  "version": "0.7.0",
+  "version": "0.9.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.7.0"
+    "@daltonr/pathwrite-core": "^0.9.0"
   },
   "devDependencies": {
     "@sveltejs/package": "^2.5.7",

package/src/PathShell.svelte

@@ -2,7 +2,7 @@
   import { onMount } from 'svelte';
   import { usePath, setPathContext } 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 {
@@ -49,8 +49,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 {
@@ -65,7 +65,7 @@
     hideCancel = false,
     hideProgress = false,
     footerLayout = 'auto',
-    validationDisplay = 'inline',
+    validationDisplay = 'summary',
     progressLayout = 'merged',
     oncomplete,
     oncancel,
@@ -185,19 +185,23 @@
       {/if}
     {/if}
 
-    <!-- Body: current step rendered via named snippet -->
+    <!-- Body: current step rendered via named snippet.
+         Prefer formId (inner step id of a StepChoice) so consumers can
+         register snippets by inner step ids directly. -->
     <div class="pw-shell__body">
-      {#if stepSnippets[snap.stepId]}
-        {@render stepSnippets[snap.stepId]()}
+      {#if snap.formId && stepSnippets[snap.formId]}
+        <svelte:component this={stepSnippets[snap.formId]} />
+      {:else if stepSnippets[snap.stepId]}
+        <svelte:component this={stepSnippets[snap.stepId]} />
       {:else}
         <p>No content for step "{snap.stepId}"</p>
       {/if}
     </div>
 
     <!-- Validation messages — suppressed when validationDisplay="inline" -->
-    {#if validationDisplay !== 'inline' && snap.hasAttemptedNext && Object.keys(snap.fieldMessages).length > 0}
+    {#if validationDisplay !== 'inline' && snap.hasAttemptedNext && Object.keys(snap.fieldErrors).length > 0}
       <ul class="pw-shell__validation">
-        {#each Object.entries(snap.fieldMessages) as [key, msg]}
+        {#each Object.entries(snap.fieldErrors) as [key, msg]}
           <li class="pw-shell__validation-item">
             {#if key !== '_'}<span class="pw-shell__validation-label">{formatFieldKey(key)}</span>{/if}{msg}
           </li>
@@ -205,6 +209,17 @@
       </ul>
     {/if}
 
+    <!-- Warning messages — non-blocking, shown immediately (no hasAttemptedNext gate) -->
+    {#if validationDisplay !== 'inline' && Object.keys(snap.fieldWarnings).length > 0}
+      <ul class="pw-shell__warnings">
+        {#each Object.entries(snap.fieldWarnings) as [key, msg]}
+          <li class="pw-shell__warnings-item">
+            {#if key !== '_'}<span class="pw-shell__warnings-label">{formatFieldKey(key)}</span>{/if}{msg}
+          </li>
+        {/each}
+      </ul>
+    {/if}
+
     <!-- Footer: navigation buttons (overridable via footer snippet) -->
     {#if footer}
       {@render footer(snap, actions)}

package/src/index.svelte.ts

@@ -30,7 +30,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 +44,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>;
@@ -62,12 +67,14 @@ export interface UsePathReturn<TData extends PathData = PathData> {
   goToStepChecked: (stepId: string) => Promise<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]) => Promise<void>;
+  /** Reset the current step's data to what it was when the step was entered. Useful for "Clear" or "Reset" buttons. */
+  resetStep: () => Promise<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) => Promise<void>;
+  restart: () => Promise<void>;
 }
 
 // ---------------------------------------------------------------------------
@@ -79,8 +86,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
@@ -143,8 +177,9 @@ export function usePath<TData extends PathData = PathData>(
   const setData = (<K extends string & keyof TData>(key: K, value: TData[K]): Promise<void> =>
     engine.setData(key, value as unknown)) as UsePathReturn<TData>["setData"];
 
-  const restart = (path: PathDefinition<any>, initialData: PathData = {}): Promise<void> =>
-    engine.restart(path, initialData);
+  const resetStep = (): Promise<void> => engine.resetStep();
+
+  const restart = (): Promise<void> => engine.restart();
 
   return {
     get snapshot() { return _snapshot; },
@@ -156,6 +191,7 @@ export function usePath<TData extends PathData = PathData>(
     goToStep,
     goToStepChecked,
     setData,
+    resetStep,
     restart
   };
 }
@@ -167,13 +203,14 @@ 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;
+  readonly snapshot: PathSnapshot<TData>;
   next: () => Promise<void>;
   previous: () => Promise<void>;
   cancel: () => Promise<void>;
   goToStep: (stepId: string) => Promise<void>;
   goToStepChecked: (stepId: string) => Promise<void>;
   setData: <K extends string & keyof TData>(key: K, value: TData[K]) => Promise<void>;
+  resetStep: () => Promise<void>;
   restart: () => Promise<void>;
 }