@equinor/fusion-framework-plugin-context-navigation 0.1.0 → 0.1.1

package/dist/types/ContextNavigationConfigurator.d.ts

@@ -0,0 +1,125 @@
+import type { ContextNavigationConfig, ContextNavigationNavigatedDetail } from './types';
+import type { ContextNavigationAdapterInput } from './adapters/types';
+import type { ReconcilerSourceFactory } from './sources/types';
+/**
+ * Configurator for the context-navigation plugin.
+ *
+ * Provides a fluent builder API for portal developers.
+ * Adapters are registered with priority — the first adapter whose
+ * `canHandle()` returns `true` is used for navigation.
+ *
+ * @example
+ * ```ts
+ * enableContextNavigation(configurator, (builder) => {
+ *   builder.setPortalName('my-portal');
+ *   builder.setDebug(true);
+ *   // Custom adapters registered at higher priority override defaults
+ *   builder.registerAdapter(myHashAdapter);
+ * });
+ * ```
+ */
+export declare class ContextNavigationConfigurator {
+    #private;
+    /**
+     * Register a navigation adapter or adapter factory.
+     *
+     * - **Object** — a static adapter with `canHandle`, `encode`, `decode`.
+     * - **Function** — a factory called with the resolution context that
+     *   returns a bound adapter or `null` to skip.
+     *
+     * Adapters are evaluated in registration order. The first match wins.
+     *
+     * **Note:** Registering any adapter disables the built-in defaults
+     * (custom, query, path). Register all adapters you need explicitly.
+     *
+     * @param adapter - The adapter instance or factory function to register.
+     * @returns The configurator instance for chaining.
+     */
+    registerAdapter(adapter: ContextNavigationAdapterInput): this;
+    /**
+     * Set the portal name used in debug output.
+     * @default 'Portal'
+     *
+     * @param name - The portal name to use in debug output.
+     * @returns The configurator instance for chaining.
+     */
+    setPortalName(name: string): this;
+    /**
+     * Set the origin for constructing absolute URLs.
+     * @default window.location.origin
+     *
+     * @param origin - The origin string to use for URL construction.
+     * @returns The configurator instance for chaining.
+     */
+    setOrigin(origin: string): this;
+    /**
+     * Enable or disable the URL guard.
+     * @default true
+     *
+     * @param enabled - Whether to enable the URL guard.
+     * @returns The configurator instance for chaining.
+     */
+    setUrlGuard(enabled: boolean): this;
+    /**
+     * Enable or disable verbose debug logging.
+     * @default false
+     *
+     * @param enabled - Whether to enable debug logging.
+     * @returns The configurator instance for chaining.
+     */
+    setDebug(enabled: boolean): this;
+    /**
+     * Set a function that computes the URL to navigate to when context is cleared.
+     *
+     * When set, the reconciler bypasses adapter encoding for null context
+     * and navigates directly to the returned URL. Use in context-portal where
+     * clearing context should return to the portal landing page.
+     *
+     * Accepts either a static string (shorthand) or a function that receives
+     * the current app key and URL for dynamic path construction.
+     *
+     * @param urlOrFn - A static path (e.g. `'/'`) or a function returning one.
+     * @returns The configurator instance for chaining.
+     */
+    setNullContextUrl(urlOrFn: string | ((args: {
+        appKey: string;
+        currentURL: URL;
+    }) => string)): this;
+    /**
+     * Set a side-effect hook called after each successful navigation.
+     * @param fn - The callback function to invoke after navigation.
+     * @returns The configurator instance for chaining.
+     */
+    setOnTransition(fn: (detail: ContextNavigationNavigatedDetail) => void): this;
+    /**
+     * Set the options passed to `navigation.navigate()` during URL updates.
+     *
+     * @default { replace: true }
+     * @param options - The navigation options to use for URL updates.
+     * @returns The configurator instance for chaining.
+     * @see INavigationProvider.navigate
+     * @see ContextNavigationConfig.navigationOptions
+     */
+    setNavigationOptions(options: {
+        replace?: boolean;
+        state?: unknown;
+    }): this;
+    /**
+     * Set the source factory that drives the reconciler's observable stream.
+     *
+     * @default createAppFirstSource()
+     * @param factory - The source factory to use for the reconciler.
+     * @returns The configurator instance for chaining.
+     * @see ReconcilerSourceFactory
+     * @see appFirstSource
+     * @see contextFirstSource
+     */
+    setSourceFactory(factory: ReconcilerSourceFactory): this;
+    /**
+     * Builds the resolved plugin configuration from the registered options.
+     *
+     * @returns The resolved configuration used by the context-navigation plugin.
+     */
+    createConfig(): ContextNavigationConfig;
+}
+//# sourceMappingURL=ContextNavigationConfigurator.d.ts.map

