@equinor/fusion-framework-module-navigation 7.0.3 → 7.0.5

package/src/NavigateEvent.ts

@@ -0,0 +1,47 @@
+import { FrameworkEvent, type FrameworkEventInit } from '@equinor/fusion-framework-module-event';
+
+import type { INavigationProvider } from './NavigationProvider.interface';
+import type { NavigationUpdate, Path } from './lib/types';
+
+/** Event detail for navigation events (before navigation). */
+export interface NavigateEventDetail {
+  /** The target path or location to navigate to */
+  location: NavigationUpdate;
+  /** Optional current location before navigation */
+  currentLocation?: Path;
+}
+
+/**
+ * Event emitted before navigation occurs.
+ * Can be canceled by calling `preventDefault()` to block the navigation.
+ *
+ * @example
+ * ```ts
+ * eventProvider.addEventListener('onNavigate', (event) => {
+ *   if (hasUnsavedChanges) {
+ *     event.preventDefault();
+ *   }
+ * });
+ * ```
+ */
+export class NavigateEvent extends FrameworkEvent<
+  FrameworkEventInit<NavigateEventDetail, INavigationProvider>
+> {
+  /** @param detail - Navigation target details. @param source - Provider dispatching the event. */
+  constructor(detail: NavigateEventDetail, source: INavigationProvider) {
+    super('onNavigate', {
+      detail,
+      source,
+    });
+  }
+}
+
+/** Declares navigation events in the FrameworkEventMap for type safety. */
+declare module '@equinor/fusion-framework-module-event' {
+  interface FrameworkEventMap {
+    /** Event emitted before navigation occurs, can be canceled to prevent navigation */
+    onNavigate: NavigateEvent;
+    /** Event emitted after navigation occurs */
+    onNavigated: import('./NavigatedEvent').NavigatedEvent;
+  }
+}

package/src/NavigatedEvent.ts

@@ -0,0 +1,35 @@
+import { FrameworkEvent, type FrameworkEventInit } from '@equinor/fusion-framework-module-event';
+
+import type { INavigationProvider } from './NavigationProvider.interface';
+import type { Action, NavigationUpdate } from './lib/types';
+
+/** Event detail for navigated events (after navigation). */
+export interface NavigatedEventDetail {
+  /** The navigation action that occurred (PUSH, POP, REPLACE) */
+  action: Action;
+  /** The new location after navigation */
+  current: NavigationUpdate;
+  /** The previous location before navigation */
+  previous: NavigationUpdate;
+}
+
+/**
+ * Event emitted after navigation completes.
+ * Contains the navigation action type and both current and previous locations.
+ *
+ * @example
+ * ```ts
+ * eventProvider.addEventListener('onNavigated', (event) => {
+ *   const { action, current, previous } = event.detail;
+ *   console.log(`${action}: ${previous.location.pathname} -> ${current.location.pathname}`);
+ * });
+ * ```
+ */
+export class NavigatedEvent extends FrameworkEvent<
+  FrameworkEventInit<NavigatedEventDetail, INavigationProvider>
+> {
+  /** @param detail - Completed navigation details. @param source - Provider dispatching the event. */
+  constructor(detail: NavigatedEventDetail, source: INavigationProvider) {
+    super('onNavigated', { detail, source });
+  }
+}

package/src/NavigationConfigurator.ts

