@real-router/svelte 0.2.13 → 0.3.0

package/README.md

@@ -142,6 +142,7 @@ Navigation link with automatic active state detection. Uses `$derived` for href
 | `activeStrict`      | `boolean`           | `false`     | Exact match only (no ancestor matching) |
 | `ignoreQueryParams` | `boolean`           | `true`      | Query params don't affect active state  |
 | `target`            | `string`            | `undefined` | Link target (`_blank`, etc.)            |
+| `onclick`           | `(evt: MouseEvent) => void` | `undefined` | Custom click handler. Runs **before** the navigation logic — call `evt.preventDefault()` to suppress navigation. |
 
 All other props are spread onto the `<a>` element.
 
@@ -206,7 +207,13 @@ Declarative error handling for navigation errors. Shows a fallback **alongside**
 </script>
 
 <RouterErrorBoundary
-  onError={(error) => analytics.track("nav_error", { code: error.code })}
+  onError={(error, toRoute, fromRoute) =>
+    analytics.track("nav_error", {
+      code: error.code,
+      to: toRoute?.name,
+      from: fromRoute?.name,
+    })
+  }
 >
   {#snippet fallback(error, resetError)}
     <div class="toast">
@@ -220,6 +227,8 @@ Declarative error handling for navigation errors. Shows a fallback **alongside**
 
 Auto-resets on next successful navigation. Works with both `<Link>` and imperative `router.navigate()`.
 
+**`onError` signature:** `(error, toRoute, fromRoute) => void`. Receives the `RouterError`, the attempted destination (`State | null`), and the previously active route (`State | null`). A throwing `onError` is caught by the boundary, logged via `console.error`, and never breaks reactivity.
+
 ## Actions
 
 ### `createLinkAction`
@@ -363,9 +372,9 @@ Full documentation: [Wiki](https://github.com/greydragon888/real-router/wiki)
 
 ## Examples
 
-15 runnable examples — each is a standalone Vite app. Run: `cd examples/svelte/basic && pnpm dev`
+16 runnable examples — each is a standalone Vite app. Run: `cd examples/svelte/basic && pnpm dev`
 
-[basic](../../examples/svelte/basic) · [nested-routes](../../examples/svelte/nested-routes) · [auth-guards](../../examples/svelte/auth-guards) · [data-loading](../../examples/svelte/data-loading) · [lazy-loading](../../examples/svelte/lazy-loading) · [async-guards](../../examples/svelte/async-guards) · [hash-routing](../../examples/svelte/hash-routing) · [persistent-params](../../examples/svelte/persistent-params) · [error-handling](../../examples/svelte/error-handling) · [dynamic-routes](../../examples/svelte/dynamic-routes) · [link-action](../../examples/svelte/link-action) · [lazy-loading-svelte](../../examples/svelte/lazy-loading-svelte) · [snippets-routing](../../examples/svelte/snippets-routing) · [reactive-source](../../examples/svelte/reactive-source) · [combined](../../examples/svelte/combined)
+[basic](../../examples/svelte/basic) · [nested-routes](../../examples/svelte/nested-routes) · [auth-guards](../../examples/svelte/auth-guards) · [data-loading](../../examples/svelte/data-loading) · [lazy-loading](../../examples/svelte/lazy-loading) · [async-guards](../../examples/svelte/async-guards) · [hash-routing](../../examples/svelte/hash-routing) · [persistent-params](../../examples/svelte/persistent-params) · [error-handling](../../examples/svelte/error-handling) · [dynamic-routes](../../examples/svelte/dynamic-routes) · [link-action](../../examples/svelte/link-action) · [lazy-loading-svelte](../../examples/svelte/lazy-loading-svelte) · [snippets-routing](../../examples/svelte/snippets-routing) · [reactive-source](../../examples/svelte/reactive-source) · [search-schema](../../examples/svelte/search-schema) · [combined](../../examples/svelte/combined)
 
 ## Related Packages
 

package/dist/RouterProvider.svelte

@@ -5,6 +5,7 @@
   import { setContext } from "svelte";
 
   import { createReactiveSource } from "./createReactiveSource.svelte";
+  import { createRouteContext } from "./createRouteContext.svelte";
   import { NAVIGATOR_KEY, ROUTE_KEY, ROUTER_KEY } from "./context";
 
   import type { Router } from "@real-router/core";
@@ -26,26 +27,11 @@
   const navigator = getNavigator(router);
   const source = createRouteSource(router);
   const reactive = createReactiveSource(source);
+  const routeContext = createRouteContext(navigator, reactive);
 
   setContext(ROUTER_KEY, router);
   setContext(NAVIGATOR_KEY, navigator);
-  setContext(ROUTE_KEY, {
-    navigator,
-    get route() {
-      return {
-        get current() {
-          return reactive.current.route;
-        },
-      };
-    },
-    get previousRoute() {
-      return {
-        get current() {
-          return reactive.current.previousRoute;
-        },
-      };
-    },
-  });
+  setContext(ROUTE_KEY, routeContext);
 </script>
 
 {@render children()}

package/dist/actions/link.svelte.d.ts

@@ -5,6 +5,7 @@ export interface LinkActionParams {
     params?: Params;
     options?: NavigationOptions;
 }
+type LinkAction = (node: HTMLElement, params: LinkActionParams) => ActionReturn<LinkActionParams>;
 /**
  * Factory function that captures router context during component initialization.
  * Must be called during component init (not inside event handlers or effects).
@@ -23,4 +24,5 @@ export interface LinkActionParams {
  * <a use:link={{ name: 'users', params: { id: '123' } }}>User Profile</a>
  * ```
  */
-export declare function createLinkAction(): (node: HTMLElement, params: LinkActionParams) => ActionReturn<LinkActionParams>;
+export declare function createLinkAction(): LinkAction;
+export {};

package/dist/actions/link.svelte.js

@@ -1,5 +1,5 @@
-import { getContext } from "svelte";
-import { ROUTER_KEY } from "../context";
+import { ROUTER_KEY, getContextOrThrow } from "../context";
+import { EMPTY_OPTIONS, EMPTY_PARAMS, NOOP } from "../constants";
 import { shouldNavigate, applyLinkA11y } from "../dom-utils/index.js";
 /**
  * Factory function that captures router context during component initialization.
@@ -20,30 +20,28 @@ import { shouldNavigate, applyLinkA11y } from "../dom-utils/index.js";
  * ```
  */
 export function createLinkAction() {
-    const router = getContext(ROUTER_KEY);
-    if (!router) {
-        throw new Error("createLinkAction must be called inside a RouterProvider");
-    }
+    const router = getContextOrThrow(ROUTER_KEY, "createLinkAction");
     return function link(node, params) {
         let currentParams = params;
         applyLinkA11y(node);
+        function navigate() {
+            router
+                .navigate(currentParams.name, currentParams.params ?? EMPTY_PARAMS, currentParams.options ?? EMPTY_OPTIONS)
+                .catch(NOOP);
+        }
         function handleClick(evt) {
             if (!shouldNavigate(evt))
                 return;
+            if (node instanceof HTMLAnchorElement &&
+                node.getAttribute("target") === "_blank") {
+                return;
+            }
             evt.preventDefault();
-            // router is guaranteed to exist due to check in factory
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            router
-                .navigate(currentParams.name, currentParams.params ?? {}, currentParams.options ?? {})
-                .catch(() => { });
+            navigate();
         }
         function handleKeyDown(evt) {
             if (evt.key === "Enter" && !(node instanceof HTMLButtonElement)) {
-                // router is guaranteed to exist due to check in factory
-                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                router
-                    .navigate(currentParams.name, currentParams.params ?? {}, currentParams.options ?? {})
-                    .catch(() => { });
+                navigate();
             }
         }
         node.addEventListener("click", handleClick);

package/dist/components/Lazy.svelte

@@ -9,26 +9,33 @@
     fallback?: Component | undefined;
   } = $props();
 
-  let LoadedComponent = $state<Component | null>(null);
-  let error = $state<Error | null>(null);
-  let loading = $state(true);
+  type LazyState =
+    | { status: "loading" }
+    | { status: "ready"; component: Component }
+    | { status: "error"; error: Error };
+
+  let state = $state<LazyState>({ status: "loading" });
 
   $effect(() => {
-    loading = true;
-    error = null;
-    LoadedComponent = null;
+    state = { status: "loading" };
     let active = true;
 
     loader()
       .then((module) => {
         if (!active) return;
-        LoadedComponent = module.default;
-        loading = false;
+        if (!module || typeof module.default === "undefined") {
+          throw new Error(
+            "[real-router] Lazy loader resolved without a `default` export.",
+          );
+        }
+        state = { status: "ready", component: module.default };
       })
-      .catch((err) => {
+      .catch((err: unknown) => {
         if (!active) return;
-        error = err;
-        loading = false;
+        state = {
+          status: "error",
+          error: err instanceof Error ? err : new Error(String(err)),
+        };
       });
 
     return () => {
@@ -37,11 +44,12 @@
   });
 </script>
 
-{#if loading && fallback}
+{#if state.status === "loading" && fallback}
   {@const Fallback = fallback}
   <Fallback />
-{:else if error}
-  <p>Error loading component: {error.message}</p>
-{:else if LoadedComponent}
+{:else if state.status === "error"}
+  <p>Error loading component: {state.error.message}</p>
+{:else if state.status === "ready"}
+  {@const LoadedComponent = state.component}
   <LoadedComponent />
 {/if}

package/dist/components/Link.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   import { useIsActiveRoute } from "../composables/useIsActiveRoute.svelte";
   import { useRouter } from "../composables/useRouter.svelte";
+  import { EMPTY_OPTIONS, EMPTY_PARAMS, NOOP } from "../constants";
   import {
     shouldNavigate,
     buildHref,
@@ -12,8 +13,8 @@
 
   let {
     routeName,
-    routeParams = {} as Params,
-    routeOptions = {} as NavigationOptions,
+    routeParams = EMPTY_PARAMS,
+    routeOptions = EMPTY_OPTIONS,
     class: className = undefined,
     activeClassName = "active",
     activeStrict = false,
@@ -64,7 +65,7 @@
     }
 
     evt.preventDefault();
-    router.navigate(routeName, routeParams, routeOptions).catch(() => {});
+    router.navigate(routeName, routeParams, routeOptions).catch(NOOP);
   }
 </script>
 

package/dist/components/RouteView.svelte

@@ -1,6 +1,26 @@
+<script lang="ts" module>
+  import { startsWithSegment } from "@real-router/route-utils";
+
+  export function getActiveSegment(
+    routeName: string,
+    node: string,
+    snippets: Record<string, unknown>,
+  ): string {
+    const prefix = node ? `${node}.` : "";
+
+    for (const segment in snippets) {
+      if (segment === "notFound") continue;
+      if (startsWithSegment(routeName, prefix + segment)) {
+        return segment;
+      }
+    }
+
+    return "";
+  }
+</script>
+
 <script lang="ts">
   import { UNKNOWN_ROUTE } from "@real-router/core";
-  import { startsWithSegment } from "@real-router/route-utils";
 
   import { useRouteNode } from "../composables/useRouteNode.svelte";
 
@@ -17,29 +37,14 @@
   } = $props();
 
   const routeContext = useRouteNode(nodeName);
-
-  function getActiveSegment(
-    routeName: string,
-    node: string,
-    snippets: Record<string, unknown>,
-  ): string {
-    for (const segment of Object.keys(snippets)) {
-      const fullSegmentName = node ? `${node}.${segment}` : segment;
-
-      if (startsWithSegment(routeName, fullSegmentName)) {
-        return segment;
-      }
-    }
-
-    return "";
-  }
 </script>
 
 {#if routeContext.route.current}
   {@const route = routeContext.route.current}
   {@const segment = getActiveSegment(route.name, nodeName, segmentSnippets)}
-  {#if segment && segmentSnippets[segment]}
-    {@render (segmentSnippets[segment] as Snippet)()}
+  {#if segment}
+    {@const snippet = segmentSnippets[segment] as Snippet}
+    {@render snippet()}
   {:else if route.name === UNKNOWN_ROUTE && notFound}
     {@render notFound()}
   {/if}

package/dist/components/RouteView.svelte.d.ts

@@ -1,3 +1,4 @@
+export declare function getActiveSegment(routeName: string, node: string, snippets: Record<string, unknown>): string;
 import type { Snippet } from "svelte";
 type $$ComponentProps = {
     nodeName: string;

package/dist/components/RouterErrorBoundary.svelte

@@ -32,12 +32,20 @@
   }
 
   $effect(() => {
-    if (snapshot.current.error) {
-      const { error, toRoute, fromRoute } = snapshot.current;
-      untrack(() => {
+    const snap = snapshot.current;
+    if (!snap.error) return;
+
+    const { error, toRoute, fromRoute } = snap;
+    untrack(() => {
+      try {
         onError?.(error, toRoute, fromRoute);
-      });
-    }
+      } catch (callbackError) {
+        console.error(
+          "[real-router] RouterErrorBoundary onError handler threw:",
+          callbackError,
+        );
+      }
+    });
   });
 </script>
 

package/dist/composables/useIsActiveRoute.svelte.d.ts

@@ -1,4 +1,4 @@
 import type { Params } from "@real-router/core";
-export declare function useIsActiveRoute(routeName: string, params?: Params, strict?: boolean, ignoreQueryParams?: boolean): {
+export declare function useIsActiveRoute(routeName: string, params: Params | undefined, strict: boolean, ignoreQueryParams: boolean): {
     readonly current: boolean;
 };

package/dist/composables/useIsActiveRoute.svelte.js

@@ -1,7 +1,7 @@
 import { createActiveRouteSource } from "@real-router/sources";
 import { createReactiveSource } from "../createReactiveSource.svelte";
 import { useRouter } from "./useRouter.svelte";
-export function useIsActiveRoute(routeName, params, strict = false, ignoreQueryParams = true) {
+export function useIsActiveRoute(routeName, params, strict, ignoreQueryParams) {
     const router = useRouter();
     const source = createActiveRouteSource(router, routeName, params, {
         strict,

package/dist/composables/useNavigator.svelte.js

@@ -1,9 +1,2 @@
-import { getContext } from "svelte";
-import { NAVIGATOR_KEY } from "../context";
-export const useNavigator = () => {
-    const navigator = getContext(NAVIGATOR_KEY);
-    if (!navigator) {
-        throw new Error("useNavigator must be used within a RouterProvider");
-    }
-    return navigator;
-};
+import { NAVIGATOR_KEY, getContextOrThrow } from "../context";
+export const useNavigator = () => getContextOrThrow(NAVIGATOR_KEY, "useNavigator");

package/dist/composables/useRoute.svelte.js

@@ -1,9 +1,2 @@
-import { getContext } from "svelte";
-import { ROUTE_KEY } from "../context";
-export const useRoute = () => {
-    const routeContext = getContext(ROUTE_KEY);
-    if (!routeContext) {
-        throw new Error("useRoute must be used within a RouterProvider");
-    }
-    return routeContext;
-};
+import { ROUTE_KEY, getContextOrThrow } from "../context";
+export const useRoute = () => getContextOrThrow(ROUTE_KEY, "useRoute");

package/dist/composables/useRouteNode.svelte.js

@@ -1,27 +1,12 @@
 import { getNavigator } from "@real-router/core";
 import { createRouteNodeSource } from "@real-router/sources";
 import { createReactiveSource } from "../createReactiveSource.svelte";
+import { createRouteContext } from "../createRouteContext.svelte";
 import { useRouter } from "./useRouter.svelte";
 export function useRouteNode(nodeName) {
     const router = useRouter();
     const navigator = getNavigator(router);
     const source = createRouteNodeSource(router, nodeName);
     const reactive = createReactiveSource(source);
-    return {
-        navigator,
-        get route() {
-            return {
-                get current() {
-                    return reactive.current.route;
-                },
-            };
-        },
-        get previousRoute() {
-            return {
-                get current() {
-                    return reactive.current.previousRoute;
-                },
-            };
-        },
-    };
+    return createRouteContext(navigator, reactive);
 }

package/dist/composables/useRouter.svelte.js

@@ -1,9 +1,2 @@
-import { getContext } from "svelte";
-import { ROUTER_KEY } from "../context";
-export const useRouter = () => {
-    const router = getContext(ROUTER_KEY);
-    if (!router) {
-        throw new Error("useRouter must be used within a RouterProvider");
-    }
-    return router;
-};
+import { ROUTER_KEY, getContextOrThrow } from "../context";
+export const useRouter = () => getContextOrThrow(ROUTER_KEY, "useRouter");

package/dist/constants.d.ts

@@ -0,0 +1,4 @@
+import type { NavigationOptions, Params } from "@real-router/core";
+export declare const EMPTY_PARAMS: Params;
+export declare const EMPTY_OPTIONS: NavigationOptions;
+export declare const NOOP: () => void;

package/dist/constants.js

@@ -0,0 +1,3 @@
+export const EMPTY_PARAMS = Object.freeze({});
+export const EMPTY_OPTIONS = Object.freeze({});
+export const NOOP = () => { };

package/dist/context.d.ts

@@ -1,3 +1,4 @@
 export declare const ROUTER_KEY = "real-router:router";
 export declare const NAVIGATOR_KEY = "real-router:navigator";
 export declare const ROUTE_KEY = "real-router:route";
+export declare function getContextOrThrow<T>(key: string, consumerName: string): T;

package/dist/context.js

@@ -1,3 +1,16 @@
+import { getContext } from "svelte";
 export const ROUTER_KEY = "real-router:router";
 export const NAVIGATOR_KEY = "real-router:navigator";
 export const ROUTE_KEY = "real-router:route";
+// The type parameter is used by the caller to narrow the return type.
+// ESLint's no-unnecessary-type-parameters sees only a single textual use of T
+// (the return type) — but each call site supplies a different T, so it is not
+// unnecessary. Inline generic helpers are a standard pattern for typed context.
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+export function getContextOrThrow(key, consumerName) {
+    const value = getContext(key);
+    if (!value) {
+        throw new Error(`${consumerName} must be used within a RouterProvider`);
+    }
+    return value;
+}

package/dist/createRouteContext.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Navigator, State } from "@real-router/core";
+import type { RouteContext } from "./types";
+export interface RouteSnapshot {
+    readonly route: State | undefined;
+    readonly previousRoute: State | undefined;
+}
+export declare function createRouteContext(navigator: Navigator, reactive: {
+    readonly current: RouteSnapshot;
+}): RouteContext;

package/dist/createRouteContext.svelte.js

@@ -0,0 +1,13 @@
+export function createRouteContext(navigator, reactive) {
+    const route = {
+        get current() {
+            return reactive.current.route;
+        },
+    };
+    const previousRoute = {
+        get current() {
+            return reactive.current.previousRoute;
+        },
+    };
+    return { navigator, route, previousRoute };
+}

package/dist/dom-utils/index.d.ts

@@ -1,3 +1,3 @@
 export { createRouteAnnouncer } from "./route-announcer.js";
-export { shouldNavigate, buildHref, buildActiveClassName, applyLinkA11y, } from "./link-utils.js";
+export { shouldNavigate, buildHref, buildActiveClassName, shallowEqual, applyLinkA11y, } from "./link-utils.js";
 export type { RouteAnnouncerOptions } from "./route-announcer.js";

package/dist/dom-utils/index.js

@@ -1,2 +1,2 @@
 export { createRouteAnnouncer } from "./route-announcer.js";
-export { shouldNavigate, buildHref, buildActiveClassName, applyLinkA11y, } from "./link-utils.js";
+export { shouldNavigate, buildHref, buildActiveClassName, shallowEqual, applyLinkA11y, } from "./link-utils.js";

package/dist/dom-utils/link-utils.d.ts

@@ -2,4 +2,5 @@ import type { Router, Params } from "@real-router/core";
 export declare function shouldNavigate(evt: MouseEvent): boolean;
 export declare function buildHref(router: Router, routeName: string, routeParams: Params): string | undefined;
 export declare function buildActiveClassName(isActive: boolean, activeClassName: string | undefined, baseClassName: string | undefined): string | undefined;
-export declare function applyLinkA11y(element: HTMLElement): void;
+export declare function shallowEqual(prev: object | undefined, next: object | undefined): boolean;
+export declare function applyLinkA11y(element: HTMLElement | null | undefined): void;

package/dist/dom-utils/link-utils.js

@@ -9,7 +9,10 @@ export function buildHref(router, routeName, routeParams) {
     try {
         const buildUrl = router.buildUrl;
         if (buildUrl) {
-            return buildUrl(routeName, routeParams);
+            const url = buildUrl(routeName, routeParams);
+            if (url !== undefined) {
+                return url;
+            }
         }
         return router.buildPath(routeName, routeParams);
     }
@@ -18,23 +21,62 @@ export function buildHref(router, routeName, routeParams) {
         return undefined;
     }
 }
+function parseTokens(value) {
+    return value ? (value.match(/\S+/g) ?? []) : [];
+}
 export function buildActiveClassName(isActive, activeClassName, baseClassName) {
     if (isActive && activeClassName) {
-        return baseClassName
-            ? `${baseClassName} ${activeClassName}`.trim()
-            : activeClassName;
+        const activeTokens = parseTokens(activeClassName);
+        if (activeTokens.length === 0) {
+            return baseClassName ?? undefined;
+        }
+        if (!baseClassName) {
+            return activeTokens.join(" ");
+        }
+        const baseTokens = parseTokens(baseClassName);
+        const seen = new Set(baseTokens);
+        for (const token of activeTokens) {
+            if (!seen.has(token)) {
+                seen.add(token);
+                baseTokens.push(token);
+            }
+        }
+        return baseTokens.join(" ");
     }
     return baseClassName ?? undefined;
 }
+export function shallowEqual(prev, next) {
+    if (Object.is(prev, next)) {
+        return true;
+    }
+    if (!prev || !next) {
+        return false;
+    }
+    const prevKeys = Object.keys(prev);
+    if (prevKeys.length !== Object.keys(next).length) {
+        return false;
+    }
+    const prevRecord = prev;
+    const nextRecord = next;
+    for (const key of prevKeys) {
+        if (!Object.is(prevRecord[key], nextRecord[key])) {
+            return false;
+        }
+    }
+    return true;
+}
 export function applyLinkA11y(element) {
+    if (!element) {
+        return;
+    }
     if (element instanceof HTMLAnchorElement ||
         element instanceof HTMLButtonElement) {
         return;
     }
-    if (!element.getAttribute("role")) {
+    if (!element.hasAttribute("role")) {
         element.setAttribute("role", "link");
     }
-    if (!element.getAttribute("tabindex")) {
+    if (!element.hasAttribute("tabindex")) {
         element.setAttribute("tabindex", "0");
     }
 }

package/dist/dom-utils/route-announcer.js

@@ -10,32 +10,57 @@ export function createRouteAnnouncer(router, options) {
     let isReady = false;
     let isDestroyed = false;
     let lastAnnouncedText = "";
+    let pendingText = null;
     let clearTimeoutId;
     const announcer = getOrCreateAnnouncer();
+    const doAnnounce = (text, h1) => {
+        lastAnnouncedText = text;
+        clearTimeout(clearTimeoutId);
+        announcer.textContent = text;
+        clearTimeoutId = setTimeout(() => {
+            announcer.textContent = "";
+            lastAnnouncedText = "";
+        }, CLEAR_DELAY);
+        manageFocus(h1);
+    };
+    // Safari-ready delay: announcing before VoiceOver wires up the aria-live region
+    // causes the first announcement to be silently dropped. Wait SAFARI_READY_DELAY ms
+    // before marking the announcer "ready" — any navigation during that window is
+    // buffered in pendingText and flushed once the delay expires.
     const safariTimeoutId = setTimeout(() => {
         isReady = true;
+        if (pendingText !== null && !isDestroyed) {
+            const text = pendingText;
+            pendingText = null;
+            doAnnounce(text, document.querySelector("h1"));
+        }
     }, SAFARI_READY_DELAY);
     const unsubscribe = router.subscribe(({ route }) => {
         if (isInitialNavigation) {
             isInitialNavigation = false;
             return;
         }
+        // Double rAF: waits for two paint frames so the incoming route's DOM
+        // (including the new <h1>) is fully rendered before resolveText reads it.
+        // Single rAF fires before the new route's template has been attached,
+        // which would cause resolveText to pick up the OLD h1 or fall back to
+        // document.title / route.name prematurely.
         requestAnimationFrame(() => {
             requestAnimationFrame(() => {
                 if (isDestroyed) {
                     return;
                 }
-                const text = resolveText(route, prefix, getCustomText);
-                if (text && text !== lastAnnouncedText && isReady) {
-                    lastAnnouncedText = text;
-                    clearTimeout(clearTimeoutId);
-                    announcer.textContent = text;
-                    clearTimeoutId = setTimeout(() => {
-                        announcer.textContent = "";
-                        lastAnnouncedText = "";
-                    }, CLEAR_DELAY);
-                    manageFocus();
+                const h1 = document.querySelector("h1");
+                const text = resolveText(route, prefix, getCustomText, h1);
+                if (!text || text === lastAnnouncedText) {
+                    return;
+                }
+                if (!isReady) {
+                    // Defer announcement until Safari-ready window elapses (see safariTimeoutId).
+                    pendingText = text;
+                    return;
                 }
+                doAnnounce(text, h1);
             });
         });
     });
@@ -65,11 +90,10 @@ function getOrCreateAnnouncer() {
 function removeAnnouncer() {
     document.querySelector(`[${ANNOUNCER_ATTR}]`)?.remove();
 }
-function resolveText(route, prefix, getCustomText) {
+function resolveText(route, prefix, getCustomText, h1) {
     if (getCustomText) {
         return getCustomText(route);
     }
-    const h1 = document.querySelector("h1");
     const h1Text = h1?.textContent.trim() ?? "";
     const routeName = route.name.startsWith(INTERNAL_ROUTE_PREFIX)
         ? ""
@@ -77,8 +101,7 @@ function resolveText(route, prefix, getCustomText) {
     const rawText = h1Text || document.title || routeName || globalThis.location.pathname;
     return `${prefix}${rawText}`;
 }
-function manageFocus() {
-    const h1 = document.querySelector("h1");
+function manageFocus(h1) {
     if (!h1) {
         return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/svelte",
-  "version": "0.2.13",
+  "version": "0.3.0",
   "type": "module",
   "description": "Svelte 5 integration for Real-Router",
   "svelte": "./dist/index.js",
@@ -58,17 +58,17 @@
     "svelte": "5.54.0",
     "svelte-check": "4.4.5",
     "svelte-eslint-parser": "1.6.0",
-    "@real-router/browser-plugin": "^0.12.1"
+    "@real-router/browser-plugin": "^0.12.2"
   },
   "peerDependencies": {
     "svelte": ">=5.7.0"
   },
   "scripts": {
-    "build": "svelte-package -i src -o dist",
     "test": "vitest",
     "test:properties": "vitest run --config vitest.config.properties.mts",
     "test:stress": "vitest run --config vitest.config.stress.mts",
     "type-check": "svelte-check --tsconfig ./tsconfig.json",
-    "lint": "eslint --cache src/ tests/ --fix --max-warnings 0"
+    "lint": "eslint --cache src/ tests/ --fix --max-warnings 0",
+    "bundle": "svelte-package -i src -o dist"
   }
 }

package/src/RouterProvider.svelte

@@ -5,6 +5,7 @@
   import { setContext } from "svelte";
 
   import { createReactiveSource } from "./createReactiveSource.svelte";
+  import { createRouteContext } from "./createRouteContext.svelte";
   import { NAVIGATOR_KEY, ROUTE_KEY, ROUTER_KEY } from "./context";
 
   import type { Router } from "@real-router/core";
@@ -26,26 +27,11 @@
   const navigator = getNavigator(router);
   const source = createRouteSource(router);
   const reactive = createReactiveSource(source);
+  const routeContext = createRouteContext(navigator, reactive);
 
   setContext(ROUTER_KEY, router);
   setContext(NAVIGATOR_KEY, navigator);
-  setContext(ROUTE_KEY, {
-    navigator,
-    get route() {
-      return {
-        get current() {
-          return reactive.current.route;
-        },
-      };
-    },
-    get previousRoute() {
-      return {
-        get current() {
-          return reactive.current.previousRoute;
-        },
-      };
-    },
-  });
+  setContext(ROUTE_KEY, routeContext);
 </script>
 
 {@render children()}

package/src/actions/link.svelte.ts

@@ -1,7 +1,7 @@
-import { getContext } from "svelte";
 import type { ActionReturn } from "svelte/action";
 import type { Router, Params, NavigationOptions } from "@real-router/core";
-import { ROUTER_KEY } from "../context";
+import { ROUTER_KEY, getContextOrThrow } from "../context";
+import { EMPTY_OPTIONS, EMPTY_PARAMS, NOOP } from "../constants";
 import { shouldNavigate, applyLinkA11y } from "../dom-utils/index.js";
 
 export interface LinkActionParams {
@@ -10,6 +10,11 @@ export interface LinkActionParams {
   options?: NavigationOptions;
 }
 
+type LinkAction = (
+  node: HTMLElement,
+  params: LinkActionParams,
+) => ActionReturn<LinkActionParams>;
+
 /**
  * Factory function that captures router context during component initialization.
  * Must be called during component init (not inside event handlers or effects).
@@ -28,15 +33,8 @@ export interface LinkActionParams {
  * <a use:link={{ name: 'users', params: { id: '123' } }}>User Profile</a>
  * ```
  */
-export function createLinkAction(): (
-  node: HTMLElement,
-  params: LinkActionParams,
-) => ActionReturn<LinkActionParams> {
-  const router = getContext<Router | undefined>(ROUTER_KEY);
-
-  if (!router) {
-    throw new Error("createLinkAction must be called inside a RouterProvider");
-  }
+export function createLinkAction(): LinkAction {
+  const router = getContextOrThrow<Router>(ROUTER_KEY, "createLinkAction");
 
   return function link(
     node: HTMLElement,
@@ -46,31 +44,31 @@ export function createLinkAction(): (
 
     applyLinkA11y(node);
 
-    function handleClick(evt: MouseEvent) {
-      if (!shouldNavigate(evt)) return;
-      evt.preventDefault();
-      // router is guaranteed to exist due to check in factory
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      router!
+    function navigate() {
+      router
         .navigate(
           currentParams.name,
-          currentParams.params ?? {},
-          currentParams.options ?? {},
+          currentParams.params ?? EMPTY_PARAMS,
+          currentParams.options ?? EMPTY_OPTIONS,
         )
-        .catch(() => {});
+        .catch(NOOP);
+    }
+
+    function handleClick(evt: MouseEvent) {
+      if (!shouldNavigate(evt)) return;
+      if (
+        node instanceof HTMLAnchorElement &&
+        node.getAttribute("target") === "_blank"
+      ) {
+        return;
+      }
+      evt.preventDefault();
+      navigate();
     }
 
     function handleKeyDown(evt: KeyboardEvent) {
       if (evt.key === "Enter" && !(node instanceof HTMLButtonElement)) {
-        // router is guaranteed to exist due to check in factory
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        router!
-          .navigate(
-            currentParams.name,
-            currentParams.params ?? {},
-            currentParams.options ?? {},
-          )
-          .catch(() => {});
+        navigate();
       }
     }
 

package/src/components/Lazy.svelte

@@ -9,26 +9,33 @@
     fallback?: Component | undefined;
   } = $props();
 
-  let LoadedComponent = $state<Component | null>(null);
-  let error = $state<Error | null>(null);
-  let loading = $state(true);
+  type LazyState =
+    | { status: "loading" }
+    | { status: "ready"; component: Component }
+    | { status: "error"; error: Error };
+
+  let state = $state<LazyState>({ status: "loading" });
 
   $effect(() => {
-    loading = true;
-    error = null;
-    LoadedComponent = null;
+    state = { status: "loading" };
     let active = true;
 
     loader()
       .then((module) => {
         if (!active) return;
-        LoadedComponent = module.default;
-        loading = false;
+        if (!module || typeof module.default === "undefined") {
+          throw new Error(
+            "[real-router] Lazy loader resolved without a `default` export.",
+          );
+        }
+        state = { status: "ready", component: module.default };
       })
-      .catch((err) => {
+      .catch((err: unknown) => {
         if (!active) return;
-        error = err;
-        loading = false;
+        state = {
+          status: "error",
+          error: err instanceof Error ? err : new Error(String(err)),
+        };
       });
 
     return () => {
@@ -37,11 +44,12 @@
   });
 </script>
 
-{#if loading && fallback}
+{#if state.status === "loading" && fallback}
   {@const Fallback = fallback}
   <Fallback />
-{:else if error}
-  <p>Error loading component: {error.message}</p>
-{:else if LoadedComponent}
+{:else if state.status === "error"}
+  <p>Error loading component: {state.error.message}</p>
+{:else if state.status === "ready"}
+  {@const LoadedComponent = state.component}
   <LoadedComponent />
 {/if}

package/src/components/Link.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   import { useIsActiveRoute } from "../composables/useIsActiveRoute.svelte";
   import { useRouter } from "../composables/useRouter.svelte";
+  import { EMPTY_OPTIONS, EMPTY_PARAMS, NOOP } from "../constants";
   import {
     shouldNavigate,
     buildHref,
@@ -12,8 +13,8 @@
 
   let {
     routeName,
-    routeParams = {} as Params,
-    routeOptions = {} as NavigationOptions,
+    routeParams = EMPTY_PARAMS,
+    routeOptions = EMPTY_OPTIONS,
     class: className = undefined,
     activeClassName = "active",
     activeStrict = false,
@@ -64,7 +65,7 @@
     }
 
     evt.preventDefault();
-    router.navigate(routeName, routeParams, routeOptions).catch(() => {});
+    router.navigate(routeName, routeParams, routeOptions).catch(NOOP);
   }
 </script>
 

package/src/components/RouteView.svelte

@@ -1,6 +1,26 @@
+<script lang="ts" module>
+  import { startsWithSegment } from "@real-router/route-utils";
+
+  export function getActiveSegment(
+    routeName: string,
+    node: string,
+    snippets: Record<string, unknown>,
+  ): string {
+    const prefix = node ? `${node}.` : "";
+
+    for (const segment in snippets) {
+      if (segment === "notFound") continue;
+      if (startsWithSegment(routeName, prefix + segment)) {
+        return segment;
+      }
+    }
+
+    return "";
+  }
+</script>
+
 <script lang="ts">
   import { UNKNOWN_ROUTE } from "@real-router/core";
-  import { startsWithSegment } from "@real-router/route-utils";
 
   import { useRouteNode } from "../composables/useRouteNode.svelte";
 
@@ -17,29 +37,14 @@
   } = $props();
 
   const routeContext = useRouteNode(nodeName);
-
-  function getActiveSegment(
-    routeName: string,
-    node: string,
-    snippets: Record<string, unknown>,
-  ): string {
-    for (const segment of Object.keys(snippets)) {
-      const fullSegmentName = node ? `${node}.${segment}` : segment;
-
-      if (startsWithSegment(routeName, fullSegmentName)) {
-        return segment;
-      }
-    }
-
-    return "";
-  }
 </script>
 
 {#if routeContext.route.current}
   {@const route = routeContext.route.current}
   {@const segment = getActiveSegment(route.name, nodeName, segmentSnippets)}
-  {#if segment && segmentSnippets[segment]}
-    {@render (segmentSnippets[segment] as Snippet)()}
+  {#if segment}
+    {@const snippet = segmentSnippets[segment] as Snippet}
+    {@render snippet()}
   {:else if route.name === UNKNOWN_ROUTE && notFound}
     {@render notFound()}
   {/if}

package/src/components/RouterErrorBoundary.svelte

@@ -32,12 +32,20 @@
   }
 
   $effect(() => {
-    if (snapshot.current.error) {
-      const { error, toRoute, fromRoute } = snapshot.current;
-      untrack(() => {
+    const snap = snapshot.current;
+    if (!snap.error) return;
+
+    const { error, toRoute, fromRoute } = snap;
+    untrack(() => {
+      try {
         onError?.(error, toRoute, fromRoute);
-      });
-    }
+      } catch (callbackError) {
+        console.error(
+          "[real-router] RouterErrorBoundary onError handler threw:",
+          callbackError,
+        );
+      }
+    });
   });
 </script>
 

package/src/composables/useIsActiveRoute.svelte.ts

@@ -7,9 +7,9 @@ import type { Params } from "@real-router/core";
 
 export function useIsActiveRoute(
   routeName: string,
-  params?: Params,
-  strict = false,
-  ignoreQueryParams = true,
+  params: Params | undefined,
+  strict: boolean,
+  ignoreQueryParams: boolean,
 ): { readonly current: boolean } {
   const router = useRouter();
 

package/src/composables/useNavigator.svelte.ts

@@ -1,15 +1,6 @@
-import { getContext } from "svelte";
-
-import { NAVIGATOR_KEY } from "../context";
+import { NAVIGATOR_KEY, getContextOrThrow } from "../context";
 
 import type { Navigator } from "@real-router/core";
 
-export const useNavigator = (): Navigator => {
-  const navigator = getContext<Navigator | undefined>(NAVIGATOR_KEY);
-
-  if (!navigator) {
-    throw new Error("useNavigator must be used within a RouterProvider");
-  }
-
-  return navigator;
-};
+export const useNavigator = (): Navigator =>
+  getContextOrThrow<Navigator>(NAVIGATOR_KEY, "useNavigator");

package/src/composables/useRoute.svelte.ts

@@ -1,15 +1,6 @@
-import { getContext } from "svelte";
-
-import { ROUTE_KEY } from "../context";
+import { ROUTE_KEY, getContextOrThrow } from "../context";
 
 import type { RouteContext } from "../types";
 
-export const useRoute = (): RouteContext => {
-  const routeContext = getContext<RouteContext | undefined>(ROUTE_KEY);
-
-  if (!routeContext) {
-    throw new Error("useRoute must be used within a RouterProvider");
-  }
-
-  return routeContext;
-};
+export const useRoute = (): RouteContext =>
+  getContextOrThrow<RouteContext>(ROUTE_KEY, "useRoute");

package/src/composables/useRouteNode.svelte.ts

@@ -2,6 +2,7 @@ import { getNavigator } from "@real-router/core";
 import { createRouteNodeSource } from "@real-router/sources";
 
 import { createReactiveSource } from "../createReactiveSource.svelte";
+import { createRouteContext } from "../createRouteContext.svelte";
 import { useRouter } from "./useRouter.svelte";
 
 import type { RouteContext } from "../types";
@@ -13,21 +14,5 @@ export function useRouteNode(nodeName: string): RouteContext {
   const source = createRouteNodeSource(router, nodeName);
   const reactive = createReactiveSource(source);
 
-  return {
-    navigator,
-    get route() {
-      return {
-        get current() {
-          return reactive.current.route;
-        },
-      };
-    },
-    get previousRoute() {
-      return {
-        get current() {
-          return reactive.current.previousRoute;
-        },
-      };
-    },
-  };
+  return createRouteContext(navigator, reactive);
 }

package/src/composables/useRouter.svelte.ts

@@ -1,15 +1,6 @@
-import { getContext } from "svelte";
-
-import { ROUTER_KEY } from "../context";
+import { ROUTER_KEY, getContextOrThrow } from "../context";
 
 import type { Router } from "@real-router/core";
 
-export const useRouter = (): Router => {
-  const router = getContext<Router | undefined>(ROUTER_KEY);
-
-  if (!router) {
-    throw new Error("useRouter must be used within a RouterProvider");
-  }
-
-  return router;
-};
+export const useRouter = (): Router =>
+  getContextOrThrow<Router>(ROUTER_KEY, "useRouter");

package/src/constants.ts

@@ -0,0 +1,9 @@
+import type { NavigationOptions, Params } from "@real-router/core";
+
+export const EMPTY_PARAMS: Params = Object.freeze({}) as Params;
+
+export const EMPTY_OPTIONS: NavigationOptions = Object.freeze(
+  {},
+) as NavigationOptions;
+
+export const NOOP = (): void => {};

package/src/context.ts

@@ -1,5 +1,22 @@
+import { getContext } from "svelte";
+
 export const ROUTER_KEY = "real-router:router";
 
 export const NAVIGATOR_KEY = "real-router:navigator";
 
 export const ROUTE_KEY = "real-router:route";
+
+// The type parameter is used by the caller to narrow the return type.
+// ESLint's no-unnecessary-type-parameters sees only a single textual use of T
+// (the return type) — but each call site supplies a different T, so it is not
+// unnecessary. Inline generic helpers are a standard pattern for typed context.
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+export function getContextOrThrow<T>(key: string, consumerName: string): T {
+  const value = getContext<T | undefined>(key);
+
+  if (!value) {
+    throw new Error(`${consumerName} must be used within a RouterProvider`);
+  }
+
+  return value;
+}

package/src/createRouteContext.svelte.ts

@@ -0,0 +1,27 @@
+import type { Navigator, State } from "@real-router/core";
+
+import type { RouteContext } from "./types";
+
+export interface RouteSnapshot {
+  readonly route: State | undefined;
+  readonly previousRoute: State | undefined;
+}
+
+export function createRouteContext(
+  navigator: Navigator,
+  reactive: { readonly current: RouteSnapshot },
+): RouteContext {
+  const route = {
+    get current(): State | undefined {
+      return reactive.current.route;
+    },
+  };
+
+  const previousRoute = {
+    get current(): State | undefined {
+      return reactive.current.previousRoute;
+    },
+  };
+
+  return { navigator, route, previousRoute };
+}