package/dist/types/ContextNavigationConfigurator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextNavigationConfigurator.d.ts","sourceRoot":"","sources":["../../src/ContextNavigationConfigurator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,gCAAgC,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAoB/D;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,6BAA6B;;IAIxC;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,OAAO,EAAE,6BAA6B,GAAG,IAAI,CAG5D;IAED;;;;;;OAMG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAGhC;IAED;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAG9B;IAED;;;;;;OAMG;IACH,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAGlC;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAG/B;IAED;;;;;;;;;;;;OAYG;IACH,iBAAiB,CACf,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,GAAG,CAAA;KAAE,KAAK,MAAM,CAAC,GACxE,IAAI,CAGN;IAED;;;;OAIG;IACH,eAAe,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,gCAAgC,KAAK,IAAI,GAAG,IAAI,CAG5E;IAED;;;;;;;;OAQG;IACH,oBAAoB,CAAC,OAAO,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAG1E;IAED;;;;;;;;;OASG;IACH,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAGvD;IAED;;;;OAIG;IACH,YAAY,IAAI,uBAAuB,CAuBtC;CACF"}

package/dist/types/__tests__/active-app-navigation-events.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=active-app-navigation-events.test.d.ts.map

package/dist/types/__tests__/active-app-navigation-events.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-app-navigation-events.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/active-app-navigation-events.test.ts"],"names":[],"mappings":""}

package/dist/types/__tests__/apply-navigation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=apply-navigation.test.d.ts.map

package/dist/types/__tests__/apply-navigation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-navigation.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/apply-navigation.test.ts"],"names":[],"mappings":""}

package/dist/types/__tests__/enable.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=enable.test.d.ts.map

package/dist/types/__tests__/enable.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enable.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/enable.test.ts"],"names":[],"mappings":""}

package/dist/types/__tests__/guard-handlers.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=guard-handlers.test.d.ts.map

package/dist/types/__tests__/guard-handlers.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-handlers.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/guard-handlers.test.ts"],"names":[],"mappings":""}

package/dist/types/__tests__/plugin.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plugin.test.d.ts.map

package/dist/types/__tests__/plugin.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/plugin.test.ts"],"names":[],"mappings":""}

package/dist/types/__tests__/reconcile.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=reconcile.test.d.ts.map

package/dist/types/__tests__/reconcile.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/reconcile.test.ts"],"names":[],"mappings":""}

package/dist/types/adapters/create-path-adapter.d.ts

@@ -0,0 +1,27 @@
+import type { ContextNavigationAdapter } from './types';
+/**
+ * Path adapter — encodes context identity as the first path segment after
+ * the app basename.
+ *
+ * **Intent:** This is the legacy/default strategy for Fusion apps. It places
+ * the context UUID immediately after `/apps/{appKey}/` as a path segment,
+ * making context visible in the URL structure. This convention predates the
+ * query strategy and remains the fallback for apps that don't declare a
+ * routing strategy.
+ *
+ * **URL shape:** `/apps/{appKey}/{contextId}/...`
+ *
+ * **Selection logic:**
+ * 1. Immediately bails if the app has custom generators registered
+ *    (those apps are owned by the custom adapter).
+ * 2. Matches when `routingStrategy === 'path'` (explicit opt-in).
+ * 3. Matches when no strategy is declared (default fallback).
+ *
+ * **Context detection:** Uses `parseAppRoute` (URLPattern-based) to parse
+ * the path into named segments, and UUID pattern matching to distinguish
+ * context ids from route names.
+ *
+ * @returns A static adapter object
+ */
+export declare function createPathAdapter(): ContextNavigationAdapter;
+//# sourceMappingURL=create-path-adapter.d.ts.map

