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

package/dist/esm/__tests__/reconcile.test.js

@@ -0,0 +1,164 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { reconcile } from '../reconcile';
+function makeContext(id) {
+    // Test double — only id and title are read by the code under test
+    return { id, title: `Context ${id}` };
+}
+function makeAdapter(overrides = {}) {
+    return {
+        id: 'test-adapter',
+        canHandle: () => true,
+        encode: ({ context, currentURL }) => {
+            // Guard — adapter cannot encode without a context item
+            if (!context)
+                return null;
+            return new URL(`/apps/my-app/${context.id}`, currentURL.origin);
+        },
+        decode: () => null,
+        ...overrides,
+    };
+}
+function makeDeps(overrides = {}) {
+    // Test doubles — only the methods exercised by reconcile are provided
+    return {
+        event: {
+            dispatchEvent: vi.fn(async () => ({ canceled: false })),
+        },
+        navigation: {
+            path: { pathname: '/apps/my-app', search: '' },
+            navigate: vi.fn(),
+        },
+        config: {
+            portalName: 'Test',
+            origin: 'https://example.com',
+            adapters: [makeAdapter()],
+            enableUrlGuard: false,
+            debug: false,
+            sourceFactory: () => ({ subscribe: vi.fn() }),
+            navigationOptions: { replace: true },
+        },
+        eventSource: { name: 'contextNavigation', version: '0.0.0' },
+        ownNavTokens: new Set(),
+        log: vi.fn(),
+        ...overrides,
+    };
+}
+describe('reconcile', () => {
+    // Test double — only the context property is accessed by the code under test
+    const appModules = {
+        context: { currentContext: null },
+    };
+    let deps;
+    beforeEach(() => {
+        deps = makeDeps();
+    });
+    it('dispatches no-context skip when contextState is undefined', () => {
+        const entry = { appKey: 'my-app', appModules, contextState: undefined };
+        reconcile(entry, deps);
+        expect(deps.event.dispatchEvent).toHaveBeenCalledWith('onContextNavigationSkipped', expect.objectContaining({ detail: { appKey: 'my-app', reason: 'no-context' } }));
+    });
+    it('navigates to nullContextUrl when contextState is null and config provides it', () => {
+        const nullContextUrl = vi.fn(() => '/apps/my-app');
+        deps = makeDeps();
+        deps.config = { ...deps.config, nullContextUrl };
+        Object.assign(deps.navigation, {
+            path: { pathname: '/apps/my-app/old-ctx', search: '' },
+        });
+        const entry = { appKey: 'my-app', appModules, contextState: null };
+        reconcile(entry, deps);
+        expect(nullContextUrl).toHaveBeenCalledWith(expect.objectContaining({ appKey: 'my-app' }));
+        expect(deps.navigation.navigate).toHaveBeenCalledWith(expect.objectContaining({ pathname: '/apps/my-app' }), expect.anything());
+        expect(deps.ownNavTokens.has('/apps/my-app')).toBe(true);
+    });
+    it('does not navigate when nullContextUrl produces the same path', () => {
+        const nullContextUrl = vi.fn(() => '/apps/my-app');
+        deps = makeDeps();
+        deps.config = { ...deps.config, nullContextUrl };
+        const entry = { appKey: 'my-app', appModules, contextState: null };
+        reconcile(entry, deps);
+        expect(deps.navigation.navigate).not.toHaveBeenCalled();
+    });
+    it('dispatches no-adapter skip when no adapter matches', () => {
+        const noMatchAdapter = makeAdapter({ canHandle: () => false });
+        deps = makeDeps();
+        deps.config = { ...deps.config, adapters: [noMatchAdapter] };
+        const entry = {
+            appKey: 'my-app',
+            appModules,
+            contextState: makeContext('ctx-1'),
+        };
+        reconcile(entry, deps);
+        expect(deps.event.dispatchEvent).toHaveBeenCalledWith('onContextNavigationSkipped', expect.objectContaining({ detail: { appKey: 'my-app', reason: 'no-adapter' } }));
+    });
+    it('dispatches adapter-resolved event and triggers navigation', async () => {
+        const entry = {
+            appKey: 'my-app',
+            appModules,
+            contextState: makeContext('ctx-1'),
+        };
+        reconcile(entry, deps);
+        await vi.waitFor(() => {
+            expect(deps.event.dispatchEvent).toHaveBeenCalledWith('onContextNavigationAdapterResolved', expect.objectContaining({ detail: { appKey: 'my-app', adapterId: 'test-adapter' } }));
+            expect(deps.navigation.navigate).toHaveBeenCalledWith(expect.objectContaining({ pathname: '/apps/my-app/ctx-1' }), { replace: true });
+        });
+    });
+    it('strips all query params on app switch', async () => {
+        // Adapter that carries currentURL.search through to its output
+        const adapter = makeAdapter({
+            encode: ({ context, currentURL }) => {
+                // Guard — adapter cannot encode without a context item
+                if (!context)
+                    return null;
+                const url = new URL(`/apps/new-app/${context.id}`, currentURL.origin);
+                url.search = currentURL.search;
+                return url;
+            },
+        });
+        deps = makeDeps();
+        deps.config = { ...deps.config, adapters: [adapter] };
+        Object.assign(deps.navigation, {
+            path: { pathname: '/apps/old-app/ctx-1', search: '?tab=settings&$contextId=ctx-1' },
+        });
+        const entry = {
+            appKey: 'new-app',
+            appModules,
+            contextState: makeContext('ctx-2'),
+        };
+        reconcile(entry, deps, { isAppSwitch: true });
+        await vi.waitFor(() => {
+            const navigatedURL = vi.mocked(deps.navigation.navigate).mock.calls[0]?.[0];
+            // All query params from the previous app should be gone
+            expect(navigatedURL.search).toBe('');
+        });
+    });
+    it('preserves query params on context change within the same app', async () => {
+        const adapter = makeAdapter({
+            encode: ({ context, currentURL }) => {
+                // Guard — adapter cannot encode without a context item
+                if (!context)
+                    return null;
+                const url = new URL(`/apps/my-app/${context.id}`, currentURL.origin);
+                url.search = currentURL.search;
+                return url;
+            },
+        });
+        deps = makeDeps();
+        deps.config = { ...deps.config, adapters: [adapter] };
+        Object.assign(deps.navigation, {
+            path: { pathname: '/apps/my-app/ctx-1', search: '?tab=settings' },
+        });
+        const entry = {
+            appKey: 'my-app',
+            appModules,
+            contextState: makeContext('ctx-2'),
+        };
+        // Context change within the same app — query params should survive
+        reconcile(entry, deps);
+        await vi.waitFor(() => {
+            const navigatedURL = vi.mocked(deps.navigation.navigate).mock.calls[0]?.[0];
+            // App-specific param should survive on context change
+            expect(navigatedURL.searchParams.get('tab')).toBe('settings');
+        });
+    });
+});
+//# sourceMappingURL=reconcile.test.js.map

