@ama-mfe/ng-utils 14.5.0-prerelease.34 → 14.5.0-prerelease.36

package/fesm2022/ama-mfe-ng-utils.mjs

@@ -1,10 +1,10 @@
 import { MessagePeerService, MESSAGE_PEER_CONFIG, MESSAGE_PEER_CONNECT_OPTIONS } from '@amadeus-it-group/microfrontends-angular';
 export { MessagePeerService as ConnectionService } from '@amadeus-it-group/microfrontends-angular';
 import * as i0 from '@angular/core';
-import { input, inject, ElementRef, computed, SecurityContext, effect, HostBinding, Directive, Injectable, signal, DestroyRef, provideAppInitializer, Pipe, makeEnvironmentProviders, Renderer2, afterNextRender, ChangeDetectionStrategy, ViewEncapsulation, Component, untracked } from '@angular/core';
+import { input, inject, ElementRef, computed, SecurityContext, effect, HostBinding, Directive, Injectable, signal, DestroyRef, provideAppInitializer, Pipe, makeEnvironmentProviders, Renderer2, afterNextRender, ChangeDetectionStrategy, ViewEncapsulation, Component, untracked, InjectionToken } from '@angular/core';
 import { DomSanitizer } from '@angular/platform-browser';
 import { LoggerService } from '@o3r/logger';
-import { HISTORY_MESSAGE_TYPE, USER_ACTIVITY_MESSAGE_TYPE, RESIZE_MESSAGE_TYPE, THEME_MESSAGE_TYPE, NAVIGATION_MESSAGE_TYPE } from '@ama-mfe/messages';
+import { HISTORY_MESSAGE_TYPE, USER_ACTIVITY_MESSAGE_TYPE, RESIZE_MESSAGE_TYPE, THEME_MESSAGE_TYPE, NAVIGATION_MESSAGE_TYPE, NAVIGATION_BLOCK_STATE_MESSAGE_TYPE, NAVIGATION_REQUEST_MESSAGE_TYPE, NAVIGATION_DECISION_MESSAGE_TYPE } from '@ama-mfe/messages';
 import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
 import { fromEvent, throttleTime, Subject, filter, map } from 'rxjs';
 import { Router, ActivatedRoute, NavigationEnd } from '@angular/router';
@@ -286,18 +286,13 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImpo
  * To use this class, simply extend it and implement the required properties (type and supportedVersions) and any additional logic needed to consume messages.
  */
 class AbstractMessageConsumer {
-    /**
-     * Creates an instance of AbstractMessageConsumer and optionally starts it.
-     * @param autoStart If true, the consumer will be started immediately after creation. Defaults to true.
-     */
-    constructor(autoStart = true) {
+    constructor() {
         /** The service used to register the consumer */
         this.consumerManagerService = inject(ConsumerManagerService);
         /** The reference used to handle the destruction of the consumer */
         this.destroyRef = inject(DestroyRef);
-        if (autoStart) {
-            this.start();
-        }
+        /** Logger shared with subclasses. */
+        this.logger = inject(LoggerService);
     }
     /** @inheritdoc */
     start() {
@@ -362,6 +357,11 @@ class HistoryConsumerService extends AbstractMessageConsumer {
                 history.go(message.payload.delta);
             }
         };
+        /**
+         * Auto-starts the consumer on creation.
+         * @deprecated The constructor auto-starts the consumer for backwards compatibility. It will be removed in v15;
+         */
+        this.start();
     }
     /** @nocollapse */ static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: HistoryConsumerService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
     /** @nocollapse */ static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: HistoryConsumerService, providedIn: 'root' }); }
