@real-router/angular 0.4.0 → 0.6.0

package/README.md

@@ -110,6 +110,8 @@ All inject functions must be called within an injection context (constructor, fi
 | `injectRouteUtils()`                        | `RouteUtils`                       | Never                                |
 | `injectRouterTransition()`                  | `Signal<RouterTransitionSnapshot>` | On transition start/end              |
 | `injectIsActiveRoute(name, params?, opts?)` | `Signal<boolean>`                  | On active state change               |
+| `injectRouteExit(handler, options?)`        | `void` — wraps `subscribeLeave` with abort + same-route guards            | Never (handler captured at injection time) |
+| `injectRouteEnter(handler, options?)`       | `void` — fires once on nav-driven mount via `effect()` + `transition.from` | Never (handler captured at injection time) |
 
 `RouteSignals` shape:
 
@@ -166,8 +168,48 @@ export class BackButtonComponent {
 export class ProgressComponent {
   readonly transition = injectRouterTransition();
 }
+
+// injectRouteExit — exit animations, draft autosave, AbortSignal-aware cleanup
+@Component({
+  selector: "app-fade-out",
+  template: `<div #box>...</div>`,
+})
+export class FadeOutComponent {
+  private el = viewChild.required<ElementRef<HTMLDivElement>>("box");
+
+  constructor() {
+    injectRouteExit(async ({ signal }) => {
+      const el = this.el().nativeElement;
+      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();
+    });
+  }
+}
+
+// injectRouteEnter — page-enter analytics, focus management, entry animations
+@Component({ selector: "app-page-enter", template: "" })
+export class PageEnterAnalyticsComponent {
+  constructor() {
+    injectRouteEnter(({ route, previousRoute }) => {
+      analytics.track("page_enter", {
+        route: route.name,
+        from: previousRoute.name,
+      });
+    });
+  }
+}
 ```
 
+> **Angular handler-reactivity:** `inject*` functions run once at construction,
+> so `handler` is captured at injection time. Pass a class method (stable
+> identity) and read signals **inside** the handler body to react to changes.
+> See [CLAUDE.md](./CLAUDE.md) → "injectRouteExit / injectRouteEnter Handler
+> Is Captured At Injection Time".
+
 ## Components
 
 ### `<route-view>`
@@ -358,11 +400,28 @@ bootstrapApplication(AppComponent, {
 ```typescript
 interface RealRouterOptions {
   scrollRestoration?: ScrollRestorationOptions; // { mode?, anchorScrolling?, scrollContainer? }
+  viewTransitions?: boolean;
 }
 ```
 
 Restores scroll on back/forward, scrolls to top (or `#hash`) on push. Three modes: `"restore"` (default), `"top"`, `"manual"`. Custom containers via `scrollContainer: () => HTMLElement | null`. The utility is created by `provideEnvironmentInitializer` and torn down via `inject(DestroyRef)`. Options are a snapshot at bootstrap — not reactive to runtime changes. 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):
+
+```typescript
+import { provideRealRouter } from "@real-router/angular";
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideRealRouter(router, { viewTransitions: true }),
+  ],
+});
+```
+
+No-op on unsupported browsers (Firefox as of 2026-04, SSR). Utility is created by `provideEnvironmentInitializer` at bootstrap and torn down via `inject(DestroyRef)`. Option is a snapshot at bootstrap — not reactive to runtime changes. 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.
+
 ## Angular-Specific Patterns
 
 ### Signals, Not Observables
@@ -460,7 +519,7 @@ const transitionSignal = sourceToSignal(createTransitionSource(router));
 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) · [Scroll Restoration](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration)
-- [injectRouter](https://github.com/greydragon888/real-router/wiki/injectRouter) · [injectRoute](https://github.com/greydragon888/real-router/wiki/injectRoute) · [injectRouteNode](https://github.com/greydragon888/real-router/wiki/injectRouteNode) · [injectNavigator](https://github.com/greydragon888/real-router/wiki/injectNavigator) · [injectRouteUtils](https://github.com/greydragon888/real-router/wiki/injectRouteUtils) · [injectRouterTransition](https://github.com/greydragon888/real-router/wiki/injectRouterTransition)
+- [injectRouter](https://github.com/greydragon888/real-router/wiki/injectRouter) · [injectRoute](https://github.com/greydragon888/real-router/wiki/injectRoute) · [injectRouteNode](https://github.com/greydragon888/real-router/wiki/injectRouteNode) · [injectNavigator](https://github.com/greydragon888/real-router/wiki/injectNavigator) · [injectRouteUtils](https://github.com/greydragon888/real-router/wiki/injectRouteUtils) · [injectRouterTransition](https://github.com/greydragon888/real-router/wiki/injectRouterTransition) · [injectRouteExit](https://github.com/greydragon888/real-router/wiki/injectRouteExit) · [injectRouteEnter](https://github.com/greydragon888/real-router/wiki/injectRouteEnter)
 
 ## Related Packages
 

package/dist/README.md

@@ -110,6 +110,8 @@ All inject functions must be called within an injection context (constructor, fi
 | `injectRouteUtils()`                        | `RouteUtils`                       | Never                                |
 | `injectRouterTransition()`                  | `Signal<RouterTransitionSnapshot>` | On transition start/end              |
 | `injectIsActiveRoute(name, params?, opts?)` | `Signal<boolean>`                  | On active state change               |
+| `injectRouteExit(handler, options?)`        | `void` — wraps `subscribeLeave` with abort + same-route guards            | Never (handler captured at injection time) |
+| `injectRouteEnter(handler, options?)`       | `void` — fires once on nav-driven mount via `effect()` + `transition.from` | Never (handler captured at injection time) |
 
 `RouteSignals` shape:
 
@@ -166,8 +168,48 @@ export class BackButtonComponent {
 export class ProgressComponent {
   readonly transition = injectRouterTransition();
 }
+
+// injectRouteExit — exit animations, draft autosave, AbortSignal-aware cleanup
+@Component({
+  selector: "app-fade-out",
+  template: `<div #box>...</div>`,
+})
+export class FadeOutComponent {
+  private el = viewChild.required<ElementRef<HTMLDivElement>>("box");
+
+  constructor() {
+    injectRouteExit(async ({ signal }) => {
+      const el = this.el().nativeElement;
+      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();
+    });
+  }
+}
+
+// injectRouteEnter — page-enter analytics, focus management, entry animations
+@Component({ selector: "app-page-enter", template: "" })
+export class PageEnterAnalyticsComponent {
+  constructor() {
+    injectRouteEnter(({ route, previousRoute }) => {
+      analytics.track("page_enter", {
+        route: route.name,
+        from: previousRoute.name,
+      });
+    });
+  }
+}
 ```
 
+> **Angular handler-reactivity:** `inject*` functions run once at construction,
+> so `handler` is captured at injection time. Pass a class method (stable
+> identity) and read signals **inside** the handler body to react to changes.
+> See [CLAUDE.md](./CLAUDE.md) → "injectRouteExit / injectRouteEnter Handler
+> Is Captured At Injection Time".
+
 ## Components
 
 ### `<route-view>`
@@ -358,11 +400,28 @@ bootstrapApplication(AppComponent, {
 ```typescript
 interface RealRouterOptions {
   scrollRestoration?: ScrollRestorationOptions; // { mode?, anchorScrolling?, scrollContainer? }
+  viewTransitions?: boolean;
 }
 ```
 
 Restores scroll on back/forward, scrolls to top (or `#hash`) on push. Three modes: `"restore"` (default), `"top"`, `"manual"`. Custom containers via `scrollContainer: () => HTMLElement | null`. The utility is created by `provideEnvironmentInitializer` and torn down via `inject(DestroyRef)`. Options are a snapshot at bootstrap — not reactive to runtime changes. 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):
+
+```typescript
+import { provideRealRouter } from "@real-router/angular";
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideRealRouter(router, { viewTransitions: true }),
+  ],
+});
+```
+
+No-op on unsupported browsers (Firefox as of 2026-04, SSR). Utility is created by `provideEnvironmentInitializer` at bootstrap and torn down via `inject(DestroyRef)`. Option is a snapshot at bootstrap — not reactive to runtime changes. 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.
+
 ## Angular-Specific Patterns
 
 ### Signals, Not Observables
@@ -460,7 +519,7 @@ const transitionSignal = sourceToSignal(createTransitionSource(router));
 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) · [Scroll Restoration](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration)
-- [injectRouter](https://github.com/greydragon888/real-router/wiki/injectRouter) · [injectRoute](https://github.com/greydragon888/real-router/wiki/injectRoute) · [injectRouteNode](https://github.com/greydragon888/real-router/wiki/injectRouteNode) · [injectNavigator](https://github.com/greydragon888/real-router/wiki/injectNavigator) · [injectRouteUtils](https://github.com/greydragon888/real-router/wiki/injectRouteUtils) · [injectRouterTransition](https://github.com/greydragon888/real-router/wiki/injectRouterTransition)
+- [injectRouter](https://github.com/greydragon888/real-router/wiki/injectRouter) · [injectRoute](https://github.com/greydragon888/real-router/wiki/injectRoute) · [injectRouteNode](https://github.com/greydragon888/real-router/wiki/injectRouteNode) · [injectNavigator](https://github.com/greydragon888/real-router/wiki/injectNavigator) · [injectRouteUtils](https://github.com/greydragon888/real-router/wiki/injectRouteUtils) · [injectRouterTransition](https://github.com/greydragon888/real-router/wiki/injectRouterTransition) · [injectRouteExit](https://github.com/greydragon888/real-router/wiki/injectRouteExit) · [injectRouteEnter](https://github.com/greydragon888/real-router/wiki/injectRouteEnter)
 
 ## Related Packages
 

package/dist/fesm2022/real-router-angular.mjs

@@ -1,11 +1,69 @@
 import * as i0 from '@angular/core';
-import { signal, inject, DestroyRef, InjectionToken, provideEnvironmentInitializer, makeEnvironmentProviders, input, TemplateRef, Directive, contentChildren, computed, Component, output, effect, ElementRef } from '@angular/core';
+import { signal, inject, DestroyRef, InjectionToken, provideEnvironmentInitializer, ApplicationRef, makeEnvironmentProviders, assertInInjectionContext, effect, input, TemplateRef, Directive, contentChildren, computed, Component, output, ElementRef } from '@angular/core';
 import { getNavigator, UNKNOWN_ROUTE } from '@real-router/core';
 import { createRouteSource, createRouteNodeSource, getTransitionSource, createActiveRouteSource, createDismissableError } from '@real-router/sources';
 import { getPluginApi } from '@real-router/core/api';
 import { getRouteUtils, startsWithSegment } from '@real-router/route-utils';
 import { NgTemplateOutlet } from '@angular/common';
 
+const NOOP_INSTANCE$2 = 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.
+ */
+function createDirectionTracker(router) {
+    if (typeof document === "undefined") {
+        return NOOP_INSTANCE$2;
+    }
+    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;
+        },
+    };
+}
+
 const CLEAR_DELAY = 7000;
 const SAFARI_READY_DELAY = 100;
 const ANNOUNCER_ATTR = "data-real-router-announcer";
@@ -102,7 +160,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;
@@ -120,21 +178,21 @@ function manageFocus(h1) {
 }
 
 const STORAGE_KEY = "real-router:scroll";
-const NOOP_INSTANCE = Object.freeze({
+const NOOP_INSTANCE$1 = Object.freeze({
     destroy: () => {
         /* no-op */
     },
 });
 function createScrollRestoration(router, options) {
     if (typeof globalThis.window === "undefined") {
-        return NOOP_INSTANCE;
+        return NOOP_INSTANCE$1;
     }
     const mode = options?.mode ?? "restore";
     // mode "manual" = utility does nothing. Don't flip history.scrollRestoration,
     // don't subscribe, don't register pagehide — leave the browser's native
     // auto-restore intact for the app to override if it wants to.
     if (mode === "manual") {
-        return NOOP_INSTANCE;
+        return NOOP_INSTANCE$1;
     }
     const anchorEnabled = options?.anchorScrolling ?? true;
     const getContainer = options?.scrollContainer;
@@ -277,6 +335,125 @@ function canonicalReplacer(_key, val) {
     return val;
 }
 
+const NOOP_INSTANCE = Object.freeze({
+    destroy: () => {
+        /* no-op */
+    },
+});
+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();
+        },
+    };
+}
+
 function shouldNavigate(evt) {
     return (evt.button === 0 &&
         !evt.metaKey &&
@@ -399,6 +576,32 @@ function provideRealRouter(router, options) {
             });
         }));
     }
+    if (options?.viewTransitions === true) {
+        providers.push(provideEnvironmentInitializer(() => {
+            const appRef = inject(ApplicationRef);
+            // Force synchronous change detection on every transition success
+            // BEFORE the VT utility resolves its deferred. The utility uses
+            // `setTimeout(0)` to release the new-snapshot capture, which is
+            // load-bearing because Chromium blocks rAF callbacks while VT sits
+            // in the `update-callback-called` phase. Angular's zoneless CD is
+            // rAF-driven by default — without this synchronous tick the new
+            // DOM is not committed when the browser captures the new snapshot,
+            // so old and new snapshots end up identical and animations finish
+            // in ~0 ms with no visible work (the inner-route `products.list ↔
+            // products.detail` morph in the example example was the canary).
+            // Subscribers fire in registration order; this one runs BEFORE
+            // `createViewTransitions` registers its own subscriber,
+            // guaranteeing CD completes first.
+            const offTick = router.subscribe(() => {
+                appRef.tick();
+            });
+            const vt = createViewTransitions(router);
+            inject(DestroyRef).onDestroy(() => {
+                offTick();
+                vt.destroy();
+            });
+        }));
+    }
     return makeEnvironmentProviders(providers);
 }
 