package/dist/esm/__tests__/reconcile.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.test.js","sourceRoot":"","sources":["../../../src/__tests__/reconcile.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAK9D,OAAO,EAAE,SAAS,EAAsB,MAAM,cAAc,CAAC;AAK7D,SAAS,WAAW,CAAC,EAAU;IAC7B,kEAAkE;IAClE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAA4B,CAAC;AAClE,CAAC;AAED,SAAS,WAAW,CAAC,SAAS,GAAsC,EAAE;IACpE,OAAO;QACL,EAAE,EAAE,cAAc;QAClB,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI;QACrB,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE;YAClC,uDAAuD;YACvD,IAAI,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAC;YAC1B,OAAO,IAAI,GAAG,CAAC,gBAAgB,OAAO,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;QAClE,CAAC;QACD,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI;QAClB,GAAG,SAAS;KACb,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,SAAS,GAA2B,EAAE;IACtD,sEAAsE;IACtE,OAAO;QACL,KAAK,EAAE;YACL,aAAa,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;SACnB;QACtC,UAAU,EAAE;YACV,IAAI,EAAE,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,EAAE,EAAE;YAC9C,QAAQ,EAAE,EAAE,CAAC,EAAE,EAAE;SACwB;QAC3C,MAAM,EAAE;YACN,UAAU,EAAE,MAAM;YAClB,MAAM,EAAE,qBAAqB;YAC7B,QAAQ,EAAE,CAAC,WAAW,EAAE,CAAC;YACzB,cAAc,EAAE,KAAK;YACrB,KAAK,EAAE,KAAK;YACZ,aAAa,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAU;YACtD,iBAAiB,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE;SACrC;QACD,WAAW,EAAE,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,OAAO,EAAE;QAC5D,YAAY,EAAE,IAAI,GAAG,EAAyB;QAC9C,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE;QACZ,GAAG,SAAS;KACb,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;IACzB,6EAA6E;IAC7E,MAAM,UAAU,GAAG;QACjB,OAAO,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE;KACgB,CAAC;IACpD,IAAI,IAAmB,CAAC;IAExB,UAAU,CAAC,GAAG,EAAE;QACd,IAAI,GAAG,QAAQ,EAAE,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,KAAK,GAA0B,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;QAE/F,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAEvB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,oBAAoB,CACnD,4BAA4B,EAC5B,MAAM,CAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,CAAC,CAChF,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8EAA8E,EAAE,GAAG,EAAE;QACtF,MAAM,cAAc,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,CAAC;QACnD,IAAI,GAAG,QAAQ,EAAE,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;QACjD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE;YAC7B,IAAI,EAAE,EAAE,QAAQ,EAAE,sBAAsB,EAAE,MAAM,EAAE,EAAE,EAAE;SACvD,CAAC,CAAC;QAEH,MAAM,KAAK,GAA0B,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QAE1F,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAEvB,MAAM,CAAC,cAAc,CAAC,CAAC,oBAAoB,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;QAC3F,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,oBAAoB,CACnD,MAAM,CAAC,gBAAgB,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,EACrD,MAAM,CAAC,QAAQ,EAAE,CAClB,CAAC;QACF,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8DAA8D,EAAE,GAAG,EAAE;QACtE,MAAM,cAAc,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,CAAC;QACnD,IAAI,GAAG,QAAQ,EAAE,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;QAEjD,MAAM,KAAK,GAA0B,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QAE1F,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAEvB,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;IAC1D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,cAAc,GAAG,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC;QAC/D,IAAI,GAAG,QAAQ,EAAE,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,cAAc,CAAC,EAAE,CAAC;QAE7D,MAAM,KAAK,GAA0B;YACnC,MAAM,EAAE,QAAQ;YAChB,UAAU;YACV,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC;SACnC,CAAC;QAEF,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAEvB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,oBAAoB,CACnD,4BAA4B,EAC5B,MAAM,CAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,CAAC,CAChF,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2DAA2D,EAAE,KAAK,IAAI,EAAE;QACzE,MAAM,KAAK,GAA0B;YACnC,MAAM,EAAE,QAAQ;YAChB,UAAU;YACV,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC;SACnC,CAAC;QAEF,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAEvB,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YACpB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,oBAAoB,CACnD,oCAAoC,EACpC,MAAM,CAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,cAAc,EAAE,EAAE,CAAC,CACrF,CAAC;YACF,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,oBAAoB,CACnD,MAAM,CAAC,gBAAgB,CAAC,EAAE,QAAQ,EAAE,oBAAoB,EAAE,CAAC,EAC3D,EAAE,OAAO,EAAE,IAAI,EAAE,CAClB,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uCAAuC,EAAE,KAAK,IAAI,EAAE;QACrD,+DAA+D;QAC/D,MAAM,OAAO,GAAG,WAAW,CAAC;YAC1B,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE;gBAClC,uDAAuD;gBACvD,IAAI,CAAC,OAAO;oBAAE,OAAO,IAAI,CAAC;gBAC1B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,iBAAiB,OAAO,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;gBACtE,GAAG,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;gBAC/B,OAAO,GAAG,CAAC;YACb,CAAC;SACF,CAAC,CAAC;QACH,IAAI,GAAG,QAAQ,EAAE,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;QACtD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE;YAC7B,IAAI,EAAE,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,EAAE,gCAAgC,EAAE;SACpF,CAAC,CAAC;QAEH,MAAM,KAAK,GAA0B;YACnC,MAAM,EAAE,SAAS;YACjB,UAAU;YACV,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC;SACnC,CAAC;QAEF,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QAE9C,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YACpB,MAAM,YAAY,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAQ,CAAC;YACnF,wDAAwD;YACxD,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8DAA8D,EAAE,KAAK,IAAI,EAAE;QAC5E,MAAM,OAAO,GAAG,WAAW,CAAC;YAC1B,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE;gBAClC,uDAAuD;gBACvD,IAAI,CAAC,OAAO;oBAAE,OAAO,IAAI,CAAC;gBAC1B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,gBAAgB,OAAO,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;gBACrE,GAAG,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;gBAC/B,OAAO,GAAG,CAAC;YACb,CAAC;SACF,CAAC,CAAC;QACH,IAAI,GAAG,QAAQ,EAAE,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;QACtD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE;YAC7B,IAAI,EAAE,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,EAAE,eAAe,EAAE;SAClE,CAAC,CAAC;QAEH,MAAM,KAAK,GAA0B;YACnC,MAAM,EAAE,QAAQ;YAChB,UAAU;YACV,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC;SACnC,CAAC;QAEF,mEAAmE;QACnE,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAEvB,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YACpB,MAAM,YAAY,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAQ,CAAC;YACnF,sDAAsD;YACtD,MAAM,CAAC,YAAY,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/esm/adapters/create-path-adapter.js