@@ -536,6 +536,17 @@ function getDefaultClientEndpointStartOptions() {
 function isEmbedded(windowParam = window) {
     return windowParam.top !== windowParam.self;
 }
+/**
+ * Generate a string id suitable for correlating asynchronous request/reply messages across the micro-frontend bus.
+ * Uses `crypto.randomUUID` when the runtime supports it, otherwise falls back to a timestamp + random suffix.
+ * @param prefix Optional prefix used by the fallback path to make ids easier to identify in logs (ignored when `crypto.randomUUID` is available).
+ */
+function generateCorrelationId(prefix = 'corr') {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
 
 /**
  * Provide the communication protocol connection configuration
@@ -593,6 +604,11 @@ class ResizeConsumerService extends AbstractMessageConsumer {
              */
             '1.0': (message) => this.newHeight.set({ height: message.payload.height, channelId: message.from })
         };
+        /**
+         * Auto-starts the consumer on creation.
+         * @deprecated The constructor auto-starts the consumer for backwards compatibility. It will be removed in v15;
+         */
+        this.start();
     }
     /** @nocollapse */ static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: ResizeConsumerService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
     /** @nocollapse */ static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: ResizeConsumerService, providedIn: 'root' }); }
@@ -1055,6 +1071,11 @@ class NavigationConsumerService extends AbstractMessageConsumer {
                 this.navigate(message.payload.url, message.payload.extras);
             }
         };