package/dist/types/adapters/create-path-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-path-adapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/create-path-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAA4B,MAAM,SAAS,CAAC;AAOlF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,IAAI,wBAAwB,CAoE5D"}

package/dist/types/adapters/create-query-adapter.d.ts

@@ -0,0 +1,34 @@
+import type { ContextNavigationAdapter } from './types';
+/**
+ * Query adapter — encodes context identity as a URL query parameter.
+ *
+ * **Intent:** This is the preferred strategy for new apps. It keeps the
+ * pathname clean for app routing while storing context in a predictable
+ * query param (`?$contextId={uuid}`). This avoids conflicts with
+ * React Router path segments and makes deep-links copy-pasteable without
+ * affecting route matching.
+ *
+ * **URL shape:** `/apps/{appKey}/route?$contextId={id}`
+ *
+ * **Selection:** Matches only when the app explicitly declares
+ * `routingStrategy: 'query'` on its context provider. Does not
+ * fall through as a default — that role belongs to the path adapter.
+ *
+ * **Query string handling:** Clones the full current URL (`currentURL.href`)
+ * so all existing query parameters are preserved. Only the context param
+ * is added/removed/replaced.
+ *
+ * @param paramName - Query parameter name to use (default `$contextId`)
+ * @returns A static adapter object (not a factory — no runtime binding needed)
+ *
+ * @example
+ * ```ts
+ * // Default param name
+ * const adapter = createQueryAdapter();
+ *
+ * // Custom param name for portal-specific needs
+ * const adapter = createQueryAdapter('contextId');
+ * ```
+ */
+export declare function createQueryAdapter(paramName?: string): ContextNavigationAdapter;
+//# sourceMappingURL=create-query-adapter.d.ts.map

package/dist/types/adapters/create-query-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-query-adapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/create-query-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAA4B,MAAM,SAAS,CAAC;AAGlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,SAA0B,GAAG,wBAAwB,CAuDhG"}

package/dist/types/adapters/custom-adapter/create-custom-adapter.d.ts

@@ -0,0 +1,29 @@
+import type { ContextNavigationAdapterFactory } from '../types';
+/**
+ * Custom adapter factory — delegates URL encoding/decoding to app-provided hooks.
+ *
+ * **Intent:** Some apps define their own URL shape for context (e.g.
+ * `/route-a/{contextId}` instead of the standard `/{contextId}/route-a`).
+ * These apps register `extractContextIdFromPath` and `generatePathFromContext`
+ * on their context provider. This adapter bridges those app hooks into the
+ * navigation handler's adapter contract so the reconciler can drive navigation
+ * without knowing the app's specific URL layout.
+ *
+ * **Selection:** The factory returns a bound adapter only when the app has
+ * both generator hooks registered (checked via {@link hasCustomContextGenerators}).
+ * Otherwise it returns `null`, letting lower-priority adapters (query, path) match.
+ *
+ * **Coordinate system:** All app hooks receive/return app-relative paths.
+ * The adapter handles stripping and prepending the `/apps/{appKey}` prefix
+ * transparently via {@link toAppRelative} and {@link toFullPath}.
+ *
+ * **Query string preservation:** The adapter always carries forward
+ * `currentURL.search` to the output URL, ensuring query parameters
+ * (e.g. `?routingStrategy=custom`) survive navigation.
+ *
+ * @returns A {@link ContextNavigationAdapterFactory} that produces a custom adapter when the
+ *          app context exposes both `extractContextIdFromPath` and `generatePathFromContext`,
+ *          or `null` to fall through to the next adapter in the resolution chain.
+ */
+export declare function createCustomAdapter(): ContextNavigationAdapterFactory;
+//# sourceMappingURL=create-custom-adapter.d.ts.map

