@daltonr/pathwrite-svelte 0.11.0 → 0.13.0

package/README.md

@@ -70,16 +70,20 @@ Peer dependencies: Svelte 5+.
 
 | Return value | Type | Description |
 |---|---|---|
-| `snapshot` | `PathSnapshot \| null` | Reactive getter. `null` when no path is active. |
+| `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. |
 
 **Options:**
 
@@ -95,19 +99,33 @@ 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. |
-| `footerLayout` | `"wizard" \| "form" \| "auto"` | `"auto"` | `"wizard"`: Back on left, Cancel+Submit on right. `"form"`: Cancel on left, Submit on right, no Back. `"auto"` picks `"form"` for single-step paths. |
+| `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 `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:
 
@@ -130,7 +148,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">
@@ -147,12 +165,24 @@ 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)
 
 ---
 
-MIT — © 2026 Devjoy Ltd.
+© 2026 Devjoy Ltd. MIT License.

package/dist/PathShell.svelte

@@ -1,7 +1,9 @@
 <script lang="ts">
   import { onMount } from 'svelte';
-  import { usePath, setPathContext, formatFieldKey, errorPhaseMessage, stepIdToCamelCase } from './index.svelte.js';
-  import type { PathDefinition, PathData, PathEngine, PathSnapshot, ProgressLayout } from './index.svelte.js';
+  import { usePath, setPathContext, getPathContextOrNull, formatFieldKey, errorPhaseMessage, stepIdToCamelCase } 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';
 
 
@@ -9,6 +11,12 @@
     path?: PathDefinition<any>;
     engine?: PathEngine;
     initialData?: PathData;
+    /**
+     * When set, this shell automatically saves its state into the nearest outer `PathShell`'s
+     * data under this key on every change, and restores from that stored state on remount.
+     * No-op when used on a top-level shell with no outer `PathShell` ancestor.
+     */
+    restoreKey?: string;
     autoStart?: boolean;
     backLabel?: string;
     nextLabel?: string;
@@ -22,12 +30,13 @@
     /** When true, calls `validate()` on the engine so all steps show inline errors simultaneously. Useful when this shell is nested inside a step of an outer shell: bind to the outer snapshot's `hasAttemptedNext`. */
     validateWhen?: boolean;
     /**
-     * Footer layout mode:
+     * Shell layout mode:
      * - "auto" (default): Uses "form" for single-step top-level paths, "wizard" otherwise.
-     * - "wizard": Back button on left, Cancel and Submit together on right.
-     * - "form": Cancel on left, Submit alone on right. Back button never shown.
+     * - "wizard": Progress header + Back button on left, Cancel and Submit together on right.
+     * - "form": Progress header + Cancel on left, Submit alone on right. Back button never shown.
+     * - "tabs": No progress header, no footer. Use for tabbed interfaces with a custom tab bar inside the step body.
      */
-    footerLayout?: "wizard" | "form" | "auto";
+    layout?: "wizard" | "form" | "auto" | "tabs";
     /**
      * Controls whether the shell renders its auto-generated field-error summary box.
      * - `"summary"` (default): Shell renders the labeled error list below the step body.
@@ -54,7 +63,9 @@
     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
     [key: string]: Component<any> | any;
   }
@@ -63,6 +74,7 @@
     path,
     engine: engineProp,
     initialData = {},
+    restoreKey = undefined,
     autoStart = true,
     backLabel = 'Previous',
     nextLabel = 'Next',
@@ -73,7 +85,7 @@
     hideProgress = false,
     hideFooter = false,
     validateWhen = false,
-    footerLayout = 'auto',
+    layout = 'auto',
     validationDisplay = 'summary',
     progressLayout = 'merged',
     services = null,
@@ -82,42 +94,107 @@
     onevent,
     header,
     footer,
+    completion,
     ...stepSnippets
   }: Props = $props();
 
+  // Read outer PathShell context BEFORE setting our own — gives access to
+  // 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, 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; },
   });
 
+  // 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. 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) {
+        console.warn(
+          `[PathShell] "${name}" was passed but will be ignored. Svelte uses lowercase callback props — use "${name.toLowerCase()}" instead.`
+        );
+      }
+    }
+  });
+
   // 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;
-      start(path, initialData);
+      let startData: PathData = initialData ?? {};
+      let restoreStepId: string | undefined;
+      if (restoreKey && outerCtx) {
+        const stored = outerCtx.snapshot?.data[restoreKey] as PathSnapshot<any> | undefined;
+        if (stored != null && typeof stored === 'object' && 'stepId' in stored) {
+          startData = stored.data as PathData;
+          if (stored.stepIndex > 0) restoreStepId = stored.stepId as string;
+        }
+      }
+      const p = start(path, startData);
+      if (restoreStepId) {
+        p.then(() => goToStep(restoreStepId!));
+      }
     }
   });
 
@@ -134,13 +211,20 @@
   }
 
   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');
 
   // Auto-detect footer layout: single-step top-level paths use "form", everything else uses "wizard"
   let resolvedFooterLayout = $derived(
-    footerLayout === 'auto' && snap
+    (layout === 'auto' || layout === 'tabs') && snap
       ? (snap.stepCount === 1 && snap.nestingLevel === 0 ? 'form' : 'wizard')
-      : (footerLayout === 'auto' ? 'wizard' : footerLayout)
+      : (layout === 'auto' || layout === 'tabs' ? 'wizard' : layout)
   );
 
   /**
@@ -153,7 +237,7 @@
    * ```
    */
   export function restart(): Promise<void> {
-    return pathReturn.restart(path, initialData);
+    return pathReturn.restart();
   }
 </script>
 