@@ -419,7 +622,11 @@ function injectNavigator() {
 }
 
 function injectRoute() {
-    return injectOrThrow(ROUTE, "injectRoute");
+    const signals = injectOrThrow(ROUTE, "injectRoute");
+    if (!signals.routeState().route) {
+        throw new Error("injectRoute called with no active route. Did you forget to await router.start() before rendering, or is the router stopped/disposed?");
+    }
+    return signals;
 }
 
 function injectRouteNode(nodeName) {
@@ -450,6 +657,175 @@ function injectIsActiveRoute(routeName, params, options) {
     return sourceToSignal(source);
 }
 
+/**
+ * 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 injection context's `DestroyRef`. Must be
+ * called within an injection context (constructor, field initializer,
+ * or `runInInjectionContext`).
+ *
+ * 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 (Angular):** `inject*` functions run **once**
+ * during component construction; `handler` is captured in closure at the
+ * call site. The common Angular pattern is to pass a class method
+ * (`this.onExit.bind(this)` or an arrow-property) — its identity is
+ * stable across change detection. To vary behavior over time, read
+ * signals **inside** the handler body — do not rely on swapping the
+ * handler reference.
+ *
+ * @example Animation
+ * ```ts
+ * \@Component({ ... })
+ * class FadeOutComponent {
+ *   private el = inject(ElementRef<HTMLElement>);
+ *
+ *   constructor() {
+ *     injectRouteExit(async ({ signal }) => {
+ *       const el = this.el.nativeElement;
+ *       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();
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Auto-save form draft
+ * ```ts
+ * injectRouteExit(async ({ signal }) => {
+ *   if (this.formState.dirty) {
+ *     await this.api.saveDraft(this.formState, { signal });
+ *   }
+ * });
+ * ```
+ */
+function injectRouteExit(handler, options) {
+    assertInInjectionContext(injectRouteExit);
+    const router = injectRouter();
+    const destroyRef = inject(DestroyRef);
+    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 });
+    });
+    destroyRef.onDestroy(off);
+}
+
+/**
+ * Fire `handler` once when the component is created as a result of a
+ * navigation. Mirror of `injectRouteExit` for the entry side.
+ *
+ * What this function covers that an ad-hoc `effect()` + `injectRoute()`
+ * 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.
+ *
+ * Effect cleanup is wired through the injection context's `DestroyRef`
+ * (Angular's `effect()` ties into the active context automatically).
+ * Must be called within an injection context (constructor, field
+ * initializer, or `runInInjectionContext`).
+ *
+ * **Handler reactivity (Angular):** `inject*` functions run **once**
+ * during component construction; `handler` is captured in closure at the
+ * call site. The common Angular pattern is to pass a class method —
+ * its identity is stable across change detection. To vary behavior
+ * over time, read signals **inside** the handler body.
+ *
+ * @example Direction-aware entry animation
+ * ```ts
+ * \@Component({ ... })
+ * class PageComponent {
+ *   private el = inject(ElementRef<HTMLElement>);
+ *
+ *   constructor() {
+ *     injectRouteEnter(({ route }) => {
+ *       const direction = route.context.browser?.direction;
+ *       this.el.nativeElement.classList.add(
+ *         direction === "back" ? "slide-from-left" : "slide-from-right",
+ *       );
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Analytics page-enter event (skip-initial built-in)
+ * ```ts
+ * injectRouteEnter(({ route, previousRoute }) => {
+ *   analytics.track("page_enter", {
+ *     route: route.name,
+ *     from: previousRoute.name,
+ *   });
+ * });
+ * ```
+ */
+function injectRouteEnter(handler, options) {
+    assertInInjectionContext(injectRouteEnter);
+    const { routeState } = injectRoute();
+    const skipSameRoute = options?.skipSameRoute ?? true;
+    let lastHandledRoute = null;
+    effect(() => {
+        const { route, previousRoute } = routeState();
+        // Early-exit guards, top-down:
+        //
+        //   - **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 on Angular (the
+        //     signal only fires on real reference changes); `!previousRoute`
+        //     is unreachable once `transition.from` is set (core populates
+        //     them together). Both kept for parity with React; v8-ignored.
+        if (!route.transition.from) {
+            return;
+        }
+        if (skipSameRoute && route.transition.from === route.name) {
+            return;
+        }
+        /* v8 ignore start */
+        if (lastHandledRoute === route || !previousRoute) {
+            return;
+        }
+        /* v8 ignore stop */
+        lastHandledRoute = route;
+        handler({ route, previousRoute });
+    });
+}
+
 class RouteMatch {
     routeMatch = input.required(...(ngDevMode ? [{ debugName: "routeMatch" }] : /* istanbul ignore next */ []));
     templateRef = inject(TemplateRef);
@@ -752,5 +1128,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { NAVIGATOR, NavigationAnnouncer, ROUTE, ROUTER, RealLink, RealLinkActive, RouteMatch, RouteNotFound, RouteSelf, RouteView, RouterErrorBoundary, injectIsActiveRoute, injectNavigator, injectRoute, injectRouteNode, injectRouteUtils, injectRouter, injectRouterTransition, provideRealRouter, sourceToSignal };
+export { NAVIGATOR, NavigationAnnouncer, ROUTE, ROUTER, RealLink, RealLinkActive, RouteMatch, RouteNotFound, RouteSelf, RouteView, RouterErrorBoundary, injectIsActiveRoute, injectNavigator, injectRoute, injectRouteEnter, injectRouteExit, injectRouteNode, injectRouteUtils, injectRouter, injectRouterTransition, provideRealRouter, sourceToSignal };
 //# sourceMappingURL=real-router-angular.mjs.map