package/dist/types/adapters/custom-adapter/create-custom-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-custom-adapter.d.ts","sourceRoot":"","sources":["../../../../src/adapters/custom-adapter/create-custom-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA4B,+BAA+B,EAAE,MAAM,UAAU,CAAC;AAO1F;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,IAAI,+BAA+B,CAoGrE"}

package/dist/types/adapters/custom-adapter/index.d.ts

@@ -0,0 +1,5 @@
+export { createCustomAdapter } from './create-custom-adapter';
+export { normalizeStringResult } from './normalize-string-result';
+export { toAppRelative } from './to-app-relative';
+export { toFullPath } from './to-full-path';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/adapters/custom-adapter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/adapters/custom-adapter/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/types/adapters/custom-adapter/normalize-string-result.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Normalize legacy app generator outputs to a plain string.
+ *
+ * Legacy apps may return their path values as either a bare string or
+ * wrapped in an array (e.g. `['path']` or `[]`). This function unifies
+ * both shapes into `string | undefined` so downstream code doesn't need
+ * to branch on format.
+ *
+ * @param value - Raw return value from an app generator hook
+ * @returns The resolved string, or `undefined` if the value is empty/invalid
+ *
+ * @example
+ * ```ts
+ * normalizeStringResult('/foo/bar');    // '/foo/bar'
+ * normalizeStringResult(['/foo/bar']); // '/foo/bar'
+ * normalizeStringResult([]);           // undefined
+ * normalizeStringResult('');           // undefined
+ * ```
+ */
+export declare function normalizeStringResult(value: unknown): string | undefined;
+//# sourceMappingURL=normalize-string-result.d.ts.map

package/dist/types/adapters/custom-adapter/normalize-string-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-string-result.d.ts","sourceRoot":"","sources":["../../../../src/adapters/custom-adapter/normalize-string-result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAkBxE"}

package/dist/types/adapters/custom-adapter/to-app-relative.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Strips the app basename prefix from a full pathname to produce an
+ * app-relative path.
+ *
+ * App-provided hooks (`extractContextIdFromPath`, `generatePathFromContext`)
+ * operate on app-relative paths — they don't know about the portal's
+ * `/apps/{appKey}` prefix. This function converts a browser-absolute
+ * pathname into the app's local coordinate system before calling those hooks.
+ *
+ * Always returns a path starting with `/` so app hooks receive consistent input.
+ *
+ * @param fullPathname - Absolute browser pathname (e.g. `/apps/my-app/route-a`)
+ * @param appBasename - The app's base path (e.g. `/apps/my-app`)
+ * @returns App-relative path (e.g. `/route-a`), or the input unchanged if
+ *          the basename doesn't match (defensive fallback)
+ *
+ * @example
+ * ```ts
+ * toAppRelative('/apps/my-app/route-a/ctx', '/apps/my-app'); // '/route-a/ctx'
+ * toAppRelative('/apps/my-app', '/apps/my-app');             // '/'
+ * toAppRelative('/other/path', '/apps/my-app');              // '/other/path'
+ * ```
+ */
+export declare function toAppRelative(fullPathname: string, appBasename: string): string;
+//# sourceMappingURL=to-app-relative.d.ts.map

package/dist/types/adapters/custom-adapter/to-app-relative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-app-relative.d.ts","sourceRoot":"","sources":["../../../../src/adapters/custom-adapter/to-app-relative.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAS/E"}

package/dist/types/adapters/custom-adapter/to-full-path.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Prepends the app basename to an app-relative path to produce a full
+ * browser-absolute pathname.
+ *
+ * Inverse of {@link toAppRelative}. After an app hook generates a new
+ * app-relative path (with context encoded), this function converts it
+ * back into a full pathname suitable for browser navigation.
+ *
+ * Handles edge cases where either side may or may not have a leading/trailing slash.
+ *
+ * @param appRelativePath - App-relative path (e.g. `/route-a/ctx-id`)
+ * @param appBasename - The app's base path (e.g. `/apps/my-app`)
+ * @returns Full browser pathname (e.g. `/apps/my-app/route-a/ctx-id`)
+ *
+ * @example
+ * ```ts
+ * toFullPath('/route-a/ctx-id', '/apps/my-app');  // '/apps/my-app/route-a/ctx-id'
+ * toFullPath('route-a/ctx-id', '/apps/my-app/');  // '/apps/my-app/route-a/ctx-id'
+ * ```
+ */
+export declare function toFullPath(appRelativePath: string, appBasename: string): string;
+//# sourceMappingURL=to-full-path.d.ts.map

