@daltonr/pathwrite-angular 0.8.0 → 0.10.0

package/README.md

@@ -410,7 +410,7 @@ import {
 @Component({
   imports: [PathShellComponent, PathStepDirective],
   template: `
-    <pw-shell [path]="myPath" [initialData]="{ name: '' }" (completed)="onDone($event)">
+    <pw-shell [path]="myPath" [initialData]="{ name: '' }" (complete)="onDone($event)">
       <ng-template pwStep="details"><app-details-form /></ng-template>
       <ng-template pwStep="review"><app-review-panel /></ng-template>
     </pw-shell>
@@ -484,7 +484,7 @@ The parent component hosting `<pw-shell>` does **not** need its own
 @Component({
   imports: [PathShellComponent, PathStepDirective],
   template: `
-    <pw-shell #shell [path]="myPath" (completed)="onDone($event)">
+    <pw-shell #shell [path]="myPath" (complete)="onDone($event)">
       <ng-template pwStep="details"><app-details-form /></ng-template>
     </pw-shell>
   `
@@ -499,9 +499,10 @@ export class MyComponent {
 
 | Input | Type | Default | Description |
 |-------|------|---------|-------------|
-| `path` | `PathDefinition` | *required* | The path definition to drive. |
+| `path` | `PathDefinition` | — | The path definition to drive. Required unless `[engine]` is provided. |
+| `engine` | `PathEngine` | — | An externally-managed engine (e.g. from `restoreOrStart()`). When provided, `autoStart` is suppressed and the shell immediately reflects the engine's current state. Use `@if (engine)` in the parent template to gate mounting until the engine is ready. |
 | `initialData` | `PathData` | `{}` | Initial data passed to `facade.start()`. |
-| `autoStart` | `boolean` | `true` | Start the path automatically on `ngOnInit`. |
+| `autoStart` | `boolean` | `true` | Start the path automatically on `ngOnInit`. Ignored when `[engine]` is provided. |
 | `backLabel` | `string` | `"Previous"` | Previous button label. |
 | `nextLabel` | `string` | `"Next"` | Next button label. |
 | `completeLabel` | `string` | `"Complete"` | Complete button label (last step). |
@@ -514,9 +515,9 @@ export class MyComponent {
 
 | Output | Payload | Description |
 |--------|---------|-------------|
-| `(completed)` | `PathData` | Emitted when the path finishes naturally. |
-| `(cancelled)` | `PathData` | Emitted when the path is cancelled. |
-| `(pathEvent)` | `PathEvent` | Emitted for every engine event. |
+| `(complete)` | `PathData` | Emitted when the path finishes naturally. |
+| `(cancel)` | `PathData` | Emitted when the path is cancelled. |
+| `(event)` | `PathEvent` | Emitted for every engine event. |
 
 ### Customising the header and footer
 
@@ -576,7 +577,7 @@ Toggle an `@if` flag to destroy and recreate the shell. Every child component re
 
 ```html
 @if (isActive) {
-  <pw-shell [path]="myPath" (completed)="isActive = false" (cancelled)="isActive = false">
+  <pw-shell [path]="myPath" (complete)="isActive = false" (cancel)="isActive = false">
     <ng-template pwStep="details"><app-details-form /></ng-template>
   </pw-shell>
 } @else {
@@ -589,7 +590,7 @@ Toggle an `@if` flag to destroy and recreate the shell. Every child component re
 Use the existing `#shell` template reference — `restart()` is a public method:
 
 ```html
-<pw-shell #shell [path]="myPath" (completed)="onDone($event)">
+<pw-shell #shell [path]="myPath" (complete)="onDone($event)">
   <ng-template pwStep="details"><app-details-form /></ng-template>
 </pw-shell>
 
@@ -872,24 +873,24 @@ Use it to distinguish initialization from re-entry:
 
 ## Persistence
 
-Use with [@daltonr/pathwrite-store-http](../store-http) for automatic state persistence. The engine is created externally via `restoreOrStart()`, then handed to the facade via `adoptEngine()`.
+Use with [@daltonr/pathwrite-store](../store) for automatic state persistence. The engine is created externally via `restoreOrStart()` and passed directly to `<pw-shell>` via the `[engine]` input.
 
 ### Simple persistence example
 
 ```typescript
-import { Component, inject, OnInit } from '@angular/core';
-import { PathFacade, PathShellComponent, PathStepDirective } from '@daltonr/pathwrite-angular';
-import { HttpStore, restoreOrStart, httpPersistence } from '@daltonr/pathwrite-store-http';
+import { Component, OnInit } from '@angular/core';
+import { PathEngine } from '@daltonr/pathwrite-angular';
+import { PathShellComponent, PathStepDirective } from '@daltonr/pathwrite-angular/shell';
+import { HttpStore, restoreOrStart, persistence } from '@daltonr/pathwrite-store';
 import { signupPath } from './signup-path';
 
 @Component({
   selector: 'app-signup-wizard',
   standalone: true,
   imports: [PathShellComponent, PathStepDirective],
-  providers: [PathFacade],
   template: `
-    @if (ready) {
-      <pw-shell [path]="path" [autoStart]="false" (completed)="onComplete($event)">
+    @if (engine) {
+      <pw-shell [path]="path" [engine]="engine" (complete)="onComplete($event)">
         <ng-template pwStep="details"><app-details-form /></ng-template>
         <ng-template pwStep="review"><app-review-panel /></ng-template>
       </pw-shell>
@@ -899,10 +900,8 @@ import { signupPath } from './signup-path';
   `
 })
 export class SignupWizardComponent implements OnInit {
-  private readonly facade = inject(PathFacade);
-
   path = signupPath;
-  ready = false;
+  engine: PathEngine | null = null;
 
   async ngOnInit() {
     const store = new HttpStore({ baseUrl: '/api/wizard' });
@@ -914,14 +913,11 @@ export class SignupWizardComponent implements OnInit {
       path: this.path,
       initialData: { name: '', email: '' },
       observers: [
-        httpPersistence({ store, key, strategy: 'onNext' })
+        persistence({ store, key, strategy: 'onNext' })
       ]
     });
 
-    // Hand the running engine to the facade — it immediately
-    // reflects the engine's current state and forwards all events.
-    this.facade.adoptEngine(engine);
-    this.ready = true;
+    this.engine = engine;
 
     if (restored) {
       console.log('Progress restored — resuming from', engine.snapshot()?.stepId);
@@ -936,9 +932,8 @@ export class SignupWizardComponent implements OnInit {
 
 ### Key points
 
-- **`adoptEngine()`** connects the facade to an externally-created engine. No `@ViewChild` or shell reference needed — inject `PathFacade` directly.
-- **`[autoStart]="false"`** prevents the shell from calling `start()` on its own — the engine is already running.
-- **The facade is the same one the shell uses** (provided in the component's `providers`), so the shell's template bindings, progress indicator, and navigation buttons all work automatically.
+- **`[engine]`** passes an externally-managed engine directly to the shell. The shell adopts it immediately and skips `autoStart`.
+- **`@if (engine)`** acts as the async gate — the shell only mounts once the engine is ready, so there is no timing window where `autoStart` could fire before the engine arrives.
 - **`restoreOrStart()`** handles the load-or-create logic: if saved state exists on the server, it restores the engine mid-flow; otherwise it starts fresh.
 
 ---

package/dist/index.css

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

package/dist/index.d.ts

@@ -29,7 +29,7 @@ export declare class PathFacade<TData extends PathData = PathData> implements On
     constructor();
     /**
      * Adopt an externally-managed `PathEngine` — for example, the engine returned
-     * by `restoreOrStart()` from `@daltonr/pathwrite-store-http`.
+     * by `restoreOrStart()` from `@daltonr/pathwrite-store`.
      *
      * The facade immediately reflects the engine's current state and forwards all
      * subsequent events. The **caller** is responsible for the engine's lifecycle
@@ -50,7 +50,11 @@ export declare class PathFacade<TData extends PathData = PathData> implements On
      * Use for "Start over" / retry flows without destroying and re-creating the
      * component that provides this facade.
      */
-    restart(path: PathDefinition<any>, initialData?: PathData): Promise<void>;
+    restart(): Promise<void>;
+    /** Re-runs the operation that set `snapshot().error`. Increments `retryCount` on repeated failure. No-op when there is no pending error. */
+    retry(): Promise<void>;
+    /** Pauses the path with intent to return. Emits `suspended`. All state is preserved. */
+    suspend(): Promise<void>;
     startSubPath(path: PathDefinition<any>, initialData?: PathData, meta?: Record<string, unknown>): Promise<void>;
     next(): Promise<void>;
     previous(): Promise<void>;
@@ -69,11 +73,11 @@ export declare class PathFacade<TData extends PathData = PathData> implements On
     static ɵprov: i0.ɵɵInjectableDeclaration<PathFacade<any>>;
 }
 /**
- * Return type of `injectPath()`. Provides signal-based reactive access to the
+ * Return type of `usePathContext()`. Provides signal-based reactive access to the
  * path state and strongly-typed navigation actions. Mirrors React's `usePathContext()`
  * return type for consistency across adapters.
  */
-export interface InjectPathReturn<TData extends PathData = PathData> {
+export interface UsePathContextReturn<TData extends PathData = PathData> {
     /** Current path snapshot as a signal. Returns `null` when no path is active. */
     snapshot: Signal<PathSnapshot<TData> | null>;
     /** Start (or restart) a path. */
@@ -98,16 +102,20 @@ export interface InjectPathReturn<TData extends PathData = PathData> {
      * Tears down any active path and immediately starts the given path fresh.
      * Use for "Start over" / retry flows.
      */
-    restart: (path: PathDefinition<any>, initialData?: PathData) => Promise<void>;
+    restart: () => Promise<void>;
+    /** Re-run the operation that set `snapshot().error`. */
+    retry: () => Promise<void>;
+    /** Pause with intent to return, preserving all state. Emits `suspended`. */
+    suspend: () => Promise<void>;
 }
 /**
- * Inject a PathFacade and return a signal-based API for use in Angular components.
+ * Access the nearest `PathFacade`'s path instance for use in Angular step components.
  * Requires `PathFacade` to be provided in the component's injector tree (either via
  * `providers: [PathFacade]` in the component or a parent component).
  *
  * **This is the recommended way to consume Pathwrite in Angular components** — it
- * provides the same ergonomic, framework-native API that React's `usePathContext()`
- * and Vue's `usePath()` offer. No template references or manual facade injection needed.
+ * provides the same ergonomic API as React's `usePathContext()` and Vue's `usePathContext()`.
+ * No template references or manual facade injection needed.
  *
  * The optional generic `TData` narrows `snapshot().data` and `setData()` to your
  * data shape. It is a **type-level assertion**, not a runtime guarantee.
@@ -126,7 +134,7 @@ export interface InjectPathReturn<TData extends PathData = PathData> {
  *   `
  * })
  * export class ContactStepComponent {
- *   protected readonly path = injectPath<ContactData>();
+ *   protected readonly path = usePathContext<ContactData>();
  *
  *   updateName(name: string) {
  *     this.path.setData('name', name);
@@ -136,7 +144,7 @@ export interface InjectPathReturn<TData extends PathData = PathData> {
  *
  * @throws Error if PathFacade is not provided in the injector tree
  */
-export declare function injectPath<TData extends PathData = PathData>(): InjectPathReturn<TData>;
+export declare function usePathContext<TData extends PathData = PathData>(): UsePathContextReturn<TData>;
 /**
  * Minimal interface describing what syncFormGroup needs from an Angular
  * FormGroup. Typed as a duck interface so that @angular/forms is not a

package/dist/index.js

@@ -31,7 +31,7 @@ export class PathFacade {
     }
     /**
      * Adopt an externally-managed `PathEngine` — for example, the engine returned
-     * by `restoreOrStart()` from `@daltonr/pathwrite-store-http`.
+     * by `restoreOrStart()` from `@daltonr/pathwrite-store`.
      *
      * The facade immediately reflects the engine's current state and forwards all
      * subsequent events. The **caller** is responsible for the engine's lifecycle
@@ -80,8 +80,16 @@ export class PathFacade {
      * Use for "Start over" / retry flows without destroying and re-creating the
      * component that provides this facade.
      */
-    restart(path, initialData = {}) {
-        return this._engine.restart(path, initialData);
+    restart() {
+        return this._engine.restart();
+    }
+    /** Re-runs the operation that set `snapshot().error`. Increments `retryCount` on repeated failure. No-op when there is no pending error. */
+    retry() {
+        return this._engine.retry();
+    }
+    /** Pauses the path with intent to return. Emits `suspended`. All state is preserved. */
+    suspend() {
+        return this._engine.suspend();
     }
     startSubPath(path, initialData = {}, meta) {
         return this._engine.startSubPath(path, initialData, meta);
@@ -122,13 +130,13 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
             type: Injectable
         }], ctorParameters: () => [] });
 /**
- * Inject a PathFacade and return a signal-based API for use in Angular components.
+ * Access the nearest `PathFacade`'s path instance for use in Angular step components.
  * Requires `PathFacade` to be provided in the component's injector tree (either via
  * `providers: [PathFacade]` in the component or a parent component).
  *
  * **This is the recommended way to consume Pathwrite in Angular components** — it
- * provides the same ergonomic, framework-native API that React's `usePathContext()`
- * and Vue's `usePath()` offer. No template references or manual facade injection needed.
+ * provides the same ergonomic API as React's `usePathContext()` and Vue's `usePathContext()`.
+ * No template references or manual facade injection needed.
  *
  * The optional generic `TData` narrows `snapshot().data` and `setData()` to your
  * data shape. It is a **type-level assertion**, not a runtime guarantee.
@@ -147,7 +155,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
  *   `
  * })
  * export class ContactStepComponent {
- *   protected readonly path = injectPath<ContactData>();
+ *   protected readonly path = usePathContext<ContactData>();
  *
  *   updateName(name: string) {
  *     this.path.setData('name', name);
@@ -157,10 +165,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
  *
  * @throws Error if PathFacade is not provided in the injector tree
  */
-export function injectPath() {
+export function usePathContext() {
     const facade = inject(PathFacade, { optional: true });
     if (!facade) {
-        throw new Error("injectPath() requires PathFacade to be provided. " +
+        throw new Error("usePathContext() requires PathFacade to be provided. " +
             "Add 'providers: [PathFacade]' to your component or a parent component.");
     }
     return {
@@ -174,7 +182,9 @@ export function injectPath() {
         resetStep: () => facade.resetStep(),
         goToStep: (stepId) => facade.goToStep(stepId),
         goToStepChecked: (stepId) => facade.goToStepChecked(stepId),
-        restart: (path, initialData = {}) => facade.restart(path, initialData),
+        restart: () => facade.restart(),
+        retry: () => facade.retry(),
+        suspend: () => facade.suspend(),
     };
 }
 /**

package/dist/index.js.map

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

package/dist/shell.d.ts

@@ -1,5 +1,5 @@
-import { TemplateRef, EventEmitter, QueryList, OnInit, OnDestroy, Injector } from "@angular/core";
-import { PathData, PathDefinition, PathEvent, PathSnapshot, ProgressLayout } from "@daltonr/pathwrite-core";
+import { TemplateRef, EventEmitter, QueryList, OnInit, OnChanges, OnDestroy, SimpleChanges, Injector } from "@angular/core";
+import { PathData, PathDefinition, PathEngine, PathEvent, PathSnapshot, ProgressLayout, formatFieldKey, errorPhaseMessage } from "@daltonr/pathwrite-core";
 import { PathFacade } from "./index";
 import * as i0 from "@angular/core";
 /**
@@ -16,6 +16,10 @@ export interface PathShellActions {
     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>;
 }
 /**
  * Structural directive that associates a template with a step ID.
@@ -90,15 +94,30 @@ export declare class PathShellFooterDirective {
  * and navigation buttons.
  *
  * ```html
- * <pw-shell [path]="myPath" [initialData]="{ name: '' }" (completed)="onDone($event)">
+ * <pw-shell [path]="myPath" [initialData]="{ name: '' }" (complete)="onDone($event)">
  *   <ng-template pwStep="details"><app-details-form /></ng-template>
  *   <ng-template pwStep="review"><app-review-panel /></ng-template>
  * </pw-shell>
  * ```
  */
-export declare class PathShellComponent implements OnInit, OnDestroy {
-    /** The path definition to run. Required. */
-    path: PathDefinition<any>;
+export declare class PathShellComponent implements OnInit, OnChanges, OnDestroy {
+    /** The path definition to run. Required unless [engine] is provided. */
+    path?: PathDefinition<any>;
+    /**
+     * An externally-managed `PathEngine` to adopt — for example, the engine
+     * returned by `restoreOrStart()` from `@daltonr/pathwrite-store`.
+     *
+     * When provided the shell skips `autoStart` and immediately reflects the
+     * engine's current state. Gate the shell's existence on the engine being
+     * ready using `@if (engine)` so the input is always non-null on mount:
+     *
+     * ```html
+     * @if (engine) {
+     *   <pw-shell [engine]="engine" [path]="myPath" ...></pw-shell>
+     * }
+     * ```
+     */
+    engine?: PathEngine;
     /** Initial data merged into the path engine on start. */
     initialData: PathData;
     /** Start the path automatically on ngOnInit. Set to false to call doStart() manually. */
@@ -109,6 +128,8 @@ export declare class PathShellComponent implements OnInit, OnDestroy {
     nextLabel: string;
     /** Label for the Next button when on the last step. */
     completeLabel: string;
+    /** Label shown on the Next/Complete button while an async operation is in progress. When undefined, the button keeps its label and shows a CSS spinner only. */
+    loadingLabel?: string;
     /** Label for the Cancel button. */
     cancelLabel: string;
     /** Hide the Cancel button entirely. */
@@ -137,9 +158,9 @@ export declare class PathShellComponent implements OnInit, OnDestroy {
      * - "activeOnly": Only the active (sub-path) bar — root bar hidden.
      */
     progressLayout: ProgressLayout;
-    completed: EventEmitter<PathData>;
-    cancelled: EventEmitter<PathData>;
-    pathEvent: EventEmitter<PathEvent>;
+    complete: EventEmitter<PathData>;
+    cancel: EventEmitter<PathData>;
+    event: EventEmitter<PathEvent>;
     stepDirectives: QueryList<PathStepDirective>;
     customHeader?: PathShellHeaderDirective;
     customFooter?: PathShellFooterDirective;
@@ -151,6 +172,7 @@ export declare class PathShellComponent implements OnInit, OnDestroy {
     /** Navigation actions passed to custom `pwShellFooter` templates. */
     protected readonly shellActions: PathShellActions;
     private readonly destroy$;
+    ngOnChanges(changes: SimpleChanges): void;
     ngOnInit(): void;
     ngOnDestroy(): void;
     doStart(): void;
@@ -170,9 +192,8 @@ export declare class PathShellComponent implements OnInit, OnDestroy {
     protected warningEntries(s: PathSnapshot): [string, string][];
     /** Resolves "auto" footerLayout based on snapshot. Single-step top-level → "form", otherwise → "wizard". */
     protected getResolvedFooterLayout(s: PathSnapshot): "wizard" | "form";
-    /** Converts a camelCase or lowercase field key to a display label.
-     *  e.g. "firstName" → "First Name", "email" → "Email" */
-    protected formatFieldKey(key: string): string;
+    protected errorPhaseMessage: typeof errorPhaseMessage;
+    protected formatFieldKey: typeof formatFieldKey;
     static ɵfac: i0.ɵɵFactoryDeclaration<PathShellComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<PathShellComponent, "pw-shell", never, { "path": { "alias": "path"; "required": true; }; "initialData": { "alias": "initialData"; "required": false; }; "autoStart": { "alias": "autoStart"; "required": false; }; "backLabel": { "alias": "backLabel"; "required": false; }; "nextLabel": { "alias": "nextLabel"; "required": false; }; "completeLabel": { "alias": "completeLabel"; "required": false; }; "cancelLabel": { "alias": "cancelLabel"; "required": false; }; "hideCancel": { "alias": "hideCancel"; "required": false; }; "hideProgress": { "alias": "hideProgress"; "required": false; }; "footerLayout": { "alias": "footerLayout"; "required": false; }; "validationDisplay": { "alias": "validationDisplay"; "required": false; }; "progressLayout": { "alias": "progressLayout"; "required": false; }; }, { "completed": "completed"; "cancelled": "cancelled"; "pathEvent": "pathEvent"; }, ["customHeader", "customFooter", "stepDirectives"], never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<PathShellComponent, "pw-shell", never, { "path": { "alias": "path"; "required": false; }; "engine": { "alias": "engine"; "required": false; }; "initialData": { "alias": "initialData"; "required": false; }; "autoStart": { "alias": "autoStart"; "required": false; }; "backLabel": { "alias": "backLabel"; "required": false; }; "nextLabel": { "alias": "nextLabel"; "required": false; }; "completeLabel": { "alias": "completeLabel"; "required": false; }; "loadingLabel": { "alias": "loadingLabel"; "required": false; }; "cancelLabel": { "alias": "cancelLabel"; "required": false; }; "hideCancel": { "alias": "hideCancel"; "required": false; }; "hideProgress": { "alias": "hideProgress"; "required": false; }; "footerLayout": { "alias": "footerLayout"; "required": false; }; "validationDisplay": { "alias": "validationDisplay"; "required": false; }; "progressLayout": { "alias": "progressLayout"; "required": false; }; }, { "complete": "complete"; "cancel": "cancel"; "event": "event"; }, ["customHeader", "customFooter", "stepDirectives"], never, true, never>;
 }

package/dist/shell.js

@@ -2,6 +2,7 @@ import { Component, Directive, Input, Output, EventEmitter, ContentChild, Conten
 import { CommonModule } from "@angular/common";
 import { Subject } from "rxjs";
 import { takeUntil } from "rxjs/operators";
+import { formatFieldKey, errorPhaseMessage, } from "@daltonr/pathwrite-core";
 import { PathFacade } from "./index";
 import * as i0 from "@angular/core";
 import * as i1 from "@angular/common";
@@ -97,7 +98,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
  * and navigation buttons.
  *
  * ```html
- * <pw-shell [path]="myPath" [initialData]="{ name: '' }" (completed)="onDone($event)">
+ * <pw-shell [path]="myPath" [initialData]="{ name: '' }" (complete)="onDone($event)">
  *   <ng-template pwStep="details"><app-details-form /></ng-template>
  *   <ng-template pwStep="review"><app-review-panel /></ng-template>
  * </pw-shell>
@@ -134,7 +135,7 @@ export class PathShellComponent {
          * - `"inline"`: Suppress the summary — handle errors inside the step template instead.
          * - `"both"`: Render the shell summary AND whatever the step template renders.
          */
-        this.validationDisplay = "inline";
+        this.validationDisplay = "summary";
         /**
          * Controls how progress bars are arranged when a sub-path is active.
          * - "merged" (default): Root and sub-path bars in one card.
@@ -143,9 +144,9 @@ export class PathShellComponent {
          * - "activeOnly": Only the active (sub-path) bar — root bar hidden.
          */
         this.progressLayout = "merged";
-        this.completed = new EventEmitter();
-        this.cancelled = new EventEmitter();
-        this.pathEvent = new EventEmitter();
+        this.complete = new EventEmitter();
+        this.cancel = new EventEmitter();
+        this.event = new EventEmitter();
         this.facade = inject(PathFacade);
         /** The shell's own component-level injector. Passed to ngTemplateOutlet so that
          *  step components can resolve PathFacade (provided by this shell) via inject(). */
@@ -159,19 +160,28 @@ export class PathShellComponent {
             goToStep: (id) => this.facade.goToStep(id),
             goToStepChecked: (id) => this.facade.goToStepChecked(id),
             setData: (key, value) => this.facade.setData(key, value),
-            restart: () => this.facade.restart(this.path, this.initialData),
+            restart: () => this.facade.restart(),
+            retry: () => this.facade.retry(),
+            suspend: () => this.facade.suspend(),
         };
         this.destroy$ = new Subject();
+        this.errorPhaseMessage = errorPhaseMessage;
+        this.formatFieldKey = formatFieldKey;
+    }
+    ngOnChanges(changes) {
+        if (changes['engine'] && this.engine) {
+            this.facade.adoptEngine(this.engine);
+        }
     }
     ngOnInit() {
         this.facade.events$.pipe(takeUntil(this.destroy$)).subscribe((event) => {
-            this.pathEvent.emit(event);
+            this.event.emit(event);
             if (event.type === "completed")
-                this.completed.emit(event.data);
+                this.complete.emit(event.data);
             if (event.type === "cancelled")
-                this.cancelled.emit(event.data);
+                this.cancel.emit(event.data);
         });
-        if (this.autoStart) {
+        if (this.autoStart && !this.engine) {
             this.doStart();
         }
     }
@@ -180,6 +190,8 @@ export class PathShellComponent {
         this.destroy$.complete();
     }
     doStart() {
+        if (!this.path)
+            throw new Error('[pw-shell] [path] is required when no [engine] is provided');
         this.started = true;
         this.facade.start(this.path, this.initialData);
     }
@@ -193,7 +205,7 @@ export class PathShellComponent {
      * ```
      */
     restart() {
-        return this.facade.restart(this.path, this.initialData);
+        return this.facade.restart();
     }
     /** Returns Object.entries(s.fieldErrors) for use in *ngFor. */
     fieldEntries(s) {
@@ -209,13 +221,8 @@ export class PathShellComponent {
             ? (s.stepCount === 1 && s.nestingLevel === 0 ? "form" : "wizard")
             : this.footerLayout;
     }
-    /** Converts a camelCase or lowercase field key to a display label.
-     *  e.g. "firstName" → "First Name", "email" → "Email" */
-    formatFieldKey(key) {
-        return key.replace(/([A-Z])/g, " $1").replace(/^./, c => c.toUpperCase()).trim();
-    }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: PathShellComponent, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
-    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "17.3.12", type: PathShellComponent, isStandalone: true, selector: "pw-shell", inputs: { path: "path", initialData: "initialData", autoStart: "autoStart", backLabel: "backLabel", nextLabel: "nextLabel", completeLabel: "completeLabel", cancelLabel: "cancelLabel", hideCancel: "hideCancel", hideProgress: "hideProgress", footerLayout: "footerLayout", validationDisplay: "validationDisplay", progressLayout: "progressLayout" }, outputs: { completed: "completed", cancelled: "cancelled", pathEvent: "pathEvent" }, providers: [PathFacade], queries: [{ propertyName: "customHeader", first: true, predicate: PathShellHeaderDirective, descendants: true }, { propertyName: "customFooter", first: true, predicate: PathShellFooterDirective, descendants: true }, { propertyName: "stepDirectives", predicate: PathStepDirective }], ngImport: i0, template: `
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "17.3.12", type: PathShellComponent, isStandalone: true, selector: "pw-shell", inputs: { path: "path", engine: "engine", initialData: "initialData", autoStart: "autoStart", backLabel: "backLabel", nextLabel: "nextLabel", completeLabel: "completeLabel", loadingLabel: "loadingLabel", cancelLabel: "cancelLabel", hideCancel: "hideCancel", hideProgress: "hideProgress", footerLayout: "footerLayout", validationDisplay: "validationDisplay", progressLayout: "progressLayout" }, outputs: { complete: "complete", cancel: "cancel", event: "event" }, providers: [PathFacade], queries: [{ propertyName: "customHeader", first: true, predicate: PathShellHeaderDirective, descendants: true }, { propertyName: "customFooter", first: true, predicate: PathShellFooterDirective, descendants: true }, { propertyName: "stepDirectives", predicate: PathStepDirective }], usesOnChanges: true, ngImport: i0, template: `
     <!-- Empty state -->
     <div class="pw-shell" *ngIf="!(facade.state$ | async)">
       <div class="pw-shell__empty" *ngIf="!started">
@@ -289,10 +296,43 @@ export class PathShellComponent {
         </li>
       </ul>
 
+      <!-- Blocking error — guard returned { allowed: false, reason } -->
+      <p class="pw-shell__blocking-error"
+         *ngIf="validationDisplay !== 'inline' && s.hasAttemptedNext && s.blockingError">
+        {{ s.blockingError }}
+      </p>
+
+      <!-- Error panel — replaces footer when an async operation has failed -->
+      <div class="pw-shell__error" *ngIf="s.status === 'error' && s.error; else footerOrCustom">
+        <div class="pw-shell__error-title">{{ s.error!.retryCount >= 2 ? 'Still having trouble.' : 'Something went wrong.' }}</div>
+        <div class="pw-shell__error-message">{{ errorPhaseMessage(s.error!.phase) }}{{ s.error!.message ? ' ' + s.error!.message : '' }}</div>
+        <div class="pw-shell__error-actions">
+          <button
+            *ngIf="s.error!.retryCount < 2"
+            type="button"
+            class="pw-shell__btn pw-shell__btn--retry"
+            (click)="facade.retry()"
+          >Try again</button>
+          <button
+            *ngIf="s.hasPersistence"
+            type="button"
+            [class]="'pw-shell__btn ' + (s.error!.retryCount >= 2 ? 'pw-shell__btn--retry' : 'pw-shell__btn--suspend')"
+            (click)="facade.suspend()"
+          >Save and come back later</button>
+          <button
+            *ngIf="s.error!.retryCount >= 2 && !s.hasPersistence"
+            type="button"
+            class="pw-shell__btn pw-shell__btn--retry"
+            (click)="facade.retry()"
+          >Try again</button>
+        </div>
+      </div>
       <!-- Footer — custom or default navigation buttons -->
-      <ng-container *ngIf="customFooter; else defaultFooter">
-        <ng-container *ngTemplateOutlet="customFooter.templateRef; context: { $implicit: s, actions: shellActions }"></ng-container>
-      </ng-container>
+      <ng-template #footerOrCustom>
+        <ng-container *ngIf="customFooter; else defaultFooter">
+          <ng-container *ngTemplateOutlet="customFooter.templateRef; context: { $implicit: s, actions: shellActions }"></ng-container>
+        </ng-container>
+      </ng-template>
       <ng-template #defaultFooter>
         <div class="pw-shell__footer">
           <div class="pw-shell__footer-left">
@@ -301,7 +341,7 @@ export class PathShellComponent {
               *ngIf="getResolvedFooterLayout(s) === 'form' && !hideCancel"
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
-              [disabled]="s.isNavigating"
+              [disabled]="s.status !== 'idle'"
               (click)="facade.cancel()"
             >{{ cancelLabel }}</button>
             <!-- Wizard mode: Back on the left -->
@@ -309,7 +349,7 @@ export class PathShellComponent {
               *ngIf="getResolvedFooterLayout(s) === 'wizard' && !s.isFirstStep"
               type="button"
               class="pw-shell__btn pw-shell__btn--back"
-              [disabled]="s.isNavigating || !s.canMovePrevious"
+              [disabled]="s.status !== 'idle' || !s.canMovePrevious"
               (click)="facade.previous()"
             >{{ backLabel }}</button>
           </div>
@@ -319,16 +359,17 @@ export class PathShellComponent {
               *ngIf="getResolvedFooterLayout(s) === 'wizard' && !hideCancel"
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
-              [disabled]="s.isNavigating"
+              [disabled]="s.status !== 'idle'"
               (click)="facade.cancel()"
             >{{ cancelLabel }}</button>
             <!-- Both modes: Submit on the right -->
             <button
               type="button"
               class="pw-shell__btn pw-shell__btn--next"
-              [disabled]="s.isNavigating"
+              [class.pw-shell__btn--loading]="s.status !== 'idle'"
+              [disabled]="s.status !== 'idle'"
               (click)="facade.next()"
-            >{{ s.isLastStep ? completeLabel : nextLabel }}</button>
+            >{{ s.status !== 'idle' && loadingLabel ? loadingLabel : s.isLastStep ? completeLabel : nextLabel }}</button>
           </div>
         </div>
       </ng-template>
@@ -417,10 +458,43 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
         </li>
       </ul>
 
+      <!-- Blocking error — guard returned { allowed: false, reason } -->
+      <p class="pw-shell__blocking-error"
+         *ngIf="validationDisplay !== 'inline' && s.hasAttemptedNext && s.blockingError">
+        {{ s.blockingError }}
+      </p>
+
+      <!-- Error panel — replaces footer when an async operation has failed -->
+      <div class="pw-shell__error" *ngIf="s.status === 'error' && s.error; else footerOrCustom">
+        <div class="pw-shell__error-title">{{ s.error!.retryCount >= 2 ? 'Still having trouble.' : 'Something went wrong.' }}</div>
+        <div class="pw-shell__error-message">{{ errorPhaseMessage(s.error!.phase) }}{{ s.error!.message ? ' ' + s.error!.message : '' }}</div>
+        <div class="pw-shell__error-actions">
+          <button
+            *ngIf="s.error!.retryCount < 2"
+            type="button"
+            class="pw-shell__btn pw-shell__btn--retry"
+            (click)="facade.retry()"
+          >Try again</button>
+          <button
+            *ngIf="s.hasPersistence"
+            type="button"
+            [class]="'pw-shell__btn ' + (s.error!.retryCount >= 2 ? 'pw-shell__btn--retry' : 'pw-shell__btn--suspend')"
+            (click)="facade.suspend()"
+          >Save and come back later</button>
+          <button
+            *ngIf="s.error!.retryCount >= 2 && !s.hasPersistence"
+            type="button"
+            class="pw-shell__btn pw-shell__btn--retry"
+            (click)="facade.retry()"
+          >Try again</button>
+        </div>
+      </div>
       <!-- Footer — custom or default navigation buttons -->
-      <ng-container *ngIf="customFooter; else defaultFooter">
-        <ng-container *ngTemplateOutlet="customFooter.templateRef; context: { $implicit: s, actions: shellActions }"></ng-container>
-      </ng-container>
+      <ng-template #footerOrCustom>
+        <ng-container *ngIf="customFooter; else defaultFooter">
+          <ng-container *ngTemplateOutlet="customFooter.templateRef; context: { $implicit: s, actions: shellActions }"></ng-container>
+        </ng-container>
+      </ng-template>
       <ng-template #defaultFooter>
         <div class="pw-shell__footer">
           <div class="pw-shell__footer-left">
@@ -429,7 +503,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
               *ngIf="getResolvedFooterLayout(s) === 'form' && !hideCancel"
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
-              [disabled]="s.isNavigating"
+              [disabled]="s.status !== 'idle'"
               (click)="facade.cancel()"
             >{{ cancelLabel }}</button>
             <!-- Wizard mode: Back on the left -->
@@ -437,7 +511,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
               *ngIf="getResolvedFooterLayout(s) === 'wizard' && !s.isFirstStep"
               type="button"
               class="pw-shell__btn pw-shell__btn--back"
-              [disabled]="s.isNavigating || !s.canMovePrevious"
+              [disabled]="s.status !== 'idle' || !s.canMovePrevious"
               (click)="facade.previous()"
             >{{ backLabel }}</button>
           </div>
@@ -447,16 +521,17 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
               *ngIf="getResolvedFooterLayout(s) === 'wizard' && !hideCancel"
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
-              [disabled]="s.isNavigating"
+              [disabled]="s.status !== 'idle'"
               (click)="facade.cancel()"
             >{{ cancelLabel }}</button>
             <!-- Both modes: Submit on the right -->
             <button
               type="button"
               class="pw-shell__btn pw-shell__btn--next"
-              [disabled]="s.isNavigating"
+              [class.pw-shell__btn--loading]="s.status !== 'idle'"
+              [disabled]="s.status !== 'idle'"
               (click)="facade.next()"
-            >{{ s.isLastStep ? completeLabel : nextLabel }}</button>
+            >{{ s.status !== 'idle' && loadingLabel ? loadingLabel : s.isLastStep ? completeLabel : nextLabel }}</button>
           </div>
         </div>
       </ng-template>
@@ -464,8 +539,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
   `
                 }]
         }], propDecorators: { path: [{
-                type: Input,
-                args: [{ required: true }]
+                type: Input
+            }], engine: [{
+                type: Input
             }], initialData: [{
                 type: Input
             }], autoStart: [{
@@ -476,6 +552,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
                 type: Input
             }], completeLabel: [{
                 type: Input
+            }], loadingLabel: [{
+                type: Input
             }], cancelLabel: [{
                 type: Input
             }], hideCancel: [{
@@ -488,11 +566,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
                 type: Input
             }], progressLayout: [{
                 type: Input
-            }], completed: [{
+            }], complete: [{
                 type: Output
-            }], cancelled: [{
+            }], cancel: [{
                 type: Output
-            }], pathEvent: [{
+            }], event: [{
                 type: Output
             }], stepDirectives: [{
                 type: ContentChildren,

package/dist/shell.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daltonr/pathwrite-angular",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "license": "MIT",
   "description": "Angular adapter for @daltonr/pathwrite-core — RxJS observables, signal-friendly, with optional <pw-shell> default UI.",
@@ -61,7 +61,7 @@
     "@angular/compiler-cli": "^17.3.12"
   },
   "dependencies": {
-    "@daltonr/pathwrite-core": "^0.8.0"
+    "@daltonr/pathwrite-core": "^0.10.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -41,7 +41,7 @@ export class PathFacade<TData extends PathData = PathData> implements OnDestroy
 
   /**
    * Adopt an externally-managed `PathEngine` — for example, the engine returned
-   * by `restoreOrStart()` from `@daltonr/pathwrite-store-http`.
+   * by `restoreOrStart()` from `@daltonr/pathwrite-store`.
    *
    * The facade immediately reflects the engine's current state and forwards all
    * subsequent events. The **caller** is responsible for the engine's lifecycle
@@ -94,8 +94,18 @@ export class PathFacade<TData extends PathData = PathData> implements OnDestroy
    * Use for "Start over" / retry flows without destroying and re-creating the
    * component that provides this facade.
    */
-  public restart(path: PathDefinition<any>, initialData: PathData = {}): Promise<void> {
-    return this._engine.restart(path, initialData);
+  public restart(): Promise<void> {
+    return this._engine.restart();
+  }
+
+  /** Re-runs the operation that set `snapshot().error`. Increments `retryCount` on repeated failure. No-op when there is no pending error. */
+  public retry(): Promise<void> {
+    return this._engine.retry();
+  }
+
+  /** Pauses the path with intent to return. Emits `suspended`. All state is preserved. */
+  public suspend(): Promise<void> {
+    return this._engine.suspend();
   }
 
   public startSubPath(path: PathDefinition<any>, initialData: PathData = {}, meta?: Record<string, unknown>): Promise<void> {
@@ -141,15 +151,15 @@ export class PathFacade<TData extends PathData = PathData> implements OnDestroy
 }
 
 // ---------------------------------------------------------------------------
-// injectPath() - Signal-based path access
+// usePathContext() - Signal-based path access
 // ---------------------------------------------------------------------------
 
 /**
- * Return type of `injectPath()`. Provides signal-based reactive access to the
+ * Return type of `usePathContext()`. Provides signal-based reactive access to the
  * path state and strongly-typed navigation actions. Mirrors React's `usePathContext()`
  * return type for consistency across adapters.
  */
-export interface InjectPathReturn<TData extends PathData = PathData> {
+export interface UsePathContextReturn<TData extends PathData = PathData> {
   /** Current path snapshot as a signal. Returns `null` when no path is active. */
   snapshot: Signal<PathSnapshot<TData> | null>;
   /** Start (or restart) a path. */
@@ -174,17 +184,21 @@ export interface InjectPathReturn<TData extends PathData = PathData> {
    * Tears down any active path and immediately starts the given path fresh.
    * Use for "Start over" / retry flows.
    */
-  restart: (path: PathDefinition<any>, initialData?: PathData) => Promise<void>;
+  restart: () => Promise<void>;
+  /** Re-run the operation that set `snapshot().error`. */
+  retry: () => Promise<void>;
+  /** Pause with intent to return, preserving all state. Emits `suspended`. */
+  suspend: () => Promise<void>;
 }
 
 /**
- * Inject a PathFacade and return a signal-based API for use in Angular components.
+ * Access the nearest `PathFacade`'s path instance for use in Angular step components.
  * Requires `PathFacade` to be provided in the component's injector tree (either via
  * `providers: [PathFacade]` in the component or a parent component).
  *
  * **This is the recommended way to consume Pathwrite in Angular components** — it
- * provides the same ergonomic, framework-native API that React's `usePathContext()`
- * and Vue's `usePath()` offer. No template references or manual facade injection needed.
+ * provides the same ergonomic API as React's `usePathContext()` and Vue's `usePathContext()`.
+ * No template references or manual facade injection needed.
  *
  * The optional generic `TData` narrows `snapshot().data` and `setData()` to your
  * data shape. It is a **type-level assertion**, not a runtime guarantee.
@@ -203,7 +217,7 @@ export interface InjectPathReturn<TData extends PathData = PathData> {
  *   `
  * })
  * export class ContactStepComponent {
- *   protected readonly path = injectPath<ContactData>();
+ *   protected readonly path = usePathContext<ContactData>();
  *
  *   updateName(name: string) {
  *     this.path.setData('name', name);
@@ -213,12 +227,12 @@ export interface InjectPathReturn<TData extends PathData = PathData> {
  *
  * @throws Error if PathFacade is not provided in the injector tree
  */
-export function injectPath<TData extends PathData = PathData>(): InjectPathReturn<TData> {
+export function usePathContext<TData extends PathData = PathData>(): UsePathContextReturn<TData> {
   const facade = inject(PathFacade, { optional: true }) as PathFacade<TData> | null;
-  
+
   if (!facade) {
     throw new Error(
-      "injectPath() requires PathFacade to be provided. " +
+      "usePathContext() requires PathFacade to be provided. " +
       "Add 'providers: [PathFacade]' to your component or a parent component."
     );
   }
@@ -234,7 +248,9 @@ export function injectPath<TData extends PathData = PathData>(): InjectPathRetur
     resetStep: () => facade.resetStep(),
     goToStep: (stepId) => facade.goToStep(stepId),
     goToStepChecked: (stepId) => facade.goToStepChecked(stepId),
-    restart: (path, initialData = {}) => facade.restart(path, initialData),
+    restart: () => facade.restart(),
+    retry: () => facade.retry(),
+    suspend: () => facade.suspend(),
   };
 }
 

package/src/shell.ts

@@ -9,7 +9,9 @@ import {
   ContentChildren,
   QueryList,
   OnInit,
+  OnChanges,
   OnDestroy,
+  SimpleChanges,
   inject,
   Injector,
   ChangeDetectionStrategy
@@ -20,10 +22,13 @@ import { takeUntil } from "rxjs/operators";
 import {
   PathData,
   PathDefinition,
+  PathEngine,
   PathEvent,
   PathSnapshot,
   ProgressLayout,
-  RootProgress
+  RootProgress,
+  formatFieldKey,
+  errorPhaseMessage,
 } from "@daltonr/pathwrite-core";
 import { PathFacade } from "./index";
 
@@ -45,6 +50,10 @@ export interface PathShellActions {
   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>;
 }
 
 // ---------------------------------------------------------------------------
@@ -127,7 +136,7 @@ export class PathShellFooterDirective {
  * and navigation buttons.
  *
  * ```html
- * <pw-shell [path]="myPath" [initialData]="{ name: '' }" (completed)="onDone($event)">
+ * <pw-shell [path]="myPath" [initialData]="{ name: '' }" (complete)="onDone($event)">
  *   <ng-template pwStep="details"><app-details-form /></ng-template>
  *   <ng-template pwStep="review"><app-review-panel /></ng-template>
  * </pw-shell>
@@ -213,10 +222,43 @@ export class PathShellFooterDirective {
         </li>
       </ul>
 
+      <!-- Blocking error — guard returned { allowed: false, reason } -->
+      <p class="pw-shell__blocking-error"
+         *ngIf="validationDisplay !== 'inline' && s.hasAttemptedNext && s.blockingError">
+        {{ s.blockingError }}
+      </p>
+
+      <!-- Error panel — replaces footer when an async operation has failed -->
+      <div class="pw-shell__error" *ngIf="s.status === 'error' && s.error; else footerOrCustom">
+        <div class="pw-shell__error-title">{{ s.error!.retryCount >= 2 ? 'Still having trouble.' : 'Something went wrong.' }}</div>
+        <div class="pw-shell__error-message">{{ errorPhaseMessage(s.error!.phase) }}{{ s.error!.message ? ' ' + s.error!.message : '' }}</div>
+        <div class="pw-shell__error-actions">
+          <button
+            *ngIf="s.error!.retryCount < 2"
+            type="button"
+            class="pw-shell__btn pw-shell__btn--retry"
+            (click)="facade.retry()"
+          >Try again</button>
+          <button
+            *ngIf="s.hasPersistence"
+            type="button"
+            [class]="'pw-shell__btn ' + (s.error!.retryCount >= 2 ? 'pw-shell__btn--retry' : 'pw-shell__btn--suspend')"
+            (click)="facade.suspend()"
+          >Save and come back later</button>
+          <button
+            *ngIf="s.error!.retryCount >= 2 && !s.hasPersistence"
+            type="button"
+            class="pw-shell__btn pw-shell__btn--retry"
+            (click)="facade.retry()"
+          >Try again</button>
+        </div>
+      </div>
       <!-- Footer — custom or default navigation buttons -->
-      <ng-container *ngIf="customFooter; else defaultFooter">
-        <ng-container *ngTemplateOutlet="customFooter.templateRef; context: { $implicit: s, actions: shellActions }"></ng-container>
-      </ng-container>
+      <ng-template #footerOrCustom>
+        <ng-container *ngIf="customFooter; else defaultFooter">
+          <ng-container *ngTemplateOutlet="customFooter.templateRef; context: { $implicit: s, actions: shellActions }"></ng-container>
+        </ng-container>
+      </ng-template>
       <ng-template #defaultFooter>
         <div class="pw-shell__footer">
           <div class="pw-shell__footer-left">
@@ -225,7 +267,7 @@ export class PathShellFooterDirective {
               *ngIf="getResolvedFooterLayout(s) === 'form' && !hideCancel"
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
-              [disabled]="s.isNavigating"
+              [disabled]="s.status !== 'idle'"
               (click)="facade.cancel()"
             >{{ cancelLabel }}</button>
             <!-- Wizard mode: Back on the left -->
@@ -233,7 +275,7 @@ export class PathShellFooterDirective {
               *ngIf="getResolvedFooterLayout(s) === 'wizard' && !s.isFirstStep"
               type="button"
               class="pw-shell__btn pw-shell__btn--back"
-              [disabled]="s.isNavigating || !s.canMovePrevious"
+              [disabled]="s.status !== 'idle' || !s.canMovePrevious"
               (click)="facade.previous()"
             >{{ backLabel }}</button>
           </div>
@@ -243,25 +285,41 @@ export class PathShellFooterDirective {
               *ngIf="getResolvedFooterLayout(s) === 'wizard' && !hideCancel"
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
-              [disabled]="s.isNavigating"
+              [disabled]="s.status !== 'idle'"
               (click)="facade.cancel()"
             >{{ cancelLabel }}</button>
             <!-- Both modes: Submit on the right -->
             <button
               type="button"
               class="pw-shell__btn pw-shell__btn--next"
-              [disabled]="s.isNavigating"
+              [class.pw-shell__btn--loading]="s.status !== 'idle'"
+              [disabled]="s.status !== 'idle'"
               (click)="facade.next()"
-            >{{ s.isLastStep ? completeLabel : nextLabel }}</button>
+            >{{ s.status !== 'idle' && loadingLabel ? loadingLabel : s.isLastStep ? completeLabel : nextLabel }}</button>
           </div>
         </div>
       </ng-template>
     </div>
   `
 })
-export class PathShellComponent implements OnInit, OnDestroy {
-  /** The path definition to run. Required. */
-  @Input({ required: true }) path!: PathDefinition<any>;
+export class PathShellComponent implements OnInit, OnChanges, OnDestroy {
+  /** The path definition to run. Required unless [engine] is provided. */
+  @Input() path?: PathDefinition<any>;
+  /**
+   * An externally-managed `PathEngine` to adopt — for example, the engine
+   * returned by `restoreOrStart()` from `@daltonr/pathwrite-store`.
+   *
+   * When provided the shell skips `autoStart` and immediately reflects the
+   * engine's current state. Gate the shell's existence on the engine being
+   * ready using `@if (engine)` so the input is always non-null on mount:
+   *
+   * ```html
+   * @if (engine) {
+   *   <pw-shell [engine]="engine" [path]="myPath" ...></pw-shell>
+   * }
+   * ```
+   */
+  @Input() engine?: PathEngine;
   /** Initial data merged into the path engine on start. */
   @Input() initialData: PathData = {};
   /** Start the path automatically on ngOnInit. Set to false to call doStart() manually. */
@@ -272,6 +330,8 @@ export class PathShellComponent implements OnInit, OnDestroy {
   @Input() nextLabel = "Next";
   /** Label for the Next button when on the last step. */
   @Input() completeLabel = "Complete";
+  /** Label shown on the Next/Complete button while an async operation is in progress. When undefined, the button keeps its label and shows a CSS spinner only. */
+  @Input() loadingLabel?: string;
   /** Label for the Cancel button. */
   @Input() cancelLabel = "Cancel";
   /** Hide the Cancel button entirely. */
@@ -291,7 +351,7 @@ export class PathShellComponent implements OnInit, OnDestroy {
    * - `"inline"`: Suppress the summary — handle errors inside the step template instead.
    * - `"both"`: Render the shell summary AND whatever the step template renders.
    */
-  @Input() validationDisplay: "summary" | "inline" | "both" = "inline";
+  @Input() validationDisplay: "summary" | "inline" | "both" = "summary";
   /**
    * Controls how progress bars are arranged when a sub-path is active.
    * - "merged" (default): Root and sub-path bars in one card.
@@ -301,9 +361,9 @@ export class PathShellComponent implements OnInit, OnDestroy {
    */
   @Input() progressLayout: ProgressLayout = "merged";
 
-  @Output() completed = new EventEmitter<PathData>();
-  @Output() cancelled = new EventEmitter<PathData>();
-  @Output() pathEvent = new EventEmitter<PathEvent>();
+  @Output() complete = new EventEmitter<PathData>();
+  @Output() cancel = new EventEmitter<PathData>();
+  @Output() event = new EventEmitter<PathEvent>();
 
   @ContentChildren(PathStepDirective) stepDirectives!: QueryList<PathStepDirective>;
   @ContentChild(PathShellHeaderDirective) customHeader?: PathShellHeaderDirective;
@@ -323,19 +383,27 @@ export class PathShellComponent implements OnInit, OnDestroy {
     goToStep: (id) => this.facade.goToStep(id),
     goToStepChecked: (id) => this.facade.goToStepChecked(id),
     setData: (key, value) => this.facade.setData(key, value as never),
-    restart: () => this.facade.restart(this.path, this.initialData),
+    restart: () => this.facade.restart(),
+    retry: () => this.facade.retry(),
+    suspend: () => this.facade.suspend(),
   };
 
   private readonly destroy$ = new Subject<void>();
 
+  public ngOnChanges(changes: SimpleChanges): void {
+    if (changes['engine'] && this.engine) {
+      this.facade.adoptEngine(this.engine);
+    }
+  }
+
   public ngOnInit(): void {
     this.facade.events$.pipe(takeUntil(this.destroy$)).subscribe((event) => {
-      this.pathEvent.emit(event);
-      if (event.type === "completed") this.completed.emit(event.data);
-      if (event.type === "cancelled") this.cancelled.emit(event.data);
+      this.event.emit(event);
+      if (event.type === "completed") this.complete.emit(event.data);
+      if (event.type === "cancelled") this.cancel.emit(event.data);
     });
 
-    if (this.autoStart) {
+    if (this.autoStart && !this.engine) {
       this.doStart();
     }
   }
@@ -346,6 +414,7 @@ export class PathShellComponent implements OnInit, OnDestroy {
   }
 
   public doStart(): void {
+    if (!this.path) throw new Error('[pw-shell] [path] is required when no [engine] is provided');
     this.started = true;
     this.facade.start(this.path, this.initialData);
   }
@@ -360,7 +429,7 @@ export class PathShellComponent implements OnInit, OnDestroy {
    * ```
    */
   public restart(): Promise<void> {
-    return this.facade.restart(this.path, this.initialData);
+    return this.facade.restart();
   }
 
   /** Returns Object.entries(s.fieldErrors) for use in *ngFor. */
@@ -380,9 +449,6 @@ export class PathShellComponent implements OnInit, OnDestroy {
       : this.footerLayout;
   }
 
-  /** Converts a camelCase or lowercase field key to a display label.
-   *  e.g. "firstName" → "First Name", "email" → "Email" */
-  protected formatFieldKey(key: string): string {
-    return key.replace(/([A-Z])/g, " $1").replace(/^./, c => c.toUpperCase()).trim();
-  }
+  protected errorPhaseMessage = errorPhaseMessage;
+  protected formatFieldKey = formatFieldKey;
 }