@real-router/svelte 0.13.1 → 0.13.3

package/dist/RouterProvider.svelte

@@ -99,12 +99,20 @@
     return () => vt.destroy();
   });
 
+  // svelte-ignore state_referenced_locally
+  // The router instance is stable for the provider lifetime.
   const navigator = getNavigator(router);
+  // svelte-ignore state_referenced_locally
+  // The route source intentionally captures the initial router instance.
   const source = createRouteSource(router);
   const reactive = createReactiveSource(source);
   const routeContext = createRouteContext(navigator, reactive);
 
+  // svelte-ignore state_referenced_locally
+  // Context exposes the same stable router instance for this provider.
   setContext(ROUTER_KEY, router);
+  // svelte-ignore state_referenced_locally
+  // Context exposes the navigator derived once from the stable router.
   setContext(NAVIGATOR_KEY, navigator);
   setContext(ROUTE_KEY, routeContext);
 </script>

package/dist/components/Link.svelte

@@ -49,6 +49,8 @@
   const router = useRouter();
   // Hash-aware active (#532): tab links sharing routeName but differing in
   // hash should only light up the matching variant.
+  // svelte-ignore state_referenced_locally
+  // Active-route state is captured at mount; href remains reactive separately.
   const activeState = useIsActiveRoute(
     routeName,
     routeParams,

package/dist/components/RouteView.svelte

@@ -18,6 +18,8 @@
     [key: string]: Snippet | string | undefined;
   } = $props();
 
+  // svelte-ignore state_referenced_locally
+  // The node source is selected once for this mounted RouteView.
   const routeContext = useRouteNode(nodeName);
 </script>
 

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

