feat: Allow extension packages to disallow routing modes

src/lib/Fallback/Fallback.svelte

@@ -2,6 +2,7 @@
 	import { resolveHashValue } from '$lib/core/resolveHashValue.js';
 	import { getRouterContext } from '$lib/Router/Router.svelte';
 	import type { RouteStatus, WhenPredicate } from '$lib/types.js';
+	import { assertAllowedRoutingMode } from '$lib/utils.js';
 	import type { Snippet } from 'svelte';
 
 	type Props = {
@@ -63,7 +64,10 @@
 
 	let { hash, when, children }: Props = $props();
 
-	const router = getRouterContext(resolveHashValue(hash));
+	const resolvedHash = resolveHashValue(hash);
+	assertAllowedRoutingMode(resolvedHash);
+
+	const router = getRouterContext(resolvedHash);
 </script>
 
 {#if (router && when?.(router.routeStatus, router.noMatches)) || (!when && router?.noMatches)}

src/lib/Fallback/Fallback.svelte.test.ts

@@ -2,8 +2,10 @@ import { init } from "$lib/init.js";
 import { describe, test, expect, beforeAll, afterAll, beforeEach } from "vitest";
 import { render } from "@testing-library/svelte";
 import Fallback from "./Fallback.svelte";
-import { addMatchingRoute, addRoutes, createRouterTestSetup, createTestSnippet, ROUTING_UNIVERSES } from "../../testing/test-utils.js";
+import { addMatchingRoute, addRoutes, createRouterTestSetup, createTestSnippet, ROUTING_UNIVERSES, ALL_HASHES } from "../../testing/test-utils.js";
 import { flushSync } from "svelte";
+import { resetRoutingOptions, setRoutingOptions } from "$lib/core/options.js";
+import type { ExtendedRoutingOptions } from "$lib/types.js";
 
 function defaultPropsTests(setup: ReturnType<typeof createRouterTestSetup>) {
     const contentText = "Fallback content.";
@@ -161,6 +163,57 @@ function reactivityTests(setup: ReturnType<typeof createRouterTestSetup>) {
     });
 }
 
+describe("Routing Mode Assertions", () => {
+    const contentText = "Fallback content.";
+    const content = createTestSnippet(contentText);
+    let cleanup: () => void;
+
+    beforeAll(() => {
+        cleanup = init();
+    });
+
+    beforeEach(() => {
+        resetRoutingOptions();
+    });
+
+    afterAll(() => {
+        resetRoutingOptions();
+        cleanup();
+    });
+
+    test.each<{
+        options: Partial<ExtendedRoutingOptions>;
+        hash: typeof ALL_HASHES[keyof typeof ALL_HASHES];
+        description: string;
+    }>([
+        {
+            options: { disallowHashRouting: true },
+            hash: ALL_HASHES.single,
+            description: 'hash routing is disallowed'
+        },
+        {
+            options: { disallowMultiHashRouting: true },
+            hash: ALL_HASHES.multi,
+            description: 'multi-hash routing is disallowed'
+        },
+        {
+            options: { disallowPathRouting: true },
+            hash: ALL_HASHES.path,
+            description: 'path routing is disallowed'
+        }
+    ])("Should throw error when $description and hash=$hash .", ({ options, hash }) => {
+        // Arrange
+        setRoutingOptions(options);
+
+        // Act & Assert
+        expect(() => {
+            render(Fallback, { 
+                props: { hash, children: content }, 
+            });
+        }).toThrow();
+    });
+});
+
 ROUTING_UNIVERSES.forEach(ru => {
     describe(`Fallback - ${ru.text}`, () => {
         const setup = createRouterTestSetup(ru.hash);

src/lib/Link/Link.svelte

@@ -6,6 +6,7 @@
 	import { getLinkContext, type ILinkContext } from '$lib/LinkContext/LinkContext.svelte';
 	import { getRouterContext } from '$lib/Router/Router.svelte';
 	import type { ActiveState, Hash, RouteStatus } from '$lib/types.js';
+	import { assertAllowedRoutingMode } from '$lib/utils.js';
 	import { type Snippet } from 'svelte';
 	import type { HTMLAnchorAttributes } from 'svelte/elements';
 
@@ -85,6 +86,7 @@
 	}: Props = $props();
 
 	const resolvedHash = resolveHashValue(hash);
+	assertAllowedRoutingMode(resolvedHash);
 	const router = getRouterContext(resolvedHash);
 	const linkContext = getLinkContext();
 	const calcReplace = $derived(replace ?? linkContext?.replace ?? false);

src/lib/Link/Link.svelte.test.ts

@@ -1,10 +1,12 @@
 import { init } from "$lib/init.js";
 import { location } from "$lib/core/Location.js";
-import { describe, test, expect, beforeAll, afterAll, beforeEach, vi } from "vitest";
+import { describe, test, expect, beforeAll, afterAll, beforeEach, vi, afterEach } from "vitest";
 import { render, fireEvent } from "@testing-library/svelte";
 import Link from "./Link.svelte";
-import { createRouterTestSetup, createTestSnippet, ROUTING_UNIVERSES } from "../../testing/test-utils.js";
+import { createRouterTestSetup, createTestSnippet, ROUTING_UNIVERSES, ALL_HASHES } from "../../testing/test-utils.js";
 import { flushSync } from "svelte";
+import { resetRoutingOptions, setRoutingOptions } from "$lib/core/options.js";
+import type { ExtendedRoutingOptions } from "$lib/types.js";
 
 function basicLinkTests(setup: ReturnType<typeof createRouterTestSetup>) {
     const linkText = "Test Link";
@@ -636,6 +638,61 @@ function reactivityTests(setup: ReturnType<typeof createRouterTestSetup>) {
     });
 }
 
+describe("Routing Mode Assertions", () => {
+    const linkText = "Test Link";
+    const content = createTestSnippet(linkText);
+    let cleanup: () => void;
+
+    beforeAll(() => {
+        cleanup = init();
+    });
+
+    afterEach(() => {
+        resetRoutingOptions();
+    });
+
+    afterAll(() => {
+        cleanup();
+    });
+
+    test.each<{
+        options: Partial<ExtendedRoutingOptions>;
+        hash: typeof ALL_HASHES[keyof typeof ALL_HASHES];
+        description: string;
+    }>([
+        {
+            options: { disallowHashRouting: true },
+            hash: ALL_HASHES.single,
+            description: 'hash routing is disallowed'
+        },
+        {
+            options: { disallowMultiHashRouting: true },
+            hash: ALL_HASHES.multi,
+            description: 'multi-hash routing is disallowed'
+        },
+        {
+            options: { disallowPathRouting: true },
+            hash: ALL_HASHES.path,
+            description: 'path routing is disallowed'
+        }
+    ])("Should throw error when $description and hash=$hash .", ({ options, hash }) => {
+        // Arrange
+        setRoutingOptions(options);
+
+        // Act & Assert
+        expect(() => {
+            render(Link, { 
+                props: { 
+                    href: "/test", 
+                    hash, 
+                    children: content 
+                }, 
+            });
+        }).toThrow();
+    });
+});
+
+
 ROUTING_UNIVERSES.forEach(ru => {
     describe(`Link - ${ru.text}`, () => {
         const setup = createRouterTestSetup(ru.hash);
@@ -649,7 +706,7 @@ ROUTING_UNIVERSES.forEach(ru => {
         });
 
         afterAll(() => {
-            cleanup();
+            cleanup?.();
         });
 
         describe("Basic Link Functionality", () => {

src/lib/Route/Route.svelte

@@ -21,6 +21,7 @@
 	import { getRouterContext } from '../Router/Router.svelte';
 	import { resolveHashValue } from '$lib/core/resolveHashValue.js';
 	import type { ParameterValue, RouteStatus } from '$lib/types.js';
+	import { assertAllowedRoutingMode } from '$lib/utils.js';
 
 	type Props = {
 		/**
@@ -132,7 +133,10 @@
 		children
 	}: Props = $props();
 
-	const router = getRouterContext(resolveHashValue(hash));
+	const resolvedHash = resolveHashValue(hash);
+	assertAllowedRoutingMode(resolvedHash);
+
+	const router = getRouterContext(resolvedHash);
 	if (!router) {
 		throw new Error(
 			'Route components must be used inside a Router component that matches the hash setting.'

src/lib/Route/Route.svelte.test.ts

@@ -1,10 +1,12 @@
-import { describe, test, expect, beforeEach, vi, beforeAll, afterAll } from "vitest";
+import { describe, test, expect, beforeEach, vi, beforeAll, afterAll, afterEach } from "vitest";
 import { render } from "@testing-library/svelte";
 import Route from "./Route.svelte";
-import { createTestSnippet, createRouterTestSetup, ROUTING_UNIVERSES } from "../../testing/test-utils.js";
+import { createTestSnippet, createRouterTestSetup, ROUTING_UNIVERSES, ALL_HASHES } from "../../testing/test-utils.js";
 import { init } from "$lib/init.js";
 import { location } from "$lib/core/Location.js";
 import TestRouteWithRouter from "../../testing/TestRouteWithRouter.svelte";
+import { resetRoutingOptions, setRoutingOptions } from "$lib/core/options.js";
+import type { ExtendedRoutingOptions, InitOptions } from "$lib/types.js";
 
 function basicRouteTests(setup: ReturnType<typeof createRouterTestSetup>) {
     beforeEach(() => {
@@ -646,6 +648,78 @@ function routeBindingTestsForUniverse(setup: ReturnType<typeof createRouterTestS
     });
 }
 
+describe("Routing Mode Assertions", () => {
+    let cleanup: () => void;
+
+    beforeAll(() => {
+        cleanup = init();
+    });
+
+    afterEach(() => {
+        resetRoutingOptions();
+    });
+
+    afterAll(() => {
+        cleanup();
+    });
+
+    test.each<{
+        options: Partial<ExtendedRoutingOptions>;
+        hash: typeof ALL_HASHES[keyof typeof ALL_HASHES];
+        description: string;
+    }>([
+        {
+            options: { disallowHashRouting: true },
+            hash: ALL_HASHES.single,
+            description: 'hash routing is disallowed'
+        },
+        {
+            options: { disallowMultiHashRouting: true },
+            hash: ALL_HASHES.multi,
+            description: 'multi-hash routing is disallowed'
+        },
+        {
+            options: { disallowPathRouting: true },
+            hash: ALL_HASHES.path,
+            description: 'path routing is disallowed'
+        }
+    ])("Should throw error when $description and hash=$hash .", ({ options, hash }) => {
+        // Arrange
+        setRoutingOptions(options);
+
+        // Act & Assert
+        expect(() => {
+            render(Route, {
+                props: {
+                    key: 'r1',
+                    hash,
+                }, 
+            });
+        }).toThrow();
+    });
+
+    test("Should not throw error when all routing modes are allowed.", () => {
+        // Arrange
+        const hash = ALL_HASHES.single;
+        const setup = createRouterTestSetup(hash);
+        setup.init();
+
+        // Act & Assert
+        expect(() => {
+            render(Route, { 
+                props: { 
+                    hash,
+                    key: "test-route", 
+                }, 
+                context: setup.context 
+            });
+        }).not.toThrow();
+
+        // Cleanup  
+        setup.dispose();
+    });
+});
+
 // Run tests for each routing universe
 for (const ru of ROUTING_UNIVERSES) {
     describe(`Route - ${ru.text}`, () => {

src/lib/RouterTrace/RouterTrace.svelte

@@ -8,6 +8,7 @@
 	import { getRouterContext } from '$lib/Router/Router.svelte';
 	import type { PatternRouteInfo } from '$lib/types.js';
 	import type { HTMLTableAttributes } from 'svelte/elements';
+	import { assertAllowedRoutingMode } from '$lib/utils.js';
 
 	type Props = Omit<HTMLTableAttributes, 'children'> & {
 		/**
@@ -56,7 +57,9 @@
 	}: Props = $props();
 
 	if (!router) {
-		router = getRouterContext(resolveHashValue(hash));
+		const resolvedHash = resolveHashValue(hash);
+		assertAllowedRoutingMode(resolvedHash);
+		router = getRouterContext(resolvedHash);
 		if (!router) {
 			throw new Error(
 				'There is no router to trace.  Make sure a Router component is an ancestor of this RouterTrace component instance, or provide a router using the "router" property.'