@@ -162,14 +246,43 @@
     <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}
     </div>
+  {:else if snap.status === 'completed'}
+    <!-- Completion panel: shown after stayOnFinal completion -->
+    {#if !effectiveHideProgress && snap.stepCount > 1}
+      <div class="pw-shell__header">
+        <div class="pw-shell__steps">
+          {#each snap.steps as step, i}
+            <div class="pw-shell__step pw-shell__step--{step.status}">
+              <span class="pw-shell__step-dot">✓</span>
+              <span class="pw-shell__step-label">{step.title ?? step.id}</span>
+            </div>
+          {/each}
+        </div>
+        <div class="pw-shell__track">
+          <div class="pw-shell__track-fill" style="width: 100%"></div>
+        </div>
+      </div>
+    {/if}
+    <div class="pw-shell__body">
+      {#if completion}
+        {@render completion(snap)}
+      {: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()}>
+            Start over
+          </button>
+        </div>
+      {/if}
+    </div>
   {:else}
     <!-- Root progress: persistent top-level bar visible during sub-paths -->
-    {#if !hideProgress && snap.rootProgress && progressLayout !== 'activeOnly'}
+    {#if !effectiveHideProgress && snap.rootProgress && progressLayout !== 'activeOnly'}
       <div class="pw-shell__root-progress">
         <div class="pw-shell__steps">
           {#each snap.rootProgress.steps as step, i}
@@ -188,7 +301,7 @@
     {/if}
 
     <!-- Header: progress indicator (overridable via header snippet) -->
-    {#if !hideProgress && progressLayout !== 'rootOnly'}
+    {#if !effectiveHideProgress && progressLayout !== 'rootOnly'}
       {#if header}
         {@render header(snap)}
       {:else if snap.stepCount > 1 || snap.nestingLevel > 0}
@@ -283,9 +396,9 @@
         </div>
       </div>
     <!-- Footer: navigation buttons (overridable via footer snippet) -->
-    {:else if !hideFooter && footer}
+    {:else if !effectiveHideFooter && footer}
       {@render footer(snap, actions)}
-    {:else if !hideFooter}
+    {:else if !effectiveHideFooter}
       <div class="pw-shell__footer">
         <div class="pw-shell__footer-left">
           {#if resolvedFooterLayout === 'form' && !hideCancel}

package/dist/PathShell.svelte.d.ts

@@ -1,9 +1,15 @@
-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>;
     engine?: PathEngine;
     initialData?: PathData;
+    /**
+     * When set, this shell automatically saves its state into the nearest outer `PathShell`'s
+     * data under this key on every change, and restores from that stored state on remount.
+     * No-op when used on a top-level shell with no outer `PathShell` ancestor.
+     */
+    restoreKey?: string;
     autoStart?: boolean;
     backLabel?: string;
     nextLabel?: string;
@@ -17,12 +23,13 @@ interface Props {
     /** When true, calls `validate()` on the engine so all steps show inline errors simultaneously. Useful when this shell is nested inside a step of an outer shell: bind to the outer snapshot's `hasAttemptedNext`. */
     validateWhen?: boolean;
     /**
-     * Footer layout mode:
+     * Shell layout mode:
      * - "auto" (default): Uses "form" for single-step top-level paths, "wizard" otherwise.
-     * - "wizard": Back button on left, Cancel and Submit together on right.
-     * - "form": Cancel on left, Submit alone on right. Back button never shown.
+     * - "wizard": Progress header + Back button on left, Cancel and Submit together on right.
+     * - "form": Progress header + Cancel on left, Submit alone on right. Back button never shown.
+     * - "tabs": No progress header, no footer. Use for tabbed interfaces with a custom tab bar inside the step body.
      */
-    footerLayout?: "wizard" | "form" | "auto";
+    layout?: "wizard" | "form" | "auto" | "tabs";
     /**
      * Controls whether the shell renders its auto-generated field-error summary box.
      * - `"summary"` (default): Shell renders the labeled error list below the step body.
@@ -47,7 +54,9 @@ 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;
 }
 declare const PathShell: Component<Props, {

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,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;;;;;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;AAqQH,QAAA,MAAM,SAAS;mBAhKQ,QAAQ,IAAI,CAAC;MAgKmB,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

@@ -77,6 +77,31 @@
   font-size: 14px;
 }
 
+/* ------------------------------------------------------------------ */
+/* Completion panel                                                    */
+/* ------------------------------------------------------------------ */
+.pw-shell__completion {
+  text-align: center;
+  padding: 40px 16px;
+}
+
+.pw-shell__completion-message {
+  font-size: 18px;
+  font-weight: 600;
+  color: var(--pw-color-text);
+  margin: 0 0 20px;
+}
+
+.pw-shell__completion-restart {
+  border: 1px solid var(--pw-color-btn-border);
+  background: var(--pw-color-btn-bg);
+  color: var(--pw-color-text);
+  padding: var(--pw-btn-padding);
+  border-radius: var(--pw-btn-radius);
+  cursor: pointer;
+  font-size: 14px;
+}
+
 /* ------------------------------------------------------------------ */
 /* Root progress — persistent top-level bar visible during sub-paths   */
 /* ------------------------------------------------------------------ */
@@ -332,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;
@@ -34,17 +40,22 @@ export interface UsePathReturn<TData extends PathData = PathData> {
     previous: () => Promise<void>;
     /** Cancel the active path (or sub-path). */
     cancel: () => Promise<void>;
-    /** Jump directly to a step by ID. Calls onLeave / onEnter but bypasses guards and shouldSkip. */
-    goToStep: (stepId: string) => Promise<void>;
+    /** Jump directly to a step by ID. Calls onLeave / onEnter but bypasses guards and shouldSkip. Pass `{ validateOnLeave: true }` to mark the departing step as attempted before navigating. */
+    goToStep: (stepId: string, options?: {
+        validateOnLeave?: boolean;
+    }) => Promise<void>;
     /** Jump directly to a step by ID, checking the current step's canMoveNext (forward) or canMovePrevious (backward) guard first. Navigation is blocked if the guard returns false. */
-    goToStepChecked: (stepId: string) => Promise<void>;
+    goToStepChecked: (stepId: string, options?: {
+        validateOnLeave?: boolean;
+    }) => 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.
+     * 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>;
@@ -110,24 +121,35 @@ 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>;
-    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>;
+    goToStep: (stepId: string, options?: {
+        validateOnLeave?: boolean;
+    }) => Promise<void>;
+    goToStepChecked: (stepId: string, options?: {
+        validateOnLeave?: boolean;
+    }) => 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;
 }
 /**
@@ -156,6 +178,13 @@ export declare function usePathContext<TData extends PathData = PathData, TServi
  * Used by PathShell component.
  */
 export declare function setPathContext<TData extends PathData = PathData, TServices = unknown>(ctx: PathContext<TData, TServices>): void;
+/**
+ * Internal: Get the PathContext from the nearest ancestor PathShell, or
+ * `undefined` if no PathShell is present. Used by PathShell itself to access
+ * the outer shell's context for `restoreKey` auto-wiring — must be called
+ * before `setPathContext()` so it reads the parent rather than self.
+ */
+export declare function getPathContextOrNull<TData extends PathData = PathData, TServices = unknown>(): PathContext<TData, TServices> | undefined;
 /**
  * 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

@@ -60,28 +60,43 @@ 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;
         }
         else if (event.type === "completed" || event.type === "cancelled") {
-            _snapshot = null;
+            _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();
     const previous = () => engine.previous();
     const cancel = () => engine.cancel();
-    const goToStep = (stepId) => engine.goToStep(stepId);
-    const goToStepChecked = (stepId) => engine.goToStepChecked(stepId);
+    const goToStep = (stepId, options) => engine.goToStep(stepId, options);
+    const goToStepChecked = (stepId, options) => engine.goToStepChecked(stepId, options);
     const setData = ((key, value) => engine.setData(key, value));
     const resetStep = () => engine.resetStep();
     const restart = () => engine.restart();
@@ -144,6 +159,15 @@ export function usePathContext() {
 export function setPathContext(ctx) {
     setContext(PATH_CONTEXT_KEY, ctx);
 }
+/**
+ * Internal: Get the PathContext from the nearest ancestor PathShell, or
+ * `undefined` if no PathShell is present. Used by PathShell itself to access
+ * the outer shell's context for `restoreKey` auto-wiring — must be called
+ * before `setPathContext()` so it reads the parent rather than self.
+ */
+export function getPathContextOrNull() {
+    return getContext(PATH_CONTEXT_KEY);
+}
 // ---------------------------------------------------------------------------
 // Helper for binding form inputs
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daltonr/pathwrite-svelte",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "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.11.0"
+    "@daltonr/pathwrite-core": "^0.13.0"
   },
   "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, formatFieldKey, errorPhaseMessage, stepIdToCamelCase } from './index.svelte.js';
-  import type { PathDefinition, PathData, PathEngine, PathSnapshot, ProgressLayout } from './index.svelte.js';
+  import { usePath, setPathContext, getPathContextOrNull, formatFieldKey, errorPhaseMessage, stepIdToCamelCase } 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';
 
 
@@ -9,6 +11,12 @@
     path?: PathDefinition<any>;
     engine?: PathEngine;
     initialData?: PathData;
+    /**
+     * When set, this shell automatically saves its state into the nearest outer `PathShell`'s
+     * data under this key on every change, and restores from that stored state on remount.
+     * No-op when used on a top-level shell with no outer `PathShell` ancestor.
+     */
+    restoreKey?: string;
     autoStart?: boolean;
     backLabel?: string;
     nextLabel?: string;
@@ -22,12 +30,13 @@
     /** When true, calls `validate()` on the engine so all steps show inline errors simultaneously. Useful when this shell is nested inside a step of an outer shell: bind to the outer snapshot's `hasAttemptedNext`. */
     validateWhen?: boolean;
     /**
-     * Footer layout mode:
+     * Shell layout mode:
      * - "auto" (default): Uses "form" for single-step top-level paths, "wizard" otherwise.
-     * - "wizard": Back button on left, Cancel and Submit together on right.
-     * - "form": Cancel on left, Submit alone on right. Back button never shown.
+     * - "wizard": Progress header + Back button on left, Cancel and Submit together on right.
+     * - "form": Progress header + Cancel on left, Submit alone on right. Back button never shown.
+     * - "tabs": No progress header, no footer. Use for tabbed interfaces with a custom tab bar inside the step body.
      */
-    footerLayout?: "wizard" | "form" | "auto";
+    layout?: "wizard" | "form" | "auto" | "tabs";
     /**
      * Controls whether the shell renders its auto-generated field-error summary box.
      * - `"summary"` (default): Shell renders the labeled error list below the step body.
@@ -54,7 +63,9 @@
     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
     [key: string]: Component<any> | any;
   }
@@ -63,6 +74,7 @@
     path,
     engine: engineProp,
     initialData = {},
+    restoreKey = undefined,
     autoStart = true,
     backLabel = 'Previous',
     nextLabel = 'Next',
@@ -73,7 +85,7 @@
     hideProgress = false,
     hideFooter = false,
     validateWhen = false,
-    footerLayout = 'auto',
+    layout = 'auto',
     validationDisplay = 'summary',
     progressLayout = 'merged',
     services = null,
@@ -82,42 +94,107 @@
     onevent,
     header,
     footer,
+    completion,
     ...stepSnippets
   }: Props = $props();
 
+  // Read outer PathShell context BEFORE setting our own — gives access to
+  // 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, 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; },
   });
 
+  // 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. 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) {
+        console.warn(
+          `[PathShell] "${name}" was passed but will be ignored. Svelte uses lowercase callback props — use "${name.toLowerCase()}" instead.`
+        );
+      }
+    }
+  });
+
   // 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;
-      start(path, initialData);
+      let startData: PathData = initialData ?? {};
+      let restoreStepId: string | undefined;
+      if (restoreKey && outerCtx) {
+        const stored = outerCtx.snapshot?.data[restoreKey] as PathSnapshot<any> | undefined;
+        if (stored != null && typeof stored === 'object' && 'stepId' in stored) {
+          startData = stored.data as PathData;
+          if (stored.stepIndex > 0) restoreStepId = stored.stepId as string;
+        }
+      }
+      const p = start(path, startData);
+      if (restoreStepId) {
+        p.then(() => goToStep(restoreStepId!));
+      }
     }
   });
 
@@ -134,13 +211,20 @@
   }
 
   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');
 
   // Auto-detect footer layout: single-step top-level paths use "form", everything else uses "wizard"
   let resolvedFooterLayout = $derived(
-    footerLayout === 'auto' && snap
+    (layout === 'auto' || layout === 'tabs') && snap
       ? (snap.stepCount === 1 && snap.nestingLevel === 0 ? 'form' : 'wizard')
-      : (footerLayout === 'auto' ? 'wizard' : footerLayout)
+      : (layout === 'auto' || layout === 'tabs' ? 'wizard' : layout)
   );
 
   /**
@@ -153,7 +237,7 @@
    * ```
    */
   export function restart(): Promise<void> {
-    return pathReturn.restart(path, initialData);
+    return pathReturn.restart();
   }
 </script>
 
@@ -162,14 +246,43 @@
     <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}
     </div>
+  {:else if snap.status === 'completed'}
+    <!-- Completion panel: shown after stayOnFinal completion -->
+    {#if !effectiveHideProgress && snap.stepCount > 1}
+      <div class="pw-shell__header">
+        <div class="pw-shell__steps">
+          {#each snap.steps as step, i}
+            <div class="pw-shell__step pw-shell__step--{step.status}">
+              <span class="pw-shell__step-dot">✓</span>
+              <span class="pw-shell__step-label">{step.title ?? step.id}</span>
+            </div>
+          {/each}
+        </div>
+        <div class="pw-shell__track">
+          <div class="pw-shell__track-fill" style="width: 100%"></div>
+        </div>
+      </div>
+    {/if}
+    <div class="pw-shell__body">
+      {#if completion}
+        {@render completion(snap)}
+      {: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()}>
+            Start over
+          </button>
+        </div>
+      {/if}
+    </div>
   {:else}
     <!-- Root progress: persistent top-level bar visible during sub-paths -->
-    {#if !hideProgress && snap.rootProgress && progressLayout !== 'activeOnly'}
+    {#if !effectiveHideProgress && snap.rootProgress && progressLayout !== 'activeOnly'}
       <div class="pw-shell__root-progress">
         <div class="pw-shell__steps">
           {#each snap.rootProgress.steps as step, i}
@@ -188,7 +301,7 @@
     {/if}
 
     <!-- Header: progress indicator (overridable via header snippet) -->
-    {#if !hideProgress && progressLayout !== 'rootOnly'}
+    {#if !effectiveHideProgress && progressLayout !== 'rootOnly'}
       {#if header}
         {@render header(snap)}
       {:else if snap.stepCount > 1 || snap.nestingLevel > 0}
@@ -283,9 +396,9 @@
         </div>
       </div>
     <!-- Footer: navigation buttons (overridable via footer snippet) -->
-    {:else if !hideFooter && footer}
+    {:else if !effectiveHideFooter && footer}
       {@render footer(snap, actions)}
-    {:else if !hideFooter}
+    {:else if !effectiveHideFooter}
       <div class="pw-shell__footer">
         <div class="pw-shell__footer-left">
           {#if resolvedFooterLayout === 'form' && !hideCancel}

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;
@@ -62,17 +68,18 @@ export interface UsePathReturn<TData extends PathData = PathData> {
   previous: () => Promise<void>;
   /** Cancel the active path (or sub-path). */
   cancel: () => Promise<void>;
-  /** Jump directly to a step by ID. Calls onLeave / onEnter but bypasses guards and shouldSkip. */
-  goToStep: (stepId: string) => Promise<void>;
+  /** Jump directly to a step by ID. Calls onLeave / onEnter but bypasses guards and shouldSkip. Pass `{ validateOnLeave: true }` to mark the departing step as attempted before navigating. */
+  goToStep: (stepId: string, options?: { validateOnLeave?: boolean }) => Promise<void>;
   /** Jump directly to a step by ID, checking the current step's canMoveNext (forward) or canMovePrevious (backward) guard first. Navigation is blocked if the guard returns false. */
-  goToStepChecked: (stepId: string) => Promise<void>;
+  goToStepChecked: (stepId: string, options?: { validateOnLeave?: boolean }) => 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.
+   * 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 = null;
+      _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);
@@ -178,8 +200,8 @@ export function usePath<TData extends PathData = PathData>(
   const previous = (): Promise<void> => engine.previous();
   const cancel = (): Promise<void> => engine.cancel();
 
-  const goToStep = (stepId: string): Promise<void> => engine.goToStep(stepId);
-  const goToStepChecked = (stepId: string): Promise<void> => engine.goToStepChecked(stepId);
+  const goToStep = (stepId: string, options?: { validateOnLeave?: boolean }): Promise<void> => engine.goToStep(stepId, options);
+  const goToStepChecked = (stepId: string, options?: { validateOnLeave?: boolean }): Promise<void> => engine.goToStepChecked(stepId, options);
 
   const setData = (<K extends string & keyof TData>(key: K, value: TData[K]): Promise<void> =>
     engine.setData(key, value as unknown)) as UsePathReturn<TData>["setData"];
@@ -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) => Promise<void>;
-  goToStepChecked: (stepId: string) => Promise<void>;
-  setData: <K extends string & keyof TData>(key: K, value: TData[K]) => Promise<void>;
-  resetStep: () => Promise<void>;
+  goToStep: (stepId: string, options?: { validateOnLeave?: boolean }) => Promise<void>;
+  goToStepChecked: (stepId: string, options?: { validateOnLeave?: boolean }) => 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;
 }
 
@@ -276,6 +306,16 @@ export function setPathContext<TData extends PathData = PathData, TServices = un
   setContext(PATH_CONTEXT_KEY, ctx);
 }
 
+/**
+ * Internal: Get the PathContext from the nearest ancestor PathShell, or
+ * `undefined` if no PathShell is present. Used by PathShell itself to access
+ * the outer shell's context for `restoreKey` auto-wiring — must be called
+ * before `setPathContext()` so it reads the parent rather than self.
+ */
+export function getPathContextOrNull<TData extends PathData = PathData, TServices = unknown>(): PathContext<TData, TServices> | undefined {
+  return getContext<PathContext<TData, TServices>>(PATH_CONTEXT_KEY);
+}
+
 // ---------------------------------------------------------------------------
 // Helper for binding form inputs
 // ---------------------------------------------------------------------------