@@ -67,9 +67,11 @@ const parseNavigationConfig = (config: unknown): INavigationConfigurator => {
  * Extends BaseConfigBuilder to provide fluent configuration API with Zod validation.
  */
 export class NavigationConfigurator extends BaseConfigBuilder<INavigationConfigurator> {
+  /** Creates a navigation configurator with default history and event providers. */
   constructor() {
     super();
     this.setEventProvider(async (args) => {
+      // Only resolve the optional provider when the event module participates in this framework.
       if (args.hasModule('event')) {
         return await args.requireInstance('event');
       }
@@ -77,10 +79,12 @@ export class NavigationConfigurator extends BaseConfigBuilder<INavigationConfigu
     this.setHistory(
       async (args) => {
         const history = (args.ref as ModulesInstance<[NavigationModule]>)?.navigation?.history;
+        // Wrap supplied history so the module owns only the proxy lifecycle.
         if (history) {
           // Wrap the provided history in a ProxyHistory to ensure the module can manage its own teardowns without affecting the original instance.
           return new ProxyHistory(history);
         }
+        // Prefer browser history when a DOM is available, otherwise use memory history for SSR.
         if (typeof window !== 'undefined') {
           return createHistory('browser');
         }
@@ -92,8 +96,10 @@ export class NavigationConfigurator extends BaseConfigBuilder<INavigationConfigu
   }
   /**
    * @deprecated Use `setBasename()` method instead
+   * @param value - Deprecated basename value to configure.
    */
   public set basename(value: string | undefined) {
+    // Warn only during development so deprecated setters remain silent in production.
     if (process.env.NODE_ENV === 'development') {
       console.warn('NavigationConfigurator.basename', 'use setBasename() method instead');
     }
@@ -102,8 +108,10 @@ export class NavigationConfigurator extends BaseConfigBuilder<INavigationConfigu
 
   /**
    * @deprecated Use `setHistory()` method instead
+   * @param value - Deprecated history value to configure.
    */
   public set history(value: History | undefined) {
+    // Warn only during development so deprecated setters remain silent in production.
     if (process.env.NODE_ENV === 'development') {
       console.warn('NavigationConfigurator.history', 'use setHistory() method instead');
     }
@@ -149,14 +157,16 @@ export class NavigationConfigurator extends BaseConfigBuilder<INavigationConfigu
         : // Normalize a direct instance to a callback for consistent handling.
           async () => historyOrCallback;
 
+    // Proxying isolates teardown ownership when callers provide an existing history instance.
     if (proxy) {
       // Wrap each emitted history in a ProxyHistory so dispose only tears down
       // proxy-owned listeners/blockers, never the underlying history itself.
       this._set('history', (args) =>
-        from(resolve(args) as ObservableInput<History | undefined>).pipe(
-          map((history) => (history ? new ProxyHistory(history) : undefined)),
-        ),
+        from(resolve(args) as ObservableInput<History | undefined>)
+          // Transform each resolved history into an independently disposable proxy.
+          .pipe(map((history) => (history ? new ProxyHistory(history) : undefined))),
       );
+      // Direct histories are already owned by the navigation module and can be used unchanged.
     } else {
       this._set('history', resolve);
     }

package/src/NavigationProvider.interface.ts

@@ -1,4 +1,4 @@
-// TODO: Remove @remix-run/router dependency once all apps have migrated to @equinor/fusion-framework-react-router
+// TODO(#5158): Remove @remix-run/router dependency once all apps have migrated to @equinor/fusion-framework-react-router
 import type { AgnosticRouteObject, Router } from '@remix-run/router';
 
 import type { History, NavigateOptions } from './lib/types';

package/src/NavigationProvider.ts

@@ -1,4 +1,4 @@
-// TODO: Remove @remix-run/router dependency once all apps have migrated to @equinor/fusion-framework-react-router
+// TODO(#5158): Remove @remix-run/router dependency once all apps have migrated to @equinor/fusion-framework-react-router
 import { type AgnosticRouteObject, createRouter } from '@remix-run/router';
 import type { Observable } from 'rxjs';
 import { filter, pairwise, shareReplay } from 'rxjs/operators';
@@ -17,7 +17,7 @@ import {
   type ITelemetryProvider,
 } from '@equinor/fusion-framework-module-telemetry';
 import type { IEventModuleProvider } from '@equinor/fusion-framework-module-event';
-import { NavigatedEvent } from './events';
+import { NavigatedEvent } from './NavigatedEvent';
 import { pathToString } from './lib/utils';
 import type { BaseHistory } from './lib';
 
@@ -68,6 +68,7 @@ export class NavigationProvider
 
   /**
    * Observable stream of navigation state updates.
+   * @returns Observable of navigation updates.
    *
    * Emits localized paths (with basename removed) and filters to only
    * paths within the basename scope. Late subscribers receive the last
@@ -88,6 +89,7 @@ export class NavigationProvider
 
   /**
    * @deprecated Use `history` instead
+   * @returns The underlying `History` instance.
    */
   public get navigator(): History {
     this.#telemetry?.trackException({
@@ -101,6 +103,7 @@ export class NavigationProvider
 
   /**
    * Gets the underlying history instance.
+   * @returns The {@link History} instance used for navigation
    *
    * @returns The {@link History} instance used for navigation
    */
@@ -129,7 +132,13 @@ export class NavigationProvider
     // Extract configuration values
     const { basename, history, telemetry, eventProvider } = args.config;
 
-    this.#basename = basename;
+    // Normalize the basename to strip trailing slashes. React Router requires
+    // the current URL to start with the exact basename string, so a basename
+    // of "/apps/my-app/" would fail to match the URL "/apps/my-app" and
+    // render nothing (blank page).
+    // Preserve slash-only basenames (e.g. "/") by falling back to the
+    // original input when normalization collapses to an empty string.
+    this.#basename = basename ? normalizePathname(basename) || basename : basename;
     this.#event = eventProvider;
     this.#telemetry = telemetry;
 
@@ -229,6 +238,9 @@ export class NavigationProvider
       level: TelemetryLevel.Warning,
       scope: ['navigation', 'deprecated', TelemetryScope.Application],
     });
+    // `this.#history` is typed as the framework's minimal history interface, but Remix Router
+    // requires its own richer `History` type — the two are runtime-compatible, so cast through
+    // `unknown`.
     const router = createRouter({
       basename: this.#basename,
       history: this.#history as unknown as import('@remix-run/router').History,

package/src/__tests__/NavigationProvider.test.ts

@@ -57,4 +57,15 @@ describe('NavigationProvider', () => {
     provider.dispose();
     expect(disposeSpy).toHaveBeenCalled();
   });
+
+  it('should preserve root basename when set to slash', () => {
+    const providerWithRootBasename = new NavigationProvider({
+      version: '1.0.0',
+      config: { history, basename: '/' },
+    });
+
+    expect(providerWithRootBasename.basename).toBe('/');
+
+    providerWithRootBasename.dispose();
+  });
 });

package/src/enable-navigation.ts

@@ -47,6 +47,7 @@ export const enableNavigation = <TRef = unknown>(
   configurator.addConfig({
     module,
     configure(config, ref) {
+      // A string shortcut sets the basename directly; otherwise defer to the caller's configure callback.
       if (typeof basenameOrOptions === 'string') {
         config.setBasename(basenameOrOptions);
       } else if (typeof basenameOrOptions === 'object' && 'configure' in basenameOrOptions) {

package/src/index.ts

@@ -33,12 +33,8 @@ export { NavigationProvider } from './NavigationProvider';
 
 export { createHistory } from './lib/create-history';
 
-export {
-  NavigateEvent,
-  NavigatedEvent,
-  type NavigateEventDetail,
-  type NavigatedEventDetail,
-} from './events';
+export { NavigateEvent, type NavigateEventDetail } from './NavigateEvent';
+export { NavigatedEvent, type NavigatedEventDetail } from './NavigatedEvent';
 
 export type {
   Path,

package/src/lib/BaseHistory.ts

@@ -49,6 +49,7 @@ export abstract class BaseHistory implements History {
   /**
    * Observable stream of navigation state changes.
    * Emits on all navigation events (push, replace, pop).
+   * @returns Observable of the current navigation update.
    */
   public get state$(): History['state$'] {
     return this.#state.subject.select((state) => state.current);
@@ -56,6 +57,7 @@ export abstract class BaseHistory implements History {
 
   /**
    * Observable stream of navigation actions.
+   * @returns Observable of navigation actions.
    */
   public get action$(): History['action$'] {
     return this.#state.subject.action$;
@@ -70,6 +72,7 @@ export abstract class BaseHistory implements History {
     return this.#state.subject.value.blockers.length > 0;
   }
 
+  /** @param state - Reactive history state backing this implementation. */
   protected constructor(state: HistoryState) {
     this.#state = state;
   }
@@ -117,6 +120,8 @@ export abstract class BaseHistory implements History {
 
   /**
    * Pushes a new location onto the history stack.
+   * @param to - Target path or partial path object.
+   * @param state - Optional state associated with the new location.
    */
   public push(to: To, state?: unknown): void {
     this.navigate(to, { state });
@@ -124,6 +129,8 @@ export abstract class BaseHistory implements History {
 
   /**
    * Replaces the current location in the history stack.
+   * @param to - Target path or partial path object.
+   * @param state - Optional state associated with the replacement location.
    */
   public replace(to: To, state?: unknown): void {
     this.navigate(to, { replace: true, state });
@@ -185,6 +192,7 @@ export abstract class BaseHistory implements History {
     return this._addTeardown(removeBlocker, { executeOnRemove: true });
   }
 
+  /** Triggers a POP action for the current history location. */
   public pop(): void {
     this.#state.subject.next(this.#state.actions.pop());
   }
@@ -225,6 +233,7 @@ export abstract class BaseHistory implements History {
   ): VoidFunction {
     this.#teardowns.add(teardown);
     return () => {
+      // Execute teardown callbacks immediately when callers explicitly request removal side effects.
       if (options?.executeOnRemove) {
         typeof teardown === 'function' ? teardown() : teardown.unsubscribe();
       }

package/src/lib/BrowserHistory.ts

@@ -59,6 +59,7 @@ export class BrowserHistory extends BaseHistory {
     // Use provided stack or default to BrowserHistoryStack
     const Stack: StackConstructor = options.stack ?? BrowserHistoryStack;
     const browserWindow = options.window ?? document.defaultView;
+    // Fail fast without a window since the browser stack depends on the DOM history API.
     if (!browserWindow) {
       throw new Error('Window is required');
     }

package/src/lib/BrowserHistoryHashStack.ts

@@ -18,6 +18,7 @@ import { resolveHashLocation, resolvePath, pathToString } from './utils';
 export class BrowserHistoryHashStack extends BrowserHistoryStack {
   /**
    * Gets the current location from window.location.hash.
+   * @returns The current hash-derived navigation location.
    */
   public get current(): Readonly<Location> {
     return resolveHashLocation(this._window);

package/src/lib/BrowserHistoryStack.ts

@@ -22,6 +22,7 @@ export class BrowserHistoryStack implements HistoryStack {
 
   /**
    * Gets the origin of the history stack.
+   * @returns The browser origin used as the URL base.
    */
   public get origin(): string {
     return this._window.location.origin;
@@ -29,6 +30,7 @@ export class BrowserHistoryStack implements HistoryStack {
 
   /**
    * Gets the current location.
+   * @returns The current browser location converted to a navigation location.
    */
   public get current(): Location {
     return resolveWindowLocation(this._window);
@@ -36,6 +38,7 @@ export class BrowserHistoryStack implements HistoryStack {
 
   /**
    * Pushes a new entry onto the history stack.
+   * @param location - Location to append to browser history.
    */
   public push(location: Location): void {
     this.navigate(location, 'PUSH');
@@ -43,6 +46,7 @@ export class BrowserHistoryStack implements HistoryStack {
 
   /**
    * Replaces the current entry in the history stack.
+   * @param location - Location to replace in browser history.
    */
   public replace(location: Location): void {
     this.navigate(location, 'REPLACE');
@@ -50,10 +54,13 @@ export class BrowserHistoryStack implements HistoryStack {
 
   /**
    * Navigates to a location with the specified action.
+   * @param location - Location to navigate to.
+   * @param action - Native history action to perform.
    */
   public navigate(location: Location, action: 'PUSH' | 'REPLACE'): void {
     const relativePath = this._createRelativePath(location);
     const state = { value: location.state, key: location.key };
+    // Select the native operation matching the requested navigation action.
     if (action === 'PUSH') {
       this._window.history.pushState(state, '', relativePath);
     } else {
@@ -63,6 +70,7 @@ export class BrowserHistoryStack implements HistoryStack {
 
   /**
    * Navigates backward or forward in the history stack.
+   * @param delta - Number of entries to move backward or forward.
    */
   public go(delta: number): void {
     this._window.history.go(delta);
@@ -70,11 +78,18 @@ export class BrowserHistoryStack implements HistoryStack {
 
   /**
    * Creates a URL object for a given path.
+   * @param to - Target path or partial path object.
+   * @returns URL resolved against the browser origin.
    */
   public createURL(to: To): URL {
     return new URL(pathToString(resolvePath(to)), this.origin);
   }
 
+  /**
+   * Creates the relative URL path used by native browser history.
+   * @param to - Target path or partial path object.
+   * @returns Relative URL path for browser history.
+   */
   protected _createRelativePath(to: To): string {
     return pathToString(this.createURL(to));
   }

package/src/lib/MemoryHistory.ts

@@ -1,6 +1,6 @@
 import { type To, type LocationState, type NavigationUpdate, Action } from './types';
 import { pathToString, resolvePath } from './utils';
-import { MemoryHistoryStack } from './MemoryStack';
+import { MemoryHistoryStack } from './MemoryHistoryStack';
 import { BaseHistory } from './BaseHistory';
 import { createHistoryReducer, createStore } from './state';
 
@@ -40,6 +40,7 @@ export type MemoryHistoryOptions = {
  * - **Node.js** — any environment without browser history APIs
  */
 export class MemoryHistory extends BaseHistory {
+  /** @param options - Optional initial location and history entries. */
   public constructor(options?: MemoryHistoryOptions) {
     const { initialLocation, initialHistory } = options ?? {};
     const initial = initialLocation ?? defaultInitialLocation;
@@ -65,6 +66,8 @@ export class MemoryHistory extends BaseHistory {
 
   /**
    * Creates a URL object for a given path using memory:// origin.
+   * @param to - Target path or partial path object.
+   * @returns URL resolved against memory://.
    */
   public createURL(to: To): URL {
     const path = pathToString(resolvePath(to));

package/src/lib/{MemoryStack.ts → MemoryHistoryStack.ts}

@@ -14,6 +14,7 @@ export class MemoryHistoryStack implements HistoryStack {
   /**
    * Gets the origin of the history stack.
    * Always returns 'memory://' for in-memory storage.
+   * @returns The fixed origin used for in-memory URLs.
    */
   get origin(): string {
     return 'memory://';
@@ -21,6 +22,7 @@ export class MemoryHistoryStack implements HistoryStack {
 
   /**
    * Gets the current location.
+   * @returns The current in-memory navigation location.
    */
   get current(): Location {
     return this.#current;
@@ -47,6 +49,7 @@ export class MemoryHistoryStack implements HistoryStack {
    * Pushes a new entry onto the history stack.
    *
    * Only updates the current location. History entries are managed by the reducer.
+   * @param location - Location to make current.
    */
   push(location: Location): void {
     this.#current = location;
@@ -56,6 +59,7 @@ export class MemoryHistoryStack implements HistoryStack {
    * Replaces the current entry in the history stack.
    *
    * Only updates the current location. History entries are managed by the reducer.
+   * @param location - Location to make current.
    */
   replace(location: Location): void {
     this.#current = location;
@@ -74,10 +78,13 @@ export class MemoryHistoryStack implements HistoryStack {
     const { history, current } = state;
     const currentLocation = current.location ?? this.#current;
     // Find current location in history by key
+    // Locate the current entry so relative navigation can preserve stack boundaries.
     const currentIndex = history.findIndex((entry) => entry.location.key === currentLocation.key);
 
     // If current location not found, use last entry
+    // Fall back to the newest entry when the stack cannot identify the current location.
     if (currentIndex === -1) {
+      // Restore the latest known entry when the history cannot locate the current key.
       if (history.length > 0) {
         this.#current = history[history.length - 1].location;
       }
@@ -86,8 +93,10 @@ export class MemoryHistoryStack implements HistoryStack {
 
     // Calculate target index and clamp to valid range
     const newIndex = currentIndex + delta;
+    // Clamp the destination to the available history range.
     if (newIndex < 0) {
       this.#current = state.history[0].location;
+      // Use the oldest entry when navigation moves beyond the end of the stack.
     } else if (newIndex >= state.history.length) {
       this.#current = state.history[state.history.length - 1].location;
     } else {
@@ -99,6 +108,8 @@ export class MemoryHistoryStack implements HistoryStack {
    * Creates a URL object for a given path.
    *
    * All URLs use the 'memory://' origin since this is in-memory storage.
+   * @param to - Target path or partial path object.
+   * @returns URL resolved against memory://.
    */
   createURL(to: To): URL {
     const path = resolvePath(to);

package/src/lib/ProxyHistory.ts

@@ -11,7 +11,7 @@ import type {
   Path,
   To,
 } from './types';
-import type { Actions } from './state/history.actions';
+import type { Actions } from './state/actions';
 
 /**
  * A lightweight proxy that delegates every {@link History} operation to an
@@ -109,6 +109,7 @@ export class ProxyHistory implements History {
    * instance; otherwise this is a no-op.
    */
   pop(): void {
+    // Only BaseHistory implementations expose pop(); anything else is a no-op.
     if ('pop' in this.#target && typeof this.#target.pop === 'function') {
       (this.#target as BaseHistory).pop();
     }

package/src/lib/create-history.ts

@@ -33,6 +33,7 @@ export const createHistory = <T extends keyof HistoryCtorMap>(
   type: T,
   ...args: Parameters<HistoryCtorMap[T]>
 ): ReturnType<HistoryCtorMap[T]> => {
+  // Dispatch to the history implementation matching the requested type.
   switch (type) {
     case 'memory':
       return new MemoryHistory(...(args as [MemoryHistoryOptions])) as ReturnType<

package/src/lib/index.ts

@@ -17,7 +17,7 @@ export { ProxyHistory } from './ProxyHistory';
 // History stacks
 export { BrowserHistoryStack } from './BrowserHistoryStack';
 export { BrowserHistoryHashStack as HashHistoryStack } from './BrowserHistoryHashStack';
-export { MemoryHistoryStack } from './MemoryStack';
+export { MemoryHistoryStack } from './MemoryHistoryStack';
 
 // Types
 export type {

package/src/lib/state/check-blockers.ts

@@ -0,0 +1,52 @@
+import { Observable, of } from 'rxjs';
+import { concatMap, map, withLatestFrom } from 'rxjs/operators';
+import type { HistoryFlowCreator } from './navigate';
+import { actions, type Actions } from './actions';
+import { filterAction } from '@equinor/fusion-observable/operators';
+import { Action, type HistoryStack, type LocationState } from '../types';
+
+/** Flow creator that gates navigation actions through registered blockers. */
+export const checkBlockers: HistoryFlowCreator =
+  (stack: HistoryStack) => (action$: Observable<Actions>, state$: Observable<LocationState>) =>
+    // Normalize each navigation-related action into a common shape before gating on blockers.
+    action$.pipe(
+      filterAction(
+        actions.navigate.type,
+        actions.pop.type,
+        actions.go.type,
+        actions.validateLocation.type,
+      ),
+      map((action) => {
+        // Only `navigate` carries a replace flag; the rest are treated as POP transitions.
+        switch (action.type) {
+          case actions.navigate.type:
+            return { replace: action.payload.options.replace, action };
+          case actions.go.type:
+          case actions.pop.type:
+          case actions.validateLocation.type:
+            return { type: 'POP' as Action, action };
+        }
+      }),
+      withLatestFrom(state$),
+      concatMap(([{ action, replace }, state]) => {
+        // Allow actions through immediately when no blocker can veto the transition.
+        if (!state.blockers.length) {
+          return of(action);
+        }
+        return new Observable<Actions>((subscriber) => {
+          const location = stack.current;
+          // Invoke all blockers and complete once every asynchronous decision settles.
+          const blockers = state.blockers.map((blocker) =>
+            Promise.resolve(
+              blocker({
+                delta: 0,
+                action: replace ? Action.Replace : Action.Push,
+                location,
+                retry: () => subscriber.next(action),
+              }),
+            ),
+          );
+          Promise.allSettled(blockers).then(() => subscriber.complete());
+        });
+      }),
+    );

package/src/lib/state/create-flow.ts

@@ -0,0 +1,36 @@
+import { merge, type Observable } from 'rxjs';
+import type { HistoryFlow, HistoryFlowCreator } from './navigate';
+import { checkBlockers } from './check-blockers';
+import type { Actions } from './actions';
+import type { HistoryStack, LocationState } from '../types';
+
+/**
+ * Creates a combined history flow from multiple flow creators.
+ * @param flowCreators - Flow creators to combine.
+ * @param options - Optional blocker configuration.
+ * @returns A combined history flow creator.
+ */
+export const createFlow = (
+  flowCreators: HistoryFlowCreator[],
+  options?: { skipBlockCheck?: boolean },
+): HistoryFlowCreator => {
+  return (stack: HistoryStack): HistoryFlow => {
+    const preProcessActions = options?.skipBlockCheck
+      ? (action$: Observable<Actions>) => action$
+      : checkBlockers(stack);
+    const flows: HistoryFlow = (
+      action$: Observable<Actions>,
+      state$: Observable<LocationState>,
+    ) => {
+      // Initialize each creator against the same stack before merging their action streams.
+      const initializedFlows = flowCreators
+        .map((initializer) => initializer(stack))
+        .map((flow) => flow(action$, state$));
+      return merge(...initializedFlows);
+    };
+    return (action$: Observable<Actions>, state$: Observable<LocationState>) => {
+      // Gate actions before dispatching them to the parallel history flows.
+      return preProcessActions(action$, state$).pipe((source$) => flows(source$, state$));
+    };
+  };
+};

package/src/lib/state/{history.reducer.ts → create-history-reducer.ts}

@@ -1,6 +1,6 @@
 import { createReducer } from '@equinor/fusion-observable';
 import type { LocationState, NavigationUpdate } from '../types';
-import { actions, type Actions } from './history.actions';
+import { actions, type Actions } from './actions';
 import { isSuccessAction } from '@equinor/fusion-observable/actions';
 
 /**
@@ -8,6 +8,7 @@ import { isSuccessAction } from '@equinor/fusion-observable/actions';
  * Used to determine where to insert/replace entries for REPLACE actions.
  */
 const findIndex = (state: LocationState) => {
+  // Locate the current entry by key rather than reference, since updates are cloned.
   return state.history.findIndex((update) => update.location.key === state.current.location.key);
 };
 
@@ -47,6 +48,7 @@ export const createHistoryReducer = (
       // and removes any forward history when not at the end
       if (update.action === 'REPLACE') {
         const currentIndex = findIndex(state);
+        // Only trim when the current entry is actually present in history.
         if (currentIndex !== -1) {
           // Remove all entries from current position onwards
           state.history.splice(currentIndex, state.history.length - currentIndex);
@@ -64,6 +66,7 @@ export const createHistoryReducer = (
     builder.addMatcher(
       () => true,
       (state) => {
+        // Trim only once history has actually grown past the configured cap.
         if (state.history.length > maxHistory) {
           // Keep only the most recent entries, removing oldest ones
           state.history = state.history.slice(-maxHistory);