@@ -0,0 +1,96 @@
+import { hasCustomContextGenerators } from '../utils/has-custom-context-generators';
+import { stripContextQueryParam } from '../utils/url/strip-context-query-param';
+import { parseAppRoute } from '../utils/url/parse-app-route';
+import { UUID_PATTERN } from '../constants';
+import { buildAppRoute } from '../utils/url/build-app-route';
+/**
+ * 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 function createPathAdapter() {
+    return {
+        id: 'path',
+        /**
+         * Self-selection predicate.
+         *
+         * Rejects apps with custom generators (they belong to the custom adapter).
+         * Accepts apps with explicit `'path'` strategy or no declared strategy
+         * (the path adapter serves as the system-wide default fallback).
+         */
+        canHandle({ appContext, routingStrategy, currentURL }) {
+            // Custom generators mean the app owns its URL shape — the custom adapter handles it, not us
+            if (hasCustomContextGenerators(appContext)) {
+                return false;
+            }
+            // Not an app route (e.g. portal chrome) — nothing for this adapter to encode context into
+            if (!parseAppRoute(currentURL.pathname)) {
+                return false;
+            }
+            const declared = routingStrategy;
+            // App explicitly opted into path-segment routing — take ownership
+            if (declared === 'path') {
+                return true;
+            }
+            // No strategy declared — path adapter is the system-wide default for legacy apps
+            if (declared === undefined || declared === null) {
+                return true;
+            }
+            return false;
+        },
+        /**
+         * Encode context into the URL as a path segment.
+         *
+         * - **Null context:** removes the context segment to produce a bare app route.
+         * - **Active context:** places/replaces the context id as the segment after the app key.
+         *
+         * Sub-routes after the context segment are intentionally dropped — a context
+         * change resets the app to its root view to avoid landing in an invalid state.
+         */
+        encode({ context, currentURL }) {
+            const match = parseAppRoute(currentURL.pathname);
+            // Pathname doesn't match the /apps/{key}/... shape — not a Fusion app route, bail out
+            if (!match)
+                return null;
+            const targetPath = context === null ? buildAppRoute(match.appKey) : buildAppRoute(match.appKey, context.id);
+            const url = new URL(targetPath, currentURL.origin);
+            url.search = currentURL.search;
+            stripContextQueryParam(url);
+            // Hash is intentionally not preserved — context changes reset app to root view
+            return url;
+        },
+        /**
+         * Extract context id from the path segment after the app key, if it matches a UUID.
+         *
+         * Returns `null` for non-UUID segments (route names, missing segments).
+         */
+        decode(url) {
+            const match = parseAppRoute(url.pathname);
+            // Only treat the segment as a context id if it's a valid UUID — route names can occupy the same slot
+            if (match?.contextId && UUID_PATTERN.test(match.contextId)) {
+                return match.contextId;
+            }
+            return null;
+        },
+    };
+}
+//# sourceMappingURL=create-path-adapter.js.map

