@real-router/svelte 0.6.0 → 0.7.0

package/README.md

@@ -69,6 +69,8 @@ All composables must be called during component initialization (not inside `$eff
 | `useRouteNode(name)`    | `{ navigator, route: { current }, previousRoute: { current } }` | `.current` when node activates/deactivates |
 | `useRouteUtils()`       | `RouteUtils`                                                    | Never                                      |
 | `useRouterTransition()` | `{ current: RouterTransitionSnapshot }`                         | `.current` on transition start/end         |
+| `useRouteExit(handler, options?)`  | `void` — wraps `subscribeLeave` with abort + same-route guards            | Never (handler captured at init)           |
+| `useRouteEnter(handler, options?)` | `void` — fires once on nav-driven mount via `$effect` + `transition.from` | Never (handler captured at init)           |
 
 ```svelte
 <!-- useRouteNode — updates only when "users.*" changes -->
@@ -111,6 +113,46 @@ All composables must be called during component initialization (not inside `$eff
 {/if}
 ```
 
+```svelte
+<!-- useRouteExit — exit animations, draft autosave, AbortSignal-aware cleanup -->
+<script lang="ts">
+  import { useRouteExit } from "@real-router/svelte";
+
+  let el: HTMLDivElement;
+
+  useRouteExit(async ({ signal }) => {
+    if (!el) return;
+    el.classList.add("fade-out");
+    const cleanup = () => el.classList.remove("fade-out");
+    signal.addEventListener("abort", cleanup, { once: true });
+    el.getBoundingClientRect(); // style flush
+    await Promise.allSettled(el.getAnimations().map((a) => a.finished));
+    cleanup();
+  });
+</script>
+
+<div bind:this={el}>...</div>
+```
+
+```svelte
+<!-- useRouteEnter — page-enter analytics, focus management, entry animations -->
+<script lang="ts">
+  import { useRouteEnter } from "@real-router/svelte";
+
+  useRouteEnter(({ route, previousRoute }) => {
+    analytics.track("page_enter", {
+      route: route.name,
+      from: previousRoute.name,
+    });
+  });
+</script>
+```
+
+> **Svelte handler-reactivity:** composables run once at init, so `handler` is
+> captured at hook-call time. To vary behavior over time, read
+> `$state` / `$derived` **inside** the handler body. See [CLAUDE.md](./CLAUDE.md)
+> → "useRouteExit / useRouteEnter Handler Is Captured At Init".
+
 ## Components
 
 ### `<Link>`
@@ -375,12 +417,24 @@ Opt-in preservation of scroll position across navigations:
 
 Restores scroll on back/forward, scrolls to top (or `#hash`) on push. Three modes: `"restore"` (default), `"top"`, `"manual"`. Custom containers via `scrollContainer: () => HTMLElement | null`. Lifecycle tied to the provider — created on mount, destroyed on unmount. See [Scroll Restoration guide](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) for details.
 
+## View Transitions
+
+Opt-in animated route transitions via the browser's [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API):
+
+```svelte
+<RouterProvider {router} viewTransitions>
+  <!-- Your app -->
+</RouterProvider>
+```
+
+Reactive via `$effect` — toggling the prop creates/destroys the utility. No-op on unsupported browsers (Firefox as of 2026-04, SSR). Customization is pure CSS via `::view-transition-*` pseudo-elements and `view-transition-name` for hero morphs. See [View Transitions guide](https://github.com/greydragon888/real-router/wiki/View-Transitions) for patterns.
+
 ## Documentation
 
 Full documentation: [Wiki](https://github.com/greydragon888/real-router/wiki)
 
-- [RouterProvider](https://github.com/greydragon888/real-router/wiki/RouterProvider) · [RouteView](https://github.com/greydragon888/real-router/wiki/RouteView) · [RouterErrorBoundary](https://github.com/greydragon888/real-router/wiki/RouterErrorBoundary) · [Link](https://github.com/greydragon888/real-router/wiki/Link) · [Scroll Restoration](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration)
-- [useRouter](https://github.com/greydragon888/real-router/wiki/useRouter) · [useRoute](https://github.com/greydragon888/real-router/wiki/useRoute) · [useRouteNode](https://github.com/greydragon888/real-router/wiki/useRouteNode) · [useNavigator](https://github.com/greydragon888/real-router/wiki/useNavigator) · [useRouteUtils](https://github.com/greydragon888/real-router/wiki/useRouteUtils) · [useRouterTransition](https://github.com/greydragon888/real-router/wiki/useRouterTransition)
+- [RouterProvider](https://github.com/greydragon888/real-router/wiki/RouterProvider) · [RouteView](https://github.com/greydragon888/real-router/wiki/RouteView) · [RouterErrorBoundary](https://github.com/greydragon888/real-router/wiki/RouterErrorBoundary) · [Link](https://github.com/greydragon888/real-router/wiki/Link) · [Scroll Restoration](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) · [View Transitions](https://github.com/greydragon888/real-router/wiki/View-Transitions)
+- [useRouter](https://github.com/greydragon888/real-router/wiki/useRouter) · [useRoute](https://github.com/greydragon888/real-router/wiki/useRoute) · [useRouteNode](https://github.com/greydragon888/real-router/wiki/useRouteNode) · [useNavigator](https://github.com/greydragon888/real-router/wiki/useNavigator) · [useRouteUtils](https://github.com/greydragon888/real-router/wiki/useRouteUtils) · [useRouterTransition](https://github.com/greydragon888/real-router/wiki/useRouterTransition) · [useRouteExit](https://github.com/greydragon888/real-router/wiki/useRouteExit) · [useRouteEnter](https://github.com/greydragon888/real-router/wiki/useRouteEnter)
 
 ## Examples
 

package/dist/RouterProvider.svelte

@@ -4,6 +4,7 @@
   import {
     createRouteAnnouncer,
     createScrollRestoration,
+    createViewTransitions,
   } from "./dom-utils";
   import { setContext, untrack } from "svelte";
 
@@ -20,11 +21,13 @@
     children,
     announceNavigation,
     scrollRestoration,
+    viewTransitions,
   }: {
     router: Router;
     children: Snippet;
     announceNavigation?: boolean;
     scrollRestoration?: ScrollRestorationOptions;
+    viewTransitions?: boolean;
   } = $props();
 
   $effect(() => {
@@ -54,6 +57,12 @@
     return () => sr.destroy();
   });
 
+  $effect(() => {
+    if (!viewTransitions) return;
+    const vt = createViewTransitions(router);
+    return () => vt.destroy();
+  });
+
   const navigator = getNavigator(router);
   const source = createRouteSource(router);
   const reactive = createReactiveSource(source);

package/dist/RouterProvider.svelte.d.ts

@@ -6,6 +6,7 @@ type $$ComponentProps = {
     children: Snippet;
     announceNavigation?: boolean;
     scrollRestoration?: ScrollRestorationOptions;
+    viewTransitions?: boolean;
 };
 declare const RouterProvider: import("svelte").Component<$$ComponentProps, {}, "">;
 type RouterProvider = ReturnType<typeof RouterProvider>;

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

@@ -0,0 +1,68 @@
+import type { State } from "@real-router/core";
+export interface RouteEnterContext {
+    /** The route that was just activated. */
+    route: State;
+    /** The route that was active immediately before this navigation. */
+    previousRoute: State;
+}
+export type RouteEnterHandler = (context: RouteEnterContext) => void;
+export interface UseRouteEnterOptions {
+    /**
+     * Skip the handler when `route.name === previousRoute.name`
+     * (sort/filter/query-only navigations on the same route). Default:
+     * `true`. Symmetric with `useRouteExit`'s same-name option.
+     */
+    skipSameRoute?: boolean;
+}
+/**
+ * Fire `handler` once when the component mounts as a result of a
+ * navigation. Mirror of `useRouteExit` for the entry side.
+ *
+ * What this composable covers that an ad-hoc `$effect` + `useRoute()`
+ * doesn't:
+ *
+ *   - **Skip-initial**: handler is skipped when there is no
+ *     `route.transition.from` (i.e. first-load mount). Most consumers
+ *     want to fire side effects only on real navigations, not on
+ *     hydration.
+ *   - **Same-route skip** (default): handler is skipped when
+ *     `route.transition.from === route.name`. Sort/filter/query-only
+ *     navigations re-run the effect (because the `route` reference
+ *     changes), but they are not "entries" in the animation / analytics
+ *     sense. Opt out with `skipSameRoute: false`.
+ *   - **Mount-time `route` / `previousRoute` snapshot**: handler receives
+ *     the values that were live at the moment of effect activation.
+ *
+ * **Handler reactivity (Svelte):** Svelte composables run **once** at
+ * component init; `handler` is captured in closure at the call site. To
+ * vary behavior over time, read `$state` / `$derived` values inside the
+ * handler body.
+ *
+ * @example Direction-aware entry animation
+ * ```svelte
+ * <script lang="ts">
+ *   import { useRouteEnter } from "@real-router/svelte";
+ *   let el: HTMLDivElement;
+ *
+ *   useRouteEnter(({ route }) => {
+ *     const direction = route.context.browser?.direction;
+ *     el?.classList.add(
+ *       direction === "back" ? "slide-from-left" : "slide-from-right",
+ *     );
+ *   });
+ * </script>
+ * ```
+ *
+ * @example Analytics page-enter event (skip-initial built-in)
+ * ```svelte
+ * <script lang="ts">
+ *   useRouteEnter(({ route, previousRoute }) => {
+ *     analytics.track("page_enter", {
+ *       route: route.name,
+ *       from: previousRoute.name,
+ *     });
+ *   });
+ * </script>
+ * ```
+ */
+export declare function useRouteEnter(handler: RouteEnterHandler, options?: UseRouteEnterOptions): void;

package/dist/composables/useRouteEnter.svelte.js

@@ -0,0 +1,93 @@
+import { useRoute } from "./useRoute.svelte";
+/**
+ * Fire `handler` once when the component mounts as a result of a
+ * navigation. Mirror of `useRouteExit` for the entry side.
+ *
+ * What this composable covers that an ad-hoc `$effect` + `useRoute()`
+ * doesn't:
+ *
+ *   - **Skip-initial**: handler is skipped when there is no
+ *     `route.transition.from` (i.e. first-load mount). Most consumers
+ *     want to fire side effects only on real navigations, not on
+ *     hydration.
+ *   - **Same-route skip** (default): handler is skipped when
+ *     `route.transition.from === route.name`. Sort/filter/query-only
+ *     navigations re-run the effect (because the `route` reference
+ *     changes), but they are not "entries" in the animation / analytics
+ *     sense. Opt out with `skipSameRoute: false`.
+ *   - **Mount-time `route` / `previousRoute` snapshot**: handler receives
+ *     the values that were live at the moment of effect activation.
+ *
+ * **Handler reactivity (Svelte):** Svelte composables run **once** at
+ * component init; `handler` is captured in closure at the call site. To
+ * vary behavior over time, read `$state` / `$derived` values inside the
+ * handler body.
+ *
+ * @example Direction-aware entry animation
+ * ```svelte
+ * <script lang="ts">
+ *   import { useRouteEnter } from "@real-router/svelte";
+ *   let el: HTMLDivElement;
+ *
+ *   useRouteEnter(({ route }) => {
+ *     const direction = route.context.browser?.direction;
+ *     el?.classList.add(
+ *       direction === "back" ? "slide-from-left" : "slide-from-right",
+ *     );
+ *   });
+ * </script>
+ * ```
+ *
+ * @example Analytics page-enter event (skip-initial built-in)
+ * ```svelte
+ * <script lang="ts">
+ *   useRouteEnter(({ route, previousRoute }) => {
+ *     analytics.track("page_enter", {
+ *       route: route.name,
+ *       from: previousRoute.name,
+ *     });
+ *   });
+ * </script>
+ * ```
+ */
+export function useRouteEnter(handler, options) {
+    const { route, previousRoute } = useRoute();
+    const skipSameRoute = options?.skipSameRoute ?? true;
+    let lastHandledRoute = null;
+    $effect(() => {
+        const currentRoute = route.current;
+        const prev = previousRoute.current;
+        // Early-exit guards, top-down:
+        //
+        //   - **Defensive**: `route.current` may be undefined during SSR or
+        //     pre-start hydration. Not testable from vitest, v8-ignored.
+        //   - **Skip-initial**: `state.transition.from` is undefined only
+        //     for the very first state committed by `router.start()`.
+        //   - **Skip-same-route**: query-only navigations have
+        //     `transition.from === route.name`. Opt-out via
+        //     `skipSameRoute: false`.
+        //   - **Defensive dedupe + missing `previousRoute`**: same `route`
+        //     ref between `$effect` re-runs is unexpected (createSubscriber
+        //     only fires on real reference changes); `!prev` is unreachable
+        //     once `transition.from` is set (core populates them together).
+        //     Both kept for parity with React; v8-ignored.
+        /* v8 ignore start */
+        if (!currentRoute) {
+            return;
+        }
+        /* v8 ignore stop */
+        if (!currentRoute.transition.from) {
+            return;
+        }
+        if (skipSameRoute && currentRoute.transition.from === currentRoute.name) {
+            return;
+        }
+        /* v8 ignore start */
+        if (lastHandledRoute === currentRoute || !prev) {
+            return;
+        }
+        /* v8 ignore stop */
+        lastHandledRoute = currentRoute;
+        handler({ route: currentRoute, previousRoute: prev });
+    });
+}

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

@@ -0,0 +1,83 @@
+import type { State } from "@real-router/core";
+export interface RouteExitContext {
+    /** The route being left. */
+    route: State;
+    /** The route being navigated to. */
+    nextRoute: State;
+    /**
+     * AbortSignal that fires when this navigation is superseded by a later
+     * one (rapid clicks). Already filtered: when the handler runs,
+     * `signal.aborted` is guaranteed to be `false`. Use
+     * `signal.addEventListener("abort", cleanup, { once: true })` for
+     * cleanup that must run on cancellation.
+     */
+    signal: AbortSignal;
+}
+export interface UseRouteExitOptions {
+    /**
+     * Skip the handler when `route.name === nextRoute.name`
+     * (sort/filter/query-only navigations on the same route). Default:
+     * `true`.
+     */
+    skipSameRoute?: boolean;
+}
+export type RouteExitHandler = (context: RouteExitContext) => void | Promise<void>;
+/**
+ * Subscribe to the router's leave-window with the universal guards baked
+ * in. Wraps `router.subscribeLeave` so consumers don't repeat the same
+ * boilerplate every time:
+ *
+ *   - **Reentrant abort pre-check**: if `signal.aborted` is already `true`
+ *     when the handler would run (rapid navigation superseded a slower
+ *     one), the handler is skipped entirely.
+ *   - **Same-route skip**: by default, `route.name === nextRoute.name`
+ *     short-circuits the handler — query-only navigations skip the work.
+ *     Opt out with `skipSameRoute: false`.
+ *
+ * Cleanup is bound to the component via `onDestroy`. Must be called
+ * during component initialization (synchronous in `<script>`).
+ *
+ * If the handler returns a Promise, the router blocks on it. If the
+ * Promise resolves, navigation proceeds. If it rejects, the router emits
+ * `TRANSITION_CANCELLED`.
+ *
+ * **Handler reactivity (Svelte):** Svelte composables run **once** at
+ * component init; `handler` is captured in closure at the call site. To
+ * vary behavior over time, read `$state` / `$derived` values inside the
+ * handler body — do not rely on swapping the handler reference.
+ *
+ * @example Animation
+ * ```svelte
+ * <script lang="ts">
+ *   import { useRouteExit } from "@real-router/svelte";
+ *   let el: HTMLDivElement;
+ *
+ *   useRouteExit(async ({ signal }) => {
+ *     if (!el) return;
+ *     el.classList.add("fade-out");
+ *     const cleanup = () => el.classList.remove("fade-out");
+ *     signal.addEventListener("abort", cleanup, { once: true });
+ *     try {
+ *       el.getBoundingClientRect();
+ *       await Promise.allSettled(el.getAnimations().map((a) => a.finished));
+ *     } finally {
+ *       cleanup();
+ *     }
+ *   });
+ * </script>
+ *
+ * <div bind:this={el}>...</div>
+ * ```
+ *
+ * @example Reading rich transition metadata via `nextRoute.transition`
+ * ```svelte
+ * <script lang="ts">
+ *   useRouteExit(({ nextRoute }) => {
+ *     if (nextRoute.transition.segments.deactivated.includes("products")) {
+ *       productCache.clear();
+ *     }
+ *   });
+ * </script>
+ * ```
+ */
+export declare function useRouteExit(handler: RouteExitHandler, options?: UseRouteExitOptions): void;

package/dist/composables/useRouteExit.svelte.js

@@ -0,0 +1,74 @@
+import { onDestroy } from "svelte";
+import { useRouter } from "./useRouter.svelte";
+/**
+ * Subscribe to the router's leave-window with the universal guards baked
+ * in. Wraps `router.subscribeLeave` so consumers don't repeat the same
+ * boilerplate every time:
+ *
+ *   - **Reentrant abort pre-check**: if `signal.aborted` is already `true`
+ *     when the handler would run (rapid navigation superseded a slower
+ *     one), the handler is skipped entirely.
+ *   - **Same-route skip**: by default, `route.name === nextRoute.name`
+ *     short-circuits the handler — query-only navigations skip the work.
+ *     Opt out with `skipSameRoute: false`.
+ *
+ * Cleanup is bound to the component via `onDestroy`. Must be called
+ * during component initialization (synchronous in `<script>`).
+ *
+ * If the handler returns a Promise, the router blocks on it. If the
+ * Promise resolves, navigation proceeds. If it rejects, the router emits
+ * `TRANSITION_CANCELLED`.
+ *
+ * **Handler reactivity (Svelte):** Svelte composables run **once** at
+ * component init; `handler` is captured in closure at the call site. To
+ * vary behavior over time, read `$state` / `$derived` values inside the
+ * handler body — do not rely on swapping the handler reference.
+ *
+ * @example Animation
+ * ```svelte
+ * <script lang="ts">
+ *   import { useRouteExit } from "@real-router/svelte";
+ *   let el: HTMLDivElement;
+ *
+ *   useRouteExit(async ({ signal }) => {
+ *     if (!el) return;
+ *     el.classList.add("fade-out");
+ *     const cleanup = () => el.classList.remove("fade-out");
+ *     signal.addEventListener("abort", cleanup, { once: true });
+ *     try {
+ *       el.getBoundingClientRect();
+ *       await Promise.allSettled(el.getAnimations().map((a) => a.finished));
+ *     } finally {
+ *       cleanup();
+ *     }
+ *   });
+ * </script>
+ *
+ * <div bind:this={el}>...</div>
+ * ```
+ *
+ * @example Reading rich transition metadata via `nextRoute.transition`
+ * ```svelte
+ * <script lang="ts">
+ *   useRouteExit(({ nextRoute }) => {
+ *     if (nextRoute.transition.segments.deactivated.includes("products")) {
+ *       productCache.clear();
+ *     }
+ *   });
+ * </script>
+ * ```
+ */
+export function useRouteExit(handler, options) {
+    const router = useRouter();
+    const skipSameRoute = options?.skipSameRoute ?? true;
+    const off = router.subscribeLeave(({ route, nextRoute, signal }) => {
+        if (skipSameRoute && route.name === nextRoute.name) {
+            return;
+        }
+        if (signal.aborted) {
+            return;
+        }
+        return handler({ route, nextRoute, signal });
+    });
+    onDestroy(off);
+}

package/dist/dom-utils/direction-tracker.d.ts

@@ -0,0 +1,26 @@
+import type { Router } from "@real-router/core";
+export interface DirectionTracker {
+    destroy: () => void;
+}
+/**
+ * Track navigation direction (forward / back) and write it to
+ * `<html data-nav-direction>` on every leave. CSS / JS readers consume
+ * the attribute via `html[data-nav-direction="back"]` selectors or
+ * `document.documentElement.dataset.navDirection`.
+ *
+ * Mechanism-agnostic — works identically whether downstream UI uses CSS
+ * `@keyframes`, View Transitions pseudo-elements, or library state
+ * (motion's `motion.div initial={{ x: ... }}`).
+ *
+ * Implementation:
+ *   - On install, set `data-nav-direction="forward"` baseline.
+ *   - Attach a `popstate` listener that flips an internal flag to
+ *     `true`. Browser back/forward navigation triggers popstate; user
+ *     clicks on `<Link>` / programmatic `router.navigate(...)` do not.
+ *   - On every `subscribeLeave`, write
+ *     `popstateFlag ? "back" : "forward"` and reset the flag.
+ *
+ * Returns `{ destroy }` to clean up the listener and clear the dataset
+ * attribute.
+ */
+export declare function createDirectionTracker(router: Router): DirectionTracker;

package/dist/dom-utils/direction-tracker.js

@@ -0,0 +1,57 @@
+const NOOP_INSTANCE = Object.freeze({
+    destroy: () => {
+        /* no-op */
+    },
+});
+/**
+ * Track navigation direction (forward / back) and write it to
+ * `<html data-nav-direction>` on every leave. CSS / JS readers consume
+ * the attribute via `html[data-nav-direction="back"]` selectors or
+ * `document.documentElement.dataset.navDirection`.
+ *
+ * Mechanism-agnostic — works identically whether downstream UI uses CSS
+ * `@keyframes`, View Transitions pseudo-elements, or library state
+ * (motion's `motion.div initial={{ x: ... }}`).
+ *
+ * Implementation:
+ *   - On install, set `data-nav-direction="forward"` baseline.
+ *   - Attach a `popstate` listener that flips an internal flag to
+ *     `true`. Browser back/forward navigation triggers popstate; user
+ *     clicks on `<Link>` / programmatic `router.navigate(...)` do not.
+ *   - On every `subscribeLeave`, write
+ *     `popstateFlag ? "back" : "forward"` and reset the flag.
+ *
+ * Returns `{ destroy }` to clean up the listener and clear the dataset
+ * attribute.
+ */
+export function createDirectionTracker(router) {
+    if (typeof document === "undefined") {
+        return NOOP_INSTANCE;
+    }
+    let popstateFlag = false;
+    document.documentElement.dataset.navDirection = "forward";
+    const onPopstate = () => {
+        popstateFlag = true;
+    };
+    // IMPORTANT — listener-ordering: `popstate` fires on `window`, which
+    // has no DOM descendants, so capture phase is moot. Listeners are
+    // dispatched in registration order. To beat the browser-plugin's own
+    // popstate handler, this tracker must be installed **before**
+    // `router.usePlugin(browserPluginFactory())` in user code. Otherwise
+    // the plugin's handler runs first and synchronously fires
+    // `subscribeLeave` while `popstateFlag` is still `false`.
+    globalThis.addEventListener("popstate", onPopstate);
+    const offLeave = router.subscribeLeave(() => {
+        document.documentElement.dataset.navDirection = popstateFlag
+            ? "back"
+            : "forward";
+        popstateFlag = false;
+    });
+    return {
+        destroy: () => {
+            offLeave();
+            globalThis.removeEventListener("popstate", onPopstate);
+            delete document.documentElement.dataset.navDirection;
+        },
+    };
+}

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

@@ -1,5 +1,9 @@
+export { createDirectionTracker } from "./direction-tracker.js";
 export { createRouteAnnouncer } from "./route-announcer.js";
 export { createScrollRestoration } from "./scroll-restore.js";
+export { createViewTransitions } from "./view-transitions.js";
 export { shouldNavigate, buildHref, buildActiveClassName, shallowEqual, applyLinkA11y, } from "./link-utils.js";
 export type { RouteAnnouncerOptions } from "./route-announcer.js";
 export type { ScrollRestorationOptions, ScrollRestorationMode, } from "./scroll-restore.js";
+export type { DirectionTracker } from "./direction-tracker.js";
+export type { ViewTransitions } from "./view-transitions.js";

package/dist/dom-utils/index.js

@@ -1,3 +1,5 @@
+export { createDirectionTracker } from "./direction-tracker.js";
 export { createRouteAnnouncer } from "./route-announcer.js";
 export { createScrollRestoration } from "./scroll-restore.js";
+export { createViewTransitions } from "./view-transitions.js";
 export { shouldNavigate, buildHref, buildActiveClassName, shallowEqual, applyLinkA11y, } from "./link-utils.js";

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

@@ -94,7 +94,7 @@ function resolveText(route, prefix, getCustomText, h1) {
     if (getCustomText) {
         return getCustomText(route);
     }
-    const h1Text = h1?.textContent.trim() ?? "";
+    const h1Text = (h1?.textContent ?? "").trim();
     const routeName = route.name.startsWith(INTERNAL_ROUTE_PREFIX)
         ? ""
         : route.name;

package/dist/dom-utils/view-transitions.d.ts

@@ -0,0 +1,5 @@
+import type { Router } from "@real-router/core";
+export interface ViewTransitions {
+    destroy: () => void;
+}
+export declare function createViewTransitions(router: Router): ViewTransitions;

package/dist/dom-utils/view-transitions.js

@@ -0,0 +1,118 @@
+const NOOP_INSTANCE = Object.freeze({
+    destroy: () => {
+        /* no-op */
+    },
+});
+export function createViewTransitions(router) {
+    if (typeof document === "undefined" ||
+        typeof document.startViewTransition !== "function") {
+        return NOOP_INSTANCE;
+    }
+    let closeVT = null;
+    let currentVT = null;
+    // Tracks whether TRANSITION_SUCCESS fired for the current leave. Used to
+    // distinguish "benign cleanup abort" (router's async path aborts its own
+    // controller in a finally block after successful navigation) from "real
+    // cancellation" (concurrent navigate, guard rejection, dispose).
+    let successFired = false;
+    const resolveAndClear = () => {
+        closeVT?.();
+        closeVT = null;
+    };
+    const offLeave = router.subscribeLeave(({ signal }) => {
+        // Reentrant abort: signal already aborted when we're called. Open no VT
+        // — router will fall through to TRANSITION_CANCELLED via isCurrentNav()
+        // after leave resolves. addEventListener("abort", ...) does not re-fire
+        // for past events, so skipping startViewTransition is the safe path.
+        if (signal.aborted) {
+            return;
+        }
+        successFired = false;
+        resolveAndClear();
+        // Return a Promise so the router awaits until the browser invokes
+        // updateCallback. This ensures old DOM snapshot is captured BEFORE the
+        // router commits the new state — giving correct exit→state→entry
+        // ordering (vs fire-and-forget, where URL changes before VT captures).
+        return new Promise((resolveLeave) => {
+            // Capture the resolver synchronously BEFORE startViewTransition() is
+            // called. The browser invokes updateCallback in a later task, but
+            // router.subscribe (TRANSITION_SUCCESS) can fire before that. If we
+            // captured `resolve` inside the callback, subscribe would see closeVT
+            // still null and skip resolving — the deferred would hang for 4s
+            // until the VT API aborts with TimeoutError.
+            const deferred = new Promise((resolve) => {
+                closeVT = resolve;
+            });
+            signal.addEventListener("abort", () => {
+                if (successFired) {
+                    // Router's async path (#finishAsyncNavigation) aborts its own
+                    // controller in a finally block AFTER completeTransition (and
+                    // thus AFTER subscribe fired). This is cleanup, not
+                    // cancellation — VT is progressing normally, do nothing.
+                    return;
+                }
+                // Real cancellation (concurrent navigate, dispose). Resolve the
+                // deferred so updateCallback can complete, skip the VT so no
+                // stale animation leaks, and unblock the router if the abort
+                // fires before updateCallback was invoked.
+                resolveAndClear();
+                currentVT?.skipTransition?.();
+                resolveLeave();
+            }, { once: true });
+            try {
+                currentVT = document.startViewTransition(() => {
+                    // Resolving here unblocks the router at the moment the browser
+                    // enters updateCallback — by spec, old DOM snapshot is captured
+                    // before this callback runs. Router now proceeds through
+                    // activation guards and setState; the VT animation waits on
+                    // `deferred`, which is resolved from router.subscribe after a
+                    // task-queue tick (see NOTE on setTimeout below).
+                    resolveLeave();
+                    return deferred;
+                });
+            }
+            catch {
+                // Defensive: spec says startViewTransition doesn't throw under
+                // normal conditions, but Chromium has had edge cases (detached
+                // document, extension interference). Clean up and unblock router.
+                resolveAndClear();
+                resolveLeave();
+            }
+        });
+    });
+    const offSuccess = router.subscribe(() => {
+        const resolver = closeVT;
+        successFired = true;
+        closeVT = null;
+        if (resolver === null) {
+            currentVT = null;
+        }
+        else {
+            // CRITICAL: CANNOT use requestAnimationFrame here. When the router
+            // takes the async path (leave returned a Promise), subscribe fires
+            // AFTER the browser has already transitioned VT into the
+            // "update-callback-called" phase. In that phase Chromium sets
+            // rendering suppression to true, which ALSO blocks rAF callbacks.
+            // rAF would never fire → deferred never resolves → browser aborts
+            // vt.ready with TimeoutError after 4s (observed in Chromium).
+            //
+            // setTimeout runs on the task queue independent of the rendering
+            // pipeline, so it fires regardless of suppression. React's scheduler
+            // uses MessageChannel tasks, which are queued before our setTimeout,
+            // so the new DOM is committed by the time our callback runs.
+            setTimeout(() => {
+                resolver();
+                currentVT = null;
+            }, 0);
+        }
+    });
+    return {
+        destroy: () => {
+            offLeave();
+            offSuccess();
+            currentVT?.skipTransition?.();
+            currentVT = null;
+            resolveAndClear();
+        },
+    };
+}

package/dist/index.d.ts

@@ -9,10 +9,14 @@ export { useRouteUtils } from "./composables/useRouteUtils.svelte";
 export { useRoute } from "./composables/useRoute.svelte";
 export { useRouteNode } from "./composables/useRouteNode.svelte";
 export { useRouterTransition } from "./composables/useRouterTransition.svelte";
+export { useRouteExit } from "./composables/useRouteExit.svelte";
+export { useRouteEnter } from "./composables/useRouteEnter.svelte";
 export { createLinkAction } from "./actions/link.svelte";
 export type { LinkActionParams } from "./actions/link.svelte";
 export { default as RouterProvider } from "./RouterProvider.svelte";
 export { ROUTER_KEY, NAVIGATOR_KEY, ROUTE_KEY } from "./context";
 export type { LinkProps, RouteContext } from "./types";
+export type { RouteExitContext, RouteExitHandler, UseRouteExitOptions, } from "./composables/useRouteExit.svelte";
+export type { RouteEnterContext, RouteEnterHandler, UseRouteEnterOptions, } from "./composables/useRouteEnter.svelte";
 export type { Navigator } from "@real-router/core";
 export type { RouterTransitionSnapshot, RouterErrorSnapshot, } from "@real-router/sources";

package/dist/index.js

@@ -12,6 +12,8 @@ export { useRouteUtils } from "./composables/useRouteUtils.svelte";
 export { useRoute } from "./composables/useRoute.svelte";
 export { useRouteNode } from "./composables/useRouteNode.svelte";
 export { useRouterTransition } from "./composables/useRouterTransition.svelte";
+export { useRouteExit } from "./composables/useRouteExit.svelte";
+export { useRouteEnter } from "./composables/useRouteEnter.svelte";
 // Actions
 export { createLinkAction } from "./actions/link.svelte";
 // Context

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/svelte",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Svelte 5 integration for Real-Router",
   "svelte": "./dist/index.js",
@@ -44,7 +44,7 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.50.1",
+    "@real-router/core": "^0.50.2",
     "@real-router/route-utils": "^0.2.1",
     "@real-router/sources": "^0.7.2"
   },
@@ -54,11 +54,11 @@
     "@testing-library/jest-dom": "6.9.1",
     "@testing-library/svelte": "5.3.1",
     "@testing-library/user-event": "14.6.1",
-    "eslint-plugin-svelte": "3.15.2",
+    "eslint-plugin-svelte": "3.17.1",
     "svelte": "5.54.0",
     "svelte-check": "4.4.5",
     "svelte-eslint-parser": "1.6.0",
-    "@real-router/browser-plugin": "^0.15.1"
+    "@real-router/browser-plugin": "^0.16.0"
   },
   "peerDependencies": {
     "svelte": ">=5.7.0"

package/src/RouterProvider.svelte

@@ -4,6 +4,7 @@
   import {
     createRouteAnnouncer,
     createScrollRestoration,
+    createViewTransitions,
   } from "./dom-utils";
   import { setContext, untrack } from "svelte";
 
@@ -20,11 +21,13 @@
     children,
     announceNavigation,
     scrollRestoration,
+    viewTransitions,
   }: {
     router: Router;
     children: Snippet;
     announceNavigation?: boolean;
     scrollRestoration?: ScrollRestorationOptions;
+    viewTransitions?: boolean;
   } = $props();
 
   $effect(() => {
@@ -54,6 +57,12 @@
     return () => sr.destroy();
   });
 
+  $effect(() => {
+    if (!viewTransitions) return;
+    const vt = createViewTransitions(router);
+    return () => vt.destroy();
+  });
+
   const navigator = getNavigator(router);
   const source = createRouteSource(router);
   const reactive = createReactiveSource(source);

package/src/composables/useRouteEnter.svelte.ts

@@ -0,0 +1,120 @@
+import { useRoute } from "./useRoute.svelte";
+
+import type { State } from "@real-router/core";
+
+export interface RouteEnterContext {
+  /** The route that was just activated. */
+  route: State;
+  /** The route that was active immediately before this navigation. */
+  previousRoute: State;
+}
+
+export type RouteEnterHandler = (context: RouteEnterContext) => void;
+
+export interface UseRouteEnterOptions {
+  /**
+   * Skip the handler when `route.name === previousRoute.name`
+   * (sort/filter/query-only navigations on the same route). Default:
+   * `true`. Symmetric with `useRouteExit`'s same-name option.
+   */
+  skipSameRoute?: boolean;
+}
+
+/**
+ * Fire `handler` once when the component mounts as a result of a
+ * navigation. Mirror of `useRouteExit` for the entry side.
+ *
+ * What this composable covers that an ad-hoc `$effect` + `useRoute()`
+ * doesn't:
+ *
+ *   - **Skip-initial**: handler is skipped when there is no
+ *     `route.transition.from` (i.e. first-load mount). Most consumers
+ *     want to fire side effects only on real navigations, not on
+ *     hydration.
+ *   - **Same-route skip** (default): handler is skipped when
+ *     `route.transition.from === route.name`. Sort/filter/query-only
+ *     navigations re-run the effect (because the `route` reference
+ *     changes), but they are not "entries" in the animation / analytics
+ *     sense. Opt out with `skipSameRoute: false`.
+ *   - **Mount-time `route` / `previousRoute` snapshot**: handler receives
+ *     the values that were live at the moment of effect activation.
+ *
+ * **Handler reactivity (Svelte):** Svelte composables run **once** at
+ * component init; `handler` is captured in closure at the call site. To
+ * vary behavior over time, read `$state` / `$derived` values inside the
+ * handler body.
+ *
+ * @example Direction-aware entry animation
+ * ```svelte
+ * <script lang="ts">
+ *   import { useRouteEnter } from "@real-router/svelte";
+ *   let el: HTMLDivElement;
+ *
+ *   useRouteEnter(({ route }) => {
+ *     const direction = route.context.browser?.direction;
+ *     el?.classList.add(
+ *       direction === "back" ? "slide-from-left" : "slide-from-right",
+ *     );
+ *   });
+ * </script>
+ * ```
+ *
+ * @example Analytics page-enter event (skip-initial built-in)
+ * ```svelte
+ * <script lang="ts">
+ *   useRouteEnter(({ route, previousRoute }) => {
+ *     analytics.track("page_enter", {
+ *       route: route.name,
+ *       from: previousRoute.name,
+ *     });
+ *   });
+ * </script>
+ * ```
+ */
+export function useRouteEnter(
+  handler: RouteEnterHandler,
+  options?: UseRouteEnterOptions,
+): void {
+  const { route, previousRoute } = useRoute();
+  const skipSameRoute = options?.skipSameRoute ?? true;
+  let lastHandledRoute: State | null = null;
+
+  $effect(() => {
+    const currentRoute = route.current;
+    const prev = previousRoute.current;
+
+    // Early-exit guards, top-down:
+    //
+    //   - **Defensive**: `route.current` may be undefined during SSR or
+    //     pre-start hydration. Not testable from vitest, v8-ignored.
+    //   - **Skip-initial**: `state.transition.from` is undefined only
+    //     for the very first state committed by `router.start()`.
+    //   - **Skip-same-route**: query-only navigations have
+    //     `transition.from === route.name`. Opt-out via
+    //     `skipSameRoute: false`.
+    //   - **Defensive dedupe + missing `previousRoute`**: same `route`
+    //     ref between `$effect` re-runs is unexpected (createSubscriber
+    //     only fires on real reference changes); `!prev` is unreachable
+    //     once `transition.from` is set (core populates them together).
+    //     Both kept for parity with React; v8-ignored.
+    /* v8 ignore start */
+    if (!currentRoute) {
+      return;
+    }
+    /* v8 ignore stop */
+    if (!currentRoute.transition.from) {
+      return;
+    }
+    if (skipSameRoute && currentRoute.transition.from === currentRoute.name) {
+      return;
+    }
+    /* v8 ignore start */
+    if (lastHandledRoute === currentRoute || !prev) {
+      return;
+    }
+    /* v8 ignore stop */
+
+    lastHandledRoute = currentRoute;
+    handler({ route: currentRoute, previousRoute: prev });
+  });
+}

package/src/composables/useRouteExit.svelte.ts

@@ -0,0 +1,113 @@
+import { onDestroy } from "svelte";
+
+import { useRouter } from "./useRouter.svelte";
+
+import type { State } from "@real-router/core";
+
+export interface RouteExitContext {
+  /** The route being left. */
+  route: State;
+  /** The route being navigated to. */
+  nextRoute: State;
+  /**
+   * AbortSignal that fires when this navigation is superseded by a later
+   * one (rapid clicks). Already filtered: when the handler runs,
+   * `signal.aborted` is guaranteed to be `false`. Use
+   * `signal.addEventListener("abort", cleanup, { once: true })` for
+   * cleanup that must run on cancellation.
+   */
+  signal: AbortSignal;
+}
+
+export interface UseRouteExitOptions {
+  /**
+   * Skip the handler when `route.name === nextRoute.name`
+   * (sort/filter/query-only navigations on the same route). Default:
+   * `true`.
+   */
+  skipSameRoute?: boolean;
+}
+
+export type RouteExitHandler = (
+  context: RouteExitContext,
+) => void | Promise<void>;
+
+/**
+ * Subscribe to the router's leave-window with the universal guards baked
+ * in. Wraps `router.subscribeLeave` so consumers don't repeat the same
+ * boilerplate every time:
+ *
+ *   - **Reentrant abort pre-check**: if `signal.aborted` is already `true`
+ *     when the handler would run (rapid navigation superseded a slower
+ *     one), the handler is skipped entirely.
+ *   - **Same-route skip**: by default, `route.name === nextRoute.name`
+ *     short-circuits the handler — query-only navigations skip the work.
+ *     Opt out with `skipSameRoute: false`.
+ *
+ * Cleanup is bound to the component via `onDestroy`. Must be called
+ * during component initialization (synchronous in `<script>`).
+ *
+ * If the handler returns a Promise, the router blocks on it. If the
+ * Promise resolves, navigation proceeds. If it rejects, the router emits
+ * `TRANSITION_CANCELLED`.
+ *
+ * **Handler reactivity (Svelte):** Svelte composables run **once** at
+ * component init; `handler` is captured in closure at the call site. To
+ * vary behavior over time, read `$state` / `$derived` values inside the
+ * handler body — do not rely on swapping the handler reference.
+ *
+ * @example Animation
+ * ```svelte
+ * <script lang="ts">
+ *   import { useRouteExit } from "@real-router/svelte";
+ *   let el: HTMLDivElement;
+ *
+ *   useRouteExit(async ({ signal }) => {
+ *     if (!el) return;
+ *     el.classList.add("fade-out");
+ *     const cleanup = () => el.classList.remove("fade-out");
+ *     signal.addEventListener("abort", cleanup, { once: true });
+ *     try {
+ *       el.getBoundingClientRect();
+ *       await Promise.allSettled(el.getAnimations().map((a) => a.finished));
+ *     } finally {
+ *       cleanup();
+ *     }
+ *   });
+ * </script>
+ *
+ * <div bind:this={el}>...</div>
+ * ```
+ *
+ * @example Reading rich transition metadata via `nextRoute.transition`
+ * ```svelte
+ * <script lang="ts">
+ *   useRouteExit(({ nextRoute }) => {
+ *     if (nextRoute.transition.segments.deactivated.includes("products")) {
+ *       productCache.clear();
+ *     }
+ *   });
+ * </script>
+ * ```
+ */
+export function useRouteExit(
+  handler: RouteExitHandler,
+  options?: UseRouteExitOptions,
+): void {
+  const router = useRouter();
+  const skipSameRoute = options?.skipSameRoute ?? true;
+
+  const off = router.subscribeLeave(({ route, nextRoute, signal }) => {
+    if (skipSameRoute && route.name === nextRoute.name) {
+      return;
+    }
+
+    if (signal.aborted) {
+      return;
+    }
+
+    return handler({ route, nextRoute, signal });
+  });
+
+  onDestroy(off);
+}

package/src/index.ts

@@ -23,6 +23,10 @@ export { useRouteNode } from "./composables/useRouteNode.svelte";
 
 export { useRouterTransition } from "./composables/useRouterTransition.svelte";
 
+export { useRouteExit } from "./composables/useRouteExit.svelte";
+
+export { useRouteEnter } from "./composables/useRouteEnter.svelte";
+
 // Actions
 export { createLinkAction } from "./actions/link.svelte";
 
@@ -36,6 +40,18 @@ export { ROUTER_KEY, NAVIGATOR_KEY, ROUTE_KEY } from "./context";
 // Types
 export type { LinkProps, RouteContext } from "./types";
 
+export type {
+  RouteExitContext,
+  RouteExitHandler,
+  UseRouteExitOptions,
+} from "./composables/useRouteExit.svelte";
+
+export type {
+  RouteEnterContext,
+  RouteEnterHandler,
+  UseRouteEnterOptions,
+} from "./composables/useRouteEnter.svelte";
+
 export type { Navigator } from "@real-router/core";
 
 export type {