+        /**
+         * Auto-starts the consumer on creation.
+         * @deprecated The constructor auto-starts the consumer for backwards compatibility. It will be removed in v15;
+         */
+        this.start();
     }
     /**
      * Parses a URL and returns an object containing the paths and query parameters.
@@ -1363,6 +1384,564 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImpo
                 }]
         }], ctorParameters: () => [] });
 
+/**
+ * Module-side writable source of truth for the navigation block state.
+ *
+ * Feature code (forms, editors, etc.) calls {@link block} when unsaved changes appear and {@link unblock} once they are saved or discarded.
+ * The {@link NavigationBlockStateProducerService} watches this signal and mirrors the state to the shell;
+ * the {@link navigationBlockModuleGuard} reads it to decide whether to intercept in-module navigation.
+ */
+class NavigationBlockService {
+    constructor() {
+        this.stateSignal = signal({ blocked: false }, ...(ngDevMode ? [{ debugName: "stateSignal" }] : /* istanbul ignore next */ []));
+        /** Readonly view of the current navigation block state. */
+        this.state = this.stateSignal.asReadonly();
+    }
+    /**
+     * Mark the module as blocked (unsaved changes present).
+     * @param reason Optional human-readable reason shown in the confirmation modal.
+     */
+    block(reason) {
+        this.stateSignal.set({ blocked: true, reason });
+    }
+    /** Mark the module as unblocked (no unsaved changes). */
+    unblock() {
+        this.stateSignal.set({ blocked: false });
+    }
+    /** @nocollapse */ static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationBlockService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    /** @nocollapse */ static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationBlockService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationBlockService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root'
+                }]
+        }] });
+
+/**
+ * Module-side producer that mirrors {@link NavigationBlockService} to the shell via `navigation-block-state` messages.
+ * Every state change triggers a broadcast so the shell guard can decide without a round-trip.
+ *
+ * Runs module-side only (it watches the module's writable state). The shell never instantiates it.
+ */
+class NavigationBlockStateProducerService {
+    constructor() {
+        /**
+         * @inheritdoc
+         */
+        this.types = NAVIGATION_BLOCK_STATE_MESSAGE_TYPE;
+        this.connectionService = inject(MessagePeerService);
+        this.producerManagerService = inject(ProducerManagerService);
+        this.logger = inject(LoggerService);
+        this.store = inject(NavigationBlockService);
+        this.producerManagerService.register(this);
+        inject(DestroyRef).onDestroy(() => this.producerManagerService.unregister(this));
+        effect(() => {
+            const state = this.store.state();
+            const message = {
+                type: NAVIGATION_BLOCK_STATE_MESSAGE_TYPE,
+                version: '1.0',
+                blocked: state.blocked,
+                reason: state.reason
+            };
+            this.connectionService.send(message);
+        });
+    }
+    /**
+     * @inheritdoc
+     */
+    handleError(message) {
+        this.logger.error('navigation-block state message could not be consumed by the shell', message);
+    }
+    /** @nocollapse */ static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationBlockStateProducerService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    /** @nocollapse */ static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationBlockStateProducerService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationBlockStateProducerService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root'
+                }]
+        }], ctorParameters: () => [] });
+
+/**
+ * Shell-side consumer for `navigation-block-state` messages sent by modules.
+ *
+ * Keeps the last received state in a signal that the shell guard reads to decide whether to intercept shell-initiated navigation.
+ * The state stays `undefined` until any module reports a value (interpreted as "no block known" which means navigation is allowed).
+ */
+class NavigationBlockStateConsumerService extends AbstractMessageConsumer {
+    constructor() {
+        super(...arguments);
+        /**
+         * @inheritdoc
+         */
+        this.type = NAVIGATION_BLOCK_STATE_MESSAGE_TYPE;
+        /**
+         * @inheritdoc
+         */
+        this.supportedVersions = {
+            // eslint-disable-next-line @typescript-eslint/naming-convention -- expected naming for versions
+            '1.0': (message) => {
+                this.blockStateSignal.set({
+                    blocked: message.payload.blocked,
+                    reason: message.payload.reason,
+                    channelId: message.from
+                });
+            }
+        };
+        this.blockStateSignal = signal(undefined, ...(ngDevMode ? [{ debugName: "blockStateSignal" }] : /* istanbul ignore next */ []));
+        /** Last navigation block state reported by any module. */
+        this.blockState = this.blockStateSignal.asReadonly();
+    }
+    /**
+     * Mark the state as unblocked after the shell has resolved a confirmation (e.g. the user confirmed a sidebar-initiated navigation).
+     */
+    clear() {
+        this.blockStateSignal.set({ blocked: false });
+    }
+    /** @nocollapse */ static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationBlockStateConsumerService, deps: null, target: i0.ɵɵFactoryTarget.Injectable }); }
+    /** @nocollapse */ static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationBlockStateConsumerService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationBlockStateConsumerService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root'
+                }]
+        }] });
+
+/**
+ * Manages navigation request/decision round-trip communication for **both** shell and module.
+ * Sends `navigation-request` messages, tracks pending requests, and sends `navigation-decision` replies.
+ * Correlates responses with their originating requests using correlation IDs.
+ *
+ * - Module-initiated navigation → guard calls `requestNavigation()` with no target, broadcasting to the shell;
+ *   the shell's handler opens the modal and replies.
+ * - Shell-initiated navigation → guard calls `requestNavigation(channelId)` after the user already confirmed locally,
+ *   so the module can run its unblock / draft-persistence logic and reply.
+ *
+ * If the peer never replies the returned promise stays pending and the navigation is held — callers rely on Angular
+ * tearing their context down (the producer's `ngOnDestroy` resolves pending promises to `false`).
+ */
+class NavigationRequestManagerService {
+    constructor() {
+        /**
+         * @inheritdoc
+         */
+        this.types = [NAVIGATION_REQUEST_MESSAGE_TYPE, NAVIGATION_DECISION_MESSAGE_TYPE];
+        this.connectionService = inject(MessagePeerService);
+        this.producerManagerService = inject(ProducerManagerService);
+        this.logger = inject(LoggerService);
+        this.producerManagerService.register(this);
+    }
+    /**
+     * Ask the peer to handle the navigation. Resolves when the peer replies with a `navigation-decision`.
+     * If the peer never replies the promise stays pending.
+     *
+     * Re-entrant calls while a request is pending (e.g. the same navigation firing both `canActivate` and `canActivateChild`)
+     * return the same promise, so only one round-trip is sent.
+     * @param target Optional target peer id. Omit to broadcast (module → shell).
+     * @param reason Optional human-readable reason surfaced in the shell modal.
+     */
+    requestNavigation(target, reason) {
+        if (this.pendingRequest) {
+            return this.pendingRequest.promise;
+        }
+        const correlationId = generateCorrelationId('nav-req');
+        let resolveFn;
+        const promise = new Promise((resolve) => {
+            resolveFn = resolve;
+        });
+        this.pendingRequest = { correlationId, promise, resolve: resolveFn };
+        const message = {
+            type: NAVIGATION_REQUEST_MESSAGE_TYPE,
+            version: '1.0',
+            correlationId,
+            reason
+        };
+        this.connectionService.send(message, target ? { to: target } : undefined);
+        return promise;
+    }
+    /**
+     * Send a `navigation-decision` reply with the given `correlationId`.
+     * Called by {@link NavigationNegotiationConsumerService} after the side-specific handler has finished.
+     * @param correlationId id echoed from the request
+     * @param target peer id of the original sender
+     * @param proceed whether to allow navigation (default true)
+     */
+    sendDecision(correlationId, target, proceed = true) {
+        const message = {
+            type: NAVIGATION_DECISION_MESSAGE_TYPE,
+            version: '1.0',
+            correlationId,
+            proceed
+        };
+        this.connectionService.send(message, { to: target });
+    }
+    /**
+     * Called by {@link NavigationDecisionConsumerService} when a decision arrives.
+     * Resolves the pending promise if the `correlationId` matches.
+     * @param correlationId
+     * @param proceed
+     */
+    resolvePendingRequest(correlationId, proceed) {
+        const pending = this.pendingRequest;
+        if (!pending || pending.correlationId !== correlationId) {
+            return;
+        }
+        this.pendingRequest = undefined;
+        pending.resolve(proceed);
+    }
+    /**
+     * @inheritdoc
+     */
+    handleError(message) {
+        this.logger.error('navigation negotiation message could not be consumed by a peer', message);
+    }
+    ngOnDestroy() {
+        if (this.pendingRequest) {
+            this.pendingRequest.resolve(false);
+            this.pendingRequest = undefined;
+        }
+        this.producerManagerService.unregister(this);
+    }
+    /** @nocollapse */ static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationRequestManagerService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    /** @nocollapse */ static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationRequestManagerService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationRequestManagerService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root'
+                }]
+        }], ctorParameters: () => [] });
+
+/**
+ * Default module-side `navigation-request` handler. Runs the module's local cleanup — at minimum clearing the block state — and resolves.
+ * Modules cannot refuse a navigation (only the shell modal can), so this always resolves and a `navigation-decision` is always sent back.
+ *
+ * Used as the default factory of {@link NAVIGATION_REQUEST_HANDLER}, so a module gets this behavior without any explicit provider.
+ * Apps that need to persist drafts before unblocking can override the token with their own handler.
+ */
+const createNavigationRequestHandler = () => {
+    const store = inject(NavigationBlockService);
+    return {
+        handle: () => {
+            store.unblock();
+        }
+    };
+};
+/**
+ * Injection token for the per-side request handler.
+ *
+ * **Default behavior (modules):** Clears the block state (unblock) — see {@link createNavigationRequestHandler}.
+ * **Shell override:** Opens confirmation modal and awaits user decision.
+ *
+ * The module handler is provided by default at root level. Only the shell application needs to override it
+ * with `provideNavigationRequestShellHandler()`.
+ */
+const NAVIGATION_REQUEST_HANDLER = new InjectionToken('NAVIGATION_REQUEST_HANDLER', {
+    providedIn: 'root',
+    factory: createNavigationRequestHandler
+});
+
+/**
+ * Agnostic consumer for `navigation-request` messages.
+ *
+ * On each incoming request, invokes the side-specific handler registered under {@link NAVIGATION_REQUEST_HANDLER}:
+ * - **Cockpit side** — handler opens the confirmation modal and awaits the user's answer. If the user cancels the handler
+ *   throws; this consumer catches it and replies with a decision carrying `proceed: false`, so the module's pending promise
+ *   resolves to `false` and the in-iframe navigation is held until a fresh request is made.
+ * - **Module side** — handler runs the unblock / future draft-persistence logic and resolves. Modules cannot refuse;
+ *   a decision is always sent.
+ */
+class NavigationRequestConsumerService extends AbstractMessageConsumer {
+    constructor() {
+        super(...arguments);
+        /**
+         * @inheritdoc
+         */
+        this.type = NAVIGATION_REQUEST_MESSAGE_TYPE;
+        /**
+         * @inheritdoc
+         */
+        this.supportedVersions = {
+            // eslint-disable-next-line @typescript-eslint/naming-convention -- expected naming for versions
+            '1.0': (message) => this.handleRequest(message)
+        };
+        this.producerService = inject(NavigationRequestManagerService);
+        this.handler = inject(NAVIGATION_REQUEST_HANDLER);
+    }
+    async handleRequest(message) {
+        try {
+            await this.handler.handle({ from: message.from, reason: message.payload.reason });
+        }
+        catch (error) {
+            // Handler rejected — usually the user cancelled, but any unexpected
+            // exception ends up here too. Log it so the failure is observable, then
+            // send a decision with proceed=false so the requester's pending promise
+            // resolves and subsequent navigation attempts can create a fresh request.
+            this.logger.error('navigation-request handler rejected', error, message);
+            this.producerService.sendDecision(message.payload.correlationId, message.from, false);
+            return;
+        }
+        this.producerService.sendDecision(message.payload.correlationId, message.from);
+    }
+    /** @nocollapse */ static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationRequestConsumerService, deps: null, target: i0.ɵɵFactoryTarget.Injectable }); }
+    /** @nocollapse */ static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationRequestConsumerService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationRequestConsumerService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root'
+                }]
+        }] });
+
+/**
+ * Provider wiring {@link NAVIGATION_REQUEST_HANDLER} to the module handler.
+ * Not normally needed — the token already defaults to this handler — but
+ * available for apps that want to register it explicitly.
+ */
+const provideNavigationRequestModuleHandler = () => makeEnvironmentProviders([
+    {
+        provide: NAVIGATION_REQUEST_HANDLER,
+        useFactory: createNavigationRequestHandler
+    }
+]);
+
+/**
+ * Default confirmation strategy using browser's native `window.confirm()`.
+ * Simple, no dependencies, works in any environment. Suitable for:
+ * - Development/testing
+ * - Apps without custom modal libraries
+ * - `@ama-mfe` packages that need basic confirmation
+ *
+ * Production apps typically override this with a modal-based strategy.
+ */
+class BrowserConfirmationStrategy {
+    /**
+     * Show native browser confirmation dialog.
+     * @param reason Optional reason displayed in the message
+     * @returns Promise<true> if user clicks OK, Promise<false> if user clicks Cancel
+     */
+    confirm(reason) {
+        const message = `${reason ? reason + '\n' : ''}Do you want to leave this page?`;
+        // eslint-disable-next-line no-alert -- intentional use of window.confirm for basic confirmation strategy
+        return Promise.resolve(window.confirm(message));
+    }
+    /** @nocollapse */ static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: BrowserConfirmationStrategy, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    /** @nocollapse */ static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: BrowserConfirmationStrategy, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: BrowserConfirmationStrategy, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root'
+                }]
+        }] });
+
+/**
+ * Injection token for the navigation block confirmation strategy.
+ * Defaults to {@link BrowserConfirmationStrategy} (uses `window.confirm()`).
+ * Apps with a styled modal override the default by passing their own class via `provideNavigationConfig({ confirmationStrategy })`
+ * or by binding this token directly.
+ */
+const NAVIGATION_BLOCK_CONFIRMATION = new InjectionToken('NAVIGATION_BLOCK_CONFIRMATION', {
+    providedIn: 'root',
+    factory: () => inject(BrowserConfirmationStrategy)
+});
+
+/**
+ * Orchestrates navigation block confirmation by delegating to a pluggable strategy.
+ * Handles concurrent call deduplication to prevent duplicate confirmations when guards run multiple times.
+ *
+ * The confirmation UI is read from the `NAVIGATION_BLOCK_CONFIRMATION` token, which defaults to {@link BrowserConfirmationStrategy}
+ * (no setup required). Apps with a styled modal override the token via `provideNavigationConfig({ confirmationStrategy })`
+ * or by binding the token directly.
+ */
+class NavigationBlockConfirmationService {
+    constructor() {
+        this.strategy = inject(NAVIGATION_BLOCK_CONFIRMATION);
+    }
+    /**
+     * Show confirmation and await user decision. Concurrent calls return the same promise to prevent duplicate confirmations.
+     * @param reason Optional reason displayed in the confirmation UI
+     * @returns `true` when the user confirms, `false` when they cancel
+     */
+    confirm(reason) {
+        // Deduplication: if confirmation already in progress, return same promise
+        if (this.pendingConfirmation) {
+            return this.pendingConfirmation;
+        }
+        // Delegate to injected strategy. Clear the slot only once the promise
+        // settles, so concurrent callers in the meantime get the same promise.
+        const pending = this.strategy.confirm(reason).finally(() => {
+            this.pendingConfirmation = undefined;
+        });
+        this.pendingConfirmation = pending;
+        return pending;
+    }
+    /** @nocollapse */ static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationBlockConfirmationService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    /** @nocollapse */ static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationBlockConfirmationService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationBlockConfirmationService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root'
+                }]
+        }] });
+
+/**
+ * Shell application `navigation-request` handler used when a module initiates the navigation (in-iframe link click).
+ * Opens the shared confirmation modal, awaits the user's answer, and — on confirm — clears the shell's block mirror.
+ * On cancel the handler throws; the consumer catches it and replies with a `navigation-decision` carrying `proceed: false`,
+ * so the module's pending promise resolves to `false` and the iframe navigation is held until a fresh request is made.
+ */
+const createNavigationRequestShellHandler = () => {
+    const confirmation = inject(NavigationBlockConfirmationService);
+    const blockConsumer = inject(NavigationBlockStateConsumerService);
+    return {
+        handle: async ({ reason }) => {
+            const confirmed = await confirmation.confirm(reason);
+            if (!confirmed) {
+                throw new Error('navigation-request cancelled by user');
+            }
+            blockConsumer.clear();
+        }
+    };
+};
+/**
+ * Provider wiring {@link NAVIGATION_REQUEST_HANDLER} to the shell application
+ * handler. Register once in the shell app providers to override the default
+ * module handler.
+ */
+const provideNavigationRequestShellHandler = () => makeEnvironmentProviders([
+    {
+        provide: NAVIGATION_REQUEST_HANDLER,
+        useFactory: createNavigationRequestShellHandler
+    }
+]);
+
+/**
+ * Agnostic consumer for `navigation-decision` messages — the reply to a
+ * previously sent `navigation-request`. Forwards the decision to
+ * {@link NavigationRequestManagerService.resolvePendingRequest} so
+ * the awaiting caller's promise resolves.
+ */
+class NavigationDecisionConsumerService extends AbstractMessageConsumer {
+    constructor() {
+        super(...arguments);
+        /**
+         * @inheritdoc
+         */
+        this.type = NAVIGATION_DECISION_MESSAGE_TYPE;
+        /**
+         * @inheritdoc
+         */
+        this.supportedVersions = {
+            // eslint-disable-next-line @typescript-eslint/naming-convention -- expected naming for versions
+            '1.0': (message) => {
+                this.producerService.resolvePendingRequest(message.payload.correlationId, message.payload.proceed);
+            }
+        };
+        this.producerService = inject(NavigationRequestManagerService);
+    }
+    /** @nocollapse */ static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationDecisionConsumerService, deps: null, target: i0.ɵɵFactoryTarget.Injectable }); }
+    /** @nocollapse */ static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationDecisionConsumerService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: NavigationDecisionConsumerService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root'
+                }]
+        }] });
+
+/**
+ * Shell application guard intercepting shell-initiated navigation (sidebar clicks, URL bar, programmatic `router.navigate`)
+ * when the last state received from a module is `blocked`.
+ *
+ * Can be used as both `canActivate` and `canActivateChild` to ensure the guard runs when entering a route directly
+ * or navigating to its children.
+ *
+ * Flow:
+ * - No state received, or `blocked === false` → navigation proceeds.
+ * - `blocked === true` → open the confirmation modal.
+ *   - On cancel/dismiss → return `false`, state is untouched, no message sent to the module.
+ *   - On confirm → clear the shell mirror, send a `navigation-request` to the originating module (so it can run its unblock /
+ *     future draft-persistence logic), await its `navigation-decision`, then return `true`.
+ */
+const navigationBlockShellGuard = async () => {
+    const consumer = inject(NavigationBlockStateConsumerService);
+    const confirmation = inject(NavigationBlockConfirmationService);
+    const negotiation = inject(NavigationRequestManagerService);
+    const state = consumer.blockState();
+    if (!state?.blocked) {
+        return true;
+    }
+    const confirmed = await confirmation.confirm(state.reason);
+    if (!confirmed) {
+        return false;
+    }
+    consumer.clear();
+    if (!state.channelId) {
+        return true;
+    }
+    return negotiation.requestNavigation(state.channelId, state.reason);
+};
+
+/**
+ * Module-side guard intercepting navigation away from a page that holds unsaved changes.
+ *
+ * - `blocked === false` → navigation proceeds.
+ * - `blocked === true` → broadcast a `navigation-request` to the shell and await the reply. The shell opens the confirmation modal
+ *   and replies in both cases: `proceed === true` on confirm, `proceed === false` on cancel/dismiss. On proceed, clear the local
+ *   state and return `true`; on cancel, return `false` and leave the block state intact so the navigation is held and a later
+ *   attempt can negotiate again.
+ *
+ * Wire it as `canDeactivate` only on the routes that can actually hold unsaved work — modules opt in per page.
+ */
+const navigationBlockModuleGuard = async () => {
+    const store = inject(NavigationBlockService);
+    const negotiation = inject(NavigationRequestManagerService);
+    const { blocked, reason } = store.state();
+    if (!blocked) {
+        return true;
+    }
+    const proceed = await negotiation.requestNavigation(undefined, reason);
+    if (proceed) {
+        store.unblock();
+    }
+    return proceed;
+};
+
+/**
+ * Convenience helper that explicitly binds the {@link NAVIGATION_BLOCK_CONFIRMATION} token to {@link BrowserConfirmationStrategy}.
+ *
+ * **Usually unnecessary** — the token already defaults to `BrowserConfirmationStrategy` via its tree-shakable factory,
+ * so the helper only re-binds the same value. Use it when you want the binding to be visible at the call site
+ * (e.g. for documentation in `app.config.ts`) or when you've previously overridden the token and want to switch back
+ * to the default in a child injector.
+ *
+ * Production apps with a styled modal pass their own strategy via `provideNavigationConfig({ confirmationStrategy })` instead.
+ * @example
+ * ```typescript
+ * // app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideDefaultNavigationBlockConfirmation(),
+ *     // ... other providers
+ *   ]
+ * };
+ * ```
+ */
+function provideDefaultNavigationBlockConfirmation() {
+    return makeEnvironmentProviders([
+        {
+            provide: NAVIGATION_BLOCK_CONFIRMATION,
+            useClass: BrowserConfirmationStrategy
+        }
+    ]);
+}
+
+// Block state (module state, its producer, and the shell-side mirror consumer)
+
 /**
  * This service observe changes in the document's body height.
  * When the height changes, it sends a resize message with the new height, to the connected peers
@@ -1420,7 +1999,6 @@ class ThemeConsumerService extends AbstractMessageConsumer {
     constructor() {
         super();
         this.domSanitizer = inject(DomSanitizer);
-        this.logger = inject(LoggerService);
         /**
          * The type of messages this service handles ('theme').
          */