package/dist/esm/adapters/create-path-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-path-adapter.js","sourceRoot":"","sources":["../../../src/adapters/create-path-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,0BAA0B,EAAE,MAAM,wCAAwC,CAAC;AACpF,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,EAAE,EAAE,MAAM;QAEV;;;;;;WAMG;QACH,SAAS,CAAC,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAA4B;YAC7E,4FAA4F;YAC5F,IAAI,0BAA0B,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC3C,OAAO,KAAK,CAAC;YACf,CAAC;YAED,0FAA0F;YAC1F,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACxC,OAAO,KAAK,CAAC;YACf,CAAC;YAED,MAAM,QAAQ,GAAG,eAAe,CAAC;YACjC,kEAAkE;YAClE,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;gBACxB,OAAO,IAAI,CAAC;YACd,CAAC;YACD,iFAAiF;YACjF,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;gBAChD,OAAO,IAAI,CAAC;YACd,CAAC;YAED,OAAO,KAAK,CAAC;QACf,CAAC;QAED;;;;;;;;WAQG;QACH,MAAM,CAAC,EAAE,OAAO,EAAE,UAAU,EAAoD;YAC9E,MAAM,KAAK,GAAG,aAAa,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YACjD,sFAAsF;YACtF,IAAI,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAC;YAExB,MAAM,UAAU,GACd,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;YAE3F,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;YACnD,GAAG,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;YAC/B,sBAAsB,CAAC,GAAG,CAAC,CAAC;YAC5B,+EAA+E;YAC/E,OAAO,GAAG,CAAC;QACb,CAAC;QAED;;;;WAIG;QACH,MAAM,CAAC,GAAQ;YACb,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC1C,qGAAqG;YACrG,IAAI,KAAK,EAAE,SAAS,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC3D,OAAO,KAAK,CAAC,SAAS,CAAC;YACzB,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/adapters/create-query-adapter.js

