feat(context-navigation): add plugin package, dev portal integration, and plugin docs (#4751)

* feat(context-navigation): add context navigation plugin package

Introduce a new plugin that manages bidirectional synchronization
between the browser URL and the selected context (e.g. facility,
project).

Supports three routing strategies:
- 'path': context ID embedded in the URL path segment
- 'query': context ID as a query parameter (?contextId=...)
- 'custom': consumer-provided adapter for non-standard URL layouts

Key capabilities:
- URL guard that intercepts navigation to resolve context from URLs
- Reconciler that updates the URL when context changes programmatically
- App-first and context-first source factories for initial resolution
- Active-app navigation event stream for cross-app context handoff
- Legacy app path normalization for backward compatibility

Includes full test coverage for plugin lifecycle, guard handlers,
reconciliation logic, and navigation event operators.

* feat(context): add routing strategy and navigation fixes

Extend the context module with a routingStrategy configuration option
that controls how context identity is represented in URLs ('path' or
'query'). This is the foundation the context-navigation plugin reads
to decide which adapter to use.

Context module changes:
- Add routingStrategy to ContextModuleConfig and configurator
- Add setRoutingStrategy() to ContextConfigBuilder
- Update resolveContextFromPath with custom matcher support and TSDoc
- Simplify resolveInitialContext to only resolve from parent context
  (URL-based resolution is now handled by the plugin)
- Expose routingStrategy on ContextProvider and IContextProvider
- Add routingStrategy as third argument to generatePathFromContext
- Add migration guide for routing strategy adoption

Navigation module changes:
- Stop stripping trailing slashes in normalizePathname
- Fix basename boundary check in _isWithinBasenameScope to prevent
  false positives from overlapping app name prefixes
- Fall back to '/' in _localizePath when basename-stripped path is empty

* feat(dev-portal): integrate context navigation plugin

Wire up the context-navigation plugin in the dev portal so that apps
running in the development shell get automatic URL-to-context
synchronization matching production behavior.

Dev portal changes:
- Enable context-navigation plugin with setPortalName, setDebug,
  and setUrlGuard in dev portal config
- Enable context module with path generator and extractor using
  plugin utility functions (buildContextUrlForStrategy,
  resolveContextIdFromUrl)
- Set explicit 'path' routing strategy
- Delete useAppContextNavigation hook (replaced by plugin)
- Remove useAppContextNavigation() call from Router component
- Update README to document context navigation plugin integration

Cookbook changes:
- Add explicit setRoutingStrategy('path') to context-using cookbook
  configs (app-react-context, app-react-bookmark,
  app-react-bookmark-advanced, app-react-context-custom-error,
  portal-analytics)

* docs: add plugin documentation, migration guides, and changesets

VuePress documentation:
- Add top-level plugins section with overview of plugin vs module
  intent and the context-navigation plugin README
- Add context routing strategy migration guide under modules/context
- Update sidebar and theme config for new plugin section

Changesets:
- plugin-context-navigation: initial release (minor)
- module-context: routing strategy addition (minor)
- module-navigation: trailing-slash and basename fix (patch)
- dev-portal: context navigation integration (patch)

Also updates pnpm-lock.yaml for new plugin package dependency.

* docs: improve context routing documentation and fix TSDoc accuracy

* fix(changeset): correct context module changeset to reflect actual changes vs main

The previous changeset described removing routingStrategy from the context
module, but that feature never existed on main. The actual change is moving
URL-based initial context resolution from the context module to the
context-navigation plugin.

Changes:
- Downgrade from major to patch (no breaking changes vs main)
- Accurately describe the URL resolution responsibility shift
- Remove references to routingStrategy removal (never existed on main)
- Keep migration guidance focused on plugin enablement

* fix(context-provider): suppress TypeScript errors for future signature updates

* fix(navigation): normalize basename to treat '/' as no-basename and fix scope checks

* fix(context-navigation): force replace:true on app switch and URL drift correction to prevent back-navigation traps

* fix(navigation): prevent ReDoS vulnerability in pathname normalization

Replace regex-based slash collapsing with iterative approach to eliminate
potential Regular Expression Denial of Service attack when processing
user-controlled basename values with pathological input.

The normalizePathname function now guarantees O(n) linear time complexity
instead of using /\/+/g regex pattern that could be exploited with
thousands of consecutive slashes.

Adds ReDoS protection test to verify performance with pathological input.

Resolves CodeQL security alert: Polynomial regular expression used on
uncontrolled data (High severity)

Related: #4751

* fix(context-navigation): clear hash fragment on context changes

Hash fragments are intentionally cleared when context changes to prevent
inconsistent app state. When a context change resets the app to its root
view, preserving the hash would leave anchors pointing to sections that
may not exist in the new context.

This matches the existing behavior for sub-routes (intentionally dropped)
and maintains consistency across all three adapters (path, query, custom).

Adds test to verify hash is cleared on context change.

Addresses PR review feedback in #4751

* fix(navigation): eliminate remaining ReDoS vulnerability in trailing slash removal

Replace regex-based trailing slash removal (.replace(/\/+$/, '')) with
iterative stripTrailingSlashes() function to prevent ReDoS attacks.

The /\/+$/ pattern can cause exponential backtracking when processing
basenames with thousands of trailing slashes. The new stripTrailingSlashes
function guarantees O(n) linear time by scanning backwards from the end.

Added test verifying performance with 10k trailing slashes (< 100ms).

This completes the ReDoS vulnerability remediation - both consecutive
slash patterns are now safe:
- normalizePathname: O(n) forward scan (commit ee14d80)
- stripTrailingSlashes: O(n) backward scan (this commit)

Addresses CodeQL alert: Polynomial regular expression used on uncontrolled data

* fix(navigation): refactor pathname normalization functions to improve performance and avoid ReDoS vulnerabilities

* refactor: improve readability by adding braces to conditional statements and using array for path construction

* chore: remove unnecessary blank line in handleReplaceModeGuard function

Author: Noggling

.changeset/fusion-framework-dev-portal_context-navigation-handler.md

@@ -0,0 +1,7 @@
+---
+"@equinor/fusion-framework-dev-portal": patch
+---
+
+Integrate `@equinor/fusion-framework-plugin-context-navigation` into the dev portal.
+
+Portal context-to-URL reconciliation is now handled by `@equinor/fusion-framework-plugin-context-navigation`, replacing the ad-hoc hook-based approach.

.changeset/fusion-framework-module-context_routing-strategy.md

@@ -0,0 +1,16 @@
+---
+"@equinor/fusion-framework-module-context": patch
+---
+
+Move URL-based initial context resolution to the context-navigation plugin.
+
+The context module's `resolveInitialContext` no longer resolves context from the URL path — that responsibility has been moved to `@equinor/fusion-framework-plugin-context-navigation` at the portal level. This decouples URL concerns from the context module.
+
+**Changes:**
+
+- `resolveInitialContext` no longer accepts the `options` parameter with path resolution config.
+- URL-based initial context resolution is now handled by the context-navigation plugin.
+- Added `version` property to `IContextProvider` interface (non-breaking).
+- Added explanatory `@ts-ignore` directives on compatibility assignments to avoid a breaking API signature change in this release.
+
+**Migration:** Apps do not need to change their code. Portal hosts should enable the `@equinor/fusion-framework-plugin-context-navigation` plugin to restore URL-based context resolution behavior.

.changeset/fusion-framework-module-navigation_trailing-slash-fix.md

@@ -0,0 +1,9 @@
+---
+"@equinor/fusion-framework-module-navigation": patch
+---
+
+Fix basename boundary matching and trailing-slash handling.
+
+- `normalizePathname` no longer strips trailing slashes — only collapses consecutive slashes. Trailing slash is now preserved as part of the path identity.
+- `_isWithinBasenameScope` uses a path-boundary check (`pathname === basename || pathname.startsWith(basename + '/')`) to prevent false positives from apps with overlapping name prefixes (e.g. `/apps/my-app` no longer matches `/apps/my-app-other/foo`).
+- `_localizePath` falls back to `'/'` when the basename-stripped pathname is empty.

.changeset/fusion-framework-plugin-context-navigation_initial.md

@@ -0,0 +1,19 @@
+---
+"@equinor/fusion-framework-plugin-context-navigation": minor
+---
+
+Initial release of the context navigation plugin.
+
+Adapter-based, event-driven plugin that reconciles context selection with the browser URL for portal hosts. Ships with built-in adapters for query-param, path-segment, and custom URL shapes, plus two pre-wired source strategies:
+
+- **app-first** — app sets context, the plugin encodes it to the URL.
+- **context-first** — the plugin decodes context from the URL on startup, redirects to a configurable null-context URL when no context is resolvable.
+
+```ts
+import { enableContextNavigation } from '@equinor/fusion-framework-plugin-context-navigation';
+import { createAppFirstSource } from '@equinor/fusion-framework-plugin-context-navigation/sources';
+
+enableContextNavigation(configurator, (builder) => {
+  builder.setSourceFactory(createAppFirstSource());
+});
+```

.changeset/module-navigation_fix-redos-vulnerability.md

@@ -0,0 +1,11 @@
+---
+"@equinor/fusion-framework-module-navigation": patch
+---
+
+**Security Fix**: Replaced regex-based pathname normalization with iterative approach to prevent potential ReDoS (Regular Expression Denial of Service) vulnerability when processing user-controlled basename values.
+
+The `normalizePathname` function now uses a simple character-by-character scan instead of `/\/+/g` regex, ensuring O(n) linear time complexity even with pathological input containing thousands of consecutive slashes.
+
+This addresses CodeQL security alert: "Polynomial regular expression used on uncontrolled data"
+
+Related: #4751

CODEMAP.md

@@ -13,7 +13,7 @@ search to rediscover it.
 
 | Path | Contains | Published? |
 | --- | --- | --- |
-| `packages/*` | Framework libraries (58 packages) | Yes, via Changesets |
+| `packages/*` | Framework libraries (59 packages) | Yes, via Changesets |
 | `cookbooks/*` | Runnable example apps and portals | Yes (versioned, but examples) |
 | `eds-content/`, `eds/` | EDS design-system content and token tooling | No |
 | `vue-press/` | Documentation site | Partly |
@@ -82,7 +82,13 @@ Format: `package name` → path → role.
 | `@equinor/fusion-framework-react-components-bookmark` | `packages/react/components/bookmark` | Bookmark UI components |
 | `@equinor/fusion-framework-react-components-people-provider` | `packages/react/components/people-resolver` | People resolver components |
 
-### Utils (`packages/utils/*`)
+### Plugins (`packages/plugins/*`)i
+
+| Package | Path | Role |
+| --- | --- | --- |
+| `@equinor/fusion-framework-plugin-context-navigation` | `packages/plugins/context-navigation` | Plugin for context-based navigation handling |
+
+## Utils (`packages/utils/*`)
 
 | Package | Path | Role |
 | --- | --- | --- |

package.json

@@ -40,6 +40,7 @@
     "lint:fusion": "pnpm build:lint && pnpm lint:fusion:packages && pnpm lint:fusion:cookbooks",
     "lint:fusion:packages": "fusion-lint lint packages",
     "lint:fusion:cookbooks": "fusion-lint lint cookbooks",
+    "lint:fusion:plugins": "fusion-lint lint packages/plugins",
     "lint:staged": "biome lint --staged",
     "verify:agent-context": "node .github/scripts/verify-agent-context.mjs",
     "format": "biome format",

packages/dev-portal/README.md

@@ -13,7 +13,7 @@ Use this package when you need a portal host for local app development. For the
 - **Portal shell**: A React application that renders the top bar, context selector, and an app mounting area.
 - **Application loader**: Dynamically initializes and mounts a Fusion app by its `appKey`, handling manifest resolution, script loading, and teardown.
 - **Framework modules**: The portal pre-configures telemetry, navigation, bookmarks, feature flags, analytics, AG Grid, and service integrations so loaded apps inherit a realistic environment.
-- **Context navigation**: When an app uses the context module, the portal synchronizes URL navigation with context changes automatically.
+- **Context navigation plugin**: The portal enables `enableContextNavigation` from `@equinor/fusion-framework-plugin-context-navigation` so context changes and app switches keep the URL in sync automatically.
 
 ## Installation
 
@@ -94,12 +94,13 @@ const devServer = await createDevServer({
 The portal is composed of these internal parts:
 
 - **`render`** — Entry point; creates a React root with theme, framework, and people-resolver providers.
-- **`configure`** — Configures all framework modules (telemetry, navigation, bookmarks, feature flags, analytics, AG Grid, services).
+- **`configure`** — Configures all framework modules (telemetry, navigation, context navigation, bookmarks, feature flags, analytics, AG Grid, services).
+- **Context configuration** — `enableContext` wires the context module's path generator and path extractor to the shared context-navigation URL utilities.
 - **`Router`** — Sets up routes with `react-router` via the navigation module; routes `/apps/:appKey/*` to the app loader.
 - **`AppLoader`** — Resolves, initializes, and mounts a Fusion app by key; handles loading states and errors.
 - **`Header`** — Top bar with the Fusion logo, context selector, bookmark toggle, and person settings.
 - **`ContextSelector`** — Wired to the current app's context module for searching and selecting context items.
-- **`useAppContextNavigation`** — Synchronizes URL pathname with context changes for apps that use the context module.
+- **`enableContextNavigation`** — Registers the portal-level context navigation plugin that reconciles the active context with the browser URL.
 
 ## Constraints
 

packages/dev-portal/package.json

@@ -34,6 +34,7 @@
     "@equinor/fusion-framework-module-app": "workspace:*",
     "@equinor/fusion-framework-module-bookmark": "workspace:*",
     "@equinor/fusion-framework-module-context": "workspace:*",
+    "@equinor/fusion-framework-plugin-context-navigation": "workspace:*",
     "@equinor/fusion-framework-module-feature-flag": "workspace:*",
     "@equinor/fusion-framework-module-navigation": "workspace:*",
     "@equinor/fusion-framework-module-services": "workspace:*",
@@ -53,12 +54,14 @@
     "@equinor/fusion-wc-person": "^3.5.5",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
+    "@types/semver": "^7.7.1",
     "@vitejs/plugin-react": "^6.0.1",
     "dotenv": "^17.3.1",
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
     "rxjs": "^7.8.1",
     "styled-components": "^6.3.11",
+    "semver": "^7.7.2",
     "tsx": "^4.19.3",
     "typescript": "^7.0.2",
     "vite": "^8.0.0"
@@ -72,6 +75,7 @@
     "@equinor/fusion-framework-module-app": "workspace:*",
     "@equinor/fusion-framework-module-bookmark": "workspace:*",
     "@equinor/fusion-framework-module-context": "workspace:*",
+    "@equinor/fusion-framework-plugin-context-navigation": "workspace:*",
     "@equinor/fusion-framework-module-feature-flag": "workspace:*",
     "@equinor/fusion-framework-module-navigation": "workspace:*",
     "@equinor/fusion-framework-module-services": "workspace:*",

packages/dev-portal/src/Router.tsx

@@ -1,11 +1,10 @@
 import { useBookmarkNavigate } from '@equinor/fusion-framework-react-module-bookmark/portal';
 
-import { Outlet, Router as FusionRouter, useParams } from '@equinor/fusion-framework-react-router';
+import { Router as FusionRouter, Outlet, useParams } from '@equinor/fusion-framework-react-router';
 import AppLoader from './AppLoader';
 import { Header } from './Header';
 
 import { styled } from 'styled-components';
-import { useAppContextNavigation } from './useAppContextNavigation';
 
 const Styled = {
   ContentContainer: styled.div`
@@ -76,11 +75,9 @@ const routes = [
 /**
  * Top-level router for the Fusion Dev Portal.
  *
- * Renders the application via `FusionRouter`. Observes context changes through
- * {@link useAppContextNavigation} to keep the URL in sync.
+ * Uses `@equinor/fusion-framework-react-router` which automatically connects
+ * to the framework's navigation module for history and basename.
  */
 export const Router = () => {
-  // observe the context changes and navigate when the context changes
-  useAppContextNavigation();
   return <FusionRouter routes={routes} />;
 };