package/dist/types/adapters/custom-adapter/to-full-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-full-path.d.ts","sourceRoot":"","sources":["../../../../src/adapters/custom-adapter/to-full-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,eAAe,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAM/E"}

package/dist/types/adapters/index.d.ts

@@ -0,0 +1,5 @@
+export { createPathAdapter } from './create-path-adapter';
+export { createQueryAdapter } from './create-query-adapter';
+export { createCustomAdapter } from './custom-adapter';
+export type { AdapterResolutionContext, ContextNavigationAdapter, ContextNavigationAdapterFactory, ContextNavigationAdapterInput, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD,YAAY,EACV,wBAAwB,EACxB,wBAAwB,EACxB,+BAA+B,EAC/B,6BAA6B,GAC9B,MAAM,SAAS,CAAC"}

package/dist/types/adapters/types.d.ts

@@ -0,0 +1,73 @@
+import type { ContextItem, IContextProvider } from '@equinor/fusion-framework-module-context';
+import type { FrameworkOptions } from '@equinor/fusion-framework-module-app';
+/**
+ * Context for adapter resolution — passed to `canHandle` so the adapter
+ * can self-select based on app config, URL shape, or other signals.
+ */
+export interface AdapterResolutionContext {
+    /** Current app key. */
+    appKey: string;
+    /** The app's context provider (has custom generators, etc.) */
+    appContext: IContextProvider;
+    /** Routing strategy declared in the app manifest's build options. */
+    routingStrategy?: FrameworkOptions['contextRouting'];
+    /** The current browser URL. */
+    currentURL: URL;
+}
+/**
+ * A context navigation adapter encodes/decodes context identity in the URL.
+ *
+ * Adapters are **self-selecting** — they declare via `canHandle` whether they
+ * apply to a given app/URL combination. The provider iterates registered
+ * adapters by priority and uses the first match.
+ *
+ * Implementations must be **pure** — no side effects, no navigation calls.
+ * The reconciler handles all navigation; adapters only compute URLs.
+ */
+export interface ContextNavigationAdapter {
+    /** Unique identifier for logging/events. */
+    readonly id: string;
+    /**
+     * Self-selecting predicate: should this adapter handle navigation for
+     * the given app and URL?
+     */
+    canHandle(ctx: AdapterResolutionContext): boolean;
+    /**
+     * Build a URL that encodes the given context.
+     *
+     * @param args.context - The context to encode, or `null` to clear context from URL.
+     * @param args.currentURL - The current browser URL (absolute).
+     * @returns The target URL with context encoded, or `null` to skip navigation.
+     */
+    encode(args: {
+        context: ContextItem | null;
+        currentURL: URL;
+    }): URL | null;
+    /**
+     * Extract the context id from a URL.
+     *
+     * @param url - The URL to decode.
+     * @returns The context id if present, or `null` if not found.
+     */
+    decode(url: URL): string | null;
+}
+/**
+ * An adapter factory receives the resolution context and returns a
+ * fully-bound adapter, or `null` to indicate it cannot handle
+ * the current app/URL combination.
+ *
+ * Use a factory when the adapter needs runtime state from the app
+ * (e.g. custom path generators) that isn't available at registration time.
+ */
+export type ContextNavigationAdapterFactory = (ctx: AdapterResolutionContext) => ContextNavigationAdapter | null;
+/**
+ * An adapter registration — either a static adapter object or a factory
+ * function that produces one.
+ *
+ * - **Object** — must implement `canHandle`, `encode`, `decode`.
+ *   The reconciler calls `canHandle` to determine if it applies.
+ * - **Function** — called with the resolution context, returns a bound
+ *   adapter or `null` to skip. Implies the factory handles its own selection.
+ */
+export type ContextNavigationAdapterInput = ContextNavigationAdapter | ContextNavigationAdapterFactory;
+//# sourceMappingURL=types.d.ts.map

package/dist/types/adapters/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/adapters/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAC9F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAI7E;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,UAAU,EAAE,gBAAgB,CAAC;IAC7B,qEAAqE;IACrE,eAAe,CAAC,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,CAAC;IACrD,+BAA+B;IAC/B,UAAU,EAAE,GAAG,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB;IACvC,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,wBAAwB,GAAG,OAAO,CAAC;IAElD;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,GAAG,CAAA;KAAE,GAAG,GAAG,GAAG,IAAI,CAAC;IAE3E;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,+BAA+B,GAAG,CAC5C,GAAG,EAAE,wBAAwB,KAC1B,wBAAwB,GAAG,IAAI,CAAC;AAErC;;;;;;;;GAQG;AACH,MAAM,MAAM,6BAA6B,GACrC,wBAAwB,GACxB,+BAA+B,CAAC"}

package/dist/types/apply-navigation.d.ts

@@ -0,0 +1,88 @@
+import type { AppModulesInstance } from '@equinor/fusion-framework-module-app';
+import type { ContextItem, ContextModule } from '@equinor/fusion-framework-module-context';
+import type { IEventModuleProvider } from '@equinor/fusion-framework-module-event';
+import type { INavigationProvider } from '@equinor/fusion-framework-module-navigation';
+import type { ContextNavigationAdapter } from './adapters/types';
+import type { ContextNavigationConfig } from './types';
+import type { ContextNavigationEventSource } from './create-context-navigation-plugin';
+/**
+ * Set of normalized paths that the plugin itself has navigated to.
+ *
+ * The guard checks incoming navigations against this set and consumes
+ * (deletes) the matching token so a future back/forward to the same
+ * URL is not silently skipped. Using a Set handles concurrent writes
+ * without one overwriting another.
+ */
+export type OwnNavigationTokens = Set<string>;
+/**
+ * Dependencies injected into {@link applyNavigation}.
+ *
+ * These are shared across the plugin's reconciler and guard handlers so that
+ * navigation, event dispatch, and token tracking behave consistently regardless
+ * of which call-site triggers a navigation.
+ */
+export interface ApplyNavigationDeps {
+    /** Event bus for dispatching cancelable lifecycle events to external listeners. */
+    event: IEventModuleProvider;
+    /** Navigation provider used to perform the actual URL transition. */
+    navigation: INavigationProvider;
+    /** Resolved plugin configuration (navigation options, adapters, callbacks). */
+    config: ContextNavigationConfig;
+    /** Event source token attached to every dispatched event for traceability. */
+    eventSource: ContextNavigationEventSource;
+    /**
+     * Set of own-navigation tokens.
+     * Written here after a successful navigation so the URL guard can
+     * distinguish plugin-initiated navigations from user-initiated ones.
+     */
+    ownNavTokens: OwnNavigationTokens;
+    /** Conditional debug logger scoped to this plugin instance. */
+    log: (msg: string) => void;
+}
+/**
+ * Payload describing the navigation that {@link applyNavigation} should attempt.
+ *
+ * Carries all the resolved information needed to encode a new URL and navigate:
+ * the target app, its modules, the selected adapter, the active context, and
+ * the URL to compare against.
+ */
+export interface ApplyNavigationPayload {
+    /** The app key identifying which application this navigation targets. */
+    appKey: string;
+    /** The app's resolved module instances (needed for event detail payloads). */
+    appModules: AppModulesInstance<[ContextModule]>;
+    /** The adapter that will encode and decode context into/from the URL. */
+    adapter: ContextNavigationAdapter;
+    /** The context to encode into the URL, or `null` if context was cleared. */
+    context: ContextItem | null;
+    /** The current browser URL used as the baseline for comparison. */
+    currentURL: URL;
+}
+/**
+ * Apply a context-driven navigation if the adapter produces a different URL.
+ *
+ * This is the single codepath through which all plugin-initiated navigations flow.
+ * It performs four steps in sequence:
+ *
+ * 1. **Encode** — asks the adapter to produce a target URL from the active context.
+ * 2. **Compare** — skips if the target matches the current URL (no-op guard).
+ * 3. **Dispatch** — fires a cancelable `onContextNavigationNavigate` event so
+ *    external listeners can veto or observe the transition.
+ * 4. **Navigate** — performs the actual URL transition and records an own-nav token
+ *    so the URL guard knows to ignore the resulting navigation state change.
+ *
+ * @param payload - The navigation target details (app, adapter, context, URL).
+ * @param deps - Shared plugin dependencies (event bus, navigation provider, config).
+ * @param navOptionsOverride - Optional navigation options that override
+ *   `config.navigationOptions` for this specific call. Used by app-switch
+ *   reconciliation and URL-drift correction, which must always replace the
+ *   current history entry regardless of the user's `replace` setting.
+ * @returns A promise that resolves after the transition is handled in this
+ *   function (applied or skipped). It does not wait for browser-level
+ *   navigation completion.
+ */
+export declare function applyNavigation(payload: ApplyNavigationPayload, deps: ApplyNavigationDeps, navOptionsOverride?: {
+    replace?: boolean;
+    state?: unknown;
+}): Promise<void>;
+//# sourceMappingURL=apply-navigation.d.ts.map

package/dist/types/apply-navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-navigation.d.ts","sourceRoot":"","sources":["../../src/apply-navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0CAA0C,CAAC;AAC3F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AACnF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6CAA6C,CAAC;AAEvF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,KAAK,EACV,uBAAuB,EAIxB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,oCAAoC,CAAC;AAGvF;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,mFAAmF;IACnF,KAAK,EAAE,oBAAoB,CAAC;IAC5B,qEAAqE;IACrE,UAAU,EAAE,mBAAmB,CAAC;IAChC,+EAA+E;IAC/E,MAAM,EAAE,uBAAuB,CAAC;IAChC,8EAA8E;IAC9E,WAAW,EAAE,4BAA4B,CAAC;IAC1C;;;;OAIG;IACH,YAAY,EAAE,mBAAmB,CAAC;IAClC,+DAA+D;IAC/D,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,UAAU,EAAE,kBAAkB,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;IAChD,yEAAyE;IACzE,OAAO,EAAE,wBAAwB,CAAC;IAClC,4EAA4E;IAC5E,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,mEAAmE;IACnE,UAAU,EAAE,GAAG,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,IAAI,EAAE,mBAAmB,EACzB,kBAAkB,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1D,OAAO,CAAC,IAAI,CAAC,CAuFf"}

package/dist/types/constants/context-query-param-key.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Query-parameter key used to carry the context id in query-routing mode.
+ *
+ * The `$` prefix is a Fusion convention that namespaces framework-managed
+ * parameters, distinguishing them from app-specific query params.
+ */
+export declare const CONTEXT_QUERY_PARAM_KEY = "$contextId";
+//# sourceMappingURL=context-query-param-key.d.ts.map

package/dist/types/constants/context-query-param-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-query-param-key.d.ts","sourceRoot":"","sources":["../../../src/constants/context-query-param-key.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,eAAe,CAAC"}

package/dist/types/constants/index.d.ts

@@ -0,0 +1,3 @@
+export { CONTEXT_QUERY_PARAM_KEY } from './context-query-param-key';
+export { UUID_PATTERN } from './uuid-pattern';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/constants/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/constants/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/types/constants/uuid-pattern.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Regex matching a standard UUID (v4 format, case-insensitive).
+ *
+ * Used to identify whether a path segment is a context id vs. a route name.
+ * Context ids in Fusion are always UUIDs, so this is a reliable discriminator.
+ */
+export declare const UUID_PATTERN: RegExp;
+//# sourceMappingURL=uuid-pattern.d.ts.map

package/dist/types/constants/uuid-pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid-pattern.d.ts","sourceRoot":"","sources":["../../../src/constants/uuid-pattern.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,YAAY,QAAoE,CAAC"}