@@ -0,0 +1,83 @@
+import { CONTEXT_QUERY_PARAM_KEY } from '../constants';
+/**
+ * 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 function createQueryAdapter(paramName = CONTEXT_QUERY_PARAM_KEY) {
+    return {
+        id: 'query',
+        /**
+         * Matches apps that explicitly opted into query-parameter context routing.
+         *
+         * Only returns `true` when `routingStrategy === 'query'` — there is no
+         * implicit fallback. Apps without a declared strategy use the path adapter.
+         */
+        canHandle({ routingStrategy }) {
+            return routingStrategy === 'query';
+        },
+        /**
+         * Encode context into the URL's query string.
+         *
+         * - **Null context:** removes the context param (clears deep-link).
+         * - **Active context:** sets the param to the context id.
+         *
+         * After mutation, the `$` character is restored from `%24` encoding
+         * because `URLSearchParams` percent-encodes `$` but we want it
+         * human-readable in the address bar as a namespace marker.
+         *
+         * Hash fragment is intentionally cleared — context changes reset the app
+         * to its root view, so any hash pointing to sub-route sections would be invalid.
+         */
+        encode({ context, currentURL }) {
+            const url = new URL(currentURL.href);
+            // Null context means the user deselected context — remove the param to produce a clean URL
+            if (context === null) {
+                url.searchParams.delete(paramName);
+            }
+            else {
+                url.searchParams.set(paramName, context.id);
+            }
+            // Restore $ from %24 — $ is a reserved namespace prefix we want visible in URLs
+            url.search = url.search.replace(/%24/gi, '$');
+            // Clear hash — context change resets app to root view
+            url.hash = '';
+            return url;
+        },
+        /**
+         * Extract the context id from the query parameter.
+         *
+         * @returns The context id string, or `null` if the param is absent.
+         */
+        decode(url) {
+            return url.searchParams.get(paramName) ?? null;
+        },
+    };
+}
+//# sourceMappingURL=create-query-adapter.js.map

package/dist/esm/adapters/create-query-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-query-adapter.js","sourceRoot":"","sources":["../../../src/adapters/create-query-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAS,GAAG,uBAAuB;IACpE,OAAO;QACL,EAAE,EAAE,OAAO;QAEX;;;;;WAKG;QACH,SAAS,CAAC,EAAE,eAAe,EAA4B;YACrD,OAAO,eAAe,KAAK,OAAO,CAAC;QACrC,CAAC;QAED;;;;;;;;;;;;WAYG;QACH,MAAM,CAAC,EAAE,OAAO,EAAE,UAAU,EAAoD;YAC9E,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YAErC,2FAA2F;YAC3F,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YACrC,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;YAC9C,CAAC;YAED,gFAAgF;YAChF,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAE9C,sDAAsD;YACtD,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC;YAEd,OAAO,GAAG,CAAC;QACb,CAAC;QAED;;;;WAIG;QACH,MAAM,CAAC,GAAQ;YACb,OAAO,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC;QACjD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/adapters/custom-adapter/create-custom-adapter.js