@@ -115,10 +115,10 @@ export function navigateWithHash(router, routeName, routeParams, hash, extraOpti
 // for the slow-path branch.
 const WHITESPACE_PROBE = /\s/;
 const WHITESPACE_SPLIT = /\S+/g;
+// `value` is always a truthy class string: both call sites narrow it first
+// (`if (isActive && activeClassName)` / `if (!baseClassName) return …`), so the
+// former `if (!value) return []` guard was unreachable dead code (#809).
 function parseTokens(value) {
-    if (!value) {
-        return [];
-    }
     // Hot-path fast-path (audit-2026-05-17 §8b #1): >99% of active-class
     // inputs at `<Link>` emit are single-token strings like `"active"` or
     // `"is-current"` — no whitespace, no leading/trailing pad. Skip the

package/dist/dom-utils/scroll-spy.js

@@ -69,6 +69,7 @@ const createUrlPluginDetector = (router, onMissing) => {
         // boolean, a hypothetical multi-fire would double-warn.
         let detectionConsumed = false;
         detectionUnsub = router.subscribe(({ route }) => {
+            /* v8 ignore next 3 -- @preserve: the multi-fire is hypothetical (see above) — the real router never invokes a subscriber synchronously twice before unsub; defensive guard, not testable without a contract-violating fake */
             if (detectionConsumed) {
                 return;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/svelte",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "type": "module",
   "description": "Svelte 5 integration for Real-Router",
   "svelte": "./dist/index.js",
@@ -18,8 +18,7 @@
     }
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "homepage": "https://github.com/greydragon888/real-router",
   "repository": {
@@ -49,21 +48,22 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.55.0",
-    "@real-router/route-utils": "^0.2.2",
-    "@real-router/sources": "^0.8.4"
+    "@real-router/core": "^0.56.0",
+    "@real-router/route-utils": "^0.2.3",
+    "@real-router/sources": "^0.8.5"
   },
   "devDependencies": {
-    "@sveltejs/package": "2.5.7",
+    "@sveltejs/package": "2.5.8",
     "@sveltejs/vite-plugin-svelte": "6.2.4",
     "@testing-library/jest-dom": "6.9.1",
     "@testing-library/svelte": "5.3.1",
     "@testing-library/user-event": "14.6.1",
     "eslint-plugin-svelte": "3.19.0",
+    "rimraf": "6.1.3",
     "svelte": "5.56.1",
-    "svelte-check": "4.5.0",
-    "svelte-eslint-parser": "1.7.1",
-    "@real-router/browser-plugin": "^0.17.5"
+    "svelte-check": "4.6.0",
+    "svelte-eslint-parser": "1.8.0",
+    "@real-router/browser-plugin": "^0.17.6"
   },
   "peerDependencies": {
     "svelte": ">=5.7.0"
@@ -74,6 +74,6 @@
     "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",
-    "bundle": "svelte-package -i src -o dist"
+    "bundle": "svelte-package -i src -o dist && rimraf dist/dom-utils/__test-helpers dist/dom-utils/CLAUDE.md"
   }
 }

package/dist/dom-utils/__test-helpers/expected-fragment.d.ts

@@ -1,30 +0,0 @@
-/**
- * Test helper: mirror of `encodeFragmentInline` from `link-utils.ts` used by
- * property tests in every adapter (`packages/{vue,preact,react,solid}/tests/
- * property/linkUtils.properties.ts` and `packages/svelte/tests/property/
- * buildHref.properties.ts`).
- *
- * Why a mirror, not an import of the real function: a property test that uses
- * the production implementation to compute its own expected value is a
- * tautology — any regression in `encodeFragmentInline` would be invisible.
- * We hand-roll the same algorithm so the test asserts an independent
- * derivation. Drift between this mirror and `encodeFragmentInline` is exactly
- * the signal property tests are supposed to surface.
- *
- * This file lives under `__test-helpers/` so the sync-dom-utils script can
- * exclude it from the Angular copy (it ships no production code), and so
- * bundlers (tsdown, svelte-package) tree-shake it out — nothing in
- * `src/index.ts` of any adapter imports from this directory.
- */
-/**
- * Compute the expected fragment portion of an href for a given raw hash input.
- *
- * Mirrors the contract of `encodeFragmentInline`:
- *  1. If input contains `%XX`, try `decodeURIComponent` → `encodeURI` (idempotent
- *     re-encoding so consumers can copy-paste `location.hash` back in without
- *     `%20` becoming `%2520`).
- *  2. If `decodeURIComponent` throws (malformed `%XX`), fall through to plain
- *     `encodeURI` on the original input.
- *  3. Defensive `#` → `%23` (encodeURI does not encode `#`).
- */
-export declare function computeExpectedFragment(rawHash: string): string;

package/dist/dom-utils/__test-helpers/expected-fragment.js

@@ -1,43 +0,0 @@
-/**
- * Test helper: mirror of `encodeFragmentInline` from `link-utils.ts` used by
- * property tests in every adapter (`packages/{vue,preact,react,solid}/tests/
- * property/linkUtils.properties.ts` and `packages/svelte/tests/property/
- * buildHref.properties.ts`).
- *
- * Why a mirror, not an import of the real function: a property test that uses
- * the production implementation to compute its own expected value is a
- * tautology — any regression in `encodeFragmentInline` would be invisible.
- * We hand-roll the same algorithm so the test asserts an independent
- * derivation. Drift between this mirror and `encodeFragmentInline` is exactly
- * the signal property tests are supposed to surface.
- *
- * This file lives under `__test-helpers/` so the sync-dom-utils script can
- * exclude it from the Angular copy (it ships no production code), and so
- * bundlers (tsdown, svelte-package) tree-shake it out — nothing in
- * `src/index.ts` of any adapter imports from this directory.
- */
-const PERCENT_ESCAPE_PROBE = /%[\dA-Fa-f]{2}/;
-/**
- * Compute the expected fragment portion of an href for a given raw hash input.
- *
- * Mirrors the contract of `encodeFragmentInline`:
- *  1. If input contains `%XX`, try `decodeURIComponent` → `encodeURI` (idempotent
- *     re-encoding so consumers can copy-paste `location.hash` back in without
- *     `%20` becoming `%2520`).
- *  2. If `decodeURIComponent` throws (malformed `%XX`), fall through to plain
- *     `encodeURI` on the original input.
- *  3. Defensive `#` → `%23` (encodeURI does not encode `#`).
- */
-export function computeExpectedFragment(rawHash) {
-    let roundtrip = rawHash;
-    if (PERCENT_ESCAPE_PROBE.test(rawHash)) {
-        try {
-            roundtrip = decodeURIComponent(rawHash);
-        }
-        catch {
-            // Malformed %XX — encodeFragmentInline falls through to plain
-            // encodeURI on the original input, so do the same here.
-        }
-    }
-    return encodeURI(roundtrip).replaceAll("#", "%23");
-}

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

@@ -1,8 +0,0 @@
-/**
- * Test-only barrel. Intentionally NOT re-exported from
- * `shared/dom-utils/index.ts` so the helpers don't leak into adapters'
- * public API surface. Property tests import from this path directly:
- *
- *   import { computeExpectedFragment } from "../../src/dom-utils/__test-helpers";
- */
-export { computeExpectedFragment } from "./expected-fragment.js";

package/dist/dom-utils/__test-helpers/index.js

@@ -1,8 +0,0 @@
-/**
- * Test-only barrel. Intentionally NOT re-exported from
- * `shared/dom-utils/index.ts` so the helpers don't leak into adapters'
- * public API surface. Property tests import from this path directly:
- *
- *   import { computeExpectedFragment } from "../../src/dom-utils/__test-helpers";
- */
-export { computeExpectedFragment } from "./expected-fragment.js";

package/src/RouterProvider.svelte

@@ -1,112 +0,0 @@
-<script lang="ts">
-  import { getNavigator } from "@real-router/core";
-  import { createRouteSource } from "@real-router/sources";
-  import {
-    createRouteAnnouncer,
-    createScrollRestoration,
-    createScrollSpy,
-    createViewTransitions,
-  } from "./dom-utils";
-  import { setContext, untrack } from "svelte";
-
-  import { createReactiveSource } from "./createReactiveSource.svelte";
-  import { createRouteContext } from "./createRouteContext.svelte";
-  import { NAVIGATOR_KEY, ROUTE_KEY, ROUTER_KEY } from "./context";
-
-  import type { ScrollRestorationOptions, ScrollSpyOptions } from "./dom-utils";
-  import type { Router } from "@real-router/core";
-  import type { Snippet } from "svelte";
-
-  let {
-    router,
-    children,
-    announceNavigation,
-    scrollRestoration,
-    scrollSpy,
-    viewTransitions,
-  }: {
-    router: Router;
-    children: Snippet;
-    announceNavigation?: boolean | undefined;
-    scrollRestoration?: ScrollRestorationOptions | undefined;
-    scrollSpy?: ScrollSpyOptions | undefined;
-    viewTransitions?: boolean | undefined;
-  } = $props();
-
-  $effect(() => {
-    if (!announceNavigation) return;
-    const announcer = createRouteAnnouncer(router);
-    return () => announcer.destroy();
-  });
-
-  // $derived memoizes by === so inline `{ mode: "restore" }` doesn't thrash:
-  // each parent re-render produces a new object ref, but .mode stays "restore"
-  // → $derived returns the same primitive → $effect doesn't re-run.
-  const srEnabled = $derived(scrollRestoration !== undefined);
-  const srMode = $derived(scrollRestoration?.mode);
-  const srAnchor = $derived(scrollRestoration?.anchorScrolling);
-  const srBehavior = $derived(scrollRestoration?.behavior);
-  const srStorageKey = $derived(scrollRestoration?.storageKey);
-
-  $effect(() => {
-    if (!srEnabled) return;
-    // Pin primitive $derived deps as explicit dependencies of this effect
-    // BEFORE constructing the utility. The four `void srX` reads make
-    // intent unambiguous: even if `createScrollRestoration` throws after
-    // partial argument evaluation (e.g. invalid `mode` rejected), every
-    // srMode/srAnchor/srBehavior/srStorageKey is already in this effect's
-    // dependency set — the next change to any of them re-runs the effect
-    // and the utility gets rebuilt. Without these reads, the dependency
-    // tracking would depend on Svelte's argument-evaluation order inside
-    // the factory call, which is brittle. Non-primitive refs (like
-    // `scrollContainer` — a DOM element that changes ref every render but
-    // is identity-equal in practice) are deliberately read via `untrack`
-    // to keep this effect from re-running on every parent re-render.
-    void srMode;
-    void srAnchor;
-    void srBehavior;
-    void srStorageKey;
-    const sr = createScrollRestoration(router, {
-      mode: srMode,
-      anchorScrolling: srAnchor,
-      behavior: srBehavior,
-      storageKey: srStorageKey,
-      scrollContainer: untrack(() => scrollRestoration?.scrollContainer),
-    });
-    return () => sr.destroy();
-  });
-
-  const spyEnabled = $derived(
-    scrollSpy !== undefined && scrollSpy.selector !== "",
-  );
-  const spySelector = $derived(scrollSpy?.selector);
-  const spyRootMargin = $derived(scrollSpy?.rootMargin);
-
-  $effect(() => {
-    if (!spyEnabled || !spySelector) return;
-    void spyRootMargin;
-    const spy = createScrollSpy(router, {
-      selector: spySelector,
-      rootMargin: spyRootMargin,
-      scrollContainer: untrack(() => scrollSpy?.scrollContainer),
-    });
-    return () => spy.destroy();
-  });
-
-  $effect(() => {
-    if (!viewTransitions) return;
-    const vt = createViewTransitions(router);
-    return () => vt.destroy();
-  });
-
-  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, routeContext);
-</script>
-
-{@render children()}

package/src/actions/link.svelte.ts

@@ -1,88 +0,0 @@
-import type { ActionReturn } from "svelte/action";
-import type { Router, Params, NavigationOptions } from "@real-router/core";
-import { ROUTER_KEY, getContextOrThrow } from "../context";
-import { EMPTY_OPTIONS, EMPTY_PARAMS, NOOP } from "../constants";
-import { shouldNavigate, applyLinkA11y } from "../dom-utils";
-
-export interface LinkActionParams {
-  name: string;
-  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).
- *
- * @returns Action function for use with `use:` directive
- * @throws Error if called outside RouterProvider
- *
- * @example
- * ```svelte
- * <script>
- *   import { createLinkAction } from '@real-router/svelte';
- *   const link = createLinkAction();
- * </script>
- *
- * <button use:link={{ name: 'home' }}>Home</button>
- * <a use:link={{ name: 'users', params: { id: '123' } }}>User Profile</a>
- * ```
- */
-export function createLinkAction(): LinkAction {
-  const router = getContextOrThrow<Router>(ROUTER_KEY, "createLinkAction");
-
-  return function link(
-    node: HTMLElement,
-    params: LinkActionParams,
-  ): ActionReturn<LinkActionParams> {
-    let currentParams = params;
-
-    applyLinkA11y(node);
-
-    function navigate() {
-      router
-        .navigate(
-          currentParams.name,
-          currentParams.params ?? EMPTY_PARAMS,
-          currentParams.options ?? EMPTY_OPTIONS,
-        )
-        .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)) {
-        navigate();
-      }
-    }
-
-    node.addEventListener("click", handleClick);
-    node.addEventListener("keydown", handleKeyDown);
-
-    return {
-      update(newParams: LinkActionParams) {
-        currentParams = newParams;
-      },
-      destroy() {
-        node.removeEventListener("click", handleClick);
-        node.removeEventListener("keydown", handleKeyDown);
-      },
-    };
-  };
-}

package/src/components/Await.svelte

@@ -1,48 +0,0 @@
-<!--
-  @component
-  Reads `useDeferred(name)` and renders the `children` snippet with the
-  resolved value via Svelte's native `{#await}` block. Optional `fallback`
-  snippet shown while the promise is pending; rejection bubbles to the
-  nearest `{:catch}` handler in the surrounding `{#await}` chain (or
-  `<Streamed>`).
-
-  ```svelte
-  <Await name="reviews">
-    {#snippet children(reviews)}
-      <ReviewList items={reviews} />
-    {/snippet}
-    {#snippet fallback()}
-      <Spinner />
-    {/snippet}
-  </Await>
-  ```
--->
-<script lang="ts" generics="T">
-  import { useDeferred } from "../composables/useDeferred.svelte";
-
-  import type { Snippet } from "svelte";
-
-  interface Props {
-    /** Deferred key declared in the loader's `defer({ deferred: { <name>: ... } })`. */
-    name: string;
-    /** Render snippet for the resolved value. */
-    children: Snippet<[T]>;
-    /** Snippet shown while the promise is pending. */
-    fallback?: Snippet;
-  }
-
-  let { name, children, fallback }: Props = $props();
-
-  // `useDeferred(name)` reads `state.context.ssrDataDeferred[name]` —
-  // wrap in `$derived` so a dynamic `name` prop re-resolves the promise
-  // (vs. capturing the initial value at component init).
-  const promise = $derived(useDeferred<T>(name));
-</script>
-
-{#await promise}
-  {#if fallback}
-    {@render fallback()}
-  {/if}
-{:then value}
-  {@render children(value)}
-{/await}

package/src/components/ClientOnly.svelte

@@ -1,22 +0,0 @@
-<script lang="ts">
-  import type { Snippet } from "svelte";
-
-  interface Props {
-    children: Snippet;
-    fallback?: Snippet;
-  }
-
-  let { children, fallback }: Props = $props();
-
-  let mounted = $state(false);
-
-  $effect(() => {
-    mounted = true;
-  });
-</script>
-
-{#if mounted}
-  {@render children()}
-{:else if fallback}
-  {@render fallback()}
-{/if}

package/src/components/HttpStatusCode.svelte

@@ -1,63 +0,0 @@
-<!--
-  @component
-  Render-time HTTP status declaration. Mount inside a route component (typical
-  use case: a glob `*` route's NotFound page) when the status is decided by
-  the rendered tree rather than a loader.
-
-  Writes `code` to the nearest `<HttpStatusProvider>`'s sink during component
-  init and renders nothing. With no provider mounted (the standard
-  client-side case) the component is a silent no-op — same component tree
-  hydrates without touching the DOM or warning about mismatches.
-
-  Loader-driven errors (`LoaderNotFound` → 404, `LoaderRedirect` → 30x) keep
-  working as before; this component covers render-time decisions only.
-
-  Last write wins when several `<HttpStatusCode />` instances mount in the
-  same render pass — sink reflects the last component that ran.
-
-  ```svelte
-  <HttpStatusCode code={404} />
-  ```
-
-  **Streaming SSR ({#await}):** Svelte 5 stable does NOT chunk-stream HTTP
-  for `{#await}` — the server emits the pending branch and returns the full
-  response immediately, async resolution happens client-side. So the sink
-  is always written by the time `await render(App, ...)` resolves, regardless
-  of where `<HttpStatusCode />` is mounted. (This is RSC-like, not React 19
-  / Solid streaming.) No ordering concern.
-
-  **Hydration symmetry:** Svelte 5's hydration walker tolerates `{#if}`-branch
-  asymmetry between server and client (verified by `ssr/` e2e — no warnings
-  fire when SSR has the wrapper but CSR doesn't). The example's `App.svelte`
-  uses `{#if httpStatusSink}` so the wrapper is server-only; this is safe in
-  Svelte but would be a hydration mismatch in Vue/Solid.
-
-  **Valid `code` range:** Node's `res.end()` throws `Invalid status code` on
-  `NaN`, `0`, negative values, or values `> 999` — this surfaces as a 5xx /
-  dropped connection, not silent corruption. Pass a real HTTP status integer
-  (commonly 4xx/5xx; 100-999 is what Node accepts).
--->
-<script lang="ts">
-  import { getContext } from "svelte";
-
-  import { HTTP_STATUS_KEY } from "../context";
-
-  import type { HttpStatusSink } from "../utils/createHttpStatusSink";
-
-  interface Props {
-    /** HTTP status to apply to the response. Common values: 404, 410, 451, 503. */
-    code: number;
-  }
-
-  let { code }: Props = $props();
-
-  const sink = getContext<HttpStatusSink | undefined>(HTTP_STATUS_KEY);
-
-  if (sink) {
-    // svelte-ignore state_referenced_locally
-    // Intentional one-time write at component init: the sink is read by the
-    // server after `await render()` and a single value is the contract.
-    // Consumers that need to update the code mid-render should remount.
-    sink.code = code;
-  }
-</script>

package/src/components/HttpStatusProvider.svelte

@@ -1,45 +0,0 @@
-<!--
-  @component
-  Wraps an SSR tree with a render-scoped `HttpStatusSink`. `<HttpStatusCode />`
-  reads the sink via `getContext` and writes its `code` to it during component
-  init. Read `sink.code` after `await render()` to set the HTTP response
-  status.
-
-  ```svelte
-  <script lang="ts">
-    import {
-      HttpStatusProvider,
-      createHttpStatusSink,
-    } from "@real-router/svelte/ssr";
-
-    const sink = createHttpStatusSink();
-  </script>
-
-  <HttpStatusProvider {sink}>
-    <App />
-  </HttpStatusProvider>
-  ```
--->
-<script lang="ts">
-  import { setContext } from "svelte";
-
-  import { HTTP_STATUS_KEY } from "../context";
-
-  import type { HttpStatusSink } from "../utils/createHttpStatusSink";
-  import type { Snippet } from "svelte";
-
-  interface Props {
-    sink: HttpStatusSink;
-    children: Snippet;
-  }
-
-  let { sink, children }: Props = $props();
-
-  // svelte-ignore state_referenced_locally
-  // The sink reference is captured once at provider init — replacing the sink
-  // mid-render isn't a supported usage pattern (the server reads it once
-  // after `await render()`).
-  setContext(HTTP_STATUS_KEY, sink);
-</script>
-
-{@render children()}

package/src/components/Lazy.svelte

@@ -1,55 +0,0 @@
-<script lang="ts">
-  import type { Component } from "svelte";
-
-  let {
-    loader,
-    fallback,
-  }: {
-    loader: () => Promise<{ default: Component }>;
-    fallback?: Component | undefined;
-  } = $props();
-
-  type LazyState =
-    | { status: "loading" }
-    | { status: "ready"; component: Component }
-    | { status: "error"; error: Error };
-
-  let state = $state<LazyState>({ status: "loading" });
-
-  $effect(() => {
-    state = { status: "loading" };
-    let active = true;
-
-    loader()
-      .then((module) => {
-        if (!active) return;
-        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: unknown) => {
-        if (!active) return;
-        state = {
-          status: "error",
-          error: err instanceof Error ? err : new Error(String(err)),
-        };
-      });
-
-    return () => {
-      active = false;
-    };
-  });
-</script>
-
-{#if state.status === "loading" && fallback}
-  {@const Fallback = fallback}
-  <Fallback />
-{:else if state.status === "error"}
-  <p>Error loading component: {state.error.message}</p>
-{:else if state.status === "ready"}
-  {@const LoadedComponent = state.component}
-  <LoadedComponent />
-{/if}