@daltonr/pathwrite-svelte 0.12.0 → 0.13.1

package/README.md

@@ -22,8 +22,9 @@ Peer dependencies: Svelte 5+.
   import { applicationPath } from "./application-path";
   import DetailsStep from "./DetailsStep.svelte";
   import CoverNoteStep from "./CoverNoteStep.svelte";
+  import type { PathData } from "@daltonr/pathwrite-core";
 
-  function handleComplete(data) {
+  function handleComplete(data: PathData) {
     console.log("Submitted:", data);
   }
 </script>
@@ -72,13 +73,16 @@ Peer dependencies: Svelte 5+.
 |---|---|---|
 | `snapshot` | `PathSnapshot \| null` | Reactive getter. `null` when no path is active or when `completionBehaviour: "dismiss"` is used. With the default `"stayOnFinal"`, a non-null snapshot with `status === "completed"` is returned after the path finishes. |
 | `start(definition, data?)` | `Promise<void>` | Start or restart a path. |
-| `restart(definition, data?)` | `Promise<void>` | Tear down any active path and start fresh. |
+| `restart()` | `Promise<void>` | Tear down any active path (without firing hooks) and restart the root path with the `initialData` from the original `start()`. Takes no arguments; rejects if nothing has been started. |
 | `next()` | `Promise<void>` | Advance one step. Completes on the last step. |
 | `previous()` | `Promise<void>` | Go back one step. No-op on the first step of a top-level path. |
 | `cancel()` | `Promise<void>` | Cancel the active path (or sub-path). |
 | `goToStep(stepId)` | `Promise<void>` | Jump to a step by ID. Calls `onLeave`/`onEnter`; bypasses guards. |
 | `goToStepChecked(stepId)` | `Promise<void>` | Jump to a step by ID, checking the current step's guard first. |
 | `setData(key, value)` | `Promise<void>` | Update a single data field. Type-safe when `TData` is specified. |
+| `resetStep()` | `Promise<void>` | Restore the current step's data to what it was when the step was entered. Emits `stateChanged` with cause `"resetStep"`; no hooks run. |
+| `retry()` | `Promise<void>` | Re-run the operation that set `snapshot.error`. Increments `retryCount` on repeated failure. No-op when there is no pending error. |
+| `suspend()` | `Promise<void>` | Pause the path with intent to return. Emits `suspended`; all state and data are preserved. |
 | `startSubPath(definition, data?, meta?)` | `Promise<void>` | Push a sub-path. `meta` is returned to `onSubPathComplete`/`onSubPathCancel`. |
 | `validate()` | `void` | Set `snapshot.hasValidated` without navigating. Triggers all inline field errors simultaneously. Used to validate all tabs in a nested shell at once. |
 
@@ -96,24 +100,32 @@ Step content is supplied as Svelte 5 snippets whose names match each step's `id`
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `path` | `PathDefinition` | — | Path to run. Mutually exclusive with `engine`. |
-| `engine` | `PathEngine` | — | Externally-managed engine (e.g. from `restoreOrStart()`). Mutually exclusive with `path`. |
-| `initialData` | `PathData` | `{}` | Initial data passed to `engine.start()`. |
+| `engine` | `PathEngine` | — | Externally-managed engine (e.g. from `restoreOrStart()`). Mutually exclusive with `path`. May be provided after mount (e.g. once an async `restoreOrStart()` resolves): the shell adopts it, re-subscribing and re-seeding from the new engine. Set `autoStart` to `false` if the shell should not start its own path in the meantime. |
+| `initialData` | `PathData` | `{}` | Initial data passed to `engine.start()`. Overridden by the stored snapshot when `restoreKey` is set. |
 | `autoStart` | `boolean` | `true` | Start on mount. Ignored when `engine` is provided. |
 | `layout` | `"wizard" \| "form" \| "auto" \| "tabs"` | `"auto"` | `"wizard"`: Back on left, Cancel+Submit on right. `"form"`: Cancel on left, Submit on right, no Back. `"tabs"`: No progress header or footer — for tabbed interfaces. `"auto"` picks `"form"` for single-step paths. |
+| `validationDisplay` | `"summary" \| "inline" \| "both"` | `"summary"` | Where `fieldErrors` are rendered. Use `"inline"` so step components render their own errors. |
+| `progressLayout` | `"merged" \| "split" \| "rootOnly" \| "activeOnly"` | `"merged"` | How the root and sub-path progress bars are arranged while a sub-path is active. |
 | `hideProgress` | `boolean` | `false` | Hide the progress indicator. Also hidden automatically for single-step paths. |
+| `hideFooter` | `boolean` | `false` | Hide the footer (navigation buttons). The error panel is still shown on async failure. |
 | `backLabel` | `string` | `"Previous"` | Previous button label. |
 | `nextLabel` | `string` | `"Next"` | Next button label. |
 | `completeLabel` | `string` | `"Complete"` | Complete button label (last step). |
+| `loadingLabel` | `string` | `undefined` | Label for the Next/Complete button while an async operation is in progress. When unset, the button keeps its label and shows a CSS spinner. |
 | `cancelLabel` | `string` | `"Cancel"` | Cancel button label. |
 | `hideCancel` | `boolean` | `false` | Hide the Cancel button. |
-| `validateWhen` | `boolean` | `false` | When it becomes `true`, calls `validate()` on the engine. Bind to the outer snapshot's `hasAttemptedNext` when this shell is nested inside a step of an outer shell. |
-| `restoreKey` | `string` | — | When set, the shell automatically saves its full state (data + active step) into the nearest outer `PathShell`'s data under this key on every change, and restores from it on remount. No-op on a top-level shell. |
+| `validateWhen` | `boolean` | `false` | When `true` (including already at mount), calls `validate()` on the engine so all steps show inline errors at once. Bind to the outer snapshot's `hasAttemptedNext` when this shell is nested inside a step of an outer shell. |
+| `restoreKey` | `string` | — | When set, the shell automatically saves its full state (data + active step) into the nearest outer `PathShell`'s data under this key on every change, and restores from it on remount. No-op on a top-level shell. The stored value also carries the inner engine's serialized state, so a remount restores in place: no `onEnter` / `onLeave` re-run, attempted / visited state kept. |
 | `services` | `unknown` | `null` | Arbitrary services object available to step components via `usePathContext<TData, TServices>().services`. |
 | `oncomplete` | `(data: PathData) => void` | — | Called when the path finishes naturally. |
 | `oncancel` | `(data: PathData) => void` | — | Called when the path is cancelled. |
 | `onevent` | `(event: PathEvent) => void` | — | Called for every engine event. |
+| `header` | `Snippet<[PathSnapshot]>` | — | Replaces the default progress header. A custom header is shown even for single-step paths, and hidden under `hideProgress` or `layout="tabs"`. |
+| `footer` | `Snippet<[PathSnapshot, PathShellActions]>` | — | Replaces the default navigation footer. `actions` contains `next`, `previous`, `cancel`, `goToStep`, `goToStepChecked`, `setData`, `restart`, `retry`, `suspend`. |
 | `completion` | `Snippet<[PathSnapshot<any>]>` | — | Custom snippet rendered when `snapshot.status === "completed"` (`completionBehaviour: "stayOnFinal"`). Receives the completed snapshot. If omitted, a default "All done." panel is shown. |
 
+The component instance also exposes `restart()` for `bind:this` refs, which restarts the path with its original `initialData` without remounting.
+
 > **Note:** Svelte requires event/callback props to be lowercase. Unlike React/Vue/Angular, passing `onComplete`, `onCancel`, or `onEvent` (camelCase) will be silently ignored. PathShell emits a `console.warn` in development if it detects one of these common mistakes.
 
 You can also replace the built-in header and footer with custom snippets:
@@ -137,7 +149,7 @@ You can also replace the built-in header and footer with custom snippets:
 
 ## usePathContext
 
-`usePathContext<TData>()` is the preferred way for step components rendered inside `<PathShell>` to access the path engine. `<PathShell>` calls `setContext()` internally with a private `Symbol` key; `usePathContext()` calls the matching `getContext()` and returns the same interface as `usePath`. It throws a clear error if called outside a `<PathShell>` — do not use Svelte's raw `getContext()` directly, as the key is a private `Symbol` and will silently return `undefined`.
+`usePathContext<TData>()` is the preferred way for step components rendered inside `<PathShell>` to access the path engine. `<PathShell>` calls `setContext()` internally with a private `Symbol` key; `usePathContext()` calls the matching `getContext()` and returns `snapshot` (typed `PathSnapshot | null` — narrow with `{#if ctx.snapshot}`), the navigation actions (`next`, `previous`, `cancel`, `goToStep`, `goToStepChecked`, `setData`, `resetStep`, `restart`, `retry`, `suspend`) and `services`; it does not expose `start`, `startSubPath` or `validate`. It throws a clear error if called outside a `<PathShell>` — do not use Svelte's raw `getContext()` directly, as the key is a private `Symbol` and will silently return `undefined`. The context is the full `usePath()` return type (`PathContext` extends `UsePathReturn`), so `start`, `startSubPath` and `validate` are available to step components too — for example to launch a sub-path from a button inside a step.
 
 ```svelte
 <script lang="ts">
@@ -154,10 +166,22 @@ You can also replace the built-in header and footer with custom snippets:
 {/if}
 ```
 
+## Other exports
+
+| Export | Description |
+|---|---|
+| `bindData(getSnapshot, setData, key)` | Two-way binding helper for inputs. Returns an object with a reactive `value` getter (reads `getSnapshot()?.data[key]`) and a `set(value)` method that calls `setData(key, value)`. Example: `const name = bindData(() => path.snapshot, path.setData, "name")`, then `<input value={name.value} oninput={(e) => name.set(e.currentTarget.value)} />`. |
+| `stepIdToCamelCase(id)` | Converts a hyphenated step ID to camelCase (`"cover-letter"` → `"coverLetter"`) — the conversion `<PathShell>` uses to resolve snippets for hyphenated step IDs. |
+| `setPathContext(ctx)` | Sets the `PathContext` that `usePathContext()` reads, under the adapter's private `Symbol` key. Used internally by `<PathShell>`; only needed when building your own shell component. |
+| `getPathContextOrNull()` | Reads the nearest ancestor `PathContext`, or `undefined` when there is none. Used internally by `<PathShell>` to reach the outer shell for `restoreKey`; call it before `setPathContext()` so it reads the parent rather than self. |
+| `formatFieldKey`, `errorPhaseMessage` | Re-exported from `@daltonr/pathwrite-core` for building custom summaries and error panels. |
+
+`PathEngine` is re-exported as a **type only**. To construct an engine, import the class from `@daltonr/pathwrite-core`.
+
 ## Further reading
 
 - [Svelte getting started guide](../../docs/getting-started/frameworks/svelte.md)
-- [Navigation & guards](../../docs/guides/navigation.md)
+- [Navigation & guards](../../docs/developer-guide/04-navigation.md)
 - [Full documentation](../../docs/README.md)
 
 ---

package/dist/PathShell.svelte

@@ -1,7 +1,9 @@
 <script lang="ts">
   import { onMount } from 'svelte';
   import { usePath, setPathContext, getPathContextOrNull, formatFieldKey, errorPhaseMessage, stepIdToCamelCase } from './index.svelte.js';
-  import type { PathDefinition, PathData, PathEngine, PathSnapshot, ProgressLayout } from './index.svelte.js';
+  import type { PathDefinition, PathData, PathEngine, PathSnapshot, ProgressLayout, PathShellActions } from './index.svelte.js';
+  import { PathEngine as PathEngineClass } from '@daltonr/pathwrite-core';
+  import type { SerializedPathState } from '@daltonr/pathwrite-core';
   import type { Snippet, Component } from 'svelte';
 
 
@@ -61,7 +63,7 @@
     onevent?: (event: any) => void;
     // Optional override snippets for header and footer
     header?: Snippet<[PathSnapshot<any>]>;
-    footer?: Snippet<[PathSnapshot<any>, object]>;
+    footer?: Snippet<[PathSnapshot<any>, PathShellActions]>;
     /** Snippet rendered when `snapshot.status === "completed"`. Defaults to a simple "All done." panel with a restart button. */
     completion?: Snippet<[PathSnapshot<any>]>;
     // All other props treated as step components keyed by step ID
@@ -100,33 +102,56 @@
   // parent shell's snapshot and setData for restoreKey auto-wiring.
   const outerCtx = getPathContextOrNull();
 
+  // When remounting under restoreKey, rebuild the inner engine from the state the
+  // previous instance exported, instead of starting the path and jumping to the
+  // step (which re-ran onEnter/onLeave and lost attempted / visited state).
+  // svelte-ignore state_referenced_locally — read once at init on purpose: restore happens at mount only
+  const restoredEngine: PathEngine | null = (() => {
+    if (engineProp || !restoreKey || !outerCtx || !path) return null;
+    const stored = outerCtx.snapshot?.data[restoreKey] as { serializedState?: SerializedPathState } | undefined;
+    if (!stored || typeof stored !== 'object' || !stored.serializedState) return null;
+    try {
+      return PathEngineClass.fromState(stored.serializedState, { [path.id]: path });
+    } catch {
+      return null; // unusable state (e.g. the path definition changed): start fresh below
+    }
+  })();
+  // The shell's own engine is created once; an `engine` prop — present at
+  // mount or arriving later — always takes precedence and is adopted by usePath.
+  const ownEngine: PathEngine = restoredEngine ?? new PathEngineClass();
+  const currentEngine = (): PathEngine => engineProp ?? ownEngine;
+
   // Initialize path engine
   const pathReturn = usePath({
-    get engine() { return engineProp; },
+    get engine() { return currentEngine(); },
     onEvent: (event) => {
       onevent?.(event);
       if (event.type === 'completed') oncomplete?.(event.data);
       if (event.type === 'cancelled') oncancel?.(event.data);
       if (restoreKey && outerCtx && event.type === 'stateChanged') {
         (outerCtx.setData as unknown as (key: string, value: unknown) => Promise<void>)(
-          restoreKey, event.snapshot
+          restoreKey, { ...event.snapshot, serializedState: currentEngine().exportState() }
         );
       }
     }
   });
 
-  const { start, next, previous, cancel, goToStep, goToStepChecked, setData, restart: restartFn, retry, suspend } = pathReturn;
+  const { start, startSubPath, next, previous, cancel, goToStep, goToStepChecked, setData, resetStep, restart: restartFn, retry, suspend, validate } = pathReturn;
 
   // Provide context for child step components
   setPathContext({
     get snapshot() { return pathReturn.snapshot; },
+    start,
+    startSubPath,
+    validate,
     next,
     previous,
     cancel,
     goToStep,
     goToStepChecked,
     setData,
-    restart: () => restartFn(path, initialData),
+    resetStep,
+    restart: () => restartFn(),
     retry,
     suspend,
     get services() { return services; },
@@ -134,8 +159,13 @@
 
   // Dev-mode warning: camelCase callback props are silently ignored in Svelte.
   // Warn if the user passed onComplete/onCancel/onEvent instead of the correct
-  // lowercase forms oncomplete/oncancel/onevent.
-  if (import.meta.env?.DEV !== false) {
+  // lowercase forms oncomplete/oncancel/onevent. Runs once, on mount (a closure
+  // — reading the props at the top level would only capture their initial value).
+  // `import.meta.env` is a bundler convention (Vite); the cast keeps this
+  // package free of Vite's ambient types.
+  const isDev = (import.meta as { env?: { DEV?: boolean } }).env?.DEV !== false;
+  onMount(() => {
+    if (!isDev) return;
     const camelCallbacks = ['onComplete', 'onCancel', 'onEvent'] as const;
     for (const name of camelCallbacks) {
       if (name in stepSnippets) {
@@ -144,12 +174,13 @@
         );
       }
     }
-  }
+  });
 
   // Auto-start the path when no external engine is provided
   let started = false;
   onMount(() => {
-    if (autoStart && !started && !engineProp) {
+    if (autoStart && !started && !engineProp && !restoredEngine) {
+      if (!path) throw new Error('[PathShell] "path" is required when no "engine" is provided');
       started = true;
       let startData: PathData = initialData ?? {};
       let restoreStepId: string | undefined;
@@ -180,7 +211,11 @@
   }
 
   let snap = $derived(pathReturn.snapshot);
-  let actions = $derived({ next, previous, cancel, goToStep, goToStepChecked, setData, restart: () => restartFn(path, initialData), retry, suspend });
+  let actions: PathShellActions = $derived({
+    next, previous, cancel, goToStep, goToStepChecked,
+    setData: (key, value) => setData(key as never, value as never),
+    restart: () => restartFn(), retry, suspend
+  });
 
   let effectiveHideProgress = $derived(hideProgress || layout === 'tabs');
   let effectiveHideFooter = $derived(hideFooter || layout === 'tabs');
@@ -202,7 +237,7 @@
    * ```
    */
   export function restart(): Promise<void> {
-    return pathReturn.restart(path, initialData);
+    return pathReturn.restart();
   }
 </script>
 
@@ -211,7 +246,7 @@
     <div class="pw-shell__empty">
       <p>No active path.</p>
       {#if !autoStart}
-        <button type="button" class="pw-shell__start-btn" onclick={() => start(path, initialData)}>
+        <button type="button" class="pw-shell__start-btn" onclick={() => path && start(path, initialData)}>
           Start
         </button>
       {/if}
@@ -239,7 +274,7 @@
       {:else}
         <div class="pw-shell__completion">
           <p class="pw-shell__completion-message">All done.</p>
-          <button type="button" class="pw-shell__completion-restart" onclick={() => restartFn(path, initialData)}>
+          <button type="button" class="pw-shell__completion-restart" onclick={() => restartFn()}>
             Start over
           </button>
         </div>

package/dist/PathShell.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { PathDefinition, PathData, PathEngine, PathSnapshot, ProgressLayout } from './index.svelte.js';
+import type { PathDefinition, PathData, PathEngine, PathSnapshot, ProgressLayout, PathShellActions } from './index.svelte.js';
 import type { Snippet, Component } from 'svelte';
 interface Props {
     path?: PathDefinition<any>;
@@ -54,7 +54,7 @@ interface Props {
     oncancel?: (data: PathData) => void;
     onevent?: (event: any) => void;
     header?: Snippet<[PathSnapshot<any>]>;
-    footer?: Snippet<[PathSnapshot<any>, object]>;
+    footer?: Snippet<[PathSnapshot<any>, PathShellActions]>;
     /** Snippet rendered when `snapshot.status === "completed"`. Defaults to a simple "All done." panel with a restart button. */
     completion?: Snippet<[PathSnapshot<any>]>;
     [key: string]: Component<any> | any;

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,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;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,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,8HAA8H;IAC9H,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,qNAAqN;IACrN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAC7C;;;;;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;IAC9C,6HAA6H;IAC7H,UAAU,CAAC,EAAE,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAE1C,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;CACrC;AA0UH,QAAA,MAAM,SAAS;mBA7LQ,QAAQ,IAAI,CAAC;MA6LmB,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,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAG9H,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;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,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,8HAA8H;IAC9H,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,qNAAqN;IACrN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAC7C;;;;;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,gBAAgB,CAAC,CAAC,CAAC;IACxD,6HAA6H;IAC7H,UAAU,CAAC,EAAE,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAE1C,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;CACrC;AA6WH,QAAA,MAAM,SAAS;mBA7LQ,QAAQ,IAAI,CAAC;MA6LmB,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}

package/dist/index.css

@@ -357,6 +357,23 @@
   content: ":";
 }
 
+/* ------------------------------------------------------------------ */
+/* Inline field-level errors and warnings (<FieldError /> component)  */
+/* ------------------------------------------------------------------ */
+.pw-field-error {
+  display: block;
+  font-size: 12px;
+  color: var(--pw-color-error);
+  margin-top: 4px;
+}
+
+.pw-field-warning {
+  display: block;
+  font-size: 12px;
+  color: var(--pw-color-warning);
+  margin-top: 4px;
+}
+
 /* ------------------------------------------------------------------ */
 /* Footer — navigation buttons                                        */
 /* ------------------------------------------------------------------ */

package/dist/index.svelte.d.ts

@@ -12,6 +12,12 @@ export interface UsePathOptions {
      * - The engine lifecycle (start / cleanup) is the **caller's responsibility**.
      * - `PathShell` will skip its own `autoStart` call.
      */
+    /**
+     * An externally managed engine. Pass it as a getter (`get engine() { … }`)
+     * over a reactive prop to have the hook track it: an engine that arrives
+     * later (e.g. from an async `restoreOrStart()`) or is swapped is adopted —
+     * the hook re-subscribes and re-seeds its snapshot from the new engine.
+     */
     engine?: PathEngine;
     /** Called for every engine event (stateChanged, completed, cancelled, resumed). */
     onEvent?: (event: PathEvent) => void;
@@ -47,8 +53,9 @@ export interface UsePathReturn<TData extends PathData = PathData> {
     /** 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.
+     * Tear down any active path (without firing hooks) and immediately restart
+     * the root path with the `initialData` from the original `start()` call.
+     * Takes no arguments; rejects if the engine has never been started.
      * Use for "Start over" / retry flows without remounting the component.
      */
     restart: () => Promise<void>;
@@ -114,8 +121,12 @@ 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, TServices = unknown> {
-    readonly snapshot: PathSnapshot<TData>;
+/**
+ * Navigation actions handed to a custom `footer` snippet of `<PathShell>`
+ * (`{#snippet footer(snap, actions)}`). Same shape as the other adapters'
+ * `PathShellActions`.
+ */
+export interface PathShellActions {
     next: () => Promise<void>;
     previous: () => Promise<void>;
     cancel: () => Promise<void>;
@@ -125,17 +136,20 @@ export interface PathContext<TData extends PathData = PathData, TServices = unkn
     goToStepChecked: (stepId: string, options?: {
         validateOnLeave?: boolean;
     }) => Promise<void>;
-    setData: <K extends string & keyof TData>(key: K, value: TData[K]) => Promise<void>;
-    resetStep: () => Promise<void>;
+    setData: (key: string, value: unknown) => Promise<void>;
+    /** Restart the shell's current path with its current `initialData`. */
     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.
-     */
+}
+/**
+ * What step components receive from `usePathContext()`: everything `usePath()`
+ * returns (derived from `UsePathReturn`, so the two cannot drift apart) plus
+ * the `services` object given to `<PathShell>`.
+ */
+export interface PathContext<TData extends PathData = PathData, TServices = unknown> extends UsePathReturn<TData> {
     services: TServices;
 }
 /**

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

@@ -60,11 +60,11 @@ export { formatFieldKey, errorPhaseMessage } from "@daltonr/pathwrite-core";
  * ```
  */
 export function usePath(options) {
-    const engine = options?.engine ?? new PathEngineClass();
-    // Reactive snapshot via $state rune
+    let ownEngine = null;
+    const resolveEngine = () => options?.engine ?? (ownEngine ??= new PathEngineClass());
+    let engine = resolveEngine();
     let _snapshot = $state(engine.snapshot());
-    // Subscribe to engine events
-    const unsubscribe = engine.subscribe((event) => {
+    const onEngineEvent = (event) => {
         if (event.type === "stateChanged" || event.type === "resumed") {
             _snapshot = event.snapshot;
         }
@@ -72,9 +72,24 @@ export function usePath(options) {
             _snapshot = engine.snapshot();
         }
         options?.onEvent?.(event);
+    };
+    let unsubscribe = engine.subscribe(onEngineEvent);
+    // Adopt a late or swapped engine (the `engine` option is a getter over a
+    // reactive prop): re-subscribe and re-seed the snapshot. Created in its own
+    // effect root so usePath() also works outside a component.
+    const stopWatching = $effect.root(() => {
+        $effect(() => {
+            const next = resolveEngine();
+            if (next === engine)
+                return;
+            unsubscribe();
+            engine = next;
+            _snapshot = engine.snapshot();
+            unsubscribe = engine.subscribe(onEngineEvent);
+        });
     });
     // Auto-cleanup when component is destroyed
-    onDestroy(unsubscribe);
+    onDestroy(() => { unsubscribe(); stopWatching(); });
     const start = (path, initialData = {}) => engine.start(path, initialData);
     const startSubPath = (path, initialData = {}, meta) => engine.startSubPath(path, initialData, meta);
     const next = () => engine.next();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daltonr/pathwrite-svelte",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "type": "module",
   "license": "MIT",
   "description": "Svelte 5 adapter for @daltonr/pathwrite-core — runes-based reactive bindings and optional PathShell component.",
@@ -28,6 +28,7 @@
       "import": "./dist/index.svelte.js"
     },
     "./PathShell.svelte": {
+      "types": "./dist/PathShell.svelte.d.ts",
       "svelte": "./dist/PathShell.svelte",
       "import": "./dist/PathShell.svelte"
     },
@@ -44,7 +45,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "svelte-package -i src -o dist && cp ../shell.css dist/index.css",
+    "check": "svelte-check --tsconfig ./tsconfig.check.json --fail-on-warnings",
+    "build": "npm run check && svelte-package -i src -o dist && cp ../shell.css dist/index.css",
     "clean": "rm -rf dist tsconfig.tsbuildinfo",
     "prepublishOnly": "test -d dist && echo 'dist already built, skipping' || (npm run clean && npm run build)"
   },
@@ -52,12 +54,15 @@
     "svelte": ">=5.0.0"
   },
   "dependencies": {
-    "@daltonr/pathwrite-core": "^0.12.0"
+    "@daltonr/pathwrite-core": "^0.13.1"
   },
   "devDependencies": {
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^4.0.0",
     "@testing-library/svelte": "^5.0.0",
     "svelte": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/PathShell.svelte

@@ -1,7 +1,9 @@
 <script lang="ts">
   import { onMount } from 'svelte';
   import { usePath, setPathContext, getPathContextOrNull, formatFieldKey, errorPhaseMessage, stepIdToCamelCase } from './index.svelte.js';
-  import type { PathDefinition, PathData, PathEngine, PathSnapshot, ProgressLayout } from './index.svelte.js';
+  import type { PathDefinition, PathData, PathEngine, PathSnapshot, ProgressLayout, PathShellActions } from './index.svelte.js';
+  import { PathEngine as PathEngineClass } from '@daltonr/pathwrite-core';
+  import type { SerializedPathState } from '@daltonr/pathwrite-core';
   import type { Snippet, Component } from 'svelte';
 
 
@@ -61,7 +63,7 @@
     onevent?: (event: any) => void;
     // Optional override snippets for header and footer
     header?: Snippet<[PathSnapshot<any>]>;
-    footer?: Snippet<[PathSnapshot<any>, object]>;
+    footer?: Snippet<[PathSnapshot<any>, PathShellActions]>;
     /** Snippet rendered when `snapshot.status === "completed"`. Defaults to a simple "All done." panel with a restart button. */
     completion?: Snippet<[PathSnapshot<any>]>;
     // All other props treated as step components keyed by step ID
@@ -100,33 +102,56 @@
   // parent shell's snapshot and setData for restoreKey auto-wiring.
   const outerCtx = getPathContextOrNull();
 
+  // When remounting under restoreKey, rebuild the inner engine from the state the
+  // previous instance exported, instead of starting the path and jumping to the
+  // step (which re-ran onEnter/onLeave and lost attempted / visited state).
+  // svelte-ignore state_referenced_locally — read once at init on purpose: restore happens at mount only
+  const restoredEngine: PathEngine | null = (() => {
+    if (engineProp || !restoreKey || !outerCtx || !path) return null;
+    const stored = outerCtx.snapshot?.data[restoreKey] as { serializedState?: SerializedPathState } | undefined;
+    if (!stored || typeof stored !== 'object' || !stored.serializedState) return null;
+    try {
+      return PathEngineClass.fromState(stored.serializedState, { [path.id]: path });
+    } catch {
+      return null; // unusable state (e.g. the path definition changed): start fresh below
+    }
+  })();
+  // The shell's own engine is created once; an `engine` prop — present at
+  // mount or arriving later — always takes precedence and is adopted by usePath.
+  const ownEngine: PathEngine = restoredEngine ?? new PathEngineClass();
+  const currentEngine = (): PathEngine => engineProp ?? ownEngine;
+
   // Initialize path engine
   const pathReturn = usePath({
-    get engine() { return engineProp; },
+    get engine() { return currentEngine(); },
     onEvent: (event) => {
       onevent?.(event);
       if (event.type === 'completed') oncomplete?.(event.data);
       if (event.type === 'cancelled') oncancel?.(event.data);
       if (restoreKey && outerCtx && event.type === 'stateChanged') {
         (outerCtx.setData as unknown as (key: string, value: unknown) => Promise<void>)(
-          restoreKey, event.snapshot
+          restoreKey, { ...event.snapshot, serializedState: currentEngine().exportState() }
         );
       }
     }
   });
 
-  const { start, next, previous, cancel, goToStep, goToStepChecked, setData, restart: restartFn, retry, suspend } = pathReturn;
+  const { start, startSubPath, next, previous, cancel, goToStep, goToStepChecked, setData, resetStep, restart: restartFn, retry, suspend, validate } = pathReturn;
 
   // Provide context for child step components
   setPathContext({
     get snapshot() { return pathReturn.snapshot; },
+    start,
+    startSubPath,
+    validate,
     next,
     previous,
     cancel,
     goToStep,
     goToStepChecked,
     setData,
-    restart: () => restartFn(path, initialData),
+    resetStep,
+    restart: () => restartFn(),
     retry,
     suspend,
     get services() { return services; },
@@ -134,8 +159,13 @@
 
   // Dev-mode warning: camelCase callback props are silently ignored in Svelte.
   // Warn if the user passed onComplete/onCancel/onEvent instead of the correct
-  // lowercase forms oncomplete/oncancel/onevent.
-  if (import.meta.env?.DEV !== false) {
+  // lowercase forms oncomplete/oncancel/onevent. Runs once, on mount (a closure
+  // — reading the props at the top level would only capture their initial value).
+  // `import.meta.env` is a bundler convention (Vite); the cast keeps this
+  // package free of Vite's ambient types.
+  const isDev = (import.meta as { env?: { DEV?: boolean } }).env?.DEV !== false;
+  onMount(() => {
+    if (!isDev) return;
     const camelCallbacks = ['onComplete', 'onCancel', 'onEvent'] as const;
     for (const name of camelCallbacks) {
       if (name in stepSnippets) {
@@ -144,12 +174,13 @@
         );
       }
     }
-  }
+  });
 
   // Auto-start the path when no external engine is provided
   let started = false;
   onMount(() => {
-    if (autoStart && !started && !engineProp) {
+    if (autoStart && !started && !engineProp && !restoredEngine) {
+      if (!path) throw new Error('[PathShell] "path" is required when no "engine" is provided');
       started = true;
       let startData: PathData = initialData ?? {};
       let restoreStepId: string | undefined;
@@ -180,7 +211,11 @@
   }
 
   let snap = $derived(pathReturn.snapshot);
-  let actions = $derived({ next, previous, cancel, goToStep, goToStepChecked, setData, restart: () => restartFn(path, initialData), retry, suspend });
+  let actions: PathShellActions = $derived({
+    next, previous, cancel, goToStep, goToStepChecked,
+    setData: (key, value) => setData(key as never, value as never),
+    restart: () => restartFn(), retry, suspend
+  });
 
   let effectiveHideProgress = $derived(hideProgress || layout === 'tabs');
   let effectiveHideFooter = $derived(hideFooter || layout === 'tabs');
@@ -202,7 +237,7 @@
    * ```
    */
   export function restart(): Promise<void> {
-    return pathReturn.restart(path, initialData);
+    return pathReturn.restart();
   }
 </script>
 
@@ -211,7 +246,7 @@
     <div class="pw-shell__empty">
       <p>No active path.</p>
       {#if !autoStart}
-        <button type="button" class="pw-shell__start-btn" onclick={() => start(path, initialData)}>
+        <button type="button" class="pw-shell__start-btn" onclick={() => path && start(path, initialData)}>
           Start
         </button>
       {/if}
@@ -239,7 +274,7 @@
       {:else}
         <div class="pw-shell__completion">
           <p class="pw-shell__completion-message">All done.</p>
-          <button type="button" class="pw-shell__completion-restart" onclick={() => restartFn(path, initialData)}>
+          <button type="button" class="pw-shell__completion-restart" onclick={() => restartFn()}>
             Start over
           </button>
         </div>

package/src/index.svelte.ts

@@ -39,6 +39,12 @@ export interface UsePathOptions {
    * - The engine lifecycle (start / cleanup) is the **caller's responsibility**.
    * - `PathShell` will skip its own `autoStart` call.
    */
+  /**
+   * An externally managed engine. Pass it as a getter (`get engine() { … }`)
+   * over a reactive prop to have the hook track it: an engine that arrives
+   * later (e.g. from an async `restoreOrStart()`) or is swapped is adopted —
+   * the hook re-subscribes and re-seeds its snapshot from the new engine.
+   */
   engine?: PathEngine;
   /** Called for every engine event (stateChanged, completed, cancelled, resumed). */
   onEvent?: (event: PathEvent) => void;
@@ -71,8 +77,9 @@ export interface UsePathReturn<TData extends PathData = PathData> {
   /** 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.
+   * Tear down any active path (without firing hooks) and immediately restart
+   * the root path with the `initialData` from the original `start()` call.
+   * Takes no arguments; rejects if the engine has never been started.
    * Use for "Start over" / retry flows without remounting the component.
    */
   restart: () => Promise<void>;
@@ -145,25 +152,40 @@ export interface UsePathReturn<TData extends PathData = PathData> {
 export function usePath<TData extends PathData = PathData>(
   options?: UsePathOptions
 ): UsePathReturn<TData> {
-  const engine = options?.engine ?? new PathEngineClass();
+  let ownEngine: PathEngine | null = null;
+  const resolveEngine = (): PathEngine => options?.engine ?? (ownEngine ??= new PathEngineClass());
+  let engine = resolveEngine();
 
-  // Reactive snapshot via $state rune
   let _snapshot: PathSnapshot<TData> | null = $state(
     engine.snapshot() as PathSnapshot<TData> | null
   );
 
-  // Subscribe to engine events
-  const unsubscribe = engine.subscribe((event: PathEvent) => {
+  const onEngineEvent = (event: PathEvent): void => {
     if (event.type === "stateChanged" || event.type === "resumed") {
       _snapshot = event.snapshot as PathSnapshot<TData>;
     } else if (event.type === "completed" || event.type === "cancelled") {
       _snapshot = engine.snapshot() as PathSnapshot<TData> | null;
     }
     options?.onEvent?.(event);
+  };
+  let unsubscribe = engine.subscribe(onEngineEvent);
+
+  // Adopt a late or swapped engine (the `engine` option is a getter over a
+  // reactive prop): re-subscribe and re-seed the snapshot. Created in its own
+  // effect root so usePath() also works outside a component.
+  const stopWatching = $effect.root(() => {
+    $effect(() => {
+      const next = resolveEngine();
+      if (next === engine) return;
+      unsubscribe();
+      engine = next;
+      _snapshot = engine.snapshot() as PathSnapshot<TData> | null;
+      unsubscribe = engine.subscribe(onEngineEvent);
+    });
   });
 
   // Auto-cleanup when component is destroyed
-  onDestroy(unsubscribe);
+  onDestroy(() => { unsubscribe(); stopWatching(); });
 
   const start = (path: PathDefinition<any>, initialData: PathData = {}): Promise<void> =>
     engine.start(path, initialData);
@@ -210,30 +232,38 @@ export function usePath<TData extends PathData = PathData>(
   };
 }
 
-// ---------------------------------------------------------------------------
-// Context API for PathShell
-// ---------------------------------------------------------------------------
-
-const PATH_CONTEXT_KEY = Symbol("pathwrite-context");
-
-export interface PathContext<TData extends PathData = PathData, TServices = unknown> {
-  readonly snapshot: PathSnapshot<TData>;
+/**
+ * Navigation actions handed to a custom `footer` snippet of `<PathShell>`
+ * (`{#snippet footer(snap, actions)}`). Same shape as the other adapters'
+ * `PathShellActions`.
+ */
+export interface PathShellActions {
   next: () => Promise<void>;
   previous: () => Promise<void>;
   cancel: () => Promise<void>;
   goToStep: (stepId: string, options?: { validateOnLeave?: boolean }) => Promise<void>;
   goToStepChecked: (stepId: string, options?: { validateOnLeave?: boolean }) => Promise<void>;
-  setData: <K extends string & keyof TData>(key: K, value: TData[K]) => Promise<void>;
-  resetStep: () => Promise<void>;
+  setData: (key: string, value: unknown) => Promise<void>;
+  /** Restart the shell's current path with its current `initialData`. */
   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.
-   */
+}
+
+// ---------------------------------------------------------------------------
+// Context API for PathShell
+// ---------------------------------------------------------------------------
+
+const PATH_CONTEXT_KEY = Symbol("pathwrite-context");
+
+/**
+ * What step components receive from `usePathContext()`: everything `usePath()`
+ * returns (derived from `UsePathReturn`, so the two cannot drift apart) plus
+ * the `services` object given to `<PathShell>`.
+ */
+export interface PathContext<TData extends PathData = PathData, TServices = unknown> extends UsePathReturn<TData> {
   services: TServices;
 }