@@ -0,0 +1,116 @@
+import { hasCustomContextGenerators } from '../../utils/has-custom-context-generators';
+import { stripContextQueryParam } from '../../utils/url/strip-context-query-param';
+import { normalizeStringResult } from './normalize-string-result';
+import { toAppRelative } from './to-app-relative';
+import { toFullPath } from './to-full-path';
+/**
+ * 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 function createCustomAdapter() {
+    return ({ appContext, appKey }) => {
+        // This app hasn't registered custom context hooks — let a lower-priority adapter handle it
+        if (!hasCustomContextGenerators(appContext)) {
+            return null;
+        }
+        const appBasename = `/apps/${appKey}`;
+        const rawExtract = appContext.extractContextIdFromPath;
+        const rawGenerate = appContext.generatePathFromContext;
+        // Both hooks must be present; if one is missing the custom URL contract can't be fulfilled
+        if (!rawExtract || !rawGenerate) {
+            return null;
+        }
+        // Capture narrowed references — TypeScript can't narrow across the closure boundary
+        const extract = rawExtract;
+        const generate = rawGenerate;
+        return {
+            id: 'custom',
+            /** Always true — selection already happened in the factory guard above. */
+            canHandle() {
+                return true;
+            },
+            /**
+             * Encode a context into the URL using the app's path generator.
+             *
+             * - **Null context:** navigates to the app root (clears context from URL).
+             * - **Existing context in URL:** replaces it with the new context id,
+             *   preferring the app generator's output, falling back to string replacement.
+             * - **No existing context:** delegates entirely to the app generator.
+             *
+             * Returns `null` when the generator cannot produce a path (signals the
+             * reconciler to skip navigation).
+             */
+            encode({ context, currentURL, }) {
+                // Null context means the user deselected context — navigate to the app root
+                if (context === null) {
+                    const url = new URL(appBasename, currentURL.origin);
+                    url.search = currentURL.search;
+                    // Remove query-adapter param — custom apps encode context in the path
+                    stripContextQueryParam(url);
+                    // Hash is intentionally not preserved — returning to root app view
+                    return url;
+                }
+                const appRelativePath = toAppRelative(currentURL.pathname, appBasename);
+                const existingContextId = normalizeStringResult(extract(appRelativePath)) ?? undefined;
+                let generatedPath;
+                // Context already lives in the URL — prefer the generator's output, but substitute the
+                // id directly as a last resort to avoid a no-op navigation
+                if (existingContextId) {
+                    // Context already embedded in the URL — let the generator rewrite it, or fall back to
+                    // a simple string replacement of the old id with the new one
+                    generatedPath =
+                        normalizeStringResult(generate(context, appRelativePath)) ??
+                            appRelativePath.replace(existingContextId, context.id);
+                }
+                else {
+                    // No context in the current URL — ask the generator where to place the new context id
+                    generatedPath = normalizeStringResult(generate(context, appRelativePath));
+                }
+                // Generator returned nothing — can't produce a valid URL; skip navigation
+                if (!generatedPath) {
+                    return null;
+                }
+                const fullPath = toFullPath(generatedPath, appBasename);
+                const url = new URL(fullPath, currentURL.origin);
+                url.search = currentURL.search;
+                // Remove query-adapter param — custom apps encode context in the path
+                stripContextQueryParam(url);
+                // Hash is intentionally not preserved — context changes reset app to root view
+                return url;
+            },
+            /**
+             * Decode a context id from the URL using the app's path extractor.
+             *
+             * Converts the browser URL to an app-relative path, then delegates
+             * to the app's extract hook. Returns `null` when no context is present.
+             */
+            decode(url) {
+                const appRelativePath = toAppRelative(url.pathname, appBasename);
+                return normalizeStringResult(extract(appRelativePath)) ?? null;
+            },
+        };
+    };
+}
+//# sourceMappingURL=create-custom-adapter.js.map

package/dist/esm/adapters/custom-adapter/create-custom-adapter.js.map

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