@@ -1447,6 +2025,11 @@ class ThemeConsumerService extends AbstractMessageConsumer {
                 }
             }
         };
+        /**
+         * Auto-starts the consumer on creation.
+         * @deprecated The constructor auto-starts the consumer for backwards compatibility. It will be removed in v15;
+         */
+        this.start();
     }
     /** @nocollapse */ static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: ThemeConsumerService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
     /** @nocollapse */ static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: ThemeConsumerService, providedIn: 'root' }); }
@@ -1874,5 +2457,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImpo
  * Generated bundle index. Do not edit.
  */
 
-export { ACTIVITY_EVENTS, AbstractMessageConsumer, ActivityConsumerService, ActivityProducerService, ApplyTheme, ConnectDirective, ConsumerManagerService, DEFAULT_ACTIVITY_PRODUCER_CONFIG, ERROR_MESSAGE_TYPE, HIGH_FREQUENCY_EVENTS, HistoryConsumerService, HostInfoPipe, IFRAME_INTERACTION_EVENT, IframeActivityTrackerService, IframeEmbedComponent, KNOWN_MESSAGES, MFE_HOST_APPLICATION_ID_PARAM, MFE_HOST_URL_PARAM, MFE_MODULE_APPLICATION_ID_PARAM, NavigationConsumerService, ProducerManagerService, ResizeConsumerService, ResizeService, RestoreRoute, RouteMemorizeDirective, RouteMemorizeService, RoutingService, ScalableDirective, THEME_QUERY_PARAM_NAME, THEME_URL_SUFFIX, ThemeConsumerService, ThemeProducerService, VISIBILITY_CHANGE_EVENT, applyInitialTheme, applyTheme, downloadApplicationThemeCss, getAvailableConsumers, getDefaultClientEndpointStartOptions, getHostInfo, getStyle, hostQueryParams, isEmbedded, isErrorMessage, isUserActivityMessage, persistHostInfo, provideConnection, provideHistoryOverrides, registerConsumer, registerProducer, sendError };
+export { ACTIVITY_EVENTS, AbstractMessageConsumer, ActivityConsumerService, ActivityProducerService, ApplyTheme, BrowserConfirmationStrategy, ConnectDirective, ConsumerManagerService, DEFAULT_ACTIVITY_PRODUCER_CONFIG, ERROR_MESSAGE_TYPE, HIGH_FREQUENCY_EVENTS, HistoryConsumerService, HostInfoPipe, IFRAME_INTERACTION_EVENT, IframeActivityTrackerService, IframeEmbedComponent, KNOWN_MESSAGES, MFE_HOST_APPLICATION_ID_PARAM, MFE_HOST_URL_PARAM, MFE_MODULE_APPLICATION_ID_PARAM, NAVIGATION_BLOCK_CONFIRMATION, NAVIGATION_REQUEST_HANDLER, NavigationBlockConfirmationService, NavigationBlockService, NavigationBlockStateConsumerService, NavigationBlockStateProducerService, NavigationConsumerService, NavigationDecisionConsumerService, NavigationRequestConsumerService, NavigationRequestManagerService, ProducerManagerService, ResizeConsumerService, ResizeService, RestoreRoute, RouteMemorizeDirective, RouteMemorizeService, RoutingService, ScalableDirective, THEME_QUERY_PARAM_NAME, THEME_URL_SUFFIX, ThemeConsumerService, ThemeProducerService, VISIBILITY_CHANGE_EVENT, applyInitialTheme, applyTheme, createNavigationRequestHandler, createNavigationRequestShellHandler, downloadApplicationThemeCss, generateCorrelationId, getAvailableConsumers, getDefaultClientEndpointStartOptions, getHostInfo, getStyle, hostQueryParams, isEmbedded, isErrorMessage, isUserActivityMessage, navigationBlockModuleGuard, navigationBlockShellGuard, persistHostInfo, provideConnection, provideDefaultNavigationBlockConfirmation, provideHistoryOverrides, provideNavigationRequestModuleHandler, provideNavigationRequestShellHandler, registerConsumer, registerProducer, sendError };
 //# sourceMappingURL=ama-mfe-ng-utils.mjs.map