package/dist/esm/adapters/custom-adapter/index.js

@@ -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.js.map

package/dist/esm/adapters/custom-adapter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","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/esm/adapters/custom-adapter/normalize-string-result.js

@@ -0,0 +1,37 @@
+/**
+ * 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 function normalizeStringResult(value) {
+    // A non-empty string can be returned directly — the most common case for modern apps
+    if (typeof value === 'string' && value.length > 0) {
+        return value;
+    }
+    // Legacy apps may wrap their return value in an array; unwrap the first element if present
+    if (Array.isArray(value)) {
+        const first = value[0];
+        // Non-empty string at index 0 is the only valid array payload
+        if (typeof first === 'string' && first.length > 0) {
+            return first;
+        }
+        // Array was empty or held a non-string — treat as no result
+        return undefined;
+    }
+    return undefined;
+}
+//# sourceMappingURL=normalize-string-result.js.map

package/dist/esm/adapters/custom-adapter/normalize-string-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-string-result.js","sourceRoot":"","sources":["../../../../src/adapters/custom-adapter/normalize-string-result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,qFAAqF;IACrF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2FAA2F;IAC3F,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACvB,8DAA8D;QAC9D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,4DAA4D;QAC5D,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/esm/adapters/custom-adapter/to-app-relative.js

@@ -0,0 +1,34 @@
+/**
+ * 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 function toAppRelative(fullPathname, appBasename) {
+    // Basename matches the pathname — the app is at its root, return '/' as the relative path
+    if (fullPathname === appBasename || fullPathname.startsWith(`${appBasename}/`)) {
+        const relative = fullPathname.slice(appBasename.length);
+        // Ensure the relative path always starts with '/' for consistent input to app hooks
+        return relative.startsWith('/') ? relative : `/${relative}`;
+    }
+    // Basename not found in pathname — return as-is; the app hook will see the full path
+    return fullPathname;
+}
+//# sourceMappingURL=to-app-relative.js.map

package/dist/esm/adapters/custom-adapter/to-app-relative.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-app-relative.js","sourceRoot":"","sources":["../../../../src/adapters/custom-adapter/to-app-relative.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,aAAa,CAAC,YAAoB,EAAE,WAAmB;IACrE,0FAA0F;IAC1F,IAAI,YAAY,KAAK,WAAW,IAAI,YAAY,CAAC,UAAU,CAAC,GAAG,WAAW,GAAG,CAAC,EAAE,CAAC;QAC/E,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACxD,oFAAoF;QACpF,OAAO,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,EAAE,CAAC;IAC9D,CAAC;IACD,qFAAqF;IACrF,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/dist/esm/adapters/custom-adapter/to-full-path.js

@@ -0,0 +1,28 @@
+/**
+ * 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 function toFullPath(appRelativePath, appBasename) {
+    // Strip trailing slash from base so we can unconditionally prepend a leading slash from rel
+    const base = appBasename.endsWith('/') ? appBasename.slice(0, -1) : appBasename;
+    // Ensure rel always starts with '/' before concatenation to avoid double- or missing-slash
+    const rel = appRelativePath.startsWith('/') ? appRelativePath : `/${appRelativePath}`;
+    return `${base}${rel}`;
+}
+//# sourceMappingURL=to-full-path.js.map

package/dist/esm/adapters/custom-adapter/to-full-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-full-path.js","sourceRoot":"","sources":["../../../../src/adapters/custom-adapter/to-full-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,UAAU,CAAC,eAAuB,EAAE,WAAmB;IACrE,4FAA4F;IAC5F,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;IAChF,2FAA2F;IAC3F,MAAM,GAAG,GAAG,eAAe,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,eAAe,EAAE,CAAC;IACtF,OAAO,GAAG,IAAI,GAAG,GAAG,EAAE,CAAC;AACzB,CAAC"}

package/dist/esm/adapters/index.js

@@ -0,0 +1,4 @@
+export { createPathAdapter } from './create-path-adapter';
+export { createQueryAdapter } from './create-query-adapter';
+export { createCustomAdapter } from './custom-adapter';
+//# sourceMappingURL=index.js.map

package/dist/esm/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","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"}

package/dist/esm/adapters/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/adapters/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapters/types.ts"],"names":[],"mappings":""}